@animalabs/agent-framework 0.22.4 → 0.23.1

package/src/tool-args.ts

@@ -0,0 +1,213 @@
+import type { ToolDefinition } from './types/index.js';
+
+/** A run of 16 or more digits, which membrane's XML parser passes as text for
+ *  a number or integer parameter: some such runs would lose precision as a
+ *  JavaScript number, so membrane keeps every one as text, and so does this
+ *  check. */
+const LARGE_INTEGER_TEXT = /^\d{16,}$/;
+
+/** The JSON kind of a value, as a schema's `type` names it. */
+function kindOf(value: unknown): string {
+  if (Array.isArray(value)) return 'array';
+  if (value === null) return 'null';
+  return typeof value;
+}
+
+/** A kind with its article, for a sentence. */
+function withArticle(kind: string): string {
+  if (kind === 'null') return 'null';
+  return /^[aeiou]/.test(kind) ? `an ${kind}` : `a ${kind}`;
+}
+
+/** The types JSON Schema names. A `type` naming anything else, such as
+ *  `any`, is one the check can't read. */
+const JSON_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'object', 'array', 'null']);
+
+/** The kinds a declaration's type admits, each once, or none when it declares
+ *  none it can read. A type list naming anything JSON Schema doesn't have is
+ *  one it can't read as a whole, as membrane reads it, rather than the names
+ *  in it that it knows. OpenAPI's `nullable: true`, the form Gemini's dialect
+ *  uses, admits `null` beside its type, as a type list naming `null` does. */
+function admittedKinds(param: { type?: unknown; nullable?: unknown } | undefined): string[] {
+  const type = param?.type;
+  const types = Array.isArray(type) ? type : type === undefined ? [] : [type];
+  if (!types.every((t) => typeof t === 'string' && JSON_TYPES.has(t))) return [];
+  const kinds = new Set((types as string[]).map((t) => (t === 'integer' ? 'number' : t)));
+  if (kinds.size > 0 && param?.nullable === true) kinds.add('null');
+  return [...kinds];
+}
+
+/** Whether `null` is a value for a key so declared: where the declaration
+ *  admits it (a type list naming it, or `nullable: true`), or declares no
+ *  type at all. A type the check can't read says nothing about `null`, so
+ *  there `null` is no value unless the declaration names it. */
+function takesNull(param: { type?: unknown; nullable?: unknown } | undefined): boolean {
+  const type = param?.type;
+  if (type === undefined || param?.nullable === true) return true;
+  return Array.isArray(type) ? type.includes('null') : type === 'null';
+}
+
+/** A value as the call gave it, briefly: the first 80 characters of its JSON
+ *  text, then an ellipsis when there are more, cut between characters rather
+ *  than inside one. The whole value is serialized before the cut. */
+function shown(value: unknown): string {
+  let text: string;
+  try {
+    text = JSON.stringify(value) ?? String(value);
+  } catch {
+    text = '(a value that could not be shown)';
+  }
+  let head = '';
+  let count = 0;
+  for (const char of text) {
+    if (count === 80) return `${head}…`;
+    head += char;
+    count++;
+  }
+  return head;
+}
+
+/** A list in prose: `a`, `a or b`, `a, b or c`. */
+function oneOf(items: string[]): string {
+  return items.length <= 1 ? items.join('') : `${items.slice(0, -1).join(', ')} or ${items[items.length - 1]}`;
+}
+
+/** A list in prose: `a`, `a and b`, `a, b and c`. */
+function allOf(items: string[]): string {
+  return items.length <= 1 ? items.join('') : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
+
+/** At most this many keys a call gave that its schema doesn't declare are named. */
+const UNDECLARED_SHOWN = 5;
+
+/** An own property, so a key such as `constructor` isn't found on the prototype. */
+function own(obj: Record<string, unknown>, key: string): unknown {
+  return Object.hasOwn(obj, key) ? obj[key] : undefined;
+}
+
+/** An object that isn't a list: a map of keys, as `properties` should be. */
+function isMap(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Every root keyword in JSON Schema's drafts 4 to 2020-12, besides
+ *  `properties` and `required`, that can accept, require or name an object's
+ *  keys, except the two read by declaresKeysPlainly (`additionalProperties`
+ *  and `unevaluatedProperties`, which count when `true` or a schema object). The
+ *  reading is cautious: a root with any of them names no key, whatever its
+ *  subschemas hold, since naming a key the schema takes would mislead the
+ *  agent more than a hint left out. So `not` is here too, since a negation
+ *  can require a key (`not: {properties: {y: {type: 'string'}}}` refuses an
+ *  object without a non-string `y`), and so is `if` with or without `then`
+ *  and `else`. `then` and `else` act only beside `if`, and a keyword JSON
+ *  Schema doesn't have declares nothing. */
+const OTHER_KEY_DECLARERS = [
+  'allOf', 'anyOf', 'oneOf', 'not', 'if', '$ref', '$dynamicRef', '$recursiveRef',
+  'dependentSchemas', 'dependencies', 'dependentRequired', 'patternProperties',
+  'propertyNames', 'enum', 'const',
+];
+
+/** Whether a schema's root declares its keys only in `properties` and
+ *  `required`, so that a key in neither isn't one of its parameters. A root
+ *  with any keyword in OTHER_KEY_DECLARERS can declare keys another way. A
+ *  schema object for `additionalProperties` or `unevaluatedProperties`, `{}`
+ *  included, or `true`, which means the same there, says the root takes keys
+ *  `properties` doesn't list, as a map's input does, so a key in neither list
+ *  may be meant. `false` there says it takes none, so it names. Left out,
+ *  the keyword is JSON Schema's default, which says nothing of what the
+ *  author meant, and most schemas leave it out without welcoming other keys,
+ *  so a root without it names them too. */
+function declaresKeysPlainly(schema: Record<string, unknown>): boolean {
+  return !OTHER_KEY_DECLARERS.some((key) => Object.hasOwn(schema, key))
+    && !takesOtherKeys(schema.additionalProperties)
+    && !takesOtherKeys(schema.unevaluatedProperties);
+}
+
+function takesOtherKeys(value: unknown): boolean {
+  return value === true || isMap(value);
+}
+
+/**
+ * What's wrong with a call's input against its tool's declared inputSchema,
+ * checked shallowly: the input is an object, and each root `required` key has
+ * a value. With `values`, also each declared key's value: a type and an enum
+ * value its declaration admits. It isn't a JSON-Schema engine: nested shapes,
+ * unions and references are the handler's to check, as they always were.
+ * Every problem is reported at once, each naming the key, what the schema
+ * wants and what the call gave. An empty list means the call can go to its
+ * handler.
+ *
+ * - An absent input (`undefined` or `null`) gives no arguments: it's refused
+ *   only for the keys the schema requires.
+ * - A required key given as `null` has no value, the same as one left out,
+ *   unless its declaration admits `null` (a type list naming it, or
+ *   `nullable: true`), or has no `type` at all: a key with no `type` takes
+ *   `null` as a value, as it takes any other. One whose `type` the check
+ *   can't read, such as Gemini's `STRING`, or a list naming one, takes
+ *   `null` only where the declaration names it, and its values aren't
+ *   checked against the type. An empty string is a value.
+ * - A schema whose `required` isn't a list requires nothing here, and a key
+ *   it lists twice is reported once.
+ * - Where a required key is missing and the call gave keys the schema
+ *   declares neither in its `properties` nor in its `required` list, those
+ *   are named too, since a key sent under another name is one reason a
+ *   required key goes missing. They're never refused for themselves. A schema
+ *   whose root can declare keys another way names none
+ *   (declaresKeysPlainly).
+ *
+ * A module tool's call is checked without `values`: a handler may take more
+ * than its schema can say on every provider, such as one name where a list
+ * is declared, and refusing that would refuse calls that work. The `utils`
+ * tool checks a utility's values too, as it always has. `field` names what
+ * the input is to the caller ("input" unless given).
+ */
+export function toolArgsProblems(
+  input: unknown,
+  schema: ToolDefinition['inputSchema'] | undefined,
+  options: { values?: boolean; field?: string } = {},
+): string[] {
+  if (!schema) return [];
+  const absent = input === undefined || input === null;
+  if (!absent && (typeof input !== 'object' || Array.isArray(input))) {
+    return [`its ${options.field ?? 'input'} must be an object, and this call gave ${withArticle(kindOf(input))}`];
+  }
+  const obj = (absent ? {} : input) as Record<string, unknown>;
+  const properties = (isMap(schema.properties) ? schema.properties : {}) as Record<string, { type?: unknown; nullable?: unknown; enum?: unknown } | undefined>;
+  const declared = (key: string) => (Object.hasOwn(properties, key) ? properties[key] : undefined);
+  const problems: string[] = [];
+  const missing = new Set<string>();
+  const required: unknown[] = Array.isArray(schema.required) ? schema.required : [];
+  for (const key of required) {
+    if (typeof key !== 'string' || missing.has(key)) continue;
+    const value = own(obj, key);
+    const kinds = admittedKinds(declared(key));
+    if (value !== undefined && (value !== null || takesNull(declared(key)))) continue;
+    missing.add(key);
+    const wanted = kinds.length > 0 ? `"${key}" (${oneOf(kinds.map(withArticle))})` : `"${key}"`;
+    problems.push(`needs ${wanted}, and this call gave ${value === null ? 'null' : 'none'}`);
+  }
+  if (missing.size > 0 && declaresKeysPlainly(schema as Record<string, unknown>)) {
+    const undeclared = Object.keys(obj).filter((key) => !Object.hasOwn(properties, key) && !required.includes(key));
+    if (undeclared.length > 0) {
+      const named = undeclared.slice(0, UNDECLARED_SHOWN).map(shown);
+      if (undeclared.length > UNDECLARED_SHOWN) named.push(`${undeclared.length - UNDECLARED_SHOWN} more`);
+      problems.push(undeclared.length === 1 ? `${named[0]} isn't one of its parameters` : `${allOf(named)} aren't among its parameters`);
+    }
+  }
+  if (!options.values) return problems;
+  for (const [key, value] of Object.entries(obj)) {
+    const param = declared(key);
+    if (!param || value === undefined || missing.has(key)) continue;
+    const kinds = admittedKinds(param);
+    const kind = kindOf(value);
+    const largeInteger = kind === 'string' && kinds.includes('number') && LARGE_INTEGER_TEXT.test(value as string);
+    if (kinds.length > 0 && !kinds.includes(kind) && !largeInteger) {
+      problems.push(`"${key}" must be ${oneOf(kinds.map(withArticle))}, and this call gave ${withArticle(kind)}`);
+      continue;
+    }
+    if (Array.isArray(param.enum) && !param.enum.includes(value)) {
+      problems.push(`"${key}" must be one of ${oneOf(param.enum.map(shown))}, and this call gave ${shown(value)}`);
+    }
+  }
+  return problems;
+}

package/src/tool-presentation.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { fchmodSync, closeSync, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { constants, fchmodSync, closeSync, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { closestNames } from './closest-names.js';
 import { boundedErrorMessage, errorMessage } from './error-message.js';
 import type { ToolDefinition, ToolResult } from './types/events.js';
@@ -24,6 +24,13 @@ export interface PresentationSnapshot {
   entries: { name: string; source: string; visible: boolean; originalDescription: string; description: string; descriptionSource?: string; inputSchema: ToolDefinition['inputSchema'] }[];
 }
 const MAX_BYTES = 256 * 1024;
+/**
+ * Opened with each read of a presentation file, as observe.ts opens workspace
+ * files: a FIFO at the operator's path opens at once and fails the regular-file
+ * check, where a blocking open would hold the whole process (it's synchronous)
+ * until something opened the FIFO for writing.
+ */
+const NONBLOCK = typeof constants.O_NONBLOCK === 'number' ? constants.O_NONBLOCK : 0;
 const MAX_DESCRIPTION_CHARS = 32768;
 const protectedNames = new Set(['set_tool_visibility', 'set_tool_description', 'workspace--read']);
 export const isPresentationTool = (name: string): boolean => name === 'set_tool_visibility' || name === 'set_tool_description';
@@ -173,7 +180,7 @@ export class ToolPresentation {
   constructor(readonly config: ToolPresentationConfig) {}
   private read(path = this.config.path, allowMissing = true): string {
     let fd: number;
-    try { fd = openSync(path, 'r'); }
+    try { fd = openSync(path, constants.O_RDONLY | NONBLOCK); }
     catch (error) {
       const code = (error as NodeJS.ErrnoException).code;
       if (code === 'ENOENT') {

package/src/types/agent.ts

@@ -14,7 +14,12 @@ export type SameRoundThinkTextPolicySource =
  */
 export interface AgentConfig {
   toolPresentation?: import("../tool-presentation.js").ToolPresentationConfig;
-  /** Unique name for this agent */
+  /**
+   * Unique name for this agent: create() refuses two configured agents of one
+   * name. Names compare exactly, so `Dup` beside `dup` is two agents, though
+   * the history tool's author filter matches their own turns without letter
+   * case and can't tell them apart there.
+   */
   name: string;
 
   /** Model to use (e.g., 'claude-sonnet-4-20250514') */
@@ -27,9 +32,19 @@ export interface AgentConfig {
   strategy?: ContextStrategy;
 
   /**
-   * Which tools this agent can use.
+   * Enforced at dispatch for registered agent callers; omitted means 'all'.
    * - 'all': all available tools
-   * - string[]: specific tool names (with module prefix)
+   * - string[]: exact tool names, including module--utility names for utilities.
+   * Utilities aren't tools of their own: an agent's model and its scripts are
+   * offered them only through 'utils', whose run checks the utility's own
+   * name. An agent that should use a utility lists both 'utils' and
+   * 'module--utility'. The name alone passes the dispatch check for any call
+   * by that name, whether the host makes it with executeToolCall on the
+   * agent's behalf or the model or a script makes it without being offered
+   * it. The slot is hidden when no utility is permitted.
+   * Trusted module calls are exempt. Genuinely unidentified public callers,
+   * including unknown legacy names, remain unrestricted. Framework-created
+   * identities have tool authority only while registered.
    */
   allowedTools?: 'all' | string[];
 
@@ -172,12 +187,6 @@ export interface AgentConfig {
     autoRewind?: boolean;
     /** Max consecutive rewinds before giving up a turn. Default 3. */
     maxRewinds?: number;
-    /**
-     * When the rewound turn is a *human* message (not a machine tool result),
-     * announce the withholding on the conversational surface (Discord) rather
-     * than dropping it silently. Default true.
-     */
-    announceHumanTurns?: boolean;
   };
 
   /** Opt-in tool-output admission and one guarded retry after a provider
@@ -197,7 +206,8 @@ export interface AgentConfig {
    *   that publication envelope through the same authorized resolver.
    *   See docs/hybrid-prose-routing.md.
    * - 'disabled': generated prose is never published. Only explicit tools may
-   *   send externally; prose remains in Chronicle with a private suppression receipt.
+   *   send externally; prose remains in Chronicle, and a turn that wrote plain
+   *   speech ends with a private `[delivered] plain speech → no channel` receipt.
    */
   proseRouting?: 'locus' | 'explicit' | 'hybrid' | 'disabled';
 
@@ -372,7 +382,8 @@ export interface InferenceRequest {
    * replies in the channel it is answering — not the process-global most-recent-
    * inbound locus, which a concurrent message elsewhere can hijack (item-3
    * redux). Undefined for non-channel wakes (heartbeat, timers, module events),
-   * which correctly fall back to the global default channel.
+   * which correctly fall back to the global default channel, except an
+   * ephemeral run's (a subagent's), which takes no global fallback.
    */
   channelId?: string;
   /**
@@ -406,11 +417,10 @@ export interface InferenceRequest {
   /** Suppress every automatic plain-prose delivery for this logical turn.
    * Explicit tool calls remain available. Used by authenticated silent wakes. */
   suppressProse?: boolean;
-  /** Ephemeral system-position prompt for this turn only. Never written to
-   * Chronicle; callers must supply bounded non-secret control text. */
-  ephemeralSystemPrompt?: string;
-  /** The authenticated silent heartbeat tick this turn answers. Every row the
-   * turn stores is stamped `metadata.silentHeartbeat` with it, and request
-   * builds render a request-only separator before the tick's first row. */
+  /** The authenticated silent heartbeat tick this turn answers. The rows the
+   * turn's reply stores (its assistant responses and tool results) are
+   * stamped `metadata.silentHeartbeat` with it, and request builds render a
+   * request-only separator carrying the tick's instruction before the tick's
+   * first surviving row (`SILENT_HEARTBEAT_SEPARATOR`). */
   silentHeartbeat?: SilentHeartbeatTick;
 }

package/src/types/events.ts

@@ -192,6 +192,14 @@ export interface ToolResult {
   error?: string;
   /** Whether this was an error (for LLM) */
   isError?: boolean;
+  /**
+   * An MCP tool's `structuredContent`: its machine-readable result, beside
+   * `data`, which is the content view. Present exactly when the server sent
+   * one, so `false`, `0` and `null` are values here, not absence. Programs
+   * read it (scripts get it in their result object); the model sees content,
+   * and sees this rendered as JSON only when the content carries no text.
+   */
+  structured?: unknown;
   /**
    * When true, the framework saves tool_use + tool_result messages to context,
    * cancels the active stream, and resets the agent to idle.

package/src/types/framework.ts

@@ -24,8 +24,6 @@ export interface ModuleProcessResponse {
 export interface ProcessLoggingConfig {
   /** Persist process logs to Chronicle (default: false) */
   persist?: boolean;
-  /** Broadcast process:completed trace events (default: false) */
-  broadcast?: boolean;
 }
 
 /**
@@ -76,6 +74,23 @@ export interface CodeExecutionConfig {
   /** Max wake_agent() calls per background script (default 100); further
    *  calls raise RuntimeError inside the script. */
   maxWakesPerScript?: number;
+  /** Variables for the python interpreter beyond the operating allowlist it
+   *  inherits (see CHILD_ENV_ALLOWLIST), such as PYTHONPATH. A recipe can
+   *  `${VAR}`-substitute them from .env. Other host variables aren't
+   *  inherited, which limits what model-authored code inherits, not what a
+   *  process running as the same user can read. The runner sets
+   *  PYTHONUNBUFFERED and PYTHONIOENCODING last, over any value given here,
+   *  since its protocol needs both. The interpreter's working directory is
+   *  its own runtime directory, so a relative path given here, as in
+   *  PYTHONPATH, resolves there: give absolute paths. */
+  env?: Record<string, string>;
+  /** The interpreter inherits the host's whole environment instead of the
+   *  allowlist: every host variable, provider keys included, reaches
+   *  model-authored code and every subprocess a script starts. Listing what
+   *  scripts need in `env` is the safer route. With code execution enabled,
+   *  `create()` refuses any value but true, false or null, which counts as
+   *  not set. */
+  inheritEnv?: boolean;
 }
 
 /** See `FrameworkConfig.providerHold`. */

package/src/types/module.ts

@@ -19,15 +19,39 @@ export interface MessageQuery {
   externalIds?: string[];
   /** Filter by participant name */
   participant?: string;
-  /** Filter by metadata fields (shallow match) */
+  /** Filter by metadata fields: each key a path, dot-separated for a nested
+   *  field (such as 'external.channelId'), its value compared by strict
+   *  equality */
   metadata?: Record<string, unknown>;
 }
 
+/**
+ * A message as a module context's reads answer it: a stored row, or a row
+ * for a write the framework holds (`held`).
+ */
+export type ModuleMessage = StoredMessage & {
+  /**
+   * True while the framework holds the message's write, as it does while
+   * the write's agent has a turn alive or the host is quiesced, until a
+   * later boundary stores it. The row's `id` is then a handle, which
+   * getMessage, editMessage and removeMessage take as they take a stored
+   * id, and which names the stored row once the write lands. Its `sequence`
+   * and `timestamp` are provisional: the sequence comes after every stored
+   * row's, the timestamp is when the framework held the write (for a write
+   * an older release held, when its queue was read back), and both change
+   * when it lands. Absent on a stored row.
+   */
+  held?: true;
+};
+
 /**
  * Result of a message query.
  */
 export interface MessageQueryResult {
-  messages: StoredMessage[];
+  /** The matching stored rows, then, as the newest, the matching rows of
+   *  writes the framework holds (ModuleMessage.held): before the stored rows
+   *  in a reversed query */
+  messages: ModuleMessage[];
   totalCount: number;
 }
 
@@ -249,7 +273,14 @@ export interface ModuleContext {
   getModule<T extends Module>(name: string): T | null;
 
   /**
-   * Add a message to the conversation.
+   * Add a message to the conversation, and answer its id. While the
+   * framework holds the write (the agent's turn is alive, or the host is
+   * quiesced), the id is a handle, `held:` and the write's id, which
+   * getMessage, editMessage and removeMessage take as they take a stored
+   * id, and which names the stored row once the write lands
+   * (ModuleMessage.held). The writes a process held, and keeps across a
+   * restart, show to the next process's modules once create() has restored
+   * them, which is after every module's start().
    */
   addMessage(
     participant: string,
@@ -258,28 +289,40 @@ export interface ModuleContext {
   ): MessageId;
 
   /**
-   * Edit a message.
+   * Edit a message, by its id or a held write's handle. A held write is
+   * stored with the new content.
    */
   editMessage(id: MessageId, content: ContentBlock[]): void;
 
   /**
-   * Remove a message.
+   * Remove a message, by its id or a held write's handle. A held write is
+   * dropped, so the agent never reads it.
    */
   removeMessage(id: MessageId): void;
 
   /**
-   * Find a message by external ID.
+   * Find the message for an external ID this context added a message under:
+   * the row it added, while the store holds it. For a write the framework
+   * held, whose id this context doesn't keep, the first row the store shows
+   * under that external ID, held rows included, a held row by its handle.
+   * Null when this context added none under it, when the row it added is
+   * gone, or when the store shows none for a held write, such as one the
+   * last process held, looked up in start().
    */
   findMessageByExternalId(source: string, externalId: string): MessageId | null;
 
   /**
-   * Get a message by ID.
+   * Get a message by its id or a held write's handle.
    */
-  getMessage(id: MessageId): StoredMessage | null;
+  getMessage(id: MessageId): ModuleMessage | null;
 
   /**
    * Query messages by filter criteria.
    * Useful for finding messages from external sources, by participant, etc.
+   * The rows of writes the framework holds come after the stored rows, as
+   * the newest, or before them in a reversed query, marked `held`
+   * (ModuleMessage). Those the last process held show once create() has
+   * restored them, after every module's start() (addMessage).
    */
   queryMessages(filter: MessageQuery): MessageQueryResult;
 
@@ -447,12 +490,14 @@ export interface EventResponse {
   addMessages?: NewMessage[];
 
   /**
-   * Messages to edit.
+   * Messages to edit, each by its id or a held write's handle
+   * (ModuleContext.editMessage).
    */
   editMessages?: MessageEdit[];
 
   /**
-   * Messages to remove.
+   * Messages to remove, each by its id or a held write's handle
+   * (ModuleContext.removeMessage).
    */
   removeMessages?: MessageId[];
 

package/src/types/trace.ts

@@ -632,7 +632,7 @@ export type TraceEvent =
   | (TraceEventBase & {
       type: 'mcpl:orphaned-response';
       serverId: string;
-      /** The JSON-RPC id of the late response whose pending request already timed out. */
+      /** The JSON-RPC id of the late response, whose request had already timed out or been ended by its transport's close. */
       responseId: string | number;
       /** Original request method when retained for mandatory-deadline visibility. */
       method?: string;
@@ -674,7 +674,7 @@ export type TraceEvent =
       parkedAdmissions?: number;
       /** True when undrained turns were force-cancelled (abandon). */
       abandoned?: boolean;
-      /** Agents whose turn abandon could not cancel (token held, no stream). */
+      /** Agents whose turn the abandon had not ended when its grace ran out: a token held with no stream and no check ahead (a puppet tool turn, a store surgery's reservation, a turn finishing its last delivery), or a turn that hadn't reached its next check, the tool-result guard's wait for its speech included. A turn whose stream the abandon cancelled while it was still streaming isn't listed, even one still running when the grace ran out. */
       unabandonable?: string[];
     })
   | (TraceEventBase & {