cinna-cli 0.4.2__tar.gz → 0.4.3__tar.gz

{cinna_cli-0.4.2 → cinna_cli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cinna-cli
-Version: 0.4.2
+Version: 0.4.3
 Summary: Local development CLI for Cinna Core agents
 Project-URL: Homepage, https://github.com/opencinna/cinna-cli
 Project-URL: Repository, https://github.com/opencinna/cinna-cli
@@ -549,6 +549,27 @@ cinna chat --show 3fa85f64-5717-4562-b3fc-2c963f66afa6     # read a transcript
 
 The session id is printed in the first `session` event — capture it to drive a multi-turn conversation with `--resume`, or to re-attach with `--attach`.
 
+### `cinna delegation create | status | report | reply`
+
+Hand work to a remote agent as a **durable delegation** — a platform task with a stable identity that survives retries and carries structured results. Run from the account workspace. Every command first checks the server's delegation capability and refuses with "This server does not support durable delegations." when it is missing or not version 1.
+
+- `create --id KEY --target AGENT_UUID --title T --brief B [--execute]` — the identity is `--target` + `--id`: a retry with the same pair returns the original task (changed title/brief are ignored) and never launches execution twice (the backend deduplicates). Prints the backend **task id** the other commands take, and whether it executes. `--depth 2 --root ROOT` makes a sub-delegation (`--root` is required at depth 2, not allowed at depth 1); `--group` tags related work.
+- `status TASK_ID` — one read: state, latest result, and any open question with its result id. A requester agent should end its turn and let Cinna Desktop deliver the result rather than poll.
+- `report [TASK_ID] --status in_progress|blocked|done|failed --summary S` — `blocked` needs `--question`; `--audience user` when a human must decide (default `requester`). `--artifact` (repeatable) is a JSON object with non-empty `kind` (backend accepts `file` or `link`), `name` and an `http(s)` `ref` — upload local files separately. `--body` adds detail.
+- **Inside a cloud task**, omit `TASK_ID`: the report goes to the current task using `AGENT_AUTH_TOKEN`, `BACKEND_URL`, `ENV_ID` and the session in `CINNA_SESSION_CONTEXT_PATH` (default `./session_context.json`); the backend checks the session belongs to this environment's agent and owner.
+- `reply TASK_ID --result-id ID --message M` — answer a blocked question.
+- `--json` (after the subcommand) prints `{"result": "ok", "delegation": {…}}`.
+
+```bash
+cinna delegation create --id research-1 --target AGENT_UUID --title Research --brief 'Find the facts' --execute
+cinna delegation status TASK_ID
+cinna delegation report TASK_ID --status blocked --summary 'Choose a source' --question 'Which source?' --audience user
+cinna delegation reply TASK_ID --result-id RESULT_ID --message 'Use the primary source'
+cinna delegation report --status done --summary 'Finished'     # inside the cloud task
+```
+
+Inside cloud tasks, cinna-core's MCP task server also offers a `handover_report` tool for the same report.
+
 ### `cinna dev`
 
 Start a foreground dev session — creates / resumes the Mutagen sync session for this workspace and attaches the terminal to a two-tab TUI (status + raw Mutagen details). Ctrl-C terminates the session; sync does not outlive the TUI. To observe sync from another terminal without affecting it, use `cinna sync status`.

{cinna_cli-0.4.2 → cinna_cli-0.4.3}/README.md

@@ -512,6 +512,27 @@ cinna chat --show 3fa85f64-5717-4562-b3fc-2c963f66afa6     # read a transcript
 
 The session id is printed in the first `session` event — capture it to drive a multi-turn conversation with `--resume`, or to re-attach with `--attach`.
 
+### `cinna delegation create | status | report | reply`
+
+Hand work to a remote agent as a **durable delegation** — a platform task with a stable identity that survives retries and carries structured results. Run from the account workspace. Every command first checks the server's delegation capability and refuses with "This server does not support durable delegations." when it is missing or not version 1.
+
+- `create --id KEY --target AGENT_UUID --title T --brief B [--execute]` — the identity is `--target` + `--id`: a retry with the same pair returns the original task (changed title/brief are ignored) and never launches execution twice (the backend deduplicates). Prints the backend **task id** the other commands take, and whether it executes. `--depth 2 --root ROOT` makes a sub-delegation (`--root` is required at depth 2, not allowed at depth 1); `--group` tags related work.
+- `status TASK_ID` — one read: state, latest result, and any open question with its result id. A requester agent should end its turn and let Cinna Desktop deliver the result rather than poll.
+- `report [TASK_ID] --status in_progress|blocked|done|failed --summary S` — `blocked` needs `--question`; `--audience user` when a human must decide (default `requester`). `--artifact` (repeatable) is a JSON object with non-empty `kind` (backend accepts `file` or `link`), `name` and an `http(s)` `ref` — upload local files separately. `--body` adds detail.
+- **Inside a cloud task**, omit `TASK_ID`: the report goes to the current task using `AGENT_AUTH_TOKEN`, `BACKEND_URL`, `ENV_ID` and the session in `CINNA_SESSION_CONTEXT_PATH` (default `./session_context.json`); the backend checks the session belongs to this environment's agent and owner.
+- `reply TASK_ID --result-id ID --message M` — answer a blocked question.
+- `--json` (after the subcommand) prints `{"result": "ok", "delegation": {…}}`.
+
+```bash
+cinna delegation create --id research-1 --target AGENT_UUID --title Research --brief 'Find the facts' --execute
+cinna delegation status TASK_ID
+cinna delegation report TASK_ID --status blocked --summary 'Choose a source' --question 'Which source?' --audience user
+cinna delegation reply TASK_ID --result-id RESULT_ID --message 'Use the primary source'
+cinna delegation report --status done --summary 'Finished'     # inside the cloud task
+```
+
+Inside cloud tasks, cinna-core's MCP task server also offers a `handover_report` tool for the same report.
+
 ### `cinna dev`
 
 Start a foreground dev session — creates / resumes the Mutagen sync session for this workspace and attaches the terminal to a two-tab TUI (status + raw Mutagen details). Ctrl-C terminates the session; sync does not outlive the TUI. To observe sync from another terminal without affecting it, use `cinna sync status`.

{cinna_cli-0.4.2 → cinna_cli-0.4.3}/docs/README.md

@@ -296,6 +296,7 @@ authoring convention.
 | **Agent addons** | `cinna skills` (list — with each declared credential slot's readiness, publish, install, uninstall, update, toggle, refresh, catalog, show, revisions, files, grants, grant, revoke, visibility, delist, relist) — the whole skills lifecycle: what an agent carries, publishing one of its `skills/<name>/` folders to the catalog, installing a package on another agent and keeping it current, and sharing after the fact | [business](features/agent_addons/agent_addons.md) · [tech](features/agent_addons/agent_addons_tech.md) · [acceptance](features/agent_addons/agent_addons_acceptance.md) |
 | **MCP integration** | `cinna connect mcp` · `cinna mcp-proxy` (knowledge stdio server) | [business](features/mcp_integration/mcp_integration.md) · [tech](features/mcp_integration/mcp_integration_tech.md) · [acceptance](features/mcp_integration/mcp_integration_acceptance.md) |
 | **Git versioning** | `cinna git` (link, status, commit, push, pull, log, checkout, unlink) | [business](features/git_versioning/git_versioning.md) · [tech](features/git_versioning/git_versioning_tech.md) · [acceptance](features/git_versioning/git_versioning_acceptance.md) |
+| **Durable delegation** | `cinna delegation` (create — idempotent per target + `--id`, status, report — owner side with a task id or from inside a cloud task, reply), gated on the backend capability version | [business](features/delegation/delegation.md) · [tech](features/delegation/delegation_tech.md) · [acceptance](features/delegation/delegation_acceptance.md) |
 | **Improvement requests** | `cinna improve` (list, show, download, status) | [business](features/improvement_requests/improvement_requests.md) · [tech](features/improvement_requests/improvement_requests_tech.md) · [acceptance](features/improvement_requests/improvement_requests_acceptance.md) |
 | **Local agent import** | `cinna agent import` (Local Agent Kit → cloud agent), incl. the versioned folder contract (`.cinna-kit/layout.json`), `publications.json` and `content_hash` | [business](features/local_agent_import/local_agent_import.md) · [tech](features/local_agent_import/local_agent_import_tech.md) · [acceptance](features/local_agent_import/local_agent_import_acceptance.md) |
 

cinna_cli-0.4.3/docs/features/delegation/delegation.md

@@ -0,0 +1,160 @@
+# Durable Delegation (`cinna delegation`)
+
+## Purpose
+
+Let a requester (a developer, a local coding agent, or a script) hand a piece of
+work to a remote platform agent as a **durable delegation**: a platform task
+with a stable identity that survives retries, reports structured results back,
+and can ask the requester (or a human) a question and wait for the answer.
+The same command group lets the cloud agent doing the work report its own
+progress from inside its task session.
+
+## Mental model / core concepts
+
+A delegation is **not** local state. It is a platform task (the same task
+record the platform UI shows) carrying extra delegation metadata. The CLI is a
+remote control over it; nothing is written to the workspace.
+
+- **Requester key (`--id`)** — a name the requester picks for one piece of work
+  (`research-1`). Together with the target agent it forms the delegation's
+  identity. Reusing the same key against the same target means "the same work",
+  never "new work".
+- **Target** — the UUID of the remote agent that will do the work.
+- **Task id** — the backend id of the created task. `create` prints it; every
+  other command (`status`, `report`, `reply`) takes it.
+- **Result** — a structured report on the task: a status (`in_progress`,
+  `blocked`, `done`, `failed`), a summary, an optional body, optional
+  artifacts, and — when blocked — a question with an audience.
+- **Question / reply** — a `blocked` result carries a question. Its result id
+  is the handle the answer is sent against (`reply --result-id`).
+- **Audience** — who must answer a question: `requester` (the agent/tool that
+  created the delegation) or `user` (a human decision).
+- **Depth and root** — a delegation may itself delegate once more. Depth 1 is a
+  top-level delegation whose root is itself; depth 2 is a sub-delegation that
+  names its depth-1 root. Deeper chains are not allowed.
+- **Owner side vs executor side** —
+  - *Owner side*: run from an **account workspace**, authenticated by the
+    account token, reaching the platform through the account API proxy
+    (`create`, `status`, `reply`, and `report` with a task id).
+  - *Executor side*: run **inside a cloud task session** in the agent's
+    environment, authenticated by the environment's own agent token
+    (`report` without a task id). It reports on "the task I am currently
+    running" — it never needs to know the task id.
+- **Capability negotiation** — durable delegations are a versioned backend
+  extension. Every owner-side command first asks the server whether it supports
+  version 1; if not, the command refuses instead of calling routes that may not
+  exist.
+
+## User flows
+
+### Hand work to a remote agent
+1. From the account workspace run
+   `cinna delegation create --id research-1 --target <agent uuid> --title … --brief …`,
+   adding `--execute` to start the work immediately.
+2. The CLI prints the backend task id and whether the task will execute.
+3. On a network error or timeout, run the **same command again**: the platform
+   returns the original task. Any changed `--title` / `--brief` on the retry is
+   ignored, and execution is never launched a second time.
+
+### Follow up without polling
+4. `cinna delegation status <task id>` reads the task once: its state, the
+   latest result, and any open question together with that question's result id.
+5. A requester agent should **end its turn** after delegating and let Cinna
+   Desktop deliver the result, rather than polling `status` in a loop.
+
+### Report progress (owner side)
+6. `cinna delegation report <task id> --status in_progress --summary …` records a
+   result on the task through the account workspace.
+
+### Report progress (inside the cloud task)
+7. The agent executing the task runs
+   `cinna delegation report --status done --summary … [--artifact …]` with no task
+   id. The CLI uses the environment's agent credentials and the current session
+   context; the backend attaches the result to the task that session belongs to.
+
+### Ask and answer a question
+8. The executor reports `--status blocked --question "Which source?"`, with
+   `--audience user` when a human must decide.
+9. The requester reads the question and its result id with `status`, then
+   answers with `cinna delegation reply <task id> --result-id <id> --message …`.
+
+### Machine-readable use
+10. Every command accepts `--json` after the subcommand; the output is a single
+    `{"result": "ok", "delegation": …}` line carrying the backend's answer, or
+    the standard `{"result": "error", …}` line on failure.
+
+## Business rules
+
+- **Account workspace required** for every owner-side command; outside one they
+  fail loud.
+- **Capability gate** — if the server lacks the capability route, or reports a
+  version other than 1, the command stops with "This server does not support
+  durable delegations." and sends nothing else.
+- **Retry identity** — the delegation identity is derived only from
+  target + requester key. The same pair always yields the same identity, so a
+  retry is idempotent. Idempotency **depends on the backend** deduplicating on
+  that identity; the CLI keeps no local record of what it created.
+- **First write wins** — on a retry the original task is returned unchanged;
+  new title/brief text does not update it.
+- **Execute at most once** — `--execute` only takes effect when the task is
+  newly created. A retry with `--execute` never launches a second run.
+- **Depth and root** — depth is 1 or 2. At depth 1 `--root` is forbidden (the
+  delegation is its own root). At depth 2 `--root` is required.
+- **Origin** — CLI-created delegations are marked as originating externally
+  (not from a platform agent, chat, or task).
+- **Blocked needs a question** — `--status blocked` without `--question` is
+  refused before any request.
+- **Audience** — defaults to `requester`; use `user` when a human must decide.
+- **Artifacts are references, not uploads** — each `--artifact` is a JSON object
+  with a non-empty `kind`, a non-empty `name`, and an `http(s)` `ref`. The CLI
+  checks only that shape; the backend further restricts `kind` (currently
+  `file` or `link`). Local files must be uploaded separately first; the CLI
+  never uploads them.
+- **Executor report is session-bound** — without a task id, `report` needs the
+  environment's agent token, backend URL and environment id, plus the current
+  session context. Missing any of them is a hard failure. The backend verifies
+  that the session belongs to this environment's agent and owner, so an agent
+  cannot report on someone else's task.
+- **Status is a single read** — no watching, no waiting.
+- **Fail loud** — any backend refusal surfaces as a platform error with the
+  backend's own detail; nothing is retried silently.
+
+## Architecture overview
+
+```
+Owner side (account workspace)
+cinna delegation create|status|reply|report TASK_ID
+      │
+      ▼
+delegation.py ──► AccountClient ──► POST /api/v1/cli/account/api-proxy
+                                        │  1. GET tasks/delegation-capabilities (version 1?)
+                                        │  2. the delegation route
+                                        ▼
+                                  cinna-core tasks API (dedup, execution, results)
+
+Executor side (inside a cloud task session)
+cinna delegation report  (no TASK_ID)
+      │  env: AGENT_AUTH_TOKEN, BACKEND_URL, ENV_ID + session_context.json
+      ▼
+POST {BACKEND_URL}/api/v1/agent/tasks/current/delegation-result
+      │  backend checks session ↔ environment agent ↔ owner
+      ▼
+result attached to the current task ──► delivered to the requester (Desktop)
+```
+
+## Integration points
+
+- **Account workspace** — owner-side commands use the account token and the api
+  proxy. See [Account Workspace](../account_workspace/account_workspace.md).
+- **Agent API / `cinna api`** — the same api-proxy escape hatch `cinna api`
+  exposes; delegation wraps the task routes with identity, validation and a
+  capability gate. See [Agent API](../agent_api/agent_api.md).
+- **Remote chat** — a delegated task runs as a platform session like the ones
+  `cinna chat` drives. See [Remote Chat](../remote_chat/remote_chat.md).
+- **cinna-core task MCP server (not in this repo)** — inside cloud tasks the
+  backend's MCP task server exposes a `handover_report` tool that records the
+  same kind of result. It is implemented and documented in cinna-core; this CLI
+  only offers the equivalent command-line path.
+
+Implementation: see [delegation_tech.md](delegation_tech.md).
+Real-usage e2e scenarios: see [delegation_acceptance.md](delegation_acceptance.md).

cinna_cli-0.4.3/docs/features/delegation/delegation_acceptance.md

@@ -0,0 +1,250 @@
+# Durable Delegation — Acceptance Scenarios (live e2e)
+
+The catalog of **real-usage scenarios** for an agent integration-testing
+`cinna delegation` against a **live** platform: a real cinna-core backend with
+the durable-delegation extension, a real account workspace, and at least one
+real target agent. These exercise backend dedup, task execution, the result /
+question / reply cycle, and the executor-side report from inside a cloud task —
+the parts unit tests only mock.
+
+How to use: run the **Steps** from inside the account workspace (except where a
+scenario says "inside the cloud task"), assert the **Expected**, and check the
+**Watch for** items. Scenarios 2–3 (retry identity) and 9–11 (executor report)
+are the highest-value ones for any change to `src/cinna/delegation.py`.
+
+## Preconditions
+
+- A reachable cinna-core backend whose `tasks/delegation-capabilities` returns
+  `version: 1`; ideally also an older backend without it (scenario 13).
+- An **account workspace** (`.cinna/account.json` reachable from the cwd;
+  `cinna login` if the token expired).
+- **Editable install**: `which cinna` resolves, and
+  `python3 -c "import cinna,os;print(os.path.dirname(cinna.__file__))"` points at
+  this repo's `src/cinna`. `cinna delegation --help` lists create, status,
+  report, reply.
+- At least one **target agent** UUID (`cinna account agents`), with a running
+  or startable environment.
+- `jq` for asserting JSON output.
+- Use a fresh key per run, e.g. `KEY=acc-$(date +%s)`, so earlier runs do not
+  dedup into this one.
+
+## Scenario catalog
+
+### 1. Create without executing
+
+- **Goal:** register work without starting it.
+- **Steps:**
+  ```
+  cinna delegation create --id "$KEY" --target "$AGENT" --title Research --brief 'Find the facts'
+  ```
+- **Expected:** exit 0; output shows the backend task id and that it will
+  **not** execute. The task appears in the platform UI for the target agent,
+  not started. Record the id as `TASK`.
+- **Watch for:** the delegation id / requester key printed instead of the
+  backend task id; the task auto-starting.
+
+### 2. Retry reuses the original task (idempotent create)
+
+- **Goal:** a retry after a timeout never duplicates work.
+- **Steps:**
+  ```
+  cinna delegation create --id "$KEY" --target "$AGENT" --title Research --brief 'Find the facts' --json | jq -r .delegation.id
+  cinna delegation create --id "$KEY" --target "$AGENT" --title 'Changed title' --brief 'Changed brief' --json | jq -r .delegation.id
+  ```
+- **Expected:** both ids equal `TASK`. The platform shows one task, still titled
+  `Research` with the original brief.
+- **Watch for:** a second task; the title/brief being overwritten; a non-`ok`
+  result on the retry.
+
+### 3. `--execute` runs at most once
+
+- **Goal:** execution is never launched twice for the same key.
+- **Steps:**
+  ```
+  KEY2=$KEY-exec
+  cinna delegation create --id "$KEY2" --target "$AGENT" --title Run --brief 'Say hello' --execute
+  cinna delegation create --id "$KEY2" --target "$AGENT" --title Run --brief 'Say hello' --execute
+  ```
+- **Expected:** the first reports the task executes; the second returns the same
+  task id. The platform shows exactly one execution/session for that task.
+- **Watch for:** two sessions on the target agent; the retry reporting a new
+  execution.
+
+### 4. Same key, different target is different work
+
+- **Goal:** identity is target + key.
+- **Steps:** repeat scenario 1's command with `--target "$AGENT_B"` (a second
+  agent) and the same `$KEY`.
+- **Expected:** a new, different task id.
+- **Watch for:** dedup across targets (identity must include the target).
+
+### 5. Depth and root rules
+
+- **Goal:** sub-delegation shape is enforced client-side.
+- **Steps:**
+  ```
+  cinna delegation create --id "$KEY-d2" --target "$AGENT" --title T --brief B --depth 2
+  cinna delegation create --id "$KEY-d1" --target "$AGENT" --title T --brief B --root "$ROOT_ID"
+  cinna delegation create --id "$KEY-d3" --target "$AGENT" --title T --brief B --depth 3
+  cinna delegation create --id "$KEY-d2" --target "$AGENT" --title T --brief B --depth 2 --root "$ROOT_ID" --json
+  ```
+  (`$ROOT_ID` is the `delegation_metadata.id` of the task from scenario 1.)
+- **Expected:** the first three fail with a usage error (exit 2) and create
+  nothing; the last succeeds and its `delegation_metadata` has `depth: 2`,
+  `root: $ROOT_ID`. A depth-1 task's metadata has `root` equal to its own id.
+- **Watch for:** a task created by an invalid invocation; `root` null at depth 1.
+
+### 6. Status is a single read
+
+- **Goal:** read state, latest result and open question once.
+- **Steps:**
+  ```
+  cinna delegation status "$TASK"
+  cinna delegation status "$TASK" --json | jq .result
+  ```
+- **Expected:** human output shows state, latest result (or none), and any open
+  question with its result id; returns immediately. JSON prints `"ok"` with the
+  task detail under `.delegation`.
+- **Watch for:** the command waiting or polling; missing result id next to an
+  open question.
+
+### 7. Owner-side report and blocked question
+
+- **Goal:** record results and ask a question through the account workspace.
+- **Steps:**
+  ```
+  cinna delegation report "$TASK" --status in_progress --summary 'Started'
+  cinna delegation report "$TASK" --status blocked --summary 'Need input'
+  cinna delegation report "$TASK" --status blocked --summary 'Need input' --question 'Which source?' --audience user
+  cinna delegation status "$TASK"
+  ```
+- **Expected:** the first succeeds; the second fails client-side (blocked
+  without a question) and sends nothing; the third succeeds. `status` shows the
+  open question `Which source?`, audience `user`, and its result id (`RESULT`).
+- **Watch for:** a blocked result accepted without a question; audience
+  defaulting wrongly (default is `requester`).
+
+### 8. Reply answers the question
+
+- **Goal:** close the question loop.
+- **Steps:**
+  ```
+  cinna delegation reply "$TASK" --result-id "$RESULT" --message 'Use the primary source'
+  cinna delegation status "$TASK"
+  ```
+- **Expected:** exit 0; the question is no longer open and the reply is visible
+  on the task. A wrong `--result-id` yields a platform error with the backend
+  detail (exit 1).
+- **Watch for:** reply accepted against a non-question result id.
+
+### 9. Artifacts are validated
+
+- **Goal:** only well-formed, portable artifact references are sent.
+- **Steps:**
+  ```
+  cinna delegation report "$TASK" --status done --summary Done --artifact '{"kind":"link","name":"r","ref":"https://example.com/r.pdf"}'
+  cinna delegation report "$TASK" --status done --summary Done --artifact 'not json'
+  cinna delegation report "$TASK" --status done --summary Done --artifact '{"kind":"link","name":"r","ref":"file:///tmp/r.pdf"}'
+  cinna delegation report "$TASK" --status done --summary Done --artifact '{"kind":"","name":"r","ref":"https://x"}'
+  cinna delegation report "$TASK" --status done --summary Done --artifact '["a"]'
+  ```
+- **Expected:** only the first succeeds and the artifact appears on the latest
+  result. The others fail client-side (exit 2) with no request sent.
+- **Watch for:** local paths or non-http refs accepted; empty `kind`/`name`
+  accepted; a JSON array accepted as an artifact.
+
+### 10. Executor report from inside the cloud task
+
+- **Goal:** the working agent reports on its own current task without a task id.
+- **Setup:** a task created with `--execute` (scenario 3), running in the target
+  environment where `AGENT_AUTH_TOKEN`, `BACKEND_URL`, `ENV_ID` are set and
+  `session_context.json` holds `backend_session_id`.
+- **Steps (inside the cloud task, e.g. as an instruction in the brief):**
+  ```
+  cinna delegation report --status done --summary 'Finished' --json
+  ```
+  Then, from the account workspace: `cinna delegation status "$TASK3"`.
+- **Expected:** `{"result": "ok", "delegation": {…}}`; `status` shows the `done`
+  result on that task. The request went to
+  `$BACKEND_URL/api/v1/agent/tasks/current/delegation-result` with the bearer
+  token and `X-Agent-Env-Id`.
+- **Watch for:** the result landing on a different task; the command trying to
+  load an account workspace.
+
+### 11. Executor report fails loud without its context
+
+- **Goal:** no silent fallback when not in a cloud task.
+- **Steps (from a plain shell, then with a partial env):**
+  ```
+  env -u AGENT_AUTH_TOKEN -u BACKEND_URL -u ENV_ID cinna delegation report --status done --summary x
+  AGENT_AUTH_TOKEN=t BACKEND_URL=https://backend.example ENV_ID=e CINNA_SESSION_CONTEXT_PATH=/nonexistent.json cinna delegation report --status done --summary x
+  ```
+- **Expected:** both fail before any network call with a clear message (missing
+  environment / no current session). Nothing is recorded on any task.
+- **Watch for:** falling back to the account workspace; a request sent with an
+  empty `X-Agent-Env-Id` or no `source_session_id`.
+
+### 12. Executor report rejected by the backend
+
+- **Goal:** backend verification and error surfacing.
+- **Steps (inside a cloud environment):** point `CINNA_SESSION_CONTEXT_PATH` at
+  a file whose `backend_session_id` belongs to another agent's session, then run
+  `cinna delegation report --status done --summary x --json`.
+- **Expected:** the backend refuses; the CLI prints
+  `{"result": "error", "code": "platform_error", "http_status": 4xx, …}` and
+  exits 1 (5xx → `platform_unavailable`, exit 12). A 3xx is not followed and is
+  also an error.
+- **Watch for:** the report accepted for a foreign session; a redirect followed
+  with the bearer token.
+
+### 13. Unsupported server
+
+- **Goal:** capability gate on every owner-side verb.
+- **Steps (against a backend without the extension, or one reporting another
+  version):**
+  ```
+  cinna delegation create --id "$KEY" --target "$AGENT" --title T --brief B
+  cinna delegation status "$TASK"
+  cinna delegation report "$TASK" --status done --summary x
+  cinna delegation reply "$TASK" --result-id r --message m
+  ```
+- **Expected:** each fails with "This server does not support durable
+  delegations." and no task is created or changed.
+- **Watch for:** a create going through on an old backend (which would ignore
+  `external_ref` and break retry safety).
+
+### 14. `--json` is per-command
+
+- **Goal:** machine output works after the subcommand.
+- **Steps:**
+  ```
+  cinna delegation status "$TASK" --json
+  cinna delegation create --id "$KEY" --target "$AGENT" --title T --brief B --json
+  ```
+- **Expected:** each prints exactly one JSON line with `result: "ok"` and the
+  backend body under `delegation`; no Rich output on stdout.
+- **Watch for:** extra human lines mixed into stdout; the body at top level
+  instead of under `delegation`.
+
+### 15. Outside an account workspace
+
+- **Steps:** `cd /tmp && cinna delegation status "$TASK"`
+- **Expected:** fails loud pointing at the missing account workspace; no request.
+
+## Cross-cutting invariants
+
+- One target + key ⇒ one task and at most one execution, across any number of
+  retries and any changed title/brief.
+- Every owner-side verb calls the capability route first; an unsupported server
+  receives no task-route writes.
+- Client-side validation failures (depth/root, blocked without question,
+  artifacts, missing executor env) send **no** request.
+- The executor bearer token is only ever sent to `BACKEND_URL` (no redirects).
+- Nothing is written to the workspace, `.cinna/`, or `~/.cinna/agents.json`. <!-- nocheck -->
+- Every `--json` invocation ends with exactly one `{"result": …}` line.
+
+## Cleanup
+
+- Delete or archive the test tasks (keys prefixed `acc-`) in the platform UI, or
+  via `cinna api DELETE tasks/<id>` where the backend allows it.
+- Stop any sessions left running on the target agent by `--execute` scenarios.

cinna_cli-0.4.3/docs/features/delegation/delegation_tech.md

@@ -0,0 +1,149 @@
+# Durable Delegation — Technical Reference
+
+Implementation of [delegation.md](delegation.md). cinna-cli is a Python CLI; all
+logic lives in `src/cinna/`, tests in `tests/`. The `cinna delegation` group is a
+thin validation + transport layer over cinna-core task routes. It keeps no local
+state.
+
+## File locations
+
+- `src/cinna/delegation.py` — the whole feature: the Click group, the four verb
+  commands, the owner-side request helper (capability gate + proxy call), the
+  executor-side report path, and output rendering.
+- `src/cinna/main.py` — attaches `json_option()` to every delegation
+  subcommand and registers the group on the root CLI
+  (`cli.add_command(delegation)`).
+- `src/cinna/account.py` — `find_account_root()` / `load_account_config()`:
+  locate the account workspace and its token.
+- `src/cinna/client.py` — public wrappers `get_delegation_capabilities()`,
+  `create_delegated_task()`, `get_task_detail()`, `put_delegation_result()`,
+  `post_delegation_reply()` over `_proxy_json()` / `api_proxy()` (the api-proxy
+  transport and error mapping), plus `AccountClient.error_detail()` used by the
+  executor path.
+- `src/cinna/console.py` — `emit_result()` (the `--json` success line) and
+  `json_mode`.
+- `src/cinna/errors.py` — `PlatformError`, `CinnaExit` (exit codes and the
+  `--json` error line).
+- Tests: `tests/test_delegation.py` — retry identity and payload, depth/root
+  rules, owner-side routes, capability gate, report validation (blocked
+  question, artifacts), executor report (env, session context, headers,
+  redirects, non-2xx), and the `--json` envelope.
+
+## Command surface
+
+- `cinna delegation` → `src/cinna/delegation.py:delegation()` (Click group).
+- `cinna delegation create` → `src/cinna/delegation.py:create()`.
+- `cinna delegation status` → `src/cinna/delegation.py:status()`.
+- `cinna delegation report` → `src/cinna/delegation.py:report()`.
+- `cinna delegation reply` → `src/cinna/delegation.py:reply()`.
+
+Each verb carries its own `--json` option (the shared per-command
+`src/cinna/main.py:json_option()`, applied in `main.py` at registration because
+`delegation.py` cannot import `main.py` without a cycle); `--json` is not taken
+from the root group.
+
+## Key functions & flow
+
+- **Owner-side request helper** (`src/cinna/delegation.py`) — every owner-side
+  call: `find_account_root()` + `load_account_config()`, open an
+  `AccountClient`, `get_delegation_capabilities()`. A 404/405 or a body that is
+  not a dict with `version` `1` raises "This server does not support durable
+  delegations."; other platform errors propagate. Only then is the actual route
+  called through the matching public client method.
+- `src/cinna/delegation.py:create()` — builds the identity string as the JSON
+  array `[target, key]`; `external_ref` is its sha256 hex digest; the delegation
+  id is `uuid5(NAMESPACE_URL, identity)`. Validates depth/root before any call.
+  POSTs `tasks/` with `title`, `original_message` (= `--brief`),
+  `selected_agent_id` (= `--target`), `external_ref`, `delegation_metadata`, and
+  `auto_execute` (= `--execute`). Human output: the backend task id and whether
+  it executes.
+- `src/cinna/delegation.py:status()` — one `GET tasks/{id}/detail`; human output
+  shows state, the latest result, and any open question with its result id.
+- `src/cinna/delegation.py:report()` — validates (`blocked` ⇒ `--question`;
+  each `--artifact` parses to a JSON object with non-empty `kind`, `name` and an
+  `http`/`https` `ref`), builds the payload (`status`, `summary`, `question`,
+  `audience`, `artifacts`, `body`), then:
+  - with `TASK_ID`: owner-side `PUT tasks/{id}/delegation-result`;
+  - without: the executor path (below).
+- **Executor path** (`report()` without `TASK_ID`) — reads `AGENT_AUTH_TOKEN`,
+  `BACKEND_URL`, `ENV_ID` (all required); reads `backend_session_id` from the
+  file at `CINNA_SESSION_CONTEXT_PATH` (default `session_context.json` in the
+  cwd) and adds it as `source_session_id`; POSTs directly (not via the account
+  proxy) with `Authorization: Bearer <token>` and `X-Agent-Env-Id: <ENV_ID>`,
+  redirects disabled, 30 s timeout. No capability gate on this path. Any 2xx is
+  accepted (an empty or non-JSON success body is treated as `{}` so callers do
+  not retry an accepted report); non-2xx raises `PlatformError` with the detail
+  from `AccountClient.error_detail()`.
+- `src/cinna/delegation.py:reply()` — `POST tasks/{id}/delegation-reply` with
+  `result_id` and `message`. Exits 0 but warns when the backend answers
+  `delivered: false` (result is not an open question) or `uncertain` (check
+  `status` before resending).
+- **Output** — in `--json` mode `console.emit_result(delegation=<backend body>)`,
+  i.e. one line `{"result": "ok", "delegation": {…}}`; otherwise a short
+  human summary.
+
+## Payload shape
+
+`delegation_metadata` on create:
+
+- `id` — `uuid5(NAMESPACE_URL, json [target, key])`, stable per target+key.
+- `requester_key` — the `--id` value.
+- `origin_kind` — always `external`; `origin_agent_id`, `origin_chat_id`,
+  `origin_task_id` — always null (a CLI requester is not a platform agent,
+  chat or task).
+- `depth` — 1 or 2.
+- `root` — own `id` at depth 1; the `--root` value at depth 2.
+- `group` — `--group` or null.
+
+There is no config or registry footprint: nothing is written to
+`.cinna/account.json`, `.cinna/config.json` or `~/.cinna/agents.json`. <!-- nocheck -->
+
+## External contracts (cinna-core backend dependencies)
+
+Owner side — all through `POST /api/v1/cli/account/api-proxy` with the account
+CLI token (`token_type="cli-account"`); the proxy mirrors the inner status and
+body:
+
+- `GET tasks/delegation-capabilities` — returns `{version: 1, …}`; 404/405 means
+  unsupported.
+- `POST tasks/` — creates the task. **Must deduplicate on `external_ref`**:
+  a second create with the same `external_ref` returns the existing task,
+  ignores new title/brief, and does not start execution again. The CLI's retry
+  safety relies entirely on this.
+- `GET tasks/{id}/detail` — task state, results, open question + result id.
+- `PUT tasks/{id}/delegation-result` — record a result on a task.
+- `POST tasks/{id}/delegation-reply` — answer a question by `result_id`.
+
+Executor side — direct call, agent-token auth:
+
+- `POST /api/v1/agent/tasks/current/delegation-result` — headers
+  `Authorization: Bearer <AGENT_AUTH_TOKEN>`, `X-Agent-Env-Id: <ENV_ID>`; body is
+  the report payload plus `source_session_id`. The backend verifies the session
+  belongs to this environment's agent and owner, and resolves the task from the
+  session. Any 2xx is success.
+
+Related, not in this repo: cinna-core's cloud MCP task server exposes a
+`handover_report` tool for the same executor-side report.
+
+## Edge cases & guardrails (preserve these)
+
+- **Identity is target+key only** — title, brief, group, depth and `--execute`
+  must not enter `external_ref` or the delegation id, or retries would create
+  duplicates (`src/cinna/delegation.py:create()`).
+- **No local dedup** — do not add a local "already created" cache; the backend
+  dedup is the single source of truth.
+- **Depth/root validated client-side** — depth outside 1–2, `--root` at depth
+  1, or missing `--root` at depth 2 are usage errors before any request.
+- **Capability gate first** — every owner-side verb gates before its real call;
+  an unsupported server gets no task-route traffic.
+- **Blocked requires a question; artifacts validated** — rejected client-side
+  (`report()`), never sent half-valid to the backend.
+- **Executor env is mandatory** — missing `AGENT_AUTH_TOKEN`, `BACKEND_URL` or
+  `ENV_ID`, or an unreadable context / missing `backend_session_id`, fails
+  before any network call.
+- **No redirects on the executor POST** — a redirect would forward the bearer
+  token to another origin; `follow_redirects=False` keeps it on `BACKEND_URL`.
+- **Any 2xx accepted** — non-2xx becomes a `PlatformError` (exit 1 for 4xx,
+  12 for 5xx) carrying the backend detail.
+- **`--json` envelope** — always `{"result": "ok", "delegation": …}` via
+  `console.emit_result()`; errors use the standard `CinnaExit` JSON line.

{cinna_cli-0.4.2 → cinna_cli-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cinna-cli"
-version = "0.4.2"
+version = "0.4.3"
 description = "Local development CLI for Cinna Core agents"
 readme = "README.md"
 requires-python = ">=3.10"