@stigmer/react 0.0.92 → 0.0.93

package/src/session/draft.ts

@@ -0,0 +1,82 @@
+import type { ResourceRef } from "@stigmer/sdk";
+
+/**
+ * Resource types that can be created or edited via a draft session.
+ *
+ * Each type maps to a Stigmer system agent that guides the user
+ * through the creation/editing flow in a conversational session.
+ */
+export type DraftResourceType = "agent" | "skill" | "mcp-server";
+
+/**
+ * Parsed draft session parameters.
+ *
+ * When `editRef` is present, the session is an edit session (modify an
+ * existing resource). When absent, it's a create session (new resource).
+ */
+export interface DraftParams {
+  /** The kind of resource this draft session will create or edit. */
+  readonly draftType: DraftResourceType;
+  /**
+   * When present, identifies the existing resource to edit.
+   * Absent for create-mode sessions.
+   */
+  readonly editRef?: {
+    /** Organization that owns the resource. */
+    readonly org: string;
+    /** URL-friendly identifier of the resource. */
+    readonly slug: string;
+  };
+}
+
+/**
+ * System agents responsible for creating each resource type.
+ *
+ * Keys match {@link DraftResourceType}; values are {@link ResourceRef}
+ * objects pointing to Stigmer's built-in creator agents.
+ */
+export const CREATOR_AGENTS: Record<DraftResourceType, ResourceRef> = {
+  agent: { org: "stigmer", slug: "agent-creator" },
+  skill: { org: "stigmer", slug: "skill-creator" },
+  "mcp-server": { org: "stigmer", slug: "mcp-server-creator" },
+};
+
+const VALID_TYPES = new Set<string>(Object.keys(CREATOR_AGENTS));
+
+/**
+ * Validate a string as a recognized {@link DraftResourceType}.
+ *
+ * Returns the validated type or `null` if unrecognized.
+ */
+export function parseDraftType(value: string | null): DraftResourceType | null {
+  if (value !== null && VALID_TYPES.has(value)) {
+    return value as DraftResourceType;
+  }
+  return null;
+}
+
+/**
+ * Parse draft session parameters from standard `URLSearchParams`.
+ *
+ * Returns `null` when no valid `draft` param is present. When `editOrg`
+ * and `editSlug` are both present, the returned object includes an
+ * `editRef` indicating this is an edit session rather than a create session.
+ *
+ * Works identically with Next.js `useSearchParams()` or react-router's
+ * `useSearchParams()` — both return standard `URLSearchParams`.
+ */
+export function parseDraftParams(
+  searchParams: URLSearchParams,
+): DraftParams | null {
+  const draftType = parseDraftType(searchParams.get("draft"));
+  if (!draftType) return null;
+
+  const editOrg = searchParams.get("editOrg");
+  const editSlug = searchParams.get("editSlug");
+
+  if (editOrg && editSlug) {
+    return { draftType, editRef: { org: editOrg, slug: editSlug } };
+  }
+
+  return { draftType };
+}

package/src/session/index.ts

