@stigmer/react 0.0.36 → 0.0.40

package/session/group-sessions.js

@@ -0,0 +1,61 @@
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+/**
+ * Groups sessions by their creation timestamp into time-based buckets:
+ * "Today", "Yesterday", "Previous 7 Days", "Previous 30 Days", "Older".
+ *
+ * Empty groups are omitted. Sessions with missing timestamps are placed
+ * in the last group. Input order is preserved within each group.
+ *
+ * @param sessions - List of sessions to group (typically from `useSessionList`).
+ * @param now - Reference time for grouping; defaults to the current time.
+ *              Accepts an explicit value for deterministic testing.
+ */
+export function groupSessionsByTime(sessions, now) {
+    const ref = now ?? new Date();
+    const todayStart = startOfDay(ref);
+    const yesterdayStart = addDays(todayStart, -1);
+    const sevenDaysAgo = addDays(todayStart, -6);
+    const thirtyDaysAgo = addDays(todayStart, -29);
+    const buckets = [
+        { label: "Today", sessions: [] },
+        { label: "Yesterday", sessions: [] },
+        { label: "Previous 7 Days", sessions: [] },
+        { label: "Previous 30 Days", sessions: [] },
+        { label: "Older", sessions: [] },
+    ];
+    for (const session of sessions) {
+        const ts = session.status?.audit?.specAudit?.createdAt;
+        const date = ts ? timestampDate(ts) : null;
+        if (!date) {
+            buckets[buckets.length - 1].sessions.push(session);
+            continue;
+        }
+        if (date >= todayStart) {
+            buckets[0].sessions.push(session);
+        }
+        else if (date >= yesterdayStart) {
+            buckets[1].sessions.push(session);
+        }
+        else if (date >= sevenDaysAgo) {
+            buckets[2].sessions.push(session);
+        }
+        else if (date >= thirtyDaysAgo) {
+            buckets[3].sessions.push(session);
+        }
+        else {
+            buckets[4].sessions.push(session);
+        }
+    }
+    return buckets.filter((b) => b.sessions.length > 0);
+}
+function startOfDay(date) {
+    const d = new Date(date);
+    d.setHours(0, 0, 0, 0);
+    return d;
+}
+function addDays(date, days) {
+    const d = new Date(date);
+    d.setDate(d.getDate() + days);
+    return d;
+}
+//# sourceMappingURL=group-sessions.js.map

package/session/group-sessions.js.map

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

package/session/index.d.ts

@@ -1,7 +1,18 @@
-export { useAgentSessionList } from "./hooks/useAgentSessionList";
-export type { UseAgentSessionListOptions, UseAgentSessionListReturn, } from "./hooks/useAgentSessionList";
-export { SessionCard } from "./components/SessionCard";
-export type { SessionCardProps } from "./components/SessionCard";
-export { AgentSessionHistory } from "./components/AgentSessionHistory";
-export type { AgentSessionHistoryProps } from "./components/AgentSessionHistory";
+export { useCreateSession } from "./useCreateSession";
+export type { CreateSessionInput, CreateSessionResult, UseCreateSessionReturn, } from "./useCreateSession";
+export { useUpdateSession } from "./useUpdateSession";
+export type { UseUpdateSessionReturn } from "./useUpdateSession";
+export { useSession } from "./useSession";
+export type { UseSessionReturn } from "./useSession";
+export { useSessionList } from "./useSessionList";
+export type { UseSessionListOptions, UseSessionListReturn, } from "./useSessionList";
+export { useSessionExecutions } from "./useSessionExecutions";
+export type { UseSessionExecutionsReturn } from "./useSessionExecutions";
+export { useSessionConversation } from "./useSessionConversation";
+export type { SendFollowUpOptions, UseSessionConversationReturn, } from "./useSessionConversation";
+export { useAgentRefFromSession } from "./useAgentRefFromSession";
+export type { UseAgentRefFromSessionReturn } from "./useAgentRefFromSession";
+export { groupSessionsByTime } from "./group-sessions";
+export type { SessionGroup } from "./group-sessions";
+export { PENDING_SUBJECT, resolvedSubject } from "@stigmer/sdk";
 //# sourceMappingURL=index.d.ts.map

package/session/index.d.ts.map

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

package/session/index.js

@@ -1,6 +1,11 @@
-// Hooks
-export { useAgentSessionList } from "./hooks/useAgentSessionList";
-// Components
-export { SessionCard } from "./components/SessionCard";
-export { AgentSessionHistory } from "./components/AgentSessionHistory";
+export { useCreateSession } from "./useCreateSession";
+export { useUpdateSession } from "./useUpdateSession";
+export { useSession } from "./useSession";
+export { useSessionList } from "./useSessionList";
+export { useSessionExecutions } from "./useSessionExecutions";
+export { useSessionConversation } from "./useSessionConversation";
+export { useAgentRefFromSession } from "./useAgentRefFromSession";
+export { groupSessionsByTime } from "./group-sessions";
+// Session utilities (re-exported from @stigmer/sdk)
+export { PENDING_SUBJECT, resolvedSubject } from "@stigmer/sdk";
 //# sourceMappingURL=index.js.map

package/session/index.js.map

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

package/session/useAgentRefFromSession.d.ts

@@ -0,0 +1,28 @@
+import type { ResourceRef } from "@stigmer/sdk";
+export interface UseAgentRefFromSessionReturn {
+    /** Resolved agent reference, or `null` while loading / on error. */
+    readonly agentRef: ResourceRef | null;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+}
+/**
+ * Derives an {@link ResourceRef} for the agent used by a session,
+ * given the session's `agentInstanceId`.
+ *
+ * Chains two lookups:
+ * 1. `agentInstance.get(instanceId)` → `spec.agentId`
+ * 2. `agent.get(agentId)` → `metadata.org` + `metadata.slug`
+ *
+ * Pass `null` or empty string to skip (stable no-op). The hook
+ * re-derives when `instanceId` changes and discards stale in-flight
+ * requests via cancellation.
+ *
+ * @example
+ * ```tsx
+ * const { agentRef, isLoading } = useAgentRefFromSession(
+ *   session?.spec?.agentInstanceId ?? null,
+ * );
+ * ```
+ */
+export declare function useAgentRefFromSession(instanceId: string | null | undefined): UseAgentRefFromSessionReturn;
+//# sourceMappingURL=useAgentRefFromSession.d.ts.map

package/session/useAgentRefFromSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentRefFromSession.d.ts","sourceRoot":"","sources":["../../src/session/useAgentRefFromSession.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,MAAM,WAAW,4BAA4B;IAC3C,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACpC,4BAA4B,CAyD9B"}

package/session/useAgentRefFromSession.js

@@ -0,0 +1,73 @@
+"use client";
+import { useEffect, useState } from "react";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+/**
+ * Derives an {@link ResourceRef} for the agent used by a session,
+ * given the session's `agentInstanceId`.
+ *
+ * Chains two lookups:
+ * 1. `agentInstance.get(instanceId)` → `spec.agentId`
+ * 2. `agent.get(agentId)` → `metadata.org` + `metadata.slug`
+ *
+ * Pass `null` or empty string to skip (stable no-op). The hook
+ * re-derives when `instanceId` changes and discards stale in-flight
+ * requests via cancellation.
+ *
+ * @example
+ * ```tsx
+ * const { agentRef, isLoading } = useAgentRefFromSession(
+ *   session?.spec?.agentInstanceId ?? null,
+ * );
+ * ```
+ */
+export function useAgentRefFromSession(instanceId) {
+    const stigmer = useStigmer();
+    const [agentRef, setAgentRef] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        if (!instanceId) {
+            setAgentRef(null);
+            setIsLoading(false);
+            setError(null);
+            return;
+        }
+        const cancelled = { current: false };
+        setIsLoading(true);
+        setError(null);
+        (async () => {
+            const instance = await stigmer.agentInstance.get(instanceId);
+            if (cancelled.current)
+                return;
+            const agentId = instance.spec?.agentId;
+            if (!agentId) {
+                throw new Error(`AgentInstance "${instanceId}" has no spec.agentId. ` +
+                    "Cannot derive an agent reference.");
+            }
+            const agent = await stigmer.agent.get(agentId);
+            if (cancelled.current)
+                return;
+            const org = agent.metadata?.org;
+            const slug = agent.metadata?.slug;
+            if (!org || !slug) {
+                throw new Error(`Agent "${agentId}" is missing metadata.org or metadata.slug. ` +
+                    "Cannot construct a ResourceRef.");
+            }
+            setAgentRef({ org, slug, kind: ApiResourceKind.agent });
+            setIsLoading(false);
+        })().catch((err) => {
+            if (cancelled.current)
+                return;
+            setError(toError(err));
+            setAgentRef(null);
+            setIsLoading(false);
+        });
+        return () => {
+            cancelled.current = true;
+        };
+    }, [instanceId, stigmer]);
+    return { agentRef, isLoading, error };
+}
+//# sourceMappingURL=useAgentRefFromSession.js.map

