@stigmer/react 0.0.36 → 0.0.40

package/execution/useExecutionUsage.d.ts

@@ -0,0 +1,45 @@
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { UsageMetrics } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+export interface UseExecutionUsageReturn {
+    /** Aggregated usage (main agent + sub-agents). Null before usage data arrives. */
+    readonly usage: UsageMetrics | null;
+    /** Whether any sub-agent contributed usage to the aggregated total. */
+    readonly hasSubAgentUsage: boolean;
+    /** Count of sub-agents that have non-null usage data. */
+    readonly subAgentUsageCount: number;
+}
+/**
+ * Pure derivation hook that aggregates {@link UsageMetrics} across the
+ * main agent and all sub-agents into a single {@link UsageMetrics} total.
+ *
+ * The proto scoping rule is:
+ * > `status.usage` = main agent's direct LLM usage (excludes sub-agents)
+ * > `subAgentExecutions[].usage` = each sub-agent's LLM usage
+ * > Total cost = `status.usage` + sum(`subAgentExecutions[].usage`)
+ *
+ * This hook performs that summation, merges `modelBreakdown` entries by
+ * `model+provider` key, and concatenates `llmCalls` sorted by timestamp.
+ *
+ * Returns `null` when the execution is absent or usage data has not yet
+ * arrived from the agent runner.
+ *
+ * @example
+ * ```tsx
+ * const { execution } = useExecutionStream(executionId);
+ * const { usage, hasSubAgentUsage } = useExecutionUsage(execution);
+ *
+ * if (usage) {
+ *   console.log(`Cost: $${usage.estimatedCostUsd}`);
+ *   console.log(`Tokens: ${usage.totalTokens}`);
+ * }
+ * ```
+ */
+export declare function useExecutionUsage(execution: AgentExecution | null): UseExecutionUsageReturn;
+/**
+ * Aggregates usage metrics from the main agent and all sub-agents into
+ * a single {@link UsageMetrics} proto object.
+ *
+ * Returns `null` when the execution or its usage data is not yet available.
+ */
+export declare function aggregateUsage(execution: AgentExecution | null): UsageMetrics | null;
+//# sourceMappingURL=useExecutionUsage.d.ts.map

package/execution/useExecutionUsage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExecutionUsage.d.ts","sourceRoot":"","sources":["../../src/execution/useExecutionUsage.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,KAAK,EACV,YAAY,EAEb,MAAM,+DAA+D,CAAC;AAMvE,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,uEAAuE;IACvE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,yDAAyD;IACzD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,cAAc,GAAG,IAAI,GAC/B,uBAAuB,CAoBzB;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,cAAc,GAAG,IAAI,GAC/B,YAAY,GAAG,IAAI,CAgCrB"}

package/execution/useExecutionUsage.js

