@xingular/harness 1.1.1 → 1.3.1-unstable.0

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

@@ -3,8 +3,8 @@ import { type Bus } from "../core/bus.js";
 import type { RunEvent, RunRecord } from "../sessions/contracts.js";
 import * as choices from "./choices.js";
 import * as env from "./env.js";
-import { type SecretStore } from "./secrets.js";
-import type { Account, AccountsOverview } from "./store.js";
+import { type CredentialLockOptions, type SecretStore } from "./secrets.js";
+import type { Account, AccountsOverview, Limit } from "./store.js";
 export type IssueCategory = 'auth_expired' | 'rate_limited' | 'quota' | 'network' | 'unknown';
 /** Best-effort classification of a provider error message. */
 export declare function classifyMessage(message: string): IssueCategory | null;
@@ -35,11 +35,13 @@ export interface AccountsOptions {
     dir: string;
     secrets: SecretStore;
     bus: Bus;
+    credentialLock?: CredentialLockOptions;
 }
 export declare class Accounts {
     readonly dir: string;
     private readonly secrets;
     private readonly bus;
+    private readonly credentialLockOptions;
     private readonly runtimes;
     private readonly logins;
     private readonly latestLogins;
@@ -48,6 +50,11 @@ export declare class Accounts {
     /** The credentials this process wrote to, or found in, each account's auth.json when its first terminal began. */
     private readonly terminalSnapshots;
     private installationDeviceIdPromise;
+    /**
+     * Lets the limits service observe each account runtime's provider responses. The Harness sets
+     * it once; with none, a runtime behaves exactly as before.
+     */
+    observeModels: ((models: unknown, accountId: string) => void) | null;
     constructor(options: AccountsOptions);
     private changed;
     overview(): AccountsOverview;
@@ -60,13 +67,17 @@ export declare class Accounts {
     resolve(accountId?: string | null, poolId?: string | null): Account;
     context(account: Account): env.AccountContext;
     readCredential(accountId: string, provider: string): Promise<Credential | null>;
+    private credentialLock;
     /** Stores a provider's credential, or removes it when `credential` is `null`. */
     writeCredential(accountId: string, provider: string, credential: Credential | null): Promise<void>;
+    /** The entire refresh read/modify/write is coordinated across services and processes. */
+    modifyCredential(accountId: string, provider: string, change: (current: Credential | undefined) => Promise<Credential | undefined>): Promise<Credential | undefined>;
+    private persistCredential;
     listCredentials(accountId: string): Promise<{
         providerId: string;
         type: 'api_key' | 'oauth';
     }[]>;
-    /** Pi's `CredentialStore` for one account. Writes are serialized, so a refresh never races another. */
+    /** Pi and explicit account edits share the same cross-process credential lock. */
     private credentialStore;
     /** Pi's OAuth device ID belongs to this Harness installation, not to one isolated account. */
     installationDeviceId(): Promise<string>;
@@ -160,6 +171,19 @@ export declare class Accounts {
     private releaseLease;
     /** Tracks account health and limits from run events. `run` is the event's run record, when it is known. */
     onRunEvent(event: RunEvent, run: RunRecord | null): void;
+    /**
+     * Records what a provider reported about its limits. An endpoint reading replaces that provider's
+     * limits; a header reading merges by id. Windows whose reset has passed are dropped. No credential
+     * is stored here.
+     */
+    applyLimits(accountId: string, readouts: readonly {
+        provider: string;
+        limits: Limit[];
+        source: 'headers' | 'provider' | 'estimate' | 'unavailable';
+        reason: string | null;
+        observedAt: string;
+        plan?: string | null;
+    }[]): AccountsOverview;
     private applyStatus;
 }
 export {};

package/dist/sdk/accounts/accounts.js

@@ -10,7 +10,7 @@ import { atomicWrite, now, readJson, safeId } from "../core/fs.js";
 import { loadPi } from "../pi/runtime.js";
 import * as choices from "./choices.js";
 import * as env from "./env.js";
-import { secretKey } from "./secrets.js";
+import { secretKey, withCredentialLock } from "./secrets.js";
 import * as store from "./store.js";
 /** Best-effort classification of a provider error message. */
 export function classifyMessage(message) {
@@ -64,6 +64,7 @@ export class Accounts {
     dir;
     secrets;
     bus;
+    credentialLockOptions;
     runtimes = new Map();
     logins = new Map();
     latestLogins = new Map();
@@ -72,10 +73,16 @@ export class Accounts {
     /** The credentials this process wrote to, or found in, each account's auth.json when its first terminal began. */
     terminalSnapshots = new Map();
     installationDeviceIdPromise = null;
+    /**
+     * Lets the limits service observe each account runtime's provider responses. The Harness sets
+     * it once; with none, a runtime behaves exactly as before.
+     */
+    observeModels = null;
     constructor(options) {
         this.dir = options.dir;
         this.secrets = options.secrets;
         this.bus = options.bus;
+        this.credentialLockOptions = options.credentialLock ?? {};
     }
     changed(payload = {}) {
         this.bus.emit({ type: 'accounts.changed', ...payload });
@@ -116,18 +123,40 @@ export class Accounts {
             return null;
         }
     }
+    credentialLock(key, work) {
+        return withCredentialLock(join(this.dir, '.credential-locks'), key, work, this.credentialLockOptions);
+    }
     /** Stores a provider's credential, or removes it when `credential` is `null`. */
     async writeCredential(accountId, provider, credential) {
         this.find(accountId);
         const name = validProvider(provider);
-        if (credential === null)
-            await this.secrets.delete(secretKey(accountId, `pi-auth/${name}`));
-        else
-            await this.secrets.set(secretKey(accountId, `pi-auth/${name}`), JSON.stringify(credential));
-        store.updateState(this.dir, accountId, (state) => {
-            state.piProviders = state.piProviders.filter((existing) => existing !== name);
-            if (credential !== null)
-                state.piProviders = [...state.piProviders, name].sort();
+        await this.credentialLock(`provider/${accountId}/${name}`, () => this.persistCredential(accountId, name, credential));
+    }
+    /** The entire refresh read/modify/write is coordinated across services and processes. */
+    async modifyCredential(accountId, provider, change) {
+        this.find(accountId);
+        const name = validProvider(provider);
+        return this.credentialLock(`provider/${accountId}/${name}`, async () => {
+            const current = (await this.readCredential(accountId, name)) ?? undefined;
+            const updated = await change(current);
+            if (updated !== undefined)
+                await this.persistCredential(accountId, name, updated);
+            return updated ?? current;
+        });
+    }
+    async persistCredential(accountId, name, credential) {
+        // Different providers still share the account's provider index. Keep its short commit serialized.
+        await this.credentialLock(`account/${accountId}`, async () => {
+            this.find(accountId);
+            if (credential === null)
+                await this.secrets.delete(secretKey(accountId, `pi-auth/${name}`));
+            else
+                await this.secrets.set(secretKey(accountId, `pi-auth/${name}`), JSON.stringify(credential));
+            store.updateState(this.dir, accountId, (state) => {
+                state.piProviders = state.piProviders.filter((existing) => existing !== name);
+                if (credential !== null)
+                    state.piProviders = [...state.piProviders, name].sort();
+            });
         });
     }
     async listCredentials(accountId) {
@@ -140,25 +169,13 @@ export class Accounts {
         }
         return listed;
     }
-    /** Pi's `CredentialStore` for one account. Writes are serialized, so a refresh never races another. */
+    /** Pi and explicit account edits share the same cross-process credential lock. */
     credentialStore(accountId) {
-        let chain = Promise.resolve();
-        const serialize = (work) => {
-            const next = chain.then(work);
-            chain = next.catch(() => undefined);
-            return next;
-        };
         return {
             read: async (providerId) => (await this.readCredential(accountId, providerId)) ?? undefined,
             list: () => this.listCredentials(accountId),
-            modify: (providerId, change) => serialize(async () => {
-                const current = (await this.readCredential(accountId, providerId)) ?? undefined;
-                const updated = await change(current);
-                if (updated !== undefined)
-                    await this.writeCredential(accountId, providerId, updated);
-                return updated ?? current;
-            }),
-            delete: (providerId) => serialize(() => this.writeCredential(accountId, providerId, null))
+            modify: (providerId, change) => this.modifyCredential(accountId, providerId, change),
+            delete: (providerId) => this.writeCredential(accountId, providerId, null)
         };
     }
     /** Pi's OAuth device ID belongs to this Harness installation, not to one isolated account. */
@@ -187,6 +204,14 @@ export class Accounts {
             const configDir = 'configDir' in account ? account.configDir : env.ensureHome(this.dir, account);
             runtime = loadPi()
                 .then(({ ModelRuntime }) => ModelRuntime.create({ credentials: this.credentialStore(id), modelsPath: join(configDir, 'models.json') }))
+                .then((created) => {
+                // Reading provider responses never changes what a request does; a broken observer is ignored.
+                try {
+                    this.observeModels?.(created, id);
+                }
+                catch { /* observation is best effort */ }
+                return created;
+            })
                 .catch((error) => {
                 this.runtimes.delete(id);
                 throw error;
@@ -690,6 +715,35 @@ export class Accounts {
                 this.changed({ accountId, health: state.health, previous });
         }
     }
+    /**
+     * Records what a provider reported about its limits. An endpoint reading replaces that provider's
+     * limits; a header reading merges by id. Windows whose reset has passed are dropped. No credential
+     * is stored here.
+     */
+    applyLimits(accountId, readouts) {
+        this.find(accountId);
+        const expired = (limit) => {
+            const time = limit.resetsAt ? Date.parse(limit.resetsAt) : Number.NaN;
+            return !Number.isNaN(time) && time <= Date.now();
+        };
+        store.updateState(this.dir, accountId, (state) => {
+            for (const readout of readouts) {
+                // An endpoint read is the provider's whole answer; a header read only adds what it saw.
+                const kept = new Map((readout.source === 'provider' ? [] : state.limits.filter((limit) => limit.provider === readout.provider && !expired(limit)))
+                    .map((limit) => [limit.id, limit]));
+                for (const limit of readout.limits)
+                    kept.set(limit.id, limit);
+                state.limits = [...state.limits.filter((limit) => limit.provider !== readout.provider), ...kept.values()];
+                const entry = { provider: readout.provider, source: readout.source, reason: readout.reason, observedAt: readout.observedAt };
+                state.providerLimits = [...state.providerLimits.filter((existing) => existing.provider !== readout.provider), entry];
+                if (readout.plan)
+                    state.plan = readout.plan;
+            }
+            state.limits.sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+        });
+        this.changed({ accountId });
+        return this.overview();
+    }
     applyStatus(event) {
         const payload = event.payload;
         if (typeof payload.accountId !== 'string')

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

@@ -3,6 +3,18 @@ export interface SecretStore {
     set(key: string, value: string): Promise<void>;
     delete(key: string): Promise<void>;
 }
+export interface CredentialLockOptions {
+    /** Acquisition only; an acquired callback is never unlocked while still running. */
+    timeoutMs?: number;
+    pollMs?: number;
+}
+/**
+ * Cross-process Lamport bakery lock. Unique participant directories make dead-pid reclamation
+ * safe: a stale cleanup can never unlink a successor's lock. No age-based stealing of live refreshes.
+ * The directory contains only hashed keys, pids, random IDs and tickets, never credential contents.
+ * All processes sharing a backend must use the same coordination directory on a local filesystem.
+ */
+export declare function withCredentialLock<T>(dir: string, key: string, work: () => Promise<T>, options?: CredentialLockOptions): Promise<T>;
 /** `<account id>/<secret name>`: the key an account's secret is stored under. */
 export declare const secretKey: (accountId: string, name: string) => string;
 /** Secrets held only for the life of the process. For tests and throwaway runs. */

package/dist/sdk/accounts/secrets.js

@@ -1,8 +1,115 @@
 // Where credentials live. The harness never writes a secret to its own files: it asks the
 // store the embedding application provides (a Keychain, an encrypted vault), by key.
-import { chmodSync, mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { atomicWrite, readJsonOr } from "../core/fs.js";
+import { chmodSync, closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { readJsonOr } from "../core/fs.js";
+/** Exclusive temporary files are private before the first byte is written, not just after rename. */
+function privateWrite(path, value) {
+    const temporary = join(dirname(path), `.credential-${randomUUID()}.tmp`);
+    try {
+        const fd = openSync(temporary, 'wx', 0o600);
+        try {
+            writeFileSync(fd, value);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temporary, path);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/**
+ * Cross-process Lamport bakery lock. Unique participant directories make dead-pid reclamation
+ * safe: a stale cleanup can never unlink a successor's lock. No age-based stealing of live refreshes.
+ * The directory contains only hashed keys, pids, random IDs and tickets, never credential contents.
+ * All processes sharing a backend must use the same coordination directory on a local filesystem.
+ */
+export async function withCredentialLock(dir, key, work, options = {}) {
+    const timeout = options.timeoutMs ?? 30_000;
+    const poll = options.pollMs ?? 20;
+    if (!Number.isFinite(timeout) || timeout < 0 || timeout > 300_000 || !Number.isFinite(poll) || poll < 1 || poll > 1000) {
+        throw new Error('Invalid credential lock wait bounds.');
+    }
+    const started = performance.now();
+    const folder = join(dir, createHash('sha256').update(key).digest('hex'));
+    mkdirSync(folder, { recursive: true, mode: 0o700 });
+    if (!lstatSync(dir).isDirectory() || !lstatSync(folder).isDirectory())
+        throw new Error('Invalid credential lock directory.');
+    chmodSync(dir, 0o700);
+    chmodSync(folder, 0o700);
+    const id = `${process.pid}-${randomUUID()}`;
+    const own = join(folder, id);
+    mkdirSync(own, { mode: 0o700 });
+    const participants = () => {
+        const entries = [];
+        for (const name of readdirSync(folder)) {
+            if (!/^\d+-[0-9a-f-]{36}$/.test(name))
+                throw new Error('Invalid credential lock metadata.');
+            const pid = Number(name.slice(0, name.indexOf('-')));
+            if (!Number.isSafeInteger(pid) || pid <= 0)
+                throw new Error('Invalid credential lock metadata.');
+            let alive = true;
+            try {
+                process.kill(pid, 0);
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    alive = false;
+            }
+            const participant = join(folder, name);
+            if (!alive) {
+                rmSync(participant, { recursive: true, force: true });
+                continue;
+            }
+            try {
+                // The absent ticket is the bakery algorithm's choosing flag.
+                const text = readFileSync(join(participant, 'ticket'), 'utf8');
+                const ticket = Number(text);
+                if (!Number.isSafeInteger(ticket) || ticket <= 0)
+                    throw new Error('Invalid credential lock metadata.');
+                entries.push({ id: name, ticket });
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                if (lstatExists(participant))
+                    entries.push({ id: name, ticket: null });
+            }
+        }
+        return entries;
+    };
+    try {
+        const ticket = Math.max(0, ...participants().map(entry => entry.ticket ?? 0)) + 1;
+        privateWrite(join(own, 'ticket'), String(ticket));
+        for (;;) {
+            const blocked = participants().some(entry => entry.id !== id && (entry.ticket === null || entry.ticket < ticket || (entry.ticket === ticket && entry.id < id)));
+            if (!blocked)
+                return await work();
+            if (performance.now() - started >= timeout)
+                throw new Error('Timed out waiting for credential modification; no credentials were changed.');
+            await new Promise(resolve => setTimeout(resolve, Math.min(poll, Math.max(1, timeout - (performance.now() - started)))));
+        }
+    }
+    finally {
+        rmSync(own, { recursive: true, force: true });
+    }
+}
+function lstatExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
 /** `<account id>/<secret name>`: the key an account's secret is stored under. */
 export const secretKey = (accountId, name) => `${accountId}/${name}`;
 /** Secrets held only for the life of the process. For tests and throwaway runs. */
@@ -23,18 +130,18 @@ export function fileSecretStore(path) {
     const read = () => readJsonOr(path, {});
     const write = (values) => {
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        atomicWrite(path, `${JSON.stringify(values, null, 2)}\n`);
+        privateWrite(path, `${JSON.stringify(values, null, 2)}\n`);
         chmodSync(path, 0o600);
     };
     return {
         get: async (key) => read()[key] ?? null,
-        set: async (key, value) => write({ ...read(), [key]: value }),
-        delete: async (key) => {
+        set: (key, value) => withCredentialLock(`${path}.locks`, 'file', async () => write({ ...read(), [key]: value })),
+        delete: (key) => withCredentialLock(`${path}.locks`, 'file', async () => {
             const values = read();
             if (key in values) {
                 delete values[key];
                 write(values);
             }
-        }
+        })
     };
 }

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

@@ -25,10 +25,33 @@ 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`, or `rejected` when the provider reports it. */
+    /** `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`. */
@@ -45,6 +68,8 @@ export interface AccountState {
     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;

package/dist/sdk/accounts/store.js

@@ -18,7 +18,7 @@ import { appendLine, newId, now, readJsonOr, safeId, writeJson } from "../core/f
 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: [], lastError: null, lastCheckedAt: null, cliVersion: null, capabilities: [], piProviders: [] });
+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');

package/dist/sdk/agents/builtin.js

@@ -1,5 +1,6 @@
+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 = ['checklist_write', 'session_name'];
+const PROGRESS = ['todo_write', 'session_name'];
 const WEB = ['web_search', 'web_fetch'];
 export const BUILTIN_PROFILES = [
     {
@@ -9,7 +10,7 @@ export const BUILTIN_PROFILES = [
         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 checklist with checklist_write when the brief has more than one step, and name your session with session_name.',
+            '- 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.'
@@ -24,11 +25,24 @@ export const BUILTIN_PROFILES = [
         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 checklist with checklist_write when the search has several parts, and name your session with session_name.',
+            '- 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.',
             '- 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: null, variant: null, model: null, effort: null
+        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.',
+            '- 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/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 };
+}

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

@@ -1,5 +1,8 @@
 import { type Effort } from "../core/effort.js";
+import { type PlanResearchContext } from "./planResearch.js";
 export declare const PROFILE_NAME: RegExp;
+/** Names a profile cannot take: `main` is how rosters show the agent a person talks to. */
+export declare const RESERVED_PROFILE_NAMES: readonly string[];
 export declare const PROFILE_COLORS: readonly ["blue", "green", "yellow", "red", "magenta", "cyan", "orange", "purple"];
 export type ProfileColor = (typeof PROFILE_COLORS)[number];
 export type ProfileSource = 'builtin' | 'global' | 'project' | 'variant';
@@ -71,10 +74,11 @@ export declare function removeProfile(root: string, cwd: string | null | undefin
 /** Where the profile list sits among the prompt sections: the slot a variant's subagents used. */
 export declare const PROFILE_SECTION_ORDER = 64;
 /** The prompt section that lists the profiles a run can start subagents from. */
-export declare function profileSection(root: string, cwd: string | null | undefined, variantDir?: string | null): {
+export declare function profileSection(root: string, cwd: string | null | undefined, variantDir?: string | null, planResearchOnly?: boolean, researchContext?: PlanResearchContext): {
     id: string;
     title: string;
     body: string;
     budget: number;
     order: number;
+    dynamic: true;
 };