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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cinna-cli
-Version: 0.4.3
+Version: 0.5.1
 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
@@ -338,6 +338,8 @@ The folder rules come from the kit's versioned contract, `.cinna-kit/layout.json
 
 Where the folder has been published is recorded in `publications.json`, a **sibling** of `cinna-agent.json` holding one entry per Cinna instance — it cannot live inside the manifest, because each entry records a hash of the exported tree and the manifest is part of that tree. Every step is idempotent (agent by the entry whose `platform_url` matches the instance you are logged into, credentials by name, schedules by name), so a partial import is resumed with `--update` instead of duplicating anything. The publication is recorded **only after the push settled** — `--no-push`, a failed flush, or remaining conflicts leave it unrecorded, and the next run is a plain `--update`. A legacy `cloud` block is migrated into the ledger on the first write and is still read until then, so an older folder's `--update` never creates a second agent. `--dry-run` makes no platform call and writes nothing.
 
+The manifest's `runtime.engine` (`opencode`, `claude`, `codex`, …) is sent when the agent is **created**; the platform runs an engine it does not support on OpenCode, and `--update` never changes an existing agent's engine. The plan prints an `Engine:` line, and a `Not carried to the cloud:` line naming the manifest fields present that the cloud has no place for (`runtime.model`, `runtime.complexity`, `runtime.credential`, `runtime.permissions`, unknown `runtime.*` keys, `handovers` — the import sends no handover at all — and `capabilities`). A malformed `runtime` costs a warning, never the import.
+
 ### `cinna skills list <agent> [--json]`
 
 List everything an agent carries beyond its prompt, as one deduplicated list. An **addon** is either an installed plugin or a `skills/<name>/` folder — a `SKILL.md` plus its files that the engine loads on demand. The two overlap (a skill installed from the catalog is *also* a plugin link), and the platform owns the dedupe rule, so this prints the server's projection rather than folding the halves itself: one row per addon, with its kind, source (`marketplace` / `bundle` / `catalog` / `local`), status, name and version.

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

@@ -301,6 +301,8 @@ The folder rules come from the kit's versioned contract, `.cinna-kit/layout.json
 
 Where the folder has been published is recorded in `publications.json`, a **sibling** of `cinna-agent.json` holding one entry per Cinna instance — it cannot live inside the manifest, because each entry records a hash of the exported tree and the manifest is part of that tree. Every step is idempotent (agent by the entry whose `platform_url` matches the instance you are logged into, credentials by name, schedules by name), so a partial import is resumed with `--update` instead of duplicating anything. The publication is recorded **only after the push settled** — `--no-push`, a failed flush, or remaining conflicts leave it unrecorded, and the next run is a plain `--update`. A legacy `cloud` block is migrated into the ledger on the first write and is still read until then, so an older folder's `--update` never creates a second agent. `--dry-run` makes no platform call and writes nothing.
 
+The manifest's `runtime.engine` (`opencode`, `claude`, `codex`, …) is sent when the agent is **created**; the platform runs an engine it does not support on OpenCode, and `--update` never changes an existing agent's engine. The plan prints an `Engine:` line, and a `Not carried to the cloud:` line naming the manifest fields present that the cloud has no place for (`runtime.model`, `runtime.complexity`, `runtime.credential`, `runtime.permissions`, unknown `runtime.*` keys, `handovers` — the import sends no handover at all — and `capabilities`). A malformed `runtime` costs a warning, never the import.
+
 ### `cinna skills list <agent> [--json]`
 
 List everything an agent carries beyond its prompt, as one deduplicated list. An **addon** is either an installed plugin or a `skills/<name>/` folder — a `SKILL.md` plus its files that the engine loads on demand. The two overlap (a skill installed from the catalog is *also* a plugin link), and the platform owns the dedupe rule, so this prints the server's projection rather than folding the halves itself: one row per addon, with its kind, source (`marketplace` / `bundle` / `catalog` / `local`), status, name and version.

{cinna_cli-0.4.3 → cinna_cli-0.5.1}/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.4.3 → cinna_cli-0.5.1}/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)
 

{cinna_cli-0.4.3 → cinna_cli-0.5.1}/docs/features/local_agent_import/local_agent_import.md

