akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/signal/mcp/McpDocument.ts

@@ -0,0 +1,286 @@
+import { capitalize, isMcpDescribableArg, mcpHintsOf, mcpRefusalOf } from "akanjs/common";
+import { FetchClient } from "akanjs/fetch";
+import { type AgentCandidate, AgentCatalogue, type AgentRefusal, type AgentUndescribed } from "../agent";
+import { type JsonSchema, JsonSchemaBuilder } from "../schema";
+import type { SerializedArg, SerializedEndpoint, SerializedSignal } from "../types";
+import { McpUriTemplate } from "./McpUriTemplate";
+import type { McpPrompt, McpResource, McpResourceTemplate, McpTool, McpToolAnnotations } from "./mcpProtocol";
+
+export interface McpDocumentOptions {
+  resolveDescription?: (key: string) => string | undefined;
+  excludeSignals?: string[];
+  /**
+   * Drops every mutation from the catalogue regardless of what it opted into. Off by default: the endpoint's own
+   * an endpoint's guards are the decision, and a second switch that silently unlists a published endpoint gives
+   * its author no way to see why. This is the read-only-deployment valve.
+   */
+  readOnly?: boolean;
+}
+
+export interface McpExposedEndpoint {
+  refName: string;
+  key: string;
+  endpoint: SerializedEndpoint;
+}
+
+/**
+ * A candidate this catalogue did not publish. The bookkeeping is audience-independent and lives on
+ * `AgentCatalogue`; these are the MCP names for it.
+ */
+export type McpRefusal = AgentRefusal;
+export type McpUndescribed = AgentUndescribed;
+
+/**
+ * Turns the serialized signal registry into the three MCP catalogues and answers the lookups `tools/call` and
+ * `resources/read` need. Pure: no IO and no DI — the sibling of `createOpenApiDocument`.
+ */
+export class McpDocument {
+  /**
+   * An array cannot be `structuredContent` — the spec types it as an object — so a list result is wrapped under
+   * this key and `outputSchema` is shaped to match. Both halves must agree, which is why they live together.
+   */
+  static readonly listKey = "items";
+
+  readonly tools: McpTool[];
+  readonly prompts: McpPrompt[];
+  readonly resourceTemplates: McpResourceTemplate[];
+  /** Every readable thing is addressed by a template, so there are no fixed resources to enumerate. */
+  readonly resources: McpResource[] = [];
+  /**
+   * Every candidate that was not published, with the sentence saying why — the rejections are fail-closed by
+   * design, and an author whose endpoint is missing otherwise has nowhere to look but the framework source.
+   */
+  readonly refusals: McpRefusal[];
+  /** What is published with no description of its own, which is the field a model picks a tool by. */
+  readonly undescribed: McpUndescribed[];
+  readonly #schema = new JsonSchemaBuilder({ refPrefix: "#/$defs/" });
+  #allSchemas: Record<string, JsonSchema> | null = null;
+  #readSchemas: Record<string, JsonSchema> | null = null;
+  readonly #options: McpDocumentOptions;
+  readonly #catalogue: AgentCatalogue;
+  readonly #byToolName = new Map<string, McpExposedEndpoint>();
+  readonly #byPromptName = new Map<string, { exposed: McpExposedEndpoint; prompt: McpPrompt }>();
+  /** Keyed by endpoint key: what is addressable, and by exactly which uri. */
+  readonly #templates = new Map<string, string>();
+
+  constructor(serializedSignal: Record<string, SerializedSignal>, options: McpDocumentOptions = {}) {
+    this.#options = options;
+    this.#catalogue = new AgentCatalogue(options);
+    const { tools, prompts } = this.#collect(serializedSignal);
+    this.refusals = this.#catalogue.refusals;
+    this.tools = tools.map((item) => this.#tool(item));
+    this.prompts = prompts.map((item) => {
+      const prompt = this.#prompt(item);
+      this.#byPromptName.set(item.key, { exposed: item, prompt });
+      return prompt;
+    });
+    this.resourceTemplates = tools.flatMap((item) => {
+      const uriTemplate = this.#templates.get(item.key);
+      return uriTemplate ? [this.#template(item, uriTemplate)] : [];
+    });
+    
+    this.undescribed = this.#catalogue.undescribed;
+  }
+
+  findTool(name: string): McpExposedEndpoint | undefined {
+    return this.#byToolName.get(name);
+  }
+
+  /** Returns the catalogue entry alongside the endpoint: `prompts/get` validates against the published one. */
+  findPrompt(name: string) {
+    return this.#byPromptName.get(name);
+  }
+
+  /**
+   * Resolves a URI only when the endpoint behind it was published as a template. An endpoint that was never
+   * advertised has to fail here rather than fall through to its guards: opting out of MCP means keeping a thing
+   * off the wire entirely, not merely making it refuse.
+   */
+  resolveResource(uri: string) {
+    const target = McpUriTemplate.parse(uri);
+    if (!target || !this.#templates.has(target.endpointKey)) return null;
+    const exposed = this.#byToolName.get(target.endpointKey);
+    return exposed ? { exposed, args: target.args } : null;
+  }
+
+  static structuredContent(endpoint: SerializedEndpoint, value: unknown) {
+    if (!endpoint.returns.modelType) return undefined;
+    if (endpoint.returns.arrDepth) return { [McpDocument.listKey]: value };
+
+    return value === null || value === undefined ? undefined : value;
+  }
+
+  /**
+   * Which of the catalogue's candidates this audience takes, and in what shape.
+   *
+   * The enumeration and the naming policy are `AgentCatalogue`'s — every audience walks the same registry and
+   * holds one name per entry. What is MCP's own is only this: that every candidate is published unless a rule
+   * refuses it, and that a published one becomes a tool, a prompt, and sometimes an addressable uri.
+   */
+  #collect(serializedSignal: Record<string, SerializedSignal>): {
+    tools: McpExposedEndpoint[];
+    prompts: McpExposedEndpoint[];
+  } {
+    const tools: McpExposedEndpoint[] = [];
+    const prompts: McpExposedEndpoint[] = [];
+    for (const candidate of AgentCatalogue.candidates(serializedSignal, {
+      excludeSignals: this.#options.excludeSignals,
+    })) {
+      const item: McpExposedEndpoint = {
+        refName: candidate.refName,
+        key: candidate.key,
+        endpoint: candidate.endpoint,
+      };
+      
+      const reason = mcpRefusalOf(item.endpoint, { readOnly: this.#options.readOnly });
+      if (reason) {
+        this.#catalogue.refuse(item.key, reason);
+        continue;
+      }
+      if (!this.#catalogue.claim(item.key)) continue;
+      if (item.endpoint.type === "prompt") {
+        
+        prompts.push(item);
+        continue;
+      }
+
+      const uriTemplate = McpDocument.#addressable(candidate)
+        ? McpDocument.#uriTemplate(item.refName, item.key, item.endpoint)
+        : undefined;
+      this.#byToolName.set(item.key, item);
+      if (uriTemplate) this.#templates.set(item.key, uriTemplate);
+      tools.push(item);
+    }
+    return { tools, prompts };
+  }
+
+  /**
+   * Whether this candidate is one of the generated reads that has an `akan://` address.
+   *
+   * Only the list side of a slice is addressable; an insight is an aggregate with nothing to point a URI at, and a
+   * custom endpoint has no generated key shape to build one from.
+   */
+  static #addressable({ origin, refName, key, baseVerb }: AgentCandidate): boolean {
+    if (origin === "base") return baseVerb === "get";
+    if (origin === "slice") return key.startsWith(`${refName}List`);
+    return false;
+  }
+
+  #tool({ refName, key, endpoint }: McpExposedEndpoint): McpTool {
+    const { paramArgs, searchArgs, bodyArgs } = FetchClient.classifyHttpArgs(endpoint.args);
+    
+    const args = [...paramArgs, ...searchArgs, ...bodyArgs].filter(isMcpDescribableArg);
+    const properties = Object.fromEntries(args.map((arg) => [arg.name, this.#argSchema(refName, key, arg)]));
+
+    const required = [...paramArgs, ...bodyArgs]
+      .filter((arg) => isMcpDescribableArg(arg) && !arg.nullable)
+      .map((arg) => arg.name);
+    const outputSchema = this.#outputSchema(endpoint);
+    return {
+      name: key,
+      ...this.#catalogue.entryTexts(refName, key),
+      inputSchema: {
+        type: "object",
+        properties,
+        ...(required.length ? { required } : {}),
+        additionalProperties: false,
+        ...this.#defs(properties),
+      },
+      ...(outputSchema ? { outputSchema } : {}),
+      annotations: mcpHintsOf(key, endpoint) satisfies McpToolAnnotations,
+    };
+  }
+
+  /**
+   * A prompt's arguments are a flat string map on the wire, so there is no schema to publish — only names,
+   * descriptions and which ones must be filled. A `param` is a path segment and always required; a `search` is
+   * the only way to declare an optional one.
+   */
+  #prompt({ refName, key, endpoint }: McpExposedEndpoint): McpPrompt {
+    const args = endpoint.args.filter((arg) => arg.type === "param" || arg.type === "search");
+    return {
+      name: key,
+      ...this.#catalogue.entryTexts(refName, key),
+      ...(args.length
+        ? {
+            arguments: args.map((arg) => {
+              const description = this.#options.resolveDescription?.(`${refName}.signal.${key}.arg.${arg.name}.desc`);
+              return {
+                name: arg.name,
+                ...(description ? { description } : {}),
+                required: arg.type === "param",
+              };
+            }),
+          }
+        : {}),
+    };
+  }
+
+  #outputSchema(endpoint: SerializedEndpoint) {
+
+    if (!endpoint.returns.modelType) return undefined;
+
+    if (endpoint.returns.nullable && !endpoint.returns.arrDepth) return undefined;
+    const returns = this.#schema.returns(endpoint.returns);
+    const schema = endpoint.returns.arrDepth
+      ? {
+          type: "object",
+          properties: { [McpDocument.listKey]: returns },
+          required: [McpDocument.listKey],
+          additionalProperties: false,
+        }
+      : returns;
+
+    return { ...schema, ...this.#defs(schema, { readable: true }) };
+  }
+
+  #defs(seed: unknown, { readable = false } = {}) {
+    const defs = this.#schema.referencedSchemas(seed, this.#modelSchemas(readable));
+
+    return Object.keys(defs).length ? { $defs: defs } : {};
+  }
+
+  /**
+   * Every registered model, built once per shape for the whole document. Narrowing runs twice per tool — input
+   * schema and output schema — so deriving the full set inside each call rebuilt every model in the app 2N times.
+   */
+  #modelSchemas(readable: boolean) {
+    if (!readable) {
+      this.#allSchemas ??= this.#schema.allModelSchemas();
+      return this.#allSchemas;
+    }
+    this.#readSchemas ??= this.#schema.allModelSchemas({ readable: true });
+    return this.#readSchemas;
+  }
+
+  #argSchema(refName: string, key: string, arg: SerializedArg) {
+    const description = this.#options.resolveDescription?.(`${refName}.signal.${key}.arg.${arg.name}.desc`);
+    return {
+      ...this.#schema.arg(arg),
+      ...(description ? { description } : {}),
+      ...(arg.example !== undefined ? { examples: [arg.example] } : {}),
+    };
+  }
+
+  #template({ refName, key }: McpExposedEndpoint, uriTemplate: string): McpResourceTemplate {
+    return {
+      uriTemplate,
+      name: key,
+      ...this.#catalogue.entryTexts(refName, key),
+      mimeType: "application/json",
+    };
+  }
+
+  static #uriTemplate(refName: string, key: string, endpoint: SerializedEndpoint) {
+    if (key === refName) return McpUriTemplate.model(refName);
+    if (key === `light${capitalize(refName)}`) return McpUriTemplate.light(refName);
+    const listPrefix = `${refName}List`;
+    if (!key.startsWith(listPrefix)) return undefined;
+    const suffix = key.slice(listPrefix.length);
+
+    const argNames = endpoint.args
+      .filter((arg) => (arg.type === "param" || arg.type === "search") && isMcpDescribableArg(arg))
+      .map((arg) => arg.name);
+    return McpUriTemplate.list(refName, suffix ? `${suffix.charAt(0).toLowerCase()}${suffix.slice(1)}` : "", argNames);
+  }
+}

