@shardflux/sdk 0.6.1 → 0.7.0

package/dist/capture-serialize.js

@@ -0,0 +1,481 @@
+/**
+ * Output encoding for tool-call capture (docs/decisions/0006-tool-call-capture.md, "Output encoding"; golden cases in
+ * packages/contracts/schemas/examples/tool-call-capture/cases.json). Pure functions: a value in, the files to store and
+ * the index fields out. Serialization never throws: a value that cannot be converted becomes `{"$type","$repr"}`, and
+ * a failure of the whole conversion is reported as `dropped: "serialize_failed"`.
+ */
+import { createHash } from 'node:crypto';
+import { inspect } from 'node:util';
+export const DEFAULT_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+const REPR_MAX = 4096;
+const encoder = new TextEncoder();
+export const sha256Hex = (data) => createHash('sha256').update(data).digest('hex');
+/**
+ * The tool name as used in file names: every Unicode code point outside `[A-Za-z0-9._-]` becomes `_`, cut to 64
+ * characters; an empty result becomes `tool`.
+ */
+export function sanitizeToolName(name) {
+    let out = '';
+    for (const ch of name) {
+        out += /^[A-Za-z0-9._-]$/.test(ch) ? ch : '_';
+        if (out.length >= 64)
+            break;
+    }
+    return out.length === 0 ? 'tool' : out;
+}
+/** Sequence numbers in file names: zero-padded to 6 digits (more digits past 999999). */
+export const padSeq = (seq) => String(seq).padStart(6, '0');
+// ---- bytes and magic numbers -------------------------------------------------------------------
+/** Raw bytes as the capture stores them: Uint8Array (and Buffer), ArrayBuffer, DataView. Other typed arrays are JSON. */
+export function asBytes(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    if (typeof SharedArrayBuffer !== 'undefined' && value instanceof SharedArrayBuffer)
+        return new Uint8Array(value);
+    if (value instanceof DataView)
+        return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    return null;
+}
+const startsWith = (b, sig, at = 0) => b.length >= at + sig.length && sig.every((v, i) => b[at + i] === v);
+const ascii = (s) => [...s].map((c) => c.charCodeAt(0));
+const MAGIC = [
+    { test: (b) => startsWith(b, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), ext: '.png', type: 'image/png' },
+    { test: (b) => startsWith(b, [0xff, 0xd8, 0xff]), ext: '.jpg', type: 'image/jpeg' },
+    { test: (b) => startsWith(b, ascii('GIF87a')) || startsWith(b, ascii('GIF89a')), ext: '.gif', type: 'image/gif' },
+    { test: (b) => startsWith(b, ascii('RIFF')) && startsWith(b, ascii('WEBP'), 8), ext: '.webp', type: 'image/webp' },
+    { test: (b) => startsWith(b, ascii('%PDF-')), ext: '.pdf', type: 'application/pdf' },
+    { test: (b) => startsWith(b, [0x50, 0x4b, 0x03, 0x04]) || startsWith(b, [0x50, 0x4b, 0x05, 0x06]) || startsWith(b, [0x50, 0x4b, 0x07, 0x08]), ext: '.zip', type: 'application/zip' },
+    { test: (b) => startsWith(b, [0x1f, 0x8b]), ext: '.gz', type: 'application/gzip' },
+    { test: (b) => startsWith(b, ascii('PAR1')), ext: '.parquet', type: 'application/vnd.apache.parquet' },
+];
+/** Extension and content type from magic bytes; `.bin` `application/octet-stream` when none matches. */
+export function sniff(bytes) {
+    for (const m of MAGIC)
+        if (m.test(bytes))
+            return { ext: m.ext, contentType: m.type };
+    return { ext: '.bin', contentType: 'application/octet-stream' };
+}
+/** MIME types with a known extension: the magic-byte table plus the text types of rule 4. */
+const MIME_EXT = {
+    ...Object.fromEntries(MAGIC.map((m) => [m.type, m.ext])),
+    'text/plain': '.txt',
+    'text/csv': '.csv',
+    'text/html': '.html',
+    'text/markdown': '.md',
+    'application/json': '.json',
+};
+const TEXT_TYPES = {
+    '.txt': 'text/plain; charset=utf-8',
+    '.csv': 'text/csv; charset=utf-8',
+    '.html': 'text/html; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
+};
+const mimeBase = (mime) => (mime.split(';')[0] ?? '').trim().toLowerCase();
+// ---- streams ------------------------------------------------------------------------------------
+/**
+ * Values capture never reads (reading would consume them): Response, ReadableStream, Node streams, Blob, generator
+ * objects and other async iterables (a wrapped tool's async generator is teed instead; see capture.ts).
+ */
+export function isUnreadable(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (typeof value[Symbol.asyncIterator] === 'function')
+        return true;
+    if (Object.prototype.toString.call(value) === '[object Generator]')
+        return true;
+    if (typeof Response !== 'undefined' && value instanceof Response)
+        return true;
+    if (typeof ReadableStream !== 'undefined' && value instanceof ReadableStream)
+        return true;
+    if (typeof Blob !== 'undefined' && value instanceof Blob)
+        return true;
+    const v = value;
+    if (typeof v.pipe === 'function' && typeof v.on === 'function')
+        return true; // Node stream
+    return typeof v.getReader === 'function' && typeof v.cancel === 'function'; // a ReadableStream from another realm
+}
+// ---- JSON-safe conversion (rule 5) --------------------------------------------------------------
+function repr(value) {
+    let type = typeof value;
+    try {
+        if (typeof value === 'object' && value !== null)
+            type = value.constructor?.name || 'Object';
+        else if (typeof value === 'function')
+            type = 'function';
+    }
+    catch {
+        // a hostile constructor getter
+    }
+    let text;
+    try {
+        text = typeof value === 'function' ? `[Function ${value.name || 'anonymous'}]` : inspect(value, { depth: 2, breakLength: Infinity });
+    }
+    catch {
+        text = `[${type}]`;
+    }
+    return { $type: type, $repr: text.length > REPR_MAX ? text.slice(0, REPR_MAX) : text };
+}
+const b64 = (bytes) => Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64');
+/** Parses a JSON arguments string (OpenAI); anything else is kept as it is. An empty string is `{}`. */
+export function parseArguments(v) {
+    if (typeof v !== 'string')
+        return v;
+    if (v.trim() === '')
+        return {};
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        return v;
+    }
+}
+/** An error as the index line and outputs carry it: `{type, message}`. */
+export function errorInfo(err) {
+    if (err instanceof Error)
+        return { type: err.name || err.constructor?.name || 'Error', message: String(err.message) };
+    if (typeof err === 'object' && err !== null) {
+        const e = err;
+        const type = typeof e.name === 'string' ? e.name : typeof e.type === 'string' ? e.type : 'Error';
+        if (typeof e.message === 'string')
+            return { type, message: e.message };
+        return { type, message: safeStringify(err) };
+    }
+    return { type: typeof err === 'string' ? 'Error' : typeof err, message: String(err) };
+}
+/**
+ * Converts any value to plain JSON data (objects, arrays, strings, finite numbers, booleans, null): `toJSON`, Date →
+ * ISO string, Map → object, Set → array, BigInt → string, NaN/Infinity → null, errors → `{type, message}`, nested bytes
+ * → `{"$base64"}`, cycles → `"[Circular]"`, unconvertible → `{"$type","$repr"}`. Functions and symbols inside objects
+ * are left out and inside arrays become null, as in JSON.stringify. Never throws. `undefined` at the top stays
+ * undefined.
+ */
+export function toJsonSafe(value) {
+    const ancestors = new Set();
+    const walk = (v, key, inArray) => {
+        switch (typeof v) {
+            case 'string':
+            case 'boolean':
+                return v;
+            case 'number':
+                return Number.isFinite(v) ? v : null;
+            case 'bigint':
+                return v.toString();
+            case 'undefined':
+                return inArray ? null : undefined;
+            case 'function':
+            case 'symbol':
+                return inArray ? null : undefined;
+        }
+        if (v === null)
+            return null;
+        const obj = v;
+        const bytes = asBytes(obj);
+        if (bytes)
+            return { $base64: b64(bytes) };
+        if (ancestors.has(obj))
+            return '[Circular]';
+        try {
+            if (obj instanceof Error)
+                return errorInfo(obj);
+            if (typeof obj.toJSON === 'function') {
+                let j;
+                try {
+                    j = obj.toJSON(key);
+                }
+                catch {
+                    return repr(obj);
+                }
+                if (j === obj)
+                    return repr(obj);
+                ancestors.add(obj);
+                try {
+                    return walk(j, key, inArray);
+                }
+                finally {
+                    ancestors.delete(obj);
+                }
+            }
+            ancestors.add(obj);
+            try {
+                if (Array.isArray(obj))
+                    return obj.map((x, i) => walk(x, String(i), true));
+                if (ArrayBuffer.isView(obj))
+                    return Array.from(obj, (x) => walk(x, '', true));
+                if (obj instanceof Map) {
+                    const out = {};
+                    for (const [k, x] of obj) {
+                        const w = walk(x, String(k), false);
+                        if (w !== undefined)
+                            out[typeof k === 'string' ? k : String(typeof k === 'object' && k !== null ? safeStringify(k) : k)] = w;
+                    }
+                    return out;
+                }
+                if (obj instanceof Set)
+                    return [...obj].map((x, i) => walk(x, String(i), true));
+                if (obj instanceof Promise || obj instanceof WeakMap || obj instanceof WeakSet || obj instanceof RegExp)
+                    return repr(obj);
+                const out = {};
+                for (const k of Object.keys(obj)) {
+                    let x;
+                    try {
+                        x = obj[k];
+                    }
+                    catch (e) {
+                        x = repr(e);
+                    }
+                    const w = walk(x, k, false);
+                    if (w !== undefined)
+                        out[k] = w;
+                }
+                return out;
+            }
+            finally {
+                ancestors.delete(obj);
+            }
+        }
+        catch {
+            return repr(obj);
+        }
+    };
+    if (typeof value === 'function' || typeof value === 'symbol')
+        return repr(value);
+    return walk(value, '', false);
+}
+/** Compact JSON of any value (via toJsonSafe); never throws. Undefined becomes `null`. */
+export function safeStringify(value) {
+    try {
+        return JSON.stringify(toJsonSafe(value)) ?? 'null';
+    }
+    catch {
+        return JSON.stringify(repr(value));
+    }
+}
+// ---- strings (rule 3) ---------------------------------------------------------------------------
+/** A JSON object or array in strict JSON (no NaN/Infinity), surrounded only by JSON whitespace. */
+export function isJsonContainerText(s) {
+    let i = 0;
+    while (i < s.length && (s[i] === ' ' || s[i] === '\t' || s[i] === '\n' || s[i] === '\r'))
+        i += 1;
+    const c = s[i];
+    if (c !== '{' && c !== '[')
+        return false;
+    try {
+        const v = JSON.parse(s);
+        return typeof v === 'object' && v !== null;
+    }
+    catch {
+        return false;
+    }
+}
+const HTML_START = /^\s*(<!doctype html|<html)/i;
+function textFile(text) {
+    if (isJsonContainerText(text))
+        return { ext: '.json', contentType: 'application/json' };
+    if (HTML_START.test(text))
+        return { ext: '.html', contentType: 'text/html; charset=utf-8' };
+    return { ext: '.txt', contentType: 'text/plain; charset=utf-8' };
+}
+/** The longest prefix of at most `max` bytes that ends on a UTF-8 character boundary. */
+export function cutUtf8(bytes, max) {
+    if (bytes.length <= max)
+        return bytes;
+    let cut = Math.max(0, max);
+    while (cut > 0 && ((bytes[cut] ?? 0) & 0xc0) === 0x80)
+        cut -= 1;
+    return bytes.subarray(0, cut);
+}
+function file(path, data, contentType) {
+    return { path, data, contentType, sha256: sha256Hex(data) };
+}
+function single(base, data, ext, contentType, max, textual) {
+    if (data.length > max) {
+        if (!textual)
+            return dropped('too_large');
+        const cut = cutUtf8(data, max);
+        const f = file(`${base}${ext}.part`, cut, contentType);
+        return { files: [f], outputPath: f.path, contentType, bytes: cut.length, sha256: f.sha256, truncated: true };
+    }
+    const f = file(`${base}${ext}`, data, contentType);
+    return { files: [f], outputPath: f.path, contentType, bytes: data.length, sha256: f.sha256, truncated: false };
+}
+export function dropped(reason, note) {
+    return { files: [], outputPath: null, contentType: null, bytes: 0, sha256: null, truncated: false, dropped: reason, ...(note ? { note } : {}) };
+}
+const NONE = Object.freeze({ files: [], outputPath: null, contentType: null, bytes: 0, sha256: null, truncated: false });
+// ---- multi-part (rule 4) ------------------------------------------------------------------------
+const BLOCK_TYPES = new Set(['text', 'image', 'document', 'resource', 'resource_link', 'audio', 'search_result']);
+const MCP_KEYS = new Set(['content', 'isError', 'is_error', 'structuredContent', 'structured_content', '_meta', 'meta', 'resultType', 'result_type']);
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** An MCP-like result: `content` a non-empty array of objects with a string `type`, other keys from the MCP set. */
+export function isMcpLike(v) {
+    if (!isObj(v))
+        return false;
+    const content = v.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return false;
+    if (!content.every((b) => isObj(b) && typeof b.type === 'string'))
+        return false;
+    return Object.keys(v).every((k) => MCP_KEYS.has(k));
+}
+/** A content-block array: non-empty, every item an object whose `type` is a known block type. */
+export function isBlockArray(v) {
+    return Array.isArray(v) && v.length > 0 && v.every((b) => isObj(b) && typeof b.type === 'string' && BLOCK_TYPES.has(b.type));
+}
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+const decodeBase64 = (s) => (s.length % 4 === 0 && BASE64.test(s) ? new Uint8Array(Buffer.from(s, 'base64')) : null);
+/** The payloads of one block, in order (at most one per block). */
+function payloadOf(block) {
+    const str = (v) => (typeof v === 'string' ? v : null);
+    const type = block.type;
+    if (type === 'text' && typeof block.text === 'string') {
+        return { kind: 'text', value: block.text, mime: str(block.mimeType) ?? str(block.mime_type), set: (r) => (block.text = r) };
+    }
+    if ((type === 'image' || type === 'audio') && typeof block.data === 'string') {
+        return { kind: 'base64', value: block.data, mime: str(block.mimeType) ?? str(block.mime_type), set: (r) => (block.data = r) };
+    }
+    if (type === 'resource' && isObj(block.resource)) {
+        const res = block.resource;
+        if (typeof res.text === 'string')
+            return { kind: 'text', value: res.text, mime: str(res.mimeType) ?? str(res.mime_type), set: (r) => (res.text = r) };
+        if (typeof res.blob === 'string')
+            return { kind: 'base64', value: res.blob, mime: str(res.mimeType) ?? str(res.mime_type), set: (r) => (res.blob = r) };
+    }
+    if (isObj(block.source)) {
+        const src = block.source;
+        if (src.type === 'text' && typeof src.data === 'string')
+            return { kind: 'text', value: src.data, mime: str(src.media_type), set: (r) => (src.data = r) };
+        if (src.type === 'base64' && typeof src.data === 'string')
+            return { kind: 'base64', value: src.data, mime: str(src.media_type), set: (r) => (src.data = r) };
+    }
+    return null;
+}
+function multipart(root, blocks, base, max) {
+    const files = [];
+    let i = 0;
+    for (const block of blocks) {
+        const p = payloadOf(block);
+        if (!p)
+            continue;
+        let data;
+        let ext;
+        let contentType;
+        if (p.kind === 'text') {
+            data = encoder.encode(p.value);
+            if (isJsonContainerText(p.value)) {
+                ext = '.json';
+                contentType = 'application/json';
+            }
+            else {
+                const m = p.mime ? mimeBase(p.mime) : '';
+                ext = m === 'text/csv' ? '.csv' : m === 'text/html' ? '.html' : m === 'text/markdown' ? '.md' : '.txt';
+                contentType = TEXT_TYPES[ext];
+            }
+        }
+        else {
+            const decoded = decodeBase64(p.value);
+            if (!decoded)
+                continue; // not base64: left in result.json as it is
+            data = decoded;
+            const sniffed = sniff(data);
+            const m = p.mime ? mimeBase(p.mime) : '';
+            contentType = p.mime ? p.mime.toLowerCase() : sniffed.contentType;
+            ext = MIME_EXT[m] ?? sniffed.ext;
+        }
+        i += 1;
+        const name = `part-${i}${ext}`;
+        files.push(file(`${base}/${name}`, data, contentType));
+        p.set({ $part: name });
+    }
+    const result = file(`${base}/result.json`, encoder.encode(JSON.stringify(root)), 'application/json');
+    files.push(result);
+    const total = files.reduce((n, f) => n + f.data.length, 0);
+    if (total > max)
+        return dropped('too_large');
+    return {
+        files,
+        outputPath: `${base}/`,
+        contentType: 'multipart/mixed',
+        bytes: total,
+        sha256: result.sha256,
+        truncated: false,
+        parts: files.map((f) => ({ path: f.path, content_type: f.contentType, bytes: f.data.length, sha256: f.sha256 })),
+    };
+}
+// ---- the whole output ---------------------------------------------------------------------------
+/**
+ * Plans how `value` is stored. `base` is `<seq>-<tool>` (zero-padded seq, sanitized tool name). Never throws.
+ */
+export function planOutput(value, base, maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES) {
+    try {
+        if (value === undefined || value === null)
+            return NONE;
+        if (isUnreadable(value))
+            return { ...NONE, note: 'stream_not_captured' };
+        const bytes = asBytes(value);
+        if (bytes) {
+            const s = sniff(bytes);
+            return single(base, bytes, s.ext, s.contentType, maxOutputBytes, false);
+        }
+        if (typeof value === 'string') {
+            const t = textFile(value);
+            return single(base, encoder.encode(value), t.ext, t.contentType, maxOutputBytes, true);
+        }
+        const plain = toJsonSafe(value);
+        if (isMcpLike(plain))
+            return multipart(plain, plain.content, base, maxOutputBytes);
+        if (isBlockArray(plain))
+            return multipart(plain, plain, base, maxOutputBytes);
+        return single(base, encoder.encode(JSON.stringify(plain) ?? 'null'), '.json', 'application/json', maxOutputBytes, true);
+    }
+    catch {
+        return dropped('serialize_failed');
+    }
+}
+/** Items of an async iterable as `.jsonl` (rule 7): one compact JSON line per item, cut at `max` bytes. */
+export class JsonlCollector {
+    #max;
+    #chunks = [];
+    #size = 0;
+    truncated = false;
+    count = 0;
+    constructor(max) {
+        this.#max = max;
+    }
+    push(item) {
+        this.count += 1;
+        if (this.truncated)
+            return;
+        const line = encoder.encode(`${safeStringify(item)}\n`);
+        if (this.#size + line.length > this.#max) {
+            this.#chunks.push(cutUtf8(line, this.#max - this.#size));
+            this.#size = this.#max;
+            this.truncated = true;
+            return;
+        }
+        this.#chunks.push(line);
+        this.#size += line.length;
+    }
+    /** The items collected so far, parsed back (a cut last line is left out). */
+    values() {
+        const text = Buffer.concat(this.#chunks).toString('utf8');
+        const out = [];
+        for (const line of text.split('\n')) {
+            if (line.length === 0)
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                // the line cut at the size limit
+            }
+        }
+        return out;
+    }
+    plan(base) {
+        const data = Buffer.concat(this.#chunks);
+        const f = file(`${base}.jsonl${this.truncated ? '.part' : ''}`, new Uint8Array(data.buffer, data.byteOffset, data.byteLength), 'application/x-ndjson');
+        return { files: [f], outputPath: f.path, contentType: 'application/x-ndjson', bytes: data.length, sha256: f.sha256, truncated: this.truncated };
+    }
+}

package/dist/capture-text.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The texts tool-call capture writes or returns, embedded because the package publishes only dist/. They are copies of
+ * packages/contracts/capture/workspace-readme.md and prompt-hint.md (test/capture.test.ts asserts they are equal).
+ * Placeholders: {{dir}} (the capture directory) and {{run_dir}} (the run directory).
+ */
+/** <dir>/README.md, written once per capture. */
+export declare const WORKSPACE_README = "# Tool calls\n\nEvery tool call made by the agent's harness is saved here by Shardflux tool-call capture. Each run (one capture,\nusually one process or one conversation turn) has its own directory, named by its start time.\n\n    {{dir}}/<run>/index.jsonl              one JSON line per call, in completion order\n    {{dir}}/<run>/000007-web_search.json   the full output of call 7 (.json, .txt, .html, .png, .pdf, ...)\n    {{dir}}/<run>/000010-search/           an output with several parts: part-1.txt, part-2.png, result.json\n    {{dir}}/<run>/000011-sql.input.json    an input too large for the index line\n    *.part                                 an output cut at the size limit (\"truncated\": true)\n\nIndex fields: seq, call_id, tool, status (ok, error, cancelled, incomplete, retry), error, started_at, duration_ms,\ninput (or input_path), output_path (relative to the run directory), content_type, bytes, truncated.\n\nRead the index with `fromjson?` so a partially written line is skipped:\n\n    cat {{dir}}/*/index.jsonl | jq -cR 'fromjson? // empty'\n    cat {{dir}}/*/index.jsonl | jq -cR 'fromjson? // empty | select(.call_id == \"toolu_...\")'\n    cat {{dir}}/*/index.jsonl | jq -cR 'fromjson? // empty | select(.tool == \"web_search\") | \"\\(.run)/\\(.output_path)\"'\n\nIn Python:\n\n    import json, pathlib\n\n    def calls(root=\"{{dir}}\"):\n        for index in sorted(pathlib.Path(root).glob(\"*/index.jsonl\")):\n            for line in index.read_text().splitlines():\n                try:\n                    yield json.loads(line)\n                except ValueError:\n                    pass  # a partially written line\n";
+/** The paragraph promptHint() returns (never injected into a prompt by the SDK). */
+export declare const PROMPT_HINT = "Every tool call you make is also saved as files in this workspace. {{run_dir}}/index.jsonl has one JSON line per call (call_id, tool, status, input, output_path), and the full output of each call is at {{run_dir}}/<output_path>. Earlier runs are in the other directories under {{dir}}, described in {{dir}}/README.md. To analyse or transform a tool result with code, read it from these files (for example with jq or Python) rather than copying it from the conversation.\n";
+/** Fills {{dir}} and {{run_dir}}. */
+export declare function fillTemplate(text: string, vars: {
+    dir: string;
+    run_dir: string;
+}): string;

package/dist/capture-text.js

@@ -0,0 +1,13 @@
+/**
+ * The texts tool-call capture writes or returns, embedded because the package publishes only dist/. They are copies of
+ * packages/contracts/capture/workspace-readme.md and prompt-hint.md (test/capture.test.ts asserts they are equal).
+ * Placeholders: {{dir}} (the capture directory) and {{run_dir}} (the run directory).
+ */
+/** <dir>/README.md, written once per capture. */
+export const WORKSPACE_README = "# Tool calls\n\nEvery tool call made by the agent's harness is saved here by Shardflux tool-call capture. Each run (one capture,\nusually one process or one conversation turn) has its own directory, named by its start time.\n\n    {{dir}}/<run>/index.jsonl              one JSON line per call, in completion order\n    {{dir}}/<run>/000007-web_search.json   the full output of call 7 (.json, .txt, .html, .png, .pdf, ...)\n    {{dir}}/<run>/000010-search/           an output with several parts: part-1.txt, part-2.png, result.json\n    {{dir}}/<run>/000011-sql.input.json    an input too large for the index line\n    *.part                                 an output cut at the size limit (\"truncated\": true)\n\nIndex fields: seq, call_id, tool, status (ok, error, cancelled, incomplete, retry), error, started_at, duration_ms,\ninput (or input_path), output_path (relative to the run directory), content_type, bytes, truncated.\n\nRead the index with `fromjson?` so a partially written line is skipped:\n\n    cat {{dir}}/*/index.jsonl | jq -cR 'fromjson? // empty'\n    cat {{dir}}/*/index.jsonl | jq -cR 'fromjson? // empty | select(.call_id == \"toolu_...\")'\n    cat {{dir}}/*/index.jsonl | jq -cR 'fromjson? // empty | select(.tool == \"web_search\") | \"\\(.run)/\\(.output_path)\"'\n\nIn Python:\n\n    import json, pathlib\n\n    def calls(root=\"{{dir}}\"):\n        for index in sorted(pathlib.Path(root).glob(\"*/index.jsonl\")):\n            for line in index.read_text().splitlines():\n                try:\n                    yield json.loads(line)\n                except ValueError:\n                    pass  # a partially written line\n";
+/** The paragraph promptHint() returns (never injected into a prompt by the SDK). */
+export const PROMPT_HINT = "Every tool call you make is also saved as files in this workspace. {{run_dir}}/index.jsonl has one JSON line per call (call_id, tool, status, input, output_path), and the full output of each call is at {{run_dir}}/<output_path>. Earlier runs are in the other directories under {{dir}}, described in {{dir}}/README.md. To analyse or transform a tool result with code, read it from these files (for example with jq or Python) rather than copying it from the conversation.\n";
+/** Fills {{dir}} and {{run_dir}}. */
+export function fillTemplate(text, vars) {
+    return text.replaceAll("{{run_dir}}", vars.run_dir).replaceAll("{{dir}}", vars.dir);
+}