@everfir/az8-cli 0.2.0-preview.3 → 0.2.0-preview.5

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable AZ8 CLI changes are recorded here. The CLI package has its own linear version sequence;
 it does not inherit the Web application or monorepo root version.
 
+## 0.2.0-preview.5 - 2026-07-22
+
+### Changed
+
+- Canvas awareness names now preserve the authenticated user's Web-equivalent display name first
+  and append a CLI-owned parenthesized client suffix, defaulting to `(cli)`.
+- `--client-name <suffix>` may override the client suffix for persistent and one-shot lifecycles,
+  but caller-provided parentheses are rejected so presence cannot obscure the name boundary.
+- CLI attention awareness now publishes only the semantic cursor and omits selection bounds.
+- `startGeneration` now carries valid Workflow execution-time estimates into the View Node's
+  generation history as Web-compatible median and maximum completion timestamps.
+
+## 0.2.0-preview.4 - 2026-07-22
+
+### Changed
+
+- Persistent NDJSON stdio is now the default interaction mode for every Canvas authoring task,
+  including a plan containing only one write.
+- One-shot is limited to isolated reads, standalone transfers, explicit caller choice, or hosts that
+  genuinely cannot retain a child process; fewer tool calls alone is not a valid reason to use it.
+- The outer repository Skill now requires preview.4 so a newly triggered agent receives this mode
+  selection policy.
+
 ## 0.2.0-preview.3 - 2026-07-21
 
 ### Changed

package/README.md

@@ -17,7 +17,7 @@ az8 guide
 For a supplied release artifact, install the exact immutable tarball instead:
 
 ```bash
-npm install --global ./everfir-az8-cli-0.2.0-preview.3.tgz
+npm install --global ./everfir-az8-cli-0.2.0-preview.5.tgz
 az8 --version
 ```
 
@@ -108,6 +108,10 @@ the agent can verify identities, byte count, MIME, and SHA-256.
 One-shot commands open a real Canvas client, complete synchronization and hydration, invoke the same
 query or Operation used by the persistent client, and close after the result is authoritative:
 
+Persistent stdio is the default for any Canvas authoring task, including a plan with only one write.
+Use this wrapper only for an isolated read, standalone transfer, explicit one-shot request, or a host
+that cannot retain a child process and write later NDJSON to stdin.
+
 ```bash
 az8 canvas query <project-id> canvas.summary
 az8 canvas query <project-id> canvas.detail --view-node-id <view-node-id>
@@ -120,7 +124,10 @@ az8 canvas operation <project-id> startGeneration \
 Operation input is one JSON object supplied by exactly one of `--input-stdin`, `--input-file`, or
 `--input-json`; omitted input defaults to `{}`. Input is limited to one MiB. `--timeout-ms` controls
 the same Operation acknowledgement or domain observation window as persistent stdio, and
-`--client-name` changes only the ephemeral awareness display name.
+`--client-name` changes only the parenthesized client suffix of the ephemeral awareness name. The
+authenticated display name always remains first: the default is `<current user> (cli)`, while
+`--client-name codex` produces `<current user> (codex)`. Parentheses are owned by the CLI and are
+rejected in caller-provided suffixes.
 
 Success writes one `az8.canvas.one-shot.v1` JSON document to stdout and exits `0`. A definitive
 input, validation, permission, or business failure writes structured JSON to stderr and exits `1`.
@@ -207,8 +214,12 @@ retried. After any non-success, the agent must decide whether a new invocation i
 
 ## Persistent Canvas client
 
+This is the default mode whenever a task may perform any Canvas write. Open it before the first
+Canvas query, keep capability discovery and all ordered Operations in the same lifecycle, and shut
+it down only after the authoring task is complete.
+
 ```bash
