@asrunjs/asrun 0.7.0 → 0.9.0

package/dist/scripts/upgrade.js

@@ -0,0 +1,256 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { spawnSync } from 'node:child_process';
+import { spawnTarget } from '../lib/command.js';
+import { compareVersions, isVersion, migrationState, pendingMigrations, readMarker, } from '../lib/migrations.js';
+import { FRAMEWORK_ROOT, MARKER, ROOT } from '../lib/paths.js';
+import { releaseInfo, releaseManifest } from '../lib/registry.js';
+import { excludeReleaseAge } from '../lib/runtime-deps.js';
+import { frameworkPath, PACKAGE } from './init.js';
+/**
+ * `pnpm asrun upgrade`: one command that installs the newest framework, refreshes the workspace files and applies the
+ * migrations the new release brings.
+ *
+ * The order matters. The migration manifest of the *target* release is read out of its tarball first, so breaking
+ * changes are known before anything is written; the install comes next, and `init --update`, `migrate` and `doctor`
+ * then run through the *newly installed* package, never through the code that is being replaced.
+ */
+const USAGE = `Usage: pnpm asrun upgrade [--version <version|dist-tag>] [--root <dir>] [--dry-run] [--yes]
+
+  --version <v>   the release to install (default: latest); a dist-tag or a concrete version
+  --root <dir>    the workspace to upgrade (default: the current workspace)
+  --dry-run       print the target release and the migrations it brings, and change nothing
+  --yes           install without asking (a breaking change, or a release that cannot be checked)
+
+What it does, in this order:
+  1. resolve the target release and read its migration manifest from the registry;
+  2. show the breaking changes and the migrations between the workspace's baseline and that release;
+  3. install @asrunjs/asrun at that version (a fresh release is exempted from pnpm's release age first);
+  4. run "init --update", "migrate" and "doctor" through the installed package.
+
+A release older than the migration manifest cannot be checked in advance: the command says so and asks before it
+installs. "pnpm asrun migrate" runs only the migration part, for a workspace that was upgraded by hand.`;
+/** How a workspace reaches its install: the nearest `node_modules/@asrunjs/asrun` at or above the workspace root. */
+function installedDir(root) {
+    for (let dir = path.resolve(root);; dir = path.dirname(dir)) {
+        const candidate = path.join(dir, 'node_modules', PACKAGE);
+        if (fs.existsSync(path.join(candidate, 'package.json')))
+            return candidate;
+        if (path.dirname(dir) === dir)
+            return null;
+    }
+}
+/** The version of the package installed in that workspace, or null when it is not there. */
+function installedVersion(dir) {
+    if (dir === null)
+        return null;
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        return typeof manifest.version === 'string' ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A person types the word; without a terminal there is no confirmation, and the command refuses. */
+async function confirm(question) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return null;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(question)).trim().toLowerCase() === 'upgrade';
+    }
+    finally {
+        rl.close();
+    }
+}
+function printMigration(entry) {
+    const tags = [entry.breaking === true ? 'breaking' : '', entry.auto === true ? 'runs automatically' : 'needs a person']
+        .filter(Boolean)
+        .join(', ');
+    console.log(`  ${entry.breaking === true ? '!' : ' '} ${entry.version}  ${entry.summary}`);
+    console.log(`        ${entry.id}${tags === '' ? '' : `  (${tags})`}`);
+    if (entry.appliesTo !== undefined)
+        console.log(`        affects: ${entry.appliesTo}`);
+    if (entry.details !== undefined)
+        console.log(`        detail:  ${entry.details}`);
+    for (const line of entry.manual ?? [])
+        console.log(`        - ${line}`);
+}
+export async function main(args) {
+    if (args.includes('--help')) {
+        console.log(USAGE);
+        return 0;
+    }
+    const value = (name) => {
+        const index = args.indexOf(name);
+        return index >= 0 && args[index + 1] !== undefined && !args[index + 1].startsWith('-') ? args[index + 1] : undefined;
+    };
+    const root = path.resolve(value('--root') ?? ROOT);
+    const dryRun = args.includes('--dry-run');
+    const yes = args.includes('--yes');
+    const spec = value('--version') ?? 'latest';
+    if (path.resolve(root) === path.resolve(FRAMEWORK_ROOT)) {
+        console.error('This folder is the framework itself, not a workspace. Run "pnpm asrun upgrade" in the project that uses ' +
+            'asrun, or pass --root <dir>.');
+        return 1;
+    }
+    if (!fs.existsSync(path.join(root, MARKER))) {
+        console.error(`No ${MARKER} in ${root}: this is not an initialized asrun workspace. Run "pnpm asrun init" first.`);
+        return 1;
+    }
+    console.log('[1/4] Checking the release');
+    const directory = installedDir(root);
+    const current = installedVersion(directory);
+    if (directory === null || current === null) {
+        // The framework's own checkout (examples/demo) has no installed package and must be updated with git; a project
+        // that never installed the framework has to add the dependency.
+        const checkout = !path.resolve(root, frameworkPath(root)).split(path.sep).includes('node_modules');
+        if (checkout) {
+            console.error(`${root} uses the framework's own checkout (${path.resolve(root, frameworkPath(root))}), not an installed ` +
+                'package: there is nothing to install. Update that checkout with git.');
+        }
+        else {
+            console.error(`${PACKAGE} is not installed in ${root}. Run "pnpm add -D ${PACKAGE}@${spec}" and then "pnpm asrun init".`);
+        }
+        return 1;
+    }
+    const lookup = releaseInfo(PACKAGE, spec);
+    if ('error' in lookup) {
+        console.error(`Could not read ${PACKAGE}@${spec} from the registry: ${lookup.error}`);
+        console.error(`\nUpgrade by hand instead:\n  pnpm add -D ${PACKAGE}@${spec}\n  pnpm asrun init --update\n  pnpm asrun migrate\n` +
+            '  pnpm asrun doctor');
+        return 1;
+    }
+    const target = lookup.info.version;
+    if (!isVersion(target) || !isVersion(current)) {
+        console.error(`The registry reported "${target}" and the workspace has "${current}"; expected versions.`);
+        return 1;
+    }
+    const order = compareVersions(target, current);
+    if (order === 0) {
+        console.log(`${PACKAGE} ${current} is already installed in ${root}.`);
+        console.log('To refresh the workspace files or apply migrations that are still pending, run "pnpm asrun init --update" ' +
+            'and "pnpm asrun migrate".');
+        return 0;
+    }
+    if (order < 0) {
+        console.error(`${PACKAGE}@${spec} is ${target}, which is older than the installed ${current}: upgrade never downgrades. ` +
+            `Run "pnpm add -D ${PACKAGE}@${target}" yourself if that is what you want.`);
+        return 1;
+    }
+    // The registry serves the package as a tarball; the manifest in it is what makes the pre-install check possible.
+    const state = migrationState(readMarker(root), current);
+    let warning = null;
+    let pending = [];
+    try {
+        const manifest = await releaseManifest(lookup.info.tarball);
+        if (manifest === null) {
+            warning = `${PACKAGE}@${target} ships no migration manifest (it predates it), so nothing could be checked in advance.`;
+        }
+        else {
+            pending = pendingMigrations(manifest, state.since, target);
+        }
+    }
+    catch (error) {
+        warning = `the migration manifest of ${PACKAGE}@${target} could not be read (${error instanceof Error ? error.message : String(error)}), so nothing could be checked in advance.`;
+    }
+    console.log(`Workspace: ${root}`);
+    console.log(`asrun:     ${current} -> ${target}`);
+    if (warning === null && pending.length === 0) {
+        console.log(`Migrations: none between ${state.since} and ${target}.`);
+    }
+    else if (pending.length > 0) {
+        console.log(`\nMigrations between ${state.since} and ${target}:`);
+        for (const entry of pending)
+            printMigration(entry);
+    }
+    if (warning !== null)
+        console.log(`\n  ! Cannot check the workspace up front: ${warning}`);
+    const breaking = pending.filter((entry) => entry.breaking === true);
+    const needsConfirmation = breaking.length > 0 || warning !== null;
+    if (dryRun) {
+        console.log(`\nWould install ${PACKAGE}@${target}, then run "init --update", "migrate" and "doctor" ` +
+            `(${pending.filter((entry) => entry.auto === true).length} automatic migration(s)).`);
+        console.log('Nothing was installed (--dry-run).');
+        return 0;
+    }
+    if (needsConfirmation) {
+        const question = breaking.length > 0
+            ? `\nType "upgrade" to install ${PACKAGE}@${target} despite ${breaking.length} breaking change(s): `
+            : `\nType "upgrade" to install ${PACKAGE}@${target} without the pre-install check: `;
+        const answer = await confirm(question);
+        if (answer === null) {
+            console.error('Refusing to install: there is no terminal to confirm in. A person adds --yes to do it.');
+            return 1;
+        }
+        if (!answer) {
+            console.error('Cancelled. Nothing was installed.');
+            return 1;
+        }
+    }
+    console.log(`\n[2/4] Installing ${PACKAGE}@${target}`);
+    const age = excludeReleaseAge(root, PACKAGE);
+    if (age === 'added' || age === 'created') {
+        console.log(`  pnpm-workspace.yaml: ${PACKAGE} exempted from pnpm's release age`);
+    }
+    else if (age === 'inline') {
+        console.log(`  ! pnpm-workspace.yaml has an inline "minimumReleaseAgeExclude": add ${PACKAGE} to it, or pnpm may install the ` +
+            'previous release instead of the one just published.');
+    }
+    const pnpm = spawnTarget('pnpm', ['add', '-D', `${PACKAGE}@${target}`]);
+    if (pnpm === null) {
+        console.error('pnpm was not found on PATH: install it, then run "pnpm asrun upgrade" again.');
+        return 1;
+    }
+    const install = spawnSync(pnpm.file, pnpm.args, {
+        cwd: root,
+        stdio: 'inherit',
+        ...(pnpm.throughShell && { windowsVerbatimArguments: true }),
+    });
+    if (install.status !== 0) {
+        const error = install.error;
+        const reason = error !== undefined
+            ? error.code === 'ENOENT'
+                ? 'pnpm was not found on PATH'
+                : error.message
+            : install.signal !== null
+                ? `pnpm was stopped by ${install.signal}`
+                : `pnpm add exited with code ${install.status}`;
+        console.error(`\n  ! ${PACKAGE}@${target} was not installed: ${reason}`);
+        console.error(`    Nothing after this step ran. Fix the cause and run "pnpm asrun upgrade" again.`);
+        return 1;
+    }
+    // Everything from here on runs the package that was just installed: its templates, its migrations, its checks. The
+    // process that started this command is still the old code, and must not write the marker with the old version.
+    const installedAfter = installedDir(root);
+    const after = installedVersion(installedAfter);
+    if (after !== null && after !== target) {
+        console.log(`\n  ! pnpm installed ${PACKAGE}@${after}, not @${target} (pnpm's release age can hold a fresh release back). ` +
+            'The workspace is brought up to the version that is there; run "pnpm asrun upgrade" again later.');
+    }
+    const bin = installedAfter === null ? '' : path.join(installedAfter, 'bin', 'asrun.mjs');
+    if (bin === '' || !fs.existsSync(bin)) {
+        console.error(`\n  ! The install finished, but the installed asrun command is missing (${bin || 'not found'}). ` +
+            'Run "pnpm install", then "pnpm asrun init --update".');
+        return 1;
+    }
+    const env = { ...process.env, ASRUN_ROOT: root };
+    const run = (commandArgs) => spawnSync(process.execPath, [bin, ...commandArgs], { cwd: process.cwd(), stdio: 'inherit', env });
+    console.log(`\n[3/4] Refreshing the workspace files and applying migrations`);
+    const init = run(['init', '--root', root, '--update']);
+    if (init.status !== 0) {
+        console.error(`\n  ! "init --update" failed. Fix the cause and run "pnpm asrun init --update", then "pnpm asrun migrate".`);
+        return 1;
+    }
+    const migrate = run(['migrate', '--root', root, '--yes']);
+    if (migrate.status !== 0) {
+        console.error(`\n  ! "migrate" failed. Fix the cause and run "pnpm asrun migrate" again.`);
+        return 1;
+    }
+    console.log(`\n[4/4] Checking the workspace`);
+    const doctor = run(['doctor']);
+    console.log(`\nUpgraded ${PACKAGE} ${current} -> ${after ?? target} in ${root}.`);
+    return doctor.status ?? 0;
+}

