@stigmer/react 0.0.52 → 0.0.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/react",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "description": "React provider and client hook for the Stigmer platform SDK",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,7 +31,7 @@
     "./styles.css": "./styles.css"
   },
   "dependencies": {
-    "@stigmer/theme": "0.0.52",
+    "@stigmer/theme": "0.0.54",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
     "yaml": "^2.8.2"
@@ -39,8 +39,8 @@
   "peerDependencies": {
     "@base-ui/react": "^1.0.0",
     "@bufbuild/protobuf": "^2.0.0",
-    "@stigmer/protos": "0.0.52",
-    "@stigmer/sdk": "0.0.52",
+    "@stigmer/protos": "0.0.54",
+    "@stigmer/sdk": "0.0.54",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   }

package/provider.d.ts

@@ -1,10 +1,22 @@
 import type { ReactNode } from "react";
-import type { Stigmer } from "@stigmer/sdk";
+import type { Stigmer, DeploymentMode } from "@stigmer/sdk";
 import type { ThemePresetId } from "@stigmer/theme";
 export interface StigmerProviderProps {
     /** A configured {@link Stigmer} client instance. */
     readonly client: Stigmer;
     readonly children: ReactNode;
+    /**
+     * Deployment mode of the connected Stigmer backend.
+     *
+     * - `"local"` — local Go CLI server (OSS). Cloud-only resources
+     *   (API keys, IAM, identity management) are unavailable.
+     * - `"cloud"` — Stigmer Cloud. All resources are available.
+     *
+     * Defaults to `"cloud"` so existing consumers see no change.
+     * The Stigmer Console derives this from the API URL hostname.
+     * Platform builders pass it based on their deployment context.
+     */
+    readonly deploymentMode?: DeploymentMode;
     /**
      * Built-in theme preset to apply.
      *
@@ -51,5 +63,5 @@ export interface StigmerProviderProps {
  * </StigmerProvider>
  * ```
  */
-export declare function StigmerProvider({ client, children, preset, className, }: StigmerProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function StigmerProvider({ client, children, deploymentMode, preset, className, }: StigmerProviderProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=provider.d.ts.map

package/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EACN,QAAQ,EACR,MAAM,EACN,SAAS,GACV,EAAE,oBAAoB,2CAQtB"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EACN,QAAQ,EACR,cAAwB,EACxB,MAAM,EACN,SAAS,GACV,EAAE,oBAAoB,2CAUtB"}

package/provider.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn, resolvePresetClass } from "@stigmer/theme";
 import { StigmerContext } from "./context";
+import { DeploymentModeContext } from "./deployment-mode";
 /**
  * React provider that distributes a {@link Stigmer} SDK client to
  * descendant components via {@link StigmerContext}.
@@ -27,8 +28,8 @@ import { StigmerContext } from "./context";
  * </StigmerProvider>
  * ```
  */
-export function StigmerProvider({ client, children, preset, className, }) {
+export function StigmerProvider({ client, children, deploymentMode = "cloud", preset, className, }) {
     const presetClass = preset ? resolvePresetClass(preset) : "";
-    return (_jsx(StigmerContext.Provider, { value: client, children: _jsx("div", { className: cn("stgm", presetClass, className), children: children }) }));
+    return (_jsx(StigmerContext.Provider, { value: client, children: _jsx(DeploymentModeContext.Provider, { value: deploymentMode, children: _jsx("div", { className: cn("stgm", presetClass, className), children: children }) }) }));
 }
 //# sourceMappingURL=provider.js.map

package/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAIb,OAAO,EAAE,EAAE,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AA4B3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,MAAM,EACN,QAAQ,EACR,MAAM,EACN,SAAS,GACY;IACrB,MAAM,WAAW,GAAG,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE7D,OAAO,CACL,KAAC,cAAc,CAAC,QAAQ,IAAC,KAAK,EAAE,MAAM,YACpC,cAAK,SAAS,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,CAAC,YAAG,QAAQ,GAAO,GAC5C,CAC3B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAIb,OAAO,EAAE,EAAE,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAwC1D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,MAAM,EACN,QAAQ,EACR,cAAc,GAAG,OAAO,EACxB,MAAM,EACN,SAAS,GACY;IACrB,MAAM,WAAW,GAAG,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE7D,OAAO,CACL,KAAC,cAAc,CAAC,QAAQ,IAAC,KAAK,EAAE,MAAM,YACpC,KAAC,qBAAqB,CAAC,QAAQ,IAAC,KAAK,EAAE,cAAc,YACnD,cAAK,SAAS,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,CAAC,YAAG,QAAQ,GAAO,GACrC,GACT,CAC3B,CAAC;AACJ,CAAC"}

package/session/index.d.ts

@@ -10,6 +10,10 @@ export { useSessionExecutions } from "./useSessionExecutions";
 export type { UseSessionExecutionsReturn } from "./useSessionExecutions";
 export { useSessionConversation } from "./useSessionConversation";
 export type { SendFollowUpOptions, UseSessionConversationReturn, } from "./useSessionConversation";
+export { useSessionArtifacts } from "./useSessionArtifacts";
+export type { SessionArtifactEntry, UseSessionArtifactsReturn, } from "./useSessionArtifacts";
+export { useSessionWriteBacks } from "./useSessionWriteBacks";
+export type { SessionWriteBackEntry, UseSessionWriteBacksReturn, } from "./useSessionWriteBacks";
 export { useAgentRefFromSession } from "./useAgentRefFromSession";
 export type { UseAgentRefFromSessionReturn } from "./useAgentRefFromSession";
 export { groupSessionsByTime } from "./group-sessions";

package/session/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEjE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EACV,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAEzE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EACV,mBAAmB,EACnB,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAE7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEjE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EACV,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAEzE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EACV,mBAAmB,EACnB,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EACV,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EACV,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAE7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/session/index.js

@@ -4,6 +4,8 @@ export { useSession } from "./useSession";
 export { useSessionList } from "./useSessionList";
 export { useSessionExecutions } from "./useSessionExecutions";
 export { useSessionConversation } from "./useSessionConversation";
+export { useSessionArtifacts } from "./useSessionArtifacts";
+export { useSessionWriteBacks } from "./useSessionWriteBacks";
 export { useAgentRefFromSession } from "./useAgentRefFromSession";
 export { groupSessionsByTime } from "./group-sessions";
 // Session utilities (re-exported from @stigmer/sdk)

package/session/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAOtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAMlD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAMlE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGvD,oDAAoD;AACpD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAOtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAMlD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAMlE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAM5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAM9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGvD,oDAAoD;AACpD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/session/useSessionArtifacts.d.ts

@@ -0,0 +1,73 @@
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+/**
+ * A single artifact entry enriched with the execution context needed
+ * for content fetching and Apply/Push gating.
+ *
+ * The `executionId` identifies which execution produced (or last
+ * updated) this artifact — required by {@link useArtifactContent} and
+ * {@link ArtifactPreviewModal}. `isTerminal` controls whether the
+ * Apply CTA is enabled in the preview modal.
+ */
+export interface SessionArtifactEntry {
+    readonly artifact: ExecutionArtifact;
+    /** ID of the execution that produced this artifact version. */
+    readonly executionId: string;
+    /** Whether the producing execution is in a terminal phase. */
+    readonly isTerminal: boolean;
+    /**
+     * `true` when another artifact in the deduplicated list shares the
+     * same display `name` but has a different `sandbox_path`. Consumers
+     * use this to render path context for disambiguation.
+     */
+    readonly hasNameCollision: boolean;
+}
+export interface UseSessionArtifactsReturn {
+    /** Deduplicated, alphabetically-sorted artifacts from all executions. */
+    readonly artifacts: readonly SessionArtifactEntry[];
+    /** `true` when there is at least one artifact across all executions. */
+    readonly hasArtifacts: boolean;
+    /** Total number of deduplicated artifacts. */
+    readonly artifactCount: number;
+}
+/**
+ * Pure derivation hook that aggregates artifacts across all executions
+ * in a session into a unified, deduplicated, alphabetically-sorted
+ * list — like a file explorer showing the conversation's output.
+ *
+ * Follows the same `useMemo`-based pattern as
+ * {@link useExecutionArtifacts}: no side effects, no data fetching.
+ *
+ * **Dedup semantics:** Artifacts are keyed by `sandbox_path` (the
+ * original filesystem path in the agent sandbox). When multiple
+ * executions produce an artifact at the same path, the latest
+ * execution's version wins — matching filesystem overwrite semantics.
+ *
+ * **Sorting:** Entries are sorted alphabetically by display `name`
+ * (case-insensitive). This matches the file-explorer mental model
+ * where users scan by filename, not by creation order.
+ *
+ * **Name collision detection:** When two artifacts share the same
+ * display `name` but differ in `sandbox_path`, both entries are
+ * flagged with `hasNameCollision: true` so consumers can render path
+ * context for disambiguation.
+ *
+ * @param executions - All executions for a session, in chronological
+ *   order (as returned by `listBySession`). Pass both completed and
+ *   active-stream executions.
+ *
+ * @example
+ * ```tsx
+ * const conv = useSessionConversation(sessionId, org);
+ * const allExecutions = [
+ *   ...conv.completedExecutions,
+ *   ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ * ];
+ * const { artifacts, hasArtifacts } = useSessionArtifacts(allExecutions);
+ * ```
+ *
+ * @see useExecutionArtifacts — single-execution artifact derivation
+ * @see ArtifactsWidget — styled component that renders this data
+ */
+export declare function useSessionArtifacts(executions: readonly AgentExecution[]): UseSessionArtifactsReturn;
+//# sourceMappingURL=useSessionArtifacts.d.ts.map

package/session/useSessionArtifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSessionArtifacts.d.ts","sourceRoot":"","sources":["../../src/session/useSessionArtifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kEAAkE,CAAC;AAI1G;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,yBAAyB;IACxC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACpD,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,cAAc,EAAE,GACpC,yBAAyB,CAoD3B"}

package/session/useSessionArtifacts.js

@@ -0,0 +1,95 @@
+"use client";
+import { useMemo } from "react";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { isTerminalPhase } from "../execution/execution-phases";
+/**
+ * Returns the dedup key for an artifact. Uses `sandbox_path` when
+ * available (stable filesystem identity within the session sandbox),
+ * falling back to `name` for older artifacts that predate the field.
+ */
+function dedupKey(artifact) {
+    return artifact.sandboxPath || artifact.name;
+}
+/**
+ * Pure derivation hook that aggregates artifacts across all executions
+ * in a session into a unified, deduplicated, alphabetically-sorted
+ * list — like a file explorer showing the conversation's output.
+ *
+ * Follows the same `useMemo`-based pattern as
+ * {@link useExecutionArtifacts}: no side effects, no data fetching.
+ *
+ * **Dedup semantics:** Artifacts are keyed by `sandbox_path` (the
+ * original filesystem path in the agent sandbox). When multiple
+ * executions produce an artifact at the same path, the latest
+ * execution's version wins — matching filesystem overwrite semantics.
+ *
+ * **Sorting:** Entries are sorted alphabetically by display `name`
+ * (case-insensitive). This matches the file-explorer mental model
+ * where users scan by filename, not by creation order.
+ *
+ * **Name collision detection:** When two artifacts share the same
+ * display `name` but differ in `sandbox_path`, both entries are
+ * flagged with `hasNameCollision: true` so consumers can render path
+ * context for disambiguation.
+ *
+ * @param executions - All executions for a session, in chronological
+ *   order (as returned by `listBySession`). Pass both completed and
+ *   active-stream executions.
+ *
+ * @example
+ * ```tsx
+ * const conv = useSessionConversation(sessionId, org);
+ * const allExecutions = [
+ *   ...conv.completedExecutions,
+ *   ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ * ];
+ * const { artifacts, hasArtifacts } = useSessionArtifacts(allExecutions);
+ * ```
+ *
+ * @see useExecutionArtifacts — single-execution artifact derivation
+ * @see ArtifactsWidget — styled component that renders this data
+ */
+export function useSessionArtifacts(executions) {
+    return useMemo(() => {
+        const entryMap = new Map();
+        for (const execution of executions) {
+            const executionId = execution.metadata?.id ?? "";
+            const phase = execution.status?.phase ??
+                ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+            const terminal = isTerminalPhase(phase);
+            for (const artifact of execution.status?.artifacts ?? []) {
+                const key = dedupKey(artifact);
+                entryMap.set(key, {
+                    artifact,
+                    executionId,
+                    isTerminal: terminal,
+                    hasNameCollision: false,
+                });
+            }
+        }
+        const entries = Array.from(entryMap.values());
+        entries.sort((a, b) => a.artifact.name.localeCompare(b.artifact.name, undefined, {
+            sensitivity: "base",
+        }));
+        // Detect name collisions: entries that share a display name but
+        // have different sandbox paths need path context for disambiguation.
+        const nameCount = new Map();
+        for (const entry of entries) {
+            const lower = entry.artifact.name.toLowerCase();
+            nameCount.set(lower, (nameCount.get(lower) ?? 0) + 1);
+        }
+        const result = entries.map((entry) => {
+            const lower = entry.artifact.name.toLowerCase();
+            if ((nameCount.get(lower) ?? 0) > 1) {
+                return { ...entry, hasNameCollision: true };
+            }
+            return entry;
+        });
+        return {
+            artifacts: result,
+            hasArtifacts: result.length > 0,
+            artifactCount: result.length,
+        };
+    }, [executions]);
+}
+//# sourceMappingURL=useSessionArtifacts.js.map

package/session/useSessionArtifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSessionArtifacts.js","sourceRoot":"","sources":["../../src/session/useSessionArtifacts.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAGhC,OAAO,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAkChE;;;;GAIG;AACH,SAAS,QAAQ,CAAC,QAA2B;IAC3C,OAAO,QAAQ,CAAC,WAAW,IAAI,QAAQ,CAAC,IAAI,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAAqC;IAErC,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAgC,CAAC;QAEzD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,MAAM,WAAW,GAAG,SAAS,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC;YACjD,MAAM,KAAK,GACT,SAAS,CAAC,MAAM,EAAE,KAAK;gBACvB,cAAc,CAAC,2BAA2B,CAAC;YAC7C,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;YAExC,KAAK,MAAM,QAAQ,IAAI,SAAS,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,EAAE,CAAC;gBACzD,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBAC/B,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE;oBAChB,QAAQ;oBACR,WAAW;oBACX,UAAU,EAAE,QAAQ;oBACpB,gBAAgB,EAAE,KAAK;iBACxB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QAE9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACpB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE;YACxD,WAAW,EAAE,MAAM;SACpB,CAAC,CACH,CAAC;QAEF,gEAAgE;QAChE,qEAAqE;QACrE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC5C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAChD,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACxD,CAAC;QAED,MAAM,MAAM,GAA2B,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAChD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpC,OAAO,EAAE,GAAG,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;YAC9C,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,SAAS,EAAE,MAAM;YACjB,YAAY,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC;YAC/B,aAAa,EAAE,MAAM,CAAC,MAAM;SAC7B,CAAC;IACJ,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;AACnB,CAAC"}

package/session/useSessionWriteBacks.d.ts

@@ -0,0 +1,56 @@
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
+/**
+ * A single write-back entry enriched with the execution context that
+ * produced it.
+ *
+ * The `executionId` links the write-back to its originating execution
+ * for traceability in the UI (e.g., tooltip or detail view).
+ */
+export interface SessionWriteBackEntry {
+    readonly writeBack: WorkspaceWriteBack;
+    /** ID of the execution that produced this write-back. */
+    readonly executionId: string;
+}
+export interface UseSessionWriteBacksReturn {
+    /** All write-backs from the session, ordered by workspace entry name. */
+    readonly writeBacks: readonly SessionWriteBackEntry[];
+    /** `true` when there is at least one write-back across all executions. */
+    readonly hasWriteBacks: boolean;
+    /** Total number of write-backs. */
+    readonly writeBackCount: number;
+}
+/**
+ * Pure derivation hook that aggregates workspace write-backs across all
+ * executions in a session into a flat, deduplicated list.
+ *
+ * Follows the same pattern as {@link useSessionArtifacts}: `useMemo`-based
+ * derivation, no side effects, no data fetching. Takes the same
+ * `executions` array input.
+ *
+ * **Dedup semantics:** Write-backs are keyed by `workspace_entry_name`.
+ * When multiple executions write back to the same workspace entry (e.g.,
+ * a follow-up execution on the same git repo), the latest execution's
+ * write-back wins — each execution creates its own branch/PR, and the
+ * most recent one is the one users care about.
+ *
+ * **Sorting:** Entries are sorted alphabetically by workspace entry name.
+ *
+ * @param executions - All executions for a session, in chronological
+ *   order. Pass both completed and active-stream executions.
+ *
+ * @example
+ * ```tsx
+ * const conv = useSessionConversation(sessionId, org);
+ * const allExecutions = [
+ *   ...conv.completedExecutions,
+ *   ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ * ];
+ * const { writeBacks, hasWriteBacks } = useSessionWriteBacks(allExecutions);
+ * ```
+ *
+ * @see useWorkspaceWriteBacks — single-execution write-back derivation
+ * @see WriteBackCard — component that renders a single write-back
+ */
+export declare function useSessionWriteBacks(executions: readonly AgentExecution[]): UseSessionWriteBacksReturn;
+//# sourceMappingURL=useSessionWriteBacks.d.ts.map

package/session/useSessionWriteBacks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSessionWriteBacks.d.ts","sourceRoot":"","sources":["../../src/session/useSessionWriteBacks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mEAAmE,CAAC;AAE5G;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,0BAA0B;IACzC,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACtD,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,mCAAmC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,SAAS,cAAc,EAAE,GACpC,0BAA0B,CA+B5B"}

package/session/useSessionWriteBacks.js

@@ -0,0 +1,56 @@
+"use client";
+import { useMemo } from "react";
+/**
+ * Pure derivation hook that aggregates workspace write-backs across all
+ * executions in a session into a flat, deduplicated list.
+ *
+ * Follows the same pattern as {@link useSessionArtifacts}: `useMemo`-based
+ * derivation, no side effects, no data fetching. Takes the same
+ * `executions` array input.
+ *
+ * **Dedup semantics:** Write-backs are keyed by `workspace_entry_name`.
+ * When multiple executions write back to the same workspace entry (e.g.,
+ * a follow-up execution on the same git repo), the latest execution's
+ * write-back wins — each execution creates its own branch/PR, and the
+ * most recent one is the one users care about.
+ *
+ * **Sorting:** Entries are sorted alphabetically by workspace entry name.
+ *
+ * @param executions - All executions for a session, in chronological
+ *   order. Pass both completed and active-stream executions.
+ *
+ * @example
+ * ```tsx
+ * const conv = useSessionConversation(sessionId, org);
+ * const allExecutions = [
+ *   ...conv.completedExecutions,
+ *   ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ * ];
+ * const { writeBacks, hasWriteBacks } = useSessionWriteBacks(allExecutions);
+ * ```
+ *
+ * @see useWorkspaceWriteBacks — single-execution write-back derivation
+ * @see WriteBackCard — component that renders a single write-back
+ */
+export function useSessionWriteBacks(executions) {
+    return useMemo(() => {
+        const entryMap = new Map();
+        for (const execution of executions) {
+            const executionId = execution.metadata?.id ?? "";
+            for (const wb of execution.status?.workspaceWriteBacks ?? []) {
+                entryMap.set(wb.workspaceEntryName, {
+                    writeBack: wb,
+                    executionId,
+                });
+            }
+        }
+        const entries = Array.from(entryMap.values());
+        entries.sort((a, b) => a.writeBack.workspaceEntryName.localeCompare(b.writeBack.workspaceEntryName, undefined, { sensitivity: "base" }));
+        return {
+            writeBacks: entries,
+            hasWriteBacks: entries.length > 0,
+            writeBackCount: entries.length,
+        };
+    }, [executions]);
+}
+//# sourceMappingURL=useSessionWriteBacks.js.map

package/session/useSessionWriteBacks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSessionWriteBacks.js","sourceRoot":"","sources":["../../src/session/useSessionWriteBacks.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AA0BhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAqC;IAErC,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAiC,CAAC;QAE1D,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,MAAM,WAAW,GAAG,SAAS,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC;YAEjD,KAAK,MAAM,EAAE,IAAI,SAAS,CAAC,MAAM,EAAE,mBAAmB,IAAI,EAAE,EAAE,CAAC;gBAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,kBAAkB,EAAE;oBAClC,SAAS,EAAE,EAAE;oBACb,WAAW;iBACZ,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QAE9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACpB,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,aAAa,CAC1C,CAAC,CAAC,SAAS,CAAC,kBAAkB,EAC9B,SAAS,EACT,EAAE,WAAW,EAAE,MAAM,EAAE,CACxB,CACF,CAAC;QAEF,OAAO;YACL,UAAU,EAAE,OAAO;YACnB,aAAa,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC;YACjC,cAAc,EAAE,OAAO,CAAC,MAAM;SAC/B,CAAC;IACJ,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;AACnB,CAAC"}

package/src/deployment-mode.ts

@@ -0,0 +1,46 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import type { DeploymentMode } from "@stigmer/sdk";
+import { isResourceAvailable, ApiResourceKind } from "@stigmer/sdk";
+
+/**
+ * React context for the current deployment mode.
+ *
+ * Separated from the provider to mirror the `StigmerContext` / `context.ts`
+ * pattern and avoid circular imports.
+ *
+ * Defaults to `"cloud"` so existing consumers who don't pass
+ * `deploymentMode` to `StigmerProvider` see all features enabled.
+ */
+export const DeploymentModeContext = createContext<DeploymentMode>("cloud");
+
+/**
+ * Read the deployment mode from the nearest `StigmerProvider`.
+ *
+ * Returns `"local"` when connected to the local Go CLI server (OSS)
+ * and `"cloud"` when connected to Stigmer Cloud.
+ */
+export function useDeploymentMode(): DeploymentMode {
+  return useContext(DeploymentModeContext);
+}
+
+/**
+ * Check whether a given {@link ApiResourceKind} is available in the
+ * current deployment mode.
+ *
+ * Combines the deployment mode from context with the proto-derived
+ * tier metadata via {@link isResourceAvailable}.
+ *
+ * @example
+ * ```tsx
+ * const available = useResourceAvailable(ApiResourceKind.api_key);
+ * if (!available) return <CloudFeatureNotice>...</CloudFeatureNotice>;
+ * ```
+ */
+export function useResourceAvailable(kind: ApiResourceKind): boolean {
+  const mode = useDeploymentMode();
+  return isResourceAvailable(kind, mode);
+}
+
+export { type DeploymentMode, ApiResourceKind };