@stigmer/react 0.0.36 → 0.0.40

package/agent/useAgentCount.d.ts

@@ -0,0 +1,49 @@
+import { type ResourceListScope } from "../search";
+export interface UseAgentCountOptions {
+    /** Text query to filter agents before counting. */
+    readonly query?: string;
+    /**
+     * Controls which agents are counted.
+     *
+     * - `"org"` — only agents owned by the given organization.
+     * - `"all"` — includes public/platform agents (e.g. `stigmer/agent-creator`).
+     *
+     * @default "org"
+     */
+    readonly scope?: ResourceListScope;
+}
+export interface UseAgentCountReturn {
+    /**
+     * Total number of agents matching the current filters. `undefined`
+     * until the first successful fetch completes.
+     */
+    readonly count: number | undefined;
+    readonly isLoading: boolean;
+    readonly error: string | null;
+    /** Re-fetch the count with the same parameters. */
+    readonly refetch: () => void;
+}
+/**
+ * Data hook that fetches the total count of agents.
+ *
+ * Issues a minimal `stigmer.agent.list()` call to retrieve only the
+ * total count — no agent entries are returned or stored. Useful for
+ * summary cards, badges, and dashboard widgets.
+ *
+ * For the full paginated agent list, use {@link useAgentList} instead.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { count, isLoading } = useAgentCount("acme");
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Count all accessible agents including public/platform ones
+ * const { count } = useAgentCount("acme", { scope: "all" });
+ * ```
+ */
+export declare function useAgentCount(org: string | null, options?: UseAgentCountOptions): UseAgentCountReturn;
+//# sourceMappingURL=useAgentCount.d.ts.map

package/agent/useAgentCount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentCount.d.ts","sourceRoot":"","sources":["../../src/agent/useAgentCount.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAErE,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,mBAAmB,CAUrB"}

package/agent/useAgentCount.js

@@ -0,0 +1,32 @@
+"use client";
+import { useCallback } from "react";
+import { useStigmer } from "../hooks";
+import { useResourceCount } from "../search";
+/**
+ * Data hook that fetches the total count of agents.
+ *
+ * Issues a minimal `stigmer.agent.list()` call to retrieve only the
+ * total count — no agent entries are returned or stored. Useful for
+ * summary cards, badges, and dashboard widgets.
+ *
+ * For the full paginated agent list, use {@link useAgentList} instead.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { count, isLoading } = useAgentCount("acme");
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Count all accessible agents including public/platform ones
+ * const { count } = useAgentCount("acme", { scope: "all" });
+ * ```
+ */
+export function useAgentCount(org, options) {
+    const stigmer = useStigmer();
+    const listFn = useCallback((params) => stigmer.agent.list(params), [stigmer]);
+    return useResourceCount(listFn, org, options);
+}
+//# sourceMappingURL=useAgentCount.js.map

package/agent/useAgentCount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentCount.js","sourceRoot":"","sources":["../../src/agent/useAgentCount.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAA0B,MAAM,WAAW,CAAC;AA4BrE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAkB,EAClB,OAA8B;IAE9B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAE7B,MAAM,MAAM,GAAG,WAAW,CACxB,CAAC,MAAgD,EAAE,EAAE,CACnD,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAC5B,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC"}

package/agent/useAgentList.d.ts

