pome-sh 0.6.6

package/dist/src/demo/render.d.ts

@@ -0,0 +1,32 @@
+export type TrialVerdict = {
+    kind: "passed";
+    seconds: number;
+} | {
+    kind: "failed";
+    seconds: number;
+    note: string;
+} | {
+    kind: "errored";
+    reason: string;
+};
+/** Reassurance frame. "No signup. No API keys." is verbatim copy of record
+ *  ([DECISION] #5); the third line names the three places honestly — local
+ *  twin locally, model calls via the anonymous demo gateway, trace evaluated
+ *  in pome cloud. */
+export declare function reassuranceBox(): string[];
+export declare function twinReadyLine(seconds: number): string;
+export declare function trialsHeaderLine(count: number, taskName: string): string;
+export declare function evaluatingLine(index: number): string;
+export declare function trialLine(index: number, verdict: TrialVerdict): string;
+export interface SummaryInput {
+    verdicts: TrialVerdict[];
+    /** Most-common failed-criterion phrase across evaluated trials, if any. */
+    failingCriterionPhrase?: string;
+    /** How many evaluated trials failed that criterion. */
+    failingCriterionCount?: number;
+    previewUrl: string;
+}
+export declare function summaryLines(input: SummaryInput): string[];
+/** Compress a criterion's text into the short "start there" phrase: first
+ *  clause, lower-cased lead, ~60 chars. */
+export declare function criterionPhrase(text: string): string;

package/dist/src/demo/render.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// FDRS-643 — pure terminal rendering for `pome demo`, matching the
+// design-of-record (CLI moments.dc.html moment 01, task/code-model
+// vocabulary):
+//
+//   [bordered reassurance box]
+//   spinning up github twin … ready (1.2s)
+//   running 5 isolated trials of first-run-demo …
+//   trial 1  ✓  passed   14.3s
+//   trial 3  ✗  failed   15.9s  <criterion failure note>
+//   trial 5  ⚠  errored         <reason> — excluded
+//   ─────
+//   2 of 4 passed · 1 trial errored on <reason>, excluded from the fraction
+//   <failing-criterion phrase> in 2 of 4 — start there
+//   see the full breakdown — read-only, still no account:
+//   → https://app.pome.sh/demo/<group_id>
+//
+// Demo verdicts are WORDS (passed/failed), never scores; errored rows show
+// no duration and are EXCLUDED from the fraction's denominator.
+/** Reassurance frame. "No signup. No API keys." is verbatim copy of record
+ *  ([DECISION] #5); the third line names the three places honestly — local
+ *  twin locally, model calls via the anonymous demo gateway, trace evaluated
+ *  in pome cloud. */
+export function reassuranceBox() {
+    const lines = [
+        "pome demo · running locally",
+        "No signup. No API keys.",
+        "The GitHub twin runs on your machine; model calls go through pome's",
+        "anonymous demo gateway; the trace is evaluated in pome cloud.",
+        "Your repo and your data are never touched.",
+    ];
+    const width = Math.max(...lines.map((line) => line.length));
+    const top = `┌${"─".repeat(width + 2)}┐`;
+    const bottom = `└${"─".repeat(width + 2)}┘`;
+    return [top, ...lines.map((line) => `│ ${line.padEnd(width)} │`), bottom];
+}
+export function twinReadyLine(seconds) {
+    return `spinning up github twin … ready (${seconds.toFixed(1)}s)`;
+}
+export function trialsHeaderLine(count, taskName) {
+    return `running ${count} isolated trials of ${taskName} …`;
+}
+export function evaluatingLine(index) {
+    return `trial ${index}  …  evaluating in the cloud …`;
+}
+export function trialLine(index, verdict) {
+    switch (verdict.kind) {
+        case "passed":
+            return `trial ${index}  ✓  passed   ${formatSeconds(verdict.seconds)}`;
+        case "failed":
+            return `trial ${index}  ✗  failed   ${formatSeconds(verdict.seconds)}  ${verdict.note}`;
+        case "errored":
+            return `trial ${index}  ⚠  errored         ${verdict.reason} — excluded`;
+    }
+}
+function formatSeconds(seconds) {
+    return `${seconds.toFixed(1)}s`;
+}
+export function summaryLines(input) {
+    const passed = input.verdicts.filter((v) => v.kind === "passed").length;
+    const failed = input.verdicts.filter((v) => v.kind === "failed").length;
+    const errored = input.verdicts.filter((v) => v.kind === "errored");
+    const denominator = passed + failed;
+    const lines = ["─────"];
+    let fraction;
+    if (denominator === 0) {
+        fraction = "no trials were evaluated";
+    }
+    else {
+        fraction = `${passed} of ${denominator} passed`;
+    }
+    if (errored.length > 0) {
+        const reason = errored[0].reason;
+        const noun = errored.length === 1 ? "trial" : "trials";
+        fraction += ` · ${errored.length} ${noun} errored on ${reason}, excluded from the fraction`;
+    }
+    lines.push(fraction);
+    if (input.failingCriterionPhrase &&
+        typeof input.failingCriterionCount === "number" &&
+        input.failingCriterionCount > 0 &&
+        denominator > 0) {
+        lines.push(`${input.failingCriterionPhrase} in ${input.failingCriterionCount} of ${denominator} — start there`);
+    }
+    if (denominator > 0) {
+        lines.push("see the full breakdown — read-only, still no account:");
+        lines.push(`→ ${input.previewUrl}`);
+    }
+    return lines;
+}
+/** Compress a criterion's text into the short "start there" phrase: first
+ *  clause, lower-cased lead, ~60 chars. */
+export function criterionPhrase(text) {
+    const clause = text.split(/[.;]/)[0]?.trim() ?? text.trim();
+    const lowered = clause.length > 0 ? clause[0].toLowerCase() + clause.slice(1) : clause;
+    return lowered.length > 64 ? `${lowered.slice(0, 61).trimEnd()}…` : lowered;
+}

