cinna-cli 0.5.0__tar.gz → 0.5.2__tar.gz

{cinna_cli-0.5.0 → cinna_cli-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cinna-cli
-Version: 0.5.0
+Version: 0.5.2
 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
@@ -486,6 +486,24 @@ Take a package out of the catalog. Agents that already installed it keep what th
 
 Put a delisted package back. `delist` has no inverse route of its own — without this verb the only way back would be `cinna api`, which would make delisting the one door in this group that opens only outwards.
 
+### `cinna agent-api access list | issue | revoke | scopes`
+
+Give people (or your own local agent) API access to a producer, from the account workspace. A key is issued to a **person** and lands in their credentials; **its value never appears in the CLI** — not on self-issue, not in `--json`. Reveal and rotate live on the web credential page, and so does the external-access switch (when it is off, `issue` is refused with the producer's Integrations URL). Writes need the `agent-developer` role.
+
+- `list <producer> [--all] [--json]` — people, their scopes and keys (prefix, status, expiry, last used, linked agents, id). Ended keys (revoked, expired, removed) are hidden unless `--all`; `--json` is always the full listing.
+- `issue <producer> --to <email|me> [--scopes a,b] [--expires-in-days N] [--service-uri SLOT] [--label TEXT] [--read-only] [--json]` — `--to` is required. `me` puts the key in your own credentials and prints the web URL where you reveal it; a local agent in Cinna Desktop calls it with `cinna_credentials.agent_api_session("<slot>")`, a cloud agent is wired with `cinna connect agent-api` instead.
+- `revoke <producer> <key> [--yes] [--json]` — `<key>` is the key id or the exact token prefix (an elided one is refused). Asks first; `--json` needs `--yes`; an already revoked key is reported, exit 0. The person's scopes stay.
+- `scopes <producer> --to <email|me> (--set a,b | --clear) [--json]` — change a grant without touching keys.
+
+```bash
+cinna agent-api access issue orders-agent --to me --service-uri orders-api
+cinna agent-api access issue orders-agent --to ana@example.com --scopes read --expires-in-days 30
+cinna agent-api access list orders-agent --all
+cinna agent-api access revoke orders-agent a1b2c3d4
+```
+
+`cinna account credentials list` shows an issued key's state in its Status column, and a skill slot filled by a revoked or expired key reads as not usable. `cinna agent import` does not draft `agent_api` credentials; it prints the `access issue` / `connect agent-api` command instead.
+
 ### `cinna connect agent-api --producer <agent> --consumer <agent> [--label TEXT] [--read-only]`
 
 Wire one agent to another's REST API from the account workspace. Resolves both agents (name, slug, or ID), mints a producer API token, and attaches it to the consumer as a credential — which rides the consumer's normal credential sync into its remote environment, so no key ever touches your machine. Prints the credential ID, token prefix, base URL, and spec URL. `--read-only` restricts the consumer to read-only access; `--label` names the credential. Backend errors surface verbatim: 400 if the producer's REST API is disabled, 403/404 for ownership violations.
@@ -508,7 +526,7 @@ Generic escape hatch into the platform API, authenticated with the account token
 
 - `--json '<obj>'` or `--data @file.json` supply a JSON request body (mutually exclusive); repeatable `--query k=v` supplies query parameters (repeating a key builds a list).
 - The inner response is passed through verbatim: the body prints to stdout (pretty-printed for JSON) and the exit code is `0` for 2xx and `1` for an inner 4xx/5xx — so it composes in shell pipelines.
-- When the escape hatch itself refuses the call, the detail prints to stderr and the exit code is `2`: policy denials (credentials, user management, admin, CLI, MFA/auth, and streaming routes are excluded — shown as `blocked by platform policy: …`), rate limiting (429, with the Retry-After delay), and request/response size caps (413/502).
+- When the escape hatch itself refuses the call, the detail prints to stderr and the exit code is `2`: policy denials (credentials, user management, admin, CLI, MFA/auth, and streaming routes are excluded, as are routes that would hand out a secret: any method on `agents/*/agent-api/keys…` (issued keys), on `environments/*/workspace/download` and `view-file`, and on `dashboards/*/blocks/*/env-file`; and POST on A2A access-tokens, MCP/ACP connector tokens, agent and task-trigger webhook create/regenerate-token. Paths are matched after percent-decoding. — shown as `blocked by platform policy: …`), rate limiting (429, with the Retry-After delay), and request/response size caps (413/502).
 
 `<path>` accepts the same **agent references** the rest of the CLI does: a segment straight after `agents/` that is not already a UUID is resolved against the account's agent listing, and the substitution is announced on stderr so a `--json` stdout stream stays pure. Resolution is sugar and never breaks the hatch — a reference that does not resolve (or an agent listing that cannot be reached) leaves the path exactly as typed, because `agents/` is a route prefix as well as a collection.
 

{cinna_cli-0.5.0 → cinna_cli-0.5.2}/README.md

@@ -449,6 +449,24 @@ Take a package out of the catalog. Agents that already installed it keep what th
 
 Put a delisted package back. `delist` has no inverse route of its own — without this verb the only way back would be `cinna api`, which would make delisting the one door in this group that opens only outwards.
 
+### `cinna agent-api access list | issue | revoke | scopes`
+
+Give people (or your own local agent) API access to a producer, from the account workspace. A key is issued to a **person** and lands in their credentials; **its value never appears in the CLI** — not on self-issue, not in `--json`. Reveal and rotate live on the web credential page, and so does the external-access switch (when it is off, `issue` is refused with the producer's Integrations URL). Writes need the `agent-developer` role.
+
+- `list <producer> [--all] [--json]` — people, their scopes and keys (prefix, status, expiry, last used, linked agents, id). Ended keys (revoked, expired, removed) are hidden unless `--all`; `--json` is always the full listing.
+- `issue <producer> --to <email|me> [--scopes a,b] [--expires-in-days N] [--service-uri SLOT] [--label TEXT] [--read-only] [--json]` — `--to` is required. `me` puts the key in your own credentials and prints the web URL where you reveal it; a local agent in Cinna Desktop calls it with `cinna_credentials.agent_api_session("<slot>")`, a cloud agent is wired with `cinna connect agent-api` instead.
+- `revoke <producer> <key> [--yes] [--json]` — `<key>` is the key id or the exact token prefix (an elided one is refused). Asks first; `--json` needs `--yes`; an already revoked key is reported, exit 0. The person's scopes stay.
+- `scopes <producer> --to <email|me> (--set a,b | --clear) [--json]` — change a grant without touching keys.
+
+```bash
+cinna agent-api access issue orders-agent --to me --service-uri orders-api
+cinna agent-api access issue orders-agent --to ana@example.com --scopes read --expires-in-days 30
+cinna agent-api access list orders-agent --all
+cinna agent-api access revoke orders-agent a1b2c3d4
+```
+
+`cinna account credentials list` shows an issued key's state in its Status column, and a skill slot filled by a revoked or expired key reads as not usable. `cinna agent import` does not draft `agent_api` credentials; it prints the `access issue` / `connect agent-api` command instead.
+
 ### `cinna connect agent-api --producer <agent> --consumer <agent> [--label TEXT] [--read-only]`
 
 Wire one agent to another's REST API from the account workspace. Resolves both agents (name, slug, or ID), mints a producer API token, and attaches it to the consumer as a credential — which rides the consumer's normal credential sync into its remote environment, so no key ever touches your machine. Prints the credential ID, token prefix, base URL, and spec URL. `--read-only` restricts the consumer to read-only access; `--label` names the credential. Backend errors surface verbatim: 400 if the producer's REST API is disabled, 403/404 for ownership violations.
@@ -471,7 +489,7 @@ Generic escape hatch into the platform API, authenticated with the account token
 
 - `--json '<obj>'` or `--data @file.json` supply a JSON request body (mutually exclusive); repeatable `--query k=v` supplies query parameters (repeating a key builds a list).
 - The inner response is passed through verbatim: the body prints to stdout (pretty-printed for JSON) and the exit code is `0` for 2xx and `1` for an inner 4xx/5xx — so it composes in shell pipelines.
-- When the escape hatch itself refuses the call, the detail prints to stderr and the exit code is `2`: policy denials (credentials, user management, admin, CLI, MFA/auth, and streaming routes are excluded — shown as `blocked by platform policy: …`), rate limiting (429, with the Retry-After delay), and request/response size caps (413/502).
+- When the escape hatch itself refuses the call, the detail prints to stderr and the exit code is `2`: policy denials (credentials, user management, admin, CLI, MFA/auth, and streaming routes are excluded, as are routes that would hand out a secret: any method on `agents/*/agent-api/keys…` (issued keys), on `environments/*/workspace/download` and `view-file`, and on `dashboards/*/blocks/*/env-file`; and POST on A2A access-tokens, MCP/ACP connector tokens, agent and task-trigger webhook create/regenerate-token. Paths are matched after percent-decoding. — shown as `blocked by platform policy: …`), rate limiting (429, with the Retry-After delay), and request/response size caps (413/502).
 
 `<path>` accepts the same **agent references** the rest of the CLI does: a segment straight after `agents/` that is not already a UUID is resolved against the account's agent listing, and the substitution is announced on stderr so a `--json` stdout stream stays pure. Resolution is sugar and never breaks the hatch — a reference that does not resolve (or an agent listing that cannot be reached) leaves the path exactly as typed, because `agents/` is a route prefix as well as a collection.
 

{cinna_cli-0.5.0 → cinna_cli-0.5.2}/docs/README.md

@@ -292,13 +292,14 @@ authoring convention.
 | **Live sync** | `cinna sync` (status, conflicts `[--diff]`, push, pull, resolve) + Mutagen transport; the session is started by `cinna agent sync` so the first push has a baseline | [business](features/live_sync/live_sync.md) · [tech](features/live_sync/live_sync_tech.md) · [acceptance](features/live_sync/live_sync_acceptance.md) |
 | **Remote exec** | `cinna exec` | [business](features/remote_exec/remote_exec.md) · [tech](features/remote_exec/remote_exec_tech.md) · [acceptance](features/remote_exec/remote_exec_acceptance.md) |
 | **Remote chat** | `cinna chat` (incl. `--attach` / `--show` to recover or read an existing session; poll failures retried within `--timeout`) · `cinna agent scenarios list / run` (replay `docs/test_scenarios/` Say rows, one session per row) | <!-- nocheck: agent-workspace path --> [business](features/remote_chat/remote_chat.md) · [tech](features/remote_chat/remote_chat_tech.md) · [acceptance](features/remote_chat/remote_chat_acceptance.md) |
-| **Agent API** | `cinna agent-api` (enable, refresh, spec, call) · `cinna api` · `cinna connect agent-api` | [business](features/agent_api/agent_api.md) · [tech](features/agent_api/agent_api_tech.md) · [acceptance](features/agent_api/agent_api_acceptance.md) |
+| **Agent API** | `cinna agent-api` (enable, refresh, spec, call, access list/issue/revoke/scopes) · `cinna api` · `cinna connect agent-api` | [business](features/agent_api/agent_api.md) · [tech](features/agent_api/agent_api_tech.md) · [acceptance](features/agent_api/agent_api_acceptance.md) |
 | **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) |
+| **Git versioning** | `cinna git` (link, status, commit, push, pull, log, checkout, unlink) — external remotes with your own credentials, `cinna` remotes with the CLI token | [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) |
+| **Team library** | `cinna library` (list, get, share, update, status, grants, suggest) — kit folders in `Local/<slug>/` shared through cinna-core-hosted git with the account token; `cinna agent import --from-library` | [business](features/team_library/team_library.md) · [tech](features/team_library/team_library_tech.md) · [acceptance](features/team_library/team_library_acceptance.md) |
 
 The sections below (Git Versioning, Sync Transport, Remote Exec, Remote Chat,
 Bootstrap Flow) remain as in-README quick references and backend contracts; the

{cinna_cli-0.5.0 → cinna_cli-0.5.2}/docs/features/account_workspace/account_workspace.md

@@ -156,7 +156,12 @@ each with its own token, registry entry, and Mutagen session.
   step; `--workspace` overrides the target workspace.
 - `cinna account credentials list` shows credentials with their type, **slot**,
   setup status (complete / needs setup, plus a placeholder marker) and full id —
-  metadata only. The slot is the credential's service URI: the non-secret id a
+  metadata only. For an issued Agent API key the Status cell shows the key's
+  state instead (Active; API turned off by producer / External access paused;
+  Revoked by issuer / Producer removed / Issuer account removed / Expired), and
+  `agent show` appends it when not active. A draft with `--type agent_api` is
+  refused by the platform: such a credential has no key behind it; use
+  `cinna agent-api access issue` (see [agent_api](../agent_api/agent_api.md)). The slot is the credential's service URI: the non-secret id a
   skill's `credentials:` block names and a script looks the credential up by, so
   it is the column that answers "which credential fills this skill's slot". The
   hint under the table names `cinna account credentials update <id> --service-uri

{cinna_cli-0.5.0 → cinna_cli-0.5.2}/docs/features/account_workspace/account_workspace_tech.md

@@ -216,6 +216,26 @@ Related (documented here as integration points): `cinna agent sync` →
 - `src/cinna/account.py:run_credentials_update()` — refuses an empty update;
   metadata fields only (`name`/`notes`/`service_uri`/`allow_sharing`).
 - `src/cinna/account.py:_credential_status_cell()` — complete / needs setup / —.
+- `src/cinna/account.py:_key_status_cell()` / `_KEY_STATUS_LABELS` — an issued
+  key's status as a coloured label; `run_credentials_list()` uses it in place of
+  the complete / needs-setup cell when `agent_api_key_status` is set, and
+  `_credential_summary()` appends it when not `active`.
+  `agent_api_key_status` is in `_ACCOUNT_AUTHORITATIVE_FIELDS`, so linked-credential
+  overlays carry it. (`tests/test_account.py`)
+- Skill slot readiness: `src/cinna/account.py:_slot_readiness()` treats a filled
+  carrier whose key status is not `active` as unusable and returns
+  `key_revoked` (revoked_by_issuer / producer_removed / issuer_removed),
+  `key_expired`, `key_paused` (api_disabled / external_access_paused) or
+  `key_unavailable` (a status this CLI does not know), via
+  `_key_unavailable_state()` / `_dead_key_carrier()` (every filled carrier of the
+  slot, of the declared type, holds a dead or paused key). A newer platform
+  flags such a slot itself as `access_revoked`; the CLI refines that reason to the
+  key state so the remedy fits. An older platform names no issue for catalog rows,
+  so the CLI checks key status there too. `_needs_linked_credentials()` fetches
+  the linked credentials for catalog rows with an `access_revoked` issue or an
+  unflagged declared slot. `_slot_remedy()` words the fix: ask the producer's owner
+  for a new key (`agent_api_issue_hint()`) for revoked/expired, "recovers by
+  itself" for paused, upgrade the CLI for unknown.
 - `src/cinna/account.py:run_credentials_list()` — `--json` echoes the listing
   untouched; otherwise the table adds a `Slot` column (`_credential_slot_cell()`,
   the escaped `service_uri` or a dim dash), marks `is_placeholder`, never wraps the

{cinna_cli-0.5.0 → cinna_cli-0.5.2}/docs/features/agent_api/agent_api.md

@@ -5,7 +5,7 @@
 Let an agent **expose its own HTTP/OpenAPI surface** (a "producer" REST API)
 that another agent (a "consumer") can call, and give a coding agent the local
 loop to build, verify, and wire those connections from the account workspace:
-`cinna agent-api` (enable / refresh / spec / call) drives the
+`cinna agent-api` (enable / refresh / spec / call / access) drives the
 **build→verify** loop on a producer; `cinna connect agent-api` does the
 **one-click wiring** of a consumer to it; and `cinna api` is a separate
 **escape hatch** for calling the platform's *own* control-plane API directly.
@@ -67,7 +67,8 @@ to test a producer endpoint — use `cinna agent-api call`.
   consumer authenticates its real calls with it.
 - **Escape hatch** — the account `api-proxy` route `cinna api` rides: a buffered
   JSON pass-through to the platform's own API, with excluded categories
-  (credentials, user management, admin, CLI, MFA/auth, streaming) denied.
+  (credentials, user management, admin, CLI, MFA/auth, streaming, and the
+  secret-minting routes listed under "Escape-hatch deny-list") denied.
 
 ## User flows
 
@@ -97,6 +98,35 @@ to test a producer endpoint — use `cinna agent-api call`.
   appears read-only under `workspace/credentials/` in a synced workspace) —
   no manual key handling.
 
+### Give API access (a person, or a local agent)
+- `cinna agent-api access list <producer>` shows who has access: one row per
+  person with their scopes and keys (prefix, status, expiry, last use, how many
+  agents use it, key id). `--all` also shows ended keys; `--json` is always the
+  full listing. The footer says whether external access is on and which scopes
+  the producer declares.
+- `cinna agent-api access issue <producer> --to <email|me>` issues a key to a
+  person. `--scopes a,b` sets their scopes (`""` = an explicit empty grant),
+  `--expires-in-days N` (1-3650), `--service-uri SLOT` names the credential's
+  slot (default `<producer>-api`), `--label`, `--read-only`.
+  - `--to me`: the key lands in your own credentials; the output names the slot
+    and the web credential page where you reveal the value. A local agent
+    (Cinna Desktop) then calls it by slot; a cloud agent is wired with
+    `cinna connect agent-api` instead.
+  - `--to <email>`: the key lands in that person's credentials; you never see
+    the value. The output prints the revoke command.
+  - Scopes outside the producer's declared catalog are stored anyway, with a
+    warning.
+- `cinna agent-api access revoke <producer> <key>` ends one key (asks first,
+  `--yes` skips). The person's scopes stay, so a new key can be issued without
+  re-granting.
+- `cinna agent-api access scopes <producer> --to <email|me> --set a,b | --clear`
+  changes a person's scopes without touching their keys, so a working key keeps
+  working. `--clear` removes the grant.
+- The result shows up elsewhere: `cinna account credentials list` shows the
+  key's status in the Status column, and a skill slot filled by a dead key
+  reads as not usable (see
+  [account_workspace](../account_workspace/account_workspace.md)).
+
 ### Call the platform's own API (unrelated to producer APIs)
 - `cinna api GET agents`, `cinna api POST agents/<id>/duplicate`,
   `cinna api PATCH agents/<id> --json '{…}'` — `PATH` is relative to the API
@@ -132,7 +162,8 @@ to test a producer endpoint — use `cinna agent-api call`.
   its own refusal from a mirrored inner error by a marker response header.
 - **Escape-hatch deny-list.** `cinna api` cannot reach credentials, user
   management, admin, CLI, MFA/auth, or streaming routes — the platform denies
-  them; don't waste calls.
+  them; don't waste calls. It also refuses routes that would hand out a secret:
+  any method on `agents/*/agent-api/keys…` (issued keys), on `environments/*/workspace/download` and `view-file`, and on `dashboards/*/blocks/*/env-file`; and POST on A2A access-tokens, MCP/ACP connector tokens, agent and task-trigger webhook create/regenerate-token. Paths are matched after percent-decoding. These refuse with 403 `excluded_path` (exit 2). Prefix-only listings stay reachable.
 - **An elided id is refused locally.** A path segment carrying `…` or `...` is
   an id copied out of a table cell too narrow to print it whole. It reaches the
   API as a well-formed path and comes back `404 Agent not found` — a sentence
@@ -150,6 +181,37 @@ to test a producer endpoint — use `cinna agent-api call`.
 - **No secret round-trip.** `connect agent-api` mints the producer token
   server-side and attaches it as a consumer credential; the secret value never
   passes through the CLI as something the user pastes or stores locally.
+- **A key value never crosses the CLI.** The platform sends none on the access
+  routes, the client drops any stray `token` field, and every runner drops it
+  again before printing or `--json`. Self-issue returns a web URL where the
+  person reveals the value; nobody should paste one into the CLI.
+- **Rotate and reveal are web-only.** Rotation replaces a value someone outside
+  the platform holds, which the CLI could not hand over, and a coding agent
+  could otherwise start a countdown that breaks every holder of the old value.
+  There is no verb for either.
+- **The external-access switch is web-only.** It is the deliberate human act
+  that exposes the API outside the platform. When it is off, `issue` is refused
+  with `external_access_disabled` and the producer's Integrations URL is
+  appended to the message (only when the platform's message lacks one); `list`
+  warns and prints the same URL.
+- **Terminal keys are hidden unless `--all`.** Revoked, producer/issuer removed
+  and expired keys drop out of the `access list` table with a footer count;
+  `--json` always carries everything.
+- **`--to` is required on `issue` and `scopes`.** The recipient is always a
+  deliberate choice: an email (resolved server-side, exact case-insensitive
+  match among active users) or `me`. An unknown email is refused, and one that
+  matches several accounts is refused as ambiguous rather than guessed.
+- **A key reference is a key id or the exact token prefix.** A reference
+  carrying an elision marker is refused locally (same rule as other ids); no
+  match or several matches fail with a candidate listing. Revoking an
+  already-revoked key is a no-op that exits 0 ("already revoked"); `--json`
+  requires `--yes`.
+- **Only the producer's owner (or an admin) manages access, and writes need
+  the developer role.** A producer that is missing or not yours reads as not
+  found. `list` is open to any account token.
+- **The generic escape hatch cannot issue keys.** `cinna api POST
+  agents/<id>/agent-api/keys` is refused (exit 2); the `access` verbs are the
+  only CLI way.
 - **Read-only is a connect-time choice.** `--read-only` is applied when the
   connection is created; it scopes the *consumer's* access, not the producer's
   surface.
@@ -169,6 +231,15 @@ build/verify (producer):
         ▼                                                      producer's env)
   agent-api call ─► owner-preview proxy ─► producer endpoint (no consumer token)
 
+people access (issued keys and scopes):
+  cinna agent-api access list/issue/revoke/scopes
+        │  account token
+        ▼
+  /api/v1/cli/account/agent-api/{access,keys,keys/revoke,access/scopes}
+        │ key lands in the recipient's credentials (value never returned)
+        ▼
+  recipient reveals it on the web; a local agent calls it by slot
+
 wiring (consumer):
   cinna connect agent-api --producer A --consumer B
         │  account token
@@ -195,6 +266,14 @@ platform escape hatch (unrelated target):
 - **Remote sync / exec** — authoring a producer API means editing files in the
   producer's synced `workspace/agent_api/` and pushing them to the running env
   (`cinna dev` / `cinna exec`); the spec is harvested from that env.
+- **Account workspace credentials and skill slots** — an issued key is a
+  credential whose listing row carries its key status; skill slot readiness
+  treats a revoked, expired or paused key as not usable. See
+  [account_workspace](../account_workspace/account_workspace.md).
+- **Local agent import** — `cinna agent import` never drafts an `agent_api`
+  credential (it could never be used); it attaches an existing same-name one or
+  prints the `access issue` / `connect agent-api` command. See
+  [local_agent_import](../local_agent_import/local_agent_import.md).
 - **`cinna agent show`** — surfaces a producer's live `agent_api_status`
   alongside its prompts and credentials, reusing the same status renderer.
 

{cinna_cli-0.5.0 → cinna_cli-0.5.2}/docs/features/agent_api/agent_api_acceptance.md

@@ -21,7 +21,7 @@ for** failure modes.
 - **Editable install** of the CLI under test:
   `python3 -c "import cinna,os;print(os.path.dirname(cinna.__file__))"` must
   point at this repo's `src/cinna`. Confirm `which cinna` resolves and
-  `cinna agent-api --help` lists `enable / refresh / spec / call`.
+  `cinna agent-api --help` lists `enable / refresh / spec / call / access`.
 - **A producer agent** you own whose workspace has (or will have) an
   `agent_api/` package + `policy.yaml`. Ideally synced locally
   (`cinna agent sync <producer>`) so you can edit + push the endpoint code.
@@ -196,6 +196,111 @@ for** failure modes.
 - **Watch for:** trying to test a producer endpoint via `cinna api` (wrong
   target — it calls platform routes, not the producer's served API).
 
+### 13. Issue yourself a key: URL, never a value
+
+- **Goal:** a builder gives themselves API access to a producer and never sees
+  the key value.
+- **Setup:** the producer's REST API is enabled; turn **external access** on in
+  the web (Integrations tab of the producer). It is web-only by design.
+- **Steps:**
+  ```
+  cinna agent-api access issue "<Producer>" --to me
+  cinna account credentials list
+  cinna agent-api access list "<Producer>"
+  ```
+- **Expected:** `Key <prefix> is in your credentials as slot <producer>-api …`
+  with a `…/credential/<id>` URL and the `cinna_credentials.agent_api_session`
+  hint; the output contains no key value. `credentials list` shows the new row
+  with Status `Active`; `access list` shows you with that key as Active.
+- **Watch for:** any full key or `token` field in the output (also with
+  `--json`); the credentials row showing `complete` instead of the key status.
+
+### 14. External access off refuses with the URL
+
+- **Goal:** issuing is fail-loud while external access is off.
+- **Setup:** turn external access off in the web.
+- **Steps:**
+  ```
+  cinna agent-api access issue "<Producer>" --to me; echo "exit=$?"
+  cinna agent-api access list "<Producer>"
+  ```
+- **Expected:** non-zero exit; the message says external access is disabled and
+  ends with `…/agent/<id>#integrations` (once, not doubled). `access list`
+  prints `External access: off` and a warning with the same URL. Turn it back on
+  before scenario 15.
+- **Watch for:** a generic error without the URL; any CLI path that switches it
+  on.
+
+### 15. Issue to another person, scopes, and list
+
+- **Goal:** give a colleague a scoped key without ever seeing it.
+- **Steps:**
+  ```
+  cinna agent-api access issue "<Producer>" --to <other-email> --scopes read --expires-in-days 30 --label qa
+  cinna agent-api access scopes "<Producer>" --to <other-email> --set read,write
+  cinna agent-api access list "<Producer>"
+  cinna agent-api access list "<Producer>" --json
+  cinna agent-api access issue "<Producer>" --to nobody@example.invalid; echo "exit=$?"
+  cinna agent-api access issue "<Producer>" --to nobody@example.invalid --json; echo "exit=$?"
+  ```
+- **Expected:** `Issued key <prefix> to <other-email>. It lands in their
+  credentials; you never see its value.` plus the revoke command. The scopes
+  command prints the person's resulting scopes and the key keeps working. The
+  table shows the person, scopes, key prefix, status, expiry, last used, linked
+  agent count and key id; `--json` is the full payload with no `token`
+  anywhere. The unknown recipient is refused and nothing is issued: the plain
+  run prints the server's sentence on stderr, and the `--json` run prints one
+  `{"result": "error", "code": "recipient_not_found", …}` line on stdout. Both
+  exit 1. An undeclared scope prints a warning but is stored.
+- **Watch for:** `--to` omitted not being a usage error; a key value in any
+  output; the scopes change revoking or replacing the key.
+
+### 16. Revoke: hidden by default, visible with `--all`, recipient sees it
+
+- **Goal:** revoking ends one key, keeps the grant, and is visible on both sides.
+- **Steps:**
+  ```
+  cinna agent-api access revoke "<Producer>" <prefix>          # answer n first, then y
+  cinna agent-api access list "<Producer>"
+  cinna agent-api access list "<Producer>" --all
+  cinna agent-api access revoke "<Producer>" <prefix> --yes     # again
+  cinna agent-api access revoke "<Producer>" <prefix> --json    # no --yes
+  ```
+  Then check the recipient's side. A recipient who is a developer can use their
+  own account workspace:
+  ```
+  cinna account credentials list
+  ```
+  An agent-user cannot create an account workspace (setup tokens are
+  developer-only), so for them sign in to the web app as the recipient and open
+  **Credentials**, or call `GET /api/v1/credentials` with their token and read
+  `agent_api_key_status`.
+- **Expected:** declining sends nothing; accepting prints `Revoked key <prefix>
+  issued to <email>. Status: Revoked by issuer`. The default list hides the key
+  with `1 ended key hidden (--all)` while the person's scopes row stays;
+  `--all` shows `Revoked by issuer`. Revoking again prints `already revoked`
+  and exits 0. `--json` without `--yes` is a usage error. The recipient still
+  has the credential, with Status `Revoked by issuer` (`agent_api_key_status:
+  revoked_by_issuer` in the API).
+- **Watch for:** the grant disappearing with the key; an elided prefix
+  (`ab12…`) not being refused locally; the recipient's credential being
+  deleted rather than flagged.
+
+### 17. The escape hatch cannot mint keys
+
+- **Goal:** `cinna api` is not a back door around the no-value rule.
+- **Steps:**
+  ```
+  cinna api POST agents/<producer-id>/agent-api/keys --json '{"label":"x"}'; echo "exit=$?"
+  cinna api GET agents/<producer-id>/agent-api/access; echo "exit=$?"
+  cinna agent-api access list "<Producer>"
+  ```
+- **Expected:** the POST prints `blocked by platform policy: …` on stderr and
+  exits 2; no key was created (the list is unchanged). The `access` GET through
+  the hatch is still reachable. The same refusal (403 `excluded_path`, exit 2)
+  applies to any method on `agents/*/agent-api/keys…`, `environments/*/workspace/download` and `view-file`, `dashboards/*/blocks/*/env-file`, and POST on token-minting routes (A2A access-tokens, MCP/ACP connector tokens, webhook create/regenerate-token), including percent-encoded spellings.
+- **Watch for:** exit 1 instead of 2; a key created by the call.
+
 ## Cross-cutting invariants (must hold across all scenarios)
 
 - **Resolve-before-mutate.** A bad agent ref fails before any enable / refresh /
@@ -209,6 +314,8 @@ for** failure modes.
   both `agent-api call` and `cinna api`; only `cinna api` adds exit 2 for the
   hatch's own refusal (policy / rate limit / size cap), distinguished by the
   marker header — never conflated with an inner 4xx.
+- **No key value in any access output.** Not in the table, not in `--json`,
+  not on self-issue; reveal and rotate are web-only.
 - **Spec is pipeable.** `cinna agent-api spec` emits plain JSON to stdout (or the
   `-o` file), never Rich-decorated.
 
@@ -221,4 +328,8 @@ for** failure modes.
   `cinna agent-api enable "<Producer>" --disable`.
 - Remove any deliberately-broken `agent_api/` edits (revert + sync), then
   `cinna agent-api refresh` to restore a clean harvested spec.
+- Revoke test keys (`cinna agent-api access revoke "<Producer>" <prefix> --yes`),
+  clear test grants (`cinna agent-api access scopes "<Producer>" --to <email>
+  --clear`), delete the revoked credentials in the web, and set external access
+  back to its prior state.
 - Delete scratch files written by `cinna agent-api spec -o spec.json`.

{cinna_cli-0.5.0 → cinna_cli-0.5.2}/docs/features/agent_api/agent_api_tech.md

@@ -13,10 +13,16 @@ talks to the platform through `AccountClient` with the account token.
   shared status renderer.
 - `src/cinna/client.py` — `AccountClient` methods that hit the account routes
   (`set_agent_api_enabled`, `refresh_agent_api`, `get_agent_api_spec`,
-  `call_agent_api`, `connect_agent_api`, `connect_mcp`, `api_proxy`).
+  `call_agent_api`, `connect_agent_api`, `connect_mcp`, `api_proxy`, and the
+  four access methods `list_agent_api_access`, `issue_agent_api_key`,
+  `revoke_agent_api_key`, `set_agent_api_scopes`) plus the `drop_token()` helper.
 - Tests: `tests/test_account.py` (enable/refresh/spec/call, connect agent-api,
   `cinna api` exit-code matrix, `api_proxy` client behavior),
-  `tests/test_client.py` (`AccountClient` route shapes).
+  `tests/test_client.py` (`AccountClient` route shapes, the access methods,
+  coded refusals, `drop_token`), `tests/test_agent_api_access.py` (the four
+  `access` verbs end to end against a mocked client), `tests/test_account.py`
+  (key status cells, slot readiness key states), `tests/test_local_import.py`
+  (`agent_api` spec skipped).
 
 ## Command surface
 
@@ -31,6 +37,16 @@ Each verb → its handler in `src/cinna/main.py` → the `run_*` in
   `src/cinna/account.py:run_agent_api_spec()`
 - `cinna agent-api call` → `src/cinna/main.py:agent_api_call()` →
   `src/cinna/account.py:run_agent_api_call()`
+- `cinna agent-api access list` → `src/cinna/main.py:agent_api_access_list()` →
+  `src/cinna/account.py:run_agent_api_access_list()`
+- `cinna agent-api access issue` → `src/cinna/main.py:agent_api_access_issue()` →
+  `src/cinna/account.py:run_agent_api_access_issue()` (`--to` required;
+  `--expires-in-days` is `click.IntRange(1, 3650)`)
+- `cinna agent-api access revoke` → `src/cinna/main.py:agent_api_access_revoke()` →
+  `src/cinna/account.py:run_agent_api_access_revoke()`
+- `cinna agent-api access scopes` → `src/cinna/main.py:agent_api_access_scopes()` →
+  `src/cinna/account.py:run_agent_api_access_scopes()` (exactly one of `--set` /
+  `--clear`, checked in the Click handler)
 - `cinna connect agent-api` → `src/cinna/main.py:connect_agent_api()` →
   `src/cinna/account.py:run_connect_agent_api()`
 - `cinna connect mcp` → `src/cinna/main.py:connect_mcp()` →
@@ -75,6 +91,49 @@ Each verb → its handler in `src/cinna/main.py` → the `run_*` in
   `client.api_proxy(method, path, query, json_body)`, then branches on the
   marker header (see below) to set the exit code.
 
+## Access verbs: key functions
+
+- `src/cinna/account.py:_access_recipient()` — `--to` as the request field:
+  `me` becomes a null email, blank is a usage error.
+- `src/cinna/account.py:_parse_scope_list()` — `a,b` to a list, `""` to an
+  explicit empty list, unset to `None` (leave the grant as is).
+- `src/cinna/main.py:_access_json_mode()` — each `access` command's own
+  `--json` also turns on console JSON mode, so a refusal prints the
+  `{"result": "error", "code", "detail", "http_status"}` line with the server's
+  code instead of a bare `Error: <sentence>`
+  (`tests/test_agent_api_access.py:test_json_refusal_carries_the_server_code`).
+- `src/cinna/account.py:run_agent_api_access_list()` — one row per person/key;
+  a grant-only person is one row with Key `—`; terminal keys filtered by
+  `_TERMINAL_KEY_STATUSES` unless `--all` with an "N ended keys hidden" footer;
+  `_print_access_footer()` prints external access on/off (warning plus
+  `manage_url` when off) and the scope catalog.
+- `src/cinna/account.py:run_agent_api_access_issue()` — catches a
+  `CodedRefusal` with code `external_access_disabled` and re-raises it with
+  `_manage_url()` appended only when the message has no `http` URL; self-issue
+  prints the slot, `credential_url` and the `cinna_credentials.agent_api_session`
+  hint, other-issue prints the revoke hint via `_agent_ref_for_hint()`;
+  `_warn_unknown_scopes()` warns, never refuses.
+- `src/cinna/account.py:_resolve_access_key()` — key id first, then exact
+  `token_prefix`, resolved against a fresh access listing; elided refs
+  (`_ELIDED_MARKERS`) are a usage error; none/several matches list candidates.
+- `src/cinna/account.py:run_agent_api_access_revoke()` — `_require_yes_for_json()`
+  first; already `revoked_by_issuer` returns without a call; other ended
+  statuses ask "revoke it anyway?"; confirmation declined aborts with no call.
+- `src/cinna/account.py:run_agent_api_access_scopes()` — `--clear` sends `None`;
+  prints the resulting scopes or "Grant removed".
+- `src/cinna/account.py:_KEY_STATUS_LABELS` / `_key_status_cell()` — the one
+  status-word table (green Active; yellow API turned off by producer / External
+  access paused; red Revoked by issuer / Producer removed / Issuer account
+  removed / Expired; unknown values printed raw and dim).
+- `src/cinna/account.py:_key_unavailable_state()`,
+  `agent_api_producer_from_slot()`, `agent_api_issue_hint()` — shared by slot
+  readiness and the importer; the hint derives the producer from a
+  `<producer>-api` slot (else `<producer>`) and omits `--service-uri` when there
+  is no slot.
+- `src/cinna/client.py:drop_token()` — recursively removes every `token` key
+  from a payload; applied by `AccountClient._access_response()` and again by
+  each runner.
+
 ## The escape hatch's exit-code logic (`run_api`)
 
 `src/cinna/account.py:run_api()` distinguishes three outcomes by the presence of
@@ -107,6 +166,22 @@ contract but has no exit-2 case (it returns the buffered
 - `call_agent_api(agent_id, method, path, query, json_body)` → `POST
   /api/v1/cli/account/agent-api/call`; owner-preview invocation, returns
   `{status_code, headers, body, is_json}`.
+- `list_agent_api_access(agent_id)` → `GET
+  /api/v1/cli/account/agent-api/access` (`agent_id` query param).
+- `issue_agent_api_key(agent_id, *, issued_to_email, scopes, expires_in_days,
+  service_uri, label, read_only)` → `POST /api/v1/cli/account/agent-api/keys`;
+  `None` fields are omitted from the body.
+- `revoke_agent_api_key(agent_id, key_id)` → `POST
+  /api/v1/cli/account/agent-api/keys/revoke`.
+- `set_agent_api_scopes(agent_id, user_email, scopes)` → `PUT
+  /api/v1/cli/account/agent-api/access/scopes`; `scopes` is always sent, as an
+  explicit `null` for `--clear` (core answers 422 if the field is omitted; null
+  removes the grant), `user_email` omitted for the caller.
+- All four go through `AccountClient._access_response()`: a bare
+  `{"detail": "Not Found"}` 404 becomes a `PlatformError` saying the platform
+  predates API access from the CLI; otherwise `_handle_response(coded=True)`
+  raises a `CodedRefusal` for a `{detail: {code, message}}` body (not for 401);
+  then `drop_token()`.
 - `connect_agent_api(producer_agent_id, consumer_agent_id, credential_label,
   read_only_override)` → `POST /api/v1/cli/account/connect/agent-api`.
 - `connect_mcp(connector_id, consumer_agent_id, …)` → `POST
@@ -126,6 +201,26 @@ All under `/api/v1/cli/account/*`, account-token auth:
 - `GET  …/agent-api/spec` — the harvested OpenAPI spec JSON.
 - `POST …/agent-api/call` — owner-preview endpoint invocation (query forwarded,
   no consumer token, no policy edge).
+- `GET  …/agent-api/access?agent_id=` — people, scopes, keys (terminal keys
+  included), `external_access_enabled`, `identity_enabled`, `scope_catalog`,
+  `manage_url`.
+- `POST …/agent-api/keys` — issue a key; answers the key's public fields plus
+  `base_url`, `spec_url`, `service_uri`, `issued_to_self`, `credential_url`
+  (self-issue only) and `unknown_scopes`. Never a key value.
+- `POST …/agent-api/keys/revoke` — body `{agent_id, key_id}`; idempotent
+  (`status: revoked_by_issuer`); the grant is untouched.
+- `PUT  …/agent-api/access/scopes` — body `{agent_id, user_email, scopes}`;
+  `scopes` is required but nullable, so `--clear` sends `"scopes": null`
+  explicitly (omitting the field is a 422 on the core side); answers `{entry, unknown_scopes}`.
+- `GET  …/credentials` — each row carries `agent_api_key_status` for issued
+  keys (null for connections); `POST …/credentials` with type `agent_api` is
+  refused with a 400 that names the issue command.
+- `api-proxy` refusals added with issued keys: 403 `excluded_path` (CLI exit 2)
+  for any method on `agents/*/agent-api/keys…`, `environments/*/workspace/download`
+  and `view-file`, `dashboards/*/blocks/*/env-file`, and POST on A2A
+  access-tokens, MCP/ACP connector tokens and agent / task-trigger webhook
+  create/regenerate-token; paths are matched percent-decoded. The CLI needs no
+  code for this: the hatch's own refusal already exits 2.
 - `POST …/connect/agent-api` — mint the producer token + attach to the consumer
   as a credential.
 - `POST …/connect/mcp` — the agent2agent MCP wiring (sibling).
@@ -133,6 +228,13 @@ All under `/api/v1/cli/account/*`, account-token auth:
   the "Platform API Endpoints" table in `docs/README.md` for the canonical
   account-route list.
 
+Error codes on the four access routes (`{"detail": {"code", "message"}}`,
+surfaced as `CodedRefusal`): `agent_not_found` (404, not owned: no leak),
+`recipient_not_found` (404), `ambiguous_recipient` (409, case-only duplicate
+emails), `external_access_disabled` (400), `api_disabled` (400), `key_not_found`
+(404), and `invalid_request` / `not_found` / `conflict` for any other platform
+refusal. 422 is body validation. A non-developer gets a plain 403 on writes.
+
 Producer-side author contract (not CLI files — they live in the producer's
 synced workspace, harvested by the platform): `workspace/agent_api/*.py`
 (endpoint modules) and `workspace/policy.yaml` (access/guardrail policy).
@@ -160,5 +262,18 @@ synced workspace, harvested by the platform): `workspace/agent_api/*.py`
   raises only on 401.)
   (`tests/test_account.py` — the `test_api_*` matrix,
   `…test_account_client_api_proxy_*`)
+- **No key value, ever.** `drop_token()` runs in the client and again in each
+  runner before printing or `--json`; the revoke path also scrubs the listing it
+  resolves the key from. (`tests/test_client.py` token-drop tests,
+  `tests/test_agent_api_access.py` self-issue test with a mock that returns a
+  `token`.)
+- **`external_access_disabled` carries a URL.** The URL is appended only when
+  absent so a platform that already names it is not doubled.
+  (`src/cinna/account.py:run_agent_api_access_issue()`)
+- **Unknown key status is unavailable, not usable.** `_key_unavailable_state()`
+  returns `key_unavailable` for a status this CLI does not know; the cell prints
+  it raw and dim. (`tests/test_account.py` slot readiness tests)
+- **Confirm before revoke, nothing sent on decline.** `--json` without `--yes`
+  is a usage error. (`tests/test_agent_api_access.py`)
 - **`--json` / `--data` mutual exclusion** in `run_api`; `--data @file` strips a
   leading `@`. (`src/cinna/account.py:run_api()`)

{cinna_cli-0.5.0 → cinna_cli-0.5.2}/docs/features/delegation/delegation.md

@@ -152,9 +152,11 @@ result attached to the current task ──► delivered to the requester (Deskto
 - **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.
+  backend's `cinna` MCP server exposes a `tasks_report` tool (the Cinna Task
+  Protocol, kit contract 1.6.0) that records the same kind of result; an
+  environment built before protocol version 1 still has it as `handover_report`
+  on the older `agent_task` server. 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.5.0 → cinna_cli-0.5.2}/docs/features/delegation/delegation_tech.md

@@ -122,8 +122,9 @@ Executor side — direct call, agent-token auth:
   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.
+Related, not in this repo: cinna-core's `cinna` MCP server exposes a
+`tasks_report` tool for the same executor-side report (`handover_report` on
+environments built before protocol version 1).
 
 ## Edge cases & guardrails (preserve these)