@animalabs/agent-framework 0.26.1 → 0.27.0

package/src/gate/index.ts

@@ -1,4 +1,4 @@
-export { EventGate, wakeProvenance, type WakeProvenance } from './event-gate.js';
+export { EventGate, wakeProvenance, wakeLineText, type WakeProvenance, type WritePlacement } from './event-gate.js';
 export type {
   GateConfig,
   GateOptions,
@@ -9,4 +9,5 @@ export type {
   GateEventInfo,
   GateStatus,
   GatePolicyStats,
+  WakeLine,
 } from './types.js';

package/src/gate/recipe-reconcile.ts

@@ -0,0 +1,355 @@
+/**
+ * What a start does to an existing gate.json, given the recipe's gate config.
+ *
+ * The gate keeps the recipe it last applied in a file of its own beside
+ * gate.json (`gate.recipe.json` for `gate.json`), written by the gate. A start
+ * merges the recipe into gate.json three ways, rule by rule, against it:
+ * - a rule as the last recipe left it follows the new recipe: it takes the
+ *   new definition, or goes when the new recipe no longer declares it, so a
+ *   renamed rule goes under its old name and comes in under its new one;
+ * - a rule edited since the last recipe keeps its definition, unless it now
+ *   agrees with the recipe's;
+ * - a rule both recipes declare, removed from gate.json since, comes back;
+ * - a rule no recipe declared (added at run time, or by hand) stays, and if
+ *   the recipe now declares it as it stands, it's the recipe's from then on;
+ * - a rule new in the recipe comes in.
+ *
+ * Order is an edit of its own, apart from a rule's definition. When gate.json
+ * holds the rules both recipes declare in the last recipe's order, the recipe's
+ * rules take the new recipe's order, in the places gate.json gives them, and
+ * every other rule keeps its place. When one of them was moved since
+ * (wake_add_rule's position moves one), gate.json's order stays. Either way, a
+ * recipe rule new to gate.json goes before the recipe rule that follows it
+ * there, or after the one before it when none follows.
+ * `default` follows the same rule as a definition.
+ *
+ * Without a last recipe, as at the first start after this change, nothing is
+ * removed or redefined: the rules that match the recipe by name and definition
+ * take its order, every other rule stays, and the line names those that differ
+ * from the recipe or aren't in it. A rule that differs can be removed, and the
+ * next start restores it from the recipe.
+ *
+ * Rules are compared by what they mean and kept as written. Two rules agree
+ * when the gate reads them the same, so a rule `wake_add_rule` wrote as the
+ * gate reads it agrees with the recipe's rule as written, and a change to a
+ * field the gate doesn't read alone isn't an edit; the caller gives the
+ * meaning (`meaningOf`). A rule the gate leaves out has no reading, so it is
+ * compared as written, a change to any of its fields an edit. A rule that agrees with the recipe stays as gate.json
+ * holds it, and one that follows the recipe takes the recipe's rule as
+ * written. A rule with no name stays where gate.json holds it, and a recipe's
+ * rule with no name is never merged: the merge keys rules by name.
+ */
+
+/** What a start changed, by rule name, for its trace and its log line. */
+export interface RecipeChanges {
+  added: string[];
+  removed: string[];
+  updated: string[];
+  restored: string[];
+  moved: string[];
+  /** Edited since the last recipe, and kept, though the new recipe changed or dropped it. */
+  keptEdited: string[];
+  /** Kept, though the recipe declares the name with another definition. */
+  differsFromRecipe: string[];
+  /** Kept, and in no recipe: named at a start without a last recipe only. */
+  outsideRecipe: string[];
+  /** gate.json's order was kept, though the recipe changed its order, since a recipe rule was moved in it. */
+  orderKept: boolean;
+  defaultChange?: { from: string; to: string };
+  /** The live `default`, kept as edited, though the recipe changed it. */
+  defaultKept?: string;
+  /** At a start without a last recipe: the live `default`, kept, and the recipe's, which differs. */
+  defaultDiffers?: { kept: string; recipe: string };
+  /** Why the recorded recipe couldn't be read, when it exists and doesn't read. */
+  recordUnreadable?: string;
+}
+
+/** The file beside gate.json that holds the recipe the gate last applied. */
+export function lastRecipePath(configPath: string): string {
+  return `${configPath.replace(/\.json$/, '')}.recipe.json`;
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === 'object') {
+    // No prototype, so a key such as "__proto__", which JSON.parse gives as an
+    // own field, is copied as one rather than setting the prototype.
+    const out: Record<string, unknown> = Object.create(null);
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      out[key] = sortKeys((value as Record<string, unknown>)[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** A config or policy as text that doesn't depend on its keys' order. */
+export function canonical(value: unknown): string {
+  return JSON.stringify(sortKeys(value));
+}
+
+const same = (a: unknown, b: unknown): boolean => canonical(a) === canonical(b);
+
+/** Changes with nothing in them, for a start to fill. */
+export function noChanges(): RecipeChanges {
+  return {
+    added: [], removed: [], updated: [], restored: [], moved: [],
+    keptEdited: [], differsFromRecipe: [], outsideRecipe: [], orderKept: false,
+  };
+}
+
+/** A gate config as written: its rule list and its `default`, each as given. */
+export interface WrittenConfig { rules: readonly unknown[]; default: unknown }
+
+/** A rule's name as written, when it has a usable one. */
+export function ruleName(rule: unknown): string | undefined {
+  if (!rule || typeof rule !== 'object' || Array.isArray(rule)) return undefined;
+  const name = (rule as { name?: unknown }).name;
+  return typeof name === 'string' && name ? name : undefined;
+}
+
+/** A rule name the list gives more than once, if any: the merge keys rules by name. */
+export function duplicateName(rules: readonly unknown[]): string | undefined {
+  const seen = new Set<string>();
+  for (const rule of rules) {
+    const name = ruleName(rule);
+    if (name === undefined) continue;
+    if (seen.has(name)) return name;
+    seen.add(name);
+  }
+  return undefined;
+}
+
+/** A `default` as the gate reads one: left out, null or "" is "always". */
+function behaviorOf(value: unknown): unknown {
+  return value === undefined || value === null || value === '' ? 'always' : value;
+}
+
+/** The names in one longest sequence that `a` and `b` share in order. */
+function longestShared(a: string[], b: string[]): Set<string> {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  const table: number[][] = Array.from({ length: rows }, () => new Array<number>(cols).fill(0));
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+    }
+  }
+  const shared = new Set<string>();
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      shared.add(a[i]);
+      i++;
+      j++;
+    } else if (table[i + 1][j] > table[i][j + 1]) {
+      i++;
+    } else {
+      // On a tie, the result's rule is the one named as moved: the rule a
+      // swap brought earlier, such as one the old appending left behind a
+      // catch-all.
+      j++;
+    }
+  }
+  return shared;
+}
+
+/**
+ * Merge `recipe` into `live` against `last`, the recipe last applied (null
+ * when there is none), each as written. Pure: the caller reads and writes the
+ * files, and gives `meaningOf`, a rule's meaning as a string two rules share
+ * when they mean the same (as written, unless given). Returns the rule list
+ * and `default` to write, each as written, and whether `default` changed.
+ * Throws when `live` or `recipe` names a rule twice, since the merge keys
+ * rules by name.
+ */
+export function reconcileWithRecipe(
+  live: WrittenConfig,
+  recipe: WrittenConfig,
+  last: WrittenConfig | null,
+  meaningOf: (rule: unknown) => string = canonical,
+): { rules: unknown[]; default: unknown; defaultChanged: boolean; changes: RecipeChanges } {
+  const agree = (a: unknown, b: unknown): boolean => meaningOf(a) === meaningOf(b);
+  const liveDuplicate = duplicateName(live.rules);
+  if (liveDuplicate !== undefined) {
+    throw new Error(`gate.json names the rule "${liveDuplicate}" twice`);
+  }
+  const recipeDuplicate = duplicateName(recipe.rules);
+  if (recipeDuplicate !== undefined) {
+    throw new Error(`the recipe names the rule "${recipeDuplicate}" twice`);
+  }
+
+  const changes = noChanges();
+  // Each rule by its name; a rule with no name by a key no name can be, so
+  // it keeps its place and matches nothing.
+  const keyOf = (rule: unknown, index: number): string => ruleName(rule) ?? `\u0000nameless ${index}`;
+  const byName = (rules: readonly unknown[]) => new Map(rules.flatMap((rule) => {
+    const name = ruleName(rule);
+    return name === undefined ? [] : [[name, rule] as const];
+  }));
+  const inLive = new Map(live.rules.map((rule, index) => [keyOf(rule, index), rule] as const));
+  const inRecipe = byName(recipe.rules);
+  const inLast = last ? byName(last.rules) : null;
+
+  // Each rule gate.json keeps, with its definition, and which of them take
+  // the recipe's order (`ordered`); the rest keep their places.
+  const definitions = new Map<string, unknown>();
+  const ordered = new Set<string>();
+  live.rules.forEach((rule, index) => {
+    const name = keyOf(rule, index);
+    const declared = inRecipe.get(name);
+    const before = inLast?.get(name);
+    if (declared !== undefined && agree(rule, declared)) {
+      // As the recipe has it: kept as written, whatever the record says, and
+      // nothing to change or name.
+      definitions.set(name, rule);
+      ordered.add(name);
+    } else if (ruleName(rule) === undefined) {
+      definitions.set(name, rule);
+    } else if (!inLast) {
+      definitions.set(name, rule);
+      (declared !== undefined ? changes.differsFromRecipe : changes.outsideRecipe).push(name);
+    } else if (before !== undefined) {
+      const edited = !agree(rule, before);
+      if (declared === undefined) {
+        if (edited) {
+          definitions.set(name, rule);
+          changes.keptEdited.push(name);
+        } else {
+          changes.removed.push(name);
+        }
+      } else {
+        // Both recipes declare it: it's a recipe rule, so it takes the recipe's order.
+        ordered.add(name);
+        if (edited) {
+          definitions.set(name, rule);
+          if (!agree(declared, before)) changes.keptEdited.push(name);
+        } else {
+          definitions.set(name, declared);
+          changes.updated.push(name);
+        }
+      }
+    } else {
+      // No recipe declared it as it stands: a run-time rule, or one the recipe
+      // now declares otherwise.
+      definitions.set(name, rule);
+      if (declared !== undefined) changes.differsFromRecipe.push(name);
+    }
+  });
+
+  const liveOrder = live.rules.map(keyOf);
+  const recipeOrder = recipe.rules.flatMap((rule) => {
+    const name = ruleName(rule);
+    return name === undefined ? [] : [name];
+  });
+  const staying = liveOrder.filter((name) => definitions.has(name));
+
+  // Whether gate.json holds the rules both recipes declare in the last recipe's order.
+  const shared = (order: string[]) => order.filter((name) => inLast?.has(name) && inRecipe.has(name) && inLive.has(name));
+  const lastOrder = last ? last.rules.flatMap((rule) => {
+    const name = ruleName(rule);
+    return name === undefined ? [] : [name];
+  }) : [];
+  const followsLast = canonical(shared(liveOrder)) === canonical(shared(lastOrder));
+
+  let order: string[];
+  if (followsLast) {
+    // The recipe's rules fill the places its rules hold, in the recipe's order.
+    const recipeRules = recipeOrder.filter((name) => ordered.has(name));
+    let next = 0;
+    order = staying.map((name) => (ordered.has(name) ? recipeRules[next++] : name));
+  } else {
+    order = staying;
+    // Named only when it holds something back: the recipe reordered these
+    // rules, and gate.json doesn't already hold the recipe's order.
+    changes.orderKept = canonical(shared(recipeOrder)) !== canonical(shared(lastOrder))
+      && canonical(shared(liveOrder)) !== canonical(shared(recipeOrder));
+  }
+  // A recipe rule new to gate.json goes before the recipe rule that follows it
+  // there, or after the one before it when none follows.
+  recipeOrder.forEach((name, index) => {
+    if (inLive.has(name)) return;
+    definitions.set(name, inRecipe.get(name)!);
+    (inLast?.has(name) ? changes.restored : changes.added).push(name);
+    const following = recipeOrder.slice(index + 1).find((later) => order.includes(later));
+    if (following !== undefined) {
+      order.splice(order.indexOf(following), 0, name);
+      return;
+    }
+    const preceding = recipeOrder.slice(0, index).reverse().find((earlier) => order.includes(earlier));
+    if (preceding !== undefined) order.splice(order.indexOf(preceding) + 1, 0, name);
+    else order.push(name);
+  });
+
+  // Only the recipe's rules move; every other rule keeps its place.
+  const stayedInOrder = longestShared(staying.filter((name) => ordered.has(name)), order.filter((name) => ordered.has(name)));
+  changes.moved = order.filter((name) => ordered.has(name) && !stayedInOrder.has(name));
+
+  // `default` as the gate reads it, compared as written once read.
+  const liveDefault = behaviorOf(live.default);
+  const recipeDefault = behaviorOf(recipe.default);
+  let defaultBehavior = live.default;
+  let defaultChanged = false;
+  const shownBehavior = (value: unknown): string => (typeof value === 'string' ? value : JSON.stringify(value));
+  if (!last) {
+    if (!same(liveDefault, recipeDefault)) changes.defaultDiffers = { kept: shownBehavior(liveDefault), recipe: shownBehavior(recipeDefault) };
+  } else {
+    const lastDefault = behaviorOf(last.default);
+    if (same(liveDefault, lastDefault) || same(liveDefault, recipeDefault)) {
+      if (!same(recipeDefault, liveDefault)) {
+        defaultBehavior = recipe.default;
+        defaultChanged = true;
+        changes.defaultChange = { from: shownBehavior(liveDefault), to: shownBehavior(recipeDefault) };
+      }
+    } else if (!same(recipeDefault, lastDefault)) {
+      changes.defaultKept = shownBehavior(liveDefault);
+    }
+  }
+
+  return {
+    rules: order.map((name) => definitions.get(name)),
+    default: defaultBehavior,
+    defaultChanged,
+    changes,
+  };
+}
+
+/** The log line a start gives its changes, or null when it changed nothing worth saying. */
+export function reconcileLine(changes: RecipeChanges): string | null {
+  const parts: string[] = [];
+  if (changes.recordUnreadable !== undefined) {
+    parts.push(`the recorded recipe couldn't be read (${changes.recordUnreadable}), so this start removed and redefined nothing`);
+  }
+  const list = (label: string, names: string[]) => {
+    if (names.length > 0) parts.push(`${label} ${names.join(', ')}`);
+  };
+  list('added', changes.added);
+  list('removed', changes.removed);
+  list('updated', changes.updated);
+  list('restored', changes.restored);
+  list('moved', changes.moved);
+  list('kept as edited, though the recipe changed or dropped it:', changes.keptEdited);
+  if (changes.differsFromRecipe.length > 0) {
+    parts.push(
+      `kept, though the recipe defines it otherwise: ${changes.differsFromRecipe.join(', ')} `
+        + '(remove such a rule, and the next start restores it from the recipe)',
+    );
+  }
+  if (changes.outsideRecipe.length > 0) {
+    parts.push(
+      `kept, not in the recipe: ${changes.outsideRecipe.join(', ')} `
+        + "(a stale one can be removed, and no start brings it back)",
+    );
+  }
+  if (changes.defaultChange) parts.push(`default ${changes.defaultChange.from} → ${changes.defaultChange.to}`);
+  if (changes.defaultKept) parts.push(`default kept as edited (${changes.defaultKept}), though the recipe changed it`);
+  if (changes.defaultDiffers) {
+    parts.push(
+      `default kept as gate.json has it (${changes.defaultDiffers.kept}), though the recipe's is ${changes.defaultDiffers.recipe} `
+        + "(set it to the recipe's, and later starts follow the recipe)",
+    );
+  }
+  if (changes.orderKept) parts.push("gate.json's order kept, though the recipe reordered its rules, since a recipe rule was moved in it");
+  return parts.length > 0 ? `[gate] the recipe was applied to gate.json: ${parts.join('; ')}` : null;
+}