@@ -48,6 +48,34 @@ export type {
 export { useAgentRefFromSession } from "./useAgentRefFromSession";
 export type { UseAgentRefFromSessionReturn } from "./useAgentRefFromSession";
 
+export { useNewSessionFlow } from "./useNewSessionFlow";
+export type {
+  UseNewSessionFlowOptions,
+  UseNewSessionFlowReturn,
+} from "./useNewSessionFlow";
+
+export { useSessionPageFlow } from "./useSessionPageFlow";
+export type {
+  UseSessionPageFlowOptions,
+  UseSessionPageFlowReturn,
+} from "./useSessionPageFlow";
+
+export { usePersistedModel } from "./usePersistedModel";
+export type { UsePersistedModelReturn } from "./usePersistedModel";
+
+export { useEditSessionPrep } from "./useEditSessionPrep";
+export type { UseEditSessionPrepReturn } from "./useEditSessionPrep";
+
+export {
+  CREATOR_AGENTS,
+  parseDraftType,
+  parseDraftParams,
+} from "./draft";
+export type {
+  DraftResourceType,
+  DraftParams,
+} from "./draft";
+
 export { groupSessionsByTime } from "./group-sessions";
 export type { SessionGroup } from "./group-sessions";
 

package/src/session/useCreateSession.ts

@@ -22,6 +22,14 @@ export interface SharedSessionFields {
   readonly mcpServerUsages?: McpServerUsageInput[];
   /** Skill references to enable for executions in this session. */
   readonly skillRefs?: ResourceRef[];
+  /**
+   * Runner to bind this session to.
+   *
+   * When set, all executions in the session are routed to this runner's
+   * task queue. When omitted, the backend auto-selects a runner (session
+   * auto-bind in OSS, cloud auto-provisioning in Cloud).
+   */
+  readonly runnerId?: string;
 }
 
 /**
@@ -147,6 +155,7 @@ export function useCreateSession(): UseCreateSessionReturn {
           workspaceEntries: input.workspaceEntries,
           mcpServerUsages: input.mcpServerUsages,
           skillRefs: input.skillRefs,
+          runnerId: input.runnerId,
           agentInstanceId: resolvedInstanceId,
         });
 

package/src/session/useEditSessionPrep.ts

@@ -0,0 +1,111 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { GetArtifactRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useAgent } from "../agent";
+import { useMcpServer } from "../mcp-server";
+import { useSkill } from "../skill";
+import { serializeAgentYaml, serializeMcpServerYaml } from "../library";
+import type { DraftResourceType } from "./draft";
+
+/** Return value of {@link useEditSessionPrep}. */
+export interface UseEditSessionPrepReturn {
+  /** Files ready to be passed as `initialAttachments` to SessionComposer. */
+  readonly files: File[] | undefined;
+  /** Non-null when resource fetch or serialization failed. */
+  readonly error: string | null;
+}
+
+/**
+ * Prepares initial attachment files for an edit-mode draft session.
+ *
+ * Given a resource type and an org/slug reference, this hook fetches the
+ * existing resource and serializes it into a `File` object suitable for
+ * the `initialAttachments` prop of `SessionComposer`:
+ *
+ * - **agent** / **mcp-server**: serialized to YAML
+ * - **skill**: downloaded as a ZIP package
+ *
+ * Pass `null` for `draftType` or `editRef` to skip preparation (used
+ * when the session is in create-mode rather than edit-mode).
+ */
+export function useEditSessionPrep(
+  draftType: DraftResourceType | null,
+  editRef: { readonly org: string; readonly slug: string } | null,
+): UseEditSessionPrepReturn {
+  const stigmer = useStigmer();
+  const editOrg = editRef?.org ?? null;
+  const editSlug = editRef?.slug ?? null;
+
+  const { agent: editAgent } = useAgent(
+    draftType === "agent" ? editOrg : null,
+    draftType === "agent" ? editSlug : null,
+  );
+
+  const { mcpServer: editMcpServer } = useMcpServer(
+    draftType === "mcp-server" ? editOrg : null,
+    draftType === "mcp-server" ? editSlug : null,
+  );
+
+  const { skill: editSkill } = useSkill(
+    draftType === "skill" ? editOrg : null,
+    draftType === "skill" ? editSlug : null,
+  );
+
+  const [files, setFiles] = useState<File[] | undefined>(undefined);
+  const [error, setError] = useState<string | null>(null);
+  const built = useRef(false);
+
+  useEffect(() => {
+    if (built.current) return;
+
+    if (draftType === "agent" && editAgent) {
+      built.current = true;
+      try {
+        const yaml = serializeAgentYaml(editAgent);
+        const slug = editAgent.metadata?.slug ?? "agent";
+        setFiles([new File([yaml], `${slug}.yaml`, { type: "text/yaml" })]);
+      } catch {
+        setError("Failed to serialize agent for editing");
+      }
+    }
+
+    if (draftType === "mcp-server" && editMcpServer) {
+      built.current = true;
+      try {
+        const yaml = serializeMcpServerYaml(editMcpServer);
+        const slug = editMcpServer.metadata?.slug ?? "mcp-server";
+        setFiles([new File([yaml], `${slug}.yaml`, { type: "text/yaml" })]);
+      } catch {
+        setError("Failed to serialize MCP server for editing");
+      }
+    }
+  }, [draftType, editAgent, editMcpServer]);
+
+  useEffect(() => {
+    if (built.current) return;
+    if (draftType !== "skill" || !editSkill) return;
+
+    const storageKey = editSkill.status?.artifactStorageKey;
+    if (!storageKey) return;
+
+    built.current = true;
+    const slug = editSkill.metadata?.slug ?? "skill";
+
+    stigmer.skill
+      .getArtifact(create(GetArtifactRequestSchema, { artifactStorageKey: storageKey }))
+      .then((resp) => {
+        const buf = new ArrayBuffer(resp.artifact.byteLength);
+        new Uint8Array(buf).set(resp.artifact);
+        const blob = new Blob([buf], { type: "application/zip" });
+        setFiles([new File([blob], `${slug}.zip`, { type: "application/zip" })]);
+      })
+      .catch(() => {
+        setError("Failed to download skill package for editing");
+      });
+  }, [draftType, editSkill, stigmer]);
+
+  return { files, error };
+}

package/src/session/useNewSessionFlow.ts

@@ -0,0 +1,283 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { getUserMessage, type McpServerUsageInput, type ResourceRef } from "@stigmer/sdk";
+import type { AgentResolution } from "../agent";
+import { useDefaultAgent } from "../agent";
+import { useModelRegistry } from "../models";
+import { useWorkspaceEntries, type UseWorkspaceEntriesReturn } from "../workspace";
+import { useSessionVariables, type UseSessionVariablesReturn } from "../execution/useSessionVariables";
+import type { SessionComposerSubmitContext } from "../composer";
+import { useCreateSession } from "./useCreateSession";
+import { useCreateAgentExecution } from "../execution/useCreateAgentExecution";
+
+const STORAGE_KEY_MODEL = "stigmer:session:model";
+
+/** Options for {@link useNewSessionFlow}. */
+export interface UseNewSessionFlowOptions {
+  /** Organization slug. Required for session and execution creation. */
+  readonly org: string;
+  /**
+   * Called after a session and its first execution are created successfully.
+   * The consumer is responsible for navigation (e.g. `router.push`).
+   */
+  readonly onSessionCreated: (sessionId: string) => void;
+  /**
+   * Called when an error occurs during session creation.
+   * The consumer can use this for toast notifications or other UI feedback.
+   * If not provided, errors are still available via {@link UseNewSessionFlowReturn.submitError}.
+   */
+  readonly onError?: (message: string) => void;
+}
+
+/** Return value of {@link useNewSessionFlow}. */
+export interface UseNewSessionFlowReturn {
+  /** Currently selected model ID (persisted to localStorage). */
+  readonly modelId: string | undefined;
+  /** Update the selected model. Automatically persists to localStorage. */
+  readonly setModelId: (id: string) => void;
+
+  /** Currently selected agent reference, or `null` for the default agent. */
+  readonly agentRef: ResourceRef | null;
+  /** Update the selected agent reference. */
+  readonly setAgentRef: (ref: ResourceRef | null) => void;
+
+  /** Current agent resolution state (saved instance vs direct reference). */
+  readonly resolution: AgentResolution | null;
+  /** Update the agent resolution. */
+  readonly setResolution: (r: AgentResolution | null) => void;
+
+  /** Active MCP server configurations. */
+  readonly mcpServerUsages: McpServerUsageInput[];
+  /** Update MCP server configurations. */
+  readonly setMcpServerUsages: (usages: McpServerUsageInput[]) => void;
+
+  /** Active skill references. */
+  readonly skillRefs: ResourceRef[];
+  /** Update skill references. */
+  readonly setSkillRefs: (refs: ResourceRef[]) => void;
+
+  /** Selected runner ID, or `null` for auto-selection. */
+  readonly runnerId: string | null;
+  /** Update the selected runner. */
+  readonly setRunnerId: (id: string | null) => void;
+
+  /** Workspace entries manager (git repos and local paths). */
+  readonly workspace: UseWorkspaceEntriesReturn;
+  /** Session variables (per-execution secrets) manager. */
+  readonly sessionVariables: UseSessionVariablesReturn;
+
+  /** `true` while the create session + execution flow is in flight. */
+  readonly isSubmitting: boolean;
+  /** Human-readable error from the last failed submission, or `null`. */
+  readonly submitError: string | null;
+
+  /**
+   * Create a session with the first execution.
+   *
+   * Composes all managed state (agent, workspace, MCP servers, skills,
+   * runner, model, session variables) into the session and execution
+   * creation RPCs, then calls `onSessionCreated` on success.
+   *
+   * The `model` parameter overrides `modelId` for this submission only
+   * (used when SessionComposer passes a per-message model selection).
+   */
+  readonly submit: (
+    message: string,
+    model?: string,
+    context?: SessionComposerSubmitContext,
+  ) => Promise<void>;
+}
+
+/**
+ * Orchestrates the "create a new session" flow.
+ *
+ * Manages all the state required to configure and submit a new session:
+ * model selection (with localStorage persistence), agent resolution,
+ * MCP server/skill/runner selection, workspace entries, and session
+ * variables. On submission, creates the session and its first execution
+ * in sequence, then notifies the consumer via `onSessionCreated`.
+ *
+ * This hook is framework-agnostic — it works identically in Next.js,
+ * Vite, Tauri, or any React environment. Navigation, toast notifications,
+ * and draft-mode logic are the consumer's responsibility.
+ *
+ * @example
+ * ```tsx
+ * const flow = useNewSessionFlow({
+ *   org: "acme",
+ *   onSessionCreated: (id) => navigate(`/sessions/${id}`),
+ *   onError: (msg) => toast.error(msg),
+ * });
+ *
+ * <SessionComposer
+ *   onSubmit={flow.submit}
+ *   isSubmitting={flow.isSubmitting}
+ *   org="acme"
+ *   workspace={flow.workspace}
+ *   agentRef={flow.agentRef}
+ *   onAgentRefChange={flow.setAgentRef}
+ *   onAgentResolutionChange={flow.setResolution}
+ *   mcpServerUsages={flow.mcpServerUsages}
+ *   onMcpServerUsagesChange={flow.setMcpServerUsages}
+ *   skillRefs={flow.skillRefs}
+ *   onSkillRefsChange={flow.setSkillRefs}
+ *   runnerId={flow.runnerId}
+ *   onRunnerIdChange={flow.setRunnerId}
+ *   sessionVariables={flow.sessionVariables}
+ *   defaultModelId={flow.modelId}
+ *   onModelChange={flow.setModelId}
+ * />
+ * ```
+ */
+export function useNewSessionFlow(
+  options: UseNewSessionFlowOptions,
+): UseNewSessionFlowReturn {
+  const { org, onSessionCreated, onError } = options;
+
+  const { getModel } = useModelRegistry();
+  const { create: createSession } = useCreateSession();
+  const { create: createExecution } = useCreateAgentExecution();
+  const { agent: defaultAgent } = useDefaultAgent(org);
+  const workspace = useWorkspaceEntries();
+  const sessionVariables = useSessionVariables();
+
+  const [modelId, setModelId] = useState<string | undefined>(undefined);
+  const [agentRef, setAgentRef] = useState<ResourceRef | null>(null);
+  const [resolution, setResolution] = useState<AgentResolution | null>(null);
+  const [mcpServerUsages, setMcpServerUsages] = useState<McpServerUsageInput[]>([]);
+  const [skillRefs, setSkillRefs] = useState<ResourceRef[]>([]);
+  const [runnerId, setRunnerId] = useState<string | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [submitError, setSubmitError] = useState<string | null>(null);
+
+  const validModelId = modelId && getModel(modelId) ? modelId : undefined;
+
+  // Restore persisted model on mount
+  useEffect(() => {
+    const stored = localStorage.getItem(STORAGE_KEY_MODEL);
+    if (stored && getModel(stored)) {
+      setModelId(stored);
+    }
+  }, [getModel]);
+
+  // Persist model on change
+  useEffect(() => {
+    if (modelId) {
+      localStorage.setItem(STORAGE_KEY_MODEL, modelId);
+    }
+  }, [modelId]);
+
+  const submit = useCallback(
+    async (
+      message: string,
+      selectedModel?: string,
+      context?: SessionComposerSubmitContext,
+    ) => {
+      if (isSubmitting) return;
+      if (!org) {
+        const msg = "Select an organization before starting a session.";
+        setSubmitError(msg);
+        onError?.(msg);
+        return;
+      }
+
+      setIsSubmitting(true);
+      setSubmitError(null);
+
+      try {
+        const sessionFields = {
+          org,
+          workspaceEntries: workspace.hasEntries
+            ? workspace.toInput()
+            : undefined,
+          mcpServerUsages: mcpServerUsages.length > 0 ? mcpServerUsages : undefined,
+          skillRefs: skillRefs.length > 0 ? skillRefs : undefined,
+          runnerId: runnerId ?? undefined,
+        };
+
+        const executionFields = {
+          org,
+          message,
+          modelName: selectedModel ?? validModelId,
+          runtimeEnv: context?.runtimeEnv,
+          attachments: context?.attachments,
+        };
+
+        let sessionId: string;
+
+        if (agentRef && resolution) {
+          if (resolution.mode === "saved") {
+            ({ sessionId } = await createSession({
+              ...sessionFields,
+              agentInstanceId: resolution.instanceId,
+            }));
+          } else {
+            ({ sessionId } = await createSession({
+              ...sessionFields,
+              agentRef,
+            }));
+          }
+        } else {
+          const defaultInstanceId = defaultAgent?.status?.defaultInstanceId;
+          if (!defaultInstanceId) {
+            throw new Error(
+              "No default agent available. Select an agent to start a session.",
+            );
+          }
+          ({ sessionId } = await createSession({
+            ...sessionFields,
+            agentInstanceId: defaultInstanceId,
+          }));
+        }
+
+        await createExecution({ ...executionFields, sessionId });
+        sessionVariables.clear();
+        onSessionCreated(sessionId);
+      } catch (err) {
+        const detail = getUserMessage(err, "Failed to start session");
+        setSubmitError(detail);
+        onError?.(detail);
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [
+      isSubmitting,
+      org,
+      validModelId,
+      workspace,
+      mcpServerUsages,
+      skillRefs,
+      runnerId,
+      agentRef,
+      resolution,
+      defaultAgent,
+      createSession,
+      createExecution,
+      sessionVariables,
+      onSessionCreated,
+      onError,
+    ],
+  );
+
+  return {
+    modelId: validModelId,
+    setModelId,
+    agentRef,
+    setAgentRef,
+    resolution,
+    setResolution,
+    mcpServerUsages,
+    setMcpServerUsages,
+    skillRefs,
+    setSkillRefs,
+    runnerId,
+    setRunnerId,
+    workspace,
+    sessionVariables,
+    isSubmitting,
+    submitError,
+    submit,
+  };
+}

package/src/session/usePersistedModel.ts

@@ -0,0 +1,41 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useModelRegistry } from "../models";
+
+const STORAGE_KEY_MODEL = "stigmer:session:model";
+
+/** Return value of {@link usePersistedModel}. */
+export type UsePersistedModelReturn = readonly [
+  modelId: string | undefined,
+  setModelId: (id: string) => void,
+];
+
+/**
+ * Model selection with localStorage persistence.
+ *
+ * Restores the last selected model on mount and validates it against the
+ * model registry. Invalid or removed models are silently ignored (returns
+ * `undefined`). On change, persists the new selection to localStorage so
+ * it survives page reloads and navigation.
+ *
+ * Used by both the session launcher (new session) and session page
+ * (follow-up messages) to maintain a consistent model preference.
+ */
+export function usePersistedModel(): UsePersistedModelReturn {
+  const { getModel } = useModelRegistry();
+
+  const [modelId, setModelId] = useState<string | undefined>(() => {
+    if (typeof window === "undefined") return undefined;
+    return localStorage.getItem(STORAGE_KEY_MODEL) ?? undefined;
+  });
+
+  useEffect(() => {
+    if (modelId) {
+      localStorage.setItem(STORAGE_KEY_MODEL, modelId);
+    }
+  }, [modelId]);
+
+  const validModelId = modelId && getModel(modelId) ? modelId : undefined;
+  return [validModelId, setModelId] as const;
+}