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

package/dist/main.js

@@ -14177,7 +14177,28 @@ var CANVAS_OPERATION_REGISTRY = [
   }),
   write2("insertPromptReference", "Bind one visible image, text, or video View Node and place its platform At token in the Prompt", "silent", {
     properties: {
-      placement: { enum: ["start", "end"], type: "string" },
+      placement: {
+        anyOf: [
+          { enum: ["start", "end"], type: "string" },
+          {
+            additionalProperties: false,
+            properties: {
+              anchor: {
+                additionalProperties: false,
+                properties: {
+                  occurrence: { minimum: 1, type: "integer" },
+                  text: stringSchema()
+                },
+                required: ["text"],
+                type: "object"
+              },
+              kind: { enum: ["before", "after"], type: "string" }
+            },
+            required: ["anchor", "kind"],
+            type: "object"
+          }
+        ]
+      },
       referenceViewNodeId: stringSchema(),
       viewNodeId: stringSchema()
     },
@@ -15068,7 +15089,7 @@ function insertPromptReferenceIntoDraft(draft, definition, reference, sourceData
   const prompt = promptInput.content;
   const token = `{{@${binding.value.sourceDataType}:${binding.slotName}:${binding.index}:${reference.id}|view-node|${encodeURIComponent(reference.viewNodeId)}}}`;
   const content = placement === "start" ? prompt.trim() ? `${token}
-${prompt}` : token : prompt.trim() ? `${prompt}${prompt.endsWith("\n") ? "" : "\n"}${token}` : token;
+${prompt}` : token : placement === "end" ? prompt.trim() ? `${prompt}${prompt.endsWith("\n") ? "" : "\n"}${token}` : token : insertAtPromptAnchor(prompt, token, placement);
   return {
     ...structuredClone(withoutExistingToken),
     inputs: {
@@ -15129,21 +15150,57 @@ function appendPromptReferenceToken(draft, slotName, referenceId, viewNodeId, no
   };
 }
 function removePromptReferenceToken(draft, referenceId) {
-  const pattern = new RegExp(PROMPT_REFERENCE_TOKEN_PATTERN, "g");
   const slots = Object.fromEntries(Object.entries(draft.inputs.slots).map(([slotName, values]) => [
     slotName,
     values.map((value) => {
       if (value.kind !== "literal" || value.assetType !== "text")
         return value;
-      const lines = value.content.split("\n").flatMap((line) => {
-        const content = line.replace(pattern, (token, _type, _slot, _index, bindingId) => bindingId === referenceId ? "" : token);
-        return content.trim() ? [content] : [];
-      });
-      return { ...value, content: lines.join("\n") };
+      return { ...value, content: removeReferenceTokenFromContent(value.content, referenceId) };
     })
   ]));
   return { ...draft, inputs: { slots } };
 }
+function insertAtPromptAnchor(prompt, token, placement) {
+  const anchor = placement.anchor.text;
+  if (!anchor.trim())
+    throw new Error("placement.anchor.text must be non-empty.");
+  const indexes = [];
+  let from2 = 0;
+  while (from2 <= prompt.length - anchor.length) {
+    const index2 = prompt.indexOf(anchor, from2);
+    if (index2 < 0)
+      break;
+    indexes.push(index2);
+    from2 = index2 + Math.max(anchor.length, 1);
+  }
+  if (indexes.length === 0) {
+    throw new Error(`Prompt anchor ${JSON.stringify(anchor)} does not exist.`);
+  }
+  const occurrence = placement.anchor.occurrence;
+  if (occurrence === void 0 && indexes.length !== 1) {
+    throw new Error(`Prompt anchor ${JSON.stringify(anchor)} is ambiguous; placement.anchor.occurrence is required.`);
+  }
+  const index = indexes[(occurrence ?? 1) - 1];
+  if (index === void 0) {
+    throw new Error(`Prompt anchor ${JSON.stringify(anchor)} does not have occurrence ${String(occurrence)}.`);
+  }
+  const insertionIndex = placement.kind === "before" ? index : index + anchor.length;
+  return `${prompt.slice(0, insertionIndex)}${token}${prompt.slice(insertionIndex)}`;
+}
+function removeReferenceTokenFromContent(content, referenceId) {
+  const matches2 = [...content.matchAll(new RegExp(PROMPT_REFERENCE_TOKEN_PATTERN, "g"))].filter((match) => match[4] === referenceId);
+  let next = content;
+  for (const match of matches2.reverse()) {
+    let start = match.index;
+    let end = start + match[0].length;
+    if (start === 0 && next[end] === "\n")
+      end += 1;
+    else if (end === next.length && next[start - 1] === "\n")
+      start -= 1;
+    next = `${next.slice(0, start)}${next.slice(end)}`;
+  }
+  return next;
+}
 function createDefaultSlots(definition) {
   return Object.fromEntries(definition.inputSchema.map((slot) => {
     if (slot.defaultValue === void 0)
@@ -16105,6 +16162,18 @@ var CoreNodeCreativeLoop = class {
     for (const id2 of ids)
       await this.recoverWorkflowRun(id2, timeoutMs);
   }
+  observePendingWorkflowRuns(ids, timeoutMs) {
+    for (const id2 of new Set(ids)) {
+      if (!this.isPending(id2))
+        continue;
+      void this.recoverWorkflowRun(id2, timeoutMs).catch((error51) => {
+        if (isSettlementWriteAttempt(error51))
+          this.context.reportBackgroundError(error51);
+        else
+          this.scheduleWorkflowRunRecovery(id2, timeoutMs, error51);
+      });
+    }
+  }
   close() {
     this.closed = true;
     for (const subscription of this.subscriptions.values())
@@ -16269,9 +16338,7 @@ var CoreNodeCreativeLoop = class {
     const sourceDataType = await this.resolveReferenceDataType(referenceViewNodeId);
     const existing = Object.values(draft.inputs.slots).flat().find((reference) => reference.kind === "view-node" && reference.viewNodeId === referenceViewNodeId);
     const referenceId = existing?.id ?? `input_ref_${crypto.randomUUID().replaceAll("-", "")}`;
-    const placement = input.placement === void 0 ? "end" : input.placement === "start" || input.placement === "end" ? input.placement : null;
-    if (!placement)
-      throw new Error("placement must be start or end.");
+    const placement = parsePromptReferencePlacement(input.placement);
     const nextDraft = insertPromptReferenceIntoDraft(draft, definition, { id: referenceId, kind: "view-node", viewNodeId: referenceViewNodeId }, sourceDataType, placement, this.context.now());
     await this.replaceDraft(target, nextDraft, "Insert Prompt Reference", timeoutMs);
     return attention(target.id, { placement, referenceId, viewNodeId: target.id });
@@ -16921,6 +16988,38 @@ function requireString3(value, field) {
     throw new Error(`${field} must be non-empty.`);
   return value.trim();
 }
+function parsePromptReferencePlacement(value) {
+  if (value === void 0 || value === "end")
+    return "end";
+  if (value === "start")
+    return "start";
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("placement must be start, end, or an anchor placement object.");
+  }
+  const placement = value;
+  assertOnlyKeys3(placement, ["anchor", "kind"]);
+  if (placement.kind !== "before" && placement.kind !== "after") {
+    throw new Error("placement.kind must be before or after.");
+  }
+  if (typeof placement.anchor !== "object" || placement.anchor === null || Array.isArray(placement.anchor)) {
+    throw new Error("placement.anchor must be an object.");
+  }
+  const anchor = placement.anchor;
+  assertOnlyKeys3(anchor, ["occurrence", "text"]);
+  const text = requirePlainString2(anchor.text, "placement.anchor.text");
+  if (!text.trim())
+    throw new Error("placement.anchor.text must be non-empty.");
+  if (anchor.occurrence !== void 0 && (!Number.isInteger(anchor.occurrence) || anchor.occurrence < 1)) {
+    throw new Error("placement.anchor.occurrence must be a positive integer.");
+  }
+  return {
+    anchor: {
+      ...anchor.occurrence === void 0 ? {} : { occurrence: anchor.occurrence },
+      text
+    },
+    kind: placement.kind
+  };
+}
 function requirePlainString2(value, field) {
   if (typeof value !== "string")
     throw new Error(`${field} must be a string.`);
@@ -17384,9 +17483,12 @@ var MediaUploader = class {
     this.systems = systems;
     this.projection = systems.projectContentProjection;
   }
-  async execute(input, timeoutMs) {
+  async execute(input, timeoutMs, onProgress) {
     const request = normalizeUploadRequest(input);
-    const prepared = await this.systems.mediaUpload.prepare(request.source);
+    const safeProgress = safeProgressListener(onProgress);
+    const prepared = await this.systems.mediaUpload.prepare(request.source, {
+      onProgress: safeProgress
+    });
     try {
       const descriptor2 = requireValidDescriptor(prepared.descriptor);
       const intent = await createIntent(request, descriptor2);
@@ -17420,9 +17522,10 @@ var MediaUploader = class {
       let uploaded = false;
       let coreNodeId;
       try {
-        const object2 = await prepared.upload({ timeoutMs });
+        const object2 = await prepared.upload({ onProgress: safeProgress, timeoutMs });
         uploaded = true;
         const fileUrl = requireUploadedMediaUrl(object2.url);
+        await safeProgress({ operation: "uploadMedia", stage: "creating-content" });
         const completion = await this.systems.projectContent.completeMediaUploads(this.context.projectId, [
           {
             asset: {
@@ -17456,6 +17559,7 @@ var MediaUploader = class {
         await this.updateBindingStatus(viewNode, "failed", errorMessage2(error51), timeoutMs);
         throw error51;
       }
+      await safeProgress({ operation: "uploadMedia", stage: "updating-canvas" });
       await this.updateBindingStatus(viewNode, "ready", null, timeoutMs);
       return result2(viewNode.id, coreNodeId, intent, true, uploaded);
     } finally {
@@ -17559,6 +17663,14 @@ var MediaUploader = class {
     return after;
   }
 };
+function safeProgressListener(listener) {
+  return async (progress) => {
+    try {
+      await listener?.(progress);
+    } catch {
+    }
+  };
+}
 var MediaUploadIndeterminateError = class extends Error {
   indeterminate = true;
   timedOut = false;
@@ -18328,6 +18440,8 @@ var SemanticCanvasRuntime = class {
     this.unsubscribeRemote = options.document.subscribeRemoteChange(() => {
       const previous = this.snapshot;
       this.snapshot = options.document.getSnapshot();
+      const previousPending = new Set(previous.pendingWorkflowInstanceIds);
+      const addedPendingWorkflowInstanceIds = this.snapshot.pendingWorkflowInstanceIds.filter((id2) => !previousPending.has(id2));
       const viewNodeChanges = diffSemanticViewNodes(previous.viewNodes, this.snapshot.viewNodes);
       this.projectionRevision += 1;
       this.emit({
@@ -18339,6 +18453,9 @@ var SemanticCanvasRuntime = class {
         revision: this.projectionRevision
       });
       this.scheduleProjectContentRefresh();
+      if (addedPendingWorkflowInstanceIds.length > 0) {
+        this.creativeLoop?.observePendingWorkflowRuns(addedPendingWorkflowInstanceIds, 15e3);
+      }
     });
   }
   get revision() {
@@ -18421,7 +18538,7 @@ var SemanticCanvasRuntime = class {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
   }
-  async execute(name, input, timeoutMs) {
+  async execute(name, input, timeoutMs, options = {}) {
     this.requireCapability(name);
     if (name === "importExternalMedia") {
       if (!this.externalMediaImporter)
@@ -18432,7 +18549,7 @@ var SemanticCanvasRuntime = class {
     if (name === "uploadMedia") {
       if (!this.mediaUploader)
         throw new Error("Media upload system is unavailable.");
-      const result3 = await this.mediaUploader.execute(input, timeoutMs);
+      const result3 = await this.mediaUploader.execute(input, timeoutMs, options.onProgress);
       return { ...result3, revision: this.projectionRevision };
     }
     if (isCreativeLoopOperation(name)) {
@@ -23510,10 +23627,12 @@ var HASH_BUFFER_BYTES = 256 * 1024;
 function createNodeCanvasMediaUploadSystem(config2, cwd = process.cwd()) {
   const backend = new Az8BackendClient(config2);
   return {
-    async prepare(sourceReference) {
+    async prepare(sourceReference, options) {
+      const report = createProgressReporter(options?.onProgress);
+      await report({ bytesCompleted: 0, operation: "uploadMedia", stage: "inspecting" });
       const source = await openUploadSource(sourceReference, cwd);
       try {
-        const descriptor2 = await inspectUploadSource(source.handle, source.absolutePath);
+        const descriptor2 = await inspectUploadSource(source.handle, source.absolutePath, report);
         return createPreparedUpload(config2, backend, source.handle, source.absolutePath, descriptor2);
       } catch (error51) {
         await source.handle.close().catch(() => void 0);
@@ -23547,7 +23666,7 @@ async function openUploadSource(sourceReference, cwd) {
   }
   return { absolutePath, handle };
 }
-async function inspectUploadSource(handle, absolutePath) {
+async function inspectUploadSource(handle, absolutePath, report) {
   const before = await handle.stat();
   if (!Number.isSafeInteger(before.size) || before.size < 1) {
     throw new Error("Media upload source must contain at least one byte.");
@@ -23566,6 +23685,7 @@ async function inspectUploadSource(handle, absolutePath) {
       chunk2.copy(header, bytes, 0, Math.min(chunk2.byteLength, header.byteLength - bytes));
     }
     bytes += bytesRead;
+    await report(uploadProgress("inspecting", bytes, before.size));
   }
   const after = await handle.stat();
   if (after.size !== before.size || after.mtimeMs !== before.mtimeMs) {
@@ -23602,6 +23722,10 @@ function createPreparedUpload(config2, backend, handle, absolutePath, descriptor
       if (closed) throw new Error("Prepared media upload is already closed.");
       if (attempted) throw new Error("Prepared media upload can only be attempted once.");
       attempted = true;
+      await reportProgress(options?.onProgress, {
+        operation: "uploadMedia",
+        stage: "requesting-upload"
+      });
       const presign = await backend.request("core_nodes/upload/presign", {
         json: { format: descriptor2.extension, type: descriptor2.mediaType },
         method: "POST",
@@ -23610,12 +23734,20 @@ function createPreparedUpload(config2, backend, handle, absolutePath, descriptor
       });
       const uploadUrl = requireHttpUrl(presign.upload_url, "upload");
       const fileUrl = requireHttpUrl(presign.file_url, "file");
-      await putPreparedFile(config2, handle, absolutePath, descriptor2, uploadUrl, options?.timeoutMs);
+      await putPreparedFile(
+        config2,
+        handle,
+        absolutePath,
+        descriptor2,
+        uploadUrl,
+        options?.timeoutMs,
+        createProgressReporter(options?.onProgress)
+      );
       return { url: fileUrl };
     }
   };
 }
-async function putPreparedFile(config2, handle, absolutePath, descriptor2, uploadUrl, timeoutMs) {
+async function putPreparedFile(config2, handle, absolutePath, descriptor2, uploadUrl, timeoutMs, report) {
   const originalStat = await handle.stat();
   const uploadHandle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
   let uploadStat;
@@ -23636,11 +23768,15 @@ async function putPreparedFile(config2, handle, absolutePath, descriptor2, uploa
   );
   const hash2 = createHash("sha256");
   let bytes = 0;
+  await report(uploadProgress("uploading", 0, descriptor2.bytes));
   const meter = new Transform({
     transform(chunk2, _encoding, callback) {
       hash2.update(chunk2);
       bytes += chunk2.byteLength;
-      callback(null, chunk2);
+      Promise.resolve(report(uploadProgress("uploading", bytes, descriptor2.bytes))).then(
+        () => callback(null, chunk2),
+        callback
+      );
     }
   });
   const source = uploadHandle.createReadStream({
@@ -23676,6 +23812,35 @@ async function putPreparedFile(config2, handle, absolutePath, descriptor2, uploa
     throw new Error("Media upload source changed before the upload completed.");
   }
 }
+function createProgressReporter(listener) {
+  let lastStage = "";
+  let lastReportedAt = 0;
+  return async (progress) => {
+    if (!listener) return;
+    const now = Date.now();
+    const complete = progress.bytesTotal !== void 0 && progress.bytesCompleted === progress.bytesTotal;
+    const stageChanged = progress.stage !== lastStage;
+    if (!stageChanged && !complete && now - lastReportedAt < 500) return;
+    lastStage = progress.stage;
+    lastReportedAt = now;
+    await reportProgress(listener, progress);
+  };
+}
+async function reportProgress(listener, progress) {
+  try {
+    await listener?.(progress);
+  } catch {
+  }
+}
+function uploadProgress(stage, bytesCompleted, bytesTotal) {
+  return {
+    bytesCompleted,
+    bytesTotal,
+    operation: "uploadMedia",
+    percent: Math.min(100, Math.round(bytesCompleted / bytesTotal * 1e3) / 10),
+    stage
+  };
+}
 function requireHttpUrl(value, kind) {
   if (typeof value !== "string" || !value.trim()) {
     throw new Error(`Media upload presign returned no ${kind} URL.`);
@@ -23744,8 +23909,19 @@ var COLLABORATION_SESSION_STATES = [
 ];
 
 // src/canvas/watch/interest-registry.ts
+var SYSTEM_WORKFLOW_TERMINAL_INTEREST_KEY = "system.workflow-terminal";
 var CollaborationInterestRegistry = class {
   interests = /* @__PURE__ */ new Map();
+  constructor(includeSystemWorkflowTerminal = false) {
+    if (includeSystemWorkflowTerminal) {
+      this.interests.set(SYSTEM_WORKFLOW_TERMINAL_INTEREST_KEY, {
+        filter: { terminalOnly: true },
+        key: SYSTEM_WORKFLOW_TERMINAL_INTEREST_KEY,
+        kind: "workflow",
+        system: true
+      });
+    }
+  }
   patch(input) {
     const upserts = input.upsert ?? [];
     const removals = input.remove ?? [];
@@ -23755,6 +23931,9 @@ var CollaborationInterestRegistry = class {
     for (const entry of upserts) {
       const key = requireKey(entry.key);
       const current = next.get(key);
+      if (current?.system) {
+        throw interestError("system-interest-readonly", `System Interest ${key} cannot be changed.`);
+      }
       if (entry.patch.kind !== void 0 && !isInterestKind(entry.patch.kind)) {
         throw interestError(
           "interest-kind-invalid",
@@ -23775,6 +23954,9 @@ var CollaborationInterestRegistry = class {
     }
     for (const rawKey of removals) {
       const key = requireKey(rawKey);
+      if (next.get(key)?.system) {
+        throw interestError("system-interest-readonly", `System Interest ${key} cannot be removed.`);
+      }
       if (next.delete(key)) changedKeys.push(key);
     }
     this.interests.clear();
@@ -23980,6 +24162,7 @@ function projectWorkflowRun(run, observedAt) {
     status: run.status,
     summary: {
       definitionId: run.definitionId,
+      workflowRunId: run.id,
       ...run.error ? {
         error: {
           ...run.error.code ? { code: run.error.code } : {},
@@ -23989,6 +24172,7 @@ function projectWorkflowRun(run, observedAt) {
       ...run.progress === void 0 ? {} : { progress: run.progress },
       ...run.outputs.length > 0 ? {
         outputs: run.outputs.map((output) => ({
+          coreNodeId: output.coreNodeId,
           role: output.role,
           slotName: output.slotName,
           ...output.viewNodeId ? { viewNodeId: output.viewNodeId } : {}
@@ -24043,7 +24227,7 @@ function safeWorkflowMessage(value) {
 
 // src/canvas/watch/watch.ts
 var AgentCollaborationWatch = class {
-  interests = new CollaborationInterestRegistry();
+  interests;
   maxChangesPerDelivery;
   maxPendingChanges;
   maxRecentResults;
@@ -24054,6 +24238,7 @@ var AgentCollaborationWatch = class {
   activeWait = null;
   continuityLost = false;
   constructor(options = {}) {
+    this.interests = new CollaborationInterestRegistry(options.includeSystemWorkflowTerminal);
     this.maxChangesPerDelivery = positive(
       options.maxChangesPerDelivery ?? 64,
       "maxChangesPerDelivery"
@@ -24289,7 +24474,7 @@ var CanvasSession = class {
     this.projectId = projectId;
     this.dependencies = dependencies;
     this.clientInstanceId = clientInstanceId;
-    this.watch = dependencies.watch ?? new AgentCollaborationWatch();
+    this.watch = dependencies.watch ?? new AgentCollaborationWatch({ includeSystemWorkflowTerminal: true });
     this.health = {
       connectionAttempts: 0,
       connectionId: null,
@@ -24382,6 +24567,9 @@ var CanvasSession = class {
       this.projectionRevision = runtime.revision;
       this.unsubscribeRuntime = runtime.subscribe((observation) => {
         this.projectionRevision = observation.revision;
+        if (observation.workflowRun) {
+          this.knownWorkflowRunIds.add(observation.workflowRun.id);
+        }
         this.watch.recordMany(projectCanvasObservation(observation, Date.now()));
         const legacyObservation = {
           ...observation.changedViewNodeIds ? { changedViewNodeIds: observation.changedViewNodeIds } : {},
@@ -24400,12 +24588,12 @@ var CanvasSession = class {
       throw error51;
     }
   }
-  async execute(name, input, timeoutMs) {
+  async execute(name, input, timeoutMs, options = {}) {
     const runtime = this.requireRuntime();
     if (typeof input.workflowRunId === "string" && input.workflowRunId) {
       this.knownWorkflowRunIds.add(input.workflowRunId);
     }
-    const result3 = await runtime.execute(name, input, timeoutMs);
+    const result3 = await runtime.execute(name, input, timeoutMs, options);
     if (typeof result3.result.workflowRunId === "string" && result3.result.workflowRunId) {
       this.knownWorkflowRunIds.add(result3.result.workflowRunId);
     }
@@ -24654,7 +24842,9 @@ var CanvasClient = class {
     };
     this.receipts.push(receipt);
     try {
-      const operation = await this.session.execute(name, input.input, input.timeoutMs ?? 15e3);
+      const operation = await this.session.execute(name, input.input, input.timeoutMs ?? 15e3, {
+        onProgress: input.onProgress
+      });
       Object.assign(receipt, {
         completedAt: (/* @__PURE__ */ new Date()).toISOString(),
         projectionRevisionAfter: operation.revision,
@@ -24827,7 +25017,7 @@ import { chmod, unlink } from "node:fs/promises";
 import net from "node:net";
 var MAX_RPC_REQUEST_BYTES = 1024 * 1024;
 var MAX_RPC_RESPONSE_BYTES = 16 * 1024 * 1024;
-async function requestAgentSession(socketPath, request, timeoutMs = 5e3, signal) {
+async function requestAgentSession(socketPath, request, timeoutMs = 5e3, signal, onProgress) {
   return new Promise((resolve, reject) => {
     const socket = net.createConnection(socketPath);
     let source = "";
@@ -24857,14 +25047,23 @@ async function requestAgentSession(socketPath, request, timeoutMs = 5e3, signal)
         finish(rpcError("session-rpc-too-large", "Agent Session RPC response is too large."));
         return;
       }
-      const newline = source.indexOf("\n");
-      if (newline < 0) return;
-      try {
-        const response = JSON.parse(source.slice(0, newline));
-        if (!response.ok) finish(rpcError(response.error.code, response.error.message));
-        else finish(void 0, response.value);
-      } catch {
-        finish(rpcError("invalid-session-rpc", "Agent Session RPC response is invalid."));
+      while (!settled) {
+        const newline = source.indexOf("\n");
+        if (newline < 0) return;
+        const line = source.slice(0, newline);
+        source = source.slice(newline + 1);
+        try {
+          const message = JSON.parse(line);
+          if ("type" in message && message.type === "progress") {
+            void Promise.resolve(onProgress?.(message.progress)).catch(() => void 0);
+            continue;
+          }
+          const response = message;
+          if (!response.ok) finish(rpcError(response.error.code, response.error.message));
+          else finish(void 0, response.value);
+        } catch {
+          finish(rpcError("invalid-session-rpc", "Agent Session RPC response is invalid."));
+        }
       }
     });
     socket.once("error", (error51) => finish(error51));
@@ -24903,7 +25102,10 @@ async function listenAgentSessionRpc(socketPath, handler) {
       handled = true;
       try {
         const request = JSON.parse(source.slice(0, newline));
-        const value = await handler(request, { signal: abortController2.signal });
+        const value = await handler(request, {
+          reportProgress: (progress) => writeProgress(socket, progress),
+          signal: abortController2.signal
+        });
         writeResponse(socket, { ok: true, value });
       } catch (error51) {
         writeResponse(
@@ -24935,6 +25137,13 @@ async function listenAgentSessionRpc(socketPath, handler) {
     }
   };
 }
+function writeProgress(socket, progress) {
+  if (socket.destroyed || !socket.writable) return Promise.resolve();
+  return new Promise((resolve) => {
+    socket.write(`${JSON.stringify({ progress, type: "progress" })}
+`, () => resolve());
+  });
+}
 function writeResponse(socket, response) {
   if (socket.destroyed) return;
   socket.end(`${JSON.stringify(response)}
@@ -25339,6 +25548,7 @@ async function startAgentSessionDaemon(spec, dependencies = {}) {
           return await client.executeOperation({
             input: request.input,
             name: request.name,
+            onProgress: context.reportProgress,
             requestId: request.requestId,
             ...request.timeoutMs ? { timeoutMs: request.timeoutMs } : {}
           });
@@ -25347,6 +25557,7 @@ async function startAgentSessionDaemon(spec, dependencies = {}) {
           () => client.executeOperation({
             input: request.input,
             name: request.name,
+            onProgress: context.reportProgress,
             requestId: request.requestId,
             ...request.timeoutMs ? { timeoutMs: request.timeoutMs } : {}
           })
@@ -25795,6 +26006,11 @@ var CanvasProtocolServer = class {
     const outcome = await this.client.executeOperation({
       input: request.payload.input,
       name: request.payload.name,
+      onProgress: (progress) => this.output.emitMandatory({
+        payload: progress,
+        requestId: request.requestId,
+        type: "operationProgress"
+      }),
       requestId: request.requestId,
       ...request.payload.timeoutMs ? { timeoutMs: request.payload.timeoutMs } : {}
     });
@@ -29434,6 +29650,9 @@ async function runCanvasOneShot(config2, command, dependencies = {}) {
       input: command.input,
       name: command.name,
       requestId: command.requestId,
+      ...dependencies.onProgress ? {
+        onProgress: (progress) => dependencies.onProgress?.({ ...progress, requestId: command.requestId })
+      } : {},
       ...command.timeoutMs ? { timeoutMs: command.timeoutMs } : {}
     });
     return operationResult(command, outcome);
@@ -29619,18 +29838,21 @@ function resolveDownloadableCoreNodeMedia(coreNode) {
 
 // src/media/download.ts
 var DEFAULT_RESOLUTION_TIMEOUT_MS = 15e3;
+var DEFAULT_DOWNLOAD_ATTEMPTS = 3;
 var FILE_TYPE_HEADER_BYTES2 = 64 * 1024;
 var MediaDownloadError = class extends Error {
-  constructor(code, message, exitCode, retryable) {
+  constructor(code, message, exitCode, retryable, details = {}) {
     super(message);
     this.code = code;
     this.exitCode = exitCode;
     this.retryable = retryable;
+    this.details = details;
     this.name = "MediaDownloadError";
   }
   code;
   exitCode;
   retryable;
+  details;
 };
 async function runCanvasMediaDownload(config2, command, dependencies = {}) {
   const requestedAbsolutePath = path6.resolve(dependencies.cwd ?? process.cwd(), command.outputPath);
@@ -29645,42 +29867,80 @@ async function runCanvasMediaDownload(config2, command, dependencies = {}) {
   } catch (error51) {
     return failureResult2(command, error51, requestedAbsolutePath);
   }
-  let client;
-  let media;
-  try {
-    client = dependencies.mediaDownloadClientFactory?.(config2, command.projectId) ?? new CanvasClient(config2, command.projectId);
-    try {
-      await client.connect(normalizeCanvasClientName(command.clientName));
-    } catch {
-      throw new MediaDownloadError(
-        "canvas-connection-failed",
-        "Unable to establish a ready Project Canvas context.",
-        2,
-        true
-      );
-    }
-    throwIfCancelled(dependencies.signal);
-    media = await resolveMediaSource(client, command, dependencies.randomUUID);
-  } catch (error51) {
-    return failureResult2(command, error51, outputTarget.absolutePath);
-  } finally {
-    client?.close();
+  const maximumAttempts = dependencies.maxAttempts ?? DEFAULT_DOWNLOAD_ATTEMPTS;
+  if (!Number.isInteger(maximumAttempts) || maximumAttempts < 1 || maximumAttempts > 3) {
+    return failureResult2(
+      command,
+      new MediaDownloadError(
+        "invalid-download-attempts",
+        "Download attempt limit must be between 1 and 3.",
+        1,
+        false,
+        { phase: "setup" }
+      ),
+      outputTarget.absolutePath,
+      0,
+      0
+    );
   }
-  try {
-    const file2 = await transferMedia(config2, media, outputTarget, command, dependencies);
-    return {
-      exitCode: 0,
-      output: {
-        file: file2,
-        format: "az8.canvas.media-download.v1",
-        media: { coreNodeId: media.coreNodeId, mediaType: media.mediaType },
-        projectId: command.projectId,
-        source: command.source
+  const deadlineAt = command.timeoutMs ? Date.now() + command.timeoutMs : null;
+  let lastError;
+  for (let attempt = 1; attempt <= maximumAttempts; attempt += 1) {
+    try {
+      throwIfCancelled(dependencies.signal);
+      const remainingMs = remainingDownloadMs(deadlineAt);
+      const attemptCommand = {
+        ...command,
+        ...remainingMs === void 0 ? {} : { timeoutMs: remainingMs }
+      };
+      const media = await resolveMediaForAttempt(config2, attemptCommand, dependencies);
+      const file2 = await transferMedia(config2, media, outputTarget, attemptCommand, dependencies);
+      return {
+        exitCode: 0,
+        output: {
+          attempts: { completed: attempt, maximum: maximumAttempts },
+          file: file2,
+          format: "az8.canvas.media-download.v1",
+          media: { coreNodeId: media.coreNodeId, mediaType: media.mediaType },
+          projectId: command.projectId,
+          source: command.source
+        }
+      };
+    } catch (error51) {
+      lastError = error51;
+      const failure = normalizeDownloadError(error51);
+      if (!failure.retryable || failure.code === "download-cancelled" || failure.code === "download-timed-out" || attempt === maximumAttempts) {
+        return failureResult2(command, failure, outputTarget.absolutePath, attempt, maximumAttempts);
       }
-    };
-  } catch (error51) {
-    return failureResult2(command, error51, outputTarget.absolutePath);
+      try {
+        await waitForDownloadRetry(
+          downloadRetryDelay(attempt, dependencies.random?.() ?? Math.random()),
+          deadlineAt,
+          dependencies
+        );
+      } catch (retryError) {
+        return failureResult2(
+          command,
+          retryError,
+          outputTarget.absolutePath,
+          attempt,
+          maximumAttempts
+        );
+      }
+    }
   }
+  return failureResult2(
+    command,
+    lastError,
+    outputTarget.absolutePath,
+    maximumAttempts,
+    maximumAttempts
+  );
+}
+function downloadRetryDelay(attempt, random) {
+  const boundedRandom = Number.isFinite(random) ? Math.max(0, Math.min(1, random)) : 0.5;
+  const base = Math.min(250 * 2 ** (attempt - 1), 1e3);
+  return Math.min(1e3, Math.round(base * (0.75 + boundedRandom * 0.5)));
 }
 function formatCanvasMediaDownloadResult(result3) {
   return `${JSON.stringify(result3.output, null, 2)}
@@ -29696,7 +29956,8 @@ async function resolveMediaSource(client, command, randomUUID4) {
         "view-node-media-unavailable",
         safeCanvasMessage(error51),
         1,
-        false
+        false,
+        { cause: sanitizeDownloadCause(error51), phase: "source-resolution" }
       );
     }
   } else {
@@ -29714,7 +29975,8 @@ async function resolveMediaSource(client, command, randomUUID4) {
       "core-node-resolution-failed",
       outcome.receipt.error?.message ?? `Core Node ${coreNodeId} could not be resolved.`,
       indeterminate ? 2 : 1,
-      indeterminate
+      indeterminate,
+      { phase: "core-node-resolution" }
     );
   }
   const coreNode = parseCoreNode(outcome.receipt.result?.coreNode, coreNodeId);
@@ -29733,7 +29995,8 @@ function parseCoreNode(value, expectedId) {
       "core-node-response-invalid",
       `Core Node ${expectedId} returned an invalid record.`,
       2,
-      true
+      true,
+      { phase: "core-node-resolution" }
     );
   }
   const record2 = value;
@@ -29742,7 +30005,8 @@ function parseCoreNode(value, expectedId) {
       "core-node-response-invalid",
       `Core Node ${expectedId} returned an invalid record.`,
       2,
-      true
+      true,
+      { phase: "core-node-resolution" }
     );
   }
   return value;
@@ -29753,7 +30017,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
       "invalid-output-path",
       "Download output path must not be blank.",
       1,
-      false
+      false,
+      { phase: "output-setup" }
     );
   }
   const absolutePath = path6.resolve(cwd, requestedPath);
@@ -29766,7 +30031,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
       "output-parent-unavailable",
       "Download output parent directory does not exist or cannot be accessed.",
       1,
-      false
+      false,
+      { phase: "output-setup" }
     );
   }
   if (!parent.isDirectory()) {
@@ -29774,7 +30040,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
       "output-parent-not-directory",
       "Download output parent is not a directory.",
       1,
-      false
+      false,
+      { phase: "output-setup" }
     );
   }
   let existing;
@@ -29786,7 +30053,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
         "output-target-unavailable",
         "Download output target cannot be inspected.",
         1,
-        false
+        false,
+        { phase: "output-setup" }
       );
     }
   }
@@ -29795,7 +30063,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
       "output-target-exists",
       "Download output target already exists; pass --overwrite to replace a regular file.",
       1,
-      false
+      false,
+      { phase: "output-setup" }
     );
   }
   if (existing && (!existing.isFile() || existing.isSymbolicLink())) {
@@ -29803,7 +30072,8 @@ async function prepareOutputTarget(requestedPath, overwrite, cwd) {
       "output-target-not-regular-file",
       "Download output target must be a regular file and must not be a symbolic link.",
       1,
-      false
+      false,
+      { phase: "output-setup" }
     );
   }
   return { absolutePath, existed: Boolean(existing), parentPath };
@@ -29814,9 +30084,9 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
   let response;
   try {
     response = await config2.fetch(media.url, { redirect: "follow", signal: deadline.signal });
-  } catch {
+  } catch (error51) {
     deadline.cleanup();
-    throw transferFailure(deadline);
+    throw transferFailure(deadline, error51);
   }
   if (!response.ok) {
     deadline.cleanup();
@@ -29825,7 +30095,8 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
       "media-http-error",
       `Media server returned HTTP ${response.status}.`,
       retryable ? 2 : 1,
-      retryable
+      retryable,
+      { phase: "media-transfer" }
     );
   }
   const contentType = normalizeContentType(response.headers.get("content-type"));
@@ -29835,8 +30106,9 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
     throw new MediaDownloadError(
       "media-content-type-mismatch",
       `Media response is ${headerFamily}, but Core Node ${media.coreNodeId} is ${media.mediaType}.`,
-      2,
-      true
+      1,
+      false,
+      { phase: "media-verification" }
     );
   }
   if (contentType === "text/html" || contentType === "application/json") {
@@ -29844,8 +30116,9 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
     throw new MediaDownloadError(
       "media-content-type-mismatch",
       "Media response returned a non-media document.",
-      2,
-      true
+      1,
+      false,
+      { phase: "media-verification" }
     );
   }
   const remoteContentLength = readContentLength(response);
@@ -29878,7 +30151,8 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
         "output-finalize-failed",
         "Temporary download file could not be finalized.",
         1,
-        false
+        false,
+        { phase: "output-finalize" }
       );
     }
     let detected;
@@ -29889,7 +30163,8 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
         "media-verification-failed",
         "Downloaded media could not be inspected safely.",
         1,
-        false
+        false,
+        { phase: "media-verification" }
       );
     }
     validateDownloadedMedia(media, contentType, detected);
@@ -29911,12 +30186,13 @@ async function transferMedia(config2, media, outputTarget, command, dependencies
   } catch (error51) {
     await temporary.handle.close().catch(() => void 0);
     if (error51 instanceof MediaDownloadError) throw error51;
-    if (deadline.signal.aborted) throw transferFailure(deadline);
+    if (deadline.signal.aborted) throw transferFailure(deadline, error51);
     throw new MediaDownloadError(
       "media-download-internal-failed",
       "Media download could not complete its local processing.",
       2,
-      true
+      true,
+      { cause: sanitizeDownloadCause(error51), phase: "media-transfer" }
     );
   } finally {
     deadline.cleanup();
@@ -29967,7 +30243,8 @@ async function streamResponseToFile(response, handle, deadline, expectedBytes) {
       "media-response-body-missing",
       "Media response has no readable body.",
       2,
-      true
+      true,
+      { phase: "media-transfer" }
     );
   }
   const reader = response.body.getReader();
@@ -29985,16 +30262,17 @@ async function streamResponseToFile(response, handle, deadline, expectedBytes) {
     }
   } catch (error51) {
     if (error51 instanceof MediaDownloadError) throw error51;
-    if (deadline.signal.aborted) throw transferFailure(deadline);
+    if (deadline.signal.aborted) throw transferFailure(deadline, error51);
     if (readFsCode2(error51)) {
       throw new MediaDownloadError(
         "output-write-failed",
         "Temporary download file could not be written completely.",
         1,
-        false
+        false,
+        { cause: sanitizeDownloadCause(error51), phase: "output-write" }
       );
     }
-    throw transferFailure(deadline);
+    throw transferFailure(deadline, error51);
   } finally {
     reader.releaseLock();
   }
@@ -30003,7 +30281,8 @@ async function streamResponseToFile(response, handle, deadline, expectedBytes) {
       "media-content-length-mismatch",
       `Media response declared ${expectedBytes} bytes but delivered ${bytes}.`,
       2,
-      true
+      true,
+      { phase: "media-transfer" }
     );
   }
   return { bytes, sha256: hash2.digest("hex") };
@@ -30017,7 +30296,8 @@ async function writeAll(handle, value) {
         "output-write-stalled",
         "Temporary download file stopped accepting data.",
         1,
-        false
+        false,
+        { phase: "output-write" }
       );
     }
     offset += bytesWritten;
@@ -30029,8 +30309,9 @@ function validateDownloadedMedia(media, contentType, detected) {
     throw new MediaDownloadError(
       "media-content-mismatch",
       `Downloaded file is ${detectedFamily}, but Core Node ${media.coreNodeId} is ${media.mediaType}.`,
-      2,
-      true
+      1,
+      false,
+      { phase: "media-verification" }
     );
   }
   const headerMatches = readMediaFamily(contentType) === media.mediaType;
@@ -30039,8 +30320,9 @@ function validateDownloadedMedia(media, contentType, detected) {
     throw new MediaDownloadError(
       "media-content-unverified",
       `Downloaded file could not be verified as ${media.mediaType} media.`,
-      2,
-      true
+      1,
+      false,
+      { phase: "media-verification" }
     );
   }
 }
@@ -30058,14 +30340,16 @@ async function commitTemporaryFile(temporaryPath, outputTarget, overwrite) {
         "output-target-exists",
         "Download output target was created before the download could be committed.",
         1,
-        false
+        false,
+        { phase: "output-commit" }
       );
     }
     throw new MediaDownloadError(
       "output-commit-failed",
       "Verified media could not be committed to the output path.",
       1,
-      false
+      false,
+      { cause: sanitizeDownloadCause(error51), phase: "output-commit" }
     );
   }
 }
@@ -30089,18 +30373,29 @@ function createTransferSignal(external, timeoutMs) {
     signal: controller.signal
   };
 }
-function transferFailure(deadline) {
+function transferFailure(deadline, cause) {
   if (deadline.external?.aborted) {
-    return new MediaDownloadError("download-cancelled", "Media download was cancelled.", 130, true);
+    return new MediaDownloadError(
+      "download-cancelled",
+      "Media download was cancelled.",
+      130,
+      true,
+      {
+        phase: "media-transfer"
+      }
+    );
   }
   if (deadline.isTimedOut()) {
-    return new MediaDownloadError("download-timed-out", "Media download timed out.", 2, true);
+    return new MediaDownloadError("download-timed-out", "Media download timed out.", 2, true, {
+      phase: "media-transfer"
+    });
   }
   return new MediaDownloadError(
     "media-network-failed",
     "Media response could not be downloaded completely.",
     2,
-    true
+    true,
+    { cause: sanitizeDownloadCause(cause), phase: "media-transfer" }
   );
 }
 function throwIfCancelled(signal) {
@@ -30129,23 +30424,111 @@ function readMediaFamily(value) {
   if (value?.startsWith("video/")) return "video";
   return null;
 }
-function failureResult2(command, error51, absolutePath) {
-  const failure = error51 instanceof MediaDownloadError ? error51 : new MediaDownloadError("media-download-failed", safeCanvasMessage(error51), 2, true);
+function failureResult2(command, error51, absolutePath, attemptsCompleted = 1, maximumAttempts = 1) {
+  const failure = normalizeDownloadError(error51);
   return {
     exitCode: failure.exitCode,
     output: {
       error: {
         code: failure.code,
         message: safeCanvasMessage(failure),
-        retryable: failure.retryable
+        ...failure.details.phase ? { phase: failure.details.phase } : {},
+        retryable: failure.retryable,
+        ...failure.details.cause ? { cause: failure.details.cause } : {}
       },
       format: "az8.canvas.media-download.v1",
+      localState: {
+        destinationCommitted: false,
+        partialFileRetained: false
+      },
       outputPath: absolutePath ?? path6.resolve(command.outputPath),
       projectId: command.projectId,
+      attempts: { completed: attemptsCompleted, maximum: maximumAttempts },
+      remoteState: "unverified",
       source: command.source
     }
   };
 }
+async function resolveMediaForAttempt(config2, command, dependencies) {
+  const client = dependencies.mediaDownloadClientFactory?.(config2, command.projectId) ?? new CanvasClient(config2, command.projectId);
+  try {
+    try {
+      await client.connect(normalizeCanvasClientName(command.clientName));
+    } catch (error51) {
+      throw new MediaDownloadError(
+        "canvas-connection-failed",
+        "Unable to establish a ready Project Canvas context.",
+        2,
+        true,
+        { cause: sanitizeDownloadCause(error51), phase: "canvas-connect" }
+      );
+    }
+    throwIfCancelled(dependencies.signal);
+    return await resolveMediaSource(client, command, dependencies.randomUUID);
+  } finally {
+    client.close();
+  }
+}
+function normalizeDownloadError(error51) {
+  return error51 instanceof MediaDownloadError ? error51 : new MediaDownloadError("media-download-failed", safeCanvasMessage(error51), 2, true, {
+    cause: sanitizeDownloadCause(error51),
+    phase: "unknown"
+  });
+}
+function remainingDownloadMs(deadlineAt) {
+  if (deadlineAt === null) return void 0;
+  const remaining = deadlineAt - Date.now();
+  if (remaining < 1) {
+    throw new MediaDownloadError("download-timed-out", "Media download timed out.", 2, true, {
+      phase: "retry-wait"
+    });
+  }
+  return remaining;
+}
+async function waitForDownloadRetry(delayMs, deadlineAt, dependencies) {
+  const remaining = remainingDownloadMs(deadlineAt);
+  if (remaining !== void 0 && remaining <= delayMs) {
+    throw new MediaDownloadError("download-timed-out", "Media download timed out.", 2, true, {
+      phase: "retry-wait"
+    });
+  }
+  await (dependencies.sleep ?? abortableSleep)(delayMs, dependencies.signal);
+  throwIfCancelled(dependencies.signal);
+}
+async function abortableSleep(delayMs, signal) {
+  if (signal?.aborted) return;
+  await new Promise((resolve) => {
+    const timeout = setTimeout(done, delayMs);
+    const onAbort = () => done();
+    function done() {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function sanitizeDownloadCause(error51) {
+  if (!error51 || typeof error51 !== "object") return void 0;
+  const record2 = error51;
+  const cause = record2.cause && typeof record2.cause === "object" ? record2.cause : record2;
+  const message = cause instanceof Error ? cause.message : typeof cause.message === "string" ? cause.message : error51 instanceof Error ? error51.message : void 0;
+  const code = typeof cause.code === "string" || typeof cause.code === "number" ? String(cause.code) : void 0;
+  const closeCode = typeof cause.closeCode === "number" ? cause.closeCode : typeof cause.websocketCloseCode === "number" ? cause.websocketCloseCode : void 0;
+  const closeReason = typeof cause.closeReason === "string" ? cause.closeReason : typeof cause.websocketCloseReason === "string" ? cause.websocketCloseReason : void 0;
+  const sanitizedMessage = message ? sanitizeTransportDetail(message) : void 0;
+  const sanitizedReason = closeReason ? sanitizeTransportDetail(closeReason) : void 0;
+  if (!code && !closeCode && !sanitizedMessage && !sanitizedReason) return void 0;
+  return {
+    ...code ? { code } : {},
+    ...sanitizedMessage ? { message: sanitizedMessage } : {},
+    ...closeCode ? { websocketCloseCode: closeCode } : {},
+    ...sanitizedReason ? { websocketCloseReason: sanitizedReason } : {}
+  };
+}
+function sanitizeTransportDetail(value) {
+  return value.replace(/token=[^\s;&]+/gi, "token=[REDACTED]").replace(/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, "[REDACTED]").replace(/(?:https?|wss?):\/\/[^\s]+/gi, "[REDACTED_URL]");
+}
 function readFsCode2(error51) {
   return typeof error51 === "object" && error51 !== null && "code" in error51 ? String(error51.code) : void 0;
 }
@@ -45064,7 +45447,7 @@ function registerCanvasCommands(program2, dependencies, setResult) {
 // package.json
 var package_default = {
   name: "@everfir/az8-cli",
-  version: "0.3.0-preview.2",
+  version: "0.3.0-preview.3",
   description: "Semantic Project Canvas client for AZ8 Studio agents.",
   license: "UNLICENSED",
   type: "module",
@@ -45427,7 +45810,8 @@ var AgentSessionManager = class {
       descriptor2.socketPath,
       request,
       options.timeoutMs ?? 5e3,
-      options.signal
+      options.signal,
+      options.onProgress
     ).catch((error51) => {
       if (isRemoteFailure(error51)) throw error51;
       throw managerError(
@@ -45795,7 +46179,11 @@ function registerSessionCommands(program2, dependencies, setResult) {
           requestId,
           ...options.timeoutMs ? { timeoutMs: options.timeoutMs } : {}
         },
-        { sessionId: options.session, timeoutMs: (options.timeoutMs ?? 15e3) + 5e3 }
+        {
+          onProgress: (progress) => dependencies.onProgress?.({ ...progress, requestId }),
+          sessionId: options.session,
+          timeoutMs: (options.timeoutMs ?? 15e3) + 5e3
+        }
       );
       const receipt = readOperationReceipt(value);
       const exitCode = receipt.status === "succeeded" ? 0 : receipt.error?.outcome === "indeterminate" ? 2 : 1;
@@ -45999,6 +46387,12 @@ process.once("SIGINT", abortOnSignal);
 process.once("SIGTERM", abortOnSignal);
 try {
   const result3 = await runAz8Cli(process.argv.slice(2), {
+    onProgress(progress) {
+      process.stderr.write(
+        `${JSON.stringify({ format: "az8.operation-progress.v1", ...progress })}
+`
+      );
+    },
     persistentCanvas: runPersistentCanvas,
     signal: abortController.signal
   });