@inflexa-ai/harness 0.19.2 → 0.21.0

package/dist/tools/report-authoring/authoring-tools.js

@@ -17,27 +17,33 @@
  * nested union. A conflict between the flat fields refuses before the core runs.
  */
 import { err, ok } from "neverthrow";
+import { basename } from "node:path";
 import { z } from "zod";
+import { capCodePoints, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
 import { isSafeId } from "../../workspace/paths.js";
 import { addBlock, changeBlock, locate, moveBlock, removeBlock, setTitle, } from "../../report-model/draft-operations.js";
 import { buildOutline, childOutline, readBlock } from "../../report-model/draft-read.js";
 import { finishDraft } from "../../report-model/draft-finish.js";
-import { DraftBlockSchema } from "../../report-model/draft.js";
+import { AuthoringBlockSchema } from "../../report-model/authoring-grammar.js";
 import { defineTool } from "../define-tool.js";
 /**
  * The block payload.
  *
- * The published JSON Schema carries the whole draft grammar, because a tool is self-describing at attach
- * time and the schema is the only place where the model learns the shape of the eight block kinds. A bare
- * `z.unknown()` emits the empty schema, which tells the model nothing and leaves it to discover each
+ * The published JSON Schema carries the whole authoring grammar, because a tool is self-describing at
+ * attach time and the schema is the only place where the model learns the shape of the eight block kinds.
+ * A bare `z.unknown()` emits the empty schema, which tells the model nothing and leaves it to discover each
  * required field through one refusal at a time.
  *
+ * The grammar is the authoring one, thus no artifact reference of the published schema carries a hash. The
+ * pinned snapshot owns that value, and the land path stamps it from the path.
+ *
  * The `z.unknown()` member keeps the runtime parse permissive. Thus a malformed payload still reaches the
- * core, which parses it with the same grammar and refuses `malformed-block` as typed data in the ok
+ * core, which parses it with the draft grammar and refuses `malformed-block` as typed data in the ok
  * channel. A strict input schema would turn that designed refusal into a hard input-validation error from
- * the loop.
+ * the loop. A payload that carries a hash rides the same arm, and the stamp drops the value before the
+ * parse.
  */
-const blockPayload = z.union([DraftBlockSchema, z.unknown()]);
+const blockPayload = z.union([AuthoringBlockSchema, z.unknown()]);
 /**
  * A flat field that the model can leave out.
  *
@@ -119,7 +125,14 @@ export async function openReportThread(gateway, scope) {
             detail: `the scope names the analysis ${analysisId}, but the thread ${threadId} belongs to the analysis ${loaded.analysisId}`,
         });
     }
-    return ok({ threadId, analysisId, state: loaded.state, token: loaded.token, seenDocumentHash: loaded.seenDocumentHash });
+    return ok({
+        threadId,
+        analysisId,
+        state: loaded.state,
+        token: loaded.token,
+        seenDocumentHash: loaded.seenDocumentHash,
+        derivations: loaded.derivations,
+    });
 }
 /** Read an absentable field. An explicit `null` and an omitted key both mean that the model gave no value. */
 function given(value) {
@@ -208,15 +221,75 @@ function readKind(block) {
 function readId(block) {
     return readStringField(block, "id");
 }
+/** Read one field of an untyped payload, or `undefined` when the payload is not an object. */
+function fieldOf(value, field) {
+    return value !== null && typeof value === "object" ? value[field] : undefined;
+}
 function readStringField(block, field) {
-    if (block !== null && typeof block === "object") {
-        const value = block[field];
-        if (typeof value === "string") {
-            return value;
+    const value = fieldOf(block, field);
+    return typeof value === "string" ? value : undefined;
+}
+/** The pinned path of an untyped reference payload, or `undefined` when it names none. */
+function referencePath(reference) {
+    const path = readStringField(reference, "path");
+    return path === undefined || path.length === 0 ? undefined : path;
+}
+/**
+ * The artifact path that an untyped block payload binds, or `undefined` when the kind binds no path.
+ *
+ * Where a reference sits differs per kind, thus the walk reads the one field of each kind and never
+ * searches the payload. A claim can hold a citation first, which names no path, thus the walk takes the
+ * first binding that names one. A metric holds a scalar reference, and a derivation holds its own two
+ * inputs, thus the first input names the derived value. A text block, a citation block, and a section
+ * bind no artifact at all.
+ *
+ * The payload is model-authored and unvalidated here, thus each read is a guarded read and a wrong shape
+ * gives `undefined`.
+ */
+function boundArtifactPath(kind, block) {
+    if (kind === "table" || kind === "chart" || kind === "figure") {
+        return referencePath(fieldOf(block, "binding"));
+    }
+    if (kind === "claim") {
+        const bindings = fieldOf(block, "bindings");
+        if (!Array.isArray(bindings)) {
+            return undefined;
         }
+        for (const binding of bindings) {
+            const path = referencePath(binding);
+            if (path !== undefined) {
+                return path;
+            }
+        }
+        return undefined;
+    }
+    if (kind === "metric") {
+        const value = fieldOf(block, "value");
+        const direct = referencePath(value);
+        if (direct !== undefined) {
+            return direct;
+        }
+        const inputs = fieldOf(value, "inputs");
+        return Array.isArray(inputs) ? referencePath(inputs[0]) : undefined;
     }
     return undefined;
 }
+/**
+ * The subject that names one added block: the title of a section in quotes, or the file name of the
+ * artifact that the block binds. A block that names neither gives no subject, and the kind stands alone.
+ *
+ * The title is model-authored text of no fixed length, thus the needle bound cuts it before the emit-site
+ * cap can cut the quote that closes it. The file name is the base name alone, because the directory
+ * segments of an analysis path repeat across every block and the file name is what tells two apart.
+ */
+function addedSubject(kind, block) {
+    if (kind === "section") {
+        const title = readStringField(block, "title");
+        return title === undefined || title.length === 0 ? undefined : `"${capCodePoints(title, DETAIL_NEEDLE_MAX_LENGTH)}"`;
+    }
+    const path = boundArtifactPath(kind, block);
+    return path === undefined ? undefined : basename(path);
+}
 /**
  * The id of the section that holds a block, or `undefined` when the block sits at the root.
  *
@@ -299,12 +372,18 @@ export function createReportAuthoringTools(gateway) {
         description: "Add one block to the draft. The `block` schema gives the eight kinds and the fields of each one. " +
             "You choose the `id` of the block, and it must be unique in the draft. " +
             "Name the destination with `parentId` and one of `place`, `before`, or `after`. " +
-            "The root admits a section only, and an atom needs a section as its parent.",
+            "The root admits a section only, and an atom needs a section as its parent. " +
+            "A reference names the path of a pinned artifact, and the session stamps the hash from the pinned evidence.",
         inputSchema: addBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => {
-            const kind = readKind(decodeBlockPayload(input.block));
-            return kind !== undefined ? `add ${kind}` : "add a block";
+            const block = decodeBlockPayload(input.block);
+            const kind = readKind(block);
+            if (kind === undefined) {
+                return "add a block";
+            }
+            const subject = addedSubject(kind, block);
+            return subject === undefined ? `add ${kind}` : `add ${kind} ${subject}`;
         },
         execute: async (input, ctx) => {
             const opened = await openThread(ctx);
@@ -324,7 +403,8 @@ export function createReportAuthoringTools(gateway) {
     const change_block = defineTool({
         id: "change_block",
         description: "Change one block by its id. Give a `title` to retitle a section, or a `block` to replace an atom, and never both. " +
-            "The change keeps the id of the target, thus the `id` of the payload does not matter. A kind change is permitted.",
+            "The change keeps the id of the target, thus the `id` of the payload does not matter. A kind change is permitted. " +
+            "A reference names the path of a pinned artifact, and the session stamps the hash from the pinned evidence.",
         inputSchema: changeBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `change ${input.targetId}`,
@@ -416,7 +496,8 @@ export function createReportAuthoringTools(gateway) {
     });
     const read_block = defineTool({
         id: "read_block",
-        description: "Read one block by its id. An atom gives the full block with its bindings. A section gives its title and the id of each child, " +
+        description: "Read one block by its id. An atom gives the full block with its bindings. A binding gives its path and no hash, " +
+            "because the session owns the hash. A section gives its title and the id of each child, " +
             "because the outline already names every block under it. Use it when the outline label is not enough.",
         inputSchema: readBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
@@ -444,7 +525,7 @@ export function createReportAuthoringTools(gateway) {
             if (opened.isErr()) {
                 return ok({ refused: opened.error });
             }
-            return ok(finishDraft(opened.value.state.document, opened.value.state.snapshot));
+            return ok(finishDraft(opened.value.state.document, opened.value.state.snapshot, opened.value.derivations));
         },
     });
     return {

package/dist/tools/report-session/derive-table.d.ts

@@ -0,0 +1,162 @@
+/**
+ * The derivation tool of a report session.
+ *
+ * A run writes statistical tables, and not plot-ready ones. This tool reshapes the pinned evidence into one
+ * table that a block can bind: a join, a pivot, or an aggregate. The agent writes the script, and the record
+ * chains the derived table back to the evidence that made it.
+ *
+ * A session derivation is not an analysis run. It mints no run id, it registers no artifact, and it writes
+ * under the session directory alone. The rails are the rails of the value tier (`tasks/extract-values.ts`):
+ * the sandbox client, the identity mint, and the authorizer on every terminal path. The container is
+ * ephemeral, and it goes away with the work.
+ *
+ * The container mounts the analysis tree read-only, and one write mount covers the `derived/` directory of
+ * the session alone. The script writes its table into that mount directly, thus a large table makes no
+ * roundtrip and no write of the script can reach the workspace tree. The working directory of the exec is
+ * that same mount, and the standard output carries the logs of the script alone.
+ *
+ * The host then reads the file that the container wrote. A path inside the mount is still untrusted bytes: a
+ * script can leave a symbolic link in place of its output. Thus the host classifies the file against the
+ * workspace root before it hashes one byte, and an escape refuses as typed data.
+ *
+ * Each declared input must sit in the served membership, and its hash comes from there. The declaration is
+ * what the record pins, thus a derived cell traces to a pinned artifact and to the script that read it.
+ *
+ * The tool refuses an output name that the membership already holds. A record is immutable, and a second
+ * derivation of one table takes a new name.
+ *
+ * A composition with no sandbox client and no run authorizer cannot derive at all. The tool reports that
+ * condition one time, up front, the same discipline as the eyes. A per-attempt failure would instead read as
+ * a transient fault, and it would invite a repeat of a call that can never pass.
+ *
+ * The transport of the client is the second such bound. A derivation runs inside one live turn and not
+ * inside a workflow body. The poll transport awaits with plain steps and a plain sleep, thus it settles
+ * there. The callback transport awaits through `DBOS.recv`, which a workflow body alone can call, thus this
+ * tool refuses up front under it rather than start a container that nothing can await.
+ */
+import { z } from "zod";
+import type { RunAuthorizer } from "../../execution/run-authorizer.js";
+import { type Logger } from "../../lib/logger.js";
+import type { SandboxClient } from "../../sandbox/client.js";
+import type { ExecResult, SubmitExecBody } from "../../sandbox/types.js";
+import type { DerivationSource, ReportSessionStateStore } from "../../state/report-session-state.js";
+import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
+import { type Tool } from "../define-tool.js";
+import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+/** The input of one derivation: the script, the declared pinned inputs, and the name of the output file. */
+declare const deriveTableInput: z.ZodObject<{
+    script: z.ZodString;
+    inputs: z.ZodArray<z.ZodString>;
+    output: z.ZodString;
+}, z.core.$strip>;
+export type DeriveTableInput = z.infer<typeof deriveTableInput>;
+/**
+ * The typed outcome of the derivation tool. Each arm is ok-channel data, thus the tool never throws for one
+ * of them.
+ *
+ * `derived` carries the workspace-relative path of the derived table, its content hash, the hash of the
+ * script, the sources that the record pins, and the header columns of the output. Each other arm names a
+ * condition that the agent repairs: a call that is out of bounds, an input that the membership does not
+ * hold, a name that a record already holds, a script that failed in the container, and a green script that
+ * left no file at the output name.
+ */
+export type DeriveTableResult = {
+    outcome: "refused";
+    refusal: SessionRefusal;
+} | {
+    outcome: "unavailable";
+    detail: string;
+} | {
+    outcome: "script-too-large";
+    bytes: number;
+    cap: number;
+    detail: string;
+} | {
+    outcome: "too-many-inputs";
+    count: number;
+    cap: number;
+    detail: string;
+} | {
+    outcome: "unsafe-name";
+    detail: string;
+} | {
+    outcome: "absent-input";
+    path: string;
+    detail: string;
+} | {
+    outcome: "repeated-name";
+    outputPath: string;
+    detail: string;
+} | {
+    outcome: "exec-failed";
+    detail: string;
+} | {
+    outcome: "no-output";
+    detail: string;
+} | {
+    outcome: "derived";
+    path: string;
+    hash: string;
+    scriptHash: string;
+    sources: DerivationSource[];
+    columns?: string[];
+};
+/**
+ * The construction deps of the derivation tool.
+ *
+ * `derivations` is the append side of the durable session state, thus the record lands beside the document
+ * and the pin. `sandboxClient` and `runAuthorizer` are the two rails of the exec, and a composition that
+ * binds neither leaves the session with no derivation at all. `resolveWorkspaceRoot` maps the analysis of
+ * the call onto its workspace root, thus one singleton tool serves every analysis.
+ */
+export interface DeriveTableToolDeps {
+    readonly gateway: ReportSessionStateGateway;
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    readonly derivations: Pick<ReportSessionStateStore, "appendDerivation">;
+    readonly sandboxClient?: SandboxClient;
+    readonly runAuthorizer?: RunAuthorizer;
+    readonly logger?: Logger;
+}
+/** The environment variable that carries the declared inputs into the container. */
+export declare const DERIVE_INPUT_ENV = "DERIVE_INPUTS";
+/** The environment variable that carries the container path of the output file into the container. */
+export declare const DERIVE_OUTPUT_ENV = "DERIVE_OUTPUT";
+/** One declared input, as the container reads it: the mounted path of the file, and its pinned hash. */
+export interface DerivationInputMount {
+    readonly path: string;
+    readonly hash: string;
+}
+/**
+ * Build the sandbox exec of one derivation. The command runs the script of the agent through `python3 -c`.
+ *
+ * The working directory is the write mount, thus the script writes its table beside where it stands. Each
+ * declared input rides as its mounted path, thus the script opens the file wherever it works from. The
+ * output path rides too, thus the script names no directory of its own.
+ *
+ * The function is pure, thus a test asserts the command shape without a sandbox.
+ */
+export declare function buildDerivationExec(args: {
+    readonly script: string;
+    readonly execId: string;
+    readonly workingDir: string;
+    readonly inputs: readonly DerivationInputMount[];
+    readonly output: string;
+}): SubmitExecBody;
+/**
+ * Give the failure of an exec result, or `undefined` when the script ran to a clean exit.
+ *
+ * A synthetic failure, a timeout, and a non-zero exit each mean that no table came back. The detail of a
+ * non-zero exit carries the tail of the standard error, thus the agent repairs the script from what the
+ * container reported.
+ *
+ * The function is pure, thus a test asserts the mapping without a sandbox.
+ */
+export declare function describeExecFailure(result: ExecResult): string | undefined;
+/**
+ * Make the derivation tool over the session-state gateway, the derivation ledger, and the sandbox rails.
+ *
+ * The tool reads the thread id from the scope of the call, and it loads the membership through the gateway.
+ * Thus one factory serves every thread, and the tool holds no per-session value.
+ */
+export declare function createDeriveTableTool(deps: DeriveTableToolDeps): Tool<DeriveTableInput, DeriveTableResult>;
+export {};