@stigmer/react 3.0.9-dev.20260616060535 → 3.1.0

package/execution/useArtifactDownloadUrl.d.ts

@@ -0,0 +1,67 @@
+/** Return value of {@link useArtifactDownloadUrl}. */
+export interface UseArtifactDownloadUrlReturn {
+    /**
+     * A freshly minted presigned download URL for the artifact, or `null` when:
+     * - Fetching is skipped (`enabled` is `false`, or `executionId`/`storageKey` is `null`)
+     * - The request is in-flight
+     * - The request failed
+     */
+    readonly url: string | null;
+    /** `true` while the URL request is in-flight (first load). */
+    readonly isLoading: boolean;
+    /** `true` while a background refetch is in flight. */
+    readonly isRefetching: boolean;
+    /** Error from the last failed attempt, or `null` when healthy. */
+    readonly error: Error | null;
+    /** Re-fetch the URL (e.g. to mint a fresh one after the previous expired). */
+    readonly refetch: () => void;
+}
+/** Options for {@link useArtifactDownloadUrl}. */
+export interface UseArtifactDownloadUrlOptions {
+    /**
+     * Gate the request. When `false`, the hook stays idle and returns `null` —
+     * use this to defer minting a URL until it is actually needed (e.g. only
+     * when an image becomes visible, or after a truncation is detected).
+     * Defaults to `true`.
+     */
+    readonly enabled?: boolean;
+}
+/**
+ * Data hook that resolves a **fresh** presigned download URL for an execution
+ * artifact on demand via `stigmer.agentExecution.getArtifactDownloadUrl()`.
+ *
+ * This exists because presigned URLs expire. The runner once baked a
+ * short-lived URL into the persisted execution status and the UI rendered it
+ * verbatim — so any link opened after the URL's lifetime failed with
+ * `ExpiredRequest`. Minting the URL at view time from the stable `storageKey`
+ * guarantees it is always valid, and works for every historical execution
+ * (the `storageKey` never expires).
+ *
+ * Use this for surfaces that genuinely need a URL — an `<img src>` for an
+ * offloaded screenshot, or a direct browser download of a large/binary
+ * artifact. For text that should render in-app, prefer {@link useArtifactContent}
+ * (CORS-safe, no presign).
+ *
+ * The URL is cached cross-mount by `storageKey` (DD-014), so repeated renders
+ * and remounts reuse the same minted URL instead of re-hitting the API.
+ *
+ * Pass `enabled: false` (or `null` for either id) to skip fetching — consistent
+ * with the `useArtifactContent(null, null)` convention.
+ *
+ * @param executionId - Execution that produced the artifact, or `null` to skip.
+ * @param storageKey - Storage key from the artifact/output ref, or `null` to skip.
+ * @param options - Optional gating (`enabled`).
+ *
+ * @example
+ * ```tsx
+ * // Render an offloaded screenshot with an always-fresh URL.
+ * const { url, isLoading } = useArtifactDownloadUrl(executionId, storageKey);
+ * if (isLoading) return <Skeleton />;
+ * return url ? <img src={url} alt="Tool output" /> : null;
+ * ```
+ *
+ * @see useArtifactContent — reads artifact bytes through the API (text preview)
+ * @see useArtifactDownload — imperative click-to-download counterpart
+ */
+export declare function useArtifactDownloadUrl(executionId: string | null, storageKey: string | null, options?: UseArtifactDownloadUrlOptions): UseArtifactDownloadUrlReturn;
+//# sourceMappingURL=useArtifactDownloadUrl.d.ts.map

package/execution/useArtifactDownloadUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useArtifactDownloadUrl.d.ts","sourceRoot":"","sources":["../../src/execution/useArtifactDownloadUrl.ts"],"names":[],"mappings":"AAQA,sDAAsD;AACtD,MAAM,WAAW,4BAA4B;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B,sDAAsD;IACtD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAE/B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAE7B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAQD,kDAAkD;AAClD,MAAM,WAAW,6BAA6B;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,OAAO,CAAC,EAAE,6BAA6B,GACtC,4BAA4B,CA0B9B"}