package/src/gate/types.ts

@@ -17,9 +17,10 @@
  * bucket are denied (decision: trigger=false). Tokens regenerate at one per
  * `refillIntervalMs`, capped at `tokens`. Buckets are partitioned by the
  * value of `keyBy` resolved against event metadata — so a per-user limit
- * uses `keyBy: "senderId"`, a per-channel limit uses `keyBy: "channelId"`,
- * etc. With no `keyBy` (or when the resolved value is missing), one shared
- * bucket is used for the policy.
+ * uses `keyBy: "senderId"`, a per-channel limit uses `keyBy: "channelId"`
+ * (resolved to the channel's registered id, as `keyBy` says), etc. With no
+ * `keyBy` (or when the resolved value is missing), one shared bucket is used
+ * for the policy.
  */
 export interface RateLimitConfig {
   /** Max bucket capacity, also the initial fill. Must be > 0. */
@@ -27,8 +28,12 @@ export interface RateLimitConfig {
   /** Milliseconds between token regenerations. Must be > 0. */
   refillIntervalMs: number;
   /**
-   * Metadata field name to partition buckets by. If absent or the metadata
-   * field is missing on a given event, all events share one bucket.
+   * Metadata field name to partition buckets by. `"channelId"` takes the
+   * channel's registered id where the gate resolves one, as `match.channel`
+   * does, so a channel's push events share its messages' bucket, a voice
+   * report's included, though it carries no `channelId`. Otherwise, if
+   * absent or the metadata field is missing on a given event, all such
+   * events share one bucket.
    */
   keyBy?: string;
 }
@@ -45,7 +50,8 @@ export interface RateLimitConfig {
 export interface PassiveSampleConfig {
   /** Trigger every N-th match. Must be > 0. */
   every: number;
-  /** Optional metadata field name for separate per-key counters. */
+  /** Optional metadata field name for separate per-key counters, resolved
+   *  as `RateLimitConfig.keyBy` is. */
   keyBy?: string;
 }
 
@@ -68,7 +74,12 @@ export interface GatePolicyMatch {
   scope?: string[];
   /** ServerId to match (exact or glob with *). */
   source?: string;
-  /** ChannelId to match (exact or glob with *). */
+  /** Channel to match (exact or glob with *): against the event's channel
+   *  id, then the registered id the gate resolves for it
+   *  (`resolveRouteChannel`). A channels/incoming message carries the
+   *  registered id (`discord:<guild>:<channel>`), and a push the adapter's
+   *  raw one or none, so a registered-form pattern meets every event in its
+   *  channel whose push names the channel, and a raw id only push events. */
   channel?: string;
   /** Content text filter. */
   filter?: { type: 'text' | 'regex'; pattern: string };
@@ -155,7 +166,17 @@ export interface GateConfig {
 export interface GateOptions {
   /** Path to gate.json. Default: derived from storePath. */
   configPath?: string;
-  /** Initial config, seeded to gate.json if the file doesn't exist. */
+  /**
+   * The recipe's gate config. The first start seeds gate.json with it. Each
+   * later start merges it into gate.json against the recipe last applied,
+   * which the gate keeps beside gate.json (`gate.recipe.json`): a rule the
+   * recipe dropped, renamed, moved or redefined follows it, a rule edited at
+   * run time or by hand stays, and so does one no recipe declared. Rules are
+   * merged by name, compared by what they mean and kept as written: a
+   * recipe's rule with no name is never merged, as one with no name was never
+   * added, and where gate.json or the recipe names a rule twice, a start only
+   * adds the rules gate.json lacks. See `recipe-reconcile.ts`.
+   */
   config?: GateConfig;
   /**
    * Path to a JSON file listing user ids that may wake the agent even while
@@ -231,6 +252,47 @@ export interface GateEventInfo {
   tags?: string[];
 }
 
+/** An MCPL event whose content the framework stored at arrival, as a
+ *  batched wake names it to the framework (EventGate's `isNewestEntry`):
+ *  a channel message by its server, channel and message id, a push event by
+ *  its server and event id. */
+export interface GateEntryRef {
+  eventType: string;
+  serverId?: string;
+  channelId?: string;
+  messageId?: string;
+  eventId?: string;
+}
+
+/** A batched wake's `[Gate: …]` line that the gate handed to the wake rather
+ *  than wrote: its batch was one event whose entry was still the newest in
+ *  the window when the batch fired (EventGate's `isNewestEntry`). A fresh
+ *  start of the wake's turn decides it (the framework's placeWakeLines): the
+ *  delivery agent's own start leaves it out while that entry is still the
+ *  newest, and writes it once something follows; a co-resident's start
+ *  places none; two or more such lines are each written;
+ *  and none is written while the host is quiesced or another reader of the
+ *  residents' shared slot has a turn alive. A line left out stays for a
+ *  later fresh start of the same wake. Its text is rendered when it's
+ *  written (wakeLineText), so its age is true then.
+ *
+ *  Every request for one wake carries the same object: the framework writes
+ *  each line once by its identity, across the wake's retries and holds. A
+ *  host that hands the gate's requests on itself passes the line on as it
+ *  is, not a copy per agent. */
+export interface WakeLine {
+  /** The event's own entry. */
+  entry: GateEntryRef;
+  policyNames: string[];
+  /** The channel as the line names it to the agent. */
+  shown: string;
+  /** When the event arrived (ms): the line's age is counted from it to when
+   *  the line is written (wakeLineText). */
+  at: number;
+  /** The channel the line names, as the omission's trace reports it. */
+  channelId?: string;
+}
+
 /** Per-policy runtime statistics (for gate:status). */
 export interface GatePolicyStats {
   name: string;

package/src/index.ts

@@ -2,9 +2,10 @@
 export * from './types/index.js';
 
 // Core classes
-export { AgentFramework, BudgetPreflightError, ProviderWaitNotSleptError, QuiesceBlockedError, ResumeBlockedError } from './framework.js';
+export { AgentFramework, BudgetPreflightError, DefaultErrorPolicy, ProviderWaitNotSleptError, QuiesceBlockedError, ResumeBlockedError } from './framework.js';
 export type { RuntimeSettingsPreview, HostModeStatus } from './framework.js';
 export { Agent } from './agent.js';
+export { storedInjectionMarkOf, type StoredInjectionMark } from './stored-injections.js';
 export type { StartStreamResult } from './agent.js';
 export { ProcessQueueImpl } from './queue.js';
 export { ModuleRegistry } from './module-registry.js';
@@ -67,12 +68,12 @@ export { buildCodeExecutionToolDefinition, CODE_EXECUTION_TOOL_NAME } from './co
 export type { SessionUsage, AgentUsage, SessionUsageSnapshot, UsageUpdatedEvent } from './usage/index.js';
 
 // EventGate
-export { EventGate, type WakeProvenance } from './gate/index.js';
-export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior } from './gate/index.js';
+export { EventGate, wakeLineText, type WakeProvenance, type WritePlacement } from './gate/index.js';
+export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior, WakeLine } from './gate/index.js';
 
 // MCPL channel registry (exposed for modules that need channel-level operations)
 export { ChannelRegistry } from './mcpl/index.js';
-export type { PublishRefusalReason } from './mcpl/index.js';
+export type { ChannelRef, PublishRefusalReason } from './mcpl/index.js';
 
 // Where each accepted inbound item came from (`metadata.inboundSource`), and
 // the digest its delivered and stored bodies are stamped with
@@ -95,6 +96,8 @@ export type { McplServerConfig } from './mcpl/index.js';
 // exactly the way the framework host does: MCPL over stdio or WebSocket, and
 // modern MCP over stdio or Streamable HTTP)
 export { McplServerConnection, McplRequestError, McplProtocolVersionError, McplUnreapedLaunchError } from './mcpl/index.js';
+// RFC-014: the meta-tools' module and its names.
+export { ToolsetsModule, TOOLSETS_MODULE, META_TOOL_NAMES } from './mcpl/index.js';
 export { ModernMcpConnection } from './mcpl/index.js';
 export type { ModernToolCallResult } from './mcpl/index.js';
 export {