@xingular/harness 1.1.1 → 1.3.1-unstable.0

package/dist/sdk/sessions/sessions.js

@@ -1,12 +1,15 @@
 // Starting a session turn: the account, the run record, the compiled prompt, the tools and
 // their gate, then Pi. Everything before Pi answers is synchronous with the caller; the reply
 // itself streams as run events.
+import { randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 import { log } from "../core/bus.js";
 import { HarnessError, invalid } from "../core/errors.js";
+import { formatBashCommandForApproval } from "../core/workspaceBashTool.js";
 import { capabilitySet as parseCapabilitySet, freezeRun } from "../capabilities/runSnapshot.js";
 import { now, writeJson } from "../core/fs.js";
+import { resolveWorkspaceRoot, verifyWorkspaceRoot } from "../core/workspace.js";
 import { takeChars } from "../core/text.js";
 import { BUILTIN_PLUGIN_REGISTRY } from "../plugins/builtin.js";
 import { sessionLaunch } from "../prompt/compile.js";
@@ -15,18 +18,44 @@ import { FIRST_PARTY_PLUGINS, firstPartyExtensions } from "../plugins/firstParty
 import { imagePruning } from "../world/images.js";
 import { materialise } from "../variant/materialise.js";
 import { ASK_USER } from "../tools/askUser.js";
-import { CHECKLIST_WRITE } from "../tools/checklist.js";
+import { TODO_WRITE } from "../tools/todo.js";
+import { CHECKPOINT_WRITE, checkpointOf } from "../tools/checkpoint.js";
 import { SESSION_NAME, sessionNameTool } from "../tools/sessionName.js";
 import { DEFAULT_TOOL_NAMES } from "../tools/definitions.js";
+import { GET_CAPABILITIES, getCapabilitiesTool } from "../tools/getCapabilities.js";
+import { isActiveStatus } from "./contracts.js";
 import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, subagentDepth, subagentHistory, subagentNesting } from "./subagents.js";
 import { selectHistory } from "./history.js";
 import { runLineageJoin } from "./lineageJoin.js";
+import { compactionCheckpoint, COMPACTION_CHECKPOINT_EXTENSION } from "./compactionCheckpoint.js";
+import { createSliceState, parseWorkSlice, sliceOf, workSliceGuard, WorkSliceError, WORK_SLICE_EXTENSION } from "./workSlice.js";
 import { piSessionFactory, runTurn, summarize } from "./runner.js";
-import { loadRun, runDir, saveRun, updateRun } from "./runStore.js";
-import { planRefusal, planSection } from "./planMode.js";
+import { loadRun, readEvents, runDir, saveRun, updateRun } from "./runStore.js";
+import { combineWorkspaceScope, inspectRunWorkspaceWrite } from "./workspaceBoundary.js";
+import { PLAN_INSTRUCTIONS, PLAN_RESEARCH_SUBAGENT_INSTRUCTIONS, planRefusal, planSection } from "./planMode.js";
 import { CONTINUATION_SECTION_ID, continuationOf, continuationSection } from "./continuation.js";
 import { deliveredSnapshot } from "../prompt/compile.js";
 import { profileSection } from "../agents/profiles.js";
