@xingular/harness 1.0.0 → 1.2.0

package/dist/sdk/sessions/sessions.js

@@ -1,32 +1,61 @@
 // 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";
 import * as attachments from "../plugins/attachments.js";
 import { FIRST_PARTY_PLUGINS, firstPartyExtensions } from "../plugins/firstParty.js";
 import { imagePruning } from "../world/images.js";
 import { materialise } from "../variant/materialise.js";
-import { ASK_USER, askUserTool } from "../tools/askUser.js";
-import { CHECKLIST_WRITE, checklistTool } from "../tools/checklist.js";
+import { ASK_USER } from "../tools/askUser.js";
+import { CHECKLIST_WRITE } from "../tools/checklist.js";
+import { CHECKPOINT_WRITE, checkpointOf } from "../tools/checkpoint.js";
 import { SESSION_NAME, sessionNameTool } from "../tools/sessionName.js";
-import { subagentTools } from "../tools/spawnSubagent.js";
 import { DEFAULT_TOOL_NAMES } from "../tools/definitions.js";
-import { harnessTools } from "../tools/harnessTools.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) {
@@ -34,6 +63,10 @@ function continueInput(root, input) {
     if (!continuation.resumable || !continuation.resume)
         throw new HarnessError('continuation_unavailable', `Run ${input.continueFrom} cannot be continued (${continuation.reason ?? 'history_missing'}).`);
     const mismatch = (what) => new HarnessError('continuation_mismatch', `A continuation keeps the earlier run's ${what}.`);
+    if (continuation.capabilities?.tools.includes(ASK_USER)
+        && (input.automatic || ['probe', 'improver', 'reflection'].includes(input.run.trigger ?? ''))) {
+        throw mismatch('attended question capability');
+    }
     if (continuation.sessionId !== input.run.sessionId)
         throw mismatch('session');
     if (input.resume?.nativeSessionId && input.resume.nativeSessionId !== continuation.resume.nativeSessionId)
@@ -91,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) => {
@@ -99,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);
@@ -118,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
                 });
@@ -135,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;
+                }
             }
         };
     }
