@skein-js/agent-protocol 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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 { GraphSchema, SkeinStore, RunQueue, RunEventBus, AuthEngine, AuthUser, Metadata, Thread, ThreadSearchQuery, ThreadState, Checkpoint, 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. */
@@ -184,6 +184,17 @@ interface PatchThreadInput {
 interface HistoryOptions {
     limit?: number;
 }
+/** Body of `POST /threads/{id}/state` — a time-travel update that forks a new checkpoint. */
+interface UpdateStateInput {
+    /** New state to write. `null`/`undefined` re-points `next` without changing values. */
+    values?: unknown;
+    /** Attribute the update as though this node produced `values` (sets up which node runs next). */
+    as_node?: string;
+    /** The checkpoint to fork from; omitted updates the thread tip. */
+    checkpoint_id?: string;
+    /** Full checkpoint pointer to fork from (alternative to `checkpoint_id`). */
+    checkpoint?: Record<string, unknown>;
+}
 interface ThreadService {
     create(input?: CreateThreadInput): Promise<Thread>;
     get(threadId: string): Promise<Thread>;
@@ -197,6 +208,15 @@ interface ThreadService {
     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>;
+    /** State at a specific checkpoint (time travel) — `GET /threads/{id}/state/{checkpoint_id}`. */
+    getStateAt(threadId: string, checkpointId: string): Promise<ThreadState>;
+    /**
+     * Update (fork) thread state at a checkpoint — `POST /threads/{id}/state`. Writes a new checkpoint
+     * via `graph.updateState`, mirrors it onto the thread row, and returns the new checkpoint pointer.
+     */
+    updateState(threadId: string, input: UpdateStateInput): Promise<{
+        checkpoint: Checkpoint;
+    }>;
 }
 
 /** `POST /assistants` — create input plus LangGraph's `if_exists` conflict policy. */
@@ -266,6 +286,8 @@ interface CreateRunInput {
     interrupt_after?: string[] | "*";
     /** Absolute `http(s)` URL POSTed with the settled run once it reaches a terminal status. */
     webhook?: string;
+    /** Time travel: fork this run from a prior checkpoint instead of the thread tip (server-validated). */
+    checkpoint_id?: string;
 }
 /** A started streaming run: its id, plus the live frame iterable to serialize as SSE. */
 interface StartedStream {
@@ -352,6 +374,12 @@ interface ProtocolRequest {
     query: Record<string, string | string[] | undefined>;
     body: unknown;
     headers: Record<string, string | undefined>;
+    /**
+     * Aborts when the client goes away, so a handler can stop work the caller will never read.
+     * Optional: an adapter that can't observe disconnects simply omits it. Currently honored by the
+     * single-graph invoke surface; protocol runs carry their own cancellation through the run row.
+     */
+    signal?: AbortSignal;
 }
 /** A normalized response an adapter serializes back onto its framework response. */
 type ProtocolResponse = {
@@ -387,6 +415,8 @@ interface ProtocolHandlers {
     deleteThread: ProtocolHandler;
     getThreadHistory: ProtocolHandler;
     getThreadState: ProtocolHandler;
+    getThreadStateAtCheckpoint: ProtocolHandler;
+    updateThreadState: ProtocolHandler;
     createWaitRun: ProtocolHandler;
     createStreamRun: ProtocolHandler;
     createBackgroundRun: ProtocolHandler;
@@ -442,11 +472,16 @@ interface ProtocolRuntime {
 declare function createProtocolRuntime(deps: ProtocolDeps, options?: ProtocolRuntimeOptions): ProtocolRuntime;
 
 type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
-interface RouteBinding {
+/**
+ * One route. `HandlerName` defaults to a member of the protocol handler table; a surface mounted
+ * outside that table (the single-graph invoke endpoint) parameterizes it with its own handler names,
+ * so `handler` never has to lie about being a `keyof ProtocolHandlers` an adapter could look up.
+ */
+interface RouteBinding<HandlerName = keyof ProtocolHandlers> {
     method: HttpMethod;
     /** Path with `:param` placeholders, e.g. `/threads/:thread_id/runs/stream`. */
     path: string;
-    handler: keyof ProtocolHandlers;
+    handler: HandlerName;
     /**
      * 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
@@ -469,18 +504,50 @@ declare function copyThreadIdIntoBody(request: ProtocolRequest): ProtocolRequest
  */
 declare const foldThreadId: typeof copyThreadIdIntoBody;
 /** A resolved route: the matched binding plus the path params extracted from the URL. */
-interface RouteMatch {
-    binding: RouteBinding;
+interface RouteMatch<HandlerName = keyof ProtocolHandlers> {
+    binding: RouteBinding<HandlerName>;
     params: Record<string, string>;
 }
+/** Matches a `method` + `pathname` against a fixed route table. Built by {@link createRouteMatcher}. */
+type RouteMatcher<HandlerName = keyof ProtocolHandlers> = (method: string, pathname: string) => RouteMatch<HandlerName> | undefined;
+/**
+ * Build a matcher over any route table — the protocol's own, or the simplified invoke surface's.
+ * Each `:param` path is compiled to a named-group regex once, anchored (`^…$`) so a literal segment
+ * can't be matched as a param value. The returned matcher iterates in table order, which is
+ * most-specific-first, so a literal segment wins over a `:param`.
+ */
+declare function createRouteMatcher<HandlerName>(bindings: readonly RouteBinding<HandlerName>[]): RouteMatcher<HandlerName>;
+/**
+ * Match a `method` + `pathname` (no query string) against the Agent Protocol route table. 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 const matchSkeinRoute: RouteMatcher;
+
+/** The default path prefix the invoke endpoint mounts under. */
+declare const DEFAULT_INVOKE_PREFIX = "/invoke";
+/** Options for {@link createGraphInvokeHandler}. */
+interface GraphInvokeOptions {
+    /**
+     * Stream modes used when the caller opts into SSE, overridable per request via `?stream_mode=`.
+     * Defaults to `"values"` — each frame is the full state after a step, ending at the same value the
+     * JSON response would have returned.
+     */
+    streamMode?: StreamMode | StreamMode[];
+}
+/** The single handler name this surface binds — deliberately not a `keyof ProtocolHandlers`. */
+type GraphInvokeHandlerName = "invokeGraph";
+/**
+ * The route table for the invoke surface — one POST, shaped like {@link skeinRoutes} so catch-all
+ * adapters (NestJS, Next.js) can match it the same way and native routers can bind it directly.
+ * Parameterized with its own handler name, so nothing can mistake it for a protocol-table lookup key.
+ */
+declare function graphInvokeRoutes(prefix?: string): RouteBinding<GraphInvokeHandlerName>[];
 /**
- * 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.
+ * Build the handler for `POST <prefix>/:graph_id`. Returns a {@link ProtocolHandler}, so every
+ * adapter serializes it through the same JSON/SSE path the protocol routes already use.
  */
-declare function matchSkeinRoute(method: string, pathname: string): RouteMatch | undefined;
+declare function createGraphInvokeHandler(deps: ProtocolDeps, options?: GraphInvokeOptions): ProtocolHandler;
 
 type LangGraphSearchItem = Item$1 & {
     score?: number;
@@ -535,4 +602,4 @@ declare function toSseEvents(frames: AsyncIterable<RunFrame>, finalStatus: () =>
  */
 declare function parseAfterSeq(lastEventId: string | undefined): number;
 
-export { type AssistantService, type Clock, type CommandInput, type CompiledGraphFactory, type CreateAssistantInput, type CreateRunInput, type CreateThreadInput, type DeleteAssistantOptions, type DrawGraphOptions, type GraphResolver, type GraphSchemas, type HistoryOptions, type HttpMethod, type Logger, type PatchThreadInput, type ProtocolContext, type ProtocolDeps, type ProtocolHandler, type ProtocolHandlers, type ProtocolRequest, type ProtocolResponse, type ProtocolRuntime, type ProtocolRuntimeOptions, type ProtocolService, type ResolvedGraph, type RouteBinding, type RouteMatch, type RunService, type RunWorker, type RunWorkerOptions, SSE_HEADERS, SkeinBaseStore, type StartedStream, type StoreService, type SubgraphsOptions, type ThreadService, type ThreadStreamInput, type ThreadStreamService, buildProtocolService, copyThreadIdIntoBody, createContext, createProtocolHandlers, createProtocolRuntime, createProtocolService, createProtocolServiceFromContext, createRunWorker, encodeFrame, encodeTerminal, foldThreadId, matchSkeinRoute, parseAfterSeq, skeinRoutes, toSseEvents };
+export { type AssistantService, type Clock, type CommandInput, type CompiledGraphFactory, type CreateAssistantInput, type CreateRunInput, type CreateThreadInput, DEFAULT_INVOKE_PREFIX, type DeleteAssistantOptions, type DrawGraphOptions, type GraphInvokeHandlerName, type GraphInvokeOptions, 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 RouteMatcher, type RunService, type RunWorker, type RunWorkerOptions, SSE_HEADERS, SkeinBaseStore, type StartedStream, type StoreService, type SubgraphsOptions, type ThreadService, type ThreadStreamInput, type ThreadStreamService, buildProtocolService, copyThreadIdIntoBody, createContext, createGraphInvokeHandler, createProtocolHandlers, createProtocolRuntime, createProtocolService, createProtocolServiceFromContext, createRouteMatcher, createRunWorker, encodeFrame, encodeTerminal, foldThreadId, graphInvokeRoutes, matchSkeinRoute, parseAfterSeq, skeinRoutes, toSseEvents };

package/dist/index.js

@@ -64,6 +64,11 @@ var streamModeSchema = z.union([z.string(), z.array(z.string())]);
 var configSchema = z.record(z.unknown());
 var multitaskStrategySchema = z.enum(["reject", "interrupt", "rollback", "enqueue"]);
 var interruptWhenSchema = z.union([z.array(z.string()), z.literal("*")]);
+var checkpointSchema = z.object({
+  checkpoint_id: z.string().optional(),
+  checkpoint_ns: z.string().nullish(),
+  checkpoint_map: z.record(z.unknown()).nullish()
+});
 var runCreateSchema = z.object({
   assistant_id: z.string().min(1),
   thread_id: z.string().min(1).optional(),
@@ -77,7 +82,21 @@ var runCreateSchema = z.object({
   interrupt_before: 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()
+  webhook: z.string().url().optional(),
+  /** Time travel: fork this run from a prior checkpoint instead of the thread tip. */
+  checkpoint_id: z.string().optional(),
+  /** Time travel: full checkpoint pointer to fork from (its `checkpoint_id` is what matters). */
+  checkpoint: checkpointSchema.optional()
+}).passthrough();
+var threadStateUpdateSchema = z.object({
+  /** New state to write. `null` re-points `next` without changing values; an array is a bulk write. */
+  values: z.union([z.record(z.unknown()), z.array(z.record(z.unknown()))]).nullish(),
+  /** Attribute the update as though this node produced `values` (sets up which node runs next). */
+  as_node: z.string().optional(),
+  /** The checkpoint to fork from; omitted updates the thread tip. */
+  checkpoint_id: z.string().optional(),
+  /** Full checkpoint pointer to fork from (alternative to `checkpoint_id`). */
+  checkpoint: checkpointSchema.nullish()
 }).passthrough();
 var threadStreamSchema = z.object({
   assistant_id: z.string().min(1),
@@ -321,6 +340,23 @@ function createProtocolHandlers(service) {
       return json(await service.threads.history(requireParam(req.params, "thread_id"), options));
     },
     getThreadState: async (req) => json(await service.threads.getState(requireParam(req.params, "thread_id"))),
+    getThreadStateAtCheckpoint: async (req) => json(
+      await service.threads.getStateAt(
+        requireParam(req.params, "thread_id"),
+        requireParam(req.params, "checkpoint_id")
+      )
+    ),
+    updateThreadState: async (req) => {
+      const body = parse(threadStateUpdateSchema, req.body ?? {});
+      return json(
+        await service.threads.updateState(requireParam(req.params, "thread_id"), {
+          values: body.values,
+          as_node: body.as_node,
+          checkpoint_id: body.checkpoint_id,
+          checkpoint: body.checkpoint ?? void 0
+        })
+      );
+    },
     // --- runs ---------------------------------------------------------------------------------
     createWaitRun: async (req) => json(await service.runs.createWait(parse(runCreateSchema, req.body))),
     createStreamRun: async (req) => {
@@ -722,50 +758,6 @@ import {
   SkeinHttpError as SkeinHttpError4
 } from "@skein-js/core";
 
-// src/normalize-error.ts
-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 };
-  }
-  return { name: "Error", message: String(error) };
-}
-
-// src/sse/run-frame-stream.ts
-var STREAM_MODES = [
-  "values",
-  "updates",
-  "messages",
-  "messages-tuple",
-  "custom",
-  "events",
-  "debug"
-];
-function isStreamMode(value) {
-  return typeof value === "string" && STREAM_MODES.includes(value);
-}
-function chunkToFrameBody(chunk) {
-  if (Array.isArray(chunk) && chunk.length === 2 && isStreamMode(chunk[0])) {
-    return { event: chunk[0], data: chunk[1] };
-  }
-  return { event: "updates", data: 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 {
   BaseStore
@@ -842,6 +834,60 @@ var SkeinBaseStore = class extends BaseStore {
   }
 };
 
+// src/graphs/resolve-compiled-graph.ts
+async function resolveCompiledGraph(graphs, graphId, attachments) {
+  const resolved = await graphs.load(graphId);
+  const shared = typeof resolved === "function" ? await resolved({ configurable: attachments.configurable }) : resolved;
+  const graph = Object.create(shared);
+  graph.checkpointer = attachments.checkpointer;
+  graph.store = new SkeinBaseStore(attachments.store);
+  return graph;
+}
+
+// src/normalize-error.ts
+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 };
+  }
+  return { name: "Error", message: String(error) };
+}
+
+// src/sse/run-frame-stream.ts
+var STREAM_MODES = [
+  "values",
+  "updates",
+  "messages",
+  "messages-tuple",
+  "custom",
+  "events",
+  "debug"
+];
+function isStreamMode(value) {
+  return typeof value === "string" && STREAM_MODES.includes(value);
+}
+function chunkToFrameBody(chunk) {
+  if (Array.isArray(chunk) && chunk.length === 2 && isStreamMode(chunk[0])) {
+    return { event: chunk[0], data: chunk[1] };
+  }
+  return { event: "updates", data: 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/runs/run-status.ts
 import { isTerminalRunStatus } from "@skein-js/core";
 function threadStatusForRun(status) {
@@ -990,10 +1036,15 @@ function toFactoryConfigurable(kwargs) {
 }
 function toGraphCallOptions(kwargs, threadId, signal) {
   const options = {
-    // 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`.
+    // Drop server-owned keys from the client's configurable, force this thread's id, add the
+    // server-owned time-travel fork target (if any) *after* sanitizing so the client can never spoof
+    // it, then stamp the authenticated caller so the graph can authorize off `langgraph_auth_user`.
     configurable: withAuthUser(
-      { ...sanitizeConfigurable(kwargs.config?.configurable), thread_id: threadId },
+      {
+        ...sanitizeConfigurable(kwargs.config?.configurable),
+        thread_id: threadId,
+        ...kwargs.checkpoint_id !== void 0 ? { checkpoint_id: kwargs.checkpoint_id } : {}
+      },
       kwargs.auth_user,
       kwargs.auth_scopes
     ),
@@ -1084,16 +1135,11 @@ function abortedStatus(reason) {
   return "cancelled";
 }
 async function resolveGraph(deps, graphId, kwargs) {
-  const resolved = await deps.graphs.load(graphId);
-  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;
+  return resolveCompiledGraph(deps.graphs, graphId, {
+    configurable: toFactoryConfigurable(kwargs),
+    checkpointer: deps.checkpointer,
+    store: deps.store.store
+  });
 }
 async function finalizeRun(deps, runId, status) {
   const fresh = await deps.store.runs.get(runId);
@@ -1334,6 +1380,7 @@ function toKwargs(input, authUser, authScopes) {
   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 (input.checkpoint_id !== void 0) kwargs.checkpoint_id = input.checkpoint_id;
   if (authUser !== void 0) {
     kwargs.auth_user = authUser;
     if (authScopes !== void 0) kwargs.auth_scopes = authScopes;
@@ -1554,13 +1601,13 @@ function createThreadService(ctx) {
     if (!thread) throw SkeinHttpError7.notFound(`Thread "${threadId}" not found.`);
     return thread;
   };
-  const readHistory = async (threadId, options) => {
+  const loadThreadGraph = async (threadId) => {
     await requireThread(threadId);
     const runs = await deps.store.runs.listByThread(threadId);
     const latest = [...runs].sort((a, b) => b.created_at.localeCompare(a.created_at))[0];
-    if (!latest) return [];
+    if (!latest) return void 0;
     const assistant = await deps.store.assistants.get(latest.assistant_id);
-    if (!assistant) return [];
+    if (!assistant) return void 0;
     const resolved = await deps.graphs.load(assistant.graph_id);
     let graph;
     if (typeof resolved === "function") {
@@ -1570,6 +1617,11 @@ function createThreadService(ctx) {
       graph = resolved;
     }
     graph.checkpointer = deps.checkpointer;
+    return graph;
+  };
+  const readHistory = async (threadId, options) => {
+    const graph = await loadThreadGraph(threadId);
+    if (!graph) return [];
     const states = [];
     const limit = options?.limit;
     for await (const snapshot of graph.getStateHistory({
@@ -1626,6 +1678,45 @@ function createThreadService(ctx) {
     async getState(threadId) {
       const [current] = await readHistory(threadId, { limit: 1 });
       return current ?? emptyThreadState(threadId);
+    },
+    async getStateAt(threadId, checkpointId) {
+      const graph = await loadThreadGraph(threadId);
+      if (!graph) return emptyThreadState(threadId);
+      const snapshot = await graph.getState({
+        configurable: { thread_id: threadId, checkpoint_ns: "", checkpoint_id: checkpointId }
+      });
+      return snapshotToThreadState(snapshot);
+    },
+    async updateState(threadId, input) {
+      const graph = await loadThreadGraph(threadId);
+      if (!graph) {
+        throw SkeinHttpError7.unprocessable(`Thread "${threadId}" has no graph to update state on.`);
+      }
+      if (await deps.store.runs.hasActiveRun(threadId)) {
+        throw SkeinHttpError7.conflict(
+          `Thread "${threadId}" is busy; wait for its active run to finish before updating state.`
+        );
+      }
+      const configurable = {
+        checkpoint_ns: "",
+        ...input.checkpoint ?? {},
+        ...input.checkpoint_id !== void 0 ? { checkpoint_id: input.checkpoint_id } : {},
+        thread_id: threadId
+      };
+      const nextConfig = await graph.updateState({ configurable }, input.values, input.as_node);
+      const snapshot = await graph.getState({ configurable: { thread_id: threadId } });
+      await deps.store.threads.update(
+        threadId,
+        snapshotToThreadUpdate(snapshot, runStatusForSnapshot(snapshot))
+      );
+      const next = nextConfig.configurable ?? {};
+      const checkpoint = {
+        thread_id: threadId,
+        checkpoint_ns: next["checkpoint_ns"] ?? "",
+        checkpoint_id: next["checkpoint_id"],
+        checkpoint_map: next["checkpoint_map"]
+      };
+      return { checkpoint };
     }
   };
 }
@@ -1828,9 +1919,12 @@ var ROUTE_AUTHZ = {
   copyThread: { resource: "threads", action: "create" },
   getThread: { resource: "threads", action: "read" },
   getThreadState: { resource: "threads", action: "read" },
+  getThreadStateAtCheckpoint: { resource: "threads", action: "read" },
   getThreadHistory: { resource: "threads", action: "read" },
   listThreads: { resource: "threads", action: "search" },
   patchThread: { resource: "threads", action: "update" },
+  // Time-travel state update forks a checkpoint — a write, so read-only principals can't fork.
+  updateThreadState: { resource: "threads", action: "update" },
   deleteThread: { resource: "threads", action: "delete" },
   // runs (authorized through the owning thread)
   createWaitRun: { resource: "threads", action: "create_run" },
@@ -1871,27 +1965,29 @@ function synthesizeRequest(req) {
   });
 }
 
-// src/auth/authorizing-handlers.ts
+// src/auth/authenticate-request.ts
 var STUDIO_USER = {
   identity: "langgraph-studio-user",
   display_name: "langgraph-studio-user",
   is_authenticated: true,
   permissions: []
 };
+async function resolveAuthContext(engine, req) {
+  if (!engine.studioAuthDisabled && req.headers["x-auth-scheme"] === "langsmith") {
+    return { user: STUDIO_USER, scopes: [] };
+  }
+  return engine.authenticate(synthesizeRequest(req));
+}
+
+// src/auth/authorizing-handlers.ts
 function createAuthorizingHandlers(context, engine) {
   const baseHandlers = createProtocolHandlers(createProtocolServiceFromContext(context));
   const names = Object.keys(ROUTE_AUTHZ);
-  const resolveAuthContext = async (req) => {
-    if (!engine.studioAuthDisabled && req.headers["x-auth-scheme"] === "langsmith") {
-      return { user: STUDIO_USER, scopes: [] };
-    }
-    return engine.authenticate(synthesizeRequest(req));
-  };
   const wrapped = {};
   for (const name of names) {
     const route = ROUTE_AUTHZ[name];
     wrapped[name] = async (req) => {
-      const authContext = await resolveAuthContext(req);
+      const authContext = await resolveAuthContext(engine, req);
       const { filters } = await engine.authorize({
         resource: route.resource,
         action: route.action,
@@ -2018,6 +2114,12 @@ var skeinRoutes = [
   { 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/state", handler: "updateThreadState" },
+  {
+    method: "get",
+    path: "/threads/:thread_id/state/:checkpoint_id",
+    handler: "getThreadStateAtCheckpoint"
+  },
   { 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" },
@@ -2059,19 +2161,22 @@ function copyThreadIdIntoBody(request) {
   return { ...request, body: { ...base, thread_id: threadId } };
 }
 var foldThreadId = copyThreadIdIntoBody;
-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 createRouteMatcher(bindings) {
+  const compiled = bindings.map((binding) => ({
+    binding,
+    regex: new RegExp(`^${binding.path.replace(/:(\w+)/g, "(?<$1>[^/]+)")}$`)
+  }));
+  return (method, pathname) => {
+    const wanted = method.toLowerCase();
+    for (const { binding, regex } of compiled) {
+      if (binding.method !== wanted) continue;
+      const match = regex.exec(pathname);
+      if (match) return { binding, params: decodeParams(match.groups) };
+    }
+    return void 0;
+  };
 }
+var matchSkeinRoute = createRouteMatcher(skeinRoutes);
 function decodeParams(groups) {
   const params = {};
   for (const [key, value] of Object.entries(groups ?? {})) {
@@ -2083,20 +2188,149 @@ function decodeParams(groups) {
   }
   return params;
 }
+
+// src/invoke/graph-invoke.ts
+import { randomUUID } from "crypto";
+import { MemorySaver } from "@langchain/langgraph";
+import {
+  SkeinHttpError as SkeinHttpError10
+} from "@skein-js/core";
+import { z as z2 } from "zod";
+var DEFAULT_INVOKE_PREFIX = "/invoke";
+function graphInvokeRoutes(prefix = DEFAULT_INVOKE_PREFIX) {
+  return [{ method: "post", path: `${normalizePrefix(prefix)}/:graph_id`, handler: "invokeGraph" }];
+}
+function normalizePrefix(prefix) {
+  const trimmed = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  return trimmed === "/" ? "" : trimmed;
+}
+function wantsEventStream(req) {
+  return req.headers["accept"]?.includes("text/event-stream") ?? false;
+}
+function createRunSignal(timeoutMs, callerSignal) {
+  if (timeoutMs === void 0 && !callerSignal) return { signal: void 0, dispose: () => {
+  } };
+  const controller = new AbortController();
+  const timer = timeoutMs === void 0 ? void 0 : setTimeout(() => controller.abort(new Error(`Run exceeded ${timeoutMs}ms`)), timeoutMs);
+  const onCallerAbort = () => controller.abort(callerSignal?.reason);
+  if (callerSignal?.aborted) onCallerAbort();
+  else callerSignal?.addEventListener("abort", onCallerAbort);
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      if (timer !== void 0) clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+  };
+}
+var INVOKE_STREAM_MODES = [
+  "values",
+  "updates",
+  "messages",
+  "messages-tuple",
+  "custom",
+  "debug"
+];
+var streamModeQuerySchema = z2.array(z2.enum(INVOKE_STREAM_MODES)).min(1, "expected at least one stream mode");
+function streamModeFromQuery(value) {
+  const raw = Array.isArray(value) ? value : value === void 0 ? [] : value.split(",");
+  const modes = raw.map((mode) => mode.trim()).filter((mode) => mode.length > 0);
+  if (modes.length === 0) return void 0;
+  if (modes.includes("events")) {
+    throw SkeinHttpError10.badRequest(
+      'Stream mode "events" is not supported on the invoke surface; use the Agent Protocol run endpoints for token-level events.'
+    );
+  }
+  return parse(streamModeQuerySchema, modes, "stream_mode query parameter");
+}
+function createGraphInvokeHandler(deps, options = {}) {
+  return async (req) => {
+    const graphId = requireParam(req.params, "graph_id");
+    let authContext;
+    if (deps.auth) {
+      authContext = await resolveAuthContext(deps.auth, req);
+      await deps.auth.authorize({
+        resource: "threads",
+        action: "create_run",
+        // `authValue` spreads the body last, and on this surface the body is arbitrary caller-supplied
+        // graph input — so a body key named `graph_id` would shadow the path param and let a policy
+        // authorize a different graph than the one that actually runs. Re-stamp the server-derived id
+        // last so the value a policy judges is always the graph we execute.
+        value: { ...authValue(req), graph_id: graphId },
+        context: authContext
+      });
+    }
+    if (!deps.graphs.ids.includes(graphId)) {
+      throw SkeinHttpError10.notFound(`Graph "${graphId}" is not registered.`, {
+        code: "graph_not_found"
+      });
+    }
+    const factoryConfigurable2 = withAuthUser({}, authContext?.user, authContext?.scopes);
+    const graph = await resolveCompiledGraph(deps.graphs, graphId, {
+      configurable: Object.keys(factoryConfigurable2).length > 0 ? factoryConfigurable2 : void 0,
+      checkpointer: new MemorySaver(),
+      store: deps.store.store
+    });
+    const configurable = withAuthUser(
+      { thread_id: randomUUID() },
+      authContext?.user,
+      authContext?.scopes
+    );
+    const input = req.body ?? {};
+    const { signal, dispose } = createRunSignal(deps.runTimeoutMs, req.signal);
+    if (!wantsEventStream(req)) {
+      try {
+        const output = await graph.invoke(input, { configurable, signal });
+        return { kind: "json", status: 200, body: output };
+      } finally {
+        dispose();
+      }
+    }
+    const streamMode = toGraphStreamModes(
+      streamModeFromQuery(req.query["stream_mode"]) ?? options.streamMode ?? "values"
+    );
+    let status = "success";
+    const frames = async function* () {
+      let seq = 0;
+      try {
+        const stream = await graph.stream(input, {
+          configurable,
+          streamMode,
+          signal
+        });
+        for await (const chunk of stream) {
+          seq += 1;
+          yield toRunFrame(seq, chunkToFrameBody(chunk));
+        }
+      } catch (error) {
+        status = "error";
+        seq += 1;
+        yield { seq, event: "error", data: serializeError(error) };
+      } finally {
+        dispose();
+      }
+    };
+    return { kind: "sse", status: 200, events: toSseEvents(frames(), async () => status) };
+  };
+}
 export {
+  DEFAULT_INVOKE_PREFIX,
   SSE_HEADERS,
   SkeinBaseStore,
   buildProtocolService,
   copyThreadIdIntoBody,
   createContext,
+  createGraphInvokeHandler,
   createProtocolHandlers,
   createProtocolRuntime,
   createProtocolService,
   createProtocolServiceFromContext,
+  createRouteMatcher,
   createRunWorker,
   encodeFrame,
   encodeTerminal,
   foldThreadId,
+  graphInvokeRoutes,
   matchSkeinRoute,
   parseAfterSeq,
   skeinRoutes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/agent-protocol",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "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>",
@@ -44,14 +44,14 @@
   },
   "dependencies": {
     "zod": "^3.25.76",
-    "@skein-js/core": "0.7.0"
+    "@skein-js/core": "0.9.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0",
     "@langchain/langgraph-sdk": "^1.9.0"
   },
   "devDependencies": {
-    "@skein-js/storage-memory": "0.7.0"
+    "@skein-js/storage-memory": "0.9.0"
   },
   "publishConfig": {
     "access": "public"