@everfir/az8-cli 0.2.0 → 0.3.0-preview.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everfir/az8-cli",
-  "version": "0.2.0",
+  "version": "0.3.0-preview.2",
   "description": "Semantic Project Canvas client for AZ8 Studio agents.",
   "license": "UNLICENSED",
   "type": "module",
@@ -16,10 +16,10 @@
   "main": "./dist/main.js",
   "publishConfig": {
     "access": "public",
-    "tag": "latest"
+    "tag": "preview"
   },
   "scripts": {
-    "build": "pnpm build:dependencies && rm -rf dist && esbuild src/main.ts --bundle --platform=node --format=esm --target=node20 --banner:js='import { createRequire } from \"node:module\"; const require = createRequire(import.meta.url);' --outfile=dist/main.js",
+    "build": "pnpm build:dependencies && rm -rf dist && esbuild src/main.ts --bundle --platform=node --format=esm --target=node22.12 --banner:js='import { createRequire } from \"node:module\"; const require = createRequire(import.meta.url);' --outfile=dist/main.js",
     "build:dependencies": "pnpm --filter @everfir/az8-cli^... build",
     "dev": "tsx src/main.ts",
     "start": "node dist/main.js",
@@ -48,9 +48,11 @@
     "yjs": "^13.6.30"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12.0"
   },
   "dependencies": {
-    "file-type": "^21.3.4"
+    "commander": "^15.0.0",
+    "file-type": "^21.3.4",
+    "zod": "^4.4.3"
   }
 }

package/skills/az8-cli/SKILL.md

@@ -11,8 +11,9 @@ capabilities instead of guessing operation names or input shapes.
 
 ## Contract
 
-- Use only public `az8 projects` and `az8 canvas` commands. Never mutate backend records, Yjs,
-  Collaborative Document fields, Core Node payloads, or Project Content bindings directly.
+- Use only public `az8 projects`, `az8 session`, and `az8 canvas` commands. Never mutate backend
+  records, Yjs, Collaborative Document fields, Core Node payloads, or Project Content bindings
+  directly.
 - Explicitly select `test` or `production`. Never infer authorization to write production data.
 - Read the relevant Canvas facts before planning a write. Submit one semantic Operation at a time.
 - Treat every accepted write as a blocker: wait for its terminal Receipt before issuing any later
@@ -33,7 +34,13 @@ capabilities instead of guessing operation names or input shapes.
   has its own connection, lifecycle, projection, History, Receipt Log, and Awareness identity.
 - **View Node** is a Canvas placement: note, group, or resource target with position, size, parent,
   stacking, Draft, and presentation state.
-- **Core Node** is immutable or server-owned creative content such as an image, video, or audio.
+- **Note** is a sticky Canvas annotation. Its content uses `createNote` and `editNoteContent`; its
+  optional accent uses `setNoteColor` with only `blue`, `orange`, `red`, `gold`, `purple`, or
+  `green`. A Note is not a Text Resource.
+- **Text Resource** is creative text content. Use `createTextNode` and `editTextContent` for manual
+  text, or `createGenerationTarget` with `contentType: "text"` for generated text. Do not represent
+  requested Text content by creating a Note.
+- **Core Node** is immutable or server-owned creative content such as text, image, video, or audio.
   Resource View Nodes resolve Core Nodes through Project Content. Do not manufacture Core Nodes or
   bindings.
 - **Project Content** is the authority that associates a View Node target with its effective Core
@@ -99,12 +106,22 @@ capabilities instead of guessing operation names or input shapes.
 
    Retain the returned Project ID. Confirm the authenticated role before assuming write access.
 
-4. Discover the effective surface for that Project:
+4. Choose the Canvas carrier before discovery. If the task may perform any Canvas write, open one
+   daemon-backed Agent Collaboration Session now and retain it through the authoring task:
 
    ```bash
-   az8 canvas query <project-id> capabilities.summary
-   az8 canvas query <project-id> capabilities.detail
-   az8 canvas query <project-id> canvas.summary
+   az8 session open <project-id> --environment test
+   az8 session query capabilities.summary
+   az8 session query capabilities.detail
+   az8 session query canvas.summary
+   ```
+
+   For an isolated read-only task, use the process-independent query instead and do not open a
+   Session merely to retain unused state:
+
+   ```bash
+   az8 canvas query <project-id> capabilities.summary --environment test
+   az8 canvas query <project-id> canvas.summary --environment test
    ```
 
    `capabilities.summary` is the short menu. `capabilities.detail` is authoritative for exact JSON
