@skein-js/agent-protocol 0.6.3 → 0.8.0

package/README.md

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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { GraphSchema, SkeinStore, RunQueue, RunEventBus, AuthEngine, 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 {
@@ -331,10 +353,16 @@ interface ProtocolService {
     store: StoreService;
 }
 /** Assemble the service over an existing context (used by the runtime to share the context). */
-declare function buildProtocolService(ctx: ProtocolContext): ProtocolService;
+declare function createProtocolServiceFromContext(ctx: ProtocolContext): ProtocolService;
 /** Build the service with its own context. Use {@link createProtocolRuntime} when you also run a
  * background worker in the same process, so cancellation is shared. */
 declare function createProtocolService(deps: ProtocolDeps): ProtocolService;
+/**
+ * @deprecated Renamed to {@link createProtocolServiceFromContext} — it builds the service over an
+ * existing `ProtocolContext` (vs {@link createProtocolService}, which takes `deps` and makes its own).
+ * Kept for back-compat; slated for removal in a future major.
+ */
+declare const buildProtocolService: typeof createProtocolServiceFromContext;
 
 /** A normalized request an adapter maps its framework request onto. */
 interface ProtocolRequest {
@@ -381,6 +409,8 @@ interface ProtocolHandlers {
     deleteThread: ProtocolHandler;
     getThreadHistory: ProtocolHandler;
     getThreadState: ProtocolHandler;
+    getThreadStateAtCheckpoint: ProtocolHandler;
+    updateThreadState: ProtocolHandler;
     createWaitRun: ProtocolHandler;
     createStreamRun: ProtocolHandler;
     createBackgroundRun: ProtocolHandler;
@@ -414,12 +444,18 @@ interface RunWorker {
 }
 declare function createRunWorker(ctx: ProtocolContext, options?: RunWorkerOptions): RunWorker;
 
+/** Options for {@link createProtocolRuntime}. */
 interface ProtocolRuntimeOptions {
+    /** Tuning for the background run worker (concurrency, poll interval). */
     worker?: RunWorkerOptions;
 }
+/** The wired engine: the service, the transport-neutral handler table, and the background worker. */
 interface ProtocolRuntime {
+    /** High-level operations over assistants / threads / runs / store (used to seed assistants). */
     service: ProtocolService;
+    /** The transport-neutral HTTP handler table an adapter dispatches requests into. */
     handlers: ProtocolHandlers;
+    /** The background worker that drains the run queue; `start()` it after seeding assistants. */
     worker: RunWorker;
 }
 /**
@@ -448,9 +484,14 @@ 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.
+ * routes, so this rule lives in one place.
+ */
+declare function copyThreadIdIntoBody(request: ProtocolRequest): ProtocolRequest;
+/**
+ * @deprecated Renamed to {@link copyThreadIdIntoBody} — it copies the path `thread_id` into the
+ * request body. Kept for back-compat; slated for removal in a future major.
  */
-declare function foldThreadId(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;
@@ -518,4 +559,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, createContext, createProtocolHandlers, createProtocolRuntime, createProtocolService, createRunWorker, encodeFrame, encodeTerminal, foldThreadId, matchSkeinRoute, parseAfterSeq, skeinRoutes, toSseEvents };
+export { type AssistantService, type Clock, type CommandInput, type CompiledGraphFactory, type CreateAssistantInput, type CreateRunInput, type CreateThreadInput, type DeleteAssistantOptions, type DrawGraphOptions, type GraphResolver, type GraphSchemas, type HistoryOptions, type HttpMethod, type Logger, type PatchThreadInput, type ProtocolContext, type ProtocolDeps, type ProtocolHandler, type ProtocolHandlers, type ProtocolRequest, type ProtocolResponse, type ProtocolRuntime, type ProtocolRuntimeOptions, type ProtocolService, type ResolvedGraph, type RouteBinding, type RouteMatch, type RunService, type RunWorker, type RunWorkerOptions, SSE_HEADERS, SkeinBaseStore, type StartedStream, type StoreService, type SubgraphsOptions, type ThreadService, type ThreadStreamInput, type ThreadStreamService, buildProtocolService, copyThreadIdIntoBody, createContext, createProtocolHandlers, createProtocolRuntime, createProtocolService, createProtocolServiceFromContext, createRunWorker, encodeFrame, encodeTerminal, foldThreadId, matchSkeinRoute, parseAfterSeq, skeinRoutes, toSseEvents };

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) => {
@@ -990,10 +1026,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
     ),
@@ -1334,6 +1375,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 +1596,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 +1612,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 +1673,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 };
     }
   };
 }
