@animalabs/agent-framework 0.28.0 → 0.30.0

package/src/agent.ts

@@ -1,3 +1,4 @@
+import { NOTICE_TAG } from './notice-tags.js';
 import { heartbeatToolAlias } from './heartbeat/heartbeat.js';
 import type { Membrane, NormalizedMessage, NormalizedRequest, ContentBlock, ThinkingBindingEntry, YieldingStream } from '@animalabs/membrane';
 import { isAbortedResponse } from '@animalabs/membrane';
@@ -320,6 +321,11 @@ export class Agent {
   /** Provider-specific request parameters forwarded unchanged by Membrane. */
   readonly providerParams?: Record<string, unknown>;
   readonly sameRoundThinkTextPolicy: AgentConfig['sameRoundThinkTextPolicy'];
+  /** The participant name this agent's turns are presented under (see AgentConfig.presentAs). */
+  readonly presentAs: string;
+  /** Stored participants presented as this agent's own turns: its name plus AgentConfig.selfParticipants. */
+  private readonly ownParticipants: ReadonlySet<string>;
+  private readonly deniedAtDispatch: ReadonlySet<string>;
 
   private _state: AgentState = { status: 'idle' };
   private _inferenceStartedAt = 0;
@@ -449,6 +455,9 @@ export class Agent {
     this.prefillUserMessage = config.prefillUserMessage;
     this.providerParams = config.providerParams;
     this.sameRoundThinkTextPolicy = config.sameRoundThinkTextPolicy;
+    this.presentAs = config.presentAs ?? config.name;
+    this.ownParticipants = new Set([config.name, ...(config.selfParticipants ?? [])]);
+    this.deniedAtDispatch = new Set(config.denyToolsAtDispatch ?? []);
     this.maxStreamTokens = config.maxStreamTokens ?? 150_000;
     // The window size converted as the projection's comparison (`projected > window`) converts it, so a string such
     // as "200000" from a JSON or YAML config is its number, for every rule that reads it. A value whose number isn't
@@ -508,6 +517,36 @@ export class Agent {
     return alias !== undefined && this.allowedTools.includes(alias);
   }
 
+  /**
+   * Whether a call to an advertised tool is refused at dispatch
+   * (see AgentConfig.denyToolsAtDispatch).
+   */
+  deniesAtDispatch(toolName: string): boolean {
+    return this.deniedAtDispatch.has(toolName);
+  }
+
+  /** Whether a stored participant is this agent's own voice. */
+  isOwnParticipant(participant: string): boolean {
+    return this.ownParticipants.has(participant);
+  }
+
+  /**
+   * Role assignment for a request: every participant that is this agent's
+   * own voice — its name, and for a derived agent the agent it inherited
+   * from — is presented under one name, which the formatter maps to the
+   * assistant role. Stored authorship is untouched; this shapes the request
+   * only. For a plain agent (no selfParticipants, presentAs = name) the
+   * input is returned as is.
+   */
+  private presentOwnTurns(messages: NormalizedMessage[]): NormalizedMessage[] {
+    if (this.ownParticipants.size === 1 && this.presentAs === this.name) return messages;
+    return messages.map((m) =>
+      this.ownParticipants.has(m.participant) && m.participant !== this.presentAs
+        ? { ...m, participant: this.presentAs }
+        : m,
+    );
+  }
+
   /**
    * Check if a source can trigger inference for this agent.
    */
@@ -1642,8 +1681,9 @@ export class Agent {
       // What it holds of the stored injections is what the agent last saw.
       this.noteRenderedInjections(compiled);
       const { systemInjections } = compiled;
-      // The framework's own pricing stamp never goes out (thinking-token-stamp.ts).
-      const messages = withoutTokenEstimates(compiled.messages);
+      // The framework's own pricing stamp never goes out (thinking-token-stamp.ts);
+      // the agent's own turns are then presented under its name (presentOwnTurns).
+      const messages = this.presentOwnTurns(withoutTokenEstimates(compiled.messages));
       // Read once, after the first compile, since results may have become
       // ready while it ran; the refusal retry, assembled while the agent is
       // inferring, sends the same ones.
@@ -1655,6 +1695,7 @@ export class Agent {
         system: this.buildSystemPrompt(systemInjections),
         tools: tools.length > 0 ? tools : undefined,
         ...this.requestSettings(),
+        assistantParticipant: this.presentAs,
       };
     };
     const request = await assemble();
@@ -1890,6 +1931,8 @@ export class Agent {
     // The framework's own pricing stamp never goes out (thinking-token-stamp.ts).
     messages = withoutTokenEstimates(messages);
 
+    messages = this.presentOwnTurns(messages);
+
     // Silent heartbeat ticks and replies to a [Continue] turn store no
     // prompt row. Render each request-only turn before its response's first
     // surviving row, so the wire formatter cannot merge the response into the
@@ -1900,7 +1943,7 @@ export class Agent {
     // renders. "First" is per agent: a broadcast tick shares its eventId with
     // every resident.
     const index = this.indexRequestOnlyRows();
-    const rendered = renderRequestOnlyRows(messages, index, this.name);
+    const rendered = renderRequestOnlyRows(messages, index, this.presentAs);
     messages = rendered.messages;
     // A tick opens wherever its separator isn't already rendered: on its first
     // request, and on a restart whose compile left none of the tick's rows,
@@ -1919,7 +1962,7 @@ export class Agent {
     let continuePrompt: RequestOnlyPrompt | undefined;
     if (openingTick) {
       messages = [...messages, silentHeartbeatSeparatorTurn()];
-    } else if (endsOnOwnMessage(messages, this.name, injectionTail)) {
+    } else if (endsOnOwnMessage(messages, this.presentAs, injectionTail)) {
       // Safety: ensure messages don't end with an assistant message.
       // Some models reject trailing assistant messages ("prefill not supported"),
       // and after context compression a stale assistant turn can end up last.
@@ -1969,7 +2012,7 @@ export class Agent {
       cacheTtl: this.cacheTtl,
       ...(this.prefillUserMessage && { prefillUserMessage: this.prefillUserMessage }),
       ...(this.providerParams && { providerParams: this.providerParams }),
-      assistantParticipant: this.name,
+      assistantParticipant: this.presentAs,
     };
   }
 
@@ -2062,7 +2105,7 @@ export class Agent {
     try {
       const stored = cm.getAllMessages() as unknown as readonly StoredRowLike[];
       if (this.requestOnlyIndex?.source === stored) return this.requestOnlyIndex.index;
-      const index = indexRequestOnlyRows(stored, this.name);
+      const index = indexRequestOnlyRows(stored, this.ownParticipants);
       this.requestOnlyIndex = { source: stored, index };
       return index;
     } catch (error) {
@@ -2398,7 +2441,9 @@ export class Agent {
     }
 
     const injectedText = systemInjections.map((block) =>
-      block.type === 'text' ? block.text : `[${block.type} block not shown: the system prompt carries text only.]`);
+      block.type === 'text'
+        ? block.text
+        : `[${NOTICE_TAG.blockNotShown}: ${/^[aeiou]/i.test(block.type) ? 'an' : 'a'} ${block.type} block; the system prompt carries text only.]`);
 
     return this.systemPrompt + '\n' + injectedText.join('\n');
   }

package/src/api/mcp-server-core.ts

@@ -12,7 +12,7 @@
  */
 
 import WebSocket from 'ws';
-import { createInterface } from 'node:readline';
+import { escapeLineSeparators, readLines } from '../line-reader.js';
 import type { ApiRequest, ApiResponse, ApiEvent } from './types.js';
 
 // ============================================================================
@@ -86,18 +86,7 @@ export class McpServer {
     // Connect to WebSocket API
     await this.connectWs();
 
-    // Set up stdio interface
-    const rl = createInterface({
-      input: process.stdin,
-      output: process.stdout,
-      terminal: false,
-    });
-
-    rl.on('line', (line) => {
-      this.handleInput(line);
-    });
-
-    rl.on('close', () => {
+    readLines(process.stdin, (line) => this.handleInput(line), () => {
       this.close();
       process.exit(0);
     });
@@ -667,7 +656,7 @@ export class McpServer {
   }
 
   private send(message: JsonRpcResponse | JsonRpcNotification): void {
-    process.stdout.write(JSON.stringify(message) + '\n');
+    process.stdout.write(escapeLineSeparators(JSON.stringify(message)) + '\n');
   }
 
   close(): void {

package/src/api/server.ts

@@ -489,9 +489,13 @@ export class ApiServer {
     if (!params.participant || !params.content) {
       throw new Error('participant and content are required');
     }
-    // ApiModule stores the message as one text block, which context-manager
-    // refuses unless its text is a string, so content that isn't text is
-    // refused here, where the caller hears it, rather than at dispatch.
+    // ApiModule stores the participant as a name, and the message as one text
+    // block, which context-manager refuses unless its text is a string. So a
+    // participant or content that isn't text is refused here, where the
+    // caller hears it, rather than at dispatch.
+    if (typeof params.participant !== 'string') {
+      throw new Error('participant must be text');
+    }
     if (typeof params.content !== 'string') {
       throw new Error('content must be text');
     }

package/src/author-presentation.ts

@@ -0,0 +1,81 @@
+/**
+ * The author of a channel message, presented to the model.
+ *
+ * MCPL `channels/incoming` carries the author as a field, `author: {id,
+ * name}`, and the body alone as content (SPEC §14); the framework stores
+ * the message under the anonymous participant `user` with the author in
+ * `metadata.author`. The wire formatter writes the participant, so without
+ * this step the model reads `user: <text>` and who spoke is lost. Servers
+ * that pre-render `Name: body` into the text themselves (portal-mcpl) are
+ * left as they are: the rule is idempotent, so the name appears once
+ * whichever shape a server sends.
+ *
+ * Applied where the framework stores a `channels/incoming` message — the
+ * compiled view carries no metadata, so the name has to be in the stored
+ * text to reach the wire — and to a tune-out backlog line, which reads the
+ * metadata and must not name an author twice. The author stays in
+ * `metadata.author` as the structured record.
+ */
+import type { ContentBlock, MessageMetadata } from '@animalabs/membrane';
+import { suppliedValue } from './supplied-text.js';
+
+/** The participant the framework stores channel traffic under: a role, not a name. */
+export const ANONYMOUS_PARTICIPANT = 'user';
+
+type TextBlock = Extract<ContentBlock, { type: 'text' }>;
+
+/** The author a stored message names, when it names one. */
+export function authorNamed(metadata: Record<string, unknown> | MessageMetadata | undefined): string | undefined {
+  const name = (metadata?.author as { name?: unknown } | undefined)?.name;
+  return typeof name === 'string' && name.length > 0 ? name : undefined;
+}
+
+/** Whether `text` already begins with the author's own line: `Name:` then a space or the end. */
+export function beginsWithAuthor(author: string, text: string): boolean {
+  if (!text.startsWith(author) || text.charAt(author.length) !== ':') return false;
+  const after = text.charAt(author.length + 1);
+  return after === '' || after === ' ' || after === '\n';
+}
+
+/**
+ * The author's name as a line of the framework's writes it: a value someone
+ * supplied, kept to one line with its notice openings marked (main's #852,
+ * suppliedValue), so a name can't open a line that reads as the framework's
+ * own notice.
+ */
+export function authorShown(author: string): string {
+  return suppliedValue(author);
+}
+
+/** Whether `text` begins with the author's line, as the author wrote their
+ *  name or as the framework shows it (authorShown). */
+export function beginsWithAuthorLine(author: string, text: string): boolean {
+  return beginsWithAuthor(author, text) || beginsWithAuthor(authorShown(author), text);
+}
+
+/** `author: text`, unless `text` begins that way already. */
+export function authorLine(author: string, text: string): string {
+  return beginsWithAuthorLine(author, text) ? text : `${authorShown(author)}: ${text}`;
+}
+
+/**
+ * A message stored under the anonymous participant that names an author is
+ * presented with the author before its first text block — or, with no text
+ * block, as a leading `Name:` line before its media. Any other message, and
+ * one whose text already begins with the author's line, is returned as is.
+ * Never mutates its input.
+ */
+export function presentAuthor<M extends { participant: string; content: ContentBlock[]; metadata?: MessageMetadata | Record<string, unknown> }>(message: M): M {
+  if (message.participant !== ANONYMOUS_PARTICIPANT) return message;
+  const author = authorNamed(message.metadata);
+  if (author === undefined) return message;
+  const index = message.content.findIndex((b) => b.type === 'text');
+  if (index === -1) {
+    return { ...message, content: [{ type: 'text', text: `${authorShown(author)}:` } as TextBlock, ...message.content] };
+  }
+  const block = message.content[index] as TextBlock;
+  if (typeof block.text !== 'string' || beginsWithAuthorLine(author, block.text)) return message;
+  const content = [...message.content];
+  content[index] = { ...block, text: `${authorShown(author)}: ${block.text}` };
+  return { ...message, content };
+}

package/src/auto-continue.ts

@@ -5,6 +5,8 @@
  * row the next turn reads.
  */
 
+import { NOTICE_TAG } from './notice-tags.js';
+
 /** The reason on a continuation's wake (InferenceRequest.reason). */
 export const AUTO_CONTINUE_REASON = 'auto-continue';
 
@@ -33,11 +35,15 @@ export function autoContinueNotice(opts: {
   stop: string;
   last: boolean;
   heldAfterSend?: boolean;
+  /** The run began with a heartbeat's turn, whose plain speech is held as drafts. */
+  heartbeat?: boolean;
 }): string {
-  return `[continue] ${opts.agentName}, another turn starts now.` +
+  return `[${NOTICE_TAG.continue}] ${opts.agentName}, another turn starts now.` +
     (opts.heldAfterSend
       ? ' Some or all of your closing words last turn were held, not sent: a send that turn may already have posted where they were going.'
       : '') +
-    ` If you're done, ${opts.stop}; anything you write without it is sent as usual.` +
+    (opts.heartbeat
+      ? ` If you're done, ${opts.stop}; plain words you write without it and with no destination are held as drafts, as on the heartbeat's turn, and an explicit send reaches a channel.`
+      : ` If you're done, ${opts.stop}; anything you write without it is sent as usual.`) +
     (opts.last ? ' This is the last continuation in a row: after this turn you wait for the next event either way.' : '');
 }

package/src/code-execution/isolate/runner.ts

@@ -4,11 +4,13 @@
  * which ends with it, so nothing a script held stays after it.
  *
  * Every frame from the child is decoded and checked before the parent acts on
- * it, since the child is untrusted. A frame that breaks the protocol, a child
- * that exits without saying how the script ended, or one that doesn't stop
- * when asked, ends the run as crashed. A tool call goes to `onToolCall`, the
- * bridge to the framework's dispatcher, and its outcome goes into the run's
- * call record at dispatch, as running until it's answered.
+ * it, since the child is untrusted. A frame that breaks the protocol, or a
+ * child that exits without saying how the script ended when no stop was
+ * asked, ends the run as crashed. One that doesn't stop when asked is ended
+ * once the stop's grace has passed, and the run ends stopped, marked short.
+ * A tool call goes to `onToolCall`, the bridge to the framework's dispatcher,
+ * and its outcome goes into the run's call record at dispatch, as running
+ * until it's answered.
  *
  * What the host holds for a script is bounded: at most MAX_CALLS_IN_FLIGHT of
  * its calls wait for answers at once, and at most MAX_CALLS_IN_FLIGHT are out

package/src/code-execution/isolate/scripts.ts

@@ -26,6 +26,7 @@
  * dispatcher a script's calls go through, and how to wake an agent.
  */
 
+import { NOTICE_TAG } from '../../notice-tags.js';
 import { ChildCapacity, ScriptRun, type CallAnswer, type Ending, type ScriptRunOptions, type ToolAnswer } from './runner.js';
 import type { CallSummary } from './calls.js';
 import type { OutputBounds, OutputWindow } from './output.js';
@@ -478,10 +479,10 @@ function leftEndingText(scriptId: string, ending: Ending): string {
       : ending.how === 'stopped'
         ? ending.why ? `was stopped: ${ending.why}` : 'was stopped at its limit'
         : 'ended';
-  return `[script ${scriptId}] Your script ${how}. {"action": "wait", "script_id": "${scriptId}"} gives its result.`;
+  return `[${NOTICE_TAG.script} ${scriptId}] Your script ${how}. {"action": "wait", "script_id": "${scriptId}"} gives its result.`;
 }
 
 function wakeText(scriptId: string, payloadJson: string, n: number, max: number, ageMs: number): string {
   const minutes = Math.round(ageMs / 60_000);
-  return `[script ${scriptId}] Woke you with wake_agent(), ${minutes} min after it started (wake ${n} of ${max}): ${payloadJson}`;
+  return `[${NOTICE_TAG.script} ${scriptId}] Woke you with wake_agent(), ${minutes} min after it started (wake ${n} of ${max}): ${payloadJson}`;
 }

package/src/dendrite/index.ts

@@ -0,0 +1,32 @@
+export { AgentRegistry, AgentSpecError } from './registry.js';
+export type { AgentRegistryOptions, RestoreOutcome, ReconcileOutcome } from './registry.js';
+export {
+  residentSpec,
+  subconsciousSpec,
+  conversationForkSpec,
+  workerSpec,
+  taskForkSpec,
+  DEFAULT_TASK_IDLE_TIMEOUT_MS,
+} from './presets.js';
+export type { BoundedJobOptions } from './presets.js';
+export type {
+  AgentName,
+  AgentKind,
+  AgentRoles,
+  AgentLifetime,
+  ActivationBounds,
+  ParentEndPolicy,
+  ResultRoute,
+  ObserveEdge,
+  AgentRelationships,
+  ContextInheritance,
+  AgentSpec,
+  AgentEndReason,
+  AgentRef,
+  ActivationRecord,
+  AgentRecord,
+  HeldMail,
+  RegistrySnapshot,
+  EndOutcome,
+  PolicyEpoch,
+} from './types.js';

package/src/dendrite/presets.ts

@@ -0,0 +1,149 @@
+/**
+ * Presets — the historical agent kinds expressed as {@link AgentSpec}
+ * values. They are configurations of the common machinery, not engines:
+ * everything a preset decides is visible in the spec it returns, and a host
+ * may register a spec that matches none of them.
+ */
+
+import type { AgentName, AgentSpec, ContextInheritance, ResultRoute } from './types.js';
+
+/** Default idle bound for a bounded job with no explicit deadline (matches the run watchdog). */
+export const DEFAULT_TASK_IDLE_TIMEOUT_MS = 15 * 60_000;
+
+/**
+ * A resident: persistent, declared in configuration, reads the residents'
+ * shared message slot. The first one declared owns default delivery.
+ */
+export function residentSpec(name: AgentName, options: { primary: boolean }): AgentSpec {
+  return {
+    name,
+    kind: 'resident',
+    roles: {
+      defaultDelivery: options.primary,
+      receivesUntargeted: true,
+      receivesGateWakes: true,
+      ownsProviderScheduling: true,
+    },
+    lifetime: { kind: 'persistent' },
+    readsSharedSlot: true,
+    namespace: `agents/${name}`,
+  };
+}
+
+/**
+ * The subconscious: a persistent attention tenant of the resident it
+ * serves. It persists across policy epochs (cancelling a tune-out ends a
+ * channel's cadence, not this agent), observes the residents' slot with
+ * held traffic included, is never a broadcast recipient, and ends with its
+ * resident.
+ */
+export function subconsciousSpec(name: AgentName, serves: AgentName): AgentSpec {
+  return {
+    name,
+    kind: 'subconscious',
+    roles: {
+      defaultDelivery: false,
+      receivesUntargeted: false,
+      receivesGateWakes: false,
+      ownsProviderScheduling: true,
+    },
+    lifetime: { kind: 'persistent' },
+    spawnedBy: serves,
+    onParentEnd: 'end',
+    observes: [{ includeHeld: true }],
+    resultTo: { to: serves, as: 'message' },
+    readsSharedSlot: true,
+    namespace: `subconscious/${serves}`,
+  };
+}
+
+/**
+ * A conversation fork: derived from a template agent's context at bind
+ * time, bound to one channel, independent continuation, ends on idle.
+ */
+export function conversationForkSpec(
+  name: AgentName,
+  options: {
+    template: AgentName;
+    /** The channel it's bound to, on its server. */
+    homeChannel: { serverId: string; channelId: string };
+    idleTtlMs: number;
+    inherit?: Partial<ContextInheritance>;
+  },
+): AgentSpec {
+  return {
+    name,
+    kind: 'conversation-fork',
+    roles: {
+      defaultDelivery: false,
+      receivesUntargeted: false,
+      // Woken by its own channel's debounced traffic through the host-wide gate.
+      receivesGateWakes: true,
+      ownsProviderScheduling: false,
+    },
+    lifetime: { kind: 'idle', idleTtlMs: options.idleTtlMs },
+    spawnedBy: options.template,
+    onParentEnd: 'orphan',
+    inherit: { from: options.template, mode: 'copy', ...options.inherit },
+    // A copy renames the template's turns as it copies them. A shared
+    // inheritance has no copy step, so the mapping is declared instead.
+    ...(options.inherit?.mode === 'shared' ? { selfParticipants: [options.template] } : {}),
+    homeChannel: { serverId: options.homeChannel.serverId, channelId: options.homeChannel.channelId },
+    namespace: `conversations/${name}`,
+  };
+}
+
+export interface BoundedJobOptions {
+  /** Who created it. Absent for an independent job driven by the host. */
+  spawnedBy?: AgentName;
+  /** Where its completion returns. */
+  resultTo?: ResultRoute;
+  deadlineMs?: number;
+  idleTimeoutMs?: number;
+  maxTurns?: number;
+  namespace?: string;
+  metadata?: Record<string, unknown>;
+}
+
+function boundedJob(name: AgentName, options: BoundedJobOptions): Omit<AgentSpec, 'kind'> {
+  return {
+    name,
+    roles: {
+      defaultDelivery: false,
+      receivesUntargeted: false,
+      receivesGateWakes: false,
+      ownsProviderScheduling: false,
+    },
+    lifetime: {
+      kind: 'task',
+      ...(options.deadlineMs !== undefined ? { deadlineMs: options.deadlineMs } : {}),
+      idleTimeoutMs: options.idleTimeoutMs ?? DEFAULT_TASK_IDLE_TIMEOUT_MS,
+      ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}),
+    },
+    ...(options.spawnedBy ? { spawnedBy: options.spawnedBy, onParentEnd: 'orphan' as const } : {}),
+    ...(options.resultTo ? { resultTo: options.resultTo } : {}),
+    namespace: options.namespace ?? `subagent/${name}`,
+    ...(options.metadata ? { metadata: options.metadata } : {}),
+  };
+}
+
+/** A fresh worker: new identity and context, one bounded job, a result route. */
+export function workerSpec(name: AgentName, options: BoundedJobOptions = {}): AgentSpec {
+  return { ...boundedJob(name, options), kind: 'worker' };
+}
+
+/**
+ * A task fork: the parent's context at a checkpoint, a private
+ * continuation, one bounded job, a return.
+ */
+export function taskForkSpec(
+  name: AgentName,
+  options: BoundedJobOptions & { parent: AgentName; inherit?: Partial<ContextInheritance> },
+): AgentSpec {
+  return {
+    ...boundedJob(name, { ...options, spawnedBy: options.spawnedBy ?? options.parent }),
+    kind: 'task-fork',
+    inherit: { from: options.parent, mode: 'copy', ...options.inherit },
+    ...(options.inherit?.mode === 'shared' ? { selfParticipants: [options.parent] } : {}),
+  };
+}