ente-cli 0.4.60 → 0.4.62

package/README.md

@@ -1,7 +1,7 @@
 # ente CLI
 
 Command-line interface for [ente](https://github.com/valentindoering/ente) — a
-relationship manager and knowledge graph (people, orgs, projects, topics and the
+relationship manager and knowledge graph (people, orgs, projects, topics, places, objects and the
 notes/calls/tasks/conversations logged against them).
 
 TypeScript, built on [clipanion](https://clipanion.dev/), bundled with esbuild
@@ -57,14 +57,16 @@ ente auth pair --url https://your-deployment.convex.site --email you@example.com
 One Ente approval page lists all profiles and scopes. Existing local profiles
 are never overwritten unless `--replace` is supplied. A stopped or expired CLI
 run must be started again. Pending requests expire after ten minutes.
-Both agent access modes can read and change Ente data and manage spaces.
-With `read`, the key can inspect the bound agent and inbox, mark inbox threads
-read/unread, and change their workflow state. `write` also permits agent
-changes and sending email. The CLI saves approved profiles before
+Every external credential is bound to an Ente agent. With `read`, it can read
+allowed space content and inspect the bound agent. It can also mark inbox threads
+read/unread, and change their workflow state when an inbox is enabled. `write`
+additionally permits changes within the agent’s current space policy, agent
+configuration changes, and sending email from its active permitted inbox. The CLI saves approved profiles before
 activating their keys, so a failed local save cannot leave active keys behind.
 
-For headless integrations or a legacy key, generate an API key in the web app
-and enter it directly in the terminal:
+For headless integrations, create or select an agent in `/agents`, issue a
+credential from its Connections settings, and enter it directly in the terminal.
+Several credentials may belong to one agent. Existing migrated keys remain valid:
 
 ```bash
 ente auth login --url https://your-deployment.convex.site --key-stdin
@@ -82,10 +84,12 @@ ENTE_PROFILE=mail-operator ente agent config show
 ENTE_PROFILE=mail-operator ente agent mail threads --unread
 ```
 
-Operator keys use the CLI's scoped REST commands. They cannot be exchanged for
-the legacy full-account CLI session token, so the bound-agent restriction
-cannot be bypassed through direct Convex commands. Use a normal account key for
-legacy administrative CLI commands that require that session token.
+Agent keys use scoped REST calls and signed CLI JWTs carrying the agent and
+credential IDs. Content calls recheck the live key and agent policy, including
+cached JWT calls. Human-only settings and administration stay in the web app;
+there is no unrestricted account-key fallback. CLI pairing without `--agent`
+creates a named connection agent. MCP authorization creates a connection agent
+named for the client.
 
 Named profiles are optional. Use one only when a person or process deliberately
 switches between several credentials. `--profile` overrides `ENTE_PROFILE`.
@@ -151,6 +155,11 @@ lets the bound external agent start, claim, and reply to external threads withou
 calling an Ente-hosted model. Ente prompt and scheduled runs configure the Ente agent
 counterpart; they are not instructions or schedules for the external operator.
 The caller cannot select another agent, mailbox, or sender.
+`ente agent list` shows the agent bound to this credential, including migrated
+connection keys. Migrated keys keep their original scopes: listing that identity
+does not grant prompt or conversation access. History needs `agent:read`;
+`agent new` and `agent send` need `agent:communicate` and post messages as the
+agent. They do not invoke a hosted model or impersonate a human user.
 The corresponding scopes are `agent:read`, `agent:write`, `mail:read`, and
 `mail:send`, and `agent:communicate`.
 
@@ -287,6 +296,14 @@ Never put secrets in chat, repositories, project `.env` files, or logs.
 
 ### Process a permitted user mailbox
 
+Existing provider drafts retain their attachments when edited or sent through
+`user-mailbox`, including the web composer's 25 MB combined raw-file budget
+(25,000,000 bytes, at most 24 files). The complete MIME message must fit 35 MiB;
+providers can allow less. `loadDraft` returns file metadata and a reviewed draft
+version, without file bytes or private storage references. Attach new files in
+the web composer. The agent's own inbox keeps its separate attachment limits.
+
+
 A user's Gmail/IMAP inbox is separate from the agent's own email address. In
 Ente `/agents`, the owner selects the mailboxes this personal agent can read,
 classification/reply permissions, destination spaces, and full conversation
@@ -318,3 +335,37 @@ and 100 per UTC day. A successful operation acknowledges only its own purpose.
 Published conversations remain durable after provider cache expiry/disconnect.
 Their individual messages appear in entity activity feeds; activity content reads
 return bounded, read-only email blocks with continuation cursors.
+
+### Guardian health (global admin)
+
+`ente health page --profile default --source toolMessages --since <epoch-ms> --until <epoch-ms> --json`
+reads one content-free aggregate page. Use `--source threads --status idle|running|error`
+or `--source recordings --status pending|transcribing|structuring|reflecting|done|error`
+for current job counts. Use `--since 0` for active jobs; terminal recording statuses require a positive
+`--since` and a window of at most seven days. Legacy terminal rows without update
+timestamps are outside that coverage.
+`--stale-after-ms` defaults to 1800000; `--limit` accepts 1–100. Follow
+`data.continueCursor` with `--cursor` and unchanged arguments until `data.isDone`.
+Counts are page-local. Tool windows are at most seven days. This is a human-only
+global administration endpoint. Agent-bound CLI credentials cannot call it,
+including credentials sponsored by an administrator. Use the web administration
+interface for these operations; creating a broader agent key does not grant access.
+No customer content or record IDs are returned. Unknown tool names become `other`.
+See `docs/admin-health-monitoring.md` for collector continuity and limits.
+
+### Assigned tasks and replies
+
+Assigned agent work is available through `ente agent tasks <operation>`. Start
+with `ente agent tasks list --view attention --json`, inspect each assignment,
+read its discussion, optionally reply with a stable idempotency key, and
+acknowledge only the returned version you processed. Newer replies remain
+pending. The shipped skill documents pagination, long-message chunks and
+optional five-minute claims. Your prompt and schedule control the workflow.
+
+Task assignment accepts multiple agents alongside humans. Use repeatable
+`ente activity create --type task --agent-assignee <agentId>` with the usual entity,
+space and title arguments, or `ente activity update <activityId> --agent-assignee <agentId>`.
+Updating replaces agent assignees and preserves human assignees. Use
+`--clear-agent-assignees` to remove them. Only active agents with write access qualify.
+
+Scheduled runs also accept `runCondition: "new_chats"`: skip model execution unless this agent has new manual or recording chats since its previous scheduled check. Scheduled/reflection chats do not trigger it; explicit Run now bypasses the condition.

package/dist/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: m:ente-cli
-description: "Cli: drives the ente CRM and knowledge graph over its Convex API as the signed-in user — entities (people, organisations, projects, topics), activities (notes, calls, meetings, tasks), relationships, spaces, full-text and AI-backed search, agent threads and mail, plus Excalidraw canvas prototypes. Use when context about a person, an organisation or a meeting has to be stored, looked up or updated from the shell. Not for splitting shared costs, which is schnorrer-cli."
+description: "Cli: drives the ente CRM and knowledge graph over its Convex API as the signed-in user — entities (people, organisations, projects, topics, places, objects), activities (notes, calls, meetings, tasks), relationships, spaces, full-text and AI-backed search, agent threads and mail, plus Excalidraw canvas prototypes. Use when context about a person, an organisation or a meeting has to be stored, looked up or updated from the shell. Not for splitting shared costs, which is schnorrer-cli."
 when_to_use: "Remembering what was said in a call or meeting; looking up open tasks, deadlines or follow-ups for a person or project; creating or renaming an entity and pinning it to a parent; linking an activity to several entities or moving it between spaces; asking a question over the whole graph and getting citations; reviewing the voice-recording prompt or debugging a failed recording; sending a notification mail or an agent-inbox reply; posting to the in-app feedback board; managing Excalidraw canvas HTML prototypes on an entity board."
 metadata:
   short-description: Relationship memory through ente
@@ -8,7 +8,7 @@ metadata:
 
 # ente-cli - CRM & Relationship Manager CLI Skill
 
-ente is a CRM / relationship manager that tracks people, organisations, projects, and topics (entities), and logs notes, calls, tasks, and conversations (activities) against them. This skill wraps the `ente` CLI so an agent can manage entities, activities, tasks, pins, and search end-to-end.
+ente is a CRM / relationship manager that tracks people, organisations, projects, topics, places, and objects (entities), and logs notes, calls, tasks, and conversations (activities) against them. This skill wraps the `ente` CLI so an agent can manage entities, activities, tasks, pins, and search end-to-end.
 
 ---
 
@@ -48,10 +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:
 
-Both agent access modes can read and change Ente data and manage spaces. With
-`read`, the key can inspect the bound agent and inbox, mark inbox threads
-read/unread, and change their workflow state. `write` also permits agent
-changes and email sending.
+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
+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.
 
 ```bash
 ente auth pair --url <convex-site-url> --email <account-email> --profile operator-name --agent <agent-id> --access write
@@ -60,10 +62,11 @@ ENTE_PROFILE=operator-name ente agent config show --json
 ENTE_PROFILE=operator-name ente agent mail threads --unread --json
 ```
 
-Operator keys use scoped REST commands and cannot mint the legacy full-account
-CLI session token. This preserves the one-agent boundary. A normal account key
-is still required for legacy administrative commands that call Convex
-functions directly.
+Agent keys use a signed agent binding and credential reference for CLI
+authentication. Current permissions and revocation are checked on each call,
+including cached JWT calls. There is no unrestricted user-key fallback. Create
+and manage keys from the agent’s Connections settings in `/agents`; several
+credentials can belong to the same agent.
 
 Named profiles are optional and only needed to switch deliberately between
 credentials. `--profile` overrides `ENTE_PROFILE`. Profiles do not activate
@@ -89,7 +92,8 @@ npm i -g ente-cli --registry https://registry.npmjs.org
 - **Space resolution**: Space names work the same way — exact match first, then substring. Use `--space` to target a workspace.
 - **--json flag**: Every command supports `--json`. Always use `--json` when parsing output programmatically.
 - **Deadlines**: stored as millisecond epochs; displayed as `DD.MM.YYYY` / `DD.MM.YYYY, HH:MM` in Europe/Berlin.
-- **Entity types**: `person`, `org`, `project`, `topic`
+- **Entity types**: `person`, `org`, `project`, `topic`, `place`, `object`
+- **Place vs Object**: use `place` for a specific location (city, apartment, room), `object` for a specific physical thing (device, furniture), and `topic` for a general subject. Create entities only when their identity or relationships will be useful later.
 - **Activity types**: `note`, `conversation`, `meeting`, `call`, `message`, `task`
 
 ---
@@ -110,7 +114,7 @@ ente ask "What's open with Erik?" [--space <name>] [--entity <name>] [--evidence
 ente query "QM system export" [--space <name>] [--entity <name>] [--verbose] [--json]         # evidence only, no AI
 
 # Entities
-ente entity list [--query <text>] [--type person|org|project|topic] [--space <name>] [--limit 50] [--archived] [--json]
+ente entity list [--query <text>] [--type person|org|project|topic|place|object] [--space <name>] [--limit 50] [--archived] [--json]
 ente entity create "Jane Doe" --type person [--pin "Acme Corp"] [--share-parents --parent-space-grant-fingerprint <token>] [--alias "JD"] [--attr email=jane@acme.com] [--tag vip] [--description "CTO at Acme"] [--json]
 ente entity get "Jane Doe" [--json]
 ente entity update "Jane Doe" [--name "Jane A. Doe"] [--alias-add "Jane"] [--alias-remove "JD"] [--attr role=CEO] [--tag vip] [--description "…"] [--json]
@@ -128,7 +132,7 @@ ente activity list [--entity "Jane"] [--type note|conversation|meeting|call|mess
 ente activity create --type meeting --title "Call with Jane" --entity "Jane Doe" --entity "Acme Corp" --space "Work" [--content "…"] [--content-file ./notes.md] [--auto-link --entity-space-grant-fingerprint <token>] [--json]
 ente activity search "quarterly review" [--entity "Acme"] [--type meeting] [--limit 10] [--json]
 ente activity get <activityId> [--json]                # complete detail: body, full nested agenda, messages/replies, entities, attachments
-ente activity update <activityId> [--title "…"] [--content "…"] [--entity-add "Bob"] [--entity-remove "Carol"] [--json]
+ente activity update <activityId> [--title "…"] [--content "…"] [--entity-add "Bob"] [--entity-remove "Carol"] [--agent-assignee <agentId> ... | --clear-agent-assignees] [--json]
 ente activity content read <activityId> [--cursor <cursor> --expected-version <version>] [--max-blocks 20] [--max-characters 12000] [--json]
 ente activity content edit <activityId> --expected-version <version> --operations-file ./operations.json [--json]
 ente activity message add <activityId> (--content "…" | --content-file ./update.md) [--json]
@@ -189,11 +193,24 @@ ente agent mail reply <thread-id> --message <message-id> --reply-all (--text "Re
 ente agent mail mark <thread-id> --state-version <version> (--handled | --open | --needs-reply | --read | --unread) [--json]
 ```
 
-Agent operator credentials are bound server-side to one exact agent. Agent read
+Agent operator credentials are bound server-side to one exact agent.
+`agent list` shows only that bound identity, including for migrated connection
+keys. Migrated keys retain their original scopes. History requires `agent:read`;
+`agent new` and `agent send` require `agent:communicate`, author messages as the
+agent, and never invoke a hosted model or fall back to a human identity.
+Agent read
 adds `agent:read` and, while the inbox is active, `mail:read`. Agent write adds
 `agent:write`, `agent:communicate`, and, while the inbox is active, `mail:send`.
 Use `agent threads --attention agent`, then `agent send`; the CLI claims the current
 attention version before replying so concurrent cron workers cannot duplicate work.
+For a user-authorized Dream/maintenance run, use `agent config show`,
+`agent threads --include-archived --limit 20`, and `agent show <thread-id>`.
+Choose messages by their timestamps, including recent messages in older threads.
+Skip scheduled-run and reflection summaries as sources for new durable lessons.
+Compare the existing prompt before writing; `agent config set-prompt` replaces
+the entire prompt, so preserve all unrelated instructions and context. Leave
+the prompt unchanged when there is nothing useful to retain. The user's own
+scheduler and prompt determine whether to perform this maintenance.
 The prompt and
 scheduled runs are Ente configuration for the Ente agent counterpart. They are
 not work instructions or scheduler settings for the external operator. The key
@@ -248,6 +265,11 @@ ambiguous timeout, retry the exact operation with the same
 
 For a focused update to an existing long body, use `activity content read`, select the returned
 version-scoped block targets, then call `activity content edit` with the exact `contentVersion`.
+Activity mentions use `[activity](ente://activity/<activityId>?display=card)` or
+`display=inline`. Copy the exact activity ID returned by Ente without changing
+any characters. Newly introduced malformed or wrong-table mention IDs are
+rejected with `INVALID_INPUT` by activity, agenda, and message writes. Existing
+broken references remain editable and render as unavailable.
 The operations file is either a JSON array or `{ "operations": [...] }`; supported operation types
 are `replaceBlock`, `insertBefore`, `insertAfter`, `deleteBlock`, `replaceText`, and `append`.
 Use `replaceText` with a unique exact Markdown substring for file-patch-like changes inside a large
@@ -295,11 +317,14 @@ ente recording list [--user <email|id>] [--status error] [--limit 20] [--json]
 ente recording show <recordingId> [--json]        # status, error, transcript size, activity count
 ente recording inspect <recordingId> [--json]     # audio container: brands, fragmented?, box counts
 ente recording rerun <recordingId> [--wait] [--timeout 900] [--json]
+ente recording backups [--state failed|joining|capturing] [--user <email|id>] [--json]   # server backups of browser recordings
+ente recording backups join <backupId> [--now]     # retry a failed join; --now joins one still waiting for its device
 ```
 
 - Admin-only (`api.admin.recordings.*`); the ordinary `recordings.*` API is creator-scoped.
 - `rerun` never modifies or deletes the stored audio; `--wait` polls to `done`/`error` and exits non-zero on failure.
 - `--status` scans newest-first and says so when the sweep is capped.
+- A backup in `failed` holds the only server copy of audio whose device never came back; read `error`, fix the cause, then `backups join`.
 
 ### Feedback board
 
@@ -361,6 +386,14 @@ Parent relationships are spaceless. Both entities must be accessible. Every acti
 
 ## User mailbox processing
 
+Existing provider drafts retain their attachments when edited or sent through
+`user-mailbox`, including the web composer's 25 MB combined raw-file budget
+(25,000,000 bytes, at most 24 files). The complete MIME message must fit 35 MiB;
+providers can allow less. `loadDraft` returns file metadata and a reviewed draft
+version, without file bytes or private storage references. Attach new files in
+the web composer. The agent's own inbox keeps its separate attachment limits.
+
+
 `ente agent user-mailbox --request JSON` or `--request-file PATH` uses the mailbox
 permission granted to the agent bound to this operator credential. This is
 separate from `ente agent mail`, which manages the agent's own inbox. The owner
@@ -382,7 +415,7 @@ through old backlog. Read starts with the newest message and returns
 minutes and fail after new arrivals or manual corrections. Re-read and claim
 again rather than forcing a stale write. Default change limits are 20 per agent
 execution and 100 per UTC day. Classification and replies are acknowledged
-independently. Mailbox permission levels are read/draft, read/draft/assign, and full access including sending and inbox changes. `accounts` lists allowed connections; `search` returns bounded cursor pages; `context` reads a captured mail scope; `editVisible` queues a revision-bound editor patch; the browser must receive it before insertion. Interactive IMAP reply reads cover the retained mailbox conversation and report `historyScope`; `purpose: classification` always reads complete provider history. `draft`, `loadDraft`, and `discardDraft` use provider drafts. `send` requires full permission, an exact draftVersion returned by loadDraft, and a unique requestId. Writes also require the active agentThreadId. Reuse requestId for the same operation; uncertain provider outcomes block automatic retries.
+independently. Mailbox permission levels are read/draft, read/draft/assign, and full access including sending and inbox changes. `accounts` lists allowed connections; `search` returns bounded cursor pages; `context` reads a captured mail scope; `editVisible` queues a revision-bound editor patch; the browser must receive it before insertion. Its canonical patch is `{revision,operation:"draft",draft:{body:"text"}}`. The exact shorthand `{draft:{body:"text"}}` binds to the active agent thread’s captured revision. Omitted draft fields are preserved; an explicit connectionId must match the captured scope. Unknown fields, partial bindings, stale revisions and edits without draft permission are rejected. Interactive IMAP reply reads cover the retained mailbox conversation and report `historyScope`; `purpose: classification` always reads complete provider history. `draft`, `loadDraft`, and `discardDraft` use provider drafts. `send` requires full permission, an exact draftVersion returned by loadDraft, and a unique requestId. Writes also require the active agentThreadId. Reuse requestId for the same operation; uncertain provider outcomes block automatic retries.
 
 Optional schedules accept `intervalHours: 1 | 24` and
 `mailPurpose: classification | replies`; empty queues skip model execution.
@@ -410,3 +443,42 @@ are ready immediately and confirmation completes the move atomically. Bulk jobs
 continue server-side; track with status. A stale plan fails closed; completed batches remain applied.
 Prepare a new review for remaining contents. Cancel only before execution.
 `restore --source SPACE_ID` restores an archived space for an owner/admin.
+
+### Guardian health (global admin)
+
+`ente health page --profile default --source toolMessages --since <epoch-ms> --until <epoch-ms> --json`
+reads one content-free aggregate page. Use `--source threads --status idle|running|error`
+or `--source recordings --status pending|transcribing|structuring|reflecting|done|error`
+for current job counts. Use `--since 0` for active jobs; terminal recording statuses require a positive
+`--since` and a window of at most seven days. Legacy terminal rows without update
+timestamps are outside that coverage.
+`--stale-after-ms` defaults to 1800000; `--limit` accepts 1–100. Follow
+`data.continueCursor` with `--cursor` and unchanged arguments until `data.isDone`.
+Counts are page-local. Tool windows are at most seven days. This is a human-only
+global administration endpoint. Agent-bound CLI credentials cannot call it,
+including credentials sponsored by an administrator. Use the web administration
+interface for these operations; creating a broader agent key does not grant access.
+No customer content or record IDs are returned. Unknown tool names become `other`.
+See `docs/admin-health-monitoring.md` for collector continuity and limits.
+
+## Assigned tasks and replies
+
+Use your bound agent's task queue independently of its mailbox:
+
+- `ente agent tasks list --json` lists open assignments, including undated tasks.
+- `ente agent tasks list --view attention --json` lists unseen changes, including closed or deleted tasks.
+- `ente agent tasks inspect --assignment <id> --json` returns durable events, `observationId`, `observedVersion`, `snapshotVersion` and `hasMore`. Continue with `--observation <id>` while `hasMore` is true. Reading does not acknowledge anything.
+- `ente agent tasks get --assignment <id> --json` reads task metadata and a body excerpt. Use the ordinary activity content read tool with its stable activity ID for the full body.
+- `ente agent tasks discussion --assignment <id> --json` pages through comments using `--cursor`. Long messages are marked `truncated`; finish them with `ente agent tasks message --assignment <id> --message <message-id> --offset <next-offset> --expected-updated-at <timestamp> --json`. Restart if the message changes.
+- `ente agent tasks comment --assignment <id> --content "..." --idempotency-key <stable-run-operation-id> --json` posts as your agent. Reuse a key only for the identical payload. A conflicting retry fails.
+- `ente agent tasks acknowledge --assignment <id> --observation <id> --version <observed-version> --json` acknowledges only processed input. Observations expire after 15 minutes. A later reply stays pending.
+- `claim`, `renew` and `release` accept `--assignment`; renew/release require `--claim-token`. Claims expire after five minutes and are optional. They do not grant write access or hide work permanently.
+
+Each assignment ID identifies one enrollment. After unassignment/reassignment, use the new ID. Assignment never grants space access. Completion uses the ordinary task operations; the user-provided prompt decides when to close a task. These tools neither start a worker nor impose a response policy.
+
+Assign agents to tasks with repeatable `activity create --agent-assignee <agentId>` or
+`activity update <activityId> --agent-assignee <agentId>`. Updating replaces only agent
+assignees and preserves humans. `--clear-agent-assignees` removes the agent assignments.
+Assignment requires the agent to have write access in the task space; it grants no access.
+
+Scheduled runs also accept `runCondition: "new_chats"`: skip model execution unless this agent has new manual or recording chats since its previous scheduled check. Scheduled/reflection chats do not trigger it; explicit Run now bypasses the condition.