@cubicecho/agent-core 4.19.0 → 4.21.0

package/README.md

@@ -568,6 +568,38 @@ its calls made on the error too, read off with `failedRun`.
 A link meant for the model alone — one whose MCP `audience` leaves out `"user"` — is the
 dispatcher's to drop, since that is MCP's rule and this package knows nothing of MCP.
 
+A link is the only source that takes no guessing, and the default. For servers that never send
+one, `artifacts` turns on the two that do, each off unless asked for:
+
+```ts
+const { artifacts } = await runAgentLoop({
+  // ...
+  artifacts: { declare: true, detect: true },
+});
+// [{ link, callId, tool, step, count, source: "declared", action: "updated", sizeBytes }]
+```
+
+- **`declare`** puts `record_artifact` (`RECORD_ARTIFACT_TOOL`) beside `hostTools` on every step,
+  in every mode, and the loop answers it without `dispatch` seeing it. It takes `location`,
+  `title`, `description` and `mediaType`. A declaration is believed only where some successful
+  call in the run was given or answered with that location — otherwise a model with no file tools
+  "saves" its answer to a file it never wrote — and the refusal is the call's answer, for the model
+  to read. A believed one is put down to the latest call that touched the location. In a
+  `parallel` batch it waits for the batch's other calls, so a write beside it counts.
+- **`detect`** reads every successful call for the shape of a write: a verb at the front of the
+  tool's own name (`write`, `create`, `save`, `upload`, `edit`, `move`, `delete`…) and a path in
+  its arguments (`destination`, `path`, `file_path`, `uri`…). Creating a folder is not an artifact.
+  A predicate in place of `true` reads only the calls it passes, which is how a host keeps its own
+  tools' writes off the list. `detectArtifact` is the same reading, for a host to call itself.
+
+One artifact per location per run, whichever sources found it. A later write moves `action`
+(`created`, `updated`, `moved`, `deleted`) and `sizeBytes` on; a declaration over a detection
+fills in the title and description and takes the `source` over, and never turns an `updated` back
+into `created`. A link is the server's word: a declaration over one fills only what it left out,
+and a link over either guess takes over. `source` is absent on a linked artifact, so the shape
+from before reads the same — `artifactSource` reads it as `linked`. The `artifact` event goes out
+once per location; the result's `artifacts` say what each ended as.
+
 ### A call that ends the run
 
 A tool whose call is the end of the job — handing off, asking a person — says so with `end` on
@@ -610,8 +642,10 @@ string. What still is not an object throws a `ToolArgumentsError` whose `kind` i
 the turn stopped at the ceiling, with a message telling the model so, and `malformed` otherwise.
 The repaired JSON is what the transcript keeps, and an unreadable call is replayed as `{}`, because
 a server that parses replayed arguments refuses the originals on every later request. `dispatch`
-is still handed the model's own text as `raw`, and the dedupe compares repaired arguments,
-so `{'a': 1}` and `{"a": 1}` are one call.
+is still handed the model's own text as `raw`, with `repaired` true where reading it took a repair
+— whitespace and blank arguments do not count — and the dedupe compares repaired arguments, so
+`{'a': 1}` and `{"a": 1}` are one call. A call recovered from text, below, is always `repaired`,
+and its `raw` is the arguments recovery read out of the reply, as JSON.
 
 A server whose tool-call parser was written for another template streams the model's call as
 plain text, and the run ends on a reply that is nothing but a call nobody made. Unless
