humanish 0.105.0 → 0.106.1

package/dist/routes/terminal/live-finish.js

@@ -0,0 +1,215 @@
+// Finishing a live terminal session: the actor trace from the captured stream, the spend ledger
+// and its caps check, the evidence files, the bundle, and the lab result.
+import { buildRunCostSummary } from "../../run/cost-summary.js";
+import { writeContainedOutputFile } from "../../run/contained-output.js";
+import { validatePreparedRunArtifactPaths, } from "../../run/paths.js";
+import { estimateActorCost } from "../../run/pricing.js";
+import { normalizeLocalActorTranscript, TERMINAL_EVENTS_ARTIFACT, TERMINAL_LEDGERS_ARTIFACT, TERMINAL_TRANSCRIPT_ARTIFACT, } from "../../run/terminal-contract.js";
+import { applyAdapterExtensionSeam } from "./adapter.js";
+import { buildLiveTerminalProductBundle } from "./bundle.js";
+import { buildCostLedger, buildNoSpendProof, describeMeasuredSpend, evaluateCapsAgainstLedger, noSpendLineMeasured, noSpendNotEstablished, } from "./ledger.js";
+import { foldScorerFailures, judgeExecution, judgeTerminal, OUTCOME_POLICIES, } from "../../run/judge.js";
+import { terminalExecutionFailures, terminalLabResult, terminalParticipantFacts, } from "./result.js";
+import { parseTerminalTokenUsage } from "./token-usage.js";
+import { buildTerminalActorTrace, scrubSplitKnownValues, tailOf } from "./trace.js";
+function buildLiveTrace(inputs) {
+    const { persona, sanitize, nowIso, runtimeEnv, runtime, knownSecretValues } = inputs;
+    const { product } = inputs.plan;
+    const { session } = inputs;
+    const { createdAt } = inputs.run;
+    const { terminalEvents, commandLog, discardedPrefixes } = inputs.recorder;
+    // Prefix reconciliation may cut through a known key. Scrub literal values across the retained
+    // chunks before any transcript/trace/event artifact is persisted. Check both each stream and
+    // the combined event order that the transcript uses; either view can assemble a split value.
+    scrubSplitKnownValues(terminalEvents, knownSecretValues, discardedPrefixes);
+    // Build the actor trace FIRST (the cost ledger reads its tokenUsage).
+    const normalizedTranscript = normalizeLocalActorTranscript(terminalEvents.map((e) => e.chunk).join(""));
+    // Parsed from the FULL stream, not the tail: usage records arrive once per turn and the tail
+    // would drop all but the last (#531).
+    const terminalTokenUsage = parseTerminalTokenUsage(normalizedTranscript);
+    const trace = buildTerminalActorTrace({
+        persona,
+        productName: product.name,
+        status: session.status,
+        completionReason: session.completionReason,
+        reason: sanitize(session.reason),
+        createdAt,
+        completedAt: nowIso(),
+        durationMs: commandLog[0]?.durationMs ?? 0,
+        terminalEvents,
+        commandLog,
+        transcriptTail: tailOf(normalizedTranscript),
+        runtimeAuth: runtimeEnv.mode,
+        runtime,
+        ...(terminalTokenUsage === undefined ? {} : { tokenUsage: terminalTokenUsage }),
+    });
+    // Codex tokens stay unpriced: the lane records its model as `codex`, which has no rate.
+    trace.estimatedCost = estimateActorCost(trace.tokenUsage, trace.provider);
+    return { normalizedTranscript, trace };
+}
+async function settleLiveLedgers(inputs, trace, normalizedTranscript) {
+    const { hooks, runtime, session } = inputs;
+    const { caps } = inputs.plan;
+    const { maxUsd } = caps;
+    const runPaths = inputs.run.paths;
+    const { recordLifecycle, lifecycle, commandLog, interventions, terminalEvents } = inputs.recorder;
+    // --- Spend ledger + no-spend proof + full caps enforcement (fail-closed). ---
+    // The cost ledger is DERIVED, with the null discipline: provider spend from the trace's
+    // tokenUsage.costUsd when present (else null = NOT MEASURED), product/media/payment null by
+    // default (core has no signal). The costProbe hook lets tests or adapters inject KNOWN
+    // spend to exercise the fail-closed cap without a real billable run.
+    const injectedLines = hooks.costProbe?.(trace.tokenUsage?.costUsd === undefined ? {} : { tokenCostUsd: trace.tokenUsage.costUsd });
+    if (hooks.costProbe)
+        await validatePreparedRunArtifactPaths(runPaths);
+    const cost = buildCostLedger({
+        ...(trace.tokenUsage?.costUsd === undefined ? {} : { tokenCostUsd: trace.tokenUsage.costUsd }),
+        ...(trace.tokenUsage === undefined ? {} : { tokenUsage: trace.tokenUsage }),
+        ...(injectedLines ? { injectedLines } : {}),
+    });
+    const noSpendProof = buildNoSpendProof(cost, maxUsd ?? null, trace.tokenUsage);
+    const proofVerdict = !noSpendProof.satisfied
+        ? `No-spend proof NOT satisfied for maxUsd=${maxUsd ?? "null"}.`
+        : noSpendLineMeasured(noSpendProof)
+            ? noSpendNotEstablished(maxUsd ?? 0)
+            : `No-spend proof satisfied on the measured lines for maxUsd=${maxUsd ?? "null"}.`;
+    const measuredSpend = describeMeasuredSpend(cost, trace.tokenUsage);
+    recordLifecycle("terminal-lab.cost.measured", `Cost ledger: known total ${cost.knownTotalUsd} USD${cost.fullyMeasured ? " (fully measured)" : " (lower bound)"}.${measuredSpend.length > 0 ? ` ${measuredSpend}` : ""} ${proofVerdict}`);
+    // FULL caps enforcement (fail-closed, NOT advisory): if a KNOWN spend line exceeds maxUsd (or a
+    // known job count exceeds maxJobs), the run fails closed — never a green result. Unknowns (null)
+    // do NOT trip the cap (we cannot claim a violation we did not measure) but never grant a pass
+    // either (the no-spend proof reports them as unmeasured). maxMinutes is already wall-clock-
+    // enforced above. A blown cap is an execution failure: the agent's own status stays the
+    // verdict, and the result's ok is false.
+    const capCheck = evaluateCapsAgainstLedger(cost, caps);
+    const capFailure = capCheck.ok ? undefined : capCheck.message;
+    if (capFailure !== undefined)
+        recordLifecycle("terminal-lab.caps.exceeded", capFailure);
+    // Assemble + persist the ledgers (now carrying the cost block + no-spend proof), the redacted
+    // event stream, the normalized transcript, the actor trace, and the run bundle.
+    const ledgers = {
+        schema: "humanish.terminal-ledgers.v1",
+        runtime,
+        lifecycle,
+        commandLog,
+        interventions, // ALWAYS present, ALWAYS empty while no assisted-input path ships.
+        cleanup: session.cleanup,
+        cost,
+        noSpendProof,
+    };
+    await writeTerminalEvidence(runPaths, { terminalEvents, normalizedTranscript, ledgers, trace });
+    return { cost, noSpendProof, capFailure, ledgers };
+}
+export async function finishLiveTerminalSession(inputs) {
+    const { normalizedTranscript, trace } = buildLiveTrace(inputs);
+    const { cost, noSpendProof, capFailure, ledgers } = await settleLiveLedgers(inputs, trace, normalizedTranscript);
+    const { plan, input, cwd, hooks, sanitize } = inputs;
+    const { product, caps } = plan;
+    const policies = plan.residual.policies;
+    const { runtimeEnv, persona, mission, run, source, warnings, session } = inputs;
+    const { runId, createdAt, paths: runPaths } = run;
+    // One judgment, after a blown cap has overridden the session: the bundle's verdict (and so
+    // status.json's outcome) and the result's ok both read it.
+    const participant = terminalParticipantFacts(trace, session.error);
+    const judgment = judgeTerminal({ dryRun: false, participant });
+    // The run cost summary, as the computer-use route records it: the sandbox's compute time from
+    // its span and observed size, and the participant's tokens (unpriced for Codex). It is not part
+    // of the cap ledger above, whose lines sum against scenario.caps.maxUsd.
+    const desktops = session.runCostDesktops();
+    const runCost = buildRunCostSummary({
+        participants: [{ trace }],
+        ...(desktops === undefined ? {} : { desktops }),
+    });
+    const bundle = buildLiveTerminalProductBundle({
+        ...(plan.lab === undefined ? {} : { lab: plan.lab }),
+        actorId: plan.actor,
+        createdAt,
+        labId: plan.labId,
+        ...(plan.title ? { labTitle: plan.title } : {}),
+        mission: sanitize(mission),
+        persona,
+        productName: product.name,
+        publicSurfaces: product.publicSurfaces,
+        caps,
+        runtimeAuthKeyName: runtimeEnv.keyName,
+        runtimeAuth: runtimeEnv.mode,
+        policies: {
+            allowPrivateRepoAccess: policies?.allowPrivateRepoAccess ?? false,
+            allowProviderCredentials: policies?.allowProviderCredentials ?? false,
+            allowPaymentCredentials: policies?.allowPaymentCredentials ?? false,
+            allowGitHubMutation: policies?.allowGitHubMutation ?? false,
+        },
+        runId,
+        source,
+        trace,
+        ledgers,
+        ...(runCost === undefined ? {} : { cost: runCost }),
+        sessionReason: sanitize(session.reason),
+        verdict: judgment.verdict,
+        ...(capFailure === undefined ? {} : { capFailure }),
+    });
+    // The adapter extension seam. A registered scorer reads the fully assembled, redacted evidence
+    // without core knowing any product noun: its namespaced RunAdapterScore lands on
+    // bundle.adapterScore, and its feedback candidates are appended to bundle.feedbackCandidates.
+    // The score does not replace the judged verdict, but a failing or malformed scorer fails the run
+    // through foldScorerFailures below. Adapter payloads pass the same scrub and redaction as the
+    // rest of the bundle, and the bundle verifier checks them downstream.
+    const scorer = await applyAdapterExtensionSeam({
+        hooks,
+        bundle,
+        trace,
+        ledgers,
+        transcript: normalizedTranscript,
+        product: product.name,
+        labId: plan.labId,
+        runId,
+        sanitize,
+        warnings,
+        ...(input.scorerProvenance === undefined ? {} : { scorerProvenance: input.scorerProvenance }),
+    });
+    // The one final verdict fold: scoring can only make the judged verdict stricter.
+    bundle.review = foldScorerFailures(bundle.review, scorer.failures);
+    await validatePreparedRunArtifactPaths(runPaths);
+    const finished = await run.finish(bundle);
+    const observer = await finished.renderObserver();
+    await validatePreparedRunArtifactPaths(runPaths);
+    // A failing agent is captured evidence on this route: only the execution and a declared scorer
+    // fail ok.
+    const execution = judgeExecution(terminalExecutionFailures({
+        participant,
+        capFailure,
+        sessionReason: sanitize(session.reason),
+        cleanup: session.cleanup,
+        observer,
+    }), OUTCOME_POLICIES.terminal);
+    const result = terminalLabResult({
+        cwd,
+        labId: plan.labId,
+        actorId: plan.actor,
+        productName: product.name,
+        runId,
+        sessionStatus: session.status,
+        completionReason: session.completionReason,
+        sessionReason: sanitize(session.reason),
+        sessionError: session.error,
+        sandboxId: session.sandboxId,
+        cleanup: session.cleanup,
+        cost,
+        noSpendProof,
+        capFailure,
+        declaredScorerFailure: scorer.failures[0],
+        judgment,
+        execution,
+        observer,
+        warnings,
+    });
+    await finished.recordOutcome({ ok: result.ok, execution });
+    return result;
+}
+/** Persist the terminal evidence: redacted events, normalized transcript, ledgers, actor trace. */
+async function writeTerminalEvidence(runPaths, evidence) {
+    const { terminalEvents, normalizedTranscript, ledgers, trace } = evidence;
+    await writeContainedOutputFile(runPaths, TERMINAL_EVENTS_ARTIFACT, `${terminalEvents.map((e) => JSON.stringify(e)).join("\n")}${terminalEvents.length > 0 ? "\n" : ""}`, "utf8");
+    await writeContainedOutputFile(runPaths, TERMINAL_TRANSCRIPT_ARTIFACT, `${normalizedTranscript}\n`, "utf8");
+    await writeContainedOutputFile(runPaths, TERMINAL_LEDGERS_ARTIFACT, `${JSON.stringify(ledgers, null, 2)}\n`, "utf8");
+    await writeContainedOutputFile(runPaths, "actor.json", `${JSON.stringify(trace, null, 2)}\n`, "utf8");
+}