package/dist/ui/server/actions.js

@@ -209,15 +209,20 @@ export function buildJobSpec(request) {
         if (request.attended && request.command !== 'explore-case') {
             throw new ActionError('Only explore-case can be attended.');
         }
-        if ((request.profiles || request.hints !== undefined || request.report) && request.command !== 'heal-spec') {
-            throw new ActionError('Only heal-spec takes profiles, hints and a report.');
+        if ((request.hints !== undefined || request.report) && request.command !== 'heal-spec') {
+            throw new ActionError('Only heal-spec takes hints and a report.');
+        }
+        // The spec is generated for every profile the case names (and runs for every profile), so a selection could only
+        // narrow it wrongly.
+        if (request.profiles && request.command === 'gen-spec') {
+            throw new ActionError('gen-spec takes no profiles: it uses every profile the case holds information for.');
         }
         const profilesInEnv = listProfiles(request.env, knownProfiles).map((profile) => profile.id);
         if (request.profiles?.some((id) => !profilesInEnv.includes(id))) {
             throw new ActionError(`Unknown profile for "${request.env}".`);
         }
         if (request.profiles?.length === 0)
-            throw new ActionError('Choose at least one profile to heal.');
+            throw new ActionError('Choose at least one profile.');
         if (request.report !== undefined && !(REPORT_ID.test(request.report) && fs.existsSync(path.join(REPORTS_DIR, request.report, 'summary.json')))) {
             throw new ActionError(`Unknown report "${request.report}".`);
         }
@@ -234,7 +239,7 @@ export function buildJobSpec(request) {
             thinking: request.thinking,
             force: request.force,
             attended: request.attended,
-            // Naming every profile is the same as leaving it out: the agent then takes all that are logged in.
+            // Naming every profile of the environment is the same as leaving it out: the agent then takes all that are logged in.
             profiles: request.profiles && request.profiles.length < profilesInEnv.length ? request.profiles : undefined,
             hints: hintsPath,
             report: request.report,

package/dist/ui/server/app.js

@@ -14,6 +14,7 @@ import { resolveInside, sendFile } from './files.js';
 import { JobConflictError, jobs } from './jobs.js';
 import { listAiModels } from './ai-models.js';
 import { fileEvents } from './watch-files.js';
+import { refreshUpdate, updateEvents, updateInfo } from './update.js';
 const REPORTS_DIR = path.join(ROOT, 'reports');
 // Built by `prepack` and shipped with the package; the framework repository builds it with `pnpm ui`.
 const WEB_DIST = path.join(FRAMEWORK_ROOT, 'ui', 'dist');
@@ -228,6 +229,17 @@ export function createApp({ port }) {
         const image = resolveInside(base, file.slice('.explore/'.length));
         return image ? sendFile(c, image) : c.notFound();
     });
+    // The release check of this server run. `refresh=1` asks the registry again and answers with the result (a person
+    // testing the notice, or a page that wants a fresh answer); otherwise the page gets the current state, and the first
+    // page load starts the check if it has not finished yet.
+    api.get('/update', async (c) => {
+        if (c.req.query('refresh') === '1')
+            return c.json(await refreshUpdate(true));
+        const info = updateInfo();
+        if (info.checkedAt === null)
+            void refreshUpdate(true);
+        return c.json(info);
+    });
     api.get('/reports', (c) => {
         if (!fs.existsSync(REPORTS_DIR))
             return c.json([]);
@@ -288,12 +300,18 @@ export function createApp({ port }) {
             if (open)
                 void stream.writeSSE({ event: 'files', data: JSON.stringify(change) }).catch(() => { });
         };
+        const updateListener = (info) => {
+            if (open)
+                void stream.writeSSE({ event: 'update', data: JSON.stringify(info) }).catch(() => { });
+        };
         jobs.events.on('job', listener);
         fileEvents.on('files', filesListener);
+        updateEvents.on('update', updateListener);
         stream.onAbort(() => {
             open = false;
             jobs.events.off('job', listener);
             fileEvents.off('files', filesListener);
+            updateEvents.off('update', updateListener);
         });
         while (open) {
             await stream.writeSSE({ event: 'ping', data: '' });

package/dist/ui/server/index.js

@@ -3,6 +3,7 @@ import { createApp } from './app.js';
 import { verifyProfiles } from './profiles.js';
 import { jobs } from './jobs.js';
 import { startFileWatcher } from './watch-files.js';
+import { startUpdateWatcher } from './update.js';
 const port = Number(process.env.ASRUN_UI_PORT ?? 4173);
 const app = createApp({ port });
 const server = serve({ fetch: app.fetch, port, hostname: '127.0.0.1' }, () => {
@@ -15,6 +16,8 @@ const server = serve({ fetch: app.fetch, port, hostname: '127.0.0.1' }, () => {
         console.log(`asrun UI: http://127.0.0.1:${port}`);
     }
     startFileWatcher();
+    // Once now (the notice lands on this terminal), then at every UTC midnight; the top bar picks the answer up.
+    startUpdateWatcher();
     void verifyProfiles();
 });
 server.on('error', (error) => {

package/dist/ui/server/update.d.ts

@@ -0,0 +1,18 @@
+import { EventEmitter } from 'node:events';
+import type { UpdateInfo } from '../shared/types.js';
+/**
+ * The release check of the web UI: once when the server starts, then once a day at 00:00 UTC. The answer is cached in
+ * `.tmp/` (see lib/update-check.ts), so several tabs and the command line share one registry read. Pages learn about a
+ * change through the `update` event of `/api/events`.
+ */
+export declare const updateEvents: EventEmitter<[never]>;
+/** What the UI should show now; before the first answer every field that needs one is null. */
+export declare function updateInfo(): UpdateInfo;
+/**
+ * Asks the registry again and tells the open pages. `force` goes past a fresh cache, which is what the startup and the
+ * daily checks do; the answer is written back to `.tmp/`, so the command line shares it. Overlapping calls share one
+ * read: the daily timer and the first page load can arrive together.
+ */
+export declare function refreshUpdate(force?: boolean): Promise<UpdateInfo>;
+/** Today's check, then one at every UTC midnight while the server runs. */
+export declare function startUpdateWatcher(): void;

package/dist/ui/server/update.js

@@ -0,0 +1,87 @@
+import { EventEmitter } from 'node:events';
+import { checkForUpdate, formatNotice, upgradeCommand, useColor } from '../../lib/update-check.js';
+/**
+ * The release check of the web UI: once when the server starts, then once a day at 00:00 UTC. The answer is cached in
+ * `.tmp/` (see lib/update-check.ts), so several tabs and the command line share one registry read. Pages learn about a
+ * change through the `update` event of `/api/events`.
+ */
+export const updateEvents = new EventEmitter();
+// One listener per open page; the default warning at ten tabs is noise.
+updateEvents.setMaxListeners(0);
+let status = null;
+let inFlight = null;
+/** The notice already printed, so a daily re-check of the same release does not repeat it. */
+let printedNotice = null;
+/** What the UI should show now; before the first answer every field that needs one is null. */
+export function updateInfo() {
+    if (status === null) {
+        return {
+            current: null,
+            latest: null,
+            available: false,
+            checkedAt: null,
+            kind: null,
+            command: null,
+            disabled: false,
+            mocked: false,
+            error: null,
+        };
+    }
+    return {
+        current: status.current,
+        latest: status.latest,
+        available: status.available,
+        checkedAt: status.checkedAt,
+        kind: status.kind,
+        command: status.available ? upgradeCommand(status.kind) : null,
+        disabled: status.disabled,
+        mocked: status.mocked,
+        error: status.error,
+    };
+}
+/**
+ * Asks the registry again and tells the open pages. `force` goes past a fresh cache, which is what the startup and the
+ * daily checks do; the answer is written back to `.tmp/`, so the command line shares it. Overlapping calls share one
+ * read: the daily timer and the first page load can arrive together.
+ */
+export function refreshUpdate(force = true) {
+    if (inFlight !== null)
+        return inFlight;
+    inFlight = (async () => {
+        try {
+            status = checkForUpdate({ force });
+        }
+        catch {
+            // checkForUpdate reports a failed read instead of throwing; if that ever changes, keep serving the last answer.
+        }
+        const answer = updateInfo();
+        const notice = status === null || status.disabled ? null : formatNotice(status, { color: useColor(process.stdout) });
+        // Printed on the terminal only when something changed: once at startup, and again for a newer release.
+        if (notice !== printedNotice && notice !== null) {
+            printedNotice = notice;
+            console.log(notice);
+        }
+        if (notice === null)
+            printedNotice = null;
+        updateEvents.emit('update', answer);
+        return answer;
+    })().finally(() => {
+        inFlight = null;
+    });
+    return inFlight;
+}
+/** Today's check, then one at every UTC midnight while the server runs. */
+export function startUpdateWatcher() {
+    void refreshUpdate(true);
+    scheduleNextCheck();
+}
+function scheduleNextCheck() {
+    const now = new Date();
+    const nextMidnight = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1);
+    const timer = setTimeout(() => {
+        void refreshUpdate(true);
+        scheduleNextCheck();
+    }, Math.max(1_000, nextMidnight - now.getTime()));
+    // The check must never keep the server process alive on its own.
+    timer.unref();
+}

package/dist/ui/shared/ai-commands.d.ts

@@ -32,9 +32,12 @@ export interface AiRunOptions {
     attended?: boolean;
     /** Show the agent's reasoning in the log (`--thinking` for OpenCode). Off by default: it costs tokens and time. */
     thinking?: boolean;
-    /** `heal-spec` only: the profiles to heal. Omitted = every profile that is logged in in `env`. */
+    /**
+     * `explore-case` and `heal-spec` only: the profiles to open / heal. Omitted = every profile that applies in `env`
+     * (all that are logged in, for heal). `gen-spec` takes none: it uses every profile the case names.
+     */
     profiles?: string[];
-    /** `heal-spec` only: file (relative to the project root) with the user's description and clues. */
+    /** `heal-spec` only: file (relative to the project root) with what the user wants repaired or improved, and any clues. */
     hints?: string;
     /** `heal-spec` only: the report (folder name under reports/) to read first instead of the newest one. */
     report?: string;
@@ -48,7 +51,7 @@ export interface AiSession {
     id: string;
     resume: boolean;
 }
-/** The prompt of a one-shot run. `heal-spec` has no questions of its own, so it keeps the plain slash command. */
+/** The prompt of a one-shot run. Every command may leave open questions in the case, so every one ends with a RESULT line. */
 export declare function headlessPrompt(command: AiCommand, caseId: string, options: AiRunOptions): string;
 /** Executable and arguments of the one-shot (non-interactive) run. */
 export declare function headlessInvocation(tool: AiTool, command: AiCommand, caseId: string, options: AiRunOptions, session?: AiSession): {

package/dist/ui/shared/ai-commands.js

@@ -17,16 +17,18 @@ export const AI_COMMAND_WRITES = {
  * Agents never write data in any of them: a person does those steps.
  */
 export const AI_ENV_HINT = {
-    'explore-case': 'Where the agent explores. It only reads; with Attended on, you do the steps that write data.',
+    'explore-case': 'Where the agent explores. Only the profiles you tick are opened; it only reads, and with Attended on you do the steps that write data.',
     'gen-spec': 'Where the agent explores and verifies the spec.',
-    'heal-spec': 'Where the failing spec is diagnosed. Only the profiles that are logged in there are run.',
+    'heal-spec': 'Where the failure is diagnosed and the pages are checked. Only the profiles that are logged in there are run.',
 };
 export const slashCommand = (command, caseId, options) => {
     const { env, force, attended, profiles, hints, report } = options;
     const heal = command === 'heal-spec';
+    // gen-spec has no profile option: its scope is every profile the case names.
+    const picksProfiles = command === 'explore-case' || heal;
     return (`/${command} ${caseId} ${env}${force && command === 'gen-spec' ? ' --force' : ''}` +
         `${attended && command === 'explore-case' ? ' --attended' : ''}` +
-        `${heal && profiles?.length ? ` --profiles ${profiles.join(',')}` : ''}` +
+        `${picksProfiles && profiles?.length ? ` --profiles ${profiles.join(',')}` : ''}` +
         `${heal && report ? ` --report ${report}` : ''}` +
         `${heal && hints ? ` --hints ${hints}` : ''}`);
 };
@@ -69,7 +71,9 @@ const STREAM_ARGS = {
     opencode: ['--format', 'json'],
 };
 function invocation(tool, prompt, writes, session, model, thinking) {
-    // OpenCode creates the session when the id does not exist yet, and continues it when it does.
+    // OpenCode creates the session when the id does not exist yet, and continues it when it does. It also keeps the
+    // agent (build/plan) on the session, so a session started in plan mode would only propose changes and ask a question
+    // nobody can answer; every one-shot run is a build run, whatever the session it continues.
     // A model is named on every run: without one OpenCode falls back to its built-in free model, which has a daily
     // usage limit, and nothing in the CLI's own state (the TUI's last-used model) applies to a one-shot run.
     if (tool === 'opencode')
@@ -78,6 +82,8 @@ function invocation(tool, prompt, writes, session, model, thinking) {
             args: [
                 'run',
                 '--auto',
+                '--agent',
+                'build',
                 ...STREAM_ARGS.opencode,
                 ...(session ? ['-s', session.id] : []),
                 ...(model ? ['--model', model] : []),
@@ -121,11 +127,9 @@ const ATTENDED = 'Attended run: a person is at the machine and the browser windo
     'inside the call that runs the card: the web UI sees that a person is needed only from that call, so without it ' +
     'there is no "Your turn" badge and no notification. Nobody can answer questions in the chat, so write open ' +
     'questions into the case file as the skill describes and end with the RESULT: line.';
-/** The prompt of a one-shot run. `heal-spec` has no questions of its own, so it keeps the plain slash command. */
+/** The prompt of a one-shot run. Every command may leave open questions in the case, so every one ends with a RESULT line. */
 export function headlessPrompt(command, caseId, options) {
     const slash = slashCommand(command, caseId, options);
-    if (command === 'heal-spec')
-        return slash;
     if (command === 'explore-case' && options.attended)
         return `${slash} ${ATTENDED}`;
     return `${slash} ${NON_INTERACTIVE}`;

package/dist/ui/shared/types.d.ts

@@ -103,7 +103,7 @@ export type StartJobRequest = {
      * its built-in free model. `heal-spec` keeps the model of the run it continues.
      */
     model?: string;
-    /** `heal-spec` only: the profiles to heal; omitted = every profile that is logged in. */
+    /** `explore-case` and `heal-spec` only: the profiles to open / heal; omitted = every profile that applies. `gen-spec` takes none: it uses every profile the case names. */
     profiles?: string[];
     /** `heal-spec` only: what the user knows (optional). The server stores it as a file for the agent. */
     hints?: string;
@@ -332,6 +332,30 @@ export interface InfoResponse {
     suites: string[];
     caseIds: string[];
 }
+/**
+ * What the web UI shows about a newer release. The first check of a server run may still be running, so every field
+ * that needs an answer is null until it finished.
+ */
+export interface UpdateInfo {
+    /** The version of the framework this server runs; null until the first check finished. */
+    current: string | null;
+    /** The newest release on the registry; null when there is none (or the registry could not be read). */
+    latest: string | null;
+    /** True when `latest` is newer than `current`. */
+    available: boolean;
+    /** When the answer was fetched, ISO. A cached answer keeps the time of the fetch. */
+    checkedAt: string | null;
+    /** `installed` when the framework comes from the registry, `checkout` for the framework's own git repository. */
+    kind: 'installed' | 'checkout' | null;
+    /** The line to run to get the newest release; null when there is nothing to upgrade. */
+    command: string | null;
+    /** True when ASRUN_NO_UPDATE_CHECK turned the check off. */
+    disabled: boolean;
+    /** True when the answer is a development mock (ASRUN_UPDATE_MOCK_* or `.tmp/update-mock.json`). */
+    mocked: boolean;
+    /** Why the last check could not read the registry; the UI stays quiet then. */
+    error: string | null;
+}
 /** Everything that belongs to one case. Shown before a delete or rename, and returned by them. */
 export interface CaseImpact {
     id: string;