sdd-engine 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +178 -2
  3. package/dist/engine/cli.js +95 -0
  4. package/dist/engine/simulate.js +214 -0
  5. package/dist/judge/conversation.js +45 -0
  6. package/dist/judge/judge.js +122 -0
  7. package/dist/judge/outcome.js +42 -0
  8. package/dist/judge/regrade.js +74 -0
  9. package/dist/pipeline/agent.js +78 -0
  10. package/dist/pipeline/agentstage.js +88 -0
  11. package/dist/pipeline/approve.js +68 -0
  12. package/dist/pipeline/cli.js +261 -0
  13. package/dist/pipeline/derive.js +287 -0
  14. package/dist/pipeline/designloop.js +385 -0
  15. package/dist/pipeline/facts.js +108 -0
  16. package/dist/pipeline/mock.js +253 -0
  17. package/dist/pipeline/project.js +79 -0
  18. package/dist/pipeline/render.js +95 -0
  19. package/dist/pipeline/spec.js +272 -0
  20. package/dist/pipeline/try.js +162 -0
  21. package/dist/runner/batch-lib.js +157 -0
  22. package/dist/runner/batch.js +56 -0
  23. package/dist/runner/cli.js +61 -0
  24. package/dist/runner/llm/claude-code.js +123 -0
  25. package/dist/runner/llm/index.js +12 -0
  26. package/dist/runner/llm/types.js +17 -0
  27. package/dist/runner/reader/answer.js +76 -0
  28. package/dist/runner/reader/extract.js +106 -0
  29. package/dist/runner/reader/run.js +111 -0
  30. package/dist/runner/reader/skim.js +115 -0
  31. package/dist/runner/rng.js +22 -0
  32. package/dist/runner/sandbox/cli.js +60 -0
  33. package/dist/runner/sandbox/sandbox.js +144 -0
  34. package/dist/runner/sandbox/server.js +64 -0
  35. package/dist/runner/spec.js +84 -0
  36. package/dist/runner/talker/decide.js +110 -0
  37. package/dist/runner/talker/run.js +159 -0
  38. package/dist/runner/talker/world.js +36 -0
  39. package/dist/runner/trace.js +130 -0
  40. package/dist/runner/visitor/decide.js +159 -0
  41. package/dist/runner/visitor/observe.js +102 -0
  42. package/dist/runner/visitor/run.js +296 -0
  43. package/dist/scorer/compare.js +119 -0
  44. package/dist/scorer/score.js +201 -0
  45. package/dist/scorer/spot-check-compare.js +41 -0
  46. package/dist/scorer/spot-check-view.js +45 -0
  47. package/dist/scorer/stats.js +45 -0
  48. package/dist/scorer/summary.js +62 -0
  49. package/package.json +49 -4
@@ -0,0 +1,61 @@
1
+ // Runner command line.
2
+ //
3
+ // node runner/cli.ts reader --persona backend-tdd [--viewport mobile] [--seed 1]
4
+ // [--spec specs/sdd-site.spec.yaml]
5
+ //
6
+ // Runs one persona through reader mode and writes one trace.
7
+ import path from 'node:path';
8
+ import { parseArgs } from 'node:util';
9
+ import { createLLM } from "./llm/index.js";
10
+ import { runReader } from "./reader/run.js";
11
+ import { startSandbox } from "./sandbox/sandbox.js";
12
+ import { loadPersona, loadSpec } from "./spec.js";
13
+ import { writeTrace } from "./trace.js";
14
+ const repoRoot = path.resolve(import.meta.dirname, '..');
15
+ const { positionals, values } = parseArgs({
16
+ allowPositionals: true,
17
+ options: {
18
+ spec: { type: 'string', default: 'specs/sdd-site.spec.yaml' },
19
+ persona: { type: 'string' },
20
+ viewport: { type: 'string', default: 'mobile' },
21
+ seed: { type: 'string', default: '1' },
22
+ },
23
+ });
24
+ if (positionals[0] !== 'reader' || !values.persona) {
25
+ console.error('Usage: node runner/cli.ts reader --persona <id> [--viewport mobile|desktop] [--seed n] [--spec file]');
26
+ process.exit(2);
27
+ }
28
+ const spec = await loadSpec(path.resolve(repoRoot, values.spec));
29
+ const persona = await loadPersona(path.resolve(repoRoot, spec.personas.working, `${values.persona}.yaml`));
30
+ if (!spec.page)
31
+ throw new Error('This spec names no page file. Use the batch command with --target.');
32
+ const sandbox = await startSandbox({
33
+ rootDir: path.dirname(path.resolve(repoRoot, spec.page)),
34
+ indexFile: path.resolve(repoRoot, spec.page),
35
+ });
36
+ let trace;
37
+ try {
38
+ trace = await runReader({
39
+ repoRoot,
40
+ spec,
41
+ persona,
42
+ viewport: values.viewport,
43
+ seed: Number(values.seed),
44
+ sandbox,
45
+ llm: createLLM(),
46
+ });
47
+ }
48
+ finally {
49
+ await sandbox.finish();
50
+ }
51
+ const file = await writeTrace(path.join(repoRoot, 'traces'), trace);
52
+ const seen = trace.steps.flatMap((s) => s.seen);
53
+ const pageWords = trace.page.words;
54
+ const seenWords = seen.reduce((n, f) => n + f.text.split(/\s+/).length, 0);
55
+ console.log(`${trace.persona.id} on ${trace.viewport.name}, seed ${trace.seed}`);
56
+ console.log(` skim: ${trace.steps.length} screens, ${trace.simulatedSeconds}s simulated, ended by ${trace.outcome}, deepest section "${trace.deepestSection}"`);
57
+ console.log(` took in ${seen.length} fragments (${seenWords} of ${pageWords} words), recalled ${trace.recalled.length}`);
58
+ for (const a of trace.answers)
59
+ console.log(` ${a.id}: ${a.answer}`);
60
+ console.log(` cost: $${trace.cost.usd.toFixed(4)} (${trace.llmCalls[0].response.model}), not graded yet`);
61
+ console.log(` trace: ${path.relative(repoRoot, file)}`);
@@ -0,0 +1,123 @@
1
+ // LLM provider that shells out to the Claude Code CLI in headless mode
2
+ // (`claude -p`), using whatever login the CLI already has.
3
+ //
4
+ // Each call is a clean, single-shot completion: no tools, no MCP servers,
5
+ // no settings or CLAUDE.md, no saved session, and an empty working directory.
6
+ // So the model sees the system prompt and the prompt, nothing from this repo.
7
+ import { spawn } from 'node:child_process';
8
+ import { mkdtemp } from 'node:fs/promises';
9
+ import { tmpdir } from 'node:os';
10
+ import path from 'node:path';
11
+ import { modelFor } from "./types.js";
12
+ /** With images, the prompt goes in as one stream-json user message and the result comes back as the last stream-json line. */
13
+ function imageInput(request) {
14
+ const content = [
15
+ ...request.images.map((image) => {
16
+ if (!image.base64)
17
+ throw new Error('Image has no data');
18
+ return { type: 'image', source: { type: 'base64', media_type: image.mediaType, data: image.base64 } };
19
+ }),
20
+ { type: 'text', text: request.prompt },
21
+ ];
22
+ return JSON.stringify({ type: 'user', message: { role: 'user', content } }) + '\n';
23
+ }
24
+ function parseResult(stdout, streamed) {
25
+ if (!streamed)
26
+ return JSON.parse(stdout);
27
+ for (const line of stdout.split('\n').reverse()) {
28
+ if (!line.trim())
29
+ continue;
30
+ try {
31
+ const event = JSON.parse(line);
32
+ if (event.type === 'result')
33
+ return event;
34
+ }
35
+ catch {
36
+ // not a JSON line
37
+ }
38
+ }
39
+ throw new Error('No result event in stream output');
40
+ }
41
+ function run(args, stdin, cwd) {
42
+ return new Promise((resolve, reject) => {
43
+ const child = spawn('claude', args, { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
44
+ let out = '';
45
+ let err = '';
46
+ child.stdout.on('data', (d) => (out += d));
47
+ child.stderr.on('data', (d) => (err += d));
48
+ child.on('error', reject);
49
+ child.on('close', (code) => {
50
+ if (code === 0)
51
+ resolve(out);
52
+ else
53
+ reject(new Error(`claude exited ${code}: ${err || out}`.slice(0, 2000)));
54
+ });
55
+ child.stdin.end(stdin);
56
+ });
57
+ }
58
+ export function createClaudeCodeLLM() {
59
+ let cwd;
60
+ return {
61
+ provider: 'claude-code',
62
+ async complete(request) {
63
+ cwd ??= mkdtemp(path.join(tmpdir(), 'sdd-llm-'));
64
+ const model = modelFor(request.role);
65
+ const args = [
66
+ '-p',
67
+ '--model', model,
68
+ '--system-prompt', request.system,
69
+ '--tools', '',
70
+ '--strict-mcp-config',
71
+ '--setting-sources', '',
72
+ '--disable-slash-commands',
73
+ '--no-session-persistence',
74
+ ];
75
+ const streamed = Boolean(request.images?.length);
76
+ if (streamed)
77
+ args.push('--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose');
78
+ else
79
+ args.push('--output-format', 'json');
80
+ if (request.schema)
81
+ args.push('--json-schema', JSON.stringify(request.schema));
82
+ const started = Date.now();
83
+ const dir = await cwd;
84
+ // Retry transient failures (rate limits, dropped connections) with backoff.
85
+ let raw;
86
+ let lastError;
87
+ for (let attempt = 0; attempt < 4 && !raw; attempt++) {
88
+ if (attempt > 0)
89
+ await new Promise((r) => setTimeout(r, 5000 * 3 ** (attempt - 1)));
90
+ try {
91
+ const stdout = await run(args, streamed ? imageInput(request) : request.prompt, dir);
92
+ const parsed = parseResult(stdout, streamed);
93
+ if (parsed.is_error)
94
+ throw new Error(`claude returned an error: ${stdout.slice(0, 2000)}`);
95
+ if (request.schema && parsed.structured_output === undefined) {
96
+ throw new Error(`claude returned no structured output: ${stdout.slice(0, 2000)}`);
97
+ }
98
+ raw = parsed;
99
+ }
100
+ catch (err) {
101
+ lastError = err;
102
+ }
103
+ }
104
+ if (!raw)
105
+ throw lastError;
106
+ return {
107
+ provider: 'claude-code',
108
+ model,
109
+ text: raw.result ?? '',
110
+ structured: raw.structured_output,
111
+ usage: {
112
+ inputTokens: raw.usage?.input_tokens ?? 0,
113
+ outputTokens: raw.usage?.output_tokens ?? 0,
114
+ cacheReadTokens: raw.usage?.cache_read_input_tokens ?? 0,
115
+ cacheWriteTokens: raw.usage?.cache_creation_input_tokens ?? 0,
116
+ },
117
+ costUsd: raw.total_cost_usd ?? 0,
118
+ durationMs: raw.duration_ms ?? Date.now() - started,
119
+ raw,
120
+ };
121
+ },
122
+ };
123
+ }
@@ -0,0 +1,12 @@
1
+ import { createClaudeCodeLLM } from "./claude-code.js";
2
+ export * from "./types.js";
3
+ /** SDD_LLM_PROVIDER picks the provider. Only claude-code exists so far. */
4
+ export function createLLM() {
5
+ const provider = process.env.SDD_LLM_PROVIDER ?? 'claude-code';
6
+ switch (provider) {
7
+ case 'claude-code':
8
+ return createClaudeCodeLLM();
9
+ default:
10
+ throw new Error(`Unknown SDD_LLM_PROVIDER "${provider}"`);
11
+ }
12
+ }
@@ -0,0 +1,17 @@
1
+ // Provider-agnostic LLM interface. The runner, judge, and reviser talk to
2
+ // this and nothing else. The model for each role comes from the environment.
3
+ /** A copy of a request that is safe to store: image bytes removed. */
4
+ export function storable(request) {
5
+ if (!request.images)
6
+ return request;
7
+ return { ...request, images: request.images.map(({ base64: _dropped, ...rest }) => rest) };
8
+ }
9
+ const DEFAULT_MODELS = {
10
+ persona: 'claude-haiku-5-5',
11
+ judge: 'claude-sonnet-5-5',
12
+ reviser: 'claude-opus-5-5',
13
+ };
14
+ /** SDD_MODEL_PERSONA, SDD_MODEL_JUDGE, SDD_MODEL_REVISER override the defaults. */
15
+ export function modelFor(role) {
16
+ return process.env[`SDD_MODEL_${role.toUpperCase()}`] ?? DEFAULT_MODELS[role];
17
+ }
@@ -0,0 +1,76 @@
1
+ // The answering call. The page has been taken away.
2
+ //
3
+ // This module is the enforcement point for "answers from seen text only".
4
+ // Its inputs are the persona, the fragments the persona recalled, the
5
+ // questions, and optionally screenshots of the screens the persona scrolled
6
+ // past with the body text blurred. It takes no page, no URL, and no browser,
7
+ // and it never sees a rubric. Keep it that way.
8
+ import { storable } from "../llm/types.js";
9
+ const SYSTEM = `You are simulating one person's memory of a web page, for a study of how well the page explains itself.
10
+
11
+ You get a profile of the person and the exact fragments of text they took in during a short skim. The page is gone. They cannot look at it again.
12
+
13
+ Answer each question the way this person would, in the first person, in one to three plain sentences.
14
+
15
+ Rules:
16
+ - Use only the fragments listed, plus general knowledge this person already had before the visit.
17
+ - Do not use anything else you know or can guess about the page or its subject.
18
+ - Fragments can be partial and out of context. Do not fill the gaps with confident guesses.
19
+ - If the person could not answer, say so plainly, for example "I'm not sure". A partial answer is fine.
20
+ - Do not try to be helpful, complete, or flattering. Be faithful to what this person would actually remember.`;
21
+ const SCREENS_NOTE = `
22
+
23
+ You also get screenshots of each screen the person scrolled past, in order. They show what the page looked like: layout, imagery, color, style, and what stood out. Body text in them is blurred on purpose, because the person did not read it. Use the screenshots for visual impressions only. Do not try to read blurred text, and do not treat anything in a screenshot as text the person read unless it is also in the fragments. Answer as the person who saw the page. Never mention screenshots, fragments, or blur in an answer.`;
24
+ export function buildAnswerRequest(persona, recalled, questions, screens = []) {
25
+ const fragments = recalled.length
26
+ ? recalled.map((f, i) => `${i + 1}. ${f.kind === 'heading' ? '[heading] ' : ''}${f.text}`).join('\n')
27
+ : '(nothing was taken in)';
28
+ const prompt = `THE PERSON
29
+ Role: ${persona.profile.role}
30
+ Experience: ${persona.profile.experience}
31
+ Already uses: ${persona.profile.already_uses.join('; ')}
32
+ Came from: ${persona.arrival.source}, after seeing only this title: "${persona.arrival.saw}"
33
+ Was hoping to find: ${persona.needs.join('; ')}
34
+ Doubts going in: ${persona.objections.join('; ')}
35
+
36
+ FRAGMENTS THEY TOOK IN, in order
37
+ ${fragments}
38
+
39
+ QUESTIONS
40
+ ${questions.map((q) => `${q.id}: ${q.ask}`).join('\n')}
41
+
42
+ Answer every question by its id.`;
43
+ return {
44
+ role: 'persona',
45
+ system: screens.length ? SYSTEM + SCREENS_NOTE : SYSTEM,
46
+ prompt,
47
+ ...(screens.length ? { images: screens } : {}),
48
+ schema: {
49
+ type: 'object',
50
+ properties: {
51
+ answers: {
52
+ type: 'array',
53
+ items: {
54
+ type: 'object',
55
+ properties: { id: { type: 'string' }, answer: { type: 'string' } },
56
+ required: ['id', 'answer'],
57
+ },
58
+ },
59
+ },
60
+ required: ['answers'],
61
+ },
62
+ };
63
+ }
64
+ export async function answerFromMemory(llm, persona, recalled, questions, screens = []) {
65
+ const request = buildAnswerRequest(persona, recalled, questions, screens);
66
+ const response = await llm.complete(request);
67
+ const reply = response.structured;
68
+ const answers = questions.map((q) => {
69
+ const found = reply?.answers?.find((a) => a.id === q.id);
70
+ if (!found || typeof found.answer !== 'string') {
71
+ throw new Error(`Persona reply has no answer for question "${q.id}"`);
72
+ }
73
+ return { id: q.id, ask: q.ask, answer: found.answer };
74
+ });
75
+ return { answers, call: { request: storable(request), response } };
76
+ }
@@ -0,0 +1,106 @@
1
+ // Reads the rendered page into text blocks with positions. Runs in the real
2
+ // browser at the persona's viewport, so the layout is what a visitor gets.
3
+ export async function extractLayout(page) {
4
+ return page.evaluate(() => {
5
+ const isBlock = (el) => {
6
+ if (el instanceof SVGElement)
7
+ return el.tagName.toLowerCase() === 'text';
8
+ const display = getComputedStyle(el).display;
9
+ return !display.startsWith('inline') && display !== 'contents';
10
+ };
11
+ // Group every visible text node under its nearest block-level ancestor.
12
+ const groups = new Map();
13
+ const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
14
+ for (let node = walker.nextNode(); node; node = walker.nextNode()) {
15
+ const text = (node.textContent ?? '').replace(/\s+/g, ' ').trim();
16
+ if (!text)
17
+ continue;
18
+ let el = node.parentElement;
19
+ if (!el || el.closest('script, style, noscript, template'))
20
+ continue;
21
+ while (el && !isBlock(el))
22
+ el = el.parentElement;
23
+ if (!el)
24
+ continue;
25
+ const list = groups.get(el) ?? [];
26
+ list.push(text);
27
+ groups.set(el, list);
28
+ }
29
+ const elements = [...groups.keys()];
30
+ const bodyFontSize = parseFloat(getComputedStyle(document.body).fontSize);
31
+ const blocks = [];
32
+ for (const el of elements) {
33
+ const style = getComputedStyle(el);
34
+ const rect = el.getBoundingClientRect();
35
+ if (style.visibility === 'hidden' || rect.width === 0 || rect.height === 0)
36
+ continue;
37
+ // innerText gets spacing and text-transform right, but would swallow
38
+ // nested blocks. Use it only when this block has none.
39
+ const hasNested = elements.some((other) => other !== el && el.contains(other));
40
+ const text = !hasNested && el instanceof HTMLElement
41
+ ? el.innerText.replace(/\s+/g, ' ').trim()
42
+ : groups.get(el).join(' ');
43
+ if (!text)
44
+ continue;
45
+ // A heading is what a skimmer's eye lands on: a heading tag, or text set
46
+ // clearly larger than body text (a hero line, a styled <dt>).
47
+ const isHeading = Boolean(el.closest('h1, h2, h3, h4, h5, h6, [role="heading"]')) ||
48
+ (el instanceof HTMLElement && parseFloat(style.fontSize) >= bodyFontSize * 1.25);
49
+ // Mark the element so screenshots can blur body text (see captureScreens).
50
+ el.setAttribute('data-sdd-kind', isHeading ? 'heading' : 'body');
51
+ const region = el.closest('section[id], header, footer, nav, aside');
52
+ blocks.push({
53
+ kind: isHeading ? 'heading' : 'body',
54
+ section: region ? region.id || region.tagName.toLowerCase() : 'page',
55
+ text,
56
+ top: rect.top + window.scrollY,
57
+ bottom: rect.bottom + window.scrollY,
58
+ left: rect.left + window.scrollX,
59
+ });
60
+ }
61
+ return {
62
+ blocks: blocks.map((b, id) => ({ id, ...b })),
63
+ pageHeight: document.documentElement.scrollHeight,
64
+ viewportHeight: window.innerHeight,
65
+ };
66
+ });
67
+ }
68
+ /**
69
+ * Screenshots of the page at each scroll position, for the persona's visual
70
+ * impression: layout, imagery, color, what stands out.
71
+ *
72
+ * Body text is blurred first. A model can read body text in a screenshot
73
+ * down to about 150 pixels wide, so shrinking alone does not preserve the
74
+ * skim: the reader would take in every word on screen. Headings stay sharp,
75
+ * since a skimmer takes those in anyway. What the reader read of the body
76
+ * comes from the skim, as text. Call after extractLayout, which marks the
77
+ * elements.
78
+ */
79
+ export async function captureScreens(page, scrollYs, maxWidth) {
80
+ await page.addStyleTag({ content: '[data-sdd-kind="body"] { filter: blur(6px) !important; }' });
81
+ const shots = [];
82
+ for (const scrollY of scrollYs) {
83
+ await page.evaluate((y) => window.scrollTo(0, y), scrollY);
84
+ const shot = await page.screenshot({ type: 'jpeg', quality: 80, scale: 'css' });
85
+ shots.push({ scrollY, b64: shot.toString('base64') });
86
+ }
87
+ // Shrink in the browser. A data URL makes no network request.
88
+ return page.evaluate(async ({ shots, maxWidth }) => {
89
+ const out = [];
90
+ for (const { scrollY, b64 } of shots) {
91
+ const img = new Image();
92
+ img.src = 'data:image/jpeg;base64,' + b64;
93
+ await img.decode();
94
+ const width = Math.min(maxWidth, img.width);
95
+ const height = Math.round((img.height * width) / img.width);
96
+ const canvas = document.createElement('canvas');
97
+ canvas.width = width;
98
+ canvas.height = height;
99
+ const g = canvas.getContext('2d');
100
+ g.imageSmoothingQuality = 'high';
101
+ g.drawImage(img, 0, 0, width, height);
102
+ out.push({ scrollY, mediaType: 'image/jpeg', base64: canvas.toDataURL('image/jpeg', 0.75).split(',')[1], width, height });
103
+ }
104
+ return out;
105
+ }, { shots, maxWidth });
106
+ }
@@ -0,0 +1,111 @@
1
+ // Reader mode: one persona, one session, one trace.
2
+ //
3
+ // 1. Load the page in the guarded browser at the persona's viewport.
4
+ // 2. Skim it for the time budget (skim.ts). Optionally screenshot each
5
+ // screen the reader reached, with body text blurred.
6
+ // 3. Take the page away. Apply recall decay.
7
+ // 4. Ask the spec's questions, giving the model only what was recalled.
8
+ import { createHash } from 'node:crypto';
9
+ import { mkdir, writeFile } from 'node:fs/promises';
10
+ import path from 'node:path';
11
+ import { devices } from 'playwright';
12
+ import { createRng, deriveSeed } from "../rng.js";
13
+ import { validateTrace } from "../trace.js";
14
+ import { answerFromMemory } from "./answer.js";
15
+ import { captureScreens, extractLayout } from "./extract.js";
16
+ import { countWords, recall, skim, UNCALIBRATED_DIALS } from "./skim.js";
17
+ export const VIEWPORTS = {
18
+ mobile: devices['iPhone 13'],
19
+ desktop: { viewport: { width: 1280, height: 800 } },
20
+ };
21
+ export async function runReader(options) {
22
+ const { spec, persona, sandbox, llm, seed } = options;
23
+ const viewportOptions = VIEWPORTS[options.viewport];
24
+ if (!viewportOptions)
25
+ throw new Error(`Unknown viewport "${options.viewport}"`);
26
+ const dials = { ...(options.dials ?? UNCALIBRATED_DIALS), timeBudgetSeconds: spec.reader.time_budget_seconds };
27
+ const derivedSeed = deriveSeed(spec.experiment, persona.id, options.viewport, seed);
28
+ const rng = createRng(derivedSeed);
29
+ const startedAt = new Date().toISOString();
30
+ const pagePath = options.pagePath ?? spec.page ?? `${sandbox.origin}${options.entryPath ?? '/'}`;
31
+ // 1. The page, as rendered for this viewport. Everything that needs the
32
+ // browser happens here: layout, the skim (which is pure), and screenshots
33
+ // of the screens the reader got to.
34
+ const context = await sandbox.newContext(viewportOptions);
35
+ let layout, skimmed, pageSource;
36
+ let screens = [];
37
+ try {
38
+ const page = await context.newPage();
39
+ const response = await page.goto(`${sandbox.origin}${options.entryPath ?? '/'}`, { waitUntil: 'load' });
40
+ if (response?.status() !== 200)
41
+ throw new Error(`Page under test returned HTTP ${response?.status()}`);
42
+ pageSource = await response.body();
43
+ await page.evaluate(() => document.fonts.ready);
44
+ layout = await extractLayout(page);
45
+ // 2. Skim. Seeded, and independent of the screenshots.
46
+ skimmed = skim(layout.blocks, layout.viewportHeight, layout.pageHeight, persona.dials, dials, rng);
47
+ if (spec.reader.screenshots) {
48
+ const width = viewportOptions.viewport.width;
49
+ screens = await captureScreens(page, skimmed.steps.map((s) => s.scrollY), width > 600 ? 640 : 300);
50
+ }
51
+ }
52
+ finally {
53
+ await context.close();
54
+ }
55
+ sandbox.assertClean(); // hard rule 1: an outside request fails the run
56
+ // 3. Forget a little. The browser is closed.
57
+ const recalled = recall(skimmed.seen, skimmed.simulatedSeconds, dials, rng);
58
+ // Screenshots are stored once per page, viewport, and scroll position, and
59
+ // referred to from the trace.
60
+ const pageHash = createHash('sha256').update(pageSource).digest('hex');
61
+ const images = [];
62
+ for (const screen of screens) {
63
+ const ref = path.join('shots', spec.experiment, pageHash.slice(0, 12), options.viewport, `y${screen.scrollY}.jpg`);
64
+ const bytes = Buffer.from(screen.base64, 'base64');
65
+ await mkdir(path.dirname(path.resolve(options.repoRoot, ref)), { recursive: true });
66
+ await writeFile(path.resolve(options.repoRoot, ref), bytes, { flag: 'wx' }).catch((err) => {
67
+ if (err.code !== 'EEXIST')
68
+ throw err;
69
+ });
70
+ images.push({ mediaType: screen.mediaType, base64: screen.base64, ref, sha256: createHash('sha256').update(bytes).digest('hex') });
71
+ }
72
+ // 4. Questions, from memory. The rubric stays behind.
73
+ const questions = spec.questions.map(({ id, ask }) => ({ id, ask }));
74
+ const { answers, call } = await answerFromMemory(llm, persona, recalled, questions, images);
75
+ const size = viewportOptions.viewport;
76
+ const trace = {
77
+ schema: 'sdd-trace/1',
78
+ runId: `${startedAt.replace(/[:.]/g, '-')}_${persona.id}_${options.viewport}_s${seed}`,
79
+ ...(options.batch ? { batch: options.batch } : {}),
80
+ experiment: spec.experiment,
81
+ mode: 'reader',
82
+ startedAt,
83
+ page: {
84
+ path: pagePath,
85
+ sha256: pageHash,
86
+ words: countWords(layout.blocks.map((b) => b.text).join(' ')),
87
+ },
88
+ persona,
89
+ personaSet: options.personaSet ?? 'working',
90
+ viewport: { name: options.viewport, width: size.width, height: size.height },
91
+ seed,
92
+ derivedSeed,
93
+ dials: { ...dials, calibrated: options.calibrated ?? false },
94
+ steps: skimmed.steps,
95
+ recalled,
96
+ outcome: skimmed.outcome,
97
+ simulatedSeconds: skimmed.simulatedSeconds,
98
+ deepestSection: skimmed.deepestSection,
99
+ answers,
100
+ grades: null,
101
+ llmCalls: [call],
102
+ cost: {
103
+ usd: call.response.costUsd,
104
+ inputTokens: call.response.usage.inputTokens + call.response.usage.cacheReadTokens + call.response.usage.cacheWriteTokens,
105
+ outputTokens: call.response.usage.outputTokens,
106
+ },
107
+ sandbox: sandbox.record(),
108
+ };
109
+ validateTrace(trace, spec.questions.map((q) => q.id));
110
+ return trace;
111
+ }
@@ -0,0 +1,115 @@
1
+ // Skim and time mechanics. Pure functions: blocks in, steps out. No browser,
2
+ // no LLM. This is the "human messiness" half of the hybrid design.
3
+ //
4
+ // Skimming: headings are always taken in. Each sentence of body text is
5
+ // taken in with a probability set by the skim rate.
6
+ // Time: reading costs words / reading speed. Glancing past a skipped
7
+ // sentence and scrolling cost a little too. When the budget is
8
+ // spent the session ends.
9
+ // Recall: each fragment taken in survives to answer time with a
10
+ // probability that decays with how long ago it was read.
11
+ /** Starting values, not yet calibrated against real readers. */
12
+ export const UNCALIBRATED_DIALS = {
13
+ timeBudgetSeconds: 60,
14
+ skimScale: 1,
15
+ recallDecayPerSecond: 0.005,
16
+ glanceSeconds: 0.2,
17
+ scrollSeconds: 0.6,
18
+ scrollFraction: 0.8,
19
+ };
20
+ export function splitSentences(text) {
21
+ return text
22
+ .split(/(?<=[.!?])\s+(?=[A-Z0-9"'(])/)
23
+ .map((s) => s.trim())
24
+ .filter(Boolean);
25
+ }
26
+ export function countWords(text) {
27
+ return text.split(/\s+/).filter(Boolean).length;
28
+ }
29
+ export function skim(blocks, viewportHeight, pageHeight, persona, dials, rng) {
30
+ const ordered = [...blocks].sort((a, b) => a.top - b.top || a.left - b.left || a.id - b.id);
31
+ const pRead = 1 - Math.min(1, Math.max(0, persona.skim_rate * dials.skimScale));
32
+ const budget = dials.timeBudgetSeconds;
33
+ const maxScroll = Math.max(0, pageHeight - viewportHeight);
34
+ const steps = [];
35
+ const allSeen = [];
36
+ let t = 0;
37
+ let scrollY = 0;
38
+ let cursor = 0;
39
+ let deepestSection = ordered[0]?.section ?? '';
40
+ let outcome;
41
+ while (!outcome) {
42
+ const start = t;
43
+ const viewBottom = scrollY + viewportHeight;
44
+ const visible = [];
45
+ const seen = [];
46
+ let timeUp = false;
47
+ // No scrolling back: each block is offered once, in reading order, when
48
+ // its middle comes on screen.
49
+ while (cursor < ordered.length && (ordered[cursor].top + ordered[cursor].bottom) / 2 < viewBottom) {
50
+ const block = ordered[cursor++];
51
+ visible.push(block);
52
+ if (timeUp)
53
+ continue; // on screen, but the clock already ran out
54
+ deepestSection = block.section;
55
+ const fragments = block.kind === 'heading' ? [block.text] : splitSentences(block.text);
56
+ for (const text of fragments) {
57
+ const reads = block.kind === 'heading' || rng() < pRead;
58
+ const cost = reads ? (countWords(text) / persona.reading_wpm) * 60 : dials.glanceSeconds;
59
+ if (t + cost > budget) {
60
+ t = budget;
61
+ timeUp = true;
62
+ break;
63
+ }
64
+ t += cost;
65
+ if (reads)
66
+ seen.push({ blockId: block.id, kind: block.kind, section: block.section, text, t: round(t) });
67
+ }
68
+ }
69
+ let action = 'scroll';
70
+ let reason = 'time remains and there is more page below';
71
+ if (timeUp) {
72
+ action = 'stop';
73
+ reason = 'time budget spent';
74
+ outcome = 'time_up';
75
+ }
76
+ else if (scrollY >= maxScroll && cursor >= ordered.length) {
77
+ action = 'stop';
78
+ reason = 'reached the end of the page';
79
+ outcome = 'end_of_page';
80
+ }
81
+ else if (t + dials.scrollSeconds > budget) {
82
+ t = budget;
83
+ action = 'stop';
84
+ reason = 'time budget spent';
85
+ outcome = 'time_up';
86
+ }
87
+ else {
88
+ t += dials.scrollSeconds;
89
+ }
90
+ steps.push({
91
+ index: steps.length,
92
+ scrollY: Math.round(scrollY),
93
+ visible: visible.map(({ id, kind, section, text }) => ({ id, kind, section, text })),
94
+ seen,
95
+ action,
96
+ reason,
97
+ simulatedSecondsStart: round(start),
98
+ simulatedSecondsEnd: round(t),
99
+ });
100
+ allSeen.push(...seen);
101
+ if (!outcome) {
102
+ // At the bottom with blocks still unread (their middle never crossed
103
+ // the fold): jump far enough that the loop always makes progress.
104
+ scrollY = scrollY >= maxScroll ? scrollY + viewportHeight : Math.min(maxScroll, scrollY + viewportHeight * dials.scrollFraction);
105
+ }
106
+ }
107
+ return { steps, seen: allSeen, outcome, simulatedSeconds: round(t), deepestSection };
108
+ }
109
+ /** What survives to answer time. Always a subset of what was seen. */
110
+ export function recall(seen, endSeconds, dials, rng) {
111
+ return seen.filter((f) => rng() < Math.exp(-dials.recallDecayPerSecond * (endSeconds - f.t)));
112
+ }
113
+ function round(n) {
114
+ return Math.round(n * 1000) / 1000;
115
+ }
@@ -0,0 +1,22 @@
1
+ // Seeded randomness. Every random choice in a run comes from here, so the
2
+ // same seed gives the same skim.
3
+ /** FNV-1a hash of the parts, as an unsigned 32 bit seed. */
4
+ export function deriveSeed(...parts) {
5
+ let h = 0x811c9dc5;
6
+ for (const ch of parts.join('\u0000')) {
7
+ h ^= ch.codePointAt(0);
8
+ h = Math.imul(h, 0x01000193);
9
+ }
10
+ return h >>> 0;
11
+ }
12
+ /** mulberry32: small, fast, good enough for sampling. Returns [0, 1). */
13
+ export function createRng(seed) {
14
+ let a = seed >>> 0;
15
+ return () => {
16
+ a = (a + 0x6d2b79f5) >>> 0;
17
+ let t = a;
18
+ t = Math.imul(t ^ (t >>> 15), t | 1);
19
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
20
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
21
+ };
22
+ }