@xingular/harness 1.1.1 → 1.3.1-unstable.0

package/dist/sdk/sessions/subagentService.js

@@ -6,9 +6,11 @@ import { now } from "../core/fs.js";
 import { takeChars } from "../core/text.js";
 import { isActiveStatus } from "./contracts.js";
 import { narrowForProfile } from "../agents/narrow.js";
+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, subagentHistory, subagentTitle } from "./subagents.js";
+import { SPAWN_SUBAGENT, SUBAGENT_RELATION, SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, briefTitle, continueHint, subagentHistory, subagentTitle } from "./subagents.js";
 function until(promise, signal) {
     if (signal.aborted) {
         void promise.catch(() => { });
@@ -27,6 +29,7 @@ export class Subagents {
     launch;
     options;
     parents = new Map();
+    runtimeSettingsByRun = new Map();
     constructor(env, runs, launch, options = {}) {
         this.env = env;
         this.runs = runs;
@@ -66,12 +69,26 @@ export class Subagents {
             started();
         this.parents.set(input.run.id, { ready, started, input: structuredClone({ ...input, text: '', images: undefined, requiresImageInput: false, preamble: null, resume: null }), accountId, capabilities: ceiling, stopped: new AbortController(), recovered: new Set(), launching: new Map() });
     }
+    runtimeSettings(runId) {
+        return this.runtimeSettingsByRun.get(runId) ?? null;
+    }
+    rememberRuntimeSettings(runId, settings) {
+        this.runtimeSettingsByRun.set(runId, settings);
+        if (this.runtimeSettingsByRun.size > 500) {
+            const oldest = this.runtimeSettingsByRun.keys().next().value;
+            if (oldest !== undefined)
+                this.runtimeSettingsByRun.delete(oldest);
+        }
+    }
     resolvedModel(runId, model, effort) {
         const parent = this.parents.get(runId);
         if (parent) {
             parent.input.model = model;
             parent.input.effort = effort ?? parent.input.effort;
         }
+        const settings = this.runtimeSettingsByRun.get(runId);
+        if (settings)
+            this.rememberRuntimeSettings(runId, { model, effort: effort ?? settings.effort });
     }
     parent(runId) {
         const parent = this.parents.get(runId);
@@ -79,11 +96,53 @@ export class Subagents {
             throw new HarnessError('run_not_active', 'The parent run is not accepting subagents.');
         return parent;
     }
+    planSpawnCheck(parentRunId, args) {
+        const parent = this.parents.get(parentRunId);
+        if (!parent || !this.runs.active(parentRunId))
+            return { refusal: 'The parent run is not accepting subagents.' };
+        if (!parent.input.plan)
+            return { refusal: 'Read-only research delegation is available only during plan mode.' };
+        if (!parent.capabilities.tools.includes(SPAWN_SUBAGENT))
+            return { refusal: 'Subagents are not enabled for this run.' };
+        if (!args || typeof args !== 'object' || Array.isArray(args))
+            return { refusal: 'Plan-mode delegation requires a named, eligible read-only research profile.' };
+        let request = args;
+        if (request.continue !== undefined) {
+            // A continued child keeps its own profile; judge that profile.
+            const id = typeof request.continue === 'string' ? request.continue.trim() : '';
+            const record = id && this.owned(parentRunId, parent).has(id) ? findRun(this.env.root, id) : null;
+            if (!record?.profile)
+                return { refusal: 'Plan mode can continue only a stopped research subagent of this conversation that has a named profile.' };
+            if (request.agent !== undefined || request.tools !== undefined)
+                return { refusal: 'A continued subagent keeps its profile and tools; omit agent and tools.' };
+            request = { agent: record.profile };
+        }
+        if (typeof request.agent !== 'string' || !request.agent.trim())
+            return { refusal: 'Plan-mode delegation requires a named, eligible read-only research profile.' };
+        if (request.tools !== undefined && (!Array.isArray(request.tools) || request.tools.some(name => typeof name !== 'string'))) {
+            return { refusal: 'The optional tools field must be an array of tool names. Omit it to inherit the selected profile’s safe research intersection.' };
+        }
+        const profile = resolveProfile(this.env.root, parent.input.cwd, request.agent.trim(), parent.input.variant && 'dir' in parent.input.variant ? parent.input.variant.dir : null);
+        if (!profile)
+            return { refusal: `There is no agent profile named ${request.agent.trim()}.` };
+        const eligibility = planResearchEligibility(profile, {
+            frozenTools: parent.capabilities.tools,
+            contributions: parent.capabilities.contributions,
+            descriptors: this.options.descriptors?.() ?? []
+        }, request.tools);
+        return { refusal: eligibility.refusal, profile, eligibility };
+    }
+    /** The plan-mode per-call gate and spawn implementation share this eligibility check. */
+    planSpawnRefusal(parentRunId, args) {
+        return this.planSpawnCheck(parentRunId, args).refusal;
+    }
     async spawn(request) {
         const parent = this.parent(request.parentRunId);
         const { input, accountId, capabilities } = parent;
         if (!capabilities.tools.includes(SPAWN_SUBAGENT))
             throw invalid('Subagents are not enabled for this run.');
+        if (request.continue !== undefined)
+            return this.continueChild(parent, request);
         const brief = typeof request.brief === 'string' ? request.brief.trim() : '';
         if (!brief)
             throw invalid('Give the subagent a brief.');
@@ -94,22 +153,33 @@ export class Subagents {
             throw invalid('wait must be a boolean.');
         if (request.tools !== undefined && (!Array.isArray(request.tools) || request.tools.some((name) => typeof name !== 'string')))
             throw invalid('Tools must be an array of tool names.');
-        const outside = request.tools?.filter((name) => !capabilities.tools.includes(name)) ?? [];
-        if (outside.length)
-            throw invalid(`A subagent cannot have tools you do not have: ${outside.join(', ')}.`);
+        let profile = null;
+        let planEligibility = null;
+        if (input.plan) {
+            const check = this.planSpawnCheck(request.parentRunId, request);
+            if (check.refusal || !check.profile || !check.eligibility)
+                throw invalid(check.refusal ?? 'The selected profile has no eligible research tools in this run.');
+            profile = check.profile;
+            planEligibility = check.eligibility;
+        }
+        else {
+            const outside = request.tools?.filter((name) => !capabilities.tools.includes(name)) ?? [];
+            if (outside.length)
+                throw invalid(`A subagent cannot have tools you do not have: ${outside.join(', ')}.`);
+            if (request.agent !== undefined) {
+                if (typeof request.agent !== 'string' || !request.agent.trim())
+                    throw invalid('agent must be the name of an agent profile.');
+                profile = resolveProfile(this.env.root, input.cwd, request.agent.trim(), input.variant && 'dir' in input.variant ? input.variant.dir : null);
+                if (!profile)
+                    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;
-        let profile = null;
-        if (request.agent !== undefined) {
-            if (typeof request.agent !== 'string' || !request.agent.trim())
-                throw invalid('agent must be the name of an agent profile.');
-            const dir = variant && 'dir' in variant ? variant.dir : null;
-            profile = resolveProfile(this.env.root, input.cwd, request.agent.trim(), dir);
-            if (!profile)
-                throw invalid(`There is no agent profile named ${request.agent.trim()}.`);
+        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')
@@ -122,25 +192,36 @@ export class Subagents {
                 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 = narrowForProfile(capabilities, profile, request.tools, this.options.descriptors?.() ?? []);
-        const tools = narrowed.capabilities.tools;
+        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 runId = randomUUID();
         const sessionId = randomUUID();
-        recordSubagent(this.env.root, request.parentRunId, runId);
         const child = {
             ...input,
-            run: { ...input.run, id: runId, sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, goal: takeChars(brief, 4000), title, attachmentCount: 0, resumedFromRunId: null, handoffId: null, profile: profile?.name ?? null },
+            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: narrowed.capabilities, depth: (input.depth ?? 0) + 1,
-            variant, launch, model, effort
+            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 } : {}) };
+    }
+    /** Records ownership, starts the child, and writes a failed record when it never opened. */
+    async launchChild(parent, request, child) {
+        const runId = child.run.id;
+        this.rememberRuntimeSettings(runId, { model: child.model ?? null, effort: child.effort ?? null });
+        recordSubagent(this.env.root, request.parentRunId, runId);
         const started = this.launch(child).catch((error) => {
             if (!findRun(this.env.root, runId)) {
                 const source = loadRun(this.env.root, request.parentRunId);
-                saveRun(this.env.root, { ...source, id: runId, sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, nativeSessionId: null, resumedFromRunId: null, handoffId: null, exitCode: null, goal: takeChars(brief, 4000), title, attachmentCount: 0, status: 'failed', startedAt: now(), endedAt: now(), terminalReason: error instanceof HarnessError ? error.message : 'Subagent startup failed before its session opened.', profile: profile?.name ?? null });
+                saveRun(this.env.root, { ...source, id: runId, sessionId: child.run.sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, nativeSessionId: null, resumedFromRunId: child.run.resumedFromRunId ?? null, handoffId: null, exitCode: null, goal: child.run.goal ?? null, title: child.run.title ?? null, attachmentCount: 0, status: 'failed', startedAt: now(), endedAt: now(), terminalReason: error instanceof HarnessError ? error.message : 'Subagent startup failed before its session opened.', profile: child.run.profile ?? null, model: child.model ?? null, effort: child.effort ?? null });
             }
             return { runId, nativeSessionId: null };
         });
@@ -149,10 +230,113 @@ export class Subagents {
         const result = await until(started, parent.stopped.signal);
         if (request.wait)
             await this.wait({ parentRunId: request.parentRunId, runIds: [runId] });
-        return { ...result, ...(profile ? { agent: profile.name } : {}), ...(narrowed.unavailable.length ? { unavailableTools: narrowed.unavailable } : {}) };
+        return result;
+    }
+    /** The children this parent may read or continue: its own, and those recovered from its history. */
+    owned(parentRunId, parent) {
+        return new Set([...recordedSubagents(this.env.root, parentRunId), ...(parent?.recovered ?? [])]);
+    }
+    /** 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) ?? []);
+        let latest = start;
+        const seen = new Set([start.id]);
+        for (;;) {
+            const next = records.filter((record) => record.resumedFromRunId === latest.id && !seen.has(record.id)).sort((left, right) => left.startedAt.localeCompare(right.startedAt)).at(-1);
+            if (!next)
+                return latest;
+            seen.add(next.id);
+            latest = next;
+        }
+    }
+    /** The first run of a chain: its folder holds the child's history for every later link. */
+    firstLink(record) {
+        let first = record;
+        const seen = new Set([record.id]);
+        while (first.resumedFromRunId && !seen.has(first.resumedFromRunId)) {
+            const previous = findRun(this.env.root, first.resumedFromRunId);
+            if (!previous || previous.relation !== SUBAGENT_RELATION)
+                break;
+            seen.add(previous.id);
+            first = previous;
+        }
+        return first;
+    }
+    /**
+     * Continues a stopped child as a new child run with `continueFrom`: the same history, profile,
+     * account, variant version and capability set, which must still lie within the parent's.
+     */
+    async continueChild(parent, request) {
+        const { root } = this.env;
+        const { input, accountId, capabilities } = parent;
+        const requested = typeof request.continue === 'string' ? request.continue.trim() : '';
+        if (!requested)
+            throw invalid('continue must be the run ID of a subagent that stopped.');
+        if (request.agent !== undefined || request.tools !== undefined)
+            throw invalid('A continued subagent keeps its profile and tools; omit agent and tools.');
+        if (request.brief !== undefined && typeof request.brief !== 'string')
+            throw invalid('brief must be text.');
+        if (request.wait !== undefined && typeof request.wait !== 'boolean')
+            throw invalid('wait must be a boolean.');
+        await until(parent.ready, parent.stopped.signal);
+        const owned = this.owned(request.parentRunId, parent);
+        const named = owned.has(requested) ? findRun(root, requested) : null;
+        if (!named || named.relation !== SUBAGENT_RELATION)
+            throw invalid('Continue only a subagent that this conversation started.');
+        const latest = this.latestLink(named, owned);
+        if (isActiveStatus(latest.status))
+            throw invalid(`Subagent ${latest.id} is still running; wait for it with wait_subagents.`);
+        if (latest.status === 'completed')
+            throw invalid(`Subagent ${latest.id} already finished and its result was delivered. Start a new subagent for more work.`);
+        const sessionDir = join(input.sessionDir, 'subagents', this.firstLink(latest).id);
+        const continuation = continuationOf(root, latest.id, sessionDir);
+        if (!continuation.resumable || !continuation.resume)
+            throw invalid(`Subagent ${latest.id} cannot be continued: ${continuation.reason === 'no_history' ? 'it stopped before its conversation started' : 'its saved conversation is missing'}. Start a new subagent instead.`);
+        if (continuation.accountId !== accountId)
+            throw invalid(`Subagent ${latest.id} ran on another account; start a new subagent instead.`);
+        const pinned = continuation.capabilities;
+        if (!pinned)
+            throw invalid(`Subagent ${latest.id} has no recorded capabilities; start a new subagent instead.`);
+        const missing = [
+            ...pinned.tools.filter((name) => !capabilities.tools.includes(name)),
+            ...pinned.connectors.filter((id) => !capabilities.connectors.includes(id)),
+            ...pinned.contributions.filter((id) => !capabilities.contributions.includes(id))
+        ];
+        if (missing.length)
+            throw invalid(`Subagent ${latest.id} needs capabilities you do not have in this run: ${missing.join(', ')}. Start a new subagent instead.`);
+        let profile = null;
+        if (latest.profile)
+            profile = resolveProfile(root, input.cwd, latest.profile, input.variant && 'dir' in input.variant ? input.variant.dir : null);
+        if (input.plan) {
+            // A plan run continues only a research child whose pinned tools still qualify.
+            const check = latest.profile ? this.planSpawnCheck(request.parentRunId, { agent: latest.profile }) : { refusal: 'Plan mode can continue only a stopped research subagent that has a named profile.' };
+            if (check.refusal || !check.eligibility)
+                throw invalid(check.refusal ?? 'This subagent is not eligible for plan-mode research.');
+            const outside = pinned.tools.filter((name) => !check.eligibility.capabilities.tools.includes(name));
+            if (outside.length)
+                throw invalid(`Subagent ${latest.id} has tools plan mode does not allow: ${outside.join(', ')}.`);
+        }
+        const launch = profile
+            ? { ...(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 }] }
+            : input.launch;
+        const runId = randomUUID();
+        const child = {
+            ...input,
+            run: { ...input.run, ...(input.plan ? { worktreeId: null } : {}), id: runId, sessionId: latest.sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, goal: latest.goal, title: latest.title ?? briefTitle(latest.goal), attachmentCount: 0, resumedFromRunId: latest.id, handoffId: null, profile: latest.profile ?? null },
+            accountId, poolId: null, sessionDir, resume: null, continueFrom: latest.id,
+            text: typeof request.brief === 'string' ? request.brief.trim() : '', images: undefined, requiresImageInput: false, preamble: null,
+            caller: { ...input.caller, runId: undefined, sessionId: latest.sessionId },
+            tools: { allow: pinned.tools, gated: (input.tools.gated ?? []).filter((name) => pinned.tools.includes(name)) },
+            capabilities: pinned, depth: (input.depth ?? 0) + 1,
+            variant: null, launch,
+            model: latest.model ?? input.model, effort: latest.effort ?? input.effort,
+            ...(input.plan ? { connections: false, subagents: null } : {})
+        };
+        const result = await this.launchChild(parent, request, child);
+        return { ...result, continued: latest.id, ...(latest.profile ? { agent: latest.profile } : {}) };
     }
     selected(selection, parent) {
-        const owned = new Set([...recordedSubagents(this.env.root, selection.parentRunId), ...(parent?.recovered ?? [])]);
+        const owned = this.owned(selection.parentRunId, parent);
         if (selection.runIds !== undefined && (!Array.isArray(selection.runIds) || selection.runIds.some((id) => typeof id !== 'string')))
             throw invalid('runIds must be an array of child run IDs.');
         const ids = [...new Set(selection.runIds ?? [...owned])];
@@ -192,7 +376,9 @@ export class Subagents {
             if (owner === parentRunId)
                 continue;
             const old = findRun(this.env.root, owner);
-            if (!old || old.sessionId !== current.sessionId || old.accountId !== current.accountId || old.agentId !== current.agentId || old.projectId !== current.projectId || old.workingDirectory !== current.workingDirectory || !old.nativeSessionId || old.nativeSessionId !== current.nativeSessionId)
+            // The owner marker on this native branch is the lineage; a host may give each launch of the
+            // same conversation a new session id (INV-RUN-4).
+            if (!old || old.accountId !== current.accountId || old.agentId !== current.agentId || old.projectId !== current.projectId || old.workingDirectory !== current.workingDirectory || !old.nativeSessionId || old.nativeSessionId !== current.nativeSessionId)
                 continue;
             for (const id of recordedSubagents(this.env.root, owner)) {
                 let child = findRun(this.env.root, id);
@@ -218,12 +404,19 @@ export class Subagents {
             }
         }
         const delivered = new Set(history.receipts.flatMap((receipt) => receipt.delivered ?? []));
-        const pending = this.results({ parentRunId }).filter((result) => !isActiveStatus(result.status) && !delivered.has(result.runId));
+        const all = this.results({ parentRunId });
+        const records = new Map(all.map((result) => [result.runId, findRun(this.env.root, result.runId)]));
+        // A stopped child that was continued is reported through its continuation instead.
+        const superseded = new Set([...records.values()].flatMap((record) => record?.resumedFromRunId ? [record.resumedFromRunId] : []));
+        const pending = all.filter((result) => !isActiveStatus(result.status) && !delivered.has(result.runId) && !superseded.has(result.runId));
         const chunks = [];
         const ids = [];
         let size = 0;
         for (const result of pending) {
-            const text = `Subagent run ${result.runId} · ${result.status}\n${result.text || result.terminalReason || 'No written reply.'}`;
+            const record = records.get(result.runId);
+            const label = [record?.profile, record?.title].filter(Boolean).join(' · ');
+            const stopped = (result.status === 'interrupted' || result.status === 'failed') && continuationOf(this.env.root, result.runId).resumable;
+            const text = `Subagent run ${result.runId} · ${result.status}${label ? ` (${label})` : ''}\n${result.text || result.terminalReason || 'No written reply.'}${stopped ? `\nIt stopped before finishing. ${continueHint(result.runId)}` : ''}`;
             if (size + text.length > 32_000 && ids.length)
                 break;
             chunks.push(text);
@@ -242,12 +435,18 @@ export class Subagents {
     }
     extension(runId) {
         return { name: 'native-subagents', factory: (pi) => {
-                pi.on('before_agent_start', (_event, ctx) => {
+                pi.on('before_agent_start', async (_event, ctx) => {
                     if (!this.parents.has(runId))
                         return;
-                    this.restore(runId, subagentHistory(ctx.sessionManager.getBranch()));
+                    const history = subagentHistory(ctx.sessionManager.getBranch());
+                    this.restore(runId, history);
                     pi.appendEntry(SUBAGENT_OWNER, { runId });
                     this.parent(runId).started();
+                    // Children an earlier reply left stopped are reported before the model answers, so it can
+                    // continue them instead of starting over.
+                    const notice = await this.delivery(runId, history, false);
+                    if (notice)
+                        return { message: { customType: SUBAGENT_RESULTS, content: notice.text, display: false, details: { [SUBAGENT_RECEIPT]: notice.receipt } } };
                 });
                 const deliver = async (event, ctx, settle) => {
                     if (!this.parents.has(runId) || (settle && event.outcome !== 'completed') || ctx.signal?.aborted)

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

@@ -11,14 +11,23 @@ export interface SubagentOptions {
 export declare function subagentDepth(options: SubagentOptions | undefined): number;
 export interface SubagentInput {
     parentRunId: string;
-    brief: string;
+    /** The task for a new child; with `continue`, an optional extra instruction. */
+    brief?: string;
     /** The short name the roster shows for the child (PROP-0030); the spawn tool requires it. */
     title?: string;
     tools?: string[];
     wait?: boolean;
     /** An agent profile by name (PROP-0029), or one of the parent variant's subagents (c5). */
     agent?: string;
+    /**
+     * A stopped child to continue instead of starting a fresh one: its run id. The new child reopens
+     * that child's own history and keeps its profile, tools, account and variant; `brief` is then an
+     * optional extra instruction.
+     */
+    continue?: string;
 }
+/** The words that tell a parent a stopped child can be continued rather than started again. */
+export declare function continueHint(runId: string): string;
 /** A subagent title is one short imperative, at most this many words (PROP-0030). */
 export declare const MAX_SUBAGENT_TITLE_WORDS = 6;
 /** The title a subagent title input means after cleaning, or undefined when it is not one. */

package/dist/sdk/sessions/subagents.js

@@ -10,6 +10,10 @@ 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));
 }
+/** The words that tell a parent a stopped child can be continued rather than started again. */
+export function continueHint(runId) {
+    return `Its conversation is saved: continue it with spawn_subagent { "continue": "${runId}" } if the work is still needed, instead of starting it again from scratch.`;
+}
 /** A subagent title is one short imperative, at most this many words (PROP-0030). */
 export const MAX_SUBAGENT_TITLE_WORDS = 6;
 const BRIEF_TITLE_LENGTH = 60;

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

@@ -0,0 +1,106 @@
+import type { Checkpoint } from "./contracts.js";
+export declare const WORK_SLICE_EXTENSION = "work-slice";
+export interface WorkSliceInput {
+    /** False turns the guard off for this run: no budget, no stall notes, no continuation. */
+    enabled?: boolean;
+    /** Tool calls in one reply; 0 disables this limit. */
+    maxToolCalls?: number;
+    /** Minutes in one reply; 0 disables this limit. */
+    maxMinutes?: number;
+    /** New tokens in one reply (new input + cache writes + output); 0 disables this limit, and no limit is the default. */
+    maxNewTokens?: number;
+    /** Slices one task may use before it is handed back to the person; 0 disables the cap. */
+    maxSlices?: number;
+    /** Start the next slice from the checkpoint without asking. */
+    continue?: boolean;
+}
+export interface SlicePolicy {
+    enabled: boolean;
+    maxToolCalls: number;
+    maxMinutes: number;
+    maxNewTokens: number;
+    maxSlices: number;
+    continue: boolean;
+}
+/** The foundation defaults: enough for one meaningful step of work, short enough to report. */
+export declare const DEFAULT_SLICE_POLICY: SlicePolicy;
+export declare class WorkSliceError extends Error {
+}
+/**
+ * The policy a run asked for, or the defaults. `XINGULAR_WORK_SLICE=off` at launch turns the guard
+ * off for every run in this process; nothing is persisted, so restarting without it restores the
+ * defaults.
+ */
+export declare function parseWorkSlice(input: unknown): SlicePolicy;
+export type SliceEnd = 'budget' | 'stuck' | 'compaction-thrash';
+/** What a live reply tracks for its slice; the runner reads it after the reply. */
+export interface SliceState {
+    slice: number;
+    steps: number;
+    tokens: number;
+    startedAt: number;
+    lastTool: string | null;
+    compactions: number;
+    checkpointWritten: boolean;
+    /** Set when the guard ended the reply instead of the model finishing it. */
+    endedBy: SliceEnd | null;
+    /** The limit that ended it, for the record. */
+    endedByLimit: string | null;
+    /** Steps past which every non-exempt tool call is refused, once one was refused. */
+    refusedAt: number | null;
+}
+export declare function createSliceState(_policy: SlicePolicy, slice?: number, now?: number): SliceState;
+/** Counters start again for each reply; a terminal session keeps one guard across replies. */
+export declare function resetSliceState(state: SliceState, now?: number): void;
+/** The first limit this reply has passed, named as a person would say it. */
+export declare function sliceLimitReached(policy: SlicePolicy, state: SliceState, now?: number): string | null;
+/** Commands that read as a check for the repeated-failure rule. */
+export declare function looksLikeCheck(command: string): boolean;
+interface ToolCall {
+    toolName: string;
+    input?: unknown;
+}
+interface ToolResult {
+    toolName: string;
+    isError?: boolean;
+    input?: unknown;
+}
+/** The part of Pi's extension API this guard uses. Structural, so the module needs no Pi import. */
+interface GuardApi {
+    on(event: 'agent_start', handler: () => unknown): void;
+    on(event: 'tool_call', handler: (event: ToolCall) => unknown): void;
+    on(event: 'tool_result', handler: (event: ToolResult) => unknown): void;
+    on(event: 'message_end', handler: (event: {
+        message: {
+            role: string;
+            usage?: {
+                input?: number;
+                output?: number;
+                cacheRead?: number;
+                cacheWrite?: number;
+            };
+        };
+    }) => unknown): void;
+}
+export interface WorkSliceGuardOptions {
+    policy: SlicePolicy;
+    state: SliceState;
+    /** Whether checkpoint_write is active; a function supports the terminal's live plan-mode switch. */
+    checkpointAvailable?: boolean | (() => boolean);
+    /** Called when a triggering call terminates the reply; the runner ends it. */
+    onEnd?: (end: SliceEnd, limit: string) => void;
+}
+/**
+ * Bounds one reply and names repeated work. Refusals request a checkpoint when available; without
+ * one, they ask for a partial report and prohibit further tools. A repeated call or failing command
+ * is named once, then ends the reply.
+ */
+export declare function workSliceGuard(options: WorkSliceGuardOptions): (pi: GuardApi) => void;
+/**
+ * Which slice of its session a run is, from 1. Counts the recorded continuation chain, so it
+ * survives a restart and needs no extra field on the run record.
+ */
+export declare function sliceOf(root: string, runId: string, limit?: number): number;
+/** The reason a checkpoint the harness derives (no model handoff) records. */
+export declare function derivedReason(end: SliceEnd | null): Checkpoint['reason'];
+export {};