@cubicecho/agent-core 4.20.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

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { CACHE_PROMPT_FIELD, resetSlots, SESSION_HEADER, SLOT_FIELD, type SlotAl
 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, 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';
 /**
@@ -379,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
@@ -532,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,6 +20,7 @@ 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, writtenMessage, } from './run-calls.js';
@@ -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: ';
 /**
@@ -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,
@@ -884,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;
+}

package/dist/run/artifacts.js

@@ -0,0 +1,412 @@
+import { ArtifactAction, ArtifactSource, } from '../wire/tool-calls.js';
+import { FUNCTION_TOOL, SchemaType } from '../wire/wire.js';
+/**
+ * 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 const RECORD_ARTIFACT = 'record_artifact';
+/** The definition of `record_artifact`, as the loop declares it beside the host's own tools. */
+export const RECORD_ARTIFACT_TOOL = {
+    type: FUNCTION_TOOL,
+    function: {
+        name: RECORD_ARTIFACT,
+        description: 'Name something a tool call in this run stored, so the run lists it: a file one of your tools ' +
+            'wrote, a page it published, an object it uploaded. Only for a location a tool was actually ' +
+            'given or answered with, and only after that call: one that no tool call in this run touched ' +
+            'is refused. Your reply is already kept, so never record it, and never invent a file to put ' +
+            'it in. Calling this adds the title and description a person would want.',
+        parameters: {
+            type: SchemaType.Object,
+            properties: {
+                location: {
+                    type: SchemaType.String,
+                    description: 'The path or URI, exactly as the tool that stored it was given it.',
+                },
+                title: { type: SchemaType.String, description: 'A short name for it.' },
+                description: { type: SchemaType.String, description: 'One sentence on what it is for.' },
+                mediaType: { type: SchemaType.String, description: 'e.g. text/markdown. Optional.' },
+            },
+            required: ['location'],
+            additionalProperties: false,
+        },
+    },
+};
+/** A verb at the front of a tool name that means something was written somewhere. */
+const WRITE_VERB = /^(write|create|save|upload|put|append|edit|move|rename|copy|publish|delete|remove)(_|$)/;
+/** Writes that leave nothing a person would call an artifact behind. */
+const NOT_ARTIFACTS = new Set(['create_directory', 'create_dir', 'create_folder', 'mkdir']);
+/** The argument names a location goes by, in the order they are believed. */
+const LOCATION_KEYS = [
+    'destination',
+    'dest',
+    'target',
+    'path',
+    'file_path',
+    'filePath',
+    'filename',
+    'file',
+    'uri',
+    'url',
+    'key',
+];
+/** The argument names a write's content goes by, in the order they are believed. */
+const CONTENT_KEYS = ['content', 'contents', 'text', 'body', 'data'];
+/** The separator between a server's slug and its tool, in the names a pool hands the loop. */
+const SLUG_SEPARATOR = '__';
+const encoder = new TextEncoder();
+/**
+ * What a write did, read off its verb.
+ *
+ * @param verb - The tool's own name, lowercased, after any slug.
+ * @returns `updated` for an edit or append, `moved` for a move or rename, `deleted` for a delete or
+ * remove, and `created` for everything else.
+ */
+function actionOf(verb) {
+    if (/^(edit|append)/.test(verb)) {
+        return ArtifactAction.Updated;
+    }
+    if (/^(move|rename)/.test(verb)) {
+        return ArtifactAction.Moved;
+    }
+    if (/^(delete|remove)/.test(verb)) {
+        return ArtifactAction.Deleted;
+    }
+    return ArtifactAction.Created;
+}
+/**
+ * The first of these arguments that is a string, under the first key that holds one.
+ *
+ * @param args - The call's arguments.
+ * @param keys - The names to try, in order.
+ * @param [isBlankOk] - Whether an empty or all-space string counts. It does for content.
+ * @returns The string, or `undefined` where none of the keys held one.
+ */
+function firstString(args, keys, isBlankOk = false) {
+    return keys
+        .map((key) => args[key])
+        .find((value) => typeof value === 'string' && (isBlankOk || value.trim() !== ''));
+}
+/**
+ * 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 function detectArtifact(name, args) {
+    const verb = name.split(SLUG_SEPARATOR).at(-1)?.toLowerCase() ?? '';
+    const isWrite = WRITE_VERB.test(verb) && NOT_ARTIFACTS.has(verb) === false;
+    const location = isWrite ? firstString(args, LOCATION_KEYS) : undefined;
+    if (location === undefined) {
+        return null;
+    }
+    const content = firstString(args, CONTENT_KEYS, true);
+    const mediaType = mediaTypeFor(location);
+    return {
+        location: location.trim(),
+        source: ArtifactSource.Detected,
+        action: actionOf(verb),
+        ...(mediaType ? { mediaType } : {}),
+        ...(content === undefined ? {} : { sizeBytes: encoder.encode(content).byteLength }),
+    };
+}
+/**
+ * What the model said through `record_artifact`.
+ *
+ * @param args - The call's arguments.
+ * @returns The draft, or `null` where it named no location.
+ */
+export function declaredArtifact(args) {
+    const text = (key) => (typeof args[key] === 'string' ? args[key].trim() : '');
+    const location = text('location');
+    if (location === '') {
+        return null;
+    }
+    const mediaType = text('mediaType') || mediaTypeFor(location);
+    return {
+        location,
+        source: ArtifactSource.Declared,
+        action: ArtifactAction.Created,
+        ...(text('title') ? { title: text('title') } : {}),
+        ...(text('description') ? { description: text('description') } : {}),
+        ...(mediaType ? { mediaType } : {}),
+    };
+}
+const MEDIA_TYPES = {
+    md: 'text/markdown',
+    markdown: 'text/markdown',
+    txt: 'text/plain',
+    csv: 'text/csv',
+    html: 'text/html',
+    htm: 'text/html',
+    css: 'text/css',
+    json: 'application/json',
+    yaml: 'application/yaml',
+    yml: 'application/yaml',
+    xml: 'application/xml',
+    js: 'text/javascript',
+    ts: 'text/x-typescript',
+    tsx: 'text/x-typescript',
+    py: 'text/x-python',
+    sh: 'application/x-sh',
+    svg: 'image/svg+xml',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    pdf: 'application/pdf',
+    zip: 'application/zip',
+};
+/**
+ * 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 function mediaTypeFor(location) {
+    const name = location.split(/[?#]/)[0].split(/[\\/]/).at(-1) ?? '';
+    const dot = name.lastIndexOf('.');
+    if (dot <= 0) {
+        return null;
+    }
+    return MEDIA_TYPES[name.slice(dot + 1).toLowerCase()] ?? 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 const artifactSource = (artifact) => artifact.source ?? ArtifactSource.Linked;
+/**
+ * A location as it is compared: no scheme, no leading slashes, no trailing ones.
+ *
+ * @param location - The path or URI.
+ * @returns The bare form, so `/work/a.md`, `work/a.md` and `file:///work/a.md` compare equal.
+ */
+function bare(location) {
+    return location
+        .trim()
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, '')
+        .replace(/^\/+|\/+$/g, '');
+}
+/**
+ * A declared or detected location as a link, the shape every artifact is kept in.
+ *
+ * @param draft - What was said of it.
+ * @returns A link whose `uri` is the location and whose `name` is its last segment.
+ */
+function linkOf(draft) {
+    const name = draft.location.split(/[?#]/)[0].split(/[\\/]/).filter(Boolean).at(-1) ?? draft.location;
+    return {
+        uri: draft.location,
+        name,
+        ...(draft.title ? { title: draft.title } : {}),
+        ...(draft.description ? { description: draft.description } : {}),
+        ...(draft.mediaType ? { mimeType: draft.mediaType } : {}),
+    };
+}
+/**
+ * What tells one call from another across a run: an id is distinct only within its step.
+ *
+ * @param from - The call.
+ * @returns Its step and id as one string.
+ */
+const callKey = ({ callId, step }) => `${step}\0${callId}`;
+/**
+ * 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 class RunArtifacts {
+    #byLocation = new Map();
+    /** Each string a call was given or answered with, bare, beside the call. Kept only to declare. */
+    #witnessed = [];
+    /** The last call each artifact was counted for, so a call that links and writes one counts once. */
+    #countedFor = new WeakMap();
+    /**
+     * The artifacts, in the order first seen.
+     *
+     * @returns A new array of the artifacts themselves, which later merges keep writing to.
+     */
+    list() {
+        return [...this.#byLocation.values()];
+    }
+    /**
+     * 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, from) {
+        const seen = new Set();
+        const added = [];
+        for (const link of links) {
+            if (seen.has(link.uri)) {
+                continue;
+            }
+            seen.add(link.uri);
+            const known = this.#byLocation.get(link.uri);
+            if (known === undefined) {
+                const artifact = { link, ...from, count: 1 };
+                this.#byLocation.set(link.uri, artifact);
+                this.#countedFor.set(artifact, callKey(from));
+                added.push(artifact);
+                continue;
+            }
+            this.#count(known, from);
+            if (known.source !== undefined) {
+                // What a guess said of it stays only where the server's own link says nothing.
+                const { title, description, mimeType } = known.link;
+                known.link = {
+                    ...(title ? { title } : {}),
+                    ...(description ? { description } : {}),
+                    ...(mimeType ? { mimeType } : {}),
+                    ...link,
+                };
+                delete known.source;
+            }
+        }
+        return added;
+    }
+    /**
+     * 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, answer, links, from) {
+        const strings = (value) => {
+            if (typeof value === 'string') {
+                this.#witnessed.push({ text: bare(value), from });
+            }
+            else if (Array.isArray(value)) {
+                value.forEach(strings);
+            }
+            else if (value && typeof value === 'object') {
+                Object.values(value).forEach(strings);
+            }
+        };
+        strings(args);
+        this.#witnessed.push({ text: answer, from });
+        for (const { uri } of links) {
+            this.#witnessed.push({ text: bare(uri), from });
+        }
+    }
+    /**
+     * 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) {
+        const wanted = bare(location);
+        if (wanted === '') {
+            return undefined;
+        }
+        return this.#witnessed.findLast(({ text }) => text === wanted || text.includes(wanted))?.from;
+    }
+    /**
+     * 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, from) {
+        const known = this.#find(draft);
+        if (known === undefined) {
+            const artifact = {
+                link: linkOf(draft),
+                ...from,
+                count: 1,
+                source: draft.source,
+                ...(draft.source === ArtifactSource.Detected ? { action: draft.action } : {}),
+                ...(draft.sizeBytes === undefined ? {} : { sizeBytes: draft.sizeBytes }),
+            };
+            this.#byLocation.set(draft.location, artifact);
+            this.#countedFor.set(artifact, callKey(from));
+            return artifact;
+        }
+        if (draft.source === ArtifactSource.Detected) {
+            this.#count(known, from);
+            known.action = draft.action;
+            if (draft.sizeBytes !== undefined) {
+                known.sizeBytes = draft.sizeBytes;
+            }
+            if (known.link.mimeType === undefined && draft.mediaType) {
+                known.link = { ...known.link, mimeType: draft.mediaType };
+            }
+            return undefined;
+        }
+        const isLinked = known.source === undefined;
+        // Over a link, only what it left out; over a guess, what the model said wins.
+        const fill = (field, value) => {
+            const isTaken = isLinked && Boolean(known.link[field]);
+            if (value && isTaken === false) {
+                known.link = { ...known.link, [field]: value };
+            }
+        };
+        fill('title', draft.title);
+        fill('description', draft.description);
+        fill('mimeType', draft.mediaType);
+        if (isLinked === false) {
+            known.source = ArtifactSource.Declared;
+        }
+        return undefined;
+    }
+    /**
+     * Counts one more call that made an artifact, unless that call was counted for it already.
+     *
+     * @param artifact - The artifact. Written to.
+     * @param from - The call.
+     */
+    #count(artifact, from) {
+        const key = callKey(from);
+        if (this.#countedFor.get(artifact) !== key) {
+            artifact.count++;
+            this.#countedFor.set(artifact, key);
+        }
+    }
+    /**
+     * The artifact a draft lands on: the one at its location, or for a declaration one that is the
+     * same location bare.
+     *
+     * @param draft - What was said.
+     * @returns The artifact, or `undefined` where the location is new.
+     */
+    #find(draft) {
+        const exact = this.#byLocation.get(draft.location);
+        if (exact !== undefined || draft.source === ArtifactSource.Detected) {
+            return exact;
+        }
+        const wanted = bare(draft.location);
+        return [...this.#byLocation.values()].find((artifact) => bare(artifact.link.uri) === wanted);
+    }
+}

package/dist/run/events.d.ts

@@ -91,9 +91,11 @@ export declare const RunEventKind: {
     /** Something the runner did that is not the model's doing — a preselection, a retry. */
     readonly Notice: 'notice';
     /**
-     * A tool call's answer linked to something the run had not produced before. `id` is the call's,
-     * `name` the tool, `text` the link's title or else its uri, and `link` the link itself. Once
-     * per uri per run: a later call that links the same uri again only adds to its count.
+     * A tool call's answer linked to something the run had not produced before — or, where the run
+     * collects them, a write was detected or a declaration believed at a new location. `id` is the
+     * call's the artifact is put down to, `name` its tool, `text` the link's title or else its uri,
+     * and `link` the link itself. Once per location per run: a later call that links or writes it
+     * again only adds to its count, and a declaration over it only fills it in.
      */
     readonly Artifact: 'artifact';
     /**

package/dist/run/events.js

@@ -58,9 +58,11 @@ export const RunEventKind = {
     /** Something the runner did that is not the model's doing — a preselection, a retry. */
     Notice: 'notice',
     /**
-     * A tool call's answer linked to something the run had not produced before. `id` is the call's,
-     * `name` the tool, `text` the link's title or else its uri, and `link` the link itself. Once
-     * per uri per run: a later call that links the same uri again only adds to its count.
+     * A tool call's answer linked to something the run had not produced before — or, where the run
+     * collects them, a write was detected or a declaration believed at a new location. `id` is the
+     * call's the artifact is put down to, `name` its tool, `text` the link's title or else its uri,
+     * and `link` the link itself. Once per location per run: a later call that links or writes it
+     * again only adds to its count, and a declaration over it only fills it in.
      */
     Artifact: 'artifact',
     /**

package/dist/run/run-calls.d.ts

@@ -1,7 +1,8 @@
 import type OpenAI from 'openai';
 import type { CatalogServer } from '../tools/catalog.ts';
 import type { Turn } from '../wire/stream.ts';
-import { type EndedBy, type RunArtifact, type ToolAnswer, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
+import { type EndedBy, type ToolAnswer, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
+import { type RunArtifacts } from './artifacts.ts';
 import type { LoadCounts, RunEventInput } from './events.ts';
 /**
  * The tools between two turns: a step's calls read, run and written into the transcript.
@@ -104,8 +105,12 @@ export interface Calling {
     loads: LoadCounts;
     used: Set<string>;
     toolCalls: ToolCallOutcome[];
-    /** What the run's calls linked to, by uri, in the order first seen. */
-    artifacts: Map<string, RunArtifact>;
+    /** What the run's calls linked to, wrote, or were said to have stored, by location. */
+    artifacts: RunArtifacts;
+    /** Whether `record_artifact` is the loop's to answer, and every successful call is witnessed. */
+    declares: boolean;
+    /** Which successful calls are read for the shape of a write. Absent where none are. */
+    detects: ((call: ToolCallRequest) => boolean) | undefined;
     dedupable: (call: ToolCallRequest) => boolean;
     dispatch: ToolDispatch;
     /** All of a step's calls together, each alone, or together in runs of the calls it passes. */

package/dist/run/run-calls.js

@@ -3,6 +3,7 @@ import { CALL_TOOL, expandNames, inCatalog, LOAD_TOOLS, loadResult, proxiedCall,
 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.
@@ -262,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.
@@ -323,10 +353,11 @@ function prepare(run, entry) {
     // 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.
@@ -334,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.
@@ -390,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) });
@@ -410,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;
@@ -449,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);
@@ -515,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);

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

@@ -278,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

@@ -178,6 +178,19 @@ The loop above a turn: send, run the tools the model asked for, send again, unti
 - `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
 
 What a run is doing, while it is doing it.
@@ -433,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.20.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",