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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cinna-cli
-Version: 0.4.3
+Version: 0.5.0
 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.0}/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.0}/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.0}/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.0}/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.0}/pyproject.toml

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

{cinna_cli-0.4.3 → cinna_cli-0.5.0}/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.0}/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.5.0"
 
 
 # ── Offline fallbacks ───────────────────────────────────────────────────────

{cinna_cli-0.4.3 → cinna_cli-0.5.0}/src/cinna/local_import.py

@@ -181,6 +181,16 @@ def load_manifest(source: Path) -> dict:
             raise click.ClickException(
                 f"{MANIFEST_FILENAME}: credential '{cred.get('name')}' needs a 'type'."
             )
+        # Contract 1.4.0: an optional explicit slot. Checked here because the
+        # agent already exists by the time the credential draft is created.
+        service_uri = cred.get("service_uri")
+        if service_uri is not None and (
+            not isinstance(service_uri, str) or not service_uri.strip()
+        ):
+            raise click.ClickException(
+                f"{MANIFEST_FILENAME}: credential '{cred['name']}' has a "
+                f"'service_uri' that is not a non-empty string."
+            )
 
     for sched in _manifest_list(data, "schedules"):
         if not isinstance(sched.get("name"), str) or not sched["name"].strip():
@@ -217,6 +227,67 @@ def _manifest_list(data: dict, key: str) -> list[dict]:
     return value
 
 
+#: ``runtime.*`` keys the contract names that the cloud import does not carry
+#: (contract 1.5.0, ``x-import: ignored``), in the order they are reported.
+#: ``runtime.engine`` is the one runtime field that travels — at creation only.
+_UNCARRIED_RUNTIME_KEYS = ("model", "complexity", "credential", "permissions")
+
+
+def read_runtime(manifest: dict) -> tuple[str | None, list[str]]:
+    """``(engine to send, manifest fields the cloud does not carry)``.
+
+    Read tolerantly, never refused: ``runtime`` is optional and its fields are
+    additive minors, so a malformed value costs a warning and nothing is sent —
+    the cloud agent then gets the platform's default engine.
+
+    The engine is a *preference*, sent stripped and otherwise raw; the backend
+    owns the mapping (``claude`` → Claude Code, anything it does not support →
+    OpenCode). The not-carried list names every field present with a value that
+    this import drops on the floor, so the loss is printed rather than silent:
+    the known ``runtime`` keys, any ``runtime`` key this build does not know,
+    ``handovers`` — whole, because this import never sends a handover at all
+    (naming only ``target_kind`` would imply the rest of one travels) — and
+    ``capabilities``, which the import maps onto nothing.
+    """
+    not_carried: list[str] = []
+    engine: str | None = None
+
+    runtime = manifest.get("runtime")
+    if runtime is not None and not isinstance(runtime, dict):
+        console.warn(
+            f"{MANIFEST_FILENAME}: 'runtime' is not an object "
+            f"({type(runtime).__name__}) — ignored; the cloud agent gets the "
+            f"platform's default engine."
+        )
+    elif isinstance(runtime, dict):
+        raw = runtime.get("engine")
+        if isinstance(raw, str):
+            engine = raw.strip() or None
+        elif raw is not None:
+            console.warn(
+                f"{MANIFEST_FILENAME}: 'runtime.engine' is not a string "
+                f"({type(raw).__name__}) — ignored; the cloud agent gets the "
+                f"platform's default engine."
+            )
+        present = [k for k, v in runtime.items() if k != "engine" and v is not None]
+        not_carried += [f"runtime.{k}" for k in _UNCARRIED_RUNTIME_KEYS if k in present]
+        not_carried += [
+            f"runtime.{k}" for k in sorted(present) if k not in _UNCARRIED_RUNTIME_KEYS
+        ]
+
+    handovers = manifest.get("handovers")
+    if isinstance(handovers, list) and handovers:
+        not_carried.append("handovers")
+
+    capabilities = manifest.get("capabilities")
+    if isinstance(capabilities, dict) and any(
+        v is not None for v in capabilities.values()
+    ):
+        not_carried.append("capabilities")
+
+    return engine, not_carried
+
+
 def _schedule_type(sched: dict) -> str:
     raw = (sched.get("schedule_type") or "static_prompt").strip()
     resolved = _SCHEDULE_TYPE_ALIASES.get(raw)
