@animalabs/agent-framework 0.21.1 → 0.22.0

package/src/record-journal.ts

@@ -0,0 +1,246 @@
+/**
+ * An append-only journal of typed Chronicle records that does not follow
+ * branch switches.
+ *
+ * Chronicle's branch state — snapshot, tree and log states — rewinds with a
+ * historical rollback (createBranchAt + switchBranch). Typed records do not:
+ * `getRecordIdsByType` enumerates them from every branch, in global order, and
+ * they survive `deleteBranch`, reopen and a hard kill. A journal is for state
+ * that must not rewind with the conversation but should live and die with its
+ * store: what a workspace's disk last agreed with, what reached a recipient,
+ * what became of a suppressed draft.
+ *
+ * Durability. A record append reaches the OS before `append` returns, so it
+ * survives a killed process, while branch-state commits are buffered until
+ * `store.sync()`: a record appended after a state commit can outlive that
+ * commit. Two barriers, each named where it's needed and neither implied by
+ * the `{id, sequence}` an append returns:
+ *  - `afterCommittedState: true` syncs BEFORE appending — for an entry that
+ *    asserts state committed just before it, so the entry can never survive
+ *    without that state;
+ *  - `durable: true` syncs AFTER appending — for an entry that must be on
+ *    stable storage before the caller acts on it (an attempt before its
+ *    outbound request, an intent before its disk effect).
+ *
+ * Checkpoints bound the replay at open: `checkpoint(snapshot)` records the
+ * caller's reduced state together with the last entry it covers, and `load()`
+ * returns the latest checkpoint's snapshot plus only the entries appended
+ * after it. A journal that never checkpoints replays everything. What entries
+ * mean, how they reduce, and when to checkpoint stay with the caller.
+ *
+ * One writer per record type: a checkpoint covers every entry up to the last
+ * one THIS journal loaded or appended, so entries another instance appended
+ * to the same type in between would be covered without being reduced.
+ *
+ * An ambiguous write must be resolved before the journal writes again. Once
+ * `append` or `checkpoint` has handed a record to the store, a failure leaves
+ * a record the caller didn't reduce, or may leave one, and a later checkpoint
+ * would cover it without its ever entering the reducer. There are two kinds:
+ *  - The store's append itself throws. Its record may still be in the store's
+ *    log, outside this process's view of the store: the store writes a
+ *    record to its log, syncs the log every so often, and only then indexes
+ *    the record, which is what `getRecordIdsByType` reads. So a failed sync
+ *    leaves a record that reopening the store will find and no `load()` on
+ *    this store can. Nothing but a reopen rereads the log, so from then on
+ *    every `append` and `checkpoint` throws, for the life of the journal. A
+ *    journal on the store reopened, as at the next start, loads that record
+ *    with its tail for the caller to reduce.
+ *  - A failure after the append returned: a `durable` barrier, or reading
+ *    the id it returned. The record is in this process's view, so every
+ *    further `append` and `checkpoint` throws until `load()` has replayed the
+ *    tail, that record included, for the caller to reduce.
+ * A failure BEFORE the record reaches the store (the `afterCommittedState`
+ * sync) wrote nothing and leaves the journal usable.
+ */
+
+import type { JsStore } from '@animalabs/chronicle';
+
+/** Where an appended record landed. Not a durability receipt — see the barriers. */
+export interface JournalRecordRef {
+  /** Chronicle record id: global, increasing in append order. */
+  id: string;
+  /** The record's sequence on the branch current when it was appended. */
+  sequence: number;
+}
+
+export interface JournalEntry<Entry> extends JournalRecordRef {
+  entry: Entry;
+}
+
+export interface JournalLoad<Entry, Snapshot> {
+  /** The latest checkpoint's snapshot, or null when none was written. */
+  snapshot: Snapshot | null;
+  /** Every entry appended after that checkpoint, in append order. */
+  entries: Array<JournalEntry<Entry>>;
+}
+
+export interface AppendOptions {
+  /** `store.sync()` before appending: the entry asserts state committed just before it. */
+  afterCommittedState?: boolean;
+  /** `store.sync()` after appending: the entry must be on stable storage before the caller acts. */
+  durable?: boolean;
+}
+
+interface CheckpointPayload<Snapshot> {
+  /** Id of the last entry the snapshot covers ("0" when it covers none). */
+  through: string;
+  snapshot: Snapshot;
+}
+
+const asError = (err: unknown): Error => (err instanceof Error ? err : new Error(String(err)));
+
+/** Record ids are decimal strings from one store-wide counter. */
+function idValue(id: string): bigint {
+  if (!/^\d+$/.test(id)) throw new Error(`RecordJournal: unexpected chronicle record id "${id}"`);
+  return BigInt(id);
+}
+
+function decode<T>(store: JsStore, id: string): { value: T; sequence: number } {
+  const record = store.getRecord(id);
+  if (!record) throw new Error(`RecordJournal: record ${id} is listed but cannot be read`);
+  return { value: JSON.parse(Buffer.from(record.payload).toString('utf-8')) as T, sequence: record.sequence };
+}
+
+export class RecordJournal<Entry, Snapshot = never> {
+  private readonly store: JsStore;
+  /** Record type of the entries. */
+  readonly type: string;
+  /** Record type of the checkpoints. */
+  readonly checkpointType: string;
+  /** Highest entry id this journal has loaded or appended (0 when none). */
+  private lastEntryId = 0n;
+  private sinceCheckpoint = 0;
+  /** Set by a failure after the store's append returned; cleared by load(). */
+  private unreconciled: Error | null = null;
+  /** Set when the store's append itself threw: its record may be in the log
+   *  but not in this process's view of the store. Never cleared. */
+  private unreadable: Error | null = null;
+
+  constructor(store: JsStore, opts: { type: string; checkpointType?: string }) {
+    if (!opts.type) throw new Error('RecordJournal: a record type is required');
+    this.store = store;
+    this.type = opts.type;
+    this.checkpointType = opts.checkpointType ?? `${opts.type}/checkpoint`;
+    if (this.checkpointType === this.type) {
+      throw new Error('RecordJournal: entries and checkpoints need distinct record types');
+    }
+  }
+
+  /** Entries appended since the last checkpoint (or since load, when there was none). */
+  get entriesSinceCheckpoint(): number {
+    return this.sinceCheckpoint;
+  }
+
+  /**
+   * The latest checkpoint and every entry after it, whichever branch each was
+   * appended on. The caller rebuilds its reduced state from exactly these —
+   * at open, and to reconcile after an ambiguous write. Also positions the
+   * journal, so later checkpoints cover what was loaded.
+   */
+  load(): JournalLoad<Entry, Snapshot> {
+    let snapshot: Snapshot | null = null;
+    let through = 0n;
+    let latestCheckpoint: bigint | null = null;
+    let latestCheckpointId: string | null = null;
+    for (const id of this.store.getRecordIdsByType(this.checkpointType)) {
+      const value = idValue(id);
+      if (latestCheckpoint === null || value > latestCheckpoint) {
+        latestCheckpoint = value;
+        latestCheckpointId = id;
+      }
+    }
+    if (latestCheckpointId !== null) {
+      const payload = decode<CheckpointPayload<Snapshot>>(this.store, latestCheckpointId).value;
+      snapshot = payload.snapshot;
+      through = idValue(payload.through);
+    }
+
+    const tail = this.store.getRecordIdsByType(this.type)
+      .map((id) => ({ id, value: idValue(id) }))
+      .filter(({ value }) => value > through)
+      .sort((a, b) => (a.value < b.value ? -1 : a.value > b.value ? 1 : 0));
+    const entries = tail.map(({ id }) => {
+      const { value, sequence } = decode<Entry>(this.store, id);
+      return { id, sequence, entry: value };
+    });
+
+    this.lastEntryId = tail.length > 0 ? tail[tail.length - 1]!.value : through;
+    this.sinceCheckpoint = entries.length;
+    this.unreconciled = null;
+    return { snapshot, entries };
+  }
+
+  /** True after a failure that load() can resolve, until it has replayed the
+   *  tail. An append that threw inside the store is never resolved here: the
+   *  journal stays unwritable until a journal on the reopened store loads it. */
+  get needsReconcile(): boolean {
+    return this.unreconciled !== null;
+  }
+
+  /** True once an append threw inside the store, for the rest of the
+   *  journal's life. What `load()` returns may then lack that append's record,
+   *  so a caller that decides from the journal's contents can't trust them
+   *  until a journal on the reopened store has loaded it. */
+  get needsReopen(): boolean {
+    return this.unreadable !== null;
+  }
+
+  /** Append one entry. The returned ref says where it landed, not that it's durable. */
+  append(entry: Entry, opts: AppendOptions = {}): JournalRecordRef {
+    this.assertReconciled();
+    if (opts.afterCommittedState) this.store.sync();
+    return this.write(this.type, entry, opts.durable === true, (ref) => {
+      const value = idValue(ref.id);
+      if (value > this.lastEntryId) this.lastEntryId = value;
+      this.sinceCheckpoint++;
+    });
+  }
+
+  /**
+   * Record the caller's reduced state as covering every entry this journal has
+   * loaded or appended. Like an entry, it's durable only with `durable`.
+   */
+  checkpoint(snapshot: Snapshot, opts: { durable?: boolean } = {}): JournalRecordRef {
+    this.assertReconciled();
+    const payload: CheckpointPayload<Snapshot> = { through: this.lastEntryId.toString(), snapshot };
+    return this.write(this.checkpointType, payload, opts.durable === true, () => {
+      this.sinceCheckpoint = 0;
+    });
+  }
+
+  /** Hand one record to the store; any failure from here on is ambiguous. */
+  private write(type: string, payload: unknown, durable: boolean, onWritten: (ref: JournalRecordRef) => void): JournalRecordRef {
+    let record: { id: string; sequence: number };
+    try {
+      record = this.store.appendJson(type, payload);
+    } catch (err) {
+      this.unreadable = asError(err);
+      throw err;
+    }
+    try {
+      const ref = { id: record.id, sequence: record.sequence };
+      onWritten(ref);
+      if (durable) this.store.sync();
+      return ref;
+    } catch (err) {
+      this.unreconciled = asError(err);
+      throw err;
+    }
+  }
+
+  private assertReconciled(): void {
+    if (this.unreadable) {
+      throw new Error(
+        `RecordJournal(${this.type}): an earlier append failed inside the store ` +
+        `(${this.unreadable.message}), and its record may be in the store's log where this process can't ` +
+        `read it back; nothing more is written until the store is reopened, as at the next start`,
+      );
+    }
+    if (this.unreconciled) {
+      throw new Error(
+        `RecordJournal(${this.type}): an earlier write failed after reaching the store ` +
+        `(${this.unreconciled.message}); load() and reduce its tail before writing again`,
+      );
+    }
+  }
+}

