@xingular/harness 0.1.7 → 1.0.0

package/dist/sdk/sessions/subagentService.js

@@ -0,0 +1,247 @@
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { loadRun as loadCapabilities } from "../capabilities/runSnapshot.js";
+import { HarnessError, invalid } from "../core/errors.js";
+import { now } from "../core/fs.js";
+import { takeChars } from "../core/text.js";
+import { isActiveStatus } from "./contracts.js";
+import { subagentOf } from "../variant/materialise.js";
+import { findRun, loadRun, readEvents, recordedSubagents, recordSubagent, saveRun } from "./runStore.js";
+import { SPAWN_SUBAGENT, SUBAGENT_RELATION, SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory } from "./subagents.js";
+function until(promise, signal) {
+    if (signal.aborted) {
+        void promise.catch(() => { });
+        return Promise.reject(new HarnessError('run_not_active', 'The parent run stopped.'));
+    }
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(new HarnessError('run_not_active', 'The parent run stopped.'));
+        signal.addEventListener('abort', abort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    });
+}
+/** One owner of native child execution and delivery, shared by SDK and terminal adapters. */
+export class Subagents {
+    env;
+    runs;
+    launch;
+    parents = new Map();
+    constructor(env, runs, launch) {
+        this.env = env;
+        this.runs = runs;
+        this.launch = launch;
+        runs.listen((event) => {
+            if (event.type !== 'completed' && event.type !== 'failed' && !(event.type === 'status.changed' && event.payload.status === 'interrupted'))
+                return;
+            this.parents.get(event.runId)?.stopped.abort();
+            this.parents.delete(event.runId);
+            if (event.type !== 'completed')
+                for (const id of runs.activeRunIds()) {
+                    const child = findRun(this.env.root, id);
+                    if (child?.relation === SUBAGENT_RELATION && child.parentRunId === event.runId)
+                        void runs.interrupt(id).catch(() => { });
+                }
+        });
+    }
+    /** Internal adapter contract: context comes from a live run, never from model arguments. */
+    register(input, accountId, capabilities, deferUntilPrompt = false) {
+        if (!this.runs.active(input.run.id))
+            throw new HarnessError('run_not_active', 'The parent run is not active.');
+        if (this.parents.has(input.run.id))
+            return;
+        const frozen = loadCapabilities(this.env.root, input.run.id);
+        if (!frozen)
+            throw invalid('A native parent requires a frozen capability snapshot.');
+        const ceiling = {
+            version: 1,
+            tools: capabilities.tools.filter(name => frozen.tools.includes(name)),
+            connectors: capabilities.connectors.filter(id => frozen.connectors.includes(id)),
+            contributions: capabilities.contributions.filter(id => frozen.contributions.includes(id))
+        };
+        let started;
+        const ready = new Promise(resolve => { started = resolve; });
+        if (!deferUntilPrompt)
+            started();
+        this.parents.set(input.run.id, { ready, started, input: structuredClone({ ...input, text: '', images: undefined, requiresImageInput: false, preamble: null, resume: null }), accountId, capabilities: ceiling, stopped: new AbortController(), recovered: new Set(), launching: new Map() });
+    }
+    resolvedModel(runId, model, effort) {
+        const parent = this.parents.get(runId);
+        if (parent) {
+            parent.input.model = model;
+            parent.input.effort = effort ?? parent.input.effort;
+        }
+    }
+    parent(runId) {
+        const parent = this.parents.get(runId);
+        if (!parent || !this.runs.active(runId))
+            throw new HarnessError('run_not_active', 'The parent run is not accepting subagents.');
+        return parent;
+    }
+    async spawn(request) {
+        const parent = this.parent(request.parentRunId);
+        const { input, accountId, capabilities } = parent;
+        if (!capabilities.tools.includes(SPAWN_SUBAGENT))
+            throw invalid('Subagents are not enabled for this run.');
+        const brief = typeof request.brief === 'string' ? request.brief.trim() : '';
+        if (!brief)
+            throw invalid('Give the subagent a brief.');
+        if (request.wait !== undefined && typeof request.wait !== 'boolean')
+            throw invalid('wait must be a boolean.');
+        if (request.tools !== undefined && (!Array.isArray(request.tools) || request.tools.some((name) => typeof name !== 'string')))
+            throw invalid('Tools must be an array of tool names.');
+        const outside = request.tools?.filter((name) => !capabilities.tools.includes(name)) ?? [];
+        if (outside.length)
+            throw invalid(`A subagent cannot have tools you do not have: ${outside.join(', ')}.`);
+        const tools = capabilities.tools.filter((name) => !request.tools || request.tools.includes(name));
+        await until(parent.ready, parent.stopped.signal);
+        let variant = input.variant ?? null;
+        let launch = input.launch;
+        if (request.agent !== undefined) {
+            if (typeof request.agent !== 'string' || !request.agent.trim())
+                throw invalid('agent must be the name of one of your subagents.');
+            const dir = variant && 'dir' in variant ? variant.dir : null;
+            const definition = dir ? subagentOf(dir, request.agent.trim()) : null;
+            if (!definition)
+                throw invalid(`There is no subagent named ${request.agent.trim()}.`);
+            // A named subagent works from its own definition, not from the parent's instructions.
+            variant = null;
+            launch = { ...(input.launch ?? {}), sections: [...(input.launch?.sections ?? []).filter((section) => section.id !== 'subagent'), { id: 'subagent', title: `Your role: ${definition.name}`, body: definition.instructions || definition.description, budget: 16_000, order: 22 }] };
+        }
+        const runId = randomUUID();
+        const sessionId = randomUUID();
+        recordSubagent(this.env.root, request.parentRunId, runId);
+        const child = {
+            ...input,
+            run: { ...input.run, id: runId, sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, goal: takeChars(brief, 4000), attachmentCount: 0, resumedFromRunId: null, handoffId: null },
+            accountId, poolId: null, sessionDir: join(input.sessionDir, 'subagents', runId), resume: null,
+            text: brief, images: undefined, requiresImageInput: false, preamble: null,
+            caller: { ...input.caller, runId: undefined, sessionId },
+            tools: { allow: tools, gated: (input.tools.gated ?? []).filter((name) => tools.includes(name)) },
+            capabilities: { ...capabilities, tools }, depth: (input.depth ?? 0) + 1,
+            variant, launch
+        };
+        const started = this.launch(child).catch((error) => {
+            if (!findRun(this.env.root, runId)) {
+                const source = loadRun(this.env.root, request.parentRunId);
+                saveRun(this.env.root, { ...source, id: runId, sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, nativeSessionId: null, resumedFromRunId: null, handoffId: null, exitCode: null, goal: takeChars(brief, 4000), attachmentCount: 0, status: 'failed', startedAt: now(), endedAt: now(), terminalReason: error instanceof HarnessError ? error.message : 'Subagent startup failed before its session opened.' });
+            }
+            return { runId, nativeSessionId: null };
+        });
+        parent.launching.set(runId, started);
+        void started.finally(() => parent.launching.delete(runId));
+        const result = await until(started, parent.stopped.signal);
+        if (request.wait)
+            await this.wait({ parentRunId: request.parentRunId, runIds: [runId] });
+        return result;
+    }
+    selected(selection, parent) {
+        const owned = new Set([...recordedSubagents(this.env.root, selection.parentRunId), ...(parent?.recovered ?? [])]);
+        if (selection.runIds !== undefined && (!Array.isArray(selection.runIds) || selection.runIds.some((id) => typeof id !== 'string')))
+            throw invalid('runIds must be an array of child run IDs.');
+        const ids = [...new Set(selection.runIds ?? [...owned])];
+        if (ids.some((id) => !owned.has(id)))
+            throw invalid('Select only subagents owned by this parent.');
+        return ids;
+    }
+    results(selection) {
+        loadRun(this.env.root, selection.parentRunId);
+        const parent = this.parents.get(selection.parentRunId);
+        return this.selected(selection, parent).map((runId) => {
+            const run = findRun(this.env.root, runId);
+            const reply = run && readEvents(this.env.root, runId).filter((event) => event.type === 'message.completed' && event.payload.role === 'assistant').at(-1);
+            const payload = reply?.payload;
+            return { runId, status: run?.status ?? 'queued', text: takeChars(payload?.text ?? '', 16_000), terminalReason: run?.terminalReason ?? null };
+        });
+    }
+    async wait(selection, signal) {
+        const parent = this.parent(selection.parentRunId);
+        const ids = this.selected(selection, parent);
+        const abort = signal ? AbortSignal.any([signal, parent.stopped.signal]) : parent.stopped.signal;
+        await until(Promise.all(ids.map(async (id) => {
+            const starting = parent.launching.get(id);
+            if (starting)
+                await starting;
+            const run = findRun(this.env.root, id);
+            if (run && isActiveStatus(run.status))
+                await this.runs.wait(id, abort);
+        })), abort);
+        return this.results({ ...selection, runIds: ids });
+    }
+    /** Reconcile only owners present on the selected native branch, with matching account and caller. */
+    restore(parentRunId, history) {
+        const parent = this.parent(parentRunId);
+        const current = loadRun(this.env.root, parentRunId);
+        for (const owner of history.owners) {
+            if (owner === parentRunId)
+                continue;
+            const old = findRun(this.env.root, owner);
+            if (!old || old.sessionId !== current.sessionId || old.accountId !== current.accountId || old.agentId !== current.agentId || old.projectId !== current.projectId || old.workingDirectory !== current.workingDirectory || !old.nativeSessionId || old.nativeSessionId !== current.nativeSessionId)
+                continue;
+            for (const id of recordedSubagents(this.env.root, owner)) {
+                let child = findRun(this.env.root, id);
+                if (!child) {
+                    // The process can die after reserving ownership but before sessions.run saves the child.
+                    saveRun(this.env.root, { ...old, id, sessionId: id, parentRunId: owner, relation: SUBAGENT_RELATION, nativeSessionId: null, resumedFromRunId: null, handoffId: null, exitCode: null, goal: null, attachmentCount: 0, status: 'interrupted', startedAt: now(), endedAt: now(), terminalReason: 'Subagent startup was interrupted before its session opened.' });
+                    child = findRun(this.env.root, id);
+                }
+                if (child?.parentRunId === owner && child.relation === SUBAGENT_RELATION && child.accountId === current.accountId)
+                    parent.recovered.add(id);
+            }
+        }
+    }
+    async delivery(parentRunId, history, settle, signal) {
+        const parent = this.parent(parentRunId);
+        this.restore(parentRunId, history);
+        if (settle) {
+            // A host may start another child while earlier children are settling.
+            for (;;) {
+                await this.wait({ parentRunId }, signal);
+                if (!parent.launching.size && this.results({ parentRunId }).every((result) => !isActiveStatus(result.status)))
+                    break;
+            }
+        }
+        const delivered = new Set(history.receipts.flatMap((receipt) => receipt.delivered ?? []));
+        const pending = this.results({ parentRunId }).filter((result) => !isActiveStatus(result.status) && !delivered.has(result.runId));
+        const chunks = [];
+        const ids = [];
+        let size = 0;
+        for (const result of pending) {
+            const text = `Subagent run ${result.runId} · ${result.status}\n${result.text || result.terminalReason || 'No written reply.'}`;
+            if (size + text.length > 32_000 && ids.length)
+                break;
+            chunks.push(text);
+            ids.push(result.runId);
+            size += text.length;
+        }
+        return ids.length ? { text: chunks.join('\n\n'), receipt: { version: 1, ownerRunId: parentRunId, delivered: ids } } : null;
+    }
+    /** A broken adapter must fail visibly rather than complete with an undelivered child result. */
+    async verify(parentRunId, history) {
+        if (history)
+            this.restore(parentRunId, history);
+        await this.wait({ parentRunId });
+        if (history && await this.delivery(parentRunId, history, false))
+            throw new HarnessError('subagent_delivery_failed', 'A child result was not persisted in this conversation. Resume this reply to recover it.');
+    }
+    extension(runId) {
+        return { name: 'native-subagents', factory: (pi) => {
+                pi.on('before_agent_start', (_event, ctx) => {
+                    if (!this.parents.has(runId))
+                        return;
+                    this.restore(runId, subagentHistory(ctx.sessionManager.getBranch()));
+                    pi.appendEntry(SUBAGENT_OWNER, { runId });
+                    this.parent(runId).started();
+                });
+                const deliver = async (event, ctx, settle) => {
+                    if (!this.parents.has(runId) || (settle && event.outcome !== 'completed') || ctx.signal?.aborted)
+                        return;
+                    const history = subagentHistory([...ctx.sessionManager.getBranch(), ...event.entries]);
+                    const result = await this.delivery(runId, history, settle, ctx.signal);
+                    if (!result)
+                        return;
+                    return { entries: [...event.entries, { type: 'custom_message', customType: SUBAGENT_RESULTS, content: result.text, display: false, details: { [SUBAGENT_RECEIPT]: result.receipt } }], continue: true };
+                };
+                pi.on('turn_end', (event, ctx) => deliver(event, ctx, false));
+                pi.on('agent_before_settle', (event, ctx) => deliver(event, ctx, true));
+            } };
+    }
+}