package/session/useAgentRefFromSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentRefFromSession.js","sourceRoot":"","sources":["../../src/session/useAgentRefFromSession.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,qFAAqF,CAAC;AACtH,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAS9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAqC;IAErC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAqB,IAAI,CAAC,CAAC;IACnE,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IAEvD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,WAAW,CAAC,IAAI,CAAC,CAAC;YAClB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC,CAAC;YACf,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACrC,YAAY,CAAC,IAAI,CAAC,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,CAAC,KAAK,IAAI,EAAE;YACV,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC7D,IAAI,SAAS,CAAC,OAAO;gBAAE,OAAO;YAE9B,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;YACvC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CACb,kBAAkB,UAAU,yBAAyB;oBACnD,mCAAmC,CACtC,CAAC;YACJ,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC/C,IAAI,SAAS,CAAC,OAAO;gBAAE,OAAO;YAE9B,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC;YAChC,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC;YAClC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CACb,UAAU,OAAO,8CAA8C;oBAC7D,iCAAiC,CACpC,CAAC;YACJ,CAAC;YAED,WAAW,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC;YACxD,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACjB,IAAI,SAAS,CAAC,OAAO;gBAAE,OAAO;YAC9B,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YACvB,WAAW,CAAC,IAAI,CAAC,CAAC;YAClB,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,EAAE;YACV,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;QAC3B,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAE1B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACxC,CAAC"}

package/session/useCreateSession.d.ts

