@animalabs/agent-framework 0.21.1 → 0.22.0

package/src/mcpl/types.ts

@@ -282,10 +282,16 @@ export interface McplServerConfig {
    */
   allowHostCommands?: boolean;
 
-  /** Feature sets to enable on connect */
+  /**
+   * Feature sets to enable on connect (`.`-segment wildcards). Omitted:
+   * every declared set is a candidate. `[]`: none. Either way a set is
+   * enabled only if its declared `uses` are recognized capabilities the
+   * grant covers (§6.4) — a set declaring no `uses` stays disabled even when
+   * listed here (logged, and traced as `mcpl:feature-set-disabled`).
+   */
   enabledFeatureSets?: string[];
 
-  /** Feature sets to explicitly disable on connect */
+  /** Feature sets to explicitly disable on connect (wins over enabledFeatureSets). */
   disabledFeatureSets?: string[];
 
   /**
@@ -388,11 +394,15 @@ export interface McplServerConfig {
 
   /**
    * Tool name prefix for this server's tools.
-   * Tools are exposed as `{toolPrefix}:{toolName}`.
+   * Tools are exposed as `{toolPrefix}--{toolName}`.
    *
-   * Default: `mcpl:{id}` (e.g., `mcpl:zk:lobby_start_game`).
+   * Default: `mcpl--{id}` (e.g., `mcpl--zk--lobby_start_game`).
    * Set to the server ID for cleaner names (e.g., `toolPrefix: 'zk'`
-   * gives `zk:lobby_start_game`).
+   * gives `zk--lobby_start_game`).
+   *
+   * Tool-name patterns elsewhere (`toolClassOverrides` keys,
+   * `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.
    */

package/src/mcpl/visible-content.ts

@@ -0,0 +1,57 @@
+/**
+ * Visibly-empty MCPL content, and the one empty push that is allowed.
+ *
+ * A push event or channel message whose content gives the model nothing to
+ * read cannot be shown: the request sanitizer strips empty text blocks and
+ * drops the message they leave empty, so a wake queued for it presents the
+ * model with `[Continue]` or with an older message re-presented as the newest.
+ * That is a wake with no visible cause, and it invites the model to invent
+ * one. Such content is rejected at the MCPL boundary, and the store/wake site
+ * drops it as a backstop.
+ *
+ * The exception is the silent-heartbeat marker: the heartbeat server's own
+ * scheduled tick, which wakes with ephemeral host-supplied context instead of
+ * a stored message.
+ */
+
+/**
+ * True when `content` holds nothing the model would see: no non-text block,
+ * and no text block whose text has a non-whitespace character. Mirrors the
+ * request sanitizer, which drops text that is not a string or trims to ''.
+ * Accepts MCPL wire blocks and converted membrane blocks alike.
+ */
+export function isVisiblyEmptyContent(content: readonly unknown[] | null | undefined): boolean {
+  if (!Array.isArray(content)) return true;
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    const b = block as { type?: unknown; text?: unknown };
+    if (b.type !== 'text') return false;
+    if (typeof b.text === 'string' && b.text.trim() !== '') return false;
+  }
+  return true;
+}
+
+/** The server id and feature set the marker must carry. */
+export const SILENT_HEARTBEAT_SERVER_ID = 'heartbeat';
+export const SILENT_HEARTBEAT_FEATURE_SET = 'heartbeat';
+
+/**
+ * The exact silent-heartbeat marker: an empty push from the `heartbeat`
+ * server on its `heartbeat` feature set, with `origin.source === 'heartbeat'`
+ * and `origin.silent === true`. Anything else that is empty is not a silent
+ * tick — arbitrary servers cannot claim the silent path by setting
+ * `origin.silent`, and a marker that carries content is ordinary content.
+ */
+export function isSilentHeartbeatMarker(event: {
+  serverId: string;
+  featureSet?: string;
+  origin?: Record<string, unknown> | null;
+  content: readonly unknown[] | null | undefined;
+}): boolean {
+  return event.serverId === SILENT_HEARTBEAT_SERVER_ID
+    && event.featureSet === SILENT_HEARTBEAT_FEATURE_SET
+    && event.origin?.source === 'heartbeat'
+    && event.origin?.silent === true
+    && Array.isArray(event.content)
+    && event.content.length === 0;
+}