package/dist/sdk/sessions/subagents.d.ts

@@ -0,0 +1,50 @@
+export declare const SPAWN_SUBAGENT = "spawn_subagent";
+export declare const WAIT_SUBAGENTS = "wait_subagents";
+export declare const SUBAGENT_RELATION = "subagent";
+/** How deep subagents may nest when the caller does not say. */
+export declare const DEFAULT_SUBAGENT_DEPTH = 1;
+export declare const MAX_SUBAGENT_DEPTH = 3;
+export interface SubagentOptions {
+    /** Maximum consecutive native subagent levels below a caller (1 to 3). */
+    maxDepth?: number;
+}
+export declare function subagentDepth(options: SubagentOptions | undefined): number;
+export interface SubagentInput {
+    parentRunId: string;
+    brief: string;
+    tools?: string[];
+    wait?: boolean;
+    /** One of the parent harness's subagents (c5) by name; its instructions frame the child. */
+    agent?: string;
+}
+export interface SubagentSelection {
+    parentRunId: string;
+    runIds?: string[];
+}
+export interface SubagentResult {
+    runId: string;
+    status: string;
+    text: string;
+    terminalReason: string | null;
+}
+export interface SubagentReceipt {
+    version: 1;
+    ownerRunId: string;
+    spawned?: string[];
+    delivered?: string[];
+}
+export declare const SUBAGENT_RECEIPT = "xingularSubagents";
+export declare const SUBAGENT_OWNER = "xingular-subagent-owner";
+export declare const SUBAGENT_RESULTS = "xingular-subagent-results";
+/** Read explicit native metadata, including entries retained before compaction. */
+export declare function subagentHistory(entries: readonly unknown[]): {
+    owners: string[];
+    receipts: SubagentReceipt[];
+};
+/** Native nesting is independent of a host's other uses of the generic caller depth. */
+export declare function subagentNesting(root: string, run: {
+    relation?: string | null;
+    parentRunId?: string | null;
+}): number;
+/** The child's final reply, or why it ended without one. */
+export declare function subagentReport(root: string, runId: string): string;

