@skein-js/agent-protocol 0.5.0 → 0.6.3

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;
@@ -270,7 +364,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;
@@ -327,6 +429,42 @@ 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 the folding rule lives in one place.
+ */
+declare function foldThreadId(request: ProtocolRequest): ProtocolRequest;
+/** 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 +518,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, createContext, createProtocolHandlers, createProtocolRuntime, createProtocolService, createRunWorker, encodeFrame, encodeTerminal, foldThreadId, matchSkeinRoute, parseAfterSeq, skeinRoutes, toSseEvents };

package/dist/index.js

@@ -75,7 +75,9 @@ var runCreateSchema = z.object({
   metadata: z.record(z.unknown()).optional(),
   multitask_strategy: multitaskStrategySchema.optional(),
   interrupt_before: interruptWhenSchema.optional(),
-  interrupt_after: interruptWhenSchema.optional()
+  interrupt_after: interruptWhenSchema.optional(),
+  /** Run-completion webhook: an absolute `http(s)` URL POSTed the settled run when it finishes. */
+  webhook: z.string().url().optional()
 }).passthrough();
 var threadStreamSchema = z.object({
   assistant_id: z.string().min(1),
@@ -111,11 +113,47 @@ var threadSearchSchema = z.object({
   sort_by: z.enum(["thread_id", "status", "created_at", "updated_at"]).optional(),
   sort_order: z.enum(["asc", "desc"]).optional()
 }).passthrough();
+var assistantCreateSchema = z.object({
+  graph_id: z.string().min(1),
+  assistant_id: z.string().min(1).optional(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  config: configSchema.optional(),
+  context: z.unknown().optional(),
+  metadata: z.record(z.unknown()).optional(),
+  /** Conflict policy when `assistant_id` already exists; defaults to `raise`. */
+  if_exists: z.enum(["raise", "do_nothing"]).optional()
+}).passthrough();
+var assistantUpdateSchema = z.object({
+  graph_id: z.string().min(1).optional(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  config: configSchema.optional(),
+  context: z.unknown().optional(),
+  metadata: z.record(z.unknown()).optional()
+}).passthrough();
 var assistantSearchSchema = z.object({
   graph_id: z.string().optional(),
-  limit: z.number().int().positive().optional(),
+  name: z.string().optional(),
+  metadata: z.record(z.unknown()).optional(),
+  limit: z.number().int().positive().max(1e3).optional(),
+  offset: z.number().int().nonnegative().optional(),
+  sort_by: z.enum(["assistant_id", "graph_id", "name", "created_at", "updated_at"]).optional(),
+  sort_order: z.enum(["asc", "desc"]).optional()
+}).passthrough();
+var assistantCountSchema = z.object({
+  graph_id: z.string().optional(),
+  name: z.string().optional(),
+  metadata: z.record(z.unknown()).optional()
+}).passthrough();
+var assistantVersionsSchema = z.object({
+  metadata: z.record(z.unknown()).optional(),
+  limit: z.number().int().positive().max(1e3).optional(),
   offset: z.number().int().nonnegative().optional()
 }).passthrough();
+var assistantSetLatestSchema = z.object({
+  version: z.number().int().positive()
+}).passthrough();
 var storePutSchema = z.object({
   namespace: z.array(z.string()).min(1),
   key: z.string().min(1),
@@ -150,6 +188,15 @@ function positiveIntQuery(value) {
   const parsed = Number.parseInt(raw, 10);
   return Number.isInteger(parsed) && parsed > 0 ? parsed : void 0;
 }
+function booleanQuery(value) {
+  const raw = queryValue(value);
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  return void 0;
+}
+function xrayQuery(value) {
+  return booleanQuery(value) ?? positiveIntQuery(value);
+}
 function createProtocolHandlers(service) {
   const sse = (runId, frames) => ({
     kind: "sse",
@@ -160,8 +207,85 @@ function createProtocolHandlers(service) {
   return {
     // --- assistants ---------------------------------------------------------------------------
     getAssistant: async (req) => json(await service.assistants.get(requireParam(req.params, "assistant_id"))),
-    searchAssistants: async (req) => json(await service.assistants.search(parse(assistantSearchSchema, req.body ?? {}))),
+    searchAssistants: async (req) => {
+      const body = parse(assistantSearchSchema, req.body ?? {});
+      return json(
+        await service.assistants.search({
+          graph_id: body.graph_id,
+          name: body.name,
+          metadata: body.metadata,
+          limit: body.limit,
+          offset: body.offset,
+          sortBy: body.sort_by,
+          sortOrder: body.sort_order
+        })
+      );
+    },
+    countAssistants: async (req) => {
+      const body = parse(assistantCountSchema, req.body ?? {});
+      return json(
+        await service.assistants.count({
+          graph_id: body.graph_id,
+          name: body.name,
+          metadata: body.metadata
+        })
+      );
+    },
     getAssistantSchemas: async (req) => json(await service.assistants.schemas(requireParam(req.params, "assistant_id"))),
+    createAssistant: async (req) => {
+      const body = parse(assistantCreateSchema, req.body);
+      return json(
+        await service.assistants.create({
+          graph_id: body.graph_id,
+          assistant_id: body.assistant_id,
+          name: body.name,
+          description: body.description,
+          config: body.config,
+          context: body.context,
+          metadata: body.metadata,
+          ifExists: body.if_exists
+        })
+      );
+    },
+    updateAssistant: async (req) => json(
+      await service.assistants.update(
+        requireParam(req.params, "assistant_id"),
+        parse(assistantUpdateSchema, req.body ?? {})
+      )
+    ),
+    deleteAssistant: async (req) => {
+      await service.assistants.delete(requireParam(req.params, "assistant_id"), {
+        deleteThreads: booleanQuery(req.query["delete_threads"]) ?? false
+      });
+      return empty();
+    },
+    listAssistantVersions: async (req) => {
+      const body = parse(assistantVersionsSchema, req.body ?? {});
+      return json(
+        await service.assistants.listVersions(requireParam(req.params, "assistant_id"), {
+          metadata: body.metadata,
+          limit: body.limit,
+          offset: body.offset
+        })
+      );
+    },
+    setAssistantLatestVersion: async (req) => {
+      const body = parse(assistantSetLatestSchema, req.body);
+      return json(
+        await service.assistants.setLatest(requireParam(req.params, "assistant_id"), body.version)
+      );
+    },
+    getAssistantGraph: async (req) => json(
+      await service.assistants.drawGraph(requireParam(req.params, "assistant_id"), {
+        xray: xrayQuery(req.query["xray"])
+      })
+    ),
+    getAssistantSubgraphs: async (req) => json(
+      await service.assistants.subgraphs(requireParam(req.params, "assistant_id"), {
+        namespace: queryValue(req.query["namespace"]) ?? req.params["namespace"],
+        recurse: booleanQuery(req.query["recurse"]) ?? false
+      })
+    ),
     // --- threads ------------------------------------------------------------------------------
     createThread: async (req) => json(await service.threads.create(parse(threadCreateSchema, req.body ?? {}))),
     getThread: async (req) => json(await service.threads.get(requireParam(req.params, "thread_id"))),
@@ -280,35 +404,133 @@ function createProtocolHandlers(service) {
 }
 
 // src/assistants/assistant-service.ts
-import { SkeinHttpError as SkeinHttpError2 } from "@skein-js/core";
-function createAssistantService(deps) {
+import {
+  isSkeinHttpError,
+  SkeinHttpError as SkeinHttpError2
+} from "@skein-js/core";
+function factoryConfigurable(config) {
+  const configurable = config?.configurable;
+  return { configurable };
+}
+function createAssistantService(ctx, threads) {
+  const { deps } = ctx;
   const requireAssistant = async (assistantId) => {
     const assistant = await deps.store.assistants.get(assistantId);
     if (!assistant) throw SkeinHttpError2.notFound(`Assistant "${assistantId}" not found.`);
     return assistant;
   };
+  const requireGraph = (graphId) => {
+    if (!deps.graphs.ids.includes(graphId)) {
+      throw SkeinHttpError2.badRequest(`Unknown graph "${graphId}".`);
+    }
+  };
+  const deletableThreads = async (assistantId) => {
+    const owned = await deps.store.threads.search({ metadata: { assistant_id: assistantId } });
+    const engine = deps.auth;
+    if (!engine?.enabled || !ctx.authUser) return owned;
+    try {
+      const { filters } = await engine.authorize({
+        resource: "threads",
+        action: "delete",
+        value: { assistant_id: assistantId },
+        context: { user: ctx.authUser, scopes: ctx.authScopes ?? [] }
+      });
+      if (!filters) return owned;
+      return owned.filter((thread) => engine.matchesFilters(thread.metadata ?? void 0, filters));
+    } catch {
+      return [];
+    }
+  };
+  const compileGraph = async (assistant) => {
+    const resolved = await deps.graphs.load(assistant.graph_id);
+    return typeof resolved === "function" ? await resolved(factoryConfigurable(assistant.config)) : resolved;
+  };
   return {
     async registerGraphAssistants() {
       const registered = [];
       for (const graphId of deps.graphs.ids) {
         const existing = await deps.store.assistants.get(graphId);
-        registered.push(
-          existing ?? await deps.store.assistants.create({ graph_id: graphId, assistant_id: graphId })
-        );
+        if (existing) {
+          registered.push(existing);
+          continue;
+        }
+        try {
+          registered.push(
+            await deps.store.assistants.create({ graph_id: graphId, assistant_id: graphId })
+          );
+        } catch (error) {
+          if (isSkeinHttpError(error) && error.status === 409) {
+            const now = await deps.store.assistants.get(graphId);
+            if (now) {
+              registered.push(now);
+              continue;
+            }
+          }
+          throw error;
+        }
       }
       return registered;
     },
     get: requireAssistant,
     list: () => deps.store.assistants.list(),
-    async search(query) {
-      const all = await deps.store.assistants.list();
-      const filtered = query.graph_id ? all.filter((assistant) => assistant.graph_id === query.graph_id) : all;
-      const offset = query.offset ?? 0;
-      return filtered.slice(offset, query.limit === void 0 ? void 0 : offset + query.limit);
-    },
+    search: (query) => deps.store.assistants.search(query),
+    count: (query) => deps.store.assistants.count(query),
     async schemas(assistantId) {
       const assistant = await requireAssistant(assistantId);
       return deps.graphs.schemas(assistant.graph_id);
+    },
+    async create({ ifExists, ...input }) {
+      requireGraph(input.graph_id);
+      try {
+        return await deps.store.assistants.create(input);
+      } catch (error) {
+        if (input.assistant_id !== void 0 && ifExists === "do_nothing" && isSkeinHttpError(error) && error.status === 409) {
+          const existing = await deps.store.assistants.get(input.assistant_id);
+          if (existing) return existing;
+        }
+        throw error;
+      }
+    },
+    update(assistantId, patch) {
+      if (patch.graph_id !== void 0) requireGraph(patch.graph_id);
+      return deps.store.assistants.update(assistantId, patch);
+    },
+    async delete(assistantId, options) {
+      await requireAssistant(assistantId);
+      if (options?.deleteThreads) {
+        const owned = await deletableThreads(assistantId);
+        await Promise.all(owned.map((thread) => threads.delete(thread.thread_id)));
+      }
+      await deps.store.assistants.delete(assistantId);
+    },
+    async listVersions(assistantId, query) {
+      await requireAssistant(assistantId);
+      return deps.store.assistants.listVersions(assistantId, query);
+    },
+    setLatest: (assistantId, version) => deps.store.assistants.setLatest(assistantId, version),
+    async drawGraph(assistantId, options) {
+      const assistant = await requireAssistant(assistantId);
+      const graph = await compileGraph(assistant);
+      const drawable = await graph.getGraphAsync({
+        ...assistant.config ?? {},
+        xray: options?.xray
+      });
+      return drawable.toJSON();
+    },
+    async subgraphs(assistantId, options) {
+      const assistant = await requireAssistant(assistantId);
+      const graph = await compileGraph(assistant);
+      const schemas = await deps.graphs.schemas(assistant.graph_id);
+      const rootGraphId = Object.keys(schemas).find((key) => !key.includes("|"));
+      const result = {};
+      for await (const [namespace] of graph.getSubgraphsAsync(
+        options?.namespace,
+        options?.recurse
+      )) {
+        const schema = schemas[`${rootGraphId}|${namespace}`] ?? (rootGraphId !== void 0 ? schemas[rootGraphId] : void 0);
+        if (schema !== void 0) result[namespace] = schema;
+      }
+      return result;
     }
   };
 }
@@ -324,11 +546,35 @@ var noopLogger = {
   error: () => {
   }
 };
+var fetchWebhookDispatcher = async (url, payload) => {
+  let scheme;
+  try {
+    scheme = new URL(url).protocol;
+  } catch {
+    throw new Error(`Webhook URL "${url}" is not a valid absolute URL`);
+  }
+  if (scheme !== "http:" && scheme !== "https:") {
+    throw new Error(`Webhook URL scheme "${scheme}" is not allowed (only http/https)`);
+  }
+  const send = globalThis.fetch;
+  if (!send) {
+    throw new Error("global fetch is unavailable; inject a webhookDispatcher to deliver webhooks");
+  }
+  const response = await send(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+  if (!response.ok) {
+    throw new Error(`Webhook POST to ${url} failed with status ${response.status}`);
+  }
+};
 function resolveDeps(deps) {
   return {
     ...deps,
     clock: deps.clock ?? (() => /* @__PURE__ */ new Date()),
-    logger: deps.logger ?? noopLogger
+    logger: deps.logger ?? noopLogger,
+    webhookDispatcher: deps.webhookDispatcher ?? fetchWebhookDispatcher
   };
 }
 
@@ -388,7 +634,10 @@ function createContext(deps) {
   return {
     deps: resolveDeps(deps),
     control: new RunControlRegistry(),
-    locks: new ThreadLocks()
+    locks: new ThreadLocks(),
+    executionLocks: new ThreadLocks(),
+    runBaseCheckpoints: /* @__PURE__ */ new Map(),
+    rollbackPlans: /* @__PURE__ */ new Map()
   };
 }
 
@@ -398,6 +647,75 @@ import {
   SkeinHttpError as SkeinHttpError5
 } from "@skein-js/core";
 
+// src/threads/checkpoint-history.ts
+import {
+  copyCheckpoint
+} from "@langchain/langgraph";
+async function replayCheckpoints(checkpointer, targetId, tuples) {
+  for (const tuple of tuples) {
+    const ns = tuple.config.configurable?.checkpoint_ns ?? "";
+    const parentId = tuple.parentConfig?.configurable?.checkpoint_id;
+    const putConfig = {
+      configurable: { thread_id: targetId, checkpoint_ns: ns, checkpoint_id: parentId }
+    };
+    await checkpointer.put(
+      putConfig,
+      copyCheckpoint(tuple.checkpoint),
+      tuple.metadata ?? {},
+      tuple.checkpoint.channel_versions
+    );
+    if (tuple.pendingWrites && tuple.pendingWrites.length > 0) {
+      const writeConfig = {
+        configurable: {
+          thread_id: targetId,
+          checkpoint_ns: ns,
+          checkpoint_id: tuple.checkpoint.id
+        }
+      };
+      const byTask = /* @__PURE__ */ new Map();
+      for (const [taskId, channel, value] of tuple.pendingWrites) {
+        const writes = byTask.get(taskId) ?? [];
+        writes.push([channel, value]);
+        byTask.set(taskId, writes);
+      }
+      for (const [taskId, writes] of byTask) {
+        await checkpointer.putWrites(writeConfig, writes, taskId);
+      }
+    }
+  }
+}
+async function listCheckpoints(checkpointer, threadId) {
+  const tuples = [];
+  for await (const tuple of checkpointer.list({ configurable: { thread_id: threadId } })) {
+    tuples.push(tuple);
+  }
+  return tuples;
+}
+async function copyCheckpointHistory(checkpointer, sourceId, targetId) {
+  const tuples = await listCheckpoints(checkpointer, sourceId);
+  await replayCheckpoints(checkpointer, targetId, tuples.reverse());
+}
+async function rollbackThreadCheckpointsTo(checkpointer, threadId, baseCheckpointId) {
+  if (baseCheckpointId === void 0) {
+    await checkpointer.deleteThread(threadId);
+    return;
+  }
+  const tuples = await listCheckpoints(checkpointer, threadId);
+  const byId = new Map(tuples.map((tuple) => [tuple.checkpoint.id, tuple]));
+  if (!byId.has(baseCheckpointId)) return;
+  const keep = [];
+  let cursor = baseCheckpointId;
+  const seen = /* @__PURE__ */ new Set();
+  while (cursor !== void 0 && byId.has(cursor) && !seen.has(cursor)) {
+    seen.add(cursor);
+    const tuple = byId.get(cursor);
+    keep.push(tuple);
+    cursor = tuple.parentConfig?.configurable?.checkpoint_id;
+  }
+  await checkpointer.deleteThread(threadId);
+  await replayCheckpoints(checkpointer, threadId, keep.reverse());
+}
+
 // src/runs/run-engine.ts
 import {
   isTerminalRunStatus as isTerminalRunStatus2,
@@ -405,7 +723,7 @@ import {
 } from "@skein-js/core";
 
 // src/normalize-error.ts
-import { isSkeinHttpError, SkeinHttpError as SkeinHttpError3 } from "@skein-js/core";
+import { isSkeinHttpError as isSkeinHttpError2, SkeinHttpError as SkeinHttpError3 } from "@skein-js/core";
 function serializeError(error) {
   if (error instanceof Error) {
     return { name: error.name, message: error.message };
@@ -435,6 +753,18 @@ function chunkToFrameBody(chunk) {
 function toRunFrame(seq, body) {
   return { seq, event: body.event, data: body.data };
 }
+function streamEventToFrameBody(event, runId, graphModes) {
+  if (event.tags?.includes("langsmith:hidden")) return null;
+  if (event.event === "on_chain_stream" && event.run_id === runId) {
+    const chunk = event.data?.chunk;
+    if (Array.isArray(chunk) && chunk.length === 2 && isStreamMode(chunk[0])) {
+      const mode = chunk[0];
+      return graphModes.includes(mode) ? { event: mode, data: chunk[1] } : null;
+    }
+    return null;
+  }
+  return { event: "events", data: event };
+}
 
 // src/store/skein-base-store.ts
 import {
@@ -601,7 +931,6 @@ function snapshotToThreadState(snapshot) {
 import { Command } from "@langchain/langgraph";
 function toGraphMode(mode) {
   if (mode === "messages-tuple") return "messages";
-  if (mode === "events") return "updates";
   return mode;
 }
 function normalizeModes(mode) {
@@ -610,6 +939,12 @@ function normalizeModes(mode) {
   const deduped = [...new Set(mapped)];
   return deduped.length > 0 ? deduped : ["values"];
 }
+function wantsEventsMode(mode) {
+  return normalizeModes(mode).includes("events");
+}
+function toGraphStreamModes(mode) {
+  return normalizeModes(mode).filter((m) => m !== "events");
+}
 function toGraphInput(kwargs) {
   if (kwargs.command) {
     return new Command(kwargs.command);
@@ -662,7 +997,7 @@ function toGraphCallOptions(kwargs, threadId, signal) {
       kwargs.auth_user,
       kwargs.auth_scopes
     ),
-    streamMode: normalizeModes(kwargs.stream_mode),
+    streamMode: toGraphStreamModes(kwargs.stream_mode),
     signal
   };
   if (kwargs.context !== void 0) options.context = kwargs.context;
@@ -701,7 +1036,10 @@ function extractToolActivity(data) {
     if (Array.isArray(toolCalls)) {
       for (const call of toolCalls) {
         if (isRecord(call) && typeof call["name"] === "string" && call["name"].length > 0) {
-          calls.push({ name: call["name"], id: typeof call["id"] === "string" ? call["id"] : void 0 });
+          calls.push({
+            name: call["name"],
+            id: typeof call["id"] === "string" ? call["id"] : void 0
+          });
         }
       }
     }
@@ -740,6 +1078,11 @@ function describeInterrupts(snapshot) {
 }
 
 // src/runs/run-engine.ts
+function abortedStatus(reason) {
+  if (reason === "timeout") return "timeout";
+  if (reason === "interrupt") return "interrupted";
+  return "cancelled";
+}
 async function resolveGraph(deps, graphId, kwargs) {
   const resolved = await deps.graphs.load(graphId);
   const graph = typeof resolved === "function" ? (
@@ -784,6 +1127,9 @@ async function executeRun(deps, exec) {
   const runId = run.run_id;
   const threadId = run.thread_id;
   let seq = 0;
+  let started = false;
+  let outcome = { status: "error", values: {} };
+  let webhookErrorMessage;
   const startedAt = deps.clock().getTime();
   const loggedTools = /* @__PURE__ */ new Set();
   const logToolActivity = (data) => {
@@ -811,10 +1157,23 @@ async function executeRun(deps, exec) {
   try {
     const current = await deps.store.runs.get(runId);
     if (current && isTerminalRunStatus2(current.status)) {
-      return { status: current.status, values: {} };
+      outcome = { status: current.status, values: {} };
+      return outcome;
     }
     await deps.store.runs.setStatus(runId, "running");
+    started = true;
     await mirrorThreadStatus(deps, threadId, "busy");
+    if (exec.recordBaseCheckpoint) {
+      try {
+        const tip = await deps.checkpointer.getTuple({ configurable: { thread_id: threadId } });
+        exec.recordBaseCheckpoint(tip?.checkpoint.id);
+      } catch (error) {
+        deps.logger.warn(
+          `run ${runId}: failed to read base checkpoint; a rollback of this run won't revert checkpoints`,
+          error
+        );
+      }
+    }
     if (deps.logRunActivity) {
       deps.logger.info(`run ${runId} started \xB7 assistant=${run.assistant_id} thread=${threadId}`);
     }
@@ -825,20 +1184,36 @@ async function executeRun(deps, exec) {
     const graph = await resolveGraph(deps, assistant.graph_id, kwargs);
     const input = toGraphInput(kwargs);
     const options = toGraphCallOptions(kwargs, threadId, control.signal);
-    const stream = await graph.stream(input, options);
-    for await (const chunk of stream) {
-      seq += 1;
-      const body = chunkToFrameBody(chunk);
-      await deps.bus.publish(runId, toRunFrame(seq, body));
-      if (deps.logRunActivity) logToolActivity(body.data);
+    if (wantsEventsMode(kwargs.stream_mode)) {
+      const graphModes = toGraphStreamModes(kwargs.stream_mode);
+      const eventStream = graph.streamEvents(input, {
+        ...options,
+        version: "v2",
+        runId
+      });
+      for await (const event of eventStream) {
+        const body = streamEventToFrameBody(event, runId, graphModes);
+        if (!body) continue;
+        seq += 1;
+        await deps.bus.publish(runId, toRunFrame(seq, body));
+        if (deps.logRunActivity) logToolActivity(body.data);
+      }
+    } else {
+      const stream = await graph.stream(input, options);
+      for await (const chunk of stream) {
+        seq += 1;
+        const body = chunkToFrameBody(chunk);
+        await deps.bus.publish(runId, toRunFrame(seq, body));
+        if (deps.logRunActivity) logToolActivity(body.data);
+      }
     }
     if (control.signal.aborted) {
-      const timedOut = control.reason.current === "timeout";
-      const finalStatus2 = await finalizeRun(deps, runId, timedOut ? "timeout" : "cancelled");
+      const finalStatus2 = await finalizeRun(deps, runId, abortedStatus(control.reason.current));
       if (finalStatus2 === "timeout") await mirrorThreadError(deps, threadId, "Run timed out.");
-      else if (finalStatus2 === "cancelled") await mirrorThreadStatus(deps, threadId, "idle");
+      else await mirrorThreadStatus(deps, threadId, "idle");
       logFinished(finalStatus2);
-      return { status: finalStatus2, values: {} };
+      outcome = { status: finalStatus2, values: {} };
+      return outcome;
     }
     const snapshot = await graph.getState({ configurable: { thread_id: threadId } });
     const computed = runStatusForSnapshot(snapshot);
@@ -855,20 +1230,23 @@ async function executeRun(deps, exec) {
       );
     }
     logFinished(finalStatus);
-    return { status: finalStatus, values: snapshot.values };
+    outcome = { status: finalStatus, values: snapshot.values };
+    return outcome;
   } catch (error) {
     const reason = control.reason.current;
     if (reason === "timeout") {
       const finalStatus2 = await finalizeRun(deps, runId, "timeout");
       if (finalStatus2 === "timeout") await mirrorThreadError(deps, threadId, "Run timed out.");
       logFinished(finalStatus2);
-      return { status: finalStatus2, values: {} };
+      outcome = { status: finalStatus2, values: {} };
+      return outcome;
     }
-    if (reason === "cancel" || control.signal.aborted) {
-      const finalStatus2 = await finalizeRun(deps, runId, "cancelled");
-      if (finalStatus2 === "cancelled") await mirrorThreadStatus(deps, threadId, "idle");
+    if (reason === "cancel" || reason === "interrupt" || reason === "rollback" || control.signal.aborted) {
+      const finalStatus2 = await finalizeRun(deps, runId, abortedStatus(reason));
+      await mirrorThreadStatus(deps, threadId, "idle");
       logFinished(finalStatus2);
-      return { status: finalStatus2, values: {} };
+      outcome = { status: finalStatus2, values: {} };
+      return outcome;
     }
     const serialized = serializeError(error);
     seq += 1;
@@ -877,10 +1255,71 @@ async function executeRun(deps, exec) {
     if (finalStatus === "error") await mirrorThreadError(deps, threadId, serialized.message);
     if (deps.logRunActivity) deps.logger.error(`run ${runId} error: ${serialized.message}`);
     logFinished(finalStatus);
-    return { status: finalStatus, values: {} };
+    webhookErrorMessage = serialized.message;
+    outcome = { status: finalStatus, values: {} };
+    return outcome;
   } finally {
     if (timer !== void 0) clearTimeout(timer);
     await deps.bus.close(runId);
+    if (started && kwargs.webhook !== void 0) {
+      const sentAt = deps.clock().toISOString();
+      const payload = {
+        ...run,
+        status: outcome.status,
+        values: outcome.values,
+        run_started_at: new Date(startedAt).toISOString(),
+        run_ended_at: sentAt,
+        webhook_sent_at: sentAt,
+        ...webhookErrorMessage !== void 0 ? { error: webhookErrorMessage } : {}
+      };
+      try {
+        await deps.webhookDispatcher(kwargs.webhook, payload);
+      } catch (error) {
+        deps.logger.warn(`run ${runId}: webhook delivery to ${kwargs.webhook} failed`, error);
+      }
+    }
+  }
+}
+
+// src/runs/run-execution.ts
+async function startRunExecution(ctx, run, kwargs) {
+  const { deps, control, executionLocks, runBaseCheckpoints, rollbackPlans } = ctx;
+  const runId = run.run_id;
+  const threadId = run.thread_id;
+  const runControl = control.register(runId);
+  try {
+    return await executionLocks.run(threadId, async () => {
+      const plan = rollbackPlans.get(runId);
+      if (plan) {
+        rollbackPlans.delete(runId);
+        if (plan.revertToCheckpoint !== false) {
+          try {
+            await rollbackThreadCheckpointsTo(
+              deps.checkpointer,
+              threadId,
+              plan.revertToCheckpoint.baseCheckpointId
+            );
+          } catch (error) {
+            deps.logger.warn(`run ${runId}: rollback of displaced writes failed`, error);
+          }
+        }
+        for (const displacedId of plan.displacedRunIds) {
+          try {
+            await deps.store.runs.delete(displacedId);
+          } catch {
+          }
+        }
+      }
+      return await executeRun(deps, {
+        run,
+        kwargs,
+        control: runControl,
+        recordBaseCheckpoint: (base) => runBaseCheckpoints.set(runId, base)
+      });
+    });
+  } finally {
+    control.clear(runId);
+    runBaseCheckpoints.delete(runId);
   }
 }
 
@@ -894,6 +1333,7 @@ function toKwargs(input, authUser, authScopes) {
   if (input.stream_mode !== void 0) kwargs.stream_mode = input.stream_mode;
   if (input.interrupt_before !== void 0) kwargs.interrupt_before = input.interrupt_before;
   if (input.interrupt_after !== void 0) kwargs.interrupt_after = input.interrupt_after;
+  if (input.webhook !== void 0) kwargs.webhook = input.webhook;
   if (authUser !== void 0) {
     kwargs.auth_user = authUser;
     if (authScopes !== void 0) kwargs.auth_scopes = authScopes;
@@ -901,7 +1341,7 @@ function toKwargs(input, authUser, authScopes) {
   return kwargs;
 }
 function createRunService(ctx) {
-  const { deps, control, locks, authUser, authScopes } = ctx;
+  const { deps, control, locks, runBaseCheckpoints, authUser, authScopes } = ctx;
   const requireThread = async (threadId) => {
     const thread = await deps.store.threads.get(threadId);
     if (!thread) throw SkeinHttpError5.notFound(`Thread "${threadId}" not found.`);
@@ -933,18 +1373,43 @@ function createRunService(ctx) {
     const existing = await deps.store.threads.get(threadId);
     return existing ?? await deps.store.threads.create({ thread_id: threadId });
   };
+  const cancelActiveRun = async (run, reason) => {
+    const terminal = reason === "interrupt" ? "interrupted" : "cancelled";
+    if (run.status === "pending") {
+      await deps.store.runs.setStatus(run.run_id, terminal);
+      await deps.bus.close(run.run_id);
+      control.abort(run.run_id, reason);
+    } else {
+      await deps.store.runs.setStatus(run.run_id, terminal);
+      control.abort(run.run_id, reason);
+    }
+  };
   const createPendingRun = async (input, threadId, assistantId, kwargs) => {
     return locks.run(threadId, async () => {
       const strategy = input.multitask_strategy ?? "reject";
-      if (await deps.store.runs.hasActiveRun(threadId)) {
-        if (strategy !== "reject") {
-          deps.logger.warn(`multitask_strategy "${strategy}" treated as reject (MVP).`);
+      const active = await deps.store.runs.listActiveRuns(threadId);
+      let rollbackPlan;
+      if (active.length > 0) {
+        if (strategy === "reject") {
+          throw SkeinHttpError5.unprocessable(
+            "Thread is already running a task. Wait for it to finish or choose a different multitask strategy.",
+            { code: "thread_busy" }
+          );
+        }
+        if (strategy === "interrupt") {
+          for (const run of active) await cancelActiveRun(run, "interrupt");
+        } else if (strategy === "rollback") {
+          let revertToCheckpoint = false;
+          for (const run of active) {
+            if (runBaseCheckpoints.has(run.run_id)) {
+              revertToCheckpoint = { baseCheckpointId: runBaseCheckpoints.get(run.run_id) };
+            }
+          }
+          rollbackPlan = { revertToCheckpoint, displacedRunIds: active.map((run) => run.run_id) };
+          for (const run of active) await cancelActiveRun(run, "rollback");
         }
-        throw SkeinHttpError5.conflict(`Thread "${threadId}" already has an active run.`, {
-          code: "thread_busy"
-        });
       }
-      return deps.store.runs.create({
+      const created = await deps.store.runs.create({
         thread_id: threadId,
         assistant_id: assistantId,
         status: "pending",
@@ -952,15 +1417,11 @@ function createRunService(ctx) {
         multitask_strategy: strategy,
         kwargs
       });
+      if (rollbackPlan) ctx.rollbackPlans.set(created.run_id, rollbackPlan);
+      return created;
     });
   };
-  const runInline = (run, kwargs) => {
-    const runControl = control.register(run.run_id);
-    const done = executeRun(deps, { run, kwargs, control: runControl }).finally(
-      () => control.clear(run.run_id)
-    );
-    return done;
-  };
+  const runInline = (run, kwargs) => startRunExecution(ctx, run, kwargs);
   return {
     async createWait(input) {
       const assistant = await requireAssistant(input.assistant_id);
@@ -1008,6 +1469,7 @@ function createRunService(ctx) {
     async cancel(runId) {
       const run = await deps.store.runs.get(runId);
       if (!run) throw SkeinHttpError5.notFound(`Run "${runId}" not found.`);
+      ctx.rollbackPlans.delete(runId);
       if (isTerminalRunStatus3(run.status)) return run;
       if (run.status === "pending") {
         await deps.store.runs.setStatus(runId, "cancelled");
@@ -1026,6 +1488,7 @@ function createRunService(ctx) {
         throw SkeinHttpError5.notFound(`Run "${runId}" not found.`);
       }
       control.abort(runId, "cancel");
+      ctx.rollbackPlans.delete(runId);
       await deps.store.runs.delete(runId);
     },
     async join(runId, afterSeq = 0) {
@@ -1064,50 +1527,10 @@ function createStoreService(deps) {
 }
 
 // src/threads/thread-service.ts
-import {
-  copyCheckpoint
-} from "@langchain/langgraph";
 import {
   isTerminalRunStatus as isTerminalRunStatus4,
   SkeinHttpError as SkeinHttpError7
 } from "@skein-js/core";
-async function copyCheckpointHistory(checkpointer, sourceId, targetId) {
-  const tuples = [];
-  for await (const tuple of checkpointer.list({ configurable: { thread_id: sourceId } })) {
-    tuples.push(tuple);
-  }
-  for (const tuple of tuples.reverse()) {
-    const ns = tuple.config.configurable?.checkpoint_ns ?? "";
-    const parentId = tuple.parentConfig?.configurable?.checkpoint_id;
-    const putConfig = {
-      configurable: { thread_id: targetId, checkpoint_ns: ns, checkpoint_id: parentId }
-    };
-    await checkpointer.put(
-      putConfig,
-      copyCheckpoint(tuple.checkpoint),
-      tuple.metadata ?? {},
-      tuple.checkpoint.channel_versions
-    );
-    if (tuple.pendingWrites && tuple.pendingWrites.length > 0) {
-      const writeConfig = {
-        configurable: {
-          thread_id: targetId,
-          checkpoint_ns: ns,
-          checkpoint_id: tuple.checkpoint.id
-        }
-      };
-      const byTask = /* @__PURE__ */ new Map();
-      for (const [taskId, channel, value] of tuple.pendingWrites) {
-        const writes = byTask.get(taskId) ?? [];
-        writes.push([channel, value]);
-        byTask.set(taskId, writes);
-      }
-      for (const [taskId, writes] of byTask) {
-        await checkpointer.putWrites(writeConfig, writes, taskId);
-      }
-    }
-  }
-}
 function emptyThreadState(threadId) {
   return {
     values: {},
@@ -1271,9 +1694,13 @@ function createThreadStreamService(ctx, runs) {
 // src/service.ts
 function buildProtocolService(ctx) {
   const runs = createRunService(ctx);
+  const threads = createThreadService(ctx);
   return {
-    assistants: createAssistantService(ctx.deps),
-    threads: createThreadService(ctx),
+    // The assistant service reuses the thread service for its `delete_threads` cascade (abort +
+    // delete), and needs the full context (auth engine + caller) to scope that cascade to the
+    // threads the caller may delete.
+    assistants: createAssistantService(ctx, threads),
+    threads,
     threadStream: createThreadStreamService(ctx, runs),
     runs,
     store: createStoreService(ctx.deps)
@@ -1386,7 +1813,15 @@ var ROUTE_AUTHZ = {
   // assistants
   getAssistant: { resource: "assistants", action: "read" },
   getAssistantSchemas: { resource: "assistants", action: "read" },
+  getAssistantGraph: { resource: "assistants", action: "read" },
+  getAssistantSubgraphs: { resource: "assistants", action: "read" },
+  listAssistantVersions: { resource: "assistants", action: "read" },
   searchAssistants: { resource: "assistants", action: "search" },
+  countAssistants: { resource: "assistants", action: "search" },
+  createAssistant: { resource: "assistants", action: "create" },
+  updateAssistant: { resource: "assistants", action: "update" },
+  setAssistantLatestVersion: { resource: "assistants", action: "update" },
+  deleteAssistant: { resource: "assistants", action: "delete" },
   // threads
   createThread: { resource: "threads", action: "create" },
   copyThread: { resource: "threads", action: "create" },
@@ -1501,17 +1936,18 @@ function createRunWorker(ctx, options = {}) {
   const inFlight = /* @__PURE__ */ new Set();
   const process = async (queued) => {
     const run = await deps.store.runs.get(queued.run_id);
-    if (!run || isTerminalRunStatus6(run.status)) return;
+    if (!run || isTerminalRunStatus6(run.status)) {
+      ctx.rollbackPlans.delete(queued.run_id);
+      return;
+    }
     const kwargs = await deps.store.runs.getKwargs(queued.run_id) ?? {};
-    const runControl = control.register(queued.run_id);
     inFlight.add(queued.run_id);
     const startedAt = Date.now();
     let status = "error";
     try {
-      status = (await executeRun(deps, { run, kwargs, control: runControl })).status;
+      status = (await startRunExecution(ctx, run, kwargs)).status;
     } finally {
       logRunLifecycle(deps.logger, run, status, startedAt, Date.now());
-      control.clear(queued.run_id);
       inFlight.delete(queued.run_id);
     }
   };
@@ -1549,6 +1985,102 @@ function createProtocolRuntime(deps, options = {}) {
     worker: createRunWorker(context, options.worker)
   };
 }
+
+// src/http/routes.ts
+var skeinRoutes = [
+  // assistants — literals (search/count) before `:assistant_id`, and nested paths before the bare id.
+  { method: "post", path: "/assistants/search", handler: "searchAssistants" },
+  { method: "post", path: "/assistants/count", handler: "countAssistants" },
+  { method: "post", path: "/assistants", handler: "createAssistant" },
+  { method: "get", path: "/assistants/:assistant_id/schemas", handler: "getAssistantSchemas" },
+  { method: "get", path: "/assistants/:assistant_id/graph", handler: "getAssistantGraph" },
+  {
+    method: "get",
+    path: "/assistants/:assistant_id/subgraphs/:namespace",
+    handler: "getAssistantSubgraphs"
+  },
+  { method: "get", path: "/assistants/:assistant_id/subgraphs", handler: "getAssistantSubgraphs" },
+  { method: "post", path: "/assistants/:assistant_id/versions", handler: "listAssistantVersions" },
+  {
+    method: "post",
+    path: "/assistants/:assistant_id/latest",
+    handler: "setAssistantLatestVersion"
+  },
+  { method: "get", path: "/assistants/:assistant_id", handler: "getAssistant" },
+  { method: "patch", path: "/assistants/:assistant_id", handler: "updateAssistant" },
+  { method: "delete", path: "/assistants/:assistant_id", handler: "deleteAssistant" },
+  // threads
+  { method: "post", path: "/threads/search", handler: "listThreads" },
+  { method: "post", path: "/threads", handler: "createThread" },
+  { method: "post", path: "/threads/:thread_id/copy", handler: "copyThread" },
+  { method: "get", path: "/threads/:thread_id", handler: "getThread" },
+  { method: "patch", path: "/threads/:thread_id", handler: "patchThread" },
+  { method: "delete", path: "/threads/:thread_id", handler: "deleteThread" },
+  { method: "get", path: "/threads/:thread_id/state", handler: "getThreadState" },
+  { method: "post", path: "/threads/:thread_id/history", handler: "getThreadHistory" },
+  // runs — the stateless handlers are reused on the thread-scoped path with the id folded in
+  { method: "post", path: "/runs/wait", handler: "createWaitRun" },
+  { method: "post", path: "/runs/stream", handler: "createStreamRun" },
+  {
+    method: "post",
+    path: "/threads/:thread_id/runs/wait",
+    handler: "createWaitRun",
+    foldThreadIdIntoBody: true
+  },
+  {
+    method: "post",
+    path: "/threads/:thread_id/runs/stream",
+    handler: "createStreamRun",
+    foldThreadIdIntoBody: true
+  },
+  { method: "post", path: "/threads/:thread_id/runs", handler: "createBackgroundRun" },
+  { method: "get", path: "/threads/:thread_id/runs", handler: "listThreadRuns" },
+  { method: "post", path: "/threads/:thread_id/runs/:run_id/cancel", handler: "cancelRun" },
+  { method: "get", path: "/threads/:thread_id/runs/:run_id/stream", handler: "joinRunStream" },
+  { method: "get", path: "/threads/:thread_id/runs/:run_id", handler: "getRun" },
+  { method: "delete", path: "/threads/:thread_id/runs/:run_id", handler: "deleteRun" },
+  { method: "get", path: "/runs/:run_id/stream", handler: "joinRunStream" },
+  // thread streaming / commands
+  { method: "post", path: "/threads/:thread_id/stream", handler: "postThreadStream" },
+  { method: "get", path: "/threads/:thread_id/stream", handler: "getThreadStream" },
+  { method: "post", path: "/threads/:thread_id/commands", handler: "postThreadCommands" },
+  // store
+  { method: "put", path: "/store/items", handler: "putStoreItem" },
+  { method: "get", path: "/store/items", handler: "getStoreItem" },
+  { method: "delete", path: "/store/items", handler: "deleteStoreItem" },
+  { method: "post", path: "/store/items/search", handler: "searchStoreItems" },
+  { method: "post", path: "/store/namespaces", handler: "listStoreNamespaces" }
+];
+function foldThreadId(request) {
+  const threadId = request.params["thread_id"];
+  if (threadId === void 0) return request;
+  const base = typeof request.body === "object" && request.body !== null && !Array.isArray(request.body) ? request.body : {};
+  return { ...request, body: { ...base, thread_id: threadId } };
+}
+var compiledRoutes = skeinRoutes.map((binding) => ({
+  binding,
+  regex: new RegExp(`^${binding.path.replace(/:(\w+)/g, "(?<$1>[^/]+)")}$`)
+}));
+function matchSkeinRoute(method, pathname) {
+  const wanted = method.toLowerCase();
+  for (const { binding, regex } of compiledRoutes) {
+    if (binding.method !== wanted) continue;
+    const match = regex.exec(pathname);
+    if (match) return { binding, params: decodeParams(match.groups) };
+  }
+  return void 0;
+}
+function decodeParams(groups) {
+  const params = {};
+  for (const [key, value] of Object.entries(groups ?? {})) {
+    try {
+      params[key] = decodeURIComponent(value);
+    } catch {
+      params[key] = value;
+    }
+  }
+  return params;
+}
 export {
   SSE_HEADERS,
   SkeinBaseStore,
@@ -1560,6 +2092,9 @@ export {
   createRunWorker,
   encodeFrame,
   encodeTerminal,
+  foldThreadId,
+  matchSkeinRoute,
   parseAfterSeq,
+  skeinRoutes,
   toSseEvents
 };

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@skein-js/agent-protocol",
-  "version": "0.5.0",
+  "version": "0.6.3",
   "description": "Framework-agnostic Agent Protocol engine for LangGraph.js — run engine, handlers, and SSE, driven entirely by injected dependencies.",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
-  "homepage": "https://github.com/mainawycliffe/skein-js/tree/main/packages/agent-protocol#readme",
+  "homepage": "https://github.com/skein-js/skein-js/tree/main/packages/agent-protocol#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mainawycliffe/skein-js.git",
+    "url": "git+https://github.com/skein-js/skein-js.git",
     "directory": "packages/agent-protocol"
   },
   "bugs": {
-    "url": "https://github.com/mainawycliffe/skein-js/issues"
+    "url": "https://github.com/skein-js/skein-js/issues"
   },
   "keywords": [
     "typescript",
@@ -44,14 +44,14 @@
   },
   "dependencies": {
     "zod": "^3.25.76",
-    "@skein-js/core": "0.5.0"
+    "@skein-js/core": "0.6.3"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0",
     "@langchain/langgraph-sdk": "^1.9.0"
   },
   "devDependencies": {
-    "@skein-js/storage-memory": "0.5.0"
+    "@skein-js/storage-memory": "0.6.3"
   },
   "publishConfig": {
     "access": "public"