@lostgradient/weft 0.2.0

package/dist/mcp/session.js

@@ -0,0 +1,204 @@
+import { WeftError } from "../core/weft-error.js";
+import { requestIdKey } from "./protocol.js";
+import { isWorkflowSearchResourceUri, workflowResourceUri } from "./resources.js";
+
+export class McpSessionLimitExceededError extends WeftError {
+  constructor() {
+    super("McpSessionLimitExceededError", "Too many MCP sessions");
+  }
+}
+const RESOURCE_EVENT_NAMES = [
+  "workflow:started",
+  "workflow:completed",
+  "workflow:failed",
+  "workflow:cancelled",
+  "workflow:timed-out",
+  "workflow:resumed",
+  "signal:received",
+  "signal:delivered",
+  "attributes:changed",
+  "update:received",
+  "update:completed"
+];
+
+export class McpSession {
+  id;
+  principal;
+  phase = "new";
+  protocolVersion = "2025-11-25";
+  subscriptions = new Set;
+  createdAtMilliseconds;
+  lastActivityMilliseconds;
+  #pendingRequests = new Map;
+  #cancelledRequestKeys = new Set;
+  #targets = new Set;
+  constructor(id, principal, currentTimeMilliseconds = Date.now()) {
+    this.id = id;
+    this.principal = principal;
+    this.createdAtMilliseconds = currentTimeMilliseconds;
+    this.lastActivityMilliseconds = currentTimeMilliseconds;
+  }
+  touch(currentTimeMilliseconds = Date.now()) {
+    this.lastActivityMilliseconds = currentTimeMilliseconds;
+  }
+  isIdleExpired(currentTimeMilliseconds, timeoutMilliseconds) {
+    return currentTimeMilliseconds - this.lastActivityMilliseconds > timeoutMilliseconds;
+  }
+  trackRequest(requestId, workflowId) {
+    const key = requestIdKey(asJsonRpcId(requestId));
+    if (key === void 0)
+      return;
+    this.#pendingRequests.set(key, { workflowId });
+  }
+  cancelRequest(requestId) {
+    const key = requestIdKey(asJsonRpcId(requestId));
+    if (key === void 0)
+      return;
+    const request = this.#pendingRequests.get(key);
+    if (request === void 0)
+      return;
+    this.#cancelledRequestKeys.add(key);
+    return request.workflowId;
+  }
+  isRequestCancelled(requestId) {
+    const key = requestIdKey(asJsonRpcId(requestId));
+    return key !== void 0 && this.#cancelledRequestKeys.has(key);
+  }
+  untrackRequest(requestId) {
+    const key = requestIdKey(asJsonRpcId(requestId));
+    if (key === void 0)
+      return;
+    this.#pendingRequests.delete(key);
+    this.#cancelledRequestKeys.delete(key);
+  }
+  workflowForRequest(requestId) {
+    const key = requestIdKey(asJsonRpcId(requestId));
+    if (key === void 0)
+      return;
+    return this.#pendingRequests.get(key)?.workflowId;
+  }
+  addTarget(target) {
+    this.#targets.add(target);
+    return () => {
+      this.#targets.delete(target);
+    };
+  }
+  notify(method, params) {
+    const message = params === void 0 ? { jsonrpc: "2.0", method } : { jsonrpc: "2.0", method, params };
+    for (const target of this.#targets)
+      target(message);
+  }
+  close() {
+    this.#pendingRequests.clear();
+    this.#cancelledRequestKeys.clear();
+    this.subscriptions.clear();
+    this.#targets.clear();
+  }
+}
+function asJsonRpcId(value) {
+  if (value === void 0)
+    return;
+  if (value === null || typeof value === "string")
+    return value;
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  return;
+}
+
+export class McpSessionManager {
+  #engine;
+  #sessions = new Map;
+  #listener;
+  #maximumSessions;
+  #sessionIdleTimeoutMilliseconds;
+  #currentTimeMilliseconds;
+  constructor(engine, options = {}) {
+    this.#engine = engine;
+    this.#maximumSessions = options.maximumSessions ?? 1024;
+    this.#sessionIdleTimeoutMilliseconds = options.sessionIdleTimeoutMilliseconds ?? 1800000;
+    this.#currentTimeMilliseconds = options.currentTimeMilliseconds ?? Date.now;
+    this.#listener = (event) => {
+      const workflowId = event.workflowId;
+      if (typeof workflowId !== "string")
+        return;
+      this.#notifyWorkflowResourceUpdated(workflowId);
+    };
+    for (const eventName of RESOURCE_EVENT_NAMES)
+      this.#engine.addEventListener(eventName, this.#listener);
+  }
+  create(principal) {
+    this.#deleteExpiredSessions();
+    if (this.#sessions.size >= this.#maximumSessions)
+      throw new McpSessionLimitExceededError;
+    const now = this.#currentTimeMilliseconds(), session = new McpSession(crypto.randomUUID(), principal, now);
+    this.#sessions.set(session.id, session);
+    return session;
+  }
+  add(session) {
+    this.#deleteExpiredSessions();
+    if (this.#sessions.size >= this.#maximumSessions)
+      throw new McpSessionLimitExceededError;
+    session.touch(this.#currentTimeMilliseconds());
+    this.#sessions.set(session.id, session);
+    return session;
+  }
+  get(sessionId) {
+    this.#deleteExpiredSessions();
+    return this.#sessions.get(sessionId);
+  }
+  touch(session) {
+    if (this.#sessions.get(session.id) !== session)
+      return;
+    session.touch(this.#currentTimeMilliseconds());
+  }
+  delete(sessionId) {
+    this.#sessions.get(sessionId)?.close();
+    this.#sessions.delete(sessionId);
+  }
+  closeAll() {
+    for (const session of this.#sessions.values())
+      session.close();
+    this.#sessions.clear();
+  }
+  #notifyWorkflowResourceUpdated(workflowId) {
+    const candidateUris = [
+      workflowResourceUri(workflowId, "state"),
+      workflowResourceUri(workflowId, "events"),
+      workflowResourceUri(workflowId, "checkpoints")
+    ], now = this.#currentTimeMilliseconds();
+    for (const session of this.#sessions.values()) {
+      const subscribedUris = new Set;
+      for (const uri of candidateUris) {
+        if (!session.subscriptions.has(uri))
+          continue;
+        subscribedUris.add(uri);
+      }
+      const searchUris = [...session.subscriptions].filter(isWorkflowSearchResourceUri);
+      for (const uri of searchUris)
+        subscribedUris.add(uri);
+      if (subscribedUris.size === 0)
+        continue;
+      session.touch(now);
+      for (const uri of subscribedUris)
+        session.notify("notifications/resources/updated", { uri });
+    }
+    this.#deleteExpiredSessions();
+  }
+  #deleteExpiredSessions() {
+    const now = this.#currentTimeMilliseconds();
+    for (const [sessionId, session] of this.#sessions) {
+      if (!session.isIdleExpired(now, this.#sessionIdleTimeoutMilliseconds))
+        continue;
+      session.close();
+      this.#sessions.delete(sessionId);
+    }
+  }
+  async[Symbol.asyncDispose]() {
+    for (const eventName of RESOURCE_EVENT_NAMES)
+      this.#engine.removeEventListener(eventName, this.#listener);
+    this.closeAll();
+  }
+}
+export function createMcpSessionManager(engine, options) {
+  return new McpSessionManager(engine, options);
+}

package/dist/mcp/stdio.d.ts

@@ -0,0 +1,89 @@
+import type { Engine } from '../core/engine.ts';
+import { type McpSessionManagerOptions } from './session.ts';
+/**
+ * Admission modes for local MCP stdio sessions.
+ *
+ * @example
+ * ```ts
+ * import { type McpStdioAdmission } from '@lostgradient/weft/mcp';
+ *
+ * const admission: McpStdioAdmission = {
+ *   kind: 'startup-token',
+ *   token: 'change-me',
+ * };
+ * void admission;
+ * ```
+ */
+export type McpStdioAdmission = {
+    readonly kind: 'allow-unauthenticated-local-admin';
+} | {
+    readonly kind: 'startup-token';
+    readonly token: string;
+} | {
+    readonly kind: 'require-one';
+};
+/**
+ * Options for running a local MCP stdio session.
+ *
+ * @example
+ * ```ts
+ * import { type McpStdioSessionOptions } from '@lostgradient/weft/mcp';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * await using engine = new Engine({ storage });
+ *
+ * const options: McpStdioSessionOptions = {
+ *   input: new ReadableStream<Uint8Array>(),
+ *   output: new WritableStream<Uint8Array>(),
+ *   engine,
+ *   admission: { kind: 'require-one' },
+ *   sessionManagerOptions: { maximumSessions: 1 },
+ * };
+ * void options;
+ * ```
+ */
+export type McpStdioSessionOptions = {
+    readonly input: ReadableStream<Uint8Array>;
+    readonly output: WritableStream<Uint8Array>;
+    readonly engine: Engine;
+    readonly admission: McpStdioAdmission;
+    readonly maxFrameBytes?: number;
+    readonly sessionManagerOptions?: McpSessionManagerOptions;
+};
+/**
+ * Result of a completed MCP stdio session.
+ *
+ * @example
+ * ```ts
+ * import { type McpStdioSessionResult } from '@lostgradient/weft/mcp';
+ *
+ * const result: McpStdioSessionResult = { exitCode: 0 };
+ * process.exitCode = result.exitCode;
+ * ```
+ */
+export type McpStdioSessionResult = {
+    readonly exitCode: number;
+    readonly reason?: string;
+};
+/**
+ * Run a newline-delimited MCP JSON-RPC stdio session against a local engine.
+ *
+ * @example
+ * ```ts
+ * import { runMcpStdioSession } from '@lostgradient/weft/mcp';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * await using engine = new Engine({ storage });
+ *
+ * const result = await runMcpStdioSession({
+ *   input: new ReadableStream<Uint8Array>(),
+ *   output: new WritableStream<Uint8Array>(),
+ *   engine,
+ *   admission: { kind: 'require-one' },
+ * });
+ * void result;
+ * ```
+ */
+export declare function runMcpStdioSession(options: McpStdioSessionOptions): Promise<McpStdioSessionResult>;

package/dist/mcp/stdio.js

@@ -0,0 +1,204 @@
+import { principalFromStdioLocal } from "../server/principal.js";
+import { dispatchMcpMessage } from "./dispatcher.js";
+import { parseMcpMessage } from "./protocol.js";
+import { McpSession, McpSessionManager } from "./session.js";
+const DEFAULT_MAX_FRAME_BYTES = 1048576;
+export async function runMcpStdioSession(options) {
+  if (options.admission.kind === "require-one")
+    return {
+      exitCode: 2,
+      reason: "MCP stdio admission required: pass --startup-token <token> or --allow-unauthenticated-local-admin"
+    };
+  if (options.admission.kind === "startup-token" && options.admission.token.trim().length === 0)
+    return { exitCode: 2, reason: "MCP stdio startup token must be non-empty" };
+  const runtime = createStdioRuntime(options), pending = new Set;
+  try {
+    const admitted = await runAdmission(options, runtime);
+    if (!admitted.ok) {
+      await closeRuntime(runtime);
+      return admitted.result;
+    }
+    await runMainReadLoop(options, runtime, admitted.remainder, pending);
+    await Promise.all(pending);
+    await closeRuntime(runtime);
+    return { exitCode: 0 };
+  } catch (error) {
+    await closeRuntime(runtime, !0);
+    return { exitCode: 1, reason: error instanceof Error ? error.message : String(error) };
+  } finally {
+    runtime.reader.releaseLock();
+  }
+}
+function createStdioRuntime(options) {
+  const writer = options.output.getWriter(), write = createSerializedWriter(writer), manager = new McpSessionManager(options.engine, options.sessionManagerOptions), session = manager.add(new McpSession("stdio-local", principalFromStdioLocal()));
+  session.addTarget((message) => {
+    manager.touch(session);
+    write(JSON.stringify(message));
+  });
+  return {
+    writer,
+    write,
+    manager,
+    session,
+    reader: options.input.getReader(),
+    decoder: new TextDecoder
+  };
+}
+async function runAdmission(options, runtime) {
+  if (options.admission.kind !== "startup-token")
+    return { ok: !0, remainder: "" };
+  return runStartupTokenAdmission(runtime.reader, runtime.decoder, options.admission.token, runtime.write, options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES);
+}
+async function runMainReadLoop(options, runtime, initialBuffer, pending) {
+  let buffer = initialBuffer;
+  while (!0) {
+    const chunk = await runtime.reader.read();
+    if (chunk.done)
+      break;
+    buffer = await appendChunkAndDispatch(buffer, chunk.value, options, runtime, pending);
+  }
+  if (buffer.trim().length > 0)
+    addPendingLine(buffer, options, runtime, pending);
+}
+async function appendChunkAndDispatch(buffer, chunk, options, runtime, pending) {
+  const nextBuffer = buffer + runtime.decoder.decode(chunk, { stream: !0 });
+  if (nextBuffer.length > (options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES)) {
+    await runtime.write(JSON.stringify({
+      jsonrpc: "2.0",
+      id: null,
+      error: { code: -32600, message: "frame exceeds maxFrameBytes" }
+    }));
+    return "";
+  }
+  const lines = nextBuffer.split(`
+`);
+  for (const line of lines.slice(0, -1))
+    addPendingLine(line, options, runtime, pending);
+  return lines.at(-1) ?? "";
+}
+function addPendingLine(line, options, runtime, pending) {
+  if (line.trim().length === 0)
+    return;
+  runtime.manager.touch(runtime.session);
+  const task = handleLine(line, options.engine, runtime.session, runtime.write).finally(() => {
+    pending.delete(task);
+  });
+  pending.add(task);
+}
+async function closeRuntime(runtime, ignoreWriterError = !1) {
+  await runtime.manager[Symbol.asyncDispose]();
+  await runtime.write.drain();
+  if (ignoreWriterError) {
+    await runtime.writer.close().catch(() => {
+      return;
+    });
+    return;
+  }
+  await runtime.writer.close();
+}
+async function runStartupTokenAdmission(reader, decoder, expectedToken, write, maxFrameBytes) {
+  const frame = await readAuthenticationFrame(reader, decoder, write, maxFrameBytes);
+  if (!frame.ok)
+    return frame;
+  const authenticated = await authenticateFrame(frame.line, expectedToken, write);
+  if (!authenticated.ok)
+    return authenticated;
+  return { ok: !0, remainder: frame.remainder };
+}
+async function readAuthenticationFrame(reader, decoder, write, maxFrameBytes) {
+  let buffer = "";
+  while (!buffer.includes(`
+`)) {
+    const chunk = await reader.read();
+    if (chunk.done)
+      return {
+        ok: !1,
+        result: { exitCode: 2, reason: "stdio session closed before authenticate frame" }
+      };
+    buffer += decoder.decode(chunk.value, { stream: !0 });
+    if (buffer.length > maxFrameBytes) {
+      await write(JSON.stringify(authenticationError(null, "authenticate frame exceeds maxFrameBytes")));
+      return {
+        ok: !1,
+        result: { exitCode: 2, reason: "authenticate frame exceeds maxFrameBytes" }
+      };
+    }
+  }
+  const newlineIndex = buffer.indexOf(`
+`);
+  return {
+    ok: !0,
+    line: buffer.slice(0, newlineIndex),
+    remainder: buffer.slice(newlineIndex + 1)
+  };
+}
+async function authenticateFrame(line, expectedToken, write) {
+  const parsed = parseAuthenticationLine(line);
+  if (!parsed.ok) {
+    await write(JSON.stringify(authenticationError(null, "first frame was not valid JSON")));
+    return { ok: !1, result: { exitCode: 2, reason: "first frame was not valid JSON" } };
+  }
+  const token = tokenFromParams(parsed.record.params);
+  if (parsed.record.method !== "weft.authenticate" || token !== expectedToken) {
+    await write(JSON.stringify(authenticationError(parsed.id, "startup token mismatch")));
+    return { ok: !1, result: { exitCode: 2, reason: "startup token mismatch" } };
+  }
+  await write(JSON.stringify({ jsonrpc: "2.0", id: parsed.id, result: {} }));
+  return { ok: !0 };
+}
+function parseAuthenticationLine(line) {
+  const parsed = parseMcpMessage(line);
+  if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object")
+    return { ok: !1 };
+  const record = parsed.value;
+  return { ok: !0, record, id: record.id ?? null };
+}
+function tokenFromParams(params) {
+  if (params !== null && typeof params === "object" && !Array.isArray(params))
+    return params.token;
+  return;
+}
+function authenticationError(id, message) {
+  return {
+    jsonrpc: "2.0",
+    id: typeof id === "string" || typeof id === "number" || id === null ? id : null,
+    error: { code: -32010, message }
+  };
+}
+async function handleLine(line, engine, session, write) {
+  const parsed = parseMcpMessage(line);
+  if (!parsed.ok) {
+    await write(JSON.stringify({
+      jsonrpc: "2.0",
+      id: null,
+      error: { code: -32700, message: "Parse error" }
+    }));
+    return;
+  }
+  const result = await dispatchMcpMessage(parsed.value, {
+    engine,
+    session,
+    principal: session.principal,
+    authRequired: !1
+  });
+  if (result.kind === "response")
+    await write(JSON.stringify(result.response));
+}
+function createSerializedWriter(writer) {
+  const encoder = new TextEncoder;
+  let chain = Promise.resolve();
+  const write = (line) => {
+    const next = chain.then(() => writer.write(encoder.encode(`${line}
+`)));
+    chain = next.catch(() => {
+      return;
+    });
+    return next;
+  };
+  write.drain = async () => {
+    await chain.catch(() => {
+      return;
+    });
+  };
+  return write;
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,27 @@
+import type { Engine } from '../core/engine.ts';
+import { type McpAccessContext } from './access.ts';
+import type { McpSession } from './session.ts';
+/** MCP tool definition. */
+export type McpToolDefinition = {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+};
+/** Result shape returned by MCP `tools/call`. */
+export type McpToolResult = {
+    readonly content: ReadonlyArray<{
+        readonly type: 'text';
+        readonly text: string;
+    }>;
+    readonly isError?: boolean;
+};
+type ToolCallContext = McpAccessContext & {
+    readonly session: McpSession;
+    readonly requestId: unknown;
+};
+/** Build deterministic MCP tool definitions for the current engine registry. */
+export declare function listMcpTools(engine: Engine): McpToolDefinition[];
+/** Invoke an MCP tool and shape application failures as tool errors. */
+export declare function callMcpTool(name: string, argumentsValue: unknown, context: ToolCallContext): Promise<McpToolResult>;
+export {};