package/dist/sdk/sessions/subagents.js

@@ -0,0 +1,68 @@
+import { takeChars } from "../core/text.js";
+import { findRun, loadRun, readEvents } from "./runStore.js";
+export const SPAWN_SUBAGENT = 'spawn_subagent';
+export const WAIT_SUBAGENTS = 'wait_subagents';
+export const SUBAGENT_RELATION = 'subagent';
+/** How deep subagents may nest when the caller does not say. */
+export const DEFAULT_SUBAGENT_DEPTH = 1;
+export const MAX_SUBAGENT_DEPTH = 3;
+export function subagentDepth(options) {
+    const value = Math.trunc(options?.maxDepth ?? DEFAULT_SUBAGENT_DEPTH);
+    return Math.min(MAX_SUBAGENT_DEPTH, Math.max(1, Number.isFinite(value) ? value : DEFAULT_SUBAGENT_DEPTH));
+}
+export const SUBAGENT_RECEIPT = 'xingularSubagents';
+export const SUBAGENT_OWNER = 'xingular-subagent-owner';
+export const SUBAGENT_RESULTS = 'xingular-subagent-results';
+/** Read explicit native metadata, including entries retained before compaction. */
+export function subagentHistory(entries) {
+    const owners = [];
+    const receipts = [];
+    for (const raw of entries) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const entry = raw;
+        if (entry.type === 'custom' && entry.customType === SUBAGENT_OWNER && typeof entry.data?.runId === 'string')
+            owners.push(entry.data.runId);
+        const message = entry.type === 'message' ? entry.message : entry;
+        const receipt = message?.details?.[SUBAGENT_RECEIPT];
+        if (!receipt || receipt.version !== 1 || typeof receipt.ownerRunId !== 'string')
+            continue;
+        const strings = (value) => Array.isArray(value) && value.every((id) => typeof id === 'string');
+        if ((receipt.spawned !== undefined && !strings(receipt.spawned)) || (receipt.delivered !== undefined && !strings(receipt.delivered)))
+            continue;
+        receipts.push(receipt);
+    }
+    return { owners, receipts };
+}
+/** Native nesting is independent of a host's other uses of the generic caller depth. */
+export function subagentNesting(root, run) {
+    let current = run;
+    let depth = 0;
+    const visited = new Set();
+    while (current.relation === SUBAGENT_RELATION) {
+        const parent = current.parentRunId;
+        if (!parent || visited.has(parent))
+            return MAX_SUBAGENT_DEPTH;
+        visited.add(parent);
+        depth++;
+        const record = findRun(root, parent);
+        if (!record)
+            return MAX_SUBAGENT_DEPTH;
+        current = record;
+    }
+    return depth;
+}
+/** The child's final reply, or why it ended without one. */
+export function subagentReport(root, runId) {
+    const run = loadRun(root, runId);
+    const reply = readEvents(root, runId).filter((event) => event.type === 'message.completed' && event.payload.role === 'assistant').at(-1);
+    const text = typeof reply?.payload?.text === 'string' ? takeChars(reply.payload.text, 16_000) : '';
+    const lines = [`Subagent run ${runId} · ${run.status}`];
+    if (text)
+        lines.push(`Result:\n${text}`);
+    else if (run.status === 'completed')
+        lines.push('It finished without a written reply.');
+    if (run.status !== 'completed' && run.terminalReason)
+        lines.push(`Stopped because: ${run.terminalReason}`);
+    return lines.join('\n');
+}

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