package/src/shutdown.ts

@@ -0,0 +1,49 @@
+/** No implicit deadline: the caller owns the module/child shutdown contract. */
+export const DEFAULT_SHUTDOWN_TIMEOUT_MS: number | undefined = undefined;
+
+export function validateShutdownTimeout(timeoutMs: number | undefined): void {
+  if (timeoutMs === undefined) return;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) {
+    throw new RangeError('Shutdown timeout must be an integer from 1 to 2147483647 ms');
+  }
+}
+
+export class ShutdownTimeoutError extends AggregateError {
+  constructor(readonly pending: string[], timeoutMs: number, failures: unknown[]) {
+    super([...failures, new Error(`Shutdown timed out after ${timeoutMs} ms; pending: ${pending.join(', ')}`)],
+      `Shutdown timed out after ${timeoutMs} ms; pending: ${pending.join(', ')}` +
+      (failures.length ? `; failures: ${failures.map(shutdownErrorMessage).join('; ')}` : ''));
+    this.name = 'ShutdownTimeoutError';
+  }
+}
+
+export function shutdownErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export async function waitForShutdown(
+  attempts: Array<{ label: string; promise: Promise<void> }>, timeoutMs: number | undefined,
+): Promise<void> {
+  validateShutdownTimeout(timeoutMs);
+  const pending = new Set(attempts.map((_, index) => index));
+  const failures = new Map<number, unknown>();
+  const settled = Promise.all(attempts.map(({ promise }, index) => promise.then(
+    () => { pending.delete(index); },
+    error => { failures.set(index, error); pending.delete(index); },
+  )));
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    if (timeoutMs === undefined) await settled;
+    else await Promise.race([settled, new Promise<void>((_, reject) => {
+      timer = setTimeout(() => reject(new ShutdownTimeoutError(
+        [...pending].map(index => attempts[index]!.label), timeoutMs, [...failures.values()],
+      )), timeoutMs);
+    })]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+  const errors = [...failures.values()];
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors,
+    `Shutdown failed: ${errors.map(shutdownErrorMessage).join('; ')}`);
+}

