@animalabs/agent-framework 0.29.0 → 0.30.0

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/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] } : {}),
+  };
+}