@@ -0,0 +1,46 @@
+import type { AccountsOverview, AccountView } from "../accounts/store.js";
+import type { MenuUi } from "./pluginMenu.js";
+export interface AccountsUi extends MenuUi {
+    input(title: string, placeholder?: string): Promise<string | undefined>;
+}
+/** `accounts.*` over the session socket, with the session's control key. */
+export type AccountsCall = <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>;
+/** The account this session is on, from `accounts.session`. */
+export interface SessionAccount {
+    accountId: string;
+    label: string;
+}
+/** One entry of `accounts.providers`. */
+export interface ProviderOption {
+    id: string;
+    name: string;
+    oauth: boolean;
+    oauthLabel: string | null;
+    apiKey: boolean;
+}
+/** The same words the app shows for each health state (`App/src/modes/accounts/accountModel.ts`). */
+export declare const HEALTH: Record<string, string>;
+/** A short "in 2h 5m" from an ISO time, or the time itself when it has passed. */
+export declare function resetIn(resetsAt: string, now?: number): string;
+/** One line per account, numbered so two accounts with the same name stay distinct in the menu. */
+export declare function accountRows(overview: AccountsOverview, session: SessionAccount | null): {
+    label: string;
+    account: AccountView;
+}[];
+/** What `Details` shows for one account. */
+export declare function accountDetails(account: AccountView): string;
+/** The whole `/accounts` conversation. Returns `'relaunch'` when the person chose to switch this session's account. */
+export declare function runAccountsMenu(ui: AccountsUi, call: AccountsCall, session: SessionAccount): Promise<'relaunch' | void>;
+export declare function addAccount(ui: AccountsUi, call: AccountsCall): Promise<void>;
+/** What can be done with one account; `details` is left out where the screen already shows them. */
+export declare function accountActions(account: AccountView, isSession: boolean, details?: boolean): string[];
+/**
+ * Runs one chosen action. `'relaunch'` means the session is switching to this account; `'gone'` that the
+ * account was removed. Anything the person declines or that fails leaves everything as it was.
+ */
+export declare function runAccountAction(ui: AccountsUi, call: AccountsCall, overview: AccountsOverview, account: AccountView, action: string): Promise<'relaunch' | 'gone' | void>;
+export declare function editPool(ui: AccountsUi, call: AccountsCall, overview: AccountsOverview, pool: {
+    id: string;
+    label: string;
+    accountIds: string[];
+} | null): Promise<void>;