@@ -0,0 +1,73 @@
+import { type McpServerUsageInput, type ResourceRef, type WorkspaceEntryInput } from "@stigmer/sdk";
+interface SharedSessionFields {
+    readonly org: string;
+    readonly workspaceEntries?: WorkspaceEntryInput[];
+    readonly subject?: string;
+    readonly mcpServerUsages?: McpServerUsageInput[];
+    readonly skillRefs?: ResourceRef[];
+}
+/**
+ * Input for creating a session. Exactly one agent resolution strategy
+ * must be provided:
+ *
+ * - **`agentInstanceId`** — Use a pre-provisioned AgentInstance directly.
+ * - **`agentRef`** — Resolve the agent's default instance via
+ *   `agent.getByReference()`.
+ *
+ * Providing both is a type error. Platform builders who need the
+ * backend's implicit agent resolution can use `@stigmer/sdk`'s
+ * `session.create()` directly.
+ */
+export type CreateSessionInput = SharedSessionFields & ({
+    readonly agentInstanceId: string;
+    readonly agentRef?: never;
+} | {
+    readonly agentRef: ResourceRef;
+    readonly agentInstanceId?: never;
+});
+export interface CreateSessionResult {
+    readonly sessionId: string;
+}
+export interface UseCreateSessionReturn {
+    readonly create: (input: CreateSessionInput) => Promise<CreateSessionResult>;
+    readonly isCreating: boolean;
+    readonly error: Error | null;
+    readonly clearError: () => void;
+}
+/**
+ * Behavior hook that wraps `session.create()` with loading/error state.
+ *
+ * Creates a Session — the conversation context that holds workspace
+ * entries, thread state, and sandbox references.
+ *
+ * Exactly one agent resolution strategy must be provided:
+ *
+ * 1. **`agentInstanceId`** — Use a pre-provisioned instance directly.
+ *    Typical for platform builders who manage instances programmatically.
+ * 2. **`agentRef`** — Resolve the agent's default instance via
+ *    `agent.getByReference()`. Useful when you know the agent slug
+ *    but not the instance ID.
+ *
+ * This hook maps 1:1 to the Session aggregate. To start the first
+ * execution within the session, compose with {@link useCreateAgentExecution}.
+ *
+ * @example
+ * ```tsx
+ * // Platform builder: pre-provisioned instance
+ * const { create } = useCreateSession();
+ * await create({ org: "acme", agentInstanceId: "inst-abc123" });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Agent reference: resolves to the agent's default instance
+ * const { create } = useCreateSession();
+ * await create({
+ *   org: "acme",
+ *   agentRef: { org: "acme", slug: "code-reviewer" },
+ * });
+ * ```
+ */
+export declare function useCreateSession(): UseCreateSessionReturn;
+export {};
+//# sourceMappingURL=useCreateSession.d.ts.map

package/session/useCreateSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCreateSession.d.ts","sourceRoot":"","sources":["../../src/session/useCreateSession.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAItB,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAClD,CACI;IAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,CAAA;CAAE,CACvE,CAAC;AAEJ,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC7E,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,gBAAgB,IAAI,sBAAsB,CA0DzD"}

package/session/useCreateSession.js

@@ -0,0 +1,87 @@
+"use client";
+import { useCallback, useState } from "react";
+import { PENDING_SUBJECT, } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+/**
+ * Behavior hook that wraps `session.create()` with loading/error state.
+ *
+ * Creates a Session — the conversation context that holds workspace
+ * entries, thread state, and sandbox references.
+ *
+ * Exactly one agent resolution strategy must be provided:
+ *
+ * 1. **`agentInstanceId`** — Use a pre-provisioned instance directly.
+ *    Typical for platform builders who manage instances programmatically.
+ * 2. **`agentRef`** — Resolve the agent's default instance via
+ *    `agent.getByReference()`. Useful when you know the agent slug
+ *    but not the instance ID.
+ *
+ * This hook maps 1:1 to the Session aggregate. To start the first
+ * execution within the session, compose with {@link useCreateAgentExecution}.
+ *
+ * @example
+ * ```tsx
+ * // Platform builder: pre-provisioned instance
+ * const { create } = useCreateSession();
+ * await create({ org: "acme", agentInstanceId: "inst-abc123" });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Agent reference: resolves to the agent's default instance
+ * const { create } = useCreateSession();
+ * await create({
+ *   org: "acme",
+ *   agentRef: { org: "acme", slug: "code-reviewer" },
+ * });
+ * ```
+ */
+export function useCreateSession() {
+    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 {
+            let resolvedInstanceId;
+            if (input.agentInstanceId) {
+                resolvedInstanceId = input.agentInstanceId;
+            }
+            else if (input.agentRef) {
+                const agent = await stigmer.agent.getByReference(input.agentRef);
+                const defaultId = agent.status?.defaultInstanceId;
+                if (!defaultId) {
+                    throw new Error(`Agent "${input.agentRef.org}/${input.agentRef.slug}" does not have a default instance. ` +
+                        `Pass an explicit agentInstanceId instead.`);
+                }
+                resolvedInstanceId = defaultId;
+            }
+            else {
+                throw new Error("useCreateSession requires either agentInstanceId or agentRef. " +
+                    "Provide one to specify which agent this session should use.");
+            }
+            const session = await stigmer.session.create({
+                name: `session-${Date.now()}`,
+                org: input.org,
+                subject: input.subject ?? PENDING_SUBJECT,
+                workspaceEntries: input.workspaceEntries,
+                mcpServerUsages: input.mcpServerUsages,
+                skillRefs: input.skillRefs,
+                agentInstanceId: resolvedInstanceId,
+            });
+            return { sessionId: session.metadata.id };
+        }
+        catch (err) {
+            setError(toError(err));
+            throw err;
+        }
+        finally {
+            setIsCreating(false);
+        }
+    }, [stigmer]);
+    return { create, isCreating, error, clearError };
+}
+//# sourceMappingURL=useCreateSession.js.map

