@qvac/harness 0.4.0 → 0.6.0

package/dist-lib/lib/helpers/run-outcome.d.ts

@@ -9,6 +9,10 @@ export interface RunOutcomeFacts {
     readonly latestFailure: string | null;
     readonly confirmedWrites: ReadonlyArray<string>;
 }
+export interface HistoryTurn {
+    readonly role: string;
+    readonly content: string;
+}
 export interface RunOutcomeTracker {
     readonly confirmedWrites: string[];
     beginRound(): void;
@@ -20,14 +24,8 @@ export interface RunOutcomeTracker {
 export declare function createRunOutcomeTracker(): RunOutcomeTracker;
 export declare function normalizeToolExecutionOutcome(result: unknown, outcome: ToolExecutionOutcome): ToolExecutionOutcome;
 export declare function failureFromToolExecution(result: unknown, outcome: ToolExecutionOutcome): string | null;
-export declare function degenerateAnswer(outcome: Exclude<RunOutcome, 'answered'>, history: ReadonlyArray<{
-    role: string;
-    content: string;
-}>, facts?: RunOutcomeFacts): string;
-export declare function lastFailedToolAnswer(history: ReadonlyArray<{
-    role: string;
-    content: string;
-}>): string | null;
+export declare function degenerateAnswer(outcome: Exclude<RunOutcome, 'answered'>, history: ReadonlyArray<HistoryTurn>, facts?: RunOutcomeFacts): string;
+export declare function lastFailedToolAnswer(history: ReadonlyArray<HistoryTurn>): string | null;
 export declare function writeResult(output: unknown): string | null;
 export declare function unnamedWrites(answer: string, landed: ReadonlyArray<string>): ReadonlyArray<string>;
 export declare function writeReport(landed: ReadonlyArray<string>): string | null;

package/dist-lib/lib/helpers/run-outcome.js

@@ -1,4 +1,5 @@
 import { TOOL_CONTINUATION_NUDGE } from '../capabilities/tool-turns.js';
+import { isRecord } from '../guards.js';
 export const DEGENERATE_ANSWER_FALLBACK = "I couldn't complete that step and don't have a useful result to share.";
 export const ROUND_CAP_ANSWER = "I ran out of steps before I could finish that. Ask me to continue and I'll pick up where I left off.";
 export const SEARCH_CAPPED_ANSWER = "I searched the web but couldn't find the answer in the results I got.";
@@ -26,8 +27,9 @@ export function createRunOutcomeTracker() {
         record(result, outcome) {
             hasRoundResult = true;
             const failure = failureFromToolExecution(result, outcome);
-            if (failure)
+            if (failure) {
                 roundFailure = failure;
+            }
         },
         finishRound() {
             if (!hasRoundResult)
@@ -36,8 +38,9 @@ export function createRunOutcomeTracker() {
         },
         confirmWrite(result) {
             const write = writeResult(result);
-            if (write)
+            if (write) {
                 confirmedWrites.push(write);
+            }
         },
         facts() {
             return { latestFailure, confirmedWrites };
@@ -62,13 +65,15 @@ export function failureFromToolExecution(result, outcome) {
 export function degenerateAnswer(outcome, history, facts) {
     const rest = (facts ? facts.latestFailure : lastFailedToolAnswer(history)) ?? cappedAnswer(outcome, history);
     const written = writeReport(facts?.confirmedWrites ?? []);
-    if (written)
+    if (written) {
         return rest ? `${written}\n\n${rest}` : written;
+    }
     return rest ?? DEGENERATE_ANSWER_FALLBACK;
 }
 function cappedAnswer(outcome, history) {
-    if (outcome === 'search-capped')
+    if (outcome === 'search-capped') {
         return searchCappedAnswer(history);
+    }
     if (outcome === 'time-capped')
         return TIME_CAPPED_ANSWER;
     return outcome === 'exhausted' ? ROUND_CAP_ANSWER : null;
@@ -90,33 +95,40 @@ function searchCappedAnswer(history) {
                 continue;
             seen.add(url);
             lines.push(`- ${title.trim()}: ${url}`);
-            if (lines.length === MAX_CAPPED_SOURCES)
+            if (lines.length === MAX_CAPPED_SOURCES) {
                 break;
+            }
         }
     }
-    if (!lines.length)
+    if (!lines.length) {
         return SEARCH_CAPPED_ANSWER;
+    }
     return `${SEARCH_CAPPED_ANSWER} These pages looked most relevant:\n${lines.join('\n')}`;
 }
 export function lastFailedToolAnswer(history) {
     for (let i = history.length - 1; i >= 0; i--) {
         const turn = history[i];
-        if (turn?.role === 'user' && turn.content === TOOL_CONTINUATION_NUDGE)
+        if (turn?.role === 'user' && turn.content === TOOL_CONTINUATION_NUDGE) {
             continue;
-        if (turn?.role !== 'tool')
+        }
+        if (turn?.role !== 'tool') {
             return null;
+        }
         const failure = failureText(turn.content.replace(TOOL_RESULT_HEADER_RE, ''));
-        if (failure)
+        if (failure) {
             return failure;
+        }
     }
     return null;
 }
 export function writeResult(output) {
     const result = asRecord(output);
-    if (!result || typeof result.status !== 'number')
+    if (!result || typeof result.status !== 'number') {
         return null;
-    if (result.status >= 400 || nonEmpty(result.error))
+    }
+    if (result.status >= 400 || nonEmpty(result.error)) {
         return null;
+    }
     return nonEmpty(result.body);
 }
 export function unnamedWrites(answer, landed) {
@@ -139,8 +151,9 @@ export function writeReport(landed) {
     const share = Math.floor(MAX_SUCCESS_CHARS / listed.length);
     const lines = listed.map((write) => bound(write, share));
     const dropped = landed.length - listed.length;
-    if (dropped)
+    if (dropped) {
         lines.push(`(+${dropped} more)`);
+    }
     return `${WRITE_RESULT_LEAD}\n${lines.join('\n')}`;
 }
 function failureText(payload) {
@@ -149,17 +162,21 @@ function failureText(payload) {
 }
 function resultFailure(value) {
     const result = typeof value === 'string' ? parsed(value) : asRecord(value);
-    if (!result)
+    if (!result) {
         return null;
-    if (result.denied === true || result.guidance === true)
+    }
+    if (result.denied === true || result.guidance === true) {
         return null;
+    }
     const status = typeof result.status === 'number' ? result.status : null;
     const httpSuffix = status !== null && status >= 400 ? ` (HTTP ${status.toString()})` : '';
     const error = nonEmpty(result.error);
-    if (error)
+    if (error) {
         return `${bound(error, MAX_FAILURE_CHARS)}${httpSuffix}`;
-    if (status !== null && status >= 400)
+    }
+    if (status !== null && status >= 400) {
         return httpFailure(status, result.body);
+    }
     if (typeof result.exitCode === 'number' && result.exitCode !== 0) {
         const output = nonEmpty(result.stderr) ?? nonEmpty(result.stdout);
         return output ? bound(output, MAX_FAILURE_CHARS) : null;
@@ -174,8 +191,9 @@ function httpFailure(status, body) {
 }
 function apiMessage(body) {
     const value = typeof body === 'string' ? parsed(body) : asRecord(body);
-    if (!value)
+    if (!value) {
         return null;
+    }
     const error = value.error;
     const fromError = typeof error === 'string' ? nonEmpty(error) : nonEmpty(asRecord(error)?.['message']);
     return fromError ?? nonEmpty(value.message);
@@ -189,9 +207,7 @@ function parsed(payload) {
     }
 }
 function asRecord(value) {
-    return value && typeof value === 'object' && !Array.isArray(value)
-        ? value
-        : null;
+    return isRecord(value) && !Array.isArray(value) ? value : null;
 }
 function nonEmpty(value) {
     if (typeof value !== 'string')

package/dist-lib/lib/helpers/spawn-path.js

@@ -5,8 +5,9 @@ export function withHomebrewPath(path, platformName) {
     const dirs = (path ?? '').split(':').filter(Boolean);
     const seen = new Set(dirs);
     const missing = HOMEBREW_BIN_DIRS.filter((dir) => !seen.has(dir));
-    if (missing.length === 0)
+    if (missing.length === 0) {
         return path;
+    }
     return [...dirs, ...missing].join(':');
 }
 export const EXEC_ENV_ALLOWLIST = [
@@ -44,12 +45,14 @@ export function execEnv(env, platformName) {
     const keys = [...EXEC_ENV_ALLOWLIST, ...(PLATFORM_EXEC_ENV_ALLOWLIST[platformName] ?? [])];
     for (const key of keys) {
         const value = env[key];
-        if (value !== undefined)
+        if (value !== undefined) {
             out[key] = value;
+        }
     }
     const path = withHomebrewPath(out.PATH ?? env.Path, platformName);
-    if (path !== undefined)
+    if (path !== undefined) {
         out.PATH = path;
+    }
     return out;
 }
 export function spawnEnv(env, platformName, overrides) {

package/dist-lib/lib/helpers/text-coalescer.js

@@ -10,23 +10,26 @@ export class TextCoalescer {
         this._holdMs = holdMs;
     }
     async add(type, text) {
-        if (this._buffered && this._buffered.type !== type)
+        if (this._buffered && this._buffered.type !== type) {
             await this.flush();
+        }
         if (!this._buffered) {
             this._buffered = { type, text: '' };
             this._hold = setTimeout(() => void this.flush(), this._holdMs);
         }
         this._buffered.text += text;
-        if (this._buffered.text.length >= this._cap)
+        if (this._buffered.text.length >= this._cap) {
             await this.flush();
+        }
     }
     flush() {
         if (this._hold) {
             clearTimeout(this._hold);
             this._hold = null;
         }
-        if (!this._buffered)
+        if (!this._buffered) {
             return Promise.resolve();
+        }
         const { type, text } = this._buffered;
         this._buffered = null;
         return this._write(type, text);

package/dist-lib/lib/helpers/thinking.js

@@ -10,6 +10,20 @@ function findEarliest(buffer, tags) {
     const found = firstMarker(buffer, tags);
     return found === null ? null : { idx: found.index, len: found.marker.length };
 }
+function nextTag(buffer, inThink) {
+    const open = findEarliest(buffer, OPEN_TAGS);
+    const close = findEarliest(buffer, CLOSE_TAGS);
+    if (inThink) {
+        if (open && (!close || open.idx < close.idx)) {
+            return { ...open, inThink: true };
+        }
+        return close && { ...close, inThink: false };
+    }
+    if (close && (!open || close.idx < open.idx)) {
+        return { ...close, inThink: false };
+    }
+    return open && { ...open, inThink: true };
+}
 export async function* splitThinking(tokens, opts) {
     let buffer = '';
     let inThink = opts?.startInThink === true;
@@ -20,75 +34,54 @@ export async function* splitThinking(tokens, opts) {
     };
     const emit = (type, text) => {
         const shown = guards[type].push(text);
-        if (!shown)
+        if (!shown) {
             return null;
-        if (type === 'thinking' && unproven !== null)
+        }
+        if (type === 'thinking' && unproven !== null) {
             unproven += shown;
+        }
         return { type, text: shown };
     };
     for await (const token of tokens) {
         buffer += token;
         while (true) {
-            if (inThink) {
-                const open = findEarliest(buffer, OPEN_TAGS);
-                const close = findEarliest(buffer, CLOSE_TAGS);
-                if (open && (!close || open.idx < close.idx)) {
-                    const event = emit('thinking', buffer.slice(0, open.idx));
-                    if (event)
-                        yield event;
-                    guards.thinking.cut();
-                    buffer = buffer.slice(open.idx + open.len);
-                    continue;
-                }
-                if (!close)
-                    break;
-                const event = emit('thinking', buffer.slice(0, close.idx));
-                if (event)
-                    yield event;
-                guards.thinking.cut();
-                buffer = buffer.slice(close.idx + close.len);
-                inThink = false;
-                unproven = null;
-                continue;
+            const tag = nextTag(buffer, inThink);
+            if (!tag) {
+                break;
             }
-            const open = findEarliest(buffer, OPEN_TAGS);
-            const close = findEarliest(buffer, CLOSE_TAGS);
-            if (close && (!open || close.idx < open.idx)) {
-                const event = emit('content', buffer.slice(0, close.idx));
-                if (event)
-                    yield event;
-                guards.content.cut();
-                buffer = buffer.slice(close.idx + close.len);
-                continue;
+            const type = inThink ? 'thinking' : 'content';
+            const event = emit(type, buffer.slice(0, tag.idx));
+            if (event) {
+                yield event;
             }
-            if (open) {
-                const event = emit('content', buffer.slice(0, open.idx));
-                if (event)
-                    yield event;
-                guards.content.cut();
-                buffer = buffer.slice(open.idx + open.len);
-                inThink = true;
-                continue;
+            guards[type].cut();
+            buffer = buffer.slice(tag.idx + tag.len);
+            if (inThink && !tag.inThink) {
+                unproven = null;
             }
-            break;
+            inThink = tag.inThink;
         }
         const held = holdback(buffer, inThink ? CLOSE_TAGS : ALL_TAGS);
         if (buffer.length > held) {
             const event = emit(inThink ? 'thinking' : 'content', buffer.slice(0, buffer.length - held));
-            if (event)
+            if (event) {
                 yield event;
+            }
             buffer = buffer.slice(buffer.length - held);
         }
     }
     const last = emit(inThink ? 'thinking' : 'content', buffer);
-    if (last)
+    if (last) {
         yield last;
+    }
     for (const type of ['thinking', 'content']) {
         const rest = guards[type].flush();
-        if (!rest)
+        if (!rest) {
             continue;
-        if (type === 'thinking' && unproven !== null)
+        }
+        if (type === 'thinking' && unproven !== null) {
             unproven += rest;
+        }
         yield { type, text: rest };
     }
     return unproven;

package/dist-lib/lib/helpers/tool-call-markup.d.ts

@@ -6,15 +6,17 @@ export interface RecoveredToolCall {
 }
 export declare const MAX_RAW_CALL_CHARS = 4096;
 export declare function clipRawCall(raw: string): string;
-export declare function recoverMarkupToolCalls(text: string, knownTools: ReadonlyArray<{
-    name: string;
-}>): RecoveredToolCall[];
+export interface KnownTool {
+    readonly name: string;
+}
+export declare function recoverMarkupToolCalls(text: string, knownTools: ReadonlyArray<KnownTool>): RecoveredToolCall[];
 export declare function stripToolCallMarkup(text: string): string;
 export declare function stripToolResponseBlocks(text: string): string;
-export declare function toolCallMarkup(calls: ReadonlyArray<{
-    name: string;
-    arguments?: Record<string, unknown>;
-}>): string;
+export interface MarkupToolCall {
+    readonly name: string;
+    readonly arguments?: Record<string, unknown>;
+}
+export declare function toolCallMarkup(calls: ReadonlyArray<MarkupToolCall>): string;
 export declare function normalizeToolArgs(args: Record<string, unknown>, declaredKeys: ReadonlyArray<string>): Record<string, unknown>;
 export declare function recoverSkillNamedCall(text: string, skillNames: ReadonlyArray<string>, skillToolName: string): RecoveredToolCall[];
 export declare function recoverPrintedSkillLoad(text: string, skillToolName: string): RecoveredToolCall[];

package/dist-lib/lib/helpers/tool-call-markup.js

@@ -1,3 +1,4 @@
+import { isRecord } from '../guards.js';
 const FUNCTION_OPEN = '<function=';
 const FUNCTION_CLOSE = '</function>';
 const TOOL_RESPONSE = { open: '<tool_response>', close: '</tool_response>' };
@@ -9,17 +10,20 @@ function* markupBlocks(text, open, close) {
     let cursor = 0;
     for (;;) {
         const start = text.indexOf(open, cursor);
-        if (start === -1)
+        if (start === -1) {
             return;
+        }
         const nameStart = start + open.length;
         cursor = nameStart;
         const name = nameOf(text, nameStart);
-        if (name === null)
+        if (name === null) {
             continue;
+        }
         const bodyStart = nameStart + name.length + 1;
         const bodyEnd = text.indexOf(close, bodyStart);
-        if (bodyEnd === -1)
+        if (bodyEnd === -1) {
             return;
+        }
         yield {
             name: name.trim(),
             body: text.slice(bodyStart, bodyEnd),
@@ -32,8 +36,9 @@ function* markupBlocks(text, open, close) {
 function nameOf(text, nameStart) {
     const window = text.slice(nameStart, nameStart + MAX_NAME_LENGTH + 1);
     const nameEnd = window.indexOf('>');
-    if (nameEnd === -1)
+    if (nameEnd === -1) {
         return null;
+    }
     const name = window.slice(0, nameEnd);
     return name.includes('\n') ? null : name;
 }
@@ -78,12 +83,14 @@ function stripSpans(text, span) {
     let cursor = 0;
     for (;;) {
         const start = hay.indexOf(span.open, cursor);
-        if (start === -1)
+        if (start === -1) {
             break;
+        }
         out += text.slice(cursor, start);
         const end = hay.indexOf(span.close, start + span.open.length);
-        if (end === -1)
+        if (end === -1) {
             return out;
+        }
         cursor = end + span.close.length;
     }
     return out + text.slice(cursor);
@@ -98,11 +105,13 @@ function danglingIndex(text) {
     let cursor = 0;
     for (;;) {
         const start = text.indexOf(FUNCTION_OPEN, cursor);
-        if (start === -1)
+        if (start === -1) {
             return -1;
+        }
         const nameStart = start + FUNCTION_OPEN.length;
-        if (nameOf(text, nameStart) !== null)
+        if (nameOf(text, nameStart) !== null) {
             return start;
+        }
         cursor = nameStart;
     }
 }
@@ -119,24 +128,27 @@ function encodeMarkupValue(value) {
     return JSON.stringify(value ?? null).replace(/</g, '\\u003c');
 }
 const ARG_WRAPPER_KEYS = new Set(['parameters', 'arguments', 'args', 'input', 'params']);
-function isRecord(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
+function isPlainObject(value) {
+    return isRecord(value) && !Array.isArray(value);
 }
 export function normalizeToolArgs(args, declaredKeys) {
-    const keys = Object.keys(args);
-    if (keys.length !== 1)
+    const [only, ...rest] = Object.keys(args);
+    if (only === undefined || rest.length) {
         return args;
-    const only = keys[0];
-    if (!ARG_WRAPPER_KEYS.has(only) || declaredKeys.includes(only))
+    }
+    if (!ARG_WRAPPER_KEYS.has(only) || declaredKeys.includes(only)) {
         return args;
+    }
     const inner = args[only];
-    if (isRecord(inner))
+    if (isPlainObject(inner)) {
         return inner;
+    }
     if (typeof inner === 'string') {
         try {
             const parsed = JSON.parse(inner);
-            if (isRecord(parsed))
+            if (isPlainObject(parsed)) {
                 return parsed;
+            }
         }
         catch {
             return args;
@@ -185,17 +197,21 @@ export function recoverPrintedSkillLoad(text, skillToolName) {
         catch {
             continue;
         }
-        if (!isRecord(candidate))
+        if (!isPlainObject(candidate)) {
             continue;
+        }
         const keys = Object.keys(candidate);
-        if (keys.length === 0 || !keys.every((key) => SKILL_LOAD_KEYS.has(key)))
+        if (keys.length === 0 || !keys.every((key) => SKILL_LOAD_KEYS.has(key))) {
             continue;
+        }
         const name = candidate.name ?? candidate.skill ?? candidate.skill_name;
         const file = candidate.file ?? candidate.path ?? candidate.filename;
-        if (typeof name !== 'string' || typeof file !== 'string')
+        if (typeof name !== 'string' || typeof file !== 'string') {
             continue;
-        if (!/\.(md|py)\s*$/i.test(file.replaceAll('"', '').trim()))
+        }
+        if (!/\.(md|py)\s*$/i.test(file.replaceAll('"', '').trim())) {
             continue;
+        }
         return [
             {
                 id: 'recovered-printed-skill-load',

package/dist-lib/lib/helpers/tool-intent.d.ts

@@ -1,7 +1,8 @@
 export declare const INTENT_PARAM = "intent";
 export declare const INTENT_PARAM_DESCRIPTION: string;
 export declare function sanitizeToolIntent(value: unknown): string | undefined;
-export declare function takeToolIntent(args: Record<string, unknown>): {
+export interface TakenToolIntent {
     args: Record<string, unknown>;
     intent?: string;
-};
+}
+export declare function takeToolIntent(args: Record<string, unknown>): TakenToolIntent;

package/dist-lib/lib/helpers/tool-intent.js

@@ -8,13 +8,15 @@ export function sanitizeToolIntent(value) {
     if (typeof value !== 'string')
         return undefined;
     const collapsed = stripControlTokens(value).replace(/\s+/g, ' ').trim();
-    if (!collapsed)
+    if (!collapsed) {
         return undefined;
+    }
     return collapsed.length > MAX_INTENT_LENGTH ? collapsed.slice(0, MAX_INTENT_LENGTH) : collapsed;
 }
 export function takeToolIntent(args) {
-    if (!(INTENT_PARAM in args))
+    if (!(INTENT_PARAM in args)) {
         return { args };
+    }
     const { [INTENT_PARAM]: raw, ...rest } = args;
     const intent = sanitizeToolIntent(raw);
     return intent === undefined ? { args: rest } : { args: rest, intent };

package/dist-lib/lib/helpers/tool-label.js

@@ -33,29 +33,33 @@ function normalizeModelLabel(raw) {
         .split(/\r?\n/)
         .map((line) => line.trim())
         .find(Boolean);
-    if (!firstLine)
+    if (!firstLine) {
         return null;
+    }
     const unlabeled = firstLine.replace(/^label\s*[:\-–]\s*/i, '');
     const unquoted = unwrap(unlabeled)
         .replace(/^["'`]+|["'`]+$/g, '')
         .trim();
     const words = unquoted.split(/\s+/).filter(Boolean).slice(0, MAX_LABEL_WORDS);
-    if (words.length === 0)
+    if (words.length === 0) {
         return null;
+    }
     const label = words
         .join(' ')
         .replace(/[.,;:!?]+$/, '')
         .trim()
         .slice(0, MAX_LABEL_LENGTH)
         .trim();
-    if (!label || ECHOED_INSTRUCTION.test(label))
+    if (!label || ECHOED_INSTRUCTION.test(label)) {
         return null;
+    }
     return label;
 }
 export function skillCallLabel(args) {
     const name = stringArg(args, 'name') || stringArg(args, 'skill_name') || stringArg(args, 'skill');
-    if (!name)
+    if (!name) {
         return 'Load skill instructions';
+    }
     const title = titleSkillName(name);
     const file = stringArg(args, 'file');
     return file ? `Read ${title}/${fileName(file)}` : `Load ${title}`;
@@ -65,8 +69,9 @@ export function isSkillTool(name) {
 }
 function stringArg(args, key) {
     const value = args[key];
-    if (typeof value !== 'string')
+    if (typeof value !== 'string') {
         return '';
+    }
     return unquoteArg(value).trim();
 }
 function fileName(path) {
@@ -82,8 +87,9 @@ function titleSkillName(name) {
 }
 function normalizeModelDescription(raw) {
     const text = stripControlTokens(raw).replace(/\s+/g, ' ').trim();
-    if (!text || ECHOED_INSTRUCTION.test(text))
+    if (!text || ECHOED_INSTRUCTION.test(text)) {
         return undefined;
+    }
     return text.length > MAX_DESCRIPTION_LENGTH
         ? `${text.slice(0, MAX_DESCRIPTION_LENGTH).trimEnd()}…`
         : text;
@@ -94,8 +100,9 @@ export function parseToolLabelResponse(raw) {
         try {
             const parsed = JSON.parse(trimmed);
             const label = typeof parsed.label === 'string' ? normalizeModelLabel(parsed.label) : null;
-            if (!label)
+            if (!label) {
                 return null;
+            }
             const description = typeof parsed.description === 'string'
                 ? normalizeModelDescription(parsed.description)
                 : undefined;
@@ -108,11 +115,13 @@ export function parseToolLabelResponse(raw) {
     return label ? { label } : null;
 }
 export function fallbackToolLabel(name, args = {}) {
-    if (isSkillTool(name))
+    if (isSkillTool(name)) {
         return skillCallLabel(args);
+    }
     const query = stringArg(args, 'query');
-    if (query)
+    if (query) {
         return `Search ${query}`.slice(0, MAX_LABEL_LENGTH).trim();
+    }
     const url = stringArg(args, 'url');
     if (url) {
         const method = stringArg(args, 'method').toUpperCase();