eve 0.63.0 → 0.64.0

package/dist/src/public/channels/chat-sdk/chatSdkChannel.d.ts

@@ -1,7 +1,7 @@
 import type { UserContent } from "ai";
 import type { ChannelAddressDeliveryOptions } from "#channel/channel-address.js";
 import type { SendPayload } from "#channel/routes.js";
-import type { SessionAuthContext, TurnPolicy } from "#channel/types.js";
+import type { SessionAuthContext, TurnPolicy, TaskDeliveryPolicy } from "#channel/types.js";
 import type { ActionEvent, Adapter, ChatConfig, SerializedThread, Thread, WebhookOptions } from "#compiled/chat/index.js";
 import { Chat } from "#compiled/chat/index.js";
 import { type Channel, type ChannelEvents, type ChannelContinuationOps, type Session } from "#public/definitions/channel.js";
@@ -67,14 +67,13 @@ export interface ChatSdkEventContext<TAdapters extends ChatSdkAdapters = ChatSdk
  * replaces the built-in default for that event.
  */
 export type ChatSdkChannelEvents<TAdapters extends ChatSdkAdapters = ChatSdkAdapters> = ChannelEvents<ChatSdkChannelContext<TAdapters>>;
-/**
- * Options for `bridge.send(...)` inside Chat SDK handlers. The `thread`
- * determines the eve continuation token and the persisted channel state.
- */
+/** The thread determines the eve continuation token and persisted channel state. */
 export interface ChatSdkSendOptions {
     readonly auth?: SessionAuthContext | null;
     readonly callback?: ChannelAddressDeliveryOptions<ChatSdkChannelState>["callback"];
     readonly mode?: ChannelAddressDeliveryOptions<ChatSdkChannelState>["mode"];
+    /** Updates the session policy; omission preserves it. */
+    readonly taskDeliveryPolicy?: TaskDeliveryPolicy;
     readonly thread: SerializedThread | Thread | string;
     readonly title?: string;
     /**

package/dist/src/public/channels/chat-sdk/chatSdkChannel.js

@@ -1,3 +1,3 @@
-import{createLogger,extractErrorId,formatErrorHint}from"#internal/logging.js";import{normalizeSendInput}from"#channel/send-input.js";import{INTERNAL_CHANNEL_DELIVER}from"#channel/channel-operations.js";import{ContextContainer,contextStorage}from"#context/container.js";import{GET,POST,defineChannel}from"#public/definitions/channel.js";import{ContextKey}from"#context/key.js";import{isNotImplemented}from"#public/channels/chat-sdk/notImplemented.js";import{Actions,Button,Card,CardText,Chat,Message,ThreadImpl}from"#compiled/chat/index.js";import{defaultAuthorizationEvents}from"#public/channels/chat-sdk/authorization.js";import{chatSdkInstrumentation}from"#public/channels/chat-sdk/audience.js";const log=createLogger(`chat-sdk.channel`),streamTextByState=new WeakMap,ActiveWebhookKey=new ContextKey(`chat-sdk.active-webhook`);function chatSdkChannel(e){let t=new Chat(e),n=e.inputActionPrefix??`eve_input:`,r=e.streaming??!0,i=e.streamingEditIntervalMs??1e3,a={...defaultEvents(n),...e.events};return t.onAction(async r=>{let i=decodeInputAction(r.actionId,n,r.value);if(i){if(!r.thread)throw Error(`chatSdkChannel input actions require a thread on the Chat SDK action event.`);await bridgeSend(t,{inputResponses:[i]},{auth:e.resolveInputAuth?await e.resolveInputAuth(r):null,thread:r.thread})}}),{bot:t,channel:defineChannel({kindHint:`chat-sdk`,turnPolicy:e.turnPolicy,state:initialState(),...chatSdkInstrumentation,context(e){return{bot:t,state:e,streaming:r,streamingEditIntervalMs:i,thread:threadFromState(t,e)}},routes:adapterNames(e.adapters).flatMap(n=>{let r=routeForAdapter(n,e),handler=async(r,i)=>{let a=t.webhooks[n],o=new ContextContainer;return o.setVirtualContext(ActiveWebhookKey,{from:i.from}),contextStorage.run(o,()=>a(r,{...e.webhook,waitUntil(e){i.waitUntil(e)}}))};return[GET(r,handler),POST(r,handler)]}),async receive(e,{from:n}){let r=serializeReceiveTarget(t,e.target);return n(r.id).send(e.message,{auth:e.auth,state:{thread:r}})},events:a}),send(e,n){return bridgeSend(t,e,n)}}}function defaultEvents(e){return{...defaultAuthorizationEvents(),async"turn.started"(e,t,n){t.state.pendingToolCallMessage=null,clearStream(t.state),await safeStartTyping(t.thread,`Working...`)},async"actions.requested"(e,t,n){let r=t.state.pendingToolCallMessage;if(t.state.pendingToolCallMessage=null,r){await safeStartTyping(t.thread,truncate(r));return}let i=e.actions.map(e=>e.kind===`tool-call`?e.toolName:e.kind);await safeStartTyping(t.thread,truncate(`Running ${i.join(`, `)}...`))},async"message.appended"(e,t,n){if(!t.thread||!canStream(t))return;let r=((t.state.streamStepIndex===e.stepIndex?streamTextByState.get(t.state):void 0)??``)+e.messageDelta;if(!r)return;streamTextByState.set(t.state,r);let i=t.state.anchorMessageId;if(!i||t.state.streamStepIndex!==e.stepIndex){let n=await t.thread.post({markdown:r});t.state.anchorMessageId=n.id,t.state.streamStepIndex=e.stepIndex,t.state.lastEditAtMs=Date.now();return}let a=t.state.lastEditAtMs??0;if(!(Date.now()-a<t.streamingEditIntervalMs))try{await editMessage(t.thread,i,r),t.state.lastEditAtMs=Date.now()}catch(e){if(!isNotImplemented(e))throw e;t.state.editSupported=!1,clearStream(t.state)}},async"input.requested"(t,n,r){n.thread&&t.requests.length!==0&&await n.thread.post(renderInputRequests(t.requests,e))},async"message.completed"(e,t,n){if(e.finishReason===`tool-calls`){t.state.pendingToolCallMessage=e.message?firstNonEmptyLine(e.message)??null:null,e.message?await finalizeStreamedMessage(t,e.message,!1):clearStream(t.state);return}if(t.state.pendingToolCallMessage=null,!e.message){clearStream(t.state);return}await finalizeStreamedMessage(t,e.message,!0)},async"turn.failed"(e,t,n){await postFailure(t.thread,`I hit an error while handling your request`,e)},async"session.failed"(e,t){await postFailure(t.thread,`This session could not recover from an error`,e)}}}async function safeStartTyping(e,t){if(e)try{await e.startTyping(t)}catch(e){if(!isNotImplemented(e))throw e}}async function editMessage(e,t,n){await e.adapter.editMessage(e.id,t,{markdown:n})}async function finalizeStreamedMessage(e,t,n){let r=e.thread;if(!r){clearStream(e.state);return}let i=e.state.anchorMessageId;if(canStream(e)&&i)try{await editMessage(r,i,t)}catch(i){if(!isNotImplemented(i))throw i;e.state.editSupported=!1,n&&await r.post({markdown:t})}else n&&await r.post({markdown:t});clearStream(e.state)}function canStream(e){return e.streaming&&e.state.editSupported!==!1}function clearStream(e){e.anchorMessageId=null,e.lastEditAtMs=null,e.streamStepIndex=null,streamTextByState.delete(e)}function firstNonEmptyLine(e){for(let t of e.split(/\r?\n/u)){let e=t.trim();if(e.length>0)return e}}function truncate(e,t=80){return e.length<=t?e:`${e.slice(0,t-1)}\u2026`}function renderInputRequests(e,t){return Card({children:e.flatMap(e=>renderInputRequest(e,t))})}function renderInputRequest(e,t){let n=[CardText(e.prompt)];return e.options&&e.options.length>0?(n.push(Actions(e.options.map(n=>Button({id:encodeInputAction(t,e.requestId,n.id),label:n.label,style:n.style,value:n.id})))),n):(n.push(CardText(`This request needs a freeform answer. Continue from the eve session UI.`)),n)}async function postFailure(e,t,n){if(!e)return;let r=formatErrorHint(n),i=extractErrorId(n.details);await e.post([`${t}${r}.`,`Please try again, rephrase, or reach out if it keeps failing.`,...i?[`Error id: ${i}`]:[]].join(`
+import{createLogger,extractErrorId,formatErrorHint}from"#internal/logging.js";import{normalizeSendInput}from"#channel/send-input.js";import{INTERNAL_CHANNEL_DELIVER}from"#channel/channel-operations.js";import{ContextContainer,contextStorage}from"#context/container.js";import{GET,POST,defineChannel}from"#public/definitions/channel.js";import{ContextKey}from"#context/key.js";import{isNotImplemented}from"#public/channels/chat-sdk/notImplemented.js";import{Actions,Button,Card,CardText,Chat,Message,ThreadImpl}from"#compiled/chat/index.js";import{defaultAuthorizationEvents}from"#public/channels/chat-sdk/authorization.js";import{chatSdkInstrumentation}from"#public/channels/chat-sdk/audience.js";const log=createLogger(`chat-sdk.channel`),streamTextByState=new WeakMap,ActiveWebhookKey=new ContextKey(`chat-sdk.active-webhook`);function chatSdkChannel(e){let t=new Chat(e),n=e.inputActionPrefix??`eve_input:`,r=e.streaming??!0,i=e.streamingEditIntervalMs??1e3,a={...defaultEvents(n),...e.events};return t.onAction(async r=>{let i=decodeInputAction(r.actionId,n,r.value);if(i){if(!r.thread)throw Error(`chatSdkChannel input actions require a thread on the Chat SDK action event.`);await bridgeSend(t,{inputResponses:[i]},{auth:e.resolveInputAuth?await e.resolveInputAuth(r):null,thread:r.thread.toJSON()})}}),{bot:t,channel:defineChannel({kindHint:`chat-sdk`,turnPolicy:e.turnPolicy,state:initialState(),...chatSdkInstrumentation,context(e){return{bot:t,state:e,streaming:r,streamingEditIntervalMs:i,thread:threadFromState(t,e)}},routes:adapterNames(e.adapters).flatMap(n=>{let r=routeForAdapter(n,e),handler=async(r,i)=>{let a=t.webhooks[n],o=new ContextContainer;return o.setVirtualContext(ActiveWebhookKey,{from:i.from}),contextStorage.run(o,()=>a(r,{...e.webhook,waitUntil(e){i.waitUntil(e)}}))};return[GET(r,handler),POST(r,handler)]}),async receive(e,{from:n}){let r=serializeReceiveTarget(t,e.target);return n(r.id).send(e.message,{auth:e.auth,state:{thread:r}})},events:a}),send(e,n){return bridgeSend(t,e,n)}}}function defaultEvents(e){return{...defaultAuthorizationEvents(),async"turn.started"(e,t,n){t.state.pendingToolCallMessage=null,clearStream(t.state),await safeStartTyping(t.thread,`Working...`)},async"actions.requested"(e,t,n){let r=t.state.pendingToolCallMessage;if(t.state.pendingToolCallMessage=null,r){await safeStartTyping(t.thread,truncate(r));return}let i=e.actions.map(e=>e.kind===`tool-call`?e.toolName:e.kind);await safeStartTyping(t.thread,truncate(`Running ${i.join(`, `)}...`))},async"message.appended"(e,t,n){if(!t.thread||!canStream(t))return;let r=((t.state.streamStepIndex===e.stepIndex?streamTextByState.get(t.state):void 0)??``)+e.messageDelta;if(!r)return;streamTextByState.set(t.state,r);let i=t.state.anchorMessageId;if(!i||t.state.streamStepIndex!==e.stepIndex){let n=await t.thread.post({markdown:r});t.state.anchorMessageId=n.id,t.state.streamStepIndex=e.stepIndex,t.state.lastEditAtMs=Date.now();return}let a=t.state.lastEditAtMs??0;if(!(Date.now()-a<t.streamingEditIntervalMs))try{await editMessage(t.thread,i,r),t.state.lastEditAtMs=Date.now()}catch(e){if(!isNotImplemented(e))throw e;t.state.editSupported=!1,clearStream(t.state)}},async"input.requested"(t,n,r){n.thread&&t.requests.length!==0&&await n.thread.post(renderInputRequests(t.requests,e))},async"message.completed"(e,t,n){if(e.finishReason===`tool-calls`){t.state.pendingToolCallMessage=e.message?firstNonEmptyLine(e.message)??null:null,e.message?await finalizeStreamedMessage(t,e.message,!1):clearStream(t.state);return}if(t.state.pendingToolCallMessage=null,!e.message){clearStream(t.state);return}await finalizeStreamedMessage(t,e.message,!0)},async"turn.failed"(e,t,n){await postFailure(t.thread,`I hit an error while handling your request`,e)},async"session.failed"(e,t){await postFailure(t.thread,`This session could not recover from an error`,e)}}}async function safeStartTyping(e,t){if(e)try{await e.startTyping(t)}catch(e){if(!isNotImplemented(e))throw e}}async function editMessage(e,t,n){await e.adapter.editMessage(e.id,t,{markdown:n})}async function finalizeStreamedMessage(e,t,n){let r=e.thread;if(!r){clearStream(e.state);return}let i=e.state.anchorMessageId;if(canStream(e)&&i)try{await editMessage(r,i,t)}catch(i){if(!isNotImplemented(i))throw i;e.state.editSupported=!1,n&&await r.post({markdown:t})}else n&&await r.post({markdown:t});clearStream(e.state)}function canStream(e){return e.streaming&&e.state.editSupported!==!1}function clearStream(e){e.anchorMessageId=null,e.lastEditAtMs=null,e.streamStepIndex=null,streamTextByState.delete(e)}function firstNonEmptyLine(e){for(let t of e.split(/\r?\n/u)){let e=t.trim();if(e.length>0)return e}}function truncate(e,t=80){return e.length<=t?e:`${e.slice(0,t-1)}\u2026`}function renderInputRequests(e,t){return Card({children:e.flatMap(e=>renderInputRequest(e,t))})}function renderInputRequest(e,t){let n=[CardText(e.prompt)];return e.options&&e.options.length>0?(n.push(Actions(e.options.map(n=>Button({id:encodeInputAction(t,e.requestId,n.id),label:n.label,style:n.style,value:n.id})))),n):(n.push(CardText(`This request needs a freeform answer. Continue from the eve session UI.`)),n)}async function postFailure(e,t,n){if(!e)return;let r=formatErrorHint(n),i=extractErrorId(n.details);await e.post([`${t}${r}.`,`Please try again, rephrase, or reach out if it keeps failing.`,...i?[`Error id: ${i}`]:[]].join(`
 
-`))}async function bridgeSend(e,t,n){let r=contextStorage.getStore()?.get(ActiveWebhookKey);if(!r)throw Error(`chatSdkChannel().send can only run during a Chat SDK webhook handler for this bridge.`);let i=serializeThread(e,n.thread,n.adapterName),a=normalizeSendInput(t),o={auth:n.auth??null,state:{thread:i}};return n.callback!==void 0&&(o.callback=n.callback),n.mode!==void 0&&(o.mode=n.mode),n.title!==void 0&&(o.title=n.title),n.turnPolicy!==void 0&&(o.turnPolicy=n.turnPolicy),r.from(i.id)[INTERNAL_CHANNEL_DELIVER](a,o)}function initialState(){return{pendingAuthMessageIds:{},thread:null}}function threadFromState(e,t){if(!t.thread)return null;try{let n=t.thread;return new ThreadImpl({adapter:e.getAdapter(n.adapterName),channelId:n.channelId,channelVisibility:n.channelVisibility,currentMessage:n.currentMessage?Message.fromJSON(n.currentMessage):void 0,id:n.id,isDM:n.isDM,stateAdapter:e.getState()})}catch(e){return log.warn(`failed to rebuild Chat SDK thread from channel state`,{error:e}),null}}function serializeReceiveTarget(e,t){if(t.thread)return t.thread;if(!t.threadId)throw Error(`chatSdkChannel().receive requires target.thread or target.threadId.`);return serializeThread(e,t.threadId,t.adapterName)}function serializeThread(e,t,n){if(typeof t==`string`){let r=n??inferAdapterName(t),i=e.getAdapter(r);return{_type:`chat:Thread`,adapterName:r,channelId:i.channelIdFromThreadId(t),channelVisibility:i.getChannelVisibility?.(t),id:t,isDM:!1}}return isSerializedThread(t)?t:t.toJSON()}function isSerializedThread(e){return`_type`in e&&e._type===`chat:Thread`}function inferAdapterName(e){let t=e.indexOf(`:`);if(t<=0)throw Error(`chatSdkChannel string thread references require options.adapterName.`);return e.slice(0,t)}function adapterNames(e){return Object.keys(e)}function routeForAdapter(e,t){return t.routes?.[e]||`${(t.route??`/eve/v1`).replace(/\/$/u,``)}/${e}`}function encodeInputAction(e,t,n){return`${e}${encodeURIComponent(t)}:${encodeURIComponent(n)}`}function decodeInputAction(e,t,n){if(!e.startsWith(t))return null;let r=e.slice(t.length),i=r.indexOf(`:`);if(i<=0)return null;try{let e=decodeURIComponent(r.slice(0,i));return{optionId:n??decodeURIComponent(r.slice(i+1)),requestId:e}}catch{return null}}export{chatSdkChannel};
+`))}async function bridgeSend(e,t,n){let r=contextStorage.getStore()?.get(ActiveWebhookKey);if(!r)throw Error(`chatSdkChannel().send can only run during a Chat SDK webhook handler for this bridge.`);let i=serializeThread(e,n.thread,n.adapterName),a=normalizeSendInput(t),o={auth:n.auth??null,state:{thread:i}};return n.callback!==void 0&&(o.callback=n.callback),n.mode!==void 0&&(o.mode=n.mode),n.title!==void 0&&(o.title=n.title),n.turnPolicy!==void 0&&(o.turnPolicy=n.turnPolicy),n.taskDeliveryPolicy!==void 0&&(o.taskDeliveryPolicy=n.taskDeliveryPolicy),r.from(i.id)[INTERNAL_CHANNEL_DELIVER](a,o)}function initialState(){return{pendingAuthMessageIds:{},thread:null}}function threadFromState(e,t){if(!t.thread)return null;try{let n=t.thread;return new ThreadImpl({adapter:e.getAdapter(n.adapterName),channelId:n.channelId,channelVisibility:n.channelVisibility,currentMessage:n.currentMessage?Message.fromJSON(n.currentMessage):void 0,id:n.id,isDM:n.isDM,stateAdapter:e.getState()})}catch(e){return log.warn(`failed to rebuild Chat SDK thread from channel state`,{error:e}),null}}function serializeReceiveTarget(e,t){if(t.thread)return t.thread;if(!t.threadId)throw Error(`chatSdkChannel().receive requires target.thread or target.threadId.`);return serializeThread(e,t.threadId,t.adapterName)}function serializeThread(e,t,n){if(typeof t==`string`){let r=n??inferAdapterName(t),i=e.getAdapter(r);return{_type:`chat:Thread`,adapterName:r,channelId:i.channelIdFromThreadId(t),channelVisibility:i.getChannelVisibility?.(t),id:t,isDM:!1}}return isSerializedThread(t)?t:t.toJSON()}function isSerializedThread(e){return`_type`in e&&e._type===`chat:Thread`}function inferAdapterName(e){let t=e.indexOf(`:`);if(t<=0)throw Error(`chatSdkChannel string thread references require options.adapterName.`);return e.slice(0,t)}function adapterNames(e){return Object.keys(e)}function routeForAdapter(e,t){return t.routes?.[e]||`${(t.route??`/eve/v1`).replace(/\/$/u,``)}/${e}`}function encodeInputAction(e,t,n){return`${e}${encodeURIComponent(t)}:${encodeURIComponent(n)}`}function decodeInputAction(e,t,n){if(!e.startsWith(t))return null;let r=e.slice(t.length),i=r.indexOf(`:`);if(i<=0)return null;try{let e=decodeURIComponent(r.slice(0,i));return{optionId:n??decodeURIComponent(r.slice(i+1)),requestId:e}}catch{return null}}export{chatSdkChannel};

package/dist/src/public/channels/github/checkout.js

@@ -1 +1 @@
-import{shellQuote}from"#shared/shell-quote.js";import{resolveGitHubInstallationToken}from"#public/channels/github/auth.js";import{getGitHubPullRequest,getGitHubRepository}from"#public/channels/github/api.js";import{gitHubGitBrokerNetworkPolicy,gitHubRemoteUrl,isFullGitSha}from"#shared/git.js";async function checkoutGitHubRepository(e,t){let n=await resolveCheckoutDescriptor(t),r=e.resolvePath(t.path??`/workspace`),i=resolveCheckoutRef(t.ref,n);if(isFullGitSha(i)){let t=await readCheckoutHead(e,r);if(t===i)return{baseRef:n.baseRef,path:r,ref:i,sha:t}}let a=normalizeCheckoutDepth(t.depth),o=t.mode===`full`?``:` --depth ${a}`,s=await resolveGitHubInstallationToken({api:t.api,credentials:t.credentials,installationId:n.installationId}),c=gitHubRemoteUrl({owner:n.owner,repo:n.repo}),l=isFullGitSha(i)?i:`FETCH_HEAD`;await e.setNetworkPolicy(gitHubGitBrokerNetworkPolicy(s)),await runCheckoutCommand({command:`mkdir -p ${shellQuote(r)}`,label:`create checkout directory`,sandbox:e}),await runCheckoutCommand({command:`cd ${shellQuote(r)} && git init`,label:`initialize git repository`,sandbox:e}),await runCheckoutCommand({command:`cd ${shellQuote(r)} && git remote remove origin >/dev/null 2>&1 || true`,label:`reset git remote`,sandbox:e}),await runCheckoutCommand({command:`cd ${shellQuote(r)} && git remote add origin ${shellQuote(c)}`,label:`configure git remote`,sandbox:e}),await runCheckoutCommand({command:`cd ${shellQuote(r)} && GIT_TERMINAL_PROMPT=0 git fetch${o} origin ${shellQuote(i)}`,label:`fetch GitHub ref`,sandbox:e}),await runCheckoutCommand({command:`cd ${shellQuote(r)} && git checkout --detach ${shellQuote(l)}`,label:`checkout GitHub ref`,sandbox:e}),t.includeBase===!0&&n.baseSha!==null&&await runCheckoutCommand({command:`cd ${shellQuote(r)} && GIT_TERMINAL_PROMPT=0 git fetch${o} origin ${shellQuote(n.baseSha)}`,label:`fetch GitHub base ref`,sandbox:e});let u=(await runCheckoutCommand({command:`cd ${shellQuote(r)} && git rev-parse HEAD`,label:`resolve checked out commit`,sandbox:e})).stdout.trim()||n.headSha||i;return{baseRef:n.baseRef,path:r,ref:i,sha:u}}async function resolveCheckoutDescriptor(e){let t=readNonEmptyString(e.owner),n=readNonEmptyString(e.repo);if(t===void 0||n===void 0)throw Error(`GitHub checkout requires a repository owner and name.`);if(e.installationId===void 0||e.installationId===null)throw Error(`GitHub checkout requires a GitHub App installation id.`);let r=e.pullRequestNumber??null,i=readNonEmptyString(e.ref),a=null;r!==null&&(i===void 0&&((e.headSha===void 0||e.headSha===null)&&(e.headRef===void 0||e.headRef===null)||e.defaultBranch===void 0||e.defaultBranch===null)||e.includeBase===!0&&(e.baseSha===void 0||e.baseSha===null)||e.includeBase===!0&&(e.baseRef===void 0||e.baseRef===null))&&(a=await getGitHubPullRequest({api:e.api,credentials:e.credentials,installationId:e.installationId,owner:t,pullRequestNumber:r,repo:n}));let o=readNonEmptyString(e.defaultBranch)??a?.defaultBranch??await resolveRepositoryDefaultBranch(e,{owner:t,pullRequestNumber:r,repo:n});return{baseRef:e.baseRef??a?.base.ref??null,baseSha:e.baseSha??a?.base.sha??null,defaultBranch:o,headRef:e.headRef??a?.head.ref??null,headSha:e.headSha??a?.head.sha??null,installationId:e.installationId,owner:t,pullRequestNumber:r,repo:n}}async function resolveRepositoryDefaultBranch(e,t){return t.pullRequestNumber!==null||readNonEmptyString(e.ref)!==void 0||readNonEmptyString(e.headSha)!==void 0||readNonEmptyString(e.headRef)!==void 0?null:(await getGitHubRepository({api:e.api,credentials:e.credentials,installationId:e.installationId??void 0,owner:t.owner,repo:t.repo})).defaultBranch??null}function resolveCheckoutRef(e,t){if(e!==void 0&&e.trim().length>0)return e.trim();if(t.headSha!==null)return t.headSha;if(t.pullRequestNumber!==null)return`refs/pull/${t.pullRequestNumber}/head`;if(t.headRef!==null)return t.headRef;if(t.defaultBranch!==null)return t.defaultBranch;throw Error(`GitHub checkout could not resolve a ref to fetch.`)}async function readCheckoutHead(e,t){let n=await e.run({command:`cd ${shellQuote(t)} && git rev-parse HEAD 2>/dev/null`});if(n.exitCode!==0)return null;let r=String(n.stdout??``).trim();return isFullGitSha(r)?r:null}async function runCheckoutCommand(e){let t=await e.sandbox.run({command:e.command}),n=String(t.stderr??``),r=String(t.stdout??``);if(t.exitCode===0)return{stderr:n,stdout:r};throw Error([`GitHub checkout failed during ${e.label} (exit ${t.exitCode}).`,n?`stderr: ${n}`:void 0,r?`stdout: ${r}`:void 0,`Verify the GitHub App installation has access to this repository.`].filter(e=>e!==void 0).join(` `))}function normalizeCheckoutDepth(e){if(e===void 0)return 1;if(!Number.isFinite(e)||e<1)throw Error(`GitHub checkout depth must be a positive number.`);return Math.floor(e)}function readNonEmptyString(e){return typeof e==`string`&&e.trim().length>0?e.trim():void 0}export{checkoutGitHubRepository};
+import{shellQuote}from"#shared/shell-quote.js";import{resolveGitHubInstallationToken}from"#public/channels/github/auth.js";import{getGitHubPullRequest,getGitHubRepository}from"#public/channels/github/api.js";import{gitHubGitBrokerNetworkPolicy,gitHubRemoteUrl,isFullGitSha}from"#shared/git.js";async function checkoutGitHubRepository(e,t){let n=await resolveCheckoutDescriptor(t),r=e.resolvePath(t.path??`/workspace`),i=resolveCheckoutRef(t.ref,n);if(isFullGitSha(i)){let t=await readCheckoutHead(e,r);if(t===i)return{baseRef:n.baseRef,path:r,ref:i,sha:t}}let a=normalizeCheckoutDepth(t.depth),o=t.mode===`full`?``:` --depth ${a}`,s=await resolveGitHubInstallationToken({api:t.api,credentials:t.credentials,installationId:n.installationId}),c=gitHubRemoteUrl({owner:n.owner,repo:n.repo}),l=isFullGitSha(i)?i:`FETCH_HEAD`;if(e.setNetworkPolicy===void 0)throw Error(`GitHub checkout requires a sandbox provider with mutable network policy.`);await e.setNetworkPolicy(gitHubGitBrokerNetworkPolicy(s)),await runCheckoutCommand({command:`mkdir -p ${shellQuote(r)}`,label:`create checkout directory`,sandbox:e}),await runCheckoutCommand({command:`cd ${shellQuote(r)} && git init`,label:`initialize git repository`,sandbox:e}),await runCheckoutCommand({command:`cd ${shellQuote(r)} && git remote remove origin >/dev/null 2>&1 || true`,label:`reset git remote`,sandbox:e}),await runCheckoutCommand({command:`cd ${shellQuote(r)} && git remote add origin ${shellQuote(c)}`,label:`configure git remote`,sandbox:e}),await runCheckoutCommand({command:`cd ${shellQuote(r)} && GIT_TERMINAL_PROMPT=0 git fetch${o} origin ${shellQuote(i)}`,label:`fetch GitHub ref`,sandbox:e}),await runCheckoutCommand({command:`cd ${shellQuote(r)} && git checkout --detach ${shellQuote(l)}`,label:`checkout GitHub ref`,sandbox:e}),t.includeBase===!0&&n.baseSha!==null&&await runCheckoutCommand({command:`cd ${shellQuote(r)} && GIT_TERMINAL_PROMPT=0 git fetch${o} origin ${shellQuote(n.baseSha)}`,label:`fetch GitHub base ref`,sandbox:e});let u=(await runCheckoutCommand({command:`cd ${shellQuote(r)} && git rev-parse HEAD`,label:`resolve checked out commit`,sandbox:e})).stdout.trim()||n.headSha||i;return{baseRef:n.baseRef,path:r,ref:i,sha:u}}async function resolveCheckoutDescriptor(e){let t=readNonEmptyString(e.owner),n=readNonEmptyString(e.repo);if(t===void 0||n===void 0)throw Error(`GitHub checkout requires a repository owner and name.`);if(e.installationId===void 0||e.installationId===null)throw Error(`GitHub checkout requires a GitHub App installation id.`);let r=e.pullRequestNumber??null,i=readNonEmptyString(e.ref),a=null;r!==null&&(i===void 0&&((e.headSha===void 0||e.headSha===null)&&(e.headRef===void 0||e.headRef===null)||e.defaultBranch===void 0||e.defaultBranch===null)||e.includeBase===!0&&(e.baseSha===void 0||e.baseSha===null)||e.includeBase===!0&&(e.baseRef===void 0||e.baseRef===null))&&(a=await getGitHubPullRequest({api:e.api,credentials:e.credentials,installationId:e.installationId,owner:t,pullRequestNumber:r,repo:n}));let o=readNonEmptyString(e.defaultBranch)??a?.defaultBranch??await resolveRepositoryDefaultBranch(e,{owner:t,pullRequestNumber:r,repo:n});return{baseRef:e.baseRef??a?.base.ref??null,baseSha:e.baseSha??a?.base.sha??null,defaultBranch:o,headRef:e.headRef??a?.head.ref??null,headSha:e.headSha??a?.head.sha??null,installationId:e.installationId,owner:t,pullRequestNumber:r,repo:n}}async function resolveRepositoryDefaultBranch(e,t){return t.pullRequestNumber!==null||readNonEmptyString(e.ref)!==void 0||readNonEmptyString(e.headSha)!==void 0||readNonEmptyString(e.headRef)!==void 0?null:(await getGitHubRepository({api:e.api,credentials:e.credentials,installationId:e.installationId??void 0,owner:t.owner,repo:t.repo})).defaultBranch??null}function resolveCheckoutRef(e,t){if(e!==void 0&&e.trim().length>0)return e.trim();if(t.headSha!==null)return t.headSha;if(t.pullRequestNumber!==null)return`refs/pull/${t.pullRequestNumber}/head`;if(t.headRef!==null)return t.headRef;if(t.defaultBranch!==null)return t.defaultBranch;throw Error(`GitHub checkout could not resolve a ref to fetch.`)}async function readCheckoutHead(e,t){let n=await e.run({command:`cd ${shellQuote(t)} && git rev-parse HEAD 2>/dev/null`});if(n.exitCode!==0)return null;let r=String(n.stdout??``).trim();return isFullGitSha(r)?r:null}async function runCheckoutCommand(e){let t=await e.sandbox.run({command:e.command}),n=String(t.stderr??``),r=String(t.stdout??``);if(t.exitCode===0)return{stderr:n,stdout:r};throw Error([`GitHub checkout failed during ${e.label} (exit ${t.exitCode}).`,n?`stderr: ${n}`:void 0,r?`stdout: ${r}`:void 0,`Verify the GitHub App installation has access to this repository.`].filter(e=>e!==void 0).join(` `))}function normalizeCheckoutDepth(e){if(e===void 0)return 1;if(!Number.isFinite(e)||e<1)throw Error(`GitHub checkout depth must be a positive number.`);return Math.floor(e)}function readNonEmptyString(e){return typeof e==`string`&&e.trim().length>0?e.trim():void 0}export{checkoutGitHubRepository};

package/dist/src/public/channels/index.d.ts

@@ -1,4 +1,4 @@
-export { defineChannel, disableRoute, GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE, WS, type AttachSessionFn, type CancelTurnResult, type ClearSessionResult, type CompactSessionResult, type ResetSessionResult, type Channel, type ChannelAudience, type AudienceCaller, type AudienceContext, type AudienceInput, type AudiencePrincipal, type ConversationEnvironment, type ChannelFrom, type ChannelReceiveContext, type ChannelResolveSession, type ChannelRespondOptions, type ChannelSendOptions, type ChannelSource, type ChannelCors, type ChannelCorsOptions, type ChannelDefinition, type DisabledRouteSentinel, type ChannelContinuationOps, type ChannelEvents, type InferChannelMetadata, type Session, type SessionCallback, type SessionHandle, type SessionRespondOptions, type SessionSendOptions, type TurnPolicy, type RouteDefinition, type RouteHandlerArgs, type HttpRouteDefinition, type WebSocketMessage, type WebSocketPeer, type WebSocketRouteDefinition, type WebSocketRouteHandler, type WebSocketRouteHooks, type WebSocketUpgradeRequest, type WebSocketUpgradeResult, isDisabledRouteSentinel, } from "#public/definitions/channel.js";
+export { defineChannel, disableRoute, GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE, WS, type AttachSessionFn, type CancelTurnResult, type ClearSessionResult, type CompactSessionResult, type ResetSessionResult, type Channel, type ChannelAudience, type AudienceCaller, type AudienceContext, type AudienceInput, type AudiencePrincipal, type ConversationEnvironment, type ChannelFrom, type ChannelReceiveContext, type ChannelResolveSession, type ChannelRespondOptions, type ChannelSendOptions, type ChannelSource, type ChannelCors, type ChannelCorsOptions, type ChannelDefinition, type DisabledRouteSentinel, type ChannelContinuationOps, type ChannelEvents, type InferChannelMetadata, type Session, type SessionCallback, type SessionHandle, type SessionRespondOptions, type SessionSendOptions, type TurnPolicy, type TaskDeliveryPolicy, type RouteDefinition, type RouteHandlerArgs, type HttpRouteDefinition, type WebSocketMessage, type WebSocketPeer, type WebSocketRouteDefinition, type WebSocketRouteHandler, type WebSocketRouteHooks, type WebSocketUpgradeRequest, type WebSocketUpgradeResult, isDisabledRouteSentinel, } from "#public/definitions/channel.js";
 export { createWebSocketUpgradeServer, type WebSocketUpgradeServerBridge, } from "#channel/websocket-upgrade-server.js";
 import type { Channel, InferChannelMetadata } from "#public/definitions/channel.js";
 /**

package/dist/src/public/channels/slack/slackChannel.d.ts

@@ -1,7 +1,7 @@
 import type { UserContent } from "ai";
 import type { ChannelResolveSession, ChannelSource } from "#channel/channel-operations.js";
 import type { Session } from "#channel/session.js";
-import type { SessionAuthContext, TurnPolicy } from "#channel/types.js";
+import type { SessionAuthContext, TurnPolicy, TaskDeliveryPolicy } from "#channel/types.js";
 import type { CardElement } from "#compiled/chat/index.js";
 import type { SessionContext } from "#public/definitions/callback-context.js";
 import type { ChannelContinuationOps } from "#public/definitions/channel.js";
@@ -221,6 +221,8 @@ export interface SlackInitialMessage {
  * Options for one turn requested by a generic Slack event handler.
  */
 export interface SlackEventSendOptions {
+    /** Updates the session policy; omission preserves it. */
+    readonly taskDeliveryPolicy?: TaskDeliveryPolicy;
     readonly auth: SessionAuthContext | null;
     readonly target: SlackReceiveTarget;
     /** Overrides the workflow run title without changing the message sent to the model. */

package/dist/src/public/channels/slack/slackChannel.js

@@ -1 +1 @@
-import{markEventHandled}from"./utils.js";import{createLogger,logError}from"#internal/logging.js";import{normalizeChannelAudience}from"#shared/channel-audience.js";import{setChannelActivityRenderers}from"#channel/compiled-channel.js";import{defaultDeliverResult}from"#channel/adapter.js";import{POST,defineChannel}from"#public/definitions/channel.js";import{mergeUploadPolicy}from"#public/channels/upload-policy.js";import{buildSlackBinding,buildSlackWorkspaceHandle,slackContinuationToken}from"#public/channels/slack/api.js";import{buildSlackAuthContext,slackUserIdFromAuthContext}from"#public/channels/slack/auth.js";import{defaultEvents,defaultInputRequestedHandler,defaultOnAppMention,defaultOnDirectMessage,postCompletedSlackReply}from"#public/channels/slack/defaults.js";import{buildSlackActivityRenderers,hasSlackActivityStatus}from"#public/channels/slack/activity.js";import{loadThreadContextMessages}from"#public/channels/slack/thread.js";import{parseSlackWebhookBody}from"#compiled/@chat-adapter/slack/webhook.js";import{bindSlackSessionOperations}from"#public/channels/slack/session-operations.js";import{buildSlackTurnMessage,collectInboundFileParts,createSlackFetchFile}from"#public/channels/slack/attachments.js";import{parseMessageEvent,parseSlackEventEnvelope,slackEventBotUserId,slackEventInstallationTeamId,slackEventReceivingBotUserId,slackMessageFromWebhookPayload}from"#public/channels/slack/inbound.js";import{formatSlackInboundMessage,formatSlackThreadContext}from"#public/channels/slack/model-context.js";import{isPrivateSlackConversation}from"#public/channels/slack/privacy.js";import{SLACK_CHANNEL_DEFAULT_ROUTE}from"#public/channels/slack/constants.js";import{handleInteractionPost}from"#public/channels/slack/interactions.js";import{verifySlackRequest as verifySlackRequest$1}from"#public/channels/slack/verify.js";const log=createLogger(`slack.channel`),ignoreSlackActivityEvent=async()=>void 0,activityOwnedMessageCompleted=async(e,t)=>{t.state.pendingToolCallMessage=null,e.finishReason!==`tool-calls`&&e.message&&await postCompletedSlackReply(t,e.message)},clearSlackTurnState=async(e,t)=>{t.state.pendingToolCallMessage=null,t.state.lastReasoningTypingAtMs=null,t.state.lastReasoningTypingStatus=null};function rebuildSlackContext(e,t,n){let{thread:r,slack:i}=buildSlackBinding({botToken:n?.botToken,channelId:e.channelId??``,threadTs:e.threadTs??``,installationTeamId:e.installationTeamId??void 0,teamId:e.teamId??void 0,onThreadTsChanged(n){e.threadTs=n,e.channelId&&t.continuation?.alias(slackContinuationToken(e.channelId,n))}});return{thread:r,slack:i,state:e}}function slackChannel(e={}){let t=mergeUploadPolicy(e.uploadPolicy),n=createSlackFetchFile({botToken:e.credentials?.botToken}),r=buildSlackActivityRenderers({botToken:e.credentials?.botToken,renderers:e.activity?.renderers??[]}),i=e.onInputResponse??defaultOnInputResponse,a=e.events?.[`authorization.required`],o=e.events?.[`approval.candidate`]??defaultEvents[`approval.candidate`],s=hasSlackActivityStatus(e.activity?.renderers),c=e.events?.[`turn.started`]??(s?clearSlackTurnState:defaultEvents[`turn.started`]),l=e.events?.[`reasoning.appended`]??(s?ignoreSlackActivityEvent:defaultEvents[`reasoning.appended`]),u=e.events?.[`actions.requested`]??(s?ignoreSlackActivityEvent:defaultEvents[`actions.requested`]),d=e.events?.[`message.completed`]??(s?activityOwnedMessageCompleted:defaultEvents[`message.completed`]),f=defaultInputRequestedHandler(e.approvalChannel),p=e.events?.[`input.requested`],m=p===void 0?f:async(e,t,n)=>p(e,t,n,async e=>{await f(e,t,n)}),h={...defaultEvents,...e.events,async"approval.candidate"(e,t,n){let r=t.state.approvalResponderUsers?.[e.responderPrincipalId];if(e.outcome===`pending`&&r!==void 0&&(t.state.pendingApprovalCandidateUsers={...t.state.pendingApprovalCandidateUsers,[e.candidateId]:r}),await o(e,t,n),e.outcome!==`pending`){let n={...t.state.pendingApprovalCandidateUsers};delete n[e.candidateId],t.state.pendingApprovalCandidateUsers=n}},async"turn.started"(e,t,n){let r=slackUserIdFromAuthContext(n.session.auth.current);r!==void 0&&(t.state.triggeringUserId=r),await c(e,t,n)},"reasoning.appended":l,"actions.requested":u,"message.completed":d,"input.requested":m,"authorization.required":a===void 0?defaultEvents[`authorization.required`]:constrainAuthorizationRequired(a)},g=new Set,_=defineChannel({kindHint:`slack`,turnPolicy:e.turnPolicy,state:{channelId:null,threadTs:null,teamId:null,installationTeamId:null,triggeringUserId:null,triggeringMessageTs:null,pendingToolCallMessage:null,lastReasoningTypingAtMs:null,lastReasoningTypingStatus:null,pendingAuthMessageTs:{},pendingApprovalCards:{},pendingApprovalCandidateUsers:{},approvalResponderUsers:{}},fetchFile:n,metadata(e){return{channelId:e.channelId,teamId:e.teamId,threadTs:e.threadTs,triggeringUserId:e.triggeringUserId??null}},audience:({state:e})=>e.audience??`unknown`,context(t,n){return rebuildSlackContext(t,n,e.credentials)},deliver(e,t){let n=e.pendingApprovalCards;typeof n==`object`&&n&&(t.state.pendingApprovalCards={...t.state.pendingApprovalCards,...n});let r=e.state?.approvalResponderUsers;return typeof r==`object`&&r&&(t.state.approvalResponderUsers={...t.state.approvalResponderUsers,...r}),defaultDeliverResult(e)},routes:[POST(e.route??SLACK_CHANNEL_DEFAULT_ROUTE,async(n,r)=>{let{waitUntil:a}=r,{from:o,resolveSession:s}=r,c=await verifyInbound(n,e.credentials);return c===null?new Response(`unauthorized`,{status:401}):shouldDropSlackHttpTimeoutRetry(n.headers)?new Response(`ok`):(n.headers.get(`content-type`)??``).includes(`application/x-www-form-urlencoded`)?handleInteractionPost(c,{from:o,resolveSession:s,waitUntil:a},{config:e,onInputResponse:i}):handleEventPost({body:c,from:o,resolveSession:s,waitUntil:a,config:e,uploadPolicy:t,handledEvents:g,headers:n.headers})})],receive(t,{from:n}){return receiveOnSlack(t,{from:n,credentials:e.credentials})},events:h});return setChannelActivityRenderers(_,{destination(e){let t=e;return{channelId:t?.channelId??null,installationTeamId:t?.installationTeamId??null,teamId:t?.teamId??null,threadTs:t?.threadTs??null,triggeringUserId:t?.triggeringUserId??null}},renderers:r}),_}function defaultOnInputResponse(e){return{auth:e.defaultAuth}}async function receiveOnSlack(e,t){let n=e.target,r=n.channelId;if(!r||typeof r!=`string`)throw Error(`slackChannel().receive requires target.channelId.`);let i=typeof n.threadTs==`string`?n.threadTs:``,a=typeof n.installationTeamId==`string`?n.installationTeamId:t.installationTeamId,o=n.initialMessage;if(o&&i.length>0)throw Error("slackChannel().receive: `threadTs` and `initialMessage` are mutually exclusive.");let s=i;if(o){let{thread:e}=buildSlackBinding({botToken:t.credentials?.botToken,channelId:r,threadTs:``,installationTeamId:a,teamId:t.teamId}),n={card:o.card};o.fallbackText!==void 0&&(n.fallbackText=o.fallbackText),s=(await e.post(n)).id}let c=s||crypto.randomUUID(),l=n.audience===void 0?void 0:normalizeChannelAudience(n.audience),u={channelId:r,installationTeamId:a??null,threadTs:s||null,teamId:t.teamId??null,triggeringUserId:t.triggeringUserId??null};return l!==void 0&&(u.audience=l),t.from(slackContinuationToken(r,c)).send(e.message,{auth:e.auth,state:u,title:e.title})}function constrainAuthorizationRequired(e){return(t,n,r)=>e(t,{postEphemeral:(e,t)=>n.thread.postEphemeral(e,t),postDirectMessage:(e,t)=>n.thread.postDirectMessage(e,t),state:n.state},r)}function shouldDropSlackHttpTimeoutRetry(e){return Number(e.get(`x-slack-retry-num`)??`0`)>=1&&e.get(`x-slack-retry-reason`)===`http_timeout`}async function handleEventPost(e){let{config:t}=e,n,r;try{n=parseSlackWebhookBody(e.body,{headers:e.headers}),r=parseSlackEventEnvelope(e.body)}catch(e){return log.warn(`inbound webhook body is not valid JSON`,{error:e}),new Response(`ok`)}if(n.kind===`url_verification`)return new Response(n.challenge,{status:200,headers:{"content-type":`text/plain`}});if(r===null)return new Response(`ok`);let i=typeof r.api_app_id==`string`?r.api_app_id:void 0,a=slackEventBotUserId(r),o=slackEventReceivingBotUserId(r),s=slackEventInstallationTeamId(r),dispatch=null,c=null;if(n.kind===`app_mention`||n.kind===`direct_message`){let r=n.kind,l=slackMessageFromWebhookPayload(n);if(l!==null&&!isSelfAuthoredSlackMessage({appId:i,botUserId:a},l)){let dispatchMessageWith=n=>()=>dispatchSlackMessage({appId:i,botUserId:a,receivingBotUserId:o,from:e.from,resolveSession:e.resolveSession,credentials:t.credentials,handler:n,installationTeamId:s,kind:r,message:l,threadContext:t.threadContext,uploadPolicy:e.uploadPolicy}),n=(r===`app_mention`?t.onAppMention:t.onDirectMessage)??t.onMessage;n===void 0?c=dispatchMessageWith(r===`app_mention`?defaultOnAppMention:defaultOnDirectMessage):dispatch=()=>dispatchSlackMessage({appId:i,botUserId:a,receivingBotUserId:o,from:e.from,resolveSession:e.resolveSession,credentials:t.credentials,handler:n,installationTeamId:s,kind:r,message:l,threadContext:t.threadContext,uploadPolicy:e.uploadPolicy})}}if(dispatch===null&&t.onMessage!==void 0){let n=parseMessageEvent(r);n!==null&&!isSelfAuthoredSlackMessage({appId:i,botUserId:a},n)&&(a===void 0||!n.text.includes(`<@${a}`))&&(dispatch=()=>dispatchSlackMessage({appId:i,botUserId:a,receivingBotUserId:o,from:e.from,resolveSession:e.resolveSession,credentials:t.credentials,handler:t.onMessage,installationTeamId:s,kind:`channel_message`,message:n,threadContext:t.threadContext,uploadPolicy:e.uploadPolicy}))}let l=t.onEvent;if(dispatch===null&&l!==void 0&&(dispatch=()=>dispatchSlackEvent({from:e.from,resolveSession:e.resolveSession,credentials:t.credentials,envelope:r,handler:l,installationTeamId:s})),dispatch??=c,dispatch===null)return new Response(`ok`);let u=r.event_id;if(u){if(e.handledEvents.has(u))return log.warn(`received a duplicate event`,{event_id:u,event_time:r.event_time,retry_num:n.retry?.num??`(null)`,retry_reason:n.retry?.reason??`(null)`}),new Response(`ok`);markEventHandled(u,e.handledEvents)}return e.waitUntil(dispatch()),new Response(`ok`)}function isSelfAuthoredSlackMessage(e,t){return e.botUserId!==void 0&&t.author?.userId===e.botUserId||e.appId!==void 0&&t.raw.app_id===e.appId}async function dispatchSlackMessage(e){let t=slackContinuationToken(e.message.channelId,e.message.threadTs),{thread:n,slack:r}=buildSlackBinding({appId:e.appId,botToken:e.credentials?.botToken,botUserId:e.botUserId,channelId:e.message.channelId,threadTs:e.message.threadTs,installationTeamId:e.installationTeamId,teamId:e.message.teamId}),i=e.message.author,a={channelId:e.message.channelId,installationTeamId:e.installationTeamId??null,teamId:e.message.teamId??null,threadTs:e.message.threadTs,triggeringMessageTs:e.message.ts,triggeringUserId:i?.userId??null},o=bindSlackSessionOperations({address:t,defaultAuth:i===void 0?null:buildSlackAuthContext({channelId:e.message.channelId,fullName:i.fullName,isBot:i.isBot,teamId:e.message.teamId,threadTs:e.message.threadTs,userId:i.userId,userName:i.userName}),from:e.from,resolveSession:e.resolveSession,state:a}),s,isDMOrPrivateChannel=()=>s??=isPrivateSlackConversation({channelId:e.message.channelId,raw:e.message.raw,request:r.request}),c=e.kind===`app_mention`||e.botUserId!==void 0&&e.message.text.includes(`<@${e.botUserId}`),l={...o,isBotMentioned:()=>c,isDMOrPrivateChannel,isSubscribed:async()=>await o.resolveSession()!==void 0,slack:r,thread:n},u;try{u=await e.handler(l,e.message)}catch(t){logError(log,`${e.kind} handler failed`,t,{channelId:e.message.channelId});return}if(u==null)return;let d=await isDMOrPrivateChannel();a.audience=e.kind===`direct_message`||d?`private`:`public`,await deliverSlackMessage({botUserId:e.receivingBotUserId,credentials:e.credentials,kind:e.kind,isPrivateConversation:d,isMentioned:c,message:e.message,result:u,sessionOperations:o,thread:n,threadContext:e.threadContext,uploadPolicy:e.uploadPolicy})}async function dispatchSlackEvent(e){let t=e.envelope.event.team_id,n=typeof t==`string`?t:typeof e.envelope.team_id==`string`?e.envelope.team_id:void 0,r=[],sourceFor=t=>e.from(slackContinuationToken(t.channelId,t.threadTs)),i={cancel:({target:e,turnId:t})=>sourceFor(e).cancel({turnId:t}),clear:({target:e})=>sourceFor(e).clear(),compact:({target:e})=>sourceFor(e).compact(),envelope:e.envelope,reset:({reason:e,target:t})=>sourceFor(t).reset({reason:e}),resolveSession:({target:t})=>e.resolveSession(slackContinuationToken(t.channelId,t.threadTs)),respond:(e,{auth:t,target:n})=>sourceFor(n).respond(e,{auth:t}),send:(t,{auth:r,target:i,title:a})=>receiveOnSlack({auth:r,message:t,target:i,title:a},{from:e.from,credentials:e.credentials,installationTeamId:e.installationTeamId,teamId:n,...typeof e.envelope.event.user==`string`?{triggeringUserId:e.envelope.event.user}:{}}),slack:buildSlackWorkspaceHandle({botToken:e.credentials?.botToken,installationTeamId:e.installationTeamId,teamId:n}),waitUntil(e){r.push(e)}};try{await e.handler(i,e.envelope.event)}catch(t){logError(log,`event handler failed`,t,{eventId:e.envelope.event_id,eventType:e.envelope.event.type})}await Promise.allSettled(r)}async function verifyInbound(e,t){try{return await verifySlackRequest$1(e,{signingSecret:t?.signingSecret??(t?.webhookVerifier?void 0:process.env.SLACK_SIGNING_SECRET),webhookVerifier:t?.webhookVerifier})}catch(e){return log.warn(`slack inbound verification failed`,{error:e}),null}}async function deliverSlackMessage(e){let{message:t,thread:n}=e;try{let r=e.threadContext===void 0?[]:await loadThreadContextMessages(n,t,e.threadContext),i=formatSlackThreadContext(r),a=await collectInboundFileParts({mention:t,thread:n,policy:e.uploadPolicy}),o={botUserId:e.botUserId,channelId:t.channelId,fullName:t.author?.fullName,isMentioned:e.isMentioned,teamId:t.teamId,threadTs:t.threadTs,userId:t.author?.userId??``,userName:t.author?.userName},s=formatSlackInboundMessage(o,t),c=buildSlackTurnMessage(i===void 0?s:`${i}\n\n${s}`,a),l=e.result.context??[],u=e.isPrivateConversation?`Private message`:e.result.title??t.markdown,d=l.length===0?{auth:e.result.auth,title:u}:{auth:e.result.auth,context:l,title:u};await e.sessionOperations.send(c,d)}catch(n){logError(log,`${e.kind} delivery failed`,n,{channelId:t.channelId})}}export{constrainAuthorizationRequired,slackChannel};
+import{markEventHandled}from"./utils.js";import{createLogger,logError}from"#internal/logging.js";import{normalizeChannelAudience}from"#shared/channel-audience.js";import{setChannelActivityRenderers}from"#channel/compiled-channel.js";import{defaultDeliverResult}from"#channel/adapter.js";import{POST,defineChannel}from"#public/definitions/channel.js";import{mergeUploadPolicy}from"#public/channels/upload-policy.js";import{buildSlackBinding,buildSlackWorkspaceHandle,slackContinuationToken}from"#public/channels/slack/api.js";import{buildSlackAuthContext,slackUserIdFromAuthContext}from"#public/channels/slack/auth.js";import{defaultEvents,defaultInputRequestedHandler,defaultOnAppMention,defaultOnDirectMessage,postCompletedSlackReply}from"#public/channels/slack/defaults.js";import{buildSlackActivityRenderers,hasSlackActivityStatus}from"#public/channels/slack/activity.js";import{loadThreadContextMessages}from"#public/channels/slack/thread.js";import{parseSlackWebhookBody}from"#compiled/@chat-adapter/slack/webhook.js";import{bindSlackSessionOperations}from"#public/channels/slack/session-operations.js";import{buildSlackTurnMessage,collectInboundFileParts,createSlackFetchFile}from"#public/channels/slack/attachments.js";import{parseMessageEvent,parseSlackEventEnvelope,slackEventBotUserId,slackEventInstallationTeamId,slackEventReceivingBotUserId,slackMessageFromWebhookPayload}from"#public/channels/slack/inbound.js";import{formatSlackInboundMessage,formatSlackThreadContext}from"#public/channels/slack/model-context.js";import{isPrivateSlackConversation}from"#public/channels/slack/privacy.js";import{SLACK_CHANNEL_DEFAULT_ROUTE}from"#public/channels/slack/constants.js";import{handleInteractionPost}from"#public/channels/slack/interactions.js";import{verifySlackRequest as verifySlackRequest$1}from"#public/channels/slack/verify.js";const log=createLogger(`slack.channel`),ignoreSlackActivityEvent=async()=>void 0,activityOwnedMessageCompleted=async(e,t)=>{t.state.pendingToolCallMessage=null,e.finishReason!==`tool-calls`&&e.message&&await postCompletedSlackReply(t,e.message)},clearSlackTurnState=async(e,t)=>{t.state.pendingToolCallMessage=null,t.state.lastReasoningTypingAtMs=null,t.state.lastReasoningTypingStatus=null};function rebuildSlackContext(e,t,n){let{thread:r,slack:i}=buildSlackBinding({botToken:n?.botToken,channelId:e.channelId??``,threadTs:e.threadTs??``,installationTeamId:e.installationTeamId??void 0,teamId:e.teamId??void 0,onThreadTsChanged(n){e.threadTs=n,e.channelId&&t.continuation?.alias(slackContinuationToken(e.channelId,n))}});return{thread:r,slack:i,state:e}}function slackChannel(e={}){let t=mergeUploadPolicy(e.uploadPolicy),n=createSlackFetchFile({botToken:e.credentials?.botToken}),r=buildSlackActivityRenderers({botToken:e.credentials?.botToken,renderers:e.activity?.renderers??[]}),i=e.onInputResponse??defaultOnInputResponse,a=e.events?.[`authorization.required`],o=e.events?.[`approval.candidate`]??defaultEvents[`approval.candidate`],s=hasSlackActivityStatus(e.activity?.renderers),c=e.events?.[`turn.started`]??(s?clearSlackTurnState:defaultEvents[`turn.started`]),l=e.events?.[`reasoning.appended`]??(s?ignoreSlackActivityEvent:defaultEvents[`reasoning.appended`]),u=e.events?.[`actions.requested`]??(s?ignoreSlackActivityEvent:defaultEvents[`actions.requested`]),d=e.events?.[`message.completed`]??(s?activityOwnedMessageCompleted:defaultEvents[`message.completed`]),f=defaultInputRequestedHandler(e.approvalChannel),p=e.events?.[`input.requested`],m=p===void 0?f:async(e,t,n)=>p(e,t,n,async e=>{await f(e,t,n)}),h={...defaultEvents,...e.events,async"approval.candidate"(e,t,n){let r=t.state.approvalResponderUsers?.[e.responderPrincipalId];if(e.outcome===`pending`&&r!==void 0&&(t.state.pendingApprovalCandidateUsers={...t.state.pendingApprovalCandidateUsers,[e.candidateId]:r}),await o(e,t,n),e.outcome!==`pending`){let n={...t.state.pendingApprovalCandidateUsers};delete n[e.candidateId],t.state.pendingApprovalCandidateUsers=n}},async"turn.started"(e,t,n){let r=slackUserIdFromAuthContext(n.session.auth.current);r!==void 0&&(t.state.triggeringUserId=r),await c(e,t,n)},"reasoning.appended":l,"actions.requested":u,"message.completed":d,"input.requested":m,"authorization.required":a===void 0?defaultEvents[`authorization.required`]:constrainAuthorizationRequired(a)},g=new Set,_=defineChannel({kindHint:`slack`,turnPolicy:e.turnPolicy,state:{channelId:null,threadTs:null,teamId:null,installationTeamId:null,triggeringUserId:null,triggeringMessageTs:null,pendingToolCallMessage:null,lastReasoningTypingAtMs:null,lastReasoningTypingStatus:null,pendingAuthMessageTs:{},pendingApprovalCards:{},pendingApprovalCandidateUsers:{},approvalResponderUsers:{}},fetchFile:n,metadata(e){return{channelId:e.channelId,teamId:e.teamId,threadTs:e.threadTs,triggeringUserId:e.triggeringUserId??null}},audience:({state:e})=>e.audience??`unknown`,context(t,n){return rebuildSlackContext(t,n,e.credentials)},deliver(e,t){let n=e.pendingApprovalCards;typeof n==`object`&&n&&(t.state.pendingApprovalCards={...t.state.pendingApprovalCards,...n});let r=e.state?.approvalResponderUsers;return typeof r==`object`&&r&&(t.state.approvalResponderUsers={...t.state.approvalResponderUsers,...r}),defaultDeliverResult(e)},routes:[POST(e.route??SLACK_CHANNEL_DEFAULT_ROUTE,async(n,r)=>{let{waitUntil:a}=r,{from:o,resolveSession:s}=r,c=await verifyInbound(n,e.credentials);return c===null?new Response(`unauthorized`,{status:401}):shouldDropSlackHttpTimeoutRetry(n.headers)?new Response(`ok`):(n.headers.get(`content-type`)??``).includes(`application/x-www-form-urlencoded`)?handleInteractionPost(c,{from:o,resolveSession:s,waitUntil:a},{config:e,onInputResponse:i}):handleEventPost({body:c,from:o,resolveSession:s,waitUntil:a,config:e,uploadPolicy:t,handledEvents:g,headers:n.headers})})],receive(t,{from:n}){return receiveOnSlack(t,{from:n,credentials:e.credentials})},events:h});return setChannelActivityRenderers(_,{destination(e){let t=e;return{channelId:t?.channelId??null,installationTeamId:t?.installationTeamId??null,teamId:t?.teamId??null,threadTs:t?.threadTs??null,triggeringUserId:t?.triggeringUserId??null}},renderers:r}),_}function defaultOnInputResponse(e){return{auth:e.defaultAuth}}async function receiveOnSlack(e,t){let n=e.target,r=n.channelId;if(!r||typeof r!=`string`)throw Error(`slackChannel().receive requires target.channelId.`);let i=typeof n.threadTs==`string`?n.threadTs:``,a=typeof n.installationTeamId==`string`?n.installationTeamId:t.installationTeamId,o=n.initialMessage;if(o&&i.length>0)throw Error("slackChannel().receive: `threadTs` and `initialMessage` are mutually exclusive.");let s=i;if(o){let{thread:e}=buildSlackBinding({botToken:t.credentials?.botToken,channelId:r,threadTs:``,installationTeamId:a,teamId:t.teamId}),n={card:o.card};o.fallbackText!==void 0&&(n.fallbackText=o.fallbackText),s=(await e.post(n)).id}let c=s||crypto.randomUUID(),l=n.audience===void 0?void 0:normalizeChannelAudience(n.audience),u={channelId:r,installationTeamId:a??null,threadTs:s||null,teamId:t.teamId??null,triggeringUserId:t.triggeringUserId??null};return l!==void 0&&(u.audience=l),t.from(slackContinuationToken(r,c)).send(e.message,{auth:e.auth,state:u,title:e.title,taskDeliveryPolicy:e.taskDeliveryPolicy})}function constrainAuthorizationRequired(e){return(t,n,r)=>e(t,{postEphemeral:(e,t)=>n.thread.postEphemeral(e,t),postDirectMessage:(e,t)=>n.thread.postDirectMessage(e,t),state:n.state},r)}function shouldDropSlackHttpTimeoutRetry(e){return Number(e.get(`x-slack-retry-num`)??`0`)>=1&&e.get(`x-slack-retry-reason`)===`http_timeout`}async function handleEventPost(e){let{config:t}=e,n,r;try{n=parseSlackWebhookBody(e.body,{headers:e.headers}),r=parseSlackEventEnvelope(e.body)}catch(e){return log.warn(`inbound webhook body is not valid JSON`,{error:e}),new Response(`ok`)}if(n.kind===`url_verification`)return new Response(n.challenge,{status:200,headers:{"content-type":`text/plain`}});if(r===null)return new Response(`ok`);let i=typeof r.api_app_id==`string`?r.api_app_id:void 0,a=slackEventBotUserId(r),o=slackEventReceivingBotUserId(r),s=slackEventInstallationTeamId(r),dispatch=null,c=null;if(n.kind===`app_mention`||n.kind===`direct_message`){let r=n.kind,l=slackMessageFromWebhookPayload(n);if(l!==null&&!isSelfAuthoredSlackMessage({appId:i,botUserId:a},l)){let dispatchMessageWith=n=>()=>dispatchSlackMessage({appId:i,botUserId:a,receivingBotUserId:o,from:e.from,resolveSession:e.resolveSession,credentials:t.credentials,handler:n,installationTeamId:s,kind:r,message:l,threadContext:t.threadContext,uploadPolicy:e.uploadPolicy}),n=(r===`app_mention`?t.onAppMention:t.onDirectMessage)??t.onMessage;n===void 0?c=dispatchMessageWith(r===`app_mention`?defaultOnAppMention:defaultOnDirectMessage):dispatch=()=>dispatchSlackMessage({appId:i,botUserId:a,receivingBotUserId:o,from:e.from,resolveSession:e.resolveSession,credentials:t.credentials,handler:n,installationTeamId:s,kind:r,message:l,threadContext:t.threadContext,uploadPolicy:e.uploadPolicy})}}if(dispatch===null&&t.onMessage!==void 0){let n=parseMessageEvent(r);n!==null&&!isSelfAuthoredSlackMessage({appId:i,botUserId:a},n)&&(a===void 0||!n.text.includes(`<@${a}`))&&(dispatch=()=>dispatchSlackMessage({appId:i,botUserId:a,receivingBotUserId:o,from:e.from,resolveSession:e.resolveSession,credentials:t.credentials,handler:t.onMessage,installationTeamId:s,kind:`channel_message`,message:n,threadContext:t.threadContext,uploadPolicy:e.uploadPolicy}))}let l=t.onEvent;if(dispatch===null&&l!==void 0&&(dispatch=()=>dispatchSlackEvent({from:e.from,resolveSession:e.resolveSession,credentials:t.credentials,envelope:r,handler:l,installationTeamId:s})),dispatch??=c,dispatch===null)return new Response(`ok`);let u=r.event_id;if(u){if(e.handledEvents.has(u))return log.warn(`received a duplicate event`,{event_id:u,event_time:r.event_time,retry_num:n.retry?.num??`(null)`,retry_reason:n.retry?.reason??`(null)`}),new Response(`ok`);markEventHandled(u,e.handledEvents)}return e.waitUntil(dispatch()),new Response(`ok`)}function isSelfAuthoredSlackMessage(e,t){return e.botUserId!==void 0&&t.author?.userId===e.botUserId||e.appId!==void 0&&t.raw.app_id===e.appId}async function dispatchSlackMessage(e){let t=slackContinuationToken(e.message.channelId,e.message.threadTs),{thread:n,slack:r}=buildSlackBinding({appId:e.appId,botToken:e.credentials?.botToken,botUserId:e.botUserId,channelId:e.message.channelId,threadTs:e.message.threadTs,installationTeamId:e.installationTeamId,teamId:e.message.teamId}),i=e.message.author,a={channelId:e.message.channelId,installationTeamId:e.installationTeamId??null,teamId:e.message.teamId??null,threadTs:e.message.threadTs,triggeringMessageTs:e.message.ts,triggeringUserId:i?.userId??null},o=bindSlackSessionOperations({address:t,defaultAuth:i===void 0?null:buildSlackAuthContext({channelId:e.message.channelId,fullName:i.fullName,isBot:i.isBot,teamId:e.message.teamId,threadTs:e.message.threadTs,userId:i.userId,userName:i.userName}),from:e.from,resolveSession:e.resolveSession,state:a}),s,isDMOrPrivateChannel=()=>s??=isPrivateSlackConversation({channelId:e.message.channelId,raw:e.message.raw,request:r.request}),c=e.kind===`app_mention`||e.botUserId!==void 0&&e.message.text.includes(`<@${e.botUserId}`),l={...o,isBotMentioned:()=>c,isDMOrPrivateChannel,isSubscribed:async()=>await o.resolveSession()!==void 0,slack:r,thread:n},u;try{u=await e.handler(l,e.message)}catch(t){logError(log,`${e.kind} handler failed`,t,{channelId:e.message.channelId});return}if(u==null)return;let d=await isDMOrPrivateChannel();a.audience=e.kind===`direct_message`||d?`private`:`public`,await deliverSlackMessage({botUserId:e.receivingBotUserId,credentials:e.credentials,kind:e.kind,isPrivateConversation:d,isMentioned:c,message:e.message,result:u,sessionOperations:o,thread:n,threadContext:e.threadContext,uploadPolicy:e.uploadPolicy})}async function dispatchSlackEvent(e){let t=e.envelope.event.team_id,n=typeof t==`string`?t:typeof e.envelope.team_id==`string`?e.envelope.team_id:void 0,r=[],sourceFor=t=>e.from(slackContinuationToken(t.channelId,t.threadTs)),i={cancel:({target:e,turnId:t})=>sourceFor(e).cancel({turnId:t}),clear:({target:e})=>sourceFor(e).clear(),compact:({target:e})=>sourceFor(e).compact(),envelope:e.envelope,reset:({reason:e,target:t})=>sourceFor(t).reset({reason:e}),resolveSession:({target:t})=>e.resolveSession(slackContinuationToken(t.channelId,t.threadTs)),respond:(e,{auth:t,target:n})=>sourceFor(n).respond(e,{auth:t}),send:(t,{auth:r,target:i,title:a,taskDeliveryPolicy:o})=>receiveOnSlack({auth:r,message:t,target:i,title:a,taskDeliveryPolicy:o},{from:e.from,credentials:e.credentials,installationTeamId:e.installationTeamId,teamId:n,...typeof e.envelope.event.user==`string`?{triggeringUserId:e.envelope.event.user}:{}}),slack:buildSlackWorkspaceHandle({botToken:e.credentials?.botToken,installationTeamId:e.installationTeamId,teamId:n}),waitUntil(e){r.push(e)}};try{await e.handler(i,e.envelope.event)}catch(t){logError(log,`event handler failed`,t,{eventId:e.envelope.event_id,eventType:e.envelope.event.type})}await Promise.allSettled(r)}async function verifyInbound(e,t){try{return await verifySlackRequest$1(e,{signingSecret:t?.signingSecret??(t?.webhookVerifier?void 0:process.env.SLACK_SIGNING_SECRET),webhookVerifier:t?.webhookVerifier})}catch(e){return log.warn(`slack inbound verification failed`,{error:e}),null}}async function deliverSlackMessage(e){let{message:t,thread:n}=e;try{let r=e.threadContext===void 0?[]:await loadThreadContextMessages(n,t,e.threadContext),i=formatSlackThreadContext(r),a=await collectInboundFileParts({mention:t,thread:n,policy:e.uploadPolicy}),o={botUserId:e.botUserId,channelId:t.channelId,fullName:t.author?.fullName,isMentioned:e.isMentioned,teamId:t.teamId,threadTs:t.threadTs,userId:t.author?.userId??``,userName:t.author?.userName},s=formatSlackInboundMessage(o,t),c=buildSlackTurnMessage(i===void 0?s:`${i}\n\n${s}`,a),l=e.result.context??[],u=e.isPrivateConversation?`Private message`:e.result.title??t.markdown,d=l.length===0?{auth:e.result.auth,title:u}:{auth:e.result.auth,context:l,title:u};await e.sessionOperations.send(c,d)}catch(n){logError(log,`${e.kind} delivery failed`,n,{channelId:t.channelId})}}export{constrainAuthorizationRequired,slackChannel};

package/dist/src/public/definitions/channel.d.ts

@@ -8,7 +8,7 @@ import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
 import type { SessionContext } from "#public/definitions/callback-context.js";
 import type { GenericChannelDefinition, GenericReceiveInput } from "#shared/channel-definition.js";
 declare const CHANNEL_METADATA_TYPE: unique symbol;
-export type { CancelTurnResult, ClearSessionResult, CompactSessionResult, GetEventStreamOptions, ResetSessionResult, SessionCallback, TurnPolicy, } from "#channel/types.js";
+export type { CancelTurnResult, ClearSessionResult, CompactSessionResult, GetEventStreamOptions, ResetSessionResult, SessionCallback, TurnPolicy, TaskDeliveryPolicy, } from "#channel/types.js";
 export type { Session, SessionHandle } from "#channel/session.js";
 export type { ChannelAudience } from "#shared/channel-audience.js";
 export type { AudienceCaller, AudienceContext, AudienceInput, AudiencePrincipal, ConversationEnvironment, } from "#shared/conversation-context.js";

package/dist/src/public/definitions/sandbox.d.ts

@@ -1,43 +1,5 @@
-import type { Optional } from "#shared/optional.js";
-import type { SandboxDefinitionWithBootstrap as SharedSandboxDefinitionWithBootstrap, SandboxDefinitionWithoutBootstrap as SharedSandboxDefinitionWithoutBootstrap } from "#shared/sandbox-definition.js";
-export type { SandboxCommandResult, SandboxProcess, SandboxReadBinaryFileOptions, SandboxReadFileOptions, SandboxRemovePathOptions, SandboxReadTextFileOptions, SandboxRunOptions, SandboxSession, RuntimeSandboxSession, SandboxSpawnOptions, SandboxWriteBinaryFileOptions, SandboxWriteFileOptions, SandboxWriteTextFileOptions, } from "#shared/sandbox-session.js";
-export type { SandboxBootstrapUseFn, SandboxRevalidationKeyFn, SandboxSessionUseFn, SandboxBootstrapContext, SandboxSessionContext, } from "#shared/sandbox-definition.js";
-/** Opaque reference to an ancestor's durable sandbox. */
-export interface SandboxAncestorReference {
-    readonly sandbox: SandboxParentValue;
-}
-/**
- * Opaque value returned from a sandbox definition to select its parent's
- * durable sandbox. It intentionally exposes no provider operations: authored
- * code can only return it to eve.
- */
-export interface SandboxParentValue {
-    readonly __eveSandboxParentValue: unique symbol;
-}
-/** Runtime ancestry passed to a parent-selecting sandbox definition. */
-export interface SandboxParentDefinitionContext {
-    readonly parent: SandboxAncestorReference | null;
-}
-/** A definition that selects the dispatching parent's exact sandbox. */
-export type SandboxParentDefinition = (context: SandboxParentDefinitionContext) => SandboxParentValue | Promise<SandboxParentValue>;
-/**
- * The shape passed to {@link defineSandbox}: a discriminated union over
- * whether a `bootstrap` hook is present. `backend` is optional here (it is
- * required on the shared base): when omitted, eve substitutes
- * `defaultBackend()` at runtime. `BO`/`SO` type the options for the
- * bootstrap-use and session-use functions respectively.
- */
-export type SandboxDefinition<BO = Record<string, never>, SO = Record<string, never>> = Optional<SharedSandboxDefinitionWithBootstrap<BO, SO>, "backend"> | Optional<SharedSandboxDefinitionWithoutBootstrap<BO, SO>, "backend">;
-/**
- * Defines the sandbox an agent (or subagent) runs in. Authored at the
- * path-derived location `agent/sandbox.ts` (or `agent/sandbox/sandbox.ts`
- * when paired with a `workspace/` folder); subagents use
- * `subagents/<name>/sandbox.ts`.
- *
- * Pass an object to define an independent sandbox. Passing a callback to
- * `defineSandbox` opts into sharing: return `parent.sandbox` to select the
- * dispatching parent's exact durable sandbox. It is intended for child-only
- * definitions; throw when `parent` is `null`.
- */
-export declare function defineSandbox(definition: SandboxParentDefinition): SandboxParentDefinition;
-export declare function defineSandbox<BO = Record<string, never>, SO = Record<string, never>>(definition: SandboxDefinition<BO, SO>): SandboxDefinition<BO, SO>;
+import type { SandboxSelector } from "#shared/sandbox-environment.js";
+export type { SandboxCommandResult, SandboxProcess, SandboxReadBinaryFileOptions, SandboxReadFileOptions, SandboxRemovePathOptions, SandboxReadTextFileOptions, FixedNetworkSandboxSession, MutableNetworkSandboxSession, SandboxRunOptions, SandboxSession, RuntimeSandboxSession, RuntimeSandboxSessionFor, SandboxSpawnOptions, SandboxWriteBinaryFileOptions, SandboxWriteFileOptions, SandboxWriteTextFileOptions, } from "#shared/sandbox-session.js";
+export type { SandboxOpenArguments, SandboxEnvironment, SandboxSelector, SandboxSelectorContext, } from "#shared/sandbox-environment.js";
+export declare function defineSandbox(definition: SandboxSelector): SandboxSelector;
+export declare function defineParentSandbox(): SandboxSelector;

package/dist/src/public/definitions/sandbox.js

@@ -1 +1 @@
-const SANDBOX_PARENT_DEFINITION_MARKER=Symbol.for(`eve.sandbox-parent-definition`);function defineSandbox(e){return typeof e==`function`&&Object.defineProperty(e,SANDBOX_PARENT_DEFINITION_MARKER,{value:!0}),e}export{defineSandbox};
+const SELECTOR=Symbol.for(`eve.sandbox-selector`),PARENT=Symbol.for(`eve.sandbox-parent-definition`);function defineSandbox(e){return Object.defineProperty(e,SELECTOR,{value:!0}),e}function defineParentSandbox(){let e=defineSandbox(async()=>{throw Error(`Parent sandbox selection is resolved by eve.`)});return Object.defineProperty(e,PARENT,{value:!0}),e}export{defineParentSandbox,defineSandbox};

package/dist/src/public/local-dev.d.ts

@@ -1,9 +1,8 @@
 /**
- * Runtime capabilities available to authored code handling a same-machine
- * request to `eve dev`.
+ * Host facilities available to authored code running on an `eve dev` server.
  *
- * A deployed runtime and a client attached to a development server over the
- * network receive `undefined`. A local TUI attached to an existing headless
- * server receives the capability because authorization follows its requests.
+ * The capability is present when the executing host owns the authored root and
+ * watcher control origin. It is unavailable in deployed runtimes and does not
+ * vary by request or peer address.
  */
 export { getLocalDevCapability, type LocalDevCapability } from "#runtime/local-dev-capability.js";

package/dist/src/public/sandbox/docker-sandbox.d.ts

@@ -1,46 +1,22 @@
-/**
- * Image pull behavior for the Docker sandbox backend.
- *
- * - `"if-not-present"` (default): pull the base image only when it is
- *   missing from the local image store.
- * - `"always"`: pull before every template build so the image floats to
- *   the registry's latest digest.
- * - `"never"`: never pull; fail when the image is missing locally.
- */
+import type { SandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxNetworkOptions, SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+/** Image pull behavior for Docker sandbox environments. */
 export type DockerSandboxPullPolicy = "if-not-present" | "always" | "never";
-/**
- * Initial network policy for sandboxes created by the Docker backend.
- * Docker supports coarse-grained egress control only: `"allow-all"`
- * attaches the container to the default bridge network, `"deny-all"`
- * runs it with networking disabled. Domain-level policies and
- * credential brokering require `vercel()`.
- */
-export type DockerSandboxNetworkPolicy = "allow-all" | "deny-all";
-/**
- * Options accepted by `docker(opts)`.
- */
-export interface DockerSandboxCreateOptions {
-    /**
-     * Base container image for templates and sessions. Defaults to eve's
-     * published `ghcr.io/vercel/eve` image, tagged with the installed eve
-     * version without build metadata or `EVE_SANDBOX_IMAGE_TAG` when set. Framework setup creates
-     * `/workspace` and verifies Bash. Install
-     * any authored runtime tools in sandbox bootstrap or provide them through a
-     * custom image.
-     */
+/** Coarse-grained egress policy for one live Docker sandbox. */
+export type DockerSandboxNetworkPolicy = Extract<SandboxNetworkPolicy, "allow-all" | "deny-all">;
+/** Options shared by every sandbox created from one Docker environment. */
+export interface DockerSandboxEnvironmentOptions {
+    /** Base container image. Defaults to eve's published sandbox image. */
     readonly image?: string;
-    /**
-     * Environment variables baked into every container the backend
-     * creates (template builds and sessions).
-     */
+    /** Environment variables baked into template builds and live containers. */
     readonly env?: Readonly<Record<string, string>>;
-    /**
-     * Base image pull behavior. Defaults to `"if-not-present"`.
-     */
+    /** Base image pull behavior. @default "if-not-present" */
     readonly pullPolicy?: DockerSandboxPullPolicy;
-    /**
-     * Initial network policy for created containers. Defaults to
-     * `"allow-all"`.
-     */
+    /** Idempotent setup captured in the prepared image. */
+    readonly prepare?: (sandbox: SandboxSession) => Promise<void> | void;
+}
+/** Options applied when eve creates one live Docker sandbox. */
+export interface DockerSandboxRuntimeOptions extends SandboxNetworkOptions {
+    /** Initial network policy for this container. @default "allow-all" */
     readonly networkPolicy?: DockerSandboxNetworkPolicy;
 }

package/dist/src/public/sandbox/docker.d.ts

@@ -1,2 +1,2 @@
-export { docker } from "#public/sandbox/backends/docker.js";
-export type { DockerSandboxCreateOptions, DockerSandboxNetworkPolicy, DockerSandboxPullPolicy, } from "#public/sandbox/docker-sandbox.js";
+export { DockerSandbox, type DockerSandboxEnvironmentOptions, type DockerSandboxRuntimeOptions, } from "#sandbox/providers/docker.js";
+export type { DockerSandboxNetworkPolicy, DockerSandboxPullPolicy, } from "#public/sandbox/docker-sandbox.js";

package/dist/src/public/sandbox/docker.js

@@ -1 +1 @@
-import{docker}from"#public/sandbox/backends/docker.js";export{docker};
+import{DockerSandbox}from"#sandbox/providers/docker.js";export{DockerSandbox};

package/dist/src/public/sandbox/index.d.ts

@@ -1,9 +1,4 @@
-/**
- * Sandbox authoring helpers for `agent/sandbox.ts` (or
- * `agent/sandbox/sandbox.ts` when paired with a `workspace/` folder).
- */
-export { defineSandbox, type SandboxAncestorReference, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxCommandResult, type SandboxDefinition, type SandboxParentDefinition, type SandboxParentDefinitionContext, type SandboxParentValue, type SandboxProcess, type SandboxReadBinaryFileOptions, type SandboxReadFileOptions, type SandboxReadTextFileOptions, type SandboxRevalidationKeyFn, type SandboxRunOptions, type SandboxSession, type RuntimeSandboxSession, type SandboxSpawnOptions, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxWriteBinaryFileOptions, type SandboxWriteFileOptions, type SandboxWriteTextFileOptions, } from "#public/definitions/sandbox.js";
-export type { SandboxBackend, SandboxBackendCreateInput, SandboxBackendHandle, SandboxBackendPrewarmInput, SandboxBackendRuntimeContext, SandboxBackendSessionState, SandboxDeleteOptions, SandboxSeedFile, } from "#public/definitions/sandbox-backend.js";
-export type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
-export { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-backend.js";
-export { defaultSandbox as defaultBackend, type DefaultSandboxOptions as DefaultBackendOptions, } from "#public/sandbox/backends/default.js";
+export { defineParentSandbox, defineSandbox, type SandboxOpenArguments, type SandboxEnvironment, type SandboxSelector, type SandboxSelectorContext, type SandboxCommandResult, type FixedNetworkSandboxSession, type MutableNetworkSandboxSession, type SandboxProcess, type SandboxReadBinaryFileOptions, type SandboxReadFileOptions, type SandboxReadTextFileOptions, type SandboxRunOptions, type SandboxSession, type RuntimeSandboxSession, type RuntimeSandboxSessionFor, type SandboxSpawnOptions, type SandboxWriteBinaryFileOptions, type SandboxWriteFileOptions, type SandboxWriteTextFileOptions, } from "#public/definitions/sandbox.js";
+export { DefaultSandbox } from "#sandbox/providers/default.js";
+export type { DefaultSandboxEnvironmentOptions } from "#sandbox/providers/default.js";
+export type { SandboxNetworkOptions, SandboxNetworkPolicy, } from "#shared/sandbox-network-policy.js";

package/dist/src/public/sandbox/index.js

@@ -1 +1 @@
-import{SandboxTemplateNotProvisionedError}from"#public/definitions/sandbox-backend.js";import{defineSandbox}from"#public/definitions/sandbox.js";import{defaultSandbox as defaultBackend}from"#public/sandbox/backends/default.js";export{SandboxTemplateNotProvisionedError,defaultBackend,defineSandbox};
+import{defineParentSandbox,defineSandbox}from"#public/definitions/sandbox.js";import{DefaultSandbox}from"#sandbox/providers/default.js";export{DefaultSandbox,defineParentSandbox,defineSandbox};

package/dist/src/public/sandbox/just-bash-sandbox.d.ts

@@ -1,19 +1,22 @@
 import type { CustomCommand, IFileSystem } from "just-bash";
+import type { SandboxSession } from "#shared/sandbox-session.js";
 /**
  * Context passed to a custom just-bash filesystem factory for each live handle.
  */
 export interface JustBashFilesystemContext {
-    /** Stable application root for this backend create call. */
-    readonly appRoot: string;
+    /** Resolves an application-relative path without exposing project layout. */
+    resolveProjectPath(path: string): string;
+    /** Stable provider-private storage directory for this sandbox. */
+    readonly storagePath: string;
     /** eve's durable, session-owned filesystem, including `/workspace`. */
     readonly defaultFilesystem: IFileSystem;
     /** The just-bash engine resolved by eve after its optional installation check. */
     readonly justBash: typeof import("just-bash");
 }
 /**
- * Options accepted by `justbash(opts)`.
+ * Options accepted by just-bash environment constructors.
  *
- * The just-bash backend runs the workspace under the pure-JS `just-bash`
+ * The just-bash provider runs the workspace under the pure-JS `just-bash`
  * interpreter with a virtual filesystem — no daemon or VM required, but
  * no real binaries either. The `just-bash` package is not bundled with
  * eve; it is loaded lazily from the application install.
@@ -31,7 +34,7 @@ export interface JustBashSandboxCreateOptions {
      * just-bash interpreter. Custom commands can participate in normal shell
      * composition, including pipelines and redirections.
      *
-     * Custom commands are not available during template prewarming. They run in
+     * Custom commands are not available during environment preparation. They run in
      * eve's host process, outside the virtual filesystem security boundary, and
      * are responsible for validating their own inputs and cleaning up host
      * resources.
@@ -45,7 +48,9 @@ export interface JustBashSandboxCreateOptions {
      *
      * This just-bash-specific escape hatch requires the application to install
      * a compatible `just-bash` version. It is not invoked during template
-     * prewarming.
+     * preparation.
      */
     readonly filesystem?: (context: JustBashFilesystemContext) => IFileSystem | Promise<IFileSystem>;
+    /** Idempotent setup captured in the prepared virtual filesystem. */
+    readonly prepare?: (sandbox: SandboxSession) => Promise<void> | void;
 }

package/dist/src/public/sandbox/just-bash.d.ts

@@ -1,2 +1,2 @@
-export { justbash } from "#public/sandbox/backends/just-bash.js";
-export type { JustBashFilesystemContext, JustBashSandboxCreateOptions, } from "#public/sandbox/just-bash-sandbox.js";
+export { JustBashSandbox, type JustBashEnvironmentOptions } from "#sandbox/providers/just-bash.js";
+export type { JustBashFilesystemContext } from "#public/sandbox/just-bash-sandbox.js";

package/dist/src/public/sandbox/just-bash.js

@@ -1 +1 @@
-import{justbash}from"#public/sandbox/backends/just-bash.js";export{justbash};
+import{JustBashSandbox}from"#sandbox/providers/just-bash.js";export{JustBashSandbox};

package/dist/src/public/sandbox/microsandbox-sandbox.d.ts

@@ -1,8 +1,9 @@
-import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxNetworkOptions, SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
 /**
- * Options accepted by `microsandbox(opts)`.
+ * Options accepted by microsandbox environment constructors.
  *
- * The microsandbox backend runs sandboxes in lightweight local VMs via
+ * The microsandbox provider runs sandboxes in lightweight local VMs via
  * [microsandbox](https://www.npmjs.com/package/microsandbox). Options
  * are eve-owned rather than a raw passthrough so the public surface can
  * stay stable while the underlying runtime evolves. Supported hosts:
@@ -12,8 +13,8 @@ export interface MicrosandboxSandboxCreateOptions {
     /**
      * OCI image used as the base runtime. eve prepares this image with
      * Bash, the framework workspace, and the sandbox user before authored
-     * bootstrap code runs. Install authored runtime tools such as Node,
-     * Python, or ripgrep in sandbox bootstrap or provide them through a
+     * environment preparation runs. Install authored runtime tools such as Node,
+     * Python, or ripgrep during preparation or provide them through a
      * custom image.
      *
      * @default The `ghcr.io/vercel/eve` tag matching the installed eve version without build metadata, or `EVE_SANDBOX_IMAGE_TAG` when set.
@@ -27,6 +28,8 @@ export interface MicrosandboxSandboxCreateOptions {
     readonly env?: Readonly<Record<string, string>>;
     /** OCI image pull policy. @default "if-missing" */
     readonly pullPolicy?: "always" | "if-missing" | "never";
+    /** Idempotent setup captured in the prepared VM snapshot. */
+    readonly prepare?: (sandbox: SandboxSession) => Promise<void> | void;
     /**
      * Installation behavior for the microsandbox npm package and its VM
      * runtime. By default eve installs both automatically when missing —
@@ -37,18 +40,9 @@ export interface MicrosandboxSandboxCreateOptions {
         readonly autoInstall?: boolean;
         readonly skipVerify?: boolean;
     };
-    /** Initial network policy applied to sandboxes after framework setup. */
-    readonly networkPolicy?: SandboxNetworkPolicy;
 }
-/**
- * Options accepted by the microsandbox backend's `bootstrap({ use })` hook.
- */
-export interface MicrosandboxBootstrapUseOptions {
-    readonly networkPolicy?: SandboxNetworkPolicy;
-}
-/**
- * Options accepted by the microsandbox backend's `onSession({ use })` hook.
- */
-export interface MicrosandboxSessionUseOptions {
+/** Options applied when eve creates one live microsandbox VM. */
+export interface MicrosandboxSandboxRuntimeOptions extends SandboxNetworkOptions {
+    /** Initial network policy for this VM. @default "allow-all" */
     readonly networkPolicy?: SandboxNetworkPolicy;
 }

package/dist/src/public/sandbox/microsandbox.d.ts

@@ -1,2 +1,2 @@
-export { microsandbox } from "#public/sandbox/backends/microsandbox.js";
-export type { MicrosandboxBootstrapUseOptions, MicrosandboxSandboxCreateOptions, MicrosandboxSessionUseOptions, } from "#public/sandbox/microsandbox-sandbox.js";
+export { MicrosandboxSandbox, type MicrosandboxEnvironmentOptions, } from "#sandbox/providers/microsandbox.js";
+export type { MicrosandboxSandboxRuntimeOptions } from "#public/sandbox/microsandbox-sandbox.js";

package/dist/src/public/sandbox/microsandbox.js

@@ -1 +1 @@
-import{microsandbox}from"#public/sandbox/backends/microsandbox.js";export{microsandbox};
+import{MicrosandboxSandbox}from"#sandbox/providers/microsandbox.js";export{MicrosandboxSandbox};

package/dist/src/public/sandbox/provider.d.ts

@@ -0,0 +1 @@
+export { defineSandboxProvider, type SandboxDeleteOptions, type SandboxPreparedArtifact, type SandboxProvider, type SandboxProviderDefinition, type SandboxProviderFiles, type SandboxProviderHandle, type SandboxProviderImplementation, type SandboxProviderPrepareContext, type SandboxProviderResourceFile, type SandboxProviderResources, type SandboxProviderResourceSource, type SandboxProviderResourceTree, type SandboxProviderSessionContext, type SandboxProviderTargetFile, } from "#shared/sandbox-provider.js";

package/dist/src/public/sandbox/provider.js

@@ -0,0 +1 @@
+import{defineSandboxProvider}from"#shared/sandbox-provider.js";export{defineSandboxProvider};

package/dist/src/public/sandbox/vercel-sandbox.d.ts

@@ -1,19 +1,19 @@
 import type * as Vercel from "#compiled/@vercel/sandbox/index.js";
+import type { SandboxNetworkOptions } from "#shared/sandbox-network-policy.js";
 type VercelCreateOptions = NonNullable<Parameters<typeof Vercel.Sandbox.create>[0]>;
-type VercelUpdateOptions = Parameters<Vercel.Sandbox["update"]>[0];
 type VercelSandboxInternalCreateOptions = {
     readonly [key: `__${string}`]: unknown;
 };
 type VercelSandboxAuthorCreateOptions<T> = T extends unknown ? Omit<T, "mounts" | "name" | "onResume" | "persistent" | "runtime" | "signal"> & VercelSandboxInternalCreateOptions : never;
 /**
- * Options accepted by `vercel(opts)`. Forwarded to Vercel
+ * Options accepted by Vercel sandbox environment constructors. Forwarded to Vercel
  * Sandbox creation for every fresh sandbox the framework creates
- * (template at prewarm time, session at first-time session-create).
+ * (template during preparation, session at first creation).
  * Skipped on resume (`Sandbox.get`) since no create happens there.
  *
  * `networkPolicy` is deferred until after framework-owned base setup
  * for fresh templates and template-less sessions, so eve can install
- * required packages before authored bootstrap code runs. Template-backed
+ * required packages before authored environment preparation runs. Template-backed
  * session creates receive it at creation time because the template
  * already contains the prepared base runtime.
  *
@@ -22,7 +22,7 @@ type VercelSandboxAuthorCreateOptions<T> = T extends unknown ? Omit<T, "mounts"
  * author-supplied values.
  *
  * `runtime` is excluded: eve defaults to its published
- * `vcr.vercel.com/vercel/eve/base` image tagged with the installed eve version without build metadata
+ * `vcr.vercel.com/vercel/eve/base` image tagged with the installed eve version
  * or `EVE_SANDBOX_IMAGE_TAG` when `image` is not supplied. Both are mutually
  * exclusive with a stock runtime.
  *
@@ -30,9 +30,9 @@ type VercelSandboxAuthorCreateOptions<T> = T extends unknown ? Omit<T, "mounts"
  * snapshot `source` takes precedence because the Vercel SDK makes it mutually
  * exclusive with `image`.
  *
- * `source` is honored only on the template create at prewarm time, so
+ * `source` is honored only on the template creation during preparation, so
  * an author-supplied snapshot, git revision, or tarball becomes the
- * base layer for the template. Framework setup, bootstrap, and seed
+ * base layer for the template. Framework setup, preparation, and seed
  * files all run on top, and the resulting
  * framework-owned snapshot is what every later session derives from,
  * so `source` is stripped from the session-create path. eve does not
@@ -48,40 +48,9 @@ export type VercelSandboxMount = Vercel.SandboxMounts[string];
 /** Drive mounts keyed by absolute sandbox path. */
 export type VercelSandboxMounts = Vercel.SandboxMounts;
 /** Options resolved when eve creates a fresh live session sandbox. */
-export interface VercelSandboxSessionCreateOptions {
+export interface VercelSandboxMountOptions {
     readonly mounts?: VercelSandboxMounts;
 }
-/** Context available while resolving fresh live-session creation options. */
-export interface VercelSandboxSessionCreateContext {
-    readonly session: {
-        readonly id: string;
-    };
-}
-/** Options accepted by `vercel(opts)`. */
-export type VercelSandboxOptions = VercelSandboxCreateOptions & {
-    /**
-     * Resolves options that apply only to fresh live sessions. It is not called
-     * while prewarming templates or resuming an existing sandbox.
-     */
-    readonly sessionCreateOptions?: (context: VercelSandboxSessionCreateContext) => Promise<VercelSandboxSessionCreateOptions> | VercelSandboxSessionCreateOptions;
-};
-/**
- * Options accepted by the Vercel backend's `bootstrap({ use })` hook.
- * Tracks the Vercel SDK's `Sandbox.update(...)` parameter because bootstrap
- * applies its options to the template via `sandbox.update(...)` after
- * `Sandbox.create()` and before the snapshot is captured. The Vercel
- * SDK persists `update`-d settings on the sandbox so they survive into
- * the snapshot, which becomes the seed for every later session.
- *
- * Today this is the same shape as
- * {@link VercelSandboxSessionUseOptions}; both are exposed as separate
- * named aliases so future divergence is non-breaking.
- */
-export type VercelSandboxBootstrapUseOptions = VercelUpdateOptions;
-/**
- * Options accepted by the Vercel backend's `onSession({ use })` hook.
- * Tracks the Vercel SDK's `Sandbox.update(...)` parameter; passed values are
- * applied to the live session via the SDK's `update`.
- */
-export type VercelSandboxSessionUseOptions = VercelUpdateOptions;
+/** Options accepted when creating one live Vercel sandbox from an environment. */
+export type VercelSandboxRuntimeOptions = Omit<VercelSandboxCreateOptions, "fetch" | "image" | "projectId" | "source" | "tags" | "teamId" | "token"> & SandboxNetworkOptions & VercelSandboxMountOptions;
 export {};