humanish 0.105.0 → 0.106.0

package/dist/lab/parse/values.js

@@ -0,0 +1,65 @@
+// The slug interpolates into an in-sandbox shell command; the strict shape is load-bearing.
+export const REPO_SLUG_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+export const ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+export function invalid(message) {
+    return { ok: false, error: { code: "HUMANISH_LAB_INVALID", message } };
+}
+export function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function str(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+export function optionalStr(key, value) {
+    const parsed = str(value);
+    return parsed === undefined ? {} : { [key]: parsed };
+}
+export function strList(value) {
+    if (typeof value === "string") {
+        const items = value
+            .split(",")
+            .map((item) => item.trim())
+            .filter(Boolean);
+        return items.length > 0 ? items : undefined;
+    }
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const items = value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return items.length > 0 ? items : undefined;
+}
+/**
+ * A positive integer from an environment value, or the fallback when it is absent or not one. It
+ * reads a leading integer the way parseInt does, so "90s" reads as 90; posInt below is stricter.
+ */
+export function readPositiveInt(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+export function posInt(value) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) {
+        return value;
+    }
+    if (typeof value === "string" && /^\d+$/.test(value)) {
+        const parsed = Number.parseInt(value, 10);
+        return Number.isSafeInteger(parsed) && parsed >= 1 ? parsed : undefined;
+    }
+    return undefined;
+}
+/** A non-negative finite number (0 allowed — caps default to 0 = no-spend). Accepts a numeric
+ *  string too, since YAML scalars can arrive as strings. */
+export function nonNegNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return value;
+    }
+    if (typeof value === "string" && /^\d+(\.\d+)?$/.test(value.trim())) {
+        const parsed = Number.parseFloat(value.trim());
+        return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+    }
+    return undefined;
+}

package/dist/lab/participant-assignment.d.ts

@@ -0,0 +1,12 @@
+import type { RunParticipantAssignment } from "../run/streams.js";
+/** Project only authored participant-facing fields. Never pass runtime-composed instructions:
+ * they can contain inbox URLs or multiplayer grants. Pick fields explicitly so a task's hidden
+ * success criteria cannot cross this evidence boundary, even from an untyped library caller. */
+export declare function participantAssignment(assignment: {
+    mission: string;
+    focus?: string;
+    tasks?: readonly {
+        id: string;
+        goal: string;
+    }[];
+}, scrubKnownValues?: (text: string) => string): RunParticipantAssignment;

package/dist/lab/participant-assignment.js

@@ -0,0 +1,19 @@
+import { redactText } from "../evidence/redaction.js";
+/** Project only authored participant-facing fields. Never pass runtime-composed instructions:
+ * they can contain inbox URLs or multiplayer grants. Pick fields explicitly so a task's hidden
+ * success criteria cannot cross this evidence boundary, even from an untyped library caller. */
+export function participantAssignment(assignment, scrubKnownValues = (text) => text) {
+    const sanitize = (text) => redactText(scrubKnownValues(text));
+    return {
+        mission: sanitize(assignment.mission),
+        ...(assignment.focus === undefined ? {} : { focus: sanitize(assignment.focus) }),
+        ...(assignment.tasks === undefined
+            ? {}
+            : {
+                tasks: assignment.tasks.map(({ id, goal }) => ({
+                    id: sanitize(id),
+                    goal: sanitize(goal),
+                })),
+            }),
+    };
+}

package/dist/lab/persona-resolve.d.ts

@@ -0,0 +1,39 @@
+import { type ResolvedPersona } from "./persona.js";
+import { type PreparedSelectedOutputDirectory } from "../run/contained-output.js";
+import type { LabActor } from "./types.js";
+/** Title-case an id for the fallback display name (`skeptical-power-user` -> `Skeptical Power User`). */
+export declare function personaTitleFromId(personaId: string): string;
+/**
+ * Resolve ONE persona from `humanish/personas/`, then the ignored `.humanish/local/personas/`.
+ * Returns `null` with a warning when the id is unsafe or no file exists. Invalid rich backgrounds
+ * reject the study before execution.
+ */
+export declare function resolveCommittedPersona(projectRoot: PreparedSelectedOutputDirectory, personaId: string): Promise<{
+    persona: ResolvedPersona | null;
+    warnings: string[];
+}>;
+/**
+ * Resolve every distinct persona id a run will use, once, before lane specs are built. Returning a
+ * map keeps the plan builder PURE (it is exported npm surface and asserted pure by tests): the
+ * async file reads happen here, and the composer only does a lookup.
+ */
+export declare function resolveCommittedPersonas(projectRoot: PreparedSelectedOutputDirectory, personaIds: readonly (string | undefined)[]): Promise<{
+    personas: Map<string, ResolvedPersona>;
+    warnings: string[];
+}>;
+/**
+ * Every persona id a lab config could put on a browser lane: the per-lane roster when one is
+ * declared, otherwise the actor-level persona that every fan-out lane inherits.
+ */
+export declare function labPersonaIds(config: {
+    actors?: readonly Pick<LabActor, "persona" | "lanes">[];
+}): string[];
+/**
+ * Same resolution from a plain cwd, for the labs that carry a directory string rather than an
+ * already-prepared root. Realpath-then-prepare mirrors the cua lab so a symlinked cwd still reads
+ * personas from the physical project.
+ */
+export declare function resolveCommittedPersonasForCwd(cwd: string, personaIds: readonly (string | undefined)[]): Promise<{
+    personas: Map<string, ResolvedPersona>;
+    warnings: string[];
+}>;

package/dist/lab/persona-resolve.js

