@inflexa-ai/harness 0.17.0 → 0.19.0

package/dist/data/safety-panel-schema.d.ts

@@ -1,8 +1,4 @@
 import { z } from "zod";
-export declare const ORGAN_SYSTEMS: readonly ["cardiac", "hepatic", "renal", "cns", "hematologic", "gi", "respiratory", "metabolic", "immune"];
-export declare const SEVERITIES: readonly ["high", "medium", "low"];
-export type OrganSystem = (typeof ORGAN_SYSTEMS)[number];
-export type Severity = (typeof SEVERITIES)[number];
 export declare const CHEMBL_RE: RegExp;
 export declare const UNIPROT_RE: RegExp;
 export declare const SafetyTargetSchema: z.ZodObject<{
@@ -16,11 +12,20 @@ export declare const SafetyTargetSchema: z.ZodObject<{
         metabolic: "metabolic";
         immune: "immune";
         hepatic: "hepatic";
+        musculoskeletal: "musculoskeletal";
         cns: "cns";
         renal: "renal";
+        reproductive: "reproductive";
         respiratory: "respiratory";
         cardiac: "cardiac";
+        vascular: "vascular";
+        pns: "pns";
         gi: "gi";
+        pancreas: "pancreas";
+        endocrine_thyroid: "endocrine_thyroid";
+        dermatologic: "dermatologic";
+        ocular: "ocular";
+        oncology: "oncology";
     }>;
     clinical_consequence: z.ZodString;
     severity: z.ZodEnum<{
@@ -46,11 +51,20 @@ export declare const SafetyPanelFileSchema: z.ZodObject<{
             metabolic: "metabolic";
             immune: "immune";
             hepatic: "hepatic";
+            musculoskeletal: "musculoskeletal";
             cns: "cns";
             renal: "renal";
+            reproductive: "reproductive";
             respiratory: "respiratory";
             cardiac: "cardiac";
+            vascular: "vascular";
+            pns: "pns";
             gi: "gi";
+            pancreas: "pancreas";
+            endocrine_thyroid: "endocrine_thyroid";
+            dermatologic: "dermatologic";
+            ocular: "ocular";
+            oncology: "oncology";
         }>;
         clinical_consequence: z.ZodString;
         severity: z.ZodEnum<{
@@ -61,4 +75,3 @@ export declare const SafetyPanelFileSchema: z.ZodObject<{
         references: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export type SafetyPanelFile = z.infer<typeof SafetyPanelFileSchema>;

package/dist/data/safety-panel-schema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
-export const ORGAN_SYSTEMS = ["cardiac", "hepatic", "renal", "cns", "hematologic", "gi", "respiratory", "metabolic", "immune"];
-export const SEVERITIES = ["high", "medium", "low"];
+import { OrganSystemSchema } from "../contracts/organ-system.js";
+import { SeveritySchema } from "../contracts/severity.js";
 export const CHEMBL_RE = /^CHEMBL\d+$/;
 // UniProt 6-char accession: letter (any A-Z, covering A-N, O, P, Q, R-Z sub-families),
 // followed by a digit, three alphanumerics, and a final digit.
@@ -21,9 +21,9 @@ export const SafetyTargetSchema = z.object({
     uniprot: UniprotSchema,
     ensembl_gene_id: EnsemblGeneSchema.optional(),
     name: z.string().min(1).max(120),
-    organ_system: z.enum(ORGAN_SYSTEMS),
+    organ_system: OrganSystemSchema,
     clinical_consequence: z.string().min(1).max(200),
-    severity: z.enum(SEVERITIES),
+    severity: SeveritySchema,
     references: z.array(ReferenceSchema).min(1),
 });
 export const SafetyPanelFileSchema = z.object({

package/dist/execution/artifact-metadata.js

@@ -95,6 +95,7 @@ function buildSubmitTool(holder, knownPaths) {
             "remaining}: accepted=true means every file now has metadata — STOP. " +
             "Otherwise drop the unknownPaths and describe the remaining files.",
         inputSchema: SubmitFileMetadataInputSchema,
+        describeCall: "none",
         execute: async (input) => {
             const unknownPaths = [];
             for (const entry of input.files) {

package/dist/execution/report-runner.js

@@ -39,11 +39,9 @@ import { passthroughStep } from "../loop/run-step.js";
 import { previewVersionDir, previewDir, latestPreviewVersion } from "../workspace/paths.js";
 import { withPreviewLock } from "../tools/lib/preview-lock.js";
 import { createBuildReportTool, createSubmitReportTool, createMintPreviewUrlTool, createPreviewSnapshotTool, createVersionFsTools, } from "../tools/report/index.js";
-import { createReportBuilderAgent, REPORT_BUILDER_AGENT_ID } from "../agents/report-builder.js";
+import { createReportBuilderAgent, REPORT_BUILDER_AGENT_ID, REPORT_BUILDER_SKILLS } from "../agents/report-builder.js";
 import { createSkillTools } from "../tools/sandbox/skills.js";
 import { createNoopLogger } from "../lib/console-logger.js";
-/** Skill pack the report-builder prompt directs the model to read (design-system reference). */
-const REPORT_BUILDER_SKILLS = ["report-html"];
 const REPORT_AGENT_MAX_STEPS = 75;
 export async function runReportIteration(deps, opts) {
     const logger = (deps.logger ?? createNoopLogger()).named("report-runner").with({ previewId: opts.previewId });

package/dist/execution/run-synthesis.js

@@ -270,6 +270,7 @@ function buildValidateTool(ctx) {
         inputSchema: z.object({
             synthesis: z.unknown().describe("The candidate synthesis, in any shape. Field-by-field schema: see submit_synthesis."),
         }),
+        describeCall: "none",
         execute: async (input) => {
             const result = fullyValidate(input.synthesis, ctx);
             return ok(result.valid ? { valid: true, issues: [] } : { valid: false, issues: result.issues });
@@ -289,6 +290,7 @@ function buildSubmitTool(holder, ctx) {
             "already-accepted synthesis untouched; a later accepted submission " +
             "supersedes an earlier one.",
         inputSchema: z.object({ synthesis: RunSynthesisSchema }),
+        describeCall: "none",
         execute: async (input) => {
             const result = fullyValidate(input.synthesis, ctx);
             if (!result.valid) {

package/dist/index.d.ts

@@ -32,6 +32,7 @@ export type { DbosWorkflowPurgerDeps } from "./execution/dbos-workflow-purger.js
 export type { WorkflowPurger } from "./execution/workflow-purger.js";
 export { defineTool, isToolError } from "./tools/define-tool.js";
 export type { Tool, ToolDefinition, ToolContext, ToolError } from "./tools/define-tool.js";
+export { normalizeDetail, DETAIL_MAX_LENGTH } from "./loop/tool-detail.js";
 export { createCitationResolver } from "./citations/resolve.js";
 export type { CitationResolverConfig, CitationResolverDependencies, CitationResolverSourceConfig } from "./citations/resolve.js";
 export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
@@ -77,6 +78,9 @@ export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./cont
 export type { CortexChatPartType, PartDescriptor, PartEmitter, PartConsumer } from "./contracts/part-registry.js";
 export { launchDbos, shutdownDbos, sweepEphemeralWorkflows } from "./runtime/dbos.js";
 export type { DbosConfig } from "./runtime/dbos.js";
+export { dbosState } from "./runtime/dbos.js";
+export type { DbosState } from "./runtime/dbos.js";
+export { isDraining } from "./runtime/lifecycle.js";
 export { StatusString } from "@dbos-inc/dbos-sdk";
 export type { WorkflowStatusString } from "@dbos-inc/dbos-sdk";
 export { createPool } from "./lib/storage.js";
@@ -118,6 +122,8 @@ export { registerExecuteAnalysis } from "./workflows/execute-analysis.js";
 export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunObservation, RunProvenanceEvent, RunStepObservation, StepRuntimeStatus, } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
 export type { SandboxStepDeps, SandboxStepInput, SandboxStepResult, SandboxAgentBuildContext } from "./workflows/sandbox-step.js";
+export { DEFAULT_CLAIM_INVESTIGATION_CONFIG } from "./workflows/target-assessment/investigation/index.js";
+export type { ClaimInvestigationConfig } from "./workflows/target-assessment/investigation/index.js";
 export { createRunEventStream } from "./execution/run-event-stream.js";
 export type { RunEventStream, RunEventStreamDeps, RunEventSubscribeOptions, RunEventPartHandler } from "./execution/run-event-stream.js";
 export { createSandboxAgents, SANDBOX_AGENT_META } from "./agents/sandbox/index.js";

package/dist/index.js

@@ -33,6 +33,15 @@ export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
 // Tool primitive.
 export { defineTool, isToolError } from "./tools/define-tool.js";
+// Tool-call-detail authoring aids for an embedder that contributes a host tool.
+// A `describeCall` hook that pre-empts truncation — a count in place of a
+// mid-value cut that would name a file that does not exist — must gate on the
+// SAME bound the harness enforces at the emit site. Thus `DETAIL_MAX_LENGTH`
+// rides the curated surface, so a host reads the one number rather than copying
+// it and drifting when the harness retunes the cap. `normalizeDetail` is that
+// emit-site transform, exported so a host can assert a hook's output against
+// exactly what the harness will render.
+export { normalizeDetail, DETAIL_MAX_LENGTH } from "./loop/tool-detail.js";
 // Host-agnostic citation verification service and its public contracts.
 export { createCitationResolver } from "./citations/resolve.js";
 export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
@@ -120,6 +129,12 @@ export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./cont
 // older releases could leave PENDING `ephemeral:*` rows that recovery would
 // otherwise re-dispatch. No current workflow creates that prefix.
 export { launchDbos, shutdownDbos, sweepEphemeralWorkflows } from "./runtime/dbos.js";
+// The readiness pair. Both flags are mutated by harness-owned code an embedder
+// does not call itself — `launchDbos` flips the DBOS state, and the `shutdown`
+// handle `bootHarness` returns marks draining — so the reads have to come from
+// here for a host's own probe to reflect them at all.
+export { dbosState } from "./runtime/dbos.js";
+export { isDraining } from "./runtime/lifecycle.js";
 // DBOS workflow-status vocabulary. An embedder that reads its own
 // `dbos.workflow_status` rows must classify them against the SDK's status set,
 // but must never depend on `@dbos-inc/dbos-sdk` directly — the SDK is
@@ -179,6 +194,10 @@ export { ExecEventMessageSchema } from "./sandbox/types.js";
 // these, but an embedder running only the run engine registers them directly.
 export { registerExecuteAnalysis } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
+// Target assessment — the bounds its claim-investigation phase runs under. An
+// embedder wiring `executeTargetAssessment` sets these at its composition root;
+// the dossier reports whichever values were in force.
+export { DEFAULT_CLAIM_INVESTIGATION_CONFIG } from "./workflows/target-assessment/investigation/index.js";
 // Run-event read seam — the fine-grained durable channel beside `observeRun`.
 // The two are a deliberate pair, not a duplication: `observeRun` is the coarse,
 // in-process run/step snapshot a workflow hands its host synchronously, and it

package/dist/lib/async-utils.d.ts

@@ -1,10 +1,22 @@
 /**
- * Shared async utilities — sleep and bounded-concurrency map.
+ * Shared async utilities — sleep and a bounded-concurrency `Promise.all`.
  */
 /** Promise-based delay. */
 export declare function sleep(ms: number): Promise<void>;
 /**
- * Map over items with bounded concurrency.
- * At most `concurrency` items are processed simultaneously.
+ * Run each task with a cap on how many run at the same time, and give back the results in the order of
+ * the input.
+ *
+ * The signature mirrors `Promise.all`. The mapped return type is element-wise, thus a tuple of thunks
+ * with different return types keeps each one, and a plain array of thunks gives a plain array. The input
+ * is an array of thunks and not an array of promises, because a promise is already running when it is
+ * made, and a cap over a set of started promises caps nothing.
+ *
+ * `concurrency` must be a number at or above 1. p-queue throws a `TypeError` for any other value.
+ *
+ * The failure behavior is that of `Promise.all`. The first rejection rejects the whole call, and each
+ * task that the queue already started still runs to completion.
  */
-export declare function mapConcurrent<T, R>(items: T[], concurrency: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export declare function allWithConcurrency<T extends readonly (() => unknown)[] | []>(tasks: T, concurrency: number): Promise<{
+    -readonly [P in keyof T]: Awaited<T[P] extends () => infer R ? R : never>;
+}>;

package/dist/lib/async-utils.js

@@ -1,24 +1,29 @@
 /**
- * Shared async utilities — sleep and bounded-concurrency map.
+ * Shared async utilities — sleep and a bounded-concurrency `Promise.all`.
  */
+import PQueue from "p-queue";
 /** Promise-based delay. */
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
- * Map over items with bounded concurrency.
- * At most `concurrency` items are processed simultaneously.
+ * Run each task with a cap on how many run at the same time, and give back the results in the order of
+ * the input.
+ *
+ * The signature mirrors `Promise.all`. The mapped return type is element-wise, thus a tuple of thunks
+ * with different return types keeps each one, and a plain array of thunks gives a plain array. The input
+ * is an array of thunks and not an array of promises, because a promise is already running when it is
+ * made, and a cap over a set of started promises caps nothing.
+ *
+ * `concurrency` must be a number at or above 1. p-queue throws a `TypeError` for any other value.
+ *
+ * The failure behavior is that of `Promise.all`. The first rejection rejects the whole call, and each
+ * task that the queue already started still runs to completion.
  */
-export async function mapConcurrent(items, concurrency, fn) {
-    const results = new Array(items.length);
-    let nextIndex = 0;
-    async function worker() {
-        while (nextIndex < items.length) {
-            const i = nextIndex++;
-            results[i] = await fn(items[i], i);
-        }
-    }
-    const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => worker());
-    await Promise.all(workers);
-    return results;
+export function allWithConcurrency(tasks, concurrency) {
+    const queue = new PQueue({ concurrency });
+    // `addAll` collapses every task onto one result type, thus it cannot express the element-wise type
+    // above. The cast is sound because `addAll` maps the input array through `Promise.all`, which keeps
+    // the position of each task, and each element is the awaited return of the task at that position.
+    return queue.addAll(tasks);
 }

package/dist/lib/host-concurrency.js

@@ -27,6 +27,7 @@ const DEFAULT_LIMITS = {
     hgnc: 6,
     uniprot: 6,
     iuphar: 4,
+    monarch: 3,
     ema: 2,
     pubchem: 4,
     "annotation-llm": 4,

package/dist/loop/__fixtures__/scripted-provider.js

@@ -29,6 +29,17 @@ export function thinkingBlock(thinking, signature) {
 export function toolUseBlock(id, name, input) {
     return { type: "tool-call", toolCallId: id, toolName: name, input };
 }
+/**
+ * The text a real provider would have streamed for this reply — one delta per
+ * text block. Reasoning and tool-call blocks carry no text on the wire, so they
+ * arrive only in the terminal `done` response.
+ */
+function textDeltas(response) {
+    const content = response.message.content;
+    if (typeof content === "string")
+        return content === "" ? [] : [content];
+    return content.filter((part) => part.type === "text").map((part) => part.text);
+}
 export function scriptedProvider(script) {
     const calls = [];
     const sessions = [];
@@ -51,8 +62,18 @@ export function scriptedProvider(script) {
             sessions.push(session);
             return okAsync(reply(i, request));
         },
-        chatStream() {
-            throw new Error("scriptedProvider: chatStream is not used by runAgent");
+        chatStream(request, session) {
+            // The call is recorded and the reply resolved eagerly, as in `chat`, so
+            // an unscripted call fails at the same point either primitive is driven.
+            const i = calls.length;
+            calls.push(request);
+            sessions.push(session);
+            const response = reply(i, request);
+            return (async function* () {
+                for (const text of textDeltas(response))
+                    yield { type: "text-delta", text };
+                yield { type: "done", response };
+            })();
         },
     };
 }

package/dist/loop/run-agent.js

@@ -155,8 +155,12 @@ export async function runAgent(agent, initial, session, opts) {
      * in what they count. An error tool result is otherwise invisible to every sink —
      * it is not a thrown failure, so nothing reports it and the loop simply feeds it
      * back — and a run that ends badly is usually a run whose tool calls were failing.
+     *
+     * `details` and `durations` are positionally aligned with `calls`. `dispatchTools`
+     * measures a duration around the call itself, because this sink emits every finish
+     * event only after the whole round settles.
      */
-    const settleRound = async (calls, results, details) => {
+    const settleRound = async (calls, results, details, durations) => {
         const errored = [];
         for (let idx = 0; idx < calls.length; idx++) {
             const tu = calls[idx];
@@ -169,7 +173,15 @@ export async function runAgent(agent, initial, session, opts) {
                 toolErrorCount++;
                 errored.push(tu.toolName);
             }
-            await emit({ type: "tool-finished", source, toolUseId: tu.toolCallId, name: tu.toolName, outcome, ...detailField(details[idx]) });
+            await emit({
+                type: "tool-finished",
+                source,
+                toolUseId: tu.toolCallId,
+                name: tu.toolName,
+                outcome,
+                ...detailField(details[idx]),
+                ...durationField(durations[idx]),
+            });
         }
         return errored;
     };
@@ -226,8 +238,8 @@ export async function runAgent(agent, initial, session, opts) {
             for (const [idx, tu] of earlier.entries()) {
                 await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(earlierDetails[idx]) });
             }
-            const results = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
-            const errored = await settleRound(earlier, results, earlierDetails);
+            const { results, durations } = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
+            const errored = await settleRound(earlier, results, earlierDetails, durations);
             results.push(errorResult(trailing, TRUNCATED_TOOL_USE_ERROR));
             // The trailing call was never dispatched, but it reaches the model as an error
             // result like any other — so it counts, or `toolErrors` reports a cleaner run
@@ -256,8 +268,8 @@ export async function runAgent(agent, initial, session, opts) {
         for (const [idx, tu] of toolCalls.entries()) {
             await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(details[idx]) });
         }
-        const results = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
-        const errored = await settleRound(toolCalls, results, details);
+        const { results, durations } = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
+        const errored = await settleRound(toolCalls, results, details, durations);
         if (errored.length > 0)
             log.debug("tool results returned errors", { iteration: i, tools: errored });
         messages.push({ role: "tool", content: results });
@@ -373,8 +385,22 @@ function markLastLoopAssistant(messages, initialCount) {
         }
     }
 }
+/**
+ * Dispatch one round of tool calls, and measure the time of each call.
+ *
+ * `results` and `durations` are positionally aligned with `toolUses`.
+ *
+ * Each measurement brackets the same unit that the loop awaits for that call. For a
+ * step-mode call that unit is `runStep`, thus the figure includes the durable-step
+ * wrapper. The wrapper is part of what the call cost, and a cached replay of a step
+ * is genuinely fast. A bracket inside the step would report a body that did not run.
+ */
 async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, runStep, toolStepName) {
     const results = new Array(toolUses.length);
+    // The array starts with holes, which read as `undefined`. The element type
+    // says so, thus it agrees with what `settleRound` accepts. Every index is in
+    // fact assigned, because the mode partition below covers each call.
+    const durations = new Array(toolUses.length);
     const stepTools = [];
     const workflowTools = [];
     const inlineTools = [];
@@ -387,16 +413,28 @@ async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, run
         else
             stepTools.push({ tu, idx });
     }
-    await Promise.all(stepTools.map(({ tu, idx }) => runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError)).then((r) => {
-        results[idx] = r;
-    })));
+    await Promise.all(stepTools.map(({ tu, idx }) => {
+        const startedAt = performance.now();
+        return runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError)).then((r) => {
+            durations[idx] = elapsedMs(startedAt);
+            results[idx] = r;
+        });
+    }));
     for (const { tu, idx } of workflowTools) {
+        const startedAt = performance.now();
         results[idx] = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError);
+        durations[idx] = elapsedMs(startedAt);
     }
     for (const { tu, idx } of inlineTools) {
+        const startedAt = performance.now();
         results[idx] = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError);
+        durations[idx] = elapsedMs(startedAt);
     }
-    return results;
+    return { results, durations };
+}
+/** Whole milliseconds since `startedAt`, on the monotonic clock that took that mark. */
+function elapsedMs(startedAt) {
+    return Math.round(performance.now() - startedAt);
 }
 async function dispatchTool(tu, toolsById, ctx, isFatalLoopError) {
     const tool = toolsById.get(tu.toolName);
@@ -500,6 +538,16 @@ function outcomeOf(result) {
 function detailField(detail) {
     return detail === undefined ? {} : { detail };
 }
+/**
+ * The optional `durationMs` field, present only for a call that the loop measured.
+ *
+ * Spread rather than assigned, for the same reason as {@link detailField}: an
+ * unmeasured call emits no `durationMs` key. A zero here is a real measurement of a
+ * call that took under half a millisecond, and it is never a stand-in for no figure.
+ */
+function durationField(durationMs) {
+    return durationMs === undefined ? {} : { durationMs };
+}
 function hasDenial(results) {
     return results.some((r) => r.output.type === "execution-denied");
 }

package/dist/loop/tool-detail.d.ts

@@ -25,6 +25,46 @@ export type { ToolCallDetail };
  * channel.
  */
 export declare const DETAIL_MAX_LENGTH = 120;
+/**
+ * The bound a hook gives a free-form needle that it marks inside a detail.
+ *
+ * A needle is model-authored text of no fixed length, thus it is the one part of
+ * a detail that can run away. Left to {@link DETAIL_MAX_LENGTH}, a long needle
+ * takes the whole line, and the cut lands inside the mark that names it: the
+ * closing quote goes, and a second fact behind it goes with no trace. A hook
+ * bounds the needle first. Then the mark always closes, and the rest of the
+ * detail keeps its room.
+ *
+ * 32 code points shows the shape of a search — enough to recognize the needle a
+ * caller typed, and short enough that a target beside it survives whole.
+ */
+export declare const DETAIL_NEEDLE_MAX_LENGTH = 32;
+/**
+ * Cap `text` at `max` CODE POINTS, not UTF-16 units.
+ *
+ * A hook calls this to pre-empt the emit-site cap: that cap cuts the TAIL, so a
+ * detail with two parts loses the second one when the first runs long. One
+ * implementation serves both sites, thus a hook's own bound cuts and marks
+ * exactly as {@link normalizeDetail} does.
+ *
+ * `String.prototype.slice` cuts at a fixed unit index, which can land between the
+ * two halves of a surrogate pair and emit a lone surrogate — a terminal paints
+ * that as a replacement character, so the cap would corrupt the very tail it is
+ * supposed to merely shorten. Iterating the string yields whole code points.
+ *
+ * Code points, not display columns, is the right unit here: this cap is a safety
+ * valve against a runaway hook, so its job is to bound the payload. A column
+ * measurement would claim knowledge of the renderer's font metrics that the
+ * harness does not have — the host measures columns, because only the host knows
+ * how wide its own line is.
+ *
+ * A cut text carries `…` so that a reader can tell a shortened detail from a
+ * complete one. The mark costs one of the `max` code points, thus the cut goes to
+ * `max - 1`: a hard bound that overshoots by the width of its own mark is not a
+ * hard bound. `trimEnd` runs BEFORE the append, because a cut that lands on a
+ * space must give `word…` and not `word …`.
+ */
+export declare function capCodePoints(text: string, max: number): string;
 /**
  * Normalize whatever a hook returned into an emittable detail, or `undefined`.
  *

package/dist/loop/tool-detail.js

@@ -22,9 +22,28 @@ import { normalizeUnicode, redactSecrets } from "../input-sanitization.js";
  * channel.
  */
 export const DETAIL_MAX_LENGTH = 120;
+/**
+ * The bound a hook gives a free-form needle that it marks inside a detail.
+ *
+ * A needle is model-authored text of no fixed length, thus it is the one part of
+ * a detail that can run away. Left to {@link DETAIL_MAX_LENGTH}, a long needle
+ * takes the whole line, and the cut lands inside the mark that names it: the
+ * closing quote goes, and a second fact behind it goes with no trace. A hook
+ * bounds the needle first. Then the mark always closes, and the rest of the
+ * detail keeps its room.
+ *
+ * 32 code points shows the shape of a search — enough to recognize the needle a
+ * caller typed, and short enough that a target beside it survives whole.
+ */
+export const DETAIL_NEEDLE_MAX_LENGTH = 32;
 /**
  * Cap `text` at `max` CODE POINTS, not UTF-16 units.
  *
+ * A hook calls this to pre-empt the emit-site cap: that cap cuts the TAIL, so a
+ * detail with two parts loses the second one when the first runs long. One
+ * implementation serves both sites, thus a hook's own bound cuts and marks
+ * exactly as {@link normalizeDetail} does.
+ *
  * `String.prototype.slice` cuts at a fixed unit index, which can land between the
  * two halves of a surrogate pair and emit a lone surrogate — a terminal paints
  * that as a replacement character, so the cap would corrupt the very tail it is
@@ -35,10 +54,19 @@ export const DETAIL_MAX_LENGTH = 120;
  * measurement would claim knowledge of the renderer's font metrics that the
  * harness does not have — the host measures columns, because only the host knows
  * how wide its own line is.
+ *
+ * A cut text carries `…` so that a reader can tell a shortened detail from a
+ * complete one. The mark costs one of the `max` code points, thus the cut goes to
+ * `max - 1`: a hard bound that overshoots by the width of its own mark is not a
+ * hard bound. `trimEnd` runs BEFORE the append, because a cut that lands on a
+ * space must give `word…` and not `word …`.
  */
-function capCodePoints(text, max) {
+export function capCodePoints(text, max) {
     const points = Array.from(text);
-    return points.length <= max ? text : points.slice(0, max).join("").trimEnd();
+    if (points.length <= max)
+        return text;
+    const cut = points.slice(0, max - 1).join("");
+    return `${cut.trimEnd()}…`;
 }
 /**
  * Normalize whatever a hook returned into an emittable detail, or `undefined`.
@@ -78,8 +106,12 @@ export function normalizeDetail(raw) {
  * second time from the repaired value costs more than the case is worth.
  */
 export function computeDetail(tool, rawInput, log) {
+    // The guard tests for a function, not for presence. A packaged tool comes from
+    // an open list — an embedder contributes its own through the host-tools seam —
+    // so a `describeCall` that is not callable is reachable. Such a tool counts as
+    // undescribed, because the alternative is a TypeError on every one of its calls.
     const describeCall = tool.describeCall;
-    if (describeCall === undefined)
+    if (typeof describeCall !== "function")
         return undefined;
     try {
         // The parse is INSIDE the guard, not before it. `safeParse` returns an

package/dist/loop/types.d.ts

@@ -81,6 +81,19 @@ export type EmitEvent = {
     readonly outcome: ToolOutcome;
     /** The same detail the matching `tool-started` carried. */
     readonly detail?: ToolCallDetail;
+    /**
+     * The time around this call's own dispatch, in milliseconds.
+     *
+     * A host cannot measure this itself. The loop emits every
+     * `tool-started` of a round before it dispatches anything, and every
+     * `tool-finished` after the round settles. Thus a host that brackets
+     * the two events measures the round, and each call of a multi-call
+     * round reports the same figure.
+     *
+     * The field is optional, and it is absent when no measurement was
+     * taken. As a result a host can fall back to its own observation.
+     */
+    readonly durationMs?: number;
 };
 /**
  * A UI presentation event a tool streams to chat — an AI-SDK `data-*`

package/dist/memory/thread-history.d.ts

@@ -161,6 +161,16 @@ export interface ThreadHistory {
      * empty thread reports `empty-thread`.
      */
     retractLastTurn(threadId: string): ResultAsync<RetractOutcome, DbError>;
+    /**
+     * The greatest `messages.seq` in the thread, or `null` when the thread holds
+     * no messages. The read takes no lock: it reports the tail at the read
+     * moment, and a concurrent append can move the tail one row later.
+     *
+     * `appendTurn` computes the same value under its lock to place the next row.
+     * This read shares the table, not that statement. A lock here buys a caller
+     * no guarantee, because the tail can move one append later without it.
+     */
+    latestSeq(threadId: string): ResultAsync<number | null, DbError>;
 }
 /**
  * Drop the memoized instruments so the next `loadRecent` rebinds to a

package/dist/memory/thread-history.js

@@ -418,5 +418,16 @@ export function createThreadHistory(pool) {
             return tryMutation("thread-history.retractLastTurn.delete", () => client.query("DELETE FROM messages WHERE thread_id = $1 AND seq >= $2::bigint", [threadId, boundary])).map((res) => ({ kind: "retracted", messages: res.rowCount ?? 0 }));
         }));
     }
-    return { appendTurn, loadRecent, loadPage, retractLastTurn };
+    function latestSeq(threadId) {
+        // `MAX(seq)` over no rows is SQL NULL, so a thread with no messages reads
+        // as `null`, not as a seq — the absence a caller reads before it treats
+        // the value as an anchor. The `::text` cast carries a seq past 2^53 across
+        // the driver intact, the way every other read of this bigint column does,
+        // and `Number` makes the crossing in one place.
+        return tryQuery("thread-history.latestSeq", () => pool.query("SELECT MAX(seq)::text AS max_seq FROM messages WHERE thread_id = $1", [threadId])).map(({ rows }) => {
+            const maxSeq = rows[0]?.max_seq ?? null;
+            return maxSeq === null ? null : Number(maxSeq);
+        });
+    }
+    return { appendTurn, loadRecent, loadPage, retractLastTurn, latestSeq };
 }

package/dist/memory/thread-store.d.ts

@@ -22,10 +22,10 @@
  * row and the thread reads as it did; a listing widened with `includeArchived`
  * is the only way to obtain the id it takes, so the recovery is reachable by a
  * host that holds no thread ids it obtained elsewhere.
- * `purgeThread` is not recoverable: it removes the `messages` rows and the
- * metadata rows of the whole subtree in one transaction, so a failure partway
- * leaves both — never a thread stripped of its transcript, nor a transcript
- * with nothing naming it. It is the thread-scoped member of this package's
+ * `purgeThread` is not recoverable: it removes the `messages` rows, the report
+ * session-state rows, and the metadata rows of the whole subtree in one
+ * transaction, so a failure partway leaves them all — never a thread stripped of
+ * its transcript, nor a transcript with nothing naming it. It is the thread-scoped member of this package's
  * reclamation vocabulary — `purgeAnalysis` reclaims an analysis's whole
  * persisted footprint, `purgeThread` one subtree's.
  *