package/dist/src/demo/runDemo.d.ts

@@ -0,0 +1,33 @@
+import { runScenario, type RunScenarioOptions } from "../runner/runScenario.js";
+import { type HostedClient } from "../hosted/client.js";
+import { mintDemoSessions, type DemoSession } from "./mint.js";
+import { type TrialVerdict } from "./render.js";
+export type DemoTrialClient = Pick<HostedClient, "requestEventsUploadUrl" | "requestStateUploadUrl" | "requestSignalsUploadUrl" | "finalize">;
+export interface RunDemoOptions {
+    /** Control-plane base URL (POME_API_BASE, default https://api.pome.sh). */
+    apiBase: string;
+    /** Dashboard base for the preview link (default https://app.pome.sh). */
+    dashboardBase: string;
+    trials?: number;
+    artifactsDir?: string;
+    out?: (line: string) => void;
+    /** Agent command override. Default re-invokes this binary: `<node> <main.js> demo-agent`. */
+    agentCommand?: string;
+    captureServerCommand?: RunScenarioOptions["captureServerCommand"];
+    runScenarioFn?: typeof runScenario;
+    mintFn?: typeof mintDemoSessions;
+    /** Per-session upload/finalize client factory (bearer demo_token). */
+    trialClientFactory?: (session: DemoSession) => DemoTrialClient;
+    /** Skip the warm-up twin boot (tests). */
+    skipTwinWarmup?: boolean;
+}
+export interface RunDemoResult {
+    exitCode: number;
+    groupId: string;
+    verdicts: TrialVerdict[];
+}
+export declare function runDemo(options: RunDemoOptions): Promise<RunDemoResult>;
+/** Production default: re-invoke this same binary as `pome demo-agent`.
+ *  Quotes both parts so paths with spaces survive runAgentCommand's
+ *  shell-less split. */
+export declare function defaultDemoAgentCommand(execPath: string, scriptPath: string | undefined): string;

package/dist/src/demo/runDemo.js

