@skein-js/agent-protocol 0.7.0 → 0.8.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 {
@@ -387,6 +409,8 @@ interface ProtocolHandlers {
     deleteThread: ProtocolHandler;
     getThreadHistory: ProtocolHandler;
     getThreadState: ProtocolHandler;
+    getThreadStateAtCheckpoint: ProtocolHandler;
+    updateThreadState: ProtocolHandler;
     createWaitRun: ProtocolHandler;
     createStreamRun: ProtocolHandler;
     createBackgroundRun: ProtocolHandler;

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 };
     }
   };
 }
@@ -1828,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" },
@@ -2018,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" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/agent-protocol",
-  "version": "0.7.0",
+  "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.7.0"
+    "@skein-js/core": "0.8.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.8.0"
   },
   "publishConfig": {
     "access": "public"