@@ -0,0 +1,62 @@
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { type ResourceListScope } from "../search";
+export interface UseAgentListOptions {
+    /** Maximum agents per page. @default 20 */
+    readonly pageSize?: number;
+    /** Page number (1-indexed). @default 1 */
+    readonly page?: number;
+    /** Text query to filter agents by name, description, or tags. */
+    readonly query?: string;
+    /**
+     * Controls which agents are visible.
+     *
+     * - `"org"` — only agents owned by the given organization.
+     * - `"all"` — includes public/platform agents (e.g. `stigmer/agent-creator`).
+     *
+     * @default "org"
+     */
+    readonly scope?: ResourceListScope;
+}
+export interface UseAgentListReturn {
+    /** Paginated agent entries for the current page. */
+    readonly agents: readonly SearchResult[];
+    /** Total number of agents matching the current filters. */
+    readonly totalCount: number;
+    /** Total pages available at the current page size. */
+    readonly totalPages: number;
+    /** The current page number (mirrors the `page` option). */
+    readonly currentPage: number;
+    readonly isLoading: boolean;
+    readonly error: string | null;
+    /** Re-fetch the current page with the same parameters. */
+    readonly refetch: () => void;
+}
+/**
+ * Data hook that fetches a paginated list of agents for the Library.
+ *
+ * Wraps `stigmer.agent.list()` with pagination, scope filtering,
+ * and text search. All parameters are externally controlled — the
+ * consumer manages page state, query debouncing, and scope toggling.
+ *
+ * For picker/type-ahead search with internal debouncing and query
+ * state management, use {@link useAgentSearch} instead.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { agents, totalCount, isLoading } = useAgentList("acme", {
+ *   page: 1,
+ *   pageSize: 20,
+ *   scope: "org",
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Show all agents including public/platform ones
+ * const { agents } = useAgentList("acme", { scope: "all" });
+ * ```
+ */
+export declare function useAgentList(org: string | null, options?: UseAgentListOptions): UseAgentListReturn;
+//# sourceMappingURL=useAgentList.d.ts.map

package/agent/useAgentList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentList.d.ts","sourceRoot":"","sources":["../../src/agent/useAgentList.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAE/E,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,kBAAkB,CAapB"}

package/agent/useAgentList.js

@@ -0,0 +1,38 @@
+"use client";
+import { useCallback } from "react";
+import { useStigmer } from "../hooks";
+import { useResourceList } from "../search";
+/**
+ * Data hook that fetches a paginated list of agents for the Library.
+ *
+ * Wraps `stigmer.agent.list()` with pagination, scope filtering,
+ * and text search. All parameters are externally controlled — the
+ * consumer manages page state, query debouncing, and scope toggling.
+ *
+ * For picker/type-ahead search with internal debouncing and query
+ * state management, use {@link useAgentSearch} instead.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { agents, totalCount, isLoading } = useAgentList("acme", {
+ *   page: 1,
+ *   pageSize: 20,
+ *   scope: "org",
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Show all agents including public/platform ones
+ * const { agents } = useAgentList("acme", { scope: "all" });
+ * ```
+ */
+export function useAgentList(org, options) {
+    const stigmer = useStigmer();
+    const listFn = useCallback((params) => stigmer.agent.list(params), [stigmer]);
+    const { entries, totalCount, totalPages, currentPage, isLoading, error, refetch } = useResourceList(listFn, org, options);
+    return { agents: entries, totalCount, totalPages, currentPage, isLoading, error, refetch };
+}
+//# sourceMappingURL=useAgentList.js.map

package/agent/useAgentList.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentList.js","sourceRoot":"","sources":["../../src/agent/useAgentList.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,eAAe,EAA0B,MAAM,WAAW,CAAC;AAmCpE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAkB,EAClB,OAA6B;IAE7B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAE7B,MAAM,MAAM,GAAG,WAAW,CACxB,CAAC,MAAgD,EAAE,EAAE,CACnD,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAC5B,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,GAC/E,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAExC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC7F,CAAC"}

package/agent/useAgentSearch.d.ts

@@ -0,0 +1,23 @@
+import { type UseResourceSearchOptions, type UseResourceSearchReturn } from "../search";
+export type UseAgentSearchOptions = UseResourceSearchOptions;
+export type UseAgentSearchReturn = UseResourceSearchReturn;
+/**
+ * Data hook that searches agents available in the given organization.
+ *
+ * Wraps `stigmer.agent.list()` with debounced search, loading/error
+ * tracking, and cancellation-safe fetching. Platform builders use this
+ * when they want full control over rendering; the {@link AgentPicker}
+ * styled component uses it internally.
+ *
+ * This is a Layer 1 building-block hook used by both platform builders
+ * (Profile A) and direct Stigmer users (Profile B). Platform builders
+ * can use it standalone to build custom agent selection UIs. The
+ * Stigmer Console composes it via higher-level orchestration hooks.
+ *
+ * @example
+ * ```tsx
+ * const { results, isLoading, query, setQuery } = useAgentSearch("acme");
+ * ```
+ */
+export declare function useAgentSearch(org: string, options?: UseAgentSearchOptions): UseAgentSearchReturn;
+//# sourceMappingURL=useAgentSearch.d.ts.map

