@asrunjs/asrun 0.2.0 → 0.5.2

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

@@ -68,10 +68,25 @@ const STREAM_ARGS = {
     claude: ['--output-format', 'stream-json', '--verbose'],
     opencode: ['--format', 'json'],
 };
-function invocation(tool, prompt, writes, session) {
+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.
+    // 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')
-        return { file: 'opencode', args: ['run', '--auto', ...STREAM_ARGS.opencode, ...(session ? ['-s', session.id] : []), prompt] };
+        return {
+            file: 'opencode',
+            args: [
+                'run',
+                '--auto',
+                ...STREAM_ARGS.opencode,
+                ...(session ? ['-s', session.id] : []),
+                ...(model ? ['--model', model] : []),
+                // Without it OpenCode does not ask the model to think, so the reasoning it does would never reach the log.
+                // Claude Code has no such flag: it shows thinking when the model and its settings have it on.
+                ...(thinking ? ['--thinking'] : []),
+                prompt,
+            ],
+        };
     return {
         file: 'claude',
         args: [
@@ -81,6 +96,7 @@ function invocation(tool, prompt, writes, session) {
             ...(session ? [session.resume ? '--resume' : '--session-id', session.id] : []),
             // `acceptEdits` approves edits anywhere in the folder, which would void the narrow Edit rules below.
             ...(writes === 'files' || writes === 'spec' ? ['--permission-mode', 'acceptEdits'] : []),
+            ...(model ? ['--model', model] : []),
             '--allowedTools',
             ...claudeAllowedTools(writes),
             '--disallowedTools',
@@ -100,7 +116,10 @@ const NON_INTERACTIVE = 'Non-interactive run: nobody can answer questions, so do
  * browser window, so the agent hands them the steps that write data and waits, as user-handoff.md describes.
  */
 const ATTENDED = 'Attended run: a person is at the machine and the browser window is visible, so hand steps that write data or ' +
-    'need a choice to them and wait, as the skill describes. Nobody can answer questions in the chat, so write open ' +
+    'need a choice to them and wait, as the skill describes. Start every handoff (also a second one in the same run) ' +
+    'with its own call that sets __handoffCfg, before the call that runs handoff-card.js, and never change those options ' +
+    '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. */
 export function headlessPrompt(command, caseId, options) {
@@ -113,7 +132,7 @@ export function headlessPrompt(command, caseId, options) {
 }
 /** Executable and arguments of the one-shot (non-interactive) run. */
 export function headlessInvocation(tool, command, caseId, options, session) {
-    return invocation(tool, headlessPrompt(command, caseId, options), AI_COMMAND_WRITES[command], session);
+    return invocation(tool, headlessPrompt(command, caseId, options), AI_COMMAND_WRITES[command], session, options.model, options.thinking);
 }
 /** The one-shot command as it is typed in a shell. */
 export function headlessCommandLine(tool, command, caseId, options, session) {
@@ -122,23 +141,27 @@ export function headlessCommandLine(tool, command, caseId, options, session) {
 /** Folder (relative to the AsRun root, git-ignored) where the clues typed into the Heal dialog are stored. */
 export const HINTS_DIR = '.tmp/hints';
 export const HINTS_MAX_CHARS = 8000;
+/** Folder (relative to the AsRun root, git-ignored) where the answers typed into the Continue box are stored. */
+export const REPLY_DIR = '.tmp/replies';
 export const REPLY_MAX_CHARS = 4000;
 export const USE_DEFAULTS_REPLY = 'Accept the suggestion of every open question: delete its TODO block and keep the sentence above it as confirmed text.';
 /**
  * The next turn of a run that ended with `RESULT: needs-input`: the user's answers. They go into the case file, which
- * stays the record of truth, and the task of the original command is finished.
+ * stays the record of truth, and the task of the original command is finished. The answers come from a file
+ * (`.tmp/replies/…md`) rather than from the prompt, so a line break or a quote in them cannot break the command line.
  */
-export function replyPrompt(command, reply) {
-    return (`The user answers your open questions (still nobody to ask, so do not stop to ask again):\n${reply.trim()}\n` +
+export function replyPrompt(command, replyFile) {
+    return (`The user answers your open questions (still nobody to ask, so do not stop to ask again). ` +
+        `Their answers are in ${replyFile}, relative to the project root: read that file first.\n` +
         'Fold every answer into the case file as the skill describes: write the answer into the sentence above the ' +
         'TODO block and remove the block, and keep a TODO block (with an empty Answer: line, emoji prefixes included) for what is still unknown. ' +
         `Then finish the task of /${command} and end with the RESULT: line.`);
 }
 /** The next turn of an earlier run, in its session and with exactly the permissions of the first turn. */
-export function continueInvocation(tool, command, reply, sessionId) {
-    return invocation(tool, replyPrompt(command, reply), AI_COMMAND_WRITES[command], { id: sessionId, resume: true });
+export function continueInvocation(tool, command, replyFile, sessionId, model, thinking) {
+    return invocation(tool, replyPrompt(command, replyFile), AI_COMMAND_WRITES[command], { id: sessionId, resume: true }, model, thinking);
 }
-export const continueCommandLine = (tool, command, reply, sessionId) => commandLine(continueInvocation(tool, command, reply, sessionId));
+export const continueCommandLine = (tool, command, replyFile, sessionId, model, thinking) => commandLine(continueInvocation(tool, command, replyFile, sessionId, model, thinking));
 /** Folder (relative to the AsRun root, git-ignored) where memos from the Cases page are stored. */
 export const MEMO_DIR = '.tmp/memos';
 export const MEMO_MAX_CHARS = 100_000;
@@ -150,5 +173,5 @@ export const makeCasePrompt = (memoPath) => `/make-case ${memoPath} ` +
     'Never overwrite an existing case: choose a new id instead. ' +
     'Put the cases of one area in a group folder (cases/<group>/<name>.md, id <group>/<name>), reusing an existing folder when it fits. ' +
     'Write the cases, run pnpm case:check, and list the open questions in your final report.';
-export const makeCaseInvocation = (tool, memoPath) => invocation(tool, makeCasePrompt(memoPath), 'cases-new');
-export const makeCaseCommandLine = (tool, memoPath) => commandLine(makeCaseInvocation(tool, memoPath));
+export const makeCaseInvocation = (tool, memoPath, model, thinking) => invocation(tool, makeCasePrompt(memoPath), 'cases-new', undefined, model, thinking);
+export const makeCaseCommandLine = (tool, memoPath, model, thinking) => commandLine(makeCaseInvocation(tool, memoPath, model, thinking));

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

@@ -33,6 +33,8 @@ export interface JobInfo {
     aiCommand?: AiCommand;
     /** The conversation of an AI run; a later job can resume it. */
     sessionId?: string;
+    /** The model the AI run was started with; omitted = the CLI's own choice. */
+    aiModel?: string;
     /** What the agent said in its last `RESULT:` line; null when it did not say or the run did not succeed. */
     resultState?: ResultState | null;
     /** The earlier job whose conversation this job continues. */
@@ -47,10 +49,33 @@ export interface AwaitingUserInfo {
 }
 /** `needs-input`: the agent wrote open questions into the case file and cannot go on without answers. */
 export type ResultState = 'ready' | 'needs-input';
+/**
+ * How one block of an AI job's log is presented. Absent for the plain output of every other job, which stays raw.
+ * `markdown`: what the agent said; `reasoning`: what it was thinking (not a result); `tool`: one call, started or
+ * finished; `result`: the first lines of a call's output; `error` / `hint`: what failed and what to do about it;
+ * `meta`: anything else a person should read (the waiting line, noise the CLI printed).
+ */
+export type JobChunkKind = 'tool' | 'result' | 'reasoning' | 'markdown' | 'error' | 'hint' | 'meta';
+/** A tool call of an AI job, so the log can color its name, its outcome and the time it took. */
+export interface JobChunkTool {
+    name: string;
+    /** What the call is about (the file, the command, the intent); empty when the CLI gave nothing telling. */
+    detail: string;
+    ok: boolean;
+    /** Still running: Claude reports the start of a call, OpenCode only its end. */
+    pending?: boolean;
+    /** How long it ran, as a person reads it (`0.4 s`); absent when the CLI did not report a start time. */
+    took?: string;
+}
 export interface JobChunk {
     seq: number;
     stream: 'stdout' | 'stderr' | 'system';
     data: string;
+    /** Set for the blocks of an AI job (see `JobChunkKind`); absent for a plain command's output. */
+    kind?: JobChunkKind;
+    /** When the block was produced, for AI jobs: shown as its own styled timestamp, not as part of the text. */
+    at?: string;
+    tool?: JobChunkTool;
 }
 export type StartJobRequest = {
     action: 'signin';
@@ -68,6 +93,16 @@ export type StartJobRequest = {
     env: string;
     force?: boolean;
     attended?: boolean;
+    /**
+     * Show the agent's reasoning in the log (`--thinking` for OpenCode; Claude shows it when its model has it on).
+     * Off by default: it costs tokens and time.
+     */
+    thinking?: boolean;
+    /**
+     * The model to run the agent with (as the CLI names it). Omitted = the CLI's own choice, which for OpenCode is
+     * 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. */
     profiles?: string[];
     /** `heal-spec` only: what the user knows (optional). The server stores it as a file for the agent. */
@@ -82,6 +117,8 @@ export type StartJobRequest = {
     action: 'make-cases';
     tool: AiTool;
     memo: string;
+    model?: string;
+    thinking?: boolean;
 } | {
     action: 'run';
     env: string;
@@ -163,6 +200,16 @@ export interface RunPlan {
 }
 export type ProfileStatus = 'missing' | 'unverified' | 'ok' | 'expired' | 'error';
 /** One profile: a row of the Profiles page. */
+export interface SessionCheckInfo {
+    /** Where a visitor without a valid session is sent: a path on the site (`/login`) or a full URL (single sign-on). */
+    loggedOutUrl: string;
+    /** A selector that only exists while signed in; null when the profile does not name one. */
+    loggedInSelector: string | null;
+    /** A selector that proves the visitor is signed out, e.g. the password field of a login form. */
+    loggedOutSelector: string | null;
+    /** How long to wait for one of those signals, in milliseconds. */
+    timeoutMs: number;
+}
 export interface ProfileInfo {
     id: string;
     name: string;
@@ -170,6 +217,14 @@ export interface ProfileInfo {
     baseURL: string;
     account: string | null;
     tags: string[];
+    /** The page "Visit" opens after a login, e.g. `/app/home`; empty = the site root. */
+    startPath: string;
+    /** A page only a signed-in visitor sees; `/account/` unless set in profiles.yaml. */
+    sessionCheckPath: string;
+    /** How that page shows a missing login. */
+    sessionCheck: SessionCheckInfo;
+    /** Tests may send real email in this environment. Always false for production. */
+    email: boolean;
     status: ProfileStatus;
     verifying: boolean;
     /** When the session file was last written. */
@@ -186,11 +241,41 @@ export interface AddProfileRequest {
     /** A label for humans (a mailbox or username). Never a password. */
     account?: string;
     tags?: string[];
+    /** The page "Visit" opens after a login. Defaults to the site root. */
+    startPath?: string;
     /** Page that redirects to /login when logged out. Defaults to /account/. */
     sessionCheckPath?: string;
+    /** How that page shows a missing login. Omitted keys keep their default. */
+    sessionCheck?: Partial<SessionCheckInfo>;
     /** Only for environments other than production. Defaults to false. */
     email?: boolean;
 }
+/** Changes to one existing profile. The id itself cannot change: commands, session files and baselines use it. */
+export interface EditProfileRequest {
+    name: string;
+    /** The environment this profile points at, e.g. `production`, `staging`. */
+    env: string;
+    baseURL: string;
+    /** A label for humans (a mailbox or username). Never a password. */
+    account?: string;
+    tags?: string[];
+    /** The page "Visit" opens after a login. Defaults to the site root. */
+    startPath?: string;
+    /** Page that redirects to /login when logged out. Defaults to /account/. */
+    sessionCheckPath?: string;
+    /** How that page shows a missing login. Omitted keys keep their default. */
+    sessionCheck?: Partial<SessionCheckInfo>;
+    /** Only for environments other than production. Defaults to false. */
+    email?: boolean;
+}
+export interface EditProfileResult {
+    profile: ProfileInfo;
+    /**
+     * True when the site address changed: the saved login belonged to the old site, was deleted, and the
+     * profile has to log in again.
+     */
+    sessionCleared: boolean;
+}
 export interface ProfilesResponse {
     profiles: ProfileInfo[];
     /** Every environment used in profiles.yaml, `production` first. */
@@ -255,3 +340,32 @@ export interface CaseImpact {
     snapshotDir: string | null;
     snapshotCount: number;
 }
+/** One model an AI CLI can be run with, as the CLI itself names it. */
+export interface AiModelOption {
+    /** Exactly what `--model` takes: `provider/model` or `provider/model#variant` (OpenCode), an alias or an id (Claude). */
+    id: string;
+    label: string;
+    /** Where the row comes from: a provider id, or `alias` / `settings` / `gateway` for a Claude CLI. */
+    group: string;
+    /** A second line: what the model is, or what an alias resolves to. */
+    detail?: string;
+}
+/** The models one AI CLI offers on this machine, read from the CLI itself or from its configuration. */
+export interface AiModelsResponse {
+    tool: AiTool;
+    models: AiModelOption[];
+    /**
+     * What the CLI would run when asrun passes no `--model`; null when it cannot be known (OpenCode picks a built-in
+     * free model, which is not stored anywhere).
+     */
+    clientDefault: string | null;
+    /**
+     * What to preselect while the user has not chosen: the CLI's default (Claude), or the model the CLI's own last
+     * session used (OpenCode). Null when neither is known.
+     */
+    suggested: string | null;
+    /** Parts of the list that could not be read, in the words of the CLI: shown above the list, never fatal. */
+    notes: string[];
+    /** Set when there is no list at all (the CLI is not installed, or its answer could not be read). */
+    error: string | null;
+}

package/docs/agents/framework-dev.md

@@ -0,0 +1,79 @@
+# Working on AsRun itself
+
+Read `AGENTS.md` first: it is the product baseline, and this file only adds how to change the framework. Nothing here
+is relevant to a project that uses asrun as a dependency.
+
+## Framework layout
+`<framework>` for a project is `node_modules/@asrunjs/asrun`. In this repository it is the root folder:
+- `lib/`              fixtures (`profile`, session guard) and assertion helpers; specs import them as
+                      `@asrunjs/asrun/<module>` (for example `@asrunjs/asrun/fixtures`, `@asrunjs/asrun/values`)
+- `scripts/`          user-facing commands, see README.md
+- `templates/`        the files `pnpm asrun init` writes into a workspace
+- `ui/`               local web UI (`pnpm ui`). It may only run the fixed actions in `ui/server/actions.ts`
+                      and must never serve anything under `.auth/`.
+- `docs/theme-guide.html` the Inkstone theme guide of the web UI: color tokens, buttons, badges, icons, surfaces
+- `examples/demo/`    a workspace for developing the framework itself against a local Docker stack (Conduit);
+                      it is committed (`.auth/` and `reports/` never are), see its README
+
+## Working on the framework itself
+- The framework repository holds no workspace content at the root: no `profiles.yaml`, `cases/`, `tests/` or
+  reports there. The one workspace is `examples/demo`, which is committed because it runs its own local site; its
+  `.auth/`, `reports/` and other run output are not. Develop against it: `pnpm demo:up` and `pnpm demo:seed` start
+  and fill the local stack, `pnpm asrun init --root examples/demo` (it also writes the framework's `.env` with
+  `ASRUN_ROOT=examples/demo`), then `pnpm asrun --env staging --read-only`.
+- Everything the framework reads for a project goes through `ROOT` in `lib/paths.ts` (the workspace root); its own
+  assets (templates, docs, skills, its `node_modules`) go through `FRAMEWORK_ROOT`. Never write into
+  `FRAMEWORK_ROOT` at run time.
+- `templates/` is the source of the files a workspace gets. When a template changes, bump `version` in
+  `package.json` so `pnpm asrun doctor` in a project shows that it is behind.
+- `init` owns two lists: `GENERATED` (rewritten by `--update`; the commands and the Playwright files) and `ONCE`
+  (written only when missing; `AGENTS.md`, `CLAUDE.md`, the configs). `AGENTS.md`, `CLAUDE.md` and
+  `.claude/skills/**` belong to the project: `init --force` refuses them unless `--reset-rules` is given, so a
+  framework update can never overwrite a project's rules.
+- A project's rules never flow back here. The framework reads a workspace only through `ROOT` at run time; nothing
+  under `templates/` or `.claude/skills/` is generated from a project.
+
+## The commands and the two agent CLIs
+- Claude Code reads `.claude/commands/*` and `.claude/skills/<name>/SKILL.md`.
+- OpenCode reads `.opencode/commands/*`, `.claude/skills/<name>/SKILL.md`, `.opencode/skills/<name>/SKILL.md` and
+  `.agents/skills/<name>/SKILL.md`. It does **not** read `.claude/commands`, and it does **not** read a flat
+  `.claude/skills/<skill>.md` as a skill (that file is a project override, read by the command and by the skill).
+- `GENERATED` renders the same four command texts into both `.claude/commands/` and `.opencode/commands/`, so edit
+  `templates/.claude/commands/*.md` once. In this repository the eight command files are written by hand: keep
+  `.claude/commands/` and `.opencode/commands/` identical (`diff -r .claude/commands .opencode/commands`).
+- OpenCode discovers skills by walking up from the working directory to the git worktree, so a workspace sees only
+  its own skills, not the framework ones under `node_modules`: the command's `Load the framework skill <path>` is a
+  plain file read. That is why the skill itself must read the project override (`.claude/skills/<skill>.md`).
+
+## Web UI (`ui/web`)
+Before adding or changing any UI element, read `docs/theme-guide.html` (open the file; it is static HTML) and follow it.
+Its rules are binding, in particular:
+- Icons: Feather via the `react-feather` package only (`import {ChevronDown} from 'react-feather'`). Never draw, paste
+  or hand-write SVGs, and never add another icon library. Size 14 in buttons, 16-20 elsewhere; decorative icons get
+  `aria-hidden="true"`, icon-only buttons get an `aria-label`. Do not use Unicode symbols (`▲ ▼ ◀ ▶ ⤢`) as icons.
+- Colors: only the tokens in `ui/web/src/index.css` (the default Tailwind palette is removed). Pick the color by impact.
+- Buttons and badges: use `buttonClass()` and `Badge` from `ui/web/src/components/status.tsx`, never hand-style them.
+- Dropdowns: use `Select` from the same file, never a bare `<select>` or hand-copied classes (native arrow and height
+  differ). A required dropdown that is empty gets `invalid` (red). See the "Dropdowns" section of the theme guide.
+- A list the user has to search in (a case id, a file name) is `SearchSelect` from
+  `ui/web/src/components/search-select.tsx`: an input with a filtered list below it, which a native `<select>` cannot
+  do. It keeps `Select`'s height, border and focus ring, so the two look like one family; do not build a third variant.
+- If a change adds or alters a token, update `ui/web/src/index.css` and `docs/theme-guide.html` together.
+Before reaching for a new dependency or writing a helper component, grep `package.json` and `ui/web/src` for what the
+project already uses.
+
+### Copy (`ui/web/src`)
+
+Every lead, label and tooltip is written for the person using the UI, never for the person who built it. Four rules:
+
+- **What → what you do → next.** A page, panel or section explains three things, in that order: what it does, what the
+  user has to do, and what comes next (state it only when something does). A run that needs nothing from the user says so.
+- **Short.** A lead is at most three sentences. A longer explanation becomes labeled paragraphs (`<b>While it runs</b> — …`)
+  or a bullet list, never one dense block. A tooltip is `# Title`, then at most three lines of one sentence each: it
+  wraps inside 320px (`ui/web/src/lib/tooltip.ts`).
+- **No implementation in the copy.** File paths, directory names, CLI flags, skill or command names, and the agent's
+  internal syntax (`TODO`, `Answer:`, `RESULT: needs-input`, `- Recipe:`) never appear in a lead, a label or a tooltip.
+  They belong where the file, the command or the syntax is the object itself: the Spec view, the Jobs drawer, a
+  `CopyBlock`, or a folded `<details>` block titled "For the command line".
+- **Say what the user sees.** "The run appears in the Jobs bar", not "the command runs in a one-shot session"; "the
+  browser shows a small card", not "the agent pauses on a `writes` step".