@animalabs/agent-framework 0.31.0 → 0.33.0

package/dist/src/foreign-rounds.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Another agent's rounds as an agent that watches its slot is sent them
+ * (#291, answer 13).
+ *
+ * An agent reads another agent's rounds through an observe edge (decision
+ * 1), as the persistent subconscious watches the residents' slot, and an
+ * agent derived or forked from such a watcher inherits them, sent in its
+ * mode. A co-resident's rows stored before audience stamps, which a window
+ * written down from the record keeps, reach an agent that observes no one
+ * too: they go out as stored there, as earlier releases sent them. An agent
+ * sent others' rounds as a transcript is sent those as one, read by their
+ * participant.
+ * Those rounds are stored as the other agent's: its signed thinking, its
+ * tool calls and their results. None of that is valid as the watcher's own.
+ * A provider takes tool blocks only in their own pairing, in the turns of
+ * the agent that made the call, and a thinking block's signature binds it
+ * to the prefix the other agent was sent. Sent raw in a user turn, the
+ * blocks are refused, or moved into the watcher's assistant turns, where
+ * they read as calls the watcher made.
+ *
+ * So by default the watcher is sent them as a transcript, a line per block:
+ * a call as the tool's name and its input in brief, a result as the tool's
+ * name and its outcome in brief, and no thinking at all. Text, images and
+ * the rest go as stored. The signature forbids sending a thinking block as
+ * part of another prefix, not its text: leaving the text out is this
+ * transcript's choice. A host can have the rounds sent as stored instead
+ * (PersistentReaderConfig.foreignRounds `'raw'`, as 0.30.0 sent them). The rule is one function of the stored row, applied the same
+ * way to a compile's messages and to a row a tool boundary injects, so what
+ * the watcher's window holds and what its requests carried stay one thing.
+ *
+ * The watcher's own rows go as stored: its rounds (its own participant's
+ * messages), and the results of its own calls, which are stored under
+ * another participant (`user`) and are told by the call they answer: the
+ * nearest call before the result with its id, since a provider (or a mock)
+ * that numbers calls per response gives two agents' calls the same id.
+ */
+import type { ContentBlock, NormalizedMessage } from '@animalabs/membrane';
+/**
+ * One stored row of another agent's as the watcher is sent it: thinking
+ * dropped, each call and each result a line of text, a text block's
+ * provider-native item (`rawItem`) dropped with it, everything else as it is.
+ * `ownCalls` are the watcher's own calls, whose results it is sent as they
+ * are; `callNames` names the calls the row's results answer, where the
+ * result doesn't name its tool itself. A row left with nothing says so in
+ * a line, rather than going empty.
+ */
+export declare function foreignRowAsSent(content: readonly ContentBlock[], context?: {
+    ownCalls?: {
+        has(id: string): boolean;
+    };
+    callNames?: {
+        get(id: string): string | undefined;
+    };
+}): ContentBlock[];
+/**
+ * A request's messages as an agent that watches another's slot is sent them:
+ * each message whose participant isn't the agent's own (`isOwn`) through
+ * foreignRowAsSent, with the results of the agent's own calls kept, and
+ * each result named by the call it answers. A result answers the nearest
+ * call before it with its id, read in one pass in order, so another
+ * agent's result whose id an own call of the watcher's also has, before or
+ * after it, is still transcribed. A call answers one result: a result after
+ * the one that answered it, in the same message or a later one, names no
+ * call (another agent's, whose call the request doesn't carry), and is
+ * transcribed. A message nothing changes is the same object, and so is the
+ * array when none changes.
+ */
+export declare function transcribeForeignRounds(messages: readonly NormalizedMessage[], isOwn: (participant: string) => boolean): NormalizedMessage[];
+//# sourceMappingURL=foreign-rounds.d.ts.map

package/dist/src/foreign-rounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foreign-rounds.d.ts","sourceRoot":"","sources":["../../src/foreign-rounds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAkE3E;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAAC,SAAS,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAA;CAAO,GAC7G,YAAY,EAAE,CAwChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,GACtC,iBAAiB,EAAE,CA0BrB"}

package/dist/src/foreign-rounds.js