@@ -114,59 +131,82 @@ capabilities instead of guessing operation names or input shapes.
 5. Use `canvas.detail` only when exact node geometry, Draft, status, or bindings are needed:
 
    ```bash
-   az8 canvas query <project-id> canvas.detail --view-node-id <view-node-id>
+   az8 session query canvas.detail --view-node-id <view-node-id>
    ```
 
-6. If the task may perform any Canvas write, open one persistent stdio client before the first
-   Canvas read or write and retain it through the authoring session. Use one-shot only under the
-   explicit exceptions below. Finish by inspecting the affected View Nodes or Workflow Run rather
-   than trusting visual assumptions.
+   For the isolated read-only carrier, use `az8 canvas query <project-id> canvas.detail` with the
+   same selector. Opening a Session selects it for the current canonical working directory, so
+   later Session commands do not repeat its ID. Finish by inspecting affected View Nodes or
+   Workflow Runs, then close any opened Session rather than trusting visual assumptions.
 
 ## Interaction modes
 
-Default to persistent stdio for Canvas authoring. A one-write plan still uses persistent stdio. This
-is the normal mode whenever a task may create, edit, move, organize, remove, undo, generate, import,
-or upload Canvas content. Open the client once, use it for capability discovery and subsequent reads
-and Operations, observe concurrent changes, and shut it down only after the Canvas task is complete:
+Default to a daemon-backed Agent Collaboration Session for Canvas authoring. A one-write plan still
+uses a Session. This is the normal mode whenever a task may create, edit, move, organize, remove,
+undo, generate, import, or upload Canvas content. One private local daemon retains the authenticated
+connection, Awareness, History, Receipts, Interests, and Watch Journal across ordinary short CLI
+calls:
 
 ```bash
-az8 canvas open <project-id> --write --format ndjson
+az8 session open <project-id> --environment test
+az8 session current
+az8 session status
 ```
 
 Use `--client-name <suffix>` only when a more specific CLI presence label helps collaborators. The
 CLI owns the surrounding parentheses, rejects parentheses in the supplied suffix, and always keeps
 the authenticated user display name first.
 
-1. Continuously drain stdout; it is an ordered NDJSON protocol stream and may apply backpressure.
-2. Read `hello`, select protocol `1.0`, then send `initialize` for the same Project ID.
-3. Wait for `ready` before any query or Operation.
-4. Keep exactly one reader for stdout. Parse each frame by `type`, `requestId`, and `streamSeq`.
-5. Use `compact` observations by default. Query `awareness.detail` when cursor context is needed;
-   cursor coordinates are intentionally not streamed.
-6. On an observation gap, query summary/detail and rebuild the local view.
-7. Send `shutdown` and wait for ordered completion. EOF or a signal is emergency cleanup, not a
-   cancellation or rollback mechanism.
-
-Protocol truth is written to stdout. stderr contains diagnostics only. Unknown optional fields are
-additive; ignore them. Do not treat a process exit code as the result of the last persistent request.
-
-Treat the persistent process lifetime and each request lifetime separately:
-
-- Keep the process running between requests. Decide request completion only from the matching
-  `requestId` and its `requestCompleted` or `requestFailed` frame; never wait for process exit.
-- Treat `requestAccepted` as admission only. For a write, wait for its terminal Receipt before
-  issuing the next query or Operation.
-- Continuously drain and parse stdout, but do not repeatedly poll an idle process merely to make it
-  produce output. No new frame is a normal healthy state when no lifecycle, request, Canvas, or
-  Workflow fact changed.
-- Do not interpret a shell/agent-host read window ending with no output (for example, a 30-second
-  terminal yield) as CLI latency, request timeout, or connection failure. Check request terminal
-  frames and lifecycle/health facts instead.
-- Keep one connected client for related work. Reopening one-shot clients repeatedly pays connection,
-  synchronization, and hydration cost each time and loses local History, Receipts, and presence.
-- Remember that the current persistent protocol processes requests serially. A long
-  `waitWorkflowRun` occupies the request lane until the Run becomes terminal or its observation
-  window ends; submit it only when no other request needs that lane.
+Session resolution is explicit and discoverable. A command-level `--session <id>` wins, then
+`AZ8_SESSION_ID`, then the current Session for the local context. Use `AZ8_CONTEXT` to separate
+parallel Agents intentionally sharing one working directory. `session list`, `current`, `status`,
+and `use` must be used whenever the binding is uncertain; never guess a Session or Project.
+
+Configure named semantic Interests once, then use the singular blocking Watch instead of polling:
+
+```bash
+az8 session interests patch --input-json '{"upsert":[{"key":"canvas-ambient","patch":{"kind":"canvas"}},{"key":"workflow-terminal","patch":{"kind":"workflow"}}]}'
+az8 session watch --timeout-ms 30000
+```
+
+- Canvas Interests exclude the Session's own changes unless `includeOwn: true` is explicit.
+- Workflow Interests are terminal-only unless progress status is explicitly requested.
+- `idle` ends one observation window normally. It does not indicate a failed connection or Run.
+- `resync-required` means bounded continuity was lost. Query authoritative summary/detail, then run
+  `az8 session resynchronize`; never pretend the missing interval was observed.
+- Exactly one consumer may wait on a Session. The daemon does not wake or restart an Agent that has
+  exited; it only completes an active `session watch` call.
+- Watch acknowledgement is internal. If stdout delivery is interrupted before confirmation, the
+  same result may repeat. Treat repeat delivery as at-least-once readiness, not a new business fact.
+- Queries wait behind an executing write. Watch collection remains independent of the write lane.
+
+For a bounded human–Agent latency check, report readiness first, start
+`az8 session watch --timeout-ms 60000`, and ask the human to make one recognizable Web Canvas change
+only after the wait is active. Acknowledge the returned semantic change immediately, then wait again
+for the next trial. `result.timing.waitedMs` measures the blocking window and each change's
+`quietForMs` measures local observation-to-delivery delay; neither includes speech recognition or
+Agent-host scheduling. Do not infer an end-to-end latency number from either field alone.
+
+Execute reads and writes through the selected Session:
+
+```bash
+az8 session query canvas.detail --view-node-id <view-node-id>
+az8 session operation createNote --request-id <unique-id> \
+  --input-json '{"name":"Plan","content":"...","position":{"x":80,"y":80}}'
+az8 session query receipt.detail --receipt-request-id <unique-id>
+```
+
+Every Session Operation returns one terminal Receipt. Keep writes sequential and stop after the
+first failed or indeterminate Receipt. Close the Session explicitly when collaboration is complete:
+
+```bash
+az8 session close
+```
+
+`az8 canvas open <project-id> --write --format ndjson` remains the lower-level persistent stdio
+surface for a host that deliberately owns and continuously drains one child process. It has the
+same semantic capabilities, but ordinary Agents should prefer `az8 session` and should not manually
+implement its daemon behavior.
 
 Use one-shot only for:
 
