@lostgradient/weft 0.2.0

package/dist/mcp/list-filter.js

@@ -0,0 +1,116 @@
+const WORKFLOW_STATUS_VALUES = [
+  "pending",
+  "running",
+  "completed",
+  "failed",
+  "cancelled",
+  "timed-out"
+];
+export function parseMcpListFilter(value) {
+  if (!isRecord(value))
+    return { ok: !1, message: "List filter must be a JSON object" };
+  const status = parseStatusFilter(value.status), type = parseOptionalString(value.type, "type"), tags = parseStringArray(value.tags, "tags"), limit = parseNonNegativeInteger(value.limit, "limit"), offset = parseNonNegativeInteger(value.offset, "offset"), failure = firstFailure([status, type, tags, limit, offset]);
+  if (failure !== void 0)
+    return failure;
+  return {
+    ok: !0,
+    filter: compactListFilter({
+      status: parsedValue(status),
+      type: parsedValue(type),
+      tags: parsedValue(tags),
+      limit: parsedValue(limit),
+      offset: parsedValue(offset)
+    })
+  };
+}
+export function parseMcpListFilterFromSearchParams(searchParams) {
+  const record = {}, status = searchParams.getAll("status");
+  if (status.length === 1)
+    record.status = status[0];
+  if (status.length > 1)
+    record.status = status;
+  const type = searchParams.get("type");
+  if (type !== null)
+    record.type = type;
+  const tags = searchParams.getAll("tag");
+  if (tags.length > 0)
+    record.tags = tags;
+  const limit = searchParams.get("limit");
+  if (limit !== null)
+    record.limit = Number(limit);
+  const offset = searchParams.get("offset");
+  if (offset !== null)
+    record.offset = Number(offset);
+  return parseMcpListFilter(record);
+}
+function parseStatusFilter(value) {
+  if (value === void 0)
+    return { ok: !0 };
+  if (typeof value === "string")
+    return isWorkflowStatus(value) ? { ok: !0, value } : { ok: !1, message: `Invalid workflow status: ${value}` };
+  if (!Array.isArray(value))
+    return { ok: !1, message: "List filter status must be a workflow status or array" };
+  const statuses = [];
+  for (const item of value) {
+    if (typeof item !== "string" || !isWorkflowStatus(item))
+      return { ok: !1, message: "List filter status array contains an invalid workflow status" };
+    statuses.push(item);
+  }
+  return { ok: !0, value: statuses };
+}
+function parseOptionalString(value, field) {
+  if (value === void 0)
+    return { ok: !0 };
+  if (typeof value !== "string")
+    return { ok: !1, message: `List filter ${field} must be a string` };
+  return { ok: !0, value };
+}
+function parseStringArray(value, field) {
+  if (value === void 0)
+    return { ok: !0 };
+  if (!Array.isArray(value))
+    return { ok: !1, message: `List filter ${field} must be an array` };
+  const values = [];
+  for (const item of value) {
+    if (typeof item !== "string")
+      return { ok: !1, message: `List filter ${field} must contain only strings` };
+    values.push(item);
+  }
+  return { ok: !0, value: values };
+}
+function parseNonNegativeInteger(value, field) {
+  if (value === void 0)
+    return { ok: !0 };
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+    return { ok: !1, message: `List filter ${field} must be a non-negative integer` };
+  return { ok: !0, value };
+}
+function firstFailure(results) {
+  for (const result of results)
+    if (!result.ok)
+      return result;
+  return;
+}
+function parsedValue(result) {
+  return result.ok ? result.value : void 0;
+}
+function compactListFilter(fields) {
+  const filter = {};
+  if (fields.status !== void 0)
+    filter.status = fields.status;
+  if (fields.type !== void 0)
+    filter.type = fields.type;
+  if (fields.tags !== void 0)
+    filter.tags = fields.tags;
+  if (fields.limit !== void 0)
+    filter.limit = fields.limit;
+  if (fields.offset !== void 0)
+    filter.offset = fields.offset;
+  return filter;
+}
+function isWorkflowStatus(value) {
+  return WORKFLOW_STATUS_VALUES.some((status) => status === value);
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/mcp/protocol.d.ts

@@ -0,0 +1,89 @@
+import { type JsonRpcId } from '../server/json-rpc-protocol.ts';
+/**
+ * MCP protocol version implemented by Weft's MCP transport adapters.
+ *
+ * @example
+ * ```ts
+ * import { MCP_PROTOCOL_VERSION } from '@lostgradient/weft/mcp';
+ *
+ * const headers = new Headers({
+ *   'Mcp-Protocol-Version': MCP_PROTOCOL_VERSION,
+ * });
+ * void headers;
+ * ```
+ */
+export declare const MCP_PROTOCOL_VERSION = "2025-11-25";
+/** MCP method used for live tool introspection. */
+export declare const MCP_TOOLS_LIST_METHOD = "tools/list";
+/** MCP method used for live resource introspection. */
+export declare const MCP_RESOURCES_LIST_METHOD = "resources/list";
+/** MCP method used for live resource-template introspection. */
+export declare const MCP_RESOURCE_TEMPLATES_LIST_METHOD = "resources/templates/list";
+/**
+ * Default MCP HTTP body limit. Mirrors the existing JSON-RPC adapter limit.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_MCP_MAX_BODY_BYTES } from '@lostgradient/weft/mcp';
+ *
+ * const maxBodyBytes = DEFAULT_MCP_MAX_BODY_BYTES;
+ * void maxBodyBytes;
+ * ```
+ */
+export declare const DEFAULT_MCP_MAX_BODY_BYTES = 1048576;
+/** JSON-RPC request accepted by the MCP dispatcher. */
+export type McpRequest = {
+    readonly jsonrpc: '2.0';
+    readonly id?: JsonRpcId | undefined;
+    readonly method: string;
+    readonly params?: unknown;
+};
+/** JSON-RPC response emitted by the MCP dispatcher. */
+export type McpResponse = {
+    readonly jsonrpc: '2.0';
+    readonly id: JsonRpcId;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+        readonly data?: unknown;
+    };
+};
+/** Result of handling one MCP message. */
+export type McpDispatchResult = {
+    readonly kind: 'response';
+    readonly response: McpResponse;
+} | {
+    readonly kind: 'accepted';
+};
+/** Build a JSON-RPC success response. */
+export declare function successResponse(id: JsonRpcId, result: unknown): McpResponse;
+/** Build a JSON-RPC error response. */
+export declare function errorResponse(id: JsonRpcId, code: number, message: string, data?: unknown): McpResponse;
+/** Invalid params error response. */
+export declare function invalidParams(id: JsonRpcId, message: string, data?: unknown): McpResponse;
+/** Method not found error response. */
+export declare function methodNotFound(id: JsonRpcId, method: string): McpResponse;
+/** Internal error response with masked details. */
+export declare function internalError(id: JsonRpcId): McpResponse;
+/** Resource-not-found response using the MCP resource error convention. */
+export declare function resourceNotFound(id: JsonRpcId, uri: string): McpResponse;
+/** Forbidden response. */
+export declare function forbidden(id: JsonRpcId, reason: string): McpResponse;
+/** True when a value is a JSON-RPC object with a method field. */
+export declare function isMcpRequest(value: unknown): value is McpRequest;
+/** True when a JSON-RPC request is a notification. */
+export declare function isNotification(request: McpRequest): boolean;
+/** Convert a request id to a stable map key. */
+export declare function requestIdKey(id: JsonRpcId | undefined): string | undefined;
+/** Parse one JSON text payload into an MCP request or a protocol response. */
+export declare function parseMcpMessage(text: string): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+};
+/** True when an HTTP content type is JSON. */
+export declare function isJsonContentType(contentType: string): boolean;
+/** True when an Accept header allows the requested MIME type. */
+export declare function accepts(acceptHeader: string | null, mimeType: string): boolean;

