@skein-js/agent-protocol 0.4.0 → 0.6.3

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);
@@ -622,7 +957,10 @@ var RESERVED_CONFIGURABLE_KEYS = /* @__PURE__ */ new Set([
   "checkpoint_id",
   "checkpoint_ns",
   "checkpoint_map",
-  "checkpoint"
+  "checkpoint",
+  "langgraph_auth_user",
+  "langgraph_auth_user_id",
+  "langgraph_auth_permissions"
 ]);
 function sanitizeConfigurable(configurable) {
   if (!configurable) return {};
@@ -633,11 +971,33 @@ function sanitizeConfigurable(configurable) {
   }
   return clean;
 }
+function withAuthUser(configurable, authUser, scopes) {
+  if (!authUser) return configurable;
+  return {
+    ...configurable,
+    langgraph_auth_user: authUser,
+    langgraph_auth_user_id: authUser.identity,
+    langgraph_auth_permissions: scopes ?? authUser.permissions
+  };
+}
+function toFactoryConfigurable(kwargs) {
+  const configurable = withAuthUser(
+    sanitizeConfigurable(kwargs.config?.configurable),
+    kwargs.auth_user,
+    kwargs.auth_scopes
+  );
+  return Object.keys(configurable).length > 0 ? configurable : void 0;
+}
 function toGraphCallOptions(kwargs, threadId, signal) {
   const options = {
-    // Drop server-owned keys from the client's configurable, then force this thread's id.
-    configurable: { ...sanitizeConfigurable(kwargs.config?.configurable), thread_id: threadId },
-    streamMode: normalizeModes(kwargs.stream_mode),
+    // Drop server-owned keys from the client's configurable, force this thread's id, then stamp the
+    // authenticated caller so the graph can authorize off `configurable.langgraph_auth_user`.
+    configurable: withAuthUser(
+      { ...sanitizeConfigurable(kwargs.config?.configurable), thread_id: threadId },
+      kwargs.auth_user,
+      kwargs.auth_scopes
+    ),
+    streamMode: toGraphStreamModes(kwargs.stream_mode),
     signal
   };
   if (kwargs.context !== void 0) options.context = kwargs.context;
@@ -676,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
+          });
         }
       }
     }
@@ -715,9 +1078,19 @@ 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" ? await resolved({ configurable: kwargs.config?.configurable }) : resolved;
+  const graph = typeof resolved === "function" ? (
+    // Expose the authenticated caller to a graph *factory* too, so a factory that branches on the
+    // principal sees the same `langgraph_auth_user` a node reads — sanitized identically, so a
+    // client can't spoof it via its own configurable.
+    await resolved({ configurable: toFactoryConfigurable(kwargs) })
+  ) : resolved;
   graph.checkpointer = deps.checkpointer;
   graph.store = new SkeinBaseStore(deps.store.store);
   return graph;
@@ -754,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) => {
@@ -781,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}`);
     }
@@ -795,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);
@@ -825,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;
@@ -847,15 +1255,76 @@ 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);
   }
 }
 
 // src/runs/run-service.ts
-function toKwargs(input) {
+function toKwargs(input, authUser, authScopes) {
   const kwargs = {};
   if (input.input !== void 0) kwargs.input = input.input;
   if (input.command !== void 0) kwargs.command = input.command;
@@ -864,10 +1333,15 @@ function toKwargs(input) {
   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;
+  }
   return kwargs;
 }
 function createRunService(ctx) {
-  const { deps, control, locks } = 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.`);
@@ -899,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",
@@ -918,20 +1417,16 @@ 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);
       const thread = await ensureThread(input.thread_id);
-      const kwargs = toKwargs(input);
+      const kwargs = toKwargs(input, authUser, authScopes);
       const run = await createPendingRun(input, thread.thread_id, assistant.assistant_id, kwargs);
       await stampGraphOnThread(thread, assistant);
       const outcome = await runInline(run, kwargs);
@@ -940,7 +1435,7 @@ function createRunService(ctx) {
     async createStream(input) {
       const assistant = await requireAssistant(input.assistant_id);
       const thread = await ensureThread(input.thread_id);
-      const kwargs = toKwargs(input);
+      const kwargs = toKwargs(input, authUser, authScopes);
       const run = await createPendingRun(input, thread.thread_id, assistant.assistant_id, kwargs);
       await stampGraphOnThread(thread, assistant);
       void runInline(run, kwargs).catch(
@@ -951,7 +1446,7 @@ function createRunService(ctx) {
     async createBackground(threadId, input) {
       const assistant = await requireAssistant(input.assistant_id);
       const thread = await requireThread(threadId);
-      const kwargs = toKwargs(input);
+      const kwargs = toKwargs(input, authUser, authScopes);
       const run = await createPendingRun(
         { ...input, thread_id: threadId },
         threadId,
@@ -974,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");
@@ -992,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) {
@@ -1030,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: {},
@@ -1237,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)
@@ -1352,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" },
@@ -1410,7 +1879,7 @@ var STUDIO_USER = {
 };
 function createAuthorizingHandlers(context, engine) {
   const baseHandlers = createProtocolHandlers(buildProtocolService(context));
-  const names = Object.keys(baseHandlers);
+  const names = Object.keys(ROUTE_AUTHZ);
   const resolveAuthContext = async (req) => {
     if (!engine.studioAuthDisabled && req.headers["x-auth-scheme"] === "langsmith") {
       return { user: STUDIO_USER, scopes: [] };
@@ -1428,13 +1897,17 @@ function createAuthorizingHandlers(context, engine) {
         value: authValue(req),
         context: authContext
       });
-      if (!filters) return baseHandlers[name](req);
-      const scopedStore = createAuthScopedStore(context.deps.store, engine, filters, route.resource);
-      const scopedContext = {
+      if (!filters && !authContext) return baseHandlers[name](req);
+      const requestContext = {
         ...context,
-        deps: { ...context.deps, store: scopedStore }
+        authUser: authContext?.user,
+        authScopes: authContext?.scopes,
+        deps: filters ? {
+          ...context.deps,
+          store: createAuthScopedStore(context.deps.store, engine, filters, route.resource)
+        } : context.deps
       };
-      return createProtocolHandlers(buildProtocolService(scopedContext))[name](req);
+      return createProtocolHandlers(buildProtocolService(requestContext))[name](req);
     };
   }
   return wrapped;
@@ -1463,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);
     }
   };
@@ -1511,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,
@@ -1522,6 +2092,9 @@ export {
   createRunWorker,
   encodeFrame,
   encodeTerminal,
+  foldThreadId,
+  matchSkeinRoute,
   parseAfterSeq,
+  skeinRoutes,
   toSseEvents
 };