@xingular/harness 1.3.1-unstable.2 → 1.3.1-unstable.3

package/dist/sdk/prompt/compile.js

@@ -11,6 +11,7 @@ import { join } from 'node:path';
 import { isSession, projectOf } from "../core/caller.js";
 import { isDir, now, readJson, safeId, writeJson } from "../core/fs.js";
 import { charCount, compareText, lines, takeChars } from "../core/text.js";
+import { readSkillFile } from "../tools/defaultSkills.js";
 import * as notes from "../wiki/notes.js";
 import { isWorldTool, WORLD_GUIDANCE } from "../world/untrusted.js";
 import { TODO_GUIDANCE, TODO_WRITE, describeTodo } from "../tools/todo.js";
@@ -22,12 +23,14 @@ const WIKI_BUDGET = 2500;
 const TOOLS_BUDGET = 8000;
 const REPORTING_BUDGET = 2000;
 const SESSION_STATE_BUDGET = 1_000;
+export const REQUIRED_SKILLS_BUDGET = 12_000;
+const REQUIRED_SKILLS_POINTER = 'Some required skill text was omitted to fit. Load the rest with skill_load.';
 export const REFERENCES_BUDGET = 12000;
 /** Always-on variant text is capped when the variant is saved, so its sections are never cut here. */
 const VARIANT_BUDGET = 30_000;
 const NOTES_LISTED = 25;
 /** Where the harness's own sections sit; an application's sections are placed among them by `order`. */