@@ -174,12 +214,12 @@ Use one-shot only for:
 - a standalone media download;
 - an explicitly standalone upload/import whose caller does not want an ongoing authoring session;
 - an explicit user request for one-shot behavior; or
-- a host that genuinely cannot retain a child process and write later NDJSON to its stdin.
+- a platform that cannot run the local Session daemon or persistent stdio carrier.
 
 Do not choose one-shot merely because the current plan has one write or because it requires fewer
-tool calls. Codex and other hosts with retained process sessions can use persistent stdio. If a host
-limitation forces fallback, disclose that the client will not preserve local History, Receipt Log,
-Awareness, observations, or request replay across invocations.
+tool calls. Codex and ordinary shell hosts can use daemon-backed Sessions without retaining stdin.
+If a host limitation forces fallback, disclose that the client will not preserve local History,
+Receipt Log, Awareness, observations, or request replay across invocations.
 
 For a permitted one-shot call, supply Operation input through exactly one of `--input-stdin`,
 `--input-file`, or `--input-json`, give every write a meaningful unique `--request-id`, and retain its
@@ -190,15 +230,24 @@ one-shot processes.
 
 1. Query `canvas.summary`; query selected details only as needed.
 2. Query `capabilities.detail` and validate the planned Operation input against its schema.
-3. Pick explicit absolute Canvas coordinates. Public move positions remain absolute even for group
+3. When artifact type and placement are already clear, make the first meaningful Canvas state
+   visible before doing lengthy prompt refinement or generation planning:
+   - create the empty generation target first, then plan and edit its Draft;
+   - create an empty manual Text Resource with `text: ""`, then fill it with
+     `editTextContent`;
+   - create a Note with its useful content directly rather than creating an empty sticky.
+   Do not create a placeholder while its type or placement is still ambiguous. Watch and the
+   Session daemon never create placeholders automatically.
+4. Pick explicit absolute Canvas coordinates. Public move positions remain absolute even for group
    children.
-4. Submit one Operation with a new request ID and wait for its terminal Receipt.
-5. Confirm the Receipt outcome and affected IDs, then query the changed View Node when subsequent
+5. Submit one Operation with a new request ID and wait for its terminal Receipt.
+6. Confirm the Receipt outcome and affected IDs, then query the changed View Node when subsequent
    work depends on its exact state.
-6. Only then plan the next interaction.
+7. Only then plan the next interaction.
 
