@skein-js/agent-protocol 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -374,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 = {
@@ -466,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
@@ -493,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;
@@ -559,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

@@ -758,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
@@ -878,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) {
@@ -1125,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);
@@ -1960,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,
@@ -2154,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 ?? {})) {
@@ -2178,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.8.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.8.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.8.0"
+    "@skein-js/storage-memory": "0.9.0"
   },
   "publishConfig": {
     "access": "public"