@cubicecho/agent-core 4.19.0 → 4.21.0

package/dist/run/run-calls.js

@@ -1,7 +1,9 @@
+import { isRecord } from '../core/guards.js';
 import { CALL_TOOL, expandNames, inCatalog, LOAD_TOOLS, loadResult, proxiedCall, proxyLoadResult, requestedNames, shownCall, toolName, } from '../tools/tool-loading.js';
 import { errorMessage } from '../wire/errors.js';
 import { parseToolArguments, } from '../wire/tool-calls.js';
 import { FUNCTION_TOOL, Role } from '../wire/wire.js';
+import { declaredArtifact, detectArtifact, RECORD_ARTIFACT, } from './artifacts.js';
 import { RunEventKind } from './events.js';
 /**
  * The tools between two turns: a step's calls read, run and written into the transcript.
@@ -26,20 +28,40 @@ export const preview = (text, limit = 2000) => text.length > limit ? `${text.sli
 const STOPPED_CALL = 'Stopped before this call finished.';
 /** The same for a call of that step the loop never got to. */
 const UNRUN_CALL = 'Not run: the run stopped first.';
+/**
+ * Whether a call's arguments are, as written, the JSON of an object — or no arguments at all.
+ *
+ * @param raw - The arguments as the turn carried them: a string, or an object a server parsed.
+ * @returns False where reading them took `parseToolArguments`' repairs.
+ */
+function readsAsWritten(raw) {
+    if (typeof raw !== 'string' || !raw.trim()) {
+        return true;
+    }
+    try {
+        return isRecord(JSON.parse(raw));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * One call with its arguments read, or with why they could not be.
  *
  * @param call - The call as the turn carried it.
  * @param finishReason - Why the turn ended, which tells a call cut off from one written wrongly.
+ * @param recovered - Whether the call was recovered from the reply's text, which makes it repaired
+ * whatever its arguments.
  * @returns The call beside its arguments and their repaired JSON, or beside the error and `{}`.
  */
-function readCall(call, finishReason) {
+function readCall(call, finishReason, recovered) {
     try {
         const args = parseToolArguments(call.function.arguments, { finishReason });
-        return { call, args, normal: JSON.stringify(args) };
+        const repaired = recovered || !readsAsWritten(call.function.arguments);
+        return { call, args, normal: JSON.stringify(args), repaired };
     }
     catch (error) {
-        return { call, error, normal: '{}' };
+        return { call, error, normal: '{}', repaired: false };
     }
 }
 /**
@@ -47,6 +69,7 @@ function readCall(call, finishReason) {
  *
  * @param calls - The turn's calls, in the order the model made them.
  * @param finishReason - Why the turn ended, which tells a call cut off from one written wrongly.
+ * @param [recovered] - Whether the calls were recovered from the reply's text.
  * @returns One entry per call, in the same order. Unreadable arguments do not throw: the entry
  * carries the error in place of them.
  *
@@ -54,7 +77,7 @@ function readCall(call, finishReason) {
  * A server that parses replayed arguments refuses the almost-JSON a model wrote, so each is
  * normalised here, and one that could not be read at all is replayed as no arguments.
  */
-export const readCalls = (calls, finishReason) => calls.map((call) => readCall(call, finishReason));
+export const readCalls = (calls, finishReason, recovered = false) => calls.map((call) => readCall(call, finishReason, recovered));
 /**
  * The assistant message a turn is written into the transcript as, its calls' arguments repaired.
  *
@@ -75,6 +98,19 @@ export const assistantMessage = (content, parsed) => ({
         }
         : {}),
 });
+/**
+ * The assistant message a turn is, as the model produced it: its text and calls as they streamed.
+ *
+ * @param content - The turn's text, recovered calls left in it. Empty is written as `null`.
+ * @param calls - The calls the model sent as calls, with their arguments as streamed. Not written
+ * to. None leaves `tool_calls` off the message rather than empty.
+ * @returns A new message, each call on it a copy.
+ */
+export const writtenMessage = (content, calls) => ({
+    role: Role.Assistant,
+    content: content || null,
+    ...(calls.length ? { tool_calls: calls.map((call) => ({ ...call, function: { ...call.function } })) } : {}),
+});
 /**
  * The definitions the host gave for these names, in the order the names are given.
  *
@@ -227,28 +263,57 @@ async function once(answered, key, make) {
     }
 }
 /**
- * Adds one call's links to the run's artifacts, telling watchers of each uri the first time.
+ * Tells watchers of artifacts the run had not produced before.
  *
- * @param run - The run. Written to: a new uri is added to `artifacts`, and a known one counted.
- * @param links - What the call's answer linked to.
- * @param from - The call they came from.
+ * @param run - The run, whose watchers hear of them.
+ * @param added - The new artifacts, each told once.
  */
-function collect(run, links, from) {
-    // Per call, so a tool that lists one uri twice in an answer is counted as making it once.
-    const seen = new Set();
-    for (const link of links) {
-        if (seen.has(link.uri)) {
-            continue;
-        }
-        seen.add(link.uri);
-        const known = run.artifacts.get(link.uri);
-        if (known) {
-            known.count++;
-            continue;
-        }
-        run.artifacts.set(link.uri, { link, ...from, count: 1 });
-        run.onEvent({ kind: RunEventKind.Artifact, id: from.callId, name: from.tool, text: link.title || link.uri, link });
+function announceArtifacts(run, added) {
+    for (const { link, callId, tool } of added) {
+        run.onEvent({ kind: RunEventKind.Artifact, id: callId, name: tool, text: link.title || link.uri, link });
+    }
+}
+/**
+ * Adds what one successful call produced to the run's artifacts: its links, and — where the run
+ * collects them — what it was given and answered, and the write it reads as.
+ *
+ * @param run - The run. Written to: its `artifacts`.
+ * @param request - The call, under the tool it was shown as.
+ * @param content - What it answered.
+ * @param links - What its answer linked to.
+ * @param from - The call, as an artifact is put down to it.
+ */
+function collect(run, request, content, links, from) {
+    announceArtifacts(run, run.artifacts.link(links, from));
+    if (run.declares) {
+        run.artifacts.witness(request.args, content, links, from);
     }
+    const draft = run.detects?.(request) ? detectArtifact(request.name, request.args) : null;
+    const added = draft ? run.artifacts.add(draft, from) : undefined;
+    announceArtifacts(run, added ? [added] : []);
+}
+/**
+ * Answers a `record_artifact`, keeping the declaration where some call in the run touched the
+ * location.
+ *
+ * @param run - The run. Written to: its `artifacts`, where the declaration is believed.
+ * @param args - The call's arguments.
+ * @returns What the model reads. Throws, which the model reads instead, for a declaration with no
+ * location or one no call in the run was given or answered with.
+ */
+function answerRecord(run, args) {
+    const draft = declaredArtifact(args);
+    if (draft === null) {
+        throw new Error(`${RECORD_ARTIFACT} needs a location.`);
+    }
+    const from = run.artifacts.seen(draft.location);
+    if (from === undefined) {
+        throw new Error(`No tool call in this run touched ${draft.location}, so it was not recorded. ` +
+            'Record only what one of your tools stored, after the call that stored it.');
+    }
+    const added = run.artifacts.add(draft, from);
+    announceArtifacts(run, added ? [added] : []);
+    return `Recorded ${draft.location}.`;
 }
 /**
  * A call looked through and built into the request every host callback is handed.
@@ -284,14 +349,15 @@ function prepare(run, entry) {
     }
     // Built for every call rather than only the dispatched ones, so a host hears of the calls
     // the loop answers itself in the same shape. Arguments that could not be read are none.
-    const request = { id: call.id, name, args: inner, raw };
+    const request = { id: call.id, name, args: inner, raw, repaired: entry.repaired };
     // By the name the model called, not the one a `call_tool` wraps: `load_tools` is not in
     // the catalogue, and one reached through `call_tool` is refused like any other.
     const load = onDemand && call.function.name === LOAD_TOOLS;
-    const dispatched = args !== undefined && load === false && refused === undefined;
+    const record = run.declares && call.function.name === RECORD_ARTIFACT;
+    const dispatched = args !== undefined && load === false && record === false && refused === undefined;
     // Keyed on the inner call, so one made through `call_tool` and one made natively share.
     const key = `${name}\0${proxy ? JSON.stringify(inner) : normal}`;
-    return { entry, request, load, refused, dedupable: dispatched && run.dedupable(request), key };
+    return { entry, request, load, record, refused, dedupable: dispatched && run.dedupable(request), key };
 }
 /**
  * Whether a call is answered without `dispatch` seeing it, so it can run beside anything.
@@ -299,10 +365,15 @@ function prepare(run, entry) {
  * @param prepared - The call.
  * @param answered - The step's calls already made, by key. A call that threw is not in it.
  * @param batch - The keys of the calls in the batch being gathered, which a repeat shares.
- * @returns True for a `load_tools`, a call whose arguments could not be read, a `call_tool` that
- * was refused, and an identical repeat that `dedupeToolCalls` answers from the first.
+ * @returns True for a `load_tools`, a `record_artifact`, a call whose arguments could not be read,
+ * a `call_tool` that was refused, and an identical repeat that `dedupeToolCalls` answers from the
+ * first.
  */
-const answersItself = ({ entry, load, refused, dedupable, key }, answered, batch) => entry.args === undefined || load || refused !== undefined || (dedupable && (answered.has(key) || batch.has(key)));
+const answersItself = ({ entry, load, record, refused, dedupable, key }, answered, batch) => entry.args === undefined ||
+    load ||
+    record ||
+    refused !== undefined ||
+    (dedupable && (answered.has(key) || batch.has(key)));
 /**
  * Where the batch of calls starting at `from` ends: every call, one call, or the calls up to the
  * first one the host's predicate does not pass.
@@ -355,7 +426,7 @@ function batchEnd(run, ready, from, total, answered) {
  */
 async function runCall(run, prepared, answered, step) {
     const { catalog, onDemand, proxied, signal } = run;
-    const { entry, request, load, refused, dedupable, key } = prepared;
+    const { entry, request, load, record, refused, dedupable, key } = prepared;
     const { call, args, error: unreadable } = entry;
     const { name, raw } = request;
     run.onEvent({ kind: RunEventKind.ToolCall, id: call.id, name, text: preview(raw) });
@@ -375,6 +446,9 @@ async function runCall(run, prepared, answered, step) {
         if (load) {
             ({ content, ok, counts: loads } = answerLoad(run, args));
         }
+        else if (record) {
+            content = answerRecord(run, args);
+        }
         else {
             if (refused) {
                 throw refused.error;
@@ -414,9 +488,10 @@ async function runCall(run, prepared, answered, step) {
         text: preview(content),
         ...(loads ? { loads } : {}),
     });
-    const isFirstAnswer = shared === false;
-    if (isFirstAnswer) {
-        collect(run, links, { callId: call.id, tool: name, step });
+    // Only what `dispatch` answered made anything, and a repeat made nothing the first did not.
+    const isMade = ok && load === false && record === false && shared === false;
+    if (isMade) {
+        collect(run, request, content, links, { callId: call.id, tool: name, step });
     }
     const result = { id: call.id, name, ok, content, ...(links.length ? { links } : {}) };
     run.onToolResult?.(result);
@@ -480,11 +555,17 @@ export async function runCalls(run, parsed, messages, step) {
             const start = from;
             const to = batchEnd(run, ready, start, parsed.length, answered);
             begun = to;
-            await Promise.all(parsed.slice(start, to).map(async (_, offset) => {
-                const { result, end } = await runCall(run, ready(start + offset), answered, step);
-                outcomes[start + offset] = result;
-                ends[start + offset] = end;
-            }));
+            const runAt = async (at) => {
+                const { result, end } = await runCall(run, ready(at), answered, step);
+                outcomes[at] = result;
+                ends[at] = end;
+            };
+            // A declaration describes what the batch beside it stored, so it waits for the rest of the
+            // batch: run together, it would be checked before the write it names had answered.
+            const positions = parsed.slice(start, to).map((_, offset) => start + offset);
+            const isRecord = (at) => ready(at).record;
+            await Promise.all(positions.filter((at) => isRecord(at) === false).map(runAt));
+            await Promise.all(positions.filter(isRecord).map(runAt));
             for (const { id, name, ok, content } of outcomes.slice(from, to).flatMap((outcome) => outcome ?? [])) {
                 toolCalls.push({ id, name, ok });
                 await keep(id, content);
@@ -540,7 +621,7 @@ export async function loadShortlist(run, shortlist, messages) {
     // host that shortlisted more has already chosen.
     const content = proxyLoadResult(expandNames(names, catalog, names.length), catalog, shortlist);
     run.onEvent({ kind: RunEventKind.ToolCall, id, name: LOAD_TOOLS, text: preview(args) });
-    run.onToolCall?.({ id, name: LOAD_TOOLS, args: { names }, raw: args });
+    run.onToolCall?.({ id, name: LOAD_TOOLS, args: { names }, raw: args, repaired: false });
     const loads = { toolsLoaded: names.length, redundantLoads: 0, unknownToolNames: 0 };
     run.onEvent({ kind: RunEventKind.ToolResult, id, name: LOAD_TOOLS, ok: true, text: preview(content), loads });
     run.onToolResult?.({ id, name: LOAD_TOOLS, ok: true, content });

package/dist/wire/tool-calls.d.ts

@@ -114,9 +114,24 @@ export interface ToolCallRequest {
     args: Record<string, unknown>;
     /**
      * The arguments as the model wrote them, before any repair. Through `call_tool`, the inner
-     * arguments as JSON text.
+     * arguments as JSON text. For a call recovered from the reply's text, the arguments recovery read
+     * out of it, as JSON text: the words the model wrote are the reply's content, which `onMessage`'s
+     * `raw` message carries.
      */
     raw: string;
+    /**
+     * Whether `args` took a repair to read: true where `raw` does not parse, as written, to the JSON
+     * object `args` holds — near-JSON, or JSON inside a string — and for every call recovered from
+     * text, which the model never sent as a call. False for blank arguments, which every reader takes
+     * as none, and for arguments that could not be read at all. Through `call_tool`, whether the
+     * `call_tool`'s own arguments did.
+     *
+     * @remarks
+     * A host that shows or stores what the model said reads `raw` where this is true. Whitespace is
+     * not a repair, though the replayed arguments are re-serialised either way. `runAgentLoop` always
+     * sets it; optional so a request built before it existed still compiles.
+     */
+    repaired?: boolean;
 }
 /** What one tool call did, in the order the model asked. */
 export interface ToolCallOutcome {
@@ -263,25 +278,68 @@ export interface ToolCallReport {
      */
     log: (entry: ServerLogEntry) => void;
 }
+/**
+ * How the loop came to know of an artifact, most trusted first.
+ *
+ * @remarks
+ * `linked` is a call's answer saying so, and is the only one that takes no guessing. `declared` is
+ * the model naming it through `record_artifact`, believed only where some call in the run touched
+ * the location. `detected` is the loop reading a successful call as a write: a verb at the front
+ * of its name and a path in its arguments. The last two are opt-in, through `artifacts` on the
+ * loop's options.
+ */
+export declare const ArtifactSource: {
+    readonly Linked: 'linked';
+    readonly Declared: 'declared';
+    readonly Detected: 'detected';
+};
+/** Any one of the sources in `ArtifactSource`. */
+export type ArtifactSource = (typeof ArtifactSource)[keyof typeof ArtifactSource];
+/** What the run's last write did to an artifact's location, as a detection read it. */
+export declare const ArtifactAction: {
+    readonly Created: 'created';
+    readonly Updated: 'updated';
+    readonly Moved: 'moved';
+    readonly Deleted: 'deleted';
+};
+/** Any one of the actions in `ArtifactAction`. */
+export type ArtifactAction = (typeof ArtifactAction)[keyof typeof ArtifactAction];
 /**
  * One thing a run's tool calls produced: the first link to a uri, and where it came from.
  *
  * @remarks
  * A link is what one call answered with; an artifact is what the run made, one per uri however
- * many calls linked to it.
+ * many calls linked to it. A declared or detected artifact is one per location the same way, and
+ * its `link` is built from what was said of it: the location as `uri`, its last segment as `name`.
  */
 export interface RunArtifact {
-    /** The link as the first call to give its uri gave it. A later call's says nothing new here. */
+    /**
+     * The link as the first call to give its uri gave it. A later call's says nothing new here, and
+     * a declaration only fills in a `title` or `description` it left out.
+     */
     link: ResourceLink;
-    /** The call that first linked to it. */
+    /** The call that first linked to it, wrote it, or — for a declaration alone — last touched it. */
     callId: string;
     /** That call's tool. For a `call_tool`, the tool it named. */
     tool: string;
     /** The loop's step that call was made in, from 0. */
     step: number;
     /**
-     * How many calls linked to it. A deduplicated repeat does not count, since nothing was made
-     * twice, and a call that links one uri twice counts once.
+     * How many calls linked to it or wrote it. A deduplicated repeat does not count, since nothing
+     * was made twice, a call that links one uri twice counts once, and a declaration counts none.
      */
     count: number;
+    /**
+     * How it came to be known: `linked` where absent, which is every artifact a call's answer
+     * linked to, so the shape from before the other two sources still reads the same. A declaration
+     * over a detection takes the source over; a link over either does too.
+     */
+    source?: ArtifactSource;
+    /**
+     * What the latest write a detection read did to it. Absent where no detection did: a link or a
+     * declaration says a thing exists, not what was done to it.
+     */
+    action?: ArtifactAction;
+    /** The bytes the latest detected write carried, where its arguments held the content. */
+    sizeBytes?: number;
 }

package/dist/wire/tool-calls.js

@@ -489,3 +489,25 @@ export const ServerLogLevel = {
     Alert: 'alert',
     Emergency: 'emergency',
 };
+/**
+ * How the loop came to know of an artifact, most trusted first.
+ *
+ * @remarks
+ * `linked` is a call's answer saying so, and is the only one that takes no guessing. `declared` is
+ * the model naming it through `record_artifact`, believed only where some call in the run touched
+ * the location. `detected` is the loop reading a successful call as a write: a verb at the front
+ * of its name and a path in its arguments. The last two are opt-in, through `artifacts` on the
+ * loop's options.
+ */
+export const ArtifactSource = {
+    Linked: 'linked',
+    Declared: 'declared',
+    Detected: 'detected',
+};
+/** What the run's last write did to an artifact's location, as a detection read it. */
+export const ArtifactAction = {
+    Created: 'created',
+    Updated: 'updated',
+    Moved: 'moved',
+    Deleted: 'deleted',
+};

package/llms.txt

@@ -176,6 +176,20 @@ The loop above a turn: send, run the tools the model asked for, send again, unti
 - `PRESELECTED_NOTICE` — What opens the notice naming the loop's own picks, ahead of the names.
 - `runAgentLoop` — Runs a question to its answer: one `runTurn` per step, the tools it asks for between them, until a turn asks for none or a call's answer ends the run.
 - `StepWindow` (type) — How full the window is as a step is about to be sent, as `beforeStep` is told it.
+- `WrittenMessage` (type) — What `onMessage` is handed beside an assistant message the model wrote: that message as the model produced it.
+
+### artifacts
+
+What a run left behind, from the two sources that take a guess: the model saying so, and a call that reads as a write.
+
+- `ArtifactDraft` (type) — What one declaration or detection said of a location, before it is merged into the run's.
+- `ArtifactOptions` (type) — Which of the guessing sources a run collects, beside the links every run keeps.
+- `artifactSource` — How an artifact came to be known, reading an absent `source` as the link it always was.
+- `declaredArtifact` — What the model said through `record_artifact`.
+- `detectArtifact` — What a successful call wrote, if its name and arguments look like a write.
+- `mediaTypeFor` — A media type guessed off a location's extension.
+- `RECORD_ARTIFACT` — The name of the tool the loop declares and answers itself when `artifacts.declare` is on.
+- `RECORD_ARTIFACT_TOOL` — The definition of `record_artifact`, as the loop declares it beside the host's own tools.
 
 ### events
 
@@ -432,6 +446,8 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 
 - `ARGUMENTS_MALFORMED` — The `ToolArgumentsError` kind for a call the model wrote wrongly.
 - `ARGUMENTS_TRUNCATED` — The `ToolArgumentsError` kind for a call cut off at the reply ceiling.
+- `ArtifactAction` — Any one of the actions in `ArtifactAction`.
+- `ArtifactSource` — Any one of the sources in `ArtifactSource`.
 - `EndedBy` (type) — The call that ended a run through its answer's `end`, as `AgentLoopResult.ended` says it.
 - `parseToolArguments` — A tool call's arguments as the object the tool is handed.
 - `ResourceLink` (type) — A handle to something a tool call made or found — a document it wrote, a file it saved.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "4.19.0",
+  "version": "4.21.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",