@walkeros/mcp 4.8.0 → 4.8.1-next-1792019907609

package/dist/specs.d.ts

@@ -0,0 +1,277 @@
+import { Flow, Ingest, WalkerOS, Simulation } from '@walkeros/core';
+import { BundleStats, PushResult } from '@walkeros/cli';
+import { ZodOptional, ZodString, ZodRawShape } from 'zod';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * The knowledge resources and prompts as plain data, so a host registers them
+ * on its own MCP server. No MCP SDK import: the shapes are what the SDK's
+ * `registerResource` and `registerPrompt` accept.
+ */
+
+interface ResourceContent {
+    text: string;
+    mimeType: string;
+}
+/** A resource at one fixed URI. */
+interface StaticResourceSpec {
+    kind: 'static';
+    /** Registration name, for example 'flow-schema'. */
+    name: string;
+    uri: string;
+    description: string;
+    mimeType: string;
+    read: () => Promise<ResourceContent>;
+}
+interface ResourceListEntry {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType: string;
+}
+/** A URI template resource that lists its own members. */
+interface TemplateResourceSpec {
+    kind: 'template';
+    name: string;
+    uriTemplate: string;
+    title?: string;
+    description: string;
+    mimeType: string;
+    list: () => Promise<ResourceListEntry[]>;
+    /** The template variables of the requested URI, as the host parsed them. */
+    read: (variables: Readonly<Record<string, string | string[]>>) => Promise<ResourceContent>;
+}
+type ResourceSpec = StaticResourceSpec | TemplateResourceSpec;
+interface PromptMessage {
+    role: 'user' | 'assistant';
+    content: {
+        type: 'text';
+        text: string;
+    };
+}
+/** A prompt; every argument is an optional string, as MCP prompt arguments are. */
+interface PromptSpec {
+    name: string;
+    description: string;
+    argsSchema: Record<string, ZodOptional<ZodString>>;
+    handler: (args: Readonly<Record<string, string | undefined>>) => Promise<{
+        messages: PromptMessage[];
+    }>;
+}
+
+/**
+ * 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. A runtime decides what the process
+ * it lives in may read and run. `createLocalRuntime()` keeps every capability
+ * for the user's own machine; a host that must not read files or URLs or run
+ * flows passes a runtime with `load` only, and the tools that need more
+ * refuse.
+ *
+ * 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. An input the runtime refuses throws a `RuntimeRefusal`.
+     */
+    load(input: string): Promise<unknown>;
+    /**
+     * The directory local `path` packages of a loaded input resolve against:
+     * the input file's directory. Absent on a runtime without a filesystem,
+     * where such packages stay a reported skip.
+     */
+    baseDir?(input: string): string | undefined;
+    /** 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>;
+    /**
+     * The values of the secrets a flow config references (`$secret.NAME`),
+     * masked wherever a simulation or push result egresses. Read by the tools
+     * only on a runtime without `loadRun`; a read that fails stops the run.
+     */
+    knownSecrets?(input: string): Promise<string[]>;
+    /**
+     * Read a push or simulate input once: the config and the values of the
+     * secrets it references. A prebuilt bundle yields no config. A read that
+     * fails rejects. Absent with `simulate` and `push`.
+     */
+    loadRun?(input: string): Promise<LoadedRun>;
+    /** 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;
+    /** The config from `loadRun`: the runtime does not read the input again. */
+    config?: Flow.Json;
+    /**
+     * Transformer, collector and destination steps: pipeline context the step
+     * reads via `ctx.ingest`. Source steps ignore it.
+     */
+    ingest?: Omit<Ingest, '_meta'>;
+    /**
+     * Collector state the step starts from. `consent` applies to every step
+     * (the collector's starting consent); `user`, `globals` and `timing` to
+     * collector steps only.
+     */
+    state?: {
+        consent?: WalkerOS.Consent;
+        user?: WalkerOS.User;
+        globals?: WalkerOS.Properties;
+        timing?: number;
+    };
+    /**
+     * Destination steps only: run this collector command with `event` as its
+     * data instead of pushing it (a step example with `command`).
+     */
+    command?: Flow.StepCommand;
+}
+/** A push or simulate input as read once by `loadRun`. */
+interface LoadedRun {
+    config?: Flow.Json;
+    knownSecrets: string[];
+}
+interface PushOptions {
+    flow?: string;
+    platform?: 'web' | 'server';
+    /** The config from `loadRun`: the runtime does not read the input again. */
+    config?: Flow.Json;
+}
+/**
+ * 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 ToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+/**
+ * A full tool specification: metadata plus executable handler.
+ *
+ * Produced by each `create<Name>ToolSpec(...)` factory. The local server
+ * registers every spec through one path; a host without an `McpServer`
+ * drives the handlers directly.
+ */
+interface ToolSpec {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: ZodRawShape;
+    /** Wire-only output shape; absent where a tool answers in several shapes. */
+    outputSchema?: ZodRawShape;
+    annotations: ToolAnnotations;
+    handler: (input: unknown) => Promise<CallToolResult>;
+}
+
+/**
+ * Wraps a user-writable string in `<user_data>…</user_data>` so the chat
+ * assistant treats it as data, never as instructions. Inner `</user_data>`
+ * sequences are mangled (`</user_data_>`) so a malicious string can't close
+ * the envelope early.
+ *
+ * Idempotent: a string that is already a well-formed envelope with no inner
+ * `</user_data>` is returned unchanged.
+ */
+declare function wrapUserData(s: string): string;
+/**
+ * A listed record (a project, a flow summary, the project of a flow group)
+ * with its top-level display text wrapped as user data. Every other field
+ * stays literal, nested ones included, so a flow's `settings[].name` (an
+ * identifier the assistant passes back as `settingsName`) is never wrapped.
+ * Anything that is not an object passes through unchanged.
+ */
+declare function wrapListedRecord(value: unknown): unknown;
+/**
+ * The single redaction rule for every tool that echoes flow/deployment data
+ * back to the chat assistant:
+ *
+ *   wrap only the human-facing display `name`/`flowName` field and deep config
+ *   VALUES; leave all structural ids/keys literal everywhere.
+ *
+ * Redaction exists to neutralise user-CONTROLLED string VALUES so an injected
+ * `</user_data>` can't escape the envelope. It must NOT touch:
+ *   - structural keys (ids, slugs, dates, immutable identifiers): the LLM needs
+ *     to reference them verbatim, and wrapping them breaks get→edit→update
+ *     round-trips (e.g. wrapping `package`/`platform` corrupts a config the
+ *     user pushes straight back).
+ *   - tool-generated text (validation messages, error strings): that text is
+ *     authored by us, not echoed user input, so it stays literal like `path`.
+ *
+ * `STRUCTURAL_KEYS` is the union of every key whose value is an id/slug/date/
+ * immutable identifier rather than user free-text. Confirmed: none of these key
+ * names ever hold a genuine user-authored free-text value — `package`/`platform`
+ * are enum/package-name fields, `kind` is a discriminator, the rest are
+ * server-generated ids/timestamps.
+ */
+declare const STRUCTURAL_KEYS: Set<string>;
+/** Return `true` for keys that must stay literal (ids, slugs, dates, package,
+ *  platform). Use as the `skip` predicate for {@link redactNestedStrings}. */
+declare const keepStructural: (key: string) => boolean;
+interface RedactOptions {
+    /** Return `true` to skip wrapping for a given object key. Only invoked for
+     *  string values on object entries — not for array elements or scalar
+     *  roots. Use to keep ids / slugs / dates literal. */
+    skip?: (key: string) => boolean;
+}
+/**
+ * Recursively walks `value` and returns a deep-copied structure where every
+ * string leaf has been passed through `wrapUserData`. Pass `skip` to exclude
+ * specific keys (e.g. `id`) from wrapping.
+ */
+declare function redactNestedStrings<T>(value: T, opts?: RedactOptions): T;
+/**
+ * Recursively wraps ONLY the human-facing display text fields (`name`,
+ * `flowName`, `summary`), leaving every other value (ids, slugs, status, type,
+ * dates) literal. Use on tool responses that echo deployment/flow summaries
+ * where the only user-authored free-text is display text.
+ */
+declare function redactDisplayNames<T>(value: T): T;
+
+/**
+ * The specs both walkerOS MCP servers share, as plain data: five tools over a
+ * FlowRuntime, the knowledge resources and the prompts. This entry imports no
+ * CLI main entry, no bundler, no package manager and no MCP SDK, so a server
+ * process registers them on its own server; a host imports everything it
+ * needs (the specs, `RuntimeRefusal`, `FlowRuntime`, the envelope helpers)
+ * from `@walkeros/mcp/specs`, never from the main entry, which loads the CLI.
+ * Bundle, simulate and push are not here: they run caller code and belong to
+ * the local server only.
+ */
+
+/** The five tools both walkerOS MCP servers offer, keyed by name. */
+type LocalToolSpecs = {
+    flow_validate: ToolSpec;
+    flow_examples: ToolSpec;
+    flow_load: ToolSpec;
+    package_search: ToolSpec;
+    package_get: ToolSpec;
+};
+declare function createLocalToolSpecs(runtime: FlowRuntime): LocalToolSpecs;
+/**
+ * The reference resources plus the package schema template, in registration
+ * order. No openapi entry: the app owns that resource.
+ */
+declare const KNOWLEDGE_RESOURCES: readonly ResourceSpec[];
+/** add-step, setup-mapping, manage-contract. */
+declare const PROMPTS: readonly PromptSpec[];
+
+export { type BundleOptions, type FlowRuntime, KNOWLEDGE_RESOURCES, type LoadedRun, type LocalToolSpecs, PROMPTS, type PromptMessage, type PromptSpec, type PushOptions, type RedactOptions, type ResourceContent, type ResourceListEntry, type ResourceSpec, RuntimeRefusal, STRUCTURAL_KEYS, type SimulateOptions, type SimulateStepType, type StaticResourceSpec, type TemplateResourceSpec, type ToolAnnotations, type ToolSpec, createLocalToolSpecs, keepStructural, redactDisplayNames, redactNestedStrings, wrapListedRecord, wrapUserData };

package/dist/specs.js

@@ -0,0 +1,25 @@
+import {
+  KNOWLEDGE_RESOURCES,
+  PROMPTS,
+  RuntimeRefusal,
+  STRUCTURAL_KEYS,
+  createLocalToolSpecs,
+  keepStructural,
+  redactDisplayNames,
+  redactNestedStrings,
+  wrapListedRecord,
+  wrapUserData
+} from "./chunk-P6JS2RWY.js";
+export {
+  KNOWLEDGE_RESOURCES,
+  PROMPTS,
+  RuntimeRefusal,
+  STRUCTURAL_KEYS,
+  createLocalToolSpecs,
+  keepStructural,
+  redactDisplayNames,
+  redactNestedStrings,
+  wrapListedRecord,
+  wrapUserData
+};
+//# sourceMappingURL=specs.js.map

package/dist/specs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}