package/agent/useAgentSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentSearch.d.ts","sourceRoot":"","sources":["../../src/agent/useAgentSearch.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC7B,MAAM,WAAW,CAAC;AAEnB,MAAM,MAAM,qBAAqB,GAAG,wBAAwB,CAAC;AAC7D,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,qBAAqB,GAC9B,oBAAoB,CAQtB"}

package/agent/useAgentSearch.js

@@ -0,0 +1,28 @@
+"use client";
+import { useCallback } from "react";
+import { useStigmer } from "../hooks";
+import { useResourceSearch, } from "../search";
+/**
+ * Data hook that searches agents available in the given organization.
+ *
+ * Wraps `stigmer.agent.list()` with debounced search, loading/error
+ * tracking, and cancellation-safe fetching. Platform builders use this
+ * when they want full control over rendering; the {@link AgentPicker}
+ * styled component uses it internally.
+ *
+ * This is a Layer 1 building-block hook used by both platform builders
+ * (Profile A) and direct Stigmer users (Profile B). Platform builders
+ * can use it standalone to build custom agent selection UIs. The
+ * Stigmer Console composes it via higher-level orchestration hooks.
+ *
+ * @example
+ * ```tsx
+ * const { results, isLoading, query, setQuery } = useAgentSearch("acme");
+ * ```
+ */
+export function useAgentSearch(org, options) {
+    const stigmer = useStigmer();
+    const listFn = useCallback((params) => stigmer.agent.list(params), [stigmer]);
+    return useResourceSearch(listFn, org, options);
+}
+//# sourceMappingURL=useAgentSearch.js.map

package/agent/useAgentSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentSearch.js","sourceRoot":"","sources":["../../src/agent/useAgentSearch.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EACL,iBAAiB,GAGlB,MAAM,WAAW,CAAC;AAKnB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,OAA+B;IAE/B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,WAAW,CACxB,CAAC,MAAgD,EAAE,EAAE,CACnD,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAC5B,CAAC,OAAO,CAAC,CACV,CAAC;IACF,OAAO,iBAAiB,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC"}

package/agent/useAgentSetup.d.ts