package/dist/routes/terminal/live-sandbox.d.ts

@@ -0,0 +1,70 @@
+import type { ActorCompletionReason, ActorStatus } from "../../actors/contract.js";
+import { type DesktopUsage } from "../../run/cost-summary.js";
+import type { RunScope } from "../../run/run.js";
+import type { buildRuntimeAuth, buildSandboxMetadata } from "./credentials.js";
+import type { createTerminalRecorder } from "./recorder.js";
+import { type declaredRuntimeProvenance } from "./runtime.js";
+import { type LiveTerminalPlan, type TerminalLedgers, type TerminalProductLabHooks } from "./types.js";
+type StartedRun = Extract<Awaited<ReturnType<RunScope["startRun"]>>, {
+    ok: true;
+}>["run"];
+/** What the sandbox session reads from the run. */
+export interface LiveSandboxInputs {
+    plan: LiveTerminalPlan;
+    cwd: string;
+    hooks: TerminalProductLabHooks;
+    now: () => number;
+    nowIso: () => string;
+    sanitize: (text: string) => string;
+    runtimeEnv: Extract<ReturnType<typeof buildRuntimeAuth>, {
+        ok: true;
+    }>;
+    /** The runtime provenance; the version check records what it observed. */
+    runtime: ReturnType<typeof declaredRuntimeProvenance>;
+    composedPrompt: string;
+    verdictNonce: string;
+    maxMinutes: number;
+    e2bApiKey: string;
+    runPaths: StartedRun["paths"];
+    metadata: ReturnType<typeof buildSandboxMetadata>;
+    /** The run's warnings. Steps append to them. */
+    warnings: string[];
+    recorder: ReturnType<typeof createTerminalRecorder>;
+}
+export declare class LiveTerminalSandbox {
+    status: ActorStatus;
+    completionReason: ActorCompletionReason;
+    reason: string;
+    error: string | undefined;
+    timedOut: boolean;
+    sandboxId: string | undefined;
+    cleanup: TerminalLedgers["cleanup"];
+    private readonly inputs;
+    private readonly requestTimeoutMs;
+    private readonly wallClockMs;
+    private readonly sandboxTimeoutMs;
+    private sandbox;
+    private module;
+    private allocation;
+    private startupCleanup;
+    private startupCleanupDetail;
+    private createdAtMs;
+    private tornDownAtMs;
+    private resources;
+    constructor(inputs: LiveSandboxInputs);
+    acquire(): Promise<void>;
+    probeReady(): Promise<void>;
+    /** Returns false when the runtime bootstrap failed; the session then fails closed. */
+    bootstrap(): Promise<boolean>;
+    /** Returns false when the observed Codex version is missing or not the requested one. */
+    verifyRuntimeVersion(): Promise<boolean>;
+    /** Returns false when the declared product upload or install could not prepare the world. */
+    prepareProduct(): Promise<boolean>;
+    execCodex(): Promise<void>;
+    /** Records a failure of the session around the steps (not one a step already recorded). */
+    recordSessionError(error: unknown): void;
+    teardown(): Promise<void>;
+    /** The sandbox's compute time for the run cost summary, when a sandbox was acquired. */
+    runCostDesktops(): DesktopUsage[] | undefined;
+}
+export {};