package/dist/mcp/protocol.js

@@ -0,0 +1,64 @@
+import {
+  JSON_RPC_ERROR_CODES,
+  JSON_RPC_VERSION
+} from "../server/json-rpc-protocol.js";
+export const MCP_PROTOCOL_VERSION = "2025-11-25", MCP_TOOLS_LIST_METHOD = "tools/list", MCP_RESOURCES_LIST_METHOD = "resources/list", MCP_RESOURCE_TEMPLATES_LIST_METHOD = "resources/templates/list", DEFAULT_MCP_MAX_BODY_BYTES = 1048576;
+export function successResponse(id, result) {
+  return { jsonrpc: JSON_RPC_VERSION, id, result };
+}
+export function errorResponse(id, code, message, data) {
+  return {
+    jsonrpc: JSON_RPC_VERSION,
+    id,
+    error: data === void 0 ? { code, message } : { code, message, data }
+  };
+}
+export function invalidParams(id, message, data) {
+  return errorResponse(id, JSON_RPC_ERROR_CODES.INVALID_PARAMS, message, data);
+}
+export function methodNotFound(id, method) {
+  return errorResponse(id, JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND, `Unknown MCP method: ${method}`, {
+    method
+  });
+}
+export function internalError(id) {
+  return errorResponse(id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR, "Internal error");
+}
+export function resourceNotFound(id, uri) {
+  return errorResponse(id, -32002, "Resource not found", { uri });
+}
+export function forbidden(id, reason) {
+  return errorResponse(id, -32011, reason, { reason });
+}
+export function isMcpRequest(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return !1;
+  const record = value;
+  if (record.jsonrpc !== JSON_RPC_VERSION)
+    return !1;
+  return typeof record.method === "string";
+}
+export function isNotification(request) {
+  return request.id === void 0;
+}
+export function requestIdKey(id) {
+  if (id === void 0 || id === null)
+    return;
+  return typeof id === "number" ? `number:${String(id)}` : `string:${id}`;
+}
+export function parseMcpMessage(text) {
+  try {
+    return { ok: !0, value: JSON.parse(text) };
+  } catch {
+    return { ok: !1 };
+  }
+}
+export function isJsonContentType(contentType) {
+  const [type = ""] = contentType.trim().toLowerCase().split(";");
+  return type.trim() === "application/json";
+}
+export function accepts(acceptHeader, mimeType) {
+  if (acceptHeader === null || acceptHeader.trim().length === 0)
+    return !0;
+  return acceptHeader.split(",").map((entry) => entry.split(";")[0]?.trim().toLowerCase() ?? "").some((entry) => entry === "*/*" || entry === mimeType);
+}

