humanish 0.104.3 → 0.106.0

package/dist/routes/shared-world/plan.js

@@ -0,0 +1,174 @@
+// The shared-world route's plan: every configuration refusal the route makes before a run starts,
+// in its order and with its codes, then the plan the run uses. What stays in the route reads
+// external state: keys and subject env values, the external comms catch, the packed working tree
+// and email receiving setup.
+import { DEFAULT_OPENAI_CU_MODEL } from "../../actors/computer-use/openai-provider.js";
+import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
+import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
+import { brainOf, capsOf, desktopRequirements, isNonEmpty, planBase } from "../../lab/plan-base.js";
+import { sharedWorldParticipants } from "../../lab/plan-participants.js";
+import { PUBLIC_TARGET_OWNER_PATTERN } from "../../lab/parse/subject.js";
+import { REPO_SLUG_PATTERN } from "../../lab/parse/values.js";
+import { concurrentSharedWorldValidationReason, desktopMediaValidationReason, externalPublicSharedWorldValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "../../lab/validation.js";
+import { MODEL_RATES } from "../../run/pricing.js";
+/** The registered descriptor for a planned actor; planSharedWorldLab checked the registry. */
+export function sharedWorldDescriptorOf(actorType) {
+    const descriptor = actorRegistry[actorType];
+    if (!descriptor || !isCuaActorDescriptor(descriptor))
+        throw new Error(`actor "${actorType}" is not a registered computer-use actor`);
+    return descriptor;
+}
+/**
+ * Plan a shared-world lab. It is called for any config handed to the shared-world runner, not only
+ * one routeOf sends here, so a config for another route gets this route's refusal.
+ */
+export function planSharedWorldLab(config, input) {
+    const refuse = (code, message, actor) => ({
+        ok: false,
+        refusal: { route: "shared-world", code, message, ...(actor === undefined ? {} : { actor }) },
+    });
+    const invalid = "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_INVALID";
+    const mediaReason = desktopMediaValidationReason(config, false);
+    if (mediaReason)
+        return refuse(invalid, mediaReason);
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    if (!analysis.ok)
+        return refuse("HUMANISH_LAB_ANALYSIS_INVALID", analysis.message);
+    const tasksReason = taskProtocolValidationReason(config, false);
+    if (tasksReason)
+        return refuse("HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason);
+    const actorType = config.actors[0]?.type ?? "";
+    const descriptor = actorRegistry[actorType];
+    if (!descriptor || !isCuaActorDescriptor(descriptor))
+        return refuse("HUMANISH_CONCURRENT_SHARED_WORLD_LAB_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered computer-use actor.`);
+    const actor = descriptor.id;
+    // An app-url subject is the external-public plane (a real operator-owned deployment used
+    // directly, with no getHost, clone, subject sandbox or seed); every other subject is the
+    // provisioned plane. The external-public check never runs the getHost synthetic gate: that gate
+    // exists because getHost is internet-reachable and harness-owned, and a public site the harness
+    // neither provisioned nor exposed is neither.
+    const externalPublic = config.subject.source === "app-url";
+    const invalidReason = outputTokenLimitValidationReason(config) ??
+        scenarioCapsValidationReason(config) ??
+        (externalPublic
+            ? externalPublicSharedWorldValidationReason(config)
+            : concurrentSharedWorldValidationReason(config));
+    if (invalidReason)
+        return refuse(invalid, invalidReason, actor);
+    if (config.actors[0]?.maxOutputTokens !== undefined && input.hooks?.runSession)
+        return refuse(invalid, "maxOutputTokens cannot be enforced by a custom runSession.", actor);
+    const caps = config.execution?.caps;
+    if (!input.dryRun && (caps?.maxUsd !== undefined || caps?.maxTotalUsd !== undefined)) {
+        const model = (config.actors[0]?.model ?? DEFAULT_OPENAI_CU_MODEL).trim().toLowerCase();
+        if (!MODEL_RATES[model])
+            return refuse("HUMANISH_CONCURRENT_SHARED_WORLD_LAB_UNPRICED_CAP", `The declared spend cap cannot be enforced for unpriced model "${model}".`, actor);
+    }
+    const receivingReason = receivingEmailValidationReason(config);
+    if (receivingReason)
+        return refuse(invalid, receivingReason, actor);
+    // The parser requires one owner/repo slug; without it the route would clone nothing and fail
+    // after the run started.
+    const repo = config.subject.repos?.[0] ?? "";
+    if (config.subject.source === "clone" && !REPO_SLUG_PATTERN.test(repo))
+        return refuse(invalid, `subject.repos[0] must be an owner/repo slug (got "${repo}").`, actor);
+    // The owner is recorded in the evidence as the operator's attestation, so it must be declared
+    // and public-safe; the parser requires the same.
+    const owner = config.subject.publicTarget?.owner;
+    if (externalPublic && (!owner || !PUBLIC_TARGET_OWNER_PATTERN.test(owner)))
+        return refuse(invalid, "`subject.publicTarget.owner` must be a public-safe operator/repo label (e.g. owner/repo); it is recorded in evidence, so it must carry no secret.", actor);
+    // The external-public plane provisions nothing, so it has no env channel. The parser refuses
+    // subject.env on an app-url subject for the same reason.
+    if (externalPublic && config.subject.env !== undefined)
+        return refuse(invalid, "`subject.env` applies only to clone subjects or local-tree subjects (the served app's environment channel).", actor);
+    const plane = planeOf(config);
+    if (plane === undefined)
+        throw new Error("shared-world validation admitted a plane it cannot plan");
+    const brain = brainOf(config, false);
+    if (brain.kind === "caller")
+        throw new Error("a shared-world participant has no caller brain");
+    const base = planBase(config, {
+        dryRun: input.dryRun,
+        ...(input.lab === undefined ? {} : { lab: input.lab }),
+        analysis,
+    });
+    return {
+        ok: true,
+        plan: {
+            ...base,
+            route: "shared-world",
+            actor,
+            plane,
+            concurrency: config.execution?.concurrency ?? plane.participants.length,
+            ...(config.execution?.timeoutMs === undefined
+                ? {}
+                : { sessionTimeoutMs: config.execution.timeoutMs }),
+            brain,
+            caps: capsOf(config),
+            requirements: base.dryRun
+                ? []
+                : [
+                    ...desktopRequirements(config, {
+                        e2b: true,
+                        brain,
+                        localVm: false,
+                        externalCatch: plane.kind === "external-public",
+                    }),
+                    // The external-public plane reads the host's lobby code with the OpenAI API, whatever
+                    // brain drives the seats.
+                    ...(plane.kind === "external-public" && brain.kind !== "openai"
+                        ? [{ kind: "key", name: "OPENAI_API_KEY" }]
+                        : []),
+                ],
+        },
+    };
+}
+/** The provisioned plane's declared subject state. The external-public plane declares none. */
+export function planeStateOf(plan) {
+    return plan.plane.kind === "provisioned" ? plan.plane.subject.state : undefined;
+}
+/**
+ * The shared plane and its participants. The validation above guarantees two or more, and on the
+ * provisioned plane a clone or local tree with `serve` and at least one checkpoint.
+ */
+function planeOf(config) {
+    const roster = sharedWorldParticipants(config);
+    if (roster.plane === "external-public") {
+        const [first, second, ...rest] = roster.participants;
+        if (first === undefined || second === undefined)
+            return undefined;
+        const owner = config.subject.publicTarget?.owner;
+        if (!owner)
+            return undefined;
+        return {
+            kind: "external-public",
+            appUrl: config.subject.appUrl ?? "",
+            owner,
+            participants: [first, second, ...rest],
+        };
+    }
+    const [first, second, ...rest] = roster.participants;
+    const { serve, state } = config.subject;
+    const checkpoint = state?.checkpoint ?? [];
+    if (first === undefined ||
+        second === undefined ||
+        serve === undefined ||
+        state === undefined ||
+        !isNonEmpty(checkpoint))
+        return undefined;
+    const env = config.subject.env ?? [];
+    const checkpointed = { ...state, checkpoint };
+    return {
+        kind: "provisioned",
+        subject: config.subject.source === "local-tree"
+            ? { kind: "local-tree", serve, env, state: checkpointed }
+            : {
+                kind: "clone",
+                // planSharedWorldLab refused a clone without an owner/repo slug.
+                repo: config.subject.repos?.[0] ?? "",
+                serve,
+                env,
+                state: checkpointed,
+            },
+        participants: [first, second, ...rest],
+    };
+}

package/dist/routes/shared-world/provenance.d.ts

@@ -0,0 +1,27 @@
+import type { RunSubjectProvenance } from "../../run/bundle.js";
+import type { LocalTreeArchive } from "../../subject/local-tree-archive.js";
+/** Extract the in-sandbox port from the (loopback) serve.url so getHost can expose it. */
+export declare function servePort(serveUrl: string): number;
+/** A getHost URL must be TOKENLESS (no userinfo, no query — no authKey; invariant 1). */
+export declare function isTokenlessHost(value: string): boolean;
+/** sha256-16 of a URL's ORIGIN — the publish-safe host identity persisted in the bundle (the raw
+ *  getHost URL embeds the live sandbox id + matches the e2b-URL redaction, so it never lands raw). */
+export declare function hostOriginDigest(url: string): string;
+/** A public-safe, human-readable route label for the bundle (host redacted to a placeholder; the
+ *  entry path kept). Never contains the raw getHost URL. */
+export declare function publicSafeRouteLabel(entry: string | undefined): string;
+/**
+ * Build the ONE subject sandbox's provenance (invariant 5): clone (repo + optional commit) or
+ * local-tree (archiveSha256 + optional commit/dirty from the once-per-run host-packed archive -
+ * archiveSha256 IS the pin; there is only ONE archive, so no per-lane unanimity math applies,
+ * unlike the cua fan-out route). Used for both the in-progress and final bundle: the archive
+ * never changes mid-run (packed before any sandbox exists).
+ */
+export declare function buildSubjectProvenance(args: {
+    localTreeRoute: boolean;
+    publicRepo: string;
+    subjectCommit: string | undefined;
+    localTreeArchive: LocalTreeArchive | undefined;
+    subjectEnvNames: string[];
+    state: RunSubjectProvenance["state"];
+}): RunSubjectProvenance;

package/dist/routes/shared-world/provenance.js

@@ -0,0 +1,65 @@
+// Subject provenance for the bundle, the checks on the served port and the getHost URL, and the
+// digest-only host and route labels.
+import { commandDigestOf } from "../../subject/state.js";
+/** Extract the in-sandbox port from the (loopback) serve.url so getHost can expose it. */
+export function servePort(serveUrl) {
+    const url = new URL(serveUrl);
+    if (url.port)
+        return Number(url.port);
+    return url.protocol === "https:" ? 443 : 80;
+}
+/** A getHost URL must be TOKENLESS (no userinfo, no query — no authKey; invariant 1). */
+export function isTokenlessHost(value) {
+    try {
+        const url = new URL(value);
+        return url.username === "" && url.password === "" && url.search === "";
+    }
+    catch {
+        return false;
+    }
+}
+/** sha256-16 of a URL's ORIGIN — the publish-safe host identity persisted in the bundle (the raw
+ *  getHost URL embeds the live sandbox id + matches the e2b-URL redaction, so it never lands raw). */
+export function hostOriginDigest(url) {
+    try {
+        return commandDigestOf(new URL(url).origin);
+    }
+    catch {
+        return commandDigestOf(url);
+    }
+}
+/** A public-safe, human-readable route label for the bundle (host redacted to a placeholder; the
+ *  entry path kept). Never contains the raw getHost URL. */
+export function publicSafeRouteLabel(entry) {
+    return `[provisioned-subject]${entry ?? "/"}`;
+}
+/**
+ * Build the ONE subject sandbox's provenance (invariant 5): clone (repo + optional commit) or
+ * local-tree (archiveSha256 + optional commit/dirty from the once-per-run host-packed archive -
+ * archiveSha256 IS the pin; there is only ONE archive, so no per-lane unanimity math applies,
+ * unlike the cua fan-out route). Used for both the in-progress and final bundle: the archive
+ * never changes mid-run (packed before any sandbox exists).
+ */
+export function buildSubjectProvenance(args) {
+    if (args.localTreeRoute) {
+        return {
+            source: "local-tree",
+            ...(args.localTreeArchive === undefined
+                ? {}
+                : { archiveSha256: args.localTreeArchive.archiveSha256 }),
+            ...(args.subjectCommit === undefined ? {} : { commit: args.subjectCommit }),
+            ...(args.localTreeArchive?.git === undefined
+                ? {}
+                : { dirty: args.localTreeArchive.git.dirty }),
+            envNames: args.subjectEnvNames,
+            state: args.state,
+        };
+    }
+    return {
+        source: "clone",
+        repo: args.publicRepo,
+        ...(args.subjectCommit === undefined ? {} : { commit: args.subjectCommit }),
+        envNames: args.subjectEnvNames,
+        state: args.state,
+    };
+}

package/dist/routes/shared-world/provisioned.d.ts

@@ -0,0 +1,57 @@
+import type { LabCommsEmail, LabConfig, LabSubjectServe, LabSubjectStateCheckpoint } from "../../lab/types.js";
+import type { RunSubjectStateStepRecord } from "../../run/bundle.js";
+import type { SharedWorldStateSnapshot } from "../../run/shared-world-evidence.js";
+import type { LocalTreeArchive } from "../../subject/local-tree-archive.js";
+import type { DetachedTimers } from "../../substrates/detached.js";
+import type { SharedWorldLabHooks } from "./types.js";
+import { type ActorRunResult, type SubjectDesktopUsage, type LiveParticipants, type PlaneContext } from "./types.js";
+/** What the provisioned plane needs besides the shared plane context. */
+export interface ProvisionedPlaneSetup {
+    serve: LabSubjectServe;
+    localTreeRoute: boolean;
+    localTreeArchive: LocalTreeArchive | undefined;
+    localTreeArchiveBuffer: ArrayBuffer | undefined;
+    subjectRepo: string;
+    publicRepo: string;
+    subjectEnvNames: string[];
+    hasGithubToken: boolean;
+    checkpoints: LabSubjectStateCheckpoint[];
+    /** The in-sandbox email catch, when a comms lab declared one. */
+    commsEmail: LabCommsEmail | undefined;
+    commsPort: number | undefined;
+    /** The catch's base URL, injected into the subject's env at create. */
+    commsEnv: Record<string, string>;
+    /** The executed seed steps. The plane appends; the orchestrator reads them at finish. */
+    stateStepRecords: RunSubjectStateStepRecord[];
+    /** The prober's state series. The plane appends; the orchestrator reads it at finish. */
+    stateSnapshots: SharedWorldStateSnapshot[];
+    timers: DetachedTimers;
+    proberCadenceMs: number;
+}
+/** What the provisioned plane hands back to the orchestrator. */
+export interface ProvisionedPlaneOutcome {
+    actorResults: ActorRunResult[];
+    runError: string | undefined;
+    subjectCommit: string | undefined;
+    subjectSandboxId: string | undefined;
+    subjectKilled: boolean;
+    subjectDesktop: SubjectDesktopUsage | undefined;
+    getHostUrl: string | undefined;
+    /** Set when the teardown drain wrote a comms thread. */
+    commsArtifactPath: string | undefined;
+}
+export declare function runProvisionedPlane(ctx: PlaneContext, live: LiveParticipants, setup: ProvisionedPlaneSetup): Promise<ProvisionedPlaneOutcome>;
+/**
+ * Packs the working tree once per run, on the host, for a local-tree subject. Returns the archive,
+ * or the message the run fails with.
+ */
+export declare function packSubjectTree(cwd: string, config: {
+    readonly subject: Pick<LabConfig["subject"], "localTree">;
+}, hooks: SharedWorldLabHooks, scrubKnownValues: (text: string) => string): Promise<{
+    ok: true;
+    archive: LocalTreeArchive;
+    buffer: ArrayBuffer;
+} | {
+    ok: false;
+    message: string;
+}>;