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

package/CHANGELOG.md

@@ -5,6 +5,30 @@ it does not inherit the Web application or monorepo root version.
 
 ## Unreleased
 
+## 0.3.0-preview.3 - 2026-07-23
+
+### Added
+
+- Every collaborative Session receives discoverable Workflow terminal events by default, including
+  the Workflow Run, target View Node, and output Core Node identities.
+- Prompt references can be inserted before or after an exact text occurrence without exposing raw
+  Canvas data.
+- Media uploads report structured stage, byte, and percentage progress across one-shot, persistent
+  stdio, and daemon-backed Session transports.
+
+### Changed
+
+- Media downloads use bounded read-only retries under one caller deadline, clean partial files, and
+  return structured, credential-safe transport diagnostics when recovery fails.
+- The built-in agent Skill prioritizes a single foreground `session watch` call, warns against
+  background polling loops, and documents terminal reconciliation and exact Prompt placement.
+
+### Safety and compatibility
+
+- User Workflow Interests remain additive and cannot disable the system terminal stream.
+- Download retries never extend the caller deadline or apply to definitive verification failures.
+- Upload progress is provisional observability and cannot change the semantic Operation result.
+
 ## 0.3.0-preview.2 - 2026-07-23
 
 ### Added

package/README.md

@@ -18,7 +18,7 @@ az8 guide
 For a supplied preview artifact, install the exact immutable tarball instead:
 
 ```bash
-npm install --global ./everfir-az8-cli-0.3.0-preview.2.tgz
+npm install --global ./everfir-az8-cli-0.3.0-preview.3.tgz
 az8 --version
 ```
 
@@ -114,12 +114,13 @@ az8 session query canvas.summary
 
 The Session remains selected for the current canonical working directory, so subsequent commands do
 not repeat its ID. Use `session current`, `list`, and `status` rather than guessing which Project or
-daemon is active. Configure semantic Interests and block on one Watch call when collaboration
-updates matter:
+daemon is active. The visible, read-only `system.workflow-terminal` Interest automatically retains
+terminal facts for locally started and remotely discovered pending Runs. Configure only additional
+semantic Interests and block on one Watch call when collaboration updates matter:
 
 ```bash
 az8 session interests patch \
-  --input-json '{"upsert":[{"key":"canvas-ambient","patch":{"kind":"canvas"}},{"key":"workflow-terminal","patch":{"kind":"workflow"}}]}'
+  --input-json '{"upsert":[{"key":"canvas-ambient","patch":{"kind":"canvas"}}]}'
 az8 session watch --timeout-ms 30000
 az8 session close
 ```
@@ -127,6 +128,9 @@ az8 session close
 `watch` returning `idle` is a successful empty observation window, not a connection error. Exactly
 one caller may wait on a Session. The daemon retains the authenticated connection and collaboration
 state between short CLI invocations, but it does not wake or restart an Agent that has exited.
+Agents should call exactly one Watch in the foreground whenever waiting is useful, process the
+result, then call it once again if needed. Do not build a shell loop, background Watch, or polling
+substitute; those add scheduling delay and can consume an event before the Agent reasons about it.
 
 For a manual human–Agent interaction latency check, have the Agent report that it is ready, start
 one 60-second Watch, and only then make one recognizable Canvas change from Web:
@@ -149,7 +153,9 @@ call `planGeneration` with the returned View Node and a prompt. Execute its retu
 `plan.operations` in order, stopping after the first failure. A
 successful `startGeneration` Receipt contains the Workflow Run identity; call `waitWorkflowRun`
 separately when a terminal output is required. Planning and starting are intentionally not one
-transaction.
+transaction. In an active Session, prefer one foreground `session watch`: the system terminal event
+includes Workflow Run, target View Node, and output Core Node identities when supplied by Workflow
+Runtime.
 
 For media transfer, `canvas upload` places a verified local image/video/audio file through the
 server-owned Core Node path. After detail query resolves the target's `resolvedCoreNodeId`, `canvas
@@ -232,8 +238,10 @@ Project Content through a deterministic, opaque intent fingerprint in its source
 existing binding returns without another upload, while conflicting key reuse fails. Results include
 View Node/Core Node identities and reproducible file metadata but never the presigned or permanent
 file URL. The wrapper uses the standard `az8.canvas.one-shot.v1` output and exit codes and defaults
-to a 300-second deadline. Batch upload, replacement, text-file import, and a durable local upload
-cache are outside the initial slice.
+to a 300-second deadline. Uploads emit rate-limited `az8.operation-progress.v1` lines to stderr for
+`inspecting`, `requesting-upload`, `uploading`, `creating-content`, and `updating-canvas`; final
+stdout remains one structured result and only its Receipt is authoritative. Batch upload,
+replacement, text-file import, and a durable local upload cache are outside the initial slice.
 
 ## Local media download
 
@@ -262,8 +270,12 @@ Success writes one `az8.canvas.media-download.v1` document with the absolute pat
 SHA-256, detected MIME/extension, response metadata, resolved Core Node identity, and whether a file
 was replaced. It deliberately omits the media URL. Exit `0` is success; exit `1` is a definitive
 source, HTTP 4xx, or local-path failure; exit `2` is a retryable connection, HTTP 429/5xx, transfer,
-integrity, or timeout failure; exit `130` is caller cancellation. Downloads are never automatically
-retried. After any non-success, the agent must decide whether a new invocation is safe.
+or timeout failure; exit `130` is caller cancellation. Retryable read/transfer phases are
+automatically attempted at most three times under the original deadline; every attempt re-resolves
+the source and leaves no partial destination. Definitive failures, verification mismatch, timeout,
+and cancellation are not retried. Failure output includes attempts, phase, retryability, sanitized
+cause when available, local commit state, and remote-state certainty. After non-success, the agent
+must use those facts to decide whether a new invocation is safe.
 
 ## Lower-level persistent stdio client
 
@@ -323,6 +335,12 @@ creates the Text Core Node only after the estimate succeeds. The published opera
 `addVisualReference` and `removeVisualReference` are retained for compatibility and also carry these
 planned Text bindings.
 
+`insertPromptReference` additionally places the platform-owned At token at `start`, `end`, or
+before/after an exact text anchor such as
+`{"kind":"after","anchor":{"text":"豆豆","occurrence":2}}`. Occurrence is one-based and is optional
+only for a unique anchor. Missing or ambiguous anchors fail without writing. Callers never construct
+At syntax, binding IDs, or slot indexes.
+
 ```json
 {"protocolVersion":"1.0","requestId":"plan-1","type":"operation","payload":{"name":"planGeneration","input":{"targetViewNodeId":"<target-id>","prompt":"A quiet observatory","references":[{"viewNodeId":"<reference-id>"}],"detail":"detail"}}}
 ```

package/RELEASE.md

@@ -60,7 +60,7 @@ authorization:
 For a preview candidate, publish the exact retained artifact to the preview channel:
 
 ```bash
-npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.3.0-preview.2.tgz --tag preview
+npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.3.0-preview.3.tgz --tag preview
 npm view @everfir/az8-cli dist-tags versions --json
 ```