@@ -0,0 +1,263 @@
+// SPDX-License-Identifier: Apache-2.0
+// FDRS-643 — `pome demo` orchestration: zero-auth cold start.
+//
+// Flow per the 2026-07-05 [DECISION] set:
+//   1. Reassurance frame first.
+//   2. Mint ALL k demo sessions upfront (POST /v1/demo/sessions, one shared
+//      grp_ id) — each 15-min TTL comfortably covers the run.
+//   3. Per trial: run the bundled agent through the REAL capture path
+//      (runScenario: in-process twin + capture-server child + POME_* env),
+//      upload the captured blobs with the trial's demo_token as Bearer, then
+//      POST /finalize (explicit 60s timeout) — the terminal verdict comes
+//      from that cloud evaluation. The CLI never scores locally.
+//   4. Errored trials are excluded from the verdict fraction; at-capacity
+//      402/429s render as honest labeled states (FDRS-662), never stack
+//      traces, never fabricated completions.
+//   5. Output ends with the no-login preview link
+//      {dashboard}/demo/<group_id>.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAvailablePort } from "../runner/ports.js";
+import { runScenario } from "../runner/runScenario.js";
+import { bootTwin } from "../twin/twinHarness.js";
+import { parseScenarioFile } from "../scenario/parseScenario.js";
+import { createHostedClient } from "../hosted/client.js";
+import { scoreFromFinalizeResponse, uploadRunBlobs, } from "../hosted/uploadAndFinalize.js";
+import { outcomeOf, scoreStatus } from "../score/view.js";
+import { HostedQuotaError } from "../hosted/errors.js";
+import { DemoCapacityError, capacityKindFrom, capacityLabel, parseCapacityMarker, } from "./capacity.js";
+import { newGroupId } from "./ids.js";
+import { mintDemoSessions } from "./mint.js";
+import { criterionPhrase, evaluatingLine, reassuranceBox, summaryLines, trialLine, trialsHeaderLine, twinReadyLine, } from "./render.js";
+import { DEMO_REPO, DEMO_TASK_NAME, demoTaskPath } from "./task.js";
+/** Explicit finalize timeout — the hosted client defaults to 30s; the demo
+ *  judge measured 5-8s, 60s is belt-and-braces ([DECISION]). */
+const DEMO_FINALIZE_TIMEOUT_MS = 60_000;
+export async function runDemo(options) {
+    const out = options.out ?? ((line) => console.error(line));
+    const trials = options.trials ?? 5;
+    const artifactsDir = options.artifactsDir ?? "runs";
+    const runScenarioFn = options.runScenarioFn ?? runScenario;
+    const mintFn = options.mintFn ?? mintDemoSessions;
+    const trialClientFactory = options.trialClientFactory ??
+        ((session) => createHostedClient({
+            baseUrl: options.apiBase,
+            apiKey: session.demo_token,
+            authScheme: "bearer",
+            timeoutMs: DEMO_FINALIZE_TIMEOUT_MS,
+        }));
+    const groupId = newGroupId();
+    const scenarioPath = demoTaskPath();
+    for (const line of reassuranceBox())
+        out(line);
+    out("");
+    // Mint all k sessions upfront — the group exists before the first trial
+    // runs, and an at-capacity day fails HERE with one honest line instead of
+    // half-way through a run.
+    let sessions;
+    try {
+        sessions = await mintFn({
+            apiBase: options.apiBase,
+            taskName: DEMO_TASK_NAME,
+            groupId,
+            count: trials,
+        });
+    }
+    catch (err) {
+        if (err instanceof DemoCapacityError) {
+            out(capacityLabel(err.kind));
+            return { exitCode: 4, groupId, verdicts: [] };
+        }
+        out(`could not reach the pome demo service (${err instanceof Error ? err.message : String(err)})`);
+        return { exitCode: 2, groupId, verdicts: [] };
+    }
+    // Warm-up boot: validates the packaged seed and gives the design's
+    // "spinning up github twin … ready" line an honest measurement. Each trial
+    // then boots its own isolated twin inside runScenario.
+    if (options.skipTwinWarmup !== true) {
+        const scenario = await parseScenarioFile(scenarioPath);
+        const warmupStart = Date.now();
+        const port = await getAvailablePort();
+        const harness = await bootTwin({
+            twin: "github",
+            seedState: scenario.seedState,
+            runId: "demo-warmup",
+            twinBaseUrl: `http://127.0.0.1:${port}`,
+        });
+        harness.close();
+        out(twinReadyLine((Date.now() - warmupStart) / 1000));
+    }
+    out(trialsHeaderLine(trials, DEMO_TASK_NAME));
+    const agentCommand = options.agentCommand ?? defaultDemoAgentCommand(process.execPath, process.argv[1]);
+    const verdicts = [];
+    // Failed-criterion texts across evaluated trials, for the "start there" line.
+    const collectedFailures = [];
+    let capacityAbort = null;
+    for (let i = 0; i < trials; i += 1) {
+        const session = sessions[i];
+        const trialNumber = i + 1;
+        let verdict;
+        try {
+            verdict = await runOneTrial({
+                trialNumber,
+                session,
+                scenarioPath,
+                agentCommand,
+                artifactsDir,
+                apiBase: options.apiBase,
+                runScenarioFn,
+                client: trialClientFactory(session),
+                captureServerCommand: options.captureServerCommand,
+                out,
+                collectedFailures,
+            });
+        }
+        catch (err) {
+            if (err instanceof DemoCapacityError) {
+                capacityAbort = capacityLabel(err.kind);
+                verdict = { kind: "errored", reason: "demo at capacity" };
+            }
+            else if (isJudgeCapQuota(err)) {
+                capacityAbort = capacityLabel("daily_judge_cap");
+                verdict = { kind: "errored", reason: "demo at capacity" };
+            }
+            else {
+                verdict = {
+                    kind: "errored",
+                    reason: shortReason(err instanceof Error ? err.message : String(err)),
+                };
+            }
+        }
+        verdicts.push(verdict);
+        out(trialLine(trialNumber, verdict));
+        if (capacityAbort)
+            break;
+    }
+    if (capacityAbort)
+        out(capacityAbort);
+    const failing = mostCommonFailedCriterion(collectedFailures);
+    out("");
+    for (const line of summaryLines({
+        verdicts,
+        failingCriterionPhrase: failing?.phrase,
+        failingCriterionCount: failing?.count,
+        previewUrl: `${options.dashboardBase.replace(/\/$/, "")}/demo/${groupId}`,
+    })) {
+        out(line);
+    }
+    const evaluated = verdicts.filter((v) => v.kind !== "errored").length;
+    const exitCode = evaluated > 0 ? 0 : capacityAbort ? 4 : 1;
+    return { exitCode, groupId, verdicts };
+}
+async function runOneTrial(input) {
+    const startedAt = Date.now();
+    const result = await input.runScenarioFn({
+        scenarioPath: input.scenarioPath,
+        agentCommand: input.agentCommand,
+        artifactsDir: input.artifactsDir,
+        captureServerCommand: input.captureServerCommand,
+        extraAgentEnv: {
+            POME_DEMO_LLM_URL: `${input.apiBase}/v1/demo/sessions/${input.session.session_id}/llm`,
+            POME_DEMO_TOKEN: input.session.demo_token,
+            POME_DEMO_TASK_NAME: DEMO_TASK_NAME,
+            POME_DEMO_REPO: DEMO_REPO,
+        },
+        egressExtraHosts: [new URL(input.apiBase).hostname],
+    });
+    const agentSeconds = (Date.now() - startedAt) / 1000;
+    if (result.exitCode !== 0) {
+        const capacityKind = parseCapacityMarker(result.agent.stderr);
+        if (capacityKind) {
+            throw new DemoCapacityError(capacityKind, capacityLabel(capacityKind));
+        }
+        if (result.agent.timedOut) {
+            return { kind: "errored", reason: "trial timed out" };
+        }
+        return {
+            kind: "errored",
+            reason: shortReason(lastLine(result.agent.stderr) ?? "agent failed"),
+        };
+    }
+    // Upload the genuinely captured blobs, then ask the cloud for the verdict.
+    input.out(evaluatingLine(input.trialNumber));
+    const runDir = result.artifacts.runDir;
+    const [eventsJsonl, stateInitialJson, stateFinalJson] = await Promise.all([
+        readFile(join(runDir, "events.jsonl"), "utf8"),
+        readFile(join(runDir, "state_initial.json"), "utf8"),
+        readFile(join(runDir, "state_final.json"), "utf8"),
+    ]);
+    const uploaded = await uploadRunBlobs(input.client, input.session.session_id, {
+        eventsJsonl,
+        stateInitialJson,
+        stateFinalJson,
+        signalsJsonl: "",
+    });
+    // criteria: [] — demo finalize replaces the client body with the
+    // server-owned task definition entirely (scenario_name selects it).
+    const finalized = await input.client.finalize(input.session.session_id, {
+        stopReason: "completed",
+        exitCode: 0,
+        durationMs: Math.max(0, Math.round(agentSeconds * 1000)),
+        agentModel: "demo-gateway",
+        agentSdk: null,
+        criteria: [],
+        scenarioName: DEMO_TASK_NAME,
+        scenarioHash: "",
+        scenarioPrompt: "",
+        expectedBehavior: "",
+        traceStorageKey: uploaded.eventsKey ?? undefined,
+        stateInitialStorageKey: uploaded.stateInitialKey ?? undefined,
+        stateFinalStorageKey: uploaded.stateFinalKey ?? undefined,
+    });
+    const score = scoreFromFinalizeResponse(finalized);
+    const status = scoreStatus(score, 100);
+    if (status === "pass") {
+        return { kind: "passed", seconds: agentSeconds };
+    }
+    if (status === "fail") {
+        const failedResults = score.results.filter((r) => outcomeOf(r) === "failed");
+        for (const r of failedResults)
+            input.collectedFailures.push(r.criterion.text);
+        const note = failedResults[0]
+            ? criterionPhrase(failedResults[0].criterion.text)
+            : "criterion not met";
+        return { kind: "failed", seconds: agentSeconds, note };
+    }
+    // Un-evaluated: the judge could not produce a verdict for this trace —
+    // honest exclusion, not a fabricated word.
+    return { kind: "errored", reason: "cloud could not evaluate the trace" };
+}
+function isJudgeCapQuota(err) {
+    return (err instanceof HostedQuotaError &&
+        capacityKindFrom(402, err.details?.kind) === "daily_judge_cap");
+}
+function mostCommonFailedCriterion(failures) {
+    if (failures.length === 0)
+        return null;
+    const counts = new Map();
+    for (const text of failures) {
+        counts.set(text, (counts.get(text) ?? 0) + 1);
+    }
+    const [text, count] = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+    return { phrase: criterionPhrase(text), count };
+}
+function lastLine(text) {
+    const lines = text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    return lines.length > 0 ? lines[lines.length - 1] : null;
+}
+function shortReason(reason) {
+    const flat = reason.replace(/\s+/g, " ").trim();
+    return flat.length > 72 ? `${flat.slice(0, 69)}…` : flat;
+}
+/** Production default: re-invoke this same binary as `pome demo-agent`.
+ *  Quotes both parts so paths with spaces survive runAgentCommand's
+ *  shell-less split. */
+export function defaultDemoAgentCommand(execPath, scriptPath) {
+    if (!scriptPath || scriptPath.length === 0) {
+        throw new Error("Cannot determine the pome binary path for the demo agent (process.argv[1] is empty).");
+    }
+    return `"${execPath}" "${scriptPath}" demo-agent`;
+}

