test: adapt alias e2e tests to current behavior

src/cmd/add.go

@@ -3,7 +3,9 @@ package cmd
 import (
 	"axolotl/models"
 	"axolotl/service"
+	"encoding/json"
 	"fmt"
+	"io"
 	"os"
 
 	"github.com/spf13/cobra"
@@ -64,6 +66,9 @@ var addCmd = &cobra.Command{
 			return
 		}
 
+		if n.GetProperty("type") == "agent" {
+			printAgentToken(cmd.OutOrStdout(), n)
+		}
 		PrintNode(cmd.OutOrStdout(), svc, n, jsonFlag)
 	},
 }
@@ -81,3 +86,13 @@ func init() {
 	f.StringArrayVar(&cTags, "tag", nil, "label tag (alias for --rel tagname)")
 	f.StringArrayVar(&cRels, "rel", nil, "relation (prefix::value or relname:target)")
 }
+
+func printAgentToken(w io.Writer, n *models.Node) {
+	var c struct {
+		AccessToken string `json:"access_token"`
+	}
+	if err := json.Unmarshal([]byte(n.Content), &c); err == nil && c.AccessToken != "" {
+		fmt.Fprintf(w, "\nAgent access token: %s\n", c.AccessToken)
+		fmt.Fprintln(w, "Save this token — it cannot be retrieved later via the CLI.")
+	}
+}

src/cmd/alias.go

@@ -4,6 +4,7 @@ import (
 	"axolotl/store"
 	"fmt"
 	"os"
+	"slices"
 
 	"github.com/spf13/cobra"
 )
