@xingular/harness 1.0.0 → 1.2.0

package/dist/sdk/terminal/browserControl.js

@@ -0,0 +1,187 @@
+import { constants, closeSync, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { describePlugin } from "../plugins/surfaces.js";
+import * as path from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { invalid } from "../core/errors.js";
+import { connectionInputSchema } from "../mcp/types.js";
+import * as library from "../variant/components.js";
+import { PI_SURFACE, componentOf } from "../variant/surface.js";
+import { headVariant } from "../variant/store.js";
+const MAX_CONTENT = 256 * 1024;
+export function isWithinBoundary(boundary, file, pathApi = path) {
+    const within = pathApi.relative(boundary, file);
+    return within !== '..' && !within.startsWith(`..${pathApi.sep}`) && !pathApi.isAbsolute(within);
+}
+function readText(path) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_CONTENT)
+            throw invalid('Preview requires a regular text file smaller than 256 KiB.');
+        return readFileSync(fd, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Only the protected terminal control route calls this adapter. It never loads discovered code. */
+export class BrowserControl {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async snapshot(refresh = false) {
+        const { root, pinned, apps } = this.options;
+        const plugins = await this.options.plugins();
+        const scope = pinned?.scope ?? null;
+        const latest = scope ? headVariant(root, scope) : null;
+        const items = [];
+        const add = (item) => items.push(item);
+        for (const [id, name, description] of [
+            ['runtime', 'Runtime and recording', 'The foundation runs sessions and records their events. Changes require a release.'],
+            ['prompt', 'Prompt compiler', 'Assembles the stable prompt and context updates. Variant c1–c4 supply configurable instructions.'],
+            ['loader', 'Resource loader', 'Selects plugins and their contributions. Discovered code waits for exact-code trust.'],
+            ['gate', 'Tool approval gate', 'Checks capabilities, policy and approvals for every tool call. Availability never grants authorization.'],
+            ['accounts', 'Accounts and secrets', 'Keeps account identities isolated and credentials in the secret store.'],
+            ['surface', 'Variant surface', 'Defines c1–c8, validation and immutable versions. Only a validated variant version may change.']
+        ])
+            add({ id: `foundation:${id}`, section: 'foundation', name: name, description: description, owner: 'Foundation', origin: 'Built-in', status: 'Read-only' });
+        for (const plugin of plugins) {
+            add({ id: `plugin:${plugin.id}`, section: 'plugins', name: plugin.title, description: describePlugin(plugin),
+                owner: plugin.title, origin: plugin.source, status: plugin.required ? 'Required' : plugin.trust === 'untrusted' ? 'Needs trust' : 'Saved configuration',
+                pluginId: plugin.id, path: plugin.path ?? undefined, required: plugin.required });
+            for (const entry of plugin.contributions) {
+                if (!['skill', 'tool', 'command', 'instruction'].includes(entry.kind))
+                    continue;
+                if ((entry.kind === 'command' || entry.kind === 'instruction') && !entry.path)
+                    continue;
+                const section = entry.kind === 'skill' ? 'skills' : entry.kind === 'tool' ? 'tools' : 'library';
+                add({ id: `contribution:${entry.id}`, section, name: entry.name, description: entry.description,
+                    owner: plugin.title, origin: plugin.source, pluginId: plugin.id, contributionId: entry.id,
+                    path: entry.path ?? undefined, scope: entry.scope, status: entry.state === 'off' ? 'Disabled' : entry.state === 'untrusted' ? 'Needs trust' : 'Enabled for future sessions',
+                    read: Boolean(entry.path && ['skill', 'command', 'instruction'].includes(entry.kind)) });
+            }
+        }
+        for (const item of library.list(root)) {
+            const added = Boolean(latest && library.isInVariant(root, latest.variant, item.id));
+            const existing = items.find(existing => existing.path === item.path);
+            if (existing) {
+                existing.componentId = item.id;
+                existing.added = added;
+                continue;
+            }
+            add({ id: `library:${item.id}`, section: item.kind === 'skills' ? 'skills' : 'library', name: item.name,
+                description: item.description, owner: 'Reusable library', origin: item.builtin ? 'Built-in library' : 'Local library', path: item.path,
+                componentId: item.id, added, status: added ? 'Saved in latest variant' : 'Library only', read: true });
+        }
+        const paths = new Set([...Object.keys(pinned?.files ?? {}), ...Object.keys(latest?.variant ?? {})]);
+        for (const path of [...paths].sort()) {
+            const component = PI_SURFACE.components.find(entry => entry.id === componentOf(PI_SURFACE, path));
+            if (!component)
+                continue;
+            const current = pinned?.files[path];
+            const future = latest?.variant[path];
+            const status = !latest || current === future ? 'Pinned version' : current === undefined ? 'Added in latest' : future === undefined ? 'Removed in latest' : 'Changed in latest';
+            add({ id: `variant:${path}`, section: 'variant', name: path, description: `c${component.index} · ${component.title}: ${component.description}`,
+                owner: 'Variant', origin: 'Variant', status, read: true });
+            if (/^skills\/[^/]+\/SKILL\.md$/.test(path) && current !== undefined) {
+                const name = path.split('/')[1];
+                const fullPath = join(pinned.dir, path);
+                if (!items.some(item => item.section === 'skills' && item.path === fullPath))
+                    add({ id: `variant-skill:${path}`, section: 'skills', name,
+                        description: /^description:\s*(.+)$/m.exec(current)?.[1] ?? '', owner: 'Variant', origin: 'Variant', status: 'Prepared for this session',
+                        path: fullPath, read: true });
+            }
+        }
+        const connections = apps.connections.list().map(connection => ({ ...connection,
+            error: connection.error ? String(apps.connections.scrub(connection.error, connection.id)) : null,
+            tools: apps.connections.scrub(connection.tools, connection.id) }));
+        for (const connection of connections)
+            add({ id: `connection:${connection.id}`, section: 'connections', name: connection.name || connection.id,
+                description: `${connection.kind === 'remote' ? 'Remote HTTP' : 'Local stdio'} MCP · ${connection.tools.length} tools${connection.checkedAt ? ` · last checked ${connection.checkedAt}` : ' · never tested'}`,
+                owner: 'Connected apps', origin: connection.kind === 'remote' ? 'Remote' : 'Local', connectionId: connection.id,
+                scope: connection.global ? 'Everywhere' : connection.projectIds.join(', ') || 'No project scope',
+                status: !connection.enabled ? 'Disabled' : connection.auth === 'oauth' && connection.authState !== 'signed_in' ? 'Sign in required' : connection.error ? 'Last check failed' : connection.checkedAt ? 'Last check passed' : 'Not tested' });
+        return { items, plugins, connections, variant: { scope, pinned: pinned?.fingerprint ?? null, latest: latest?.fingerprint ?? null,
+                writable: this.options.writable && Boolean(scope && latest) }, hub: this.options.hub ? await this.options.hub.list(refresh) : null };
+    }
+    async read(id, latestVersion = false) {
+        const { root, pinned } = this.options;
+        const snapshot = await this.snapshot();
+        const item = snapshot.items.find(entry => entry.id === id);
+        if (!item?.read)
+            throw invalid('This resource has no inspectable content.');
+        if (id.startsWith('variant:') || id.startsWith('variant-skill:')) {
+            const path = id.slice(id.indexOf(':') + 1);
+            const files = latestVersion && pinned?.scope ? headVariant(root, pinned.scope)?.variant : pinned?.files;
+            const content = files?.[path] ?? '(File absent in this version.)';
+            return { content: content.length > MAX_CONTENT ? content.slice(0, MAX_CONTENT) + '\n[Preview truncated.]' : content };
+        }
+        if (!item.path)
+            throw invalid('This resource has no file.');
+        const plugin = snapshot.plugins.find(plugin => plugin.id === item.pluginId);
+        const registryItem = item.componentId ? library.list(root).find(entry => entry.id === item.componentId) : undefined;
+        const boundary = realpathSync(registryItem && !registryItem.builtin ? join(root, 'registry') : plugin?.path ?? dirname(item.path));
+        const file = realpathSync(item.path);
+        if (!isWithinBoundary(boundary, file))
+            throw invalid('Resource is outside its owner folder.');
+        return { content: readText(file) };
+    }
+    importSkill(input) {
+        const start = resolve(this.options.cwd, input);
+        const folder = lstatSync(start).isDirectory() ? start : dirname(start);
+        if (start !== folder && basename(start) !== 'SKILL.md')
+            throw invalid('Choose a skill folder or its SKILL.md.');
+        const files = [];
+        let bytes = 0;
+        let directories = 0;
+        const visit = (directory, depth = 0) => {
+            if (++directories > 100 || depth > 16)
+                throw invalid('Skill import exceeds its directory limit.');
+            for (const name of readdirSync(directory)) {
+                if (name.startsWith('.'))
+                    continue;
+                const path = join(directory, name);
+                const stat = lstatSync(path);
+                if (stat.isSymbolicLink())
+                    throw invalid('Skill imports cannot contain symbolic links.');
+                if (stat.isDirectory()) {
+                    visit(path, depth + 1);
+                    continue;
+                }
+                if (!stat.isFile() || files.length >= 100 || stat.size > 10 * 1024 * 1024)
+                    throw invalid('Skill import exceeds its file limit.');
+                bytes += stat.size;
+                if (bytes > 10 * 1024 * 1024)
+                    throw invalid('Skill import exceeds 10 MiB.');
+                files.push({ path: relative(folder, path), content: readFileSync(path).toString('base64'), encoding: 'base64' });
+            }
+        };
+        if (lstatSync(folder).isSymbolicLink())
+            throw invalid('Choose a regular skill folder.');
+        visit(folder);
+        library.importItems(this.options.root, 'skills', [{ name: basename(folder), files }]);
+    }
+    async connection(action, params) {
+        const apps = this.options.apps;
+        if (action === 'appClients')
+            return apps.appClients();
+        if (action === 'save')
+            return apps.save(connectionInputSchema.parse(params.input));
+        const id = typeof params.id === 'string' ? params.id : '';
+        if (!apps.connections.list().some(connection => connection.id === id))
+            throw invalid('Unknown connection.');
+        if (action === 'test') {
+            const result = await apps.test(id);
+            return { ...result, error: result.error ? String(apps.connections.scrub(result.error, id)) : null,
+                tools: apps.connections.scrub(result.tools, id) };
+        }
+        if (action === 'signIn')
+            return apps.signIn(id);
+        if (action === 'signOut')
+            return apps.signOut(id);
+        if (action === 'remove')
+            return apps.remove(id);
+        throw invalid('Unknown connection action.');
+    }
+}

package/dist/sdk/terminal/commandHelp.d.ts

@@ -0,0 +1,17 @@
+export interface TerminalCommandCompletion {
+    name: string;
+    aliases?: string[];
+    description?: string;
+    group: string;
+}
+export interface TerminalCommandHelpEntry {
+    name: string;
+    aliases?: string[];
+    description?: string;
+}
+export declare function formatTerminalCommandLabel(name: string, aliases?: readonly string[]): string;
+export interface TerminalCommandHelpGroup {
+    name: string;
+    commands: TerminalCommandHelpEntry[];
+}
+export declare function groupTerminalCommands(commands: readonly TerminalCommandCompletion[]): TerminalCommandHelpGroup[];

package/dist/sdk/terminal/commandHelp.js

@@ -0,0 +1,20 @@
+export function formatTerminalCommandLabel(name, aliases) {
+    return aliases?.length ? `${name} (${aliases.join(', ')})` : name;
+}
+const GROUP_ORDER = ['Core', 'Run', 'Model', 'Session', 'Inspect', 'Harness', 'Plugins', 'Extensions', 'Prompts'];
+export function groupTerminalCommands(commands) {
+    const groups = new Map();
+    for (const command of commands) {
+        const group = groups.get(command.group) ?? [];
+        group.push({
+            name: command.name,
+            ...(command.aliases?.length ? { aliases: command.aliases } : {}),
+            description: command.description
+        });
+        groups.set(command.group, group);
+    }
+    const order = new Map(GROUP_ORDER.map((name, index) => [name, index]));
+    return [...groups]
+        .sort(([left], [right]) => (order.get(left) ?? GROUP_ORDER.length) - (order.get(right) ?? GROUP_ORDER.length))
+        .map(([name, entries]) => ({ name, commands: entries }));
+}

package/dist/sdk/terminal/controller.d.ts

@@ -1,8 +1,10 @@
-import type { RunEvent } from "../sessions/contracts.js";
+import { type RunEvent, type RunRecord } from "../sessions/contracts.js";
 import type { ActiveRun, ApprovalDecision, QuestionAnswer } from "../sessions/registry.js";
+import { type TerminalSubagentActivity, type TerminalSubagentProfile, type TerminalSubagentRun } from "./subagentMonitor.js";
 export interface PolicyReply {
     allowed: boolean;
     reason?: string | null;
+    workspaceRoot?: string;
     requiresApproval?: boolean;
     rememberable?: boolean;
     standing?: 'full' | 'switch' | 'none';
@@ -18,6 +20,12 @@ export interface ControllerHooks {
     }): ActiveRun;
     /** Whether a native tool call may run. */
     policy(run: ActiveRun, tool: string, args: unknown): Promise<PolicyReply>;
+    /** The workspace root pinned on the run record. */
+    workspaceRoot(run: ActiveRun): string;
+    /** One-shot approval before an explicitly broad Bash command runs. */
+    workspaceEscape(run: ActiveRun, tool: string, args: unknown, reason: string): Promise<boolean>;
+    /** Whether Full Permission may bypass the filesystem boundary for this Bash command. */
+    workspaceBoundaryBypass(run: ActiveRun, tool: string, args: unknown): Promise<boolean>;
     /** Saves a user-selected tool grant in the shared local approval store. */
     allowToolGlobally(target: string): void;
     /** The native conversation identity changed. */
@@ -35,6 +43,8 @@ export declare class TerminalController {
     private readonly hooks;
     private run;
     private readonly pending;
+    private readonly subagents;
+    private subagentParentRunId;
     private ready;
     private disposed;
     private dirty;
@@ -64,6 +74,10 @@ export declare class TerminalController {
     disconnected(): void;
     /** Project registry-owned questions, including grouped requests, into the terminal inbox. */
     observe(event: RunEvent, descendant?: boolean): void;
+    /** A child event that belongs to the active terminal parent run. */
+    observeSubagent(parentRunId: string, run: RunRecord, event: RunEvent, profile?: TerminalSubagentProfile | null, runtime?: Pick<TerminalSubagentRun, 'accountLabel' | 'model' | 'effort'>): void;
+    /** Read-only child activity for the latest parent run, retained until another run begins. */
+    subagentSnapshot(): TerminalSubagentActivity[];
     /** The socket grants this interface only to the process that owns terminal input. */
     control(call: string, data: Record<string, any>): Promise<unknown>;
     private requestNativeApproval;

package/dist/sdk/terminal/controller.js

@@ -4,12 +4,17 @@
 // extension's questions about policy, approvals, and what to do next.
 import { createHash, randomUUID } from 'node:crypto';
 import { HarnessError } from "../core/errors.js";
+import { runStatusSchema } from "../sessions/contracts.js";
+import { briefTitle } from "../sessions/subagents.js";
+import { SubagentMonitor } from "./subagentMonitor.js";
 const READY_TIMEOUT_MS = 90_000;
 const ACK_TIMEOUT_MS = 25_000;
 export class TerminalController {
     hooks;
     run = null;
     pending = new Map();
+    subagents = new SubagentMonitor();
+    subagentParentRunId = null;
     ready = false;
     disposed = false;
     dirty = false;
@@ -48,6 +53,8 @@ export class TerminalController {
             throw new Error('The native prompt did not match the reserved delivery. Inspect the terminal before continuing.');
         const run = this.hooks.begin({ reservedRunId: delivery?.runId ?? null, nativeTurnId, text });
         this.run = run;
+        this.subagentParentRunId = run.runId;
+        this.subagents.begin(run.runId);
         run.onInterrupt(() => void this.commands.push({ type: 'interrupt' }));
         if (text)
             run.emit('message.completed', { messageId: nativeTurnId, role: 'user', text });
@@ -55,8 +62,8 @@ export class TerminalController {
         this.delivery = null;
         return run;
     }
-    finish(outcome, message) {
-        this.run?.finish(outcome, message ? { code: 'terminal_attention', message } : undefined);
+    finish(outcome, message, reason) {
+        this.run?.finish(outcome, message ? { code: 'terminal_attention', message } : undefined, reason);
         this.run = null;
         this.seen.clear();
         this.pending.clear();
@@ -126,10 +133,11 @@ export class TerminalController {
             const payload = event.payload;
             this.pending.set(String(payload.questionId), { ...payload, type: 'question', requestId: payload.questionId, runId: event.runId });
         }
-        else if (descendant && event.type === 'approval.requested') {
+        else if (event.type === 'approval.requested') {
             const payload = event.payload;
-            if (!payload.automatic)
+            if (!payload.automatic && (descendant || payload.target === 'workspace-write')) {
                 this.pending.set(String(payload.approvalId), { ...payload, type: 'approval', requestId: payload.approvalId, runId: event.runId });
+            }
         }
         else if (event.type === 'approval.resolved') {
             this.pending.delete(String(event.payload.approvalId));
@@ -138,6 +146,27 @@ export class TerminalController {
             this.pending.delete(String(event.payload.questionId));
         }
     }
+    /** A child event that belongs to the active terminal parent run. */
+    observeSubagent(parentRunId, run, event, profile = null, runtime = {}) {
+        if (this.disposed || this.activeRun?.runId !== parentRunId || run.relation !== 'subagent')
+            return;
+        this.subagents.observe(parentRunId, {
+            id: run.id,
+            parentRunId: run.parentRunId,
+            relation: 'subagent',
+            title: run.title ?? briefTitle(run.goal),
+            goal: run.goal,
+            status: runStatusSchema.parse(run.status),
+            startedAt: run.startedAt,
+            endedAt: run.endedAt,
+            profile,
+            ...runtime
+        }, event);
+    }
+    /** Read-only child activity for the latest parent run, retained until another run begins. */
+    subagentSnapshot() {
+        return this.subagentParentRunId ? this.subagents.snapshot(this.subagentParentRunId) : [];
+    }
     /** The socket grants this interface only to the process that owns terminal input. */
     async control(call, data) {
         if (this.disposed)
@@ -157,6 +186,20 @@ export class TerminalController {
                 throw new HarnessError('invalid_request', 'An active run and tool name are required.');
             return this.hooks.policy(run, data.tool, data.args ?? {});
         }
+        if (call === 'terminal.workspaceBoundaryBypass') {
+            const run = this.activeRun;
+            if (!run || data.tool !== 'bash')
+                throw new HarnessError('invalid_request', 'An active run and Bash command are required.');
+            const args = data.args && typeof data.args === 'object' && !Array.isArray(data.args) ? data.args : {};
+            return { bypass: await this.hooks.workspaceBoundaryBypass(run, 'bash', args) };
+        }
+        if (call === 'terminal.workspaceEscape') {
+            const run = this.activeRun;
+            if (!run || data.tool !== 'bash' || typeof data.reason !== 'string' || !data.reason)
+                throw new HarnessError('invalid_request', 'An active run, Bash command, and outside-scope request are required.');
+            const args = data.args && typeof data.args === 'object' && !Array.isArray(data.args) ? data.args : {};
+            return { approved: await this.hooks.workspaceEscape(run, 'bash', args, data.reason) };
+        }
         if (call === 'terminal.approval')
             return this.requestNativeApproval(data);
         if (call === 'terminal.answers' && this.hooks.answerQuestions) {
@@ -266,6 +309,10 @@ export class TerminalController {
             }
             this.ready = true;
             if (typeof data.nativeSessionId === 'string' && data.nativeSessionId) {
+                if (this.nativeId !== data.nativeSessionId) {
+                    this.subagents.clear();
+                    this.subagentParentRunId = null;
+                }
                 this.nativeId = data.nativeSessionId;
                 this.hooks.native(data.nativeSessionId);
             }
@@ -273,7 +320,7 @@ export class TerminalController {
         }
         if (event === 'begin') {
             const run = this.begin(String(data.turnId ?? randomUUID()), String(data.text ?? ''));
-            return { runId: run.runId };
+            return { runId: run.runId, workspaceRoot: this.hooks.workspaceRoot(run) };
         }
         if (event === 'shutdown') {
             this.ready = false;
@@ -281,7 +328,11 @@ export class TerminalController {
             return {};
         }
         if (event === 'settled') {
-            this.finish(data.aborted ? 'interrupted' : data.error ? 'failed' : 'completed', data.error ? String(data.error) : undefined);
+            // A reply that stopped at its work-slice boundary is interrupted, not completed: the record
+            // says `slice_complete` (or `stalled`) so a host can continue it (PROP-0041).
+            const reason = typeof data.reason === 'string' ? data.reason : undefined;
+            const outcome = data.error ? 'failed' : data.aborted || reason ? 'interrupted' : 'completed';
+            this.finish(outcome, data.error ? String(data.error) : undefined, reason);
             return {};
         }
         const run = this.run;
@@ -301,8 +352,10 @@ export class TerminalController {
             if (existing)
                 return event === 'approval' ? { decision: await existing } : existing;
             if (event === 'question') {
-                const response = run.requestAnswer({ requestId: key, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect, allowText: true });
-                this.pending.set(key, { type: 'question', requestId: key, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect });
+                const summary = typeof data.summary === 'string' && data.summary.trim() ? data.summary.trim() : undefined;
+                const sketchMode = data.uiSketch === undefined ? {} : { uiSketch: data.uiSketch };
+                const response = run.requestAnswer({ requestId: key, ...(summary ? { summary } : {}), ...sketchMode, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect, allowText: true });
+                this.pending.set(key, { type: 'question', requestId: key, ...(summary ? { summary } : {}), ...sketchMode, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect });
                 this.seen.set(key, response);
                 return response.finally(() => this.pending.delete(key));
             }
@@ -324,6 +377,10 @@ export class TerminalController {
         }
         if (event === 'usage')
             run.emit('usage.updated', data);
+        else if (event === 'checklist')
+            run.emit('checklist.updated', { items: data.items });
+        else if (event === 'checkpoint')
+            run.emit('checkpoint', data);
         else if (event === 'file')
             run.emit('file.changed', data);
         else if (event === 'message')
@@ -347,5 +404,7 @@ export class TerminalController {
         this.delivery?.reject(new Error('The terminal stopped before prompt acknowledgement.'));
         this.delivery = null;
         this.finish('interrupted');
+        this.subagents.clear();
+        this.subagentParentRunId = null;
     }
 }

package/dist/sdk/terminal/opentui/subagentsWidget.d.ts

@@ -0,0 +1,28 @@
+import { type TerminalSubagentActivity } from "../subagentMonitor.js";
+export type SubagentTone = 'success' | 'warning' | 'error' | 'muted' | 'accent';
+/** One roster row: status mark, profile, session name, checklist progress, in that order. */
+export interface SubagentRowView {
+    id: string;
+    mark: string;
+    tone: SubagentTone;
+    /** The profile name, or `subagent` for a copy of the parent. */
+    profile: string;
+    /** The profile's colour name (PROP-0029); null for a copy of the parent. */
+    color: string | null;
+    title: string;
+    /** `n of m tasks`, or null when the child wrote no checklist. */
+    tasks: string | null;
+}
+export interface SubagentRosterView {
+    rows: SubagentRowView[];
+    /** `+N more · /subagents` when rows were left out. */
+    overflow: string | null;
+}
+export declare function subagentTasks(checklist: TerminalSubagentActivity['checklist']): string | null;
+/**
+ * The compact live roster shown under the status line: active children first, at most three
+ * rows. The session name is cut first when the terminal is narrow.
+ */
+export declare function subagentRoster(items: readonly TerminalSubagentActivity[], width: number, frame?: string): SubagentRosterView | null;
+/** A row as plain text, the way it reads on screen. */
+export declare function subagentRowText(row: SubagentRowView): string;

package/dist/sdk/terminal/opentui/subagentsWidget.js

@@ -0,0 +1,52 @@
+import { stripTerminalSequences, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { ACTIVE_SUBAGENT_STATUSES } from "../subagentMonitor.js";
+import { getWorkingSpinnerFrames } from "../tui/workingStatus.js";
+const MAX_VISIBLE_ROWS = 3;
+const GAP = '  ';
+/** Cuts plain text to a width; the cut adds no styling codes. */
+function cut(text, width) {
+    return stripTerminalSequences(truncateToWidth(text, width, '…'));
+}
+function safe(text) {
+    return stripTerminalSequences(text).replace(/[\x00-\x1f\x7f]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+function mark(status, frame) {
+    switch (status) {
+        case 'completed': return { mark: '✓', tone: 'success' };
+        case 'failed': return { mark: '✕', tone: 'error' };
+        case 'interrupted': return { mark: '!', tone: 'muted' };
+        case 'queued': return { mark: '○', tone: 'muted' };
+        case 'waiting_for_approval':
+        case 'waiting_for_input': return { mark: '●', tone: 'accent' };
+        case 'running': return { mark: frame, tone: 'warning' };
+    }
+}
+export function subagentTasks(checklist) {
+    return checklist && checklist.total > 0 ? `${checklist.done} of ${checklist.total} tasks` : null;
+}
+/**
+ * The compact live roster shown under the status line: active children first, at most three
+ * rows. The session name is cut first when the terminal is narrow.
+ */
+export function subagentRoster(items, width, frame = getWorkingSpinnerFrames()[0] ?? '') {
+    if (!items.length || width < 1)
+        return null;
+    const ordered = [...items].sort((left, right) => {
+        const active = Number(ACTIVE_SUBAGENT_STATUSES.has(right.status)) - Number(ACTIVE_SUBAGENT_STATUSES.has(left.status));
+        return active || left.startedAt.localeCompare(right.startedAt) || left.id.localeCompare(right.id);
+    });
+    const rows = ordered.slice(0, MAX_VISIBLE_ROWS).map((item) => {
+        const status = mark(item.status, frame);
+        const profile = cut(safe(item.profile?.name ?? '') || 'subagent', Math.max(1, Math.min(24, width - 2)));
+        const tasks = subagentTasks(item.checklist);
+        const used = 2 + visibleWidth(profile) + GAP.length + (tasks ? GAP.length + tasks.length : 0);
+        const title = cut(safe(item.title) || 'Subagent', Math.max(1, width - used));
+        return { id: item.id, mark: status.mark, tone: status.tone, profile, color: item.profile?.color ?? null, title, tasks };
+    });
+    const overflow = ordered.length - rows.length;
+    return { rows, overflow: overflow > 0 ? cut(`+${overflow} more · /subagents`, width) : null };
+}
+/** A row as plain text, the way it reads on screen. */
+export function subagentRowText(row) {
+    return [`${row.mark} ${row.profile}`, row.title, row.tasks].filter(Boolean).join(GAP);
+}

package/dist/sdk/terminal/opentui/theme.d.ts

@@ -0,0 +1,43 @@
+export interface OpenTuiTheme {
+    background: string;
+    panel: string;
+    /** The translucent layer that dims the console behind a centered page dialog. */
+    scrim: string;
+    border: string;
+    borderFocus: string;
+    text: string;
+    muted: string;
+    dim: string;
+    /** The shared selected-row field and its two text tones. */
+    selectionBg: string;
+    selectionText: string;
+    selectionMuted: string;
+    questionSelectedBg: string;
+    questionActionBg: string;
+    questionActionText: string;
+    primary: string;
+    accent: string;
+    success: string;
+    warning: string;
+    error: string;
+    /** The composer's Bash mode marker and rules; the command body keeps the normal text color. */
+    bashMode: string;
+    /** The composer's rules while plan mode is on. */
+    planMode: string;
+    /** Image and pasted-text labels in the composer and in sent messages. */
+    attachment: string;
+    purple: string;
+    cyan: string;
+}
+export declare const opentuiTheme: OpenTuiTheme;
+/** The colour of an agent profile's name (PROP-0029); an unknown name falls back to the accent. */
+export declare function profileColor(theme: OpenTuiTheme, name: string): string;
+export declare function blendHexColor(from: string, to: string, amount: number): string;
+export declare function composerRuleColor(theme: OpenTuiTheme, mode: {
+    bash: boolean;
+    plan: boolean;
+    overlay: boolean;
+}): string;
+export declare function noticeColor(theme: OpenTuiTheme, type: string): string;
+export declare function toolColor(theme: OpenTuiTheme, status: 'running' | 'ok' | 'error' | 'pending'): string;
+export declare function thinkingLevelColor(theme: OpenTuiTheme, level: string): string;

package/dist/sdk/terminal/opentui/theme.js

@@ -0,0 +1,87 @@
+// OpenCode's terminal palette, carried by the Harness's own product name.
+import { SELECTION_COLORS } from "../tui/selection.js";
+export const opentuiTheme = {
+    background: '#0b0b0d',
+    panel: '#111114',
+    scrim: '#0b0b0d99',
+    border: '#2a2a31',
+    borderFocus: '#3a3a44',
+    text: '#e6e6e9',
+    muted: '#8b8b95',
+    dim: '#5c5c66',
+    selectionBg: SELECTION_COLORS.dark.background,
+    selectionText: SELECTION_COLORS.dark.text,
+    selectionMuted: SELECTION_COLORS.dark.muted,
+    questionSelectedBg: '#193322',
+    questionActionBg: '#35754a',
+    questionActionText: '#f7fff8',
+    primary: '#fab283',
+    accent: '#8ab4f8',
+    success: '#a6da95',
+    warning: '#eed49f',
+    error: '#ed8796',
+    bashMode: '#00ff88',
+    planMode: '#8ab4f8',
+    attachment: '#5ea1ff',
+    purple: '#c6a0f6',
+    cyan: '#8bd5ca'
+};
+/** The colour of an agent profile's name (PROP-0029); an unknown name falls back to the accent. */
+export function profileColor(theme, name) {
+    switch (name) {
+        case 'blue': return theme.accent;
+        case 'green': return theme.success;
+        case 'yellow': return theme.warning;
+        case 'red': return theme.error;
+        case 'magenta': return '#f5bde6';
+        case 'cyan': return theme.cyan;
+        case 'orange': return theme.primary;
+        case 'purple': return theme.purple;
+        default: return theme.accent;
+    }
+}
+export function blendHexColor(from, to, amount) {
+    const start = /^#([\da-f]{6})$/iu.exec(from)?.[1];
+    const end = /^#([\da-f]{6})$/iu.exec(to)?.[1];
+    if (!start || !end)
+        return from;
+    const weight = Number.isFinite(amount) ? Math.max(0, Math.min(1, amount)) : 0;
+    const channels = [0, 2, 4].map(offset => {
+        const first = Number.parseInt(start.slice(offset, offset + 2), 16);
+        const second = Number.parseInt(end.slice(offset, offset + 2), 16);
+        return Math.round(first + (second - first) * weight).toString(16).padStart(2, '0');
+    });
+    return `#${channels.join('')}`;
+}
+export function composerRuleColor(theme, mode) {
+    if (mode.bash)
+        return theme.bashMode;
+    if (mode.plan)
+        return theme.planMode;
+    return mode.overlay ? theme.border : theme.dim;
+}
+export function noticeColor(theme, type) {
+    if (type === 'error')
+        return theme.error;
+    if (type === 'warning')
+        return theme.warning;
+    return theme.muted;
+}
+export function toolColor(theme, status) {
+    if (status === 'error')
+        return theme.error;
+    if (status === 'running')
+        return theme.warning;
+    if (status === 'pending')
+        return theme.dim;
+    return theme.success;
+}
+export function thinkingLevelColor(theme, level) {
+    if (level === 'off')
+        return theme.dim;
+    if (level === 'minimal' || level === 'low')
+        return theme.muted;
+    if (level === 'medium')
+        return theme.accent;
+    return theme.primary;
+}