@@ -0,0 +1,118 @@
+// Shared contained persona resolution for browser and terminal participants.
+import { parse as parseYaml } from "yaml";
+import path from "node:path";
+import { parseResolvedPersona, PersonaConfigError } from "./persona.js";
+import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
+import { digestText, redactText } from "../evidence/redaction.js";
+import { realpath } from "node:fs/promises";
+import { rosterOf } from "./parse/actors.js";
+/** Persona ids are file-name segments, never paths: the same grammar the terminal lane enforces. */
+const PERSONA_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/** Title-case an id for the fallback display name (`skeptical-power-user` -> `Skeptical Power User`). */
+export function personaTitleFromId(personaId) {
+    return personaId
+        .split(/[-_]/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+/** Where a persona id resolves, in order: a committed persona wins over a machine-local one. */
+const PERSONA_DIRECTORIES = [
+    path.posix.join("humanish", "personas"),
+    path.posix.join(".humanish", "local", "personas"),
+];
+/**
+ * Resolve ONE persona from `humanish/personas/`, then the ignored `.humanish/local/personas/`.
+ * Returns `null` with a warning when the id is unsafe or no file exists. Invalid rich backgrounds
+ * reject the study before execution.
+ */
+export async function resolveCommittedPersona(projectRoot, personaId) {
+    if (!PERSONA_ID_PATTERN.test(personaId)) {
+        return {
+            persona: null,
+            warnings: ["Persona id is not a safe filename; using the id only (no persona context)."],
+        };
+    }
+    for (const candidate of PERSONA_DIRECTORIES.flatMap((directory) => [
+        path.posix.join(directory, `${personaId}.yaml`),
+        path.posix.join(directory, `${personaId}.yml`),
+    ])) {
+        const bytes = await readContainedRegularFile(projectRoot, candidate);
+        if (!bytes)
+            continue;
+        let raw;
+        try {
+            raw = parseYaml(bytes.toString("utf8"));
+        }
+        catch {
+            return {
+                persona: null,
+                warnings: [
+                    `${candidate} could not be parsed as YAML; the participant ran with the persona id only (no traits applied).`,
+                ],
+            };
+        }
+        const warnings = [];
+        const persona = parseResolvedPersona(raw, { id: personaId, name: personaTitleFromId(personaId) }, warnings);
+        persona.sourceDigest = digestText(bytes.toString("utf8"));
+        return { persona, warnings: warnings.map((warning) => `${candidate}: ${warning}`) };
+    }
+    return {
+        persona: null,
+        warnings: [
+            `Persona ${redactText(personaId)} has no readable file under humanish/personas or .humanish/local/personas; using the id only (no persona context).`,
+        ],
+    };
+}
+/**
+ * Resolve every distinct persona id a run will use, once, before lane specs are built. Returning a
+ * map keeps the plan builder PURE (it is exported npm surface and asserted pure by tests): the
+ * async file reads happen here, and the composer only does a lookup.
+ */
+export async function resolveCommittedPersonas(projectRoot, personaIds) {
+    const personas = new Map();
+    const warnings = [];
+    for (const personaId of new Set(personaIds.filter((id) => typeof id === "string" && id.length > 0))) {
+        const resolved = await resolveCommittedPersona(projectRoot, personaId);
+        if (resolved.persona)
+            personas.set(personaId, resolved.persona);
+        warnings.push(...resolved.warnings);
+    }
+    return { personas, warnings };
+}
+/**
+ * Every persona id a lab config could put on a browser lane: the per-lane roster when one is
+ * declared, otherwise the actor-level persona that every fan-out lane inherits.
+ */
+export function labPersonaIds(config) {
+    const ids = [];
+    for (const actor of config.actors ?? []) {
+        if (actor.persona)
+            ids.push(actor.persona);
+        for (const entry of rosterOf(actor) ?? []) {
+            if (entry.persona)
+                ids.push(entry.persona);
+        }
+    }
+    return [...new Set(ids)];
+}
+/**
+ * Same resolution from a plain cwd, for the labs that carry a directory string rather than an
+ * already-prepared root. Realpath-then-prepare mirrors the cua lab so a symlinked cwd still reads
+ * personas from the physical project.
+ */
+export async function resolveCommittedPersonasForCwd(cwd, personaIds) {
+    try {
+        const physical = await realpath(path.resolve(cwd));
+        const projectRoot = await prepareSelectedOutputDirectory(path.dirname(physical), physical);
+        return await resolveCommittedPersonas(projectRoot, personaIds);
+    }
+    catch (error) {
+        if (error instanceof PersonaConfigError)
+            throw error;
+        return {
+            personas: new Map(),
+            warnings: ["Persona directory could not be read; no persona context was loaded."],
+        };
+    }
+}

package/dist/lab/persona.d.ts

@@ -0,0 +1,39 @@
+import type { ActorPersonaRef } from "../actors/contract.js";
+type PersonaLevel = "low" | "medium" | "high";
+export declare const PERSONA_BACKGROUND_MAX_BYTES: number;
+export declare class PersonaConfigError extends Error {
+    constructor(message: string);
+}
+export interface ResolvedPersona {
+    id: string;
+    name: string;
+    summary?: string;
+    background?: string;
+    /** Digest of the source file, when resolved from disk. */
+    sourceDigest?: string;
+    traits: {
+        patience?: PersonaLevel;
+        skill?: PersonaLevel;
+        accessibilityNeeds?: string;
+    };
+    constraints: string[];
+}
+export interface PersonaDirectives {
+    frictionTolerance: string;
+    skillBias: string;
+    accessibilityBehavior?: string;
+    constraints: string[];
+    /** Directives included in the prompt, not proof of behavioral adherence. */
+    traitsApplied: string[];
+}
+/** Legacy short fields keep their bounds, but every discarded value is diagnosed. */
+export declare function parseResolvedPersona(raw: unknown, fallback: {
+    id: string;
+    name: string;
+}, warnings?: string[]): ResolvedPersona;
+export declare function personaToDirectives(persona: ResolvedPersona): PersonaDirectives;
+export declare function renderPersonaPromptSection(persona: ResolvedPersona): string;
+/** Only the authored persona section; excludes task criteria, runtime grants and inbox URLs. */
+export declare function personaBrief(persona: ResolvedPersona, scrub?: (text: string) => string): NonNullable<ActorPersonaRef["brief"]>;
+export declare function scrubPersonaBrief(persona: ActorPersonaRef, scrub: (text: string) => string): ActorPersonaRef;
+export {};

package/dist/lab/persona.js

@@ -0,0 +1,192 @@
+import { digestText, redactText } from "../evidence/redaction.js";
+export const PERSONA_BACKGROUND_MAX_BYTES = 32 * 1024;
+const PERSONA_COMPILER_VERSION = 2;
+export class PersonaConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PersonaConfigError";
+    }
+}
+const LEVELS = ["low", "medium", "high"];
+const PERSONA_FIELDS = new Set([
+    "schema",
+    "id",
+    "name",
+    "summary",
+    "background",
+    "traits",
+    "constraints",
+]);
+const TRAIT_FIELDS = new Set(["patience", "technical_confidence", "accessibility_needs"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cleanText(value) {
+    return value
+        .replace(/\r\n?/g, "\n")
+        .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, " ")
+        .replace(/HUMANISH_ACTOR_(?:VERDICT|NONCE)/gi, "HUMANISH_ACTOR_[neutralized]")
+        .trim();
+}
+/** Legacy short fields keep their bounds, but every discarded value is diagnosed. */
+export function parseResolvedPersona(raw, fallback, warnings = []) {
+    const record = isRecord(raw) ? raw : {};
+    const traits = isRecord(record.traits) ? record.traits : {};
+    if (!isRecord(raw))
+        warnings.push("Persona must be a mapping; using the legacy defaults.");
+    for (const field of Object.keys(record)) {
+        if (!PERSONA_FIELDS.has(field))
+            warnings.push(`Unsupported persona field ${redactText(JSON.stringify(field))}; it is not sent to the participant. Use background for relevant context.`);
+    }
+    for (const field of Object.keys(traits)) {
+        if (!TRAIT_FIELDS.has(field))
+            warnings.push(`Unsupported persona trait ${redactText(JSON.stringify(field))}; it is not sent to the participant.`);
+    }
+    const short = (value, max, field) => {
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== "string") {
+            warnings.push(`${field} must be text; ignored.`);
+            return undefined;
+        }
+        const cleaned = cleanText(value).replace(/\s+/g, " ");
+        if (!cleaned)
+            return undefined;
+        if (cleaned.length > max)
+            warnings.push(`${field} exceeds ${max} characters and was shortened; move detailed context to background.`);
+        return cleaned.length > max ? `${cleaned.slice(0, max - 1)}…` : cleaned;
+    };
+    let background;
+    if (record.background !== undefined) {
+        if (typeof record.background !== "string")
+            throw new PersonaConfigError("Persona background must be text.");
+        background = cleanText(record.background);
+        if (!background)
+            throw new PersonaConfigError("Persona background must not be empty.");
+        if (Buffer.byteLength(record.background, "utf8") > PERSONA_BACKGROUND_MAX_BYTES ||
+            Buffer.byteLength(background, "utf8") > PERSONA_BACKGROUND_MAX_BYTES) {
+            throw new PersonaConfigError(`Persona background exceeds ${PERSONA_BACKGROUND_MAX_BYTES} UTF-8 bytes; shorten it explicitly. No background was truncated.`);
+        }
+    }
+    const level = (field) => {
+        const value = traits[field];
+        const normalized = typeof value === "string" ? value.trim().toLowerCase() : undefined;
+        if (LEVELS.includes(normalized))
+            return normalized;
+        if (value !== undefined)
+            warnings.push(`traits.${field} must be low, medium or high; ${background ? "ignored" : "using medium"}.`);
+        return background ? undefined : "medium";
+    };
+    if (record.traits !== undefined && !isRecord(record.traits))
+        warnings.push("Persona traits must be a mapping; invalid traits ignored.");
+    if (background &&
+        Object.keys(traits).some((field) => field === "patience" || field === "technical_confidence")) {
+        warnings.push("Background and explicit trait directives are both sent to the participant. Review the brief for conflicting instructions; prose conflicts are not automatically detected.");
+    }
+    let accessibilityNeeds = short(traits.accessibility_needs, 80, "traits.accessibility_needs");
+    if (accessibilityNeeds &&
+        /^(none[ _-]declared|none|not[ _-]applicable)$/i.test(accessibilityNeeds))
+        accessibilityNeeds = undefined;
+    if (record.constraints !== undefined && !Array.isArray(record.constraints))
+        warnings.push("Persona constraints must be a list; ignored.");
+    const allConstraints = Array.isArray(record.constraints) ? record.constraints : [];
+    if (allConstraints.length > 8)
+        warnings.push("Only the first eight persona constraints are used; move detailed context to background.");
+    const constraints = allConstraints
+        .slice(0, 8)
+        .map((value) => short(value, 160, "constraint"))
+        .filter((value) => value !== undefined);
+    const patience = level("patience"), skill = level("technical_confidence");
+    const summary = short(record.summary, 280, "summary");
+    return {
+        id: short(record.id, 120, "id") ?? fallback.id,
+        name: short(record.name, 120, "name") ?? fallback.name,
+        ...(summary === undefined ? {} : { summary }),
+        ...(background === undefined ? {} : { background }),
+        traits: {
+            ...(patience === undefined ? {} : { patience }),
+            ...(skill === undefined ? {} : { skill }),
+            ...(accessibilityNeeds === undefined ? {} : { accessibilityNeeds }),
+        },
+        constraints,
+    };
+}
+const FRICTION_TOLERANCE = {
+    low: "You are impatient: if you hit repeated friction or stop making progress toward your goal, you are likely to stop. Describe what you actually encountered.",
+    medium: "You have moderate patience: you will work through some friction, but may stop if further effort no longer seems worthwhile.",
+    high: "You are determined: you are willing to spend effort on recovery when the goal matters to you, but may stop at an unrecoverable dead-end.",
+};
+const SKILL_BIAS = {
+    low: "You are not technically confident and generally rely on familiar, visible controls. Describe confusion only when you actually encounter it.",
+    medium: "You have moderate technical confidence and generally use straightforward paths through the product.",
+    high: "You are technically confident and comfortable with keyboard shortcuts and advanced options on the surfaces this product gives you.",
+};
+function accessibilityBehavior(needs) {
+    if (/keyboard[ _-]first/i.test(needs))
+        return "You prefer keyboard navigation, but can use a pointer when needed. Describe any difficulty you encounter switching between them.";
+    if (/keyboard[ _-]only/i.test(needs))
+        return "You can only use the keyboard. If an essential control has no discoverable keyboard path, describe where you could not proceed.";
+    if (/terminal|output/i.test(needs))
+        return "You rely on clear terminal output. Describe any difficulty understanding the output you actually encounter.";
+    return `Your accessibility requirement is: ${needs}. Use the available interface within this requirement and describe any difficulty you encounter.`;
+}
+export function personaToDirectives(persona) {
+    const { patience, skill, accessibilityNeeds } = persona.traits;
+    const traitsApplied = [
+        ...(patience ? [`patience:${patience}`] : []),
+        ...(skill ? [`skill:${skill}`] : []),
+    ];
+    if (accessibilityNeeds)
+        traitsApplied.push(`accessibility:${accessibilityNeeds}`);
+    if (persona.constraints.length)
+        traitsApplied.push(`constraints:${persona.constraints.length}`);
+    return {
+        frictionTolerance: patience ? FRICTION_TOLERANCE[patience] : "",
+        skillBias: skill ? SKILL_BIAS[skill] : "",
+        ...(accessibilityNeeds
+            ? { accessibilityBehavior: accessibilityBehavior(accessibilityNeeds) }
+            : {}),
+        constraints: persona.constraints,
+        traitsApplied,
+    };
+}
+export function renderPersonaPromptSection(persona) {
+    const directives = personaToDirectives(persona);
+    return [
+        `Persona: ${persona.name}.`,
+        persona.summary,
+        persona.background ? `Background:\n${persona.background}` : undefined,
+        directives.frictionTolerance,
+        directives.skillBias,
+        directives.accessibilityBehavior,
+        persona.constraints.length
+            ? `Honor these constraints: ${persona.constraints.join("; ")}.`
+            : undefined,
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+}
+/** Only the authored persona section; excludes task criteria, runtime grants and inbox URLs. */
+export function personaBrief(persona, scrub = (text) => text) {
+    const original = renderPersonaPromptSection(persona), text = redactText(scrub(original));
+    return {
+        compilerVersion: PERSONA_COMPILER_VERSION,
+        text,
+        digest: digestText(original),
+        redacted: text !== original,
+        ...(persona.sourceDigest ? { sourceDigest: persona.sourceDigest } : {}),
+    };
+}
+export function scrubPersonaBrief(persona, scrub) {
+    if (!persona.brief)
+        return persona;
+    const text = redactText(scrub(persona.brief.text));
+    return {
+        ...persona,
+        brief: {
+            ...persona.brief,
+            text,
+            redacted: persona.brief.redacted || text !== persona.brief.text,
+        },
+    };
+}

package/dist/lab/plan-base.d.ts

@@ -0,0 +1,24 @@
+import type { RunLabProvenance } from "../run/status.js";
+import type { Brain, ComputerUsePlan, NonEmpty, PlannedAnalysis, ProvisionedSubject, Requirement } from "./plan-types.js";
+import type { LabConfig } from "./types.js";
+export type Base = Omit<ComputerUsePlan, "route" | "actor" | "runner" | "concurrency" | "sessionBudgetMs" | "sandboxMs" | "caps" | "rerun">;
+export declare function isNonEmpty<T>(values: readonly T[]): values is NonEmpty<T>;
+export declare function capsOf(config: LabConfig): ComputerUsePlan["caps"];
+export declare function provisionedSubject(config: LabConfig): ProvisionedSubject | undefined;
+/** Keys, env and local tools a live run checks right before it acquires anything. */
+export declare function desktopRequirements(config: LabConfig, args: {
+    e2b: boolean;
+    brain: Brain;
+    localVm: boolean;
+    externalCatch: boolean;
+}): Requirement[];
+export declare function brainOf(config: LabConfig, callerProvider: boolean): Brain;
+/** The fields every plan shares, from a config whose analysis already resolved. */
+export declare function planBase(config: LabConfig, input: {
+    readonly dryRun: boolean;
+    readonly lab?: RunLabProvenance;
+    readonly analysis?: {
+        readonly config?: PlannedAnalysis["config"] | undefined;
+        readonly preferLargerOutput?: boolean | undefined;
+    };
+}): Base;

package/dist/lab/plan-base.js

@@ -0,0 +1,113 @@
+// What every route planner shares: the plan fields common to all routes, the frozen residual config,
+// and the requirement and subject helpers.
+import { DEFAULT_OPENAI_CU_MODEL } from "../actors/computer-use/openai-provider.js";
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+function residualOf(config) {
+    const { comms, policies, personas, defaults, review } = config;
+    return deepFreeze(structuredClone({
+        ...(comms === undefined ? {} : { comms }),
+        ...(policies === undefined ? {} : { policies }),
+        ...(personas === undefined ? {} : { personas }),
+        ...(defaults === undefined ? {} : { defaults }),
+        ...(review === undefined ? {} : { review }),
+        ...(config.execution?.desktop === undefined && config.execution?.target === undefined
+            ? {}
+            : {
+                execution: {
+                    ...(config.execution?.desktop === undefined
+                        ? {}
+                        : { desktop: config.execution.desktop }),
+                    ...(config.execution?.target === undefined
+                        ? {}
+                        : { target: config.execution.target }),
+                },
+            }),
+        subject: {
+            ...(config.subject.clone === undefined ? {} : { clone: config.subject.clone }),
+            ...(config.subject.localTree === undefined ? {} : { localTree: config.subject.localTree }),
+            ...(config.subject.repos === undefined ? {} : { repos: config.subject.repos }),
+            ...(config.subject.envValues === undefined ? {} : { envValues: config.subject.envValues }),
+        },
+    }));
+}
+export function isNonEmpty(values) {
+    return values.length > 0;
+}
+export function capsOf(config) {
+    const caps = config.execution?.caps;
+    return {
+        ...(caps?.maxUsd === undefined ? {} : { maxUsd: caps.maxUsd }),
+        ...(caps?.maxTotalUsd === undefined ? {} : { maxTotalUsd: caps.maxTotalUsd }),
+    };
+}
+export function provisionedSubject(config) {
+    const { serve, state } = config.subject;
+    const env = config.subject.env ?? [];
+    if (serve === undefined)
+        return undefined;
+    const withState = state === undefined ? {} : { state };
+    if (config.subject.source === "local-tree")
+        return { kind: "local-tree", serve, env, ...withState };
+    const repo = config.subject.repos?.[0];
+    if (config.subject.source !== "clone" || repo === undefined)
+        return undefined;
+    return { kind: "clone", repo, serve, env, ...withState };
+}
+/** Keys, env and local tools a live run checks right before it acquires anything. */
+export function desktopRequirements(config, args) {
+    const requirements = [];
+    if (args.e2b)
+        requirements.push({ kind: "key", name: "E2B_API_KEY" });
+    if (args.localVm)
+        requirements.push({ kind: "local-vm" });
+    if (args.brain.kind === "openai")
+        requirements.push({ kind: "key", name: "OPENAI_API_KEY" });
+    if (args.brain.kind === "local-agent")
+        requirements.push({ kind: "local-agent", agent: args.brain.agent });
+    const env = config.subject.source === "clone" || config.subject.source === "local-tree";
+    const names = env ? (config.subject.env ?? []) : [];
+    if (isNonEmpty(names))
+        requirements.push({ kind: "subject-env", names });
+    const email = config.comms?.email;
+    if (args.externalCatch && email?.kind === "fake" && email.external !== undefined)
+        requirements.push({ kind: "external-catch", url: email.external.catchBaseUrl });
+    if (email?.kind === "real")
+        requirements.push({ kind: "receiving-connection", connection: email.connection });
+    return requirements;
+}
+export function brainOf(config, callerProvider) {
+    const actor = config.actors[0];
+    if (callerProvider)
+        return { kind: "caller" };
+    if (actor?.type === "local-agent")
+        return { kind: "local-agent", agent: actor.localAgent ?? "codex" };
+    return { kind: "openai", model: actor?.model ?? DEFAULT_OPENAI_CU_MODEL };
+}
+/** The fields every plan shares, from a config whose analysis already resolved. */
+export function planBase(config, input) {
+    const analysis = input.analysis?.config;
+    return {
+        labId: config.id,
+        ...(config.title === undefined ? {} : { title: config.title }),
+        ...(input.lab === undefined ? {} : { lab: input.lab }),
+        residual: residualOf(config),
+        dryRun: input.dryRun,
+        ...(analysis === undefined
+            ? {}
+            : {
+                analysis: {
+                    config: analysis,
+                    trigger: config.review?.analysis === undefined ? "default" : "explicit",
+                    preferLargerOutput: input.analysis?.preferLargerOutput === true,
+                },
+            }),
+        requirements: [],
+    };
+}