@robota-sdk/agent-subagent-runner 3.0.0-beta.82 → 3.0.0-beta.83

package/dist/node/index.cjs

@@ -1,2 +1,2 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("node:child_process"),t=require("node:fs"),n=require("node:path"),r=require("@robota-sdk/agent-executor"),i=require("@robota-sdk/agent-process"),a=require("@robota-sdk/agent-core"),o=require("@robota-sdk/agent-framework");function s(e){return{provider:{model:e.provider.model},permissions:e.permissions,defaultTrustLevel:e.defaultTrustLevel,...e.hooks===void 0?{}:{hooks:e.hooks}}}function c(e){return{agentsMd:e.agentsMd,projectNotesMd:e.projectNotesMd}}const l={name:{kind:`string`,required:!0},description:{kind:`string`,required:!0},systemPrompt:{kind:`string`,required:!0},model:{kind:`string`,required:!1},effort:{kind:`effort`,required:!1},role:{kind:`string`,required:!1},maxTurns:{kind:`number`,required:!1},tools:{kind:`string[]`,required:!1},disallowedTools:{kind:`string[]`,required:!1}},u={agentsMd:{kind:`string`,required:!0},projectNotesMd:{kind:`string`,required:!0},memoryMd:{kind:`string`,required:!1},taskContext:{kind:`string`,required:!1},compactInstructions:{kind:`string`,required:!1},agentsFileEntries:{kind:`file-entry[]`,required:!1},projectNotesFileEntries:{kind:`file-entry[]`,required:!1}};function d(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function ee(e){return Array.isArray(e)&&e.every(e=>typeof e==`string`)}function te(e){return d(e)&&typeof e.filePath==`string`&&typeof e.content==`string`&&typeof e.contentHash==`string`}function ne(e,t){switch(e){case`string`:return typeof t==`string`;case`number`:return typeof t==`number`&&Number.isFinite(t);case`effort`:return typeof t==`string`&&(0,a.isModelEffort)(t);case`string[]`:return ee(t);case`file-entry[]`:return Array.isArray(t)&&t.every(te)}}function f(e,t){let n={};for(let r of Object.keys(t)){let t=e[r];t!==void 0&&(n[r]=t)}return n}function p(e,t,n){if(!d(t))return{ok:!1,reason:`${e}: expected an object`};for(let[r,i]of Object.entries(n)){let n=t[r];if(n===void 0){if(i.required)return{ok:!1,reason:`${e}.${r}: required`};continue}if(!ne(i.kind,n))return{ok:!1,reason:`${e}.${r}: expected ${i.kind}`}}return{ok:!0,value:f(t,n)}}function m(e){return f(e,l)}function h(e){return p(`agentDefinition`,e,l)}function g(e){let t={name:e.name,description:e.description,systemPrompt:e.systemPrompt};return e.model!==void 0&&(t.model=e.model),e.effort!==void 0&&(t.effort=e.effort),e.role!==void 0&&(t.role=e.role),e.maxTurns!==void 0&&(t.maxTurns=e.maxTurns),e.tools!==void 0&&(t.tools=[...e.tools]),e.disallowedTools!==void 0&&(t.disallowedTools=[...e.disallowedTools]),t}function _(e){return f(e,u)}function v(e){return p(`parentContext`,e,u)}function y(e){let t={agentsMd:e.agentsMd,projectNotesMd:e.projectNotesMd};return e.memoryMd!==void 0&&(t.memoryMd=e.memoryMd),e.taskContext!==void 0&&(t.taskContext=e.taskContext),e.compactInstructions!==void 0&&(t.compactInstructions=e.compactInstructions),e.agentsFileEntries!==void 0&&(t.agentsFileEntries=e.agentsFileEntries.map(e=>({...e}))),e.projectNotesFileEntries!==void 0&&(t.projectNotesFileEntries=e.projectNotesFileEntries.map(e=>({...e}))),t}function b(e){return e.sessionTiers===void 0?{}:{sessionTiers:e.sessionTiers}}async function x(e){let{sandboxClient:t,sandboxType:n}=e;return t?.snapshot===void 0||n===void 0?{}:{sandboxProjection:{type:n,snapshotId:await t.snapshot()}}}function S(e,t,n,i,o){let s=n.providerDefinitions,c=(n.providerConfig??t.config.provider).name;if((0,a.findProviderDefinition)(s,c)===void 0)throw new r.BackgroundTaskError(`validation`,`No provider definition for "${c}" was given to the subagent runner, so the connection a child would make cannot be checked; the subagent was not started.`);let l=T(n.providerConfig,t,e,s),u=(0,r.connectionEnvironmentNames)(l,s),d=(0,r.findConnectionEnvironmentDivergence)(u,i,o);if(d!==void 0)throw new r.BackgroundTaskError(`validation`,`The subagent's environment sets ${d} differently from this session, which would change where its provider connects or which credential it sends; the subagent was not started.`);return{providerProfile:l,connectionCheck:(0,r.sealConnectionEnvironment)(u,o)}}function re(e,t,n){let r=ie(e.request.agentType,t.customAgentRegistry,t.builtInAgents,t.agentDefinitions),i={taskId:e.taskId,request:e.request,...e.worktree?{worktree:e.worktree}:{},agentDefinition:m(C(r,e)),parentConfig:s(t.getParentPermissionRules===void 0?t.config:{...t.config,permissions:t.getParentPermissionRules()}),parentContext:_(c(t.context)),...n.connection??S(e,t,n,process.env,process.env),permissionMode:t.permissionMode,...b(t),...n.logsDir?{logsDir:n.logsDir}:{}};return x(t).then(e=>({...i,...e}))}function ie(e,t,n,i){let a=t?.(e)??n?.find(t=>t.name===e)??i?.find(t=>t.name===e);if(!a)throw new r.BackgroundTaskError(`validation`,`Unknown agent type: ${e}`);return a}function C(e,t){return{...e,...t.request.model?{model:t.request.model}:{},...t.request.effort===void 0?{}:{effort:t.request.effort},...t.request.allowedTools?{tools:t.request.allowedTools}:{},...t.request.disallowedTools?{disallowedTools:t.request.disallowedTools}:{}}}function w(e,t){return e.apiKeyEnv===void 0?e.apiKey===void 0?t===void 0?{}:t.startsWith(`$ENV:`)?{apiKeyEnv:t.slice(5)}:{apiKey:t}:{apiKey:e.apiKey}:{apiKeyEnv:e.apiKeyEnv}}function T(e,t,n,r){let i=e??t.config.provider,o=(0,a.findProviderDefinition)(r,i.name)?.defaults??{},s=i.baseURL??o.baseURL,c=i.options??o.options,l=w(i,o.apiKey);return{...e===void 0&&t.config.currentProvider!==void 0?{profileName:t.config.currentProvider}:{},type:i.name,model:n.request.model??i.model,...l,...s===void 0?{}:{baseURL:s},...i.timeout===void 0?{}:{timeout:i.timeout},...c===void 0?{}:{options:c}}}function E(e){return typeof e==`object`&&!!e}function ae(e){if(!E(e)||!D(e,`nonce`)||!D(e,`digest`))return!1;let t=e.names;return Array.isArray(t)&&t.every(e=>typeof e==`string`)}function D(e,t){return typeof e[t]==`string`}function O(e,t){return D(e,t)}function oe(e,t){return D(e,t)}function se(e,t){return e[t]===void 0||typeof e[t]==`string`}function ce(e){if(e.usage===void 0)return!0;let t=e.usage;return E(t)?typeof t.promptTokens==`number`&&typeof t.completionTokens==`number`&&typeof t.totalTokens==`number`:!1}function k(e){if(e.composedToolNames===void 0)return!0;let t=e.composedToolNames;return Array.isArray(t)?t.every(e=>typeof e==`string`):!1}function A(e){return!E(e)||!oe(e,`taskId`)||!E(e.request)||!O(e.request,`agentType`)||!O(e.request,`prompt`)||!O(e.request,`permissionPolicy`)||!O(e.request,`cwd`)||!se(e.request,`resumeSessionId`)||e.worktree!==void 0&&(!E(e.worktree)||!D(e.worktree,`path`))||!h(e.agentDefinition).ok||!E(e.parentConfig)||!v(e.parentContext).ok||!E(e.providerProfile)||!D(e.providerProfile,`type`)||!D(e.providerProfile,`model`)?!1:ae(e.connectionCheck)}function j(e){if(!E(e)||!D(e,`type`))return!1;switch(e.type){case`start`:return A(e.payload);case`send`:return D(e,`prompt`);case`cancel`:return e.reason===void 0||typeof e.reason==`string`;default:return!1}}function M(e){if(!E(e)||!D(e,`type`))return!1;switch(e.type){case`ready`:return k(e);case`text_delta`:return D(e,`delta`);case`tool_start`:return D(e,`toolName`);case`tool_end`:return D(e,`toolName`)&&typeof e.success==`boolean`;case`result`:return D(e,`output`)&&ce(e);case`error`:return D(e,`message`);case`cancelled`:return e.reason===void 0||typeof e.reason==`string`;default:return!1}}const N=process.platform!==`win32`;function P(e,t){return new Promise(n=>{if(e.exitCode!==null||e.signalCode!==null){n();return}let r=setTimeout(()=>{e.removeListener(`exit`,i),n()},t);r.unref?.();let i=()=>{clearTimeout(r),n()};e.once(`exit`,i)})}const F=new WeakMap;function I(e){let t=e.stderr;if(!t)return;let n=(0,a.createBoundedOutput)({maxBytes:4096,retain:`tail`,truncationMarker:()=>``});F.set(e,n),t.on(`error`,()=>{}),t.on(`data`,e=>n.append(e))}function L(e){return(F.get(e)?.toString()??``).trim()}function R(e,t,n,i,a){switch(e.type){case`ready`:t();break;case`result`:n(e);break;case`error`:i(new r.BackgroundTaskError(`runner`,e.message));break;case`cancelled`:i(new r.BackgroundTaskError(`runner`,e.reason??`Subagent worker cancelled`));break;case`text_delta`:a?.({type:`background_task_text_delta`,delta:e.delta});break;case`tool_start`:a?.({type:`background_task_tool_start`,toolName:e.toolName,firstArg:z(e.toolArgs)});break;case`tool_end`:a?.({type:`background_task_tool_end`,toolName:e.toolName,success:e.success});break;default:i(new r.BackgroundTaskError(`runner`,`Unhandled subagent worker message`))}}function z(e){if(!e)return;let t=Object.values(e)[0];if(t!==void 0)return typeof t==`object`?JSON.stringify(t):String(t)}function B(e,t){return new Promise((n,i)=>{if(!e.connected){i(new r.BackgroundTaskError(`crash`,`Subagent worker IPC channel is closed`));return}e.send(t,e=>{if(e){i(e);return}n()})})}async function V(e,t){await(0,i.killProcessTree)(e.child,{graceMs:e.killGraceMs,processGroup:N,preKill:async()=>{e.child.connected&&(await B(e.child,{type:`cancel`,reason:t}).catch(()=>void 0),await P(e.child,e.killGraceMs))}})}function H(e){return new Promise((t,n)=>{new U(e,t,n).start()})}var U=class{options;resolve;reject;settled=!1;started=!1;ready=!1;timeoutTimer;handshakeTimer;handshakeBudgetMs;payload;constructor(e,t,n){this.options=e,this.resolve=t,this.reject=n;let i=e.handshakeBudgetMs;this.handshakeBudgetMs=i!==void 0&&i>0?i:3e4,this.payload=e.payload.catch(e=>{this.rejectOnce(e instanceof Error?e:Error(String(e)))}),this.timeoutTimer=G(this.options.runtime,e=>this.rejectOnce(e)),this.handshakeTimer=setTimeout(()=>{this.ready||this.settled||(V(this.options.runtime,`Subagent worker never signalled ready`),this.rejectOnce(new r.BackgroundTaskError(`runner`,`Subagent worker never signalled ready within ${this.handshakeBudgetMs}ms. Its entry must dispatch worker mode before starting the host application.`)))},this.handshakeBudgetMs),this.handshakeTimer.unref?.()}start(){let{child:e}=this.options.runtime;e.on(`message`,this.onMessage),e.on(`error`,this.onError),e.on(`exit`,this.onExit),e.once(`spawn`,()=>{setImmediate(this.startWorker)})}startWorker=()=>{if(this.started)return;this.started=!0;let{child:e}=this.options.runtime;this.payload.then(t=>t===void 0?void 0:B(e,{type:`start`,payload:t})).catch(e=>{this.rejectOnce(e instanceof Error?e:Error(String(e)))})};onMessage=e=>{if(!M(e)){this.rejectOnce(new r.BackgroundTaskError(`runner`,`Received malformed subagent worker message`));return}this.ready=!0,clearTimeout(this.handshakeTimer);let{job:t}=this.options.runtime;R(e,this.startWorker,this.resolveOnce,this.rejectOnce,t.emit)};onError=e=>{this.rejectOnce(new r.BackgroundTaskError(`crash`,e.message))};onExit=(e,t)=>{this.settled||this.rejectOnce(new r.BackgroundTaskError(`crash`,K(e,t,L(this.options.runtime.child))))};resolveOnce=e=>{if(this.settled)return;this.settled=!0,this.clearTimers(),this.cleanup();let{runtime:t,resolveTranscriptPath:n}=this.options;this.resolve(le(t.job,e,n))};rejectOnce=e=>{this.settled||(this.settled=!0,this.clearTimers(),this.cleanup(),this.reject(e))};clearTimers(){this.timeoutTimer&&clearTimeout(this.timeoutTimer),clearTimeout(this.handshakeTimer)}cleanup(){let{child:e}=this.options.runtime;e.off(`message`,this.onMessage),e.off(`error`,this.onError),e.off(`exit`,this.onExit)}};function W(e){let t=!1,n=()=>{};return{promise:new Promise((e,t)=>{n=t}),reject(i){t||(t=!0,n(new r.BackgroundTaskError(`runner`,i??`Subagent job cancelled: ${e}`)))}}}function G(e,t){if(e.job.request.timeoutMs)return setTimeout(()=>{V(e,`Subagent worker timed out`),t(new r.BackgroundTaskError(`timeout`,`Subagent worker timed out`))},e.job.request.timeoutMs)}function le(e,t,n){let r=n(e);return{taskId:e.taskId,output:t.output,...r?{metadata:{transcriptPath:r,logPath:r}}:{},...t.usage?{usage:t.usage}:{}}}function K(e,t,n){return`Subagent worker exited before result: ${t===null?`exit code ${e===null?`unknown`:e}`:`signal ${t}`}${n.length>0?`: ${n}`:``}`}const q=`--__robota-subagent-worker`;function ue(e){return e.includes(q)}const de=process.platform!==`win32`;function fe(e){return t=>{let n=new J(t,e);return e.worktreeIsolation===!1?n:(0,r.createWorktreeSubagentRunner)({runner:n,worktreeAdapter:e.worktreeAdapter,hooks:t.config.hooks,hookTypeExecutors:t.hookTypeExecutors})}}var J=class{deps;workerEntry;killGraceMs;handshakeBudgetMs;providerConfig;providerDefinitions;env;logsDir;constructor(e,t){this.deps=e,this.workerEntry=t.workerEntry,this.killGraceMs=t.killGraceMs??i.DEFAULT_KILL_GRACE_MS,this.handshakeBudgetMs=t.handshakeBudgetMs,this.providerConfig=t.providerConfig,this.providerDefinitions=t.providerDefinitions,this.env=t.env,this.logsDir=t.logsDir}start(t){let n=this.workerEntry,i={...process.env,...this.env??{}},a=S(t,this.deps,{...this.providerConfig===void 0?{}:{providerConfig:this.providerConfig},providerDefinitions:this.providerDefinitions},process.env,i),o=(0,e.spawn)(n.execPath,[...n.execArgv??[],...n.args,q],{cwd:(0,r.subagentExecutionRoot)(t),env:i,stdio:[`ignore`,`ignore`,`pipe`,`ipc`],detached:de});I(o);let s={job:t,child:o,killGraceMs:this.killGraceMs},c=H({runtime:s,payload:this.createStartPayload(t,a),...this.handshakeBudgetMs===void 0?{}:{handshakeBudgetMs:this.handshakeBudgetMs},resolveTranscriptPath:e=>this.resolveTranscriptPath(e)}),l=W(t.taskId);c.catch(()=>void 0);let u=Promise.race([c,l.promise]);u.catch(()=>void 0);let d=this.resolveTranscriptPath(t);return{taskId:t.taskId,...o.pid!==void 0&&{pid:o.pid},...d!==void 0&&{transcriptPath:d,logPath:d},result:u,cancel:async e=>{l.reject(e),await V(s,e)},send:async e=>{await B(o,{type:`send`,prompt:e})},...d!==void 0&&{readLog:async e=>pe(t.taskId,d,e)}}}createStartPayload(e,t){return re(e,this.deps,{connection:t,providerDefinitions:this.providerDefinitions,...this.logsDir===void 0?{}:{logsDir:this.logsDir}})}resolveTranscriptPath(e){if(this.logsDir)return(0,n.join)(this.logsDir,e.request.parentSessionId,`subagents`,`${e.taskId}.jsonl`)}};function pe(e,n,i){return(0,t.existsSync)(n)?(0,r.createBackgroundTaskLogPage)(e,(0,t.readFileSync)(n,`utf8`).split(/\r?\n/).filter(Boolean),i):{taskId:e,cursor:i,lines:[]}}function me(e,t,n){let r=e.request.resumeSessionId;if(r!==void 0){if(n===void 0)throw Error(`subagent worker: job ${e.taskId} asks to resume session ${r}, but this composition opens no session store. Register ISubagentWorkerComposition.openSessionStore at the composition root — the same place providerDefinitions is registered.`);(0,o.restoreSessionRecordIntoSession)(n,r,t)}}function he(e,t){let n=e.request.resumeSessionId;if(n!==void 0){if(t.openSessionStore===void 0)throw Error(`subagent worker: job ${e.taskId} asks to resume session ${n}, but this composition opens no session store. Register ISubagentWorkerComposition.openSessionStore at the composition root — the same place providerDefinitions is registered.`);return t.openSessionStore({cwd:e.request.cwd})}}async function ge(e,t){if(e===void 0)return;let n=t?.[e.type];if(n===void 0)throw Error(`subagent worker: sandbox type "${e.type}" is not registered in the worker composition. The parent is sandboxed and passed a snapshot reference, but this child cannot construct that client type. Register it in ISubagentWorkerComposition.sandboxFactories at the composition root — the same place providerDefinitions is registered, and for the same reason.`);return n(e.snapshotId)}const _e={write:()=>{},writeLine:()=>{},writeMarkdown:()=>{},writeError:()=>{},prompt:()=>Promise.resolve(``),select:()=>Promise.resolve(0),spinner:()=>({stop:()=>{},update:()=>{}})};let Y=null,X=!1,Z=Promise.resolve();function Q(e){process.send&&process.send(e)}function $(e,t){let n=!1,r=()=>{n||(n=!0,process.exit(t))};if(process.send){let t=setTimeout(r,2e3);t.unref?.(),process.send(e,void 0,void 0,()=>{clearTimeout(t),r()})}else r()}function ve(e){try{return(0,a.sumHistoryUsage)(e.getFullHistory())}catch{return}}async function ye(e,t){try{if(!(0,r.verifyConnectionEnvironment)(e.connectionCheck,process.env))throw Error(`The provider connection environment changed after the parent checked it; the subagent was not started.`);let n=await ge(e.sandboxProjection,t.sandboxFactories),i=(0,r.createProviderFromExactProfile)(e.providerProfile,e.request.model,t.providerDefinitions),a=e.logsDir?(0,o.createSubagentLogger)(e.request.parentSessionId,e.taskId,e.logsDir):void 0,s=he(e,t);Y=(0,o.createSubagentSession)({agentDefinition:g(e.agentDefinition),parentConfig:e.parentConfig,parentContext:y(e.parentContext),parentTools:t.createTools({cwd:(0,r.subagentExecutionRoot)(e),...n===void 0?{}:{sandboxClient:n},...e.sessionTiers===void 0?{}:{sessionTiers:e.sessionTiers}}),cwd:(0,r.subagentExecutionRoot)(e),provider:i,terminal:_e,sessionId:e.request.resumeSessionId??e.taskId,...s===void 0?{}:{sessionStore:s},...a?{sessionLogger:a}:{},permissionMode:e.permissionMode,...e.request.permissionPolicy===void 0?{}:{permissionPolicy:e.request.permissionPolicy},...e.request.allowedTools===void 0?{}:{taskAllowedTools:e.request.allowedTools},...e.request.disallowedTools===void 0?{}:{taskDisallowedTools:e.request.disallowedTools},hooks:e.parentConfig.hooks,...t.createHookTypeExecutors===void 0?{}:{hookTypeExecutors:t.createHookTypeExecutors()},onTextDelta:e=>Q({type:`text_delta`,delta:e}),onToolExecution:be}),me(e,Y,s);let c=await Y.run(e.request.prompt);if(X){$({type:`cancelled`,reason:`Subagent worker cancelled`},130);return}let l=ve(Y);$({type:`result`,output:c,...l?{usage:l}:{}},0)}catch(e){if(X){$({type:`cancelled`,reason:`Subagent worker cancelled`},130);return}$({type:`error`,message:e instanceof Error?e.message:String(e)},0)}}function be(e){if(e.type===`start`){Q({type:`tool_start`,toolName:e.toolName,toolArgs:e.toolArgs});return}Q({type:`tool_end`,toolName:e.toolName,success:e.success??!0})}function xe(e){if(Y===null){Q({type:`error`,message:`Subagent worker has not started`});return}Z=Z.then(async()=>{try{await Y?.run(e)}catch(e){Q({type:`error`,message:e instanceof Error?e.message:String(e)})}})}async function Se(e){X=!0,Y?.abort(),Q({type:`cancelled`,reason:e}),await Y?.shutdown({reason:`other`}).catch(()=>void 0),setTimeout(()=>process.exit(130),0)}function Ce(e){try{return e.createTools({cwd:process.cwd()}).map(e=>e.getName())}catch(e){process.stderr.write(`robota: could not enumerate the composed tool surface: ${e instanceof Error?e.message:String(e)}\n`);return}}function we(e){process.send===void 0&&(process.stderr.write(`robota: subagent worker mode requires an IPC channel; it is started by the agent runtime, not by hand.
-`),process.exit(2)),process.on(`message`,t=>{if(!j(t)){Q({type:`error`,message:`Malformed subagent worker parent message`});return}switch(t.type){case`start`:Z=Z.then(()=>ye(t.payload,e));break;case`send`:xe(t.prompt);break;case`cancel`:Se(t.reason);break;default:Q({type:`error`,message:`Unhandled subagent worker parent message`})}}),process.on(`disconnect`,()=>{X=!0,Y?.abort(),Y?.shutdown({reason:`other`}).catch(()=>void 0)});let t=Ce(e);Q({type:`ready`,...t?{composedToolNames:t}:{}})}exports.ChildProcessSubagentRunner=J,exports.SUBAGENT_WORKER_MODE_FLAG=q,exports.createChildProcessSubagentRunnerFactory=fe,exports.decodeAgentDefinitionDto=h,exports.decodeParentContextDto=v,exports.encodeAgentDefinition=m,exports.encodeParentContext=_,exports.isSubagentWorkerChildMessage=M,exports.isSubagentWorkerModeArgv=ue,exports.isSubagentWorkerParentMessage=j,exports.restoreAgentDefinition=g,exports.restoreParentContext=y,exports.runSubagentWorkerMain=we;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("node:child_process"),t=require("node:fs"),n=require("node:path"),r=require("@robota-sdk/agent-executor"),i=require("@robota-sdk/agent-process"),a=require("@robota-sdk/agent-core"),o=require("@robota-sdk/agent-framework");function s(e){return{provider:{model:e.provider.model},permissions:e.permissions,defaultTrustLevel:e.defaultTrustLevel,...e.hooks===void 0?{}:{hooks:e.hooks}}}function c(e){return{agentsMd:e.agentsMd,projectNotesMd:e.projectNotesMd}}const l={name:{kind:`string`,required:!0},description:{kind:`string`,required:!0},systemPrompt:{kind:`string`,required:!0},model:{kind:`string`,required:!1},effort:{kind:`effort`,required:!1},role:{kind:`string`,required:!1},maxTurns:{kind:`number`,required:!1},tools:{kind:`string[]`,required:!1},disallowedTools:{kind:`string[]`,required:!1}},u={agentsMd:{kind:`string`,required:!0},projectNotesMd:{kind:`string`,required:!0},memoryMd:{kind:`string`,required:!1},taskContext:{kind:`string`,required:!1},compactInstructions:{kind:`string`,required:!1},agentsFileEntries:{kind:`file-entry[]`,required:!1},projectNotesFileEntries:{kind:`file-entry[]`,required:!1}};function d(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function f(e){return Array.isArray(e)&&e.every(e=>typeof e==`string`)}function p(e){return d(e)&&typeof e.filePath==`string`&&typeof e.content==`string`&&typeof e.contentHash==`string`}function ee(e,t){switch(e){case`string`:return typeof t==`string`;case`number`:return typeof t==`number`&&Number.isFinite(t);case`effort`:return typeof t==`string`&&(0,a.isModelEffort)(t);case`string[]`:return f(t);case`file-entry[]`:return Array.isArray(t)&&t.every(p)}}function m(e,t){let n={};for(let r of Object.keys(t)){let t=e[r];t!==void 0&&(n[r]=t)}return n}function h(e,t,n){if(!d(t))return{ok:!1,reason:`${e}: expected an object`};for(let[r,i]of Object.entries(n)){let n=t[r];if(n===void 0){if(i.required)return{ok:!1,reason:`${e}.${r}: required`};continue}if(!ee(i.kind,n))return{ok:!1,reason:`${e}.${r}: expected ${i.kind}`}}return{ok:!0,value:m(t,n)}}function g(e){return m(e,l)}function _(e){return h(`agentDefinition`,e,l)}function v(e){let t={name:e.name,description:e.description,systemPrompt:e.systemPrompt};return e.model!==void 0&&(t.model=e.model),e.effort!==void 0&&(t.effort=e.effort),e.role!==void 0&&(t.role=e.role),e.maxTurns!==void 0&&(t.maxTurns=e.maxTurns),e.tools!==void 0&&(t.tools=[...e.tools]),e.disallowedTools!==void 0&&(t.disallowedTools=[...e.disallowedTools]),t}function y(e){return m(e,u)}function b(e){return h(`parentContext`,e,u)}function x(e){let t={agentsMd:e.agentsMd,projectNotesMd:e.projectNotesMd};return e.memoryMd!==void 0&&(t.memoryMd=e.memoryMd),e.taskContext!==void 0&&(t.taskContext=e.taskContext),e.compactInstructions!==void 0&&(t.compactInstructions=e.compactInstructions),e.agentsFileEntries!==void 0&&(t.agentsFileEntries=e.agentsFileEntries.map(e=>({...e}))),e.projectNotesFileEntries!==void 0&&(t.projectNotesFileEntries=e.projectNotesFileEntries.map(e=>({...e}))),t}function te(e){return e.sessionTiers===void 0?{}:{sessionTiers:e.sessionTiers}}async function ne(e){let{sandboxClient:t,sandboxType:n}=e;return t?.snapshot===void 0||n===void 0?{}:{sandboxProjection:{type:n,snapshotId:await t.snapshot()}}}function S(e,t,n,i,o){let s=n.providerDefinitions,c=(n.providerConfig??t.config.provider).name;if((0,a.findProviderDefinition)(s,c)===void 0)throw new r.BackgroundTaskError(`validation`,`No provider definition for "${c}" was given to the subagent runner, so the connection a child would make cannot be checked; the subagent was not started.`);let l=oe(n.providerConfig,t,e,s),u=(0,r.connectionEnvironmentNames)(l,s),d=(0,r.findConnectionEnvironmentDivergence)(u,i,o);if(d!==void 0)throw new r.BackgroundTaskError(`validation`,`The subagent's environment sets ${d} differently from this session, which would change where its provider connects or which credential it sends; the subagent was not started.`);return{providerProfile:l,connectionCheck:(0,r.sealConnectionEnvironment)(u,o)}}function re(e,t,n){let r=ie(e.request.agentType,t.customAgentRegistry,t.builtInAgents,t.agentDefinitions),i={taskId:e.taskId,request:e.request,...e.worktree?{worktree:e.worktree}:{},agentDefinition:g(ae(r,e)),parentConfig:s(t.getParentPermissionRules===void 0?t.config:{...t.config,permissions:t.getParentPermissionRules()}),parentContext:y(c(t.context)),...n.connection??S(e,t,n,process.env,process.env),permissionMode:t.permissionMode,...te(t),...n.parentSandboxSettings===void 0?{}:{parentSandboxSettings:n.parentSandboxSettings},...n.logsDir?{logsDir:n.logsDir}:{}};return ne(t).then(e=>({...i,...e}))}function ie(e,t,n,i){let a=t?.(e)??n?.find(t=>t.name===e)??i?.find(t=>t.name===e);if(!a)throw new r.BackgroundTaskError(`validation`,`Unknown agent type: ${e}`);return a}function ae(e,t){return{...e,...t.request.model?{model:t.request.model}:{},...t.request.effort===void 0?{}:{effort:t.request.effort},...t.request.allowedTools?{tools:t.request.allowedTools}:{},...t.request.disallowedTools?{disallowedTools:t.request.disallowedTools}:{}}}function C(e,t){return e.apiKeyEnv===void 0?e.apiKey===void 0?t===void 0?{}:t.startsWith(`$ENV:`)?{apiKeyEnv:t.slice(5)}:{apiKey:t}:{apiKey:e.apiKey}:{apiKeyEnv:e.apiKeyEnv}}function oe(e,t,n,r){let i=e??t.config.provider,o=(0,a.findProviderDefinition)(r,i.name)?.defaults??{},s=i.baseURL??o.baseURL,c=i.options??o.options,l=C(i,o.apiKey);return{...e===void 0&&t.config.currentProvider!==void 0?{profileName:t.config.currentProvider}:{},type:i.name,model:n.request.model??i.model,...l,...s===void 0?{}:{baseURL:s},...i.timeout===void 0?{}:{timeout:i.timeout},...c===void 0?{}:{options:c}}}function w(e){return typeof e==`object`&&!!e}function T(e){if(!w(e)||!E(e,`nonce`)||!E(e,`digest`))return!1;let t=e.names;return Array.isArray(t)&&t.every(e=>typeof e==`string`)}function E(e,t){return typeof e[t]==`string`}function D(e,t){return E(e,t)}function se(e,t){return E(e,t)}function ce(e,t){return e[t]===void 0||typeof e[t]==`string`}function le(e){if(e.usage===void 0)return!0;let t=e.usage;return w(t)?typeof t.promptTokens==`number`&&typeof t.completionTokens==`number`&&typeof t.totalTokens==`number`:!1}function ue(e){if(e.composedToolNames===void 0)return!0;let t=e.composedToolNames;return Array.isArray(t)?t.every(e=>typeof e==`string`):!1}function de(e){return!w(e)||!se(e,`taskId`)||!w(e.request)||!D(e.request,`agentType`)||!D(e.request,`prompt`)||!D(e.request,`permissionPolicy`)||!D(e.request,`cwd`)||!ce(e.request,`resumeSessionId`)||e.worktree!==void 0&&(!w(e.worktree)||!E(e.worktree,`path`))||!_(e.agentDefinition).ok||!w(e.parentConfig)||!b(e.parentContext).ok||!w(e.providerProfile)||!E(e.providerProfile,`type`)||!E(e.providerProfile,`model`)||e.parentSandboxSettings!==void 0&&!w(e.parentSandboxSettings)?!1:T(e.connectionCheck)}function O(e){if(!w(e)||!E(e,`type`))return!1;switch(e.type){case`start`:return de(e.payload);case`send`:return E(e,`prompt`);case`cancel`:return e.reason===void 0||typeof e.reason==`string`;case`sandbox_settings`:return w(e.settings);default:return!1}}function k(e){if(!w(e)||!E(e,`type`))return!1;switch(e.type){case`ready`:return ue(e);case`text_delta`:return E(e,`delta`);case`tool_start`:return E(e,`toolName`);case`tool_end`:return E(e,`toolName`)&&typeof e.success==`boolean`;case`result`:return E(e,`output`)&&le(e);case`error`:return E(e,`message`);case`cancelled`:return e.reason===void 0||typeof e.reason==`string`;default:return!1}}const A=process.platform!==`win32`;function j(e,t){return new Promise(n=>{if(e.exitCode!==null||e.signalCode!==null){n();return}let r=setTimeout(()=>{e.removeListener(`exit`,i),n()},t);r.unref?.();let i=()=>{clearTimeout(r),n()};e.once(`exit`,i)})}const M=new WeakMap;function N(e){let t=e.stderr;if(!t)return;let n=(0,a.createBoundedOutput)({maxBytes:4096,retain:`tail`,truncationMarker:()=>``});M.set(e,n),t.on(`error`,()=>{}),t.on(`data`,e=>n.append(e))}function P(e){return(M.get(e)?.toString()??``).trim()}function F(e,t,n,i,a){switch(e.type){case`ready`:t();break;case`result`:n(e);break;case`error`:i(new r.BackgroundTaskError(`runner`,e.message));break;case`cancelled`:i(new r.BackgroundTaskError(`runner`,e.reason??`Subagent worker cancelled`));break;case`text_delta`:a?.({type:`background_task_text_delta`,delta:e.delta});break;case`tool_start`:a?.({type:`background_task_tool_start`,toolName:e.toolName,firstArg:I(e.toolArgs)});break;case`tool_end`:a?.({type:`background_task_tool_end`,toolName:e.toolName,success:e.success});break;default:i(new r.BackgroundTaskError(`runner`,`Unhandled subagent worker message`))}}function I(e){if(!e)return;let t=Object.values(e)[0];if(t!==void 0)return typeof t==`object`?JSON.stringify(t):String(t)}function L(e,t){return new Promise((n,i)=>{if(!e.connected){i(new r.BackgroundTaskError(`crash`,`Subagent worker IPC channel is closed`));return}e.send(t,e=>{if(e){i(e);return}n()})})}async function R(e,t){await(0,i.killProcessTree)(e.child,{graceMs:e.killGraceMs,processGroup:A,preKill:async()=>{e.child.connected&&(await L(e.child,{type:`cancel`,reason:t}).catch(()=>void 0),await j(e.child,e.killGraceMs))}})}function z(e){return new Promise((t,n)=>{new B(e,t,n).start()})}var B=class{options;resolve;reject;settled=!1;started=!1;ready=!1;timeoutTimer;handshakeTimer;handshakeBudgetMs;payload;constructor(e,t,n){this.options=e,this.resolve=t,this.reject=n;let i=e.handshakeBudgetMs;this.handshakeBudgetMs=i!==void 0&&i>0?i:3e4,this.payload=e.payload.catch(e=>{this.rejectOnce(e instanceof Error?e:Error(String(e)))}),this.timeoutTimer=H(this.options.runtime,e=>this.rejectOnce(e)),this.handshakeTimer=setTimeout(()=>{this.ready||this.settled||(R(this.options.runtime,`Subagent worker never signalled ready`),this.rejectOnce(new r.BackgroundTaskError(`runner`,`Subagent worker never signalled ready within ${this.handshakeBudgetMs}ms. Its entry must dispatch worker mode before starting the host application.`)))},this.handshakeBudgetMs),this.handshakeTimer.unref?.()}start(){let{child:e}=this.options.runtime;e.on(`message`,this.onMessage),e.on(`error`,this.onError),e.on(`exit`,this.onExit),e.once(`spawn`,()=>{setImmediate(this.startWorker)})}startWorker=()=>{if(this.started)return;this.started=!0;let{child:e}=this.options.runtime;this.payload.then(t=>t===void 0?void 0:L(e,{type:`start`,payload:t})).catch(e=>{this.rejectOnce(e instanceof Error?e:Error(String(e)))})};onMessage=e=>{if(!k(e)){this.rejectOnce(new r.BackgroundTaskError(`runner`,`Received malformed subagent worker message`));return}this.ready=!0,clearTimeout(this.handshakeTimer);let{job:t}=this.options.runtime;F(e,this.startWorker,this.resolveOnce,this.rejectOnce,t.emit)};onError=e=>{this.rejectOnce(new r.BackgroundTaskError(`crash`,e.message))};onExit=(e,t)=>{this.settled||this.rejectOnce(new r.BackgroundTaskError(`crash`,pe(e,t,P(this.options.runtime.child))))};resolveOnce=e=>{if(this.settled)return;this.settled=!0,this.clearTimers(),this.cleanup();let{runtime:t,resolveTranscriptPath:n}=this.options;this.resolve(fe(t.job,e,n))};rejectOnce=e=>{this.settled||(this.settled=!0,this.clearTimers(),this.cleanup(),this.reject(e))};clearTimers(){this.timeoutTimer&&clearTimeout(this.timeoutTimer),clearTimeout(this.handshakeTimer)}cleanup(){let{child:e}=this.options.runtime;e.off(`message`,this.onMessage),e.off(`error`,this.onError),e.off(`exit`,this.onExit)}};function V(e){let t=!1,n=()=>{};return{promise:new Promise((e,t)=>{n=t}),reject(i){t||(t=!0,n(new r.BackgroundTaskError(`runner`,i??`Subagent job cancelled: ${e}`)))}}}function H(e,t){if(e.job.request.timeoutMs)return setTimeout(()=>{R(e,`Subagent worker timed out`),t(new r.BackgroundTaskError(`timeout`,`Subagent worker timed out`))},e.job.request.timeoutMs)}function fe(e,t,n){let r=n(e);return{taskId:e.taskId,output:t.output,...r?{metadata:{transcriptPath:r,logPath:r}}:{},...t.usage?{usage:t.usage}:{}}}function pe(e,t,n){return`Subagent worker exited before result: ${t===null?`exit code ${e===null?`unknown`:e}`:`signal ${t}`}${n.length>0?`: ${n}`:``}`}const U=`--__robota-subagent-worker`;function me(e){return e.includes(U)}const he=process.platform!==`win32`;function ge(e){return t=>{let n=new W(t,e);return e.worktreeIsolation===!1?n:(0,r.createWorktreeSubagentRunner)({runner:n,worktreeAdapter:e.worktreeAdapter,hooks:t.config.hooks,hookTypeExecutors:t.hookTypeExecutors})}}var W=class{deps;workerEntry;killGraceMs;handshakeBudgetMs;providerConfig;providerDefinitions;env;logsDir;parentSandboxSettings;watchParentSandboxSettings;constructor(e,t){this.deps=e,this.workerEntry=t.workerEntry,this.killGraceMs=t.killGraceMs??i.DEFAULT_KILL_GRACE_MS,this.handshakeBudgetMs=t.handshakeBudgetMs,this.providerConfig=t.providerConfig,this.providerDefinitions=t.providerDefinitions,this.env=t.env,this.logsDir=t.logsDir,this.parentSandboxSettings=t.parentSandboxSettings,this.watchParentSandboxSettings=t.watchParentSandboxSettings}start(t){let n=this.workerEntry,i={...process.env,...this.env??{}},a=S(t,this.deps,{...this.providerConfig===void 0?{}:{providerConfig:this.providerConfig},providerDefinitions:this.providerDefinitions},process.env,i),o=(0,e.spawn)(n.execPath,[...n.execArgv??[],...n.args,U],{cwd:(0,r.subagentExecutionRoot)(t),env:i,stdio:[`ignore`,`ignore`,`pipe`,`ipc`],detached:he});N(o),this.forwardSandboxSettingChanges(o);let s={job:t,child:o,killGraceMs:this.killGraceMs},c=z({runtime:s,payload:this.createStartPayload(t,a),...this.handshakeBudgetMs===void 0?{}:{handshakeBudgetMs:this.handshakeBudgetMs},resolveTranscriptPath:e=>this.resolveTranscriptPath(e)}),l=V(t.taskId);c.catch(()=>void 0);let u=Promise.race([c,l.promise]);u.catch(()=>void 0);let d=this.resolveTranscriptPath(t);return{taskId:t.taskId,...o.pid!==void 0&&{pid:o.pid},...d!==void 0&&{transcriptPath:d,logPath:d},result:u,cancel:async e=>{l.reject(e),await R(s,e)},send:async e=>{await L(o,{type:`send`,prompt:e})},...d!==void 0&&{readLog:async e=>_e(t.taskId,d,e)}}}createStartPayload(e,t){let n=this.parentSandboxSettings?.();return re(e,this.deps,{connection:t,providerDefinitions:this.providerDefinitions,...this.logsDir===void 0?{}:{logsDir:this.logsDir},...n===void 0?{}:{parentSandboxSettings:n}})}forwardSandboxSettingChanges(e){let t=this.watchParentSandboxSettings?.(t=>{e.connected&&L(e,{type:`sandbox_settings`,settings:t}).catch(()=>void 0)});t!==void 0&&(e.once(`exit`,t),e.once(`error`,t))}resolveTranscriptPath(e){if(this.logsDir)return(0,n.join)(this.logsDir,e.request.parentSessionId,`subagents`,`${e.taskId}.jsonl`)}};function _e(e,n,i){return(0,t.existsSync)(n)?(0,r.createBackgroundTaskLogPage)(e,(0,t.readFileSync)(n,`utf8`).split(/\r?\n/).filter(Boolean),i):{taskId:e,cursor:i,lines:[]}}function ve(e,t,n){let r=e.request.resumeSessionId;if(r!==void 0){if(n===void 0)throw Error(`subagent worker: job ${e.taskId} asks to resume session ${r}, but this composition opens no session store. Register ISubagentWorkerComposition.openSessionStore at the composition root — the same place providerDefinitions is registered.`);(0,o.restoreSessionRecordIntoSession)(n,r,t)}}function ye(e,t){let n=e.request.resumeSessionId;if(n!==void 0){if(t.openSessionStore===void 0)throw Error(`subagent worker: job ${e.taskId} asks to resume session ${n}, but this composition opens no session store. Register ISubagentWorkerComposition.openSessionStore at the composition root — the same place providerDefinitions is registered.`);return t.openSessionStore({cwd:e.request.cwd})}}async function be(e,t){if(e===void 0)return;let n=t?.[e.type];if(n===void 0)throw Error(`subagent worker: sandbox type "${e.type}" is not registered in the worker composition. The parent is sandboxed and passed a snapshot reference, but this child cannot construct that client type. Register it in ISubagentWorkerComposition.sandboxFactories at the composition root — the same place providerDefinitions is registered, and for the same reason.`);return n(e.snapshotId)}const xe={write:()=>{},writeLine:()=>{},writeMarkdown:()=>{},writeError:()=>{},prompt:()=>Promise.resolve(``),select:()=>Promise.resolve(0),spinner:()=>({stop:()=>{},update:()=>{}})};let G=null,K=!1,q,J,Y,X=Promise.resolve();function Z(e){process.send&&process.send(e)}function Q(e,t){let n=!1,r=()=>{n||(n=!0,process.exit(t))};if(process.send){let t=setTimeout(r,2e3);t.unref?.(),process.send(e,void 0,void 0,()=>{clearTimeout(t),r()})}else r()}function Se(e){try{return(0,a.sumHistoryUsage)(e.getFullHistory())}catch{return}}async function $(e,t){try{if(!(0,r.verifyConnectionEnvironment)(e.connectionCheck,process.env))throw Error(`The provider connection environment changed after the parent checked it; the subagent was not started.`);let n=await be(e.sandboxProjection,t.sandboxFactories),i=(0,r.createProviderFromExactProfile)(e.providerProfile,e.request.model,t.providerDefinitions),a=e.logsDir?(0,o.createSubagentLogger)(e.request.parentSessionId,e.taskId,e.logsDir):void 0,s=ye(e,t),c=q??e.parentSandboxSettings;J=n===void 0?t.createSandbox?.({cwd:(0,r.subagentExecutionRoot)(e),...c===void 0?{}:{parentSettings:c}}):void 0;let l=n??J?.client;G=(0,o.createSubagentSession)({agentDefinition:v(e.agentDefinition),parentConfig:e.parentConfig,parentContext:x(e.parentContext),parentTools:t.createTools({cwd:(0,r.subagentExecutionRoot)(e),...l===void 0?{}:{sandboxClient:l},...e.sessionTiers===void 0?{}:{sessionTiers:e.sessionTiers}}),cwd:(0,r.subagentExecutionRoot)(e),provider:i,terminal:xe,sessionId:e.request.resumeSessionId??e.taskId,...s===void 0?{}:{sessionStore:s},...a?{sessionLogger:a}:{},permissionMode:e.permissionMode,...J?.commandSandbox===void 0?{}:{commandSandbox:J.commandSandbox},...e.request.permissionPolicy===void 0?{}:{permissionPolicy:e.request.permissionPolicy},...e.request.allowedTools===void 0?{}:{taskAllowedTools:e.request.allowedTools},...e.request.disallowedTools===void 0?{}:{taskDisallowedTools:e.request.disallowedTools},hooks:e.parentConfig.hooks,...t.createHookTypeExecutors===void 0?{}:{hookTypeExecutors:t.createHookTypeExecutors()},onTextDelta:e=>Z({type:`text_delta`,delta:e}),onToolExecution:Ce}),ve(e,G,s);let u=await G.run(e.request.prompt);if(Y!==void 0){Q({type:`error`,message:Y},0);return}if(K){Q({type:`cancelled`,reason:`Subagent worker cancelled`},130);return}let d=Se(G);Q({type:`result`,output:u,...d?{usage:d}:{}},0)}catch(e){if(Y!==void 0){Q({type:`error`,message:Y},0);return}if(K){Q({type:`cancelled`,reason:`Subagent worker cancelled`},130);return}Q({type:`error`,message:e instanceof Error?e.message:String(e)},0)}}function Ce(e){if(e.type===`start`){Z({type:`tool_start`,toolName:e.toolName,toolArgs:e.toolArgs});return}Z({type:`tool_end`,toolName:e.toolName,success:e.success??!0})}function we(e){if(G===null){Z({type:`error`,message:`Subagent worker has not started`});return}X=X.then(async()=>{try{await G?.run(e)}catch(e){Z({type:`error`,message:e instanceof Error?e.message:String(e)})}})}async function Te(e){K=!0,G?.abort(),Z({type:`cancelled`,reason:e}),await G?.shutdown({reason:`other`}).catch(()=>void 0),setTimeout(()=>process.exit(130),0)}function Ee(e){try{return e.createTools({cwd:process.cwd()}).map(e=>e.getName())}catch(e){process.stderr.write(`robota: could not enumerate the composed tool surface: ${e instanceof Error?e.message:String(e)}\n`);return}}function De(e){q=e;try{J?.applyParentSettings?.(e)}catch(e){Y??=e instanceof Error?e.message:String(e),G?.abort()}}function Oe(e){process.send===void 0&&(process.stderr.write(`robota: subagent worker mode requires an IPC channel; it is started by the agent runtime, not by hand.
+`),process.exit(2)),process.on(`message`,t=>{if(!O(t)){Z({type:`error`,message:`Malformed subagent worker parent message`});return}switch(t.type){case`start`:X=X.then(()=>$(t.payload,e));break;case`send`:we(t.prompt);break;case`cancel`:Te(t.reason);break;case`sandbox_settings`:De(t.settings);break;default:Z({type:`error`,message:`Unhandled subagent worker parent message`})}}),process.on(`disconnect`,()=>{K=!0,G?.abort(),G?.shutdown({reason:`other`}).catch(()=>void 0)});let t=Ee(e);Z({type:`ready`,...t?{composedToolNames:t}:{}})}exports.ChildProcessSubagentRunner=W,exports.SUBAGENT_WORKER_MODE_FLAG=U,exports.createChildProcessSubagentRunnerFactory=ge,exports.decodeAgentDefinitionDto=_,exports.decodeParentContextDto=b,exports.encodeAgentDefinition=g,exports.encodeParentContext=y,exports.isSubagentWorkerChildMessage=k,exports.isSubagentWorkerModeArgv=me,exports.isSubagentWorkerParentMessage=O,exports.restoreAgentDefinition=v,exports.restoreParentContext=x,exports.runSubagentWorkerMain=Oe;

package/dist/node/index.d.cts

@@ -1,6 +1,6 @@
 import { IConnectionEnvironmentCheck, ISubagentJobHandle, ISubagentJobStart, ISubagentRunner, ISubagentWorktreeAdapter } from "@robota-sdk/agent-executor";
 import { IHookTypeExecutor, IProviderDefinition, IProviderDefinitionConfig, ISessionUsageTotals, IToolWithEventService, TPermissionMode, TToolArgs } from "@robota-sdk/agent-core";
-import { IAgentDefinition, IInProcessSubagentRunnerDeps, IResolvedConfig, ISubagentParentContext, TSubagentRunnerFactory, restoreSessionRecordIntoSession } from "@robota-sdk/agent-framework";
+import { IAgentDefinition, IInProcessSubagentRunnerDeps, IResolvedConfig, ISubagentOptions, ISubagentParentContext, TSubagentRunnerFactory, restoreSessionRecordIntoSession } from "@robota-sdk/agent-framework";
 import { ISerializableProviderProfile, ISubagentSpawnRequest } from "@robota-sdk/agent-interface-execution";
 //#region src/worker-entry.d.ts
 /**
@@ -42,104 +42,6 @@ interface ISubagentWorkerEntry {
 /** True when this process was started as a subagent worker. */
 declare function isSubagentWorkerModeArgv(argv: readonly string[]): boolean;
 //#endregion
-//#region src/child-process-subagent-runner.d.ts
-interface IChildProcessSubagentRunnerOptions {
-  /**
-   * DIST-006: how to start a copy of the running artifact in subagent-worker mode, stated by the
-   * composition root. It replaced `workerPath`, which asked this package to locate a file whose
-   * location is a property of the packaging step — a question no library can answer, and one that
-   * was answered wrongly twice.
-   */
-  workerEntry: ISubagentWorkerEntry;
-  providerConfig?: IProviderDefinitionConfig;
-  /**
-   * The parent's provider registry. Its defaults complete the connection the child is given, and
-   * each definition names the environment its client reads. Required: a job whose provider has no
-   * definition here is refused, because its connection cannot be checked.
-   */
-  providerDefinitions: readonly IProviderDefinition[];
-  killGraceMs?: number;
-  /**
-   * How long a spawned worker may take to signal `ready` before the runner gives up. Injectable so
-   * the branch is reachable in a test; without that it is a fix that ships untested.
-   */
-  handshakeBudgetMs?: number;
-  env?: NodeJS.ProcessEnv;
-  worktreeIsolation?: boolean;
-  worktreeAdapter: ISubagentWorktreeAdapter;
-  logsDir?: string;
-}
-declare function createChildProcessSubagentRunnerFactory(options: IChildProcessSubagentRunnerOptions): TSubagentRunnerFactory;
-declare class ChildProcessSubagentRunner implements ISubagentRunner {
-  private readonly deps;
-  private readonly workerEntry;
-  private readonly killGraceMs;
-  private readonly handshakeBudgetMs?;
-  private readonly providerConfig?;
-  private readonly providerDefinitions;
-  private readonly env?;
-  private readonly logsDir?;
-  constructor(deps: IInProcessSubagentRunnerDeps, options: IChildProcessSubagentRunnerOptions);
-  start(job: ISubagentJobStart): ISubagentJobHandle;
-  /**
-   * The payload the child is started with. The builder lives in
-   * `child-process-subagent-projection.ts` (CLI-1994 moved it there so the ARCH-044 key-set test
-   * pins the code that produces it); review of ARCH-033/ARCH-034 is the reason it is a named
-   * producer at all — both fields were declared on the wire type, read by the worker, and set by
-   * nothing, because this was the only production site that constructs a payload and no test
-   * reached it.
-   */
-  private createStartPayload;
-  private resolveTranscriptPath;
-}
-//#endregion
-//#region src/subagent-worker-start-dto.d.ts
-/**
- * The parent's loaded-context RUNTIME model (`ILoadedContext`, which the framework barrel does not
- * export). Named here for the encoder/restore signatures only — the wire DTO below never references it.
- */
-type TParentContextModel = IInProcessSubagentRunnerDeps['context'];
-interface ISubagentWorkerAgentDefinitionDto {
-  readonly name: string;
-  readonly description: string;
-  readonly systemPrompt: string;
-  readonly model?: string;
-  readonly effort?: IAgentDefinition['effort'];
-  readonly role?: string;
-  readonly maxTurns?: number;
-  readonly tools?: readonly string[];
-  readonly disallowedTools?: readonly string[];
-}
-interface ISubagentWorkerContextFileEntryDto {
-  readonly filePath: string;
-  readonly content: string;
-  readonly contentHash: string;
-}
-interface ISubagentWorkerParentContextDto {
-  readonly agentsMd: string;
-  readonly projectNotesMd: string;
-  readonly memoryMd?: string;
-  readonly taskContext?: string;
-  readonly compactInstructions?: string;
-  readonly agentsFileEntries?: readonly ISubagentWorkerContextFileEntryDto[];
-  readonly projectNotesFileEntries?: readonly ISubagentWorkerContextFileEntryDto[];
-}
-type TDtoDecodeResult<TDto> = {
-  readonly ok: true;
-  readonly value: TDto;
-} | {
-  readonly ok: false;
-  readonly reason: string;
-};
-declare function encodeAgentDefinition(definition: IAgentDefinition): ISubagentWorkerAgentDefinitionDto;
-declare function decodeAgentDefinitionDto(value: unknown): TDtoDecodeResult<ISubagentWorkerAgentDefinitionDto>;
-/** Explicit restore in the worker: the DTO's fields are the runtime model's, copied, not aliased. */
-declare function restoreAgentDefinition(dto: ISubagentWorkerAgentDefinitionDto): IAgentDefinition;
-/** Accepts the issue #2317 projection (or anything wider, structurally); only declared fields cross. */
-declare function encodeParentContext(context: ISubagentParentContext): ISubagentWorkerParentContextDto;
-declare function decodeParentContextDto(value: unknown): TDtoDecodeResult<ISubagentWorkerParentContextDto>;
-declare function restoreParentContext(dto: ISubagentWorkerParentContextDto): TParentContextModel;
-//#endregion
 //#region src/worker-composition.d.ts
 /**
  * The session record store a fork job's `resumeSessionId` names a record in, typed FROM the one
@@ -252,6 +154,34 @@ interface ISubagentWorkerComposition {
   readonly openSessionStore?: (context: {
     readonly cwd: string;
   }) => TResumeSessionStore;
+  /**
+   * A sandbox the child composes itself at its execution root, rather than restoring one from a
+   * snapshot: the OS sandbox is a function of the root and its settings, and the settings cross as
+   * data (`parentSettings`, the parent's as they stood at spawn) where a live handle cannot.
+   *
+   * The worker builds it once and hands the SAME instance to `createTools` (as `sandboxClient`) and to
+   * the session (as `commandSandbox`), so the approval a confined command gets comes from the instance
+   * the command runs under. Absent ⇒ the child's session approves no command on a sandbox's say-so.
+   */
+  readonly createSandbox?: (context: {
+    readonly cwd: string;
+    /** The parent's sandbox settings at spawn, when its composition root sent them. */
+    readonly parentSettings?: TParentSandboxSettings;
+  }) => ISubagentComposedSandbox | undefined;
+}
+/** A composition root's sandbox settings, as plain data that crosses the process boundary. */
+type TParentSandboxSettings = Readonly<Record<string, unknown>>;
+/** A sandbox the child composed itself: the client its tools run under and the approval it gives. */
+interface ISubagentComposedSandbox {
+  readonly client: TProjectedSandboxClient;
+  readonly commandSandbox?: ISubagentOptions['commandSandbox'];
+  /**
+   * Take the parent's settings after a change it made while this child runs (`/sandbox`), so the
+   * next command is confined and approved as the parent's would be. Throws on settings it cannot
+   * read: the worker then aborts the run and ends it with that error, rather than run on settings the
+   * user has replaced.
+   */
+  readonly applyParentSettings?: (settings: TParentSandboxSettings) => void;
 }
 /**
  * Rebuilds a sandbox client of ONE type from a snapshot reference the parent produced.
@@ -284,6 +214,119 @@ interface ISandboxProjection {
   readonly snapshotId: string;
 }
 //#endregion
+//#region src/child-process-subagent-runner.d.ts
+interface IChildProcessSubagentRunnerOptions {
+  /**
+   * DIST-006: how to start a copy of the running artifact in subagent-worker mode, stated by the
+   * composition root. It replaced `workerPath`, which asked this package to locate a file whose
+   * location is a property of the packaging step — a question no library can answer, and one that
+   * was answered wrongly twice.
+   */
+  workerEntry: ISubagentWorkerEntry;
+  providerConfig?: IProviderDefinitionConfig;
+  /**
+   * The parent's provider registry. Its defaults complete the connection the child is given, and
+   * each definition names the environment its client reads. Required: a job whose provider has no
+   * definition here is refused, because its connection cannot be checked.
+   */
+  providerDefinitions: readonly IProviderDefinition[];
+  killGraceMs?: number;
+  /**
+   * How long a spawned worker may take to signal `ready` before the runner gives up. Injectable so
+   * the branch is reachable in a test; without that it is a fix that ships untested.
+   */
+  handshakeBudgetMs?: number;
+  env?: NodeJS.ProcessEnv;
+  worktreeIsolation?: boolean;
+  worktreeAdapter: ISubagentWorktreeAdapter;
+  logsDir?: string;
+  /**
+   * The parent's sandbox settings as they stand now, read at EACH spawn: a setting the user changed
+   * this session (`/sandbox`) lives on the parent's live client, not in the files a child would read.
+   * The child's `createSandbox` receives the value. Absent ⇒ the child reads its root's settings.
+   */
+  parentSandboxSettings?: () => TParentSandboxSettings | undefined;
+  /**
+   * Be told the parent's sandbox settings after each change (`/sandbox`); returns the way to stop.
+   * The runner forwards each change to every running child, so a child started before the change
+   * follows it too.
+   */
+  watchParentSandboxSettings?: (listener: (settings: TParentSandboxSettings) => void) => () => void;
+}
+declare function createChildProcessSubagentRunnerFactory(options: IChildProcessSubagentRunnerOptions): TSubagentRunnerFactory;
+declare class ChildProcessSubagentRunner implements ISubagentRunner {
+  private readonly deps;
+  private readonly workerEntry;
+  private readonly killGraceMs;
+  private readonly handshakeBudgetMs?;
+  private readonly providerConfig?;
+  private readonly providerDefinitions;
+  private readonly env?;
+  private readonly logsDir?;
+  private readonly parentSandboxSettings?;
+  private readonly watchParentSandboxSettings?;
+  constructor(deps: IInProcessSubagentRunnerDeps, options: IChildProcessSubagentRunnerOptions);
+  start(job: ISubagentJobStart): ISubagentJobHandle;
+  /**
+   * The payload the child is started with. The builder lives in
+   * `child-process-subagent-projection.ts` (CLI-1994 moved it there so the ARCH-044 key-set test
+   * pins the code that produces it); review of ARCH-033/ARCH-034 is the reason it is a named
+   * producer at all — both fields were declared on the wire type, read by the worker, and set by
+   * nothing, because this was the only production site that constructs a payload and no test
+   * reached it.
+   */
+  private createStartPayload;
+  private forwardSandboxSettingChanges;
+  private resolveTranscriptPath;
+}
+//#endregion
+//#region src/subagent-worker-start-dto.d.ts
+/**
+ * The parent's loaded-context RUNTIME model (`ILoadedContext`, which the framework barrel does not
+ * export). Named here for the encoder/restore signatures only — the wire DTO below never references it.
+ */
+type TParentContextModel = IInProcessSubagentRunnerDeps['context'];
+interface ISubagentWorkerAgentDefinitionDto {
+  readonly name: string;
+  readonly description: string;
+  readonly systemPrompt: string;
+  readonly model?: string;
+  readonly effort?: IAgentDefinition['effort'];
+  readonly role?: string;
+  readonly maxTurns?: number;
+  readonly tools?: readonly string[];
+  readonly disallowedTools?: readonly string[];
+}
+interface ISubagentWorkerContextFileEntryDto {
+  readonly filePath: string;
+  readonly content: string;
+  readonly contentHash: string;
+}
+interface ISubagentWorkerParentContextDto {
+  readonly agentsMd: string;
+  readonly projectNotesMd: string;
+  readonly memoryMd?: string;
+  readonly taskContext?: string;
+  readonly compactInstructions?: string;
+  readonly agentsFileEntries?: readonly ISubagentWorkerContextFileEntryDto[];
+  readonly projectNotesFileEntries?: readonly ISubagentWorkerContextFileEntryDto[];
+}
+type TDtoDecodeResult<TDto> = {
+  readonly ok: true;
+  readonly value: TDto;
+} | {
+  readonly ok: false;
+  readonly reason: string;
+};
+declare function encodeAgentDefinition(definition: IAgentDefinition): ISubagentWorkerAgentDefinitionDto;
+declare function decodeAgentDefinitionDto(value: unknown): TDtoDecodeResult<ISubagentWorkerAgentDefinitionDto>;
+/** Explicit restore in the worker: the DTO's fields are the runtime model's, copied, not aliased. */
+declare function restoreAgentDefinition(dto: ISubagentWorkerAgentDefinitionDto): IAgentDefinition;
+/** Accepts the issue #2317 projection (or anything wider, structurally); only declared fields cross. */
+declare function encodeParentContext(context: ISubagentParentContext): ISubagentWorkerParentContextDto;
+declare function decodeParentContextDto(value: unknown): TDtoDecodeResult<ISubagentWorkerParentContextDto>;
+declare function restoreParentContext(dto: ISubagentWorkerParentContextDto): TParentContextModel;
+//#endregion
 //#region src/child-process-subagent-ipc.d.ts
 type TSubagentWorkerWireValue = string | number | boolean | null | undefined | object;
 /** ARCH-044: the four config members the child reads. See `projectParentConfig`. */
