jevway 0.1.2 → 0.2.0

package/dist/{task → recording}/recording.js

@@ -2,7 +2,11 @@ import { execFile } from 'node:child_process';
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
-import { BASE_STYLE, clock, dollars, escapeHtml, fact, FONT_LINK, playerMarkup, plural, PLAYER_SCRIPT, seconds, statusWord, thousands, } from './recording-page.js';
+import { safeSlug, stepFileName } from '../output/layout.js';
+import { describeStep } from './describe-step.js';
+import { escapeHtml } from './recording-page.js';
+import { renderRunPage } from './run-page.js';
+export { describeStep, escapeHtml };
 const VIDEO = 'run.mp4';
 // The video shows what changed, not how long anyone waited: no frame holds longer than this.
 const LONGEST_FRAME_S = 1.5;
@@ -17,41 +21,26 @@ const SHORTEST_FRAME_S = 1 / 30;
 export const frameDurations = (times) => times.map((at, i) => i === times.length - 1 ? LONGEST_FRAME_S : Math.min(LONGEST_FRAME_S, Math.max(SHORTEST_FRAME_S, times[i + 1] - at)));
 /** Seconds into the encoded video at which the wall-clock moment `at` appears. */
 export const videoOffset = (times, durations, at) => times.reduce((offset, time, i) => (time < at ? offset + durations[i] : offset), 0);
-// Row labels carry a whole table row; a sentence needs its first words.
-const shorten = (label, max = 70) => {
-    const text = label.replace(/\s+/g, ' ').trim();
-    return text.length > max ? `${text.slice(0, max).replace(/\s+\S*$/, '')}…` : text;
-};
-/**
- * A step as one plain sentence for people reading a recording.
- *
- * @example
- * describeStep({ operation: 'TYPE_TEXT', element: 'Search traces', valueKey: 'search_query' })
- * // 'Type the "search_query" value into "Search traces"'
- */
-export const describeStep = ({ operation, element = '', valueKey, option }) => {
-    const target = `"${shorten(element)}"`;
+// A step shot's name: the verb and what it acts on, short enough to read in a file list.
+const stepWords = ({ operation, element = '', valueKey, fileKey, option }) => {
     switch (operation) {
         case 'CLICK':
-            return `Click ${target}`;
         case 'CLICK_AT':
-            return `Click the control at ${target} by its on-screen position`;
+            return `click ${element}`;
         case 'TYPE_TEXT':
-            return `Type the "${valueKey}" value into ${target}`;
+            return `type ${valueKey ?? element}`;
+        case 'UPLOAD':
+            return `upload ${fileKey ?? element}`;
         case 'SELECT':
-            return option ? `Choose "${option}" in ${target}` : `Choose an option in ${target}`;
+            return `select ${option ?? element}`;
         case 'PRESS_ENTER':
-            return `Press Enter in ${target} to submit it`;
         case 'PRESS_ESCAPE':
-            return 'Press Escape to close the open menu or popup';
         case 'SCROLL_DOWN':
-            return 'Scroll down to reveal more of the page';
         case 'SCROLL_UP':
-            return 'Scroll back up';
         case 'WAIT':
-            return 'Wait for the page to finish updating';
+            return operation.replace('_', ' ');
         default:
-            return `${operation} ${target}`;
+            return `finished ${operation}`;
     }
 };
 /**
@@ -60,12 +49,14 @@ export const describeStep = ({ operation, element = '', valueKey, option }) => {
  * and an `index.html` viewer. Separate from what the model sees.
  *
  * @example
- * const task = new BrowserTask(tab, ask, { goal, recordDir: 'runs/langfuse' });
- * await task.run(); // runs/langfuse/run.mp4, 01.jpg … index.html
+ * const task = new BrowserTask(tab, ask, { goal, output: { dir: 'runs/langfuse', record: true } });
+ * await task.run(); // runs/langfuse/run.mp4, steps/01-click-traces.jpg … index.html
  */
 export class Recording {
     steps = [];
     summaries = [];
+    /** What each call was asked, scrubbed, one per summary. */
+    asked = [];
     #dir;
     #frames = [];
     /** The page size the screencast reports (CSS pixels): the run page and the reports shape the video's frame by it. */
@@ -96,7 +87,8 @@ export class Recording {
     }
     async step(tab, page, intent, target) {
         const marks = target ? [{ label: intent.operation, rect: target }] : [];
-        const file = `${String(this.steps.length + 1).padStart(2, '0')}.jpg`;
+        const file = stepFileName(this.steps.length + 1, safeSlug(stepWords(intent), this.#scrub));
+        mkdirSync(join(this.#dir, 'steps'), { recursive: true });
         writeFileSync(join(this.#dir, file), Buffer.from(await tab.markedScreenshot(marks, page, { sharp: true }), 'base64'));
         this.steps.push({
             file,
@@ -109,7 +101,7 @@ export class Recording {
     }
     /** The action shot just taken never ran (the page moved first); the retry takes its place. */
     discardLast() {
-        this.steps.pop();
+        this.#remove(this.steps.pop());
     }
     /** The action shot just taken never ran: its target couldn't be reached. Repeats of the same miss fold into one. */
     markUnreachable() {
@@ -118,26 +110,34 @@ export class Recording {
             return;
         if (previous?.unreachable && previous.description === last.description) {
             previous.attempts = (previous.attempts ?? 1) + 1;
-            this.steps.pop();
+            this.#remove(this.steps.pop());
             return;
         }
         last.unreachable = true;
         last.attempts = 1;
     }
+    // A shot named for a step that never ran would sit in the folder with no step to explain it.
+    #remove(step) {
+        if (step)
+            rmSync(join(this.#dir, step.file), { force: true });
+    }
     // A session can run several times (missing value, confirmation); each run ends with its own final shot,
     // and the video is re-encoded to cover every run so far.
-    async finish(tab, summary) {
+    async finish(tab, summary, asked) {
         const page = await tab.observe();
         await this.step(tab, page, { operation: summary.status });
         this.steps.at(-1).description = `Finished: ${summary.status}. ${summary.reason}`;
         this.summaries.push(summary);
+        if (asked)
+            this.asked.push({ goal: this.#scrub(asked.goal), ...(asked.doneWhen && { done_when: this.#scrub(asked.doneWhen) }) });
         await tab.send('Page.stopScreencast').catch(() => undefined);
         this.#stopListening?.();
         this.#stopListening = undefined;
         const video = (await this.#encode()) ?? null;
         const viewport = this.#viewport;
-        writeFileSync(join(this.#dir, 'summary.json'), JSON.stringify({ summaries: this.summaries, video, steps: this.steps, ...(viewport && { viewport }) }, null, 1));
-        writeFileSync(join(this.#dir, 'index.html'), renderSteps(this.steps, this.summaries, video, viewport));
+        const record = { summaries: this.summaries, video, steps: this.steps, ...(viewport && { viewport }), ...(this.asked.length && { asked: this.asked }) };
+        writeFileSync(join(this.#dir, 'summary.json'), JSON.stringify(record, null, 1));
+        writeFileSync(join(this.#dir, 'index.html'), renderRunPage(record));
     }
     // Frames → H.264 through ffmpeg's concat list, each frame held for its duration. Without ffmpeg: no video.
     async #encode() {
@@ -172,61 +172,3 @@ export class Recording {
         }
     }
 }
-export { escapeHtml };
-// What a run's calls cost, summed: requests, input tokens, time, and the estimate unless a call has none.
-const costLine = (summaries) => {
-    const sum = (pick) => summaries.reduce((total, s) => total + pick(s), 0);
-    const cost = summaries.reduce((total, s) => (total === null || s.jev.est_cost_usd == null ? null : total + s.jev.est_cost_usd), 0);
-    return `${plural(sum((s) => s.jev.requests), 'Jev request')} · ${thousands(sum((s) => s.jev.input_tokens))} input tokens · ${seconds(sum((s) => s.elapsed_ms))} · ${cost === null ? 'est. cost unknown' : `est. ${dollars(cost)}`}`;
-};
-// epoch seconds → "2026-11-01 18:39 UTC"
-const recordedAt = (at) => `${new Date(at * 1000).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
-/**
- * A run's own page (`index.html` in its record folder), in the reports' layout: how it ended, then the screencast with
- * its steps on a timeline and a strip kept in sync, then the facts. One self-contained file next to its shots and
- * video; it reads without JS (the script only syncs the player).
- *
- * @example
- * writeFileSync('runs/a/index.html', renderSteps(steps, summaries, 'run.mp4', { width: 1120, height: 780 }));
- */
-export const renderSteps = (steps, summaries, video = null, viewport) => {
-    const last = summaries.at(-1);
-    const ending = last ? `Finished: ${statusWord(last.status)}` : 'jevway run';
-    const actions = summaries.reduce((total, s) => total + s.steps.length, 0);
-    const bar = `<div class="player-bar grid4"><p class="meta c1s3">${plural(steps.length, 'step')}${video ? ' · pick one to play from there' : ''}</p><span class="meta clock c4 end">${video ? clock(0) : ''}</span></div>`;
-    const player = steps.length
-        ? playerMarkup({ dir: '', video, steps, label: 'this run', featured: true, viewport, bar, preload: 'metadata' })
-        : '<div class="screen quiet"><p class="small">No step was recorded.</p></div>';
-    const facts = [
-        ...(summaries.length ? [fact('Calls', `${escapeHtml(summaries.map((s) => statusWord(s.status)).join(' → '))} · ${plural(actions, 'action')}`)] : []),
-        ...(last ? [fact('Final reason', escapeHtml(last.reason)), fact('Final address', `<span class="address">${escapeHtml(last.url)}</span>`), fact('Page title', escapeHtml(last.title))] : []),
-        ...(summaries.length ? [fact('Cost', `<span class="num">${costLine(summaries)}</span>`)] : []),
-        fact('Files', `<a href="summary.json">summary.json</a>${video ? ` · <a href="${escapeHtml(video)}">${escapeHtml(video)}</a>` : ''}`),
-    ];
-    return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
-<title>${escapeHtml(`jevway run: ${last ? statusWord(last.status) : 'recorded'}`)}</title>
-<link rel="preconnect" href="https://api.fontshare.com" crossorigin>
-<link rel="stylesheet" href="${FONT_LINK}">
-<style>${BASE_STYLE}
-.run-page { padding-bottom: 4rem; }
-.run-page .facts { margin-top: 4rem; }
-</style>
-</head><body>
-<main class="wrapper run-page">
-<header class="job-head grid4">
-<p class="meta">jevway run<br>${steps.length ? recordedAt(steps[0].at) : ''}</p>
-<h1 class="job-title c2s2">${escapeHtml(ending)}</h1>
-<p class="meta c4 end">${plural(summaries.length, 'call')} · ${plural(actions, 'action')}</p>
-${last ? `<p class="small story c2s2">${escapeHtml(last.reason)}</p>` : ''}
-</header>
-<div class="run player current">
-${player}
-</div>
-<dl class="facts">${facts.join('\n')}</dl>
-</main>
-<footer><div class="wrapper"><span>Recorded by jevway for people to read; the model never sees these shots.</span><span>${plural(steps.length, 'step')}${video ? ` · ${escapeHtml(video)}` : ' · no video (needs ffmpeg)'}</span></div></footer>
-${PLAYER_SCRIPT}
-</body></html>
-`;
-};

package/dist/recording/run-page.js

@@ -0,0 +1,155 @@
+import { BASE_STYLE, clock, dollars, embeddedJson, escapeHtml as escape, fact, FONT_STYLESHEET, GENERATOR_META, indexLabel, JEVWAY_VERSION, pathOf, playerMarkup, plural, PLAYER_SCRIPT, seconds, sentencesOf, statusLabel, statusTone, statusWord, storyOfRecording, thousands, } from './recording-page.js';
+const total = (summaries, pick) => summaries.reduce((sum, s) => sum + pick(s), 0);
+// Unknown when any call has no estimate (a model without a published rate).
+const estimatedCost = (summaries) => summaries.reduce((sum, s) => (sum === null || s.jev.est_cost_usd == null ? null : sum + s.jev.est_cost_usd), 0);
+// epoch seconds → "2026-11-01 18:39 UTC"
+const utc = (at) => `${new Date(at * 1000).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+const RUN_STYLE = `
+.run-top { padding-block: 2.5rem 0; display: grid; gap: 1.75rem; }
+.run-top .label { padding-top: 0.5rem; }
+.done-when { margin-top: 0.75rem; }
+.outcome-line { font-size: 1.125rem; line-height: 1.625rem; overflow-wrap: anywhere; }
+.status { display: inline-flex; align-items: center; gap: 0.5rem; font-weight: 500; margin-right: 0.5rem; }
+.status::before { content: ""; flex: none; width: 0.625rem; height: 0.625rem; border-radius: 99px; background: var(--muted-foreground); }
+.status.held::before { background: var(--held); } .status.reached::before { background: var(--reached); } .status.missed::before { background: var(--missed); }
+.glance { border-top: 1px solid var(--muted); padding-top: 1.25rem; grid-template-columns: repeat(2, minmax(0, 1fr)); row-gap: 1.25rem; }
+@media (min-width: 64rem) { .glance { grid-template-columns: repeat(4, minmax(0, 1fr)); } }
+.glance dt { margin-bottom: 0.25rem; }
+.glance dd { font-size: 1.125rem; line-height: 1.5rem; font-weight: 500; font-variant-numeric: tabular-nums; overflow-wrap: anywhere; }
+.glance dd .small { display: block; font-weight: 400; }
+.run-top .facts .fact { padding-block: 0.875rem; }
+.block { margin-top: 4rem; }
+.block-head { margin-bottom: 1.5rem; }
+#recording .screen { margin-top: 0; }
+.call + .call { margin-top: 1.5rem; }
+.call-head { padding-top: 0.875rem; }
+.call-asked { margin-top: 0.25rem; }
+.story { border-bottom: 1px solid var(--muted); }
+.entry { display: grid; grid-template-columns: 2.25rem minmax(0, 1fr); gap: 0.125rem 0.75rem; padding: 0.875rem 0.75rem 0.875rem 0.5rem; border-top: 1px solid var(--muted); scroll-margin-top: 4rem; }
+.entry .n { padding-top: 0.2rem; }
+.entry .sentence { font-size: 1rem; line-height: 1.5rem; overflow-wrap: anywhere; }
+.entry .links { grid-column: 2; display: flex; flex-wrap: wrap; gap: 0.125rem 1rem; font-size: 0.75rem; line-height: 1.25rem; color: var(--muted-foreground); }
+.entry .links > * { min-width: 0; }
+.entry .where { max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.entry .links a { text-decoration: underline; text-decoration-color: var(--muted); text-underline-offset: 3px; }
+.entry .links a:hover { color: var(--foreground); text-decoration-color: currentColor; }
+.entry.unshot .sentence { color: var(--muted-foreground); }
+.entry.ended .sentence { font-weight: 500; }
+.entry:target, .entry[aria-current="step"] { box-shadow: inset 2px 0 0 var(--foreground); background: color-mix(in oklch, var(--muted) 35%, transparent); }
+.entry[aria-current="step"] .n { color: var(--foreground); }
+.files dt { text-transform: none; letter-spacing: 0; font-family: var(--font-mono); }
+.files dd a { text-decoration: underline; text-decoration-color: var(--muted); text-underline-offset: 3px; }
+.run-page { padding-bottom: 4rem; }
+`;
+/** One line of a call's story: its number and sentence, then its time in the video, its shot file and its address. */
+const storyEntry = ({ sentence, shot }, steps, video) => {
+    if (shot === undefined)
+        return `<li class="entry unshot"><span class="n meta num" aria-hidden="true">·</span><p class="sentence">${escape(sentence)}</p></li>`;
+    const step = steps[shot];
+    const id = `s${shot + 1}`;
+    const name = step.file.split('/').pop();
+    const links = [
+        ...(video && step.video_at !== undefined ? [`<a class="at num" data-seek="${shot}" href="#${id}" aria-label="Play from step ${shot + 1}, at ${clock(step.video_at)}">${clock(step.video_at)}</a>`] : []),
+        `<a href="${escape(step.file)}">${escape(name)}</a>`,
+        `<span class="where">${escape(pathOf(step.url))}</span>`,
+    ];
+    const ended = step.operation === step.operation.toLowerCase();
+    return `<li class="entry${ended ? ' ended' : ''}" id="${id}" data-shot="${shot}"><span class="n meta num">${indexLabel(shot)}</span><p class="sentence">${escape(sentence)}</p><p class="links">${links.join('')}</p></li>`;
+};
+const callStories = (stories, record) => {
+    const several = stories.length > 1;
+    return stories
+        .map((story, n) => {
+        const asked = record.asked?.[n];
+        const before = record.asked?.[n - 1];
+        const differs = n > 0 && asked && before && (asked.goal !== before.goal || asked.done_when !== before.done_when);
+        const status = story.status ?? record.summaries[n]?.status;
+        const head = several ? `<h3 class="meta">Call ${n + 1}${status ? ` · ${escape(statusWord(status))}` : ''}</h3>` : '';
+        return `<div class="call grid4"><div class="call-head">${head}${differs ? `<p class="small call-asked">Asked: ${escape(asked.goal)}${asked.done_when ? `<br>Done when: ${escape(asked.done_when)}` : ''}</p>` : ''}</div><ol class="story c2s3">${story.entries.map((entry) => storyEntry(entry, record.steps, record.video)).join('')}</ol></div>`;
+    })
+        .join('\n');
+};
+/**
+ * The page for a recorded run folder, from its `summary.json` record. The top says what was asked, how the run ended
+ * and why, when, how long, what it cost, and where it started and ended; then the screencast (or the first shot); then
+ * each call's story, every step linking its shot file and its video time (`#s<n>`, also a deep link); then the
+ * details and the folder's files. The record itself is embedded as `#jevway-summary`.
+ *
+ * @example
+ * writeFileSync('runs/a/index.html', renderRunPage(JSON.parse(readFileSync('runs/a/summary.json', 'utf8'))));
+ */
+export const renderRunPage = (record) => {
+    const { summaries, steps, video, viewport } = record;
+    const last = summaries.at(-1);
+    const goal = record.asked?.[0]?.goal;
+    const doneWhen = record.asked?.[0]?.done_when;
+    // Actions that ran: a step told back to Jev as not done (`not_executed`) is in the story, not in the count.
+    const actions = total(summaries, (s) => s.steps.filter((step) => !step.not_executed).length);
+    const cost = estimatedCost(summaries);
+    const stories = storyOfRecording(steps, summaries);
+    const outcome = last ? statusLabel(last.status) : 'Recorded';
+    const title = `${outcome}${goal ? `: ${goal}` : ''} · jevway run`;
+    const bar = `<div class="player-bar grid4"><p class="meta c1s3">${plural(steps.length, 'step')}${video ? ' · pick one to play from there' : ''}</p><span class="meta clock c4 end">${video ? clock(0) : ''}</span></div>`;
+    const player = steps.length
+        ? playerMarkup({ dir: '', video, steps, label: 'this run', featured: true, viewport, bar, preload: 'metadata', sentences: sentencesOf(stories) })
+        : '<div class="screen quiet"><p class="small">No step was recorded.</p></div>';
+    const glance = [
+        ['Started', steps.length ? utc(steps[0].at) : 'unknown'],
+        ['Took', summaries.length ? seconds(total(summaries, (s) => s.elapsed_ms)) : 'unknown'],
+        ['Cost', `${cost === null ? 'est. cost unknown' : `est. ${dollars(cost)}`}<span class="small">${plural(total(summaries, (s) => s.jev.requests), 'Jev request')}</span>`],
+        ['Steps', `${plural(summaries.length, 'call')} · ${plural(actions, 'action')}`],
+    ];
+    const header = `<header class="wrapper run-top">
+<div class="grid4"><p class="meta label">Asked</p><div class="c2s3"><h1 class="job-title">${goal ? escape(goal) : 'Goal not recorded'}</h1>${doneWhen ? `<p class="small done-when"><span class="kv">Done when</span> ${escape(doneWhen)}</p>` : ''}${goal ? '' : '<p class="small done-when">This run was recorded before jevway kept the goal in its folder.</p>'}</div></div>
+<div class="grid4"><p class="meta label">Outcome</p><p class="c2s3 outcome-line">${last ? `<span class="status ${statusTone(last.status)}">${escape(outcome)}</span> ${escape(last.reason)}` : 'No call finished.'}</p></div>
+<dl class="glance grid4">${glance.map(([label, value]) => `<div><dt class="meta">${label}</dt><dd>${value}</dd></div>`).join('')}</dl>
+<dl class="facts">${[
+        ...(steps.length ? [fact('Start page', `<span class="address">${escape(steps[0].url)}</span>`)] : []),
+        ...(last ? [fact('End page', `<span class="address">${escape(last.url)}</span>${last.title ? ` · ${escape(last.title)}` : ''}`)] : []),
+    ].join('\n')}</dl>
+</header>`;
+    const details = [
+        ...(summaries.length ? [fact('Calls', `${escape(summaries.map((s) => statusWord(s.status)).join(' → '))} · ${plural(actions, 'action')}`)] : []),
+        ...(last ? [fact('Final page', `${escape(last.title)}<br><span class="address">${escape(last.url)}</span>`)] : []),
+        ...(summaries.length
+            ? [fact('Cost', `<span class="num">${plural(total(summaries, (s) => s.jev.requests), 'Jev request')} · ${thousands(total(summaries, (s) => s.jev.input_tokens))} input tokens · ${seconds(total(summaries, (s) => s.elapsed_ms))} · ${cost === null ? 'est. cost unknown' : `est. ${dollars(cost)}`}</span>`)]
+            : []),
+        ...(last?.jev.model ? [fact('Model', escape(last.jev.model))] : []),
+        ...(viewport ? [fact('Viewport', `<span class="num">${viewport.width} × ${viewport.height}</span> CSS pixels`)] : []),
+    ];
+    const files = [
+        fact('<a href="summary.json">summary.json</a>', "Each call's summary and the recorded steps: the same data this page embeds as <code>#jevway-summary</code>"),
+        fact('<a href="manifest.json">manifest.json</a>', 'Every file in this folder, with what it is'),
+        ...(video ? [fact(`<a href="${escape(video)}">${escape(video)}</a>`, 'Screencast of the whole session, idle stretches shortened')] : []),
+        fact('steps/', `${plural(steps.length, 'shot')}: one before each action, its target outlined, and one as each call ended; each step above links its own`),
+    ];
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<title>${escape(title)}</title>
+<meta name="description" content="${escape(`${goal ?? 'A jevway run'}: ${outcome.toLowerCase()}${last ? `. ${last.reason}` : ''}`)}">
+${GENERATOR_META}
+<meta name="color-scheme" content="light dark">
+<link rel="alternate" type="application/json" href="summary.json" title="This run as data">
+${FONT_STYLESHEET}
+<style>${BASE_STYLE}${RUN_STYLE}</style>
+</head><body>
+<nav class="top" aria-label="This page"><div class="wrapper"><span>jevway · run</span><div class="links"><a href="#steps">Steps</a><a href="#details">Details</a><a href="#files">Files</a></div></div></nav>
+${header}
+<main class="wrapper run-page">
+<div class="run player current" data-step-links>
+<section id="recording" class="block" aria-labelledby="recording-title"><h2 class="block-head meta" id="recording-title">Recording</h2>
+${player}
+</section>
+<section id="steps" class="block" aria-labelledby="steps-title"><h2 class="section-title block-head" id="steps-title">Steps</h2>
+${callStories(stories, record)}
+</section>
+</div>
+<section id="details" class="block" aria-labelledby="details-title"><h2 class="section-title block-head" id="details-title">Details</h2><dl class="facts">${details.join('\n')}</dl></section>
+<section id="files" class="block" aria-labelledby="files-title"><h2 class="section-title block-head" id="files-title">Files</h2><dl class="facts files">${files.join('\n')}</dl></section>
+</main>
+<footer><div class="wrapper"><span>Recorded by jevway ${escape(JEVWAY_VERSION)} for people to read; the model never sees these shots.</span><span>${plural(steps.length, 'step')}${video ? ` · ${escape(video)}` : ' · no video (recording one needs ffmpeg)'}</span></div></footer>
+${embeddedJson('jevway-summary', record)}
+${PLAYER_SCRIPT}
+</body></html>
+`;
+};

package/dist/session/session-service.js

@@ -0,0 +1,193 @@
+import { randomUUID } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { scrubberFor } from '../jev/secrets.js';
+import { ensureOutRoot, journeyFolderName, outRoot, runFolderName } from '../output/layout.js';
+import { lookAt } from '../task/look.js';
+import { storyLine } from '../task/present.js';
+/** A session id the service does not hold: it ended, expired, or never existed. `code` is for structured CLI errors. */
+export class UnknownSession extends Error {
+    code = 'unknown_session';
+}
+// 3600000 → '1 h', 1800000 → '30 min'.
+const idleWords = (ms) => (ms % 3_600_000 === 0 ? `${ms / 3_600_000} h` : `${Math.round(ms / 60_000)} min`);
+/**
+ * The sessions behind every adapter (the MCP server, the CLI daemon): task sessions and journeys by opaque UUID, each
+ * with its folder under the output root, calls that wait for a session's still-running call, and errors that say what
+ * to do next. Transport-free: adapters translate parameters in and present results out.
+ *
+ * @example
+ * const sessions = createSessionService(createRunner('auto'));
+ * const first = await sessions.task({ goal: 'Book a stay', url: 'https://stays.example' }, { onEvent: console.error });
+ * presentSummary(first); // { session, status: 'needs_input', next: 'Add the missing values …', story, files, … }
+ * await sessions.task({ goal: 'Book a stay', session: first.session, values: { email: 'ada@example.com' } });
+ * await sessions.end(first.session);
+ */
+export const createSessionService = (runner, options = {}) => {
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    const root = resolve(cwd, options.outDir ?? outRoot(env, cwd));
+    const now = options.now ?? (() => new Date());
+    const newId = options.newId ?? randomUUID;
+    const sessions = new Map();
+    const journeys = new Map();
+    const lifetime = `when the server restarts${options.idleMs ? ` or after ${idleWords(options.idleMs)} idle` : ''}`;
+    const findTask = (id) => {
+        const entry = sessions.get(id);
+        if (!entry)
+            throw new UnknownSession(`Unknown session "${id}". Sessions end ${lifetime}; start a new one with \`url\` (or \`tab\`).`);
+        entry.lastUsedAt = now();
+        return entry;
+    };
+    const findJourney = (id) => {
+        const entry = journeys.get(id);
+        if (!entry)
+            throw new UnknownSession(`Unknown journey "${id}". Journeys end when finished or ${lifetime}; start a new one with its \`url\`.`);
+        entry.lastUsedAt = now();
+        return entry;
+    };
+    const startTask = async ({ session: _session, record, recordDir, ...request }) => {
+        const id = newId();
+        const at = now();
+        const values = request.values ?? {};
+        const secretKeys = request.secretKeys ?? [];
+        const scrub = scrubberFor(values, secretKeys);
+        const runDir = recordDir ? resolve(cwd, recordDir) : join(ensureOutRoot(root), 'runs', runFolderName({ at, goal: request.goal, id, scrub }));
+        const task = await runner.start({ ...request, output: { dir: runDir, record: Boolean(record || recordDir) } });
+        const entry = { task, ownsTab: Boolean(request.url), busy: false, goal: scrub(request.goal), values, secretKeys, runDir, startedAt: at, lastUsedAt: at };
+        sessions.set(id, entry);
+        return { id, entry };
+    };
+    const continueTask = async (id, request) => {
+        const entry = findTask(id);
+        await entry.running;
+        // Only what a later call may change: start-only fields (url, tab, coordinate clicks, recording) stay as started.
+        entry.task.update({
+            goal: request.goal,
+            values: request.values,
+            secretKeys: request.secretKeys,
+            files: request.files,
+            doneWhen: request.doneWhen,
+            checks: request.checks,
+            maxSteps: request.maxSteps,
+            maxSeconds: request.maxSeconds,
+            allowedHosts: request.allowedHosts,
+            blockedHosts: request.blockedHosts,
+            confirmIrreversible: request.confirmIrreversible,
+            confirmTarget: request.confirmTarget,
+        });
+        entry.values = { ...entry.values, ...request.values };
+        entry.secretKeys = [...new Set([...entry.secretKeys, ...(request.secretKeys ?? [])])];
+        entry.goal = scrubberFor(entry.values, entry.secretKeys)(request.goal);
+        return { id, entry };
+    };
+    const journeysRoot = () => env.JEVWAY_JOURNEYS_DIR ? resolve(cwd, env.JEVWAY_JOURNEYS_DIR) : join(ensureOutRoot(root), 'journeys');
+    const journeyReply = async (id, journey, report) => ({
+        journey: id,
+        report: report,
+        preview: await journey.preview(),
+    });
+    return {
+        /** The output root this service writes under. */
+        outDir: root,
+        /**
+         * Runs one call: a new session (with `url` or `tab`) or the next call of `session`, which first waits for that
+         * session's still-running call. `signal` cancels this call (the run ends `blocked` at its next check).
+         */
+        async task(request, { signal, onEvent } = {}) {
+            const { id, entry } = request.session ? await continueTask(request.session, request) : await startTask(request);
+            // A listener is the adapter's (progress, NDJSON): it never decides how the run goes.
+            const tell = (event) => {
+                try {
+                    onEvent?.(event);
+                }
+                catch {
+                    // ignored
+                }
+            };
+            tell({ type: 'started', session: id });
+            entry.busy = true;
+            const running = entry.task.run({ signal, onStep: (step, n, url) => tell({ type: 'step', session: id, n, story: storyLine(step), url }) });
+            entry.running = running.catch(() => undefined);
+            try {
+                const summary = await running;
+                entry.status = summary.status;
+                entry.url = summary.url;
+                tell({ type: 'finished', session: id, status: summary.status });
+                const call = entry.task.lastCall;
+                return { session: id, summary, ...(call && { files: call.files }), ...(call?.screenshot && { screenshot: call.screenshot }) };
+            }
+            finally {
+                entry.busy = false;
+                entry.lastUsedAt = now();
+            }
+        },
+        /** Reads a page with no model call and no input: a session's tab (its secret values masked), an open tab by URL part, or a URL opened and closed again. */
+        async look({ session, tab, url }) {
+            if ([session, tab, url].filter(Boolean).length !== 1)
+                throw new Error('Pass exactly one of session, tab or url.');
+            if (session)
+                return lookAt(await findTask(session).task.look());
+            return lookAt(await runner.look({ url, tab }));
+        },
+        /** Forgets a session and closes the tabs it opened (its first tab only when it started from `url`), unless `keepTab`. */
+        async end(session, { keepTab = false } = {}) {
+            const entry = findTask(session);
+            sessions.delete(session);
+            if (!keepTab)
+                await entry.task.closeTabs({ keepFirst: !entry.ownsTab });
+            return { session, run_dir: entry.runDir };
+        },
+        /** Every open task session and journey, oldest first, with what it is doing and where its files are. */
+        listSessions() {
+            const tasks = [...sessions].map(([session, entry]) => ({
+                session,
+                kind: 'task',
+                goal: entry.goal,
+                ...(entry.status && { status: entry.status }),
+                ...(entry.url && { url: entry.url }),
+                running: entry.busy,
+                started_at: entry.startedAt.toISOString(),
+                last_used_at: entry.lastUsedAt.toISOString(),
+                run_dir: entry.runDir,
+            }));
+            const maps = [...journeys].map(([session, entry]) => ({
+                session,
+                kind: 'journey',
+                url: entry.url,
+                started_at: entry.startedAt.toISOString(),
+                last_used_at: entry.lastUsedAt.toISOString(),
+                run_dir: entry.outDir,
+            }));
+            return [...tasks, ...maps].sort((a, b) => a.started_at.localeCompare(b.started_at));
+        },
+        /** Opens `url` on an emulated phone and maps its first screen, into `<root>/journeys/<stamp>_<host>_<id4>/` (or `outDir`). */
+        async journeyStart({ url, device, intent, values, stayWithin, outDir }) {
+            const id = newId();
+            const at = now();
+            const dir = outDir ? resolve(cwd, outDir) : join(journeysRoot(), journeyFolderName({ at, host: new URL(url).host, id }));
+            const journey = await runner.startJourney({ startUrl: url, device, intent, values, stayWithin, outDir: dir });
+            journeys.set(id, { journey, url, outDir: dir, startedAt: at, lastUsedAt: at });
+            return journeyReply(id, journey, journey.report());
+        },
+        async journeyStep(id, input) {
+            const { journey } = findJourney(id);
+            return journeyReply(id, journey, await journey.step(input));
+        },
+        async journeyAutopilot(id, input) {
+            const { journey } = findJourney(id);
+            return journeyReply(id, journey, await journey.autopilot(input));
+        },
+        journeyAnnotate(id, screen, notes, relabel) {
+            findJourney(id).journey.annotate(screen, notes, relabel);
+        },
+        /** Writes the final map, closes the journey's tab unless `keepTab`, and forgets the journey. */
+        async journeyFinish(id, { keepTab = false } = {}) {
+            const { journey, outDir } = findJourney(id);
+            const summary = await journey.finish({ closeTab: !keepTab });
+            journeys.delete(id);
+            return { ...summary, manifest: join(outDir, 'manifest.json') };
+        },
+        /** Closes the browser connection (a launched browser closes with it). */
+        close: () => runner.close(),
+    };
+};

package/dist/setup/atomic-write.js

@@ -0,0 +1,13 @@
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Writes `text` to a temporary file beside `path` and renames it into place, so an interrupted setup leaves the file
+ * either as it was or complete. `mode` applies to the result even where the file existed before.
+ */
+export const writeFileAtomic = (path, text, mode = 0o644) => {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.jevway-${process.pid}.tmp`;
+    writeFileSync(temporary, text, { mode });
+    chmodSync(temporary, mode);
+    renameSync(temporary, path);
+};