+/** A session command acts on a saved conversation and is never combined with a request of its own. */
+function checkCommand(command, historyFile, input) {
+    if (!historyFile)
+        throw invalid('There is no saved conversation for this command yet.');
+    if (input.plan || input.continueFrom || input.automatic || input.initialBashCommand != null || input.images?.length) {
+        throw invalid('A session command runs on its own, without plan mode, a continuation, Bash or images.');
+    }
+    switch (command?.name) {
+        case 'compact': return;
+        case 'navigate':
+            if (typeof command.entryId !== 'string' || !command.entryId)
+                throw invalid('navigate needs the entry to go to.');
+            return;
+        case 'export':
+            if (typeof command.path !== 'string' || !isAbsolute(command.path) || !command.path.endsWith('.html'))
+                throw invalid('export needs an absolute .html path.');
+            return;
+        default: throw invalid('Unknown session command.');
+    }
+}
 const CONTINUE_TEXT = 'Continue from where you stopped.';
 /** Fills a continuing run's input from the run it continues, refusing anything that would differ. */
 function continueInput(root, input) {
@@ -95,7 +124,7 @@ export class Sessions {
     diagnosticGate(run, caller) {
         return this.gate(run, caller, new Set(), true);
     }
-    gate(run, caller, gated, diagnostic = false) {
+    gate(run, caller, gated, diagnostic = false, automatic = false) {
         const { policy } = this.options;
         return {
             ask: (names) => {
@@ -103,9 +132,19 @@ export class Sessions {
                     gated.add(name);
             },
             check: async (tool, args) => {
-                const call = { run: loadRun(this.env.root, run.runId), caller, tool, args };
-                const scope = (await policy.scope?.(call)) ?? { allowed: true };
-                if (!scope.allowed && (scope.automatic || !scope.requiresApproval))
+                let record;
+                let inspection;
+                try {
+                    record = loadRun(this.env.root, run.runId);
+                    inspection = inspectRunWorkspaceWrite(record, tool, args);
+                }
+                catch (error) {
+                    return error instanceof Error ? error.message : 'The active project workspace could not be verified.';
+                }
+                const call = { run: record, caller, tool, args: inspection.input };
+                const hostScope = (await policy.scope?.(call)) ?? { allowed: true };
+                const scope = combineWorkspaceScope(hostScope, inspection);
+                if (!scope.allowed && (scope.automatic || (automatic && inspection.outside) || !scope.requiresApproval))
                     return scope.reason ?? 'Outside the approved work scope.';
                 try {
                     await policy.authorize?.(call);
@@ -122,11 +161,11 @@ export class Sessions {
                     return scope.reason ? `Refused in a refinement run: ${scope.reason}` : 'Refused in a refinement run: this call needs a person to approve it.';
                 if (call.run.trigger === 'reflection')
                     return scope.reason ? `Refused in a reflection run: ${scope.reason}` : 'Refused in a reflection run: this call needs a person to approve it.';
-                // A call outside the scope is approved one at a time; a gated tool may be remembered, unless only a person may decide it.
+                const boundaryAction = inspection.outside ? `${inspection.reason} ${summarize(call.args, tool)}` : summarize(call.args);
                 const decision = await run.requestApproval({
                     target: tool,
-                    action: summarize(args),
-                    operation: { tool, args: (args && typeof args === 'object' ? args : {}) },
+                    action: boundaryAction,
+                    operation: { tool, args: (call.args && typeof call.args === 'object' ? call.args : {}) },
                     rememberable: scope.allowed && !scope.humanOnly,
                     standing: scope.humanOnly ? (scope.allowGlobalApproval ? 'switch' : 'none') : undefined
                 });
@@ -139,6 +178,69 @@ export class Sessions {
                     return error instanceof Error ? error.message : 'Tool was disabled while waiting.';
                 }
                 return null;
+            },
+            workspaceBoundaryBypass: async (tool, args) => {
+                if (diagnostic || automatic || tool.toLowerCase() !== 'bash')
+                    return false;
+                const record = loadRun(this.env.root, run.runId);
+                if (record.trigger != null && record.trigger !== 'user')
+                    return false;
+                if (!await this.options.fullPermission?.(record))
+                    return false;
+                const call = { run: record, caller, tool, args };
+                const scope = (await policy.scope?.(call)) ?? { allowed: true };
+                if (scope.automatic || (!scope.allowed && !scope.requiresApproval) || (scope.humanOnly && !scope.allowGlobalApproval))
+                    return false;
+                try {
+                    await policy.authorize?.(call);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            requestWorkspaceWriteScope: async (tool, args, reason) => {
+                if (diagnostic || automatic || tool.toLowerCase() !== 'bash')
+                    return false;
+                const record = loadRun(this.env.root, run.runId);
+                if (!isActiveStatus(record.status) || (record.trigger != null && record.trigger !== 'user'))
+                    return false;
+                const operationArgs = (args && typeof args === 'object' && !Array.isArray(args) ? args : {});
+                if (operationArgs.workspaceWriteScope !== 'outside' || typeof operationArgs.command !== 'string' || !operationArgs.command)
+                    return false;
+                const call = { run: record, caller, tool, args: operationArgs };
+                const scope = (await policy.scope?.(call)) ?? { allowed: true };
+                if (scope.automatic || (!scope.allowed && !scope.requiresApproval))
+                    return false;
+                try {
+                    await policy.authorize?.(call);
+                }
+                catch {
+                    return false;
+                }
+                const decision = await run.requestApproval({
+                    target: 'workspace-write',
+                    action: `${reason}\n\nCommand to be run once after approval:\n${formatBashCommandForApproval(operationArgs.command)}`,
+                    operation: { tool, args: operationArgs },
+                    rememberable: false,
+                    standing: 'none'
+                });
+                if (decision !== 'approved')
+                    return false;
+                const currentRecord = loadRun(this.env.root, run.runId);
+                if (!isActiveStatus(currentRecord.status) || (currentRecord.trigger != null && currentRecord.trigger !== 'user'))
+                    return false;
+                const currentCall = { run: currentRecord, caller, tool, args: operationArgs };
+                const currentScope = (await policy.scope?.(currentCall)) ?? { allowed: true };
+                if (currentScope.automatic || (!currentScope.allowed && !currentScope.requiresApproval))
+                    return false;
+                try {
+                    await policy.authorize?.(currentCall);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
             }
         };
     }
@@ -195,6 +297,50 @@ export class Sessions {
         });
         return { release };
     }
+    /**
+     * Starts the next slice when a reply stopped at its work-slice boundary (PROP-0041). Never for
+     * unattended, plan, subagent, command or worktree runs, after a blocked or fruitless slice, or
+     * past the policy's slice cap. The earlier record is never reopened; this is a new run with the
+     * same pins, exactly as an application-asked continuation.
+     */
+    async continueSlice(input) {
+        const { root, runId, source, policy } = input;
+        if (!policy.enabled || !policy.continue || policy.maxSlices <= 0)
+            return;
+        if (source.automatic || source.plan || source.command || source.run.relation || source.run.worktreeId)
+            return;
+        if ((source.depth ?? 0) > 0)
+            return;
+        const record = loadRun(root, runId);
+        if (record.terminalReason !== 'slice_complete')
+            return;
+        const events = readEvents(root, runId);
+        const checkpoint = checkpointOf(events);
+        if (checkpoint?.blocked)
+            return;
+        const progressed = events.some((event) => event.type === 'file.changed')
+            || events.some((event) => {
+                const payload = event.payload;
+                return event.type === 'tool.completed' && payload.name === 'bash' && payload.ok === true;
+            })
+            || (checkpoint?.done.length ?? 0) > 0;
+        if (!progressed)
+            return;
+        if (sliceOf(root, runId) >= policy.maxSlices)
+            return;
+        const next = {
+            ...source,
+            run: { ...source.run, id: randomUUID(), resumedFromRunId: null, parentRunId: null, relation: null },
+            continueFrom: runId,
+            text: CONTINUE_TEXT
+        };
+        next.initialBashCommand = undefined;
+        next.initialBashContext = undefined;
+        next.images = undefined;
+        next.resume = null;
+        next.command = undefined;
+        await this.run(next).catch((error) => log(`the next work slice did not start: ${error instanceof Error ? error.message : String(error)}`));
+    }
     async start(input) {
         const { root } = this.env;
         if ((input.initialBashCommand !== undefined && input.initialBashCommand !== null) || (input.initialBashContext !== undefined && input.initialBashContext !== null)) {
@@ -222,8 +368,23 @@ export class Sessions {
                 throw invalid('An initial Bash command is available only for a new interactive user turn.');
             }
         }
+        let slicePolicy;
+        try {
+            slicePolicy = parseWorkSlice(input.workSlice);
+        }
+        catch (error) {
+            if (error instanceof WorkSliceError)
+                throw invalid(error.message);
+            throw error;
+        }
         const continuation = input.continueFrom ? continueInput(root, input) : null;
+        const previousRun = continuation ? loadRun(root, continuation.runId) : null;
+        const workspaceRoot = previousRun?.workspaceRoot
+            ? verifyWorkspaceRoot(previousRun.workspaceRoot)
+            : resolveWorkspaceRoot(previousRun?.workingDirectory ?? input.cwd);
         const historyFile = selectHistory({ sessionDir: input.sessionDir, resume: input.resume });
+        if (input.command)
+            checkCommand(input.command, historyFile, input);
         const account = this.options.accounts.resolve(input.accountId, input.poolId);
         const context = this.options.accounts.context(account);
         const runId = input.run.id;
@@ -239,7 +400,7 @@ export class Sessions {
         const canAskUser = pinnedAskUser || (interactivePlan && harnessToolsEnabled);
         const requestedTools = [...new Set([
                 ...input.tools.allow.filter((name) => name !== SPAWN_SUBAGENT && name !== WAIT_SUBAGENTS && (name !== ASK_USER || canAskUser)),
-                ...(harnessToolsEnabled ? [...(canAskUser ? [ASK_USER] : []), CHECKLIST_WRITE, SESSION_NAME, ...DEFAULT_TOOL_NAMES] : []),
+                ...(harnessToolsEnabled ? [...(canAskUser ? [ASK_USER] : []), TODO_WRITE, CHECKPOINT_WRITE, SESSION_NAME, GET_CAPABILITIES, ...DEFAULT_TOOL_NAMES] : []),
                 ...(broker?.toolNames ?? []),
                 ...(canSpawn ? [SPAWN_SUBAGENT, WAIT_SUBAGENTS] : [])
             ])];
@@ -276,6 +437,7 @@ export class Sessions {
             sessionId: input.run.sessionId,
             nativeSessionId: null,
             workingDirectory: input.cwd,
+            workspaceRoot,
             worktreeId: input.run.worktreeId ?? null,
             goal: input.run.goal ?? takeChars(input.text, 4000),
             attachmentCount: input.run.attachmentCount ?? 0,
@@ -290,7 +452,9 @@ export class Sessions {
             variantScope: variant?.scope ?? null,
             variantVersion: variant?.fingerprint ?? null,
             ...(input.run.profile ? { profile: input.run.profile } : {}),
-            ...(input.run.title ? { title: input.run.title } : {})
+            ...(input.run.title ? { title: input.run.title } : {}),
+            ...(input.model ? { model: input.model } : {}),
+            ...(input.effort ? { effort: input.effort } : {})
         });
         // What the session is, kept with the run so later consolidation knows which memory it had.
         try {
@@ -310,11 +474,18 @@ export class Sessions {
             if (!existsSync(input.sessionDir))
                 mkdirSync(input.sessionDir, { recursive: true });
             const launch = input.launch ?? {};
-            const plan = planSection(input.plan === true, historyFile);
+            const plan = planSection(input.plan === true, historyFile, input.run.relation === 'subagent');
             const delivered = historyFile ? deliveredSnapshot(historyFile) : null;
             const resumed = continuationSection(continuation, delivered?.some((entry) => entry.id === CONTINUATION_SECTION_ID) ?? false);
             // The profiles replace the variant's own subagent list, which they include.
-            const profiles = capabilities.tools.includes(SPAWN_SUBAGENT) ? profileSection(root, input.cwd, variant?.dir ?? null) : null;
+            const researchContext = input.plan === true ? {
+                frozenTools: capabilities.tools,
+                contributions: capabilities.contributions,
+                descriptors: BUILTIN_PLUGIN_REGISTRY.descriptors()
+            } : undefined;
+            const profiles = capabilities.tools.includes(SPAWN_SUBAGENT)
+                ? profileSection(root, input.cwd, variant?.dir ?? null, input.plan === true, researchContext)
+                : null;
             if (profiles && variant)
                 variant = { ...variant, sections: variant.sections.filter((section) => section.id !== profiles.id) };
             const own = [plan, resumed, profiles].filter((section) => section !== null);
@@ -331,6 +502,11 @@ export class Sessions {
             fail(error);
             throw error;
         }
+        // Plan-research children are bounded too, but their read-only capability set omits checkpoint_write.
+        const checkpointAvailable = capabilities.tools.includes(CHECKPOINT_WRITE);
+        const planResearchChild = input.plan === true && input.run.relation === 'subagent';
+        const sliceEnabled = slicePolicy.enabled && (checkpointAvailable || planResearchChild);
+        const sliceState = createSliceState(slicePolicy, sliceOf(root, runId));
         const run = this.options.runs.start(input.run.sessionId, runId);
         if (run.finished)
             return { runId, nativeSessionId: null };
@@ -353,6 +529,11 @@ export class Sessions {
         });
         try {
             const tools = [
+                ...(harnessToolsEnabled && allow.includes(GET_CAPABILITIES) ? [getCapabilitiesTool(() => ({
+                        capabilities,
+                        active: pi?.getActiveToolNames?.() ?? [],
+                        registered: pi?.getAllTools?.() ?? []
+                    }))] : []),
                 ...BUILTIN_PLUGIN_REGISTRY.tools({
                     env: this.options.env,
                     caller,
@@ -379,12 +560,15 @@ export class Sessions {
                 }
             }
             const readOnly = new Set(tools.filter((tool) => tool.readOnly).map((tool) => tool.name));
+            const checkpointPlanInstructions = input.plan
+                ? () => input.run.relation === 'subagent' ? PLAN_RESEARCH_SUBAGENT_INSTRUCTIONS : PLAN_INSTRUCTIONS
+                : undefined;
             const planModeSafety = new Map();
             for (const tool of tools)
                 if (tool.planModeSafe)
                     planModeSafety.set(tool.name, tool.planModeSafe);
             const gate = (() => {
-                const baseGate = this.gate(run, caller, new Set((input.tools.gated ?? []).filter((name) => capabilities.tools.includes(name))));
+                const baseGate = this.gate(run, caller, new Set((input.tools.gated ?? []).filter((name) => capabilities.tools.includes(name))), false, input.automatic === true);
                 return {
                     ...baseGate,
                     check: (name, args) => {
@@ -401,7 +585,9 @@ export class Sessions {
                 ...(input.initialBashContext !== undefined && input.initialBashContext !== null ? { initialBashContext: input.initialBashContext } : {}),
                 gate,
                 restrictTools: input.run.relation === 'subagent',
+                ...(input.plan ? { plan: true } : {}),
                 cwd: input.cwd,
+                workspaceRoot,
                 sessionDir: input.sessionDir,
                 historyFile,
                 model: input.model ?? null,
@@ -414,10 +600,20 @@ export class Sessions {
                 account: context,
                 resources: { ids: [], skillPaths: variant?.skillPaths ?? [], promptPaths: [] },
                 variantExtensions: variant?.extensionPaths ?? [],
-                inline: [...firstPartyFor(root, capabilities.contributions), runLineageJoin(root, runId), this.options.subagents.extension(runId), { name: 'image-pruning', factory: imagePruning() }],
+                inline: [
+                    ...firstPartyFor(root, capabilities.contributions),
+                    runLineageJoin(root, runId),
+                    this.options.subagents.extension(runId),
+                    { name: 'image-pruning', factory: imagePruning() },
+                    { name: COMPACTION_CHECKPOINT_EXTENSION, factory: compactionCheckpoint({ initialTodo: continuation?.todo, planInstructions: checkpointPlanInstructions }) },
+                    ...(sliceEnabled ? [{ name: WORK_SLICE_EXTENSION, factory: workSliceGuard({ policy: slicePolicy, state: sliceState, checkpointAvailable }) }] : [])
+                ],
                 ...(plugins ? { plugins: { loading: () => plugins.loading({ cwd: input.cwd, agentDir: context.configDir, install: true, caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null }, contributions: capabilities.contributions }), loaded: (extensions) => plugins.loaded(extensions) } } : {}),
                 system,
-                update
+                ...(sliceEnabled ? { slice: { state: sliceState, maxToolCalls: slicePolicy.maxToolCalls } } : {}),
+                // A command sends no request of its own, so the context update waits for the next turn.
+                update: input.command ? null : update,
+                ...(input.command ? { command: input.command } : {})
             };
             pi = await this.factory({
                 params,
@@ -440,12 +636,19 @@ export class Sessions {
                 throw new HarnessError('native_resume_unavailable', 'The saved conversation could not be restored.');
             }
             const opened = pi;
-            updateRun(root, runId, (record) => void (record.nativeSessionId = opened.sessionId));
+            const openedModel = pi.model?.id && pi.model.provider ? `${pi.model.provider}/${pi.model.id}` : null;
+            updateRun(root, runId, (record) => {
+                record.nativeSessionId = opened.sessionId;
+                if (openedModel)
+                    record.model = openedModel;
+                if (opened.thinkingLevel)
+                    record.effort = opened.thinkingLevel;
+            });
             this.options.subagents.register(input, account.id, capabilities, Boolean(pi.sessionManager));
-            if (pi.model?.id && pi.model.provider)
-                this.options.subagents.resolvedModel(runId, `${pi.model.provider}/${pi.model.id}`, pi.thinkingLevel);
+            if (openedModel)
+                this.options.subagents.resolvedModel(runId, openedModel, pi.thinkingLevel);
             params.settle = () => this.options.subagents.verify(runId, opened.sessionManager ? subagentHistory(opened.sessionManager.getBranch()) : undefined);
-            void runTurn(run, pi, params);
+            void runTurn(run, pi, params).then(() => (sliceEnabled && !input.command ? this.continueSlice({ root, runId, source: input, policy: slicePolicy }) : undefined));
             return { runId, nativeSessionId: pi.sessionId };
         }
         catch (error) {

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

@@ -14,7 +14,12 @@ type Started = {
 export type SpawnedSubagent = Started & {
     agent?: string;
     unavailableTools?: string[];
+    continued?: string;
 };
+export interface SubagentRuntimeSettings {
+    model: string | null;
+    effort: Effort | null;
+}
 export interface SubagentServiceOptions {
     /** The plugin descriptors, so a profile's plugin list can drop the tools those plugins own. */
     descriptors?: () => readonly PluginDescriptor[];
@@ -30,12 +35,31 @@ export declare class Subagents {
     private readonly launch;
     private readonly options;
     private readonly parents;
+    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;
+    private rememberRuntimeSettings;
     resolvedModel(runId: string, model: string, effort?: Effort): void;
     private parent;
+    private planSpawnCheck;
+    /** The plan-mode per-call gate and spawn implementation share this eligibility check. */
+    planSpawnRefusal(parentRunId: string, args: unknown): string | null;
     spawn(request: SubagentInput): Promise<SpawnedSubagent>;
+    /** Records ownership, starts the child, and writes a failed record when it never opened. */
+    private launchChild;
+    /** The children this parent may read or continue: its own, and those recovered from its history. */
+    private owned;
+    /** 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. */
+    private firstLink;
+    /**
+     * 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.
+     */
+    private continueChild;
     private selected;
     results(selection: SubagentSelection): SubagentResult[];
     wait(selection: SubagentSelection, signal?: AbortSignal): Promise<SubagentResult[]>;