@kortyx/agent 0.2.0

package/src/chat/create-agent.ts

@@ -0,0 +1,97 @@
+import type { KortyxConfig, WorkflowRegistry } from "@kortyx/runtime";
+import { createFileWorkflowRegistry, loadKortyxConfig } from "@kortyx/runtime";
+import { resolve } from "path";
+import type { SelectWorkflowFn } from "../orchestrator";
+import type { ChatMessage } from "../types/chat-message";
+import type { ProcessChatArgs } from "./process-chat";
+import { processChat } from "./process-chat";
+
+export interface CreateAgentArgs<
+  Config extends Record<string, unknown>,
+  Options,
+> extends Omit<
+    ProcessChatArgs<Config, Options>,
+    "messages" | "options" | "selectWorkflow" | "workflowRegistry"
+  > {
+  workflowsDir?: string;
+  workflowRegistry?: WorkflowRegistry;
+  selectWorkflow?: SelectWorkflowFn;
+  fallbackWorkflowId?: string;
+  config?: KortyxConfig;
+  configPath?: string;
+}
+
+export function createAgent<
+  Config extends Record<string, unknown>,
+  Options = unknown,
+>(args: CreateAgentArgs<Config, Options>) {
+  const {
+    workflowsDir,
+    workflowRegistry,
+    selectWorkflow,
+    fallbackWorkflowId,
+    config,
+    configPath,
+    ...baseArgs
+  } = args;
+
+  const resolvedCwd = process.cwd();
+  const registryPromise: Promise<WorkflowRegistry | undefined> = (async () => {
+    if (workflowRegistry) return workflowRegistry;
+    if (workflowsDir) {
+      return createFileWorkflowRegistry({
+        workflowsDir,
+        fallbackId: fallbackWorkflowId ?? "general-chat",
+      });
+    }
+
+    const loadConfigArgs = {
+      cwd: resolvedCwd,
+      ...(configPath ? { configPath } : {}),
+    } as const;
+    const loadedConfig = config ?? (await loadKortyxConfig(loadConfigArgs));
+    const resolvedWorkflowsDir =
+      loadedConfig?.workflowsDir ?? resolve(resolvedCwd, "src", "workflows");
+    const registryOptions = {
+      workflowsDir: resolvedWorkflowsDir,
+      fallbackId:
+        loadedConfig?.fallbackWorkflowId ??
+        fallbackWorkflowId ??
+        "general-chat",
+      ...(loadedConfig?.registry?.cache !== undefined
+        ? { cache: loadedConfig.registry.cache }
+        : {}),
+      ...(loadedConfig?.registry?.extensions
+        ? { extensions: loadedConfig.registry.extensions }
+        : {}),
+    } as const;
+    return createFileWorkflowRegistry(registryOptions);
+  })();
+
+  return {
+    processChat: async (messages: ChatMessage[], options?: Options) => {
+      if (selectWorkflow) {
+        return processChat({
+          ...(baseArgs as ProcessChatArgs<Config, Options>),
+          messages,
+          options,
+          selectWorkflow,
+        });
+      }
+
+      const registry = await registryPromise;
+      if (!registry) {
+        throw new Error(
+          "createAgent requires workflowsDir, workflowRegistry, or selectWorkflow.",
+        );
+      }
+
+      return processChat({
+        ...(baseArgs as ProcessChatArgs<Config, Options>),
+        messages,
+        options,
+        workflowRegistry: registry,
+      });
+    },
+  };
+}

package/src/chat/process-chat.ts