@@ -21,7 +21,9 @@ The kit's machine-readable half is a **versioned contract** (`layout.json`,
 `GET /api/agent-start/contract.tar.gz` with a cheap version poll at
 `GET /api/agent-start/contract/version`. cinna-cli reads the copy installed at
 `.cinna-kit/`; a shipped build should obtain it from those routes rather than
-vendoring one.
+vendoring one. This build implements contract **1.5.0** (`runtime.engine`,
+`runtime.complexity` and `handovers[].target_kind` in core's one schema); only
+the major decides compatibility, so any `1.x` folder imports.
 
 Nothing platform-side is new: the import replays the manifest through the
 existing account-scoped verbs (`agent create`, the bulk prompt write, `agent
@@ -57,6 +59,30 @@ sync`, `sync push`, `account credentials create`, `agent schedule create`,
   `.env.sample` and `.env.template` still travel. Credentials are created as
   **empty drafts** and the command prints the URLs the user opens to fill each
   one in the browser. No secret value is read, sent, or printed at any point.
+- **A credential spec can name its slot.** Since contract 1.4.0 a manifest
+  credential may carry `service_uri` — the slot the agent's credential reader
+  matches an attached credential on. The import passes it to the draft
+  unchanged; one that is not a non-empty string is refused with the other
+  manifest guards, before the agent is created.
+- **The engine is a preference, carried once.** A manifest's `runtime.engine`
+  (`opencode`, `claude`, `codex`, or a name this build has never heard of) is
+  sent to the platform when the agent is **created**, which maps it to the
+  environment's SDK and runs an engine it does not support on OpenCode — the
+  folder is never refused over it. `--update` never changes an existing agent's
+  engine. A `runtime` that is not an object, or an engine that is not a string,
+  costs a warning and nothing is sent.
+- **What the cloud does not carry is named, not dropped silently.** The other
+  `runtime` fields (`model`, `complexity`, `credential`, `permissions`, and any
+  key this build does not know) have no cloud counterpart, and the import
+  sends no `handovers` at all (not only the desktop's `target_kind`) and maps
+  `capabilities` onto nothing; the plan lists the ones present in one
+  `Not carried to the cloud:` line.
+- **Using cloud credentials on the desktop is not an import concern.** A
+  locally running agent in Cinna Desktop gets credential values from the
+  platform's desktop delivery route, gated per credential by *allow local use*
+  for credentials shared with you (your own always qualify). That exchange is
+  between the platform and the desktop; `cinna agent import` never reads
+  credential values, and the CLI has no switch for *allow local use* yet.
 - **The ledger is a sibling file, never a manifest key.** Where an agent folder
   has been published is recorded in `publications.json` beside
   `cinna-agent.json` — one entry per Cinna instance. It has to be a separate
@@ -83,10 +109,11 @@ Each prints as `[n/9]`:
    contract: refuse a folder built against a newer **major** contract version,
    warn on an older one or on a folder that records none, resolve the exclude
    list and the secret rules, plan the copy and compute the tree's
-   `content_hash`.
+   `content_hash`. Read `runtime` tolerantly and print the `Engine:` line and,
+   when any are present, the `Not carried to the cloud:` line.
 2. **Agent** — resolve by the `publications.json` entry for this instance
    (requires `--update`) or create a new agent in the active user workspace
-   (`--workspace` overrides).
+   (`--workspace` overrides), passing `runtime.engine` on creation only.
 3. **Prompts + metadata** — one bulk write carrying `description`,
    `router_trigger_prompt`, `example_prompts`, and the three document prompts
    read from the files named in `prompts`; then the status refresh command.
@@ -99,7 +126,8 @@ Each prints as `[n/9]`:
 6. **Push** — `cinna sync push` equivalent (skipped by `--no-push`).
 7. **Credentials** — one empty draft per spec, attached to the agent; an
    existing credential of the same name is attached rather than recreated.
-   Setup URLs are collected for the summary.
+   A spec's `service_uri` is set on a new draft; an existing credential keeps
+   its own. Setup URLs are collected for the summary.
 8. **Schedules** — one per spec, name-idempotent; `--update` rewrites an
    existing schedule in place.
 9. **Record** — add or update this instance's entry in `publications.json`
@@ -131,7 +159,11 @@ file that would be copied, every credential draft, every schedule — and makes
 `publications.json` entry whose `platform_url` matches the instance you are
 logged into (not by workspace, and not by position in the list), rewrites
 prompts and metadata, re-copies the tree, pushes, attaches existing credentials,
-and updates the schedules in place.
+and updates the schedules in place. The agent's engine is left as it is; when
+the manifest names one, the `Engine:` line says it was not applied. An
+`--update` with no known agent id cannot tell from the plan whether it will
+find the agent by name or create it, so the plan says the engine is sent only
+on creation, and the lookup then says which happened.
 
 ### Resume a partial import
 
@@ -160,11 +192,15 @@ created are reused, not duplicated.
 | `schema_version` newer than supported | Refused with an upgrade hint — never half-read |
 | Folder built against a newer **major** contract version | Refused with an upgrade hint — a minor or patch difference is not a compatibility question and passes silently |
 | Folder records no `contract_version` | Warned and imported — every folder created before contract 1.0.0 is in that state |
+| A credential's `service_uri` is empty or not a string | Refused before any platform call, naming the credential |
+| `runtime` is not an object, or `runtime.engine` is not a string | Warned and imported; no engine is sent, so the agent gets the platform default |
+| `runtime.engine` names an engine the cloud does not support | Imported; the platform runs the agent on OpenCode |
+| Older platform without the `engine` create field | Imported; the platform ignores the unknown field and the agent gets its default engine |
 | Already imported to this instance, no `--update` | Refused, naming the agent id and where the link was recorded |
 | The recorded agent id is not among your agents | Refused — you are logged into a different platform, or the agent was deleted |
 | `--update` with several name matches | Refused, listing them; add the `publications.json` entry to disambiguate |
 | Push failed or left conflicts | Warned, **nothing recorded**, with the resolve + `--update` hint |
-| `.cinna-kit/layout.json` missing or unreadable | Imported with the built-in contract copy, the `Exclusions:` line marked `DEGRADED`, and **no `content_hash` recorded** — a hash over a file set another host would not select is worse than none |
+| `.cinna-kit/layout.json` missing or unreadable | Imported with the built-in copy of contract 1.5.0, the `Exclusions:` line marked `DEGRADED`, and **no `content_hash` recorded** — a hash over a file set another host would not select is worse than none |
 | A travelling file or directory cannot be read | Refused — a complete-looking export with a subtree missing from it is the one outcome worth stopping for |
 | `publications.json` unreadable | Refused, and the file is left exactly as it was |
 | Credential/schedule 403 | The platform error surfaces verbatim; earlier steps stay done and `--update` resumes |

{cinna_cli-0.4.3 → cinna_cli-0.5.1}/docs/features/local_agent_import/local_agent_import_acceptance.md

@@ -121,7 +121,8 @@ any change to the orchestrator.
 
 - **Steps:** in a scratch copy of the agent folder, one at a time: bump
   `schema_version` to `2`; rename the folder so it disagrees with `slug`; make
-  `cron_string` `"every morning"`; drop a credential's `type`.
+  `cron_string` `"every morning"`; drop a credential's `type`; set a
+  credential's `service_uri` to `""`.
 - **Expected:** each is refused *before* any platform call, with a message that
   names the offending field.
 - **Watch for:** a half-applied import (agent created, then the manifest
@@ -242,14 +243,55 @@ any change to the orchestrator.
 ### 10f. The `contract_version` gate
 
 - **Steps:** set the manifest's `contract_version` to `2.0.0` and import; then
-  to `1.4.2` and import; then remove the key entirely and import.
+  to `1.5.2` and import; then remove the key entirely and import.
 - **Expected:** `2.0.0` is refused before any platform call, naming `2.x`;
-  `1.4.2` passes **silently** (same major — a minor contract change is additive
+  `1.5.2` passes **silently** (same major — a minor contract change is additive
   by definition and reaches a non-adopting reader as silence); the missing key
   warns about a re-stamp and imports anyway.
 - **Watch for:** a warning on the same-major pair. That is the gate's shape, not
   a bug: anything an old reader must notice needs a major bump.
 
+### 10g. A credential slot reaches the draft (contract 1.4.0)
+
+- **Goal:** a manifest credential that names its slot gets a draft the agent's
+  credential reader can match, in the cloud and on the desktop.
+- **Setup:** a fresh agent whose manifest credential carries
+  `"service_uri": "imap://billing"` and whose name does **not** exist yet in the
+  account.
+- **Steps:**
+  ```bash
+  cinna agent import MyAgents/Local/<agent> --yes
+  cinna account credentials list
+  ```
+- **Expected:** the draft is listed with `imap://billing` in the **Slot** column; after it is filled
+  in the browser, `cinna skills list <agent>` (if a skill declares the slot)
+  shows it ready. Re-running with `--update` does not change the URI of the
+  existing credential.
+- **Watch for:** a draft created without the slot, so the reader falls back to
+  name matching; a second draft created because the slot differs.
+
+### 10h. The engine travels at creation, and nothing else from `runtime` (contract 1.5.0)
+
+- **Setup:** a fresh agent whose manifest carries
+  `"runtime": {"engine": "claude", "model": "claude-sonnet", "complexity": "medium"}`
+  and a handover with `"target_kind": "coordinator"`. Requires a cinna-core that
+  accepts `engine` on `POST /api/v1/cli/account/agents`.
+- **Steps:**
+  ```bash
+  cinna agent import MyAgents/Local/<agent> --dry-run
+  cinna agent import MyAgents/Local/<agent> --yes
+  cinna agent import MyAgents/Local/<agent> --update --yes
+  ```
+- **Expected:** both the dry run and the import print
+  `Engine:      claude — sent as a preference (the cloud runs engines it does not support on OpenCode)`
+  and `Not carried to the cloud: runtime.model, runtime.complexity, handovers`;
+  the new agent's environment runs on Claude Code. Set `"engine": "codex"` on a
+  fresh agent: it imports and runs on OpenCode. The `--update` run prints
+  `Engine:      claude — not applied: --update never changes an existing agent's engine`
+  and the environment is unchanged.
+- **Watch for:** the import refusing an unknown engine; the model override
+  changing; an older cinna-core rejecting the create (it should ignore `engine`).
+
 ### 11. Verification loop the guide promises
 
 - **Steps:**

{cinna_cli-0.4.3 → cinna_cli-0.5.1}/docs/features/local_agent_import/local_agent_import_tech.md

@@ -39,7 +39,7 @@ endpoint exists for this feature.
 
 | Step | Call |
 |------|------|
-| 2 | `list_account_agents()` (resolve) / `create_agent(name, description, user_workspace_id=…)` |
+| 2 | `list_account_agents()` (resolve) / `create_agent(name, description, user_workspace_id=…, engine=…)` — `engine` is in the body only when set |
 | 3 | `update_agent_config(agent_id, fields)` → `PUT agents/{id}` **through the api-proxy escape hatch**, then `set_status_refresh_command(agent_id, cmd)` |
 | 4 | `account.py:run_agent_sync(agent_id, None)` (mints the child token, provisions the workspace) — skipped when `resolve_child_workspace()` already finds one |
 | 6 | `sync_session.ensure_session()` + `sync_session.flush()` — the same pair `cinna sync push` uses |
@@ -70,10 +70,59 @@ pragmatic subset `kit.py validate` checks:
 - `slug` matches `^[a-z0-9][a-z0-9-]{1,62}$` **and** equals the folder name.
 - `name` present, ≤ 255 chars; `description` a string when present.
 - `prompts` an object; `example_prompts` a list of strings.
-- Each credential has a non-empty `name` and `type`.
+- Each credential has a non-empty `name` and `type`, and a `service_uri`
+  (contract 1.4.0, optional) is a non-empty string when present. Checked here
+  rather than left to the platform because the agent already exists by the time
+  `_sync_credentials()` sends it — a 422 there is a half-applied import.
 - Each schedule has a name, a 5-field `cron_string`, a known `schedule_type`, and
   a `command` when it is a script schedule.
 
+`runtime` is **not** validated here — `read_runtime(manifest)` reads it
+tolerantly after the manifest loads, because its fields are additive minors
+that must never cost the import:
+
+- `runtime` not an object, or `runtime.engine` not a string → a
+  `console.warn` naming the type, and no engine is sent.
+- `runtime.engine` stripped; empty means absent. Otherwise sent raw — it is not
+  an enum, and the backend owns the mapping (`claude` → Claude Code, everything
+  it does not support → OpenCode, decision 4 of the 1.5.0 unification plan).
+- The fields the cloud import does not carry are returned as dotted paths, in
+  a fixed order: `runtime.model`, `runtime.complexity`, `runtime.credential`,
+  `runtime.permissions` (`_UNCARRIED_RUNTIME_KEYS`), then any unknown
+  `runtime.*` key sorted, then `handovers` — the whole list, when it is
+  non-empty, because this import sends no handover at all; naming only
+  `handovers[].target_kind` would imply the rest of a handover travels — then
+  `capabilities`, when any of its keys has a value (`x-import: ignored`). A
+  key whose value is `null` counts as absent.
+
+The engine reaches `_resolve_or_create_agent()` and is passed to
+`create_agent()` **only on the create branch**. An agent resolved by id or
+reattached by name keeps its engine: the id case says so in the step-1 `Engine:`
+line (`known_agent_id` is known before the plan prints). `--update` without a
+known id only learns at step 2 whether a name match exists, so its step-1 line
+is the undecided one, and step 2 prints either the kept line (name-matched
+resume) or the sent line (no match, agent created). The `Engine:` values,
+verbatim:
+
+```
+  Engine:      claude — sent as a preference (the cloud runs engines it does not support on OpenCode)
+  Engine:      claude — not applied: --update never changes an existing agent's engine
+  Engine:      claude — sent only if this import creates the agent; --update keeps the engine of an existing agent it finds by name
+  Engine:      not set — the cloud agent gets the platform's default
+  Not carried to the cloud: runtime.model, runtime.complexity, handovers
+```
+
+The last line is printed only when the list is non-empty. The warnings:
+
+```
+! cinna-agent.json: 'runtime' is not an object (str) — ignored; the cloud agent gets the platform's default engine.
+! cinna-agent.json: 'runtime.engine' is not a string (int) — ignored; the cloud agent gets the platform's default engine.
+```
+
+Sending `engine` to an older cinna-core is safe: `AccountAgentCreateBody` is a
+plain `SQLModel` with no `extra` setting, so pydantic's default (`ignore`)
+drops the unknown field and the agent is created with the default engine.
+
 Unknown keys are preserved: the dict is mutated and re-dumped, so a manifest
 written by a newer kit survives a round-trip through an older CLI.
 
@@ -91,7 +140,39 @@ hosts read it — Cinna Desktop, cinna-core's `kit.py`, and this CLI — so the
 folder rules are data rather than prose each host re-derives.
 `src/cinna/kit_contract.py` is cinna-cli's reader and the port of the algorithms
 that must stay byte-identical across hosts. `SUPPORTED_CONTRACT_VERSION` names
-the contract version this build implements.
+the contract version this build implements — **1.5.0**. It is the tool half of
+the compatibility pair when no kit sits beside the agent, and it is the version
+named in the `DEGRADED —` `Exclusions:` line.
+
+### Contract 1.5.0 — what changed for this reader
+
+1.5.0 brings the desktop's `runtime.engine`, `runtime.complexity` and
+`handovers[].target_kind` into cinna-core's one manifest schema. Nothing this
+module evaluates changed — `cloud_import_excludes`, `secret_files` and the
+ledger schema are as in 1.4.0. The manifest side is `local_import.py`:
+`runtime.engine` now reaches the platform at creation, and the fields the cloud
+does not carry are printed (see *Manifest handling*).
+
+### Contract 1.4.0 — what changed for this reader
+
+1.4.0 (cloud and local credential delivery) is additive for cinna-cli; the
+cross-repo checks below pass unchanged against cinna-core's 1.4.0 files.
+
+- `cloud_import_excludes` is unchanged in content: `credentials/` was already
+  excluded whole, and the notes now say why (the platform regenerates
+  `credentials/README.md` and feeds it to the cloud prompt). `DEFAULT_EXCLUDE`
+  and `DEFAULT_SECRET_FILE_RULES` equal the 1.4.0 lists.
+- `desktop_owned` shrank to a bare path list (the `contract_keys` block is
+  gone). This module does not read `desktop_owned`, so nothing depends on it.
+- The manifest schema gained an optional `credentials[].service_uri`;
+  `local_import.py:load_manifest()` validates it and
+  `local_import.py:_sync_credentials()` passes it to
+  `client.py:AccountClient.create_credential()`.
+- Credential values for a locally running agent come from cinna-core's
+  `/api/v1/external/credentials` routes (list, and a desktop-only
+  `materialize`), gated per credential by `allow_local_use`. Those are
+  desktop-JWT routes; `POST|PUT /api/v1/cli/account/credentials` do not accept
+  `allow_local_use` yet, so the CLI neither sends nor shows it.
 
 ### Finding it
 
@@ -293,7 +374,9 @@ failure warns and yields no file rather than aborting the import.
   absent + no `--update` → create.
 - **Credentials** — `list_credentials()` keyed by name; an existing name is only
   *attached* (`share_credential_with_agent`), never recreated, so re-runs cannot
-  produce a second empty draft that shadows the filled one.
+  produce a second empty draft that shadows the filled one. Its `service_uri`
+  is not compared or rewritten either — the manifest's slot applies to a new
+  draft only.
 - **Schedules** — `list_schedules()` keyed by name; existing + `--update` →
   `update_schedule`, existing without `--update` → left alone with a notice.
 - **Manifest settle** — `write_manifest()` runs after the confirmation and
@@ -316,7 +399,8 @@ failure warns and yields no file rather than aborting the import.
 
 `--dry-run` returns before the first `AccountClient` is constructed and before
 any local write: it prints the resolved plan (file list, credential drafts,
-schedules, create-vs-update) and stops. The test asserts the patched
+schedules, the `Engine:` and `Not carried to the cloud:` lines,
+create-vs-update) and stops. The test asserts the patched
 `AccountClient` class was never called at all.
 
 ## Tests
@@ -386,4 +470,17 @@ against `publications.schema.json`.
 - `run_agent_sync` is called exactly once when no workspace exists yet;
 - `--no-push` and push-with-conflicts both leave the ledger unwritten;
 - `layout.json` supplying the exclude list while `credentials/` stays excluded;
-- `--workspace` / `--name` threading and verbatim `PlatformError` surfacing.
+- a bad credential `service_uri` refused by `load_manifest()`, and a good one
+  reaching `create_credential()`;
+- `--workspace` / `--name` threading and verbatim `PlatformError` surfacing;
+- contract 1.5.0 runtime: `read_runtime()` over absent, null, blank, unknown and
+  full `runtime` blocks and empty/non-empty `handovers`; the stripped engine
+  reaching `create_agent()`; the default-engine line; a non-object `runtime`
+  and a non-string engine warning without refusing; the exact
+  `Not carried to the cloud:` line on a real run and on `--dry-run`, with no
+  runtime field in the metadata write; `--update` by id and by name match
+  leaving the engine alone and saying so once, and saying nothing when the
+  manifest names no engine.
+
+`tests/test_client.py` asserts `create_agent()` puts `engine` in the body only
+when it is set.

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

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

{cinna_cli-0.4.3 → cinna_cli-0.5.1}/src/cinna/client.py

@@ -318,6 +318,7 @@ class AccountClient:
         name: str,
         description: str | None = None,
         user_workspace_id: str | None = None,
+        engine: str | None = None,
     ) -> dict:
         """POST /api/v1/cli/account/agents — create an agent (thin client).
 
@@ -325,12 +326,20 @@ class AccountClient:
         (AI credentials, env template, environment creation) and returns the
         full agent record. ``user_workspace_id`` targets the account's active
         user workspace (``None`` = Default).
+
+        ``engine`` is a Local Agent Kit ``runtime.engine`` preference
+        (``opencode``, ``claude``, ``codex``, …), sent raw: the backend maps it
+        to the environment's SDK and runs an engine it does not support on
+        OpenCode. It is sent only when set — an older backend ignores the
+        unknown field, so sending it is backward compatible.
         """
         body: dict = {"name": name}
         if description is not None:
             body["description"] = description
         if user_workspace_id is not None:
             body["user_workspace_id"] = user_workspace_id
+        if engine is not None:
+            body["engine"] = engine
         response = self._client.post("/api/v1/cli/account/agents", json=body)
         return self._handle_response(response).json()
 

{cinna_cli-0.4.3 → cinna_cli-0.5.1}/src/cinna/delegation.py

@@ -78,8 +78,13 @@ def _emit_json(result) -> bool:
 
 
 def _parse_artifacts(values: tuple[str, ...]) -> list[dict]:
-    """Each ``--artifact`` must be a JSON object with kind, name and an
-    HTTP(S) ``ref`` — the only kind of reference another agent can open."""
+    """Each ``--artifact`` must be a JSON object with ``kind`` and ``name``.
+
+    A ``link`` needs an HTTP(S) ``ref`` — the only kind of reference another
+    agent can open. A ``file`` may leave ``ref`` out (the Cinna Task Protocol's
+    name-only file artifact, kit contract 1.6.0); when it carries one it must be
+    HTTP(S) too, never a local path.
+    """
     artifacts = []
     for value in values:
         try:
@@ -90,9 +95,10 @@ def _parse_artifacts(values: tuple[str, ...]) -> list[dict]:
             raise click.BadParameter(
                 f"Not a JSON object: {value}", param_hint="--artifact"
             )
+        required = ("kind", "name") if artifact.get("kind") == "file" and "ref" not in artifact else ("kind", "name", "ref")
         missing = [
             key
-            for key in ("kind", "name", "ref")
+            for key in required
             if not isinstance(artifact.get(key), str) or not artifact[key].strip()
         ]
         if missing:
@@ -100,7 +106,7 @@ def _parse_artifacts(values: tuple[str, ...]) -> list[dict]:
                 f"Artifact needs non-empty string {', '.join(missing)}: {value}",
                 param_hint="--artifact",
             )
-        if urlparse(artifact["ref"]).scheme.lower() not in ("http", "https"):
+        if "ref" in artifact and urlparse(artifact["ref"]).scheme.lower() not in ("http", "https"):
             raise click.BadParameter(
                 "Artifact ref must be an http(s) URL (upload local files first): "
                 f"{artifact['ref']}",
@@ -311,7 +317,7 @@ def status(task_id):
 @click.option(
     "--artifact",
     multiple=True,
-    help='JSON object {"kind", "name", "ref"} with an http(s) ref; repeatable.',
+    help='JSON object {"kind", "name", "ref"} with an http(s) ref; a "file" may omit ref; repeatable.',
 )
 @click.option("--body", default="", help="The full result text.")
 def report(task_id, result_status, summary, question, audience, artifact, body):

{cinna_cli-0.4.3 → cinna_cli-0.5.1}/src/cinna/kit_contract.py

@@ -24,7 +24,12 @@ rather than compute it a different way. The safe direction is a property of the
 consequence, not a house style.
 
 Ported from cinna-core's ``docs/local_agent_kit/tools/kit.py``, which is the
-reference implementation, at contract version 1.0.0.
+reference implementation, at contract version 1.0.0; the offline fallbacks below
+are checked against contract 1.5.0. Neither 1.4.0 (cloud and local credential
+delivery — ``credentials/`` was already excluded whole) nor 1.5.0 (the
+``runtime.engine``/``runtime.complexity``/``handovers[].target_kind`` manifest
+fields brought into core's schema, read by :mod:`cinna.local_import`) changed
+anything this module evaluates.
 """
 
 from __future__ import annotations
@@ -54,7 +59,7 @@ CONTRACT_VERSION_FILENAME = "CONTRACT_VERSION"
 
 #: The contract version this CLI implements. Only the MAJOR component is a
 #: compatibility question — see ``check_contract_compatibility``.
-SUPPORTED_CONTRACT_VERSION = "1.0.0"
+SUPPORTED_CONTRACT_VERSION = "1.6.0"
 
 
 # ── Offline fallbacks ───────────────────────────────────────────────────────