humanish 0.38.0 → 0.40.0

package/dist/orientation.js

@@ -0,0 +1,95 @@
+// What `humanish` says when you run it with no arguments (#367).
+//
+// It used to print commander's help: sixteen subcommands before any value, identical whether you
+// had never run the tool or had a finished study sitting on disk. That is a poor first contact for
+// a human, and it is worse for a coding agent, which needs to know WHERE IT IS before it can choose
+// a command — help is a menu, not an orientation.
+//
+// So bare invocation answers three questions instead: what is this, what state is this project in,
+// and what should I run next. The answer is derived from the project rather than fixed, so it is
+// useful on first contact and still useful on the hundredth run.
+//
+// Both audiences are served by the same data (docs/principles/three-roles.md). A human on a
+// terminal gets prose and an offer to set things up; an agent gets the same facts as stable text,
+// or as JSON with `--json`. Neither is a special case of the other bolted on afterwards.
+import { listLabManifests } from "./labs.js";
+import { listRuns } from "./run.js";
+export const ORIENTATION_SCHEMA = "humanish.orientation.v1";
+/**
+ * Read the project's state. Pure-ish: it only reads, never writes, and never touches the network or
+ * a provider — bare invocation must not be able to spend money or mutate a repo.
+ */
+export async function readOrientation(cwd) {
+    const [labs, runs] = await Promise.all([
+        listLabManifests(cwd).catch(() => undefined),
+        listRuns(cwd).catch(() => undefined)
+    ]);
+    const labIds = (labs?.labs ?? []).map((lab) => lab.id).filter((id) => typeof id === "string");
+    const runIds = (runs?.runs ?? []).map((run) => run.runId).filter((id) => typeof id === "string");
+    const latest = typeof runs?.latest === "string" ? runs.latest : runIds[0];
+    const initialized = (labs?.labs ?? []).some((lab) => lab.origin === "committed") || labIds.length > 0;
+    return {
+        schema: ORIENTATION_SCHEMA,
+        initialized,
+        labCount: labIds.length,
+        labIds: labIds.slice(0, 3),
+        runCount: runIds.length,
+        ...(latest === undefined ? {} : { latestRunId: latest }),
+        nextCommands: nextCommandsFor({ initialized, labIds, hasRun: runIds.length > 0 })
+    };
+}
+/**
+ * The two or three commands worth running from this state. Deliberately short: a list of everything
+ * is what bare invocation used to print, and it is why nobody read it.
+ */
+function nextCommandsFor(args) {
+    if (!args.initialized) {
+        return [
+            { command: "humanish init", why: "create humanish/ with a starter lab and persona" },
+            { command: "humanish run first-run", why: "a synthetic run with no keys and no spend, to see the shape of the evidence" }
+        ];
+    }
+    const suggestedLab = args.labIds[0];
+    const commands = [
+        {
+            command: suggestedLab ? `humanish watch ${suggestedLab}` : "humanish watch",
+            why: "run a lab and open the Observer while it goes"
+        }
+    ];
+    if (args.hasRun) {
+        commands.push({ command: "humanish verify --run latest", why: "check the last run's evidence and public-safety gates" });
+        commands.push({ command: "humanish observe --run latest", why: "reopen the last run's Observer" });
+    }
+    else {
+        commands.push({ command: "humanish lab list", why: "see the labs this project declares" });
+        commands.push({ command: "humanish doctor", why: "check what this project still needs before a live run" });
+    }
+    return commands;
+}
+/**
+ * The human rendering. Says where you are before it says what to do, because "what should I run"
+ * has no answer that is true in every project.
+ */
+export function formatOrientationHuman(state) {
+    const lines = [
+        "humanish — run realistic synthetic personas against your app and keep the evidence.",
+        ""
+    ];
+    if (!state.initialized) {
+        lines.push("This project is not set up yet.");
+    }
+    else {
+        const labs = state.labCount === 1 ? "1 lab" : `${state.labCount} labs`;
+        const runs = state.runCount === 0 ? "no runs yet" : state.runCount === 1 ? "1 run" : `${state.runCount} runs`;
+        lines.push(`This project has ${labs} and ${runs}${state.latestRunId ? ` (latest: ${state.latestRunId})` : ""}.`);
+    }
+    lines.push("");
+    for (const next of state.nextCommands) {
+        lines.push(`  ${next.command}`);
+        lines.push(`      ${next.why}`);
+    }
+    lines.push("");
+    lines.push("`humanish --help` lists every command.");
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=orientation.js.map

package/dist/orientation.js.map

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

package/dist/persona-resolve.d.ts

@@ -0,0 +1,44 @@
+import { type ResolvedPersona } from "./persona.js";
+import { type PreparedSelectedOutputDirectory } from "./selected-output-paths.js";
+/** Persona ids are file-name segments, never paths: the same grammar the terminal lane enforces. */
+export declare const PERSONA_ID_PATTERN: RegExp;
+/** Title-case an id for the fallback display name (`skeptical-power-user` -> `Skeptical Power User`). */
+export declare function personaTitleFromId(personaId: string): string;
+/**
+ * Resolve ONE committed persona. Returns `null` (never a throw, never a guess) when the id is
+ * unsafe or no file exists, so a lane always runs.
+ */
+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 {
+        persona?: string;
+        lanes?: readonly {
+            persona?: string;
+        }[];
+    }[];
+}): 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/persona-resolve.js

