@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/tools/ad-hoc-router.js

@@ -1,22 +1,24 @@
-import { jsonSchema, tool as aiTool } from "ai";
+import { errorMessageOf } from "../lib/thrown.js";
+import { textOf } from "../lib/unknown-text.js";
+import { ok } from "neverthrow";
 import { z } from "zod";
 import { PLANNABLE_AGENT_CATALOG } from "../agents/sandbox-catalog.js";
+import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
 import { forSubAgent } from "../auth/types.js";
 import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../app/data-profile-orientation.js";
-import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { createNoopLogger } from "../lib/console-logger.js";
-import { unwrapOrThrow } from "../lib/result.js";
-import { countChatTokens } from "../loop/metrics.js";
-import { accountForChatCall } from "../loop/run-agent.js";
+import { toThrowable, unwrapOrThrow } from "../lib/result.js";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
+import { runLoop } from "../loop/run-loop.js";
 import { packagesSection, resourceEstimationSection } from "../prompts/planner.js";
 import { effectiveDeadlineMs } from "../providers/types.js";
 import { formatQuery, parseQuery } from "../sandbox/package-identity.js";
 import { loadDataProfileStatus } from "../state/index.js";
+import { defineTool } from "./define-tool.js";
 export const AD_HOC_ROUTER_AGENT_ID = "adhoc-router";
 export const AD_HOC_ROUTER_TIMEOUT_MS = 10_000;
 export const AD_HOC_FALLBACK_AGENT_ID = "scientific-executor";