package/src/silent-heartbeat.ts

@@ -0,0 +1,141 @@
+/**
+ * Stored-row handling for silent heartbeat ticks.
+ *
+ * A silent tick stores no prompt row (#216): its reply is written straight
+ * after whatever the window held before it — often the previous assistant
+ * message, since a suppressed tick leaves no delivery receipt behind. The
+ * wire formatter merges consecutive same-role messages, so without a turn
+ * between them the tick would read as an unprompted continuation of the
+ * earlier response and one assistant message would carry signed thinking
+ * from two separate responses (a provider 400 when it is the latest
+ * assistant message; see `Agent.addAssistantResponse`).
+ *
+ * Every row a tick writes is therefore stamped with `metadata.silentHeartbeat`
+ * and, at request-build time only, a terse user turn is rendered immediately
+ * before the first of the tick's rows that survives compilation. The
+ * separator is never stored and its position is a function of the stamped
+ * rows alone, so every compile renders it in the same place (the tick's own
+ * request ends on the same turn), which keeps the prompt-cache prefix
+ * stable — unlike a per-compile injection that re-anchors to the newest user
+ * message.
+ *
+ * Known limit: compiled messages carry no store provenance, so a stored row
+ * is recognised only by structural identity the provider made unique
+ * (tool_use ids, thinking signatures). A tick reply with neither — unsigned
+ * and tool-free — gets no separator and still merges as before. Without
+ * signed thinking that merge carries no provider-rejection risk; it is only
+ * a misreading. Reply text is deliberately never used as identity: identical
+ * replies ("all quiet") would collide, and an ordinary reply with the same
+ * text could take a tick's separator and rewrite cached history. Exact
+ * matching for every row would need the compile result to expose each
+ * message's source rows.
+ */
+import type { ContentBlock, NormalizedMessage } from '@animalabs/membrane';
+
+/** Request-only separator text. Constant on purpose: it carries no time or
+ * id, so it is byte-identical on every compile. */
+export const SILENT_HEARTBEAT_SEPARATOR = '[heartbeat tick]';
+
+/** Identity of one authenticated silent heartbeat tick. */
+export interface SilentHeartbeatTick {
+  /** The MCPL push event that woke the tick. A broadcast tick reaches every
+   * resident with the same id. */
+  eventId: string;
+  /** The MCPL server that sent it. */
+  serverId: string;
+}
+
+/** `metadata.silentHeartbeat` on every row a tick's turn writes. Residents
+ * share one message slot, so the stamp names the agent whose turn wrote it
+ * (tool_result rows are stored as `user`). */
+export interface SilentHeartbeatStamp extends SilentHeartbeatTick {
+  agentName: string;
+}
+
+/** The tick stamp on a stored row's metadata, if any. */
+export function silentHeartbeatOf(metadata: unknown): SilentHeartbeatStamp | undefined {
+  const stamp = (metadata as { silentHeartbeat?: unknown } | undefined)?.silentHeartbeat;
+  if (!stamp || typeof stamp !== 'object') return undefined;
+  const { eventId, serverId, agentName } = stamp as Record<string, unknown>;
+  return typeof eventId === 'string' && typeof serverId === 'string' && typeof agentName === 'string'
+    ? { eventId, serverId, agentName }
+    : undefined;
+}
+
+export function silentHeartbeatSeparatorTurn(): NormalizedMessage {
+  return { participant: 'user', content: [{ type: 'text', text: SILENT_HEARTBEAT_SEPARATOR }] };
+}
+
+/**
+ * Structural identity of one stored response wherever a compile renders it:
+ * tool_use ids and thinking signatures, which the provider made unique and
+ * strategies keep verbatim (the same identity the tool-result guard relies
+ * on). Text is never read, so request-build sanitizing (blank text blocks
+ * stripped) cannot make a stored row and its compiled copy disagree.
+ */
+function identityKeys(content: ContentBlock[]): string[] {
+  const keys: string[] = [];
+  for (const block of content) {
+    if (block.type === 'tool_use' && typeof block.id === 'string' && block.id) keys.push(`tool_use:${block.id}`);
+    else if (block.type === 'thinking' && typeof block.signature === 'string' && block.signature) {
+      keys.push(`thinking:${block.signature}`);
+    } else if (block.type === 'redacted_thinking' && typeof block.data === 'string' && block.data) {
+      keys.push(`redacted:${block.data}`);
+    }
+  }
+  return keys;
+}
+
+export interface StoredRowLike {
+  participant: string;
+  content: ContentBlock[];
+  metadata?: unknown;
+}
+
+export interface SilentTickIndex {
+  /** Identity key of every assistant row this agent stored during a tick → tick event id. */
+  rows: Map<string, string>;
+  /** Ticks this agent has already stored rows for (its own, not another resident's). */
+  started: Set<string>;
+}
+
+/** Index the rows this agent stored during silent ticks. */
+export function indexSilentTickRows(stored: readonly StoredRowLike[], agentName: string): SilentTickIndex {
+  const rows = new Map<string, string>();
+  const started = new Set<string>();
+  for (const row of stored) {
+    const stamp = silentHeartbeatOf(row.metadata);
+    if (!stamp || stamp.agentName !== agentName) continue;
+    started.add(stamp.eventId);
+    if (row.participant !== agentName) continue;
+    for (const key of identityKeys(row.content)) rows.set(key, stamp.eventId);
+  }
+  return { rows, started };
+}
+
+/**
+ * Insert the separator turn immediately before the first surviving row of
+ * each tick in a compiled window — the tick's first row when it is rendered,
+ * otherwise whichever later row a strategy kept. Rows folded into summaries
+ * simply do not match; ordinary messages pass through untouched.
+ */
+export function separateSilentHeartbeatTicks(
+  messages: NormalizedMessage[],
+  rows: ReadonlyMap<string, string>,
+  agentName: string,
+): NormalizedMessage[] {
+  if (rows.size === 0) return messages;
+  const separated = new Set<string>();
+  const out: NormalizedMessage[] = [];
+  for (const message of messages) {
+    if (message.participant === agentName) {
+      const eventId = identityKeys(message.content).map((key) => rows.get(key)).find((id) => id !== undefined);
+      if (eventId !== undefined && !separated.has(eventId)) {
+        separated.add(eventId);
+        out.push(silentHeartbeatSeparatorTurn());
+      }
+    }
+    out.push(message);
+  }
+  return out;
+}