@@ -0,0 +1,157 @@
+"use client";
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import { UsageMetricsSchema, ModelUsageSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+/**
+ * Pure derivation hook that aggregates {@link UsageMetrics} across the
+ * main agent and all sub-agents into a single {@link UsageMetrics} total.
+ *
+ * The proto scoping rule is:
+ * > `status.usage` = main agent's direct LLM usage (excludes sub-agents)
+ * > `subAgentExecutions[].usage` = each sub-agent's LLM usage
+ * > Total cost = `status.usage` + sum(`subAgentExecutions[].usage`)
+ *
+ * This hook performs that summation, merges `modelBreakdown` entries by
+ * `model+provider` key, and concatenates `llmCalls` sorted by timestamp.
+ *
+ * Returns `null` when the execution is absent or usage data has not yet
+ * arrived from the agent runner.
+ *
+ * @example
+ * ```tsx
+ * const { execution } = useExecutionStream(executionId);
+ * const { usage, hasSubAgentUsage } = useExecutionUsage(execution);
+ *
+ * if (usage) {
+ *   console.log(`Cost: $${usage.estimatedCostUsd}`);
+ *   console.log(`Tokens: ${usage.totalTokens}`);
+ * }
+ * ```
+ */
+export function useExecutionUsage(execution) {
+    return useMemo(() => {
+        const usage = aggregateUsage(execution);
+        if (!usage) {
+            return { usage: null, hasSubAgentUsage: false, subAgentUsageCount: 0 };
+        }
+        const subAgents = execution?.status?.subAgentExecutions ?? [];
+        let subAgentUsageCount = 0;
+        for (const sub of subAgents) {
+            if (sub.usage)
+                subAgentUsageCount++;
+        }
+        return {
+            usage,
+            hasSubAgentUsage: subAgentUsageCount > 0,
+            subAgentUsageCount,
+        };
+    }, [execution]);
+}
+// ---------------------------------------------------------------------------
+// Pure aggregation function — testable without React
+// ---------------------------------------------------------------------------
+/**
+ * Aggregates usage metrics from the main agent and all sub-agents into
+ * a single {@link UsageMetrics} proto object.
+ *
+ * Returns `null` when the execution or its usage data is not yet available.
+ */
+export function aggregateUsage(execution) {
+    const mainUsage = execution?.status?.usage;
+    if (!mainUsage)
+        return null;
+    const subAgents = execution?.status?.subAgentExecutions ?? [];
+    const subUsages = [];
+    for (const sub of subAgents) {
+        if (sub.usage)
+            subUsages.push(sub.usage);
+    }
+    if (subUsages.length === 0)
+        return mainUsage;
+    const allUsages = [mainUsage, ...subUsages];
+    return create(UsageMetricsSchema, {
+        promptTokens: sumField(allUsages, "promptTokens"),
+        completionTokens: sumField(allUsages, "completionTokens"),
+        totalTokens: sumField(allUsages, "totalTokens"),
+        llmCallCount: sumField(allUsages, "llmCallCount"),
+        cacheCreationTokens: sumField(allUsages, "cacheCreationTokens"),
+        cacheReadTokens: sumField(allUsages, "cacheReadTokens"),
+        estimatedCostUsd: sumField(allUsages, "estimatedCostUsd"),
+        totalDurationMs: sumField(allUsages, "totalDurationMs"),
+        llmDurationMs: sumField(allUsages, "llmDurationMs"),
+        toolDurationMs: sumField(allUsages, "toolDurationMs"),
+        approvalWaitDurationMs: sumField(allUsages, "approvalWaitDurationMs"),
+        toolResultCharsTruncated: sumBigIntField(allUsages),
+        primaryModel: mainUsage.primaryModel,
+        primaryProvider: mainUsage.primaryProvider,
+        modelBreakdown: mergeModelBreakdowns(allUsages),
+        llmCalls: mergeLlmCalls(allUsages),
+    });
+}
+function sumField(usages, field) {
+    let total = 0;
+    for (const u of usages) {
+        total += u[field];
+    }
+    return total;
+}
+function sumBigIntField(usages) {
+    let total = BigInt(0);
+    for (const u of usages) {
+        total += u.toolResultCharsTruncated;
+    }
+    return total;
+}
+/**
+ * Merges model breakdown entries across all usages by `model+provider` key.
+ * Entries for the same model and provider are combined into a single
+ * {@link ModelUsage} with summed numeric fields. Pricing rates are taken
+ * from the first entry encountered for each key (rates are stamped at
+ * execution time and are identical for the same model).
+ */
+function mergeModelBreakdowns(usages) {
+    const merged = new Map();
+    for (const usage of usages) {
+        for (const entry of usage.modelBreakdown) {
+            const key = `${entry.model}\0${entry.provider}`;
+            const existing = merged.get(key);
+            if (existing) {
+                existing.inputTokens += entry.inputTokens;
+                existing.outputTokens += entry.outputTokens;
+                existing.cacheCreationTokens += entry.cacheCreationTokens;
+                existing.cacheReadTokens += entry.cacheReadTokens;
+                existing.callCount += entry.callCount;
+                existing.estimatedCostUsd += entry.estimatedCostUsd;
+            }
+            else {
+                merged.set(key, {
+                    model: entry.model,
+                    provider: entry.provider,
+                    inputTokens: entry.inputTokens,
+                    outputTokens: entry.outputTokens,
+                    cacheCreationTokens: entry.cacheCreationTokens,
+                    cacheReadTokens: entry.cacheReadTokens,
+                    callCount: entry.callCount,
+                    estimatedCostUsd: entry.estimatedCostUsd,
+                    inputPricePerMillion: entry.inputPricePerMillion,
+                    outputPricePerMillion: entry.outputPricePerMillion,
+                    cacheCreationPricePerMillion: entry.cacheCreationPricePerMillion,
+                    cacheReadPricePerMillion: entry.cacheReadPricePerMillion,
+                });
+            }
+        }
+    }
+    return Array.from(merged.values()).map((m) => create(ModelUsageSchema, m));
+}
+/**
+ * Concatenates `llmCalls` from all usages, sorted by ISO 8601 timestamp.
+ * This gives a globally chronological view across main agent and sub-agents,
+ * since per-agent `sequence` numbers overlap.
+ */
+function mergeLlmCalls(usages) {
+    const all = usages.flatMap((u) => u.llmCalls);
+    if (all.length <= 1)
+        return all;
+    return all.slice().sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+}
+//# sourceMappingURL=useExecutionUsage.js.map

package/execution/useExecutionUsage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useExecutionUsage.js","sourceRoot":"","sources":["../../src/execution/useExecutionUsage.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAM5C,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,+DAA+D,CAAC;AAWvE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAgC;IAEhC,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,KAAK,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;QAExC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,EAAE,CAAC;QACzE,CAAC;QAED,MAAM,SAAS,GAAG,SAAS,EAAE,MAAM,EAAE,kBAAkB,IAAI,EAAE,CAAC;QAC9D,IAAI,kBAAkB,GAAG,CAAC,CAAC;QAC3B,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,IAAI,GAAG,CAAC,KAAK;gBAAE,kBAAkB,EAAE,CAAC;QACtC,CAAC;QAED,OAAO;YACL,KAAK;YACL,gBAAgB,EAAE,kBAAkB,GAAG,CAAC;YACxC,kBAAkB;SACnB,CAAC;IACJ,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,8EAA8E;AAC9E,qDAAqD;AACrD,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAgC;IAEhC,MAAM,SAAS,GAAG,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC;IAC3C,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAE5B,MAAM,SAAS,GAAG,SAAS,EAAE,MAAM,EAAE,kBAAkB,IAAI,EAAE,CAAC;IAC9D,MAAM,SAAS,GAAmB,EAAE,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,IAAI,GAAG,CAAC,KAAK;YAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAE7C,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,CAAC;IAE5C,OAAO,MAAM,CAAC,kBAAkB,EAAE;QAChC,YAAY,EAAE,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;QACjD,gBAAgB,EAAE,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;QACzD,WAAW,EAAE,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;QAC/C,YAAY,EAAE,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;QACjD,mBAAmB,EAAE,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;QAC/D,eAAe,EAAE,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;QACvD,gBAAgB,EAAE,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;QACzD,eAAe,EAAE,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;QACvD,aAAa,EAAE,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;QACnD,cAAc,EAAE,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;QACrD,sBAAsB,EAAE,QAAQ,CAAC,SAAS,EAAE,wBAAwB,CAAC;QACrE,wBAAwB,EAAE,cAAc,CAAC,SAAS,CAAC;QACnD,YAAY,EAAE,SAAS,CAAC,YAAY;QACpC,eAAe,EAAE,SAAS,CAAC,eAAe;QAC1C,cAAc,EAAE,oBAAoB,CAAC,SAAS,CAAC;QAC/C,QAAQ,EAAE,aAAa,CAAC,SAAS,CAAC;KACnC,CAAC,CAAC;AACL,CAAC;AAUD,SAAS,QAAQ,CAAC,MAAsB,EAAE,KAAmB;IAC3D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,KAAK,IAAI,CAAC,CAAC,KAAK,CAAW,CAAC;IAC9B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,cAAc,CAAC,MAAsB;IAC5C,IAAI,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACtB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,KAAK,IAAI,CAAC,CAAC,wBAAwB,CAAC;IACtC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,oBAAoB,CAAC,MAAsB;IAClD,MAAM,MAAM,GAAG,IAAI,GAAG,EAgBnB,CAAC;IAEJ,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;YACzC,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC;YAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAEjC,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,WAAW,IAAI,KAAK,CAAC,WAAW,CAAC;gBAC1C,QAAQ,CAAC,YAAY,IAAI,KAAK,CAAC,YAAY,CAAC;gBAC5C,QAAQ,CAAC,mBAAmB,IAAI,KAAK,CAAC,mBAAmB,CAAC;gBAC1D,QAAQ,CAAC,eAAe,IAAI,KAAK,CAAC,eAAe,CAAC;gBAClD,QAAQ,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC;gBACtC,QAAQ,CAAC,gBAAgB,IAAI,KAAK,CAAC,gBAAgB,CAAC;YACtD,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE;oBACd,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,WAAW,EAAE,KAAK,CAAC,WAAW;oBAC9B,YAAY,EAAE,KAAK,CAAC,YAAY;oBAChC,mBAAmB,EAAE,KAAK,CAAC,mBAAmB;oBAC9C,eAAe,EAAE,KAAK,CAAC,eAAe;oBACtC,SAAS,EAAE,KAAK,CAAC,SAAS;oBAC1B,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;oBACxC,oBAAoB,EAAE,KAAK,CAAC,oBAAoB;oBAChD,qBAAqB,EAAE,KAAK,CAAC,qBAAqB;oBAClD,4BAA4B,EAAE,KAAK,CAAC,4BAA4B;oBAChE,wBAAwB,EAAE,KAAK,CAAC,wBAAwB;iBACzD,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,MAAsB;IAC3C,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IAChC,OAAO,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AAC5E,CAAC"}

package/execution/useSessionVariables.d.ts

@@ -0,0 +1,102 @@
+import type { EnvVarInput } from "@stigmer/sdk";
+/**
+ * A single entry in the session variables editor.
+ *
+ * Each entry maps to one environment variable. When `saveForFuture`
+ * is `false` (default), the value is injected into the agent sandbox
+ * for a single execution only. When `true`, the value is persisted
+ * to the user's personal environment for reuse across sessions.
+ */
+export interface SessionVariableEntry {
+    readonly id: string;
+    readonly key: string;
+    readonly value: string;
+    readonly isSecret: boolean;
+    readonly saveForFuture: boolean;
+}
+export interface UseSessionVariablesReturn {
+    /** Current entries in the editor. */
+    readonly entries: readonly SessionVariableEntry[];
+    /** Append a blank entry. Defaults to `isSecret: true` (safer default). */
+    readonly addEntry: () => void;
+    /** Remove an entry by its unique ID. */
+    readonly removeEntry: (id: string) => void;
+    /** Patch one or more fields on an existing entry. */
+    readonly updateEntry: (id: string, patch: {
+        key?: string;
+        value?: string;
+        isSecret?: boolean;
+        saveForFuture?: boolean;
+    }) => void;
+    /** Remove all entries. Call after submission to prevent stale values. */
+    readonly clear: () => void;
+    /** True when there are no entries at all. */
+    readonly isEmpty: boolean;
+    /**
+     * True when at least one entry has a non-empty key AND non-empty value.
+     * Use this to decide whether to include `runtimeEnv` in the execution.
+     */
+    readonly hasValidEntries: boolean;
+    /**
+     * Convert valid entries to the SDK input shape for execution-scoped
+     * runtime env.
+     *
+     * Includes all entries with non-empty keys and values, regardless of
+     * `saveForFuture`. When duplicate keys exist, the last entry wins
+     * (consistent with environment semantics).
+     */
+    readonly toRuntimeEnv: () => Record<string, EnvVarInput>;
+    /**
+     * Convert valid save-for-future entries (saveForFuture === true) to
+     * the SDK input shape for personal environment persistence.
+     *
+     * Filters out entries with empty keys or values. When duplicate keys
+     * exist, the last entry wins.
+     */
+    readonly toSaveForFutureEnv: () => Record<string, EnvVarInput>;
+    /**
+     * True when at least one valid entry has `saveForFuture === true`.
+     */
+    readonly hasSaveForFutureEntries: boolean;
+}
+/**
+ * Behavior hook that manages an array of session variable entries for
+ * execution-scoped environment variables.
+ *
+ * Session variables are injected into the agent sandbox at execution
+ * time. By default they are ephemeral (single execution), but users
+ * can opt into persisting individual entries to their personal
+ * environment via the `saveForFuture` flag.
+ *
+ * Follows the same controlled-state pattern as {@link useWorkspaceEntries}:
+ * the consumer owns the hook instance, passes it to UI components, reads
+ * the output during submission, and calls {@link UseSessionVariablesReturn.clear}
+ * after sending to prevent stale values on the next follow-up.
+ *
+ * @example
+ * ```tsx
+ * function Chat({ sessionId, org }: { sessionId: string; org: string }) {
+ *   const conv = useSessionConversation(sessionId, org);
+ *   const sessionVariables = useSessionVariables();
+ *
+ *   const handleSubmit = (message: string, model?: string) => {
+ *     const runtimeEnv = sessionVariables.isEmpty
+ *       ? undefined
+ *       : sessionVariables.toRuntimeEnv();
+ *     conv.sendFollowUp(message, { modelName: model, runtimeEnv });
+ *     sessionVariables.clear();
+ *   };
+ *
+ *   return (
+ *     <SessionComposer
+ *       onSubmit={handleSubmit}
+ *       sessionVariables={sessionVariables}
+ *       disabled={!conv.canSendFollowUp}
+ *       isSubmitting={conv.isSending}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare function useSessionVariables(): UseSessionVariablesReturn;
+//# sourceMappingURL=useSessionVariables.d.ts.map

package/execution/useSessionVariables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSessionVariables.d.ts","sourceRoot":"","sources":["../../src/execution/useSessionVariables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,yBAAyB;IACxC,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,CACpB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,KACjF,IAAI,CAAC;IACV,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACzD;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/D;;OAEG;IACH,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;CAC3C;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,mBAAmB,IAAI,yBAAyB,CA+E/D"}

package/execution/useSessionVariables.js

@@ -0,0 +1,102 @@
+"use client";
+import { useCallback, useMemo, useState } from "react";
+let nextId = 0;
+function uid() {
+    return `sv-${++nextId}-${Date.now()}`;
+}
+/**
+ * Behavior hook that manages an array of session variable entries for
+ * execution-scoped environment variables.
+ *
+ * Session variables are injected into the agent sandbox at execution
+ * time. By default they are ephemeral (single execution), but users
+ * can opt into persisting individual entries to their personal
+ * environment via the `saveForFuture` flag.
+ *
+ * Follows the same controlled-state pattern as {@link useWorkspaceEntries}:
+ * the consumer owns the hook instance, passes it to UI components, reads
+ * the output during submission, and calls {@link UseSessionVariablesReturn.clear}
+ * after sending to prevent stale values on the next follow-up.
+ *
+ * @example
+ * ```tsx
+ * function Chat({ sessionId, org }: { sessionId: string; org: string }) {
+ *   const conv = useSessionConversation(sessionId, org);
+ *   const sessionVariables = useSessionVariables();
+ *
+ *   const handleSubmit = (message: string, model?: string) => {
+ *     const runtimeEnv = sessionVariables.isEmpty
+ *       ? undefined
+ *       : sessionVariables.toRuntimeEnv();
+ *     conv.sendFollowUp(message, { modelName: model, runtimeEnv });
+ *     sessionVariables.clear();
+ *   };
+ *
+ *   return (
+ *     <SessionComposer
+ *       onSubmit={handleSubmit}
+ *       sessionVariables={sessionVariables}
+ *       disabled={!conv.canSendFollowUp}
+ *       isSubmitting={conv.isSending}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useSessionVariables() {
+    const [entries, setEntries] = useState([]);
+    const addEntry = useCallback(() => {
+        setEntries((prev) => [
+            ...prev,
+            { id: uid(), key: "", value: "", isSecret: true, saveForFuture: false },
+        ]);
+    }, []);
+    const removeEntry = useCallback((id) => {
+        setEntries((prev) => prev.filter((e) => e.id !== id));
+    }, []);
+    const updateEntry = useCallback((id, patch) => {
+        setEntries((prev) => prev.map((e) => (e.id === id ? { ...e, ...patch } : e)));
+    }, []);
+    const clear = useCallback(() => {
+        setEntries([]);
+    }, []);
+    const hasValidEntries = useMemo(() => entries.some((e) => e.key.trim() !== "" && e.value.trim() !== ""), [entries]);
+    const toRuntimeEnv = useCallback(() => {
+        const result = {};
+        for (const entry of entries) {
+            const key = entry.key.trim();
+            if (key === "" || entry.value.trim() === "")
+                continue;
+            result[key] = { value: entry.value, isSecret: entry.isSecret };
+        }
+        return result;
+    }, [entries]);
+    const toSaveForFutureEnv = useCallback(() => {
+        const result = {};
+        for (const entry of entries) {
+            const key = entry.key.trim();
+            if (key === "" || entry.value.trim() === "")
+                continue;
+            if (!entry.saveForFuture)
+                continue;
+            result[key] = { value: entry.value, isSecret: entry.isSecret };
+        }
+        return result;
+    }, [entries]);
+    const hasSaveForFutureEntries = useMemo(() => entries.some((e) => e.saveForFuture &&
+        e.key.trim() !== "" &&
+        e.value.trim() !== ""), [entries]);
+    return {
+        entries,
+        addEntry,
+        removeEntry,
+        updateEntry,
+        clear,
+        isEmpty: entries.length === 0,
+        hasValidEntries,
+        toRuntimeEnv,
+        toSaveForFutureEnv,
+        hasSaveForFutureEntries,
+    };
+}
+//# sourceMappingURL=useSessionVariables.js.map

package/execution/useSessionVariables.js.map

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

package/execution/useSubmitApproval.d.ts

@@ -0,0 +1,39 @@
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+export interface UseSubmitApprovalReturn {
+    /**
+     * Submit an approval decision for a specific tool call within an
+     * execution. Resolves when the backend accepts the decision; the
+     * execution stream will deliver the updated state.
+     */
+    readonly submitApproval: (executionId: string, toolCallId: string, action: ApprovalAction, comment?: string) => Promise<void>;
+    /**
+     * Set of tool call IDs currently being submitted. Enables per-button
+     * loading state in batch approval scenarios where the user may
+     * approve one tool while another decision is still in flight.
+     */
+    readonly submittingToolCallIds: ReadonlySet<string>;
+    readonly error: Error | null;
+    readonly clearError: () => void;
+}
+/**
+ * Behavior hook that wraps `agentExecution.submitApproval()` with
+ * per-tool-call loading state and error management.
+ *
+ * Tracks submitting state per tool call ID (not a single boolean)
+ * because batch approvals allow concurrent decisions on different
+ * tool calls within the same execution.
+ *
+ * Platform builders who need full control over the approval UI use
+ * this hook directly. Those who prefer drop-in components use
+ * {@link ApprovalCard} which accepts the callback shape produced
+ * by this hook.
+ *
+ * @example
+ * ```tsx
+ * const { submitApproval, submittingToolCallIds, error } = useSubmitApproval();
+ *
+ * await submitApproval(executionId, toolCallId, ApprovalAction.APPROVAL_ACTION_APPROVE);
+ * ```
+ */
+export declare function useSubmitApproval(): UseSubmitApprovalReturn;
+//# sourceMappingURL=useSubmitApproval.d.ts.map