@@ -969,7 +1003,11 @@ try {
 
 `onMessage` hears the assistant message as it will be replayed — recovered calls folded in, and
 arguments repaired, which the turn `onTurn` is handed does not show — together with that `Turn`,
-and then each tool result, in transcript order. `onTurn` is not awaited and never sees a tool
+and then each tool result, in transcript order. Beside an assistant message the model wrote comes a
+fourth argument, `{ raw }`: the same message as the model produced it, its text whole with any call
+written into it left there, and its calls' arguments exactly as streamed, under the same ids. Store
+or show `raw` to keep what the model said; replay `message` to keep what an endpoint will take back.
+The loop's own messages — a proxied run's preselected load — come without it. `onTurn` is not awaited and never sees a tool
 result; this is the one to store from. What it returns is ignored, since `beforeStep` is the one way to rewrite
 the transcript, and what it throws ends the run.
 

package/dist/index.d.ts

@@ -19,7 +19,8 @@ export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools,
 export { CACHE_PROMPT_FIELD, resetSlots, SESSION_HEADER, SLOT_FIELD, type SlotAllocator, slotAllocator, } from './endpoint/slots.ts';
 export { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hooks/hook-events.ts';
 export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, type HookContext, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from './hooks/hooks.ts';
-export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, PRESELECT_APPEND, PRESELECT_EXCLUSIVE, PRESELECTED_NOTICE, runAgentLoop, type StepWindow, } from './run/agent-loop.ts';
+export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, PRESELECT_APPEND, PRESELECT_EXCLUSIVE, PRESELECTED_NOTICE, runAgentLoop, type StepWindow, type WrittenMessage, } from './run/agent-loop.ts';
+export { type ArtifactDraft, type ArtifactOptions, artifactSource, declaredArtifact, detectArtifact, mediaTypeFor, RECORD_ARTIFACT, RECORD_ARTIFACT_TOOL, } from './run/artifacts.ts';
 export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type LoadCounts, type RunEvent, type RunEventInput, RunEventKind, type RunMetrics, type RunMetricsOptions, RunOutcome, type RunUsage, resetEvents, runMetrics, type TurnReport, watch, } from './run/events.ts';
 export { buildBody } from './run/request-body.ts';
 export { preview, type ToolDispatch } from './run/run-calls.ts';
@@ -40,5 +41,5 @@ export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow,
 export { CacheBreakReason, type InFlight, type LoopUsage, type PartialTurn, type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, type UsageTotals, } from './wire/stream.ts';
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, SPLIT_OUTPUT, SPLIT_REASONING, type Split, stripThinking, THINK_FENCE, } from './wire/thinking.ts';
 export { type ContextBreakdown, type ContextBreakdownOptions, compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, type TokenEstimateOptions, } from './wire/tokens.ts';
-export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, type EndedBy, parseToolArguments, type ResourceLink, type RunArtifact, recoverToolCalls, type ServerLogEntry, ServerLogLevel, type ToolAnswer, ToolArgumentsError, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult, } from './wire/tool-calls.ts';
+export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, ArtifactAction, ArtifactSource, type EndedBy, parseToolArguments, type ResourceLink, type RunArtifact, recoverToolCalls, type ServerLogEntry, ServerLogLevel, type ToolAnswer, ToolArgumentsError, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult, } from './wire/tool-calls.ts';
 export { FinishReason, FUNCTION_TOOL, JSON_SCHEMA_FORMAT, PartType, Role, SchemaType } from './wire/wire.ts';

package/dist/index.js

@@ -20,6 +20,7 @@ export { CACHE_PROMPT_FIELD, resetSlots, SESSION_HEADER, SLOT_FIELD, slotAllocat
 export { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hooks/hook-events.js';
 export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from './hooks/hooks.js';
 export { PRESELECT_APPEND, PRESELECT_EXCLUSIVE, PRESELECTED_NOTICE, runAgentLoop, } from './run/agent-loop.js';
+export { artifactSource, declaredArtifact, detectArtifact, mediaTypeFor, RECORD_ARTIFACT, RECORD_ARTIFACT_TOOL, } from './run/artifacts.js';
 export { configureEvents, emit, endRun, fold, history, RunEventKind, RunOutcome, resetEvents, runMetrics, watch, } from './run/events.js';
 export { buildBody } from './run/request-body.js';
 export { preview } from './run/run-calls.js';
@@ -39,5 +40,5 @@ export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow,
 export { CacheBreakReason, streamTurn, } from './wire/stream.js';
 export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, SPLIT_OUTPUT, SPLIT_REASONING, stripThinking, THINK_FENCE, } from './wire/thinking.js';
 export { compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, } from './wire/tokens.js';
-export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, parseToolArguments, recoverToolCalls, ServerLogLevel, ToolArgumentsError, } from './wire/tool-calls.js';
+export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, ArtifactAction, ArtifactSource, parseToolArguments, recoverToolCalls, ServerLogLevel, ToolArgumentsError, } from './wire/tool-calls.js';
 export { FinishReason, FUNCTION_TOOL, JSON_SCHEMA_FORMAT, PartType, Role, SchemaType } from './wire/wire.js';

