@stigmer/react 3.1.16 → 3.2.0

package/src/execution/agent-execution-document.ts

@@ -0,0 +1,54 @@
+// Identity of agent-execution transcript tabs in the workspace surface's
+// editor group. Domain: execution (the transcript renderer and the
+// AgentExecution data model are execution-domain; the workflow panel is the
+// first host, and a future session-side consumer — e.g. sub-agent expansion —
+// would share this identity rather than minting a divergent one).
+//
+// Kept in its own module (not in a component file) so behavior-only
+// consumers — the panel controller opens the tabs, the viewer routes them —
+// depend on the identity without pulling the transcript renderer into their
+// module graph (DD-003 headless-first). Mirrors artifact-document.ts and
+// file-change-document.ts.
+
+import { virtualEntryId } from "../internal/store/index.js";
+
+/**
+ * Virtual entry id of the agent-execution transcript document FAMILY. Like
+ * artifacts and file changes (and unlike the session's single plan tab),
+ * transcripts are many: every opened child AgentExecution shares this one
+ * entry id and is distinguished by its id-derived tab path, so
+ * `editorKey(AGENT_EXECUTION_DOCUMENT_ENTRY_ID, path)` yields one tab per
+ * child execution — the VS Code "each file is a tab" model. The
+ * NUL-namespaced virtual id can never alias a real workspace entry, and its
+ * distinct `"agentexec"` kind can never collide with the
+ * `"artifact"`/`"filechange"`/`"plan"` families.
+ */
+export const AGENT_EXECUTION_DOCUMENT_ENTRY_ID = virtualEntryId("agentexec");
+
+/**
+ * The identity of a child AgentExecution's transcript tab within the family.
+ *
+ * The path deliberately CARRIES the child execution id (unlike artifact tabs,
+ * which need an owner-level record map to resolve content): a transcript
+ * needs only the id to fetch/stream itself, so the viewer parses it straight
+ * back out with {@link parseAgentExecutionTabPath} — no lookup map to keep in
+ * sync. The suffix is the AGENT_CALL task name because the editor tab's LABEL
+ * is the path's basename: the task name correlates the tab with the DAG node
+ * the user opened it from, and keeps two calls to the same agent distinct.
+ */
+export function agentExecutionTabPath(
+  childExecutionId: string,
+  taskName: string,
+): string {
+  return `${childExecutionId}/${taskName}`;
+}
+
+/**
+ * Recovers the child execution id from a transcript tab's path — the inverse
+ * of {@link agentExecutionTabPath}. Splits on the FIRST separator: execution
+ * ids never contain `/`, so a task name that does still round-trips.
+ */
+export function parseAgentExecutionTabPath(path: string): string {
+  const separator = path.indexOf("/");
+  return separator === -1 ? path : path.slice(0, separator);
+}

package/src/execution/artifact-document.ts

@@ -0,0 +1,24 @@
+// Identity of artifact document tabs in the workspace surface's editor group.
+// Domain: execution (shared — both the session and workflow panels open
+// artifact tabs, and a single identity source prevents the two viewers from
+// minting divergent virtual ids for the same tab family).
+//
+// Kept in its own module (not in a component file) so behavior-only
+// consumers — the session/workflow panel controllers open artifact tabs, the
+// viewers route to them — depend on the identity without pulling a component
+// (and its content renderer) into their module graph (DD-003 headless-first).
+// Mirrors session/plan-document.ts.
+
+import { virtualEntryId } from "../internal/store/index.js";
+
+/**
+ * Virtual entry id of the artifact document FAMILY. Unlike the plan (one tab
+ * per session), artifacts are many: every opened artifact shares this one
+ * entry id and is distinguished by its identity-derived `path` (the session's
+ * `artifactKey`, the workflow's `Artifact` id), so
+ * `editorKey(ARTIFACT_DOCUMENT_ENTRY_ID, path)` yields one tab per artifact —
+ * the VS Code "each file is a tab" model. The NUL-namespaced virtual id can
+ * never alias a real workspace entry, and its distinct `"artifact"` kind can
+ * never collide with the plan tab's `"plan"` kind.
+ */
+export const ARTIFACT_DOCUMENT_ENTRY_ID = virtualEntryId("artifact");