-Common capabilities include notes, move/resize/rename, duplicate/remove, groups and stacking, Core
-Node placement, and media targets. The runtime catalog is authoritative. Group nodes cannot nest;
+Common capabilities include notes, manual Text Resources, move/resize/rename, duplicate/remove,
+groups and stacking, Core Node placement, and generation targets. The runtime catalog is
+authoritative. Group nodes cannot nest;
 stacking applies only among siblings. Unsupported World, Decoration, Asset, alignment, and automatic
 layout behavior must not be simulated through lower-level writes.
 
@@ -210,13 +259,30 @@ entries. Never use compensating low-level mutations to imitate undo.
 
 Generation is an explicit sequence, never one transaction:
 
-1. Create a target with `createMediaTarget` and retain its View Node ID.
+1. Create a target with `createGenerationTarget` and retain its View Node ID. It accepts `audio`,
+   `image`, `text`, or `video`; `createMediaTarget` remains a compatibility capability for non-text
+   targets when advertised.
 2. Call the read-only `planGeneration` Operation with the target, prompt, and any references. Use
    `detail: "detail"` when configuration fields or dynamic enum options are needed.
+   Every reference must be `{ "viewNodeId": "..." }`. If the desired Core Node is not currently
+   on the Canvas, first call `placeCoreNode`, wait for its successful Receipt, and use the returned
+   View Node ID. Never pass a Core Node ID as a generation reference or silently choose among
+   multiple placements of the same Core Node. A manual Text Resource is also a valid reference:
+   pass its View Node ID instead of copying its text into `prompt`. Planning reads its current text,
+   the Draft retains the View Node binding for Web lineage and connection rendering, and
+   `startGeneration` materializes the Text Core Node only after estimation succeeds. The stable
+   operation names `addVisualReference` and `removeVisualReference` cover these planned Text
+   bindings as well as image/video bindings; execute the names returned by the plan rather than
+   interpreting them literally.
 3. If the plan reports blocking issues, resolve them and plan again. Do not execute a non-ready
    plan.
 4. Execute `plan.operations` exactly in order, one Operation at a time. Each step revalidates
    current facts. Stop after the first non-success.
+   When a reference must also appear at a meaningful Prompt position, use
+   `insertPromptReference` with the target View Node, visible reference View Node, and
+   `placement: "start"` or `"end"`. The CLI creates and validates the binding and At token
+   atomically. Do not write `{{@...}}`, choose an input slot/index, or allocate a binding ID
+   yourself. `addVisualReference` remains the connection-only operation.
 5. `startGeneration` succeeds when the Workflow Run is accepted and immediate Canvas effects are
    acknowledged. This completes the start interaction; it does not mean generation finished.
 6. Retain the Workflow Run ID. After the successful start Receipt, continue any work that does not
@@ -230,6 +296,19 @@ Generation is an explicit sequence, never one transaction:
 8. On terminal success, query the target detail and resolve its current output Core Node through
    Project Content before downloading or placing it elsewhere.
 
+If `startGeneration` returns an indeterminate Receipt after the Workflow was accepted, retain
+`receipt.result.workflowRunId` and `receipt.result.viewNodeId`, reconnect the Session, and invoke
+`reconcileGenerationStart` with those two identities. Never call `startGeneration` again for that
+intent. `running-insufficient` means the Run is still authoritative but does not yet expose enough
+target evidence: wait and reconcile later. `repaired` means the CLI restored the missing Canvas
+launch facts through the semantic Command path. `conflict` or `insufficient` requires inspection;
+neither authorizes a retry.
+
+A Workflow Interest performs an authoritative status catch-up for Run IDs already known to the
+Session; explicit `filter.runIds` narrows or restores that set when needed. This closes
+missed-live-event races and delivers each unchanged terminal fact once. Keep explicit Run ID filters
+current across handoffs; the daemon does not scan unrelated Workflow Runs.
+
 Workflow Definitions change over time. Query `workflowDefinitions.summary`, then
 `workflowDefinition.detail` only when planning detail is insufficient. Never guess a Definition,
 configuration option, modality, cost, or media compatibility from its display name.
@@ -338,8 +417,8 @@ Before reporting a task complete, verify all applicable facts:
 - Generation start and generation completion were reported as separate interactions; the target's
   effective Core Node was resolved after completion.
 - Media transfers were verified by identities and checksums without exposing URLs or credentials.
-- Persistent stdio was shut down in order, or any abnormal termination and uncertain active write
-  was disclosed.
+- The daemon-backed Session was closed explicitly (or persistent stdio was shut down in order), and
+  any abnormal termination or uncertain active write was disclosed.
 - Deferred scopes were not approximated by bypassing the public semantic surface.
 
 When any item cannot be proven, report the uncertainty and the next safe read or reconciliation