@@ -0,0 +1,109 @@
+// Resolve committed persona files into compiled personas, for EVERY lane (#381).
+//
+// #308 gave the terminal lane this: read `humanish/personas/<id>.yaml`, compile the traits into
+// behavioral directives, and record truthfully which traits were applied. The computer-use lanes
+// never got it — they composed a bare `Persona: <id>.` line and hardcoded `traitsApplied: []`, so
+// on browser routes the persona axis was a label rather than a behavior. A live two-lane contrast
+// (an impatient expert vs a patient newcomer, same app, same mission) came back with near-identical
+// action profiles, which read like evidence that personas do not matter and was actually evidence
+// that personas were never applied.
+//
+// This module is the shared implementation so the two routes cannot drift again: one containment
+// rule, one compiler, one fallback polarity.
+//
+// FAIL-SAFE, not fail-closed — deliberately the opposite polarity to the scorer loader. A persona
+// that declared nothing must never be given fabricated traits, so an unsafe id, a missing file, or
+// unparseable YAML falls back to the bare id line with a truthful EMPTY traitsApplied (warning only
+// when the file existed but could not be read). Silence here is honest; invention would not be.
+import { parse as parseYaml } from "yaml";
+import path from "node:path";
+import { parseResolvedPersona } from "./persona.js";
+import { prepareSelectedOutputDirectory, readContainedRegularFile } from "./selected-output-paths.js";
+import { realpath } from "node:fs/promises";
+/** Persona ids are file-name segments, never paths: the same grammar the terminal lane enforces. */
+export 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(" ");
+}
+/**
+ * Resolve ONE committed persona. Returns `null` (never a throw, never a guess) when the id is
+ * unsafe or no file exists, so a lane always runs.
+ */
+export async function resolveCommittedPersona(projectRoot, personaId) {
+    if (!PERSONA_ID_PATTERN.test(personaId)) {
+        return { persona: null, warnings: [] };
+    }
+    for (const candidate of [
+        path.posix.join("humanish", "personas", `${personaId}.yaml`),
+        path.posix.join("humanish", "personas", `${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 lane ran with the persona id only (no traits applied).`]
+            };
+        }
+        return { persona: parseResolvedPersona(raw, { id: personaId, name: personaTitleFromId(personaId) }), warnings: [] };
+    }
+    return { persona: null, warnings: [] };
+}
+/**
+ * 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 lane of actor.lanes ?? []) {
+            if (lane.persona)
+                ids.push(lane.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 {
+        return { personas: new Map(), warnings: [] };
+    }
+}
+//# sourceMappingURL=persona-resolve.js.map

package/dist/persona-resolve.js.map

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

package/dist/pi-agent-core.js

@@ -21,6 +21,10 @@ export function piStatusToCompletionReason(status) {
             return "timed_out";
         case "blocked":
             return "blocked_approval";
+        case "abandoned":
+            return "gave_up";
+        case "incomplete":
+            return "budget_reached";
         case "failed":
             return "actor_error";
     }

package/dist/pi-agent-core.js.map

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

package/dist/pricing.d.ts

@@ -6,6 +6,11 @@ export interface ModelRate {
     inputUsdPerToken: number;
     /** USD per output token. */
     outputUsdPerToken: number;
