@xingular/harness 0.1.7 → 1.0.0

package/dist/sdk/terminal/accountsMenu.js

@@ -0,0 +1,392 @@
+/** The same words the app shows for each health state (`App/src/modes/accounts/accountModel.ts`). */
+export const HEALTH = {
+    ok: 'Ready',
+    limited: 'Limit reached',
+    auth_expired: 'Sign in again',
+    signed_out: 'Signed out',
+    error: 'Needs attention',
+    unknown: 'Not checked'
+};
+const ADD = 'Add account';
+const POOLS = 'Pools';
+const CHECK_ALL = 'Check all accounts';
+const DONE = 'Done';
+const BACK = 'Back';
+const USE_HERE = 'Use for this session (restarts it)';
+const MAKE_DEFAULT = 'Make default for new sessions';
+const RENAME = 'Rename';
+const CHECK = 'Check';
+const DETAILS = 'Details';
+const ACTIVITY = 'Activity';
+const SIGN_IN = 'Sign in';
+const REMOVE_PROVIDER = 'Remove a provider';
+const SIGN_OUT = 'Sign out';
+const REMOVE = 'Remove account';
+const NEW_POOL = 'New pool';
+const EDIT = 'Edit';
+const DELETE = 'Delete';
+const SAVE_POOL = 'Save pool';
+const CANCEL = 'Cancel';
+const START_OVER = 'Start over';
+const REMOVE_LAST = 'Remove the last one';
+const CANCEL_SIGN_IN = 'Cancel sign-in';
+const CHECK_STATUS = 'Check status';
+const LOGIN_TIMEOUT_MS = 10 * 60_000;
+const POLL_MS = 1000;
+const message = (error) => (error instanceof Error ? error.message : String(error));
+/** Runs one call, reports a failure through the menu, and says whether it worked. */
+async function attempt(ui, action) {
+    try {
+        await action();
+        return true;
+    }
+    catch (error) {
+        ui.notify(message(error), 'error');
+        return false;
+    }
+}
+/** A short "in 2h 5m" from an ISO time, or the time itself when it has passed. */
+export function resetIn(resetsAt, now = Date.now()) {
+    const minutes = Math.round((Date.parse(resetsAt) - now) / 60_000);
+    if (Number.isNaN(minutes))
+        return resetsAt;
+    if (minutes <= 0)
+        return 'now';
+    if (minutes < 60)
+        return `in ${minutes}m`;
+    if (minutes < 60 * 24)
+        return `in ${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+    return `in ${Math.floor(minutes / (60 * 24))}d`;
+}
+/** One line per account, numbered so two accounts with the same name stay distinct in the menu. */
+export function accountRows(overview, session) {
+    return overview.accounts.map((account, index) => {
+        const mark = account.isDefault ? '●' : '○';
+        const here = session?.accountId === account.id ? ' · this session' : '';
+        return { account, label: `${index + 1}. ${mark} ${account.label} · ${HEALTH[account.state.health] ?? HEALTH.unknown}${here}` };
+    });
+}
+const limitLine = (limit) => `${limit.label}: ${limit.usedPercent ?? '?'}% used${limit.resetsAt ? `, resets ${resetIn(limit.resetsAt)}` : ''}`;
+/** What `Details` shows for one account. */
+export function accountDetails(account) {
+    const state = account.state;
+    const lines = [
+        account.label,
+        `Health: ${HEALTH[state.health] ?? HEALTH.unknown}`,
+        `Default for new sessions: ${account.isDefault ? 'yes' : 'no'}`,
+        `Signed in: ${state.signedIn === null ? 'not checked' : state.signedIn ? 'yes' : 'no'}`,
+        `Providers: ${state.piProviders.length ? state.piProviders.join(', ') : 'none'}`,
+        state.plan ? `Plan: ${state.plan}` : null,
+        state.identity ? `Identity: ${state.identity}` : null,
+        `Last checked: ${state.lastCheckedAt ? new Date(state.lastCheckedAt).toLocaleString() : 'never'}`,
+        state.lastError ? `Last error: ${state.lastError.message}${state.lastError.resetsAt ? ` (resets ${resetIn(state.lastError.resetsAt)})` : ''}` : null,
+        ...state.limits.map(limitLine),
+        state.limits.length ? null : 'Usage limits: Pi providers do not report them.',
+        state.capabilities.length ? `Detected: ${state.capabilities.join(', ')}` : null
+    ];
+    return lines.filter((line) => line !== null).join('\n');
+}
+/** The text shown while a sign-in waits for the person: a link, or a code to enter. */
+function loginStep(step) {
+    if (step.type === 'auth_url' && typeof step.url === 'string')
+        return `Open this link to sign in:\n${step.url}${typeof step.instructions === 'string' ? `\n${step.instructions}` : ''}`;
+    if (step.type === 'device_code' && typeof step.userCode === 'string')
+        return `Enter the code ${step.userCode} at ${String(step.verificationUri ?? '')}`;
+    return null;
+}
+/** The whole `/accounts` conversation. Returns `'relaunch'` when the person chose to switch this session's account. */
+export async function runAccountsMenu(ui, call, session) {
+    for (;;) {
+        const overview = await call('accounts.list');
+        const rows = accountRows(overview, session);
+        const options = [...rows.map((row) => row.label), ADD, POOLS, CHECK_ALL, DONE];
+        const picked = await ui.select('Accounts', options);
+        if (!picked || picked === DONE)
+            return;
+        if (picked === ADD) {
+            await addAccount(ui, call);
+            continue;
+        }
+        if (picked === POOLS) {
+            await poolsMenu(ui, call);
+            continue;
+        }
+        if (picked === CHECK_ALL) {
+            await attempt(ui, () => call('accounts.refresh'));
+            continue;
+        }
+        const row = rows[options.indexOf(picked)];
+        if (!row)
+            continue;
+        if ((await accountMenu(ui, call, session, row.account.id)) === 'relaunch')
+            return 'relaunch';
+    }
+}
+export async function addAccount(ui, call) {
+    const label = await ui.input('Name for the new account', 'Work, Personal, …');
+    if (!label?.trim())
+        return;
+    if (await attempt(ui, () => call('accounts.create', { label: label.trim(), authKind: 'subscription' })))
+        ui.notify('Account added. Sign in to use it.', 'info');
+}
+/** What can be done with one account; `details` is left out where the screen already shows them. */
+export function accountActions(account, isSession, details = true) {
+    return [
+        ...(isSession ? [] : [USE_HERE]),
+        ...(account.isDefault ? [] : [MAKE_DEFAULT]),
+        RENAME,
+        CHECK,
+        ...(details ? [DETAILS] : []),
+        ACTIVITY,
+        SIGN_IN,
+        ...(account.state.piProviders.length ? [REMOVE_PROVIDER] : []),
+        SIGN_OUT,
+        // The session's own account is in use, so it cannot be removed from inside the session.
+        ...(isSession ? [] : [REMOVE])
+    ];
+}
+/**
+ * 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 async function runAccountAction(ui, call, overview, account, action) {
+    const accountId = account.id;
+    if (action === USE_HERE) {
+        if (!(await ui.confirm('Switch this session?', `This ends the terminal's Pi process and resumes the conversation on ${account.label}. Work in progress stops.`)))
+            return;
+        if (await attempt(ui, () => call('accounts.relaunch', { accountId }))) {
+            ui.notify(`Switching to ${account.label}.`, 'info');
+            return 'relaunch';
+        }
+    }
+    else if (action === MAKE_DEFAULT) {
+        if (await attempt(ui, () => call('accounts.setDefault', { accountId })))
+            ui.notify(`${account.label} is the default for new sessions.`, 'info');
+    }
+    else if (action === RENAME) {
+        const label = await ui.input('New name', account.label);
+        if (label?.trim())
+            await attempt(ui, () => call('accounts.rename', { accountId, label: label.trim() }));
+    }
+    else if (action === CHECK) {
+        if (await attempt(ui, () => call('accounts.refresh', { accountId })))
+            ui.notify('Checked.', 'info');
+    }
+    else if (action === DETAILS) {
+        await ui.select(accountDetails(account), [BACK]);
+    }
+    else if (action === ACTIVITY) {
+        await showActivity(ui, call, accountId, account.label);
+    }
+    else if (action === SIGN_IN) {
+        await signIn(ui, call, account);
+    }
+    else if (action === REMOVE_PROVIDER) {
+        const provider = await ui.select('Remove which provider?', [...account.state.piProviders, BACK]);
+        if (!provider || provider === BACK)
+            return;
+        if (await ui.confirm(`Remove ${provider}?`, `The stored ${provider} sign-in for ${account.label} is deleted from this device.`))
+            await attempt(ui, () => call('accounts.removeProvider', { accountId, provider }));
+    }
+    else if (action === SIGN_OUT) {
+        if (await ui.confirm(`Sign out of ${account.label}?`, 'Stored sign-ins are deleted. The account stays, so you can sign in again.'))
+            await attempt(ui, () => call('accounts.signOut', { accountId }));
+    }
+    else if (action === REMOVE) {
+        const last = overview.accounts.length === 1;
+        const consequence = last
+            ? 'This is the only account. New sessions will ask you to add one.'
+            : account.isDefault
+                ? 'New sessions will use another account.'
+                : 'Sessions pinned to it will ask for another account next time they start.';
+        if (!(await ui.confirm(`Remove ${account.label}?`, `Its stored sign-in and its runtime folder are deleted. ${consequence}`)))
+            return;
+        if (await attempt(ui, () => call('accounts.remove', { accountId }))) {
+            ui.notify(`${account.label} was removed.`, 'info');
+            return 'gone';
+        }
+    }
+}
+async function accountMenu(ui, call, session, accountId) {
+    const isSession = session.accountId === accountId;
+    for (;;) {
+        const overview = await call('accounts.list');
+        const account = overview.accounts.find((candidate) => candidate.id === accountId);
+        if (!account)
+            return;
+        const action = await ui.select(`${account.label} · ${HEALTH[account.state.health] ?? HEALTH.unknown}`, [...accountActions(account, isSession), BACK]);
+        if (!action || action === BACK)
+            return;
+        const outcome = await runAccountAction(ui, call, overview, account, action);
+        if (outcome === 'relaunch')
+            return 'relaunch';
+        if (outcome === 'gone')
+            return;
+    }
+}
+async function showActivity(ui, call, accountId, label) {
+    const entries = await call('accounts.audit', { accountId, limit: 30 });
+    const lines = entries.map((entry) => `${new Date(entry.at).toLocaleString()} · ${entry.action} · ${entry.detail}`);
+    await ui.select(`${label}: activity\n${lines.join('\n') || 'Nothing has happened here yet.'}`, [BACK]);
+}
+async function signIn(ui, call, account) {
+    const providers = await call('accounts.providers');
+    if (!providers.length) {
+        ui.notify('No provider here can be signed in to.', 'warning');
+        return;
+    }
+    const labels = providers.map((provider, index) => `${index + 1}. ${provider.name}${account.state.piProviders.includes(provider.id) ? ' · signed in' : ''}`);
+    const pickedLabel = await ui.select(`Sign in ${account.label} to which provider?`, [...labels, BACK]);
+    const index = labels.indexOf(pickedLabel ?? '');
+    const provider = providers[index];
+    if (!provider)
+        return;
+    const methods = [...(provider.oauth ? [provider.oauthLabel ?? 'Sign in with the browser'] : []), ...(provider.apiKey ? ['Enter an API key'] : [])];
+    if (!methods.length) {
+        ui.notify(`${provider.name} has no sign-in from a terminal.`, 'warning');
+        return;
+    }
+    const method = methods.length === 1 ? methods[0] : await ui.select(`${provider.name}: how to sign in`, [...methods, BACK]);
+    if (!method || method === BACK)
+        return;
+    if (method === 'Enter an API key') {
+        const key = await ui.input(`API key for ${provider.name}`, 'Paste the key');
+        if (!key?.trim())
+            return;
+        if (await attempt(ui, () => call('accounts.setApiKey', { accountId: account.id, provider: provider.id, key: key.trim() })))
+            ui.notify(`Key saved for ${provider.name}.`, 'info');
+        return;
+    }
+    await runLogin(ui, call, account.id, provider.id);
+}
+/** Starts a provider sign-in and follows it until it ends: shows the link or code, answers prompts, and stops on a timeout. */
+async function runLogin(ui, call, accountId, provider) {
+    let loginId;
+    try {
+        loginId = (await call('accounts.loginStart', { accountId, provider })).loginId;
+    }
+    catch (error) {
+        ui.notify(message(error), 'error');
+        return;
+    }
+    return followLogin(ui, call, accountId, loginId);
+}
+async function followLogin(ui, call, accountId, loginId) {
+    const deadline = Date.now() + LOGIN_TIMEOUT_MS;
+    let shownRevision = -1;
+    for (;;) {
+        const snapshot = await call('accounts.loginStatus', { accountId });
+        // A newer sign-in on this account replaced ours; there is nothing left to follow.
+        if (!snapshot || snapshot.loginId !== loginId)
+            return;
+        if (snapshot.status !== 'running')
+            return reportLogin(ui, snapshot);
+        if (snapshot.prompt) {
+            await answerPrompt(ui, call, loginId, snapshot.prompt);
+            continue;
+        }
+        const step = [...snapshot.events].reverse().map(loginStep).find((text) => text !== null);
+        if (step && snapshot.revision !== shownRevision) {
+            shownRevision = snapshot.revision;
+            const choice = await ui.select(`${step}\n\nFinish in your browser, then choose Check status.`, [CHECK_STATUS, CANCEL_SIGN_IN]);
+            if (choice === CANCEL_SIGN_IN) {
+                await call('accounts.loginCancel', { accountId, loginId });
+                ui.notify('Sign-in cancelled.', 'warning');
+                return;
+            }
+            continue;
+        }
+        if (Date.now() > deadline) {
+            await call('accounts.loginCancel', { accountId, loginId });
+            ui.notify('Sign-in timed out and was cancelled.', 'error');
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+    }
+}
+function reportLogin(ui, snapshot) {
+    if (snapshot.status === 'completed')
+        ui.notify('Signed in.', 'info');
+    else if (snapshot.status === 'cancelled')
+        ui.notify('Sign-in was cancelled.', 'warning');
+    else
+        ui.notify(snapshot.error ?? 'Sign-in failed.', 'error');
+}
+async function answerPrompt(ui, call, loginId, prompt) {
+    const promptId = String(prompt.promptId ?? '');
+    const detail = (prompt.prompt ?? {});
+    const text = detail.message ?? 'Sign-in needs an answer.';
+    // A secret is typed with `input` like any other answer: it is never echoed or logged here.
+    let value;
+    if (detail.type === 'select' && Array.isArray(detail.options)) {
+        if (detail.options.every((option) => typeof option === 'string')) {
+            value = await ui.select(text, detail.options);
+        }
+        else if (detail.options.every((option) => typeof option === 'object' && option !== null && 'id' in option && typeof option.id === 'string' && 'label' in option && typeof option.label === 'string')) {
+            const options = detail.options;
+            const selected = await ui.select(text, options.map((option) => option.label));
+            value = options.find((option) => option.label === selected)?.id;
+        }
+    }
+    else {
+        value = await ui.input(text, detail.placeholder ?? undefined);
+    }
+    await call('accounts.loginRespond', { loginId, promptId, value: value ?? null });
+}
+async function poolsMenu(ui, call) {
+    for (;;) {
+        const overview = await call('accounts.list');
+        const names = new Map(overview.accounts.map((account) => [account.id, account.label]));
+        const labels = overview.pools.map((pool, index) => `${index + 1}. ${pool.label} · ${pool.accountIds.map((id) => names.get(id) ?? 'removed account').join(' → ')}`);
+        const options = [NEW_POOL, ...labels, BACK];
+        const picked = await ui.select('Pools: new sessions use the first ready account in a pool, in this order', options);
+        if (!picked || picked === BACK)
+            return;
+        if (picked === NEW_POOL) {
+            await editPool(ui, call, overview, null);
+            continue;
+        }
+        const pool = overview.pools[options.indexOf(picked) - 1];
+        if (!pool)
+            continue;
+        const action = await ui.select(pool.label, [EDIT, DELETE, BACK]);
+        if (action === EDIT)
+            await editPool(ui, call, overview, pool);
+        else if (action === DELETE && (await ui.confirm(`Delete ${pool.label}?`, 'The accounts stay. Only the pool is removed.')))
+            await attempt(ui, () => call('accounts.removePool', { poolId: pool.id }));
+    }
+}
+export async function editPool(ui, call, overview, pool) {
+    const label = await ui.input('Pool name', pool?.label);
+    if (!label?.trim())
+        return;
+    const names = new Map(overview.accounts.map((account) => [account.id, account.label]));
+    const order = [...(pool?.accountIds ?? [])];
+    for (;;) {
+        const ordered = order.map((id, index) => `${index + 1}. ${names.get(id) ?? 'removed account'}`).join('  ');
+        const free = overview.accounts.filter((account) => !order.includes(account.id));
+        const addOptions = free.map((account) => `Add ${account.label}`);
+        const options = [...addOptions, ...(order.length ? [REMOVE_LAST, START_OVER] : []), SAVE_POOL, CANCEL];
+        const picked = await ui.select(`${label.trim()}: ${ordered || 'no accounts yet'}`, options);
+        if (!picked || picked === CANCEL)
+            return;
+        if (picked === SAVE_POOL) {
+            if (!order.length) {
+                ui.notify('A pool needs at least one account.', 'error');
+                continue;
+            }
+            if (await attempt(ui, () => call('accounts.savePool', { pool: { id: pool?.id, label: label.trim(), accountIds: order } })))
+                ui.notify('Pool saved.', 'info');
+            return;
+        }
+        if (picked === START_OVER)
+            order.length = 0;
+        else if (picked === REMOVE_LAST)
+            order.pop();
+        else {
+            const account = free[addOptions.indexOf(picked)];
+            if (account)
+                order.push(account.id);
+        }
+    }
+}

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

@@ -0,0 +1,20 @@
+import type { HarnessCall } from "../tools/definitions.js";
+export declare const WIKI_COMMAND = "xagent-wiki";
+export declare const APPS_COMMAND = "xagent-mcp";
+export declare const USAGE = "Usage: xagent-wiki <command> [arguments]\n\n  search <query> [--project SLUG]    Search the Wiki's project notes\n  read <path>                        Read one note, e.g. projects/<slug>/decisions\n  list [project slug | library]      List notes\n  write <path> <text | ->            Save a note (when this session may write the Wiki)\n  skill [name]                       Load one of your skills, or list them\n  history <query> [--scope all] [--since YYYY-MM-DD]\n                                     Search earlier conversations and runs (also: recall)\n  history-read <run id>              Read one earlier run (also: recall-read)\n";
+export declare const APPS_USAGE = "Usage: xagent-mcp <command>\n\n  list                               The app and connected-app tools this session may use\n  call <tool-name> '<JSON arguments>'\n                                     Use one of them\n";
+export type CliCommand = {
+    kind: 'call';
+    call: HarnessCall;
+    params: Record<string, unknown>;
+} | {
+    kind: 'help';
+} | {
+    kind: 'stdin-write';
+    path: string;
+};
+export declare function parseCli(argv: string[]): CliCommand;
+/** Runs `xagent-wiki <argv>`; returns the exit code. */
+export declare function runWikiCli(argv: string[]): Promise<number>;
+/** Runs `xagent-mcp <argv>`; returns the exit code. */
+export declare function runAppsCli(argv: string[]): Promise<number>;

package/dist/sdk/terminal/cli.js

@@ -0,0 +1,121 @@
+import { connectionFromEnv, socketCall } from "./client.js";
+export const WIKI_COMMAND = 'xagent-wiki';
+export const APPS_COMMAND = 'xagent-mcp';
+export const USAGE = `Usage: ${WIKI_COMMAND} <command> [arguments]
+
+  search <query> [--project SLUG]    Search the Wiki's project notes
+  read <path>                        Read one note, e.g. projects/<slug>/decisions
+  list [project slug | library]      List notes
+  write <path> <text | ->            Save a note (when this session may write the Wiki)
+  skill [name]                       Load one of your skills, or list them
+  history <query> [--scope all] [--since YYYY-MM-DD]
+                                     Search earlier conversations and runs (also: recall)
+  history-read <run id>              Read one earlier run (also: recall-read)
+`;
+export const APPS_USAGE = `Usage: ${APPS_COMMAND} <command>
+
+  list                               The app and connected-app tools this session may use
+  call <tool-name> '<JSON arguments>'
+                                     Use one of them
+`;
+function options(args) {
+    const positional = [];
+    const flags = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg.startsWith('--') && index + 1 < args.length) {
+            flags[arg.slice(2)] = args[index + 1];
+            index += 1;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, flags };
+}
+export function parseCli(argv) {
+    const [command, ...rest] = argv;
+    const { positional, flags } = options(rest);
+    const joined = positional.join(' ').trim();
+    switch (command) {
+        case 'search':
+            if (!joined)
+                return { kind: 'help' };
+            return { kind: 'call', call: 'wiki.search', params: { query: joined, ...(flags.project ? { project: flags.project } : {}) } };
+        case 'read':
+            if (!joined)
+                return { kind: 'help' };
+            return { kind: 'call', call: 'wiki.read', params: { path: joined } };
+        case 'list':
+            return { kind: 'call', call: 'wiki.list', params: joined ? { project: joined } : {} };
+        case 'write': {
+            const [path, ...words] = positional;
+            if (!path)
+                return { kind: 'help' };
+            if (words.join(' ').trim() === '-')
+                return { kind: 'stdin-write', path };
+            if (!words.length)
+                return { kind: 'help' };
+            return { kind: 'call', call: 'wiki.write', params: { path, text: words.join(' ') } };
+        }
+        case 'skill':
+            return { kind: 'call', call: 'skill.load', params: joined ? { name: joined } : {} };
+        case 'history':
+        case 'recall':
+            if (!joined)
+                return { kind: 'help' };
+            return { kind: 'call', call: 'recall.search', params: { query: joined, ...(flags.scope ? { scope: flags.scope } : {}), ...(flags.since ? { since: flags.since } : {}) } };
+        case 'history-read':
+        case 'recall-read':
+            if (!joined)
+                return { kind: 'help' };
+            return { kind: 'call', call: 'recall.read', params: { run: joined } };
+        default:
+            return { kind: 'help' };
+    }
+}
+async function readStdin() {
+    let text = '';
+    for await (const chunk of process.stdin)
+        text += chunk.toString();
+    return text;
+}
+const errorText = (error) => (error instanceof Error ? error.message : String(error));
+/** Runs `xagent-wiki <argv>`; returns the exit code. */
+export async function runWikiCli(argv) {
+    const command = parseCli(argv);
+    if (command.kind === 'help') {
+        process.stdout.write(USAGE);
+        return argv.length ? 2 : 0;
+    }
+    try {
+        const connection = connectionFromEnv();
+        const result = command.kind === 'stdin-write'
+            ? await socketCall(connection, 'wiki.write', { path: command.path, text: await readStdin() })
+            : await socketCall(connection, command.call, command.params);
+        process.stdout.write(`${typeof result === 'string' ? result : JSON.stringify(result)}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${errorText(error)}\n`);
+        return 1;
+    }
+}
+/** Runs `xagent-mcp <argv>`; returns the exit code. */
+export async function runAppsCli(argv) {
+    const [command, name, args] = argv;
+    if (command !== 'list' && !(command === 'call' && name)) {
+        process.stdout.write(APPS_USAGE);
+        return argv.length ? 2 : 0;
+    }
+    try {
+        const connection = connectionFromEnv();
+        const result = command === 'list' ? await socketCall(connection, 'mcp.list', {}, 90_000) : await socketCall(connection, 'mcp.call', { name, args: JSON.parse(args ?? '{}') }, 1_230_000);
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${errorText(error)}\n`);
+        return 1;
+    }
+}

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

@@ -0,0 +1,15 @@
+export declare const SOCKET_ENV = "XINGULAR_HARNESS_SOCKET";
+export declare const TOKEN_ENV = "XINGULAR_HARNESS_TOKEN";
+export declare class SocketError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface SocketConnection {
+    socket: string;
+    token: string;
+}
+export declare function connectionFromEnv(env?: NodeJS.ProcessEnv): SocketConnection;
+/** A memory, Wiki, recall, or connected-app call made on behalf of the session that owns the token. */
+export declare function socketCall<T = unknown>(connection: SocketConnection, call: string, params?: Record<string, unknown>, timeoutMs?: number, control?: string): Promise<T>;
+/** Telemetry and decisions from the native `pi` process. Approvals may wait on a person, so the default wait is long. */
+export declare function terminalCall<T = Record<string, unknown>>(event: string, data?: Record<string, unknown>, timeoutMs?: number): Promise<T>;

package/dist/sdk/terminal/client.js

@@ -0,0 +1,126 @@
+// How a process outside the harness (the `pi` command's extension, the `xagent-wiki` and
+// `xagent-mcp` commands) reaches it: newline-delimited JSON requests and replies on the session
+// socket, authorized by the token the harness put in its environment. A reply leaves its connection
+// open for the next request, so the terminal's frequent small calls do not each open a socket.
+import { createConnection } from 'node:net';
+export const SOCKET_ENV = 'XINGULAR_HARNESS_SOCKET';
+export const TOKEN_ENV = 'XINGULAR_HARNESS_TOKEN';
+export class SocketError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function connectionFromEnv(env = process.env) {
+    const socket = env[SOCKET_ENV];
+    const token = env[TOKEN_ENV];
+    if (!socket || !token)
+        throw new SocketError('not_configured', `This command only works inside a terminal session the harness started (${SOCKET_ENV} and ${TOKEN_ENV} are not set).`);
+    return { socket, token };
+}
+const MAX_IDLE_PER_SOCKET = 4;
+/** Open connections waiting for their next request, per socket path. Idle ones never keep a process alive. */
+const idle = new Map();
+function takeIdle(path) {
+    const entries = idle.get(path);
+    const entry = entries?.values().next().value;
+    if (!entries || !entry)
+        return undefined;
+    entries.delete(entry);
+    entry.stream.off('close', entry.drop);
+    entry.stream.off('error', entry.drop);
+    entry.stream.ref();
+    return entry.stream;
+}
+function putIdle(path, stream) {
+    const entries = idle.get(path) ?? new Set();
+    if (stream.destroyed || entries.size >= MAX_IDLE_PER_SOCKET) {
+        stream.end();
+        return;
+    }
+    const entry = { stream, drop: () => { entries.delete(entry); stream.destroy(); } };
+    stream.once('close', entry.drop);
+    stream.on('error', entry.drop);
+    stream.unref();
+    entries.add(entry);
+    idle.set(path, entries);
+}
+function request(connection, body, what, timeoutMs) {
+    const reused = takeIdle(connection.socket);
+    return attempt(connection, body, what, timeoutMs, reused).catch((error) => {
+        // An idle connection the harness had already closed fails before any reply; one fresh retry.
+        if (reused && error instanceof StaleConnection)
+            return attempt(connection, body, what, timeoutMs, undefined);
+        throw error;
+    });
+}
+class StaleConnection extends Error {
+}
+function attempt(connection, body, what, timeoutMs, reused) {
+    return new Promise((resolve, reject) => {
+        const stream = reused ?? createConnection(connection.socket);
+        let buffer = '';
+        let replied = false;
+        let settled = false;
+        const send = () => stream.write(`${JSON.stringify({ token: connection.token, ...body, keep: true })}\n`);
+        const onData = (chunk) => {
+            replied = true;
+            buffer += chunk.toString('utf8');
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                return;
+            const rest = buffer.slice(newline + 1);
+            try {
+                const reply = JSON.parse(buffer.slice(0, newline));
+                if (reply.error) {
+                    const error = typeof reply.error === 'string' ? { message: reply.error } : reply.error;
+                    finish(() => reject(new SocketError(error.code ?? 'error', error.message ?? `${what} failed.`)), !rest);
+                }
+                else
+                    finish(() => resolve(reply.result), !rest);
+            }
+            catch {
+                finish(() => reject(new SocketError('invalid_reply', 'The harness sent an unreadable reply.')));
+            }
+        };
+        const onError = (error) => finish(() => reject(reused && !replied ? new StaleConnection(error.message) : new SocketError('unavailable', `The harness is not reachable: ${error.message}.`)));
+        const onClose = () => finish(() => reject(reused && !replied ? new StaleConnection('closed') : new SocketError('unavailable', 'The harness closed the connection.')));
+        const finish = (action, keep = false) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            stream.off('connect', send);
+            stream.off('data', onData);
+            stream.off('error', onError);
+            stream.off('close', onClose);
+            if (keep)
+                putIdle(connection.socket, stream);
+            else {
+                stream.on('error', () => { });
+                stream.end();
+            }
+            action();
+        };
+        const timer = setTimeout(() => {
+            stream.destroy();
+            finish(() => reject(new SocketError('timeout', `The harness did not answer ${what}.`)));
+        }, timeoutMs);
+        stream.on('data', onData);
+        stream.on('error', onError);
+        stream.on('close', onClose);
+        if (reused)
+            send();
+        else
+            stream.on('connect', send);
+    });
+}
+/** A memory, Wiki, recall, or connected-app call made on behalf of the session that owns the token. */
+export function socketCall(connection, call, params = {}, timeoutMs = 120_000, control) {
+    return request(connection, { call, params, ...(control ? { control } : {}) }, call, timeoutMs);
+}
+/** Telemetry and decisions from the native `pi` process. Approvals may wait on a person, so the default wait is long. */
+export function terminalCall(event, data = {}, timeoutMs = 600_000) {
+    return request(connectionFromEnv(), { event, data }, event, timeoutMs);
+}