@stigmer/react 0.0.36 → 0.0.40

package/execution/useArtifactContent.d.ts

@@ -0,0 +1,75 @@
+export interface UseArtifactContentReturn {
+    /**
+     * Decoded text content of the artifact, or `null` when:
+     * - Fetching is skipped (`executionId` or `storageKey` is `null`)
+     * - The request is in-flight
+     * - The request failed
+     */
+    readonly content: string | null;
+    /**
+     * Detected content type (e.g., `"text/yaml"`, `"text/plain"`).
+     * `null` before the first successful fetch.
+     */
+    readonly contentType: string | null;
+    /**
+     * Whether the returned content was truncated by the server's
+     * `max_bytes` limit. When `true`, the full artifact should be
+     * downloaded via `getArtifactDownloadUrl` instead.
+     */
+    readonly isTruncated: boolean;
+    /** `true` while the content request is in-flight. */
+    readonly isLoading: boolean;
+    /** Error message from the last failed attempt, or `null` when healthy. */
+    readonly error: string | null;
+    /**
+     * Re-fetch the artifact content. Uses the `fetchKey` counter pattern
+     * consistent with `refetch()` in other SDK hooks.
+     */
+    readonly refetch: () => void;
+}
+/**
+ * Data hook that fetches the text content of a single execution artifact
+ * via `stigmer.agentExecution.getArtifactContent()`.
+ *
+ * The server reads the artifact from R2 and returns the bytes through the
+ * Stigmer API, eliminating CORS concerns for SDK consumers who need to
+ * read artifact content programmatically (YAML detection, preview
+ * rendering, resource type identification).
+ *
+ * Pass `null` for either parameter to skip fetching — consistent with
+ * the `useExecutionStream(null)` convention. The caller controls when
+ * to fetch based on artifact metadata (e.g., only for text artifacts
+ * below a size threshold):
+ *
+ * ```tsx
+ * const shouldFetch = isTextArtifact(artifact) && Number(artifact.sizeBytes) < MAX_SIZE;
+ * const { content } = useArtifactContent(
+ *   shouldFetch ? executionId : null,
+ *   shouldFetch ? artifact.storageKey : null,
+ * );
+ * ```
+ *
+ * For directory artifacts (ZIPs), pass `entryPath` to extract a specific
+ * file from the archive instead of returning the raw ZIP bytes:
+ *
+ * ```tsx
+ * const { content } = useArtifactContent(executionId, storageKey, "SKILL.md");
+ * ```
+ *
+ * The server enforces a content size limit (default 512 KB). Content
+ * exceeding this limit is truncated — check `isTruncated` and offer
+ * a full download via the pre-signed URL for large artifacts.
+ *
+ * The returned `content` is decoded from UTF-8 bytes. For binary
+ * artifacts, use `getArtifactDownloadUrl` instead of this hook.
+ *
+ * @param executionId - Execution that produced the artifact, or `null` to skip.
+ * @param storageKey - Storage key from `ExecutionArtifact.storageKey`, or `null` to skip.
+ * @param entryPath - For directory artifacts: relative path of a file within
+ *   the archive to extract. `null` returns the full artifact (existing behavior).
+ *
+ * @see useExecutionArtifacts — extracts artifact metadata from an execution
+ * @see isTextArtifact — heuristic for whether content is fetchable as text
+ */
+export declare function useArtifactContent(executionId: string | null, storageKey: string | null, entryPath?: string | null): UseArtifactContentReturn;
+//# sourceMappingURL=useArtifactContent.d.ts.map

package/execution/useArtifactContent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useArtifactContent.d.ts","sourceRoot":"","sources":["../../src/execution/useArtifactContent.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GACxB,wBAAwB,CAiE1B"}

package/execution/useArtifactContent.js

