humanish 0.0.1 → 0.15.1

package/dist/shared-world-lab.d.ts

@@ -0,0 +1,208 @@
+import type { ActorCompletionReason, ActorPersonaRef, ActorStatus } from "./actor-contract.js";
+import { type BrowserLabAdapterHooks } from "./adapter-extension.js";
+import { type CuaActorDescriptor } from "./actor-registry.js";
+import type { CuaActorSessionOptions } from "./computer-use-actor.js";
+import type { CuaLoopResult } from "./computer-use.js";
+import { type DesktopBrowserEvidence, type SubjectPhaseEvent } from "./cua-actor-lab.js";
+import { type E2BDesktopModule, type E2BDesktopSandbox } from "./e2b-desktop-launch.js";
+import { type DetachedTimers } from "./e2b-detached.js";
+import type { DevicePreset } from "./device-presets.js";
+import { type LabConfig, type LabSubjectStateCheckpoint } from "./lab-config.js";
+import { renderObserver, type ObserverResult } from "./observer.js";
+import type { LocalTreeArchive } from "./source-archive.js";
+import type { StopWhen } from "./stop-conditions.js";
+import { type RunBundle, type RunSubjectProvenance, type SharedWorldCheckpoint } from "./run.js";
+export declare const SHARED_WORLD_LAB_SCHEMA = "humanish.shared-world-lab-result.v1";
+export declare const SHARED_WORLD_LAB_PROVIDER_METADATA: {
+    readonly mode: "shared-world-lab";
+    readonly tool: "humanish";
+};
+/**
+ * Library-level hooks mirroring CuaActorLabHooks — the DI seams that let CI drive the FULL
+ * orchestration with fakes at $0/zero-network. The fake desktop module records create/kill BY id
+ * and exposes NO `list` method (the by-id teardown rail is then provable by construction).
+ */
+export interface SharedWorldLabHooks extends BrowserLabAdapterHooks {
+    /** Lazy-load the E2B desktop module (tests inject a fake; default loadE2BDesktopModule). */
+    loadDesktopModule?: () => Promise<E2BDesktopModule>;
+    /** Runs once after sandbox creation, before subject provisioning (library setup seam). */
+    prepareDesktop?: (desktop: E2BDesktopSandbox) => Promise<void>;
+    /** The per-seat computer-use session runner (default: the resolved actor descriptor's). */
+    runSession?: (options: CuaActorSessionOptions) => Promise<CuaLoopResult>;
+    /** The operator environment (keys + subject env values). Defaults to process.env. */
+    env?: Record<string, string | undefined>;
+    renderObserverFn?: typeof renderObserver;
+    /** Injected clock/sleep for the detached-step polling (tests only). */
+    detachedTimers?: DetachedTimers;
+    /**
+     * Subject-provisioning phase sink (mirrors CuaActorLabHooks.onPhase): one call per
+     * started/completed boundary during the ONE shared-plane provision (clone route: clone, install,
+     * build, serve start, ready, subject.state seed-step groups; local-tree route: upload, extract,
+     * install, build, serve start, ready, seed-step groups - no clone phase). Defaults to one stderr
+     * line per event. Override in tests to capture instead of writing to real stderr.
+     */
+    onPhase?: (event: SubjectPhaseEvent) => void;
+    /**
+     * CONCURRENT route only (#164 phase 2): the harness clock used to MEASURE each actor's laneWindow
+     * [start,end] (default Date.now). The deterministic heart test does NOT override this — overlap is
+     * produced by a rendezvous latch in the fake runSession + measured by the REAL clock (FIX-1), so
+     * the windows are real, not injected. (A test may override only for non-overlap assertions.)
+     */
+    now?: () => number;
+    /** CONCURRENT route only: the background stateSeries prober cadence (ms). Default 1000. */
+    proberCadenceMs?: number;
+    /**
+     * Local-tree packing DI seam (tests only, no npm dependency needed to exercise the route):
+     * defaults to createLocalTreeArchive(root, opts) plus a host-side read of the produced archive
+     * file into an ArrayBuffer (the SAME default cua-actor-lab.ts uses). Called ONCE per run, before
+     * the ONE shared-plane sandbox is created, on the live local-tree route.
+     */
+    packLocalTree?: (args: {
+        root: string;
+        extraExclude?: string[];
+        maxArchiveBytes?: number;
+    }) => Promise<{
+        archive: LocalTreeArchive;
+        buffer: ArrayBuffer;
+    }>;
+}
+export interface RunSharedWorldLabOptions {
+    cwd: string;
+    config: LabConfig;
+    /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
+    dryRun: boolean;
+    open?: boolean;
+    runId?: string;
+    hooks?: SharedWorldLabHooks;
+}
+export type SharedWorldLabErrorCode = "HUMANISH_SHARED_WORLD_LAB_FAILED" | "HUMANISH_SHARED_WORLD_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_SHARED_WORLD_LAB_INVALID" | "HUMANISH_SHARED_WORLD_LAB_KEYS_MISSING" | "HUMANISH_SHARED_WORLD_LAB_SUBJECT_ENV_MISSING";
+/** One role seat's terminal outcome in the result projection. */
+export interface SharedWorldRoleResult {
+    id: string;
+    index: number;
+    persona: string;
+    /** Terminal role status; "blocked" = fail-fast skipped it; "contract_proof_only" = dry-run. */
+    status: ActorStatus | "blocked" | "contract_proof_only";
+    ok: boolean;
+    session?: {
+        status: ActorStatus;
+        completionReason: ActorCompletionReason;
+        reason: string;
+        screenshots: number;
+    };
+    /** The user-data-dir profile this seat drove (proves per-seat isolation). */
+    profileDir: string;
+    /** Set when the role was skipped by fail-fast (a pinned reason string). */
+    skippedReason?: string;
+    error?: {
+        code: SharedWorldLabErrorCode;
+        message: string;
+    };
+}
+export interface SharedWorldLabResult {
+    schema: typeof SHARED_WORLD_LAB_SCHEMA;
+    /** True when the bundle verified AND (dry-run, or every role reached a terminal, engaged
+     * verdict without a harness error). The roles' 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 seats. */
+    actor: string;
+    topology: "shared-world";
+    /** The DECLARED number of role seats. */
+    roleCount: number;
+    /** The role ids that actually took a turn, in declared order. */
+    sequence: string[];
+    dryRun: boolean;
+    runId: string;
+    /** Live-only: the ONE shared sandbox's lifecycle proof (the stream/key value is never surfaced). */
+    sandbox?: {
+        sandboxId: string;
+        killed: boolean;
+    };
+    /** Subject provenance (invariant 5): the ONE shared plane. */
+    subject?: RunSubjectProvenance;
+    roles: SharedWorldRoleResult[];
+    observer?: ObserverResult;
+    warnings: string[];
+    error?: {
+        code: SharedWorldLabErrorCode;
+        message: string;
+    };
+}
+/** A fully-resolved role seat (internal). */
+interface RoleSpec {
+    roleId: string;
+    /** 0-based. */
+    roleIndex: number;
+    simId: string;
+    streamId: string;
+    persona: ActorPersonaRef;
+    instructions: string;
+    /** The role's declared device (a PROMPT SIGNAL — see the file's FIDELITY NOTE). */
+    deviceName: string;
+    /** Deterministic harness-owned completion guard. Lane-level override, else actor default. */
+    stopWhen?: StopWhen;
+    entry?: string;
+    seatUrl: string;
+    screenshotDir: string;
+    traceArtifactPath: string;
+    profileDir: string;
+}
+/** One role seat's end-to-end run outcome (internal; projected into the result + the bundle). */
+interface RoleOutcome {
+    spec: RoleSpec;
+    session?: CuaLoopResult;
+    sessionError?: string;
+    screenshots: string[];
+    desktopBrowser?: DesktopBrowserEvidence;
+    /** Set when fail-fast skipped this role before it ran. */
+    skippedReason?: string;
+    noEngagement: boolean;
+    harnessError: boolean;
+    /** The checkpoint snapshot taken AFTER this role's turn (absent for skipped roles). */
+    afterCheckpoint?: SharedWorldCheckpoint;
+}
+/** Combine a snapshot's per-probe digests into ONE sha256-16 (digest-only; no raw value). */
+export declare function combineCheckpointDigest(parts: string[]): string;
+/**
+ * Run ONE checkpoint snapshot LIVE: each declared probe runs read-only via the detached
+ * primitive; its stdout is literal-scrubbed (provisioned values + the probe's declared redact
+ * literals, folded into `scrub`) then pattern-redacted, then digested. Only the COMBINED digest
+ * persists — never the raw value (the seed-step lockdown). Unique step names per snapshot prevent
+ * stale-status reuse across snapshots.
+ */
+export declare function runCheckpointSnapshot(args: {
+    desktop: E2BDesktopSandbox;
+    snapshotIndex: number;
+    name: string;
+    checkpoints: LabSubjectStateCheckpoint[];
+    prevDigest: string | undefined;
+    scrub: (text: string) => string;
+    requestTimeoutMs: number;
+    timers: DetachedTimers;
+}): Promise<SharedWorldCheckpoint>;
+/** The DECLARED (dry-run) checkpoint snapshot: digest the probe RECIPE (command digests), no run. */
+export declare function declaredCheckpointSnapshot(name: string, checkpoints: LabSubjectStateCheckpoint[]): SharedWorldCheckpoint;
+/** sha256-16 over the ordered seed-step command digests — the seeded-state RECIPE identity. */
+export declare function seedRecipeDigest(config: LabConfig): string;
+export declare function runSharedWorldLab(options: RunSharedWorldLabOptions): Promise<SharedWorldLabResult>;
+/** Project the shared-world run into a humanish.run-bundle.v1 with the sharedWorld evidence block. */
+export declare function buildSharedWorldBundle(args: {
+    config: LabConfig;
+    descriptor: CuaActorDescriptor;
+    createdAt: string;
+    dryRun: boolean;
+    runId: string;
+    source: RunBundle["source"];
+    roleSpecs: RoleSpec[];
+    roleOutcomes: RoleOutcome[];
+    baselineCheckpoint: SharedWorldCheckpoint;
+    subject: RunSubjectProvenance;
+    sandboxResolution: [number, number];
+    sandboxPreset: DevicePreset;
+    seedDigest: string;
+    subjectCommit?: string;
+    failFastReason?: string;
+}): RunBundle;
+export {};