package/dist/run/agent-loop.d.ts

@@ -11,6 +11,7 @@ import { type ToolOrder } from '../tools/tool-loading.ts';
 import { type SideTask } from '../turn/side-task.ts';
 import { type LoopUsage, type Turn } from '../wire/stream.ts';
 import { type EndedBy, type RunArtifact, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
+import { type ArtifactOptions } from './artifacts.ts';
 import { type RunEventInput, type RunMetrics } from './events.ts';
 import { type ToolDispatch } from './run-calls.ts';
 /**
@@ -23,6 +24,24 @@ import { type ToolDispatch } from './run-calls.ts';
  * and two never did. What is here is the part that does not know what the run is for; the
  * prompts, the tools and what a run means stay with the caller.
  */
+/**
+ * What `onMessage` is handed beside an assistant message the model wrote: that message as the model
+ * produced it.
+ *
+ * @remarks
+ * The message `onMessage` is handed is what later requests replay — arguments repaired, `{}` for
+ * none, recovered calls taken out of the text and made calls — which is right to send and quietly
+ * wrong to show as the model's. Absent for a message the loop wrote itself, such as a proxied
+ * run's preselected load.
+ */
+export interface WrittenMessage {
+    /**
+     * The reply as it streamed: its text whole, a call written into it as text left there, and the
+     * calls it sent as calls with their arguments as streamed. A call that never got a name is left
+     * off, since nothing answers it. Ids are the turn's, so the tool results pair with either.
+     */
+    raw: OpenAI.ChatCompletionAssistantMessageParam;
+}
 /**
  * One step's request as `onRequest` is handed it: what the model is about to read.
  *
@@ -361,6 +380,23 @@ export interface AgentLoopOptions {
      * `idempotentHint` annotations can answer it; nothing in an OpenAI tool definition can.
      */
     dedupeToolCalls?: boolean | ((call: ToolCallRequest) => boolean);
+    /**
+     * Collects artifacts from the two sources that take a guess, beside the `links` every run keeps:
+     * `declare` has the model name them through `record_artifact`, and `detect` reads each successful
+     * call for the shape of a write. Both off by default.
+     *
+     * @remarks
+     * For servers that never send a `resource_link`, which is the source to rely on. One artifact per
+     * location either way: a later write moves `action` on, a declaration over a detection fills in
+     * the title and description and takes the `source` over, and a link over either takes over too.
+     *
+     * `record_artifact` is declared beside `hostTools`, in every mode, and answered by the loop
+     * without `dispatch` seeing it. A declaration is believed only where some successful call in the
+     * run was given or answered with the location, and is otherwise refused for the model to read;
+     * run in a batch, it waits for the batch's other calls. `onToolCall` and `onToolResult` hear it
+     * as they hear `load_tools`, and it counts in `toolCalls` but not in `used`.
+     */
+    artifacts?: ArtifactOptions;
     /**
      * Told of every call the model made, as it starts — the ones `dispatch` never sees included:
      * `load_tools`, an identical repeat answered from the first, and a call whose arguments could
@@ -459,8 +495,12 @@ export interface AgentLoopOptions {
      * a proxied run writes for its `preselected` shortlist, told as step zero's before any request.
      * What it returns is ignored: `beforeStep` is the one way to rewrite the transcript. What it
      * throws ends the run, and it is not called again for that run.
+     *
+     * Beside an assistant message the model wrote comes `written`, whose `raw` is the message as the
+     * model produced it, for a host that shows or stores what was said rather than what is replayed.
+     * See `WrittenMessage`.
      */
-    onMessage?: (message: OpenAI.ChatCompletionMessageParam, step: number, turn?: Turn) => void | Promise<void>;
+    onMessage?: (message: OpenAI.ChatCompletionMessageParam, step: number, turn?: Turn, written?: WrittenMessage) => void | Promise<void>;
     /**
      * How many times an answer cut off at `maxTokens` is continued, zero for never. Opt-in because
      * it spends another request, and on a server that does not continue a trailing assistant
@@ -510,7 +550,7 @@ export interface AgentLoopResult {
     /**
      * What the run's calls linked to, one per uri in the order first seen, each with the call and
      * step that first linked to it and how many calls did. Empty where `dispatch` answered with
-     * strings only.
+     * strings only and `artifacts` collected nothing else.
      */
     artifacts: RunArtifact[];
     /**

package/dist/run/agent-loop.js

@@ -20,9 +20,10 @@ import { addCounts, loopUsage, noUsage, reportsCache, } from '../wire/stream.js'
 import { contextTokens, toolsChars } from '../wire/tokens.js';
 import { recoverToolCalls, } from '../wire/tool-calls.js';
 import { FinishReason, PartType, Role } from '../wire/wire.js';
+import { RECORD_ARTIFACT_TOOL, RunArtifacts } from './artifacts.js';
 import { RunEventKind, RunOutcome, runMetrics, stamp, } from './events.js';
 import { buildBody } from './request-body.js';
-import { assistantMessage, definedAs, loadShortlist, readCalls, runCalls, } from './run-calls.js';
+import { assistantMessage, definedAs, loadShortlist, readCalls, runCalls, writtenMessage, } from './run-calls.js';
 /** The `preselectRouting` that sends the first step the shortlist alone. */
 export const PRESELECT_EXCLUSIVE = 'exclusive';
 /** The `preselectRouting` that loads the shortlist after what was carried, and sends the first step like any other. */
@@ -136,7 +137,7 @@ export async function runAgentLoop(options) {
         }),
     };
     let result;