package/session/useCreateSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCreateSession.js","sourceRoot":"","sources":["../../src/session/useCreateSession.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,EACL,eAAe,GAIhB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAuC9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,gBAAgB;IAC9B,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,EAAE,KAAyB,EAAgC,EAAE;QAChE,aAAa,CAAC,IAAI,CAAC,CAAC;QACpB,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,IAAI,CAAC;YACH,IAAI,kBAA0B,CAAC;YAE/B,IAAI,KAAK,CAAC,eAAe,EAAE,CAAC;gBAC1B,kBAAkB,GAAG,KAAK,CAAC,eAAe,CAAC;YAC7C,CAAC;iBAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;gBAC1B,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBACjE,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,iBAAiB,CAAC;gBAElD,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,MAAM,IAAI,KAAK,CACb,UAAU,KAAK,CAAC,QAAQ,CAAC,GAAG,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,sCAAsC;wBACvF,2CAA2C,CAC9C,CAAC;gBACJ,CAAC;gBAED,kBAAkB,GAAG,SAAS,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CACb,gEAAgE;oBAC9D,6DAA6D,CAChE,CAAC;YACJ,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC;gBAC3C,IAAI,EAAE,WAAW,IAAI,CAAC,GAAG,EAAE,EAAE;gBAC7B,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,eAAe;gBACzC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;gBACxC,eAAe,EAAE,KAAK,CAAC,eAAe;gBACtC,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,eAAe,EAAE,kBAAkB;aACpC,CAAC,CAAC;YAEH,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,QAAS,CAAC,EAAE,EAAE,CAAC;QAC7C,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/session/useSession.d.ts

@@ -0,0 +1,17 @@
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+export interface UseSessionReturn {
+    readonly session: Session | null;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+}
+/**
+ * Data hook that fetches a single Session by ID.
+ *
+ * Pass `null` to skip fetching (stable no-op). When the `id` changes,
+ * the previous in-flight request is discarded and a fresh fetch begins.
+ *
+ * Returns the full proto {@link Session} resource so consumers have
+ * access to metadata, spec, and status without additional calls.
+ */
+export declare function useSession(id: string | null): UseSessionReturn;
+//# sourceMappingURL=useSession.d.ts.map

package/session/useSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSession.d.ts","sourceRoot":"","sources":["../../src/session/useSession.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sDAAsD,CAAC;AAIpF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,gBAAgB,CAqC9D"}

package/session/useSession.js

@@ -0,0 +1,46 @@
+"use client";
+import { useEffect, useState } from "react";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+/**
+ * Data hook that fetches a single Session by ID.
+ *
+ * Pass `null` to skip fetching (stable no-op). When the `id` changes,
+ * the previous in-flight request is discarded and a fresh fetch begins.
+ *
+ * Returns the full proto {@link Session} resource so consumers have
+ * access to metadata, spec, and status without additional calls.
+ */
+export function useSession(id) {
+    const stigmer = useStigmer();
+    const [session, setSession] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        if (!id) {
+            setSession(null);
+            setIsLoading(false);
+            setError(null);
+            return;
+        }
+        const cancelled = { current: false };
+        setIsLoading(true);
+        setError(null);
+        stigmer.session.get(id).then((result) => {
+            if (cancelled.current)
+                return;
+            setSession(result);
+            setIsLoading(false);
+        }, (err) => {
+            if (cancelled.current)
+                return;
+            setError(toError(err));
+            setIsLoading(false);
+        });
+        return () => {
+            cancelled.current = true;
+        };
+    }, [id, stigmer]);
+    return { session, isLoading, error };
+}
+//# sourceMappingURL=useSession.js.map