@@ -0,0 +1,132 @@
+import type { GraphState, MemoryEnvelope } from "@kortyx/core";
+import type { MemoryAdapter } from "@kortyx/memory";
+import type { GetProviderFn } from "@kortyx/providers";
+import type { WorkflowRegistry } from "@kortyx/runtime";
+import { buildInitialGraphState, createLangGraph } from "@kortyx/runtime";
+import { createStreamResponse, type StreamChunk } from "@kortyx/stream";
+import type { ApplyResumeSelection } from "../interrupt/resume-handler";
+import { tryPrepareResumeStream } from "../interrupt/resume-handler";
+import type { SaveMemoryFn, SelectWorkflowFn } from "../orchestrator";
+import { orchestrateGraphStream } from "../orchestrator";
+import type { ChatMessage } from "../types/chat-message";
+import { extractLatestUserMessage } from "../utils/extract-latest-message";
+
+type InitializeProvidersFn<Config> = (
+  aiConfig: Config extends { ai: infer A } ? A : unknown,
+) => void;
+
+export interface ProcessChatArgs<
+  Config extends Record<string, unknown>,
+  Options,
+> {
+  messages: ChatMessage[];
+  options?: Options | undefined;
+  sessionId?: string;
+  defaultWorkflowId?: string;
+  loadRuntimeConfig: (options?: Options) => Config | Promise<Config>;
+  selectWorkflow?: SelectWorkflowFn;
+  workflowRegistry?: WorkflowRegistry;
+  getProvider: GetProviderFn;
+  initializeProviders?: InitializeProvidersFn<Config>;
+  memoryAdapter: MemoryAdapter;
+  applyResumeSelection?: ApplyResumeSelection;
+}
+
+export async function processChat<
+  Config extends Record<string, unknown>,
+  Options = unknown,
+>({
+  messages,
+  options,
+  sessionId,
+  defaultWorkflowId,
+  loadRuntimeConfig,
+  selectWorkflow,
+  workflowRegistry,
+  getProvider,
+  initializeProviders,
+  memoryAdapter,
+  applyResumeSelection,
+}: ProcessChatArgs<Config, Options>): Promise<Response> {
+  // Load runtime configuration (API keys, environment, etc.)
+  const config = await loadRuntimeConfig(options);
+  if (initializeProviders) {
+    initializeProviders((config as any)?.ai);
+  }
+  const runtimeConfig = {
+    ...config,
+    getProvider,
+    ...(memoryAdapter ? { memoryAdapter } : {}),
+  } as Record<string, unknown>;
+
+  const workflowSelector: SelectWorkflowFn | null =
+    selectWorkflow ??
+    (workflowRegistry ? (id) => workflowRegistry.select(id) : null);
+  if (!workflowSelector) {
+    throw new Error(
+      "processChat requires selectWorkflow or workflowRegistry to resolve workflows.",
+    );
+  }
+
+  // Extract session + input
+  const fallbackSessionId = (options as { sessionId?: string } | undefined)
+    ?.sessionId;
+  const resolvedSessionId =
+    sessionId || fallbackSessionId || "anonymous-session";
+  const last = messages[messages.length - 1];
+  const input = extractLatestUserMessage(messages);
+
+  // Load conversation memory (Redis memory)
+  const previousMessages = messages.slice(0, -1);
+  const storedState = await memoryAdapter.load(resolvedSessionId);
+  const memory: MemoryEnvelope = {
+    ...(storedState?.memory ?? {}),
+    ...(previousMessages.length > 0 && {
+      conversationMessages: previousMessages,
+    }),
+  };
+
+  // Base state (LLM input, messages, memory)
+  const baseState = await buildInitialGraphState({
+    input,
+    config: runtimeConfig,
+    memory,
+    ...(defaultWorkflowId ? { defaultWorkflowId } : {}),
+  });
+
+  const saveMemory: SaveMemoryFn = async (
+    activeSessionId: string,
+    state: GraphState,
+  ) => {
+    await memoryAdapter.save(activeSessionId, state);
+  };
+
+  // If this is a resume request, continue from pending snapshot and skip workflow determination
+  const resumeStream = await tryPrepareResumeStream({
+    lastMessage: last,
+    sessionId: resolvedSessionId,
+    config: runtimeConfig,
+    saveMemory,
+    selectWorkflow: workflowSelector,
+    ...(defaultWorkflowId ? { defaultWorkflowId } : {}),
+    ...(applyResumeSelection ? { applyResumeSelection } : {}),
+  });
+  if (resumeStream) return createStreamResponse(resumeStream);
+
+  // Determine which workflow to run (defaults to frontdesk)
+  const currentWorkflow = baseState.currentWorkflow;
+  const selectedWorkflow = await workflowSelector(currentWorkflow as string);
+
+  const graph = await createLangGraph(selectedWorkflow, runtimeConfig as any);
+
+  const orchestratedStream = await orchestrateGraphStream({
+    sessionId: resolvedSessionId,
+    graph,
+    state: { ...baseState, currentWorkflow },
+    config: runtimeConfig,
+    saveMemory,
+    selectWorkflow: workflowSelector,
+  });
+
+  return createStreamResponse(orchestratedStream as AsyncIterable<StreamChunk>);
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export type { CreateAgentArgs } from "./chat/create-agent";
+export { createAgent } from "./chat/create-agent";
+export type { ProcessChatArgs } from "./chat/process-chat";
+export { processChat } from "./chat/process-chat";
+export type {
+  ApplyResumeSelection,
+  ResumeMeta,
+} from "./interrupt/resume-handler";
+export {
+  parseResumeMeta,
+  tryPrepareResumeStream,
+} from "./interrupt/resume-handler";
+export type {
+  CompiledGraphLike,
+  OrchestrateArgs,
+  SaveMemoryFn,
+  SelectWorkflowFn,
+} from "./orchestrator";
+export { orchestrateGraphStream } from "./orchestrator";
+export { transformGraphStreamForUI } from "./stream/transform-graph-stream-for-ui";
+export type { ChatMessage } from "./types/chat-message";
+export { extractLatestUserMessage } from "./utils/extract-latest-message";

package/src/interrupt/resume-handler.ts

@@ -0,0 +1,146 @@
+import type { GraphState } from "@kortyx/core";
+import {
+  deletePendingRequest,
+  getPendingRequest,
+  type PendingRequestRecord,
+} from "@kortyx/memory";
+import { createLangGraph } from "@kortyx/runtime";
+import type { StreamChunk } from "@kortyx/stream";
+import type { SaveMemoryFn, SelectWorkflowFn } from "../orchestrator";
+import { orchestrateGraphStream } from "../orchestrator";
+import type { ChatMessage } from "../types/chat-message";
+
+export interface ResumeMeta {
+  token: string;
+  requestId: string;
+  selected: string[]; // normalized to array for consistency
+  cancel?: boolean;
+}
+
+export type ApplyResumeSelection = (args: {
+  pending: PendingRequestRecord;
+  selected: string[];
+}) => Record<string, unknown> | null | undefined;
+
+export function parseResumeMeta(
+  msg: ChatMessage | undefined,
+): ResumeMeta | null {
+  if (!msg || !msg.metadata) return null;
+  const raw = (msg.metadata as any)?.resume;
+  if (!raw) return null;
+  const token = typeof raw.token === "string" ? raw.token : "";
+  const requestId = typeof raw.requestId === "string" ? raw.requestId : "";
+  const cancel = Boolean(raw.cancel);
+
+  // Accept multiple shapes; normalize to selected: string[]
+  let selected: string[] = [];
+  if (typeof raw.selected === "string") selected = [raw.selected];
+  else if (Array.isArray(raw.selected))
+    selected = raw.selected.map((x: any) => String(x));
+  else if (raw?.choice?.id) selected = [String(raw.choice.id)];
+  else if (Array.isArray(raw?.choices))
+    selected = raw.choices.map((c: any) => String(c.id));
+
+  if (!token || !requestId) return null;
+  return { token, requestId, selected, cancel };
+}
+
+interface TryResumeArgs {
+  lastMessage: ChatMessage | undefined;
+  sessionId: string;
+  config: Record<string, unknown>;
+  saveMemory?: SaveMemoryFn;
+  selectWorkflow: SelectWorkflowFn;
+  defaultWorkflowId?: string;
+  applyResumeSelection?: ApplyResumeSelection;
+}
+
+export async function tryPrepareResumeStream({
+  lastMessage,
+  sessionId,
+  config,
+  saveMemory,
+  selectWorkflow,
+  defaultWorkflowId,
+  applyResumeSelection,
+}: TryResumeArgs): Promise<AsyncIterable<StreamChunk> | null> {
+  const meta = parseResumeMeta(lastMessage);
+  if (!meta) return null;
+
+  const pending = getPendingRequest(meta.token);
+  if (!pending || pending.requestId !== meta.requestId) {
+    // Invalid/expired; ignore and continue normal flow
+    // eslint-disable-next-line no-console
+    console.log(
+      `[resume] pending not found or mismatched. token=${meta.token} requestId=${meta.requestId}`,
+    );
+    return null;
+  }
+
+  if (meta.cancel) {
+    deletePendingRequest(pending.token);
+    return null;
+  }
+
+  // Build a minimal state; the checkpointer (keyed by sessionId) will restore paused context
+  // eslint-disable-next-line no-console
+  console.log(
+    `[resume] token=${meta.token} requestId=${meta.requestId} selected=${JSON.stringify(
+      meta.selected,
+    )} sessionId=${sessionId}`,
+  );
+
+  const resumeData = applyResumeSelection
+    ? applyResumeSelection({ pending, selected: meta.selected })
+    : meta.selected?.length
+      ? { coordinates: String(meta.selected[0]) }
+      : {};
+
+  const resumeDataPatch =
+    resumeData && typeof resumeData === "object" ? resumeData : {};
+
+  const resumedState: GraphState = {
+    // For static breakpoints, resume with null input (set in orchestrator),
+    // and stash the user selection into data so the next node can read it.
+    input: "" as any,
+    lastNode: "__start__" as any,
+    currentWorkflow:
+      (pending.workflow as any) ||
+      (defaultWorkflowId as any) ||
+      ("job-search" as any),
+    config: config as any,
+    conversationHistory: [],
+    awaitingHumanInput: false,
+    data: {
+      ...(pending.state?.data ?? {}),
+      ...resumeDataPatch,
+    } as any,
+  } as any;
+
+  const wf = await selectWorkflow(resumedState.currentWorkflow as string);
+  const resumeValue = meta.selected?.length
+    ? String(meta.selected[0])
+    : undefined;
+  const resumedGraph = await createLangGraph(wf, {
+    ...(config as any),
+    resume: true,
+    ...(resumeValue !== undefined ? { resumeValue } : {}),
+  });
+  deletePendingRequest(pending.token);
+
+  const args: any = {
+    sessionId,
+    graph: resumedGraph,
+    state: resumedState,
+    config: {
+      ...(config as any),
+      resume: true,
+      ...(resumeValue !== undefined ? { resumeValue } : {}),
+    },
+    selectWorkflow,
+  };
+  if (saveMemory) args.saveMemory = saveMemory;
+
+  const stream = await orchestrateGraphStream(args);
+  return stream as AsyncIterable<StreamChunk>;
+}