-    const apart = hostToolsApart(options);
+    const apart = hostToolsApart(withRecordTool(options));
     try {
         pin = await pinSession(apart);
         result = await runSteps(apart, standing, pin);
@@ -440,6 +441,23 @@ function hostToolsApart(options) {
         ...(preselected ? { preselected: preselected.filter(isCatalogued) } : {}),
     };
 }
+/**
+ * The run's options with `record_artifact` among the host's tools, where the run declares.
+ *
+ * @param options - What `runAgentLoop` was given. Not written to.
+ * @returns `options` itself where `artifacts.declare` is off, and otherwise a copy whose `hostTools`
+ * open with the loop's definition, which a host tool of the same name does not displace.
+ *
+ * @remarks
+ * A host tool in all but who answers it, so it is declared in every mode, kept off the catalogue,
+ * recoverable from text, and refused through `call_tool` exactly as the host's own are.
+ */
+function withRecordTool(options) {
+    if (options.artifacts?.declare !== true) {
+        return options;
+    }
+    return { ...options, hostTools: loadedTools([RECORD_ARTIFACT_TOOL], options.hostTools ?? []) };
+}
 /** What opens the notice naming the loop's own picks, ahead of the names. */
 export const PRESELECTED_NOTICE = 'tools picked before the run: ';
 /**
@@ -502,8 +520,8 @@ function definitionsByName(tools) {
  * Offers each message written into the transcript to the host.
  *
  * @param onMessage - The host's callback, awaited. Absent offers nothing.
- * @returns The offer, taking a message, its step and the turn it came with: it resolves once the
- * host has taken the message, and rejects with what the host threw — once.
+ * @returns The offer, taking a message, its step, the turn it came with and what the model wrote:
+ * it resolves once the host has taken the message, and rejects with what the host threw — once.
  *
  * @remarks
  * Once `onMessage` has thrown the run is ending on that, and the results still to be written are
@@ -511,12 +529,12 @@ function definitionsByName(tools) {
  */
 function announcer(onMessage) {
     let heard = true;
-    return async (message, step, turn) => {
+    return async (message, step, turn, written) => {
         if (!onMessage || !heard) {
             return;
         }
         try {
-            await onMessage(message, step, turn);
+            await onMessage(message, step, turn, written);
         }
         catch (error) {
             heard = false;
@@ -558,21 +576,21 @@ const usageEvent = (usage, turn, ledger, contextLength) => {
  * nothing is looked for in a turn that made a named call of its own or has no text.
  * @param notice - Told when calls were recovered, and how many.
  * @returns `calls`, the turn's own less any with no name, and `content`, its text as it was — or,
- * where calls were recovered, those calls and the text without them.
+ * where calls were recovered, those calls and the text without them, and `recovered` true.
  */
 function turnCalls(turn, recoverable, notice) {
     // A call with no name is a fragment the server never finished sending: nothing to run, and
     // an assistant message naming it would be answered by nothing.
     const calls = turn.toolCalls.filter((call) => call.function.name);
     if (!recoverable || calls.length || !turn.content) {
-        return { calls, content: turn.content };
+        return { calls, content: turn.content, recovered: false };
     }
     const recovered = recoverToolCalls(turn.content, { names: recoverable });
     if (!recovered.toolCalls.length) {
-        return { calls, content: turn.content };
+        return { calls, content: turn.content, recovered: false };
     }
     notice(`recovered ${counted(recovered.toolCalls.length, 'tool call')} the model wrote as text; the server's tool-call parser does not match this model's template`);
-    return { calls: recovered.toolCalls, content: recovered.content };
+    return { calls: recovered.toolCalls, content: recovered.content, recovered: true };
 }
 /**
  * The steps of `runAgentLoop`, throwing what they caught as it was caught.
@@ -586,7 +604,7 @@ function turnCalls(turn, recoverable, notice) {
  */
 async function runSteps(options, standing, pin) {
     const { config, system = '', tools = [], catalog = [], dispatch, hooks, signal } = options;
-    const { onRequest, onTurn, onMessage, onToolCall, onToolResult, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, dedupeToolCalls = true, preselectRouting = PRESELECT_EXCLUSIVE, serverInstructions = false, } = options;
+    const { onRequest, onTurn, onMessage, onToolCall, onToolResult, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, dedupeToolCalls = true, preselectRouting = PRESELECT_EXCLUSIVE, serverInstructions = false, artifacts: collecting = {}, } = options;
     const dedupable = typeof dedupeToolCalls === 'function' ? dedupeToolCalls : () => dedupeToolCalls;
     const started = Date.now();
     const { recorded, onEvent } = recorder(options.onEvent);
@@ -637,7 +655,9 @@ async function runSteps(options, standing, pin) {
     let usage = noUsage();
     let cacheReported = false;
     const toolCalls = [];
-    const artifacts = new Map();
+    const artifacts = new RunArtifacts();
+    const { detect = false } = collecting;
+    const detects = typeof detect === 'function' ? detect : detect ? () => true : undefined;
     // A box per request, emptied once its turn is in `messages`: a failure while the tools run had
     // no request in flight.
     let inFlight = {};
@@ -648,7 +668,7 @@ async function runSteps(options, standing, pin) {
             ...(partial ? { partial } : {}),
             usage: loopUsage(usage, cacheReported),
             toolCalls,
-            artifacts: [...artifacts.values()],
+            artifacts: artifacts.list(),
             // As the result would have said it: proxied, nothing is loaded that the history does not hold.
             loaded: proxied ? [] : [...loaded],
             used: [...used],
@@ -693,6 +713,8 @@ async function runSteps(options, standing, pin) {
         used,
         toolCalls,
         artifacts,
+        declares: collecting.declare === true,
+        detects,
         dedupable,
         dispatch,
         parallel,
@@ -850,15 +872,16 @@ async function runSteps(options, standing, pin) {
             notice(`the model stopped at maxTokens (${config.maxTokens}); this turn is cut short`);
         }
         const canRecover = recover && (tools.length > 0 || hostTools.length > 0 || onDemand);
-        const { calls, content } = turnCalls(turn, canRecover ? recoverable : undefined, notice);
+        const { calls, content, recovered } = turnCalls(turn, canRecover ? recoverable : undefined, notice);
         const shown = { ...turn, content, toolCalls: calls };
         onTurn?.(shown, step);
         // Read before the assistant message is written, so what is replayed on every later request
         // is the repaired JSON.
-        const parsed = readCalls(calls, turn.finishReason);
+        const parsed = readCalls(calls, turn.finishReason, recovered);
         const assistant = assistantMessage(content, parsed);
         messages.push(assistant);
-        await announce(assistant, step, shown);
+        // Recovered calls were never calls on the wire: what the model said is the text they came from.
+        await announce(assistant, step, shown, { raw: writtenMessage(turn.content, recovered ? [] : calls) });
         const isAnswer = calls.length === 0;
         const ended = isAnswer ? undefined : await runCalls(calling, parsed, messages, step);
         if (ended) {
@@ -883,7 +906,7 @@ async function runSteps(options, standing, pin) {
                 messages,
                 usage: loopUsage(usage, cacheReported),
                 toolCalls,
-                artifacts: [...artifacts.values()],
+                artifacts: artifacts.list(),
                 loaded: proxied ? [] : [...loaded],
                 used: [...used],
                 preselected: [...preselected],

package/dist/run/artifacts.d.ts

@@ -0,0 +1,145 @@
+import type OpenAI from 'openai';
+import { ArtifactAction, ArtifactSource, type ResourceLink, type RunArtifact, type ToolCallRequest } from '../wire/tool-calls.ts';
+/**
+ * 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. kanban-server and telos each grew these rules, and this is them in one
+ * place; a call's `links`, which take no guessing, are kept by the same ledger.
+ *
+ * A declaration is believed only where some call in the run was given or answered with that
+ * location. Without that, a model with no file tools "saves" its answer to a file it never wrote.
+ */
+/** The name of the tool the loop declares and answers itself when `artifacts.declare` is on. */
+export declare const RECORD_ARTIFACT = "record_artifact";
+/** The definition of `record_artifact`, as the loop declares it beside the host's own tools. */
+export declare const RECORD_ARTIFACT_TOOL: OpenAI.ChatCompletionFunctionTool;
+/**
+ * Which of the guessing sources a run collects, beside the links every run keeps.
+ *
+ * @remarks
+ * Both are off by default: `linked` is the source to rely on, and these are for servers that
+ * never send a `resource_link`.
+ */
+export interface ArtifactOptions {
+    /**
+     * Declares `record_artifact` on every step and answers it in the loop, never through `dispatch`.
+     * The host's own tool of that name, if it has one, is not dispatched while this is on.
+     *
+     * @defaultValue `false`
+     */
+    declare?: boolean;
+    /**
+     * Reads every successful call for the shape of a write. A predicate reads only the calls it
+     * passes, which is how a host keeps its own tools' writes — a note on its board — off the list.
+     *
+     * @defaultValue `false`
+     */
+    detect?: boolean | ((call: ToolCallRequest) => boolean);
+}
+/** What one declaration or detection said of a location, before it is merged into the run's. */
+export interface ArtifactDraft {
+    /** The path or URI, trimmed. */
+    location: string;
+    source: typeof ArtifactSource.Declared | typeof ArtifactSource.Detected;
+    /** What was done to it. A declaration says `created`, and never moves an earlier write's. */
+    action: ArtifactAction;
+    title?: string;
+    description?: string;
+    /** As declared, or else a guess off the extension. */
+    mediaType?: string;
+    /** The bytes of the content the write carried, where its arguments held it. */
+    sizeBytes?: number;
+}
+/** The call an artifact is put down to: the one that linked it, wrote it, or touched it. */
+export type ArtifactFrom = Pick<RunArtifact, 'callId' | 'tool' | 'step'>;
+/**
+ * What a successful call wrote, if its name and arguments look like a write.
+ *
+ * @param name - The tool, as the call named it: `fs__write_file` and `write_file` read alike, the
+ * verb being the last `__` segment.
+ * @param args - The call's arguments.
+ * @returns The draft, or `null` where the name has no write verb, names a folder, or the arguments
+ * hold no location.
+ */
+export declare function detectArtifact(name: string, args: Record<string, unknown>): ArtifactDraft | null;
+/**
+ * What the model said through `record_artifact`.
+ *
+ * @param args - The call's arguments.
+ * @returns The draft, or `null` where it named no location.
+ */
+export declare function declaredArtifact(args: Record<string, unknown>): ArtifactDraft | null;
+/**
+ * A media type guessed off a location's extension.
+ *
+ * @param location - The path or URI. A query or fragment is ignored.
+ * @returns The media type, or `null` for a name with no extension, a dotfile, or an extension this
+ * table does not know.
+ */
+export declare function mediaTypeFor(location: string): string | null;
+/**
+ * How an artifact came to be known, reading an absent `source` as the link it always was.
+ *
+ * @param artifact - One of a run's artifacts.
+ * @returns Its source, `linked` where it carries none.
+ */
+export declare const artifactSource: (artifact: Pick<RunArtifact, 'source'>) => ArtifactSource;
+/**
+ * A run's artifacts, one per location, and what its calls touched for a declaration to be checked
+ * against.
+ *
+ * @remarks
+ * The merge rules are kanban-server's. A later write moves `action` and `sizeBytes` on and leaves
+ * the rest; a declaration over a detection fills in what only the model could say and takes the
+ * source over, without turning an `updated` back into `created`. A link is the server's word, so
+ * a declaration over one fills only what it left out, and a link over either guess takes over.
+ * Each method that adds a location answers with the new artifact, for the caller to announce;
+ * a merge into one already known answers nothing, since the event says when a location was first
+ * seen and the result says what it ended as.
+ */
+export declare class RunArtifacts {
+    #private;
+    /**
+     * The artifacts, in the order first seen.
+     *
+     * @returns A new array of the artifacts themselves, which later merges keep writing to.
+     */
+    list(): RunArtifact[];
+    /**
+     * Adds one call's links, counting a uri seen before and taking over a guess at the same one.
+     *
+     * @param links - What the call's answer linked to, a uri given twice counted once.
+     * @param from - The call they came from.
+     * @returns The artifacts this call added, in the order its links gave them.
+     */
+    link(links: ResourceLink[], from: ArtifactFrom): RunArtifact[];
+    /**
+     * Keeps what a successful call was given and answered, so a declaration naming it is believed.
+     *
+     * @param args - The call's arguments. Every string in them, however deep, is kept bare.
+     * @param answer - What the call answered, kept whole.
+     * @param links - The uris its answer linked to.
+     * @param from - The call.
+     */
+    witness(args: Record<string, unknown>, answer: string, links: ResourceLink[], from: ArtifactFrom): void;
+    /**
+     * The latest call in the run that was given or answered with `location`, which is telos's rule
+     * for believing a declaration.
+     *
+     * @param location - The path or URI a declaration names.
+     * @returns That call, or `undefined` where none was. A blank location was touched by none.
+     */
+    seen(location: string): ArtifactFrom | undefined;
+    /**
+     * Merges a declaration or a detection into the artifact at its location, or adds one.
+     *
+     * @param draft - What was said of the location.
+     * @param from - The call to put a new artifact down to: the write, or for a declaration the call
+     * that touched the location. A merge keeps the earlier one's.
+     * @returns The artifact where this added one, and `undefined` where it merged into one known.
+     *
+     * @remarks
+     * A declaration also finds an artifact whose location is the same bare, so a model's
+     * `/work/a.md` describes the `work/a.md` the write was given rather than standing beside it.
+     */
+    add(draft: ArtifactDraft, from: ArtifactFrom): RunArtifact | undefined;
+}