ente-cli 0.4.102 → 0.4.104

package/README.md

@@ -39,6 +39,11 @@ ente auth pair --url https://your-deployment.convex.site --email you@example.com
   --profile mail-operator --agent <agent-id> --access write
 ```
 
+All keys of an agent share the agent's one permission set. `--access` only
+seeds an agent that has no keys yet; otherwise the new key shares the agent's
+existing permissions, which the approval page shows. Change them for all keys in
+the agent's Settings tab.
+
 For up to ten operators, put the exact agent IDs and local profile names in a
 JSON file outside a repository:
 
@@ -442,6 +447,9 @@ schedule templates. Schedules support `intervalHours: 1 | 24` and
 ```sh
 ente agent user-mailbox --request '{"operation":"list","purpose":"classification","limit":20}'
 ente agent user-mailbox --request-file ./mail-operation.json
+ente agent mail --schema createDraft
+ente agent mail --request '{"operation":"search","mailboxId":"<mailbox>","query":"from:sender@example.com before:2026/07/01"}'
+ente agent mail --request '{"operation":"createDraft","mailboxId":"<mailbox>","messageId":"<provider-message-id>","body":"Reply text","requestId":"unique-request-1"}'
 ```
 
 Use the returned `threadId` to `read` or `claim`. External claims require the
@@ -624,3 +632,14 @@ unavailability. Ask exits nonzero unless `synthesisStatus` is `answered`.
 Default/lexical `ente query` remains deterministic and available without AI.
 Hybrid/semantic query requires private beta enrollment and separate passage
 consent; unavailable responses point to ordinary commands and lexical query.
+
+
+Canonical mailbox calls name `mailboxId`; `listMailboxes` discovers permitted own,
+user and shared inboxes. `createDraft` resolves provider reply headers without a
+synced Ente thread or agent chat. Draft fields are top-level `to/subject/body`;
+`patch.draft.body` belongs to visible-editor editing only. `--dry-run` validates
+without provider state or receipts. Optional `executionId` groups writes under
+the run budget, with a credential/mailbox 60-minute window floor across fresh IDs.
+Every result names `from` and the exact `permissionUsed` level. Old command names,
+connection IDs and workflow payloads remain supported. Run `--schema <operation>`
+or `--help` for per-operation JSON schemas.

package/dist/SKILL.md

@@ -48,9 +48,12 @@ For an agent operator, pair a named profile with the exact agent ID and scope.
 For several operators, pass a JSON manifest with up to ten `{ profile, agentId,
 access }` entries. The Ente page shows the complete set for one approval:
 
-Every external credential is bound to an Ente agent. `read` permits reading
-allowed space content and the bound agent. `write` additionally permits changes
-within the agent’s current space policy. A mailbox is optional; mailbox
+Every external credential is bound to an Ente agent, and all keys of an agent
+share that agent's one permission set (changed in the agent's Settings tab).
+`read` permits reading allowed space content and the bound agent. `write`
+additionally permits changes within the agent’s current space policy. `--access`
+only seeds an agent that has no keys yet; otherwise a new key shares the
+agent's existing permissions, and the approval page shows them. A mailbox is optional; mailbox
 capabilities require an active mailbox and the relevant scopes. Read keys may
 mark inbox threads read/unread, and change their workflow state. A CLI pairing
 without `--agent` creates a named connection agent rather than a user API key.
@@ -850,3 +853,42 @@ with your agent. Default/lexical `ente query` remains available without AI.
 a Bedrock key, provider access or model change to repair beta unavailability.
 
 Agent platform inspection uses `ente admin tables|get|page --profile <profile>`. The agent owner must have platform admin rights and explicitly enable Platform access → Read in the agent panel. It is off by default and optional expiry is enforced on every request. Revocation applies to cached CLI sessions. Reads record agent/key, table/record or page size/order and timestamp, never row contents. Other admin commands still require standalone platform keys. `auth whoami` and `agent permissions` show the platform level and expiry. Space rights never imply platform rights.
+
+### Unified mailbox operations
+
+Use `ente agent user-mailbox --profile ente-operator --request '<JSON>'`.
+Existing `agent mail` commands and old `user-mailbox` requests remain supported.
+New requests name `mailboxId` explicitly; obtain it with `listMailboxes`.
+The same operations apply to own, connected and shared inboxes. Inspect
+`permissionUsed` (`read`, `draft`, `send`, `allowlist-send`) and `from` in results.
+User and shared inbox sends require an explicit send grant; own mail retains its
+exact correspondent allowlist. No draft operation sends mail.
+
+- `{"operation":"listMailboxes"}` lists addresses and grants.
+- `{"operation":"search","mailboxId":"...","query":"from:sender@example.com before:2026/07/01"}` searches the provider for connected mail, including unsynced history. Inspect coverage and continue cursors. Gmail uses native q; IMAP supports from/to/subject/after/before and plain text, with server-specific TEXT semantics and bounded UID windows.
+- `{"operation":"readThread","mailboxId":"...","threadId":"provider-thread-id"}` reads bounded content. A provider `messageId` is also accepted. Continue text cursors. IMAP reads the selected message first and discovers its RFC reference conversation; it states bounds and coverage explicitly.
+- `{"operation":"createDraft","mailboxId":"...","messageId":"provider-message-id","body":"Reply text","requestId":"unique-request-1"}` resolves reply recipients, subject and threading headers itself. Search→createDraft takes two calls; search→readThread→createDraft takes three. `to`, `cc`, `bcc`, `subject`, `body` and `html` are top-level fields. `patch.draft.body` belongs only to `editVisible`.
+- `{"operation":"loadDraft","mailboxId":"...","draftId":"..."}` returns its reviewed `draftVersion`.
+- `{"operation":"sendDraft","mailboxId":"...","draftId":"...","draftVersion":"...","requestId":"unique-send-1"}` sends the exact reviewed draft only with the appropriate permission.
+- `{"operation":"discardDraft","mailboxId":"...","draftId":"...","requestId":"unique-discard-1"}` discards it. Loading it afterward returns not-found.
+- `{"operation":"modifyLabels","mailboxId":"...","threadId":"...","labels":["handled"],"requestId":"unique-label-1"}` sets workflow labels; `needs-reply` and an empty list are supported. Shared/own inbox changes also require the reviewed `stateVersion`. IMAP keyword support depends on the server.
+
+Set `dryRun:true` on a write to validate without creating provider state or
+receipts. Reply-target validation may make read-only provider calls.
+Chat-free writes need no `agentThreadId`. Optional `executionId` groups a run;
+the verified credential/mailbox 60-minute window remains a budget floor across
+fresh IDs, and the daily limit also applies. Reuse `requestId` on transport retries.
+Never automatically retry an uncertain send. Revocation is checked live.
+
+Per-operation JSON schemas are included in `ente agent user-mailbox --help`,
+MCP/OpenAPI descriptions and the shared `mailboxOperationSchemas` declaration.
+
+<!-- mailbox-operation-schemas:start -->
+
+Canonical request JSON schemas (generated from `mailboxOperationSchemas`):
+
+```json
+{"listMailboxes":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operation":{"const":"listMailboxes"}},"additionalProperties":false,"required":["operation"]},"search":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operation":{"const":"search"},"mailboxId":{"type":"string","minLength":1,"maxLength":4000},"query":{"type":"string","minLength":1,"maxLength":300},"cursor":{"type":"string","minLength":1,"maxLength":4000},"limit":{"type":"integer","minimum":1,"maximum":50}},"required":["operation","mailboxId","query"],"additionalProperties":false},"readThread":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operation":{"const":"readThread"},"mailboxId":{"type":"string","minLength":1,"maxLength":4000},"messageId":{"type":"string","minLength":1,"maxLength":4000},"threadId":{"type":"string","minLength":1,"maxLength":4000},"providerThreadId":{"type":"string","minLength":1,"maxLength":4000},"cursor":{"type":"string","minLength":1,"maxLength":4000}},"required":["operation","mailboxId"],"additionalProperties":false,"anyOf":[{"required":["messageId"]},{"required":["threadId"]},{"required":["providerThreadId"]}]},"createDraft":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operation":{"const":"createDraft"},"mailboxId":{"type":"string","minLength":1,"maxLength":4000},"requestId":{"type":"string","pattern":"^[a-zA-Z0-9-]{8,100}$"},"executionId":{"type":"string","minLength":1,"maxLength":100},"dryRun":{"type":"boolean"},"messageId":{"type":"string","minLength":1,"maxLength":4000},"threadId":{"type":"string","minLength":1,"maxLength":4000},"providerThreadId":{"type":"string","minLength":1,"maxLength":4000},"from":{"type":"string"},"to":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":320}},"cc":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":320}},"bcc":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":320}},"subject":{"type":"string","maxLength":2000},"body":{"type":"string","maxLength":32000},"html":{"type":"string","maxLength":64000},"draftId":{"type":"string","minLength":1,"maxLength":4000},"replyAll":{"type":"boolean"}},"required":["operation","mailboxId","requestId"],"additionalProperties":false},"loadDraft":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operation":{"const":"loadDraft"},"mailboxId":{"type":"string","minLength":1,"maxLength":4000},"draftId":{"type":"string","minLength":1,"maxLength":4000}},"required":["operation","mailboxId","draftId"],"additionalProperties":false},"discardDraft":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operation":{"const":"discardDraft"},"mailboxId":{"type":"string","minLength":1,"maxLength":4000},"requestId":{"type":"string","pattern":"^[a-zA-Z0-9-]{8,100}$"},"executionId":{"type":"string","minLength":1,"maxLength":100},"dryRun":{"type":"boolean"},"draftId":{"type":"string","minLength":1,"maxLength":4000}},"required":["operation","mailboxId","requestId","draftId"],"additionalProperties":false},"sendDraft":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operation":{"const":"sendDraft"},"mailboxId":{"type":"string","minLength":1,"maxLength":4000},"requestId":{"type":"string","pattern":"^[a-zA-Z0-9-]{8,100}$"},"executionId":{"type":"string","minLength":1,"maxLength":100},"dryRun":{"type":"boolean"},"draftId":{"type":"string","minLength":1,"maxLength":4000},"draftVersion":{"type":"string","minLength":1,"maxLength":4000}},"required":["operation","mailboxId","requestId","draftId","draftVersion"],"additionalProperties":false},"modifyLabels":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operation":{"const":"modifyLabels"},"mailboxId":{"type":"string","minLength":1,"maxLength":4000},"requestId":{"type":"string","pattern":"^[a-zA-Z0-9-]{8,100}$"},"executionId":{"type":"string","minLength":1,"maxLength":100},"dryRun":{"type":"boolean"},"messageId":{"type":"string","minLength":1,"maxLength":4000},"threadId":{"type":"string","minLength":1,"maxLength":4000},"providerThreadId":{"type":"string","minLength":1,"maxLength":4000},"labels":{"maxItems":1,"type":"array","items":{"type":"string","enum":["handled","needs-reply"]}},"stateVersion":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["operation","mailboxId","requestId","labels"],"additionalProperties":false,"anyOf":[{"required":["messageId"]},{"required":["threadId"]},{"required":["providerThreadId"]}]}}
+```
+
+<!-- mailbox-operation-schemas:end -->