package/dist/mcp/resources.d.ts

@@ -0,0 +1,40 @@
+import { type McpAccessContext } from './access.ts';
+import type { McpSession } from './session.ts';
+/** MCP resource definition. */
+export type McpResourceDefinition = {
+    readonly uri: string;
+    readonly name: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly mimeType?: string;
+};
+/** MCP resource template definition. */
+export type McpResourceTemplate = {
+    readonly uriTemplate: string;
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly mimeType: string;
+};
+/** MCP resource-read result. */
+export type McpResourceReadResult = {
+    readonly contents: ReadonlyArray<{
+        readonly uri: string;
+        readonly mimeType: string;
+        readonly text: string;
+    }>;
+};
+/** Return the static resource templates Weft exposes through MCP. */
+export declare function listMcpResourceTemplates(): McpResourceTemplate[];
+/** List visible workflow state resources. */
+export declare function listMcpResources(context: McpAccessContext): Promise<McpResourceDefinition[]>;
+/** Read a visible Weft MCP resource. */
+export declare function readMcpResource(uri: string, context: McpAccessContext): Promise<McpResourceReadResult | null>;
+/** Subscribe to updates for a visible resource. */
+export declare function subscribeMcpResource(uri: string, session: McpSession, context: McpAccessContext): Promise<boolean>;
+/** Remove a resource subscription. */
+export declare function unsubscribeMcpResource(uri: string, session: McpSession): void;
+/** Return true when a URI identifies a valid workflow search resource. */
+export declare function isWorkflowSearchResourceUri(uri: string): boolean;
+/** Build the canonical MCP URI for a workflow resource. */
+export declare function workflowResourceUri(workflowId: string, resourceKind: 'state' | 'events' | 'checkpoints'): string;

package/dist/mcp/resources.js