-az8 canvas open <project-id> --write --format ndjson
+az8 canvas open <project-id> --write --format ndjson [--client-name codex]
 ```
 
 The process writes one `hello` frame, then waits for an `initialize` request on stdin:
@@ -218,9 +229,12 @@ The process writes one `hello` frame, then waits for an `initialize` request on
 ```
 
 Before readiness the client hydrates the current authenticated account profile. Canvas Operations use
-that immutable account id and display name for persisted creator data. The `client.name` supplied by
-`initialize` is awareness-only and cannot impersonate or rename the persisted author. Project owner
-metadata is likewise never treated as the current actor on shared Projects.
+that immutable account id and display name for persisted creator data. Awareness always displays the
+authenticated name first and a CLI-owned parenthesized client suffix second. The default suffix is
+`cli`; startup `--client-name` overrides it, otherwise `initialize.client.name` may provide it.
+Caller suffixes cannot contain parentheses. This name is awareness-only and cannot impersonate or
+rename the persisted author. The CLI publishes its Attention Cursor but deliberately omits selection
+bounds. Project owner metadata is likewise never treated as the current actor on shared Projects.
 
 After `ready`, requests use `query`, `configureObservations`, `operation`, `reconnect`, or `shutdown`.
 The public authoring surface includes the note lifecycle, non-World View Node hierarchy operations,
@@ -303,6 +317,9 @@ explicitly submitting the same input. An uncertain backend or collaboration outc
 are acknowledged. It first estimates the exact current Draft inputs, then materializes literal Core
 Nodes and starts with the estimate's cost and Definition version. This estimate is internal: there is
 no public estimate Operation, balance query, caller-supplied expected cost, or second confirmation.
+When the estimate includes execution-time ranges, the generation history records Web-compatible
+median and maximum completion timestamps from the pre-submit time so Web can render the same expected
+generation duration for a CLI-started Run.
 Waiting for a terminal result is deliberately a separate operation. Generation is a non-undoable
 Canvas History barrier. The CLI does not expose Assets, arbitrary Core Node creation, or 3D World
 operations.

package/RELEASE.md

@@ -35,7 +35,7 @@ repository-wide `pnpm verify`. Publishing is an external action and requires exp
 authorization:
 
 ```bash
-npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0-preview.3.tgz --tag preview
+npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0-preview.5.tgz --tag preview
 npm view @everfir/az8-cli dist-tags versions --json
 ```
 

package/dist/main.js

@@ -4527,6 +4527,27 @@ var require_src2 = __commonJS({
   }
 });
 
+// src/canvas-awareness.ts
+var DEFAULT_CANVAS_CLIENT_NAME = "cli";
+function normalizeCanvasClientName(value) {
+  const name = (value ?? DEFAULT_CANVAS_CLIENT_NAME).trim();
+  if (!name) {
+    throw invalidClientName("Canvas client name must not be empty.");
+  }
+  if (/[()]/.test(name)) {
+    throw invalidClientName(
+      "Canvas client name must not contain parentheses; AZ8 adds the required (name) suffix."
+    );
+  }
+  return name;
+}
+function formatCanvasAwarenessName(actorDisplayName, clientName) {
+  return `${actorDisplayName} (${normalizeCanvasClientName(clientName)})`;
+}
+function invalidClientName(message) {
+  return Object.assign(new Error(message), { code: "invalid-client-name" });
+}
+
 // ../../node_modules/.pnpm/lib0@0.2.117/node_modules/lib0/math.js
 var floor = Math.floor;
 var abs = Math.abs;
@@ -22727,9 +22748,26 @@ function mapWorkflowRunEstimate(value, definitionId) {
     canAfford: value.can_afford,
     definitionId: value.definition_id,
     definitionVersion: value.definition_version,
-    estimatedCost: value.estimated_cost
+    estimatedCost: value.estimated_cost,
+    executionTimeRanges: (value.execution_time_ranges ?? []).flatMap((item) => {
+      const range = item.range;
+      if (!range || !isNonNegativeFinite(range.minSeconds) || !isNonNegativeFinite(range.maxSeconds) || !isNonNegativeFinite(range.medianSeconds) || !isNonNegativeFinite(range.sampleCount)) {
+        return [];
+      }
+      return [
+        {
+          maxSeconds: range.maxSeconds,
+          medianSeconds: range.medianSeconds,
+          minSeconds: range.minSeconds,
+          sampleCount: range.sampleCount
+        }
+      ];
+    })
   };
 }
