humanish 0.105.0 → 0.106.0

package/dist/e2b-terminal-lab.d.ts

@@ -1,383 +0,0 @@
-import { type AutomaticAnalysisHooks, type AutomaticAnalysisResult } from "./automatic-analysis-completion.js";
-import type { ActorRuntimeProvenance } from "./actor-contract.js";
-export { resolveCommittedPersona as resolveTerminalPersona } from "./persona-resolve.js";
-import type { ActorCompletionReason, ActorPersonaRef, ActorStatus, ActorTrace } from "./actor-contract.js";
-import { type RunLabProvenance } from "./run-status.js";
-import type { LabConfig, LabScenarioCaps, LabRuntimeAuth } from "./lab-config.js";
-import { type E2BDesktopModule } from "./e2b-desktop-launch.js";
-import { renderObserver, type ObserverResult } from "./observer.js";
-import { type RunAdapterScore, type RunBundle, type RunFeedbackCandidate, type RunScorerProvenance } from "./run.js";
-import { TERMINAL_AGENT_NOT_IMPLEMENTED_CODE } from "./terminal-agent-actor.js";
-/** Provider-neutral metadata constant: the lane's non-secret tag (mirrors CUA_ACTOR_LAB_PROVIDER_METADATA). */
-export declare const TERMINAL_PRODUCT_LAB_PROVIDER_METADATA: {
-    readonly mode: "terminal-product-lab";
-    readonly tool: "humanish";
-};
-export declare const TERMINAL_EVENTS_ARTIFACT = "terminal-events.ndjson";
-export declare const TERMINAL_TRANSCRIPT_ARTIFACT = "terminal-transcript.txt";
-export declare const TERMINAL_LEDGERS_ARTIFACT = "terminal-ledgers.json";
-export declare const TERMINAL_PRODUCT_LAB_SCHEMA = "humanish.terminal-lab-result.v1";
-/**
- * Library-level hooks: the DI seams that drive the full live path against a fake sandbox + mock
- * CLI at zero spend. The deterministic merge-gate test wires loadModule (a fake @e2b/desktop
- * module) + env (the operator key source) + now (an injected clock); the live rung uses none of
- * them (it loads the real module and reads the real environment).
- */
-/**
- * The read-only evidence a thin adapter's scorer/feedback hook sees (the layer-6 extension seam,
- * issue #154 acceptance #8). It is the FULLY-ASSEMBLED, redacted, verifiable evidence — the live run
- * bundle, the provider-neutral actor trace, and the persisted ledgers (substrate/command/
- * interventions/cleanup/cost/no-spend). Every member is an EXPORTED public type, so a thin adapter
- * types against `import("humanish")` alone — never a deep `src/` import. The adapter reads this
- * to score the product attempt and derive feedback; it cannot mutate core's evidence (the lane
- * attaches only the namespaced `RunAdapterScore` it returns + the feedback candidates it derives).
- */
-export interface TerminalProductScoringContext {
-    /** The assembled live run bundle (already redacted/scrubbed + verifiable). Read-only to the adapter. */
-    bundle: RunBundle;
-    /** The provider-neutral actor trace for the in-sandbox agent session. */
-    trace: ActorTrace;
-    /** The persisted terminal-product ledgers (lifecycle/command/interventions/cleanup/cost/no-spend). */
-    ledgers: TerminalLedgers;
-    /**
-     * The FULL normalized transcript of the in-sandbox agent session — scrubbed (literal known
-     * values) then redacted (shape patterns) AT THE SOURCE, capped at MAX_TRANSCRIPT_BYTES, and
-     * byte-identical to the persisted terminal-transcript.txt artifact. The trace's transcriptTail
-     * is a ~2KB projection of this; a scorer needs the whole session so a rubric can find
-     * command-tier evidence anywhere in it, not only in the tail window (#341).
-     */
-    transcript: string;
-    /** The studied product name (public-safe). */
-    product: string;
-    /** The lab id (the run's scenario scope). */
-    labId: string;
-    /** The run id (for building namespaced idempotency keys + evidence pointers). */
-    runId: string;
-}
-export interface TerminalProductLabHooks {
-    /** Lazy-load the E2B module (tests inject a fake; default loadE2BDesktopModule). */
-    loadModule?: () => Promise<E2BDesktopModule>;
-    /**
-     * The operator environment the lane reads the runtime key from (and from which it asserts no
-     * banned credential is requested). Defaults to process.env. The runtime key is injected ONLY
-     * into command-scoped `codex` env or an external header transform — NEVER Sandbox.create envs (the credential
-     * boundary); tests plant a fake key here and assert it never reaches metadata/global env/artifacts.
-     */
-    env?: Record<string, string | undefined>;
-    renderObserverFn?: typeof renderObserver;
-    /** Injected clock for deterministic timestamps + wall-clock arithmetic (tests only). */
-    now?: () => number;
-    /**
-     * Optional cost-ledger seam. Core has no product/media/payment spend signal, so it populates only
-     * the provider line from trace tokenUsage when present. Tests and adapters can inject KNOWN spend
-     * lines; absent signals retain the null-discipline default.
-     */
-    costProbe?: (context: {
-        tokenCostUsd?: number;
-    }) => Partial<Record<"product" | "media" | "payment" | "provider", CostLine>> | undefined;
-    /**
-     * THE LAYER-6 EXTENSION SEAM (issue #154 acceptance #8: "product-adapter hooks WITHOUT forking
-     * core"). A thin in-repo/out-of-tree adapter registers a product scorer here. The lane calls it
-     * (when provided) over the fully-assembled evidence and attaches the returned, ADAPTER-NAMESPACED
-     * `RunAdapterScore` to `bundle.adapterScore` WITHOUT core knowing any product noun (the score is
-     * namespaced + its component breakdown rides in `data`). When NO scorer is given, the default
-     * mission-based verdict (`review`) is unchanged. This is the SEAM the adopter's scorecard plugs
-     * into — NOT a built-in product scorer (that lives in the adopter's repo).
-     */
-    score?: (ctx: TerminalProductScoringContext) => RunAdapterScore | Promise<RunAdapterScore>;
-    /**
-     * Companion seam: derive product-feedback candidates from the same assembled evidence. The lane
-     * appends the returned candidates to `bundle.feedbackCandidates`. The adapter records its
-     * product-specific concepts (public CLI command observed, hosted success-or-blocker, feedback id,
-     * media/job ids, no-spend proof, defection/friction risk) under each candidate's ADAPTER-NAMESPACED
-     * `adapter` block — never as core enums (issue #154's "record product-specific concepts as
-     * NON-core nouns" list). The candidates must still satisfy core's feedback-candidate shape (which
-     * the bundle verifier enforces), so a malformed adapter candidate fails closed.
-     */
-    deriveFeedback?: (ctx: TerminalProductScoringContext) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
-}
-export interface RunTerminalProductLabOptions {
-    automaticAnalysis?: AutomaticAnalysisHooks;
-    /** Which manifest produced this run (#455); threaded into the status record + bundle. */
-    lab?: RunLabProvenance;
-    cwd: string;
-    config: LabConfig;
-    /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
-    dryRun: boolean;
-    open?: boolean;
-    runId?: string;
-    hooks?: TerminalProductLabHooks;
-    /**
-     * Present ONLY when the scorer hooks were CONFIG-DECLARED and loaded by the CLI (#316). Its presence
-     * is the "declared" marker: a config-declared terminal scorer returning status:"fail" FLIPS
-     * bundle.review.verdict (like the browser routes), and one that throws becomes a visible review.gaps
-     * entry. A LIBRARY caller passing `hooks` directly leaves this ABSENT and keeps today's purely
-     * additive terminal behavior (verdict unchanged). Core-computed, never adopter-supplied.
-     */
-    scorerProvenance?: RunScorerProvenance;
-}
-export interface TerminalProductLabResult extends AutomaticAnalysisResult {
-    schema: typeof TERMINAL_PRODUCT_LAB_SCHEMA;
-    /** True when the bundle verified AND (dry-run, or the live session reached a terminal verdict
-     *  without a harness error + cleanup was proven). The agent's pass/fail is evidence, not the
-     *  lab's exit code. */
-    ok: boolean;
-    cwd: string;
-    labId: string;
-    /** The registry-resolved actor id that ran (or would run) the session. */
-    actor: string;
-    /** The studied product name (public-safe). */
-    product: string;
-    dryRun: boolean;
-    runId: string;
-    /** Live-only: the in-sandbox agent session verdict (omitted on dry-run / pre-session failure). */
-    session?: {
-        status: ActorStatus;
-        completionReason: ActorCompletionReason;
-        reason: string;
-    };
-    /** Live-only: the sandbox lifecycle proof (the key/auth value is NEVER surfaced here). */
-    sandbox?: {
-        sandboxId: string;
-        killed: boolean;
-        /** BY-ID proof (never a re-list): 0 = confirmed reclaimed, 1 = still present (unconfirmed),
-         *  -1 = kill(id) itself failed or was unavailable. See TerminalLedgers["cleanup"]. */
-        remaining: number;
-    };
-    /** Live-only: the spend ledger surfaced on the result — unknowns are null, never guessed.
-     *  Lets a programmatic caller read spend without parsing the bundle. */
-    cost?: {
-        knownTotalUsd: number;
-        fullyMeasured: boolean;
-        /** Per-category USD: a known number, or null = NOT MEASURED (never coerced to 0). */
-        lines: Record<"product" | "media" | "payment" | "provider", number | null>;
-    };
-    /** Live-only: the no-spend proof DERIVED from the ledger. */
-    noSpend?: {
-        satisfied: boolean;
-        maxUsd: number | null;
-        knownZeroLines: string[];
-        unmeasuredLines: string[];
-    };
-    observer?: ObserverResult;
-    warnings: string[];
-    error?: {
-        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_TERMINAL_LAB_FAILED" | "HUMANISH_TERMINAL_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_TERMINAL_LAB_SUBJECT_INVALID" | "HUMANISH_TERMINAL_LAB_KEYPLACEMENT_INVALID" | "HUMANISH_TERMINAL_LAB_RUNTIME_AUTH_MISSING" | "HUMANISH_TERMINAL_LAB_CAPS_MISSING" | "HUMANISH_TERMINAL_LAB_CAPS_EXCEEDED" | "HUMANISH_TERMINAL_LAB_CREDENTIAL_DENIED" | "HUMANISH_TERMINAL_LAB_CLEANUP_UNPROVEN" | typeof TERMINAL_AGENT_NOT_IMPLEMENTED_CODE;
-        message: string;
-    };
-}
-/**
- * Wrapped so a DIRECT library caller gets the same status-record lifetime the CLI does: returning
- * from this function finalizes any record the run opened, whichever of its fail-closed exits it
- * took. `runLab` establishes a scope too and nesting is harmless — the inner scope owns what it
- * opened. Without this a test or an adopter calling the backend directly leaves the 5s cadence
- * ticking into a directory something else is deleting, which surfaces as an unrelated ENOTEMPTY.
- */
-export declare function runTerminalProductLab(options: RunTerminalProductLabOptions): Promise<TerminalProductLabResult>;
-/** Substrate lifecycle ledger entry (create/readiness/exec/cleanup events with timestamps). */
-export interface LifecycleRecord {
-    at: string;
-    event: string;
-    /** Redacted+scrubbed before persisting (it never carries a secret, but the harness never trusts that). */
-    message: string;
-}
-/** Command-log ledger entry: which command ran, with what exit/duration (NEVER its env values). */
-export interface CommandLogRecord {
-    at: string;
-    /** A public-safe label for the command (e.g. "codex-exec"); the full argv is bound by digest only. */
-    label: string;
-    /** sha256-12 of the exact command string — pins "same recipe" without persisting it. */
-    commandDigest: string;
-    /** The env var NAMES injected command-scoped (values NEVER persisted) — the credential evidence. */
-    envNames: string[];
-    exitCode?: number;
-    timedOut?: boolean;
-    durationMs: number;
-}
-/**
- * One operator intervention (assisted-input event). The current route ships NO assisted-input
- * path, so this ledger is ALWAYS empty — but always PRESENT (the safety contract: empty-present is
- * the contract, an absent ledger fails verify). A future assisted path can fill this shape.
- */
-export interface InterventionRecord {
-    at: string;
-    kind: "stdin";
-    /** Redacted+scrubbed digest of the injected input (never the raw bytes). */
-    inputDigest: string;
-}
-/**
- * One cost line of the spend ledger. THE NULL DISCIPLINE (issue #154, the cost/no-spend asks):
- * three distinct states are crisply modeled and NEVER conflated —
- *   - `usd: 0`     => KNOWN to be zero. A measured-and-zero spend (we metered this category and it
- *                     billed nothing). The no-spend proof may legitimately assert this is zero.
- *   - `usd: null`  => NOT MEASURED. This run carries no spend signal for the category. `null` is
- *                     written explicitly (never undefined-omitted, never guessed to 0). The no-spend
- *                     proof must list this line as UNMEASURED and must NOT claim it is zero.
- *   - line ABSENT  => NOT APPLICABLE to this lane/run (n/a). The line simply does not appear in
- *                     `lines`. (The current route emits all four lines, so absence is reserved for
- *                     future lanes that genuinely have no such category.)
- * `null` vs missing-key is the load-bearing distinction: a missing key means "this category does not
- * exist for this run"; a present key with `null` means "this category exists but we did not measure
- * it". A no-spend proof that claimed zero on a `null` line would claim more than it measured.
- */
-export interface CostLine {
-    /** known zero (0) | not measured (null). The key is ALWAYS present when the line is applicable. */
-    usd: number | null;
-    /** Optional billable-unit count, same discipline: a known count, or null = not measured. */
-    count?: number | null;
-    /** How this line's value was established (provenance for the verifier + the human reviewer). */
-    source: "provider-token-usage" | "no-spend-signal" | "operator-cap" | "unmeasured"
-    /** Tokens were COUNTED but no rate could price them, so `usd` stays null while the note
-     *  carries the measured token totals (#531). Distinct from "unmeasured", which means no
-     *  signal at all. */
-     | "unpriced-token-usage";
-    /** A short, public-safe note (never a secret value). */
-    note: string;
-}
-/** The cost categories the lane meters. product/media/payment are adapter signals; core can
- *  populate the provider line from the actor trace's tokenUsage.costUsd when present. */
-export type CostCategory = "product" | "media" | "payment" | "provider";
-/**
- * The spend ledger (a block of `TerminalLedgers`). The no-spend PROOF is DERIVED from this — never
- * asserted independently. Every applicable category appears as a line; unknowns are `null`.
- */
-export interface TerminalCostLedger {
-    schema: "humanish.terminal-cost-ledger.v1";
-    /** USD currency unit (recorded explicitly so a future multi-currency lane is unambiguous). */
-    currency: "usd";
-    lines: Record<CostCategory, CostLine>;
-    /** Sum of the KNOWN (non-null) lines. null lines contribute NOTHING and are NOT guessed as 0. */
-    knownTotalUsd: number;
-    /** True when every applicable line is measured (no null). When false, knownTotalUsd is a LOWER
-     *  bound, not the full spend — the no-spend proof says so honestly. */
-    fullyMeasured: boolean;
-}
-/**
- * The no-spend proof, DERIVED from the cost ledger (issue #154: "derived from a ledger, not
- * asserted"). It is honest about what it knows: it lists the KNOWN-zero lines it can vouch for and,
- * separately, the UNMEASURED (null) lines it CANNOT vouch for. `satisfied` is true only when every
- * KNOWN line is zero (a known non-zero line fails it); but a proof with unmeasured lines explicitly
- * says it could not measure them — it never claims zero on a line the ledger marks null.
- */
-export interface NoSpendProof {
-    schema: "humanish.terminal-no-spend-proof.v1";
-    /** The maxUsd cap this proof was evaluated against (the no-spend scenario declares maxUsd: 0). */
-    maxUsd: number | null;
-    /** True iff every KNOWN (measured) line is <= maxUsd (for a no-spend run, == 0). */
-    satisfied: boolean;
-    /** Categories the ledger MEASURED and found at (known) zero — the proof CAN vouch for these. */
-    knownZeroLines: CostCategory[];
-    /** Categories the ledger measured with a known NON-zero spend (these break `satisfied`). */
-    knownNonZeroLines: CostCategory[];
-    /** Categories the ledger marks `null` (NOT MEASURED). The proof explicitly lists these and does
-     *  NOT claim they are zero — it claims only that this run could not measure them. */
-    unmeasuredLines: CostCategory[];
-    /** Sum of the known lines (== 0 for a satisfied no-spend run). */
-    knownTotalUsd: number;
-    /** Human-readable honesty statement covering both what is proven and what is unmeasured. */
-    statement: string;
-}
-/** The persisted terminal-product ledgers artifact (substrate lifecycle + command log + interventions + cleanup + cost). */
-export interface TerminalLedgers {
-    schema: "humanish.terminal-ledgers.v1";
-    runtime?: ActorRuntimeProvenance;
-    lifecycle: LifecycleRecord[];
-    commandLog: CommandLogRecord[];
-    /** ALWAYS present; ALWAYS empty while no assisted-input path ships — the safety contract. */
-    interventions: InterventionRecord[];
-    cleanup: {
-        /** True when exact-id kill resolved, including the startup guard's acquired-instance kill
-         *  (found-and-killed or already gone both prove absence; see `remaining`/`reason`). */
-        killed: boolean;
-        /** BY-ID proof, NEVER derived from Sandbox.list: 0 = confirmed reclaimed (kill(id) RESOLVED
-         *  -- returned true "found and killed" OR false "404, exact id already gone" -- and, when the
-         *  SDK exposes it, getInfo(id) did not report a live sandbox); 1 = getInfo(id) still reports
-         *  this exact sandbox running/paused (NOT reclaimed); -1 = kill(id) itself failed, threw, or
-         *  was unavailable (the server-side kill-on-timeout is the backstop). */
-        remaining: number;
-        /** Honest, human-readable statement of which by-id signal produced `remaining`. */
-        reason: string;
-    };
-    /** The spend ledger. Unknowns are `null`, never guessed; the no-spend proof
-     *  below is DERIVED from it. */
-    cost: TerminalCostLedger;
-    /** The no-spend proof DERIVED from `cost`. Never an independent assertion. */
-    noSpendProof: NoSpendProof;
-}
-/**
- * Build the sandbox metadata from a POSITIVE ALLOWLIST (safety contract item 6). This is the ONLY
- * way metadata is set on the terminal lane — it carries solely non-secret labels and rejects any
- * value that is not a plain short label. A verifier check asserts the persisted metadata has no
- * prompt/token/secret shapes; this builder makes that true by construction.
- */
-export declare function buildSandboxMetadata(allowlist: {
-    labId: string;
-    simId: string;
-    runId: string;
-}): Record<string, string>;
-/**
- * Project the terminal-product lab run into a humanish.run-bundle.v1 (no schema change — a new
- * producer only). DRY-RUN: a contract bundle. The terminal stream is a contract placeholder
- * (stdin disabled, no captured tail — honest: nothing ran), the subject is declared UNPINNED, and
- * the caps/policies/runtime-auth declarations are recorded without pretending that live ledgers
- * exist. The shipped live builder fills the same evidence contract. Exported for tests.
- */
-export declare function buildTerminalProductBundle(args: {
-    /** Lab provenance for the bundle\'s own `lab` field (#455). */
-    lab?: RunLabProvenance;
-    actorId: string;
-    createdAt: string;
-    dryRun: boolean;
-    labId: string;
-    labTitle?: string;
-    mission: string;
-    persona: ActorPersonaRef;
-    productName: string;
-    publicSurfaces: string[];
-    caps?: LabScenarioCaps;
-    runtimeAuth?: string;
-    stdin: "disabled" | "planned" | "sent";
-    policies: {
-        allowPrivateRepoAccess: boolean;
-        allowProviderCredentials: boolean;
-        allowPaymentCredentials: boolean;
-        allowGitHubMutation: boolean;
-    };
-    runId: string;
-    source: RunBundle["source"];
-}): RunBundle;
-/**
- * Build the LIVE terminal-product run bundle (mode "live") from the captured session: the actor
- * trace seam (stream.actor = trace), the substrate-lifecycle events, the terminal stream with the
- * redacted transcript tail, and references to the written evidence artifacts (terminal event
- * stream, transcript, ledgers, actor trace). verifyRun's terminal-product check (gated on
- * mode==="live") enforces the ledgers + proven cleanup + interventions-present over this bundle.
- */
-export declare function buildLiveTerminalProductBundle(args: {
-    /** Lab provenance for the bundle\'s own `lab` field (#455). */
-    lab?: RunLabProvenance;
-    actorId: string;
-    createdAt: string;
-    labId: string;
-    labTitle?: string;
-    mission: string;
-    persona: ActorPersonaRef;
-    productName: string;
-    publicSurfaces: string[];
-    caps?: LabScenarioCaps;
-    runtimeAuthKeyName: string;
-    runtimeAuth?: LabRuntimeAuth;
-    policies: {
-        allowPrivateRepoAccess: boolean;
-        allowProviderCredentials: boolean;
-        allowPaymentCredentials: boolean;
-        allowGitHubMutation: boolean;
-    };
-    runId: string;
-    source: RunBundle["source"];
-    trace: ActorTrace;
-    ledgers: TerminalLedgers;
-    sandboxId?: string;
-    sessionError?: string;
-    sessionReason: string;
-}): RunBundle;