@@ -676,6 +747,7 @@ def run_agent_import(
     description = manifest.get("description")
     credentials = _manifest_list(manifest, "credentials")
     schedules = _manifest_list(manifest, "schedules")
+    engine, not_carried = read_runtime(manifest)
     contract = load_export_contract(source)
     known_agent_id, known_from = resolve_known_agent_id(
         source, manifest, account_cfg.platform_url
@@ -707,6 +779,12 @@ def run_agent_import(
         )
     _line(f"  Credentials: {len(credentials)} draft(s)")
     _line(f"  Schedules:   {len(schedules)}")
+    # Without a known id, --update decides create-or-reattach only when it
+    # looks the agent up by name, so the plan cannot say which yet.
+    existing = True if known_agent_id else (None if update else False)
+    _line(f"  Engine:      {_engine_line(engine, existing)}")
+    if not_carried:
+        _line(f"  Not carried to the cloud: {', '.join(not_carried)}")
 
     if dry_run:
         console.console.print()
@@ -779,6 +857,7 @@ def run_agent_import(
             known_agent_id=known_agent_id,
             update=update,
             user_workspace_id=user_workspace_id,
+            engine=engine,
         )
         agent_id = agent["id"]
 
@@ -890,11 +969,17 @@ def _resolve_or_create_agent(
     known_agent_id: str | None,
     update: bool,
     user_workspace_id: str | None,
+    engine: str | None = None,
 ) -> dict:
     """Return the cloud agent record, creating it when this is a first import.
 
     Resolution is by id whenever the manifest carries one — a duplicate display
     name on the platform must never make the import write into the wrong agent.
+
+    ``engine`` reaches the platform only on creation. An existing agent keeps
+    its engine: the id-resolved case already said so in the plan. For --update
+    without an id the plan could not know, so the outcome is said here —
+    kept on a name-matched resume, sent when no agent matched.
     """
     if known_agent_id:
         items = client.list_account_agents().get("data", [])
@@ -925,6 +1010,8 @@ def _resolve_or_create_agent(
                 f"  Reusing existing agent {matches[0].get('name')} "
                 f"({matches[0].get('id')})."
             )
+            if engine:
+                _line(f"  Engine:      {_engine_line(engine, existing=True)}")
             return matches[0]
         if len(matches) > 1:
             rows = ", ".join(f"{a['name']} ({a['id']})" for a in matches)
@@ -934,12 +1021,35 @@ def _resolve_or_create_agent(
             )
 
     agent = client.create_agent(
-        agent_name, description, user_workspace_id=user_workspace_id
+        agent_name, description, user_workspace_id=user_workspace_id, engine=engine
     )
     _line(f"  Created agent {agent.get('name')} ({agent.get('id')}).")
+    if update and engine:
+        _line(f"  Engine:      {_engine_line(engine, existing=False)}")
     return agent
 
 
+def _engine_line(engine: str | None, existing: bool | None) -> str:
+    """The ``Engine:`` line's value — what the cloud will do with the preference.
+
+    ``existing`` is ``None`` when that is not known yet: --update without a
+    known id reattaches to an agent matched by name, or creates one.
+    """
+    if engine is None:
+        return "not set — the cloud agent gets the platform's default"
+    if existing is None:
+        return (
+            f"{engine} — sent only if this import creates the agent; "
+            f"--update keeps the engine of an existing agent it finds by name"
+        )
+    if existing:
+        return (
+            f"{engine} — not applied: --update never changes an existing "
+            f"agent's engine"
+        )
+    return f"{engine} — sent as a preference (the cloud runs engines it does not support on OpenCode)"
+
+
 def _write_prompts_and_metadata(
     client: AccountClient, agent_id: str, source: Path, manifest: dict
 ) -> None:

{cinna_cli-0.4.3 → cinna_cli-0.5.0}/tests/test_client.py

@@ -469,3 +469,18 @@ def test_a_bare_coded_body_is_still_a_coded_refusal(account_client):
         account_client.install_skill_on_agent("agent-123", "pkg-uuid")
     assert exc_info.value.code == "already_installed"
     assert "already added" in exc_info.value.detail
+
+
+@respx.mock
+@pytest.mark.parametrize("engine, sent", [(None, False), ("claude", True)])
+def test_create_agent_sends_the_engine_only_when_set(account_client, engine, sent):
+    """An older core ignores an unknown body field; a newer one maps it."""
+    route = respx.post("https://platform.example.com/api/v1/cli/account/agents").respond(
+        200, json={"id": "agent-1", "name": "Invoice Watcher"}
+    )
+
+    account_client.create_agent("Invoice Watcher", engine=engine)
+    body = json.loads(route.calls.last.request.content)
+    assert ("engine" in body) is sent
+    if sent:
+        assert body["engine"] == "claude"