@@ -15,21 +16,32 @@ var aliasCmd = &cobra.Command{
 	Run: func(cmd *cobra.Command, args []string) {
 		w := cmd.OutOrStdout()
 		if len(args) == 0 {
-			if aliases, err := cfg.ListAliases(); err == nil {
-				PrintAliases(w, aliases, jsonFlag)
-			}
+			PrintAliases(w, cfg.Aliases, jsonFlag)
 			return
 		}
 		if len(args) == 1 {
-			a, err := cfg.GetAlias(args[0])
-			if err != nil {
-				fmt.Fprintln(os.Stderr, "alias not found:", args[0])
-				os.Exit(1)
+			for _, a := range cfg.Aliases {
+				if a.Name == args[0] {
+					fmt.Println(a.Command)
+					return
+				}
 			}
-			fmt.Println(a.Command)
-			return
+			fmt.Fprintln(os.Stderr, "alias not found:", args[0])
+			os.Exit(1)
 		}
-		if err := cfg.SetAlias(&store.Alias{Name: args[0], Command: args[1], Description: aliasDesc}); err != nil {
+		alias := &store.Alias{Name: args[0], Command: args[1], Description: aliasDesc}
+		found := false
+		for i, a := range cfg.Aliases {
+			if a.Name == alias.Name {
+				cfg.Aliases[i] = alias
+				found = true
+				break
+			}
+		}
+		if !found {
+			cfg.Aliases = append(cfg.Aliases, alias)
+		}
+		if err := cfg.Save(); err != nil {
 			fmt.Fprintln(os.Stderr, "failed to set alias:", err)
 		} else {
 			PrintAction(w, "Alias set", args[0], false)
@@ -40,7 +52,19 @@ var aliasCmd = &cobra.Command{
 var aliasDelCmd = &cobra.Command{
 	Use: "del <name>", Short: "Delete an alias", Args: cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
-		if err := cfg.DeleteAlias(args[0]); err != nil {
+		found := false
+		for i, a := range cfg.Aliases {
+			if a.Name == args[0] {
+				cfg.Aliases = slices.Delete(cfg.Aliases, i, i+1)
+				found = true
+				break
+			}
+		}
+		if !found {
+			fmt.Fprintln(os.Stderr, "alias not found")
+			os.Exit(1)
+		}
+		if err := cfg.Save(); err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			os.Exit(1)
 		}

src/cmd/edit.go

@@ -33,7 +33,7 @@ var editCmd = &cobra.Command{
 		tmp.Close()
 		defer os.Remove(tmp.Name())
 
-		c := exec.Command(cfg.GetEditor(), tmp.Name())
+		c := exec.Command(cfg.Editor, tmp.Name())
 		c.Stdin, c.Stdout, c.Stderr = os.Stdin, os.Stdout, os.Stderr
 		if err := c.Run(); err != nil {
 			fmt.Fprintln(os.Stderr, "editor failed:", err)

src/cmd/login.go

@@ -15,12 +15,11 @@ var loginCmd = &cobra.Command{
 	Use:   "login",
 	Short: "Authenticate with the remote server via OIDC",
 	Run: func(cmd *cobra.Command, args []string) {
-		rc, ok := cfg.GetRemoteConfig()
-		if !ok {
+		if cfg.Remote.Host == "" {
 			fmt.Fprintln(os.Stderr, "no remote server configured; set remote.host in your config")
 			os.Exit(1)
 		}
-		base := fmt.Sprintf("http://%s:%d", rc.Host, rc.Port)
+		base := fmt.Sprintf("http://%s:%d", cfg.Remote.Host, cfg.Remote.Port)
 
 		sessionID := tryDeviceFlow(base)
 		if sessionID == "" {

src/cmd/root.go

@@ -12,12 +12,12 @@ import (
 )
 
 func getNodeService() (service.NodeService, error) {
-	user := cfg.GetUser()
+	user := cfg.User
 	if user == "" {
 		return nil, fmt.Errorf("no user configured: run 'ax user set <username>' first")
 	}
-	if rc, ok := cfg.GetRemoteConfig(); ok {
-		base := fmt.Sprintf("http://%s:%d", rc.Host, rc.Port)
+	if cfg.Remote.Host != "" {
+		base := fmt.Sprintf("http://%s:%d", cfg.Remote.Host, cfg.Remote.Port)
 		return service.NewRemoteNodeService(base, user), nil
 	}
 	st, err := store.FindAndOpenSQLiteStore()
@@ -33,7 +33,7 @@ var rootCmd = &cobra.Command{Use: "ax", Short: "The axolotl issue tracker"}
 
 func Execute() {
 	var err error
-	cfg, err = store.LoadConfigFile()
+	cfg, err = store.LoadConfig()
 	if err != nil {
 		fmt.Fprintln(os.Stderr, "failed to load config:", err)
 		os.Exit(1)
@@ -50,7 +50,7 @@ func init() {
 
 func RegisterAliasCommands() {
 	rootCmd.AddGroup(&cobra.Group{ID: "aliases", Title: "Aliases:"})
-	aliases, _ := cfg.ListAliases()
+	aliases := cfg.Aliases
 	for _, a := range aliases {
 		rootCmd.AddCommand(&cobra.Command{
 			Use:                a.Name,
@@ -59,7 +59,7 @@ func RegisterAliasCommands() {
 			DisableFlagParsing: true,
 			Run: func(ccmd *cobra.Command, args []string) {
 				acmd := a.Command
-				acmd = strings.ReplaceAll(acmd, "$me", cfg.GetUser())
+				acmd = strings.ReplaceAll(acmd, "$me", cfg.User)
 				parts := strings.Fields(acmd)
 				var expanded []string
 				usedArgs := make([]bool, len(args))

src/cmd/serve.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"net/http"
 	"os"
+	"time"
 
 	"github.com/spf13/cobra"
 )
@@ -15,12 +16,19 @@ var serveCmd = &cobra.Command{
 	Use:   "serve",
 	Short: "Start the JSON API server",
 	Run: func(cmd *cobra.Command, args []string) {
-		sc := cfg.GetServerConfig()
-		addr := fmt.Sprintf("%s:%d", sc.Host, sc.Port)
+		addr := fmt.Sprintf("%s:%d", cfg.Serve.Host, cfg.Serve.Port)
 
 		var oidcCfg *store.OIDCConfig
-		if oc, ok := cfg.GetOIDCConfig(); ok {
-			oidcCfg = oc
+		if cfg.OIDC.Issuer != "" {
+			oidcCfg = &cfg.OIDC
+		}
+
+		agentLookup := func(token string) string {
+			st, err := store.FindOrInitSQLiteStore()
+			if err != nil {
+				return ""
+			}
+			return service.LookupAgentToken(st, token)
 		}
 
 		handler, err := serve.New(func(user string) (service.NodeService, error) {
@@ -32,13 +40,20 @@ var serveCmd = &cobra.Command{
 				return nil, err
 			}
 			return service.NewLocalNodeService(st, user), nil
-		}, oidcCfg)
+		}, oidcCfg, agentLookup)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			os.Exit(1)
 		}
 		fmt.Fprintf(os.Stdout, "listening on %s\n", addr)
-		if err := http.ListenAndServe(addr, handler); err != nil {
+		srv := &http.Server{
+			Addr:         addr,
+			Handler:      handler,
+			ReadTimeout:  5 * time.Second,
+			WriteTimeout: 30 * time.Second,
+			IdleTimeout:  120 * time.Second,
+		}
+		if err := srv.ListenAndServe(); err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			os.Exit(1)
 		}

src/cmd/update.go

@@ -11,7 +11,7 @@ import (
 
 var (
 	uTitle, uContent, uDue               string
-	uClearDue                            bool
+	uClearDue, uRegenToken               bool
 	uStatus, uPrio, uType                string
 	uNamespace, uAssignee                string
 	uAddTags, uRmTags, uAddRels, uRmRels []string
@@ -83,12 +83,18 @@ var updateCmd = &cobra.Command{
 			}
 			input.RemoveRels = append(input.RemoveRels, ri)
 		}
+		if uRegenToken {
+			input.RegenerateAccessToken = true
+		}
 
 		n, err := svc.Update(args[0], input)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			os.Exit(1)
 		}
+		if uRegenToken {
+			printAgentToken(cmd.OutOrStdout(), n)
+		}
 		PrintNode(cmd.OutOrStdout(), svc, n, jsonFlag)
 	},
 }
@@ -109,4 +115,5 @@ func init() {
 	f.StringArrayVar(&uRmTags, "tag-remove", nil, "remove label tag")
 	f.StringArrayVar(&uAddRels, "rel", nil, "add relation (prefix::value or relname:target)")
 	f.StringArrayVar(&uRmRels, "rel-remove", nil, "remove relation (prefix::value or relname:target)")
+	f.BoolVar(&uRegenToken, "regenerate-access-token", false, "regenerate agent access token")
 }

src/e2e/e2e_aliases_test.go

@@ -2,7 +2,6 @@ package e2e_test
 
 import (
 	"encoding/json"
-	"slices"
 	"strings"
 	"testing"
 )
@@ -10,20 +9,14 @@ import (
 func TestAliases(t *testing.T) {
 	env := newTestEnv(t, "testuser")
 
-	t.Run("DefaultsPresent", func(t *testing.T) {
+	t.Run("EmptyByDefault", func(t *testing.T) {
 		out := env.mustAx("alias", "--json")
 		var aliases []map[string]string
 		if err := json.Unmarshal([]byte(out), &aliases); err != nil {
 			t.Fatalf("failed to parse alias JSON: %v\n%s", err, out)
 		}
-		names := make([]string, len(aliases))
-		for i, a := range aliases {
-			names[i] = a["name"]
-		}
-		for _, want := range []string{"mine", "due", "inbox"} {
-			if !slices.Contains(names, want) {
-				t.Errorf("default alias %q not found in: %v", want, names)
-			}
+		if len(aliases) != 0 {
+			t.Errorf("expected no aliases by default, got: %v", aliases)
 		}
 	})
 
@@ -46,22 +39,18 @@ func TestAliases(t *testing.T) {
 		}
 	})
 
-	t.Run("CannotDeleteDefault", func(t *testing.T) {
-		_, err := env.ax("alias", "del", "inbox")
-		if err == nil {
-			t.Fatal("expected error deleting default alias, got none")
-		}
-	})
-
 	t.Run("Execute_Due", func(t *testing.T) {
-		// The built-in 'due' alias lists open issues.
+		env.mustAx("alias", "due", "list --due")
 		out := env.mustAx("due", "--json")
 		env.parseNodes(out)
+		env.mustAx("alias", "del", "due")
 	})
 
 	t.Run("Execute_Mine_WithMeExpansion", func(t *testing.T) {
 		// 'mine' expands $me to AX_USER=testuser.
+		env.mustAx("alias", "mine", "list --assignee $me")
 		out := env.mustAx("mine", "--json")
 		env.parseNodes(out)
+		env.mustAx("alias", "del", "mine")
 	})
 }

src/serve/auth.go

@@ -144,13 +144,13 @@ func (h *authHandler) callback(w http.ResponseWriter, r *http.Request) {
 		oauth2.SetAuthURLParam("code_verifier", pending.verifier),
 	)
 	if err != nil {
-		http.Error(w, "token exchange failed: "+err.Error(), http.StatusBadRequest)
+		http.Error(w, "token exchange failed", http.StatusBadRequest)
 		return
 	}
 
 	username, err := h.extractUsername(r.Context(), token)
 	if err != nil {
-		http.Error(w, "failed to identify user: "+err.Error(), http.StatusInternalServerError)
+		http.Error(w, "failed to identify user", http.StatusInternalServerError)
 		return
 	}
 
@@ -177,7 +177,7 @@ func (h *authHandler) deviceStart(w http.ResponseWriter, r *http.Request) {
 		oauth2.SetAuthURLParam("client_secret", h.cfg.ClientSecret),
 	)
 	if err != nil {
-		writeError(w, http.StatusBadGateway, "device authorization request failed: "+err.Error())
+		writeError(w, http.StatusBadGateway, "device authorization request failed")
 		return
 	}
 
@@ -196,7 +196,7 @@ func (h *authHandler) deviceStart(w http.ResponseWriter, r *http.Request) {
 		if err != nil {
 			h.mu.Lock()
 			if p := h.pendingDevice[loginID]; p != nil {
-				p.err = err.Error()
+				p.err = "device token exchange failed"
 			}
 			h.mu.Unlock()
 			return
@@ -206,7 +206,7 @@ func (h *authHandler) deviceStart(w http.ResponseWriter, r *http.Request) {
 		if err != nil {
 			h.mu.Lock()
 			if p := h.pendingDevice[loginID]; p != nil {
-				p.err = "failed to identify user: " + err.Error()
+				p.err = "failed to identify user"
 			}
 			h.mu.Unlock()
 			return

src/serve/oidc.go

@@ -13,7 +13,8 @@ const userContextKey contextKey = "ax_user"
 // withSessionAuth wraps a handler with ax session token authentication.
 // Auth endpoints (/auth/*) are passed through without a token check.
 // All other requests must supply Authorization: Bearer <server_token>.
-func withSessionAuth(ah *authHandler, next http.Handler) http.Handler {
+// If the token is not a valid OIDC session, agentLookup is tried as a fallback.
+func withSessionAuth(ah *authHandler, agentLookup func(string) string, next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if strings.HasPrefix(r.URL.Path, "/auth/") {
 			next.ServeHTTP(w, r)
@@ -26,6 +27,9 @@ func withSessionAuth(ah *authHandler, next http.Handler) http.Handler {
 		}
 		token := strings.TrimPrefix(auth, "Bearer ")
 		username := ah.lookupSession(token)
+		if username == "" && agentLookup != nil {
+			username = agentLookup(token)
+		}
 		if username == "" {
 			writeError(w, http.StatusUnauthorized, "invalid or expired session; run 'ax login'")
 			return

src/serve/ratelimit.go

@@ -0,0 +1,86 @@
+package serve
+
+import (
+	"net/http"
+	"sync"
+	"time"
+)
+
+type visitor struct {
+	tokens   float64
+	lastSeen time.Time
+}
+
+type rateLimiter struct {
+	mu       sync.Mutex
+	visitors map[string]*visitor
+	rate     float64 // tokens per second
+	burst    float64 // max tokens
+}
+
+func newRateLimiter(rate float64, burst int) *rateLimiter {
+	rl := &rateLimiter{
+		visitors: make(map[string]*visitor),
+		rate:     rate,
+		burst:    float64(burst),
+	}
+	go rl.cleanup()
+	return rl
+}
+
+func (rl *rateLimiter) allow(ip string) bool {
+	rl.mu.Lock()
+	defer rl.mu.Unlock()
+
+	v, exists := rl.visitors[ip]
+	now := time.Now()
+	if !exists {
+		rl.visitors[ip] = &visitor{tokens: rl.burst - 1, lastSeen: now}
+		return true
+	}
+
+	elapsed := now.Sub(v.lastSeen).Seconds()
+	v.lastSeen = now
+	v.tokens += elapsed * rl.rate
+	if v.tokens > rl.burst {
+		v.tokens = rl.burst
+	}
+
+	if v.tokens < 1 {
+		return false
+	}
+	v.tokens--
+	return true
+}
+
+func (rl *rateLimiter) cleanup() {
+	for range time.Tick(time.Minute) {
+		rl.mu.Lock()
+		for ip, v := range rl.visitors {
+			if time.Since(v.lastSeen) > 5*time.Minute {
+				delete(rl.visitors, ip)
+			}
+		}
+		rl.mu.Unlock()
+	}
+}
+
+func clientIP(r *http.Request) string {
+	if ip := r.Header.Get("X-Forwarded-For"); ip != "" {
+		return ip
+	}
+	if ip := r.Header.Get("X-Real-IP"); ip != "" {
+		return ip
+	}
+	return r.RemoteAddr
+}
+
+func withRateLimit(rl *rateLimiter, next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !rl.allow(clientIP(r)) {
+			writeError(w, http.StatusTooManyRequests, "rate limit exceeded")
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}

src/serve/server.go

@@ -14,8 +14,8 @@ import (
 // When oidcCfg is non-nil, every request must carry a valid Bearer token;
 // the authenticated username is derived from the token claim configured in
 // OIDCConfig.UserClaim. Without OIDC, the X-Ax-User header is used instead.
-func New(newSvc func(user string) (service.NodeService, error), oidcCfg *store.OIDCConfig) (http.Handler, error) {
-	s := &server{newSvc: newSvc}
+func New(newSvc func(user string) (service.NodeService, error), oidcCfg *store.OIDCConfig, agentLookup func(string) string) (http.Handler, error) {
+	s := &server{newSvc: newSvc, agentLookup: agentLookup}
 	mux := http.NewServeMux()
 	mux.HandleFunc("GET /nodes", s.listNodes)
 	mux.HandleFunc("POST /nodes", s.addNode)
@@ -24,6 +24,8 @@ func New(newSvc func(user string) (service.NodeService, error), oidcCfg *store.O
 	mux.HandleFunc("DELETE /nodes/{id}", s.deleteNode)
 	mux.HandleFunc("GET /users", s.listUsers)
 	mux.HandleFunc("POST /users", s.addUser)
+	rl := newRateLimiter(10, 30) // 10 req/s sustained, burst of 30
+
 	if oidcCfg != nil {
 		ah, err := newAuthHandler(*oidcCfg)
 		if err != nil {
@@ -33,17 +35,23 @@ func New(newSvc func(user string) (service.NodeService, error), oidcCfg *store.O
 		mux.HandleFunc("POST /auth/device/start", ah.deviceStart)
 		mux.HandleFunc("GET /auth/callback", ah.callback)
 		mux.HandleFunc("GET /auth/poll", ah.poll)
-		return withSessionAuth(ah, mux), nil
+		return withRateLimit(rl, withSessionAuth(ah, agentLookup, mux)), nil
 	}
-	return mux, nil
+	return withRateLimit(rl, mux), nil
 }
 
 type server struct {
-	newSvc func(user string) (service.NodeService, error)
+	newSvc      func(user string) (service.NodeService, error)
+	agentLookup func(string) string
 }
 
 func (s *server) svc(w http.ResponseWriter, r *http.Request) (service.NodeService, bool) {
 	user := userFromContext(r)
+	if user == "" && s.agentLookup != nil {
+		if auth := r.Header.Get("Authorization"); strings.HasPrefix(auth, "Bearer ") {
+			user = s.agentLookup(strings.TrimPrefix(auth, "Bearer "))
+		}
+	}
 	if user == "" {
 		user = r.Header.Get("X-Ax-User")
 	}
@@ -53,7 +61,7 @@ func (s *server) svc(w http.ResponseWriter, r *http.Request) (service.NodeServic
 	}
 	svc, err := s.newSvc(user)
 	if err != nil {
-		writeError(w, http.StatusInternalServerError, err.Error())
+		writeError(w, http.StatusInternalServerError, "internal error")
 		return nil, false
 	}
 	return svc, true
@@ -96,7 +104,7 @@ func (s *server) listNodes(w http.ResponseWriter, r *http.Request) {
 	}
 	nodes, err := svc.List(filter)
 	if err != nil {
-		writeError(w, http.StatusInternalServerError, err.Error())
+		writeError(w, http.StatusInternalServerError, "internal error")
 		return
 	}
 	writeJSON(w, nodes)
@@ -171,7 +179,7 @@ func (s *server) listUsers(w http.ResponseWriter, r *http.Request) {
 	}
 	users, err := svc.ListUsers()
 	if err != nil {
-		writeError(w, http.StatusInternalServerError, err.Error())
+		writeError(w, http.StatusInternalServerError, "internal error")
 		return
 	}
 	writeJSON(w, users)

src/service/api_client.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"net/http"
 	"net/url"
+	"os"
 	"strconv"
 )
 
@@ -42,6 +43,11 @@ func (c *apiClient) do(method, path string, body any) (*http.Response, error) {
 // setAuth attaches either a Bearer token (when a session exists) or the
 // X-Ax-User header (no session / non-OIDC servers).
 func (c *apiClient) setAuth(req *http.Request) error {
+	// Agent token takes priority (stateless, no login needed).
+	if token := os.Getenv("AX_TOKEN"); token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+		return nil
+	}
 	sess, err := store.LoadSession()
 	if err != nil || sess == nil || sess.Token == "" {
 		req.Header.Set("X-Ax-User", c.user)

src/service/node_service.go

@@ -47,12 +47,13 @@ type AddInput struct {
 // Adding an assignee rel replaces the previous single target.
 // Setting Namespace transfers ownership from the current namespace to the new one.
 type UpdateInput struct {
-	Title      *string
-	Content    *string
-	DueDate    *string // nil = no change; pointer to "" = clear due date
-	Namespace  *string // nil = no change; namespace name or ID to move node into
-	AddRels    []RelInput
-	RemoveRels []RelInput
+	Title                 *string
+	Content               *string
+	DueDate               *string // nil = no change; pointer to "" = clear due date
+	Namespace             *string // nil = no change; namespace name or ID to move node into
+	AddRels               []RelInput
+	RemoveRels            []RelInput
+	RegenerateAccessToken bool // when true, regenerates the access token for agent nodes
 }
 
 // ListFilter specifies which nodes to return. Empty slices are ignored.

src/service/node_service_impl.go

@@ -3,6 +3,10 @@ package service
 import (
 	"axolotl/models"
 	"axolotl/store"
+	"crypto/rand"
+	"crypto/subtle"
+	"encoding/base64"
+	"encoding/json"
 	"fmt"
 	"maps"
 	"regexp"
@@ -11,6 +15,39 @@ import (
 	"time"
 )
 
+// agentContent is the JSON structure stored in agent node content.
+type agentContent struct {
+	AccessToken string `json:"access_token"`
+}
+
+// generateAccessToken returns a cryptographically random base64url token.
+func generateAccessToken() (string, error) {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return "", err
+	}
+	return base64.RawURLEncoding.EncodeToString(b), nil
+}
+
+// LookupAgentToken finds the agent node whose content contains the given
+// access token. Returns the agent node ID, or "" if not found.
+func LookupAgentToken(st store.GraphStore, token string) string {
+	agents, err := st.FindNodes([]*models.Rel{{Type: "_type::agent", Target: ""}})
+	if err != nil {
+		return ""
+	}
+	for _, agent := range agents {
+		var c agentContent
+		if err := json.Unmarshal([]byte(agent.Content), &c); err != nil {
+			continue
+		}
+		if subtle.ConstantTimeCompare([]byte(c.AccessToken), []byte(token)) == 1 {
+			return agent.ID
+		}
+	}
+	return ""
+}
+
 type nodeServiceImpl struct {
 	store  store.GraphStore
 	userID string
@@ -105,9 +142,16 @@ func (pc *permContext) hasOwnership(nodeID string) bool { return pc.levels[nodeI
 // If the user node doesn't exist yet, returns an empty permContext (no access);
 // Add operations still work because unresolved targets skip the permission check.
 func (s *nodeServiceImpl) getPermContext() (*permContext, error) {
-	userNodeID, err := s.resolveIDByNameAndType(s.store, s.userID, "user")
-	if err != nil {
-		return nil, err
+	// If userID is already a node ID (e.g. for agents), use it directly.
+	var userNodeID string
+	if exists, _ := s.store.NodeExists(s.userID); exists {
+		userNodeID = s.userID
+	} else {
+		var err error
+		userNodeID, err = s.resolveIDByNameAndType(s.store, s.userID, "user")
+		if err != nil {
+			return nil, err
+		}
 	}
 	pc := &permContext{levels: make(map[string]int)}
 	if userNodeID == "" {
@@ -158,7 +202,7 @@ func (s *nodeServiceImpl) getPermContext() (*permContext, error) {
 // --- Validation ---
 
 var (
-	validTypes    = map[string]bool{"issue": true, "note": true, "user": true, "namespace": true}
+	validTypes    = map[string]bool{"issue": true, "note": true, "user": true, "namespace": true, "agent": true}
 	validStatuses = map[string]bool{"open": true, "done": true}
 	validPrios    = map[string]bool{"high": true, "medium": true, "low": true}
 )
@@ -349,6 +393,16 @@ func (s *nodeServiceImpl) Add(input AddInput) (*models.Node, error) {
 		}
 	}
 
+	// Agent nodes get an auto-generated access token stored as JSON content.
+	if tmp.GetProperty("type") == "agent" {
+		token, err := generateAccessToken()
+		if err != nil {
+			return nil, fmt.Errorf("failed to generate access token: %w", err)
+		}
+		data, _ := json.Marshal(agentContent{AccessToken: token})
+		input.Content = string(data)
+	}
+
 	dueDate, err := parseDueDate(input.DueDate)
 	if err != nil {
 		return nil, err
@@ -419,8 +473,15 @@ func (s *nodeServiceImpl) Add(input AddInput) (*models.Node, error) {
 			}
 		}
 
+		// Agent nodes get self-ownership (like users).
+		if tmp.GetProperty("type") == "agent" {
+			if err := st.AddRel(id, string(models.RelHasOwnership), id); err != nil {
+				return err
+			}
+		}
+
 		// Grant ownership of the new node.
-		// Namespace nodes are owned by their creator (user node).
+		// Namespace and agent nodes are owned by their creator (user node).
 		// All other nodes are owned by the namespace they belong to — the user
 		// retains transitive ownership through the namespace's own ownership chain
 		// (e.g. user→has_ownership→default-ns→has_ownership→node).
@@ -429,7 +490,8 @@ func (s *nodeServiceImpl) Add(input AddInput) (*models.Node, error) {
 			return err
 		}
 		ownerID := creatorID
-		if tmp.GetProperty("type") != "namespace" {
+		nodeType := tmp.GetProperty("type")
+		if nodeType != "namespace" && nodeType != "agent" {
 			nsRef := input.Namespace
 			if nsRef == "" {
 				nsRef = s.userID
@@ -465,7 +527,7 @@ func (s *nodeServiceImpl) Update(id string, input UpdateInput) (*models.Node, er
 	}
 
 	// Field/tag changes, rel removals, and namespace change require can_write on the node.
-	needsWrite := input.Title != nil || input.Content != nil || input.DueDate != nil || input.Namespace != nil
+	needsWrite := input.Title != nil || input.Content != nil || input.DueDate != nil || input.Namespace != nil || input.RegenerateAccessToken
 	for _, ri := range input.AddRels {
 		if ri.Target == "" {
 			needsWrite = true
@@ -548,8 +610,22 @@ func (s *nodeServiceImpl) Update(id string, input UpdateInput) (*models.Node, er
 			title = *input.Title
 		}
 		if input.Content != nil {
+			if current.GetProperty("type") == "agent" {
+				return fmt.Errorf("cannot set content on agent nodes; use --regenerate-access-token to rotate the token")
+			}
 			content = *input.Content
 		}
+		if input.RegenerateAccessToken {
+			if current.GetProperty("type") != "agent" {
+				return fmt.Errorf("cannot regenerate access token: node is not an agent")
+			}
+			token, err := generateAccessToken()
+			if err != nil {
+				return fmt.Errorf("failed to generate access token: %w", err)
+			}
+			data, _ := json.Marshal(agentContent{AccessToken: token})
+			content = string(data)
+		}
 		if input.DueDate != nil {
 			parsed, err := parseDueDate(*input.DueDate)
 			if err != nil {

src/store/config.go

@@ -2,40 +2,26 @@ package store
 
 import (
 	"encoding/json"
-	"errors"
 	"fmt"
 	"os"
 	"os/user"
 	"path/filepath"
-	"slices"
 )
 
-var builtinAliases = []*Alias{
-	{Name: "mine", Command: "list --assignee $me", Description: "My assigned issues"},
-	{Name: "due", Command: "list --status open", Description: "Open issues"},
-	{Name: "inbox", Command: "list --mention $me", Description: "My mentions"},
-}
-
-func isBuiltinAlias(name string) bool {
-	for _, a := range builtinAliases {
-		if a.Name == name {
-			return true
-		}
-	}
-	return false
-}
-
+// Alias defines a user-defined command shortcut.
 type Alias struct {
 	Name        string `json:"name"`
 	Command     string `json:"command"`
 	Description string `json:"description,omitempty"`
 }
 
+// ServerConfig holds a host:port pair used for both the local server and the remote connection.
 type ServerConfig struct {
 	Host string `json:"host"`
 	Port int    `json:"port"`
 }
 
+// OIDCConfig holds the settings needed to authenticate users via OpenID Connect.
 type OIDCConfig struct {
 	Issuer       string `json:"issuer"`
 	ClientID     string `json:"client_id"`
@@ -44,16 +30,86 @@ type OIDCConfig struct {
 	UserClaim    string `json:"user_claim"`
 }
 
+// Config is the central configuration object for ax, loaded from config.json.
 type Config struct {
-	path        string
-	User        string       `json:"user"`
-	Editor      string       `json:"editor"`
-	UserAliases []*Alias     `json:"aliases"`
-	Serve       ServerConfig `json:"serve"`
-	Remote      ServerConfig `json:"remote"`
-	OIDC        OIDCConfig   `json:"oidc"`
+	path    string
+	User    string       `json:"user"`
+	Editor  string       `json:"editor"`
+	Aliases []*Alias     `json:"aliases"`
+	Serve   ServerConfig `json:"serve"`
+	Remote  ServerConfig `json:"remote"`
+	OIDC    OIDCConfig   `json:"oidc"`
 }
 
+// LoadConfig reads config.json from the data root and applies environment
+// variable overrides (AX_USER, EDITOR) and sensible defaults for any
+// unset fields. If no config file exists, a default config is returned.
+func LoadConfig() (*Config, error) {
+	configRoot, err := FindDataRoot(".config")
+	if err != nil {
+		return nil, err
+	}
+	path := filepath.Join(configRoot, "config.json")
+	c := &Config{path: path, Aliases: []*Alias{}}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if !os.IsNotExist(err) {
+			return nil, err
+		}
+	} else {
+		if err := json.Unmarshal(data, c); err != nil {
+			return nil, err
+		}
+	}
+
+	// Apply env overrides and defaults.
+	if c.User == "" {
+		c.User = os.Getenv("AX_USER")
+	}
+	if c.User == "" {
+		if u, err := user.Current(); err == nil {
+			c.User = u.Username
+		} else {
+			c.User = "unknown"
+		}
+	}
+	if c.Editor == "" {
+		c.Editor = os.Getenv("EDITOR")
+	}
+	if c.Editor == "" {
+		c.Editor = "vi"
+	}
+	if c.Serve.Host == "" {
+		c.Serve.Host = "localhost"
+	}
+	if c.Serve.Port == 0 {
+		c.Serve.Port = 7000
+	}
+	if c.Remote.Host != "" && c.Remote.Port == 0 {
+		c.Remote.Port = 7000
+	}
+	if c.OIDC.Issuer != "" && c.OIDC.UserClaim == "" {
+		c.OIDC.UserClaim = "preferred_username"
+	}
+
+	return c, nil
+}
+
+// Save writes the config back to disk as indented JSON.
+func (c *Config) Save() error {
+	if err := os.MkdirAll(filepath.Dir(c.path), 0755); err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(c, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(c.path, data, 0644)
+}
+
+// FindDataRoot locates the .ax directory by walking up from the current
+// working directory. If none is found, it falls back to ~/<std>/ax
+// (e.g. ~/.config/ax or ~/.local/share/ax).
 func FindDataRoot(std ...string) (string, error) {
 	dir, err := filepath.Abs(".")
 	if err != nil {
@@ -74,145 +130,8 @@ func FindDataRoot(std ...string) (string, error) {
 	}
 	home, err := os.UserHomeDir()
 	if err != nil {
-		return "", err
+		return "", fmt.Errorf("could not determine home directory: %w", err)
 	}
 	stdpath := filepath.Join(std...)
 	return filepath.Join(home, stdpath, "ax"), nil
 }
-
-func LoadConfigFile() (*Config, error) {
-	configRoot, err := FindDataRoot(".config")
-	if err != nil {
-		return nil, err
-	}
-	path := filepath.Join(configRoot, "config.json")
-	fc := &Config{path: path, UserAliases: []*Alias{}}
-	data, err := os.ReadFile(path)
-	if err != nil {
-		if !os.IsNotExist(err) {
-			return nil, err
-		}
-	} else {
-		if err := json.Unmarshal(data, fc); err != nil {
-			return nil, err
-		}
-	}
-	return fc, nil
-}
-
-func (c *Config) GetUser() string {
-	if c.User != "" {
-		return c.User
-	}
-	if u := os.Getenv("AX_USER"); u != "" {
-		return u
-	}
-	if u, err := user.Current(); err == nil {
-		return u.Username
-	}
-	return "unknown"
-}
-
-func (c *Config) GetEditor() string {
-	if c.Editor != "" {
-		return c.User
-	}
-	if u := os.Getenv("EDITOR"); u != "" {
-		return u
-	}
-	return "vi"
-}
-
-func (c *Config) GetAlias(name string) (*Alias, error) {
-	for _, a := range c.UserAliases {
-		if a.Name == name {
-			return a, nil
-		}
-	}
-	return nil, errors.New("alias not found")
-}
-
-func (c *Config) SetAlias(alias *Alias) error {
-	for i, a := range c.UserAliases {
-		if a.Name == alias.Name {
-			c.UserAliases[i] = alias
-			return c.Save()
-		}
-	}
-	c.UserAliases = append(c.UserAliases, alias)
-	return c.Save()
-}
-
-func (c *Config) DeleteAlias(name string) error {
-	if isBuiltinAlias(name) {
-		return fmt.Errorf("cannot delete built-in alias %q", name)
-	}
-	for i, a := range c.UserAliases {
-		if a.Name == name {
-			c.UserAliases = slices.Delete(c.UserAliases, i, i+1)
-			return c.Save()
-		}
-	}
-	return errors.New("alias not found")
-}
-
-func (c *Config) ListAliases() ([]*Alias, error) {
-	seen := make(map[string]bool)
-	var result []*Alias
-	for _, a := range builtinAliases {
-		result = append(result, a)
-		seen[a.Name] = true
-	}
-	for _, a := range c.UserAliases {
-		if !seen[a.Name] {
-			result = append(result, a)
-			seen[a.Name] = true
-		}
-	}
-	return result, nil
-}
-
-func (c *Config) GetOIDCConfig() (*OIDCConfig, bool) {
-	if c.OIDC.Issuer == "" {
-		return nil, false
-	}
-	cfg := c.OIDC
-	if cfg.UserClaim == "" {
-		cfg.UserClaim = "preferred_username"
-	}
-	return &cfg, true
-}
-
-func (c *Config) GetRemoteConfig() (*ServerConfig, bool) {
-	if c.Remote.Host == "" {
-		return nil, false
-	}
-	port := c.Remote.Port
-	if port == 0 {
-		port = 7000
-	}
-	return &ServerConfig{Host: c.Remote.Host, Port: port}, true
-}
-
-func (c *Config) GetServerConfig() *ServerConfig {
-	host := c.Serve.Host
-	if host == "" {
-		host = "localhost"
-	}
-	port := c.Serve.Port
-	if port == 0 {
-		port = 7000
-	}
-	return &ServerConfig{Host: host, Port: port}
-}
-
-func (c *Config) Save() error {
-	if err := os.MkdirAll(filepath.Dir(c.path), 0755); err != nil {
-		return err
-	}
-	data, err := json.MarshalIndent(c, "", "  ")
-	if err != nil {
-		return err
-	}
-	return os.WriteFile(c.path, data, 0644)
-}

src/store/session.go

@@ -13,6 +13,8 @@ type Session struct {
 	Token string `json:"token"`
 }
 
+// LoadSession reads the session token from disk. If no session file
+// exists, an empty Session is returned (Token will be "").
 func LoadSession() (*Session, error) {
 	sessionRoot, err := FindDataRoot(".local", "share")
 	if err != nil {
@@ -34,6 +36,7 @@ func LoadSession() (*Session, error) {
 	return &s, nil
 }
 
+// Save writes the session token to disk with restrictive permissions (0600).
 func (s *Session) Save() error {
 	if err := os.MkdirAll(filepath.Dir(s.path), 0700); err != nil {
 		return err
@@ -45,6 +48,7 @@ func (s *Session) Save() error {
 	return os.WriteFile(s.path, data, 0600)
 }
 
+// ClearSession deletes the session file from disk.
 func (s *Session) ClearSession() error {
 	err := os.Remove(s.path)
 	if os.IsNotExist(err) {