package/dist/src/demo/task.d.ts

@@ -0,0 +1,10 @@
+/** Server-allowlisted demo task name (mint + gateway + finalize key). */
+export declare const DEMO_TASK_NAME = "first-run-demo";
+/** The repo the packaged seed creates; handed to the bundled agent. */
+export declare const DEMO_REPO = "acme/api";
+/**
+ * Absolute path of the packaged demo task markdown. Resolves next to this
+ * module: `src/demo/` in the dev tree, `dist/src/demo/` in the published
+ * package (copied by scripts/copy-prompts.mjs).
+ */
+export declare function demoTaskPath(): string;

package/dist/src/demo/task.js

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+// FDRS-643 — the packaged first-run demo task.
+//
+// `first-run-demo.md` (+ its hand-written seed sidecar) in this directory is
+// the CANONICAL demo task content. The cloud's server-owned judge definition
+// (pome-cloud apps/control-plane/src/lib/demo.ts,
+// DEMO_TASK_DEFINITIONS["first-run-demo"]) is regenerated from that markdown;
+// at finalize the cloud IGNORES the client body entirely and judges the
+// server copy, so the CLI-side pin here is informational (mint sends
+// task_hash: "").
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Server-allowlisted demo task name (mint + gateway + finalize key). */
+export const DEMO_TASK_NAME = "first-run-demo";
+/** The repo the packaged seed creates; handed to the bundled agent. */
+export const DEMO_REPO = "acme/api";
+/**
+ * Absolute path of the packaged demo task markdown. Resolves next to this
+ * module: `src/demo/` in the dev tree, `dist/src/demo/` in the published
+ * package (copied by scripts/copy-prompts.mjs).
+ */
+export function demoTaskPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidate = join(here, "first-run-demo.md");
+    if (!existsSync(candidate)) {
+        throw new Error(`Packaged demo task not found at ${candidate}. ` +
+            "This is a packaging bug — the demo task markdown ships with pome-sh " +
+            "(scripts/copy-prompts.mjs copies src/demo/ into dist/).");
+    }
+    return candidate;
+}

package/dist/src/doctor/checks.d.ts

@@ -0,0 +1,19 @@
+export type DoctorCheckId = "config" | "twin" | "routing" | "egress";
+export interface DoctorCheck {
+    id: DoctorCheckId;
+    status: "pass" | "fail";
+    label: string;
+    detail?: string;
+    cause?: string;
+    fix?: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+export interface RunDoctorChecksOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    mode?: "full" | "hosted";
+}
+export declare function runDoctorChecks(options?: RunDoctorChecksOptions): Promise<DoctorReport>;