@skein-js/agent-protocol 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { GraphSchema, SkeinStore, RunQueue, RunEventBus, AuthEngine, Assistant, Config, StreamMode, Metadata, MultitaskStrategy, RunFrame, DefaultValues, Run, RunStatus, Item, StoreSearchQuery, SearchItem, Thread, ThreadState, StoreRepo } from '@skein-js/core';
+import { GraphSchema, SkeinStore, RunQueue, RunEventBus, AuthEngine, Assistant, AuthUser, Config, StreamMode, Metadata, MultitaskStrategy, RunFrame, DefaultValues, Run, RunStatus, StorePutOptions, Item, StoreSearchQuery, SearchItem, Thread, ThreadSearchQuery, ThreadState, StoreRepo } from '@skein-js/core';
 import { 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. */
@@ -119,6 +119,14 @@ interface ProtocolContext {
     deps: ResolvedDeps;
     control: RunControlRegistry;
     locks: ThreadLocks;
+    /**
+     * The authenticated caller for the current request, populated by the authorizing handler wrapper
+     * so the run service can stamp it onto a run's kwargs. Undefined when no auth engine is
+     * configured (the default), matching `langgraph dev` — no principal is injected into the graph.
+     */
+    authUser?: AuthUser;
+    /** The current request's authenticated permission scopes (`AuthContext.scopes`), stamped with {@link authUser}. */
+    authScopes?: string[];
 }
 declare function createContext(deps: ProtocolDeps): ProtocolContext;
 
@@ -159,7 +167,7 @@ interface RunService {
 }
 
 interface StoreService {
-    put(namespace: string[], key: string, value: Record<string, unknown>): Promise<Item>;
+    put(namespace: string[], key: string, value: Record<string, unknown>, options?: StorePutOptions): Promise<Item>;
     get(namespace: string[], key: string): Promise<Item>;
     delete(namespace: string[], key: string): Promise<void>;
     search(query: StoreSearchQuery): Promise<SearchItem[]>;
@@ -180,7 +188,11 @@ interface ThreadService {
     create(input?: CreateThreadInput): Promise<Thread>;
     get(threadId: string): Promise<Thread>;
     list(): Promise<Thread[]>;
+    /** Filtered + paginated listing — `POST /threads/search`. */
+    search(query: ThreadSearchQuery): Promise<Thread[]>;
     patch(threadId: string, patch: PatchThreadInput): Promise<Thread>;
+    /** Duplicate a thread (new id) together with its full checkpoint history — `POST /threads/{id}/copy`. */
+    copy(threadId: string): Promise<Thread>;
     delete(threadId: string): Promise<void>;
     history(threadId: string, options?: HistoryOptions): Promise<ThreadState[]>;
     /** The thread's current state snapshot — `GET /threads/{id}/state`, what `useStream` hydrates from. */
@@ -262,6 +274,7 @@ interface ProtocolHandlers {
     createThread: ProtocolHandler;
     getThread: ProtocolHandler;
     listThreads: ProtocolHandler;
+    copyThread: ProtocolHandler;
     patchThread: ProtocolHandler;
     deleteThread: ProtocolHandler;
     getThreadHistory: ProtocolHandler;

package/dist/index.js

@@ -101,6 +101,16 @@ var threadCreateSchema = z.object({
 var threadPatchSchema = z.object({
   metadata: z.record(z.unknown()).optional()
 }).passthrough();
+var threadSearchSchema = z.object({
+  metadata: z.record(z.unknown()).optional(),
+  values: z.record(z.unknown()).optional(),
+  status: z.enum(["idle", "busy", "interrupted", "error"]).optional(),
+  ids: z.array(z.string()).optional(),
+  limit: z.number().int().positive().optional(),
+  offset: z.number().int().nonnegative().optional(),
+  sort_by: z.enum(["thread_id", "status", "created_at", "updated_at"]).optional(),
+  sort_order: z.enum(["asc", "desc"]).optional()
+}).passthrough();
 var assistantSearchSchema = z.object({
   graph_id: z.string().optional(),
   limit: z.number().int().positive().optional(),
@@ -109,7 +119,9 @@ var assistantSearchSchema = z.object({
 var storePutSchema = z.object({
   namespace: z.array(z.string()).min(1),
   key: z.string().min(1),
-  value: z.record(z.unknown())
+  value: z.record(z.unknown()),
+  /** Optional item lifetime in minutes; overrides the configured `store.ttl.default_ttl`. */
+  ttl: z.number().positive().optional()
 }).passthrough();
 var storeSearchSchema = z.object({
   namespace_prefix: z.array(z.string()).optional(),
@@ -153,7 +165,22 @@ function createProtocolHandlers(service) {
     // --- 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"))),
-    listThreads: async () => json(await service.threads.list()),
+    listThreads: async (req) => {
+      const body = parse(threadSearchSchema, req.body ?? {});
+      return json(
+        await service.threads.search({
+          metadata: body.metadata,
+          values: body.values,
+          status: body.status,
+          ids: body.ids,
+          limit: body.limit,
+          offset: body.offset,
+          sortBy: body.sort_by,
+          sortOrder: body.sort_order
+        })
+      );
+    },
+    copyThread: async (req) => json(await service.threads.copy(requireParam(req.params, "thread_id"))),
     patchThread: async (req) => json(
       await service.threads.patch(
         requireParam(req.params, "thread_id"),
@@ -221,7 +248,7 @@ function createProtocolHandlers(service) {
     // --- store --------------------------------------------------------------------------------
     putStoreItem: async (req) => {
       const body = parse(storePutSchema, req.body);
-      return json(await service.store.put(body.namespace, body.key, body.value));
+      return json(await service.store.put(body.namespace, body.key, body.value, { ttl: body.ttl }));
     },
     getStoreItem: async (req) => {
       const namespace = namespaceFromQuery(req.query["namespace"]);
@@ -496,9 +523,11 @@ function threadStatusForRun(status) {
     case "error":
     case "timeout":
       return "error";
-    // pending (not yet started) and success both leave the thread idle.
+    // pending (not yet started), success, and cancelled all leave the thread idle. A cancellation
+    // is a clean stop, not a failure, so the thread returns to idle rather than error.
     case "pending":
     case "success":
+    case "cancelled":
       return "idle";
     default:
       return "idle";
@@ -593,7 +622,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 {};
@@ -604,10 +636,32 @@ 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 },
+    // 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: normalizeModes(kwargs.stream_mode),
     signal
   };
@@ -688,7 +742,12 @@ function describeInterrupts(snapshot) {
 // src/runs/run-engine.ts
 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;
@@ -775,9 +834,9 @@ async function executeRun(deps, exec) {
     }
     if (control.signal.aborted) {
       const timedOut = control.reason.current === "timeout";
-      const finalStatus2 = await finalizeRun(deps, runId, timedOut ? "timeout" : "error");
+      const finalStatus2 = await finalizeRun(deps, runId, timedOut ? "timeout" : "cancelled");
       if (finalStatus2 === "timeout") await mirrorThreadError(deps, threadId, "Run timed out.");
-      else if (finalStatus2 === "error") await mirrorThreadStatus(deps, threadId, "idle");
+      else if (finalStatus2 === "cancelled") await mirrorThreadStatus(deps, threadId, "idle");
       logFinished(finalStatus2);
       return { status: finalStatus2, values: {} };
     }
@@ -806,8 +865,8 @@ async function executeRun(deps, exec) {
       return { status: finalStatus2, values: {} };
     }
     if (reason === "cancel" || control.signal.aborted) {
-      const finalStatus2 = await finalizeRun(deps, runId, "error");
-      if (finalStatus2 === "error") await mirrorThreadStatus(deps, threadId, "idle");
+      const finalStatus2 = await finalizeRun(deps, runId, "cancelled");
+      if (finalStatus2 === "cancelled") await mirrorThreadStatus(deps, threadId, "idle");
       logFinished(finalStatus2);
       return { status: finalStatus2, values: {} };
     }
@@ -826,7 +885,7 @@ async function executeRun(deps, exec) {
 }
 
 // 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;
@@ -835,24 +894,44 @@ 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 (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, authUser, authScopes } = ctx;
   const requireThread = async (threadId) => {
-    if (!await deps.store.threads.get(threadId)) {
-      throw SkeinHttpError5.notFound(`Thread "${threadId}" not found.`);
-    }
+    const thread = await deps.store.threads.get(threadId);
+    if (!thread) throw SkeinHttpError5.notFound(`Thread "${threadId}" not found.`);
+    return thread;
   };
   const requireAssistant = async (assistantId) => {
     const assistant = await deps.store.assistants.get(assistantId);
     if (!assistant) throw SkeinHttpError5.notFound(`Assistant "${assistantId}" not found.`);
-    return assistant.assistant_id;
+    return assistant;
+  };
+  const stampGraphOnThread = async (thread, assistant) => {
+    if (thread.metadata?.["graph_id"] === assistant.graph_id && thread.metadata?.["assistant_id"] === assistant.assistant_id) {
+      return;
+    }
+    try {
+      await deps.store.threads.update(thread.thread_id, {
+        metadata: {
+          ...thread.metadata,
+          graph_id: assistant.graph_id,
+          assistant_id: assistant.assistant_id
+        }
+      });
+    } catch (error) {
+      deps.logger.warn("failed to stamp graph_id/assistant_id onto thread", error);
+    }
   };
   const ensureThread = async (threadId) => {
-    if (threadId === void 0) return (await deps.store.threads.create()).thread_id;
+    if (threadId === void 0) return deps.store.threads.create();
     const existing = await deps.store.threads.get(threadId);
-    return (existing ?? await deps.store.threads.create({ thread_id: threadId })).thread_id;
+    return existing ?? await deps.store.threads.create({ thread_id: threadId });
   };
   const createPendingRun = async (input, threadId, assistantId, kwargs) => {
     return locks.run(threadId, async () => {
@@ -884,33 +963,36 @@ function createRunService(ctx) {
   };
   return {
     async createWait(input) {
-      const assistantId = await requireAssistant(input.assistant_id);
-      const threadId = await ensureThread(input.thread_id);
-      const kwargs = toKwargs(input);
-      const run = await createPendingRun(input, threadId, assistantId, kwargs);
+      const assistant = await requireAssistant(input.assistant_id);
+      const thread = await ensureThread(input.thread_id);
+      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);
       return outcome.values;
     },
     async createStream(input) {
-      const assistantId = await requireAssistant(input.assistant_id);
-      const threadId = await ensureThread(input.thread_id);
-      const kwargs = toKwargs(input);
-      const run = await createPendingRun(input, threadId, assistantId, kwargs);
+      const assistant = await requireAssistant(input.assistant_id);
+      const thread = await ensureThread(input.thread_id);
+      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(
         (error) => deps.logger.error("stream run failed", error)
       );
       return { runId: run.run_id, frames: deps.bus.subscribe(run.run_id, 0) };
     },
     async createBackground(threadId, input) {
-      const assistantId = await requireAssistant(input.assistant_id);
-      await requireThread(threadId);
-      const kwargs = toKwargs(input);
+      const assistant = await requireAssistant(input.assistant_id);
+      const thread = await requireThread(threadId);
+      const kwargs = toKwargs(input, authUser, authScopes);
       const run = await createPendingRun(
         { ...input, thread_id: threadId },
         threadId,
-        assistantId,
+        assistant.assistant_id,
         kwargs
       );
+      await stampGraphOnThread(thread, assistant);
       await deps.queue.enqueue({ run_id: run.run_id, thread_id: threadId });
       return run;
     },
@@ -928,12 +1010,12 @@ function createRunService(ctx) {
       if (!run) throw SkeinHttpError5.notFound(`Run "${runId}" not found.`);
       if (isTerminalRunStatus3(run.status)) return run;
       if (run.status === "pending") {
-        await deps.store.runs.setStatus(runId, "error");
+        await deps.store.runs.setStatus(runId, "cancelled");
         await deps.store.threads.update(run.thread_id, { status: "idle" });
         await deps.bus.close(runId);
         control.abort(runId, "cancel");
       } else {
-        await deps.store.runs.setStatus(runId, "error");
+        await deps.store.runs.setStatus(runId, "cancelled");
         await deps.store.threads.update(run.thread_id, { status: "idle" });
         control.abort(runId, "cancel");
       }
@@ -960,10 +1042,12 @@ function createRunService(ctx) {
 }
 
 // src/store/store-service.ts
-import { SkeinHttpError as SkeinHttpError6 } from "@skein-js/core";
+import {
+  SkeinHttpError as SkeinHttpError6
+} from "@skein-js/core";
 function createStoreService(deps) {
   return {
-    put: (namespace, key, value) => deps.store.store.put(namespace, key, value),
+    put: (namespace, key, value, options) => deps.store.store.put(namespace, key, value, options),
     async get(namespace, key) {
       const item = await deps.store.store.get(namespace, key);
       if (!item) {
@@ -980,10 +1064,50 @@ 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: {},
@@ -1037,10 +1161,33 @@ function createThreadService(ctx) {
     create: (input) => deps.store.threads.create(input),
     get: requireThread,
     list: () => deps.store.threads.list(),
+    search: (query) => deps.store.threads.search(query),
     async patch(threadId, patch) {
       await requireThread(threadId);
       return deps.store.threads.update(threadId, { metadata: patch.metadata });
     },
+    async copy(threadId) {
+      await requireThread(threadId);
+      const copy = await deps.store.threads.copy(threadId);
+      await copyCheckpointHistory(deps.checkpointer, threadId, copy.thread_id);
+      const sourceRuns = await deps.store.runs.listByThread(threadId);
+      for (const run of [...sourceRuns].sort((a, b) => a.created_at.localeCompare(b.created_at))) {
+        if (!isTerminalRunStatus4(run.status)) continue;
+        const kwargs = await deps.store.runs.getKwargs(run.run_id);
+        await deps.store.runs.create({
+          thread_id: copy.thread_id,
+          assistant_id: run.assistant_id,
+          status: run.status,
+          metadata: run.metadata,
+          multitask_strategy: run.multitask_strategy,
+          ...kwargs ? { kwargs } : {}
+        });
+      }
+      if (copy.status === "busy") {
+        return deps.store.threads.update(copy.thread_id, { status: "idle" });
+      }
+      return copy;
+    },
     async delete(threadId) {
       await requireThread(threadId);
       const runs = await deps.store.runs.listByThread(threadId);
@@ -1162,6 +1309,14 @@ function createAuthScopedStore(inner, engine, filters, resource) {
   if (resource === "threads") {
     const threads = {
       list: async () => (await inner.threads.list()).filter((thread) => matches(thread.metadata)),
+      search: async (query) => {
+        const { limit, offset, ...filters2 } = query;
+        const owned = (await inner.threads.search(filters2)).filter(
+          (thread) => matches(thread.metadata)
+        );
+        const start = offset ?? 0;
+        return owned.slice(start, limit === void 0 ? void 0 : start + limit);
+      },
       get: async (threadId) => {
         const thread = await inner.threads.get(threadId);
         return thread && matches(thread.metadata) ? thread : null;
@@ -1183,6 +1338,13 @@ function createAuthScopedStore(inner, engine, filters, resource) {
         const next = patch.metadata !== void 0 ? { ...patch, metadata: stamp(patch.metadata) } : patch;
         return inner.threads.update(threadId, next);
       },
+      copy: async (threadId) => {
+        const thread = await inner.threads.get(threadId);
+        if (!thread || !matches(thread.metadata)) {
+          throw SkeinHttpError9.notFound(`Thread "${threadId}" not found.`);
+        }
+        return inner.threads.copy(threadId);
+      },
       delete: async (threadId) => {
         const thread = await inner.threads.get(threadId);
         if (!thread || !matches(thread.metadata)) {
@@ -1227,6 +1389,7 @@ var ROUTE_AUTHZ = {
   searchAssistants: { resource: "assistants", action: "search" },
   // threads
   createThread: { resource: "threads", action: "create" },
+  copyThread: { resource: "threads", action: "create" },
   getThread: { resource: "threads", action: "read" },
   getThreadState: { resource: "threads", action: "read" },
   getThreadHistory: { resource: "threads", action: "read" },
@@ -1281,7 +1444,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: [] };
@@ -1299,13 +1462,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;

package/package.json

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