cinna-cli 0.2.2__tar.gz → 0.2.3__tar.gz

{cinna_cli-0.2.2 → cinna_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cinna-cli
-Version: 0.2.2
+Version: 0.2.3
 Summary: Local development CLI for Cinna Core agents
 Project-URL: Homepage, https://github.com/opencinna/cinna-cli
 Project-URL: Repository, https://github.com/opencinna/cinna-cli
@@ -255,6 +255,30 @@ cinna api PATCH agents/3fa85f64-5717-4562-b3fc-2c963f66afa6 --json '{"descriptio
 cinna api POST tasks --data @task.json
 ```
 
+### `cinna chat [--agent <ref>] [--resume <session_id>] [--file PATH ...] [MESSAGE...]`
+
+Talk to an agent through a **real platform session** — the same conversation pipeline production uses (permission checks, agent-env calls, the model/SDK the platform selects), not a local mock. Built for a local coding agent to test the agent it is building: it can prepare a prompt, attach files, and read the reply back as structured data.
+
+Run it from the account workspace (or any synced agent folder under it). The reply is observed by **polling** the backend rather than reading a live stream, so it is robust to streaming/transport quirks.
+
+- `--agent <name|slug|id>` picks the agent; omit it inside a synced agent workspace to infer it. `--resume <session_id>` continues an existing conversation instead of opening a new one (default mode for a new session is `conversation`; `--mode building` opens a building session).
+- The message is the positional argument; if omitted it is read from stdin, or you are prompted for it interactively in a TTY.
+- `--file PATH` (repeatable) uploads a local file and attaches it to the message.
+- Output is **NDJSON** by default — one JSON event per line (`session`, `upload`, `message`, `status`, `done`), trivially parseable by another agent. `--pretty` switches to a human-readable transcript.
+- Each `message` carries the agent's reasoning/tool trace under **`events`** — an ordered list of the `thinking` blocks, `tool` calls (with their full `tool_input` payload) and tool results behind the reply, so you see *what the agent did*, not just its final `content`. Pass `--no-events` to drop the trace and keep only the final text.
+- Files the agent attaches to its replies are downloaded under `./cinna-chat-files/<session_id>/` (override with `--download-dir`, or skip with `--no-download` to just report the file ids). Downloads are bounded by the api-proxy's 8 MiB response cap.
+- `--interval` / `--timeout` tune the poll cadence and the maximum wait for a turn. Ctrl-C interrupts the agent's turn and exits.
+
+```bash
+cinna chat --agent crm-agent "Summarize today's leads"
+cinna chat --agent crm-agent --file report.csv "Validate this export"
+cinna chat --resume 3fa85f64-5717-4562-b3fc-2c963f66afa6 "Now break it down by region"
+echo "ping" | cinna chat --agent crm-agent          # message from stdin
+cinna chat --agent crm-agent "hi" | jq -c 'select(.event=="message")'
+```
+
+The session id is printed in the first `session` event — capture it to drive a multi-turn conversation with `--resume`.
+
 ### `cinna dev`
 
 Start a foreground dev session — creates / resumes the Mutagen sync session for this workspace and attaches the terminal to a two-tab TUI (status + raw Mutagen details). Ctrl-C terminates the session; sync does not outlive the TUI. To observe sync from another terminal without affecting it, use `cinna sync status`.

{cinna_cli-0.2.2 → cinna_cli-0.2.3}/README.md

@@ -218,6 +218,30 @@ cinna api PATCH agents/3fa85f64-5717-4562-b3fc-2c963f66afa6 --json '{"descriptio
 cinna api POST tasks --data @task.json
 ```
 
+### `cinna chat [--agent <ref>] [--resume <session_id>] [--file PATH ...] [MESSAGE...]`
+
+Talk to an agent through a **real platform session** — the same conversation pipeline production uses (permission checks, agent-env calls, the model/SDK the platform selects), not a local mock. Built for a local coding agent to test the agent it is building: it can prepare a prompt, attach files, and read the reply back as structured data.
+
+Run it from the account workspace (or any synced agent folder under it). The reply is observed by **polling** the backend rather than reading a live stream, so it is robust to streaming/transport quirks.
+
+- `--agent <name|slug|id>` picks the agent; omit it inside a synced agent workspace to infer it. `--resume <session_id>` continues an existing conversation instead of opening a new one (default mode for a new session is `conversation`; `--mode building` opens a building session).
+- The message is the positional argument; if omitted it is read from stdin, or you are prompted for it interactively in a TTY.
+- `--file PATH` (repeatable) uploads a local file and attaches it to the message.
+- Output is **NDJSON** by default — one JSON event per line (`session`, `upload`, `message`, `status`, `done`), trivially parseable by another agent. `--pretty` switches to a human-readable transcript.
+- Each `message` carries the agent's reasoning/tool trace under **`events`** — an ordered list of the `thinking` blocks, `tool` calls (with their full `tool_input` payload) and tool results behind the reply, so you see *what the agent did*, not just its final `content`. Pass `--no-events` to drop the trace and keep only the final text.
+- Files the agent attaches to its replies are downloaded under `./cinna-chat-files/<session_id>/` (override with `--download-dir`, or skip with `--no-download` to just report the file ids). Downloads are bounded by the api-proxy's 8 MiB response cap.
+- `--interval` / `--timeout` tune the poll cadence and the maximum wait for a turn. Ctrl-C interrupts the agent's turn and exits.
+
+```bash
+cinna chat --agent crm-agent "Summarize today's leads"
+cinna chat --agent crm-agent --file report.csv "Validate this export"
+cinna chat --resume 3fa85f64-5717-4562-b3fc-2c963f66afa6 "Now break it down by region"
+echo "ping" | cinna chat --agent crm-agent          # message from stdin
+cinna chat --agent crm-agent "hi" | jq -c 'select(.event=="message")'
+```
+
+The session id is printed in the first `session` event — capture it to drive a multi-turn conversation with `--resume`.
+
 ### `cinna dev`
 
 Start a foreground dev session — creates / resumes the Mutagen sync session for this workspace and attaches the terminal to a two-tab TUI (status + raw Mutagen details). Ctrl-C terminates the session; sync does not outlive the TUI. To observe sync from another terminal without affecting it, use `cinna sync status`.

{cinna_cli-0.2.2 → cinna_cli-0.2.3}/docs/README.md

@@ -199,6 +199,7 @@ main.py  (CLI commands — Click)
   ├── bootstrap.py       — setup orchestration
   ├── account.py         — account workspace; `cinna login` (device auth), `cinna account`, `cinna agent`
   ├── doctor.py          — `cinna doctor`: reconcile registry ↔ Mutagen, repair stale state, refresh tokens
+  ├── chat.py            — `cinna chat`: session-backed conversation testing (poll + NDJSON) over the api-proxy
   ├── config.py          — .cinna/config.json: load/save/find
   ├── auth.py            — JWT storage, Authorization headers
   ├── client.py          — PlatformClient: HTTP + SSE stream_exec
@@ -356,6 +357,31 @@ To run an actual remote shell snippet (pipes, redirects, `&&`), pass it explicit
 
 ---
 
+## Remote Chat (`cinna chat`)
+
+`cinna chat` lets a local coding agent **test the agent it is building** by driving a real platform conversation session — exercising the production path (permission checks, agent-env calls, the model/SDK the platform selects) rather than a local mock. It lives in `chat.py` and runs entirely through the **account workspace's api-proxy** (`AccountClient`), so it needs an account workspace (`.cinna/account.json`) — found by walking up from the cwd, exactly like the other account verbs, so it works from a synced `agents/<slug>/` folder too.
+
+### Why polling, not streaming
+
+The platform's send-message route (`POST /sessions/{id}/messages/stream`) returns a **JSON ack immediately** and runs the agent turn asynchronously; the live events go out over a Socket.IO room *and* are persisted onto each message's `message_metadata.streaming_events`. The api-proxy is a buffered JSON hatch (it rejects `text/event-stream`), so `cinna chat` never reads the stream. Instead it:
+
+1. Creates the session (`POST /sessions/`, mode `conversation` by default) — or resumes the one passed to `--resume`.
+2. Uploads each `--file` and collects the returned file ids.
+3. Records the current message count as a cursor, then sends the message (`file_ids` carry the attachments).
+4. **Polls** `GET /sessions/{id}/messages?offset=<cursor>` (messages are ordered ascending by `sequence_number`, so `offset` is the cursor) and `GET …/messages/streaming-status` (`{is_streaming}`) until the turn settles — `is_streaming` false with no message flagged `streaming_in_progress`. A start-grace window covers env wake / queueing before the turn begins; an overall `--timeout` bounds the wait.
+
+Each finalized message is emitted as one NDJSON line (`session` / `upload` / `message` / `status` / `done`); the in-progress assistant message is held back (its content is still growing) and emitted once final. Every `message` also carries the agent's reasoning/tool trace under **`events`** — the normalized `streaming_events` (thinking blocks, `tool` calls with their full `tool_input` payloads, tool results), with the bookkeeping/`attachment` entries stripped (attachments are surfaced separately). The final coalesced text stays in `content`; the trace shows *how* the agent got there. `--no-events` drops the trace; `--pretty` swaps NDJSON for a Rich transcript. Ctrl-C calls `POST …/messages/interrupt` and exits 130.
+
+### Attachments
+
+Agents attach workspace files to replies via `<cinna_attach>` tags; the backend materializes them and both injects an `attachment` streaming event (`metadata.file_id` / `filename` / `mime_type` / `size`) and lists them under the message's `files[]` with `source == "agent_attachment"`. `chat.py` collects attachments from the streaming events (preferred) with the `files[]` list as a replay fallback, dedups by file id, and downloads each via the proxy (`GET /files/{id}/download`) into `./cinna-chat-files/<session_id>/`. Because the proxy buffers the response, downloads are bounded by its **8 MiB** response cap; larger files surface a clear `PlatformError` instead of a partial write.
+
+### File upload — the one dedicated route
+
+The api-proxy is JSON-only and cannot carry a multipart body, and neither the account token nor a per-agent token may call `/files/upload` directly. So uploading a local attachment uses a dedicated account-CLI route, **`POST /api/v1/cli/account/files/upload`** (multipart, account-token auth), added alongside the other `/cli/account/*` routes; it creates a `File` owned by the account user and returns `FileUploadPublic` whose `id` goes into the message's `file_ids`. This is the only part of `cinna chat` that does not ride the api-proxy.
+
+---
+
 ## Bootstrap Flow
 
 ```
@@ -439,8 +465,12 @@ When a CLI token expires (or is revoked) the normal remedy is `cinna set-token <
 | POST | `/api/v1/cli/account/login/start` | None | Begin a `cinna login` device-authorization request |
 | POST | `/api/v1/cli/account/login/poll` | None | Poll a `cinna login` request — always HTTP 200 + `status` |
 | POST | `/api/v1/cli/account/agents/{id}/mint` | Account token | Mint a per-agent CLI token (`cinna agent sync`, `cinna doctor` re-mint) |
+| POST | `/api/v1/cli/account/api-proxy` | Account token | Buffered JSON escape hatch — `cinna api`, and the transport for every `cinna chat` session/message call |
+| POST | `/api/v1/cli/account/files/upload` | Account token | Multipart upload for `cinna chat --file` (the proxy can't carry multipart) |
+
+`cinna chat` reaches the conversation API **through** the api-proxy (so these are inner routes, not CLI routes): `POST /sessions/`, `GET /sessions/{id}`, `GET /sessions/{id}/messages`, `POST /sessions/{id}/messages/stream`, `GET /sessions/{id}/messages/streaming-status`, `POST /sessions/{id}/messages/interrupt`, and `GET /files/{id}/download`.
 
-The account-workspace surface adds the broader `/api/v1/cli/account/*` route group (login, agents, credentials, connect, schedules, status, api-proxy); only the routes the sync / login / doctor paths use are listed here.
+The account-workspace surface adds the broader `/api/v1/cli/account/*` route group (login, agents, credentials, connect, schedules, status, api-proxy, files/upload); only the routes the sync / login / doctor / chat paths use are listed here.
 
 Endpoints that were part of the old Docker-replica model (`build-context`, `workspace` POST, `workspace/manifest`, `credentials`) have been removed from the backend and from this CLI.
 

{cinna_cli-0.2.2 → cinna_cli-0.2.3}/pyproject.toml

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

{cinna_cli-0.2.2 → cinna_cli-0.2.3}/src/cinna/account.py

@@ -732,6 +732,12 @@ def _write_account_claude_md(account_root: Path, config: AccountConfig) -> None:
     )
     (account_root / "CLAUDE.md").write_text(claude_md)
 
+    # Companion testing guide (loaded by the orchestrator only when it tests an
+    # agent via `cinna chat`). Bundled + overwritten, like the orchestrator guide.
+    from cinna.context import write_chat_testing_guide
+
+    write_chat_testing_guide(account_root)
+
 
 def _install_context_package(
     account_cfg: AccountConfig, account_root: Path, *, replace: bool = False
@@ -864,9 +870,10 @@ def run_account_refresh_context() -> None:
 
     The old context tree is only removed after a successful download, so a
     failed refresh leaves the existing context intact (warn-don't-die). The
-    orchestrator `CLAUDE.md` is re-rendered from the bundled template too, so a
-    CLI upgrade's new commands / guidance reach existing account workspaces
-    without a full re-setup.
+    orchestrator `CLAUDE.md` is re-rendered from the bundled template too — and
+    so is every synced agent's per-agent `CLAUDE.md` under `agents/<slug>/` — so
+    a CLI upgrade's new commands / guidance reach existing account workspaces
+    (orchestrator and child agents alike) without a full re-setup.
     """
     account_root = find_account_root()
     account_cfg = load_account_config(account_root)
@@ -888,6 +895,26 @@ def run_account_refresh_context() -> None:
     # account workspaces (auto-generated infra — safe to overwrite).
     _write_account_mcp_config(account_root)
 
+    # Re-render the per-agent CLAUDE.md for every synced child workspace from
+    # the same bundled template — offline (the local-dev guide is a pure
+    # function of the template + the agent's config), so one bad workspace never
+    # aborts the rest. BUILDING_AGENT.md is left untouched (it mirrors the
+    # platform's building prompt and is refreshed on sync, not from a template).
+    from cinna.context import regenerate_claude_md
+
+    refreshed = 0
+    for child, child_cfg in list_child_workspaces(account_root):
+        try:
+            regenerate_claude_md(child_cfg, child)
+            refreshed += 1
+        except Exception as exc:  # one unreadable/locked workspace mustn't abort
+            console.warn(f"Could not regenerate CLAUDE.md for {child.name}: {exc}")
+    if refreshed:
+        console.status(
+            f"Regenerated CLAUDE.md for {refreshed} synced agent "
+            f"workspace{'s' if refreshed != 1 else ''}"
+        )
+
 
 def run_account_agents(show_all: bool = False) -> None:
     """List accessible agents — called by `cinna account agents`.

{cinna_cli-0.2.2 → cinna_cli-0.2.3}/src/cinna/bootstrap.py

@@ -243,6 +243,7 @@ def provision_workspace(
 # `cinna agent unsync`; user workspace files are preserved.
 GENERATED_WORKSPACE_FILES = [
     "CLAUDE.md",
+    "CHAT_TESTING.md",
     "BUILDING_AGENT.md",
     ".mcp.json",
     "opencode.json",