@inflexa-ai/harness 0.45.1 → 0.46.2

package/dist/literature/sources/semantic-scholar.js

@@ -7,8 +7,7 @@ import { z } from "zod";
 import { requestJson } from "./http.js";
 const BASE_URL = "https://api.semanticscholar.org/graph/v1";
 const FIELDS = "paperId,title,abstract,year,venue,citationCount,url,authors,externalIds";
-const WirePaperSchema = z
-    .object({
+const WirePaperSchema = z.looseObject({
     paperId: z.string().optional(),
     title: z.string().nullable().optional(),
     abstract: z.string().nullable().optional(),
@@ -23,8 +22,7 @@ const WirePaperSchema = z
         .record(z.string(), z.union([z.string(), z.number()]))
         .nullable()
         .optional(),
-})
-    .passthrough();
+});
 export const ExactPaperSchema = WirePaperSchema.extend({ paperId: z.string() });
 export const SearchResponseSchema = z.object({ data: z.array(WirePaperSchema).optional() });
 /** Give one text form to each external id, thus a numeric `CorpusId` reaches a caller that keys on a string. */
@@ -39,17 +37,25 @@ function mapPaper(raw) {
         return undefined;
     const authors = raw.authors?.flatMap((author) => (typeof author.name === "string" && author.name.trim() ? [author.name] : [])) ?? [];
     const externalIds = stringExternalIds(raw.externalIds);
-    return {
+    const paper = {
         id: raw.paperId,
-        ...(typeof raw.title === "string" ? { title: raw.title } : {}),
-        ...(typeof raw.abstract === "string" ? { abstract: raw.abstract } : {}),
-        ...(typeof raw.year === "number" ? { year: raw.year } : {}),
-        ...(typeof raw.venue === "string" ? { venue: raw.venue } : {}),
-        ...(typeof raw.citationCount === "number" ? { citationCount: raw.citationCount } : {}),
-        ...(typeof raw.url === "string" ? { url: raw.url } : {}),
         authors,
-        ...(externalIds === undefined ? {} : { externalIds }),
     };
+    if (typeof raw.title === "string")
+        paper.title = raw.title;
+    if (typeof raw.abstract === "string")
+        paper.abstract = raw.abstract;
+    if (typeof raw.year === "number")
+        paper.year = raw.year;
+    if (typeof raw.venue === "string")
+        paper.venue = raw.venue;
+    if (typeof raw.citationCount === "number")
+        paper.citationCount = raw.citationCount;
+    if (typeof raw.url === "string")
+        paper.url = raw.url;
+    if (externalIds !== undefined)
+        paper.externalIds = externalIds;
+    return paper;
 }
 export function parseSemanticScholarResponse(raw) {
     const parsed = SearchResponseSchema.safeParse(raw);
@@ -57,7 +63,10 @@ export function parseSemanticScholarResponse(raw) {
         return [];
     return (parsed.data.data ?? []).flatMap((paper) => {
         const mapped = mapPaper(paper);
-        return mapped?.title === undefined ? [] : [mapped];
+        if (mapped === undefined || mapped.title === undefined)
+            return [];
+        const { title } = mapped;
+        return [{ ...mapped, title }];
     });
 }
 export function createSemanticScholarSource(options = {}) {

package/dist/loop/accounting.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The accounting of each model call: the token counters and the usage record.
+ *
+ * The middleware runs inside the durable step of the call, below the step and
+ * above the retry envelope. Thus it sees the stream of the attempt that answered,
+ * and a replay of a recorded step does not run it again. The usage record and
+ * the counters therefore count each call one time.
+ */
+import type { LanguageModelMiddleware } from "ai";
+import type { LanguageModelV4Usage } from "@ai-sdk/provider";
+import type { AgentSession } from "../auth/types.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
+import type { Logger } from "../lib/logger.js";
+import type { ChatUsage } from "../providers/types.js";
+import { type AgentRunUsage } from "./metrics.js";
+/** What one completed model call is accounted under. */
+export type CallAccounting = {
+    readonly session: AgentSession;
+    /** The id that the counters and the record name, which is not always the id of the agent. */
+    readonly agentId: string;
+    /** The id of the tool call that runs the loop, when the loop runs inside a tool call. */
+    readonly invocationId?: string;
+    readonly usageRecorder: UsageRecorder;
+    /** The sink that the notice helper logs the reason of a recorder `err` to. */
+    readonly logger: Logger;
+};
+/**
+ * Idempotency key for one call's usage record, and for the kept text of one cut
+ * tool result: `{runId}[:{stepId}]:{callPath}[:{invocationId}]:{callKey}`. A
+ * workflow with no `RunFrame`, a chat turn, puts its own workflow id in place of
+ * the run and the step.
+ *
+ * Each component is a fact the same call carries again on every rerun:
+ *
+ * - `stepId` — `executeAnalysis` runs one child workflow per step under a
+ *   single shared `runId`.
+ * - `callPath` — several loops run under one frame: a step agent and its
+ *   follow-up requests, and the run synthesis and the sub-agents of its tools.
+ * - `invocationId` — the same sub-agent dispatched twice in one round has an
+ *   identical call path, so only the dispatching tool-call id tells the two
+ *   child loops apart. Each data profile runs under the same constant frame,
+ *   thus the workflow id of its attempt takes this place.
+ * - `callKey` — the id of the model response, or the id of the tool call. A
+ *   recorded step gives the same id on a replay.
+ *
+ * Outside a workflow there is no replay to be safe against, so a fresh id is
+ * enough and is what keeps two calls in one turn distinct.
+ */
+export declare function recordKeyFor(session: AgentSession, invocationId: string | undefined, callKey: string): string;
+/** The usage of one call in the names of the harness. An unreported figure stays absent. */
+export declare function chatUsageOf(usage: LanguageModelV4Usage): ChatUsage;
+/**
+ * Folds the usage of each model call into the rollups of the run. It wraps the
+ * durable step of the call, thus a replayed call folds the usage of its
+ * checkpoint, and a reply whose tool calls an abort cut folds too.
+ */
+export declare function rollupMiddleware(rollups: readonly AgentRunUsage[]): LanguageModelMiddleware;
+/**
+ * The accounting of each model call of a run, as a model middleware. It reads
+ * the response id and the model id of the response metadata, and it accounts
+ * the call at the `finish` part.
+ */
+export declare function accountingMiddleware(call: CallAccounting): LanguageModelMiddleware;

package/dist/loop/accounting.js

@@ -0,0 +1,141 @@
+/**
+ * The accounting of each model call: the token counters and the usage record.
+ *
+ * The middleware runs inside the durable step of the call, below the step and
+ * above the retry envelope. Thus it sees the stream of the attempt that answered,
+ * and a replay of a recorded step does not run it again. The usage record and
+ * the counters therefore count each call one time.
+ */
+import { randomUUID } from "node:crypto";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { deliverNotice } from "../lib/hooks.js";
+import { fallbackModelOf } from "../providers/ai-sdk.js";
+import { addChatUsage, hasReportedUsage, recordChatCall } from "./metrics.js";
+/**
+ * Delimiter joining the call path into one key segment.
+ *
+ * Deliberately not the `:` that separates the key's segments, so a call path
+ * can never be read as one: agent ids are kebab-case identifiers, and none of
+ * the other segments can contain `>`.
+ */
+const CALL_PATH_DELIMITER = ">";
+/**
+ * Idempotency key for one call's usage record, and for the kept text of one cut
+ * tool result: `{runId}[:{stepId}]:{callPath}[:{invocationId}]:{callKey}`. A
+ * workflow with no `RunFrame`, a chat turn, puts its own workflow id in place of
+ * the run and the step.
+ *
+ * Each component is a fact the same call carries again on every rerun:
+ *
+ * - `stepId` — `executeAnalysis` runs one child workflow per step under a
+ *   single shared `runId`.
+ * - `callPath` — several loops run under one frame: a step agent and its
+ *   follow-up requests, and the run synthesis and the sub-agents of its tools.
+ * - `invocationId` — the same sub-agent dispatched twice in one round has an
+ *   identical call path, so only the dispatching tool-call id tells the two
+ *   child loops apart. Each data profile runs under the same constant frame,
+ *   thus the workflow id of its attempt takes this place.
+ * - `callKey` — the id of the model response, or the id of the tool call. A
+ *   recorded step gives the same id on a replay.
+ *
+ * Outside a workflow there is no replay to be safe against, so a fresh id is
+ * enough and is what keeps two calls in one turn distinct.
+ */
+export function recordKeyFor(session, invocationId, callKey) {
+    const frame = session.runFrame;
+    const workflowId = DBOS.workflowID;
+    if (frame === undefined && workflowId === undefined)
+        return randomUUID();
+    const scope = frame === undefined ? [workflowId] : [frame.runId, ...(frame.stepId === undefined ? [] : [frame.stepId])];
+    return [...scope, session.provenance.callPath.join(CALL_PATH_DELIMITER), ...(invocationId === undefined ? [] : [invocationId]), callKey].join(":");
+}
+/** The usage of one call in the names of the harness. An unreported figure stays absent. */
+export function chatUsageOf(usage) {
+    return {
+        inputTokens: usage.inputTokens.total,
+        outputTokens: usage.outputTokens.total,
+        cacheCreationInputTokens: usage.inputTokens.cacheWrite,
+        cacheReadInputTokens: usage.inputTokens.cacheRead,
+        reasoningTokens: usage.outputTokens.reasoning,
+    };
+}
+/** Count one completed call, and send its usage record. */
+function account(call, facts) {
+    recordChatCall({ agentId: call.agentId, usage: facts.usage, servedModelId: facts.servedModelId, provider: facts.provider });
+    if (!hasReportedUsage(facts.usage))
+        return;
+    const { session } = call;
+    const record = {
+        recordKey: recordKeyFor(session, call.invocationId, facts.responseId ?? randomUUID()),
+        agentId: call.agentId,
+        callPath: session.provenance.callPath,
+        scope: session.scope,
+        usage: facts.usage,
+        requestedModelId: facts.requestedModelId,
+    };
+    if (session.runFrame?.runId !== undefined)
+        record.runId = session.runFrame.runId;
+    if (session.runFrame?.stepId !== undefined)
+        record.stepId = session.runFrame.stepId;
+    if (facts.servedModelId !== undefined)
+        record.servedModelId = facts.servedModelId;
+    void deliverNotice(call.logger, "UsageRecorder.record", call.usageRecorder.record(record));
+}
+/**
+ * Folds the usage of each model call into the rollups of the run. It wraps the
+ * durable step of the call, thus a replayed call folds the usage of its
+ * checkpoint, and a reply whose tool calls an abort cut folds too.
+ */
+export function rollupMiddleware(rollups) {
+    return {
+        specificationVersion: "v4",
+        wrapStream: async ({ doStream }) => {
+            const { stream, ...rest } = await doStream();
+            const observed = stream.pipeThrough(new TransformStream({
+                transform(part, controller) {
+                    if (part.type === "finish")
+                        for (const rollup of rollups)
+                            addChatUsage(rollup, chatUsageOf(part.usage));
+                    controller.enqueue(part);
+                },
+            }));
+            return { ...rest, stream: observed };
+        },
+    };
+}
+/**
+ * The accounting of each model call of a run, as a model middleware. It reads
+ * the response id and the model id of the response metadata, and it accounts
+ * the call at the `finish` part.
+ */
+export function accountingMiddleware(call) {
+    return {
+        specificationVersion: "v4",
+        wrapStream: async ({ doStream, model }) => {
+            const { stream, ...rest } = await doStream();
+            let responseId;
+            let servedModelId;
+            const observed = stream.pipeThrough(new TransformStream({
+                transform(part, controller) {
+                    if (part.type === "response-metadata") {
+                        responseId = part.id ?? responseId;
+                        servedModelId = part.modelId ?? servedModelId;
+                    }
+                    else if (part.type === "finish") {
+                        // A fallback hop names the model that answered, and the metadata keeps the requested one.
+                        const servedBy = fallbackModelOf(part.providerMetadata);
+                        account(call, {
+                            usage: chatUsageOf(part.usage),
+                            responseId,
+                            provider: model.provider,
+                            requestedModelId: model.modelId,
+                            servedModelId: servedBy === undefined || servedBy === "" ? servedModelId : servedBy,
+                        });
+                    }
+                    controller.enqueue(part);
+                },
+            }));
+            return { ...rest, stream: observed };
+        },
+    };
+}

package/dist/loop/call-policy.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The policy that refuses a tool call before it runs: the mask of a request,
+ * the budget of a run, and the guard against repeated calls.
+ *
+ * A signed thinking block is bound to the exact prefix of its request, so a
+ * request always declares the full tool set of its agent. The policy acts at
+ * the approval of each call instead. A refused call gets a result that gives
+ * the reason, and the run continues.
+ *
+ * The policy reads only the calls of the run, in the order that they arrive.
+ * A replay sees the same calls in the same order, thus it refuses the same calls.
+ */
+/** An absent mask lets each declared tool run. */
+export type ToolMask = "none" | {
+    readonly allow: readonly string[];
+};
+/** A tool with no entry has no limit. */
+export type ToolBudget = Readonly<Record<string, number>>;
+export type CallGuardPolicy = {
+    /** The calls with one identical input that a run may make to one tool. The next one is refused. */
+    readonly identicalLimit: number;
+    /** The calls, with any input, that a run may make to one tool. The next one is refused. */
+    readonly perToolLimit: number;
+    /** The calls, with any input, that a run may make across every guarded tool. The next one is refused by every tool. */
+    readonly totalLimit: number;
+};
+/**
+ * Two identical calls let a model confirm an answer once. Twelve calls of one
+ * tool is above the largest count a frontier planner made in the Phase 0
+ * campaign (six and a half calls per plan across ALL tools) and far below the
+ * two hundred that a looping planner reached. Forty calls across every tool
+ * bounds the round over the tools that stays under each per-tool budget: in
+ * the 32-task campaign every submitted Sonnet plan but two needed fewer, and
+ * the one plan that ran to the wall clock made 62.
+ */
+export declare const DEFAULT_CALL_GUARD: CallGuardPolicy;
+export type GuardedCallRefusal = {
+    readonly tool: string;
+    readonly kind: "identical" | "budget" | "total";
+    readonly calls: number;
+};
+/**
+ * The guard against repeated calls of a set of tools. A model that treats a
+ * tool answer as a state to poll calls the same tool with the same input again
+ * and again, or drifts through one query after another, until the step cap or
+ * the wall clock ends the run. A frontier model reads an "unavailable" answer
+ * once and continues; a smaller model does not.
+ */
+export type CallGuard = {
+    readonly tools: readonly string[];
+    readonly policy?: CallGuardPolicy;
+    /** Called on each refusal of the guard, for the log of the host and for a cap of the run. */
+    readonly onRefusal?: (refusal: GuardedCallRefusal) => void;
+};
+export type CallPolicy = {
+    /** The tools that can run for each request of the task. A follow-up request gives its own mask. */
+    readonly mask?: ToolMask;
+    readonly budget?: ToolBudget;
+    readonly guard?: CallGuard;
+};
+/** The counters of one conversation. */
+export type CallPolicyState = {
+    /** The refusal text of a call, or `undefined` for a call that runs. A call that runs counts against each limit. */
+    refusalOf(call: {
+        readonly toolName: string;
+        readonly input: unknown;
+    }, mask: ToolMask | undefined): string | undefined;
+};
+/** A stable key for one input: the JSON text with the object keys sorted at every depth. */
+export declare function canonicalInputKey(input: unknown): string;
+/** The mask that lets each tool run except the named ones. */
+export declare function maskExcept(toolIds: readonly string[], ids: readonly string[]): ToolMask;
+export declare function createCallPolicy(policy: CallPolicy): CallPolicyState;

package/dist/loop/call-policy.js

@@ -0,0 +1,109 @@
+/**
+ * The policy that refuses a tool call before it runs: the mask of a request,
+ * the budget of a run, and the guard against repeated calls.
+ *
+ * A signed thinking block is bound to the exact prefix of its request, so a
+ * request always declares the full tool set of its agent. The policy acts at
+ * the approval of each call instead. A refused call gets a result that gives
+ * the reason, and the run continues.
+ *
+ * The policy reads only the calls of the run, in the order that they arrive.
+ * A replay sees the same calls in the same order, thus it refuses the same calls.
+ */
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
+/**
+ * Two identical calls let a model confirm an answer once. Twelve calls of one
+ * tool is above the largest count a frontier planner made in the Phase 0
+ * campaign (six and a half calls per plan across ALL tools) and far below the
+ * two hundred that a looping planner reached. Forty calls across every tool
+ * bounds the round over the tools that stays under each per-tool budget: in
+ * the 32-task campaign every submitted Sonnet plan but two needed fewer, and
+ * the one plan that ran to the wall clock made 62.
+ */
+export const DEFAULT_CALL_GUARD = { identicalLimit: 2, perToolLimit: 12, totalLimit: 40 };
+/** A stable key for one input: the JSON text with the object keys sorted at every depth. */
+export function canonicalInputKey(input) {
+    return JSON.stringify(sortKeys(input));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    const record = parseUnknownRecord(value);
+    if (record !== undefined) {
+        const out = {};
+        for (const key of Object.keys(record).sort())
+            out[key] = sortKeys(record[key]);
+        return out;
+    }
+    return value;
+}
+/** Matches the `{ error, retryable }` shape of every other tool error. */
+function refusal(error) {
+    return JSON.stringify({ error, retryable: false });
+}
+function maskRefusal(mask, toolName) {
+    if (mask === "none")
+        return refusal(`No tool can run for this request, thus ${toolName} did not run. Answer in text.`);
+    if (mask.allow.includes(toolName))
+        return undefined;
+    const available = mask.allow.length === 0 ? "none" : mask.allow.join(", ");
+    return refusal(`The tool ${toolName} is not available for this request, thus it did not run. The tools that can run now: ${available}.`);
+}
+/** The mask that lets each tool run except the named ones. */
+export function maskExcept(toolIds, ids) {
+    return { allow: toolIds.filter((id) => !ids.includes(id)) };
+}
+export function createCallPolicy(policy) {
+    const used = new Map();
+    const guard = policy.guard;
+    const limits = guard?.policy ?? DEFAULT_CALL_GUARD;
+    const guarded = new Set(guard?.tools ?? []);
+    const guardCalls = new Map();
+    const byInput = new Map();
+    let guardTotal = 0;
+    const guardRefusal = (toolName, input) => {
+        if (!guarded.has(toolName))
+            return undefined;
+        const calls = (guardCalls.get(toolName) ?? 0) + 1;
+        guardCalls.set(toolName, calls);
+        const key = `${toolName}:${canonicalInputKey(input)}`;
+        const identical = (byInput.get(key) ?? 0) + 1;
+        byInput.set(key, identical);
+        if (identical > limits.identicalLimit) {
+            guard?.onRefusal?.({ tool: toolName, kind: "identical", calls: identical });
+            return refusal(`This run already called ${toolName} with this exact input ${identical - 1} times, and the answer does not change within a run. ` +
+                "Use the answer you have and continue. If the answer was that a resource is absent, plan without it or ask for it; do not search again.");
+        }
+        guardTotal += 1;
+        if (guardTotal > limits.totalLimit) {
+            guard?.onRefusal?.({ tool: toolName, kind: "total", calls: guardTotal });
+            return refusal(`This run made ${limits.totalLimit} calls across its search tools, which is the search budget of one run. ` +
+                "Submit the plan you have now. If a required resource is absent, ask for it; do not search again.");
+        }
+        if (calls > limits.perToolLimit) {
+            guard?.onRefusal?.({ tool: toolName, kind: "budget", calls });
+            return refusal(`This run made ${limits.perToolLimit} calls of ${toolName}, which is the budget of one run for one tool. ` +
+                "Continue with what you have. If a required resource is absent, ask for it; do not search again.");
+        }
+        return undefined;
+    };
+    return {
+        refusalOf(call, mask) {
+            if (mask !== undefined) {
+                const refused = maskRefusal(mask, call.toolName);
+                if (refused !== undefined)
+                    return refused;
+            }
+            const limit = policy.budget?.[call.toolName];
+            const count = used.get(call.toolName) ?? 0;
+            if (limit !== undefined && count >= limit) {
+                return refusal(`The tool ${call.toolName} reached its limit of ${limit} calls in this run, thus this call did not run.`);
+            }
+            const guardRefused = guardRefusal(call.toolName, call.input);
+            if (guardRefused !== undefined)
+                return guardRefused;
+            used.set(call.toolName, count + 1);
+            return undefined;
+        },
+    };
+}

package/dist/loop/chat-stream.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The durable stream of a chat turn, and of each sub-agent of the turn.
+ *
+ * The turn writes to the stream of its workflow with the writer of
+ * `@dbos-inc/vercel-ai`: each model call writes its text from inside its step,
+ * and the harness writes each of its own frames as one `data-harness-frame`
+ * chunk. The reader converts the chunks to the `ChatFrame`s that a host gives
+ * its client. A model record also holds the input of each tool call, and the
+ * converter drops it, thus a client gets the frames of an in-process turn.
+ */
+import { type DurableStreamSource } from "@dbos-inc/vercel-ai";
+import type { UIMessageChunk, UIMessageStreamWriter } from "ai";
+import type { ChatFrame, EventSource } from "../contracts/chat-events.js";
+import type { EmitFn } from "./types.js";
+/** The key of the durable stream of a chat turn. */
+export declare const CHAT_STREAM_KEY = "chat";
+/** The data part that names the child workflow of a sub-agent call in the stream of its caller. */
+export declare const SUB_AGENT_STREAM_PART = "data-subagent-stream";
+/** The chunk that carries one frame of the harness in the stream of a turn. A transient chunk is live only. */
+export declare function chunkOfFrame(frame: ChatFrame, transient?: boolean): UIMessageChunk;
+/** What the body of a turn workflow writes to its stream, and what each of its tool steps writes. */
+export type TurnStreamWriter = {
+    /** The emit sink of the loop of the turn. */
+    readonly emit: EmitFn;
+    /** The writer that the tool steps of the turn give their chunks to, through the library. */
+    readonly toolWriter: UIMessageStreamWriter;
+    /** Write one frame from the body of the workflow. */
+    write(frame: ChatFrame): Promise<void>;
+    /** Wait for each write in flight. A failed write fails the call. */
+    settle(): Promise<void>;
+};
+/**
+ * The writer of the stream of a turn workflow. `observe` gets each frame of the turn that goes to the stream: the
+ * frames of the body, and the frames of each tool step, the frames that a replay of a step gives again included.
+ *
+ * From the body a write is checkpointed, thus a replay writes nothing again. From a step a write is at-least-once,
+ * and a fold of the frames by the id of a tool call or a part makes a second copy harmless.
+ */
+export declare function createTurnStreamWriter(rootSource: EventSource, observe: (frame: ChatFrame) => void): TurnStreamWriter;
+/**
+ * The frames of one chunk of the stream. The text of a model call is the text of the root agent, because a
+ * sub-agent writes to the stream of its own workflow. The end chunks of the library carry no fact of the turn,
+ * except the error and the abort of a workflow that ended before the turn wrote its own end.
+ */
+export declare function framesOfChunk(chunk: UIMessageChunk, rootSource: EventSource): ChatFrame[];
+export type ReadChatTurnOptions = {
+    /**
+     * The source of the root agent of the turn, which the text of each model call takes. Absent: the source of the
+     * first frame of the harness, which the turn writes before its first model call.
+     */
+    readonly rootSource?: EventSource;
+    /** A `DBOSClient` for a process that did not launch DBOS. Absent: the `DBOS` of this process. */
+    readonly client?: DurableStreamSource;
+};
+/**
+ * Read the frames of a turn from its start, live, until the turn ends. A second read gives the same frames.
+ *
+ * The read merges the stream of each sub-agent child that the turn names, in the order of arrival. A child stream
+ * gives only the frames of the harness: the child ends before its caller continues, and the result of its tool call
+ * tells its outcome. The end frame of the turn comes last.
+ */
+export declare function readChatTurn(turnId: string, options: ReadChatTurnOptions): AsyncGenerator<ChatFrame>;