@skein-js/agent-protocol 0.2.1 → 0.4.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, 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. */
@@ -159,7 +159,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 +180,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 +266,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";
@@ -775,9 +804,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 +835,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: {} };
     }
@@ -840,19 +869,35 @@ function toKwargs(input) {
 function createRunService(ctx) {
   const { deps, control, locks } = 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 +929,36 @@ function createRunService(ctx) {
   };
   return {
     async createWait(input) {
-      const assistantId = await requireAssistant(input.assistant_id);
-      const threadId = await ensureThread(input.thread_id);
+      const assistant = await requireAssistant(input.assistant_id);
+      const thread = await ensureThread(input.thread_id);
       const kwargs = toKwargs(input);
-      const run = await createPendingRun(input, threadId, assistantId, kwargs);
+      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 assistant = await requireAssistant(input.assistant_id);
+      const thread = await ensureThread(input.thread_id);
       const kwargs = toKwargs(input);
-      const run = await createPendingRun(input, threadId, assistantId, kwargs);
+      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 assistant = await requireAssistant(input.assistant_id);
+      const thread = await requireThread(threadId);
       const kwargs = toKwargs(input);
       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 +976,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 +1008,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 +1030,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 +1127,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 +1275,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 +1304,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 +1355,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" },
@@ -1312,8 +1441,21 @@ function createAuthorizingHandlers(context, engine) {
 }
 
 // src/runs/run-worker.ts
-import { isTerminalRunStatus as isTerminalRunStatus6 } from "@skein-js/core";
+import {
+  isTerminalRunStatus as isTerminalRunStatus6
+} from "@skein-js/core";
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function logRunLifecycle(logger, run, status, startedAt, endedAt) {
+  logger.info(status === "success" ? "Background run succeeded" : `Background run ${status}`, {
+    run_id: run.run_id,
+    run_attempt: 1,
+    run_created_at: run.created_at,
+    run_started_at: new Date(startedAt).toISOString(),
+    run_ended_at: new Date(endedAt).toISOString(),
+    run_exec_ms: endedAt - startedAt,
+    run_queue_ms: startedAt - Date.parse(run.created_at)
+  });
+}
 function createRunWorker(ctx, options = {}) {
   const { deps, control } = ctx;
   const maxConcurrency = options.maxConcurrency ?? 1;
@@ -1325,9 +1467,12 @@ function createRunWorker(ctx, options = {}) {
     const kwargs = await deps.store.runs.getKwargs(queued.run_id) ?? {};
     const runControl = control.register(queued.run_id);
     inFlight.add(queued.run_id);
+    const startedAt = Date.now();
+    let status = "error";
     try {
-      await executeRun(deps, { run, kwargs, control: runControl });
+      status = (await executeRun(deps, { run, kwargs, control: runControl })).status;
     } finally {
+      logRunLifecycle(deps.logger, run, status, startedAt, Date.now());
       control.clear(queued.run_id);
       inFlight.delete(queued.run_id);
     }

package/package.json

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