@animalabs/agent-framework 0.22.2 → 0.23.0

package/src/mcpl/types.ts

@@ -211,15 +211,22 @@ export interface McplChannelCapabilities {
 /**
  * Configuration for connecting to a single MCPL server.
  * Provided in FrameworkConfig.mcplServers[].
+ *
+ * Treat a submitted configuration and its nested values as immutable for as
+ * long as the server uses them. Apply changed settings with
+ * `restartMcplServer(id, newConfig)`; use `accessProvider` for a network
+ * server's rotating credentials (a stdio server's changed `env` goes through
+ * a restart with the new configuration).
  */
 export interface McplServerConfig {
   /** Unique server identifier */
   id: string;
 
   /**
-   * Command to spawn the server process (stdio transport). Mutually exclusive
-   * with `url`. Required for the stdio transport; omit it (and set `url`) for
-   * the WebSocket transport.
+   * Command to spawn the server process (stdio transport). Required for the
+   * stdio transport; omit it (and set `url`) for a network server, over
+   * WebSocket or HTTP. A configuration with both needs `transport` to say
+   * which one is used, and is refused without it.
    */
   command?: string;
 
@@ -238,27 +245,49 @@ export interface McplServerConfig {
   /**
    * Escape hatch: pass the host's entire environment (including secrets) to
    * the stdio child, as older versions did. Only for servers that genuinely
-   * need it. Default false.
+   * need it. Default false. Only `true` turns it on, and null counts as not
+   * set. For a stdio server, `create()`, `connectMcplServer` and
+   * `restartMcplServer` refuse any other value, such as a quoted "false". A
+   * WebSocket server never reads it.
    */
   inheritEnv?: boolean;
 
   /**
-   * WebSocket URL for the network transport (`ws://` or `wss://`). Mutually
-   * exclusive with `command`. When set (or `transport: 'websocket'`), the host
-   * dials this endpoint instead of spawning a process — newline-delimited
-   * JSON-RPC MCPL runs over the socket identically to stdio.
+   * URL for a network server, used instead of `command`. A configuration
+   * with both needs `transport` to say which one is used, and is refused
+   * without it. Its scheme decides the protocol family:
+   * - `ws://` or `wss://` is a legacy MCPL server over MCPL's WebSocket
+   *   binding. The host dials it and runs the same newline-delimited JSON-RPC
+   *   as over stdio.
+   * - `http://` or `https://` is a modern MCP (2026-07-28) server over
+   *   Streamable HTTP.
    */
   url?: string;
 
   /**
-   * Transport selector. Defaults to `'websocket'` when a bare `url` is given
-   * (no `command`), `'stdio'` otherwise. Set explicitly to disambiguate.
+   * Transport selector. When it is absent, a `command` means stdio and a
+   * `url` means the transport its scheme names; with both, it is required.
+   * When it is set, it decides which of the two is used and must agree with
+   * it: `'stdio'` needs a `command`, `'websocket'` a ws(s):// url and
+   * `'http'` an http(s):// url.
+   */
+  transport?: 'stdio' | 'websocket' | 'http';
+
+  /**
+   * Protocol family for a stdio (`command`) server. Defaults to `'legacy'`,
+   * which is MCP 2024-11-05 + MCPL and today's behavior. `'modern'` speaks
+   * MCP 2026-07-28 through the SDK-backed modern engine. A network server's
+   * family comes from its url's scheme, so setting this on one is a
+   * configuration error. There is no probing between families.
    */
-  transport?: 'stdio' | 'websocket';
+  protocol?: 'legacy' | 'modern';
 
   /**
-   * Bearer token for WebSocket auth. Appended to `url` as a `token` query
-   * parameter (`?token=…`) on connect. Ignored by the stdio transport.
+   * Bearer token for a network server. Where it travels depends on the
+   * transport: on a ws(s):// url it is appended as a `token` query parameter
+   * (`?token=…`) on connect; to an http(s):// server it is sent as an
+   * `Authorization: Bearer` header and never put in the url. A legacy stdio
+   * server ignores it, and a modern stdio server refuses it.
    */
   token?: string;
 
@@ -278,7 +307,9 @@ export interface McplServerConfig {
    * unstick). DEFAULT FALSE: no §6.2 capability path exists for it, and the
    * grant cannot confer it — only this config, decided by the operator, can
    * (PR #79 review blocker 9). The one legitimate fleet user is
-   * discord-mcpl's slash-command relay.
+   * discord-mcpl's slash-command relay. Only `true` turns it on, and null
+   * counts as not set. `create()`, `connectMcplServer` and
+   * `restartMcplServer` refuse any other value, such as a quoted "true".
    */
   allowHostCommands?: boolean;
 
@@ -351,6 +382,9 @@ export interface McplServerConfig {
    * When true, connect() resolves immediately (with null capabilities) if the
    * server is unavailable, and retries in the background.
    * Adapted from Anarchid/agent-framework@mcpl-module-proto.
+   * Only `true` turns it on, and null counts as not set. `create()`,
+   * `connectMcplServer` and `restartMcplServer` refuse any other value, such
+   * as a quoted "false".
    */
   reconnect?: boolean;
 
@@ -376,9 +410,20 @@ export interface McplServerConfig {
    * descriptive error, which the framework surfaces as a normal isError
    * tool_result. Request timeouts are the only bound for a stdio server that
    * stops reading its stdin without closing it: the host's writes are
-   * buffered, no error is raised, and the connection stays up. This is the
-   * timeout of every request that names none; the handshake's initialize has
-   * its own. Set 0 to disable. Default: 60000 (60 seconds).
+   * buffered, no error is raised, and the connection stays up. Under Bun they
+   * are also the only bound for one that closes its stdin, since Bun emits no
+   * 'error' event for the writes to it. requestTimeoutMs is the timeout of
+   * every request that names none; the handshake's initialize has its own.
+   * Set 0 to disable, except for channels/publish and the channels/open a
+   * delivery may send first, which keep the 60 s default: a publish's outcome
+   * is reported to the resident and recorded for its draft, so it must end.
+   * Default: 60000 (60 seconds). A value above 2^31−1 is refused: Node runs a
+   * longer timer after about 1 ms, so every request would time out at once.
+   *
+   * For a modern server it is one deadline per tool call, across every leg
+   * of the call, and must be an integer from 1 to 2^31−1. It can't be
+   * disabled: the SDK reads 0 as "time out now". At the deadline
+   * cancellation is requested and the outcome is unknown.
    */
   requestTimeoutMs?: number;
 
@@ -408,7 +453,10 @@ export interface McplServerConfig {
    * `toolLifecycle.*.tools`) match these full names; `enabledTools` /
    * `disabledTools` use the bare server-side names.
    *
-   * Must not collide with any module name or another server's prefix.
+   * Must not equal any module name or another server's prefix, nor meet
+   * another server's prefix: two prefixes meet when one is the other
+   * followed by `-`, or begins with the other followed by `--`, as `foo-`
+   * and `foo--bar` each meet `foo` (prefixesMeet, #265).
    */
   toolPrefix?: string;
 
@@ -1064,7 +1112,15 @@ export interface ChannelsListResult {
  * Spec Section 14.3.
  */
 export interface ChannelsOpenParams {
-  /** Exact registered id. Preferred over type/address matching. */
+  /**
+   * The exact registered id to open. Without it, a server matches by `type`
+   * and `address`, as before. A server that doesn't know the id should
+   * refuse rather than open another channel: the host fails an open whose
+   * answer names a different channel id, by its `channel.id` or a history
+   * item's `channelId`, compared exactly, as the server's traffic is. When
+   * that other channel is registered and decided closed, the host closes it
+   * again.
+   */
   channelId?: string;
   type: string;
   address?: Record<string, unknown>;
@@ -1319,6 +1375,8 @@ export interface McpToolDefinition {
   name: string;
   description?: string;
   inputSchema: Record<string, unknown>;
+  /** Server metadata for the tool (e.g. RFC-008 `mcpl/class` hints). */
+  _meta?: Record<string, unknown>;
 }
 
 /**

package/src/mcpl/visible-content.ts

@@ -31,6 +31,34 @@ export function isVisiblyEmptyContent(content: readonly unknown[] | null | undef
   return true;
 }
 
+/**
+ * What the converter (convertBlock, on every lane) shows for a text
+ * block whose text isn't a string, which only a nonconformant sender writes,
+ * so the agent learns that a block was there. It is the host's word, not the
+ * sender's, so it never makes content visible (isVisiblyEmptyConversion).
+ * The other blocks the converters can't show have theirs in references.ts.
+ */
+export const NON_STRING_TEXT_PLACEHOLDER = '[Text not shown: a text part arrived without readable text.]';
+
+/** A wire text block whose text isn't a string, which the converter shows as
+ *  NON_STRING_TEXT_PLACEHOLDER. */
+function isNonStringTextBlock(block: unknown): boolean {
+  if (!block || typeof block !== 'object') return false;
+  const b = block as { type?: unknown; text?: unknown };
+  return b.type === 'text' && typeof b.text !== 'string';
+}
+
+/**
+ * isVisiblyEmptyContent for content as a converter showed it, `wire` being
+ * the content as it arrived, block for block: a block shown as
+ * NON_STRING_TEXT_PLACEHOLDER counts as the nothing it held. So content that
+ * is only such blocks (or blank text) is still empty, and anything else is
+ * judged as the converted blocks show it, placeholders included.
+ */
+export function isVisiblyEmptyConversion(wire: readonly unknown[], converted: readonly unknown[]): boolean {
+  return isVisiblyEmptyContent(converted.filter((_, i) => !isNonStringTextBlock(wire[i])));
+}
+
 /** The server id and feature set the marker must carry. */
 export const SILENT_HEARTBEAT_SERVER_ID = 'heartbeat';
 export const SILENT_HEARTBEAT_FEATURE_SET = 'heartbeat';

package/src/module-registry.ts

@@ -1,11 +1,9 @@
-import type { JsStore } from '@animalabs/chronicle';
+import type { JsStateRegistration, JsStore } from '@animalabs/chronicle';
 import type { ContentBlock } from '@animalabs/membrane';
 import type {
   MessageId,
   MessageMetadata,
   MessageQuery,
-  MessageQueryResult,
-  StoredMessage,
   ContextInjection,
 } from '@animalabs/context-manager';
 import type {
@@ -22,9 +20,14 @@ import type {
   SpeechHandlerOptions,
   ProcessEvent,
   TraceEventListener,
+  ModuleMessage,
+  MessageQueryResult,
 } from './types/index.js';
+import { heldWriteId } from './held-writes.js';
 import type { Agent } from './agent.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, waitForShutdown } from './shutdown.js';
+import { logValue } from './mcpl/log-value.js';
+import { toolArgsProblems } from './tool-args.js';
 
 /** How the registry queues a module's event: its push names the module. A
  * `ProcessQueue` serves too, ignoring the name. */
@@ -44,6 +47,25 @@ export function isStateExistsError(err: unknown): boolean {
   return err instanceof Error && err.message.includes('State already exists');
 }
 
+/**
+ * Register a state, treating "already exists" as done: a store reopened after
+ * a restart already holds it. Every other failure is thrown here, where it
+ * happened, naming the state, with the store's own error as its cause. Each
+ * state the framework registers goes through this.
+ */
+export function ensureStateRegistered(
+  store: Pick<JsStore, 'registerState'>,
+  registration: JsStateRegistration,
+): void {
+  try {
+    store.registerState(registration);
+  } catch (error) {
+    if (isStateExistsError(error)) return;
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Registering state '${registration.id}' failed: ${reason}`, { cause: error });
+  }
+}
+
 /**
  * Hard ceiling for a single module's gatherContext budget, regardless of the
  * `contextTimeoutMs` it declares. gatherContext runs on the critical path of
@@ -81,6 +103,8 @@ export class ModuleRegistry {
 
   private modules: Map<string, Module> = new Map();
   private stopping = new Map<Module, Promise<void>>();
+  /** Module and namespace pairs already told that a system injection held a block that isn't text. */
+  private notShownWarned = new Set<string>();
   private moduleContexts: Map<string, ModuleContextImpl> = new Map();
   private speechHandlers: SpeechHandler[] = [];
   private store: JsStore;
@@ -89,7 +113,7 @@ export class ModuleRegistry {
   private addMessageFn: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
   private editMessageFn: (id: MessageId, content: ContentBlock[]) => void;
   private removeMessageFn: (id: MessageId) => void;
-  private getMessageFn: (id: MessageId) => StoredMessage | null;
+  private getMessageFn: (id: MessageId) => ModuleMessage | null;
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
 
   private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
@@ -113,7 +137,7 @@ export class ModuleRegistry {
       addMessage: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
       editMessage: (id: MessageId, content: ContentBlock[]) => void;
       removeMessage: (id: MessageId) => void;
-      getMessage: (id: MessageId) => StoredMessage | null;
+      getMessage: (id: MessageId) => ModuleMessage | null;
       queryMessages: (filter: MessageQuery) => MessageQueryResult;
       /** Called with the pushing module's name. */
       pushEvent: (event: ProcessEvent, moduleName?: string) => void;
@@ -146,14 +170,7 @@ export class ModuleRegistry {
 
     // Register module state in store
     const stateId = this.getStateId(module.name);
-    try {
-      this.store.registerState({
-        id: stateId,
-        strategy: 'snapshot',
-      });
-    } catch {
-      // State already registered (from previous run)
-    }
+    ensureStateRegistered(this.store, { id: stateId, strategy: 'snapshot' });
 
     // Check if this is a restart (state exists)
     const existingState = this.store.getStateJson(stateId);
@@ -285,8 +302,8 @@ export class ModuleRegistry {
    * model. The result is checked and read once, in its JSON form
    * ({@link storableToolResult}).
    */
-  async storableToolCall(call: ToolCall): Promise<ToolResult> {
-    return storableToolResult(call, await this.handleToolCall(call));
+  async storableToolCall(call: ToolCall, options: { definition?: ToolDefinition } = {}): Promise<ToolResult> {
+    return storableToolResult(call, await this.handleToolCall(call, options));
   }
 
   /**
@@ -294,8 +311,14 @@ export class ModuleRegistry {
    * result, unchecked, as it returned it, for a caller that uses the result
    * in process (`ModuleContext.callTool`, `executeToolCall`, or a host
    * calling the registry). A module's throw is answered as an error result.
+   * A call whose input isn't an object, or lacks a key the tool's schema
+   * requires, is answered before the module runs, with an error result that
+   * opens "Nothing was done:" and names what to send (toolArgsProblems).
+   * A caller that has already resolved the tool's definition, as the `utils`
+   * tool has a utility's, passes it as `definition`, and it's checked against
+   * that one.
    */
-  async handleToolCall(call: ToolCall): Promise<ToolResult> {
+  async handleToolCall(call: ToolCall, options: { definition?: ToolDefinition } = {}): Promise<ToolResult> {
     // Parse module--tool name
     const sepIndex = call.name.indexOf('--');
     if (sepIndex === -1) {
@@ -318,15 +341,37 @@ export class ModuleRegistry {
       };
     }
 
-    // Create a call with the un-prefixed name (preserving caller identity)
+    // Create a call with the un-prefixed name (preserving caller identity and turn)
     const moduleCall: ToolCall = {
       id: call.id,
       name: toolName,
       input: call.input,
       callerAgentName: call.callerAgentName,
+      ...(call.callerTurnId !== undefined ? { callerTurnId: call.callerTurnId } : {}),
     };
 
     try {
+      // The call against the tool's declared schema, before the module runs:
+      // a missing required argument is refused with what to send, where the
+      // handler would otherwise fail deep inside, or run without it. Values
+      // aren't checked here, since a handler may take more than its schema
+      // can say (toolArgsProblems). The module's own listing runs inside the
+      // try, so its throw is answered like any other. Utilities are listed
+      // only for a name the tools don't have, so a utility listing that
+      // throws or is slow reaches only calls to such names: a utility called
+      // by its own name, and a name the module answers without declaring it.
+      // A caller that passes `definition` lists nothing.
+      const definition = options.definition
+        ?? module.getTools().find((tool) => tool.name === toolName)
+        ?? module.getUtilities?.()?.find((tool) => tool.name === toolName);
+      const problems = toolArgsProblems(call.input, definition?.inputSchema);
+      if (problems.length > 0) {
+        return {
+          success: false,
+          error: `Nothing was done: ${call.name} ${problems.join('; ')}.`,
+          isError: true,
+        };
+      }
       return await module.handleToolCall(moduleCall);
     } catch (error) {
       return thrownResult(error);
@@ -425,7 +470,10 @@ export class ModuleRegistry {
       );
       let timer: ReturnType<typeof setTimeout> | undefined;
       const promise = Promise.race([
-        module.gatherContext(agentName).then(r => injections.push(...r)),
+        module.gatherContext(agentName).then(r => {
+          injections.push(...r);
+          this.noteBlocksNotShown(module.name, r);
+        }),
         new Promise<void>((_, rej) => {
           timer = setTimeout(
             () => rej(new Error(`gatherContext timed out after ${budgetMs}ms`)),
@@ -443,6 +491,28 @@ export class ModuleRegistry {
     return injections;
   }
 
+  /**
+   * The system prompt is text, so an agent given a `system` injection reads
+   * a line in place of each of its blocks that isn't text (the agent's
+   * buildSystemPrompt), though `ContextInjection`'s content may be any
+   * block. The module meant those blocks for the model, so its operator is
+   * told, once per module and namespace, as the module's injections are
+   * gathered, whichever agents are given them.
+   */
+  private noteBlocksNotShown(moduleName: string, injections: ContextInjection[]): void {
+    for (const injection of injections) {
+      if (injection.position !== 'system' || !injection.content.some((block) => block.type !== 'text')) continue;
+      const key = `${moduleName}\u0000${injection.namespace}`;
+      if (this.notShownWarned.has(key)) continue;
+      this.notShownWarned.add(key);
+      console.error(
+        `[${moduleName}] gatherContext: a system injection in namespace ${logValue(injection.namespace)} holds a block that ` +
+          "isn't text, which the system prompt can't carry, so an agent given the injection reads a line in place of each such block; " +
+          'this line prints once per module and namespace while the host runs',
+      );
+    }
+  }
+
   /**
    * Tell modules an agent's tool batch completed (see
    * Module.onToolBatchComplete). Hooks run in parallel, each awaited up to
@@ -542,7 +612,7 @@ class ModuleContextImpl implements ModuleContext {
   private addMessageFn: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
   private editMessageFn: (id: MessageId, content: ContentBlock[]) => void;
   private removeMessageFn: (id: MessageId) => void;
-  private getMessageFn: (id: MessageId) => StoredMessage | null;
+  private getMessageFn: (id: MessageId) => ModuleMessage | null;
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
   private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
@@ -562,7 +632,7 @@ class ModuleContextImpl implements ModuleContext {
     addMessage: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId,
     editMessage: (id: MessageId, content: ContentBlock[]) => void,
     removeMessage: (id: MessageId) => void,
-    getMessage: (id: MessageId) => StoredMessage | null,
+    getMessage: (id: MessageId) => ModuleMessage | null,
     queryMessages: (filter: MessageQuery) => MessageQueryResult,
     pushEvent: (event: ProcessEvent, moduleName?: string) => void,
     onTrace: (listener: TraceEventListener) => () => void,
@@ -640,18 +710,12 @@ class ModuleContextImpl implements ModuleContext {
     name: string,
     opts?: { deltaSnapshotEvery?: number; fullSnapshotEvery?: number }
   ): void {
-    const id = this.logStateId(name);
-    try {
-      this.store.registerState({
-        id,
-        strategy: 'append_log',
-        deltaSnapshotEvery: opts?.deltaSnapshotEvery ?? 100,
-        fullSnapshotEvery: opts?.fullSnapshotEvery ?? 20,
-      });
-    } catch (err) {
-      if (!isStateExistsError(err)) throw err;
-      // Already registered (previous run) — idempotent path.
-    }
+    ensureStateRegistered(this.store, {
+      id: this.logStateId(name),
+      strategy: 'append_log',
+      deltaSnapshotEvery: opts?.deltaSnapshotEvery ?? 100,
+      fullSnapshotEvery: opts?.fullSnapshotEvery ?? 20,
+    });
     this.registeredLogStates.add(name);
   }
 
@@ -695,10 +759,13 @@ class ModuleContextImpl implements ModuleContext {
   ): MessageId {
     const id = this.addMessageFn(participant, content, metadata);
 
-    // Track external ID if provided
+    // Track external ID if provided. A write the framework holds keeps '',
+    // as it did before held writes had handles: the map is module state an
+    // earlier release reads back, and a handle is no id to it.
+    // findMessageByExternalId finds the held write by its external id.
     if (metadata?.external) {
       const key = `${metadata.external.source}:${metadata.external.id}`;
-      this.externalIdMap.set(key, id);
+      this.externalIdMap.set(key, heldWriteId(id) === undefined ? id : '');
       // Persist the mapping
       this.persistExternalIdMap();
     }
@@ -724,10 +791,33 @@ class ModuleContextImpl implements ModuleContext {
 
   findMessageByExternalId(source: string, externalId: string): MessageId | null {
     const key = `${source}:${externalId}`;
-    return this.externalIdMap.get(key) ?? null;
+    const entry = this.externalIdMap.get(key);
+    if (entry === undefined) return null;
+    // A stored id answers while the store holds its row, and once the row is
+    // gone the entry goes, as removeMessage drops it. The '' a held write
+    // keeps here (addMessage) names no row, so the message is looked up in
+    // the store by its external id, held rows included, and the first row
+    // found is taken, as context-manager's findByExternalId takes it: a held
+    // row answers by its handle and leaves the entry as it is, and a stored
+    // row's id becomes the entry. With nothing found, '' stays, as earlier
+    // releases kept it: in a module's start(), the writes the last process
+    // held don't show yet, since create() restores them after the modules
+    // start, and a write that shows later finds its entry.
+    if (entry !== '') {
+      if (this.getMessageFn(entry)) return entry;
+      this.externalIdMap.delete(key);
+      this.persistExternalIdMap();
+      return null;
+    }
+    const row = this.queryMessagesFn({ source, externalIds: [externalId] }).messages[0];
+    if (row?.held) return row.id;
+    if (!row) return null;
+    this.externalIdMap.set(key, row.id);
+    this.persistExternalIdMap();
+    return row.id;
   }
 
-  getMessage(id: MessageId): StoredMessage | null {
+  getMessage(id: MessageId): ModuleMessage | null {
     return this.getMessageFn(id);
   }
 

package/src/modules/api/index.ts

@@ -5,6 +5,7 @@
  * into conversation messages and inference requests.
  */
 
+import { unknownToolMessage } from '../unknown-tool.js';
 import type {
   Module,
   ModuleContext,
@@ -38,9 +39,9 @@ export class ApiModule implements Module {
     // Nothing to clean up
   }
 
-  async handleToolCall(_call: ToolCall): Promise<ToolResult> {
+  async handleToolCall(call: ToolCall): Promise<ToolResult> {
     // API module has no tools
-    return { success: false, error: 'Unknown tool' };
+    return { success: false, error: unknownToolMessage(this.name, call.name, this.getTools()), isError: true };
   }
 
   async onProcess(event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {