humanish 0.17.0 → 0.19.0

package/dist/serve-exposure.d.ts

@@ -0,0 +1,62 @@
+import { type ServeMode } from "./serve-http.js";
+import { type ServeTunnel, type StartNgrokTunnelOptions } from "./serve-tunnel.js";
+export type ExposureSurface = "serve" | "watch";
+export type ExposureErrorCode = "HUMANISH_SERVE_ALLOW_REQUIRES_OAUTH" | "HUMANISH_SERVE_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_SERVE_OPTION_CONFLICT" | "HUMANISH_SERVE_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE" | "HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE";
+export interface ExposureRequest {
+    expose: boolean;
+    tunnel?: "ngrok" | undefined;
+    tunnelDomain?: string | undefined;
+    oauth?: "google" | undefined;
+    allowEmails: string[];
+    allowDomains: string[];
+    publicUrl?: string | undefined;
+    safe: boolean;
+}
+export interface WatchLiveContext {
+    dryRun: boolean;
+    detach: boolean;
+    json: boolean;
+}
+export interface ExposurePlan {
+    exposed: boolean;
+    edgeAuthed: boolean;
+    mode: ServeMode;
+    safe: boolean;
+    tunnel?: "ngrok";
+    tunnelDomain?: string;
+    oauth?: {
+        provider: "google";
+        allowEmails: string[];
+        allowDomains: string[];
+    };
+    publicOrigin?: {
+        origin: string;
+        host: string;
+        scheme: "http" | "https";
+    };
+    warnings: string[];
+}
+export type ExposureValidation = {
+    ok: true;
+    plan: ExposurePlan;
+} | {
+    ok: false;
+    error: {
+        code: ExposureErrorCode;
+        message: string;
+    };
+};
+export declare function validateExposure(surface: ExposureSurface, request: ExposureRequest, live?: WatchLiveContext): ExposureValidation;
+export interface ExposableServer {
+    readonly port: number;
+    readonly url: string;
+    addPublicOrigin(origin: string): void;
+}
+export interface ExposureResult {
+    tunnel?: ServeTunnel;
+    publicUrl?: string;
+    warnings: string[];
+}
+export declare function startExposedObserver(server: ExposableServer, plan: ExposurePlan, deps?: {
+    startTunnel?: (options: StartNgrokTunnelOptions) => Promise<ServeTunnel>;
+}): Promise<ExposureResult>;

package/dist/serve-exposure.js

@@ -0,0 +1,129 @@
+// Shared fail-closed exposure validation + tunnel orchestration for BOTH `serve` (a library of
+// finished runs) and `watch` (one live run). Exposure auth is TUNNEL-EDGE only: humanish carries no
+// in-process auth. Exposure is admitted only behind edge auth (ngrok --oauth google, or an operator
+// --public-url they secure) OR, for serve, behind --safe (share_ready runs only). A live watch run
+// is never share_ready (raw, unverified screenshots), so watch --expose ALWAYS requires edge auth.
+//
+// This module is pure with respect to the fail-closed matrix (validateExposure) and thin over the
+// tunnel launcher (startExposedObserver), so the CLI just maps flags in and results out.
+import { parsePublicOrigin } from "./serve-http.js";
+import { startNgrokTunnel } from "./serve-tunnel.js";
+function code(surface, suffix) {
+    return `HUMANISH_${surface.toUpperCase()}_${suffix}`;
+}
+export function validateExposure(surface, request, live) {
+    const fail = (suffix, message) => ({
+        ok: false,
+        error: { code: code(surface, suffix), message }
+    });
+    // Structural guards (both surfaces), in the fail-closed order documented in the matrix. These run
+    // before any bind/spawn so a mis-configured exposure aborts before sandbox/provider spend.
+    if ((request.allowEmails.length > 0 || request.allowDomains.length > 0) && !request.oauth) {
+        return fail("ALLOW_REQUIRES_OAUTH", "--allow-email/--allow-domain configure the ngrok edge OAuth allow-list; they require --oauth google.");
+    }
+    if (request.oauth && !request.tunnel) {
+        return fail("OAUTH_REQUIRES_TUNNEL", "--oauth turns on edge OAuth on the ngrok tunnel; it requires --tunnel ngrok (a --public-url operator brings their own edge auth).");
+    }
+    if (request.tunnel && request.publicUrl !== undefined) {
+        return fail("OPTION_CONFLICT", "Use either --tunnel or --public-url as the public origin, not both.");
+    }
+    if (request.tunnelDomain !== undefined && !request.tunnel) {
+        return fail("OPTION_CONFLICT", "--tunnel-domain requires --tunnel.");
+    }
+    const publicOrigin = request.publicUrl !== undefined ? parsePublicOrigin(request.publicUrl) : null;
+    if (request.publicUrl !== undefined && !publicOrigin) {
+        return fail("OPTION_CONFLICT", "--public-url must be an http(s) origin like https://observer.example.com.");
+    }
+    if (!request.expose) {
+        // Exposure flags without --expose are refused (no silent wide-open). --safe is orthogonal and
+        // stays valid without --expose (a loopback share_ready filter).
+        if (request.tunnel) {
+            return fail("TUNNEL_REQUIRES_EXPOSE", "--tunnel exposes the surface; declare that intent with --expose.");
+        }
+        if (request.publicUrl !== undefined) {
+            return fail("OPTION_CONFLICT", "--public-url only applies with --expose.");
+        }
+        return {
+            ok: true,
+            plan: { exposed: false, edgeAuthed: false, mode: "loopback", safe: request.safe, warnings: [] }
+        };
+    }
+    const oauth = request.oauth
+        ? { provider: "google", allowEmails: request.allowEmails, allowDomains: request.allowDomains }
+        : undefined;
+    const edgeAuthed = Boolean(request.oauth) || Boolean(publicOrigin);
+    const warnings = [];
+    if (surface === "watch") {
+        // A live, in-progress run is never share_ready (raw screenshots, unverified), so --safe would
+        // admit nothing and expose nothing: watch --expose ALWAYS requires edge auth, and the live-follow
+        // preconditions are checked first so `--dry-run`/`--detach`/`--json` fail with the clearer reason.
+        if (live && (live.dryRun || live.detach || live.json)) {
+            return fail("EXPOSE_REQUIRES_LIVE_FOLLOW", "watch --expose streams a live desktop over an attached follow channel; it cannot combine with --dry-run, --detach, or --json.");
+        }
+        // --safe is a share_ready LIBRARY filter for `serve`; watch streams a single live run that is
+        // never share_ready, so --safe would silently do nothing here. Reject it rather than ignore it.
+        if (request.safe) {
+            return fail("SAFE_NOT_APPLICABLE", "watch streams a single live run that is never share_ready; --safe (a share_ready library filter) applies to `serve`, not `watch`. Restrict viewers with edge auth: --allow-email / --allow-domain.");
+        }
+        if (!edgeAuthed) {
+            return fail("EXPOSE_REQUIRES_EDGE_AUTH", "watch --expose serves a live run that is never share_ready, so --safe cannot gate it; require edge auth: --tunnel ngrok --oauth google, or an operator-secured --public-url.");
+        }
+    }
+    else {
+        // serve: --expose must ALWAYS resolve to a reachable public origin (a tunnel or a --public-url),
+        // even under --safe. Without one the exposed server is an unreachable loopback no-op, so fail
+        // closed before the origin-less bind. When an origin IS present, keep the edge-auth-OR-safe gate.
+        if (!request.tunnel && !publicOrigin) {
+            return fail("EXPOSE_REQUIRES_ORIGIN", "--expose needs a declared public origin: pass --tunnel ngrok or --public-url <origin>.");
+        }
+        if (!edgeAuthed && !request.safe) {
+            return fail("EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE", "--expose opens a public URL to local run bundles; require edge auth (--oauth google with --tunnel, or a --public-url you secure) OR --safe (share_ready runs only).");
+        }
+    }
+    if (request.oauth && request.allowEmails.length === 0 && request.allowDomains.length === 0) {
+        warnings.push("ngrok --oauth google with NO --allow-email/--allow-domain lets ANY Google account that reaches the URL in; add at least one allow rule to restrict who can watch.");
+    }
+    const mode = edgeAuthed ? "exposed" : "share-safe-open";
+    return {
+        ok: true,
+        plan: {
+            exposed: true,
+            edgeAuthed,
+            mode,
+            safe: request.safe,
+            ...(request.tunnel ? { tunnel: request.tunnel } : {}),
+            ...(request.tunnelDomain ? { tunnelDomain: request.tunnelDomain } : {}),
+            ...(oauth ? { oauth } : {}),
+            ...(publicOrigin ? { publicOrigin } : {}),
+            warnings
+        }
+    };
+}
+// Orchestrate the edge in front of an already-bound loopback server: spawn the ngrok tunnel (with
+// oauth/allow args) or declare the operator's --public-url, then extend the server's Host allowlist.
+// May throw a ServeTunnelError (ngrok missing/failed); callers close the loopback server on throw.
+export async function startExposedObserver(server, plan, deps = {}) {
+    const warnings = [...plan.warnings];
+    if (plan.tunnel === "ngrok") {
+        const startTunnel = deps.startTunnel ?? startNgrokTunnel;
+        const tunnel = await startTunnel({
+            port: server.port,
+            ...(plan.tunnelDomain ? { domain: plan.tunnelDomain } : {}),
+            ...(plan.oauth
+                ? {
+                    oauthProvider: plan.oauth.provider,
+                    oauthAllowEmails: plan.oauth.allowEmails,
+                    oauthAllowDomains: plan.oauth.allowDomains
+                }
+                : {})
+        });
+        server.addPublicOrigin(tunnel.url);
+        return { tunnel, publicUrl: tunnel.url.replace(/\/$/, ""), warnings };
+    }
+    if (plan.publicOrigin) {
+        server.addPublicOrigin(plan.publicOrigin.origin);
+        return { publicUrl: plan.publicOrigin.origin, warnings };
+    }
+    return { warnings };
+}
+//# sourceMappingURL=serve-exposure.js.map

package/dist/serve-exposure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-exposure.js","sourceRoot":"","sources":["../src/serve-exposure.ts"],"names":[],"mappings":"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"}

package/dist/serve-http.d.ts

@@ -0,0 +1,8 @@
+export type ServeMode = "loopback" | "exposed" | "share-safe-open";
+export declare function buildServeSecurityHeaders(): Record<string, string>;
+export declare function hostAllowed(hostHeader: string | undefined, allowlist: ReadonlySet<string>): boolean;
+export declare function parsePublicOrigin(value: string): {
+    origin: string;
+    host: string;
+    scheme: "http" | "https";
+} | null;

package/dist/serve-http.js

@@ -0,0 +1,37 @@
+// Shared HTTP hardening primitives for the serve surfaces. Extracted here so BOTH the live
+// Observer server (src/observer.ts, exposed mode) and the run-library server
+// (src/observer-serve.ts) can enforce the identical Host allowlist + security-header posture
+// without a module cycle. This file imports nothing from the serve modules.
+export function buildServeSecurityHeaders() {
+    return {
+        "cache-control": "no-store",
+        "referrer-policy": "no-referrer",
+        "x-content-type-options": "nosniff",
+        "x-frame-options": "DENY",
+        "x-robots-tag": "noindex, nofollow"
+    };
+}
+export function hostAllowed(hostHeader, allowlist) {
+    return typeof hostHeader === "string" && allowlist.has(hostHeader.trim().toLowerCase());
+}
+export function parsePublicOrigin(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return null;
+    }
+    if ((parsed.pathname !== "/" && parsed.pathname !== "") || parsed.search || parsed.hash || !parsed.host) {
+        return null;
+    }
+    return {
+        origin: parsed.origin,
+        host: parsed.host.toLowerCase(),
+        scheme: parsed.protocol === "https:" ? "https" : "http"
+    };
+}
+//# sourceMappingURL=serve-http.js.map

package/dist/serve-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-http.js","sourceRoot":"","sources":["../src/serve-http.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,6EAA6E;AAC7E,6FAA6F;AAC7F,4EAA4E;AAS5E,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,eAAe,EAAE,UAAU;QAC3B,iBAAiB,EAAE,aAAa;QAChC,wBAAwB,EAAE,SAAS;QACnC,iBAAiB,EAAE,MAAM;QACzB,cAAc,EAAE,mBAAmB;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,UAA8B,EAAE,SAA8B;IACxF,OAAO,OAAO,UAAU,KAAK,QAAQ,IAAI,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,GAAG,IAAI,MAAM,CAAC,QAAQ,KAAK,EAAE,CAAC,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACxG,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE;QAC/B,MAAM,EAAE,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;KACxD,CAAC;AACJ,CAAC"}

package/dist/serve-tunnel.d.ts

@@ -8,9 +8,13 @@ export interface ServeTunnel {
     url: string;
     close(): Promise<void>;
 }
-export declare function startNgrokTunnel(options: {
+export interface StartNgrokTunnelOptions {
     port: number;
     domain?: string;
+    oauthProvider?: "google";
+    oauthAllowEmails?: string[];
+    oauthAllowDomains?: string[];
     timeoutMs?: number;
     spawnImpl?: typeof spawn;
-}): Promise<ServeTunnel>;
+}
+export declare function startNgrokTunnel(options: StartNgrokTunnelOptions): Promise<ServeTunnel>;

package/dist/serve-tunnel.js

@@ -10,6 +10,14 @@ export class ServeTunnelError extends Error {
 export async function startNgrokTunnel(options) {
     const spawnImpl = options.spawnImpl ?? spawn;
     const timeoutMs = options.timeoutMs ?? 15_000;
+    const oauthArgs = options.oauthProvider
+        ? [
+            "--oauth",
+            options.oauthProvider,
+            ...(options.oauthAllowEmails ?? []).flatMap((email) => ["--oauth-allow-email", email]),
+            ...(options.oauthAllowDomains ?? []).flatMap((domain) => ["--oauth-allow-domain", domain])
+        ]
+        : [];
     const args = [
         "http",
         "--log",
@@ -17,6 +25,7 @@ export async function startNgrokTunnel(options) {
         "--log-format",
         "json",
         ...(options.domain ? ["--url", options.domain] : []),
+        ...oauthArgs,
         String(options.port)
     ];
     const child = spawnImpl("ngrok", args, { stdio: ["ignore", "pipe", "ignore"] });

package/dist/serve-tunnel.js.map

@@ -1 +1 @@
-{"version":3,"file":"serve-tunnel.js","sourceRoot":"","sources":["../src/serve-tunnel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"serve-tunnel.js","sourceRoot":"","sources":["../src/serve-tunnel.ts"],"names":[],"mappings":"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"}

package/docs/architecture/actor-contract.md

@@ -111,7 +111,10 @@ export type ActorCompletionReason =
   | "turn_completed"      // harness saw an explicit done signal, no predicate
   | "gave_up"             // persona abandoned in character: friction exceeded its tolerance
   | "blocked_approval"    // an action was auto-declined and the actor could not proceed
-  | "timed_out"
+  | "timed_out"           // wall-clock deadline hit with ZERO material progress → still a FAILURE
+  | "budget_reached"      // wall-clock time budget hit AFTER productive activity (>=1 material
+                          // action) → ActorStatus "passed", a NON-FAILURE open-ended-watch
+                          // completion; distinct from goal_satisfied (no goal was claimed)
   | "actor_error"
   | "step_failed"         // a deterministic scripted step/expectation evaluated false: the
                           // SUBJECT failed the script; the harness executed faithfully
@@ -162,6 +165,7 @@ export interface ActorTrace {
   counts: Record<string, number>;
   items: ActorTraceItem[];
   tokenUsage?: { input?: number; output?: number; total?: number; costUsd?: number };
+  estimatedCost?: ActorEstimatedCost;                // humanish.actor-estimated-cost.v1 (additive)
   capabilities: ActorCapabilities;
 }
 
@@ -229,6 +233,17 @@ export interface Actor {
   target URLs, or unredacted provider payloads in the trace.
 - **Capabilities.** Declare them honestly; the registry uses them to refuse
   unsuitable dispatch.
+- **Cost (estimate vs. charge).** `tokenUsage.costUsd` stays RESERVED for a
+  real, provider-returned charge (the codex/agent-SDK path) — a bare `costUsd`
+  always means "the provider billed this". The optional `estimatedCost`
+  (`humanish.actor-estimated-cost.v1`) is a SEPARATE, differently-named field: a
+  token-derived rate-table multiply from the operator-editable `src/pricing.ts`,
+  labeled honestly as an estimate and projected up into `RunBundle.cost` (see
+  [`../contracts/schemas.md`](../contracts/schemas.md) → Run Cost Summary And
+  Estimated Actor Cost). The CUA lab computes and attaches `estimatedCost` at the
+  lab boundary before persisting the trace, so the pure computer-use loop never
+  depends on the pricing table. An unknown model yields
+  `estimatedCostUsd: null` + a `reason`, never a guessed charge.
 
 ## The scripted-browser lane (shipped)
 
@@ -245,8 +260,31 @@ Completion semantics: `goal_satisfied` means the scenario's `expect` blocks —
 predicate — all held ("the app still affords this exact journey", nothing about user
 behavior); `step_failed` means a deterministic step or expectation evaluated false (the
 subject failed the script; the harness ran faithfully); `timed_out` is the journey wall-clock
-budget; `harness_error` is a browser that could not launch. `gave_up` and `blocked_approval`
-are unreachable — no persona patience, no approvals exist on a deterministic replay.
+budget hit with NO material progress (still a failure); `harness_error` is a browser that could
+not launch. `gave_up` and `blocked_approval` are unreachable — no persona patience, no
+approvals exist on a deterministic replay.
+
+### The time budget vs. a stuck timeout (`budget_reached`)
+
+`execution.timeoutMs` is a GENEROUS wall-clock SAFETY cap, not a goal. For an open-ended
+"watch it play" session there is no success predicate — productive play IS the outcome — so the
+computer-use loop distinguishes two ways to hit the cap:
+
+- **`budget_reached`** — the deadline was reached AFTER at least one material (non-idle) action.
+  This maps to `ActorStatus: "passed"`: a non-failure completion, `laneOutcomeOk` returns true,
+  the verdict is `pass`, and the CLI exits `0`. It stays a distinct `completionReason` (never
+  `goal_satisfied`), and the trace `reason` says it reached the budget after productive activity,
+  so a reviewer of a strictly goal-directed lab sees it hit the cap rather than reaching a goal
+  (goal-directed labs should set a tight `timeoutMs`).
+- **`timed_out`** — the deadline was reached with ZERO material actions (a hung provider, an
+  idle-only stall). This maps to `ActorStatus: "timed_out"`, `laneOutcomeOk` is false, the
+  verdict is `fail`, and the CLI exits `2`. "Made zero progress then timed out" stays a failure.
+
+`ActorStatus` intentionally gains NO new member — the honest distinction lives in
+`completionReason`/`reason` — which keeps the change from rippling through ~10 provider mappers.
+`statusForCompletion` is an exhaustive switch with no default, so a new completion reason forces a
+compile-time decision about its status. ~30 min (`1_800_000`) is a reasonable default for
+open-ended watch; the persona still stops early on `goal_satisfied`/`gave_up`/`stopWhen`.
 
 Actuation-vs-spend gate: on the scripted lab route `scenario.mode: live` is still required
 even though provider spend is $0 by mechanism. The gate's justification there is ACTUATION,

package/docs/architecture/observer.md

@@ -78,6 +78,36 @@ LIBRARY surface — every run under `.humanish/runs/` — and never serves runti
 stream URLs in any mode; remote viewers see persisted evidence only. See
 [Serve: the run library surface](serve.md).
 
+### Exposed hardening and `watch --expose`
+
+The live `serveObserver` server binds `127.0.0.1` and, by default, is a
+permissive local-dev server (no Host allowlist, no security headers). Under its
+`exposed` option — set by `watch --expose` — it enforces the SAME
+DNS-rebinding defense as the library surface: a strict Host allowlist (loopback
+names at bind, extended by `addPublicOrigin(tunnel.url | public-url)`, `421
+Misdirected Request` otherwise) and the shared `buildServeSecurityHeaders()` on
+every response (both live in `src/serve-http.ts`, shared without a module cycle).
+Loopback (non-exposed) behavior is byte-identical to before.
+
+Exposed mode also SCOPES the surface to the attached live run (`result.run`): the
+`/_humanish/history.json` index is filtered to that one run, and `/_humanish/runs/<id>/…`
+404s byte-identically to a nonexistent run for any other id. A remote viewer who
+clears the edge auth can therefore see only the run being watched — never enumerate
+or fetch a prior run's raw, unverified evidence. Loopback keeps the full cross-run
+library (history + any run by id) exactly as before.
+
+`watch --expose` is the ONE surface that DELIBERATELY streams the live E2B
+desktop to a remote viewer: the attached watch process genuinely holds the
+runtime stream URLs (in the in-memory `WeakMap`, never persisted), and streaming
+them is the whole point of watching from a phone. It is safe only because the
+ngrok edge (Google OAuth + allow rules) or an operator `--public-url` edge
+authenticates the viewer first — `watch --expose` therefore always requires edge
+auth (a live run is never `share_ready`, so `--safe` alone cannot gate it). The
+attached server comes up DURING the run and survives a `timed_out`/`failed` run
+(serving is not gated on pass/fail), so a failed run's evidence stays inspectable
+to Ctrl-C. `serve` still never injects stream URLs. See
+[Serve: the run library surface](serve.md).
+
 ## UI Shape
 
 The Observer shell has: