@walkeros/mcp 4.6.0-next-1788933594957 → 4.6.1

package/README.md

@@ -162,13 +162,16 @@ can mount the protocol over HTTP instead of running the stdio binary:
 ```typescript
 import {
   createWalkerOSMcpServer,
+  createHostedRuntime,
   HttpToolClient,
   createStreamableHttpHandler,
 } from '@walkeros/mcp';
 
+const client = new HttpToolClient();
 const server = createWalkerOSMcpServer({
-  client: new HttpToolClient(),
+  client,
   version: '1.0.0',
+  runtime: createHostedRuntime(client),
 });
 
 export const POST = createStreamableHttpHandler(server, {
@@ -176,10 +179,19 @@ export const POST = createStreamableHttpHandler(server, {
 });
 ```
 
+The server reads, bundles and runs flows only through a runtime, which decides
+what the process it lives in may do. `createHostedRuntime(client)` is the
+default when `runtime` is omitted and the right choice for anything reached over
+the network: it loads inline JSON and saved flow ids, refuses local file paths
+and URLs, and never bundles, simulates or pushes in the host process.
+`createLocalRuntime()` keeps every capability, including local files, URLs and
+in-process execution, and belongs only on the user's own machine; the stdio
+binary uses it.
+
 To use the tool registry without the MCP protocol, for example with the Vercel
