@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/accounts/store.d.ts

@@ -0,0 +1,139 @@
+/** The only provider the harness runs. Records of other providers are kept in the file and ignored. */
+export declare const PROVIDER = "pi";
+export interface Account {
+    id: string;
+    provider: string;
+    label: string;
+    /** `subscription` (a provider's own sign-in) or `apiKey`. */
+    authKind: string;
+    credentialStore?: string;
+    createdAt: string;
+}
+export interface Pool {
+    id: string;
+    provider: string;
+    label: string;
+    accountIds: string[];
+}
+interface Registry {
+    accounts: Account[];
+    defaults: Record<string, string>;
+    pools: Pool[];
+    migratedProviderKeys: boolean;
+}
+export interface Limit {
+    id: string;
+    label: string;
+    usedPercent?: number | null;
+    /** The same window from the other side: quota left. Additive for surfaces that read limits as remaining. */
+    remainingPercent?: number | null;
+    resetsAt?: string | null;
+    windowMinutes?: number | null;
+    /** `allowed`, `warning`, `rejected`, or `configured` when the provider reports it. */
+    status?: string | null;
+    /** Which provider the reading belongs to. Older records may omit it. */
+    provider?: string | null;
+    /** What kind of ceiling this is. */
+    kind?: 'window' | 'rate' | 'credit' | 'configured' | 'error';
+    /** The unit of `used`, `limit` and `remaining`. */
+    unit?: 'percent' | 'requests' | 'tokens' | 'usd' | 'currency' | 'count';
+    used?: number | null;
+    limit?: number | null;
+    remaining?: number | null;
+    /** How the reading was obtained. */
+    source?: 'headers' | 'provider' | 'estimate' | 'error';
+    observedAt?: string | null;
+    /** A short provider note, such as a balance currency. */
+    detail?: string | null;
+}
+/** The last readout for one provider of one account, including when nothing could be read. */
+export interface ProviderLimitState {
+    provider: string;
+    source: 'headers' | 'provider' | 'estimate' | 'unavailable';
+    reason: string | null;
+    observedAt: string;
+}
+export interface Issue {
+    /** `auth_expired`, `rate_limited`, `quota`, `network`, or `unknown`. */
+    category: string;
+    message: string;
+    at: string;
+    resetsAt: string | null;
+}
+export interface AccountState {
+    /** `ok`, `limited`, `auth_expired`, `signed_out`, `error`, or `unknown`. */
+    health: string;
+    signedIn: boolean | null;
+    authMethod: string | null;
+    plan: string | null;
+    identity: string | null;
+    limits: Limit[];
+    /** What the last limit readout found for each provider, including an unavailable one. */
+    providerLimits: ProviderLimitState[];
+    lastError: Issue | null;
+    lastCheckedAt: string | null;
+    cliVersion: string | null;
+    /** Features detected for this account, e.g. `models:12`, `provider:anthropic`. */
+    capabilities: string[];
+    /** Providers with a stored credential (names only). */
+    piProviders: string[];
+}
+export declare const emptyState: () => AccountState;
+export type AccountView = Account & {
+    isDefault: boolean;
+    state: AccountState;
+};
+export interface AccountsOverview {
+    accounts: AccountView[];
+    pools: Pool[];
+    defaults: Record<string, string>;
+}
+export interface AuditEntry {
+    at: string;
+    accountId: string | null;
+    action: string;
+    detail: string;
+}
+export declare function loadRegistry(dir: string): Registry;
+export declare function saveRegistry(dir: string, registry: Registry): void;
+export declare function loadState(dir: string, accountId: string): AccountState;
+/** Replaces anything that looks like a token so audit lines and stored errors never hold secrets. */
+export declare function scrub(text: string): string;
+export declare function audit(dir: string, accountId: string | null, action: string, detail: string): void;
+/** The newest audit entries first, optionally for one account. */
+export declare function readAudit(dir: string, accountId?: string | null, limit?: number): AuditEntry[];
+export declare const isLimitCategory: (category: string) => boolean;
+/**
+ * Whether a `rate_limited` or `quota` error still counts. With a reset time it counts until
+ * then; without one it counts for a short while after it was recorded.
+ */
+export declare function limitErrorActive(issue: Issue): boolean;
+export declare function deriveHealth(state: AccountState): string;
+/** Read-modify-write on one account's state. Returns the previous health and the new state. */
+export declare function updateState(dir: string, accountId: string, change: (state: AccountState) => void): {
+    previous: string;
+    state: AccountState;
+};
+export declare function find(dir: string, accountId: string): Account;
+/**
+ * Chooses the account for a new session: the explicit account, else the pool's first usable
+ * account, else the default, else the first account. It never skips to another one silently.
+ */
+export declare function resolve(dir: string, accountId?: string | null, poolId?: string | null): Account;
+/** The default account, if any exists. */
+export declare function defaultAccount(dir: string): Account | null;
+export declare function summaryAuthentication(dir: string): 'authenticated' | 'unauthenticated' | 'unknown';
+export declare function overview(dir: string): AccountsOverview;
+export declare function cleanLabel(label: string): string;
+export declare function addAccount(dir: string, label: string, authKind: string): Account;
+export declare function renameAccount(dir: string, accountId: string, label: string): void;
+export declare function setDefault(dir: string, accountId: string): Account;
+/** Drops the account from the registry, its pools, and the default. Its folder and secrets are the caller's to remove. */
+export declare function forgetAccount(dir: string, account: Account): void;
+export declare function savePool(dir: string, pool: {
+    id?: string;
+    label: string;
+    accountIds: string[];
+}): Pool;
+export declare function removePool(dir: string, poolId: string): void;
+export {};

package/dist/sdk/accounts/store.js

@@ -0,0 +1,255 @@
+// Accounts. One profile (settings, registry, memory) and any number of Pi accounts, each with
+// its own isolated agent folder, stored credentials, sign-in state, limits, health, and audit
+// trail.
+//
+// Device-local layout under `<state dir>/accounts/`:
+//   accounts.json        accounts, the default, pools (no secrets)
+//   <id>/state.json      health, plan, limits, last error (no secrets)
+//   <id>/home/pi/        Pi's own agent folder for this account
+//   _shared/pi/          settings, skills, prompts linked into every account's agent folder
+//   audit.jsonl          append-only account actions (secrets scrubbed)
+//
+// Switching is always manual. A pool only chooses an account when a session starts; a running
+// or resumed session keeps the account it started with.
+import { mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { HarnessError, invalid, notFound } from "../core/errors.js";
+import { appendLine, newId, now, readJsonOr, safeId, writeJson } from "../core/fs.js";
+import { charCount, compareText, lines, takeChars } from "../core/text.js";
+/** The only provider the harness runs. Records of other providers are kept in the file and ignored. */
+export const PROVIDER = 'pi';
+export const emptyState = () => ({ health: 'unknown', signedIn: null, authMethod: null, plan: null, identity: null, limits: [], providerLimits: [], lastError: null, lastCheckedAt: null, cliVersion: null, capabilities: [], piProviders: [] });
+// ---- Files ------------------------------------------------------------------------------
+const registryPath = (dir) => join(dir, 'accounts.json');
+const statePath = (dir, accountId) => join(dir, safeId(accountId), 'state.json');
+export function loadRegistry(dir) {
+    const stored = readJsonOr(registryPath(dir), {}) ?? {};
+    return { accounts: stored.accounts ?? [], defaults: stored.defaults ?? {}, pools: stored.pools ?? [], migratedProviderKeys: stored.migratedProviderKeys ?? false };
+}
+export function saveRegistry(dir, registry) {
+    mkdirSync(dir, { recursive: true });
+    writeJson(registryPath(dir), registry);
+}
+export function loadState(dir, accountId) {
+    try {
+        return { ...emptyState(), ...(readJsonOr(statePath(dir, accountId), {}) ?? {}) };
+    }
+    catch {
+        return emptyState();
+    }
+}
+function saveState(dir, accountId, state) {
+    writeJson(statePath(dir, accountId), state);
+}
+/** Replaces anything that looks like a token so audit lines and stored errors never hold secrets. */
+export function scrub(text) {
+    const words = text.split(' ').map((word) => {
+        const bytes = Buffer.byteLength(word);
+        const tokenLike = bytes >= 24 && (word.match(/[A-Za-z0-9]/g)?.length ?? 0) * 10 >= bytes * 8;
+        return tokenLike || word.startsWith('sk-') || word.startsWith('sess-') ? '[redacted]' : word;
+    });
+    return takeChars(words.join(' '), 500);
+}
+export function audit(dir, accountId, action, detail) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        appendLine(join(dir, 'audit.jsonl'), JSON.stringify({ at: now(), accountId, action, detail: scrub(detail) }));
+    }
+    catch {
+        // An audit line that cannot be written never fails the action it describes.
+    }
+}
+/** The newest audit entries first, optionally for one account. */
+export function readAudit(dir, accountId, limit = 100) {
+    let text = '';
+    try {
+        text = readFileSync(join(dir, 'audit.jsonl'), 'utf8');
+    }
+    catch {
+        text = '';
+    }
+    const entries = lines(text).flatMap((line) => {
+        try {
+            const entry = JSON.parse(line);
+            return entry && typeof entry.at === 'string' && typeof entry.action === 'string' && (!accountId || entry.accountId === accountId) ? [entry] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    return entries.reverse().slice(0, Math.min(limit, 1000));
+}
+// ---- Health -----------------------------------------------------------------------------
+function inFuture(timestamp) {
+    const time = timestamp ? Date.parse(timestamp) : Number.NaN;
+    return !Number.isNaN(time) && time > Date.now();
+}
+// How long a limit error that came without a reset time keeps the account limited. Providers
+// report no limit windows, so nothing else would ever lift it.
+const UNTIMED_LIMIT_ERROR_SECS = 3600;
+export const isLimitCategory = (category) => category === 'rate_limited' || category === 'quota';
+/**
+ * Whether a `rate_limited` or `quota` error still counts. With a reset time it counts until
+ * then; without one it counts for a short while after it was recorded.
+ */
+export function limitErrorActive(issue) {
+    if (issue.resetsAt)
+        return inFuture(issue.resetsAt);
+    const at = Date.parse(issue.at);
+    return !Number.isNaN(at) && Math.trunc((Date.now() - at) / 1000) < UNTIMED_LIMIT_ERROR_SECS;
+}
+export function deriveHealth(state) {
+    const limitedByWindow = state.limits.some((limit) => (limit.status === 'rejected' || (limit.usedPercent ?? 0) >= 100) && (!limit.resetsAt || inFuture(limit.resetsAt)));
+    const issue = state.lastError;
+    if (issue?.category === 'auth_expired')
+        return 'auth_expired';
+    if (issue && isLimitCategory(issue.category) && limitErrorActive(issue))
+        return 'limited';
+    if (state.signedIn === false)
+        return 'signed_out';
+    if (limitedByWindow)
+        return 'limited';
+    if (issue && !isLimitCategory(issue.category))
+        return 'error';
+    return state.signedIn === true ? 'ok' : 'unknown';
+}
+/** Read-modify-write on one account's state. Returns the previous health and the new state. */
+export function updateState(dir, accountId, change) {
+    const state = loadState(dir, accountId);
+    const previous = state.health;
+    change(state);
+    state.health = deriveHealth(state);
+    saveState(dir, accountId, state);
+    return { previous, state };
+}
+// ---- Lookup and pinning -----------------------------------------------------------------
+export function find(dir, accountId) {
+    const account = loadRegistry(dir).accounts.find((entry) => entry.id === accountId);
+    if (!account)
+        throw new HarnessError('account_required', "This session's account was removed.", 'Choose another account for it.');
+    return account;
+}
+const usable = (state) => state.health === 'ok' || state.health === 'unknown';
+/**
+ * Chooses the account for a new session: the explicit account, else the pool's first usable
+ * account, else the default, else the first account. It never skips to another one silently.
+ */
+export function resolve(dir, accountId, poolId) {
+    const registry = loadRegistry(dir);
+    if (accountId) {
+        const account = find(dir, accountId);
+        if (account.provider !== PROVIDER)
+            throw invalid('That account belongs to another provider.');
+        return account;
+    }
+    if (poolId) {
+        const pool = registry.pools.find((entry) => entry.id === poolId);
+        if (!pool)
+            throw notFound('Pool');
+        const members = pool.accountIds.flatMap((id) => registry.accounts.find((account) => account.id === id) ?? []);
+        const ready = members.find((account) => usable(loadState(dir, account.id)));
+        if (ready)
+            return ready;
+        const resets = members.flatMap((account) => {
+            const state = loadState(dir, account.id);
+            return [...state.limits.map((limit) => limit.resetsAt), state.lastError?.resetsAt].filter((reset) => Boolean(reset));
+        });
+        const earliest = resets.sort(compareText)[0];
+        throw new HarnessError('account_unavailable', `Every account in ${pool.label} is unavailable.`, earliest ? `The earliest reset is ${earliest}.` : 'Reauthenticate an account in Accounts.');
+    }
+    const account = registry.accounts.find((entry) => entry.id === registry.defaults[PROVIDER]) ?? registry.accounts.find((entry) => entry.provider === PROVIDER);
+    if (!account)
+        throw new HarnessError('account_required', 'Add a Pi account first.', 'Open Accounts (⌘4) to sign in.');
+    return account;
+}
+/** The default account, if any exists. */
+export function defaultAccount(dir) {
+    try {
+        return resolve(dir);
+    }
+    catch {
+        return null;
+    }
+}
+export function summaryAuthentication(dir) {
+    const states = loadRegistry(dir).accounts.filter((account) => account.provider === PROVIDER).map((account) => loadState(dir, account.id));
+    if (states.some((state) => state.signedIn === true))
+        return 'authenticated';
+    return states.some((state) => state.signedIn === false) ? 'unauthenticated' : 'unknown';
+}
+export function overview(dir) {
+    const registry = loadRegistry(dir);
+    return {
+        accounts: registry.accounts.filter((account) => account.provider === PROVIDER).map((account) => ({ ...account, isDefault: registry.defaults[account.provider] === account.id, state: loadState(dir, account.id) })),
+        pools: registry.pools.filter((pool) => pool.provider === PROVIDER),
+        defaults: registry.defaults
+    };
+}
+// ---- Changes ----------------------------------------------------------------------------
+export function cleanLabel(label) {
+    const cleaned = label.trim();
+    if (!cleaned || charCount(cleaned) > 60)
+        throw invalid('Give the account a name of 1–60 characters.');
+    return cleaned;
+}
+export function addAccount(dir, label, authKind) {
+    if (authKind !== 'subscription' && authKind !== 'apiKey')
+        throw invalid('Unknown sign-in type.');
+    const account = { id: newId(), provider: PROVIDER, label: cleanLabel(label), authKind, credentialStore: 'keyring', createdAt: now() };
+    const registry = loadRegistry(dir);
+    registry.defaults[PROVIDER] ??= account.id;
+    registry.accounts.push(account);
+    saveRegistry(dir, registry);
+    return account;
+}
+export function renameAccount(dir, accountId, label) {
+    const cleaned = cleanLabel(label);
+    const registry = loadRegistry(dir);
+    const account = registry.accounts.find((entry) => entry.id === accountId);
+    if (!account)
+        throw notFound('Account');
+    account.label = cleaned;
+    saveRegistry(dir, registry);
+}
+export function setDefault(dir, accountId) {
+    const account = find(dir, accountId);
+    const registry = loadRegistry(dir);
+    registry.defaults[account.provider] = account.id;
+    saveRegistry(dir, registry);
+    return account;
+}
+/** Drops the account from the registry, its pools, and the default. Its folder and secrets are the caller's to remove. */
+export function forgetAccount(dir, account) {
+    const registry = loadRegistry(dir);
+    registry.accounts = registry.accounts.filter((entry) => entry.id !== account.id);
+    if (registry.defaults[account.provider] === account.id) {
+        const next = registry.accounts.find((entry) => entry.provider === account.provider);
+        if (next)
+            registry.defaults[account.provider] = next.id;
+        else
+            delete registry.defaults[account.provider];
+    }
+    for (const pool of registry.pools)
+        pool.accountIds = pool.accountIds.filter((id) => id !== account.id);
+    saveRegistry(dir, registry);
+}
+export function savePool(dir, pool) {
+    const label = cleanLabel(pool.label);
+    const registry = loadRegistry(dir);
+    for (const id of pool.accountIds) {
+        const account = registry.accounts.find((entry) => entry.id === id);
+        if (!account)
+            throw notFound('Account');
+        if (account.provider !== PROVIDER)
+            throw invalid('A pool holds accounts of one provider.');
+    }
+    const next = { id: pool.id ? safeId(pool.id) : newId(), provider: PROVIDER, label, accountIds: [...pool.accountIds] };
+    registry.pools = [...registry.pools.filter((existing) => existing.id !== next.id), next];
+    saveRegistry(dir, registry);
+    return next;
+}
+export function removePool(dir, poolId) {
+    const registry = loadRegistry(dir);
+    registry.pools = registry.pools.filter((pool) => pool.id !== poolId);
+    saveRegistry(dir, registry);
+}

package/dist/sdk/agents/builtin.d.ts

@@ -0,0 +1,2 @@
+import type { ProfileDefinition } from "./profiles.js";
+export declare const BUILTIN_PROFILES: readonly ProfileDefinition[];

package/dist/sdk/agents/builtin.js

@@ -0,0 +1,50 @@
+import { PLAN_RESEARCH_PLUGINS } from "./planResearch.js";
+const RECALL = ['history_search', 'history_read', 'trajectory_search', 'trajectory_read', 'wiki_search', 'wiki_read', 'wiki_list', 'skill_load'];
+const PROGRESS = ['todo_write', 'session_name'];
+const WEB = ['web_search', 'web_fetch'];
+export const BUILTIN_PROFILES = [
+    {
+        name: 'worker',
+        description: 'Carries out a well-defined change: reads, edits and writes files and runs commands.',
+        color: 'green',
+        instructions: [
+            'You carry out one piece of work from your brief, end to end.',
+            '- Read the code you change first and follow the conventions you find.',
+            '- Keep a todo list with todo_write when the brief has more than one step, and name your session with session_name.',
+            '- Make the change, then check it: run the relevant tests, type checks or commands.',
+            '- Stay inside the brief. If something outside it blocks you, stop and say so instead of widening the change.',
+            '- Finish with a short report: what you changed (files), how you checked it, and anything left open.'
+        ].join('\n'),
+        tools: ['read', 'grep', 'find', 'ls', 'edit', 'write', 'bash', ...PROGRESS, ...RECALL, ...WEB],
+        plugins: null, variant: null, model: null, effort: null
+    },
+    {
+        name: 'explorer',
+        description: 'Finds and explains code, files and history without changing anything.',
+        color: 'cyan',
+        instructions: [
+            'You answer a question about the code, files or history in your brief. You never change anything.',
+            '- Search broadly first, then read the parts that matter.',
+            '- Keep a todo list with todo_write when the search has several parts, and name your session with session_name.',
+            '- Cite what you found as path:line.',
+            '- If the brief needs a tool you do not have (running tests or commands, editing), say so in your first line, then answer what you can by reading.',
+            '- Return conclusions, not file dumps: what you found, where, and how sure you are.'
+        ].join('\n'),
+        tools: ['read', 'grep', 'find', 'ls', ...PROGRESS, ...RECALL, ...WEB],
+        plugins: [...PLAN_RESEARCH_PLUGINS], variant: null, model: null, effort: null
+    },
+    {
+        name: 'researcher',
+        description: 'Researches code, history and public sources without changing anything.',
+        color: 'purple',
+        instructions: [
+            'You investigate the bounded research question in your brief and return concise, evidence-backed findings to the parent.',
+            '- Use read-only repository and public-web sources. Never modify files, run commands, call connected apps, or ask the user.',
+            '- Prefer primary sources. Cite repository claims as path:line and external claims with source URLs.',
+            '- If the brief needs a tool you do not have (running tests or commands, editing), say so in your first line, then answer what you can by reading.',
+            '- Separate observed facts from inference, state uncertainty, and return only findings relevant to the brief; do not implement.'
+        ].join('\n'),
+        tools: ['read', 'grep', 'find', 'ls', ...PROGRESS, ...RECALL, ...WEB],
+        plugins: [...PLAN_RESEARCH_PLUGINS], variant: null, model: null, effort: null
+    }
+];

package/dist/sdk/agents/narrow.d.ts

@@ -0,0 +1,13 @@
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { PluginDescriptor } from "../plugins/types.js";
+import type { AgentProfile } from "./profiles.js";
+export interface NarrowedCapabilities {
+    capabilities: CapabilitySet;
+    /** Tools the profile names that the parent does not have here. */
+    unavailable: string[];
+}
+/**
+ * The parent's set narrowed by the profile's tools and plugins and by the tools the spawn call
+ * asked for. A required plugin always stays; a tool whose plugin was dropped goes with it.
+ */
+export declare function narrowForProfile(parent: CapabilitySet, profile: Pick<AgentProfile, 'tools' | 'plugins'> | null, requested: readonly string[] | undefined, descriptors: readonly PluginDescriptor[]): NarrowedCapabilities;

package/dist/sdk/agents/narrow.js

@@ -0,0 +1,29 @@
+function pluginOf(id) {
+    return id.split('/')[0] ?? '';
+}
+/**
+ * The parent's set narrowed by the profile's tools and plugins and by the tools the spawn call
+ * asked for. A required plugin always stays; a tool whose plugin was dropped goes with it.
+ */
+export function narrowForProfile(parent, profile, requested, descriptors) {
+    let tools = parent.tools.filter((name) => !requested || requested.includes(name));
+    let contributions = parent.contributions;
+    const unavailable = profile?.tools?.filter((name) => !parent.tools.includes(name)) ?? [];
+    if (profile?.tools)
+        tools = tools.filter((name) => profile.tools.includes(name));
+    if (profile?.plugins) {
+        const allowed = new Set([...profile.plugins, ...descriptors.filter((descriptor) => descriptor.required).map((descriptor) => descriptor.id)]);
+        contributions = contributions.filter((id) => allowed.has(pluginOf(id)));
+        const owner = new Map();
+        for (const descriptor of descriptors)
+            for (const tool of descriptor.tools ?? [])
+                owner.set(tool.name, descriptor.id);
+        for (const id of parent.contributions) {
+            const [plugin, kind, name] = id.split('/');
+            if (kind === 'tool' && plugin && name)
+                owner.set(name, plugin);
+        }
+        tools = tools.filter((name) => !owner.has(name) || allowed.has(owner.get(name)));
+    }
+    return { capabilities: { ...parent, tools, contributions }, unavailable };
+}

package/dist/sdk/agents/planResearch.d.ts

@@ -0,0 +1,27 @@
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { PluginDescriptor } from "../plugins/types.js";
+import type { AgentProfile } from "./profiles.js";
+export declare const PLAN_RESEARCH_TOOLS: ReadonlySet<string>;
+export declare const PLAN_RESEARCH_PLUGINS: readonly string[];
+export declare const PLAN_RESEARCH_EVIDENCE_TOOLS: ReadonlySet<string>;
+/** Capability snapshot needed to tell whether a profile can research in this particular run. */
+export interface PlanResearchContext {
+    frozenTools: readonly string[];
+    contributions: readonly string[];
+    descriptors: readonly PluginDescriptor[];
+}
+export interface PlanResearchEligibility {
+    eligible: boolean;
+    refusal: string | null;
+    /** The exact safe child snapshot to launch when eligible. */
+    capabilities: CapabilitySet;
+    unavailableTools: string[];
+}
+/** Whether the profile's explicit allowlists are restricted to read-only research. */
+export declare function planResearchProfile(profile: Pick<AgentProfile, 'name' | 'tools' | 'plugins'> | null | undefined): boolean;
+/**
+ * Evaluate the same effective intersection used for launch, including tool ownership removed by
+ * profile plugin narrowing. An explicit request is a strict override; omission inherits the safe
+ * profile/parent intersection.
+ */
+export declare function planResearchEligibility(profile: Pick<AgentProfile, 'name' | 'tools' | 'plugins'> | null | undefined, context: PlanResearchContext, requested?: readonly string[]): PlanResearchEligibility;

package/dist/sdk/agents/planResearch.js

@@ -0,0 +1,82 @@
+import { narrowForProfile } from "./narrow.js";
+export const PLAN_RESEARCH_TOOLS = new Set([
+    'read', 'grep', 'find', 'ls', 'todo_write', 'session_name',
+    'history_search', 'history_read', 'trajectory_search', 'trajectory_read',
+    'wiki_entrypoint', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load',
+    'web_search', 'web_fetch'
+]);
+export const PLAN_RESEARCH_PLUGINS = ['history', 'variant', 'web', 'wiki'];
+export const PLAN_RESEARCH_EVIDENCE_TOOLS = new Set([
+    'read', 'grep', 'find', 'ls', 'history_search', 'trajectory_search', 'wiki_search', 'web_search', 'web_fetch'
+]);
+function profileRefusal(profile) {
+    if (!profile)
+        return 'Plan-mode delegation requires a named, eligible read-only research profile.';
+    if (!Array.isArray(profile.tools) || profile.tools.length === 0) {
+        return `Profile ${profile.name} must declare an explicit tools allowlist for plan-mode research.`;
+    }
+    const unsafeTools = profile.tools.filter(name => !PLAN_RESEARCH_TOOLS.has(name));
+    if (unsafeTools.length) {
+        return `Profile ${profile.name} includes non-research tools: ${[...new Set(unsafeTools)].join(', ')}. Use a profile whose tools are all plan research tools.`;
+    }
+    if (!profile.tools.some(name => PLAN_RESEARCH_EVIDENCE_TOOLS.has(name))) {
+        return `Profile ${profile.name} must allow at least one read-only research evidence tool.`;
+    }
+    if (!Array.isArray(profile.plugins)) {
+        return `Profile ${profile.name} must declare an explicit plugin allowlist for plan-mode research.`;
+    }
+    const unsafePlugins = profile.plugins.filter(name => !PLAN_RESEARCH_PLUGINS.includes(name));
+    if (unsafePlugins.length) {
+        return `Profile ${profile.name} includes non-research plugins: ${[...new Set(unsafePlugins)].join(', ')}. Use only the plan research plugins: ${PLAN_RESEARCH_PLUGINS.join(', ')}.`;
+    }
+    return null;
+}
+/** Whether the profile's explicit allowlists are restricted to read-only research. */
+export function planResearchProfile(profile) {
+    return profileRefusal(profile) === null;
+}
+/**
+ * Evaluate the same effective intersection used for launch, including tool ownership removed by
+ * profile plugin narrowing. An explicit request is a strict override; omission inherits the safe
+ * profile/parent intersection.
+ */
+export function planResearchEligibility(profile, context, requested) {
+    const empty = { version: 1, tools: [], connectors: [], contributions: [] };
+    const profileProblem = profileRefusal(profile);
+    if (profileProblem)
+        return { eligible: false, refusal: profileProblem, capabilities: empty, unavailableTools: [] };
+    const parent = {
+        version: 1,
+        tools: [...context.frozenTools],
+        connectors: [],
+        contributions: [...context.contributions]
+    };
+    const narrowed = narrowForProfile(parent, profile, requested, context.descriptors);
+    const capabilities = {
+        ...narrowed.capabilities,
+        tools: narrowed.capabilities.tools.filter(name => PLAN_RESEARCH_TOOLS.has(name)),
+        connectors: []
+    };
+    if (requested) {
+        const effective = new Set(capabilities.tools);
+        const incompatible = [...new Set(requested.filter(name => !PLAN_RESEARCH_TOOLS.has(name)
+                || !profile.tools.includes(name)
+                || !context.frozenTools.includes(name)
+                || !effective.has(name)))];
+        if (incompatible.length) {
+            return {
+                eligible: false,
+                refusal: `Plan-mode tools override contains incompatible tool(s): ${incompatible.join(', ')}. Omit \`tools\` to inherit the selected profile's safe research intersection, or retry with only tools allowed by that profile, available in this parent run, and in the plan research set.`,
+                capabilities,
+                unavailableTools: narrowed.unavailable
+            };
+        }
+    }
+    if (!capabilities.tools.some(name => PLAN_RESEARCH_EVIDENCE_TOOLS.has(name))) {
+        const refusal = requested
+            ? `The tools override [${requested.join(', ')}] leaves no available research evidence tool for profile ${profile.name}. Omit \`tools\` to inherit the safe intersection, or retry with an available evidence tool from this profile.`
+            : `Profile ${profile.name} has no read-only research evidence tool after intersecting its allowlists with this run's frozen capabilities and plugin contributions. Choose a profile with an available evidence tool.`;
+        return { eligible: false, refusal, capabilities, unavailableTools: narrowed.unavailable };
+    }
+    return { eligible: true, refusal: null, capabilities, unavailableTools: narrowed.unavailable };
+}