package/src/execution/artifact-row-item.ts

@@ -0,0 +1,97 @@
+// Type-agnostic view-model for artifact list rows, with adapters from both
+// artifact data models. Domain: execution (shared by session + workflow).
+
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { Artifact } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+
+/**
+ * What an artifact row displays, independent of which artifact data model
+ * produced it.
+ *
+ * Two artifact models exist and are deliberately unified ONLY at this
+ * presentational layer, never at the data layer: the session's
+ * `ExecutionArtifact` (embedded in `AgentExecution.status.artifacts`) and the
+ * workflow's first-class `Artifact` resource. Their identity, provenance, and
+ * download mechanics differ — so the view-model carries no identity; list
+ * keys and open/download behavior stay with the domain-specific hosts.
+ */
+export interface ArtifactRowItem {
+  /** Display label (file or directory name). */
+  readonly name: string;
+  /** Hover title — the fullest location/name known for the artifact. */
+  readonly tooltip: string;
+  /**
+   * Disambiguation subtitle rendered after the name when another row shares
+   * the same display name: the parent directory for sandbox-backed artifacts,
+   * the producing task for workflow artifacts. `null` when not needed.
+   */
+  readonly subtitlePath: string | null;
+  /** Content size in bytes (protobuf `int64` is `bigint`). */
+  readonly sizeBytes: bigint | number;
+  /** Directory artifacts render a folder icon, a `/` suffix, and ZIP download copy. */
+  readonly isDirectory: boolean;
+}
+
+/**
+ * Adapts a session `ExecutionArtifact` to a row item.
+ *
+ * @param hasNameCollision - When `true`, the artifact's parent directory (from
+ *   `sandbox_path`) becomes the disambiguation subtitle. Typically supplied
+ *   from `SessionArtifactEntry.hasNameCollision`.
+ */
+export function fromExecutionArtifact(
+  artifact: ExecutionArtifact,
+  hasNameCollision = false,
+): ArtifactRowItem {
+  return {
+    name: artifact.name,
+    tooltip: artifact.sandboxPath || artifact.name,
+    subtitlePath:
+      hasNameCollision && artifact.sandboxPath
+        ? parentDirectory(artifact.sandboxPath)
+        : null,
+    sizeBytes: artifact.sizeBytes,
+    isDirectory: artifact.kind === ExecutionArtifactKind.DIRECTORY,
+  };
+}
+
+/**
+ * Adapts a workflow `Artifact` resource to a row item.
+ *
+ * A workflow artifact is always a single content-typed blob — the resource
+ * model has no directory concept — so `isDirectory` is always `false`. Name
+ * collisions disambiguate by the producing task (`source.task_name`), the
+ * workflow analog of the session's parent-directory subtitle.
+ *
+ * @param hasNameCollision - When `true` and the artifact has a source task,
+ *   that task name becomes the disambiguation subtitle.
+ */
+export function fromArtifact(
+  artifact: Artifact,
+  hasNameCollision = false,
+): ArtifactRowItem {
+  const name =
+    artifact.spec?.displayName || artifact.metadata?.name || "Unnamed";
+  const taskName = artifact.spec?.source?.taskName ?? "";
+  return {
+    name,
+    tooltip: name,
+    subtitlePath: hasNameCollision && taskName ? taskName : null,
+    sizeBytes: artifact.status?.sizeBytes ?? BigInt(0),
+    isDirectory: false,
+  };
+}
+
+/**
+ * Extracts a human-readable parent directory label from a sandbox path.
+ * Given `/workspace/configs/agent.yaml` returns `configs/`.
+ * Returns `null` when the path has no meaningful parent segment.
+ */
+export function parentDirectory(sandboxPath: string): string | null {
+  const lastSlash = sandboxPath.lastIndexOf("/");
+  if (lastSlash <= 0) return null;
+  const parent = sandboxPath.slice(0, lastSlash);
+  const segment = parent.slice(parent.lastIndexOf("/") + 1);
+  return segment ? `${segment}/` : null;
+}

package/src/execution/deriveExecutionFileChanges.ts