package/session/useSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSession.js","sourceRoot":"","sources":["../../src/session/useSession.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAQ9C;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,EAAiB;IAC1C,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAiB,IAAI,CAAC,CAAC;IAC7D,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IAEvD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,UAAU,CAAC,IAAI,CAAC,CAAC;YACjB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC,CAAC;YACf,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACrC,YAAY,CAAC,IAAI,CAAC,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEf,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAC1B,CAAC,MAAM,EAAE,EAAE;YACT,IAAI,SAAS,CAAC,OAAO;gBAAE,OAAO;YAC9B,UAAU,CAAC,MAAM,CAAC,CAAC;YACnB,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,EACD,CAAC,GAAG,EAAE,EAAE;YACN,IAAI,SAAS,CAAC,OAAO;gBAAE,OAAO;YAC9B,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YACvB,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CACF,CAAC;QAEF,OAAO,GAAG,EAAE;YACV,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;QAC3B,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;IAElB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACvC,CAAC"}

package/session/useSessionConversation.d.ts

@@ -0,0 +1,151 @@
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import { ApprovalAction, type ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import type { McpServerUsage as ProtoMcpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { WorkspaceEntry as ProtoWorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
+import type { ApiResourceReference as ProtoApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import type { AttachmentInput, EnvVarInput, McpServerUsageInput, ResourceRef, WorkspaceEntryInput } from "@stigmer/sdk";
+/**
+ * Options for {@link UseSessionConversationReturn.sendFollowUp}.
+ *
+ * Session-level fields (`workspaceEntries`, `mcpServerUsages`,
+ * `skillRefs`) trigger a `session.update()` before the execution is
+ * created. Only provided fields are overwritten; omitted fields
+ * preserve the session's existing values.
+ *
+ * `runtimeEnv` is forwarded to the execution (Execution Flow). These
+ * values are scoped to the single execution and deleted on completion.
+ */
+export interface SendFollowUpOptions {
+    readonly modelName?: string;
+    /**
+     * Override the session's agent instance for this and all future
+     * executions. When provided, the session is updated before the
+     * execution is created.
+     */
+    readonly agentInstanceId?: string;
+    readonly workspaceEntries?: WorkspaceEntryInput[];
+    readonly mcpServerUsages?: McpServerUsageInput[];
+    readonly skillRefs?: ResourceRef[];
+    /**
+     * 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 override both
+     * Environment values and agent defaults.
+     *
+     * @see {@link CreateAgentExecutionInput.runtimeEnv}
+     */
+    readonly runtimeEnv?: Record<string, EnvVarInput>;
+    /**
+     * Pre-uploaded file attachments for this execution.
+     *
+     * Each entry must include a `storageKey` from
+     * `agentExecution.uploadAttachment()`. Forwarded directly to
+     * execution creation.
+     *
+     * @see {@link CreateAgentExecutionInput.attachments}
+     */
+    readonly attachments?: AttachmentInput[];
+}
+export interface UseSessionConversationReturn {
+    /** The session object, or null while loading. */
+    readonly session: Session | null;
+    /** Executions in terminal phases, in chronological order. */
+    readonly completedExecutions: readonly AgentExecution[];
+    /** Currently streaming execution (stream or fetch fallback), or null. */
+    readonly activeStreamExecution: AgentExecution | null;
+    /** Phase of the active execution, or null if none active. */
+    readonly activePhase: ExecutionPhase | null;
+    /** True while the active execution's stream is delivering updates. */
+    readonly isStreaming: boolean;
+    /**
+     * Submit a follow-up message. Internally creates an execution and
+     * starts streaming it.
+     *
+     * When session-level fields (`agentInstanceId`, `workspaceEntries`,
+     * `mcpServerUsages`, `skillRefs`) are provided in options, the
+     * session is updated via `session.update()` before creating the
+     * execution.
+     */
+    readonly sendFollowUp: (message: string, options?: SendFollowUpOptions) => Promise<void>;
+    /** True when the input should be enabled (no active execution, not creating). */
+    readonly canSendFollowUp: boolean;
+    /** True during the create RPC call (between submit and execution ID). */
+    readonly isSending: boolean;
+    /** Error from the last sendFollowUp attempt, or null. */
+    readonly sendError: Error | null;
+    readonly clearSendError: () => void;
+    /** The user's message text, shown in the thread before the stream delivers it. */
+    readonly pendingUserMessage: string | null;
+    /** Current workspace entries from the session spec. Empty array when session is not loaded. */
+    readonly workspaceEntries: readonly ProtoWorkspaceEntry[];
+    /** Current MCP server usages from the session spec. Empty array when session is not loaded. */
+    readonly mcpServerUsages: readonly ProtoMcpServerUsage[];
+    /** Current skill references from the session spec. Empty array when session is not loaded. */
+    readonly skillRefs: readonly ProtoApiResourceReference[];
+    /** Pending approval requests from the active execution, empty when none. */
+    readonly pendingApprovals: readonly PendingApproval[];
+    /** Submit an approval decision. The executionId is managed internally. */
+    readonly submitApproval: (toolCallId: string, action: ApprovalAction, comment?: string) => Promise<void>;
+    /** Set of tool call IDs currently being submitted for approval. */
+    readonly submittingApprovalIds: ReadonlySet<string>;
+    /**
+     * Tool call IDs that have been submitted and should be hidden from
+     * the approval UI. Pass to {@link MessageThread.dismissedApprovalIds}
+     * for optimistic removal.
+     */
+    readonly dismissedApprovalIds: ReadonlySet<string>;
+    readonly approvalError: Error | null;
+    readonly clearApprovalError: () => void;
+    readonly isLoading: boolean;
+    readonly loadError: Error | null;
+    readonly streamError: Error | null;
+    readonly reconnectStream: () => void;
+}
+/**
+ * Behavior hook that encapsulates the full conversation lifecycle for
+ * a session: loading data, streaming the active execution, submitting
+ * follow-up messages, and updating session-level workspace entries.
+ *
+ * Composes {@link useSession}, {@link useSessionExecutions},
+ * {@link useCreateAgentExecution}, {@link useExecutionStream}, and
+ * {@link useUpdateSession} into a single return value that drives
+ * both {@link MessageThread} and {@link SessionComposer}.
+ *
+ * Platform builders get the complete conversation loop without
+ * reimplementing orchestration logic.
+ *
+ * @param sessionId - Session to display and converse in. Pass `null` to skip.
+ * @param org - Organization slug for creating follow-up executions.
+ *
+ * @example
+ * ```tsx
+ * function Chat({ sessionId, org }: { sessionId: string; org: string }) {
+ *   const conv = useSessionConversation(sessionId, org);
+ *
+ *   if (conv.isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <>
+ *       <MessageThread
+ *         executions={conv.completedExecutions}
+ *         activeStreamExecution={conv.activeStreamExecution}
+ *         pendingUserMessage={conv.pendingUserMessage}
+ *         onApprovalSubmit={conv.submitApproval}
+ *         submittingApprovalIds={conv.submittingApprovalIds}
+ *         dismissedApprovalIds={conv.dismissedApprovalIds}
+ *       />
+ *       <SessionComposer
+ *         onSubmit={(msg, model) => conv.sendFollowUp(msg, { modelName: model })}
+ *         disabled={!conv.canSendFollowUp}
+ *         isSubmitting={conv.isSending}
+ *       />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSessionConversation(sessionId: string | null, org: string): UseSessionConversationReturn;
+//# sourceMappingURL=useSessionConversation.d.ts.map

package/session/useSessionConversation.d.ts.map

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