@@ -0,0 +1,152 @@
+import { NOTICE_TAG } from './notice-tags.js';
+import { cutToFit, markedTexts, oneLine } from './supplied-text.js';
+/** How long one transcript line's call or outcome runs before it is cut. */
+const BRIEF_CHARS = 160;
+/** `text` on one line: each line break the framework counts as one
+ *  (oneLine), and each other run of whitespace, as one space. */
+function flat(text) {
+    return oneLine(text).replace(/\s+/g, ' ').trim();
+}
+/** A tool result's content as pieces: its text, and its other blocks named
+ *  by kind, in placeholders that are the framework's own. */
+function resultPieces(content) {
+    if (typeof content === 'string')
+        return [{ text: content, supplied: true }];
+    return content.map((b) => (b.type === 'text'
+        ? { text: b.text, supplied: true }
+        : { text: `[${b.type}]`, supplied: false }));
+}
+/** A call's input as a piece: its JSON, or what the model sent when that
+ *  wasn't an object. */
+function callPiece(block) {
+    if (block.unparseableInput !== undefined)
+        return { text: block.unparseableInput, supplied: true };
+    try {
+        return { text: JSON.stringify(block.input ?? {}) ?? '', supplied: true };
+    }
+    catch {
+        return { text: '', supplied: true };
+    }
+}
+/**
+ * A transcript line: the framework's bracket around the tool's name, which
+ * the other agent's call supplied, the framework's words for what happened
+ * (`words[0]` before a call or outcome, `words[1]` when there is none), and
+ * the call or outcome in brief. What the line holds is supplied text
+ * (#852): set inside the framework's bracket here, where a tool block's own
+ * content isn't, an opening of one of the framework's notices is marked
+ * wherever it forms, read across the whole line (markedTexts): inside a
+ * piece, across a result's blocks, or where the name meets the bracket or
+ * the framework's words. Those words and the placeholders aren't marked.
+ * Each piece goes on one line first (flat), and the call or outcome is cut
+ * to BRIEF_CHARS with an ellipsis, at a whole character, never parting a
+ * mark from its bracket (cutToFit).
+ */
+function transcriptLine(name, words, body) {
+    const pieces = body.map((p) => ({ ...p, text: flat(p.text) })).filter((p) => p.text.length > 0);
+    const word = pieces.length > 0 ? words[0] : words[1];
+    const marked = markedTexts(['[', oneLine(name), word, ...pieces.map((p) => p.text)], [true, true, false, ...pieces.map((p) => p.supplied)]);
+    const said = marked.slice(3).join(' ');
+    return `${marked.slice(0, 3).join('')}${said.length > BRIEF_CHARS ? `${cutToFit(said, BRIEF_CHARS - 1)}…` : said}]`;
+}
+/** Where a row with nothing left to send stands, so the transcript keeps a row for each stored one. */
+const NOTHING_SAID = `[${NOTICE_TAG.noText}]`;
+/**
+ * One stored row of another agent's as the watcher is sent it: thinking
+ * dropped, each call and each result a line of text, a text block's
+ * provider-native item (`rawItem`) dropped with it, everything else as it is.
+ * `ownCalls` are the watcher's own calls, whose results it is sent as they
+ * are; `callNames` names the calls the row's results answer, where the
+ * result doesn't name its tool itself. A row left with nothing says so in
+ * a line, rather than going empty.
+ */
+export function foreignRowAsSent(content, context = {}) {
+    let changed = false;
+    const out = [];
+    for (const block of content) {
+        switch (block.type) {
+            case 'thinking':
+            case 'redacted_thinking':
+                changed = true;
+                break;
+            case 'tool_use': {
+                changed = true;
+                out.push({ type: 'text', text: transcriptLine(block.name, [' called: ', ' called: '], [callPiece(block)]) });
+                break;
+            }
+            case 'tool_result': {
+                if (context.ownCalls?.has(block.toolUseId)) {
+                    out.push(block);
+                    break;
+                }
+                changed = true;
+                const name = block.toolName ?? context.callNames?.get(block.toolUseId) ?? 'a tool';
+                const word = block.isError ? ' failed' : ' returned';
+                out.push({ type: 'text', text: transcriptLine(name, [`${word}: `, word], resultPieces(block.content)) });
+                break;
+            }
+            case 'text': {
+                if (block.rawItem === undefined) {
+                    out.push(block);
+                    break;
+                }
+                changed = true;
+                if (block.text.length > 0)
+                    out.push({ type: 'text', text: block.text });
+                break;
+            }
+            default:
+                out.push(block);
+        }
+    }
+    if (!changed)
+        return content;
+    return out.length > 0 ? out : [{ type: 'text', text: NOTHING_SAID }];
+}
+/**
+ * A request's messages as an agent that watches another's slot is sent them:
+ * each message whose participant isn't the agent's own (`isOwn`) through
+ * foreignRowAsSent, with the results of the agent's own calls kept, and
+ * each result named by the call it answers. A result answers the nearest
+ * call before it with its id, read in one pass in order, so another
+ * agent's result whose id an own call of the watcher's also has, before or
+ * after it, is still transcribed. A call answers one result: a result after
+ * the one that answered it, in the same message or a later one, names no
+ * call (another agent's, whose call the request doesn't carry), and is
+ * transcribed. A message nothing changes is the same object, and so is the
+ * array when none changes.
+ */
+export function transcribeForeignRounds(messages, isOwn) {
+    const latest = new Map();
+    // The watcher's own call is answered by the first result read for it,
+    // block by block: that result takes its entry, so a second result for it
+    // in the same message names no call.
+    const ownCalls = {
+        has: (id) => {
+            if (latest.get(id)?.own !== true)
+                return false;
+            latest.delete(id);
+            return true;
+        },
+    };
+    const callNames = { get: (id) => latest.get(id)?.name };
+    let changed = false;
+    const out = messages.map((m) => {
+        const own = isOwn(m.participant);
+        for (const b of m.content)
+            if (b.type === 'tool_use')
+                latest.set(b.id, { own, name: b.name });
+        const content = own ? m.content : foreignRowAsSent(m.content, { ownCalls, callNames });
+        // A call answers one result: a later result with its id (another
+        // agent's, whose call the request doesn't carry) answers no call here.
+        for (const b of m.content)
+            if (b.type === 'tool_result')
+                latest.delete(b.toolUseId);
+        if (content === m.content)
+            return m;
+        changed = true;
+        return { ...m, content };
+    });
+    return changed ? out : messages;
+}
+//# sourceMappingURL=foreign-rounds.js.map

package/dist/src/foreign-rounds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foreign-rounds.js","sourceRoot":"","sources":["../../src/foreign-rounds.ts"],"names":[],"mappings":"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"}