@@ -0,0 +1,237 @@
+// Pure derivation of net file changes across a chronological list of agent
+// executions, plus the FileChange → FileDiffEntry projection for file lists.
+// Domain: execution (shared — the session's Changes surface and the workflow
+// panel's Changes facet both collapse per-execution captures into one net
+// change per path, and a single core prevents the two from drifting on the
+// non-trivial net-diff semantics below).
+//
+// Not a hook: callers memoize on their executions reference
+// (`useSessionFileChanges` for sessions; `useWorkflowExecutionFileChanges`
+// aggregates a workflow's AGENT_CALL children).
+
+import { create } from "@bufbuild/protobuf";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { FileChangeSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  FileChangeCaptureLevel,
+  FileChangeType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { displayFileChangeSets, toDisplayFileChange } from "@stigmer/sdk";
+import { computeDiff } from "../version-history/computeDiff.js";
+import type { DiffHunk, FileDiffEntry } from "../version-history/types.js";
+
+/**
+ * Collapses the file changes captured across `executions` into one *net*
+ * {@link FileChange} per path, ordered for a file list (modified, then
+ * created/renamed, then deleted; alphabetical within each group).
+ *
+ * **Source (ledger-first).** Under apply-then-review the changes live in the
+ * file-review ledger; {@link displayFileChangeSets} reads the server's live
+ * projection or folds the durable ledger for a terminal execution (whose
+ * projection is nil), and each captured change is projected onto the display
+ * {@link FileChange} via {@link toDisplayFileChange}. The execution-scoped
+ * ledger already includes sub-agent captures (DD-19), so one pass per
+ * execution suffices.
+ *
+ * **Net-diff (not latest-wins).** A {@link FileChange} is a *delta* — an
+ * agent often rewrites the same file several times, and showing only the last
+ * edit's diff would misrepresent what changed. So changes to the same path
+ * are reduced to a single net change: `before` from the first change, `after`
+ * from the last. Because a WHOLE_FILE `after` is a complete file snapshot,
+ * `first.before → last.after` is exactly the net change. A group with one
+ * change (the common case) is passed through untouched; multi-edit groups
+ * synthesize a net {@link FileChange} so every consumer speaks one proto
+ * type (DD-007).
+ *
+ * **Ordering is a correctness input.** `executions` MUST be chronological:
+ * the net collapse anchors on each path's first and last change, so two
+ * executions touching the same path (a session's follow-up turns; two
+ * workflow agent-call tasks) produce a wrong net diff if visited out of
+ * order.
+ *
+ * Counts and unified diffs for whole-file captures stay derivable by the
+ * presentation layer (the runner emits 0/"" sentinels), matching the
+ * contract the SDK `tool-view` established.
+ */
+export function deriveExecutionFileChanges(
+  executions: readonly AgentExecution[],
+): readonly FileChange[] {
+  // Path -> chronological list of raw changes to that path.
+  const groups = new Map<string, FileChange[]>();
+  // Preserve first-seen path order as a stable tiebreaker before sorting.
+  const collect = (change: FileChange) => {
+    const key = change.path || change.absolutePath;
+    if (!key) return;
+    const list = groups.get(key);
+    if (list) list.push(change);
+    else groups.set(key, [change]);
+  };
+
+  for (const execution of executions) {
+    const capturedChanges = displayFileChangeSets(execution.status).flatMap(
+      (set) => set.changes,
+    );
+    for (const captured of capturedChanges) collect(toDisplayFileChange(captured));
+  }
+
+  const fileChanges = Array.from(groups.values(), netChange);
+  fileChanges.sort(fileChangeComparator);
+  return fileChanges;
+}
+
+/**
+ * Reduces a path's chronological change list to a single net change.
+ * A one-change group is returned as-is (the common path, no allocation);
+ * multi-edit groups synthesize a net {@link FileChange}.
+ */
+function netChange(changes: FileChange[]): FileChange {
+  if (changes.length === 1) return changes[0];
+
+  const first = changes[0];
+  const last = changes[changes.length - 1];
+  const changeType = netChangeType(first, last);
+
+  // Whole-file only when both chosen sides come from whole-file captures;
+  // otherwise fall back to the last change's hunk diff. A path edited by a
+  // single harness won't mix levels — this just stays honest if it ever does.
+  const wholeFile =
+    first.captureLevel === FileChangeCaptureLevel.WHOLE_FILE &&
+    last.captureLevel === FileChangeCaptureLevel.WHOLE_FILE;
+
+  if (wholeFile) {
+    return create(FileChangeSchema, {
+      path: last.path,
+      absolutePath: last.absolutePath,
+      changeType,
+      captureLevel: FileChangeCaptureLevel.WHOLE_FILE,
+      before: first.before,
+      after: last.after,
+      renameFrom: changeType === FileChangeType.RENAME ? first.renameFrom : "",
+    });
+  }
+
+  return create(FileChangeSchema, {
+    path: last.path,
+    absolutePath: last.absolutePath,
+    changeType,
+    captureLevel: FileChangeCaptureLevel.HUNK_ONLY,
+    unifiedDiff: last.unifiedDiff,
+    linesAdded: last.linesAdded,
+    linesRemoved: last.linesRemoved,
+    renameFrom: changeType === FileChangeType.RENAME ? first.renameFrom : "",
+  });
+}
+
+/**
+ * Reconciles the net `change_type` of a path from its first and last change.
+ *
+ * Intent: the badge should describe the file's journey across the *whole*
+ * span of executions, anchored on its two endpoints, in this precedence:
+ *
+ * 1. Ends deleted (`last` is DELETE) → DELETE. The file is gone, regardless of
+ *    how it got there — this includes create-then-delete, which we deliberately
+ *    surface as DELETE rather than hiding the path. (`before` then comes from
+ *    the first change, which for a created-then-deleted file is empty, so the
+ *    diff reads as the removal of whatever briefly existed.)
+ * 2. Started created (`first` is CREATE) and still exists → CREATE. A file born
+ *    in this span and later modified is, on net, a new file.
+ * 3. Started renamed (`first` is RENAME) and still exists → RENAME, carrying the
+ *    original `rename_from` so the move is preserved across later edits.
+ * 4. Otherwise → MODIFY (the common multi-edit case).
+ */
+function netChangeType(first: FileChange, last: FileChange): FileChangeType {
+  if (last.changeType === FileChangeType.DELETE) return FileChangeType.DELETE;
+  if (first.changeType === FileChangeType.CREATE) return FileChangeType.CREATE;
+  if (first.changeType === FileChangeType.RENAME) return FileChangeType.RENAME;
+  return FileChangeType.MODIFY;
+}
+
+// Most-actionable first (modified), then additions (create/rename), then
+// deletions — mirroring GitHub's file-list convention — alphabetical within
+// each group so the list is stable and scannable.
+const CHANGE_TYPE_ORDER: Readonly<Record<FileChangeType, number>> = {
+  [FileChangeType.MODIFY]: 0,
+  [FileChangeType.CREATE]: 1,
+  [FileChangeType.RENAME]: 1,
+  [FileChangeType.DELETE]: 2,
+  [FileChangeType.UNSPECIFIED]: 3,
+};
+
+function fileChangeComparator(a: FileChange, b: FileChange): number {
+  const order =
+    (CHANGE_TYPE_ORDER[a.changeType] ?? 3) -
+    (CHANGE_TYPE_ORDER[b.changeType] ?? 3);
+  if (order !== 0) return order;
+  return a.path.localeCompare(b.path, undefined, { sensitivity: "base" });
+}
+
+// ---------------------------------------------------------------------------
+// FileChange → FileDiffEntry projection (file lists)
+// ---------------------------------------------------------------------------
+
+/**
+ * Projects a {@link FileChange} into a {@link FileDiffEntry} for a file list
+ * (`DiffFileList`).
+ *
+ * Counts: hunk-only uses the runner's authoritative numbers; whole-file inline
+ * is derived from the content (identical to the runner's capture-time counts by
+ * construction — same diff algorithm). A whole-file side with no synchronous
+ * content (offloaded / binary) falls back to the runner's capture-time
+ * `linesAdded`/`linesRemoved` — zero when no count exists, which the list
+ * renders as no stat.
+ */
+export function toFileDiffEntry(change: FileChange): FileDiffEntry {
+  const changeType =
+    change.changeType === FileChangeType.CREATE
+      ? "added"
+      : change.changeType === FileChangeType.DELETE
+        ? "removed"
+        : "modified";
+
+  if (change.captureLevel === FileChangeCaptureLevel.HUNK_ONLY) {
+    return {
+      path: change.path,
+      changeType,
+      additions: change.linesAdded,
+      deletions: change.linesRemoved,
+    };
+  }
+
+  const before = inlineSide(change.before);
+  const after = inlineSide(change.after);
+  if (before !== null && after !== null) {
+    const { additions, deletions } = countHunks(computeDiff(before, after));
+    return { path: change.path, changeType, additions, deletions };
+  }
+
+  return {
+    path: change.path,
+    changeType,
+    additions: change.linesAdded,
+    deletions: change.linesRemoved,
+  };
+}
+
+/** Sums added/removed line counts across rendered diff hunks. */
+export function countHunks(hunks: readonly DiffHunk[]): {
+  additions: number;
+  deletions: number;
+} {
+  let additions = 0;
+  let deletions = 0;
+  for (const hunk of hunks) {
+    for (const line of hunk.lines) {
+      if (line.type === "added") additions++;
+      else if (line.type === "removed") deletions++;
+    }
+  }
+  return { additions, deletions };
+}
+
+/** Inline text of a side, or null when absent/offloaded/binary. */
+function inlineSide(side: FileChange["before"]): string | null {
+  if (!side) return "";
+  if (side.isBinary) return null;
+  return side.body.case === "inline" ? side.body.value : null;
+}

package/src/execution/file-change-document.ts

@@ -0,0 +1,37 @@
+// Identity of file-change diff document tabs in the workspace surface's
+// editor group. Domain: execution (the diff renderer and the FileChange data
+// model are execution-domain; the workflow panel is the first host, and a
+// future session-side consumer would share this identity rather than minting
+// a divergent one).
+//
+// Kept in its own module (not in a component file) so behavior-only
+// consumers — the panel controller opens the tabs, the viewer routes them —
+// depend on the identity without pulling the diff renderer into their module
+// graph (DD-003 headless-first). Mirrors artifact-document.ts.
+
+import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { virtualEntryId } from "../internal/store/index.js";
+
+/**
+ * Virtual entry id of the file-change diff document FAMILY. Like artifacts
+ * (and unlike the session's single plan tab), file changes are many: every
+ * opened diff shares this one entry id and is distinguished by its
+ * change-path-derived tab path, so
+ * `editorKey(FILE_CHANGE_DOCUMENT_ENTRY_ID, path)` yields one tab per changed
+ * file — the VS Code "each file is a tab" model. The NUL-namespaced virtual
+ * id can never alias a real workspace entry, and its distinct `"filechange"`
+ * kind can never collide with the `"artifact"`/`"plan"` families.
+ */
+export const FILE_CHANGE_DOCUMENT_ENTRY_ID = virtualEntryId("filechange");
+
+/**
+ * The identity of a file change's diff tab within the family. The net rollup
+ * carries at most one {@link FileChange} per path, so the change's path IS
+ * the identity — and, as the tab path, its basename is exactly the tab label
+ * (no prefixing needed, unlike artifact tabs whose ids are opaque).
+ * `absolutePath` is the fallback for captures without a workspace-relative
+ * path, matching the keying inside the net-collapse core.
+ */
+export function fileChangeTabPath(change: FileChange): string {
+  return change.path || change.absolutePath;
+}

package/src/execution/index.ts

@@ -12,6 +12,9 @@ export { isTerminalPhase } from "./execution-phases.js";
 export { useExecutionStream } from "./useExecutionStream.js";
 export type { UseExecutionStreamReturn } from "./useExecutionStream.js";
 
+export { useLiveAgentExecution } from "./useLiveAgentExecution.js";
+export type { UseLiveAgentExecutionReturn } from "./useLiveAgentExecution.js";
+
 export { useAgentExecutionActions } from "./useAgentExecutionActions.js";
 export type {
   UseAgentExecutionActionsOptions,
@@ -55,6 +58,9 @@ export type { UseExecutionArtifactsReturn } from "./useExecutionArtifacts.js";
 export { useArtifactContent } from "./useArtifactContent.js";
 export type { UseArtifactContentReturn } from "./useArtifactContent.js";
 
+export { useArtifactContentById } from "./useArtifactContentById.js";
+export type { UseArtifactContentByIdReturn } from "./useArtifactContentById.js";
+
 export { useArtifactDownloadUrl } from "./useArtifactDownloadUrl.js";
 export type {
   UseArtifactDownloadUrlReturn,
@@ -92,6 +98,11 @@ export type { DiffStatSummary } from "./write-back-utils.js";
 export { FileChangesView, FileChangeDiff } from "./FileChangesView.js";
 export type { FileChangesViewProps, FileChangeDiffProps } from "./FileChangesView.js";
 
+export {
+  deriveExecutionFileChanges,
+  toFileDiffEntry,
+} from "./deriveExecutionFileChanges.js";
+
 export { EmptyChangeNotice } from "./EmptyChangeNotice.js";
 export type { EmptyChangeNoticeProps, EmptyChangeKind } from "./EmptyChangeNotice.js";
 
@@ -264,9 +275,34 @@ export type { FileReviewContextValue } from "./FileReviewContext.js";
 export { ArtifactRow } from "./ArtifactRow.js";
 export type { ArtifactRowProps } from "./ArtifactRow.js";
 
+export { ArtifactRowView } from "./ArtifactRowView.js";
+export type { ArtifactRowViewProps } from "./ArtifactRowView.js";
+
+export {
+  fromExecutionArtifact,
+  fromArtifact,
+} from "./artifact-row-item.js";
+export type { ArtifactRowItem } from "./artifact-row-item.js";
+
+export { ARTIFACT_DOCUMENT_ENTRY_ID } from "./artifact-document.js";
+
+export {
+  FILE_CHANGE_DOCUMENT_ENTRY_ID,
+  fileChangeTabPath,
+} from "./file-change-document.js";
+
+export {
+  AGENT_EXECUTION_DOCUMENT_ENTRY_ID,
+  agentExecutionTabPath,
+  parseAgentExecutionTabPath,
+} from "./agent-execution-document.js";
+
 export { ArtifactContentRenderer } from "./ArtifactContentRenderer.js";
 export type { ArtifactContentRendererProps } from "./ArtifactContentRenderer.js";
 
+export { ArtifactFileContent } from "./ArtifactFileContent.js";
+export type { ArtifactFileContentProps } from "./ArtifactFileContent.js";
+
 export { ArtifactContentBody } from "./ArtifactContentBody.js";
 export type { ArtifactContentBodyProps } from "./ArtifactContentBody.js";
 

package/src/execution/useArtifactContentById.ts

@@ -0,0 +1,120 @@
+"use client";
+
+// Data hook that reads an Artifact resource's content by artifact id.
+// Domain: execution (the Artifact-resource counterpart of useArtifactContent).
+
+import { create } from "@bufbuild/protobuf";
+import { GetArtifactContentRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+interface ArtifactContentData {
+  content: string | null;
+  contentType: string | null;
+  totalSizeBytes: bigint;
+  isTruncated: boolean;
+}
+
+const EMPTY_ARTIFACT: ArtifactContentData = {
+  content: null,
+  contentType: null,
+  totalSizeBytes: BigInt(0),
+  isTruncated: false,
+};
+
+/** Return value of {@link useArtifactContentById}. */
+export interface UseArtifactContentByIdReturn {
+  /**
+   * Decoded text content of the artifact, or `null` when:
+   * - Fetching is skipped (`artifactId` is `null`)
+   * - The request is in-flight
+   * - The request failed
+   */
+  readonly content: string | null;
+  /**
+   * MIME content type recorded at artifact creation
+   * (`ArtifactSpec.content_type`). `null` before the first successful fetch.
+   */
+  readonly contentType: string | null;
+  /**
+   * Actual total size of the artifact in bytes — larger than the returned
+   * content when `isTruncated` is `true` ("showing 512 KB of 2.1 MB").
+   */
+  readonly totalSizeBytes: bigint;
+  /**
+   * Whether the returned content was truncated by the server's `max_bytes`
+   * limit. When `true`, offer the full artifact via `getDownloadUrl` instead.
+   */
+  readonly isTruncated: boolean;
+  /** `true` while the content request is in-flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Re-fetch the artifact content. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the text content of an `Artifact` resource via
+ * `stigmer.artifact.getContent()`.
+ *
+ * The server proxies the artifact bytes through the Stigmer API rather than
+ * handing out a presigned URL — embedded SDK consumers on third-party origins
+ * avoid the CORS exposure of fetching storage URLs from the browser (the same
+ * rationale as the agent-execution side's `useArtifactContent`, which this
+ * hook mirrors; artifacts here are addressed by artifact ID, the artifact
+ * store's identity, instead of `executionId` + `storageKey`).
+ *
+ * Pass `null` for `artifactId` to skip fetching — the caller controls when to
+ * fetch based on artifact metadata (e.g. only for text content types below a
+ * size threshold), consistent with the `useArtifactContent(null)` convention.
+ *
+ * The server enforces a content size limit (default 512 KB). Content
+ * exceeding it comes back with `isTruncated: true`; offer a full download via
+ * `getDownloadUrl` in that case. The returned `content` is decoded as UTF-8 —
+ * for binary artifacts, use `getDownloadUrl` instead of this hook.
+ *
+ * @param artifactId - The `Artifact` resource id (`art_…`), or `null` to skip.
+ * @param cacheKey - Optional cross-mount cache key (DD-014). When set, a
+ *   remount with the same key renders previously-fetched content instantly
+ *   and refetches in the background — used by the workflow artifact document
+ *   so switching back to a recently-viewed tab is instant.
+ */
+export function useArtifactContentById(
+  artifactId: string | null,
+  cacheKey?: string,
+): UseArtifactContentByIdReturn {
+  const stigmer = useStigmer();
+
+  const { data, isLoading, isRefetching, error, refetch } = useFetch(
+    artifactId
+      ? () =>
+          stigmer.artifact
+            .getContent(
+              create(GetArtifactContentRequestSchema, { artifactId }),
+            )
+            .then((result): ArtifactContentData => ({
+              content: new TextDecoder().decode(result.content),
+              contentType: result.contentType || null,
+              totalSizeBytes: result.totalSizeBytes,
+              isTruncated: result.truncated,
+            }))
+      : null,
+    [artifactId, stigmer],
+    EMPTY_ARTIFACT,
+    cacheKey ? { cacheKey } : undefined,
+  );
+
+  return {
+    content: data.content,
+    contentType: data.contentType,
+    totalSizeBytes: data.totalSizeBytes,
+    isTruncated: data.isTruncated,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+  };
+}

package/src/execution/useArtifactDownload.ts

@@ -28,9 +28,10 @@ export interface UseArtifactDownloadReturn {
 /**
  * Behavior hook that downloads an execution artifact on demand.
  *
- * Mirrors the click → mint fresh URL → browser download flow established by
- * `WorkflowExecutionArtifactPanel`, generalized so every artifact "Download"
- * affordance shares one implementation. The URL is minted at click time from
+ * Implements the click → mint fresh URL → browser download flow so every
+ * artifact "Download" affordance shares one implementation (the workflow's
+ * `Artifact`-resource counterpart is `useWorkflowArtifactDownload`). The URL
+ * is minted at click time from
  * the stable `storageKey` via `getArtifactDownloadUrl`, so it is always valid —
  * unlike the previously persisted, short-lived URL that expired after an hour.
  *

package/src/execution/useCreateAgentExecution.ts

@@ -72,7 +72,7 @@ export interface SharedAgentExecutionFields {
    * the Environment Flow instead (store secrets in an Environment
    * resource and bind them via an AgentInstance).
    *
-   * @see {@link https://docs.stigmer.ai/product/how-to-provide-secrets | How to Provide Secrets}
+   * @see {@link https://stigmer.ai/docs/product/how-to-provide-secrets | How to Provide Secrets}
    */
   readonly runtimeEnv?: Record<string, EnvVarInput>;
   /**