package/execution/useArtifactDownloadUrl.js

@@ -0,0 +1,59 @@
+"use client";
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import { GetArtifactDownloadUrlRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+const EMPTY = { url: null };
+/**
+ * Data hook that resolves a **fresh** presigned download URL for an execution
+ * artifact on demand via `stigmer.agentExecution.getArtifactDownloadUrl()`.
+ *
+ * This exists because presigned URLs expire. The runner once baked a
+ * short-lived URL into the persisted execution status and the UI rendered it
+ * verbatim — so any link opened after the URL's lifetime failed with
+ * `ExpiredRequest`. Minting the URL at view time from the stable `storageKey`
+ * guarantees it is always valid, and works for every historical execution
+ * (the `storageKey` never expires).
+ *
+ * Use this for surfaces that genuinely need a URL — an `<img src>` for an
+ * offloaded screenshot, or a direct browser download of a large/binary
+ * artifact. For text that should render in-app, prefer {@link useArtifactContent}
+ * (CORS-safe, no presign).
+ *
+ * The URL is cached cross-mount by `storageKey` (DD-014), so repeated renders
+ * and remounts reuse the same minted URL instead of re-hitting the API.
+ *
+ * Pass `enabled: false` (or `null` for either id) to skip fetching — consistent
+ * with the `useArtifactContent(null, null)` convention.
+ *
+ * @param executionId - Execution that produced the artifact, or `null` to skip.
+ * @param storageKey - Storage key from the artifact/output ref, or `null` to skip.
+ * @param options - Optional gating (`enabled`).
+ *
+ * @example
+ * ```tsx
+ * // Render an offloaded screenshot with an always-fresh URL.
+ * const { url, isLoading } = useArtifactDownloadUrl(executionId, storageKey);
+ * if (isLoading) return <Skeleton />;
+ * return url ? <img src={url} alt="Tool output" /> : null;
+ * ```
+ *
+ * @see useArtifactContent — reads artifact bytes through the API (text preview)
+ * @see useArtifactDownload — imperative click-to-download counterpart
+ */
+export function useArtifactDownloadUrl(executionId, storageKey, options) {
+    const stigmer = useStigmer();
+    const enabled = options?.enabled ?? true;
+    const active = enabled && !!executionId && !!storageKey;
+    const { data, isLoading, isRefetching, error, refetch } = useFetch(active
+        ? () => stigmer.agentExecution
+            .getArtifactDownloadUrl(create(GetArtifactDownloadUrlRequestSchema, {
+            executionId: executionId,
+            storageKey: storageKey,
+        }))
+            .then((result) => ({ url: result.downloadUrl || null }))
+        : null, [executionId, storageKey, active, stigmer], EMPTY, { cacheKey: storageKey ? `artifact-url:${storageKey}` : undefined });
+    return useMemo(() => ({ url: data.url, isLoading, isRefetching, error, refetch }), [data.url, isLoading, isRefetching, error, refetch]);
+}
+//# sourceMappingURL=useArtifactDownloadUrl.js.map

package/execution/useArtifactDownloadUrl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useArtifactDownloadUrl.js","sourceRoot":"","sources":["../../src/execution/useArtifactDownloadUrl.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,mCAAmC,EAAE,MAAM,4DAA4D,CAAC;AACjH,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AA6BhD,MAAM,KAAK,GAAY,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AAarC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAA0B,EAC1B,UAAyB,EACzB,OAAuC;IAEvC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC;IACzC,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,UAAU,CAAC;IAExD,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,QAAQ,CAChE,MAAM;QACJ,CAAC,CAAC,GAAG,EAAE,CACH,OAAO,CAAC,cAAc;aACnB,sBAAsB,CACrB,MAAM,CAAC,mCAAmC,EAAE;YAC1C,WAAW,EAAE,WAAY;YACzB,UAAU,EAAE,UAAW;SACxB,CAAC,CACH;aACA,IAAI,CAAC,CAAC,MAAM,EAAW,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC,CAAC;QACvE,CAAC,CAAC,IAAI,EACR,CAAC,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAC1C,KAAK,EACL,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,gBAAgB,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE,CACpE,CAAC;IAEF,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAClE,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,CAAC,CACpD,CAAC;AACJ,CAAC"}

package/execution/useFileChangeContent.d.ts

@@ -0,0 +1,61 @@
+import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+/** Return value of {@link useFileChangeContent}. */
+export interface UseFileChangeContentReturn {
+    /**
+     * Before-side text for diffing. `""` for an absent side (e.g. CREATE has no
+     * before). `null` while an offloaded side is in-flight or failed to load.
+     */
+    readonly beforeText: string | null;
+    /**
+     * After-side text for diffing. `""` for an absent side (e.g. DELETE has no
+     * after). `null` while an offloaded side is in-flight or failed to load.
+     */
+    readonly afterText: string | null;
+    /** `true` when either side is binary — render "binary file changed", not a diff. */
+    readonly isBinary: boolean;
+    /** `true` while an offloaded side's content request is in flight. */
+    readonly isLoading: boolean;
+    /** Error from a failed offloaded-side fetch, or `null`. */
+    readonly error: Error | null;
+    /**
+     * `true` when an offloaded side exceeded the server's content-size limit and
+     * was truncated — the inline diff would be incomplete; offer {@link downloadUrl}.
+     */
+    readonly isTruncated: boolean;
+    /**
+     * Direct download URL for an offloaded side (the after side preferred), used
+     * as the fallback when content is truncated. `null` when neither side is offloaded.
+     */
+    readonly downloadUrl: string | null;
+}
+/**
+ * Behavior hook that resolves a {@link FileChange}'s before/after sides to the
+ * text the diff renderer needs.
+ *
+ * Small bodies are carried inline on the proto and returned with zero cost.
+ * Large bodies were offloaded to artifact storage by the runner
+ * (`FileContent.ref`); this hook lazily fetches them via
+ * {@link useArtifactContent} through the server proxy (CORS-safe). The fetch's
+ * `executionId` is derived from the ref's own `storageKey`
+ * (`artifacts/{executionId}/...`), so a net diff whose two sides originated in
+ * different executions still resolves each side correctly.
+ *
+ * This is the single place offload refs are dereferenced — the SDK's
+ * `tool-view` deliberately stays fetch-free, deferring all ref handling here.
+ *
+ * Rules-of-hooks safe: both sides always issue a (possibly skipped)
+ * `useArtifactContent` call; inline/absent sides pass `null` and never fetch.
+ *
+ * @param change - The file change whose content to resolve.
+ *
+ * @see useSessionFileChanges — produces the changes this resolves
+ * @see FileChangeDiff — renders the resolved content
+ */
+export declare function useFileChangeContent(change: FileChange): UseFileChangeContentReturn;
+/**
+ * Extracts the execution id from an artifact storage key of the form
+ * `artifacts/{executionId}/...`. Returns `null` for an unexpected shape so the
+ * caller skips the fetch rather than issuing a request the server would reject.
+ */
+export declare function execIdFromStorageKey(storageKey: string): string | null;
+//# sourceMappingURL=useFileChangeContent.d.ts.map

package/execution/useFileChangeContent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFileChangeContent.d.ts","sourceRoot":"","sources":["../../src/execution/useFileChangeContent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EAEX,MAAM,iEAAiE,CAAC;AAIzE,oDAAoD;AACpD,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,GACjB,0BAA0B,CAmD5B;AAqBD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMtE"}

package/execution/useFileChangeContent.js

@@ -0,0 +1,89 @@
+"use client";
+import { useMemo } from "react";
+import { useArtifactContent } from "./useArtifactContent";
+import { useArtifactDownloadUrl } from "./useArtifactDownloadUrl";
+/**
+ * Behavior hook that resolves a {@link FileChange}'s before/after sides to the
+ * text the diff renderer needs.
+ *
+ * Small bodies are carried inline on the proto and returned with zero cost.
+ * Large bodies were offloaded to artifact storage by the runner
+ * (`FileContent.ref`); this hook lazily fetches them via
+ * {@link useArtifactContent} through the server proxy (CORS-safe). The fetch's
+ * `executionId` is derived from the ref's own `storageKey`
+ * (`artifacts/{executionId}/...`), so a net diff whose two sides originated in
+ * different executions still resolves each side correctly.
+ *
+ * This is the single place offload refs are dereferenced — the SDK's
+ * `tool-view` deliberately stays fetch-free, deferring all ref handling here.
+ *
+ * Rules-of-hooks safe: both sides always issue a (possibly skipped)
+ * `useArtifactContent` call; inline/absent sides pass `null` and never fetch.
+ *
+ * @param change - The file change whose content to resolve.
+ *
+ * @see useSessionFileChanges — produces the changes this resolves
+ * @see FileChangeDiff — renders the resolved content
+ */
+export function useFileChangeContent(change) {
+    const beforeRef = refOf(change.before);
+    const afterRef = refOf(change.after);
+    const beforeFetch = useArtifactContent(beforeRef ? execIdFromStorageKey(beforeRef.storageKey) : null, beforeRef ? beforeRef.storageKey : null, null, beforeRef?.contentHash);
+    const afterFetch = useArtifactContent(afterRef ? execIdFromStorageKey(afterRef.storageKey) : null, afterRef ? afterRef.storageKey : null, null, afterRef?.contentHash);
+    // The download fallback is needed only when an offloaded side was truncated.
+    // Resolve a fresh URL on demand from the stable storageKey (after side
+    // preferred), gated on truncation so we don't mint a URL we won't use.
+    const isTruncated = beforeFetch.isTruncated || afterFetch.isTruncated;
+    const downloadRef = afterRef ?? beforeRef;
+    const { url: downloadUrl } = useArtifactDownloadUrl(downloadRef ? execIdFromStorageKey(downloadRef.storageKey) : null, downloadRef ? downloadRef.storageKey : null, { enabled: isTruncated });
+    return useMemo(() => ({
+        beforeText: sideText(change.before, beforeFetch.content),
+        afterText: sideText(change.after, afterFetch.content),
+        isBinary: Boolean(change.before?.isBinary || change.after?.isBinary),
+        isLoading: beforeFetch.isLoading || afterFetch.isLoading,
+        error: beforeFetch.error ?? afterFetch.error,
+        isTruncated,
+        downloadUrl,
+    }), [
+        change.before,
+        change.after,
+        beforeFetch.content,
+        afterFetch.content,
+        beforeFetch.isLoading,
+        afterFetch.isLoading,
+        beforeFetch.error,
+        afterFetch.error,
+        isTruncated,
+        downloadUrl,
+    ]);
+}
+/** The offload pointer of a side, or null when the side is absent/inline/binary. */
+function refOf(side) {
+    if (!side || side.isBinary)
+        return null;
+    return side.body.case === "ref" ? side.body.value : null;
+}
+/**
+ * Resolves one side to text: absent → "" (empty file), inline → its value,
+ * offloaded → the fetched content (`null` until it loads).
+ */
+function sideText(side, fetched) {
+    if (!side || side.isBinary)
+        return "";
+    if (side.body.case === "inline")
+        return side.body.value;
+    return fetched;
+}
+/**
+ * Extracts the execution id from an artifact storage key of the form
+ * `artifacts/{executionId}/...`. Returns `null` for an unexpected shape so the
+ * caller skips the fetch rather than issuing a request the server would reject.
+ */
+export function execIdFromStorageKey(storageKey) {
+    const parts = storageKey.split("/");
+    if (parts.length >= 3 && parts[0] === "artifacts" && parts[1]) {
+        return parts[1];
+    }
+    return null;
+}
+//# sourceMappingURL=useFileChangeContent.js.map

package/execution/useFileChangeContent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFileChangeContent.js","sourceRoot":"","sources":["../../src/execution/useFileChangeContent.ts"],"names":[],"mappings":"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"}

package/execution/useFileReview.d.ts

@@ -0,0 +1,89 @@
+import { FileDecisionAction, FileDecisionScope } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+/** Options narrowing a file decision to a single file and binding its digest. */
+export interface FileDecisionOptions {
+    /**
+     * Decision scope. Defaults to `FILE` when {@link fileChangeId} is set, else
+     * `CHANGE_SET` (the whole-set decision that covers every file).
+     */
+    readonly scope?: FileDecisionScope;
+    /** The captured file this decision targets; required for `FILE` scope. */
+    readonly fileChangeId?: string;
+    /**
+     * The digest the reviewer saw (`aggregate_digest` for CHANGE_SET,
+     * `file_digest` for FILE). The server enforces it at decision time and the
+     * runner re-verifies it at reconcile — "what you approve is what gets applied".
+     */
+    readonly expectedDigest?: string;
+    /** Optional free-text comment recorded on the decision (audit trail). */
+    readonly reason?: string;
+    /**
+     * Set on an APPROVE to consciously KEEP a change whose diff could not be fully
+     * reviewed. Honored only for a binary file at `FILE` scope (a binary has no
+     * text diff, but its exact bytes are captured and reconcilable). It never
+     * relaxes the digest gate, and is ignored for other incompleteness. See DD-16.
+     */
+    readonly acknowledgeUnreviewable?: boolean;
+}
+/** Return value of {@link useFileReview}. */
+export interface UseFileReviewReturn {
+    /**
+     * Submit an approve/reject decision for a change set (or one file within it).
+     * Resolves when the backend accepts the decision; the execution stream will
+     * deliver the updated `file_change_sets` projection.
+     */
+    readonly submitFileDecision: (executionId: string, changeSetId: string, action: FileDecisionAction, options?: FileDecisionOptions) => Promise<void>;
+    /**
+     * Keys (`changeSetId` for a whole-set decision, `changeSetId:fileChangeId` for
+     * a per-file one) currently being submitted — drives per-button loading state
+     * when a reviewer decides files independently. Build a key with
+     * {@link fileDecisionKey}.
+     */
+    readonly submittingDecisionKeys: ReadonlySet<string>;
+    /**
+     * Per-decision failures, keyed exactly like {@link submittingDecisionKeys}
+     * (via {@link fileDecisionKey}). This is the per-target parallel of the
+     * in-flight Set: a review card has many decision targets (the whole set plus
+     * each file), so a failure must be attributable to the *one* control that
+     * failed — a single scalar cannot say which file. {@link FileReviewCard}
+     * consumes this map to render the error in-card, beside the failed control.
+     */
+    readonly decisionErrors: ReadonlyMap<string, Error>;
+    /** Clear the error for one decision key (e.g. before a retry of that target). */
+    readonly clearDecisionError: (key: string) => void;
+    /**
+     * The most-recent decision failure, or `null` when healthy — a convenience
+     * mirror of {@link decisionErrors} for a headless consumer that wants a single
+     * error value (a banner). The map is authoritative for per-control surfacing.
+     */
+    readonly error: Error | null;
+    /** Reset every decision error (both {@link decisionErrors} and {@link error}). */
+    readonly clearError: () => void;
+}
+/**
+ * The loading-state key for a file decision: the change set id for a whole-set
+ * (CHANGE_SET) decision, or `changeSetId:fileChangeId` for a per-file one.
+ */
+export declare function fileDecisionKey(changeSetId: string, fileChangeId?: string): string;
+/**
+ * Behavior hook that wraps `agentExecution.submitFileDecision()` with per-decision
+ * loading state and error management — the file-review sibling of
+ * {@link useSubmitApproval}.
+ *
+ * File edits are reviewed as a captured change set (the `file_change_sets`
+ * projection), NOT as tool-call approvals. Platform builders who want full
+ * control over the review UI use this hook directly; those who prefer a drop-in
+ * surface use {@link FileReviewCard}, which accepts the callback shape this
+ * hook produces.
+ *
+ * @example
+ * ```tsx
+ * const { submitFileDecision, submittingDecisionKeys } = useFileReview();
+ *
+ * // Approve the whole change set:
+ * await submitFileDecision(executionId, changeSet.id, FileDecisionAction.APPROVE, {
+ *   expectedDigest: changeSet.aggregateDigest,
+ * });
+ * ```
+ */
+export declare function useFileReview(): UseFileReviewReturn;
+//# sourceMappingURL=useFileReview.d.ts.map

package/execution/useFileReview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFileReview.d.ts","sourceRoot":"","sources":["../../src/execution/useFileReview.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,8DAA8D,CAAC;AAKtE,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAC5C;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,EAAE,CAC3B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,CAAC,EAAE,mBAAmB,KAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrD;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACpD,iFAAiF;IACjF,QAAQ,CAAC,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAElF;AAKD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,IAAI,mBAAmB,CAqFnD"}

package/execution/useFileReview.js

@@ -0,0 +1,106 @@
+"use client";
+import { useCallback, useMemo, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { FileDecisionScope, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { SubmitFileDecisionInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+/**
+ * The loading-state key for a file decision: the change set id for a whole-set
+ * (CHANGE_SET) decision, or `changeSetId:fileChangeId` for a per-file one.
+ */
+export function fileDecisionKey(changeSetId, fileChangeId) {
+    return fileChangeId ? `${changeSetId}:${fileChangeId}` : changeSetId;
+}
+/** A stable empty map so an error-free hook keeps a constant `decisionErrors` ref. */
+const NO_DECISION_ERRORS = new Map();
+/**
+ * Behavior hook that wraps `agentExecution.submitFileDecision()` with per-decision
+ * loading state and error management — the file-review sibling of
+ * {@link useSubmitApproval}.
+ *
+ * File edits are reviewed as a captured change set (the `file_change_sets`
+ * projection), NOT as tool-call approvals. Platform builders who want full
+ * control over the review UI use this hook directly; those who prefer a drop-in
+ * surface use {@link FileReviewCard}, which accepts the callback shape this
+ * hook produces.
+ *
+ * @example
+ * ```tsx
+ * const { submitFileDecision, submittingDecisionKeys } = useFileReview();
+ *
+ * // Approve the whole change set:
+ * await submitFileDecision(executionId, changeSet.id, FileDecisionAction.APPROVE, {
+ *   expectedDigest: changeSet.aggregateDigest,
+ * });
+ * ```
+ */
+export function useFileReview() {
+    const stigmer = useStigmer();
+    const [submittingKeys, setSubmittingKeys] = useState(new Set());
+    const [decisionErrors, setDecisionErrors] = useState(NO_DECISION_ERRORS);
+    const [error, setError] = useState(null);
+    const clearDecisionError = useCallback((key) => {
+        setDecisionErrors((prev) => {
+            if (!prev.has(key))
+                return prev;
+            const next = new Map(prev);
+            next.delete(key);
+            return next;
+        });
+    }, []);
+    const clearError = useCallback(() => {
+        setDecisionErrors(NO_DECISION_ERRORS);
+        setError(null);
+    }, []);
+    const submitFileDecision = useCallback(async (executionId, changeSetId, action, options) => {
+        const fileChangeId = options?.fileChangeId ?? "";
+        const scope = options?.scope ??
+            (fileChangeId ? FileDecisionScope.FILE : FileDecisionScope.CHANGE_SET);
+        const key = fileDecisionKey(changeSetId, fileChangeId || undefined);
+        setSubmittingKeys((prev) => {
+            const next = new Set(prev);
+            next.add(key);
+            return next;
+        });
+        // Clear this target's prior failure (and the scalar mirror) so a retry
+        // starts clean — the map and `error` are updated together, never drift.
+        clearDecisionError(key);
+        setError(null);
+        try {
+            const input = create(SubmitFileDecisionInputSchema, {
+                agentExecutionId: executionId,
+                changeSetId,
+                scope,
+                fileChangeId,
+                action,
+                expectedDigest: options?.expectedDigest ?? "",
+                reason: options?.reason ?? "",
+                acknowledgeUnreviewable: options?.acknowledgeUnreviewable ?? false,
+            });
+            await stigmer.agentExecution.submitFileDecision(input);
+        }
+        catch (err) {
+            const e = toError(err);
+            setDecisionErrors((prev) => new Map(prev).set(key, e));
+            setError(e);
+            throw err;
+        }
+        finally {
+            setSubmittingKeys((prev) => {
+                const next = new Set(prev);
+                next.delete(key);
+                return next;
+            });
+        }
+    }, [stigmer, clearDecisionError]);
+    return useMemo(() => ({
+        submitFileDecision,
+        submittingDecisionKeys: submittingKeys,
+        decisionErrors,
+        clearDecisionError,
+        error,
+        clearError,
+    }), [submitFileDecision, submittingKeys, decisionErrors, clearDecisionError, error, clearError]);
+}
+//# sourceMappingURL=useFileReview.js.map

package/execution/useFileReview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFileReview.js","sourceRoot":"","sources":["../../src/execution/useFileReview.ts"],"names":[],"mappings":"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"}

package/execution/useSubmitApproval.d.ts

@@ -13,9 +13,24 @@ export interface UseSubmitApprovalReturn {
      * approve one tool while another decision is still in flight.
      */
     readonly submittingToolCallIds: ReadonlySet<string>;
-    /** Error from the last failed approval submission, or `null` when healthy. */
+    /**
+     * Per-tool-call failures, keyed by `toolCallId` exactly like
+     * {@link submittingToolCallIds}. This is the per-target parallel of the
+     * in-flight Set: a thread can hold many simultaneous gates (one per inline
+     * tool row, plus the bottom backstop), so a failure must be attributable to
+     * the *one* gate that failed — a single scalar cannot say which. {@link
+     * ApprovalCard} / {@link ApprovalCardBody} consume this (threaded via
+     * {@link ApprovalContext}) to render the error in-card, beside the failed gate.
+     */
+    readonly errorsByToolCallId: ReadonlyMap<string, Error>;
+    /**
+     * Error from the last failed approval submission, or `null` when healthy — a
+     * convenience mirror of {@link errorsByToolCallId} for a headless consumer
+     * that wants a single error value (e.g. a banner, or the `ink` surface). The
+     * map is authoritative for per-gate surfacing.
+     */
     readonly error: Error | null;
-    /** Reset `error` to `null`. */
+    /** Reset every approval error (both {@link errorsByToolCallId} and {@link error}). */
     readonly clearError: () => void;
 }
 /**

package/execution/useSubmitApproval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSubmitApproval.d.ts","sourceRoot":"","sources":["../../src/execution/useSubmitApproval.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAC;AAK9F,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,CACvB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpD,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CA8C3D"}
+{"version":3,"file":"useSubmitApproval.d.ts","sourceRoot":"","sources":["../../src/execution/useSubmitApproval.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAC;AAM9F,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,CACvB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpD;;;;;;;;OAQG;IACH,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACxD;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CAoD3D"}

package/execution/useSubmitApproval.js

@@ -1,9 +1,10 @@
 "use client";
-import { useCallback, useState } from "react";
+import { useCallback, useMemo, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import { SubmitApprovalInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
+import { useKeyedSubmission } from "../internal/useKeyedSubmission";
 /**
  * Behavior hook that wraps `agentExecution.submitApproval()` with
  * per-tool-call loading state and error management.
@@ -26,37 +27,40 @@ import { toError } from "../internal/toError";
  */
 export function useSubmitApproval() {
     const stigmer = useStigmer();
-    const [submittingIds, setSubmittingIds] = useState(new Set());
+    // Per-gate in-flight + error state, keyed by tool-call id, lives in the
+    // shared keyed-submission primitive. The scalar `error` below is a thin
+    // mirror kept in lockstep for headless / ink consumers.
+    const keyed = useKeyedSubmission();
     const [error, setError] = useState(null);
-    const clearError = useCallback(() => setError(null), []);
+    const clearError = useCallback(() => {
+        keyed.clearErrors();
+        setError(null);
+    }, [keyed.clearErrors]);
     const submitApproval = useCallback(async (executionId, toolCallId, action, comment) => {
-        setSubmittingIds((prev) => {
-            const next = new Set(prev);
-            next.add(toolCallId);
-            return next;
-        });
+        // Clear the scalar mirror at submit-start; `keyed.run` clears this gate's
+        // keyed entry, so the map and `error` are updated together and never drift.
         setError(null);
         try {
-            const input = create(SubmitApprovalInputSchema, {
-                agentExecutionId: executionId,
-                toolCallId,
-                action,
-                comment: comment ?? "",
+            await keyed.run(toolCallId, async () => {
+                await stigmer.agentExecution.submitApproval(create(SubmitApprovalInputSchema, {
+                    agentExecutionId: executionId,
+                    toolCallId,
+                    action,
+                    comment: comment ?? "",
+                }));
             });
-            await stigmer.agentExecution.submitApproval(input);
         }
         catch (err) {
             setError(toError(err));
             throw err;
         }
-        finally {
-            setSubmittingIds((prev) => {
-                const next = new Set(prev);
-                next.delete(toolCallId);
-                return next;
-            });
-        }
-    }, [stigmer]);
-    return { submitApproval, submittingToolCallIds: submittingIds, error, clearError };
+    }, [stigmer, keyed.run]);
+    return useMemo(() => ({
+        submitApproval,
+        submittingToolCallIds: keyed.submittingKeys,
+        errorsByToolCallId: keyed.errorsByKey,
+        error,
+        clearError,
+    }), [submitApproval, keyed.submittingKeys, keyed.errorsByKey, error, clearError]);
 }
 //# sourceMappingURL=useSubmitApproval.js.map

package/execution/useSubmitApproval.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSubmitApproval.js","sourceRoot":"","sources":["../../src/execution/useSubmitApproval.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,4DAA4D,CAAC;AACvG,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AA2B9C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAChD,IAAI,GAAG,EAAE,CACV,CAAC;IACF,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IAEvD,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAEzD,MAAM,cAAc,GAAG,WAAW,CAChC,KAAK,EACH,WAAmB,EACnB,UAAkB,EAClB,MAAsB,EACtB,OAAgB,EACD,EAAE;QACjB,gBAAgB,CAAC,CAAC,IAAI,EAAE,EAAE;YACxB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,CAAC,yBAAyB,EAAE;gBAC9C,gBAAgB,EAAE,WAAW;gBAC7B,UAAU;gBACV,MAAM;gBACN,OAAO,EAAE,OAAO,IAAI,EAAE;aACvB,CAAC,CAAC;YACH,MAAM,OAAO,CAAC,cAAc,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YACvB,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,gBAAgB,CAAC,CAAC,IAAI,EAAE,EAAE;gBACxB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;gBAC3B,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;gBACxB,OAAO,IAAI,CAAC;YACd,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,aAAa,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AACrF,CAAC"}
+{"version":3,"file":"useSubmitApproval.js","sourceRoot":"","sources":["../../src/execution/useSubmitApproval.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,4DAA4D,CAAC;AACvG,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AA0CpE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,wEAAwE;IACxE,wEAAwE;IACxE,wDAAwD;IACxD,MAAM,KAAK,GAAG,kBAAkB,EAAQ,CAAC;IACzC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IAEvD,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;QAClC,KAAK,CAAC,WAAW,EAAE,CAAC;QACpB,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;IAExB,MAAM,cAAc,GAAG,WAAW,CAChC,KAAK,EACH,WAAmB,EACnB,UAAkB,EAClB,MAAsB,EACtB,OAAgB,EACD,EAAE;QACjB,0EAA0E;QAC1E,4EAA4E;QAC5E,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,IAAI,EAAE;gBACrC,MAAM,OAAO,CAAC,cAAc,CAAC,cAAc,CACzC,MAAM,CAAC,yBAAyB,EAAE;oBAChC,gBAAgB,EAAE,WAAW;oBAC7B,UAAU;oBACV,MAAM;oBACN,OAAO,EAAE,OAAO,IAAI,EAAE;iBACvB,CAAC,CACH,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YACvB,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,EACD,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CACrB,CAAC;IAEF,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC;QACL,cAAc;QACd,qBAAqB,EAAE,KAAK,CAAC,cAAc;QAC3C,kBAAkB,EAAE,KAAK,CAAC,WAAW;QACrC,KAAK;QACL,UAAU;KACX,CAAC,EACF,CAAC,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,EAAE,UAAU,CAAC,CAC7E,CAAC;AACJ,CAAC"}