Files
gstack/lib/first-use-message.ts
T
Garry Tanandcapy-ai[bot] dd4266dc4b Check each app build with an agent from another model family before its owner is asked to try it (GST-3025) (#4465)
Adds `gstack-first-use`: before an app build reaches its owner as "ready
to try", an agent from another model family plays that exact build, does
the plan's first five day-one actions with a screenshot or video of
each, and checks every link. Only then does it print the "try this
build" message.

Why: a recent app build passed every review and its owner still found
the first screen broken, because nothing tried the build the way the
owner would.

Nothing to do now; the first real use is that app's next build.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Review-Finding: p1/red-team#2 reader=red-team
Review-Finding: p1/red-team#4 reader=red-team
2026-11-17 23:19:24 +00:00

116 lines
8.3 KiB
TypeScript

/**
* first-use-message — the play spec and the two texts the first-use check prints
* (docs/first-use-check.md). The play spec holds the ten parts every ask to play
* or try a build carries (the factory's R47): the links, the device and setup,
* what it is, how to start, the controls, how long, what we want to learn, how
* to report back, known quirks and the reply word. renderPlayMessage() is the
* only "try this build" text, printed after decide() passes; renderBrief() is
* what the cold checker from the other model family is given, and nothing more.
*/
import { buildLabel, type Decision, type FirstUseError, type Manifest } from './first-use';
export interface PlayLink { url: string; label: string; login_gated?: boolean }
export interface PlaySpec {
links: PlayLink[]; device: string; setup: string; account: string; what: string; start: string;
controls: string; minutes: number; learn: string; report: string; quirks: string; reply_word: string;
}
/** R47's ten parts in order, with the play-spec fields each one reads. */
export const PLAY_PARTS: Array<{ part: string; fields: Array<keyof PlaySpec> }> = [
{ part: 'The links, each checked live minutes before sending', fields: ['links'] },
{ part: 'Device and setup', fields: ['device', 'setup', 'account'] },
{ part: 'What it is, in a sentence', fields: ['what'] },
{ part: 'How to start', fields: ['start'] },
{ part: 'Controls', fields: ['controls'] },
{ part: 'How long to play', fields: ['minutes'] },
{ part: 'What we want to learn', fields: ['learn'] },
{ part: 'How to report back', fields: ['report'] },
{ part: 'Known quirks', fields: ['quirks'] },
{ part: 'Reply word', fields: ['reply_word'] },
];
const TEXT_FIELDS = ['device', 'setup', 'account', 'what', 'start', 'controls', 'learn', 'report', 'quirks', 'reply_word'] as const;
/** A complete play spec, or the R47 parts it is missing. "none" is a fine answer for quirks; an empty field is not. */
export function checkPlaySpec(raw: unknown): { spec: PlaySpec } | { error: FirstUseError } {
const o = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>;
const bad = new Set<keyof PlaySpec>();
for (const f of TEXT_FIELDS) if (typeof o[f] !== 'string' || !(o[f] as string).trim()) bad.add(f);
if (typeof o.reply_word === 'string' && !/^[A-Za-z][A-Za-z0-9-]{0,23}$/.test(o.reply_word.trim())) bad.add('reply_word');
if (!Number.isInteger(o.minutes) || (o.minutes as number) < 1 || (o.minutes as number) > 240) bad.add('minutes');
const links = Array.isArray(o.links) ? o.links as Array<Record<string, unknown>> : [];
const linkOk = (l: Record<string, unknown>) => typeof l?.label === 'string' && !!l.label.trim() && typeof l.url === 'string' && /^https?:\/\/[^\s]+$/.test(l.url)
&& (l.login_gated === undefined || typeof l.login_gated === 'boolean');
if (!links.length || !links.every(linkOk)) bad.add('links');
if (bad.size) {
const parts = PLAY_PARTS.filter(p => p.fields.some(f => bad.has(f))).map(p => `${p.part} (${p.fields.filter(f => bad.has(f)).join(', ')})`);
return { error: { code: 'FIRST_USE_PLAY_SPEC_INCOMPLETE', detail: `missing or invalid: ${parts.join('; ')}` } };
}
const spec: PlaySpec = {
links: links.map(l => ({ url: l.url as string, label: (l.label as string).trim(), ...(l.login_gated ? { login_gated: true } : {}) })),
minutes: o.minutes as number,
...Object.fromEntries(TEXT_FIELDS.map(f => [f, (o[f] as string).trim()])) as Omit<PlaySpec, 'links' | 'minutes'>,
};
return { spec };
}
const hhmm = (iso: string) => iso.slice(11, 16);
const platformName = { ios: 'iOS', android: 'Android', web: 'web' } as const;
/** The "try this build" message: R47's ten parts, then what the cold check covered. Call only after decide() passed. */
export function renderPlayMessage(d: Decision, now: Date = new Date()): string {
const m = d.manifest!, p = m.play;
const checked = d.links.map(l => Date.parse(l.checked_at));
const oldest = Math.min(...checked);
const ago = Math.max(0, Math.round((now.getTime() - oldest) / 60_000));
return [
`**Try ${m.app}: ${buildLabel(m.build)}**`, '',
`1. **Links** (each checked live at ${new Date(oldest).toISOString().slice(11, 16)} UTC, ${ago} min before this message):`,
...p.links.map(l => ` - [${l.label}](${l.url})${l.login_gated ? ' (asks you to sign in)' : ''}`),
`2. **Device and setup:** ${p.device}. ${p.setup} Account: ${p.account}.`,
`3. **What it is:** ${p.what}`,
`4. **How to start:** ${p.start}`,
`5. **Controls:** ${p.controls}`,
`6. **How long:** about ${p.minutes} minutes.`,
`7. **What we want to learn:** ${p.learn}`,
`8. **How to report back:** ${p.report} Give it a score from 1 to 10 and one line on what stood out.`,
`9. **Known quirks:** ${p.quirks}`,
`10. **Reply word:** ${p.reply_word}, then your score and your line, for example "${p.reply_word} 7, the first screen was slow".`,
'',
`Checked before it reached you: an agent from another model family (${m.checker.model}) played this exact build cold on a ${platformName[m.build.platform]} cloud device and did the first ${m.actions.length} things you'll do on day one. All ${d.passed} worked, with a screenshot or video of each:`,
...m.actions.map(a => `- ${a.action}`),
'',
].join('\n');
}
/** One POSIX shell word: single quotes, with each embedded single quote closed, escaped and reopened. */
export const shellQuote = (v: string) => `'${v.replace(/'/g, `'\\''`)}'`;
/** What the cold checker is given: the build, the device and account, the play message parts and the frozen actions, with the commands that record each. */
export function renderBrief(m: Manifest, dir: string): string {
const p = m.play, b = m.build;
const install = b.platform === 'web'
? 'open the first link in a browser on that device'
: `attach a ${platformName[b.platform]} phone (\`tools.capy.phone\` with action "attach", platform "${b.platform}" and the model closest to the device above), install this exact build on it (action "install"; ${b.testflight ? `TestFlight build ${b.testflight}` : `version ${b.deploy}`}), and drive its screen with \`tools.capy.computer.on({ machine_id })\``;
const by = `--by ${shellQuote(m.checker.model)}`, run = `--run ${shellQuote(dir)}`;
return [
`# Cold first-use check: ${m.app}, ${buildLabel(b)}`, '',
`You are playing this build for the first time, as its owner will. You run on ${m.checker.model}; the team that built it runs on ${m.builder.family} models, and you have not seen its plan, code, notes or messages. Do not read them: you get only what the owner gets, below.`, '',
'## Device and account', '',
`Use the same kind of device and account as the owner: ${p.device}. ${p.setup} Account: ${p.account} (play only on this kind of account; \`record\` takes it exactly). On Capy, ${install}.`, '',
'## What the owner is told', '',
`- What it is: ${p.what}`, `- Links: ${p.links.map(l => `${l.label} ${l.url}`).join('; ')}`, `- How to start: ${p.start}`, `- Controls: ${p.controls}`,
`- How long: about ${p.minutes} minutes`, `- Known quirks: ${p.quirks}`, '',
`## The ${m.actions.length} things the owner will do on day one (frozen ${m.created_at.slice(0, 10)})`, '',
...m.actions.map(a => `${a.n}. ${a.action} (${a.frequency || 'how often unstated'}). Way in: ${a.route || 'not stated'}. It works when: ${a.check}`), '',
'## What to do', '',
'1. Do each action as the owner would, from a cold start, with no help beyond the text above.',
'2. Capture a screenshot or a short video that shows the result, then record it. A pass means the owner would see it work on the first try; anything else is a fail, and the note says what happened:',
'', '```bash', `gstack-first-use record ${run} --action N --verdict pass --evidence FILE --device 'DEVICE YOU USED' --account ${shellQuote(p.account)} ${by}`,
`gstack-first-use record ${run} --action N --verdict fail --evidence FILE --device 'DEVICE YOU USED' --account ${shellQuote(p.account)} ${by} --note 'WHAT HAPPENED'`, '```', '',
'3. Predict the owner\'s score from 1 to 10 for this build, with one line on why:', '',
'```bash', `gstack-first-use predict ${run} --score N --why 'ONE LINE' ${by}`, '```', '',
'4. Report back: one line per action (pass or fail and why), your predicted score, and the one thing most likely to disappoint the owner.',
'',
].join('\n');
}