@@ -147,10 +253,96 @@ export class Sessions {
      * session that cannot be opened ends its run as failed and returns no native session id.
      */
     async run(input) {
-        const { root } = this.env;
         if (!input?.run?.id || !input.run.sessionId || typeof input.text !== 'string')
             throw invalid('A session turn needs a run id, a session, and text.');
         input = structuredClone(input);
+        const worktree = await this.enterWorktree(input);
+        try {
+            return await this.start(input);
+        }
+        catch (error) {
+            await worktree?.release();
+            throw error;
+        }
+    }
+    /**
+     * A run that names a worktree the harness manages works in that worktree's folder and holds it
+     * until the run settles. An id the harness does not know is kept as the caller's own field.
+     */
+    async enterWorktree(input) {
+        const id = input.run.worktreeId;
+        const worktrees = this.options.worktrees;
+        if (!id || !worktrees)
+            return null;
+        const path = worktrees.pathOf(id);
+        if (!path)
+            return null;
+        const holder = input.run.sessionId;
+        await worktrees.acquire(id, holder);
+        input.cwd = path;
+        let released = false;
+        const release = async () => {
+            if (released)
+                return;
+            released = true;
+            stop();
+            await worktrees.release(id, holder).catch(() => undefined);
+        };
+        const stop = this.options.runs.listen((event) => {
+            if (event.runId !== input.run.id)
+                return;
+            const settled = event.type === 'completed' || event.type === 'failed' || (event.type === 'status.changed' && event.payload.status === 'interrupted');
+            if (settled)
+                void release();
+        });
+        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)) {
             const request = input.text.trimStart();
             const requestedCommand = /^!\s*([\s\S]+)$/u.exec(request)?.[1];
@@ -176,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;
@@ -185,9 +392,15 @@ export class Sessions {
         const broker = input.connections ? this.options.broker : null;
         const depth = input.depth ?? 0;
         const canSpawn = input.subagents !== null && (!input.automatic || input.subagents !== undefined) && subagentNesting(root, input.run) < subagentDepth(input.subagents ?? undefined);
+        const pinnedAskUser = continuation?.capabilities?.tools.includes(ASK_USER) ?? false;
+        const interactivePlan = input.plan === true
+            && !input.automatic
+            && (input.run.trigger === undefined || input.run.trigger === null || input.run.trigger === 'user');
+        const harnessToolsEnabled = input.harnessTools !== false || pinnedAskUser;
+        const canAskUser = pinnedAskUser || (interactivePlan && harnessToolsEnabled);
         const requestedTools = [...new Set([
-                ...input.tools.allow.filter((name) => name !== SPAWN_SUBAGENT && name !== WAIT_SUBAGENTS),
-                ...(input.harnessTools === false ? [] : [ASK_USER, CHECKLIST_WRITE, SESSION_NAME, ...DEFAULT_TOOL_NAMES]),
+                ...input.tools.allow.filter((name) => name !== SPAWN_SUBAGENT && name !== WAIT_SUBAGENTS && (name !== ASK_USER || canAskUser)),
+                ...(harnessToolsEnabled ? [...(canAskUser ? [ASK_USER] : []), CHECKLIST_WRITE, CHECKPOINT_WRITE, SESSION_NAME, GET_CAPABILITIES, ...DEFAULT_TOOL_NAMES] : []),
                 ...(broker?.toolNames ?? []),
                 ...(canSpawn ? [SPAWN_SUBAGENT, WAIT_SUBAGENTS] : [])
             ])];
@@ -224,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,
@@ -236,7 +450,9 @@ export class Sessions {
             agentId: input.run.agentId ?? caller.agentId ?? null,
             trigger: input.run.trigger ?? null,
             variantScope: variant?.scope ?? null,
-            variantVersion: variant?.fingerprint ?? null
+            variantVersion: variant?.fingerprint ?? null,
+            ...(input.run.profile ? { profile: input.run.profile } : {}),
+            ...(input.run.title ? { title: input.run.title } : {})
         });
         // What the session is, kept with the run so later consolidation knows which memory it had.
         try {
@@ -256,10 +472,14 @@ 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);
-            const own = [plan, resumed].filter((section) => section !== null);
+            // 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, input.plan === true) : null;
+            if (profiles && variant)
+                variant = { ...variant, sections: variant.sections.filter((section) => section.id !== profiles.id) };
+            const own = [plan, resumed, profiles].filter((section) => section !== null);
             const effectiveLaunch = {
                 ...launch,
                 sections: own.length ? [...(launch.sections ?? []).filter((section) => !own.some((entry) => entry.id === section.id)), ...own] : launch.sections,
@@ -273,6 +493,9 @@ export class Sessions {
             fail(error);
             throw error;
         }
+        // A reply is bounded only when its checkpoint tool is part of the frozen capability set.
+        const sliceEnabled = slicePolicy.enabled && capabilities.tools.includes(CHECKPOINT_WRITE);
+        const sliceState = createSliceState(slicePolicy, sliceOf(root, runId));
         const run = this.options.runs.start(input.run.sessionId, runId);
         if (run.finished)
             return { runId, nativeSessionId: null };
@@ -295,9 +518,23 @@ export class Sessions {
         });
         try {
             const tools = [
-                ...(broker ? broker.tools(session, { readOnly: typeof input.connections === 'object' && input.connections.readOnly === true }) : []),
-                ...(input.harnessTools === false ? [] : [...harnessTools(this.options.env, caller, { variantDir: variant?.dir ?? null }), askUserTool(run), checklistTool(run), naming]),
-                ...subagentTools(this.options.subagents, runId).filter(tool => allow.includes(tool.name))
+                ...(harnessToolsEnabled && allow.includes(GET_CAPABILITIES) ? [getCapabilitiesTool(() => ({
+                        capabilities,
+                        active: pi?.getActiveToolNames?.() ?? [],
+                        registered: pi?.getAllTools?.() ?? []
+                    }))] : []),
+                ...BUILTIN_PLUGIN_REGISTRY.tools({
+                    env: this.options.env,
+                    caller,
+                    variantDir: variant?.dir ?? null,
+                    run,
+                    runId,
+                    allowedTools: allow,
+                    harnessTools: harnessToolsEnabled,
+                    subagents: this.options.subagents,
+                    sessionName: naming,
+                    ...(broker ? { connectionTools: () => broker.tools(session, { readOnly: typeof input.connections === 'object' && input.connections.readOnly === true }) } : {})
+                })
             ];
             if (input.providers !== false) {
                 const named = new Set(tools.map((tool) => tool.name));
@@ -312,12 +549,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) => {
@@ -334,7 +574,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,
@@ -347,10 +589,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({ initialChecklist: continuation?.checklist, planInstructions: checkpointPlanInstructions }) },
+                    ...(sliceEnabled ? [{ name: WORK_SLICE_EXTENSION, factory: workSliceGuard({ policy: slicePolicy, state: sliceState }) }] : [])
+                ],
                 ...(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,
@@ -378,7 +630,7 @@ export class Sessions {
             if (pi.model?.id && pi.model.provider)
                 this.options.subagents.resolvedModel(runId, `${pi.model.provider}/${pi.model.id}`, 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/sideQuestionServerMethods.d.ts

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function sideQuestionServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/sessions/sideQuestionServerMethods.js

@@ -0,0 +1,19 @@
+import { invalid } from "../core/errors.js";
+export function sideQuestionServerMethods(harness) {
+    return {
+        'sideQuestions.start': params => harness.sideQuestions.start(params),
+        'sideQuestions.read': params => {
+            if (typeof params.runId !== 'string' || typeof params.sessionId !== 'string')
+                throw invalid('A side-question run and session id are required.');
+            const afterSequence = params.afterSequence === undefined ? -1 : params.afterSequence;
+            if (typeof afterSequence !== 'number')
+                throw invalid('A side-question event sequence is required.');
+            return harness.sideQuestions.read(params.runId, params.sessionId, afterSequence);
+        },
+        'sideQuestions.interrupt': params => {
+            if (typeof params.runId !== 'string' || typeof params.sessionId !== 'string')
+                throw invalid('A side-question run and session id are required.');
+            return harness.sideQuestions.interrupt(params.runId, params.sessionId);
+        }
+    };
+}

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

@@ -0,0 +1,66 @@
+import type { RunEvent, RunRecord } from "./contracts.js";
+import type { RunRegistry } from "./registry.js";
+import type { SessionRunInput, Sessions } from "./sessions.js";
+import type { HarnessEnv } from "../core/env.js";
+import type { CallerContext } from "../core/caller.js";
+import type { Reference } from "../prompt/compile.js";
+export declare const SIDE_QUESTION_INSTRUCTION: string;
+export interface SideQuestionContext {
+    /** Used when the source has no Harness run event containing its effective system prompt. */
+    instructions?: string;
+    /** Visible conversation text and public progress supplied by the surface. */
+    transcript?: string;
+    /** References selected specifically for this side question, supplied as untrusted context data. */
+    references?: Reference[];
+}
+export interface SideQuestionStartInput {
+    /** Optional caller-reserved identifiers; the Harness creates these when omitted. */
+    runId?: string;
+    sessionId?: string;
+    /** The main run whose persisted prompt and public run events should be mirrored. */
+    parentRunId?: string | null;
+    /** The conversation session that owns parentRunId when the side run uses a fresh session id. */
+    parentSessionId?: string | null;
+    accountId?: string | null;
+    model?: string | null;
+    effort?: SessionRunInput['effort'];
+    cwd: string;
+    caller: CallerContext;
+    question: string;
+    context?: SideQuestionContext;
+}
+export interface SideQuestionRead {
+    run: RunRecord;
+    events: RunEvent[];
+}
+export interface BuildSideQuestionTextInput {
+    question: string;
+    context?: SideQuestionContext;
+    references?: readonly string[];
+    parentEvents?: readonly RunEvent[];
+    parentStatus?: string | null;
+}
+/** Bounded, redacted context copied into the side run's user message. */
+export declare function buildSideQuestionText(input: BuildSideQuestionTextInput): string;
+export interface SideQuestionsOptions {
+    env: HarnessEnv;
+    sessions: Sessions;
+    runs: RunRegistry;
+}
+/** A single Harness-owned side-question capability shared by hosts and the standalone terminal. */
+export declare class SideQuestions {
+    private readonly options;
+    private readonly sessionDirs;
+    private readonly unsubscribe;
+    constructor(options: SideQuestionsOptions);
+    start(raw: SideQuestionStartInput): Promise<{
+        runId: string;
+        sessionId: string;
+        nativeSessionId: string | null;
+    }>;
+    read(runId: string, sessionId: string, afterSequence?: number): SideQuestionRead;
+    interrupt(runId: string, sessionId: string): Promise<{
+        runId: string;
+    }>;
+    close(): Promise<void>;
+}