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

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 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

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.4.tgz
+npm install --global ./everfir-az8-cli-0.2.0-preview.5.tgz
 az8 --version
 ```
 
@@ -124,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`.
@@ -216,7 +219,7 @@ Canvas query, keep capability discovery and all ordered Operations in the same l
 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:
@@ -226,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,
@@ -311,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.4.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.4",
+  "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.
 
@@ -131,6 +133,10 @@ and Operations, observe concurrent changes, and shut it down only after the Canv
 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.
@@ -207,7 +213,9 @@ 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
 
@@ -285,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;