package/signal/mcp/McpProgress.ts

@@ -0,0 +1,106 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface McpProgressOption {
+  /** Denominator for the ratio a client renders. Omit when the amount of work is not known up front. */
+  total?: number;
+  /** One short line describing the current step. Shown to the user, so keep it prose rather than a status code. */
+  message?: string;
+}
+
+export interface McpProgressReport extends McpProgressOption {
+  progress: number;
+}
+
+/**
+ * The progress channel for one streamed MCP call.
+ *
+ * Reached through `AsyncLocalStorage` rather than a parameter so an endpoint reports progress from wherever the
+ * work actually happens — a service, an adapter, a loop several frames down — without every signature between
+ * here and there growing a channel argument. Outside a streamed call `report` is a no-op, so the same endpoint
+ * code runs unchanged over plain HTTP, a websocket, or a test.
+ */
+export class McpProgress {
+  static readonly #storage = new AsyncLocalStorage<McpProgress>();
+
+  /**
+   * Reports progress for the call running on this stack. Silent when nothing is listening, which is every call
+   * that did not ask for a stream.
+   */
+  static report(progress: number, option: McpProgressOption = {}) {
+    const channel = McpProgress.#storage.getStore();
+    if (channel) channel.#push(progress, option);
+  }
+
+  /** True while the caller is streaming, so an expensive progress message can be skipped when nobody reads it. */
+  static get streaming() {
+    return !!McpProgress.#storage.getStore();
+  }
+
+  static async run<T>(channel: McpProgress, exec: () => Promise<T>): Promise<T> {
+    return await McpProgress.#storage.run(channel, exec);
+  }
+
+  readonly #queue: McpProgressReport[] = [];
+  readonly #abort = new AbortController();
+  #wake: (() => void) | null = null;
+  #start: (() => void) | null = null;
+  #ended = false;
+
+  /** Resolves on the first report and never otherwise — a call that reports nothing has nothing to stream. */
+  readonly started: Promise<void>;
+
+  constructor() {
+    this.started = new Promise<void>((resolve) => {
+      this.#start = resolve;
+    });
+  }
+
+  /**
+   * Aborted when the client closes the response stream, which is how cancellation is signalled over this
+   * transport. Long-running work may watch it; the framework cannot force an `exec` already in flight to stop.
+   */
+  get signal() {
+    return this.#abort.signal;
+  }
+
+  /** Yields every report until the call finishes. Buffered ones come out first, so none is lost to a late reader. */
+  async *reports(): AsyncGenerator<McpProgressReport> {
+
+    while (!this.#ended || this.#queue.length) {
+      for (const report of this.#queue.splice(0)) yield report;
+
+      if (this.#ended || this.#queue.length) continue;
+      await new Promise<void>((resolve) => {
+        this.#wake = resolve;
+      });
+    }
+  }
+
+  end() {
+    this.#ended = true;
+    this.#release();
+  }
+
+  abort() {
+    this.#abort.abort();
+    this.end();
+  }
+
+  #push(progress: number, { total, message }: McpProgressOption) {
+    
+    if (this.#ended) return;
+    this.#queue.push({
+      progress,
+      ...(total === undefined ? {} : { total }),
+      ...(message ? { message } : {}),
+    });
+    this.#start?.();
+    this.#start = null;
+    this.#release();
+  }
+
+  #release() {
+    this.#wake?.();
+    this.#wake = null;
+  }
+}