+function isNonNegativeFinite(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
 function mapWorkflowDefinition(value) {
   if (!value.id || !value.name || typeof value.version !== "number") {
     throw new Error("Workflow Runtime returned an invalid Definition.");
@@ -22903,7 +22941,8 @@ var CanvasSession = class {
   projectionRevision = 0;
   actorId = null;
   health;
-  async connect(displayName, onState) {
+  async connect(clientName, onState) {
+    const normalizedClientName = normalizeCanvasClientName(clientName);
     this.closeContext();
     this.transition("authenticating", onState);
     this.health.connectionAttempts += 1;
@@ -22927,7 +22966,10 @@ var CanvasSession = class {
     });
     this.document = document2;
     try {
-      document2.setIdentity({ accountId: actor.accountId, displayName });
+      document2.setIdentity({
+        accountId: actor.accountId,
+        displayName: formatCanvasAwarenessName(actor.displayName, normalizedClientName)
+      });
       this.transition("hydrating", onState);
       const foundationData = this.dependencies.foundationData ?? createAz8FoundationDataSystem(this.config);
       const projectContent = this.dependencies.projectContent ?? createAz8ProjectContentSystem(this.config);
@@ -23037,8 +23079,7 @@ var CanvasSession = class {
   }
   publishAttentionBounds(bounds) {
     this.requireDocument().setAttention({
-      cursor: { x: bounds.x + bounds.width + 24, y: bounds.y + bounds.height / 2 },
-      selection: bounds
+      cursor: { x: bounds.x + bounds.width + 24, y: bounds.y + bounds.height / 2 }
     });
   }
   closeContext() {
@@ -23379,18 +23420,20 @@ function requirePositiveInteger(value, field) {
 
 // src/canvas-protocol-server.ts
 var CanvasProtocolServer = class {
-  constructor(config, projectId, output, session) {
+  constructor(config, projectId, output, session, options = {}) {
     this.projectId = projectId;
     this.output = output;
+    this.options = options;
     this.client = new CanvasClient(config, projectId, session);
   }
   projectId;
   output;
+  options;
   client;
   initialized = false;
   shuttingDown = false;
   shutdownFinalized = false;
-  displayName = "AZ8 CLI";
+  clientName = "cli";
   observationPreset = "compact";
   observationInclude = /* @__PURE__ */ new Set();
   recordedRequests = /* @__PURE__ */ new Map();
@@ -23533,8 +23576,11 @@ var CanvasProtocolServer = class {
         "initialize projectId does not match canvas open."
       );
     }
+    const clientName = normalizeCanvasClientName(
+      this.options.clientName ?? request.payload.client?.name
+    );
     this.initialized = true;
-    this.displayName = request.payload.client?.name ?? "AZ8 CLI";
+    this.clientName = clientName;
     this.observationPreset = request.payload.observationPreset ?? "compact";
     this.unsubscribeObservation = this.session.subscribe((observation) => {
       const category = observation.kind === "workflow" ? "workflow" : "canvas";
@@ -23558,7 +23604,7 @@ var CanvasProtocolServer = class {
   }
   async connect(requestId) {
     try {
-      await this.client.connect(this.displayName, (state) => {
+      await this.client.connect(this.clientName, (state) => {
         void this.output.emitMandatory({ payload: { state }, requestId, type: "lifecycle" });
       });
     } catch (error) {
@@ -23936,7 +23982,7 @@ async function runCanvasOneShot(config, command, dependencies = {}) {
   try {
     assertProcessIndependent(command);
     client = dependencies.clientFactory?.(config, command.projectId) ?? new CanvasClient(config, command.projectId);
-    await client.connect(command.clientName ?? "AZ8 CLI one-shot");
+    await client.connect(normalizeCanvasClientName(command.clientName));
     if (command.kind === "query") {
       return {
         exitCode: 0,
@@ -24159,7 +24205,7 @@ async function runCanvasMediaDownload(config, command, dependencies = {}) {
   try {
     client = dependencies.mediaDownloadClientFactory?.(config, command.projectId) ?? new CanvasClient(config, command.projectId);
     try {
-      await client.connect(command.clientName ?? "AZ8 CLI media download");
+      await client.connect(normalizeCanvasClientName(command.clientName));
     } catch {
       throw new MediaDownloadError(
         "canvas-connection-failed",
@@ -25029,7 +25075,7 @@ function projectHelpOutput() {
 function canvasHelpOutput() {
   return [
     "Canvas:",
-    "  az8 canvas open <project-id> --write --format ndjson",
+    "  az8 canvas open <project-id> --write --format ndjson [--client-name <suffix>]",
     "  az8 canvas inspect <project-id>    Print the latest persisted snapshot as JSON",
     "  az8 canvas upload <project-id> --file <path> --idempotency-key <key>",
     "  az8 canvas download <project-id> (--view-node-id <id> | --core-node-id <id>) --output <path>",
@@ -25042,7 +25088,7 @@ function canvasHelpOutput() {
     "  --input-json <json>              Read one inline JSON object",
     "  --request-id <id>                Set the Operation Receipt request ID",
     "  --timeout-ms <ms>                Set the operation acknowledgement timeout",
-    "  --client-name <name>             Set the ephemeral awareness display name",
+    "  --client-name <suffix>           Set the parenthesized awareness client suffix",
     "",
     "One-shot query options:",
     "  --view-node-id <id>              Select one View Node for canvas.detail",
@@ -25235,7 +25281,15 @@ async function runPersistentCanvas(args2) {
   });
   try {
     const config = await resolveCliConfig(args2, {});
-    server = new CanvasProtocolServer(config, projectId, output);
+    const requestedClientName = readOption3(args2, "--client-name");
+    const clientName = requestedClientName ? normalizeCanvasClientName(requestedClientName) : void 0;
+    server = new CanvasProtocolServer(
+      config,
+      projectId,
+      output,
+      void 0,
+      clientName ? { clientName } : {}
+    );
     const shutdownOnSignal = (signal) => {
       void server?.shutdownFromControl(signal.toLowerCase()).finally(() => process.stdin.destroy());
     };
@@ -25252,7 +25306,10 @@ async function runPersistentCanvas(args2) {
 }
 function readOption3(args2, name) {
   const index = args2.indexOf(name);
-  return index >= 0 ? args2[index + 1] : void 0;
+  if (index < 0) return void 0;
+  const value = args2[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${name} requires a value.`);
+  return value;
 }
 function safeDiagnostic(error) {
   const message = error instanceof Error ? error.message : "Persistent Canvas client failed.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everfir/az8-cli",
-  "version": "0.2.0-preview.3",
+  "version": "0.2.0-preview.5",
   "description": "Semantic Project Canvas client for AZ8 Studio agents.",
   "license": "UNLICENSED",
   "type": "module",

package/skills/az8-cli/SKILL.md

@@ -46,8 +46,10 @@ capabilities instead of guessing operation names or input shapes.
   outcome, revisions, and optional usage. It is not Canvas History.
 - **History** contains reversible local interactions. Only Operations advertised as `undoable`
   participate. A generation start is a History barrier and is not undone by `undo`.
-- **Awareness** is ephemeral presence, client name, and Attention Cursor information. It never
-  grants authority, changes persisted authorship, or proves a business result.
+- **Awareness** is ephemeral presence, client suffix, and Attention Cursor information. The visible
+  name is always `<authenticated display name> (<client suffix>)`; the default suffix is `cli`.
+  CLI awareness does not publish selection bounds. Awareness never grants authority, changes
+  persisted authorship, or proves a business result.
 - **Actor** is the authenticated account from `AZ8_TOKEN`. A client or awareness name cannot
   impersonate another author.
 
@@ -115,31 +117,26 @@ capabilities instead of guessing operation names or input shapes.
    az8 canvas query <project-id> canvas.detail --view-node-id <view-node-id>
    ```
 
-6. Choose one-shot for independent tasks and persistent stdio for a collaborative session. Finish
-   by inspecting the affected View Nodes or Workflow Run rather than trusting visual assumptions.
+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.
 
 ## Interaction modes
 
-Use one-shot commands for a self-contained query, write, upload, or download:
-
-```bash
-printf '%s\n' '{"text":"Idea","position":{"x":160,"y":160}}' |
-  az8 canvas operation <project-id> createNote --input-stdin --request-id create-note-1
-```
-
-- Supply Operation input through exactly one of `--input-stdin`, `--input-file`, or `--input-json`.
-- Give every write attempt a meaningful unique `--request-id` and retain its returned Receipt.
-- Each invocation opens, hydrates, executes, and closes a real Canvas client.
-- One-shot processes do not preserve local History, Receipt Log, Awareness, or request replay.
-  Therefore `undo`, `redo`, `receipts.summary`, and `receipt.detail` require persistent stdio.
-
-Use persistent stdio when multiple ordered interactions, live synchronization, History, Receipt
-lookup, observations, or human collaboration matter:
+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:
 
 ```bash
 az8 canvas open <project-id> --write --format ndjson
 ```
 
+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.
@@ -153,6 +150,24 @@ az8 canvas open <project-id> --write --format ndjson
 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.
 
+Use one-shot only for:
+
+- an isolated read when no Canvas write is planned;
+- 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.
+
+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.
+
+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
+returned Receipt. `undo`, `redo`, `receipts.summary`, and `receipt.detail` are never available across
+one-shot processes.
+
 ## Canvas SOP
 
 1. Query `canvas.summary`; query selected details only as needed.
@@ -198,11 +213,15 @@ configuration option, modality, cost, or media compatibility from its display na
 
 The start Receipt may report `usage.credits.status` as `estimated`, `not-consumed`, or `unknown`.
 Estimated cost is informational, not final charged usage. There is no second confirmation. Never
-claim actual credit consumption from an estimate.
+claim actual credit consumption from an estimate. When timing data is available, `startGeneration`
+also records the same median and maximum completion timestamps Web uses to display expected duration;
+these timestamps remain estimates and do not change the Run's completion boundary.
 
 ## Media
 
-For a local image, video, or audio file, use the semantic upload wrapper:
+Within an active persistent authoring session, invoke the discovered `uploadMedia` Operation so the
+write shares that client lifecycle. For an explicitly standalone local image, video, or audio
+transfer, use the semantic one-shot upload wrapper:
 
 ```bash
 az8 canvas upload <project-id> \
@@ -274,8 +293,8 @@ Never:
   or protocol payloads;
 - inspect, print, or edit an operator-provisioned credential source merely to check whether it
   exists; authenticate with a bounded read instead;
-- use awareness client names to impersonate persisted authors or treat Attention Cursor position as
-  authority;
+- use awareness client suffixes to impersonate persisted authors, supply parentheses to obscure the
+  authenticated-name boundary, or treat Attention Cursor position as authority;
 - use one-shot as if it retained History, Receipts, replay state, observations, or presence;
 - attempt Asset membership, arbitrary Core Node creation, 3D World editing, unsupported
   Decoration, alignment, or automatic layout through lower-level access;