@@ -358,6 +401,12 @@ interface ISubagentWorkerStartPayload {
   sessionTiers?: {
     readonly includeGoalTool?: boolean;
   };
+  /**
+   * The parent's sandbox settings as they stand at spawn, including a change made this session.
+   * Opaque here: the composition root produced it and its `createSandbox` reads it, so the child
+   * confines and approves as the parent does now, not as its root's settings files say.
+   */
+  parentSandboxSettings?: TParentSandboxSettings;
   permissionMode?: TPermissionMode;
   logsDir?: string;
 }
@@ -373,7 +422,12 @@ interface ISubagentWorkerCancelMessage {
   type: 'cancel';
   reason?: string;
 }
-type TSubagentWorkerParentMessage = ISubagentWorkerStartMessage | ISubagentWorkerSendMessage | ISubagentWorkerCancelMessage;
+/** The parent's sandbox settings changed while the child runs (`/sandbox`); the child follows. */
+interface ISubagentWorkerSandboxSettingsMessage {
+  type: 'sandbox_settings';
+  settings: TParentSandboxSettings;
+}
+type TSubagentWorkerParentMessage = ISubagentWorkerStartMessage | ISubagentWorkerSendMessage | ISubagentWorkerCancelMessage | ISubagentWorkerSandboxSettingsMessage;
 interface ISubagentWorkerReadyMessage {
   type: 'ready';
   /**
@@ -432,5 +486,5 @@ declare function isSubagentWorkerChildMessage(value: TSubagentWorkerWireValue):
  */
 declare function runSubagentWorkerMain(composition: ISubagentWorkerComposition): void;
 //#endregion
-export { ChildProcessSubagentRunner, type IChildProcessSubagentRunnerOptions, type ISubagentWorkerAgentDefinitionDto, type ISubagentWorkerComposition, type ISubagentWorkerContextFileEntryDto, type ISubagentWorkerEntry, type ISubagentWorkerParentContextDto, type ISubagentWorkerStartPayload, SUBAGENT_WORKER_MODE_FLAG, type TResumeSessionStore, type TSubagentWorkerChildMessage, type TSubagentWorkerParentMessage, type TSubagentWorkerWireValue, createChildProcessSubagentRunnerFactory, decodeAgentDefinitionDto, decodeParentContextDto, encodeAgentDefinition, encodeParentContext, isSubagentWorkerChildMessage, isSubagentWorkerModeArgv, isSubagentWorkerParentMessage, restoreAgentDefinition, restoreParentContext, runSubagentWorkerMain };
+export { ChildProcessSubagentRunner, type IChildProcessSubagentRunnerOptions, type ISubagentComposedSandbox, type ISubagentWorkerAgentDefinitionDto, type ISubagentWorkerComposition, type ISubagentWorkerContextFileEntryDto, type ISubagentWorkerEntry, type ISubagentWorkerParentContextDto, type ISubagentWorkerStartPayload, SUBAGENT_WORKER_MODE_FLAG, type TParentSandboxSettings, type TResumeSessionStore, type TSubagentWorkerChildMessage, type TSubagentWorkerParentMessage, type TSubagentWorkerWireValue, createChildProcessSubagentRunnerFactory, decodeAgentDefinitionDto, decodeParentContextDto, encodeAgentDefinition, encodeParentContext, isSubagentWorkerChildMessage, isSubagentWorkerModeArgv, isSubagentWorkerParentMessage, restoreAgentDefinition, restoreParentContext, runSubagentWorkerMain };
 //# sourceMappingURL=index.d.cts.map

package/dist/node/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/worker-entry.ts","../../src/child-process-subagent-runner.ts","../../src/subagent-worker-start-dto.ts","../../src/worker-composition.ts","../../src/child-process-subagent-ipc.ts","../../src/child-process-subagent-worker.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;cAmBa;;;;;;;;;;UAWI;;WAEN;;WAEA;;WAEA;;;iBAIK,yBAAyB;;;UCMxB;;;;;;;EAOf,aAAa;EACb,iBAAiB;;;;;;EAMjB,8BAA8B;EAC9B;;;;;EAKA;EACA,MAAM,OAAO;EACb;EACA,iBAAiB;EACjB;;iBAGc,wCACd,SAAS,qCACR;cAaU,sCAAsC;mBAU9B;mBATF;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;EAGE,YAAA,MAAM,8BACvB,SAAS;EAWX,MAAM,KAAK,oBAAoB;;;;;;;;;UAsFvB;UAWA;;;;;;;;KClLL,sBAAsB;UAEV;WACN;WACA;WACA;WACA;WACA,SAAS;WACT;WACA;WACA;WACA;;UAGM;WACN;WACA;WACA;;UAGM;WACN;WACA;WACA;WACA;WACA;WACA,6BAA6B;WAC7B,mCAAmC;;KAmClC,iBAAiB;WAChB;WAAmB,OAAO;;WAAoB;WAAoB;;iBAmE/D,sBACd,YAAY,mBACX;iBAOa,yBACd,iBACC,iBAAiB;;iBASJ,uBAAuB,KAAK,oCAAoC;;iBAgBhE,oBACd,SAAS,yBACR;iBAOa,uBACd,iBACC,iBAAiB;iBAIJ,qBAAqB,KAAK,kCAAkC;;;;;;;;;KCrMhE,sBAAsB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;UAuBnC;;EAEf,gCAAgC;;;;;;;;;EAShC,YAAY;aACD;;;;;;;;;;;;;;aAcA;;eAEE;;;;;;;;;;aAUF,gBAAgB;MACvB;;;;;;WAOK,8BAA8B;;;;;;;;;;;;;;;;;;;;;WAsB9B,mBAAmB,SAAS,eAAe;;;;;;;;;;;;;;WAe3C,oBAAoB;aAAoB;QAAkB;;;;;;;;KASzD,yBAAyB,uBAAuB,QAAQ;;;;;;;;;;;;;KAcxD;;;;;;;UAQK;WACN;WACA;;;;KCxIC;;UAKK;WACN;aAAqB;;WACrB,aAAa;WACb,mBAAmB;WACnB,QAAQ;;UAGF;EACf;EACA,SAAS;;;;;;;;;;EAUT;aAAsB;aAAuB;;;EAE7C,iBAAiB;;;;;;;;;;;EAWjB,cAAc;;;;;;;EAOd,eAAe;EACf,iBAAiB;;;;;EAKjB,iBAAiB;;;;;;;;;;;;EAYjB,oBAAoB;;;;;;;EAOpB;aAA0B;;EAC1B,iBAAiB;EACjB;;UAGe;EACf;EACA,SAAS;;UAGM;EACf;EACA;;UAGe;EACf;EACA;;KAGU,+BACV,8BAA8B,6BAA6B;UAE5C;EACf;;;;;;;;;EASA;;UAGe;EACf;EACA;;UAGe;EACf;EACA;EACA,WAAW;;UAGI;EACf;EACA;EACA;;UAGe;EACf;EACA;;EAEA,QAAQ;;UAGO;EACf;EACA;;UAGe;EACf;EACA;;KAGU,8BACR,8BACA,kCACA,kCACA,gCACA,+BACA,8BACA;iBA+GY,8BACd,OAAO,2BACN,SAAS;iBAcI,6BACd,OAAO,2BACN,SAAS;;;;;;;;;;;;;;iBCpCI,sBAAsB,aAAa"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/worker-entry.ts","../../src/worker-composition.ts","../../src/child-process-subagent-runner.ts","../../src/subagent-worker-start-dto.ts","../../src/child-process-subagent-ipc.ts","../../src/child-process-subagent-worker.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;cAmBa;;;;;;;;;;UAWI;;WAEN;;WAEA;;WAEA;;;iBAIK,yBAAyB;;;;;;;;;KC3B7B,sBAAsB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;UAuBnC;;EAEf,gCAAgC;;;;;;;;;EAShC,YAAY;aACD;;;;;;;;;;;;;;aAcA;;eAEE;;;;;;;;;;aAUF,gBAAgB;MACvB;;;;;;WAOK,8BAA8B;;;;;;;;;;;;;;;;;;;;;WAsB9B,mBAAmB,SAAS,eAAe;;;;;;;;;;;;;;WAe3C,oBAAoB;aAAoB;QAAkB;;;;;;;;;;WAW1D,iBAAiB;aACf;;aAEA,iBAAiB;QACtB;;;KAII,yBAAyB,SAAS;;UAG7B;WACN,QAAQ;WACR,iBAAiB;;;;;;;WAOjB,uBAAuB,UAAU;;;;;;;;KAShC,yBAAyB,uBAAuB,QAAQ;;;;;;;;;;;;;KAcxD;;;;;;;UAQK;WACN;WACA;;;;UCvIM;;;;;;;EAOf,aAAa;EACb,iBAAiB;;;;;;EAMjB,8BAA8B;EAC9B;;;;;EAKA;EACA,MAAM,OAAO;EACb;EACA,iBAAiB;EACjB;;;;;;EAMA,8BAA8B;;;;;;EAM9B,8BAA8B,WAAW,UAAU;;iBAGrC,wCACd,SAAS,qCACR;cAaU,sCAAsC;mBAY9B;mBAXF;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;EAGE,YAAA,MAAM,8BACvB,SAAS;EAaX,MAAM,KAAK,oBAAoB;;;;;;;;;UAyFvB;UAaA;UAYA;;;;;;;;KCrNL,sBAAsB;UAEV;WACN;WACA;WACA;WACA;WACA,SAAS;WACT;WACA;WACA;WACA;;UAGM;WACN;WACA;WACA;;UAGM;WACN;WACA;WACA;WACA;WACA;WACA,6BAA6B;WAC7B,mCAAmC;;KAmClC,iBAAiB;WAChB;WAAmB,OAAO;;WAAoB;WAAoB;;iBAmE/D,sBACd,YAAY,mBACX;iBAOa,yBACd,iBACC,iBAAiB;;iBASJ,uBAAuB,KAAK,oCAAoC;;iBAgBhE,oBACd,SAAS,yBACR;iBAOa,uBACd,iBACC,iBAAiB;iBAIJ,qBAAqB,KAAK,kCAAkC;;;KClMhE;;UAKK;WACN;aAAqB;;WACrB,aAAa;WACb,mBAAmB;WACnB,QAAQ;;UAGF;EACf;EACA,SAAS;;;;;;;;;;EAUT;aAAsB;aAAuB;;;EAE7C,iBAAiB;;;;;;;;;;;EAWjB,cAAc;;;;;;;EAOd,eAAe;EACf,iBAAiB;;;;;EAKjB,iBAAiB;;;;;;;;;;;;EAYjB,oBAAoB;;;;;;;EAOpB;aAA0B;;;;;;;EAM1B,wBAAwB;EACxB,iBAAiB;EACjB;;UAGe;EACf;EACA,SAAS;;UAGM;EACf;EACA;;UAGe;EACf;EACA;;;UAIe;EACf;EACA,UAAU;;KAGA,+BACR,8BACA,6BACA,+BACA;UAEa;EACf;;;;;;;;;EASA;;UAGe;EACf;EACA;;UAGe;EACf;EACA;EACA,WAAW;;UAGI;EACf;EACA;EACA;;UAGe;EACf;EACA;;EAEA,QAAQ;;UAGO;EACf;EACA;;UAGe;EACf;EACA;;KAGU,8BACR,8BACA,kCACA,kCACA,gCACA,+BACA,8BACA;iBAkHY,8BACd,OAAO,2BACN,SAAS;iBAgBI,6BACd,OAAO,2BACN,SAAS;;;;;;;;;;;;;;iBCPI,sBAAsB,aAAa"}