@sweny-ai/core 0.1.207 → 0.1.208

package/dist/cli/run-history.d.ts

@@ -16,6 +16,15 @@ import { type SpendKind } from "../budget.js";
 export declare const RUN_HISTORY_SCHEMA_VERSION = 1;
 export declare const RUN_HISTORY_DIR: string;
 export declare const RUN_HISTORY_KEEP = 200;
+/**
+ * Version of the optional detail fields (per-node `tool_counts`, `tokens_in`, `tokens_out`,
+ * `num_turns`, and the record's `policy`), stamped as `detail_version` on records that carry them.
+ * `schema_version` stays 1: older records have no detail and read as such, and older readers ignore it.
+ */
+export declare const RUN_DETAIL_VERSION = 1;
+/** At most this many distinct tool names are kept per node, each cut to {@link TOOL_NAME_MAX} characters. */
+export declare const TOOL_COUNTS_MAX = 64;
+export declare const TOOL_NAME_MAX = 80;
 export type RunStatus = "success" | "failed" | "crashed";
 export interface RunNodeRecord {
     id: string;
@@ -27,6 +36,25 @@ export interface RunNodeRecord {
     /** SDK-reported cost; null when none was reported (never estimated). */
     cost_usd: number | null;
     retries: number;
+    /**
+     * Calls per tool name (names and counts only, never inputs or outputs). Optional: absent on records
+     * written before `detail_version` 1, and when the node made no tool call.
+     */
+    tool_counts?: Record<string, number>;
+    /** Input tokens, when the node reported usage. Optional (detail_version 1). */
+    tokens_in?: number;
+    /** Output tokens, when the node reported usage. Optional (detail_version 1). */
+    tokens_out?: number;
+    /** Model turns, when the node reported them. Optional (detail_version 1). */
+    num_turns?: number;
+}
+/** The agent floor the run ran under: booleans and a mode only. Optional (detail_version 1). */
+export interface RunPolicyRecord {
+    /** The agent subprocess env was narrowed to the allowlist on every node. */
+    scoped: boolean;
+    sandbox: "off" | "auto" | "strict";
+    /** The sandbox was enabled for every node that reported it. */
+    sandboxed: boolean;
 }
 export interface RunTotals {
     nodes_total: number;
@@ -65,6 +93,10 @@ export interface RunRecord {
      * jump in `totals` that no node explains shows here.
      */
     spend?: Partial<Record<SpendKind, RunKindSpend>>;
+    /** 1 when the optional detail fields below and on nodes are recorded. Absent on older records. */
+    detail_version?: number;
+    /** Absent when no node reported its floor. */
+    policy?: RunPolicyRecord;
 }
 export interface RunKindSpend {
     tokens: number;
@@ -84,6 +116,10 @@ export interface NodeTimer {
     lastResults: Map<string, NodeResult>;
 }
 export declare function createNodeTimer(now?: () => number): NodeTimer;
+/** Calls per tool name, in first-seen order. Names are cut and capped; undefined when there are none. */
+export declare function countTools(calls: ReadonlyArray<{
+    tool: string;
+}> | undefined): Record<string, number> | undefined;
 export interface BuildRunRecordInput {
     runId: string;
     workflow: Workflow;

package/dist/cli/run-history.js

@@ -20,6 +20,15 @@ import { openNoFollow } from "../safe-file.js";
 export const RUN_HISTORY_SCHEMA_VERSION = 1;
 export const RUN_HISTORY_DIR = path.join(".sweny", "runs");
 export const RUN_HISTORY_KEEP = 200;
+/**
+ * Version of the optional detail fields (per-node `tool_counts`, `tokens_in`, `tokens_out`,
+ * `num_turns`, and the record's `policy`), stamped as `detail_version` on records that carry them.
+ * `schema_version` stays 1: older records have no detail and read as such, and older readers ignore it.
+ */
+export const RUN_DETAIL_VERSION = 1;
+/** At most this many distinct tool names are kept per node, each cut to {@link TOOL_NAME_MAX} characters. */
+export const TOOL_COUNTS_MAX = 64;
+export const TOOL_NAME_MAX = 80;
 const RECORD_READ_MAX_BYTES = 1024 * 1024;
 // ── Hash + ids ──────────────────────────────────────────────────
 function canonicalize(value) {
@@ -78,6 +87,29 @@ export function createNodeTimer(now = Date.now) {
 }
 // ── Build the record ────────────────────────────────────────────
 const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+/** Calls per tool name, in first-seen order. Names are cut and capped; undefined when there are none. */
+export function countTools(calls) {
+    const counts = new Map();
+    for (const c of calls ?? []) {
+        if (typeof c?.tool !== "string")
+            continue;
+        // eslint-disable-next-line no-control-regex
+        const name = c.tool.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, TOOL_NAME_MAX);
+        if (name === "")
+            continue;
+        if (!counts.has(name) && counts.size >= TOOL_COUNTS_MAX)
+            continue;
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+    }
+    if (counts.size === 0)
+        return undefined;
+    const out = {};
+    // defineProperty: a tool named `__proto__` stays a plain key.
+    for (const [k, v] of counts) {
+        Object.defineProperty(out, k, { value: v, enumerable: true, writable: true, configurable: true });
+    }
+    return out;
+}
 export function buildRunRecord(i) {
     const summary = summarizeRun(i.results, i.durationMs, i.crashed, i.trace);
     const retries = new Map();
@@ -91,6 +123,7 @@ export function buildRunRecord(i) {
         const tokens = hasTokens
             ? (isNum(u.inputTokens) ? u.inputTokens : 0) + (isNum(u.outputTokens) ? u.outputTokens : 0)
             : null;
+        const toolCounts = countTools(r.toolCalls);
         return {
             id,
             status: r.status,
@@ -99,6 +132,10 @@ export function buildRunRecord(i) {
             tokens,
             cost_usd: u && isNum(u.costUsd) ? u.costUsd : null,
             retries: retries.get(id) ?? 0,
+            ...(toolCounts ? { tool_counts: toolCounts } : {}),
+            ...(u && isNum(u.inputTokens) ? { tokens_in: u.inputTokens } : {}),
+            ...(u && isNum(u.outputTokens) ? { tokens_out: u.outputTokens } : {}),
+            ...(u && isNum(u.numTurns) ? { num_turns: u.numTurns } : {}),
         };
     });
     const harness = [...i.results.values()].find((r) => r.harness)?.harness;
@@ -124,6 +161,16 @@ export function buildRunRecord(i) {
         ...(harness ? { harness: { id: harness.id, version: harness.version } } : {}),
         ...(degraded.length > 0 ? { degraded } : {}),
         ...(summary.spend ? { spend: recordSpend(summary.spend) } : {}),
+        detail_version: RUN_DETAIL_VERSION,
+        ...(summary.policy?.envScope !== undefined && summary.policy.sandbox
+            ? {
+                policy: {
+                    scoped: summary.policy.envScope,
+                    sandbox: summary.policy.sandbox.mode,
+                    sandboxed: summary.policy.sandbox.started,
+                },
+            }
+            : {}),
     };
 }
 function recordSpend(spend) {
@@ -205,6 +252,29 @@ const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
 const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
 const numOrNull = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
 const RUNGS = new Set(["expr", "decider", "agent"]);
+const SANDBOX_MODES = new Set(["off", "auto", "strict"]);
+const count = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+/**
+ * Per-tool counts read back: own keys only, names within the writer's own limits (no control
+ * characters, at most TOOL_NAME_MAX long, at most TOOL_COUNTS_MAX of them), values non-negative
+ * integers. Anything else is dropped; undefined when nothing is left.
+ */
+function parseToolCounts(v) {
+    if (!isObj(v))
+        return undefined;
+    const out = {};
+    let kept = 0;
+    for (const [k, c] of Object.entries(v)) {
+        if (kept >= TOOL_COUNTS_MAX)
+            break;
+        // eslint-disable-next-line no-control-regex
+        if (k === "" || k.length > TOOL_NAME_MAX || /[\u0000-\u001f\u007f]/.test(k) || !count(c))
+            continue;
+        Object.defineProperty(out, k, { value: c, enumerable: true, writable: true, configurable: true });
+        kept++;
+    }
+    return kept > 0 ? out : undefined;
+}
 /**
  * A typed, allow-listed copy of a stored record, or null when it is not a run record. History is
  * agent-writable, so a record is never passed through: only the documented fields are copied, numbers
@@ -235,15 +305,23 @@ function parseRecord(v) {
         status: v.status,
         nodes: v.nodes
             .filter((n) => isObj(n) && typeof n.id === "string" && typeof n.status === "string")
-            .map((n) => ({
-            id: n.id,
-            status: n.status,
-            duration_ms: num(n.duration_ms),
-            tool_calls: num(n.tool_calls),
-            tokens: numOrNull(n.tokens),
-            cost_usd: numOrNull(n.cost_usd),
-            retries: num(n.retries),
-        })),
+            .map((n) => {
+            const toolCounts = parseToolCounts(n.tool_counts);
+            return {
+                id: n.id,
+                status: n.status,
+                duration_ms: num(n.duration_ms),
+                tool_calls: num(n.tool_calls),
+                tokens: numOrNull(n.tokens),
+                cost_usd: numOrNull(n.cost_usd),
+                retries: num(n.retries),
+                // detail_version 1 fields: optional, kept only when well-formed.
+                ...(toolCounts ? { tool_counts: toolCounts } : {}),
+                ...(count(n.tokens_in) ? { tokens_in: n.tokens_in } : {}),
+                ...(count(n.tokens_out) ? { tokens_out: n.tokens_out } : {}),
+                ...(count(n.num_turns) ? { num_turns: n.num_turns } : {}),
+            };
+        }),
         routes: v.routes
             .filter((e) => isObj(e) && typeof e.from === "string" && typeof e.to === "string")
             .map((e) => ({
@@ -263,6 +341,19 @@ function parseRecord(v) {
     if (isObj(v.harness) && typeof v.harness.id === "string" && typeof v.harness.version === "string") {
         out.harness = { id: v.harness.id, version: v.harness.version };
     }
+    if (count(v.detail_version) && v.detail_version >= 1)
+        out.detail_version = v.detail_version;
+    if (isObj(v.policy) &&
+        typeof v.policy.scoped === "boolean" &&
+        typeof v.policy.sandboxed === "boolean" &&
+        typeof v.policy.sandbox === "string" &&
+        SANDBOX_MODES.has(v.policy.sandbox)) {
+        out.policy = {
+            scoped: v.policy.scoped,
+            sandbox: v.policy.sandbox,
+            sandboxed: v.policy.sandboxed,
+        };
+    }
     if (Array.isArray(v.degraded))
         out.degraded = v.degraded.filter((d) => typeof d === "string");
     if (isObj(v.spend)) {

package/dist/cli/try-capture.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `sweny try --capture <run>`: turn a recorded run into the `sweny try` fixture (#537).
+ *
+ * Input is what a real run already left in `.sweny/runs/`: the history record
+ * (`<run-id>.json`, run-history.ts) and the answers (`<run-id>/answers.json`,
+ * run-answers.ts). Output is a `TryFixture` with `illustrative: false`, so
+ * `sweny try` labels it "a replay of a real run on <date>".
+ *
+ * Nothing is invented. Durations, tool-call counts, token and cost totals, the
+ * harness, the policy floor and the answer all come from the record. A run that
+ * lacks them (written before `detail_version` 1), failed, or answered nothing is
+ * refused with the reason, never padded. The answer is redacted a second time
+ * here (the journal's redactor plus the run's secret values), so a token that
+ * slipped past the first pass does not reach a committed file.
+ *
+ * Deterministic: fixed key order, no clock, no randomness. The same run always
+ * yields the same bytes.
+ */
+import { type RunAnswers } from "./run-answers.js";
+import { type RunRecord } from "./run-history.js";
+import { type TryFixture } from "./try.js";
+export interface CaptureOptions {
+    /** `owner/name` of the repo the run was on (a record does not hold it). */
+    sampleRepo: string;
+    /** Extra secret values to scrub from the answer. Default: none beyond the redactor's patterns. */
+    secrets?: string[];
+}
+/**
+ * The fixture for one recorded run. Throws, naming the reason, when the run cannot honestly be one:
+ * not a success, no detail (older record), no harness, an unknown template or node, or no answers.
+ */
+export declare function buildTryFixture(record: RunRecord, answers: RunAnswers | null, opts: CaptureOptions): TryFixture;
+/** The committed bytes: two-space JSON, a trailing newline. */
+export declare function serializeTryFixture(fixture: TryFixture): string;
+export interface CaptureSource {
+    record: RunRecord;
+    answers: RunAnswers | null;
+}
+/**
+ * Find the run a `--capture` argument names, through the same validating readers `sweny runs` uses
+ * (history is agent-writable, so a planted or linked file is skipped, not trusted). `ref` is
+ * `latest` (newest record under `<cwd>/.sweny/runs`), a run id or unique prefix, or a path to the run
+ * dir (`.sweny/runs/<id>`) or its record (`.sweny/runs/<id>.json`).
+ */
+export declare function resolveCaptureRun(ref: string, cwd?: string): CaptureSource;
+export interface CaptureRequest {
+    ref: string;
+    repo?: string;
+    /** Write the fixture here. Default: return it for stdout. */
+    out?: string;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+}
+/** Resolve, convert and (when `out` is set) write. Returns the fixture text and where it went. */
+export declare function captureTryFixture(req: CaptureRequest): {
+    text: string;
+    fixture: TryFixture;
+    wrote?: string;
+};

package/dist/cli/try-capture.js

@@ -0,0 +1,157 @@
+/**
+ * `sweny try --capture <run>`: turn a recorded run into the `sweny try` fixture (#537).
+ *
+ * Input is what a real run already left in `.sweny/runs/`: the history record
+ * (`<run-id>.json`, run-history.ts) and the answers (`<run-id>/answers.json`,
+ * run-answers.ts). Output is a `TryFixture` with `illustrative: false`, so
+ * `sweny try` labels it "a replay of a real run on <date>".
+ *
+ * Nothing is invented. Durations, tool-call counts, token and cost totals, the
+ * harness, the policy floor and the answer all come from the record. A run that
+ * lacks them (written before `detail_version` 1), failed, or answered nothing is
+ * refused with the reason, never padded. The answer is redacted a second time
+ * here (the journal's redactor plus the run's secret values), so a token that
+ * slipped past the first pass does not reach a committed file.
+ *
+ * Deterministic: fixed key order, no clock, no randomness. The same run always
+ * yields the same bytes.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { redact, runSecretValues } from "../journal.js";
+import { readRunAnswers } from "./run-answers.js";
+import { RUN_HISTORY_DIR, RUN_ID_RE, findRun, listRuns } from "./run-history.js";
+import { loadTryWorkflow, parseTryFixture } from "./try.js";
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+function usageOf(n) {
+    const usage = {};
+    if (typeof n.tokens_in === "number")
+        usage.inputTokens = n.tokens_in;
+    if (typeof n.tokens_out === "number")
+        usage.outputTokens = n.tokens_out;
+    if (typeof n.cost_usd === "number")
+        usage.costUsd = n.cost_usd;
+    if (typeof n.num_turns === "number")
+        usage.numTurns = n.num_turns;
+    return Object.keys(usage).length > 0 ? usage : undefined;
+}
+/**
+ * The fixture for one recorded run. Throws, naming the reason, when the run cannot honestly be one:
+ * not a success, no detail (older record), no harness, an unknown template or node, or no answers.
+ */
+export function buildTryFixture(record, answers, opts) {
+    const refuse = (why) => {
+        throw new Error(`cannot capture run ${record.run_id}: ${why}`);
+    };
+    if (!REPO_RE.test(opts.sampleRepo))
+        refuse(`--repo must look like owner/name, got "${opts.sampleRepo}"`);
+    if (record.status !== "success")
+        refuse(`it ended ${record.status}; a demo is captured from a successful run`);
+    if (typeof record.detail_version !== "number" || record.detail_version < 1) {
+        refuse("it predates per-tool call counts (no detail_version). Re-run with a sweny that records them");
+    }
+    if (!record.harness)
+        refuse("it recorded no harness");
+    if (!record.policy)
+        refuse("it recorded no policy floor (env scope and sandbox)");
+    if (!answers)
+        refuse("it has no answers.json");
+    if (answers.run_id !== record.run_id || answers.workflow_id !== record.workflow_id) {
+        refuse("answers.json belongs to a different run");
+    }
+    if (record.nodes.length === 0)
+        refuse("it recorded no nodes");
+    const workflow = loadTryWorkflow(record.workflow_id);
+    const secrets = opts.secrets ?? [];
+    const nodes = {};
+    for (const n of record.nodes) {
+        if (!workflow.nodes[n.id])
+            refuse(`node "${n.id}" is not in the ${record.workflow_id} template`);
+        if (n.status !== "success")
+            refuse(`node "${n.id}" ended ${n.status}`);
+        const usage = usageOf(n);
+        // Only nodes whose template declares an output schema: a free-form `summary` (what answers.json
+        // keeps for a node with no schema) is the agent's working notes, not the answer, and stays out.
+        const schema = workflow.nodes[n.id].output;
+        const declared = schema?.properties && Object.keys(schema.properties).length > 0 ? answers.nodes[n.id] : undefined;
+        const output = declared ? redact(declared, secrets).value : undefined;
+        nodes[n.id] = {
+            duration_ms: n.duration_ms,
+            tool_calls: { ...(n.tool_counts ?? {}) },
+            ...(usage ? { usage } : {}),
+            ...(output && Object.keys(output).length > 0 ? { output } : {}),
+        };
+    }
+    if (!Object.values(nodes).some((n) => n.output))
+        refuse("no node recorded an answer");
+    const date = record.started_at.slice(0, 10);
+    return parseTryFixture({
+        schema_version: 1,
+        illustrative: false,
+        captured_at: record.started_at,
+        notice: `A replay of a real run of ${record.workflow_id} on ${opts.sampleRepo}, started ${record.started_at.slice(0, 19)}Z (${date}). ` +
+            "Durations, tool-call counts, token usage and cost are as recorded; the answer is redacted. " +
+            "Made by `sweny try --capture`; do not edit by hand.",
+        workflow: record.workflow_id,
+        sample_repo: opts.sampleRepo,
+        harness: { id: record.harness.id, version: record.harness.version },
+        policy: {
+            envScope: record.policy.scoped,
+            sandbox: record.policy.sandbox,
+            sandboxStarted: record.policy.sandboxed,
+        },
+        nodes,
+    });
+}
+/** The committed bytes: two-space JSON, a trailing newline. */
+export function serializeTryFixture(fixture) {
+    return `${JSON.stringify(fixture, null, 2)}\n`;
+}
+/**
+ * Find the run a `--capture` argument names, through the same validating readers `sweny runs` uses
+ * (history is agent-writable, so a planted or linked file is skipped, not trusted). `ref` is
+ * `latest` (newest record under `<cwd>/.sweny/runs`), a run id or unique prefix, or a path to the run
+ * dir (`.sweny/runs/<id>`) or its record (`.sweny/runs/<id>.json`).
+ */
+export function resolveCaptureRun(ref, cwd = process.cwd()) {
+    let root = cwd;
+    let wanted = ref;
+    if (ref !== "latest" && !RUN_ID_RE.test(ref)) {
+        const abs = path.resolve(cwd, ref);
+        const id = path.basename(abs).replace(/\.json$/, "");
+        const runsDir = path.dirname(abs);
+        const stateDir = path.dirname(runsDir);
+        if (path.basename(runsDir) !== path.basename(RUN_HISTORY_DIR) || path.basename(stateDir) !== ".sweny") {
+            // Not a path into .sweny/runs: maybe a unique id prefix.
+            wanted = ref;
+        }
+        else {
+            root = path.dirname(stateDir);
+            wanted = id;
+        }
+    }
+    const runs = listRuns(root);
+    const record = wanted === "latest" ? runs[0] : findRun(runs, wanted);
+    if (!record) {
+        throw new Error(`no run "${ref}" under ${path.join(root, RUN_HISTORY_DIR)}` +
+            (runs.length === 0 ? " (no runs recorded there)" : ""));
+    }
+    return { record, answers: readRunAnswers(record.run_id, root) };
+}
+/** Resolve, convert and (when `out` is set) write. Returns the fixture text and where it went. */
+export function captureTryFixture(req) {
+    const env = req.env ?? process.env;
+    const cwd = req.cwd ?? process.cwd();
+    const repo = req.repo ?? env.GITHUB_REPOSITORY;
+    if (!repo)
+        throw new Error("--repo owner/name is required (GITHUB_REPOSITORY is not set)");
+    const { record, answers } = resolveCaptureRun(req.ref, cwd);
+    const fixture = buildTryFixture(record, answers, { sampleRepo: repo, secrets: runSecretValues(undefined, env) });
+    const text = serializeTryFixture(fixture);
+    if (!req.out)
+        return { text, fixture };
+    const file = path.resolve(cwd, req.out);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, text, { mode: 0o644 });
+    return { text, fixture, wrote: file };
+}

package/dist/cli/try.d.ts

@@ -9,7 +9,9 @@
  * executor is empty by construction.
  *
  * The recording lives in `try-fixture.json` (metadata plus the sample answer
- * only). Until a real run is recorded it is labelled illustrative.
+ * only). Until a real run is committed (`illustrative: false`, made by
+ * `sweny try --capture`, try-capture.ts) it is labelled illustrative; a real one
+ * says "replay of a real run on <date>" instead.
  */
 import type { Command } from "commander";
 import type { AgentHarness } from "../harness/types.js";
@@ -33,6 +35,11 @@ export interface TryFixture {
     schema_version: 1;
     /** True until the owner replaces the file with a recording of a real run. */
     illustrative: boolean;
+    /**
+     * When the recorded run started (ISO 8601). Required when `illustrative` is false: the label says
+     * "replay of a real run on <date>".
+     */
+    captured_at?: string;
     notice: string;
     /** Built-in template id the recording is of. */
     workflow: string;
@@ -62,13 +69,19 @@ export declare function loadTryWorkflow(templateId: string): Workflow;
  * reported through `onProgress` spread across that time so progress feels live.
  */
 export declare function createReplayHarness(fixture: TryFixture, opts: {
-    paceMs: number;
+    paceMs: number | ((nodeId: string) => number);
 }): AgentHarness;
 export declare const TRY_BANNER_TITLE = "Recorded demo";
 /** The one command to run next: scaffolds the same workflow on the user's repo and says how to run it. */
 export declare const TRY_NEXT_COMMAND = "npx @sweny-ai/core new --template explain-repo";
 /** Appended to `sweny try --help`. */
 export declare const TRY_HELP_NOTE: string;
+/** `YYYY-MM-DD` of the recorded run, or "" when the fixture carries none. */
+export declare function capturedDate(fixture: TryFixture): string;
+/** What the recording is, in one clause: the label `sweny try` shows. Illustrative until a real run is committed. */
+export declare function tryLabel(fixture: TryFixture): string;
+/** The note under `sweny try --help`, for the recording that ships. */
+export declare function tryHelpNote(fixture: TryFixture): string;
 /** The tagline, then the demo notice as one dim line. */
 export declare function formatTryBanner(fixture: TryFixture, paint?: Paint, unicode?: boolean): string;
 /** The closing line: one command. */
@@ -76,7 +89,11 @@ export declare function formatTryNext(paint?: Paint): string;
 export interface TryOptions {
     /** Replay instantly (and land the stamp without the one-frame pause). */
     fast?: boolean;
-    /** Milliseconds each node takes to replay. Default 1200. Ignored with `fast`. */
+    /**
+     * Milliseconds each node takes to replay, fixed. Default: the recorded timings scaled to about
+     * {@link REPLAY_TARGET_MS} in total, and instant when output is not a live terminal (non-TTY, CI,
+     * dumb terminal). Ignored with `fast`.
+     */
     paceMs?: number;
     /** Also write the PR-comment markdown here. */
     commentFile?: string;
@@ -94,7 +111,12 @@ export interface TryOptions {
     columns?: number;
     fixture?: TryFixture;
 }
-export declare const DEFAULT_TRY_PACE_MS = 1200;
+/** A default replay takes about this long in total, however long the real run took. */
+export declare const REPLAY_TARGET_MS = 8000;
+/** No node replays faster than this unless the replay is instant. */
+export declare const REPLAY_NODE_MIN_MS = 250;
+/** Per-node replay time: the recorded durations scaled to {@link REPLAY_TARGET_MS} in total (never slowed down). */
+export declare function scaledPace(fixture: TryFixture, targetMs?: number): (nodeId: string) => number;
 /** The line that opens the job summary preview (record.ts cuts the preview from here). */
 export declare const SUMMARY_PREVIEW_LEAD = "In CI, the job summary gets this heading, this DAG and the receipt below:";
 /** Replay the recording. Returns the process exit code. */

package/dist/cli/try.js

@@ -9,7 +9,9 @@
  * executor is empty by construction.
  *
  * The recording lives in `try-fixture.json` (metadata plus the sample answer
- * only). Until a real run is recorded it is labelled illustrative.
+ * only). Until a real run is committed (`illustrative: false`, made by
+ * `sweny try --capture`, try-capture.ts) it is labelled illustrative; a real one
+ * says "replay of a real run on <date>" instead.
  */
 import fs from "node:fs";
 import { workspaceRoot, writeFileNoFollow } from "../safe-file.js";
@@ -24,9 +26,10 @@ import { formatReceiptDuration, summarizeRun } from "./run-output.js";
 import { DagRenderer } from "./renderer.js";
 import { createNodeProgress, toolCallsText } from "./progress.js";
 import { createPaint } from "./style.js";
-import { colorEnabled, glyphsFor, supportsUnicode, terminalColumns } from "./terminal.js";
+import { colorEnabled, glyphsFor, richOutput, supportsUnicode, terminalColumns } from "./terminal.js";
 import { writeReceipt } from "./ticket.js";
 import { SWENY_TAGLINE } from "../theme.js";
+const CAPTURED_AT_RE = /^\d{4}-\d{2}-\d{2}(T[\d:.]+Z)?$/;
 const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
 /** Shape check with a message naming the first bad field. Throws on a malformed fixture. */
 export function parseTryFixture(raw) {
@@ -43,6 +46,12 @@ export function parseTryFixture(raw) {
     }
     if (typeof raw.illustrative !== "boolean")
         bad("illustrative must be a boolean");
+    if (raw.illustrative === false && (typeof raw.captured_at !== "string" || !CAPTURED_AT_RE.test(raw.captured_at))) {
+        bad("a real recording (illustrative: false) needs captured_at, an ISO date such as 2026-11-12T14:00:00.000Z");
+    }
+    if (raw.captured_at !== undefined && (typeof raw.captured_at !== "string" || !CAPTURED_AT_RE.test(raw.captured_at))) {
+        bad("captured_at must be an ISO date");
+    }
     if (!isObj(raw.harness) || typeof raw.harness.id !== "string" || typeof raw.harness.version !== "string") {
         bad("harness must be { id, version }");
     }
@@ -135,7 +144,8 @@ export function createReplayHarness(fixture, opts) {
                 for (let i = 0; i < count; i++)
                     toolCalls.push({ tool, input: {} });
             }
-            const step = toolCalls.length > 0 ? opts.paceMs / toolCalls.length : opts.paceMs;
+            const nodePace = typeof opts.paceMs === "function" ? opts.paceMs(id) : opts.paceMs;
+            const step = toolCalls.length > 0 ? nodePace / toolCalls.length : nodePace;
             for (const tc of toolCalls) {
                 await sleep(step, req.signal);
                 req.onProgress?.(tc.tool);
@@ -161,20 +171,46 @@ export const TRY_NEXT_COMMAND = "npx @sweny-ai/core new --template explain-repo"
 /** Appended to `sweny try --help`. */
 export const TRY_HELP_NOTE = "The recording is ILLUSTRATIVE SAMPLE DATA (a fictional repo, hand-written timings and token counts), not output from a real run. " +
     "Nothing runs: no agent, no network, no credentials read, no files written.";
+/** `YYYY-MM-DD` of the recorded run, or "" when the fixture carries none. */
+export function capturedDate(fixture) {
+    return fixture.captured_at?.slice(0, 10) ?? "";
+}
+/** What the recording is, in one clause: the label `sweny try` shows. Illustrative until a real run is committed. */
+export function tryLabel(fixture) {
+    return fixture.illustrative
+        ? `of ${fixture.workflow} on a sample repo (${fixture.sample_repo}), illustrative data`
+        : `of ${fixture.workflow} on ${fixture.sample_repo}, a replay of a real run on ${capturedDate(fixture)}`;
+}
+/** The note under `sweny try --help`, for the recording that ships. */
+export function tryHelpNote(fixture) {
+    return fixture.illustrative
+        ? TRY_HELP_NOTE
+        : `The recording is a replay of a real run of ${fixture.workflow} on ${fixture.sample_repo} (${capturedDate(fixture)}): ` +
+            "recorded tool-call counts, tokens, cost and answer (redacted), timings scaled for replay. " +
+            "Nothing runs now: no agent, no network, no credentials read, no files written.";
+}
 /** The tagline, then the demo notice as one dim line. */
 export function formatTryBanner(fixture, paint = createPaint(false), unicode = true) {
     const g = glyphsFor(unicode);
-    const data = fixture.illustrative ? ", illustrative data" : "";
     return [
         `  ${paint.brand(g.brand)} ${paint.strong("SWEny")}  ${SWENY_TAGLINE}`,
-        paint.muted(`  ${TRY_BANNER_TITLE} of ${fixture.workflow} on a sample repo (${fixture.sample_repo})${data}. No agent, network or credentials.`),
+        paint.muted(`  ${TRY_BANNER_TITLE} ${tryLabel(fixture)}. No agent, network or credentials.`),
     ].join("\n");
 }
 /** The closing line: one command. */
 export function formatTryNext(paint = createPaint(false)) {
     return `  ${paint.muted("Run it on your repo:")}  ${paint.strong(TRY_NEXT_COMMAND)}`;
 }
-export const DEFAULT_TRY_PACE_MS = 1200;
+/** A default replay takes about this long in total, however long the real run took. */
+export const REPLAY_TARGET_MS = 8000;
+/** No node replays faster than this unless the replay is instant. */
+export const REPLAY_NODE_MIN_MS = 250;
+/** Per-node replay time: the recorded durations scaled to {@link REPLAY_TARGET_MS} in total (never slowed down). */
+export function scaledPace(fixture, targetMs = REPLAY_TARGET_MS) {
+    const total = Object.values(fixture.nodes).reduce((a, n) => a + n.duration_ms, 0);
+    const scale = total > targetMs ? targetMs / total : 1;
+    return (id) => Math.max(REPLAY_NODE_MIN_MS, Math.round((fixture.nodes[id]?.duration_ms ?? 0) * scale));
+}
 const silentLogger = { info() { }, warn() { }, error() { }, debug() { } };
 /** The line that opens the job summary preview (record.ts cuts the preview from here). */
 export const SUMMARY_PREVIEW_LEAD = "In CI, the job summary gets this heading, this DAG and the receipt below:";
@@ -182,8 +218,16 @@ export const SUMMARY_PREVIEW_LEAD = "In CI, the job summary gets this heading, t
 export async function runTry(opts = {}) {
     const write = opts.write ?? ((s) => void process.stdout.write(s));
     const tty = opts.tty ?? Boolean(process.stdout.isTTY);
-    const paceMs = opts.fast ? 0 : Math.max(0, opts.paceMs ?? DEFAULT_TRY_PACE_MS);
     const fixture = opts.fixture ?? loadTryFixture();
+    // Explicit pace wins. Otherwise real timings, scaled, on a live terminal only: a pipe, CI or a
+    // dumb terminal gets the replay at once (the receipt shows the recorded times either way).
+    const paceMs = opts.fast
+        ? 0
+        : opts.paceMs !== undefined
+            ? Math.max(0, opts.paceMs)
+            : richOutput({ isTTY: tty }, process.env)
+                ? scaledPace(fixture)
+                : 0;
     const workflow = loadTryWorkflow(fixture.workflow);
     for (const id of Object.keys(fixture.nodes)) {
         if (!workflow.nodes[id])
@@ -281,16 +325,53 @@ export async function runTry(opts = {}) {
     write(`${formatTryNext(paint)}\n\n`);
     return receipt.ok ? 0 : 1;
 }
+/** The shipped fixture's label, falling back to the illustrative wording when it cannot be read. */
+function shippedHelp() {
+    try {
+        const fixture = loadTryFixture();
+        return {
+            description: fixture.illustrative
+                ? "Replay a recorded demo run: no credentials, no network, no model calls (illustrative sample data)"
+                : "Replay a recorded real run: no credentials, no network, no model calls",
+            note: tryHelpNote(fixture),
+        };
+    }
+    catch {
+        return {
+            description: "Replay a recorded demo run: no credentials, no network, no model calls (illustrative sample data)",
+            note: TRY_HELP_NOTE,
+        };
+    }
+}
 export function registerTryCommand(program) {
+    const help = shippedHelp();
     return program
         .command("try")
-        .description("Replay a recorded demo run: no credentials, no network, no model calls (illustrative sample data)")
+        .description(help.description)
         .option("--fast", "Replay instantly instead of pacing the progress")
-        .option("--pace <ms>", `Milliseconds each node takes to replay (default ${DEFAULT_TRY_PACE_MS})`)
+        .option("--pace <ms>", `Fixed milliseconds per node (default: the recorded timings scaled to about ${REPLAY_TARGET_MS / 1000}s, instant when not a live terminal)`)
         .option("--comment-file <path>", "Also write the PR-comment markdown to <path>")
         .option("--record <file.svg>", "Write the demo as an animated, self-contained SVG terminal recording to <file.svg>")
-        .addHelpText("after", `\n${TRY_HELP_NOTE}\n`)
+        .option("--capture <run>", "Convert a recorded run (latest, a run id, or a path under .sweny/runs) into a try fixture instead of replaying")
+        .option("--repo <owner/name>", "With --capture: the repo the run was on (default: GITHUB_REPOSITORY)")
+        .option("--out <file>", "With --capture: write the fixture to <file> (default: stdout)")
+        .addHelpText("after", `\n${help.note}\n`)
         .action(async (options) => {
+        if (options.capture) {
+            try {
+                const { captureTryFixture } = await import("./try-capture.js");
+                const res = captureTryFixture({ ref: options.capture, repo: options.repo, out: options.out });
+                if (res.wrote)
+                    process.stderr.write(`  wrote ${res.wrote} (replay of run ${res.fixture.captured_at})\n`);
+                else
+                    process.stdout.write(res.text);
+            }
+            catch (err) {
+                console.error(`\n  could not capture the run: ${err instanceof Error ? err.message : err}\n`);
+                process.exitCode = 1;
+            }
+            return;
+        }
         if (options.record) {
             try {
                 const { recordTrySvgToFile } = await import("./record.js");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.207",
+  "version": "0.1.208",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"