-/** Must differ from a loop step name such as `llm-0`, since both share the usage-record key space. */
-const AD_HOC_ROUTE_CALL_NAME = "adhoc-route";
+const SUBMIT_ROUTE_TOOL_ID = "submit_route";
 const resourcesSchema = z.object({
     cpu: z.number().positive(),
     memoryGb: z.number().positive(),
@@ -24,6 +26,7 @@ const resourcesSchema = z.object({
 });
 const routeSchema = z.object({
     agentId: z.string().optional().describe("The id of one specialist from the eligible catalog, copied exactly."),
+    capability: z.string().optional().describe("The one capability phrase of that specialist which this request uses, copied exactly from its capabilities."),
     resources: resourcesSchema
         .optional()
         .describe("The sandbox resources of the step, inside the stated ranges. Omit to take the defaults; a value outside the ranges is replaced by the defaults."),
@@ -68,7 +71,7 @@ async function profileOrientation(pool, analysisId, logger) {
         return buildDataProfileOrientation(status.result, analysisId, DATA_PROFILE_ORIENTATION_MAX_CHARS);
     }
     catch (error) {
-        logger.warn("could not load data profile for ad hoc routing", { error: error instanceof Error ? error.message : String(error) });
+        logger.warn("could not load data profile for ad hoc routing", { error: errorMessageOf(error) ?? textOf(error) });
         return "The persisted data profile could not be loaded; route from the request alone.";
     }
 }
@@ -96,7 +99,7 @@ async function routePackages(raw, resolve, logger) {
     const seen = new Set();
     for (const element of entries) {
         if (typeof element !== "string") {
-            droppedPackages.push({ entry: String(element), reason: "unparsable" });
+            droppedPackages.push({ entry: textOf(element), reason: "unparsable" });
             continue;
         }
         const entry = element.trim();
@@ -121,7 +124,7 @@ async function routePackages(raw, resolve, logger) {
     catch (error) {
         // A resolution that throws is the same condition as an inventory that
         // reports itself unavailable: it says nothing about the packages.
-        logger.warn("ad hoc package resolution failed", { error: error instanceof Error ? error.message : String(error) });
+        logger.warn("ad hoc package resolution failed", { error: errorMessageOf(error) ?? textOf(error) });
         rows = null;
     }
     if (rows === null)
@@ -152,13 +155,15 @@ async function routePackages(raw, resolve, logger) {
     }
     return { packages, droppedPackages };
 }
+/** The one tool of the router. The route is the input of its call, thus the call itself records nothing. */
 function routeTool() {
-    return {
-        submit_route: aiTool({
-            description: "Submit the single specialist, the resource recommendation, and the packages of the step. This is the only valid response.",
-            inputSchema: jsonSchema(z.toJSONSchema(routeSchema)),
-        }),
-    };
+    return defineTool({
+        id: SUBMIT_ROUTE_TOOL_ID,
+        description: "Submit the single specialist, the resource recommendation, and the packages of the step. This is the only valid response.",
+        inputSchema: routeSchema,
+        describeCall: "none",
+        execute: () => Promise.resolve(ok({ recorded: true })),
+    });
 }
 export async function routeAdHocRequest(deps, input) {
     const logger = (deps.logger ?? createNoopLogger()).named("adhoc-router").with({ analysisId: input.analysisId, model: deps.model });
@@ -166,14 +171,15 @@ export async function routeAdHocRequest(deps, input) {
     const catalog = PLANNABLE_AGENT_CATALOG.map((agent) => `- ${agent.id}: capabilities [${agent.capabilities.join(", ")}]; suitable for [${agent.suitableFor.join(", ")}]`).join("\n");
     const orientation = await profileOrientation(deps.pool, input.analysisId, logger);
     const controller = new AbortController();
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- a guard, not a wait: it aborts the routing controller at the deadline while the provider call runs, and the finally clears it.
     const timer = setTimeout(() => controller.abort(new Error("ad hoc routing timed out")), effectiveDeadlineMs(deps.provider, AD_HOC_ROUTER_TIMEOUT_MS, deps.timeoutMs));
     const signal = AbortSignal.any([input.signal, controller.signal]);
     let raw;
     let failure;
     try {
-        const response = unwrapOrThrow(await deps.provider
-            .chat({
-            system: [
+        const router = {
+            id: AD_HOC_ROUTER_AGENT_ID,
+            systemPrompt: [
                 "Select exactly one specialist for a targeted one-step analysis, estimate its sandbox resources, and name the packages that the step imports.",
                 "Choose only from the supplied catalog. Do not create a plan, reject the request, or select scientific-executor.",
                 resourceEstimationSection(deps.resourcePolicy),
@@ -182,45 +188,54 @@ export async function routeAdHocRequest(deps, input) {
                 "You hold no package census. For a name that both ecosystems hold, the language of the specialist you select and the wording of the request decide the track.",
                 "Respond only by calling submit_route.",
             ].join("\n\n"),
-            messages: [
-                {
-                    role: "user",
-                    content: `Request:\n${input.request}\n\nPersisted data-profile orientation:\n${orientation}\n\nEligible specialists:\n${catalog}`,
-                },
-            ],
-            // No forced tool choice: some Claude models reject it with a
-            // 400. A reply without the call falls back below as `malformed`.
-            tools: routeTool(),
-        }, routerSession, signal)
-            .map(countChatTokens(AD_HOC_ROUTER_AGENT_ID)));
-        // A failed call throws at unwrapOrThrow above, so no usage is recorded.
-        accountForChatCall(response, {
-            session: routerSession,
-            agentId: AD_HOC_ROUTER_AGENT_ID,
-            callPath: routerSession.provenance.callPath,
-            stepName: AD_HOC_ROUTE_CALL_NAME,
-            ...(input.invocationId === undefined ? {} : { invocationId: input.invocationId }),
-            usageRecorder: deps.usageRecorder ?? createNoopUsageRecorder(),
-            logger,
-            rollups: input.turnUsage === undefined ? [] : [input.turnUsage],
+            model: deps.model,
+            tools: [routeTool()],
+            // One request: the route is the input of the call, thus no second request is due.
+            maxIterations: 1,
+        };
+        const run = await runLoop(router, [
+            {
+                role: "user",
+                content: `Request:\n${input.request}\n\nPersisted data-profile orientation:\n${orientation}\n\nEligible specialists:\n${catalog}`,
+            },
+        ], routerSession, {
+            provider: deps.provider,
+            signal,
+            emit: () => undefined,
+            // One request reads no cache back, thus a cache write is a cost with no return.
+            promptCache: "off",
+            logger: deps.logger,
+            usageRecorder: deps.usageRecorder,
+            // The router call folds its usage into the turn total, and the turn root reports it.
+            turnUsage: input.turnUsage ?? {},
+            invocationId: input.invocationId,
+            stopWhen: (steps) => steps.some((step) => step.calls.some((call) => call.toolName === SUBMIT_ROUTE_TOOL_ID)),
         });
-        const call = Array.isArray(response.message.content)
-            ? response.message.content.find((part) => part.type === "tool-call" && part.toolName === "submit_route")
-            : undefined;
-        raw = call?.input;
-        if (!call)
-            failure = "malformed";
+        if (run.finish.reason === "aborted") {
+            if (input.signal.aborted)
+                throw toThrowable(input.signal.reason);
+            failure = "timeout";
+            logger.warn("ad hoc route fell back", { failure });
+        }
+        else {
+            // No forced tool choice: some Claude models reject it with a 400. A reply
+            // without the call falls back below as `malformed`.
+            const call = run.steps.flatMap((step) => step.calls).find((entry) => entry.toolName === SUBMIT_ROUTE_TOOL_ID);
+            raw = call?.input;
+            if (!call)
+                failure = "malformed";
+        }
     }
     catch (error) {
         if (input.signal.aborted)
             throw error;
-        failure = controller.signal.aborted && !input.signal.aborted ? "timeout" : "provider_error";
-        logger.warn("ad hoc route fell back", { failure, error: error instanceof Error ? error.message : String(error) });
+        failure = controller.signal.aborted ? "timeout" : "provider_error";
+        logger.warn("ad hoc route fell back", { failure, error: errorMessageOf(error) ?? textOf(error) });
     }
     finally {
         clearTimeout(timer);
     }
-    const candidate = raw !== null && typeof raw === "object" ? raw : {};
+    const candidate = parseUnknownRecord(raw) ?? {};
     const requestedAgent = typeof candidate.agentId === "string" ? candidate.agentId : undefined;
     const validAgent = requestedAgent !== undefined && PLANNABLE_AGENT_CATALOG.some((agent) => agent.id === requestedAgent);
     const agentId = validAgent ? requestedAgent : AD_HOC_FALLBACK_AGENT_ID;
@@ -241,6 +256,20 @@ export async function routeAdHocRequest(deps, input) {
     // never becomes a `fallbackClass`, because that class describes the route
     // as a whole and a step agent reads it as "the routing itself fell back".
     const { packages, droppedPackages } = await routePackages(candidate.packages, deps.resolvePackages, logger);
-    logger.info("ad hoc route selected", { agentId, resources, rationale, failure, packages, droppedPackages });
-    return { agentId, resources, rationale, packages, droppedPackages, ...(failure ? { fallbackClass: failure } : {}) };
+    // Kept only when the chosen agent really advertises it. A phrase that no agent advertises
+    // resolves no data requirement anyway, and carrying it would put a fabricated capability into
+    // the step and into the run record. An absent phrase is a normal answer, not a fallback class:
+    // most requests use a capability that declares nothing.
+    const requestedCapability = typeof candidate.capability === "string" ? candidate.capability.trim() : "";
+    const capability = (SANDBOX_AGENT_META[agentId]?.capabilities ?? []).includes(requestedCapability) ? requestedCapability : undefined;
+    logger.info("ad hoc route selected", { agentId, resources, rationale, failure, packages, droppedPackages, capability });
+    return {
+        agentId,
+        resources,
+        rationale,
+        packages,
+        droppedPackages,
+        capability,
+        fallbackClass: failure,
+    };
 }

package/dist/tools/analysis-invocation.d.ts

@@ -2,3 +2,10 @@
 export declare function adHocPlanId(analysisId: string, invocationId: string): string;
 /** Deterministic RFC-4122 UUID used as both cortex run id and DBOS workflow id. */
 export declare function adHocRunId(analysisId: string, invocationId: string): string;
+/**
+ * The run id of a plan launch from a tool call, a version-5 UUID of the key of the call. The same call
+ * gives the same id, thus a rerun of the call reserves and launches the run of its first attempt.
+ */
+export declare function callRunId(callKey: string): string;
+/** The key of a tool call inside a workflow, `${workflowId}:${toolCallId}`, or `undefined` outside one, where nothing reruns. */
+export declare function durableCallKey(toolCallId: string): string | undefined;

package/dist/tools/analysis-invocation.js

@@ -1,7 +1,10 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
 import { createHash } from "node:crypto";
 const TOOL_ID = "execute_analysis";
-function digest(analysisId, invocationId) {
-    return createHash("sha256").update(`${TOOL_ID}\0${analysisId}\0${invocationId}`, "utf8").digest();
+function digest(...parts) {
+    return createHash("sha256")
+        .update([TOOL_ID, ...parts].join("\0"), "utf8")
+        .digest();
 }
 /** Deterministic internal plan id in the existing persistence shape. */
 export function adHocPlanId(analysisId, invocationId) {
@@ -9,9 +12,30 @@ export function adHocPlanId(analysisId, invocationId) {
 }
 /** Deterministic RFC-4122 UUID used as both cortex run id and DBOS workflow id. */
 export function adHocRunId(analysisId, invocationId) {
-    const bytes = Buffer.from(digest(analysisId, invocationId).subarray(4, 20));
-    bytes[6] = (bytes[6] & 0x0f) | 0x50;
-    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    return uuidOf(digest(analysisId, invocationId));
+}
+/**
+ * The run id of a plan launch from a tool call, a version-5 UUID of the key of the call. The same call
+ * gives the same id, thus a rerun of the call reserves and launches the run of its first attempt.
+ */
+export function callRunId(callKey) {
+    return uuidOf(digest("plan", callKey));
+}
+/** The key of a tool call inside a workflow, `${workflowId}:${toolCallId}`, or `undefined` outside one, where nothing reruns. */
+export function durableCallKey(toolCallId) {
+    const workflowId = DBOS.workflowID;
+    return workflowId === undefined ? undefined : `${workflowId}:${toolCallId}`;
+}
+function uuidOf(hash) {
+    const bytes = Buffer.from(hash.subarray(4, 20));
+    const versionByte = bytes[6];
+    if (versionByte === undefined)
+        throw new Error("the digest is shorter than the UUID layout");
+    bytes[6] = (versionByte & 0x0f) | 0x50;
+    const variantByte = bytes[8];
+    if (variantByte === undefined)
+        throw new Error("the digest is shorter than the UUID layout");
+    bytes[8] = (variantByte & 0x3f) | 0x80;
     const hex = bytes.toString("hex");
     return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }

package/dist/tools/approval/contract.d.ts

@@ -1,15 +1,13 @@
 /**
- * The tool-approval seam contract: the request a conversation tool pauses on,
- * the decision the user returns, and the deny-by-default realization shipped for
- * hosts that wire no interactive surface.
+ * The tool-approval contract: the request that the approval hook of a tool gives,
+ * and the decision that the user returns.
  *
- * The seam is generic — nothing here names a tool or a domain. A tool describes
+ * The contract is generic — nothing here names a tool or a domain. A tool describes
  * the concrete action it needs approved (`AskRequest`); a surface renders it, the
- * user decides, and the decision comes back as an `AskApproval` on approval or an
- * `AskRejectedError` throw on denial.
+ * user decides, and the loop runs the call on an approval or denies it.
  *
- * These are standalone types so `define-tool.ts` can type-import them into
- * `ToolContext` without an import cycle back through the tools layer.
+ * These are standalone types so `define-tool.ts` can type-import them without an
+ * import cycle back through the tools layer.
  */
 /**
  * The human-facing content a surface renders to describe the exact action being
@@ -17,7 +15,7 @@
  * they saw is precisely what is granted, nothing broader. No tool- or
  * domain-specific fields: the harness stays agnostic to what is being approved.
  */
-export interface AskRequest {
+export type AskRequest = {
     readonly title: string;
     readonly command: string;
     readonly detail?: string;
@@ -29,15 +27,12 @@ export interface AskRequest {
      * field, and the surface never renders it. Absent, the grant keys on `command`.
      */
     readonly grantKey?: string;
-}
+};
 /**
  * A user's decision on an approval request — three distinct outcomes, never a
  * boolean. `once` approves the single pending invocation; `always` approves it
  * AND records a standing grant for the matched action; `reject` denies and MAY
  * carry model-facing feedback.
- *
- * This full three-variant union is the wire type the outward `answer` API takes;
- * `ctx.ask` itself resolves only with the `AskApproval` subset (denial throws).
  */
 export type AskReply = {
     readonly kind: "once";
@@ -47,42 +42,3 @@ export type AskReply = {
     readonly kind: "reject";
     readonly feedback?: string;
 };
-/**
- * The subset of `AskReply` `ctx.ask` may resolve with. Denial never returns — it
- * throws `AskRejectedError` — so a resolved approval is only ever `once` or
- * `always`, and a caller never has to inspect for a reject variant.
- */
-export type AskApproval = Exclude<AskReply, {
-    kind: "reject";
-}>;
-/**
- * The throw a `reject` reply raises out of `ctx.ask`, carrying the optional
- * model-facing feedback.
- *
- * Denial is a throw rather than a returned reject variant so a tool never has to
- * inspect the reply to learn it was denied: only asks throw, so the throw itself
- * is the denial signal, and the loop needs no per-tool "was denied" flag — it maps
- * the caught error to an execution-denied tool result and stops the turn.
- */
-export declare class AskRejectedError extends Error {
-    readonly feedback?: string;
-    constructor(feedback?: string);
-}
-/**
- * The user-approval seam. `ask` pauses on an approval request and resolves with
- * the approval decision, or throws `AskRejectedError` when the user denies.
- * Realizations are wired by the embedder; an unwired host resolves to
- * `UnavailableAsk`.
- */
-export interface Ask {
-    ask(request: AskRequest): Promise<AskApproval>;
-}
-/**
- * Deny-by-default realization — the shipped `Ask` for hosts that wire no
- * interactive surface (workflow contexts, headless embedders). Every request is
- * denied, so a tool that calls `ctx.ask` where nothing can answer is rejected
- * rather than left waiting on a surface that will never respond.
- */
-export declare class UnavailableAsk implements Ask {
-    ask(_request: AskRequest): Promise<AskApproval>;
-}

package/dist/tools/approval/contract.js

@@ -1,41 +1,12 @@
 /**
- * The tool-approval seam contract: the request a conversation tool pauses on,
- * the decision the user returns, and the deny-by-default realization shipped for
- * hosts that wire no interactive surface.
+ * The tool-approval contract: the request that the approval hook of a tool gives,
+ * and the decision that the user returns.
  *
- * The seam is generic — nothing here names a tool or a domain. A tool describes
+ * The contract is generic — nothing here names a tool or a domain. A tool describes
  * the concrete action it needs approved (`AskRequest`); a surface renders it, the
- * user decides, and the decision comes back as an `AskApproval` on approval or an
- * `AskRejectedError` throw on denial.
+ * user decides, and the loop runs the call on an approval or denies it.
  *
- * These are standalone types so `define-tool.ts` can type-import them into
- * `ToolContext` without an import cycle back through the tools layer.
+ * These are standalone types so `define-tool.ts` can type-import them without an
+ * import cycle back through the tools layer.
  */
-/**
- * The throw a `reject` reply raises out of `ctx.ask`, carrying the optional
- * model-facing feedback.
- *
- * Denial is a throw rather than a returned reject variant so a tool never has to
- * inspect the reply to learn it was denied: only asks throw, so the throw itself
- * is the denial signal, and the loop needs no per-tool "was denied" flag — it maps
- * the caught error to an execution-denied tool result and stops the turn.
- */
-export class AskRejectedError extends Error {
-    feedback;
-    constructor(feedback) {
-        super(feedback ? `approval rejected: ${feedback}` : "approval rejected");
-        this.name = "AskRejectedError";
-        this.feedback = feedback;
-    }
-}
-/**
- * Deny-by-default realization — the shipped `Ask` for hosts that wire no
- * interactive surface (workflow contexts, headless embedders). Every request is
- * denied, so a tool that calls `ctx.ask` where nothing can answer is rejected
- * rather than left waiting on a surface that will never respond.
- */
-export class UnavailableAsk {
-    async ask(_request) {
-        throw new AskRejectedError("approval is unavailable in this environment");
-    }
-}
+export {};

package/dist/tools/approval/gateway.d.ts

@@ -1,48 +1,47 @@
 /**
- * The poll-based tool-approval gateway — the constructed `Ask` seam realization
- * an embedder wires over its Postgres pool, plus the outward `answer` / `pending`
- * API it drives and the boot-time `sweepExpired`.
- *
- * `ask` is the per-turn seam an embedder binds: a conversation tool's `ctx.ask`
- * pauses on it. The database is the single source of truth for ask state — `ask`
- * inserts a `pending` ledger row, emits the `data-ask` part, and polls that row to
- * a terminal status; there is no in-memory resolver map. `answer` is one guarded
- * write. See the poll site below for why.
+ * The tool-approval gateway: the ask ledger over the Postgres pool of an
+ * embedder. A turn workflow raises an ask under a known id and waits for the
+ * answer itself. `answer` is one guarded write, and `pending` and the boot-time
+ * `sweepExpired` read and expire the ledger.
  */
 import type { Pool } from "pg";
-import type { EmitFn } from "../../loop/types.js";
-import { type AskApproval, type AskReply, type AskRequest } from "./contract.js";
-import { type AnswerOutcome, type PendingAsk } from "./queries.js";
+import type { AskPart } from "../../contracts/chat-parts.js";
+import type { AskReply, AskRequest } from "./contract.js";
+import { type AnswerOutcome, type AskStatus, type PendingAsk } from "./queries.js";
 export type { AnswerOutcome, PendingAsk } from "./queries.js";
 /** Construction deps: the harness application pool the ledger lives in. */
-export interface AskGatewayDeps {
+export type AskGatewayDeps = {
     readonly pool: Pool;
-}
-/**
- * Per-turn context an embedder binds into the `Ask` seam. It scopes the ask to an
- * analysis/thread and to one user, carries the turn's abort `signal`, and supplies
- * the `emit` sink the `data-ask` part flows through.
- */
-export interface AskContext {
+};
+/** Who an ask goes to and where it belongs. */
+export type AskScope = {
     readonly analysisId: string;
     /** The opaque identity of the person the ask goes to. The harness never reads it. */
     readonly userId: string;
     readonly threadId?: string;
-    readonly signal: AbortSignal;
-    readonly emit: EmitFn;
-}
-/** The gateway surface: the per-turn seam plus the outward embedder-driven API. */
-export interface AskGateway {
-    ask(request: AskRequest, ctx: AskContext): Promise<AskApproval>;
+};
+/** The gateway surface: the raise of a turn and the outward embedder-driven API. */
+export type AskGateway = {
+    /**
+     * Raise an ask under a known id, for a turn workflow that waits for the answer itself. A standing grant settles
+     * it at once as `resolved`. Else the row waits as `pending`. A second raise of the same id changes nothing.
+     */
+    raise(id: string, request: AskRequest, scope: AskScope): Promise<"granted" | "pending">;
+    /** Mark a pending ask `expired`. */
+    expire(id: string): Promise<void>;
+    /** Mark a pending ask `aborted`. */
+    abort(id: string): Promise<void>;
     answer(id: string, reply: AskReply): Promise<AnswerOutcome>;
     pending(): Promise<PendingAsk[]>;
     /** Expire pending asks older than `maxAgeMs` (default {@link DEFAULT_SWEEP_MAX_AGE_MS}). */
     sweepExpired(maxAgeMs?: number): Promise<number>;
-}
+};
 /**
  * Pending rows older than this are treated as orphans of a dead process. Far
  * beyond any plausible live turn, so a boot sweep during a rolling deployment
- * cannot expire an ask another pod is still polling.
+ * cannot expire an ask another pod is still waiting on.
  */
 export declare const DEFAULT_SWEEP_MAX_AGE_MS: number;
 export declare function createAskGateway(deps: AskGatewayDeps): AskGateway;
+/** The `data-ask` part of an ask in one status. Each status of one ask reconciles under the same id. */
+export declare function askPartOf(id: string, request: AskRequest, status: AskStatus, reply?: AskReply["kind"]): AskPart;