@@ -0,0 +1,102 @@
+"use client";
+import { useCallback, useEffect, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { GetArtifactContentRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+/**
+ * Data hook that fetches the text content of a single execution artifact
+ * via `stigmer.agentExecution.getArtifactContent()`.
+ *
+ * The server reads the artifact from R2 and returns the bytes through the
+ * Stigmer API, eliminating CORS concerns for SDK consumers who need to
+ * read artifact content programmatically (YAML detection, preview
+ * rendering, resource type identification).
+ *
+ * Pass `null` for either parameter to skip fetching — consistent with
+ * the `useExecutionStream(null)` convention. The caller controls when
+ * to fetch based on artifact metadata (e.g., only for text artifacts
+ * below a size threshold):
+ *
+ * ```tsx
+ * const shouldFetch = isTextArtifact(artifact) && Number(artifact.sizeBytes) < MAX_SIZE;
+ * const { content } = useArtifactContent(
+ *   shouldFetch ? executionId : null,
+ *   shouldFetch ? artifact.storageKey : null,
+ * );
+ * ```
+ *
+ * For directory artifacts (ZIPs), pass `entryPath` to extract a specific
+ * file from the archive instead of returning the raw ZIP bytes:
+ *
+ * ```tsx
+ * const { content } = useArtifactContent(executionId, storageKey, "SKILL.md");
+ * ```
+ *
+ * The server enforces a content size limit (default 512 KB). Content
+ * exceeding this limit is truncated — check `isTruncated` and offer
+ * a full download via the pre-signed URL for large artifacts.
+ *
+ * The returned `content` is decoded from UTF-8 bytes. For binary
+ * artifacts, use `getArtifactDownloadUrl` instead of this hook.
+ *
+ * @param executionId - Execution that produced the artifact, or `null` to skip.
+ * @param storageKey - Storage key from `ExecutionArtifact.storageKey`, or `null` to skip.
+ * @param entryPath - For directory artifacts: relative path of a file within
+ *   the archive to extract. `null` returns the full artifact (existing behavior).
+ *
+ * @see useExecutionArtifacts — extracts artifact metadata from an execution
+ * @see isTextArtifact — heuristic for whether content is fetchable as text
+ */
+export function useArtifactContent(executionId, storageKey, entryPath) {
+    const stigmer = useStigmer();
+    const [content, setContent] = useState(null);
+    const [contentType, setContentType] = useState(null);
+    const [isTruncated, setIsTruncated] = useState(false);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [fetchKey, setFetchKey] = useState(0);
+    const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+    useEffect(() => {
+        if (!executionId || !storageKey) {
+            setContent(null);
+            setContentType(null);
+            setIsTruncated(false);
+            setIsLoading(false);
+            setError(null);
+            return;
+        }
+        const cancelled = { current: false };
+        setIsLoading(true);
+        setError(null);
+        stigmer.agentExecution
+            .getArtifactContent(create(GetArtifactContentRequestSchema, {
+            executionId,
+            storageKey,
+            ...(entryPath ? { entryPath } : {}),
+        }))
+            .then((result) => {
+            if (cancelled.current)
+                return;
+            const decoded = new TextDecoder().decode(result.content);
+            setContent(decoded);
+            setContentType(result.contentType || null);
+            setIsTruncated(result.truncated);
+            setIsLoading(false);
+        }, (err) => {
+            if (cancelled.current)
+                return;
+            setError(err instanceof Error
+                ? err.message
+                : "Failed to load artifact content");
+            setContent(null);
+            setContentType(null);
+            setIsTruncated(false);
+            setIsLoading(false);
+        });
+        return () => {
+            cancelled.current = true;
+        };
+    }, [executionId, storageKey, entryPath, stigmer, fetchKey]);
+    return { content, contentType, isTruncated, isLoading, error, refetch };
+}
+//# sourceMappingURL=useArtifactContent.js.map

package/execution/useArtifactContent.js.map

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

package/execution/useCreateAgentExecution.d.ts

@@ -0,0 +1,84 @@
+import type { AttachmentInput, EnvVarInput } from "@stigmer/sdk";
+export interface CreateAgentExecutionInput {
+    readonly org: string;
+    readonly sessionId: string;
+    readonly message: string;
+    readonly modelName?: string;
+    readonly agentId?: string;
+    /**
+     * Execution-scoped secrets and configuration (Execution Flow).
+     *
+     * Values are injected into the agent sandbox for this execution only
+     * and deleted when the execution completes. They take the highest
+     * merge priority, overriding both Environment values and agent
+     * defaults.
+     *
+     * Use this for B2B integrations where per-call credentials are
+     * injected at runtime, or for one-off secrets that should not persist.
+     *
+     * For persistent credentials that are reused across executions, use
+     * 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}
+     */
+    readonly runtimeEnv?: Record<string, EnvVarInput>;
+    /**
+     * Pre-uploaded file attachments injected into the agent sandbox.
+     *
+     * Each entry must include a `storageKey` obtained from
+     * `agentExecution.uploadAttachment()`. The agent can read attached
+     * files from their mount paths (default `/inputs/{filename}`).
+     */
+    readonly attachments?: AttachmentInput[];
+}
+export interface CreateAgentExecutionResult {
+    readonly executionId: string;
+    readonly sessionId: string;
+}
+export interface UseCreateAgentExecutionReturn {
+    readonly create: (input: CreateAgentExecutionInput) => Promise<CreateAgentExecutionResult>;
+    readonly isCreating: boolean;
+    readonly error: Error | null;
+    readonly clearError: () => void;
+}
+/**
+ * Behavior hook that wraps `agentExecution.create()` with loading/error
+ * state.
+ *
+ * Maps 1:1 to the AgentExecution aggregate — a single run of an agent
+ * within an existing session. Requires a `sessionId`; use
+ * {@link useCreateSession} to create the session first.
+ *
+ * Supports both secret delivery flows:
+ *
+ * - **Environment Flow** — Secrets are stored in Environment resources
+ *   and bound via AgentInstance. No `runtimeEnv` needed; the backend
+ *   resolves credentials from the session's agent instance.
+ * - **Execution Flow** — Pass `runtimeEnv` to inject per-execution
+ *   secrets. Values are merged with the highest priority and deleted
+ *   when the execution completes.
+ *
+ * @example
+ * ```tsx
+ * // Environment Flow: secrets come from the agent instance's environments
+ * const { create } = useCreateAgentExecution();
+ * await create({ org: "acme", sessionId: "ses_abc", message: "Review the PR" });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Execution Flow: inject per-call secrets
+ * const { create } = useCreateAgentExecution();
+ * await create({
+ *   org: "acme",
+ *   sessionId: "ses_abc",
+ *   message: "Deploy to production",
+ *   runtimeEnv: {
+ *     CUSTOMER_API_KEY: { value: "cust_xyz...", isSecret: true },
+ *   },
+ * });
+ * ```
+ */
+export declare function useCreateAgentExecution(): UseCreateAgentExecutionReturn;
+//# sourceMappingURL=useCreateAgentExecution.d.ts.map

package/execution/useCreateAgentExecution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCreateAgentExecution.d.ts","sourceRoot":"","sources":["../../src/execution/useCreateAgentExecution.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAIjE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAClD;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,CACf,KAAK,EAAE,yBAAyB,KAC7B,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,uBAAuB,IAAI,6BAA6B,CA2CvE"}

package/execution/useCreateAgentExecution.js

@@ -0,0 +1,79 @@
+"use client";
+import { useCallback, useState } from "react";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+/**
+ * Behavior hook that wraps `agentExecution.create()` with loading/error
+ * state.
+ *
+ * Maps 1:1 to the AgentExecution aggregate — a single run of an agent
+ * within an existing session. Requires a `sessionId`; use
+ * {@link useCreateSession} to create the session first.
+ *
+ * Supports both secret delivery flows:
+ *
+ * - **Environment Flow** — Secrets are stored in Environment resources
+ *   and bound via AgentInstance. No `runtimeEnv` needed; the backend
+ *   resolves credentials from the session's agent instance.
+ * - **Execution Flow** — Pass `runtimeEnv` to inject per-execution
+ *   secrets. Values are merged with the highest priority and deleted
+ *   when the execution completes.
+ *
+ * @example
+ * ```tsx
+ * // Environment Flow: secrets come from the agent instance's environments
+ * const { create } = useCreateAgentExecution();
+ * await create({ org: "acme", sessionId: "ses_abc", message: "Review the PR" });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Execution Flow: inject per-call secrets
+ * const { create } = useCreateAgentExecution();
+ * await create({
+ *   org: "acme",
+ *   sessionId: "ses_abc",
+ *   message: "Deploy to production",
+ *   runtimeEnv: {
+ *     CUSTOMER_API_KEY: { value: "cust_xyz...", isSecret: true },
+ *   },
+ * });
+ * ```
+ */
+export function useCreateAgentExecution() {
+    const stigmer = useStigmer();
+    const [isCreating, setIsCreating] = useState(false);
+    const [error, setError] = useState(null);
+    const clearError = useCallback(() => setError(null), []);
+    const create = useCallback(async (input) => {
+        setIsCreating(true);
+        setError(null);
+        try {
+            const execution = await stigmer.agentExecution.create({
+                name: `execution-${Date.now()}`,
+                org: input.org,
+                sessionId: input.sessionId,
+                agentId: input.agentId,
+                message: input.message,
+                executionConfig: input.modelName
+                    ? { modelName: input.modelName }
+                    : undefined,
+                runtimeEnv: input.runtimeEnv,
+                attachments: input.attachments,
+            });
+            return {
+                executionId: execution.metadata.id,
+                sessionId: input.sessionId,
+            };
+        }
+        catch (err) {
+            setError(toError(err));
+            throw err;
+        }
+        finally {
+            setIsCreating(false);
+        }
+    }, [stigmer]);
+    return { create, isCreating, error, clearError };
+}
+//# sourceMappingURL=useCreateAgentExecution.js.map

package/execution/useCreateAgentExecution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCreateAgentExecution.js","sourceRoot":"","sources":["../../src/execution/useCreateAgentExecution.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAkD9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpD,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,MAAM,GAAG,WAAW,CACxB,KAAK,EACH,KAAgC,EACK,EAAE;QACvC,aAAa,CAAC,IAAI,CAAC,CAAC;QACpB,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC;gBACpD,IAAI,EAAE,aAAa,IAAI,CAAC,GAAG,EAAE,EAAE;gBAC/B,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,eAAe,EAAE,KAAK,CAAC,SAAS;oBAC9B,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE;oBAChC,CAAC,CAAC,SAAS;gBACb,UAAU,EAAE,KAAK,CAAC,UAAU;gBAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;aAC/B,CAAC,CAAC;YAEH,OAAO;gBACL,WAAW,EAAE,SAAS,CAAC,QAAS,CAAC,EAAE;gBACnC,SAAS,EAAE,KAAK,CAAC,SAAS;aAC3B,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YACvB,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,aAAa,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACH,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AACnD,CAAC"}

package/execution/useExecutionArtifacts.d.ts

@@ -0,0 +1,42 @@
+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";
+export interface UseExecutionArtifactsReturn {
+    /** Artifacts published by the agent during execution. Ordered by creation time (oldest first). */
+    readonly artifacts: readonly ExecutionArtifact[];
+    /** `true` when the execution has at least one artifact. */
+    readonly hasArtifacts: boolean;
+    /** Total number of artifacts. */
+    readonly artifactCount: number;
+}
+/**
+ * Pure derivation hook that extracts artifact metadata from an
+ * {@link AgentExecution} snapshot.
+ *
+ * Follows the same pattern as {@link useExecutionUsage}: a `useMemo`-based
+ * derivation with no side effects and no data fetching. The execution
+ * object (typically from {@link useExecutionStream}) is the single input.
+ *
+ * Returns an empty array when the execution is `null` or has no artifacts,
+ * eliminating null-checking at every consumer call site.
+ *
+ * For reading artifact *content* (e.g., for YAML detection or preview
+ * rendering), compose with {@link useArtifactContent} on a per-artifact
+ * basis. For determining whether an artifact is text-based, use
+ * {@link isTextArtifact}.
+ *
+ * @example
+ * ```tsx
+ * const { execution } = useExecutionStream(executionId);
+ * const { artifacts, hasArtifacts } = useExecutionArtifacts(execution);
+ *
+ * if (hasArtifacts) {
+ *   artifacts.forEach((a) => console.log(a.name, a.sizeBytes));
+ * }
+ * ```
+ *
+ * @see useArtifactContent — content-fetching hook for a single artifact
+ * @see isTextArtifact — heuristic for fetchable text content
+ * @see formatArtifactSize — human-readable file size formatting
+ */
+export declare function useExecutionArtifacts(execution: AgentExecution | null): UseExecutionArtifactsReturn;
+//# sourceMappingURL=useExecutionArtifacts.d.ts.map

package/execution/useExecutionArtifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExecutionArtifacts.d.ts","sourceRoot":"","sources":["../../src/execution/useExecutionArtifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kEAAkE,CAAC;AAE1G,MAAM,WAAW,2BAA2B;IAC1C,kGAAkG;IAClG,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,iCAAiC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,cAAc,GAAG,IAAI,GAC/B,2BAA2B,CAU7B"}

package/execution/useExecutionArtifacts.js

@@ -0,0 +1,43 @@
+"use client";
+import { useMemo } from "react";
+/**
+ * Pure derivation hook that extracts artifact metadata from an
+ * {@link AgentExecution} snapshot.
+ *
+ * Follows the same pattern as {@link useExecutionUsage}: a `useMemo`-based
+ * derivation with no side effects and no data fetching. The execution
+ * object (typically from {@link useExecutionStream}) is the single input.
+ *
+ * Returns an empty array when the execution is `null` or has no artifacts,
+ * eliminating null-checking at every consumer call site.
+ *
+ * For reading artifact *content* (e.g., for YAML detection or preview
+ * rendering), compose with {@link useArtifactContent} on a per-artifact
+ * basis. For determining whether an artifact is text-based, use
+ * {@link isTextArtifact}.
+ *
+ * @example
+ * ```tsx
+ * const { execution } = useExecutionStream(executionId);
+ * const { artifacts, hasArtifacts } = useExecutionArtifacts(execution);
+ *
+ * if (hasArtifacts) {
+ *   artifacts.forEach((a) => console.log(a.name, a.sizeBytes));
+ * }
+ * ```
+ *
+ * @see useArtifactContent — content-fetching hook for a single artifact
+ * @see isTextArtifact — heuristic for fetchable text content
+ * @see formatArtifactSize — human-readable file size formatting
+ */
+export function useExecutionArtifacts(execution) {
+    return useMemo(() => {
+        const artifacts = execution?.status?.artifacts ?? [];
+        return {
+            artifacts,
+            hasArtifacts: artifacts.length > 0,
+            artifactCount: artifacts.length,
+        };
+    }, [execution]);
+}
+//# sourceMappingURL=useExecutionArtifacts.js.map

package/execution/useExecutionArtifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExecutionArtifacts.js","sourceRoot":"","sources":["../../src/execution/useExecutionArtifacts.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAahC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,qBAAqB,CACnC,SAAgC;IAEhC,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,SAAS,GAAG,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC;QAErD,OAAO;YACL,SAAS;YACT,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;YAClC,aAAa,EAAE,SAAS,CAAC,MAAM;SAChC,CAAC;IACJ,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/execution/useExecutionStream.d.ts

@@ -0,0 +1,62 @@
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+export interface UseExecutionStreamReturn {
+    /** Latest full execution snapshot from the stream, or `null` before the first update arrives. */
+    readonly execution: AgentExecution | null;
+    /**
+     * Convenience extraction of `execution.status.phase`.
+     *
+     * Derived from `execution` via `useMemo` — always consistent with the
+     * current snapshot. Returns `EXECUTION_PHASE_UNSPECIFIED` when
+     * `execution` is `null`.
+     */
+    readonly phase: ExecutionPhase;
+    /** `true` while receiving non-terminal updates from the server stream. */
+    readonly isStreaming: boolean;
+    /** `true` after subscription starts but before the first snapshot arrives. */
+    readonly isConnecting: boolean;
+    /** Error from the last failed stream attempt, or `null` when healthy. */
+    readonly error: Error | null;
+    /**
+     * Reset error state and re-establish the stream subscription.
+     *
+     * Works in any lifecycle state — error, complete, or mid-stream.
+     * Uses the `connectKey` counter pattern consistent with `refetch()`
+     * in other SDK hooks.
+     */
+    readonly reconnect: () => void;
+}
+/**
+ * Behavior hook that subscribes to real-time {@link AgentExecution}
+ * updates via `stigmer.agentExecution.subscribe()`.
+ *
+ * Manages the full subscription lifecycle: connection establishment,
+ * snapshot streaming, terminal-phase detection, error handling, and
+ * manual reconnection. Each server message replaces the previous
+ * snapshot atomically — no delta merging.
+ *
+ * Pass `null` to skip subscribing (stable no-op). When `executionId`
+ * changes, the previous subscription is aborted and a fresh one begins.
+ *
+ * @example
+ * ```tsx
+ * function LiveExecution({ id }: { id: string }) {
+ *   const { execution, isStreaming, error, reconnect } =
+ *     useExecutionStream(id);
+ *
+ *   if (error) return <p>{error.message} <button onClick={reconnect}>Retry</button></p>;
+ *   if (!execution) return <p>Connecting…</p>;
+ *
+ *   return (
+ *     <div>
+ *       {execution.status?.messages.map((m, i) => (
+ *         <p key={i}>{m.content}</p>
+ *       ))}
+ *       {isStreaming && <span>Streaming…</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useExecutionStream(executionId: string | null): UseExecutionStreamReturn;
+//# sourceMappingURL=useExecutionStream.d.ts.map

package/execution/useExecutionStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExecutionStream.d.ts","sourceRoot":"","sources":["../../src/execution/useExecutionStream.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAC;AAK9F,MAAM,WAAW,wBAAwB;IACvC,iGAAiG;IACjG,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,GAAG,IAAI,GACzB,wBAAwB,CA8E1B"}

package/execution/useExecutionStream.js

@@ -0,0 +1,99 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import { isTerminalPhase } from "./execution-phases";
+/**
+ * Behavior hook that subscribes to real-time {@link AgentExecution}
+ * updates via `stigmer.agentExecution.subscribe()`.
+ *
+ * Manages the full subscription lifecycle: connection establishment,
+ * snapshot streaming, terminal-phase detection, error handling, and
+ * manual reconnection. Each server message replaces the previous
+ * snapshot atomically — no delta merging.
+ *
+ * Pass `null` to skip subscribing (stable no-op). When `executionId`
+ * changes, the previous subscription is aborted and a fresh one begins.
+ *
+ * @example
+ * ```tsx
+ * function LiveExecution({ id }: { id: string }) {
+ *   const { execution, isStreaming, error, reconnect } =
+ *     useExecutionStream(id);
+ *
+ *   if (error) return <p>{error.message} <button onClick={reconnect}>Retry</button></p>;
+ *   if (!execution) return <p>Connecting…</p>;
+ *
+ *   return (
+ *     <div>
+ *       {execution.status?.messages.map((m, i) => (
+ *         <p key={i}>{m.content}</p>
+ *       ))}
+ *       {isStreaming && <span>Streaming…</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useExecutionStream(executionId) {
+    const stigmer = useStigmer();
+    const [execution, setExecution] = useState(null);
+    const [isConnecting, setIsConnecting] = useState(false);
+    const [isStreaming, setIsStreaming] = useState(false);
+    const [error, setError] = useState(null);
+    const [connectKey, setConnectKey] = useState(0);
+    const abortRef = useRef(null);
+    const reconnect = useCallback(() => {
+        setError(null);
+        setConnectKey((k) => k + 1);
+    }, []);
+    useEffect(() => {
+        if (!executionId) {
+            setExecution(null);
+            setIsConnecting(false);
+            setIsStreaming(false);
+            setError(null);
+            return;
+        }
+        abortRef.current?.abort();
+        const controller = new AbortController();
+        abortRef.current = controller;
+        setExecution(null);
+        setIsConnecting(true);
+        setIsStreaming(false);
+        setError(null);
+        (async () => {
+            try {
+                for await (const snapshot of stigmer.agentExecution.subscribe(executionId, controller.signal)) {
+                    if (controller.signal.aborted)
+                        return;
+                    const currentPhase = snapshot.status?.phase ??
+                        ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+                    const isTerminal = isTerminalPhase(currentPhase);
+                    setExecution(snapshot);
+                    setIsConnecting(false);
+                    setIsStreaming(!isTerminal);
+                    if (isTerminal)
+                        break;
+                }
+                if (!controller.signal.aborted) {
+                    setIsStreaming(false);
+                }
+            }
+            catch (err) {
+                if (controller.signal.aborted)
+                    return;
+                setError(toError(err));
+                setIsConnecting(false);
+                setIsStreaming(false);
+            }
+        })();
+        return () => {
+            controller.abort();
+        };
+    }, [executionId, stigmer, connectKey]);
+    const phase = useMemo(() => execution?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED, [execution]);
+    return { execution, phase, isStreaming, isConnecting, error, reconnect };
+}
+//# sourceMappingURL=useExecutionStream.js.map

package/execution/useExecutionStream.js.map

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