feat(mail): add Bot-bound Agent Mail commands

Add Bot- and Space-bound Agent Mail authorization, encrypted mailbox credentials, guarded send and Draft workflows, JMAP polling support, and agent-facing skill guidance. Keep dry-run network-free, bind mailbox credentials to the authorizing Bot token and normalized API origin, and surface ambiguous send outcomes safely.\n\nRefs #128

Author: lxy

CLAUDE.md

@@ -22,14 +22,26 @@
 - **Credential resolution** (see `internal/credential`, `internal/authstore`): a token comes from a stored encrypted profile or, as a fallback, an env var — `OCTO_TOKEN` first, then `OCTO_BOT_TOKEN`. The credential's `Source` records which variable was used, so the envelope's `identity.source` cannot mislead. Stored profiles live in `~/.octo-cli` (override `OCTO_CONFIG_DIR`): metadata in plaintext `config.json`, tokens in AES-256-GCM `credentials.enc`. Manage them with `octo-cli auth`.
 - **Per-domain token gate and mount routing**: a spec may declare which token kinds it accepts and which server mount each kind uses. `drive` accepts all three and routes `uk_*` to `/v1/user/drive/*`, bots to `/v1/bot/drive/*`. An incompatible kind fails locally with `TOKEN_KIND_NOT_ALLOWED` (`validation`, exit 2 — switch credentials, don't re-auth), implemented once in `cmd/service/identity.go` and reused by the hand-written drive composites via `service.MountForOperation`. Generated leaves and composites alike resolve identity **before** `--dry-run` or any local success return, so a refused credential can never have a request described for it or a document link resolved under it.
 - **Lossless uint64 ids**: `drive` file ids are backend uint64s. Inputs are decimal-string flags validated in `[0, 2^64-1]` and sent as JSON integers; responses are emitted as decimal strings. Go's `int` cannot hold the upper half of the range and a `float64` would round above 2^53, so neither is used on this path. The rule holds for *every* output format, not just `json`: the row extraction behind `--format table|csv|ndjson` decodes with `UseNumber` too, so a large integer a spec did not declare as a lossless field still prints the digits the backend sent rather than a rounded float.
-- **Selecting a credential at runtime**: `--bot-id <robot_id>` (env `OCTO_BOT_ID`) is the agent's primary selector — robot ids are self-known; `--profile <name>` selects by friendly name. With exactly one profile, selection is implicit; with **two or more, a selector is required** (ambiguity is a hard error, never a silent guess). Precedence: selector > sole/implicit profile > `OCTO_BOT_TOKEN`. The success envelope's `identity` echoes the active `{profile, robot_id, bot_kind, source}` so misuse is visible.
+- **Selecting a credential at runtime**: `--bot-id <robot_id>` (env `OCTO_BOT_ID`) is the agent's primary selector — robot ids are self-known; `--profile <name>` selects by friendly name. With exactly one profile, selection is implicit; with **two or more, a selector is required** (ambiguity is a hard error, never a silent guess). Precedence: selector > sole/implicit profile > `OCTO_BOT_TOKEN`. An explicit `--bot-id` always selects a stored profile and fails closed when none exists; `OCTO_BOT_ID` may instead label an environment token when the profile store is empty. The success envelope reports that unverified environment value as `identity.robot_id_claimed`; `identity.robot_id` is reserved for a stored or verified binding.
 - **Isolation boundary = OS user**: the encryption key is machine-derived, so the store resists off-machine leakage (commit/backup/sync) but not a same-user process. Isolate mutually-distrusting bots with separate OS users or `OCTO_CONFIG_DIR` values.
 - **Daemon task isolation**: `OCTO_CREDENTIAL_MODE=task` selects the restricted Loop-only policy but cannot protect against a process rewriting its own environment. Daemon task processes must receive an isolated `OCTO_CONFIG_DIR` with no host profiles and the short-lived `OCTO_BOT_TOKEN`.
 - Each Bot has an **owner**; operations are attributed to the Bot identity. For LLM-backed paths (`matter extract`) the bot acts on behalf of its owner — pass `owner_uid` as `creator_uid`.
 - **Search subjects** (`message search` family): a `bf_` token searches as the bot, or as a real person with `--on-behalf-of <uid>` (OBO — requires an active grant); a `uk_` token searches as the real person it belongs to. An `app_` token cannot search — the CLI rejects it locally (`validation`, in `internal/client/search_route.go`) before any request, distinct from a server-side `FORBIDDEN`.
 - `OCTO_SPACE_ID` (or `--space`) supplies space context for platform-scoped bots. Space-scoped bots resolve their space server-side.
-
-## Command Structure (11 active domains, 284 operations)
+- Agent Mail authorization is attached to the current Bot and Space.
+  The Bot may come from a stored profile or the same runtime-provided
+  `OCTO_BOT_TOKEN` used by every other service. A real authorization login
+  resolves the authoritative RobotID through `/v1/bot/register`; `--dry-run`
+  never performs that lookup. The mailbox token is kept in a dedicated
+  encrypted file under `OCTO_CONFIG_DIR`, keyed by RobotID, SpaceID, the
+  normalized Octo API origin, and a SHA-256 fingerprint of the authorizing Bot
+  token. This prevents a replaced Bot token, another Space, or another gateway
+  origin from unlocking the old mailbox credential without storing the Bot
+  token again. Changing the API origin therefore requires a Mail authorization
+  for that origin. Mail never uses a separate token or base-URL environment
+  variable.
+
+## Command Structure (12 active domains, 308 operations)
 
 Service commands are auto-registered. The hand-written leaves are `schema`, `version`, `api` (generic passthrough), `config`, `auth`, and the cobra-generated `completion`.
 
@@ -84,17 +96,28 @@ octo-cli html      list | get | publish | versions | rm     (octo-doc HTML docs;
                element  get|replace
                reply
 
-octo-cli auth      login | status | logout | list
+octo-cli mail      me
+               auth login|status
+               mailbox list
+               address list
+               thread get
+               message list|read|raw|send|send-intent|reply|reply-draft
+                       reply-all|forward|flag|delete|delivery|auto-reply-context
+                       state|changes
+                       attachment download
+               draft list|create|create-agent|update|send|delete
+
+octo-cli auth      login | status | update | logout | list
 octo-cli schema [--list [domain] | <operation-id>]
 octo-cli api <METHOD> <PATH> [--params ...] [--data ...] [--service ...]
 octo-cli config show
 octo-cli completion bash|zsh|fish|powershell
 octo-cli version
 ```
 
-`octo-cli auth login` stores a bot token (read from a hidden prompt, `--with-token` stdin, or `--token-file` — never argv) under a profile keyed by `--bot-id`/`--profile`. `status`/`list` show metadata only (tokens always masked); `logout` removes a profile.
+`octo-cli auth login` stores a bot token (read from a hidden prompt, `--with-token` stdin, or `--token-file` — never argv) under a profile keyed by `--bot-id`/`--profile`. `update` changes non-secret profile settings such as the API base URL without re-entering or rewriting the token. `status`/`list` show metadata only (tokens always masked); `logout` removes a profile.
 
-Bot-type capability and per-command flags are in `docs/octo-cli-design.md`. Agent-facing usage lives under `skills/` (`octo-shared`, `octo-matter` (withheld — see above), `octo-summary` (withheld — see CHANGELOG "Currently withheld" note), `octo-messaging`, `octo-files`, `octo-drive`, `octo-docs`, `octo-html`, `octo-marketplace`) — keep those in sync when command shapes change.
+Bot-type capability and per-command flags are in `docs/octo-cli-design.md`. Agent-facing usage lives under `skills/` (`octo-shared`, `octo-matter` (withheld — see above), `octo-summary` (withheld — see CHANGELOG "Currently withheld" note), `octo-messaging`, `octo-files`, `octo-drive`, `octo-docs`, `octo-html`, `octo-marketplace`, `octo-mail`) — keep those in sync when command shapes change.
 
 The hand-written drive leaves (`cmd/drive*.go`) are the exception to "everything is generated": `upload file` / `download file` / `share download` are multi-request transfers, `share create` branches on node type, and `share blob-create` / `share access` / `share download` take an argument shape (positional body field, whole share URL) the engine cannot express. They replace the generated leaf of the same name where one exists, so the spec still documents the endpoint for `octo-cli schema`.
 

README.md

@@ -128,6 +128,14 @@ octo-cli thread create group-abc --name "design review"
 octo-cli file upload --file ./report.pdf
 octo-cli file download abc123 --jq '.data.url'
 
+# Agent Mail — policy-aware send; the server may accept it or save a Draft
+# depending on the mailbox's current outbound mode.
+octo-cli mail message send-intent \
+  --to recipient@example.com --subject "Status update" --text "Ready." \
+  --idempotency-key "send-example-001"
+octo-cli mail thread get T123
+octo-cli mail draft list
+
 # Docs — create/list/search, then read and incrementally edit the live body.
 octo-cli docs create --title "Design notes"
 octo-cli docs list --sort updatedAt:desc
@@ -181,6 +189,7 @@ octo-cli schema --list              # all operations across all domains
 octo-cli schema --list message      # operations in one domain
 octo-cli schema message.send        # request/response schema for one op
 octo-cli config show                # resolved config (token masked)
+octo-cli auth update --api-base-url https://octo.example # persist endpoint for the active profile
 
 # Generic passthrough for ops that aren't auto-registered.
 octo-cli api GET  /v1/messages --params '{"chat_id":"chat-1"}'
@@ -350,6 +359,8 @@ Machine-readable usage docs for AI Agents live under [`skills/`](./skills/):
   **separate backend** from `octo-docs`): publish immutable versions, drafts,
   share codes & per-uid grants, media assets, inline comments, agent element
   read/replace.
+- [`octo-mail`](./skills/octo-mail/SKILL.md) — Agent Mail authorization,
+  mailbox access, message handling, drafts, attachments, and delivery status.
 - [`octo-summary`](./skills/octo-summary/SKILL.md) — create owner-only summaries
   from explicit sources, then discover, read, and cite summaries visible to the
   personal Agent's human owner. **Temporarily withheld** while the create
@@ -360,6 +371,7 @@ These docs are also **embedded in the binary**, so a released `octo-cli` ships t
 
 ```bash
 octo-cli skills                       # list embedded skills
+octo-cli skills octo-mail             # load the official Agent Mail guide
 octo-cli skills octo-docs             # print one skill (SKILL.md + its references)
 octo-cli skills --install ~/.config/octo/skills   # write every skill (SKILL.md + references) to a dir
 ```

cmd/api_secrets_test.go

@@ -425,10 +425,13 @@ func TestAPI_AStringValueAtASecretPropertyStillWorks(t *testing.T) {
 
 // TestSecrets_NoSpecDeclaresASecretApiCannotCollectOrMask is round-16 P2-2's tripwire.
 //
-// `api` recovers secrets by matching the concrete path and walking the body, which leaves
-// two declarations it would silently ignore: a secret in *query* or *header* position (
-// pathSegments drops the query component and headers are not read at all), and a secret on a
-// non-string schema, which the request side now refuses outright rather than masks.
+// `api` recovers secrets by matching the concrete path and walking the body, which leaves a
+// secret in *query* position unmasked because pathSegments drops the query component. A
+// header declaration is safe here: the generic command has no arbitrary-header input, so
+// there is no caller-supplied header value for it to collect; generated commands collect
+// those values from their bound flags. If `api` ever gains a header option, its own tests must
+// extend apiSecretsForRequest before that option ships. A secret on a non-string schema is
+// likewise unsupported because the request side refuses it outright rather than masking it.
 //
 // No embedded spec declares either today, which is why neither is a live leak — but nothing
 // pinned that, so adding one would produce an unmasked credential-equivalent value with no
@@ -448,10 +451,10 @@ func TestSecrets_NoSpecDeclaresASecretApiCannotCollectOrMask(t *testing.T) {
 				if !p.Secret {
 					continue
 				}
-				if p.In != "path" {
+				if p.In != "path" && p.In != "header" {
 					t.Errorf("%s declares x-octo-secret on a %s parameter %q, but `api` only "+
-						"collects path and body secrets — teach apiSecretsForRequest to read %s "+
-						"position before shipping this declaration", info.ID, p.In, p.Name, p.In)
+						"collects path and body secrets and cannot safely recover a %s value",
+						info.ID, p.In, p.Name, p.In)
 				}
 				if p.Type != "" && p.Type != "string" {
 					t.Errorf("%s declares x-octo-secret on a %s-typed parameter %q; the masker's "+

cmd/auth.go

@@ -31,12 +31,74 @@ func newAuthCmd(f *cmdutil.Factory) *cobra.Command {
 	cmd.AddCommand(
 		newAuthLoginCmd(f),
 		newAuthStatusCmd(f),
+		newAuthUpdateCmd(f),
 		newAuthLogoutCmd(f),
 		newAuthListCmd(f),
 	)
 	return cmd
 }
 
+func newAuthUpdateCmd(f *cmdutil.Factory) *cobra.Command {
+	var apiBaseURL string
+
+	cmd := &cobra.Command{
+		Use:   "update",
+		Short: "Update non-secret settings for a stored bot profile",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if strings.TrimSpace(apiBaseURL) == "" {
+				return failErr(f, output.ErrValidation(
+					"--api-base-url is required",
+					"pass the public OCTO API origin for this Bot profile",
+				))
+			}
+			normalized, err := config.NormalizeAPIBaseURL(apiBaseURL)
+			if err != nil {
+				return failErr(f, output.ErrValidation(
+					err.Error(),
+					"pass only the Octo gateway base URL, without a service path",
+				))
+			}
+			apiBaseURL = normalized
+
+			store, err := f.AuthStore()
+			if err != nil {
+				return failErr(f, err)
+			}
+			name, meta, status, err := store.ActiveProfile(f.Globals.Profile, selectorBotID(f))
+			if err != nil {
+				return failErr(f, err)
+			}
+			switch status {
+			case authstore.StatusFound:
+				if err := store.UpdateProfileAPIBaseURL(name, apiBaseURL); err != nil {
+					return failErr(f, err)
+				}
+				result := map[string]any{
+					"profile": name, "api_base_url": apiBaseURL,
+				}
+				putIfSet(result, "robot_id", meta.RobotID)
+				return emitJSON(f, result)
+			case authstore.StatusAmbiguous:
+				return failErr(f, output.ErrValidation(
+					"multiple profiles configured; specify which Bot to update",
+					"pass --bot-id <robot_id> or --profile <name>",
+				))
+			case authstore.StatusMissing:
+				return failErr(f, output.ErrAuth(
+					"no matching profile", "check `octo-cli auth list`",
+				))
+			default:
+				return failErr(f, output.ErrValidation(
+					"no stored profiles", "run `octo-cli auth login` first",
+				))
+			}
+		},
+	}
+	cmd.Flags().StringVar(&apiBaseURL, "api-base-url", "", "set OCTO API base URL for this profile")
+	return cmd
+}
+
 func newAuthLoginCmd(f *cmdutil.Factory) *cobra.Command {
 	var withToken bool
 	var tokenFile string

cmd/auth_test.go

@@ -89,6 +89,97 @@ func TestAuth_LoginListStatusLogout(t *testing.T) {
 	}
 }
 
+func TestAuth_UpdateAPIBaseURLPreservesCredentials(t *testing.T) {
+	t.Setenv(authstore.EnvConfigDir, t.TempDir())
+	loginToken(t, "cli_demo", "app_demo_token")
+
+	store, err := authstore.New()
+	if err != nil {
+		t.Fatalf("authstore.New: %v", err)
+	}
+	if err := store.SaveMailCredential("cli_demo", "omb_mail_secret"); err != nil {
+		t.Fatalf("SaveMailCredential: %v", err)
+	}
+
+	f := newTestFactoryWithReg()
+	out, _, err := execRoot(t, f,
+		"auth", "update", "--bot-id", "cli_demo",
+		"--api-base-url", "http://127.0.0.1:28080/")
+	if err != nil {
+		t.Fatalf("auth update: %v", err)
+	}
+	data := dataOf(t, out)
+	if data["api_base_url"] != "http://127.0.0.1:28080" {
+		t.Fatalf("api_base_url = %v", data["api_base_url"])
+	}
+
+	botToken, err := store.GetToken("cli_demo")
+	if err != nil || botToken != "app_demo_token" {
+		t.Fatalf("Bot token changed: %q, %v", botToken, err)
+	}
+	mailToken, err := store.GetMailCredential("cli_demo")
+	if err != nil || mailToken != "omb_mail_secret" {
+		t.Fatalf("mail token changed: %q, %v", mailToken, err)
+	}
+
+	f = newTestFactoryWithReg()
+	out, _, err = execRoot(t, f, "auth", "status", "--bot-id", "cli_demo")
+	if err != nil {
+		t.Fatalf("auth status: %v", err)
+	}
+	if activeOf(t, out)["api_base_url"] != "http://127.0.0.1:28080" {
+		t.Fatalf("active profile = %#v", activeOf(t, out))
+	}
+}
+
+func TestAuth_UpdateAPIBaseURLRejectsInvalidOriginWithoutChangingProfile(t *testing.T) {
+	t.Setenv(authstore.EnvConfigDir, t.TempDir())
+	loginToken(t, "cli_demo", "app_demo_token")
+
+	store, err := authstore.New()
+	if err != nil {
+		t.Fatalf("authstore.New: %v", err)
+	}
+	if err := store.UpdateProfileAPIBaseURL("cli_demo", "https://octo.example"); err != nil {
+		t.Fatalf("seed API base URL: %v", err)
+	}
+
+	for _, invalid := range []string{
+		"not a url at all",
+		"https://evil.example/fleet/api?x=1",
+	} {
+		t.Run(invalid, func(t *testing.T) {
+			f := newTestFactoryWithReg()
+			_, _, err := execRoot(t, f,
+				"auth", "update", "--bot-id", "cli_demo",
+				"--api-base-url", invalid)
+			ee := output.AsExitError(err)
+			if ee == nil || ee.Type != "validation" {
+				t.Fatalf("auth update error = %v, want validation", err)
+			}
+
+			profiles, err := store.LoadProfiles()
+			if err != nil {
+				t.Fatalf("LoadProfiles: %v", err)
+			}
+			if got := profiles["cli_demo"].APIBaseURL; got != "https://octo.example" {
+				t.Fatalf("invalid update changed API base URL to %q", got)
+			}
+		})
+	}
+}
+
+func TestAuth_UpdateAPIBaseURLRequiresStoredProfile(t *testing.T) {
+	t.Setenv(authstore.EnvConfigDir, t.TempDir())
+	f := newTestFactoryWithReg()
+	_, _, err := execRoot(t, f,
+		"auth", "update", "--api-base-url", "https://octo.example")
+	ee := output.AsExitError(err)
+	if ee == nil || ee.Type != "validation" || !strings.Contains(ee.Message, "no stored profiles") {
+		t.Fatalf("auth update error = %v", err)
+	}
+}
+
 func TestAuth_DuplicateRobotIDRejected(t *testing.T) {
 	t.Setenv(authstore.EnvConfigDir, t.TempDir())
 	loginToken(t, "cli_x", "app_a") // profile name defaults to "cli_x", robot_id cli_x

cmd/cmd_test.go

@@ -474,6 +474,12 @@ func TestSkipValidation(t *testing.T) {
 	if !skipValidation(findCmd("config", "show")) {
 		t.Error("config show should skip via parent")
 	}
+	if !skipValidation(findCmd("auth")) {
+		t.Error("top-level auth should skip validation")
+	}
+	if skipValidation(findCmd("mail", "auth", "login")) {
+		t.Error("nested mail auth login should NOT skip validation")
+	}
 
 	// Pick any real service leaf — should NOT skip.
 	svcLeaf := findCmd("event", "list")