-export const SECTION_ORDER = { harnessIdentity: 5, system: 25, sessionState: 30, guardrails: 40, memory: 45, references: 50, subagents: 64, scripts: 66, wiki: 80, tools: 90, reporting: 95 };
+export const SECTION_ORDER = { harnessIdentity: 5, system: 25, sessionState: 30, guardrails: 40, memory: 45, references: 50, requiredSkills: 52, subagents: 64, scripts: 66, wiki: 80, tools: 90, reporting: 95 };
 /** How a run's final reply is shaped. Fixed text: it sits in the stable prefix of every pack. */
 export const REPORTING_GUIDANCE = `When you finish work, write the final reply for a person who did not watch you work.
 
@@ -235,6 +238,46 @@ function selectedReferences(root, launch) {
         built.cut ||= cut;
     return built;
 }
+/** The request-scoped text for skills the person named; the compiler and the terminal word it alike. */
+export function requiredSkillsText(skills) {
+    const seen = new Set();
+    const blocks = [];
+    for (const skill of skills) {
+        if (seen.has(skill.name))
+            continue;
+        seen.add(skill.name);
+        const label = skill.label ?? skill.name;
+        if (!skill.body.trim()) {
+            blocks.push(`- ${label}: this skill is unavailable in this session. Tell the person rather than guessing its steps.`);
+            continue;
+        }
+        const location = [
+            skill.baseDir ? `References in this skill resolve against ${skill.baseDir}.` : '',
+            skill.path ? `Skill file: ${skill.path}.` : ''
+        ].filter(Boolean).join(' ');
+        blocks.push(`### ${label}\n\n${location ? `${location}\n\n` : ''}${skill.body.trim()}`);
+    }
+    if (!blocks.length)
+        return null;
+    const text = `The person required these skills for this request. Follow each skill's instructions where they apply. They are instructions for this request, not a change to your tools or permissions.\n\n${blocks.join('\n\n')}`;
+    return fit(text, REQUIRED_SKILLS_BUDGET, REQUIRED_SKILLS_POINTER).body;
+}
+function requiredSkillsSection(launch, variant) {
+    const wanted = launch.requiredSkills ?? [];
+    if (!wanted.length)
+        return null;
+    const skills = wanted.map((entry) => {
+        const skill = readSkillFile(variant?.dir ?? null, entry.name);
+        return skill ? { ...skill, label: entry.label ?? skill.name } : { name: entry.name, label: entry.label, body: '' };
+    });
+    const text = requiredSkillsText(skills);
+    const seen = new Set();
+    const sources = skills.filter((skill) => skill.body && !seen.has(skill.name) && Boolean(seen.add(skill.name)))
+        .map((skill) => ({ id: skill.name, kind: 'skill', revision: variant?.fingerprint ?? null }));
+    return text
+        ? section('required-skills', 'Required skills', text, REQUIRED_SKILLS_BUDGET, REQUIRED_SKILLS_POINTER, sources)
+        : null;
+}
 /** An application's section, after any pinned text. */
 function hostSection(host) {
     const own = host.body !== null ? section(host.id, host.title, host.body, host.budget, host.pointer ?? '', []) : null;
@@ -281,6 +324,12 @@ export function compile(env, context, launch = {}, variant = null) {
     const { root } = env;
     const groups = toolGroups(context, launch, root);
     const variantSource = variant ? [{ id: variant.scope ?? variant.dir, kind: 'variant', revision: variant.fingerprint }] : [];
+    const toolSection = launch.hideToolGuidance ? null : tools(groups, variant?.toolGuidance ?? '', launch.toolsPointer ?? '');
+    // The tools section ends with the variant's tool guidance: record how much of it is the variant's.
+    if (toolSection && variant?.toolGuidance.trim() && !toolSection.cut) {
+        const block = `### How to use your tools\n\n${variant.toolGuidance.trim()}\n`;
+        toolSection.sources = [{ ...variantSource[0], chars: Math.min(block.length, toolSection.size) }];
+    }
     const built = [
         {
             order: SECTION_ORDER.harnessIdentity,
@@ -289,8 +338,9 @@ export function compile(env, context, launch = {}, variant = null) {
         ...(variant?.sections ?? []).map((entry) => ({ order: entry.order, section: section(entry.id, entry.title, entry.body, VARIANT_BUDGET, '', variantSource) })),
         { order: SECTION_ORDER.sessionState, section: sessionStateSection(launch.sessionState, launch.tools ?? []) },
         { order: SECTION_ORDER.references, section: selectedReferences(root, launch) },
+        { order: SECTION_ORDER.requiredSkills, section: requiredSkillsSection(launch, variant) },
         { order: SECTION_ORDER.wiki, section: wiki(root, context) },
-        { order: SECTION_ORDER.tools, section: launch.hideToolGuidance ? null : tools(groups, variant?.toolGuidance ?? '', launch.toolsPointer ?? '') },
+        { order: SECTION_ORDER.tools, section: toolSection },
         { order: SECTION_ORDER.reporting, section: section('reporting', 'Reporting your work', REPORTING_GUIDANCE, REPORTING_BUDGET, '', []) },
         ...(launch.standard ? standardSections({ ...launch.standard, project: launch.standard.project ?? projectName(root, context) }, launch.tools ?? []).filter((own) => !(launch.sections ?? []).some((host) => host.id === own.id)) : []).map((own) => ({ order: own.order, section: hostSection(own) })),
         ...(launch.sections ?? []).filter((host) => host.id !== 'session-state').map((host) => ({ order: host.order, section: hostSection(host) }))
@@ -306,17 +356,22 @@ export function compile(env, context, launch = {}, variant = null) {
         compiledAt: now()
     };
 }
-/** The pack as the one string a session receives. */
-export function render(env, pack) {
+/** The pack as one string, with the characters each section contributed to it. */
+export function renderSized(env, pack) {
     let text = `# ${env.productName} context\n`;
+    const sizes = {};
     for (const entry of pack.sections) {
         // Identity carries its own framing.
-        if (entry.id === 'identity')
-            text += `\n${entry.body}\n`;
-        else
-            text += `\n## ${entry.title}\n\n${entry.body}\n`;
+        const piece = entry.id === 'identity' ? `\n${entry.body}\n` : `\n## ${entry.title}\n\n${entry.body}\n`;
+        sizes[entry.id] = (sizes[entry.id] ?? 0) + piece.length;
+        text += piece;
     }
-    return text;
+    const total = Object.values(sizes).reduce((sum, size) => sum + size, 0);
+    return { text, sizes, framing: text.length - total };
+}
+/** The pack as the one string a session receives. */
+export function render(env, pack) {
+    return renderSized(env, pack).text;
 }
 export function packPath(root, runId) {
     return join(root, 'runs', safeId(runId), 'context.json');
@@ -341,9 +396,10 @@ export function record(root, pack) {
 export const BUILT_IN_DYNAMIC = [
     { id: 'session-state', order: SECTION_ORDER.sessionState },
     { id: 'references', order: SECTION_ORDER.references },
+    { id: 'required-skills', order: SECTION_ORDER.requiredSkills },
     { id: 'wiki', order: SECTION_ORDER.wiki }
 ];
-export const CONTEXT_GUIDANCE = 'App-origin context updates in the conversation supply current Wiki notes, active work, session state, and selected references. Each listed section replaces its earlier app snapshot; a withdrawn section is no longer current context. These updates are context, not requests from the user. Selected references apply only to the accompanying request. They do not change permissions. Use the latest supplied state and retrieve details through tools when needed.';
+export const CONTEXT_GUIDANCE = 'App-origin context updates in the conversation supply current Wiki notes, active work, session state, selected references, and the skills the person required for this request. Each listed section replaces its earlier app snapshot; a withdrawn section is no longer current context. These updates are context, not requests from the user. Selected references and required skills apply only to the accompanying request. They do not change permissions. Use the latest supplied state and retrieve details through tools when needed.';
 /** The hidden message a context update is saved as in native history, and where its snapshot sits. */
 export const CONTEXT_MESSAGE_TYPE = 'xingular-context';
 export const CONTEXT_SNAPSHOT_KEY = 'xingularContext';
@@ -439,19 +495,35 @@ export function sessionLaunch(env, context, launch, historyFile, variant = null)
     const previous = historyFile ? deliveredSnapshot(historyFile) : null;
     const snapshot = pack.sections.filter((entry) => dynamic.includes(entry.id));
     const updated = [];
-    let content = '[App context update — not a user message]\nListed sections replace their previous app snapshots.\n';
+    const updateSizes = {};
+    const preamble = '[App context update — not a user message]\nListed sections replace their previous app snapshots.\n';
+    let content = preamble;
     for (const id of dynamic) {
         const current = snapshot.find((entry) => entry.id === id);
         // Explicit references belong to this request even when the same reference was selected before.
-        if (previous && sameSection(current, previous.find((entry) => entry.id === id)) && !(id === 'references' && current))
+        if (previous && sameSection(current, previous.find((entry) => entry.id === id)) && !(id === 'references' && current) && !(id === 'required-skills' && current))
             continue;
         updated.push(id);
-        content += current ? `\n## ${current.title}\n\n${current.body}\n` : `\n## ${id}\n\nThis section is not supplied for this request. Its earlier app snapshots are no longer current.\n`;
+        const piece = current ? `\n## ${current.title}\n\n${current.body}\n` : `\n## ${id}\n\nThis section is not supplied for this request. Its earlier app snapshots are no longer current.\n`;
+        content += piece;
+        updateSizes[id] = piece.length;
     }
     const stable = pack.sections.filter((entry) => !dynamic.includes(entry.id));
-    pack.delivery = { systemSectionIds: stable.map((entry) => entry.id), updatedSectionIds: updated };
+    const rendered = renderSized(env, { sections: stable });
+    const system = `${rendered.text}\n## Context updates\n\n${CONTEXT_GUIDANCE}\n`;
+    const total = (sizes) => Object.values(sizes).reduce((sum, size) => sum + size, 0);
+    pack.delivery = {
+        systemSectionIds: stable.map((entry) => entry.id),
+        updatedSectionIds: updated,
+        sizes: {
+            system: rendered.sizes,
+            update: updated.length ? updateSizes : {},
+            systemFraming: system.length - total(rendered.sizes),
+            updateFraming: updated.length ? content.length - total(updateSizes) : 0
+        }
+    };
     record(env.root, pack);
-    return { system: `${render(env, { sections: stable })}\n## Context updates\n\n${CONTEXT_GUIDANCE}\n`, update: updated.length ? { content, snapshot } : null, pack };
+    return { system, update: updated.length ? { content, snapshot } : null, pack };
 }
 // ---- Sessions that keep the instructions they started with ---------------------------------
 /** A terminal session keeps the pack it started with; each of its runs records a copy. */

package/dist/sdk/server/methods.js

@@ -12,6 +12,7 @@ import * as plugins from "../plugins/api.js";
 import { BUILTIN_PLUGIN_REGISTRY } from "../plugins/builtin.js";
 import * as install from "../plugins/install.js";
 import * as proposals from "../plugins/proposals.js";
+import { attribution } from "../context/attribution.js";
 import { compile, load, render } from "../prompt/compile.js";
 import { continuationOf } from "../sessions/continuation.js";
 import * as control from "../sessions/control.js";
@@ -200,6 +201,8 @@ export function methods(harness) {
             return params.render ? { pack, text: render(env, pack) } : pack;
         },
         'context.runPack': (params) => load(root(), text(params, 'runId')),
+        // What the request was made of: one row per contributor, reconciled to the provider's figure.
+        'context.attribution': (params) => attribution(env, text(params, 'runId')),
         // ---- Plugins: everything that shapes a session, and the trust a working folder's code needs ---
         // A host that is not a Node program describes its own parts here instead of in the options.
         'plugins.describe': (params) => {

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

@@ -271,6 +271,10 @@ export declare const runEventPayloadSchemas: {
             description: z.ZodString;
             parameters: z.ZodUnknown;
         }, z.core.$strip>>;
+        compaction: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            reserveTokens: z.ZodNumber;
+        }, z.core.$strip>>;
         systemPromptTruncated: z.ZodOptional<z.ZodBoolean>;
         contextUpdateTruncated: z.ZodOptional<z.ZodBoolean>;
         toolsTruncated: z.ZodOptional<z.ZodBoolean>;

package/dist/sdk/sessions/contracts.js

@@ -42,6 +42,8 @@ const contextSnapshotPayload = z.object({
     systemPrompt: z.string().max(100_000),
     contextUpdate: z.string().max(100_000).optional(),
     tools: z.array(z.object({ name: z.string(), description: z.string().max(2_000), parameters: z.unknown() })).max(120),
+    /** The headroom Pi held the run to when it measured compaction, as the session's own settings give it. */
+    compaction: z.object({ enabled: z.boolean(), reserveTokens: z.number().nonnegative() }).optional(),
     systemPromptTruncated: z.boolean().optional(),
     contextUpdateTruncated: z.boolean().optional(),
     toolsTruncated: z.boolean().optional()

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

@@ -170,6 +170,16 @@ export interface PiSessionLike {
         description?: string;
         parameters?: unknown;
     }>;
+    /** Pi's compaction settings, so the run records the headroom it was held to. */
+    settingsManager?: {
+        getCompactionSettings(model?: {
+            provider: string;
+            id: string;
+        }): {
+            enabled: boolean;
+            reserveTokens: number;
+        };
+    };
     subscribe(listener: (event: PiEvent) => void): () => void;
     prompt(text: string, options?: {
         images?: unknown[];

package/dist/sdk/sessions/runner.js

@@ -129,6 +129,21 @@ function contextToolSpecs(session) {
     });
     return { tools: tools.map((entry) => entry.spec), truncated: source.length > MAX_TOOL_SPECS || tools.some((entry) => entry.truncated) };
 }
+/** Pi's compaction settings for this session's model, when the session exposes them. */
+function compactionSettings(session) {
+    const manager = session.settingsManager;
+    if (!manager?.getCompactionSettings)
+        return null;
+    try {
+        const model = session.model?.id && session.model.provider ? { provider: session.model.provider, id: session.model.id } : undefined;
+        const settings = manager.getCompactionSettings(model);
+        return { enabled: settings.enabled === true, reserveTokens: Math.max(0, Math.round(settings.reserveTokens || 0)) };
+    }
+    catch {
+        // A model Pi cannot resolve keeps the reserve unknown rather than guessed.
+        return null;
+    }
+}
 const numberField = (event, key, fallback = 0) => (typeof event[key] === 'number' && Number.isFinite(event[key]) ? event[key] : fallback);
 const stringField = (event, key, fallback = '') => (typeof event[key] === 'string' ? event[key] : fallback);
 const lastLine = (text) => {
@@ -183,10 +198,12 @@ export async function runTurn(run, session, params) {
     const systemPrompt = limitedText(session.systemPrompt ?? params.system, MAX_SYSTEM_PROMPT_CHARS);
     const contextUpdate = limitedText(params.update?.content ?? '', MAX_SYSTEM_PROMPT_CHARS);
     const toolSpecs = contextToolSpecs(session);
+    const compaction = compactionSettings(session);
     run.emit('context.snapshot', {
         systemPrompt: systemPrompt.text,
         ...(contextUpdate.text ? { contextUpdate: contextUpdate.text } : {}),
         tools: toolSpecs.tools,
+        ...(compaction ? { compaction } : {}),
         ...(systemPrompt.truncated ? { systemPromptTruncated: true } : {}),
         ...(contextUpdate.truncated ? { contextUpdateTruncated: true } : {}),
         ...(toolSpecs.truncated ? { toolsTruncated: true } : {})

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

@@ -5,7 +5,7 @@ import type { RunRegistry } from "./registry.js";
 import type { Effort } from "./runner.js";
 import type { SessionRunInput } from "./sessions.js";
 import type { PluginDescriptor } from "../plugins/types.js";
-import { type SubagentInput, type SubagentReceipt, type SubagentResult, type SubagentSelection } from "./subagents.js";
+import { type SubagentInput, type SubagentQuota, type SubagentReceipt, type SubagentResult, type SubagentSelection } from "./subagents.js";
 type Started = {
     runId: string;
     nativeSessionId: string | null;
@@ -35,11 +35,15 @@ export declare class Subagents {
     private readonly launch;
     private readonly options;
     private readonly parents;
+    /** Child runs reserved synchronously at spawn, before their record exists, so parallel calls cannot overspend. */
+    private readonly reserved;
     private readonly runtimeSettingsByRun;
     constructor(env: HarnessEnv, runs: RunRegistry, launch: (input: SessionRunInput) => Promise<Started>, options?: SubagentServiceOptions);
     /** Internal adapter contract: context comes from a live run, never from model arguments. */
     register(input: SessionRunInput, accountId: string, capabilities: CapabilitySet, deferUntilPrompt?: boolean): void;
     runtimeSettings(runId: string): SubagentRuntimeSettings | null;
+    /** The budget for a run, or the foundation defaults when it has not registered one. */
+    quota(runId: string): SubagentQuota;
     private rememberRuntimeSettings;
     resolvedModel(runId: string, model: string, effort?: Effort): void;
     private parent;
@@ -51,6 +55,12 @@ export declare class Subagents {
     private launchChild;
     /** The children this parent may read or continue: its own, and those recovered from its history. */
     private owned;
+    /** The run and the runs it was continued from, so a work-slice continuation keeps the budget. */
+    private ancestry;
+    /** Distinct child conversations this run has started, plus slots reserved before their record exists. */
+    private usage;
+    private reserve;
+    private release;
     /** The newest run in a continued child's chain, among the runs this parent owns. */
     private latestLink;
     /** The first run of a chain: its folder holds the child's history for every later link. */

package/dist/sdk/sessions/subagentService.js

@@ -10,7 +10,7 @@ import { planResearchEligibility } from "../agents/planResearch.js";
 import { resolveProfile } from "../agents/profiles.js";
 import { continuationOf } from "./continuation.js";
 import { findRun, loadRun, readEvents, recordedSubagents, recordSubagent, saveRun } from "./runStore.js";
-import { SPAWN_SUBAGENT, SUBAGENT_RELATION, SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, briefTitle, continueHint, subagentHistory, subagentTitle } from "./subagents.js";
+import { SPAWN_SUBAGENT, SUBAGENT_RELATION, SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, UNPROFILED_SUBAGENT, briefTitle, continueHint, subagentHistory, subagentProfileKey, subagentProfileLimit, subagentQuota, subagentTitle } from "./subagents.js";
 function until(promise, signal) {
     if (signal.aborted) {
         void promise.catch(() => { });
@@ -29,6 +29,8 @@ export class Subagents {
     launch;
     options;
     parents = new Map();
+    /** Child runs reserved synchronously at spawn, before their record exists, so parallel calls cannot overspend. */
+    reserved = new Map();
     runtimeSettingsByRun = new Map();
     constructor(env, runs, launch, options = {}) {
         this.env = env;
@@ -72,6 +74,10 @@ export class Subagents {
     runtimeSettings(runId) {
         return this.runtimeSettingsByRun.get(runId) ?? null;
     }
+    /** The budget for a run, or the foundation defaults when it has not registered one. */
+    quota(runId) {
+        return subagentQuota(this.parents.get(runId)?.input.subagents ?? undefined);
+    }
     rememberRuntimeSettings(runId, settings) {
         this.runtimeSettingsByRun.set(runId, settings);
         if (this.runtimeSettingsByRun.size > 500) {
@@ -174,44 +180,63 @@ export class Subagents {
                     throw invalid(`There is no agent profile named ${request.agent.trim()}.`);
             }
         }
-        await until(parent.ready, parent.stopped.signal);
-        let variant = input.variant ?? null;
-        let launch = input.launch;
-        let model = input.model;
-        let effort = input.effort;
-        if (profile) {
-            // A variant's own subagent works from its definition alone; a profile keeps the parent's
-            // variant unless it names another one, or none.
-            if (profile.source === 'variant' || profile.variant === 'none')
-                variant = null;
-            else if (profile.variant)
-                variant = { scope: profile.variant.scope, version: profile.variant.version };
-            if (profile.model)
-                model = profile.model;
-            if (profile.effort)
-                effort = profile.effort;
-            launch = { ...(input.launch ?? {}), sections: [...(input.launch?.sections ?? []).filter((section) => section.id !== 'subagent'), { id: 'subagent', title: `Your role: ${profile.name}`, body: profile.instructions || profile.description, budget: 16_000, order: 22 }] };
-        }
-        const narrowed = input.plan
-            ? { capabilities: planEligibility.capabilities, unavailable: planEligibility.unavailableTools }
-            : narrowForProfile(capabilities, profile, request.tools, this.options.descriptors?.() ?? []);
-        const childCapabilities = narrowed.capabilities;
-        const tools = childCapabilities.tools;
+        const quota = subagentQuota(input.subagents ?? undefined);
         const runId = randomUUID();
-        const sessionId = randomUUID();
-        const child = {
-            ...input,
-            run: { ...input.run, ...(input.plan ? { worktreeId: null } : {}), id: runId, sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, goal: takeChars(brief, 4000), title, attachmentCount: 0, resumedFromRunId: null, handoffId: null, profile: profile?.name ?? null },
-            accountId, poolId: null, sessionDir: join(input.sessionDir, 'subagents', runId), resume: null,
-            text: brief, images: undefined, requiresImageInput: false, preamble: null,
-            caller: { ...input.caller, runId: undefined, sessionId },
-            tools: { allow: tools, gated: (input.tools.gated ?? []).filter((name) => tools.includes(name)) },
-            capabilities: childCapabilities, depth: (input.depth ?? 0) + 1,
-            variant, launch, model, effort,
-            ...(input.plan ? { connections: false, subagents: null } : {})
-        };
-        const result = await this.launchChild(parent, request, child);
-        return { ...result, ...(profile ? { agent: profile.name } : {}), ...(narrowed.unavailable.length ? { unavailableTools: narrowed.unavailable } : {}) };
+        const usage = this.usage(request.parentRunId);
+        const slot = (count, of = '') => `${count} ${of}subagent slot${count === 1 ? '' : 's'}`;
+        if (usage.total >= quota.children)
+            throw invalid(`This run has used its ${slot(quota.children)}. Do the remaining work yourself.`);
+        const profileKey = subagentProfileKey(profile?.name);
+        const profileLimit = subagentProfileLimit(quota, profileKey);
+        const profileUsed = usage.byProfile.get(profileKey) ?? 0;
+        if (profileUsed >= profileLimit) {
+            const label = profileKey === UNPROFILED_SUBAGENT ? 'unprofiled ' : `${profileKey} `;
+            throw invalid(`This run has used its ${slot(profileLimit, label)}. Do the remaining work yourself.`);
+        }
+        // Reserve before the first await so two tool calls in one message cannot both pass the check.
+        this.reserve(request.parentRunId, runId, profileKey);
+        try {
+            await until(parent.ready, parent.stopped.signal);
+            let variant = input.variant ?? null;
+            let launch = input.launch;
+            let model = input.model;
+            let effort = input.effort;
+            if (profile) {
+                // A variant's own subagent works from its definition alone; a profile keeps the parent's
+                // variant unless it names another one, or none.
+                if (profile.source === 'variant' || profile.variant === 'none')
+                    variant = null;
+                else if (profile.variant)
+                    variant = { scope: profile.variant.scope, version: profile.variant.version };
+                if (profile.model)
+                    model = profile.model;
+                if (profile.effort)
+                    effort = profile.effort;
+                launch = { ...(input.launch ?? {}), sections: [...(input.launch?.sections ?? []).filter((section) => section.id !== 'subagent'), { id: 'subagent', title: `Your role: ${profile.name}`, body: profile.instructions || profile.description, budget: 16_000, order: 22 }] };
+            }
+            const narrowed = input.plan
+                ? { capabilities: planEligibility.capabilities, unavailable: planEligibility.unavailableTools }
+                : narrowForProfile(capabilities, profile, request.tools, this.options.descriptors?.() ?? []);
+            const childCapabilities = narrowed.capabilities;
+            const tools = childCapabilities.tools;
+            const sessionId = randomUUID();
+            const child = {
+                ...input,
+                run: { ...input.run, ...(input.plan ? { worktreeId: null } : {}), id: runId, sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, goal: takeChars(brief, 4000), title, attachmentCount: 0, resumedFromRunId: null, handoffId: null, profile: profile?.name ?? null },
+                accountId, poolId: null, sessionDir: join(input.sessionDir, 'subagents', runId), resume: null,
+                text: brief, images: undefined, requiresImageInput: false, preamble: null,
+                caller: { ...input.caller, runId: undefined, sessionId },
+                tools: { allow: tools, gated: (input.tools.gated ?? []).filter((name) => tools.includes(name)) },
+                capabilities: childCapabilities, depth: (input.depth ?? 0) + 1,
+                variant, launch, model, effort,
+                ...(input.plan ? { connections: false, subagents: null } : {})
+            };
+            const result = await this.launchChild(parent, request, child);
+            return { ...result, ...(profile ? { agent: profile.name } : {}), ...(narrowed.unavailable.length ? { unavailableTools: narrowed.unavailable } : {}) };
+        }
+        finally {
+            this.release(request.parentRunId, runId);
+        }
     }
     /** Records ownership, starts the child, and writes a failed record when it never opened. */
     async launchChild(parent, request, child) {
@@ -236,6 +261,63 @@ export class Subagents {
     owned(parentRunId, parent) {
         return new Set([...recordedSubagents(this.env.root, parentRunId), ...(parent?.recovered ?? [])]);
     }
+    /** The run and the runs it was continued from, so a work-slice continuation keeps the budget. */
+    ancestry(runId) {
+        const chain = [];
+        const seen = new Set();
+        let current = runId;
+        while (current && !seen.has(current) && chain.length < 20) {
+            seen.add(current);
+            chain.push(current);
+            current = findRun(this.env.root, current)?.resumedFromRunId ?? null;
+        }
+        return chain;
+    }
+    /** Distinct child conversations this run has started, plus slots reserved before their record exists. */
+    usage(parentRunId) {
+        const byProfile = new Map();
+        const seen = new Set();
+        let total = 0;
+        const add = (key) => {
+            total += 1;
+            byProfile.set(key, (byProfile.get(key) ?? 0) + 1);
+        };
+        for (const owner of this.ancestry(parentRunId)) {
+            for (const id of recordedSubagents(this.env.root, owner)) {
+                const record = findRun(this.env.root, id);
+                if (!record || record.relation !== SUBAGENT_RELATION)
+                    continue;
+                // Continuing a stopped child opens a new run of the same conversation: one slot.
+                const first = this.firstLink(record).id;
+                if (seen.has(first))
+                    continue;
+                seen.add(first);
+                add(subagentProfileKey(record.profile));
+            }
+        }
+        const reserved = this.reserved.get(parentRunId);
+        if (reserved)
+            for (const [id, key] of reserved) {
+                if (seen.has(id) || findRun(this.env.root, id))
+                    continue;
+                seen.add(id);
+                add(key);
+            }
+        return { total, byProfile };
+    }
+    reserve(parentRunId, runId, profile) {
+        const reserved = this.reserved.get(parentRunId) ?? new Map();
+        reserved.set(runId, profile);
+        this.reserved.set(parentRunId, reserved);
+    }
+    release(parentRunId, runId) {
+        const reserved = this.reserved.get(parentRunId);
+        if (!reserved)
+            return;
+        reserved.delete(runId);
+        if (!reserved.size)
+            this.reserved.delete(parentRunId);
+    }
     /** The newest run in a continued child's chain, among the runs this parent owns. */
     latestLink(start, owned) {
         const records = [...owned].flatMap((id) => findRun(this.env.root, id) ?? []);

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

@@ -7,7 +7,38 @@ export declare const MAX_SUBAGENT_DEPTH = 3;
 export interface SubagentOptions {
     /** Maximum consecutive native subagent levels below a caller (1 to 3). */
     maxDepth?: number;
+    /** Distinct child conversations a run may start. */
+    maxChildren?: number;
+    /** Children a run may start from one named profile; a name it omits uses `maxOther`. */
+    maxByProfile?: Record<string, number>;
+    /** Children allowed from a named profile `maxByProfile` does not list. */
+    maxOther?: number;
+    /** Children allowed when the caller starts one with no profile. */
+    maxUnprofiled?: number;
 }
+/** How many distinct children a run may start when the caller does not say. */
+export declare const DEFAULT_SUBAGENT_CHILDREN = 4;
+/** The most a host may allow, so a mistyped setting cannot lift the budget entirely. */
+export declare const MAX_SUBAGENT_CHILDREN = 50;
+/** Foundation limits for the profiles the harness ships; `maxByProfile` overrides them. */
+export declare const DEFAULT_SUBAGENT_PROFILE_CHILDREN: Readonly<Record<string, number>>;
+export declare const DEFAULT_SUBAGENT_OTHER_PROFILE = 1;
+export declare const DEFAULT_SUBAGENT_UNPROFILED = 1;
+/** The bucket a child with no profile counts against. No profile name can be `*`. */
+export declare const UNPROFILED_SUBAGENT = "*";
+/** The children one run may start, by profile and in total. */
+export interface SubagentQuota {
+    children: number;
+    profiles: Readonly<Record<string, number>>;
+    other: number;
+    unprofiled: number;
+}
+/** The effective budget: the caller's values merged over the foundation defaults. */
+export declare function subagentQuota(options: SubagentOptions | undefined): SubagentQuota;
+/** The bucket a child counts against: its profile name, or the unprofiled bucket. */
+export declare function subagentProfileKey(profile: string | null | undefined): string;
+/** How many children this profile may still start under the quota. */
+export declare function subagentProfileLimit(quota: SubagentQuota, key: string): number;
 export declare function subagentDepth(options: SubagentOptions | undefined): number;
 export interface SubagentInput {
     parentRunId: string;

package/dist/sdk/sessions/subagents.js

@@ -6,6 +6,51 @@ export const SUBAGENT_RELATION = 'subagent';
 /** How deep subagents may nest when the caller does not say. */
 export const DEFAULT_SUBAGENT_DEPTH = 1;
 export const MAX_SUBAGENT_DEPTH = 3;
+/** How many distinct children a run may start when the caller does not say. */
+export const DEFAULT_SUBAGENT_CHILDREN = 4;
+/** The most a host may allow, so a mistyped setting cannot lift the budget entirely. */
+export const MAX_SUBAGENT_CHILDREN = 50;
+/** Foundation limits for the profiles the harness ships; `maxByProfile` overrides them. */
+export const DEFAULT_SUBAGENT_PROFILE_CHILDREN = { worker: 2, explorer: 3 };
+export const DEFAULT_SUBAGENT_OTHER_PROFILE = 1;
+export const DEFAULT_SUBAGENT_UNPROFILED = 1;
+/** The bucket a child with no profile counts against. No profile name can be `*`. */
+export const UNPROFILED_SUBAGENT = '*';
+function limit(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    return Math.min(MAX_SUBAGENT_CHILDREN, Math.max(0, Math.trunc(value)));
+}
+/** The effective budget: the caller's values merged over the foundation defaults. */
+export function subagentQuota(options) {
+    const profiles = { ...DEFAULT_SUBAGENT_PROFILE_CHILDREN };
+    const given = options?.maxByProfile;
+    if (given && typeof given === 'object' && !Array.isArray(given)) {
+        for (const [raw, value] of Object.entries(given)) {
+            const name = raw.trim();
+            if (!name || name.length > 64 || /[\x00-\x1f\x7f]/u.test(name))
+                continue;
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                continue;
+            profiles[name] = limit(value, profiles[name] ?? DEFAULT_SUBAGENT_OTHER_PROFILE);
+        }
+    }
+    return {
+        children: limit(options?.maxChildren, DEFAULT_SUBAGENT_CHILDREN),
+        profiles,
+        other: limit(options?.maxOther, DEFAULT_SUBAGENT_OTHER_PROFILE),
+        unprofiled: limit(options?.maxUnprofiled, DEFAULT_SUBAGENT_UNPROFILED)
+    };
+}
+/** The bucket a child counts against: its profile name, or the unprofiled bucket. */
+export function subagentProfileKey(profile) {
+    const name = typeof profile === 'string' ? profile.trim() : '';
+    return name || UNPROFILED_SUBAGENT;
+}
+/** How many children this profile may still start under the quota. */
+export function subagentProfileLimit(quota, key) {
+    return key === UNPROFILED_SUBAGENT ? quota.unprofiled : quota.profiles[key] ?? quota.other;
+}
 export function subagentDepth(options) {
     const value = Math.trunc(options?.maxDepth ?? DEFAULT_SUBAGENT_DEPTH);
     return Math.min(MAX_SUBAGENT_DEPTH, Math.max(1, Number.isFinite(value) ? value : DEFAULT_SUBAGENT_DEPTH));

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

@@ -10,6 +10,6 @@ export interface SocketConnection {
 }
 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>;
+export declare function socketCall<T = unknown>(connection: SocketConnection, call: string, params?: Record<string, unknown>, timeoutMs?: number, control?: string, signal?: AbortSignal): 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>;