-AI SDK, import `TOOL_DEFINITIONS` and supply your own `ToolClient`. The stdio
-binary stays available as `@walkeros/mcp/stdio` and the `walkeros-mcp` bin
-entry.
+AI SDK, call `createToolHandlers(client, version, runtime)` or import
+`TOOL_DEFINITIONS` and supply your own `ToolClient`. The stdio binary stays
+available as `@walkeros/mcp/stdio` and the `walkeros-mcp` bin entry.
 
 ## Documentation
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ListFlowsOptions, ListPreviewsOptions, GetPreviewOptions, CreatePreviewOptions, DeletePreviewOptions, ListSecretsOptions, CreateSecretOptions, UpdateSecretOptions, DeleteSecretOptions, DeployOptions, ListDeploymentsOptions, DeviceAuthorization, DeviceLoginResult, FeedbackOptions } from '@walkeros/cli';
-import { Journey, JourneyGap, JourneyUnattributed } from '@walkeros/core';
+import { ListFlowsOptions, ListPreviewsOptions, GetPreviewOptions, CreatePreviewOptions, DeletePreviewOptions, ListSecretsOptions, CreateSecretOptions, UpdateSecretOptions, DeleteSecretOptions, DeployOptions, ListDeploymentsOptions, DeviceAuthorization, DeviceLoginResult, FeedbackOptions, BundleStats, PushResult } from '@walkeros/cli';
+import { Journey, JourneyGap, JourneyUnattributed, Ingest, WalkerOS, Simulation } from '@walkeros/core';
 import { ZodRawShape, z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -590,6 +590,71 @@ interface ToolSpec {
     handler: (input: unknown) => Promise<unknown>;
 }
 
+/**
+ * The capability seam between the flow tools and the machine they run on.
+ *
+ * Every file read, URL fetch, bundle, simulation and push a tool performs goes
+ * through a `FlowRuntime` and nothing else, so the runtime alone decides what
+ * the process it lives in may do:
+ *
+ * - `createLocalRuntime()` keeps every capability. It is for the user's own
+ *   machine (stdio, the developer CLI), where the user is responsible for what
+ *   runs there.
+ * - `createHostedRuntime(client)` is least privilege for a shared, network
+ *   reached process: it loads inline JSON and saved flow ids only, refuses
+ *   local paths and URLs, and has no `bundle`, `simulate` or `push` at all.
+ *
+ * A tool whose operation the runtime does not provide refuses with a hint that
+ * names only out-of-process routes.
+ */
+interface FlowRuntime {
+    /**
+     * Resolve a config input to parsed JSON. Local: a file path, an http(s) URL
+     * or inline JSON. Hosted: inline JSON or a saved `flow_`/`cfg_` id; a local
+     * path or URL is refused with a `RuntimeRefusal`.
+     */
+    load(input: string): Promise<unknown>;
+    /** Compile a flow. Absent on a runtime that must not build in its process. */
+    bundle?(input: string, opts: BundleOptions): Promise<BundleStats | void>;
+    /** Build and run one step of a flow. Absent where that must not happen. */
+    simulate?(input: string, opts: SimulateOptions): Promise<Simulation.Result>;
+    /** Build and run a flow against real destinations. Absent where forbidden. */
+    push?(input: string, event: Record<string, unknown>, opts: PushOptions): Promise<PushResult>;
+}
+interface BundleOptions {
+    flowName?: string;
+    stats?: boolean;
+    output?: string;
+}
+type SimulateStepType = 'source' | 'transformer' | 'collector' | 'destination';
+interface SimulateOptions {
+    stepType: SimulateStepType;
+    stepId: string;
+    event: unknown;
+    flow?: string;
+    /** Transformer steps only: pipeline context the step reads via `ctx.ingest`. */
+    ingest?: Omit<Ingest, '_meta'>;
+    /** Collector steps only: state snapshot seeded before enrichment runs. */
+    state?: {
+        consent?: WalkerOS.Consent;
+        user?: WalkerOS.User;
+        globals?: WalkerOS.Properties;
+        timing?: number;
+    };
+}
+interface PushOptions {
+    flow?: string;
+    platform?: 'web' | 'server';
+}
+/**
+ * Thrown by a runtime when it refuses an input on principle rather than on a
+ * fault. Carries the hint a tool should surface next to the message.
+ */
+declare class RuntimeRefusal extends Error {
+    readonly hint: string;
+    constructor(message: string, hint: string);
+}
+
 interface Logger {
     debug?(message: string, meta?: Record<string, unknown>): void;
     info?(message: string, meta?: Record<string, unknown>): void;
@@ -601,6 +666,15 @@ interface CreateServerOptions {
     logger?: Logger;
     version?: string;
     catalogBaseUrl?: string;
+    /**
+     * The capability runtime the flow tools read, build and run flows through.
+     * Omitted, the HOSTED runtime is used, the safe default for any shared or
+     * network-reached process: inline JSON and saved flow ids only, no local
+     * files, no URLs, no in-process bundle, simulate or push. Pass
+     * `createLocalRuntime()` only on the user's own machine (stdio, the CLI) to
+     * keep local file, URL and execution behaviour. See `FlowRuntime`.
+     */
+    runtime?: FlowRuntime;
 }
 declare function createWalkerOSMcpServer(opts: CreateServerOptions): McpServer;
 
@@ -819,6 +893,31 @@ interface CreateStreamableHttpHandlerOptions extends WebStandardStreamableHTTPSe
  */
 declare function createStreamableHttpHandler(server: McpServer, opts?: CreateStreamableHttpHandlerOptions): (request: Request) => Promise<Response>;
 
+/**
+ * The full-capability runtime for the user's own machine (stdio, the developer
+ * CLI). It wraps the `@walkeros/cli` loaders and runners exactly as the tools
+ * called them before the runtime seam existed, so local behaviour is unchanged:
+ * a config may be a file path, an http(s) URL or inline JSON, and bundling,
+ * simulation and push run in this process.
+ *
+ * This is the only module in the package that may bind those cli functions;
+ * the tools reach them through the `FlowRuntime` interface and nothing else.
+ */
+declare function createLocalRuntime(): FlowRuntime;
+
+/**
+ * The least-privilege runtime for a shared, network-reached process: the app's
+ * OAuth door, in-app chat, and any third-party HTTP host.
+ *
+ * It never touches the filesystem or the network on the caller's behalf. A
+ * saved `flow_`/`cfg_` id is resolved through the access-scoped tool client, a
+ * document is parsed inline, and everything else is refused. `bundle`,
+ * `simulate` and `push` are deliberately absent: compiling or importing a
+ * caller's flow pulls that caller's code (inline or by package name) into this
+ * process, and no input shape makes that safe here.
+ */
+declare function createHostedRuntime(client: Pick<ToolClient, 'getFlow'>): FlowRuntime;
+
 /**
  * Exported so the hosted plane can assert parity against this exact string
  * instead of retyping it.
@@ -1195,8 +1294,10 @@ declare module '@walkeros/core' {
  * Handlers are closed over `client`, so the caller can bind a single
  * `ToolClient` (such as the zero-hop `ServiceToolClient`) once per session.
  * `packageVersion` is reported by the `diagnostics` tool and defaults to
- * `'0.0.0'` when omitted.
+ * `'0.0.0'` when omitted. `runtime` defaults to the hosted runtime, the safe
+ * choice for any shared process; pass `createLocalRuntime()` only on the
+ * user's own machine.
  */
-declare function createToolHandlers(client: ToolClient, packageVersion?: string): Record<string, ToolSpec>;
+declare function createToolHandlers(client: ToolClient, packageVersion?: string, runtime?: FlowRuntime): Record<string, ToolSpec>;
 
-export { type CreateServerOptions, type CreateStreamableHttpHandlerOptions, type DeploymentLinkTarget, FEATURE_NOT_AVAILABLE, FRAME_HINT_EXTENDS_BASE, FRAME_HINT_MARK_SPACE, FRAME_HINT_NAMES_ARE_DOCUMENTATION, FRAME_HINT_NONE_ON_PAGE, FRAME_HINT_NONE_YET, FRAME_HINT_OPEN_PAGE_OR_GET, FRAME_HINT_READ_KNOWLEDGE, FRAME_MANAGE_DESCRIPTION, FRAME_MANAGE_INPUT_SCHEMA, FRAME_NOT_FOUND_HINT, type FlowCanvasPayload, type FlowCanvasToolResult, type FlowLinkTarget, type FrameLeanListWire, type FrameLeanWire, type FrameListWire, type FrameWire, type GatedFeature, HINT_EMPTY_FEED, HINT_ENDED, HINT_NO_WINDOW, HINT_PREVIEW_STREAMS, HINT_READ, HINT_SIMULATE_FIRST, HINT_STOP, HUB_HINT_CONFIRM_INDEX, HUB_HINT_ENTRY_NAMES_FLOW, HUB_HINT_KEEP_ONE_THREAD, HUB_HINT_KNOWLEDGE_INDEX, HUB_HINT_KNOWLEDGE_PAGE_CAPPED, HUB_HINT_KNOWLEDGE_READ_ONLY, HUB_HINT_MASKED_ONLY, HUB_HINT_MESSAGES_TRUNCATED, HUB_HINT_MESSAGE_VISIBLE, HUB_HINT_NOTHING_DISCUSSED, HUB_HINT_NOTHING_WRITTEN, HUB_HINT_NO_MATCH, HUB_HINT_NO_THREAD_ON_ANCHOR, HUB_HINT_OPEN_RELEASE, HUB_HINT_RATIONALE_VISIBLE, HUB_HINT_READ_BACK, HUB_HINT_READ_FRAME, HUB_HINT_RELEASE_GET, HUB_HINT_REPLY_OR_OPEN, HUB_HINT_RESOLVE_IN_APP, HUB_HINT_ROWS_ARE_DEPLOYMENTS, HUB_HINT_SCAN_CAPPED, HUB_HINT_STAYS_RESOLVED, HUB_HINT_STEP_HISTORY, HUB_HINT_THREADS_INDEX, HUB_HINT_THREADS_PAGE_CAPPED, HUB_HINT_THREAD_OPEN, HUB_HINT_TRACE_STEP, HUB_HINT_WRITE_RATIONALE, HUB_MANAGE_DESCRIPTION, HUB_MANAGE_INPUT_SCHEMA, HUB_NOT_FOUND_HINT, HttpToolClient, type HubThreadWire, type JourneysResult, type KnowledgeEntryWire, type ListKnowledgeWire, type ListThreadsWire, type Logger, DESCRIPTION as OBSERVE_SESSION_DESCRIPTION, type RedactOptions, type ReleaseDetailWire, type ReleaseIndexWire, type ReleaseRef, type StepHistoryWire, type StepLinkTarget, type SuggestionTile, TOOL_DEFINITIONS, type ThreadLinkTarget, type ToolAnnotations, type ToolClient, type ToolDefinition, type ToolSpec, type VersionAnnotationWire, createStreamableHttpHandler, createToolHandlers, createWalkerOSMcpServer, featureDenialHint, flowCanvasResult, isFeatureDenial, isFlowCanvasResult, links, redactNestedStrings, wrapUserData };
+export { type BundleOptions, type CreateServerOptions, type CreateStreamableHttpHandlerOptions, type DeploymentLinkTarget, FEATURE_NOT_AVAILABLE, FRAME_HINT_EXTENDS_BASE, FRAME_HINT_MARK_SPACE, FRAME_HINT_NAMES_ARE_DOCUMENTATION, FRAME_HINT_NONE_ON_PAGE, FRAME_HINT_NONE_YET, FRAME_HINT_OPEN_PAGE_OR_GET, FRAME_HINT_READ_KNOWLEDGE, FRAME_MANAGE_DESCRIPTION, FRAME_MANAGE_INPUT_SCHEMA, FRAME_NOT_FOUND_HINT, type FlowCanvasPayload, type FlowCanvasToolResult, type FlowLinkTarget, type FlowRuntime, type FrameLeanListWire, type FrameLeanWire, type FrameListWire, type FrameWire, type GatedFeature, HINT_EMPTY_FEED, HINT_ENDED, HINT_NO_WINDOW, HINT_PREVIEW_STREAMS, HINT_READ, HINT_SIMULATE_FIRST, HINT_STOP, HUB_HINT_CONFIRM_INDEX, HUB_HINT_ENTRY_NAMES_FLOW, HUB_HINT_KEEP_ONE_THREAD, HUB_HINT_KNOWLEDGE_INDEX, HUB_HINT_KNOWLEDGE_PAGE_CAPPED, HUB_HINT_KNOWLEDGE_READ_ONLY, HUB_HINT_MASKED_ONLY, HUB_HINT_MESSAGES_TRUNCATED, HUB_HINT_MESSAGE_VISIBLE, HUB_HINT_NOTHING_DISCUSSED, HUB_HINT_NOTHING_WRITTEN, HUB_HINT_NO_MATCH, HUB_HINT_NO_THREAD_ON_ANCHOR, HUB_HINT_OPEN_RELEASE, HUB_HINT_RATIONALE_VISIBLE, HUB_HINT_READ_BACK, HUB_HINT_READ_FRAME, HUB_HINT_RELEASE_GET, HUB_HINT_REPLY_OR_OPEN, HUB_HINT_RESOLVE_IN_APP, HUB_HINT_ROWS_ARE_DEPLOYMENTS, HUB_HINT_SCAN_CAPPED, HUB_HINT_STAYS_RESOLVED, HUB_HINT_STEP_HISTORY, HUB_HINT_THREADS_INDEX, HUB_HINT_THREADS_PAGE_CAPPED, HUB_HINT_THREAD_OPEN, HUB_HINT_TRACE_STEP, HUB_HINT_WRITE_RATIONALE, HUB_MANAGE_DESCRIPTION, HUB_MANAGE_INPUT_SCHEMA, HUB_NOT_FOUND_HINT, HttpToolClient, type HubThreadWire, type JourneysResult, type KnowledgeEntryWire, type ListKnowledgeWire, type ListThreadsWire, type Logger, DESCRIPTION as OBSERVE_SESSION_DESCRIPTION, type PushOptions, type RedactOptions, type ReleaseDetailWire, type ReleaseIndexWire, type ReleaseRef, RuntimeRefusal, type SimulateOptions, type SimulateStepType, type StepHistoryWire, type StepLinkTarget, type SuggestionTile, TOOL_DEFINITIONS, type ThreadLinkTarget, type ToolAnnotations, type ToolClient, type ToolDefinition, type ToolSpec, type VersionAnnotationWire, createHostedRuntime, createLocalRuntime, createStreamableHttpHandler, createToolHandlers, createWalkerOSMcpServer, featureDenialHint, flowCanvasResult, isFeatureDenial, isFlowCanvasResult, links, redactNestedStrings, wrapUserData };