@animalabs/agent-framework 0.21.0 → 0.22.0

package/dist/src/tool-presentation.js

@@ -0,0 +1,235 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { fchmodSync, closeSync, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+const MAX_BYTES = 256 * 1024;
+const protectedNames = new Set(['set_tool_visibility', 'set_tool_description', 'workspace--read']);
+export const isPresentationTool = (name) => name === 'set_tool_visibility' || name === 'set_tool_description';
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+export function parsePresentation(raw) {
+    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;
+        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) {
+    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 } },
+    ];
+}
+/** Per-agent presentation; files are the sole persistent source, independent of editor identity. */
+export class ToolPresentation {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    read(path = this.config.path, allowMissing = true) {
+        let fd;
+        try {
+            fd = openSync(path, 'r');
+        }
+        catch (error) {
+            if (allowMissing && error.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, sources = new Map()) {
+        let raw = '', doc = { version: 1, tools: {} }, diagnostics = [];
+        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();
+        const configuredSources = new Set();
+        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, input, available) {
+        const lock = this.config.path + '.lock';
+        let fd, tempFd, temp;
+        try {
+            if (!isPresentationTool(tool))
+                throw new Error('Unknown editing tool');
+            const value = input;
+            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.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) {
+    const groups = new Map();
+    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 = [
+        '# 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();
+    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');
+}
+//# sourceMappingURL=tool-presentation.js.map

package/dist/src/tool-presentation.js.map

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

package/dist/src/tool-result-guard.d.ts

@@ -1,8 +1,64 @@
-import type { ContextManager, MessageId } from '@animalabs/context-manager';
+import type { ContextManager, MessageId, MessageMetadata } from '@animalabs/context-manager';
 import type { ContentBlock, NormalizedMessage, ToolResult } from '@animalabs/membrane';
 import type { CompletedToolCall } from './types/index.js';
 export declare const TOOL_RESULT_GUARD_NOTICE = "Tool result withheld by the guard. The tool has already executed.";
 export declare const TOOL_RESULT_GUARD_AUDIT_STATE = "framework/tool-result-guard";
+/** Where a withheld result's original went: a workspace path; the path a
+ *  write to it failed at (`error`); the path a write was still under way to
+ *  when the host stopped waiting for it (`unfinished`); no write, because the
+ *  workspace isn't answering (`workspace_unanswered`: an earlier write is
+ *  still under way past the host's deadline) or because the workspace had
+ *  left the stub's branch when the file would have been committed
+ *  (`branch_changed`), or because the batch used its deadline before this
+ *  write could start (`batch_deadline`); or null when no file is written at all (no writable
+ *  workspace, or the host is stopping). */
+export type WithheldSpill = {
+    path: string;
+    error?: string;
+    unfinished?: true;
+} | {
+    skipped: 'workspace_unanswered' | 'branch_changed' | 'batch_deadline';
+} | null;
+/**
+ * Writes one withheld original as a workspace file, using what remains of
+ * the batch's absolute deadline. A write still running then is unfinished.
+ * Once a write reaches that deadline, later spills are workspace_unanswered
+ * until all overdue writes settle. Other batches can start before that gate
+ * closes. An exhausted batch starts no write (batch_deadline).
+ * The tree entry lands on branch or the write is declined (branch_changed).
+ * The mount's disk directory is shared across branches.
+ */
+export type WithheldSpiller = (label: string, text: string, branch: string, deadline: number) => Promise<WithheldSpill>;
+/** What a host gives a guard for its withheld results: where originals are
+ *  written, where each annotation is registered, so the host's stop can
+ *  wait for it even after the agent itself was disposed, and where the
+ *  guard says whether it has work left. */
+export interface WithheldHost {
+    spill: WithheldSpiller;
+    /** Absolute deadline for one batch (Date.now() time), taken when the batch is queued. */
+    deadline(): number;
+    track(annotation: Promise<void>): void;
+    /** Whether the guard is idle (see ToolResultGuard.idle), told after each
+     *  change that can alter it: when an annotation starts or ends, and after
+     *  each pass over the storage queue. A host keeps a guard that isn't idle
+     *  within reach for retries, whatever has become of its agent, and lets
+     *  an idle one go. */
+    idle(idle: boolean): void;
+}
+/**
+ * The stub a withheld result settles to: #159's neutral notice, then where
+ * the original is. It names no refusal and no category (#159 keeps those in
+ * operational logs), only the place, so reading it back is the agent's
+ * deliberate choice (agent-framework #277). The place holds the result as
+ * stored, which for one over the inline cap is its capped text, whose own
+ * note names the file with the whole output; so the stub says "its result",
+ * not its full result. A failed write's own error text
+ * stays in the audit record and the logs, not here. The audit
+ * record is said to keep the original only when it was saved: a staged
+ * record whose save failed is still queued in memory, and a restart before
+ * its retry loses it.
+ */
+export declare function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean): string;
 /**
  * Admission of newly returned tool output to durable model-facing memory.
  *
@@ -21,8 +77,43 @@ export declare class ToolResultGuard {
     private override;
     /** True until a recovery produces a clean response/new tool round. */
     recovering: boolean;
+    /** Writes withheld originals where the agent can read them; without it,
+     *  a stub names only the audit record. */
+    private host;
+    /** Annotations of withheld stubs, chained in settlement order. */
+    private annotating;
+    /** Annotations started so far, so a read can tell one began during it. */
+    private annotationsStarted;
     constructor(agentName: string, cm: ContextManager, configured?: boolean);
     get enabled(): boolean;
+    setHost(host: WithheldHost | undefined): void;
+    /** Settles once every annotation started so far has finished: each of
+     *  those stubs has been edited to say where its original is, or its edit
+     *  failed and waits in the storage queue, retried in order until it lands
+     *  or an operator's change supersedes it (until then the stub is the bare
+     *  notice, kept out of summaries by its compression hold, and the audit
+     *  record names the place). It never rejects. Each batch has one deadline
+     *  for all its workspace writes; queued batches are annotated in order.
+     *  A request may carry an unfinished-write notice once that deadline passes. */
+    whenAnnotated(): Promise<void>;
+    /**
+     * Runs `read` (a compile of the context) once no withheld stub is still
+     * being annotated, and again if an annotation began while it ran, since a
+     * settlement can land during the compile's own awaits, such as a previous
+     * frame's teardown abandoning its batch. The framework's sent-request
+     * compiles go through it: the agent's activations, its direct
+     * API calls and their refusal retry, and a conversation fork's seed from its
+     * template. A request preview doesn't, so it never waits on a
+     * workspace write.
+     *
+     * Before `read`, a stub edit that failed gets another try with the rest of
+     * the storage queue; a store that is still failing then compiles the bare
+     * notice, which its hold keeps out of summaries.
+     */
+    afterAnnotations<T>(read: () => Promise<T>): Promise<T>;
+    /** No annotation is running and no storage work is queued: nothing of this
+     *  guard is left for a host to wait on or retry. */
+    get idle(): boolean;
     setOverride(value: boolean | undefined): void;
     get settingOverride(): boolean | undefined;
     get hasPending(): boolean;
@@ -37,15 +128,22 @@ export declare class ToolResultGuard {
     get pendingWireReserveTokens(): number;
     /** Ordered storage work, separate from batches awaiting a provider verdict.
      * A failed acceptance edit retains both the payload and its compression
-     * hold here; it can never re-arm refusal handling or tool submission. */
+     * hold here; it can never re-arm refusal handling or tool submission.
+     * Any failed head, including an audit-only record, blocks later queued
+     * edits and their holds until that operation succeeds. */
     private unrecorded;
-    /** Retry edits and audit writes before a new activation, audit write,
-     * maintenance pass, or shutdown. A failed operation stays at the head. */
+    /** Retry edits and audit writes before a new activation, a compile of a
+     * request that is sent (afterAnnotations), an audit write, a maintenance
+     * pass, or shutdown. A failed operation stays at the head. */
     flushUnrecorded(): void;
+    /** Make an operation's history edit, if it still has one: once it is made,
+     *  or superseded by an operator's change, only its record is left to
+     *  write, and its hold can go. */
+    private applyEdit;
     private append;
     private write;
     private archive;
-    storeResults(content: ContentBlock[], wireResults: ToolResult[], originals: CompletedToolCall[]): MessageId;
+    storeResults(content: ContentBlock[], wireResults: ToolResult[], originals: CompletedToolCall[], metadata?: MessageMetadata): MessageId;
     /** Results for a live continuation (provideToolResults). Marks the batch
      * submitted and returns the originals only when the audit is durable;
      * otherwise returns placeholder results and leaves it unsubmitted. */
@@ -74,8 +172,29 @@ export declare class ToolResultGuard {
     withhold(category: string): string[] | null;
     /** Transfer ownership from provider admission to an ordered storage job.
      * Failure retains the accepted payload and its hold until the edit succeeds.
-     * Withheld content is final already, so audit failures cannot keep it held. */
+     * A withheld batch's hold passes to its annotation instead, and from there
+     * to its stub's edit, so no summary is made of a stub that doesn't yet say
+     * where its original went. */
     private settle;
+    /**
+     * Turn a withheld batch's notices into stubs that say where each original
+     * is (agent-framework #277): written to the workspace when a writable mount
+     * takes it, else kept in the audit record. Its own unedited placeholder is
+     * the only thing it edits: an operator's later edit, removal or rollback
+     * stands.
+     *
+     * Where each original went is queued first, on its own ('annotated'), so
+     * a stub edit that fails can't take the record of a written file with it.
+     * The edit is then made at once, so no storage work queued ahead of it
+     * holds it, not even that record if its write is failing, and its record
+     * ('stub_updated') is written in order after the others. An
+     * edit that fails joins the ordered storage queue like an admission's, with
+     * the batch's compression hold: retried before the next activation, compile,
+     * maintenance pass or stop until it lands or an operator's change supersedes
+     * it. Until then the stub is the bare notice, which the hold keeps out of
+     * summaries, and the audit record names the file.
+     */
+    private annotate;
     private releaseOperationHold;
     private releaseHold;
 }

package/dist/src/tool-result-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-result-guard.d.ts","sourceRoot":"","sources":["../../src/tool-result-guard.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,eAAO,MAAM,wBAAwB,sEAAsE,CAAC;AAC5G,eAAO,MAAM,6BAA6B,gCAAgC,CAAC;AAsB3E;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAQxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAT7B,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAsB;IACtC,sEAAsE;IACtE,UAAU,UAAS;gBAGA,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,cAAc,EAClB,UAAU,UAAQ;IAGrC,IAAI,OAAO,IAAI,OAAO,CAA6C;IACnE,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI;IAC7C,IAAI,eAAe,IAAI,OAAO,GAAG,SAAS,CAA0B;IACpE,IAAI,UAAU,IAAI,OAAO,CAAuC;IAChE;;iFAE6E;IAC7E,IAAI,mBAAmB,IAAI,OAAO,CAA6C;IAE/E;;;2EAGuE;IACvE,IAAI,wBAAwB,IAAI,MAAM,CAcrC;IAED;;6EAEyE;IACzE,OAAO,CAAC,UAAU,CAAwB;IAE1C;8EAC0E;IAC1E,eAAe,IAAI,IAAI;IA8BvB,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,KAAK;IAab,OAAO,CAAC,OAAO;IASf,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,iBAAiB,EAAE,GAAG,SAAS;IAmD3G;;0EAEsE;IACtE,iBAAiB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE;IAStD;;;iEAG6D;IAC7D,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ7B;sEACkE;IAClE,cAAc,CAAC,QAAQ,EAAE,iBAAiB,EAAE,EAAE,gBAAgB,UAAQ,GAAG,iBAAiB,EAAE;IAkB5F;;;yEAGqE;IACrE,eAAe,IAAI,IAAI;IAQvB;;;oDAGgD;IAChD,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAO5C,4EAA4E;IAC5E,MAAM,IAAI,IAAI;IAQd,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAW3C;;mFAE+E;IAC/E,OAAO,CAAC,MAAM;IAmBd,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,WAAW;CAGpB"}
+{"version":3,"file":"tool-result-guard.d.ts","sourceRoot":"","sources":["../../src/tool-result-guard.ts"],"names":[],"mappings":"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"}