package/src/module-registry.ts

@@ -24,6 +24,7 @@ import type {
   TraceEventListener,
 } from './types/index.js';
 import type { Agent } from './agent.js';
+import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, waitForShutdown } from './shutdown.js';
 
 const MODULE_STATE_PREFIX = 'modules/';
 
@@ -46,6 +47,15 @@ export function isStateExistsError(err: unknown): boolean {
  */
 const MAX_CONTEXT_TIMEOUT_MS = 30_000;
 
+/**
+ * Bound on each module's onToolBatchComplete. The hook runs inside the
+ * framework's sequential event loop, so a wedged module would stall every
+ * agent's events, not just its own round; past this the round goes on without
+ * it. A module with its own semantic deadline (the workspace scan's) sets it
+ * below this one, so it can record the miss itself.
+ */
+export const TOOL_BATCH_HOOK_TIMEOUT_MS = 30_000;
+
 /**
  * Registered speech handler.
  */
@@ -60,7 +70,11 @@ interface SpeechHandler {
  * Registry for managing modules.
  */
 export class ModuleRegistry {
+  /** Each module's tool-batch hook still running, past its bound or not. */
+  private batchHooksRunning = new Map<string, Promise<unknown>>();
+
   private modules: Map<string, Module> = new Map();
+  private stopping = new Map<Module, Promise<void>>();
   private moduleContexts: Map<string, ModuleContextImpl> = new Map();
   private speechHandlers: SpeechHandler[] = [];
   private store: JsStore;
@@ -173,9 +187,7 @@ export class ModuleRegistry {
       throw new Error(`Module not found: ${name}`);
     }
 
-    await module.stop();
-    this.modules.delete(name);
-    this.moduleContexts.delete(name);
+    await this.stopModule(module);
   }
 
   /**
@@ -261,7 +273,20 @@ export class ModuleRegistry {
   }
 
   /**
-   * Handle a tool call by routing to the appropriate module.
+   * A module tool's call for a path that stores or sends its result: the
+   * model's dispatch, a script's inner call, the `utils` meta-tool for a
+   * 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));
+  }
+
+  /**
+   * Handle a tool call by routing to the appropriate module: the module's own
+   * 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.
    */
   async handleToolCall(call: ToolCall): Promise<ToolResult> {
     // Parse module--tool name
@@ -297,23 +322,37 @@ export class ModuleRegistry {
     try {
       return await module.handleToolCall(moduleCall);
     } catch (error) {
-      return {
-        success: false,
-        error: error instanceof Error ? error.message : String(error),
-        isError: true,
-      };
+      return thrownResult(error);
     }
   }
 
   /**
-   * Stop all modules.
+   * Stop all modules. A caller may bound its wait without cancelling cleanup.
+   * The default waits for each module's own shutdown contract.
    */
-  async stopAll(): Promise<void> {
-    const stopPromises = Array.from(this.modules.values()).map((m) => m.stop());
-    await Promise.all(stopPromises);
-    this.modules.clear();
-    this.moduleContexts.clear();
-    this.speechHandlers = [];
+  async stopAll(timeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS): Promise<void> {
+    validateShutdownTimeout(timeoutMs);
+    await waitForShutdown(Array.from(this.modules.values(), module => ({
+      label: `module:${module.name}`, promise: this.stopModule(module),
+    })), timeoutMs);
+  }
+
+  private stopModule(module: Module): Promise<void> {
+    const existing = this.stopping.get(module);
+    if (existing) return existing;
+    const attempt = Promise.resolve().then(() => module.stop()).then(() => {
+      if (this.modules.get(module.name) === module) {
+        this.modules.delete(module.name);
+        this.moduleContexts.delete(module.name);
+        this.speechHandlers = this.speechHandlers.filter(handler => handler.moduleName !== module.name);
+      }
+      this.stopping.delete(module);
+    }, error => {
+      this.stopping.delete(module);
+      throw error;
+    });
+    this.stopping.set(module, attempt);
+    return attempt;
   }
 
   /**
@@ -397,6 +436,57 @@ export class ModuleRegistry {
     return injections;
   }
 
+  /**
+   * Tell modules an agent's tool batch completed (see
+   * Module.onToolBatchComplete). Hooks run in parallel, each awaited up to
+   * `timeoutMs`; a hook that throws or times out is logged and skipped, so a
+   * wedged module can't hold the round. Returns the modules that didn't
+   * finish, for the caller's trace.
+   */
+  async notifyToolBatchComplete(
+    agentName: string,
+    timeoutMs = TOOL_BATCH_HOOK_TIMEOUT_MS,
+  ): Promise<Array<{ module: string; error: string }>> {
+    const failures: Array<{ module: string; error: string }> = [];
+    const promises: Promise<void>[] = [];
+    for (const module of this.modules.values()) {
+      if (!module.onToolBatchComplete) continue;
+      // A hook still running from an earlier batch (it outlasted its bound)
+      // isn't called again or waited for: a wedged module costs one bound,
+      // not one per batch.
+      if (this.batchHooksRunning.has(module.name)) {
+        failures.push({ module: module.name, error: 'still running from an earlier batch' });
+        continue;
+      }
+      // Called from a promise, so a hook that throws synchronously, before
+      // returning its promise, is caught below like any other failure
+      // instead of escaping the round (the result would never be provided).
+      const call = Promise.resolve().then(() => module.onToolBatchComplete!(agentName));
+      this.batchHooksRunning.set(module.name, call);
+      const settled = (): void => {
+        if (this.batchHooksRunning.get(module.name) === call) this.batchHooksRunning.delete(module.name);
+      };
+      call.then(settled, settled);
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      promises.push(
+        Promise.race([
+          call,
+          new Promise<void>((_, rej) => {
+            timer = setTimeout(() => rej(new Error(`onToolBatchComplete timed out after ${timeoutMs}ms`)), timeoutMs);
+          }),
+        ])
+          .catch((err: unknown) => {
+            const error = err instanceof Error ? err.message : String(err);
+            failures.push({ module: module.name, error });
+            console.error(`[${module.name}] onToolBatchComplete:`, err);
+          })
+          .finally(() => clearTimeout(timer)),
+      );
+    }
+    await Promise.all(promises);
+    return failures;
+  }
+
   /**
    * Dispatch speech to registered handlers.
    */
@@ -711,3 +801,149 @@ class ProcessStateImpl implements ProcessState {
     this.ctx.pushEvent(event);
   }
 }
+
+/** A result's flags, which consumers read for their truth: booleans here. */
+const RESULT_FLAGS = ['success', 'isError', 'endTurn'] as const;
+
+/**
+ * A module's tool result as the framework can store, send and trace it. A
+ * module runs in the host's process, so it can return what JSON can't hold,
+ * such as a cyclic object, a BigInt or a `toJSON` that throws, no result
+ * object at all, or one whose getters or Proxy traps throw, or answer
+ * differently each time they're read. Everything after this (the stored
+ * history, the request sent to the model, traces, the tool-result guard's
+ * audit record, a script's result) would throw on it, and the agent's turn
+ * would never settle.
+ *
+ * So the result is read once, here, and this never throws. Each field a
+ * consumer reads is read by name, so a result class's getters count, and any
+ * other own field is kept, except a `toJSON`: consumers read a result's
+ * fields, never a `toJSON` of the result. What's returned is the JSON form of
+ * those fields, parsed, so every consumer holds plain data and no module code
+ * runs again. It's taken where the framework stores or sends a result
+ * ({@link ModuleRegistry.storableToolCall}). A caller that uses the result
+ * in process (`ModuleContext.callTool`, `executeToolCall`) gets the module's
+ * own result, as the module returned it ({@link ModuleRegistry.handleToolCall}).
+ * The flags are booleans, read for their truth as consumers read them.
+ * `error` is its text form, which is all a consumer reads of it, so an error
+ * value JSON can't hold costs nothing. An error that says nothing (null,
+ * false or empty) is left out, so the result reads as having no error text.
+ *
+ * A result that can't be read or converted becomes an error result naming the
+ * tool, keeping the module's own error text and its `endTurn` when they could
+ * be read. So does data that is a function or a symbol, which JSON leaves out
+ * whole.
+ */
+export function storableToolResult(call: ToolCall, result: unknown): ToolResult {
+  return checkedToolResult(call, result).result;
+}
+
+/**
+ * {@link storableToolResult}, saying whether the module's result was usable:
+ * read and converted (`usable`), or replaced by the error result naming the
+ * tool. A caller that stores the result and hands the module's own result
+ * back, as `puppetToolCall` does, hands back the error result instead when
+ * there was nothing usable to store.
+ */
+export function checkedToolResult(call: ToolCall, result: unknown): { result: ToolResult; usable: boolean } {
+  // What's been read so far, kept by an error result if a later read throws.
+  let ownText: string | undefined;
+  let endTurn = false;
+  const unusable = (problem: string): { result: ToolResult; usable: boolean } => {
+    const own = ownText ? `, with this error: ${ownText}` : '.';
+    const error = `Tool '${call.name}' ${problem}. The call itself completed${own}`;
+    console.error(`[tools] ${call.callerAgentName ? `agent ${call.callerAgentName}: ` : ''}${error}`);
+    return { result: { success: false, isError: true, error, ...(endTurn ? { endTurn: true } : {}) }, usable: false };
+  };
+  const reasonOf = (error: unknown) => thrownText(error).split('\n')[0] || 'no reason given';
+  try {
+    if (!result || typeof result !== 'object' || Array.isArray(result) || result instanceof Error) {
+      const what = result === undefined || result === null ? String(result)
+        : Array.isArray(result) ? 'an array' : result instanceof Error ? 'an Error' : `a ${typeof result}`;
+      if (result instanceof Error) ownText = errorText(result);
+      return unusable(`returned ${what} instead of a result object, so there's nothing to store or send`);
+    }
+    const candidate = result as Record<string, unknown>;
+    // No prototype, so an own field named like an inherited one is a field.
+    const fields: Record<string, unknown> = Object.create(null);
+    const read = (key: string) => { if (key in candidate) fields[key] = candidate[key]; };
+    // endTurn first and the error's text next, so an error result keeps
+    // whichever of them could be read when a later read throws.
+    read('endTurn');
+    endTurn = Boolean(fields.endTurn);
+    read('error');
+    ownText = errorText(fields.error);
+    for (const key of ['success', 'isError', 'data']) read(key);
+    for (const key of Object.keys(candidate)) {
+      if (key !== 'toJSON' && !(key in fields)) fields[key] = candidate[key];
+    }
+    // The error is kept as its text, which consumers read; its value isn't.
+    delete fields.error;
+    // The flags are kept as their truth, which is all consumers read of them,
+    // before anything is serialized, so a flag's own value (a BigInt, a
+    // function, an object with a toJSON) neither breaks nor runs anything.
+    for (const flag of RESULT_FLAGS) {
+      if (fields[flag] !== undefined) fields[flag] = Boolean(fields[flag]);
+    }
+    // An error result reads as its error, so only a non-error result's data matters.
+    if (!fields.isError && (typeof fields.data === 'function' || typeof fields.data === 'symbol')) {
+      return unusable(`returned a ${typeof fields.data} as its data, which JSON leaves out, so there's nothing to store or send`);
+    }
+    let json: string;
+    try {
+      json = JSON.stringify(fields);
+    } catch (error) {
+      return unusable(`returned a result that can't be converted to JSON, so it can't be stored or sent (${reasonOf(error)})`);
+    }
+    const storable = JSON.parse(json) as Record<string, unknown>;
+    if (ownText !== undefined) storable.error = ownText;
+    return { result: storable as unknown as ToolResult, usable: true };
+  } catch (error) {
+    return unusable(`returned a result that can't be read, so it can't be stored or sent (${reasonOf(error)})`);
+  }
+}
+
+/** A result's `error` as text, always a string or none: a string as it is,
+ *  an `Error`'s message read the same way (a module's value, so not always a
+ *  string), an object's own `message`, any other value's JSON, and a
+ *  primitive JSON can't hold (a BigInt, a symbol) as its String(). None for a
+ *  value that says nothing: absent, null, false or empty, which consumers
+ *  then report as "Unknown error". */
+function errorText(error: unknown): string | undefined {
+  if (error === undefined || error === null || error === false || error === '') return undefined;
+  if (typeof error === 'string') return error;
+  if (error instanceof Error) return errorText(error.message);
+  const message = (error as { message?: unknown }).message;
+  if (typeof message === 'string' && message) return message;
+  try {
+    const json = JSON.stringify(error) as string | undefined;
+    if (json !== undefined) return json;
+  } catch {
+    // A cyclic or BigInt-holding value: nothing faithful to show as JSON.
+  }
+  if (typeof error !== 'object' && typeof error !== 'function') return thrownText(error);
+  return 'an error value with no text form';
+}
+
+/** A module's throw, answered as an error result: its text, or none when it
+ *  has none, so consumers say "Unknown error". */
+export function thrownResult(error: unknown): ToolResult {
+  const text = thrownText(error);
+  return { success: false, isError: true, ...(text ? { error: text } : {}) };
+}
+
+/** A thrown value's whole text, always a string, for a result's error, and
+ *  for a value that has none too. An `Error`'s message is a module's value,
+ *  so it may not be a string: one that isn't is given its String(), and an
+ *  absent one is empty. String() throws on an object without a prototype,
+ *  and such a value is named as having no text form. */
+function thrownText(value: unknown): string {
+  try {
+    if (!(value instanceof Error)) return String(value);
+    const message: unknown = value.message;
+    if (typeof message === 'string') return message;
+    return message === undefined || message === null ? '' : String(message);
+  } catch {
+    return 'a value with no text form';
+  }
+}

package/src/modules/workspace/branch-intent.ts

@@ -0,0 +1,123 @@
+/**
+ * Branch-local intent about workspace paths: what the workspace on THIS branch
+ * deliberately did or still owes, kept in a per-mount Chronicle tree state so
+ * it rewinds with the workspace tree it qualifies (a branch switch that brings
+ * back a deleted file brings back its missing tombstone too).
+ *
+ *  - tombstone: the workspace deleted the path while disk kept a copy (no
+ *    autoMaterialize, or a refused unlink). The hash is the deleted entry's,
+ *    so even a legacy entry with no disk evidence keeps a durable intent.
+ *  - origin 'store': the entry was created through workspace tools and disk
+ *    has never agreed with it.
+ *  - conflict: disk and workspace diverged in a way no rule may resolve
+ *    silently; kept until a path sync, a forced materialize, or convergence.
+ *
+ * Each record is a small JSON blob addressed from the tree, so reading one is
+ * treeGet + getBlob and writing one is storeBlob + treeSet.
+ */
+
+import type { JsStore } from '@animalabs/chronicle';
+
+export type ConflictKind =
+  /** Disk, workspace and the last agreement all differ. */
+  | 'both-changed'
+  /** Disk deleted a file whose workspace copy differs from the last agreement. */
+  | 'deleted-on-disk'
+  /** Disk changed a file the workspace deleted. */
+  | 'changed-after-workspace-delete'
+  /** Disk holds a file at the path of a workspace-created entry, with other content. */
+  | 'store-origin-collision'
+  /** A legacy entry whose disk copy differs, with no evidence of which side changed. */
+  | 'unknown-provenance'
+  /** A module write or adoption was interrupted, and disk holds neither outcome. */
+  | 'interrupted';
+
+/** The disk side of a conflict, as observed when it was recorded. */
+export interface DiskCounterpart {
+  hash: string;
+  size: number;
+  mtimeMs: number;
+  /** Blob hash of the stored copy (text within limits); absent when only referenced. */
+  stored?: string;
+}
+
+export interface ConflictRecord {
+  kind: ConflictKind;
+  /** When the conflict was recorded (ms). */
+  at: number;
+  /** null when disk had no file. */
+  disk: DiskCounterpart | null;
+}
+
+export interface BranchIntent {
+  tombstone?: { hash: string };
+  origin?: 'store';
+  conflict?: ConflictRecord;
+  /**
+   * Why a recorded intent can't be read (its blob missing from the store, or
+   * not an intent): a tombstone or conflict it held is unknown, never absent.
+   * Never written; a put replaces the damaged record.
+   */
+  unreadable?: string;
+}
+
+function isEmpty(intent: BranchIntent): boolean {
+  return intent.tombstone === undefined && intent.origin === undefined && intent.conflict === undefined &&
+    intent.unreadable === undefined;
+}
+
+/** A recorded intent's blob, read; a damaged one says why it can't be. */
+function readIntent(store: JsStore, blobHash: string): BranchIntent {
+  const blob = store.getBlob(blobHash);
+  if (!blob) return { unreadable: "its record's blob is missing from the store" };
+  try {
+    const parsed = JSON.parse(blob.toString('utf-8')) as unknown;
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed as BranchIntent;
+  } catch {
+    // reported below
+  }
+  return { unreadable: 'its record is not a branch intent' };
+}
+
+export class BranchIntents {
+  constructor(private readonly store: JsStore, readonly treeStateId: string) {}
+
+  get(path: string): BranchIntent | null {
+    const entry = this.store.treeGet(this.treeStateId, path);
+    if (!entry) return null;
+    return readIntent(this.store, entry.blobHash);
+  }
+
+  /** Replace a path's intent; an empty intent removes the record. */
+  put(path: string, intent: BranchIntent | null): void {
+    if (intent?.unreadable !== undefined) {
+      const { unreadable: _damaged, ...rest } = intent;
+      intent = rest;
+    }
+    if (!intent || isEmpty(intent)) {
+      if (this.store.treeGet(this.treeStateId, path)) this.store.treeRemove(this.treeStateId, path);
+      return;
+    }
+    const bytes = Buffer.from(JSON.stringify(intent), 'utf-8');
+    const blobHash = this.store.storeBlob(bytes, 'application/json');
+    this.store.treeSet(this.treeStateId, path, { blobHash, size: bytes.byteLength, mode: 0 });
+  }
+
+  /** Update one path's intent in place. */
+  update(path: string, change: (current: BranchIntent) => BranchIntent): void {
+    this.put(path, change({ ...(this.get(path) ?? {}) }));
+  }
+
+  /** Every recorded intent under a prefix ('' for the whole mount). */
+  list(prefix = ''): Array<[string, BranchIntent]> {
+    const out: Array<[string, BranchIntent]> = [];
+    for (const entry of this.store.treeList(this.treeStateId, prefix ? prefix + '/' : undefined)) {
+      out.push([entry.path, readIntent(this.store, entry.blobHash)]);
+    }
+    if (prefix) {
+      const exact = this.get(prefix);
+      if (exact) out.push([prefix, exact]);
+    }
+    return out;
+  }
+}