@@ -0,0 +1,141 @@
+import {
+  assertScope,
+  getVisibleWorkflowState,
+  listVisibleWorkflows
+} from "./access.js";
+import { parseMcpListFilterFromSearchParams } from "./list-filter.js";
+export function listMcpResourceTemplates() {
+  return [
+    {
+      uriTemplate: "weft://workflows/{workflowId}/state",
+      name: "workflow_state",
+      title: "Workflow state",
+      description: "Read the current state for a Weft workflow.",
+      mimeType: "application/json"
+    },
+    {
+      uriTemplate: "weft://workflows/{workflowId}/events",
+      name: "workflow_events",
+      title: "Workflow events",
+      description: "Read the event log for a Weft workflow.",
+      mimeType: "application/json"
+    },
+    {
+      uriTemplate: "weft://workflows/{workflowId}/checkpoints",
+      name: "workflow_checkpoints",
+      title: "Workflow checkpoints",
+      description: "Read checkpoint history summaries for a Weft workflow.",
+      mimeType: "application/json"
+    },
+    {
+      uriTemplate: "weft://workflows/search{?status,type,tag,limit,offset}",
+      name: "workflow_search",
+      title: "Workflow search",
+      description: "List visible Weft workflows using query filters.",
+      mimeType: "application/json"
+    }
+  ];
+}
+export async function listMcpResources(context) {
+  assertScope(context, "workflows:read", "Listing workflow resources");
+  return (await listVisibleWorkflows(context.engine, {})).items.map((workflow) => ({
+    uri: workflowResourceUri(workflow.id, "state"),
+    name: `workflow_${workflow.id}`,
+    title: `${workflow.type} workflow ${workflow.id}`,
+    description: `Current state for workflow ${workflow.id}.`,
+    mimeType: "application/json"
+  }));
+}
+export async function readMcpResource(uri, context) {
+  assertScope(context, "workflows:read", "Reading workflow resources");
+  const parsed = parseWeftResourceUri(uri);
+  if (parsed === null)
+    return null;
+  if (parsed.kind === "search") {
+    const result = await listVisibleWorkflows(context.engine, parsed.filter);
+    return jsonResource(uri, result);
+  }
+  const state = await getVisibleWorkflowState(context.engine, parsed.workflowId);
+  if (state === null)
+    return null;
+  switch (parsed.kind) {
+    case "state":
+      return jsonResource(uri, state);
+    case "events":
+      assertScope(context, "events:read", "Reading workflow events");
+      return jsonResource(uri, { events: await context.engine.getEvents(parsed.workflowId) });
+    case "checkpoints":
+      return jsonResource(uri, {
+        checkpoints: await context.engine.listCheckpoints(parsed.workflowId)
+      });
+  }
+}
+export async function subscribeMcpResource(uri, session, context) {
+  if (await readMcpResource(uri, context) === null)
+    return !1;
+  session.subscriptions.add(uri);
+  return !0;
+}
+export function unsubscribeMcpResource(uri, session) {
+  session.subscriptions.delete(uri);
+}
+function jsonResource(uri, value) {
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(value)
+      }
+    ]
+  };
+}
+function parseWeftResourceUri(uri) {
+  const url = parseWeftUrl(uri);
+  if (url === null)
+    return null;
+  if (url.pathname === "/search")
+    return parseSearchResource(url.searchParams);
+  return parseWorkflowResourcePath(url.pathname);
+}
+function parseWeftUrl(uri) {
+  let url;
+  try {
+    url = new URL(uri);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "weft:" || url.hostname !== "workflows")
+    return null;
+  return url;
+}
+function parseSearchResource(searchParams) {
+  const parsed = parseMcpListFilterFromSearchParams(searchParams);
+  return parsed.ok ? { kind: "search", filter: parsed.filter } : null;
+}
+export function isWorkflowSearchResourceUri(uri) {
+  return parseWeftResourceUri(uri)?.kind === "search";
+}
+function parseWorkflowResourcePath(pathname) {
+  const parts = pathname.split("/").filter(Boolean).map(decodePathSegment);
+  if (parts.some((part) => part === null))
+    return null;
+  if (parts.length !== 2)
+    return null;
+  const [workflowId, resourceKind] = parts;
+  if (!workflowId)
+    return null;
+  if (resourceKind === "state" || resourceKind === "events" || resourceKind === "checkpoints")
+    return { kind: resourceKind, workflowId };
+  return null;
+}
+export function workflowResourceUri(workflowId, resourceKind) {
+  return `weft://workflows/${encodeURIComponent(workflowId)}/${resourceKind}`;
+}
+function decodePathSegment(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+}

package/dist/mcp/session.d.ts