package/src/tool-presentation.ts

@@ -0,0 +1,188 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { fchmodSync, closeSync, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import type { ToolDefinition, ToolResult } from './types/events.js';
+
+export interface ToolPresentationConfig {
+  /** Absolute path to shared editable JSON. Missing file means no overrides. */
+  path: string;
+  /** Reserved generated workspace path, e.g. board/tool-catalogue.md. */
+  cataloguePath: string;
+  /** Optional description-only profiles, bound to a registered component source. */
+  defaults?: { source: string; path: string }[];
+}
+export interface ToolOverride { description?: string; visible?: boolean }
+export interface PresentationDocument { version: 1; tools: Record<string, ToolOverride> }
+export interface PresentationSnapshot {
+  revision: string;
+  source: string;
+  cataloguePath: string;
+  diagnostics: string[];
+  available: ToolDefinition[];
+  advertised: ToolDefinition[];
+  entries: { name: string; source: string; visible: boolean; originalDescription: string; description: string; descriptionSource?: string; inputSchema: ToolDefinition['inputSchema'] }[];
+}
+const MAX_BYTES = 256 * 1024;
+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';
+const hash = (value: string): string => createHash('sha256').update(value).digest('hex');
+
+export function parsePresentation(raw: string): PresentationDocument {
+  const doc = JSON.parse(raw);
+  if (!doc || doc.version !== 1 || !doc.tools || typeof doc.tools !== 'object' || Array.isArray(doc.tools)
+      || Object.keys(doc).some(k => !['version', 'tools'].includes(k))) throw new Error('Expected {"version":1,"tools":{...}}');
+  for (const [name, value] of Object.entries(doc.tools)) {
+    if (!name || !value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`Invalid override: ${name}`);
+    const item = value as Record<string, unknown>;
+    if (Object.keys(item).some(k => !['description', 'visible'].includes(k))
+      || ('description' in item && (typeof item.description !== 'string' || item.description.length > 32768))
+      || ('visible' in item && typeof item.visible !== 'boolean')) throw new Error(`Invalid description/visibility for ${name}`);
+    if (protectedNames.has(name) && item.visible === false) throw new Error(`Cannot hide recovery tool ${name}`);
+  }
+  return doc;
+}
+
+export function presentationTools(path: string): ToolDefinition[] {
+  const signpost = ` Read the generated catalogue with workspace--read {"path":${JSON.stringify(path)},"limit":140}. Hidden tools remain available; changes affect the next newly compiled request, not an in-flight stream.`;
+  return [
+    {name:'set_tool_visibility', description:'Show or hide a tool definition. Hiding does not revoke permission.' + signpost,
+      inputSchema:{type:'object',properties:{name:{type:'string'},visible:{type:'boolean'}},required:['name','visible'],additionalProperties:false}},
+    {name:'set_tool_description', description:'Set a personal tool description; null restores the configured component default, or the installed description when none is configured.' + signpost,
+      inputSchema:{type:'object',properties:{name:{type:'string'},description:{type:['string','null']}},required:['name','description'],additionalProperties:false}},
+  ] as unknown as ToolDefinition[];
+}
+
+/** Per-agent presentation; files are the sole persistent source, independent of editor identity. */
+export class ToolPresentation {
+  constructor(readonly config: ToolPresentationConfig) {}
+  private read(path = this.config.path, allowMissing = true): string {
+    let fd: number;
+    try { fd = openSync(path, 'r'); }
+    catch (error) { if (allowMissing && (error as NodeJS.ErrnoException).code === 'ENOENT') return '{"version":1,"tools":{}}'; throw error; }
+    try {
+      const stat = fstatSync(fd);
+      if (!stat.isFile() || stat.size > MAX_BYTES) throw new Error('Presentation must be a regular file under 256 KiB');
+      const data = Buffer.alloc(MAX_BYTES + 1);
+      let size = 0, count = 0;
+      while (size < data.length && (count = readSync(fd, data, size, data.length - size, null)) > 0) size += count;
+      if (size > MAX_BYTES) throw new Error('Presentation exceeds 256 KiB');
+      return data.subarray(0,size).toString('utf8');
+    } finally { closeSync(fd); }
+  }
+  resolve(tools: ToolDefinition[], sources: ReadonlyMap<string, string> = new Map()): PresentationSnapshot {
+    let raw = '', doc: PresentationDocument = {version:1,tools:{}}, diagnostics: string[] = [];
+    try { raw = this.read(); doc = parsePresentation(raw); }
+    catch (error) { diagnostics.push(`Overrides not applied: ${String(error)}. Default visibility and component descriptions retained.`); }
+    const defaults = new Map<string, {description: string; path: string}>();
+    const configuredSources = new Set<string>();
+    for (const profile of this.config.defaults ?? []) {
+      if (configuredSources.has(profile.source)) {
+        diagnostics.push(`Duplicate defaults source ignored: ${profile.source}`); continue;
+      }
+      configuredSources.add(profile.source);
+      // Absent components contribute neither tools nor missing-file errors.
+      if (!tools.some(t => (sources.get(t.name) ?? 'Unattributed') === profile.source)) continue;
+      try {
+        const profileDoc = parsePresentation(this.read(profile.path, false));
+        if (Object.values(profileDoc.tools).some(item => Object.keys(item).some(k => k !== 'description')))
+          throw new Error('Component defaults may contain descriptions only; visibility belongs to the resident');
+        for (const tool of tools) {
+          if ((sources.get(tool.name) ?? 'Unattributed') !== profile.source) continue;
+          const item = Object.hasOwn(profileDoc.tools, tool.name) ? profileDoc.tools[tool.name] : undefined;
+          if (item?.description !== undefined) defaults.set(tool.name, {description:item.description,path:profile.path});
+        }
+      } catch (error) { diagnostics.push(`Component defaults not applied (${profile.source}): ${String(error)}`); }
+    }
+    const names = new Set(tools.map(t => t.name));
+    for (const name of Object.keys(doc.tools)) if (!names.has(name)) diagnostics.push(`Not currently available: ${name}`);
+    const entries = tools.map(tool => {
+      const override = Object.hasOwn(doc.tools, tool.name) ? doc.tools[tool.name] : undefined;
+      // Always retain a usable discovery signpost, even when its wording is overridden.
+      const componentDefault = defaults.get(tool.name);
+      let description = override?.description ?? componentDefault?.description ?? tool.description;
+      const descriptionSource = override?.description !== undefined ? this.config.path : componentDefault?.path ?? "installed component";
+      if (isPresentationTool(tool.name) && (override?.description !== undefined || componentDefault !== undefined))
+        description += `\nCatalogue: workspace--read {"path":${JSON.stringify(this.config.cataloguePath)},"limit":140}. Changes affect the next newly compiled request.`;
+      return {name:tool.name,source:sources.get(tool.name) ?? 'Unattributed',visible:override?.visible ?? true,originalDescription:tool.description,description,descriptionSource,inputSchema:structuredClone(tool.inputSchema)};
+    });
+    const available = tools.map((tool,i) => ({...structuredClone(tool),description:entries[i].description}));
+    return {revision:hash(JSON.stringify({raw,entries,diagnostics})),source:this.config.path,cataloguePath:this.config.cataloguePath,diagnostics,available,
+      advertised:available.filter((_,i)=>entries[i].visible),entries};
+  }
+  edit(tool: string, input: unknown, available: ToolDefinition[]): ToolResult {
+    const lock = this.config.path + '.lock';
+    let fd: number | undefined, tempFd: number | undefined, temp: string | undefined;
+    try {
+      if (!isPresentationTool(tool)) throw new Error('Unknown editing tool');
+      const value = input as Record<string, unknown>;
+      const field = tool === 'set_tool_visibility' ? 'visible' : 'description';
+      if (!value || typeof value !== 'object' || Array.isArray(value) || typeof value.name !== 'string'
+        || Object.keys(value).some(k=> !['name',field].includes(k)) || !Object.hasOwn(value,field)) throw new Error('Invalid editing arguments');
+      if (!available.some(t=>t.name===value.name)) throw new Error('Tool is not currently available to this agent');
+      if (field === 'visible' ? typeof value.visible !== 'boolean' : value.description !== null && typeof value.description !== 'string') throw new Error(`Invalid ${field}`);
+      fd = openSync(lock, 'wx', 0o600);
+      let mode = 0o600;
+      try { const stat = lstatSync(this.config.path); if (stat.isSymbolicLink()) throw new Error('Edit the target file directly; tool editing refuses symlinks'); mode = stat.mode & 0o777; }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+      const before = this.read(), doc = parsePresentation(before);
+      const old = Object.hasOwn(doc.tools,value.name) ? doc.tools[value.name] : {};
+      const updated = {...old};
+      if (field === 'description' && value.description === null) delete updated.description;
+      else Object.assign(updated,{[field]:value[field]});
+      Object.defineProperty(doc.tools,value.name,{value:updated,enumerable:true,writable:true,configurable:true});
+      const next = JSON.stringify(doc,null,2)+'\n';
+      parsePresentation(next);
+      if (Buffer.byteLength(next)>MAX_BYTES) throw new Error('Presentation exceeds 256 KiB');
+      temp = this.config.path + '.' + randomUUID() + '.tmp';
+      tempFd = openSync(temp,'wx',0o600);
+      writeFileSync(tempFd,next);
+      fchmodSync(tempFd,mode); // preserve permissions on the opened inode, never a replacement path
+      if (this.read() !== before) throw new Error('File changed concurrently; retry after reading it');
+      const opened = fstatSync(tempFd), named = lstatSync(temp);
+      if (!named.isFile() || named.dev !== opened.dev || named.ino !== opened.ino)
+        throw new Error('Temporary file changed concurrently; retry after checking the directory');
+      renameSync(temp,this.config.path); temp=undefined;
+      return {success:true,data:{name:value.name,[field]:value[field],effective:'next newly compiled request',catalogue:this.config.cataloguePath}};
+    } catch (error) { return {success:false,isError:true,error:String(error)}; }
+    finally { if(tempFd!==undefined) closeSync(tempFd); if(temp) try{unlinkSync(temp);}catch{} if(fd!==undefined){closeSync(fd);unlinkSync(lock);} }
+  }
+}
+export function renderCatalogue(snapshot: PresentationSnapshot): string {
+  const groups = new Map<string, PresentationSnapshot['entries']>();
+  for (const entry of snapshot.entries) {
+    const group = groups.get(entry.source) ?? [];
+    group.push(entry); groups.set(entry.source, group);
+  }
+  const visible = snapshot.entries.filter(e => e.visible).length;
+  const lines: string[] = [
+    '# Tool catalogue — generated from currently available tools', '',
+    `Revision: ${snapshot.revision}`, '',
+    `${snapshot.entries.length} tools: ${visible} visible, ${snapshot.entries.length-visible} hidden.`,
+    'Visible = supplied in new requests. Hidden = stored away, still available.',
+    'These are your visibility choices, not fixed primary/secondary rankings.',
+    'Copy exact names from the index; similar-sounding names may not exist.',
+    'Show a hidden tool: set_tool_visibility {"name":"EXACT_NAME","visible":true}.',
+    `Read details: workspace--read {"path":${JSON.stringify(snapshot.cataloguePath)},"offset":LINE,"limit":LINES}.`,
+    'Line references below belong to this revision; reread the index after changes.', '',
+  ];
+  for (const diagnostic of snapshot.diagnostics) lines.push('Diagnostic: '+diagnostic);
+  lines.push('## Index by source', '');
+  const index = new Map<string, number>();
+  for (const [source, entries] of groups) {
+    lines.push(`### ${source} (${entries.length})`);
+    for (const entry of entries) {index.set(entry.name,lines.length);lines.push('');}
+    lines.push('');
+  }
+  lines.push('## Full definitions', '');
+  for (const [source, entries] of groups) {
+    lines.push(`### ${source}`, '');
+    for (const entry of entries) {
+      const start = lines.length + 1;
+      lines.push(`#### ${entry.name} (${entry.visible?'visible':'hidden'})`, '',
+        ...entry.description.split('\n'), '', `Description from: ${entry.descriptionSource ?? 'installed component'}`, '', `Schema: ${JSON.stringify(entry.inputSchema)}`);
+      if(entry.description!==entry.originalDescription) lines.push('', 'Original description:', ...entry.originalDescription.split('\n'));
+      lines.push('');
+      lines[index.get(entry.name)!] = `- [${entry.visible?'visible':'hidden'}] ${entry.name} — details: offset ${start}, limit ${lines.length-start+1}`;
+    }
+  }
+  return lines.join('\n');
+}