package/execution/useSubmitApproval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSubmitApproval.d.ts","sourceRoot":"","sources":["../../src/execution/useSubmitApproval.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAC;AAK9F,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,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CA8C3D"}

package/execution/useSubmitApproval.js

@@ -0,0 +1,62 @@
+"use client";
+import { useCallback, 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";
+/**
+ * Behavior hook that wraps `agentExecution.submitApproval()` with
+ * per-tool-call loading state and error management.
+ *
+ * Tracks submitting state per tool call ID (not a single boolean)
+ * because batch approvals allow concurrent decisions on different
+ * tool calls within the same execution.
+ *
+ * Platform builders who need full control over the approval UI use
+ * this hook directly. Those who prefer drop-in components use
+ * {@link ApprovalCard} which accepts the callback shape produced
+ * by this hook.
+ *
+ * @example
+ * ```tsx
+ * const { submitApproval, submittingToolCallIds, error } = useSubmitApproval();
+ *
+ * await submitApproval(executionId, toolCallId, ApprovalAction.APPROVAL_ACTION_APPROVE);
+ * ```
+ */
+export function useSubmitApproval() {
+    const stigmer = useStigmer();
+    const [submittingIds, setSubmittingIds] = useState(new Set());
+    const [error, setError] = useState(null);
+    const clearError = useCallback(() => setError(null), []);
+    const submitApproval = useCallback(async (executionId, toolCallId, action, comment) => {
+        setSubmittingIds((prev) => {
+            const next = new Set(prev);
+            next.add(toolCallId);
+            return next;
+        });
+        setError(null);
+        try {
+            const input = 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 };
+}
+//# sourceMappingURL=useSubmitApproval.js.map

package/execution/useSubmitApproval.js.map

@@ -0,0 +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;AAwB9C;;;;;;;;;;;;;;;;;;;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"}

package/github/GitHubRepoPicker.d.ts

@@ -0,0 +1,24 @@
+export interface GitHubRepoPickerProps {
+    /** GitHub access token for API calls. */
+    readonly token: string;
+    /** Called when the user selects a repo and branch. */
+    readonly onSelect: (repoUrl: string, branch: string) => void;
+    /** Called when the user dismisses the picker (Escape key). */
+    readonly onCancel?: () => void;
+    readonly className?: string;
+}
+/**
+ * Styled component for browsing and selecting a GitHub repository.
+ *
+ * Features:
+ * - Owner-grouped sections (personal repos first, then orgs)
+ * - Recently selected repos pinned at top
+ * - Fixed 300px max-height with scroll shadow indicators
+ * - Keyboard navigation (Arrow keys, Enter, Escape)
+ * - Search with match highlighting
+ * - Branch selector after repo selection
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ */
+export declare function GitHubRepoPicker({ token, onSelect, onCancel, className, }: GitHubRepoPickerProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=GitHubRepoPicker.d.ts.map

package/github/GitHubRepoPicker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubRepoPicker.d.ts","sourceRoot":"","sources":["../../src/github/GitHubRepoPicker.tsx"],"names":[],"mappings":"AAYA,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAuHD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,SAAS,GACV,EAAE,qBAAqB,2CAoWvB"}