@@ -0,0 +1,138 @@
+import type { Engine } from '../core/engine.ts';
+import { WeftError } from '../core/weft-error.ts';
+import type { Principal } from '../server/principal.ts';
+import { type McpResponse } from './protocol.ts';
+type NotificationTarget = (message: McpResponse | Record<string, unknown>) => void;
+/**
+ * MCP lifecycle phase tracked for one session.
+ *
+ * @example
+ * ```ts
+ * import { type McpSessionPhase } from '@lostgradient/weft/mcp';
+ *
+ * const phase: McpSessionPhase = 'ready';
+ * void phase;
+ * ```
+ */
+export type McpSessionPhase = 'new' | 'initializing' | 'ready';
+/**
+ * Options for bounding remote MCP session lifetime and memory usage.
+ *
+ * @example
+ * ```ts
+ * import { createMcpSessionManager, type McpSessionManagerOptions } from '@lostgradient/weft/mcp';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * await using engine = new Engine({ storage });
+ *
+ * const options: McpSessionManagerOptions = {
+ *   maximumSessions: 256,
+ *   sessionIdleTimeoutMilliseconds: 15 * 60 * 1000,
+ * };
+ * const manager = createMcpSessionManager(engine, options);
+ * void manager;
+ * ```
+ */
+export type McpSessionManagerOptions = {
+    readonly maximumSessions?: number;
+    readonly sessionIdleTimeoutMilliseconds?: number;
+    readonly currentTimeMilliseconds?: () => number;
+};
+export declare class McpSessionLimitExceededError extends WeftError<'McpSessionLimitExceededError'> {
+    constructor();
+}
+/**
+ * Mutable MCP session state. Remote HTTP sessions are created during
+ * `initialize`; stdio creates one local session for the process lifetime.
+ *
+ * @example
+ * ```ts
+ * import { McpSessionManager, type McpSession } from '@lostgradient/weft/mcp';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * await using engine = new Engine({ storage });
+ * await using manager = new McpSessionManager(engine);
+ *
+ * const session: McpSession = manager.create({ method: 'unauthenticated' });
+ * session.notify('notifications/initialized');
+ * ```
+ */
+export declare class McpSession {
+    #private;
+    readonly id: string;
+    readonly principal: Principal;
+    phase: McpSessionPhase;
+    protocolVersion: string;
+    readonly subscriptions: Set<string>;
+    readonly createdAtMilliseconds: number;
+    lastActivityMilliseconds: number;
+    constructor(id: string, principal: Principal, currentTimeMilliseconds?: number);
+    /** Mark the session as active after a successful transport-level lookup. */
+    touch(currentTimeMilliseconds?: number): void;
+    /** True when this session has exceeded its idle timeout. */
+    isIdleExpired(currentTimeMilliseconds: number, timeoutMilliseconds: number): boolean;
+    /** Track an in-flight request that started a workflow and can be cancelled. */
+    trackRequest(requestId: unknown, workflowId: string): void;
+    /** Record cancellation for a tracked in-flight request and return its workflow id. */
+    cancelRequest(requestId: unknown): string | undefined;
+    /** True when an in-flight MCP request has received a cancellation notification. */
+    isRequestCancelled(requestId: unknown): boolean;
+    /** Stop tracking an in-flight request after it completes. */
+    untrackRequest(requestId: unknown): void;
+    /** Return the workflow associated with an in-flight MCP request. */
+    workflowForRequest(requestId: unknown): string | undefined;
+    /** Attach a notification sink. Returns a cleanup function. */
+    addTarget(target: NotificationTarget): () => void;
+    /** Broadcast a JSON-RPC notification to every live stream for this session. */
+    notify(method: string, params?: Record<string, unknown>): void;
+    close(): void;
+}
+/**
+ * Owns MCP sessions for a running server and translates engine events into
+ * resource update notifications.
+ *
+ * @example
+ * ```ts
+ * import { McpSessionManager } from '@lostgradient/weft/mcp';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * await using engine = new Engine({ storage });
+ * await using manager = new McpSessionManager(engine);
+ *
+ * manager.closeAll();
+ * ```
+ */
+export declare class McpSessionManager implements AsyncDisposable {
+    #private;
+    constructor(engine: Engine, options?: McpSessionManagerOptions);
+    /** Create and store a new session for a principal. */
+    create(principal: Principal): McpSession;
+    /** Store an externally-created session. Used by stdio. */
+    add(session: McpSession): McpSession;
+    get(sessionId: string): McpSession | undefined;
+    /** Mark a stored session active using the manager's clock. */
+    touch(session: McpSession): void;
+    delete(sessionId: string): void;
+    closeAll(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Create an MCP session manager for an engine.
+ *
+ * @example
+ * ```ts
+ * import { createMcpSessionManager } from '@lostgradient/weft/mcp';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * await using engine = new Engine({ storage });
+ * await using manager = createMcpSessionManager(engine);
+ *
+ * void manager;
+ * ```
+ */
+export declare function createMcpSessionManager(engine: Engine, options?: McpSessionManagerOptions): McpSessionManager;
+export {};