@@ -0,0 +1,115 @@
+import type { EnvVarInput, ResourceRef } from "@stigmer/sdk";
+import { type AgentSetupResult, type AgentSetupReadyResult, type AgentSetupState } from "./agentSetupReducer";
+export type { AgentResolution, AgentSetupResult, AgentSetupReadyResult, AgentSetupState, AgentSetupPhase, } from "./agentSetupReducer";
+export interface SubmitEnvVarsOptions {
+    /**
+     * When `true` (default), the provided values are saved to the user's
+     * personal environment and a personal agent instance is created.
+     * Subsequent runs of the same agent will reuse these credentials.
+     *
+     * When `false`, the values are collected as `runtimeEnv` for this
+     * execution only — no data is persisted and no agent instance is
+     * created. This path is instant (no network calls).
+     *
+     * @default true
+     */
+    readonly saveForFuture?: boolean;
+}
+export interface UseAgentSetupReturn {
+    /**
+     * Current state of the agent setup flow.
+     *
+     * A discriminated union on `status`:
+     * - `"idle"` — no agent selected
+     * - `"resolving"` — evaluating an agent's requirements
+     * - `"needsEnvVars"` — waiting for user to provide missing variables
+     * - `"submitting"` — saving environment / creating instance
+     * - `"ready"` — agent resolved, `resolution` describes how to proceed
+     *
+     * `error` is available on all variants (orthogonal to phase).
+     */
+    readonly state: AgentSetupState;
+    /**
+     * Evaluate whether an agent is ready to use or needs env var collection.
+     *
+     * Fetches the full agent to read its `env_spec`, checks for an existing
+     * personal instance, and diffs env_spec keys against the personal
+     * environment. Returns `"ready"` when the agent can be used immediately,
+     * or `"needsEnvVars"` when the caller should present {@link AgentEnvForm}.
+     */
+    readonly resolveAgent: (ref: ResourceRef) => Promise<AgentSetupResult>;
+    /**
+     * Complete the env var collection flow for the pending agent.
+     *
+     * Behavior depends on `options.saveForFuture`:
+     * - `true` (default) — Creates or updates the personal environment
+     *   with the provided values, then creates a personal agent instance.
+     *   Returns `{ resolution: { mode: "saved", instanceId } }`.
+     * - `false` — Collects values as `runtimeEnv` without any API calls.
+     *   Returns `{ resolution: { mode: "oneTime", runtimeEnv } }`.
+     *
+     * Must only be called when `state.status === "needsEnvVars"`.
+     */
+    readonly submitEnvVars: (values: Record<string, EnvVarInput>, options?: SubmitEnvVarsOptions) => Promise<AgentSetupReadyResult>;
+    /** Clear the error without changing the current phase. */
+    readonly clearError: () => void;
+    /** Reset to `idle` state, clearing all phase data and errors. */
+    readonly reset: () => void;
+}
+/**
+ * Layer 2 behavior hook that encapsulates the agent selection,
+ * personal environment resolution, and secret delivery routing flow.
+ *
+ * When a user picks an agent in the {@link AgentPicker}, this hook
+ * determines whether the agent requires credentials (via its
+ * `env_spec`), checks what the user has already provided in their
+ * personal environment, and either reports the agent as ready or
+ * identifies the missing variables so the caller can render
+ * {@link AgentEnvForm}.
+ *
+ * The hook supports two secret delivery paths via the `saveForFuture`
+ * option on {@link submitEnvVars}:
+ * - **Saved** — secrets are persisted to the personal environment and
+ *   a personal agent instance is created for reuse.
+ * - **One-time** — secrets are returned as `runtimeEnv` for a single
+ *   execution, with no data persisted.
+ *
+ * State is managed by a `useReducer` state machine with five phases:
+ * `idle → resolving → needsEnvVars → submitting → ready`.
+ *
+ * Composes {@link usePersonalEnvironment} for personal environment
+ * operations and calls the Stigmer client directly for agent and
+ * agent instance queries.
+ *
+ * > **Why not compose `usePersonalAgentInstance`?**
+ * > `resolveAgent` is an imperative async callback that needs
+ * > immediate results within a single invocation. Hook state
+ * > updates require a render cycle. Instance creation is delegated
+ * > through the shared `buildPersonalInstanceInput` helper instead.
+ *
+ * Pass `null` as `org` to disable all operations (stable no-op).
+ *
+ * @param org - Organization slug. Pass `null` to disable.
+ * @param poolKeys - Optional set of env-var keys already available
+ *   from the session env pool (manual secrets, one-time env vars from
+ *   other components). When provided, agents whose `env_spec` keys
+ *   are fully covered by `poolKeys` + personal env auto-resolve to
+ *   `ready` without prompting. Reactive — when `poolKeys` changes,
+ *   `needsEnvVars` is re-evaluated.
+ *
+ * @example
+ * ```tsx
+ * const { state, resolveAgent, submitEnvVars } = useAgentSetup("acme", pool.availableKeys);
+ *
+ * const result = await resolveAgent({ org: "acme", slug: "code-reviewer" });
+ *
+ * if (result.status === "needsEnvVars") {
+ *   // Render AgentEnvForm with result.missingVariables
+ *   // On form submit:
+ *   const ready = await submitEnvVars(formValues, { saveForFuture: true });
+ *   // ready.resolution.mode === "saved" | "oneTime"
+ * }
+ * ```
+ */
+export declare function useAgentSetup(org: string | null, poolKeys?: Set<string>): UseAgentSetupReturn;
+//# sourceMappingURL=useAgentSetup.d.ts.map

