@skein-js/agent-protocol 0.5.0 → 0.7.0

package/README.md

@@ -101,7 +101,7 @@ Graph **state, history, and interrupt/resume are 100% LangGraph-native** via the
 ## API
 
 - **Entry points:** `createProtocolRuntime(deps, options?)` → `{ service, handlers, worker }`;
-  `createProtocolService` / `buildProtocolService`; `createProtocolHandlers`; `createContext`;
+  `createProtocolService` / `createProtocolServiceFromContext`; `createProtocolHandlers`; `createContext`;
   `createRunWorker(ctx, options?)` (`RunWorkerOptions`: `maxConcurrency`, `shutdownGraceMs`).
 - **Service surface** (`runtime.service`): `assistants` (`registerGraphAssistants`, `get`, `list`,
   `search`, `schemas`), `threads` (`create`/`get`/`list`/`patch`/`delete`/`history`/`getState`),

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { GraphSchema, SkeinStore, RunQueue, RunEventBus, AuthEngine, Assistant, AuthUser, Config, StreamMode, Metadata, MultitaskStrategy, RunFrame, DefaultValues, Run, RunStatus, StorePutOptions, Item, StoreSearchQuery, SearchItem, Thread, ThreadSearchQuery, ThreadState, StoreRepo } from '@skein-js/core';
+import { GraphSchema, SkeinStore, RunQueue, RunEventBus, AuthEngine, AuthUser, Metadata, Thread, ThreadSearchQuery, ThreadState, Assistant, AssistantSearchQuery, AssistantCreate, AssistantUpdate, AssistantVersionsQuery, AssistantVersion, AssistantGraph, Config, StreamMode, MultitaskStrategy, RunFrame, DefaultValues, Run, RunStatus, StorePutOptions, Item, StoreSearchQuery, SearchItem, StoreRepo } from '@skein-js/core';
 import { CompiledGraph, BaseCheckpointSaver, BaseStore, Item as Item$1, Operation, OperationResults } from '@langchain/langgraph';
 
 /** A factory export: called (optionally with per-run config) to produce a compiled graph. */
@@ -23,6 +23,18 @@ interface GraphResolver {
 }
 /** A source of the current time; injected so tests are deterministic. */
 type Clock = () => Date;