+    /** USD per input token served from the provider's prompt cache, when the provider bills those at
+     *  a reduced rate. Optional: absent means we do not model a discount and every input token is
+     *  billed at `inputUsdPerToken` — the previous behavior, kept as the fallback so a rate sheet
+     *  without this field prices exactly as it did before (#391). */
+    cachedInputUsdPerToken?: number;
     /** "YYYY-MM-DD" the entry was last checked against `source`. */
     asOf: string;
     /** Public pricing page the number came from (a comment/URL, never a secret). */
@@ -45,6 +50,9 @@ export interface ActorEstimatedCost {
         outputUsd: number;
         inputTokens: number;
         outputTokens: number;
+        /** Of `inputTokens`, how many were billed at the reduced cached rate. Present only when the
+         *  provider reported cache hits AND the rate sheet models a cached rate. */
+        cachedInputTokens?: number;
     };
 }
 /** The desktop-minute cost ESTIMATE (host-side create->teardown span * a per-minute rate). Same

package/dist/pricing.js

@@ -23,13 +23,14 @@ export const MODEL_RATES = {
         asOf: "2026-08-01",
         source: "openai.com/api/pricing (computer-use-preview)"
     },
-    // gpt-5.5 = the shipped CUA default (DEFAULT_OPENAI_CU_MODEL). $5 / 1M input, $30 / 1M output
-    // ($0.50 / 1M cached input, not modeled here). NOTE: OpenAI's live pricing page no longer lists
-    // gpt-5.5 (superseded by the gpt-5.6 family) — rate confirmed against public third-party sheets
-    // instead; refreshing the default model is tracked in issue #334.
+    // gpt-5.5 = the shipped CUA default (DEFAULT_OPENAI_CU_MODEL). $5 / 1M input, $30 / 1M output,
+    // $0.50 / 1M cached input. NOTE: OpenAI's live pricing page no longer lists gpt-5.5 (superseded
+    // by the gpt-5.6 family) — rate confirmed against public third-party sheets instead; refreshing
+    // the default model is tracked in issue #334.
     "gpt-5.5": {
         inputUsdPerToken: 5e-6,
         outputUsdPerToken: 30e-6,
+        cachedInputUsdPerToken: 0.5e-6,
         asOf: "2026-08-05",
         source: "openrouter.ai/openai/gpt-5.5 (gpt-5.5 no longer on openai.com/api/pricing; see #334)"
     }
@@ -73,7 +74,16 @@ export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
     }
     const inTok = tokenUsage.input ?? 0;
     const outTok = tokenUsage.output ?? 0;
-    const inputUsd = round6(inTok * rate.inputUsdPerToken);
+    // Cached input is billed at a fraction of the full rate, and on a session that threads state
+    // through the provider it is the MAJORITY of input — a warm prefix is re-sent every turn. Pricing
+    // it at the full rate overstated real spend by up to ~10x on long sessions, which is enough to
+    // abort a run against its own cap for money it never spent (#391).
+    //
+    // Both halves are honestly absent: no reported cachedInput, or a rate sheet without a cached
+    // rate, prices exactly as before. We never assume a discount we cannot evidence.
+    const cachedTok = rate.cachedInputUsdPerToken === undefined ? 0 : Math.min(inTok, Math.max(0, tokenUsage.cachedInput ?? 0));
+    const fullTok = inTok - cachedTok;
+    const inputUsd = round6(fullTok * rate.inputUsdPerToken + cachedTok * (rate.cachedInputUsdPerToken ?? 0));
     const outputUsd = round6(outTok * rate.outputUsdPerToken);
     return {
         schema: ACTOR_ESTIMATED_COST_SCHEMA,
@@ -82,7 +92,13 @@ export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
         source: rate.source,
         ...(modelId ? { modelId } : {}),
         ...(rate.placeholder ? { placeholder: true } : {}),
-        breakdown: { inputUsd, outputUsd, inputTokens: inTok, outputTokens: outTok }
+        breakdown: {
+            inputUsd,
+            outputUsd,
+            inputTokens: inTok,
+            outputTokens: outTok,
+            ...(cachedTok > 0 ? { cachedInputTokens: cachedTok } : {})
+        }
     };
 }
 /**

package/dist/pricing.js.map

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

package/dist/program.js

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { formatOrientationHuman, readOrientation } from "./orientation.js";
 import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -136,6 +137,18 @@ function reportUnexpectedActionError(command, io, error) {
 export function createProgram(io = {}) {
     const cliIo = { ...defaultIo, ...io };
     const program = new HumanishCommand(undefined, cliIo);
+    // Bare `humanish` orients instead of printing sixteen subcommands (#367). --help is untouched;
+    // this is only what happens when no command was chosen at all.
+    program.action(async (options) => {
+        const state = await readOrientation(".");
+        if (options.json === true) {
+            cliIo.writeOut(`${JSON.stringify(state, null, 2)}\n`);
+        }
+        else {
+            cliIo.writeOut(formatOrientationHuman(state));
+        }
+        cliIo.setExitCode(0);
+    });
     program
         .name("humanish")
         .description("Open-source-safe persona simulation CLI and proof harness.")
@@ -387,6 +400,8 @@ function registerCommsCommands(parent, io) {
         .option("--port <port>", "Port for capture + inbox (default 8025).", String(DEFAULT_SANDBOX_CATCH_PORT))
         .option("--dir <path>", "Directory for the deliveries log and rendered inbox.", ".humanish/comms-catch")
         .option("--token <value>", "Require this bearer token on GET /deliveries (recommended when reachable off-host).")
+        .option("--inbox-port <port>", "Also serve a READ-ONLY inbox listener on 0.0.0.0:<port>, so a persona on another machine can open /inbox. Without it the catch stays loopback-only.")
+        .option("--recipient <address>", "Only render mail sent to this address (repeatable). Default: render whatever the app actually mailed.", (value, previous = []) => [...previous, value])
         .action(async (options) => {
         const port = Number.parseInt(options.port, 10);
         if (!Number.isInteger(port) || port <= 0 || port > 65_534) {
@@ -394,7 +409,27 @@ function registerCommsCommands(parent, io) {
             io.setExitCode(2);
             return;
         }
-        await runCommsCatchHost({ port, dir: options.dir, ...(options.token ? { token: options.token } : {}) }, io);
+        let inboxPort;
+        if (options.inboxPort !== undefined) {
+            inboxPort = Number.parseInt(options.inboxPort, 10);
+            if (!Number.isInteger(inboxPort) || inboxPort <= 0 || inboxPort > 65_534) {
+                io.writeErr("--inbox-port must be an integer between 1 and 65534.\n");
+                io.setExitCode(2);
+                return;
+            }
+            if (inboxPort === port) {
+                io.writeErr("--inbox-port must differ from --port (the capture listener is loopback-only; the inbox listener is not).\n");
+                io.setExitCode(2);
+                return;
+            }
+        }
+        await runCommsCatchHost({
+            port,
+            dir: options.dir,
+            ...(options.token ? { token: options.token } : {}),
+            ...(inboxPort === undefined ? {} : { inboxPort }),
+            ...(options.recipient && options.recipient.length > 0 ? { recipients: options.recipient } : {})
+        }, io);
     });
 }
 function registerReclaimCommand(parent, io) {