package/agent/useAgentSetup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentSetup.d.ts","sourceRoot":"","sources":["../../src/agent/useAgentSetup.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAW,MAAM,cAAc,CAAC;AAStE,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AA6C7B,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAEhC;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEvE;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,aAAa,EAAE,CACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACnC,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAEpC,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;IAEhC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,mBAAmB,CA8OrB"}

package/agent/useAgentSetup.js

@@ -0,0 +1,279 @@
+"use client";
+import { useCallback, useEffect, useReducer } from "react";
+import { create } from "@bufbuild/protobuf";
+import { ListAgentInstancesRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import { usePersonalEnvironment } from "../environment/usePersonalEnvironment";
+import { buildPersonalInstanceInput } from "../agent-instance/buildPersonalInstanceInput";
+import { diffEnvSpec } from "../environment/diffEnvSpec";
+import { agentSetupReducer, INITIAL_STATE, } from "./agentSetupReducer";
+const PERSONAL_LABEL = "stigmer.ai/personal";
+const FOR_AGENT_LABEL = "stigmer.ai/for-agent";
+/**
+ * Re-checks for an existing personal instance immediately before
+ * creating one. Narrows the race window when multiple clients
+ * (tabs, double-clicks) attempt to create simultaneously.
+ */
+async function findOrCreatePersonalInstance(stigmer, params) {
+    const { org, agentId, agentSlug, agentLabel, environmentRef } = params;
+    const recheck = await stigmer.agentInstance.list(create(ListAgentInstancesRequestSchema, {
+        org,
+        labels: {
+            [PERSONAL_LABEL]: "true",
+            [FOR_AGENT_LABEL]: agentLabel,
+        },
+    }));
+    if (recheck.items.length > 0) {
+        return recheck.items[0];
+    }
+    return stigmer.agentInstance.create(buildPersonalInstanceInput({ org, agentId, agentSlug, environmentRef }));
+}
+/**
+ * Layer 2 behavior hook that encapsulates the agent selection,
+ * personal environment resolution, and secret delivery routing flow.
+ *
+ * When a user picks an agent in the {@link AgentPicker}, this hook
+ * determines whether the agent requires credentials (via its
+ * `env_spec`), checks what the user has already provided in their
+ * personal environment, and either reports the agent as ready or
+ * identifies the missing variables so the caller can render
+ * {@link AgentEnvForm}.
+ *
+ * The hook supports two secret delivery paths via the `saveForFuture`
+ * option on {@link submitEnvVars}:
+ * - **Saved** — secrets are persisted to the personal environment and
+ *   a personal agent instance is created for reuse.
+ * - **One-time** — secrets are returned as `runtimeEnv` for a single
+ *   execution, with no data persisted.
+ *
+ * State is managed by a `useReducer` state machine with five phases:
+ * `idle → resolving → needsEnvVars → submitting → ready`.
+ *
+ * Composes {@link usePersonalEnvironment} for personal environment
+ * operations and calls the Stigmer client directly for agent and
+ * agent instance queries.
+ *
+ * > **Why not compose `usePersonalAgentInstance`?**
+ * > `resolveAgent` is an imperative async callback that needs
+ * > immediate results within a single invocation. Hook state
+ * > updates require a render cycle. Instance creation is delegated
+ * > through the shared `buildPersonalInstanceInput` helper instead.
+ *
+ * Pass `null` as `org` to disable all operations (stable no-op).
+ *
+ * @param org - Organization slug. Pass `null` to disable.
+ * @param poolKeys - Optional set of env-var keys already available
+ *   from the session env pool (manual secrets, one-time env vars from
+ *   other components). When provided, agents whose `env_spec` keys
+ *   are fully covered by `poolKeys` + personal env auto-resolve to
+ *   `ready` without prompting. Reactive — when `poolKeys` changes,
+ *   `needsEnvVars` is re-evaluated.
+ *
+ * @example
+ * ```tsx
+ * const { state, resolveAgent, submitEnvVars } = useAgentSetup("acme", pool.availableKeys);
+ *
+ * const result = await resolveAgent({ org: "acme", slug: "code-reviewer" });
+ *
+ * if (result.status === "needsEnvVars") {
+ *   // Render AgentEnvForm with result.missingVariables
+ *   // On form submit:
+ *   const ready = await submitEnvVars(formValues, { saveForFuture: true });
+ *   // ready.resolution.mode === "saved" | "oneTime"
+ * }
+ * ```
+ */
+export function useAgentSetup(org, poolKeys) {
+    const stigmer = useStigmer();
+    const personalEnv = usePersonalEnvironment(org);
+    const [state, dispatch] = useReducer(agentSetupReducer, INITIAL_STATE);
+    const clearError = useCallback(() => dispatch({ type: "CLEAR_ERROR" }), []);
+    const reset = useCallback(() => dispatch({ type: "RESET" }), []);
+    // -------------------------------------------------------------------------
+    // resolveAgent
+    // -------------------------------------------------------------------------
+    const resolveAgent = useCallback(async (ref) => {
+        if (!org) {
+            throw new Error("useAgentSetup: cannot resolve agent when org is null.");
+        }
+        dispatch({ type: "RESOLVE_START", agentRef: ref });
+        try {
+            const agent = await stigmer.agent.getByReference(ref);
+            const agentName = agent.metadata?.name ?? ref.slug;
+            const envSpecData = agent.spec?.envSpec?.data;
+            // No env_spec — agent is immediately ready (direct mode).
+            if (!envSpecData || Object.keys(envSpecData).length === 0) {
+                const resolution = { mode: "direct" };
+                dispatch({
+                    type: "RESOLVE_READY",
+                    agentRef: ref,
+                    agentName,
+                    resolution,
+                });
+                return { status: "ready", agentRef: ref, agentName, resolution };
+            }
+            // Agent has env_spec — check for existing personal instance.
+            const agentLabel = `${ref.org}/${ref.slug}`;
+            const instanceList = await stigmer.agentInstance.list(create(ListAgentInstancesRequestSchema, {
+                org,
+                labels: {
+                    [PERSONAL_LABEL]: "true",
+                    [FOR_AGENT_LABEL]: agentLabel,
+                },
+            }));
+            if (instanceList.items.length > 0) {
+                const resolution = {
+                    mode: "saved",
+                    instanceId: instanceList.items[0].metadata.id,
+                };
+                dispatch({
+                    type: "RESOLVE_READY",
+                    agentRef: ref,
+                    agentName,
+                    resolution,
+                });
+                return { status: "ready", agentRef: ref, agentName, resolution };
+            }
+            // No personal instance — diff against existing env keys + pool.
+            const existingKeys = new Set(Object.keys(personalEnv.environment?.spec?.data ?? {}));
+            const personalOnlyMissing = diffEnvSpec(envSpecData, existingKeys);
+            const missingVariables = diffEnvSpec(envSpecData, existingKeys, poolKeys);
+            if (personalOnlyMissing.length === 0) {
+                // Personal env covers all keys — create personal instance.
+                const env = await personalEnv.getOrCreate();
+                const envRef = {
+                    org,
+                    slug: env.metadata.slug,
+                    kind: ApiResourceKind.environment,
+                };
+                const instance = await findOrCreatePersonalInstance(stigmer, {
+                    org,
+                    agentId: agent.metadata.id,
+                    agentSlug: ref.slug,
+                    agentLabel,
+                    environmentRef: envRef,
+                });
+                const resolution = {
+                    mode: "saved",
+                    instanceId: instance.metadata.id,
+                };
+                dispatch({
+                    type: "RESOLVE_READY",
+                    agentRef: ref,
+                    agentName,
+                    resolution,
+                });
+                return { status: "ready", agentRef: ref, agentName, resolution };
+            }
+            if (missingVariables.length === 0) {
+                // Pool covers remaining keys — use default instance, pool
+                // values flow via sessionVariables.toRuntimeEnv() at submit.
+                const resolution = { mode: "direct" };
+                dispatch({
+                    type: "RESOLVE_READY",
+                    agentRef: ref,
+                    agentName,
+                    resolution,
+                });
+                return { status: "ready", agentRef: ref, agentName, resolution };
+            }
+            // Missing variables — transition to needsEnvVars.
+            dispatch({
+                type: "RESOLVE_NEEDS_ENV",
+                agentRef: ref,
+                agentId: agent.metadata.id,
+                agentName,
+                missingVariables,
+            });
+            return {
+                status: "needsEnvVars",
+                agentRef: ref,
+                agentName,
+                missingVariables,
+            };
+        }
+        catch (err) {
+            dispatch({ type: "ERROR", error: toError(err) });
+            throw err;
+        }
+    }, [org, stigmer, personalEnv, poolKeys]);
+    // -------------------------------------------------------------------------
+    // Pool re-evaluation — auto-resolve needsEnvVars when pool changes
+    // -------------------------------------------------------------------------
+    const agentMissingVars = state.status === "needsEnvVars" ? state.missingVariables : null;
+    useEffect(() => {
+        if (!poolKeys || poolKeys.size === 0)
+            return;
+        if (!agentMissingVars)
+            return;
+        const stillMissing = agentMissingVars.filter((v) => !poolKeys.has(v.key));
+        dispatch({ type: "POOL_RESOLVE", missingVariables: stillMissing });
+    }, [poolKeys, agentMissingVars]);
+    // -------------------------------------------------------------------------
+    // submitEnvVars
+    // -------------------------------------------------------------------------
+    const submitEnvVars = useCallback(async (values, options) => {
+        if (state.status !== "needsEnvVars") {
+            throw new Error("useAgentSetup: submitEnvVars requires state.status === 'needsEnvVars'. " +
+                `Current status is '${state.status}'. Call resolveAgent() first ` +
+                "and ensure it returned status 'needsEnvVars'.");
+        }
+        if (!org) {
+            throw new Error("useAgentSetup: cannot submit env vars when org is null.");
+        }
+        const { agentRef, agentId, agentName } = state;
+        const saveForFuture = options?.saveForFuture ?? true;
+        // ----- One-time path: no API calls, instant result -----
+        if (!saveForFuture) {
+            const resolution = {
+                mode: "oneTime",
+                runtimeEnv: values,
+            };
+            dispatch({
+                type: "SUBMIT_READY",
+                agentRef,
+                agentName,
+                resolution,
+            });
+            return { status: "ready", agentRef, agentName, resolution };
+        }
+        // ----- Save path: persist to environment + create instance -----
+        dispatch({ type: "SUBMIT_START" });
+        try {
+            const env = await personalEnv.getOrCreate();
+            await personalEnv.addVariables(values);
+            const envRef = {
+                org,
+                slug: env.metadata.slug,
+                kind: ApiResourceKind.environment,
+            };
+            const agentLabel = `${agentRef.org}/${agentRef.slug}`;
+            const instance = await findOrCreatePersonalInstance(stigmer, {
+                org,
+                agentId,
+                agentSlug: agentRef.slug,
+                agentLabel,
+                environmentRef: envRef,
+            });
+            const resolution = {
+                mode: "saved",
+                instanceId: instance.metadata.id,
+            };
+            dispatch({
+                type: "SUBMIT_READY",
+                agentRef,
+                agentName,
+                resolution,
+            });
+            return { status: "ready", agentRef, agentName, resolution };
+        }
+        catch (err) {
+            dispatch({ type: "ERROR", error: toError(err) });
+            throw err;
+        }
+    }, [org, stigmer, personalEnv, state]);
+    return { state, resolveAgent, submitEnvVars, clearError, reset };
+}
+//# sourceMappingURL=useAgentSetup.js.map