+/**
+ * Delivers a run-completion webhook: POST `payload` (as JSON) to `url`. Injected so the transport is
+ * swappable and tests can capture deliveries without a network. Should resolve once sent and reject
+ * on failure — the engine calls it best-effort (a rejection is logged, never fails the run).
+ *
+ * Security: `url` is client-supplied, so the dispatcher makes a *server-side* request to a target the
+ * caller chose (an SSRF surface) and sends it the run's final `values`. The default dispatcher
+ * restricts the scheme to `http(s)` but, since skein is self-hosted and internal webhook targets are a
+ * legitimate use, does **not** block private/loopback hosts. Deployments that accept untrusted
+ * `webhook` URLs should inject a dispatcher that validates the resolved host against an allowlist.
+ */
+type WebhookDispatcher = (url: string, payload: unknown) => Promise<void>;
 /** A minimal structured logger. Defaults to a no-op so nothing is required. */
 interface Logger {
     debug(message: string, meta?: unknown): void;
@@ -58,6 +70,11 @@ interface ProtocolDeps {
     logRunActivity?: boolean;
     /** Optional per-run wall-clock timeout in ms. When set, a run exceeding it becomes `"timeout"`. */
     runTimeoutMs?: number;
+    /**
+     * Delivers run-completion webhooks (the run's `webhook` field). Defaults to a `globalThis.fetch`
+     * POST with a JSON body; inject to customize transport/retries or to capture deliveries in tests.
+     */
+    webhookDispatcher?: WebhookDispatcher;
     /**
      * Optional auth engine. When set, every request is authenticated (401 on failure) and authorized
      * per resource + action (403 on deny), with ownership filters scoping reads and stamping writes.
@@ -65,28 +82,23 @@ interface ProtocolDeps {
      */
     auth?: AuthEngine;
 }
-/** Fill in the optional deps (`clock`, `logger`) so the rest of the code can rely on them. */
+/** Fill in the optional deps (`clock`, `logger`, `webhookDispatcher`) so the rest can rely on them. */
 interface ResolvedDeps extends ProtocolDeps {
     clock: Clock;
     logger: Logger;
+    webhookDispatcher: WebhookDispatcher;
 }
 
-interface AssistantSearch {
-    graph_id?: string;
-    limit?: number;
-    offset?: number;
-}
-interface AssistantService {
-    /** Register one assistant per declared graph (idempotent — safe to call on every boot). */
-    registerGraphAssistants(): Promise<Assistant[]>;
-    get(assistantId: string): Promise<Assistant>;
-    list(): Promise<Assistant[]>;
-    search(query: AssistantSearch): Promise<Assistant[]>;
-    schemas(assistantId: string): Promise<GraphSchemas>;
-}
-
-/** Why a run was aborted. Absent (`null`) means the run failed on its own. */
-type AbortReason = "cancel" | "timeout";
+/**
+ * Why a run was aborted. Absent (`null`) means the run failed on its own.
+ * - `cancel` — explicit `POST /runs/{id}/cancel`; the run settles `cancelled`.
+ * - `timeout` — the run exceeded `runTimeoutMs`; it settles `timeout`.
+ * - `interrupt` — displaced by a `multitask_strategy: "interrupt"` run; it settles `interrupted`,
+ *   keeping its checkpoint writes.
+ * - `rollback` — displaced by a `multitask_strategy: "rollback"` run; it settles terminally and the
+ *   displacing run then discards its checkpoint writes (see the run service).
+ */
+type AbortReason = "cancel" | "timeout" | "interrupt" | "rollback";
 /** Handle handed to the engine for a run: the signal to thread into the graph, and the reason box. */
 interface RunControl {
     signal: AbortSignal;
@@ -115,10 +127,42 @@ declare class ThreadLocks {
     run<T>(key: string, task: () => Promise<T>): Promise<T>;
 }
 
+/**
+ * What a `multitask_strategy: "rollback"` run must do to the thread *before* it executes: drop the
+ * displaced run(s)' checkpoint writes and delete their run rows. Registered at create time and
+ * applied once the displaced run has settled (see `startRunExecution`). In-process, like
+ * {@link RunControlRegistry} — a single-process seam.
+ *
+ * `revertToCheckpoint` is `false` when no displaced run wrote checkpoints (all were still pending),
+ * so only the rows are deleted; otherwise it carries the base tip to revert to (`baseCheckpointId
+ * === undefined` means the displaced run started on a fresh thread, so the revert is a clean wipe).
+ */
+interface RollbackPlan {
+    revertToCheckpoint: {
+        baseCheckpointId: string | undefined;
+    } | false;
+    displacedRunIds: string[];
+}
 interface ProtocolContext {
     deps: ResolvedDeps;
     control: RunControlRegistry;
+    /** Per-thread lock closing the create-guard's check-then-insert race. */
     locks: ThreadLocks;
+    /**
+     * Per-thread lock serializing run *execution* (distinct from {@link locks}, which only guards
+     * creation). Every run executes inside it, so a second run on a busy thread waits its turn — this
+     * is what makes `multitask_strategy: "enqueue"` run behind the active run, and what makes an
+     * `interrupt`/`rollback` run start only after the displaced run has fully settled.
+     */
+    executionLocks: ThreadLocks;
+    /**
+     * runId → the thread's checkpoint tip when that run started executing (`undefined` if the thread
+     * had no checkpoints yet). Captured by the engine at `pending -> running`, cleared when the run
+     * settles; read to compute a {@link RollbackPlan}. In-process, per {@link control}'s convention.
+     */
+    runBaseCheckpoints: Map<string, string | undefined>;
+    /** New runId → the {@link RollbackPlan} its execution must apply before running. In-process. */
+    rollbackPlans: Map<string, RollbackPlan>;
     /**
      * The authenticated caller for the current request, populated by the authorizing handler wrapper
      * so the run service can stamp it onto a run's kwargs. Undefined when no auth engine is
@@ -130,6 +174,79 @@ interface ProtocolContext {
 }
 declare function createContext(deps: ProtocolDeps): ProtocolContext;
 
+interface CreateThreadInput {
+    thread_id?: string;
+    metadata?: Metadata;
+}
+interface PatchThreadInput {
+    metadata?: Metadata;
+}
+interface HistoryOptions {
+    limit?: number;
+}
+interface ThreadService {
+    create(input?: CreateThreadInput): Promise<Thread>;
+    get(threadId: string): Promise<Thread>;
+    list(): Promise<Thread[]>;
+    /** Filtered + paginated listing — `POST /threads/search`. */
+    search(query: ThreadSearchQuery): Promise<Thread[]>;
+    patch(threadId: string, patch: PatchThreadInput): Promise<Thread>;
+    /** Duplicate a thread (new id) together with its full checkpoint history — `POST /threads/{id}/copy`. */
+    copy(threadId: string): Promise<Thread>;
+    delete(threadId: string): Promise<void>;
+    history(threadId: string, options?: HistoryOptions): Promise<ThreadState[]>;
+    /** The thread's current state snapshot — `GET /threads/{id}/state`, what `useStream` hydrates from. */
+    getState(threadId: string): Promise<ThreadState>;
+}
+
+/** `POST /assistants` — create input plus LangGraph's `if_exists` conflict policy. */
+interface CreateAssistantInput extends AssistantCreate {
+    /** When the `assistant_id` already exists: `"raise"` (default, 409) or `"do_nothing"` (return it). */
+    ifExists?: "raise" | "do_nothing";
+}
+/** `DELETE /assistants/{id}` options. */
+interface DeleteAssistantOptions {
+    /** Also delete threads whose `metadata.assistant_id` is this assistant (aborting their runs). */
+    deleteThreads?: boolean;
+}
+/** `GET /assistants/{id}/graph` options. */
+interface DrawGraphOptions {
+    /** Include subgraphs in the drawn graph; an integer bounds the depth (mirrors LangGraph). */
+    xray?: number | boolean;
+}
+/** `GET /assistants/{id}/subgraphs[/{namespace}]` options. */
+interface SubgraphsOptions {
+    /** Restrict to this subgraph namespace. */
+    namespace?: string;
+    /** Recurse into nested subgraphs. */
+    recurse?: boolean;
+}
+interface AssistantService {
+    /** Register one assistant per declared graph (idempotent — safe to call on every boot). */
+    registerGraphAssistants(): Promise<Assistant[]>;
+    get(assistantId: string): Promise<Assistant>;
+    list(): Promise<Assistant[]>;
+    /** Filtered + paginated listing — `POST /assistants/search`. */
+    search(query: AssistantSearchQuery): Promise<Assistant[]>;
+    /** Count matching assistants (ignores limit/offset) — `POST /assistants/count`. */
+    count(query: AssistantSearchQuery): Promise<number>;
+    schemas(assistantId: string): Promise<GraphSchemas>;
+    /** Create an assistant, honoring `if_exists` — `POST /assistants`. */
+    create(input: CreateAssistantInput): Promise<Assistant>;
+    /** Patch an assistant, minting a new version — `PATCH /assistants/{id}`. */
+    update(assistantId: string, patch: AssistantUpdate): Promise<Assistant>;
+    /** Delete an assistant (and, optionally, its threads) — `DELETE /assistants/{id}`. */
+    delete(assistantId: string, options?: DeleteAssistantOptions): Promise<void>;
+    /** Version history, newest-first — `POST /assistants/{id}/versions`. */
+    listVersions(assistantId: string, query?: AssistantVersionsQuery): Promise<AssistantVersion[]>;
+    /** Roll back to an existing version — `POST /assistants/{id}/latest`. */
+    setLatest(assistantId: string, version: number): Promise<Assistant>;
+    /** The drawable graph JSON — `GET /assistants/{id}/graph`. */
+    drawGraph(assistantId: string, options?: DrawGraphOptions): Promise<AssistantGraph>;
+    /** Each subgraph's schema, keyed by namespace — `GET /assistants/{id}/subgraphs`. */
+    subgraphs(assistantId: string, options?: SubgraphsOptions): Promise<GraphSchemas>;
+}
+
 /** A run request as it arrives from any of the run endpoints (already validated). */
 interface CreateRunInput {
     thread_id?: string;
@@ -147,6 +264,8 @@ interface CreateRunInput {
     multitask_strategy?: MultitaskStrategy;
     interrupt_before?: string[] | "*";
     interrupt_after?: string[] | "*";
+    /** Absolute `http(s)` URL POSTed with the settled run once it reaches a terminal status. */
+    webhook?: string;
 }
 /** A started streaming run: its id, plus the live frame iterable to serialize as SSE. */
 interface StartedStream {
@@ -174,31 +293,6 @@ interface StoreService {
     listNamespaces(prefix?: string[]): Promise<string[][]>;
 }
 
-interface CreateThreadInput {
-    thread_id?: string;
-    metadata?: Metadata;
-}
-interface PatchThreadInput {
-    metadata?: Metadata;
-}
-interface HistoryOptions {
-    limit?: number;
-}
-interface ThreadService {
-    create(input?: CreateThreadInput): Promise<Thread>;
-    get(threadId: string): Promise<Thread>;
-    list(): Promise<Thread[]>;
-    /** Filtered + paginated listing — `POST /threads/search`. */
-    search(query: ThreadSearchQuery): Promise<Thread[]>;
-    patch(threadId: string, patch: PatchThreadInput): Promise<Thread>;
-    /** Duplicate a thread (new id) together with its full checkpoint history — `POST /threads/{id}/copy`. */
-    copy(threadId: string): Promise<Thread>;
-    delete(threadId: string): Promise<void>;
-    history(threadId: string, options?: HistoryOptions): Promise<ThreadState[]>;
-    /** The thread's current state snapshot — `GET /threads/{id}/state`, what `useStream` hydrates from. */
-    getState(threadId: string): Promise<ThreadState>;
-}
-
 /** Body for `POST /threads/{id}/stream` — a run request without the thread id (it's in the path). */
 interface ThreadStreamInput {
     assistant_id: string;
@@ -237,10 +331,16 @@ interface ProtocolService {
     store: StoreService;
 }
 /** Assemble the service over an existing context (used by the runtime to share the context). */
-declare function buildProtocolService(ctx: ProtocolContext): ProtocolService;
+declare function createProtocolServiceFromContext(ctx: ProtocolContext): ProtocolService;
 /** Build the service with its own context. Use {@link createProtocolRuntime} when you also run a
  * background worker in the same process, so cancellation is shared. */
 declare function createProtocolService(deps: ProtocolDeps): ProtocolService;
+/**
+ * @deprecated Renamed to {@link createProtocolServiceFromContext} — it builds the service over an
+ * existing `ProtocolContext` (vs {@link createProtocolService}, which takes `deps` and makes its own).
+ * Kept for back-compat; slated for removal in a future major.
+ */
+declare const buildProtocolService: typeof createProtocolServiceFromContext;
 
 /** A normalized request an adapter maps its framework request onto. */
 interface ProtocolRequest {
@@ -270,7 +370,15 @@ type ProtocolHandler = (req: ProtocolRequest) => Promise<ProtocolResponse>;
 interface ProtocolHandlers {
     getAssistant: ProtocolHandler;
     searchAssistants: ProtocolHandler;
+    countAssistants: ProtocolHandler;
     getAssistantSchemas: ProtocolHandler;
+    createAssistant: ProtocolHandler;
+    updateAssistant: ProtocolHandler;
+    deleteAssistant: ProtocolHandler;
+    listAssistantVersions: ProtocolHandler;
+    setAssistantLatestVersion: ProtocolHandler;
+    getAssistantGraph: ProtocolHandler;
+    getAssistantSubgraphs: ProtocolHandler;
     createThread: ProtocolHandler;
     getThread: ProtocolHandler;
     listThreads: ProtocolHandler;
@@ -312,12 +420,18 @@ interface RunWorker {
 }
 declare function createRunWorker(ctx: ProtocolContext, options?: RunWorkerOptions): RunWorker;
 
+/** Options for {@link createProtocolRuntime}. */
 interface ProtocolRuntimeOptions {
+    /** Tuning for the background run worker (concurrency, poll interval). */
     worker?: RunWorkerOptions;
 }
+/** The wired engine: the service, the transport-neutral handler table, and the background worker. */
 interface ProtocolRuntime {
+    /** High-level operations over assistants / threads / runs / store (used to seed assistants). */
     service: ProtocolService;
+    /** The transport-neutral HTTP handler table an adapter dispatches requests into. */
     handlers: ProtocolHandlers;
+    /** The background worker that drains the run queue; `start()` it after seeding assistants. */
     worker: RunWorker;
 }
 /**
@@ -327,6 +441,47 @@ interface ProtocolRuntime {
  */
 declare function createProtocolRuntime(deps: ProtocolDeps, options?: ProtocolRuntimeOptions): ProtocolRuntime;
 
+type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+interface RouteBinding {
+    method: HttpMethod;
+    /** Path with `:param` placeholders, e.g. `/threads/:thread_id/runs/stream`. */
+    path: string;
+    handler: keyof ProtocolHandlers;
+    /**
+     * Fold the path `thread_id` into the request body before dispatch. The SDK addresses a
+     * thread-scoped run by its path (`POST /threads/{id}/runs/stream`) while carrying only
+     * `assistant_id` in the body, but the stateless run handlers read `thread_id` from the body — so a
+     * thread-scoped mount must copy it across, or the run would target a stray new thread.
+     */
+    foldThreadIdIntoBody?: boolean;
+}
+/** The route table, ordered most-specific-first within each method so literals win over params. */
+declare const skeinRoutes: readonly RouteBinding[];
+/**
+ * Copy the path `thread_id` into an object body so a stateless run handler runs on the right thread.
+ * A no-op when there is no `thread_id` param. Used by every adapter for the `foldThreadIdIntoBody`
+ * routes, so this rule lives in one place.
+ */
+declare function copyThreadIdIntoBody(request: ProtocolRequest): ProtocolRequest;
+/**
+ * @deprecated Renamed to {@link copyThreadIdIntoBody} — it copies the path `thread_id` into the
+ * request body. Kept for back-compat; slated for removal in a future major.
+ */
+declare const foldThreadId: typeof copyThreadIdIntoBody;
+/** A resolved route: the matched binding plus the path params extracted from the URL. */
+interface RouteMatch {
+    binding: RouteBinding;
+    params: Record<string, string>;
+}
+/**
+ * Match a `method` + `pathname` (no query string) against the route table, returning the binding and
+ * extracted path params, or `undefined` when nothing matches. Iterates in table order, which is
+ * most-specific-first, so a literal segment wins over a `:param`. This is what adapters that dispatch
+ * from a catch-all route (NestJS middleware, Next.js route handlers) use in place of a framework
+ * router; Express/Fastify bind `skeinRoutes` to their native router instead.
+ */
+declare function matchSkeinRoute(method: string, pathname: string): RouteMatch | undefined;
+
 type LangGraphSearchItem = Item$1 & {
     score?: number;
 };
@@ -380,4 +535,4 @@ declare function toSseEvents(frames: AsyncIterable<RunFrame>, finalStatus: () =>
  */
 declare function parseAfterSeq(lastEventId: string | undefined): number;
 
-export { type AssistantSearch, type AssistantService, type Clock, type CommandInput, type CompiledGraphFactory, type CreateRunInput, type CreateThreadInput, type GraphResolver, type GraphSchemas, type HistoryOptions, type Logger, type PatchThreadInput, type ProtocolContext, type ProtocolDeps, type ProtocolHandler, type ProtocolHandlers, type ProtocolRequest, type ProtocolResponse, type ProtocolRuntime, type ProtocolRuntimeOptions, type ProtocolService, type ResolvedGraph, type RunService, type RunWorker, type RunWorkerOptions, SSE_HEADERS, SkeinBaseStore, type StartedStream, type StoreService, type ThreadService, type ThreadStreamInput, type ThreadStreamService, buildProtocolService, createContext, createProtocolHandlers, createProtocolRuntime, createProtocolService, createRunWorker, encodeFrame, encodeTerminal, parseAfterSeq, toSseEvents };
+export { type AssistantService, type Clock, type CommandInput, type CompiledGraphFactory, type CreateAssistantInput, type CreateRunInput, type CreateThreadInput, type DeleteAssistantOptions, type DrawGraphOptions, type GraphResolver, type GraphSchemas, type HistoryOptions, type HttpMethod, type Logger, type PatchThreadInput, type ProtocolContext, type ProtocolDeps, type ProtocolHandler, type ProtocolHandlers, type ProtocolRequest, type ProtocolResponse, type ProtocolRuntime, type ProtocolRuntimeOptions, type ProtocolService, type ResolvedGraph, type RouteBinding, type RouteMatch, type RunService, type RunWorker, type RunWorkerOptions, SSE_HEADERS, SkeinBaseStore, type StartedStream, type StoreService, type SubgraphsOptions, type ThreadService, type ThreadStreamInput, type ThreadStreamService, buildProtocolService, copyThreadIdIntoBody, createContext, createProtocolHandlers, createProtocolRuntime, createProtocolService, createProtocolServiceFromContext, createRunWorker, encodeFrame, encodeTerminal, foldThreadId, matchSkeinRoute, parseAfterSeq, skeinRoutes, toSseEvents };