@@ -1692,7 +1778,7 @@ function createThreadStreamService(ctx, runs) {
 }
 
 // src/service.ts
-function buildProtocolService(ctx) {
+function createProtocolServiceFromContext(ctx) {
   const runs = createRunService(ctx);
   const threads = createThreadService(ctx);
   return {
@@ -1707,8 +1793,9 @@ function buildProtocolService(ctx) {
   };
 }
 function createProtocolService(deps) {
-  return buildProtocolService(createContext(deps));
+  return createProtocolServiceFromContext(createContext(deps));
 }
+var buildProtocolService = createProtocolServiceFromContext;
 
 // src/auth/auth-scoped-store.ts
 import {
@@ -1827,9 +1914,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" },
@@ -1878,7 +1968,7 @@ var STUDIO_USER = {
   permissions: []
 };
 function createAuthorizingHandlers(context, engine) {
-  const baseHandlers = createProtocolHandlers(buildProtocolService(context));
+  const baseHandlers = createProtocolHandlers(createProtocolServiceFromContext(context));
   const names = Object.keys(ROUTE_AUTHZ);
   const resolveAuthContext = async (req) => {
     if (!engine.studioAuthDisabled && req.headers["x-auth-scheme"] === "langsmith") {
@@ -1907,7 +1997,7 @@ function createAuthorizingHandlers(context, engine) {
           store: createAuthScopedStore(context.deps.store, engine, filters, route.resource)
         } : context.deps
       };
-      return createProtocolHandlers(buildProtocolService(requestContext))[name](req);
+      return createProtocolHandlers(createProtocolServiceFromContext(requestContext))[name](req);
     };
   }
   return wrapped;
@@ -1977,7 +2067,7 @@ function createRunWorker(ctx, options = {}) {
 // src/runtime.ts
 function createProtocolRuntime(deps, options = {}) {
   const context = createContext(deps);
-  const service = buildProtocolService(context);
+  const service = createProtocolServiceFromContext(context);
   const handlers = deps.auth ? createAuthorizingHandlers(context, deps.auth) : createProtocolHandlers(service);
   return {
     service,
@@ -2017,6 +2107,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" },
@@ -2051,12 +2147,13 @@ var skeinRoutes = [
   { method: "post", path: "/store/items/search", handler: "searchStoreItems" },
   { method: "post", path: "/store/namespaces", handler: "listStoreNamespaces" }
 ];
-function foldThreadId(request) {
+function copyThreadIdIntoBody(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 foldThreadId = copyThreadIdIntoBody;
 var compiledRoutes = skeinRoutes.map((binding) => ({
   binding,
   regex: new RegExp(`^${binding.path.replace(/:(\w+)/g, "(?<$1>[^/]+)")}$`)
@@ -2085,10 +2182,12 @@ export {
   SSE_HEADERS,
   SkeinBaseStore,
   buildProtocolService,
+  copyThreadIdIntoBody,
   createContext,
   createProtocolHandlers,
   createProtocolRuntime,
   createProtocolService,
+  createProtocolServiceFromContext,
   createRunWorker,
   encodeFrame,
   encodeTerminal,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/agent-protocol",
-  "version": "0.6.3",
+  "version": "0.8.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.6.3"
+    "@skein-js/core": "0.8.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0",
     "@langchain/langgraph-sdk": "^1.9.0"
   },
   "devDependencies": {
-    "@skein-js/storage-memory": "0.6.3"
+    "@skein-js/storage-memory": "0.8.0"
   },
   "publishConfig": {
     "access": "public"