package/signal/mcp/McpUriTemplate.ts

@@ -0,0 +1,85 @@
+import { capitalize } from "akanjs/common";
+
+export interface McpResourceTarget {
+  endpointKey: string;
+  args: Record<string, string | string[]>;
+}
+
+/**
+ * Two-way map between an `akan://` resource URI and the endpoint that answers it.
+ *
+ * Parsing is done by hand rather than through `URL`: `akan:` is a non-special scheme, and how a runtime
+ * normalizes the authority of one (case, percent-decoding) is exactly where a camelCase refName like
+ * `agentSession` would quietly stop matching its model.
+ */
+export class McpUriTemplate {
+  static readonly scheme = "akan";
+  /** Reserved second segment: a model id may never take one of these values, and none is a valid ObjectId. */
+  static readonly #reserved = new Set(["light", "list"]);
+
+  static model(refName: string) {
+    return `${McpUriTemplate.scheme}://${refName}/{${refName}Id}`;
+  }
+  static light(refName: string) {
+    return `${McpUriTemplate.scheme}://${refName}/light/{${refName}Id}`;
+  }
+  /**
+   * The model's own unfiltered list is the bare `…/list`, never `…/list/<token>`. A named slice occupies the
+   * third segment, and a slice key is an author-chosen identifier — so any token put there for the root list
+   * would be one a slice could also be called, and the two would publish the same uri with only one of them
+   * readable. `list` in the *second* segment is already reserved against a model id, so there is nothing to
+   * collide with here.
+   */
+  static list(refName: string, sliceKey: string, argNames: string[]) {
+    const base = `${McpUriTemplate.scheme}://${refName}/list${sliceKey ? `/${sliceKey}` : ""}`;
+    return argNames.length ? `${base}{?${argNames.join(",")}}` : base;
+  }
+
+  static parse(uri: string): McpResourceTarget | null {
+    const authority = `${McpUriTemplate.scheme}://`;
+    if (!uri.startsWith(authority)) return null;
+    const rest = uri.slice(authority.length);
+    const queryAt = rest.indexOf("?");
+    const segments = (queryAt === -1 ? rest : rest.slice(0, queryAt)).split("/");
+    if (segments.some((segment) => !segment)) return null;
+    const search = new URLSearchParams(queryAt === -1 ? "" : rest.slice(queryAt + 1));
+    const decoded = McpUriTemplate.#decode(segments);
+    if (!decoded) return null;
+    const [refName, second, third] = decoded as [string, string?, string?];
+
+    if (segments.length === 2 && second && !McpUriTemplate.#reserved.has(second))
+      return { endpointKey: refName, args: { [`${refName}Id`]: second } };
+    if (segments.length === 2 && second === "list")
+      return { endpointKey: `${refName}List`, args: McpUriTemplate.#searchArgs(search) };
+    if (segments.length === 3 && second === "light" && third)
+      return { endpointKey: `light${capitalize(refName)}`, args: { [`${refName}Id`]: third } };
+    if (segments.length === 3 && second === "list" && third)
+      return { endpointKey: `${refName}List${capitalize(third)}`, args: McpUriTemplate.#searchArgs(search) };
+    return null;
+  }
+
+  /**
+   * A percent escape the decoder rejects (`akan://banner/%`) makes the uri unreadable, which is the same answer as
+   * a uri naming nothing: `resources/read` says `Unknown resource`. Left to throw, `decodeURIComponent`'s `URIError`
+   * reached the router's catch and became "the server failed" with a stack in the log — on a method an agent may
+   * call with any string it likes, so it was a log-spam path as well as a wrong verdict. The query half needs no
+   * such guard: `URLSearchParams` reads a bad escape as literal text.
+   */
+  static #decode(segments: string[]) {
+    try {
+      return segments.map(decodeURIComponent);
+    } catch {
+      return null;
+    }
+  }
+
+  /** Repeated keys become an array so an `arrDepth` search arg round-trips through `{?statuses}` form expansion. */
+  static #searchArgs(search: URLSearchParams): Record<string, string | string[]> {
+    const args: Record<string, string | string[]> = {};
+    for (const key of new Set(search.keys())) {
+      const values = search.getAll(key);
+      args[key] = values.length > 1 ? values : (values[0] ?? "");
+    }
+    return args;
+  }
+}