eve 0.29.3 → 0.29.5

package/dist/src/setup/slack-connect-lifecycle.js

@@ -1 +1 @@
-import{object,string}from"../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/schemas.js";import"../node_modules/.pnpm/zod@4.4.3/node_modules/zod/index.js";import{parseSlackConnectorDetails,parseSlackConnectors}from"./slack-connect.js";import{join}from"node:path";import{SLACK_CHANNEL_DEFAULT_ROUTE}from"#setup/scaffold/index.js";import{readFile}from"node:fs/promises";import"#setup/primitives/run-vercel.js";import"#setup/cli/index.js";import{CONNECT_MUTATION_TIMEOUT_MS,replaceConnectTrigger}from"#setup/connect-provisioning.js";const CONNECT_LOOKUP_TIMEOUT_MS=6e4,VercelProjectLinkSchema=object({projectId:string().min(1),orgId:string().min(1)});async function listSlackConnectors(e,t,n,i){let a=await e.captureVercel([`connect`,`list`,`-F`,`json`,`--all-projects`],{cwd:t,onOutput:n,timeoutMs:CONNECT_LOOKUP_TIMEOUT_MS,signal:i});if(!a.ok)return{state:`failed`,message:a.failure.message};try{let e=JSON.parse(a.stdout);if(typeof e!=`object`||!e)return{state:`failed`,message:`Vercel returned a malformed connector list.`};let t=e;return Array.isArray(t.connectors??t.clients)?{state:`ok`,body:e,connectors:parseSlackConnectors(e)}:{state:`failed`,message:`Vercel returned a malformed connector list.`}}catch{return{state:`failed`,message:`Vercel returned invalid JSON for the connector list.`}}}async function readProjectLink(e){try{let t=await readFile(join(e,`.vercel`,`project.json`),`utf8`),n=VercelProjectLinkSchema.safeParse(JSON.parse(t));return n.success?n.data:void 0}catch{return}}async function findSlackConnector(e,t,n,r,i,a){let o=await listSlackConnectors(e,t,i,a);if(o.state===`failed`)return o;let s=new Set(o.connectors.map(e=>e.uid));if(n===void 0)return{state:`not-found`,connectorUids:s};let c=o.connectors.filter(e=>e.id!==void 0&&e.projectIds.includes(n)).sort((e,t)=>t.createdAt-e.createdAt).map(({uid:e,id:t})=>({uid:e,id:t}));if(c.length===0)return{state:`not-found`,connectorUids:s};let l=c.find(e=>e.uid===r);return l===void 0?{state:`found`,connectors:c,connectorUids:s}:{state:`found`,connectors:c,preferred:l,connectorUids:s}}async function attachSlackConnector(e,t,n,r,i){return replaceConnectTrigger({connectorUid:n.uid,projectRoot:t,triggerPath:SLACK_CHANNEL_DEFAULT_ROUTE,onOutput:r,signal:i,deps:e})}async function fetchSlackConnectorDetails(e){let t=e.orgId===void 0?``:`?teamId=${encodeURIComponent(e.orgId)}`,r=[`api`,`/v1/connect/connectors/${encodeURIComponent(e.connectorId)}${t}`];e.orgId!==void 0&&r.push(`--scope`,e.orgId);let i=await e.deps.captureVercel(r,{cwd:e.projectRoot,onOutput:e.onOutput,timeoutMs:e.timeoutMs,signal:e.signal});if(!i.ok)return{state:`failed`,message:i.failure.message};try{let t=parseSlackConnectorDetails(JSON.parse(i.stdout));return t?.ref.id===e.connectorId?{state:`found`,details:t}:{state:`failed`,message:`Vercel returned an invalid Slack connector.`}}catch{return{state:`failed`,message:`Vercel returned invalid JSON for the Slack connector.`}}}async function fetchSlackWorkspace(e){let t=await fetchSlackConnectorDetails(e);return t.state===`failed`?t:t.details.workspace===void 0?{state:`pending`}:{state:`connected`,workspace:t.details.workspace}}async function cleanupConnectorUid(e,t){let{log:n,deps:r,projectRoot:i,onOutput:a}=e;return await r.runVercel([`connect`,`remove`,t,`--disconnect-all`,`--yes`],{cwd:i,onOutput:a,timeoutMs:CONNECT_MUTATION_TIMEOUT_MS})?!0:(n.warning(`Could not remove the abandoned Slack connector. Run \`vercel connect remove ${t} --disconnect-all --yes\` to clean it up.`),!1)}async function cleanupConnectorUids(e,t){let n=[];for(let r of new Set(t))await cleanupConnectorUid(e,r)||n.push(r);return n.length===0?{state:`clean`}:{state:`failed`,connectorUids:n}}async function cleanupCreatedAttempt(e,t){if(t.createdRef)return cleanupConnectorUids(e,[t.createdRef.uid]);e.log.warning(`Vercel returned no connector UID for the abandoned Slack Connect request, so eve cannot prove that request was cancelled. No connector was removed; do not retry until the browser request is no longer usable.`);let n=await listSlackConnectors(e.deps,e.projectRoot,e.onOutput);return n.state===`failed`?{state:`failed`,connectorUids:[]}:{state:`failed`,connectorUids:n.connectors.map(e=>e.uid).filter(e=>(e===t.expectedUid||e.startsWith(`${t.expectedUid}-`))&&!t.baselineConnectorUids.has(e))}}export{CONNECT_LOOKUP_TIMEOUT_MS,attachSlackConnector,cleanupCreatedAttempt,fetchSlackConnectorDetails,fetchSlackWorkspace,findSlackConnector,listSlackConnectors,readProjectLink};
+import{object,string}from"../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/schemas.js";import"../node_modules/.pnpm/zod@4.4.3/node_modules/zod/index.js";import{parseSlackConnectorDetails,parseSlackConnectors}from"./slack-connect.js";import{readFile}from"node:fs/promises";import{join}from"node:path";import{SLACK_CHANNEL_DEFAULT_ROUTE}from"#setup/scaffold/index.js";import"#setup/primitives/run-vercel.js";import"#setup/cli/index.js";import{CONNECT_MUTATION_TIMEOUT_MS,replaceConnectTrigger}from"#setup/connect-provisioning.js";const CONNECT_LOOKUP_TIMEOUT_MS=6e4,VercelProjectLinkSchema=object({projectId:string().min(1),orgId:string().min(1)});async function listSlackConnectors(e,t,n,i){let a=await e.captureVercel([`connect`,`list`,`-F`,`json`,`--all-projects`],{cwd:t,onOutput:n,timeoutMs:CONNECT_LOOKUP_TIMEOUT_MS,signal:i});if(!a.ok)return{state:`failed`,message:a.failure.message};try{let e=JSON.parse(a.stdout);if(typeof e!=`object`||!e)return{state:`failed`,message:`Vercel returned a malformed connector list.`};let t=e;return Array.isArray(t.connectors??t.clients)?{state:`ok`,body:e,connectors:parseSlackConnectors(e)}:{state:`failed`,message:`Vercel returned a malformed connector list.`}}catch{return{state:`failed`,message:`Vercel returned invalid JSON for the connector list.`}}}async function readProjectLink(e){try{let t=await readFile(join(e,`.vercel`,`project.json`),`utf8`),n=VercelProjectLinkSchema.safeParse(JSON.parse(t));return n.success?n.data:void 0}catch{return}}async function findSlackConnector(e,t,n,r,i,a){let o=await listSlackConnectors(e,t,i,a);if(o.state===`failed`)return o;let s=new Set(o.connectors.map(e=>e.uid));if(n===void 0)return{state:`not-found`,connectorUids:s};let c=o.connectors.filter(e=>e.id!==void 0&&e.projectIds.includes(n)).sort((e,t)=>t.createdAt-e.createdAt).map(({uid:e,id:t})=>({uid:e,id:t}));if(c.length===0)return{state:`not-found`,connectorUids:s};let l=c.find(e=>e.uid===r);return l===void 0?{state:`found`,connectors:c,connectorUids:s}:{state:`found`,connectors:c,preferred:l,connectorUids:s}}async function attachSlackConnector(e,t,n,r,i){return replaceConnectTrigger({connectorUid:n.uid,projectRoot:t,triggerPath:SLACK_CHANNEL_DEFAULT_ROUTE,onOutput:r,signal:i,deps:e})}async function fetchSlackConnectorDetails(e){let t=e.orgId===void 0?``:`?teamId=${encodeURIComponent(e.orgId)}`,r=[`api`,`/v1/connect/connectors/${encodeURIComponent(e.connectorId)}${t}`];e.orgId!==void 0&&r.push(`--scope`,e.orgId);let i=await e.deps.captureVercel(r,{cwd:e.projectRoot,onOutput:e.onOutput,timeoutMs:e.timeoutMs,signal:e.signal});if(!i.ok)return{state:`failed`,message:i.failure.message};try{let t=parseSlackConnectorDetails(JSON.parse(i.stdout));return t?.ref.id===e.connectorId?{state:`found`,details:t}:{state:`failed`,message:`Vercel returned an invalid Slack connector.`}}catch{return{state:`failed`,message:`Vercel returned invalid JSON for the Slack connector.`}}}async function fetchSlackWorkspace(e){let t=await fetchSlackConnectorDetails(e);return t.state===`failed`?t:t.details.workspace===void 0?{state:`pending`}:{state:`connected`,workspace:t.details.workspace}}async function cleanupConnectorUid(e,t){let{log:n,deps:r,projectRoot:i,onOutput:a}=e;return await r.runVercel([`connect`,`remove`,t,`--disconnect-all`,`--yes`],{cwd:i,onOutput:a,timeoutMs:CONNECT_MUTATION_TIMEOUT_MS})?!0:(n.warning(`Could not remove the abandoned Slack connector. Run \`vercel connect remove ${t} --disconnect-all --yes\` to clean it up.`),!1)}async function cleanupConnectorUids(e,t){let n=[];for(let r of new Set(t))await cleanupConnectorUid(e,r)||n.push(r);return n.length===0?{state:`clean`}:{state:`failed`,connectorUids:n}}async function cleanupCreatedAttempt(e,t){if(t.createdRef)return cleanupConnectorUids(e,[t.createdRef.uid]);e.log.warning(`Vercel returned no connector UID for the abandoned Slack Connect request, so eve cannot prove that request was cancelled. No connector was removed; do not retry until the browser request is no longer usable.`);let n=await listSlackConnectors(e.deps,e.projectRoot,e.onOutput);return n.state===`failed`?{state:`failed`,connectorUids:[]}:{state:`failed`,connectorUids:n.connectors.map(e=>e.uid).filter(e=>(e===t.expectedUid||e.startsWith(`${t.expectedUid}-`))&&!t.baselineConnectorUids.has(e))}}export{CONNECT_LOOKUP_TIMEOUT_MS,attachSlackConnector,cleanupCreatedAttempt,fetchSlackConnectorDetails,fetchSlackWorkspace,findSlackConnector,listSlackConnectors,readProjectLink};

package/dist/src/setup/vercel-project-framework.js

@@ -1 +1 @@
-import{object,string}from"../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/schemas.js";import"../node_modules/.pnpm/zod@4.4.3/node_modules/zod/index.js";import{readProjectLink}from"./project-resolution.js";import{resolveVercelHostFrameworkPreset}from"./scaffold/update/channels.js";import"./scaffold/index.js";import{isForbiddenApiFailure,normalizeVercelApiResult}from"./vercel-api-failure.js";import{VERCEL_PROJECT_REQUEST_TIMEOUT_MS,parseVercelJson,requireVercelTeamAccess}from"./vercel-project-api.js";import{extname,join}from"node:path";import*as fs from"node:fs/promises";import{captureVercel}from"#setup/primitives/index.js";import"#setup/cli/index.js";const VercelProjectFrameworkSchema=object({framework:string().min(1).nullish()}),EVE_FRAMEWORK_INTEGRATIONS={nextjs:{label:`Next.js`,importSpecifier:`eve/next`},nuxt:{label:`Nuxt`,importSpecifier:`eve/nuxt`},nuxtjs:{label:`Nuxt`,importSpecifier:`eve/nuxt`},sveltekit:{label:`SvelteKit`,importSpecifier:`eve/sveltekit`}},FRAMEWORK_INTEGRATION_SOURCE_EXTENSIONS=new Set([`.cjs`,`.cts`,`.js`,`.json`,`.jsx`,`.mjs`,`.mts`,`.svelte`,`.ts`,`.tsx`,`.vue`]),FRAMEWORK_INTEGRATION_IGNORED_DIRECTORIES=new Set([`.eve`,`.git`,`.next`,`.nuxt`,`.output`,`.svelte-kit`,`.turbo`,`.vercel`,`build`,`coverage`,`dist`,`node_modules`]);function parseProjectFramework(e,t){let n=VercelProjectFrameworkSchema.safeParse(parseVercelJson(e,t));if(!n.success)throw Error(`Could not read Vercel project framework from ${t}.`);return n.data.framework??void 0}async function fetchProjectFramework(e,t,n,r){let s=normalizeVercelApiResult(await captureVercel([`api`,`/v9/projects/${n}`,`--scope`,t,`--raw`],{cwd:e,signal:r.signal,timeoutMs:VERCEL_PROJECT_REQUEST_TIMEOUT_MS}));if(s.ok)return parseProjectFramework(s.stdout,`project ${n}`);throw isForbiddenApiFailure(s.failure)&&requireVercelTeamAccess(s.failure),Error(`Could not inspect Vercel project "${n}". ${s.failure.message}`)}async function setProjectFramework(e,t,n,r,s,l){let u=normalizeVercelApiResult(await captureVercel([`api`,`/v9/projects/${n}`,`--scope`,t,`--method`,`PATCH`,`--raw-field`,`framework=${r}`,`--raw`],{cwd:e,onOutput:s,signal:l.signal,timeoutMs:VERCEL_PROJECT_REQUEST_TIMEOUT_MS}));if(!u.ok)throw isForbiddenApiFailure(u.failure)&&requireVercelTeamAccess(u.failure),Error(`Could not set Vercel project "${n}" framework to ${r}. ${u.failure.message}`)}async function confirmDetectedFramework(e,t,n){return await e.select({message:`Vercel detected ${n.label}. Is this project using ${n.importSpecifier}?`,options:[{value:!0,label:`Yes, keep ${t}`,hint:`Use this for a host app that integrates eve through ${n.importSpecifier}.`},{value:!1,label:`No, switch to eve`,hint:`Use this for a standalone eve agent.`}]})?`keep`:`switch-to-eve`}function sourceMentionsPackageSpecifier(e,t){return e.includes(`"${t}"`)||e.includes(`'${t}'`)||e.includes(`\`${t}\``)}async function directoryContainsPackageSpecifier(e,t){let n;try{n=await fs.readdir(e,{encoding:`utf8`,withFileTypes:!0})}catch{return!1}for(let r of n){let n=join(e,r.name);if(r.isDirectory()){if(FRAMEWORK_INTEGRATION_IGNORED_DIRECTORIES.has(r.name))continue;if(await directoryContainsPackageSpecifier(n,t))return!0;continue}if(!(!r.isFile()||!FRAMEWORK_INTEGRATION_SOURCE_EXTENSIONS.has(extname(r.name))))try{if(sourceMentionsPackageSpecifier(await fs.readFile(n,`utf8`),t))return!0}catch{continue}}return!1}async function detectFrameworkIntegrationImport(e,t){return directoryContainsPackageSpecifier(e,t)}async function resolveDetectedFrameworkAction(e,t,n,r){let i=EVE_FRAMEWORK_INTEGRATIONS[n];return i===void 0?`switch-to-eve`:await(r.detectFrameworkIntegrationImport??detectFrameworkIntegrationImport)(t,i.importSpecifier)?`keep`:r.headless?`switch-to-eve`:confirmDetectedFramework(e,n,i)}function frameworkPresetLabel(e){return EVE_FRAMEWORK_INTEGRATIONS[e]?.label??e}function describeError(e){return e instanceof Error?e.message:String(e)}async function syncHostFrameworkPreset(e,t,i,a){let o=await resolveVercelHostFrameworkPreset(t);if(o===void 0)return;let s=await readProjectLink(t);if(s===void 0)return;let c=frameworkPresetLabel(o),l;try{l=await fetchProjectFramework(t,s.orgId,s.projectId,a)}catch(t){if(a.signal?.aborted)throw t;e.log.warning(`Could not check this Vercel project's Framework Preset (${describeError(t)}). If it is not already ${c}, set it under Project Settings → Build and Deployment → Framework Settings before deploying.`);return}if(l===o)return;let u=l===void 0?void 0:frameworkPresetLabel(l),d=u===void 0?`had no Framework Preset set`:`was set to "${u}"`;try{await setProjectFramework(t,s.orgId,s.projectId,o,i,a)}catch(t){if(a.signal?.aborted)throw t;e.log.warning(`${describeError(t)} Set this Vercel project's Framework Preset to ${c} (Project Settings → Build and Deployment → Framework Settings) before deploying, or the deployment will not build your ${c} app.`);return}e.log.info(`This project uses ${c}, but its Vercel Framework Preset ${d}; switched it to ${c} so the deployment builds your app.`)}async function ensureCreatedProjectFramework(e,t,n,r,i,a){let o=await fetchProjectFramework(t,n,r,a);o!==`eve`&&(o===void 0?`switch-to-eve`:await resolveDetectedFrameworkAction(e,t,o,a))===`switch-to-eve`&&await setProjectFramework(t,n,r,`eve`,i,a)}export{ensureCreatedProjectFramework,syncHostFrameworkPreset};
+import{object,string}from"../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/schemas.js";import"../node_modules/.pnpm/zod@4.4.3/node_modules/zod/index.js";import{readProjectLink}from"./project-resolution.js";import{resolveVercelHostFrameworkPreset}from"./scaffold/update/channels.js";import"./scaffold/index.js";import{isForbiddenApiFailure,normalizeVercelApiResult}from"./vercel-api-failure.js";import{VERCEL_PROJECT_REQUEST_TIMEOUT_MS,parseVercelJson,requireVercelTeamAccess}from"./vercel-project-api.js";import*as fs from"node:fs/promises";import{extname,join}from"node:path";import{captureVercel}from"#setup/primitives/index.js";import"#setup/cli/index.js";const VercelProjectFrameworkSchema=object({framework:string().min(1).nullish()}),EVE_FRAMEWORK_INTEGRATIONS={nextjs:{label:`Next.js`,importSpecifier:`eve/next`},nuxt:{label:`Nuxt`,importSpecifier:`eve/nuxt`},nuxtjs:{label:`Nuxt`,importSpecifier:`eve/nuxt`},sveltekit:{label:`SvelteKit`,importSpecifier:`eve/sveltekit`}},FRAMEWORK_INTEGRATION_SOURCE_EXTENSIONS=new Set([`.cjs`,`.cts`,`.js`,`.json`,`.jsx`,`.mjs`,`.mts`,`.svelte`,`.ts`,`.tsx`,`.vue`]),FRAMEWORK_INTEGRATION_IGNORED_DIRECTORIES=new Set([`.eve`,`.git`,`.next`,`.nuxt`,`.output`,`.svelte-kit`,`.turbo`,`.vercel`,`build`,`coverage`,`dist`,`node_modules`]);function parseProjectFramework(e,t){let n=VercelProjectFrameworkSchema.safeParse(parseVercelJson(e,t));if(!n.success)throw Error(`Could not read Vercel project framework from ${t}.`);return n.data.framework??void 0}async function fetchProjectFramework(e,t,n,r){let s=normalizeVercelApiResult(await captureVercel([`api`,`/v9/projects/${n}`,`--scope`,t,`--raw`],{cwd:e,signal:r.signal,timeoutMs:VERCEL_PROJECT_REQUEST_TIMEOUT_MS}));if(s.ok)return parseProjectFramework(s.stdout,`project ${n}`);throw isForbiddenApiFailure(s.failure)&&requireVercelTeamAccess(s.failure),Error(`Could not inspect Vercel project "${n}". ${s.failure.message}`)}async function setProjectFramework(e,t,n,r,s,l){let u=normalizeVercelApiResult(await captureVercel([`api`,`/v9/projects/${n}`,`--scope`,t,`--method`,`PATCH`,`--raw-field`,`framework=${r}`,`--raw`],{cwd:e,onOutput:s,signal:l.signal,timeoutMs:VERCEL_PROJECT_REQUEST_TIMEOUT_MS}));if(!u.ok)throw isForbiddenApiFailure(u.failure)&&requireVercelTeamAccess(u.failure),Error(`Could not set Vercel project "${n}" framework to ${r}. ${u.failure.message}`)}async function confirmDetectedFramework(e,t,n){return await e.select({message:`Vercel detected ${n.label}. Is this project using ${n.importSpecifier}?`,options:[{value:!0,label:`Yes, keep ${t}`,hint:`Use this for a host app that integrates eve through ${n.importSpecifier}.`},{value:!1,label:`No, switch to eve`,hint:`Use this for a standalone eve agent.`}]})?`keep`:`switch-to-eve`}function sourceMentionsPackageSpecifier(e,t){return e.includes(`"${t}"`)||e.includes(`'${t}'`)||e.includes(`\`${t}\``)}async function directoryContainsPackageSpecifier(e,t){let n;try{n=await fs.readdir(e,{encoding:`utf8`,withFileTypes:!0})}catch{return!1}for(let r of n){let n=join(e,r.name);if(r.isDirectory()){if(FRAMEWORK_INTEGRATION_IGNORED_DIRECTORIES.has(r.name))continue;if(await directoryContainsPackageSpecifier(n,t))return!0;continue}if(!(!r.isFile()||!FRAMEWORK_INTEGRATION_SOURCE_EXTENSIONS.has(extname(r.name))))try{if(sourceMentionsPackageSpecifier(await fs.readFile(n,`utf8`),t))return!0}catch{continue}}return!1}async function detectFrameworkIntegrationImport(e,t){return directoryContainsPackageSpecifier(e,t)}async function resolveDetectedFrameworkAction(e,t,n,r){let i=EVE_FRAMEWORK_INTEGRATIONS[n];return i===void 0?`switch-to-eve`:await(r.detectFrameworkIntegrationImport??detectFrameworkIntegrationImport)(t,i.importSpecifier)?`keep`:r.headless?`switch-to-eve`:confirmDetectedFramework(e,n,i)}function frameworkPresetLabel(e){return EVE_FRAMEWORK_INTEGRATIONS[e]?.label??e}function describeError(e){return e instanceof Error?e.message:String(e)}async function syncHostFrameworkPreset(e,t,i,a){let o=await resolveVercelHostFrameworkPreset(t);if(o===void 0)return;let s=await readProjectLink(t);if(s===void 0)return;let c=frameworkPresetLabel(o),l;try{l=await fetchProjectFramework(t,s.orgId,s.projectId,a)}catch(t){if(a.signal?.aborted)throw t;e.log.warning(`Could not check this Vercel project's Framework Preset (${describeError(t)}). If it is not already ${c}, set it under Project Settings → Build and Deployment → Framework Settings before deploying.`);return}if(l===o)return;let u=l===void 0?void 0:frameworkPresetLabel(l),d=u===void 0?`had no Framework Preset set`:`was set to "${u}"`;try{await setProjectFramework(t,s.orgId,s.projectId,o,i,a)}catch(t){if(a.signal?.aborted)throw t;e.log.warning(`${describeError(t)} Set this Vercel project's Framework Preset to ${c} (Project Settings → Build and Deployment → Framework Settings) before deploying, or the deployment will not build your ${c} app.`);return}e.log.info(`This project uses ${c}, but its Vercel Framework Preset ${d}; switched it to ${c} so the deployment builds your app.`)}async function ensureCreatedProjectFramework(e,t,n,r,i,a){let o=await fetchProjectFramework(t,n,r,a);o!==`eve`&&(o===void 0?`switch-to-eve`:await resolveDetectedFrameworkAction(e,t,o,a))===`switch-to-eve`&&await setProjectFramework(t,n,r,`eve`,i,a)}export{ensureCreatedProjectFramework,syncHostFrameworkPreset};

package/dist/src/shared/agent-definition.d.ts

@@ -165,6 +165,13 @@ export interface AgentLimitsDefinition {
  * These options are unstable and may change or be removed in any release.
  */
 export interface AgentExperimentalDefinition {
+    /**
+     * Keeps this agent's delegated subagent sessions alive after they answer.
+     * The model can pass `agentId` to a subagent tool to continue a previous
+     * delegation, and the system prompt documents the `<agents>` listing.
+     * When unset, delegated children run as one-shot tasks.
+     */
+    readonly subagentPersistentSessions?: boolean;
     /**
      * Durable Workflow runtime configuration. Root agents may use this to select
      * the Workflow world backing sessions and runs.

package/dist/src/shared/agent-turn-outcome.d.ts

@@ -0,0 +1,47 @@
+import { z } from "#compiled/zod/index.js";
+import type { JsonValue } from "#shared/json.js";
+import { type TokenUsage } from "#shared/token-usage.js";
+/**
+ * What one delegated child turn produced, independent of whether the child
+ * session survived it.
+ */
+export type AgentTurnResult = {
+    readonly kind: "succeeded";
+    readonly output: JsonValue;
+} | {
+    readonly kind: "failed";
+    readonly error: JsonValue;
+} | {
+    readonly kind: "cancelled";
+};
+/**
+ * How one delegated child turn settled.
+ *
+ * `parked` means the child session survived the turn and can accept another
+ * delivery; `terminal` means the child session ended with this turn. The
+ * lifecycle is carried explicitly: a failed turn can leave the child parked,
+ * and a succeeded turn can be terminal (task mode). Consumers must never
+ * infer lifecycle from success or error codes.
+ *
+ * `usageDelta` is the provider-reported usage this turn added to the child's
+ * session subtree: the child captures its session totals at turn entry and
+ * reports final-minus-entry when the turn settles. The parent folds each
+ * delta exactly once, so repeated turns of a persistent child never re-report
+ * earlier turns.
+ */
+export type AgentTurnOutcome = {
+    readonly kind: "parked";
+    readonly result: AgentTurnResult;
+    readonly usageDelta: TokenUsage;
+} | {
+    readonly kind: "terminal";
+    readonly result: AgentTurnResult;
+    readonly usageDelta: TokenUsage;
+};
+/**
+ * Zod schema for {@link AgentTurnOutcome}.
+ *
+ * Validates outcomes crossing the process boundary (remote session
+ * callbacks). Local notification paths construct the type directly.
+ */
+export declare const agentTurnOutcomeSchema: z.ZodType<AgentTurnOutcome>;

package/dist/src/shared/agent-turn-outcome.js

@@ -0,0 +1 @@
+import{z}from"#compiled/zod/index.js";import{tokenUsageSchema}from"#shared/token-usage.js";const jsonValueSchema=z.lazy(()=>z.union([z.null(),z.boolean(),z.number(),z.string(),z.array(jsonValueSchema),z.record(z.string(),jsonValueSchema)])),agentTurnResultSchema=z.discriminatedUnion(`kind`,[z.strictObject({kind:z.literal(`succeeded`),output:jsonValueSchema}),z.strictObject({error:jsonValueSchema,kind:z.literal(`failed`)}),z.strictObject({kind:z.literal(`cancelled`)})]),agentTurnOutcomeSchema=z.discriminatedUnion(`kind`,[z.strictObject({kind:z.literal(`parked`),result:agentTurnResultSchema,usageDelta:tokenUsageSchema}),z.strictObject({kind:z.literal(`terminal`),result:agentTurnResultSchema,usageDelta:tokenUsageSchema})]);export{agentTurnOutcomeSchema};

package/dist/src/shared/dynamic-tool-definition.d.ts

@@ -116,7 +116,7 @@ export declare const DYNAMIC_SENTINEL_KIND: "eve:dynamic";
 /**
  * Return value of `defineDynamic`: the runtime shape of a dynamic export,
  * stamped with a sentinel kind the compiler/normalizer detects. `TFallback`
- * is `never` except for dynamic agent models, the only slot with a fallback.
+ * is used by dynamic agent models.
  */
 export type DynamicSentinel<TResult = unknown, TFallback = never> = {
     readonly kind: typeof DYNAMIC_SENTINEL_KIND;
@@ -124,10 +124,6 @@ export type DynamicSentinel<TResult = unknown, TFallback = never> = {
 } & ([TFallback] extends [never] ? object : {
     readonly fallback: TFallback;
 });
-/**
- * Throws when a dynamic sentinel outside the agent `model` slot carries a
- * `fallback` — anywhere else it would be silently dead configuration.
- */
 export declare function rejectDynamicSentinelFallback(sentinel: DynamicSentinel, message: string): void;
 export declare function isDynamicSentinel(value: unknown): value is DynamicSentinel;
 /**

package/dist/src/shared/dynamic-tool-definition.js

@@ -1 +1 @@
-const ALLOWED_DYNAMIC_TOOL_EVENTS=new Set([`session.started`,`turn.started`,`step.started`]),ALLOWED_DYNAMIC_INSTRUCTION_EVENTS=new Set([`session.started`,`turn.started`]),ALLOWED_DYNAMIC_SKILL_EVENTS=new Set([`session.started`,`turn.started`]),DYNAMIC_SENTINEL_KIND=`eve:dynamic`;function rejectDynamicSentinelFallback(e,t){if(`fallback`in e)throw Error(`${t} "fallback" is only supported on a dynamic agent model (the "model" field in agent.ts). For dynamic tools, skills, and instructions, author a static entry as the default or return null.`)}function isDynamicSentinel(e){return typeof e==`object`&&!!e&&e.kind===`eve:dynamic`}const TOOL_BRAND=Symbol.for(`eve:tool-brand`);function isBrandedToolEntry(e){return typeof e==`object`&&!!e&&e[TOOL_BRAND]===!0}const INSTRUCTIONS_BRAND=Symbol.for(`eve:instructions-brand`);function isBrandedInstructionsEntry(e){return typeof e==`object`&&!!e&&e[INSTRUCTIONS_BRAND]===!0}const SKILL_BRAND=Symbol.for(`eve:skill-brand`);function isBrandedSkillEntry(e){return typeof e==`object`&&!!e&&e[SKILL_BRAND]===!0}export{ALLOWED_DYNAMIC_INSTRUCTION_EVENTS,ALLOWED_DYNAMIC_SKILL_EVENTS,ALLOWED_DYNAMIC_TOOL_EVENTS,DYNAMIC_SENTINEL_KIND,INSTRUCTIONS_BRAND,SKILL_BRAND,TOOL_BRAND,isBrandedInstructionsEntry,isBrandedSkillEntry,isBrandedToolEntry,isDynamicSentinel,rejectDynamicSentinelFallback};
+const ALLOWED_DYNAMIC_TOOL_EVENTS=new Set([`session.started`,`turn.started`,`step.started`]),ALLOWED_DYNAMIC_INSTRUCTION_EVENTS=new Set([`session.started`,`turn.started`]),ALLOWED_DYNAMIC_SKILL_EVENTS=new Set([`session.started`,`turn.started`]),DYNAMIC_SENTINEL_KIND=`eve:dynamic`;function rejectDynamicSentinelFallback(e,t){if(`fallback`in e)throw Error(`${t} "fallback" is only supported on a dynamic agent model. For dynamic tools, skills, instructions, and subagents, return null when the capability should be omitted.`)}function isDynamicSentinel(e){return typeof e==`object`&&!!e&&e.kind===`eve:dynamic`}const TOOL_BRAND=Symbol.for(`eve:tool-brand`);function isBrandedToolEntry(e){return typeof e==`object`&&!!e&&e[TOOL_BRAND]===!0}const INSTRUCTIONS_BRAND=Symbol.for(`eve:instructions-brand`);function isBrandedInstructionsEntry(e){return typeof e==`object`&&!!e&&e[INSTRUCTIONS_BRAND]===!0}const SKILL_BRAND=Symbol.for(`eve:skill-brand`);function isBrandedSkillEntry(e){return typeof e==`object`&&!!e&&e[SKILL_BRAND]===!0}export{ALLOWED_DYNAMIC_INSTRUCTION_EVENTS,ALLOWED_DYNAMIC_SKILL_EVENTS,ALLOWED_DYNAMIC_TOOL_EVENTS,DYNAMIC_SENTINEL_KIND,INSTRUCTIONS_BRAND,SKILL_BRAND,TOOL_BRAND,isBrandedInstructionsEntry,isBrandedSkillEntry,isBrandedToolEntry,isDynamicSentinel,rejectDynamicSentinelFallback};

package/dist/src/shared/guards.d.ts

@@ -29,6 +29,8 @@ export declare function isObject(value: unknown): value is Record<string, unknow
  * meaningful value by display or correlation logic.
  */
 export declare function isNonEmptyString(value: unknown): value is string;
+/** Returns a non-empty string or `undefined` for any other value. */
+export declare function readNonEmptyString(value: unknown): string | undefined;
 /**
  * Returns `true` when `value` is a thenable — an object with a `then`
  * function. Used to reject async instrumentation metadata projectors

package/dist/src/shared/guards.js

@@ -1 +1 @@
-function isObject(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function isNonEmptyString(e){return typeof e==`string`&&e.length>0}function isThenable(e){return isObject(e)&&typeof e.then==`function`}function isErrnoCode(e,t){return e instanceof Error&&`code`in e&&e.code===t}function isPlainRecord(e){if(!isObject(e))return!1;let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}export{isErrnoCode,isNonEmptyString,isObject,isPlainRecord,isThenable};
+function isObject(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function isNonEmptyString(e){return typeof e==`string`&&e.length>0}function readNonEmptyString(e){return isNonEmptyString(e)?e:void 0}function isThenable(e){return isObject(e)&&typeof e.then==`function`}function isErrnoCode(e,t){return e instanceof Error&&`code`in e&&e.code===t}function isPlainRecord(e){if(!isObject(e))return!1;let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}export{isErrnoCode,isNonEmptyString,isObject,isPlainRecord,isThenable,readNonEmptyString};

package/dist/src/shared/skill-package.js

@@ -1 +1 @@
-import{dirname,join}from"node:path";import{mkdir,writeFile}from"node:fs/promises";import{resolveSandboxSkillRoot,resolveSandboxSkillWritePath}from"#shared/skill-paths.js";import{Buffer}from"node:buffer";function normalizeSkillPackage(e){assertSafeSkillPackageName(e.name);let t=[{content:Buffer.from(e.markdown,`utf8`),relativePath:`SKILL.md`}];for(let[n,r]of Object.entries(e.files??{}))assertSafeSkillPackageFilePath(n),t.push({content:contentToBuffer(r),relativePath:n});return t.sort((e,t)=>comparePaths(e.relativePath,t.relativePath)),{description:e.description,files:t,license:e.license,markdown:e.markdown,metadata:e.metadata===void 0?void 0:{...e.metadata},name:e.name}}async function writeSkillPackageDirectory(i){for(let a of i.skill.files){let o=join(i.rootPath,`skills`,i.skill.name,a.relativePath);await mkdir(dirname(o),{recursive:!0}),await writeFile(o,a.content)}}async function writeSkillPackageToSandbox(e){for(let t of e.skill.files)await e.sandbox.writeBinaryFile({content:t.content,path:await resolveSandboxSkillWritePath({name:e.skill.name,relativePath:t.relativePath,sandbox:e.sandbox})})}async function removeSkillPackageFromSandbox(e){assertSafeSkillPackageName(e.name);let t=await resolveSandboxSkillRoot({sandbox:e.sandbox});await e.sandbox.removePath({force:!0,path:`${t}/${e.name}`,recursive:!0})}function assertSafeSkillPackageName(e){if(e.length===0||e.startsWith(`.`)||e.includes(`/`)||e.includes(`\\`)||e.includes(`..`)||!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(e)||/^[A-Za-z]:/.test(e))throw Error(`Expected skill name to be a non-empty shell-safe path segment starting with an alphanumeric character and containing only alphanumerics, ".", "_", or "-".`)}function assertSafeSkillPackageFilePath(e){if(e===`SKILL.md`)throw Error(`Skill package files must not include "SKILL.md"; eve generates it.`);if(e.length===0||e.startsWith(`/`)||e.includes(`\\`)||/^[A-Za-z]:/.test(e)||e.split(`/`).some(e=>e.length===0||e===`.`||e===`..`))throw Error(`Expected skill package file paths to be relative POSIX paths.`)}function contentToBuffer(e){return typeof e==`string`?Buffer.from(e,`utf8`):Buffer.from(e)}function comparePaths(e,t){return e<t?-1:+(e>t)}export{assertSafeSkillPackageName,normalizeSkillPackage,removeSkillPackageFromSandbox,writeSkillPackageDirectory,writeSkillPackageToSandbox};
+import{mkdir,writeFile}from"node:fs/promises";import{dirname,join}from"node:path";import{resolveSandboxSkillRoot,resolveSandboxSkillWritePath}from"#shared/skill-paths.js";import{Buffer}from"node:buffer";function normalizeSkillPackage(e){assertSafeSkillPackageName(e.name);let t=[{content:Buffer.from(e.markdown,`utf8`),relativePath:`SKILL.md`}];for(let[n,r]of Object.entries(e.files??{}))assertSafeSkillPackageFilePath(n),t.push({content:contentToBuffer(r),relativePath:n});return t.sort((e,t)=>comparePaths(e.relativePath,t.relativePath)),{description:e.description,files:t,license:e.license,markdown:e.markdown,metadata:e.metadata===void 0?void 0:{...e.metadata},name:e.name}}async function writeSkillPackageDirectory(i){for(let a of i.skill.files){let o=join(i.rootPath,`skills`,i.skill.name,a.relativePath);await mkdir(dirname(o),{recursive:!0}),await writeFile(o,a.content)}}async function writeSkillPackageToSandbox(e){for(let t of e.skill.files)await e.sandbox.writeBinaryFile({content:t.content,path:await resolveSandboxSkillWritePath({name:e.skill.name,relativePath:t.relativePath,sandbox:e.sandbox})})}async function removeSkillPackageFromSandbox(e){assertSafeSkillPackageName(e.name);let t=await resolveSandboxSkillRoot({sandbox:e.sandbox});await e.sandbox.removePath({force:!0,path:`${t}/${e.name}`,recursive:!0})}function assertSafeSkillPackageName(e){if(e.length===0||e.startsWith(`.`)||e.includes(`/`)||e.includes(`\\`)||e.includes(`..`)||!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(e)||/^[A-Za-z]:/.test(e))throw Error(`Expected skill name to be a non-empty shell-safe path segment starting with an alphanumeric character and containing only alphanumerics, ".", "_", or "-".`)}function assertSafeSkillPackageFilePath(e){if(e===`SKILL.md`)throw Error(`Skill package files must not include "SKILL.md"; eve generates it.`);if(e.length===0||e.startsWith(`/`)||e.includes(`\\`)||/^[A-Za-z]:/.test(e)||e.split(`/`).some(e=>e.length===0||e===`.`||e===`..`))throw Error(`Expected skill package file paths to be relative POSIX paths.`)}function contentToBuffer(e){return typeof e==`string`?Buffer.from(e,`utf8`):Buffer.from(e)}function comparePaths(e,t){return e<t?-1:+(e>t)}export{assertSafeSkillPackageName,normalizeSkillPackage,removeSkillPackageFromSandbox,writeSkillPackageDirectory,writeSkillPackageToSandbox};

package/dist/src/shared/skill-paths.d.ts

@@ -9,6 +9,10 @@ export declare function formatFallbackSkillPath(input: {
     readonly name: string;
     readonly relativePath: string;
 }): string;
+/**
+ * Resolves where skills live in the sandbox: under the probed home when it has
+ * one, and under {@link FALLBACK_SKILL_ROOT} when it does not.
+ */
 export declare function resolveSandboxSkillRoot(input: {
     readonly sandbox: SandboxSession;
 }): Promise<string>;
@@ -32,7 +36,3 @@ export declare function resolveSandboxSkillWritePath(input: {
     readonly relativePath: string;
     readonly sandbox: SandboxSession;
 }): Promise<string>;
-export declare function resolveSandboxSeedFilePath(input: {
-    readonly path: string;
-    readonly sandbox: SandboxSession;
-}): Promise<string>;

package/dist/src/shared/skill-paths.js

@@ -1,2 +1,2 @@
-const MODEL_SKILL_ROOT=`$HOME/.agents/skills`,FALLBACK_SKILL_ROOT=`/workspace/skills`,MODEL_HOME_ROOT=`$HOME`,sandboxHomeCache=new WeakMap;function formatSkillModelPath(t){return formatSkillPath({name:t.name,relativePath:t.relativePath,root:MODEL_SKILL_ROOT})}function formatFallbackSkillPath(e){return formatSkillPath({name:e.name,relativePath:e.relativePath,root:FALLBACK_SKILL_ROOT})}async function resolveSandboxSkillRoot(e){let n=await resolveSandboxHome(e.sandbox);return n===null?FALLBACK_SKILL_ROOT:joinHomeSkillRoot(n)}async function resolveSandboxModelPath(e){if(!isModelHomePath(e.path))return e.path;let n=await resolveSandboxHome(e.sandbox);if(n!==null){let t=e.path.slice(5);return t.length===0?n:`${n===`/`?``:n}${t}`}return isModelSkillPath(e.path)?`${FALLBACK_SKILL_ROOT}${e.path.slice(20)}`:e.path}async function resolveSandboxSkillReadPaths(e){return[formatSkillPath({name:e.name,relativePath:e.relativePath,root:await resolveSandboxSkillRoot({sandbox:e.sandbox})})]}async function resolveSandboxSkillWritePath(e){return formatSkillPath({name:e.name,relativePath:e.relativePath,root:await resolveSandboxSkillRoot({sandbox:e.sandbox})})}async function resolveSandboxSeedFilePath(e){return isModelSkillPath(e.path)?await resolveSandboxModelPath(e):e.path}function formatSkillPath(e){return`${e.root}/${e.name}/${e.relativePath}`}async function resolveSandboxHome(e){let t=sandboxHomeCache.get(e);if(t!==void 0)return await t;let n=probeSandboxHome(e);return sandboxHomeCache.set(e,n),await n}async function probeSandboxHome(e){try{let t=await e.run({command:`printf '%s\\n' "$HOME"`});if(t.exitCode!==0)return null;let n=t.stdout.trim();return isUsableSandboxHome(n)?normalizeSandboxHome(n):null}catch{return null}}function isModelHomePath(e){return e===MODEL_HOME_ROOT||e.startsWith(`${MODEL_HOME_ROOT}/`)}function isModelSkillPath(e){return e===`$HOME/.agents/skills`||e.startsWith(`$HOME/.agents/skills/`)}function isUsableSandboxHome(e){return e.length>0&&e.startsWith(`/`)&&!e.includes(`\0`)&&!e.includes(`
-`)&&!e.includes(`\r`)}function joinHomeSkillRoot(e){return`${e===`/`?``:e}/.agents/skills`}function normalizeSandboxHome(e){return e===`/`?e:e.replace(/\/+$/,``)}export{FALLBACK_SKILL_ROOT,MODEL_SKILL_ROOT,formatFallbackSkillPath,formatSkillModelPath,resolveSandboxModelPath,resolveSandboxSeedFilePath,resolveSandboxSkillReadPaths,resolveSandboxSkillRoot,resolveSandboxSkillWritePath};
+const MODEL_HOME_ROOT=`$HOME`,MODEL_SKILL_ROOT=`${MODEL_HOME_ROOT}/.agents/skills`,FALLBACK_SKILL_ROOT=`/workspace/skills`,sandboxHomeCache=new WeakMap;function formatSkillModelPath(e){return formatSkillPath({name:e.name,relativePath:e.relativePath,root:MODEL_SKILL_ROOT})}function formatFallbackSkillPath(e){return formatSkillPath({name:e.name,relativePath:e.relativePath,root:FALLBACK_SKILL_ROOT})}async function resolveSandboxSkillRoot(e){return await resolveSandboxModelPath({path:MODEL_SKILL_ROOT,sandbox:e.sandbox})}async function resolveSandboxModelPath(e){if(!isModelHomePath(e.path))return e.path;let r=await resolveSandboxHome(e.sandbox);if(r!==null){let t=e.path.slice(5);return t.length===0?r:`${r===`/`?``:r}${t}`}return isModelSkillPath(e.path)?`${FALLBACK_SKILL_ROOT}${e.path.slice(MODEL_SKILL_ROOT.length)}`:e.path}async function resolveSandboxSkillReadPaths(e){return[formatSkillPath({name:e.name,relativePath:e.relativePath,root:await resolveSandboxSkillRoot({sandbox:e.sandbox})})]}async function resolveSandboxSkillWritePath(e){return formatSkillPath({name:e.name,relativePath:e.relativePath,root:await resolveSandboxSkillRoot({sandbox:e.sandbox})})}function formatSkillPath(e){return`${e.root}/${e.name}/${e.relativePath}`}async function resolveSandboxHome(e){let t=sandboxHomeCache.get(e);if(t!==void 0)return await t;let n=probeSandboxHome(e);return sandboxHomeCache.set(e,n),await n}async function probeSandboxHome(e){try{let t=await e.run({command:`printf '%s\\n' "$HOME"`});if(t.exitCode!==0)return null;let n=t.stdout.trim();return isUsableSandboxHome(n)?normalizeSandboxHome(n):null}catch{return null}}function isModelHomePath(t){return t===MODEL_HOME_ROOT||t.startsWith(`${MODEL_HOME_ROOT}/`)}function isModelSkillPath(e){return e===MODEL_SKILL_ROOT||e.startsWith(`${MODEL_SKILL_ROOT}/`)}function isUsableSandboxHome(e){return e.length>0&&e.startsWith(`/`)&&!e.includes(`\0`)&&!e.includes(`
+`)&&!e.includes(`\r`)}function normalizeSandboxHome(e){return e===`/`?e:e.replace(/\/+$/,``)}export{FALLBACK_SKILL_ROOT,MODEL_SKILL_ROOT,formatFallbackSkillPath,formatSkillModelPath,resolveSandboxModelPath,resolveSandboxSkillReadPaths,resolveSandboxSkillRoot,resolveSandboxSkillWritePath};

package/dist/src/shared/vercel-output-directory.js

@@ -1 +1 @@
-import{dirname,join}from"node:path";import{stat}from"node:fs/promises";async function fileExists(e){try{return(await stat(e)).isFile()}catch(e){if(e instanceof Error&&`code`in e&&e.code===`ENOENT`)return!1;throw e}}async function findClosestDirectoryWithFile(t){let n=t.start;for(;;){let r=join(n,t.directoryName);if(await fileExists(join(r,t.fileName)))return r;let i=dirname(n);if(i===n)return;n=i}}async function findClosestLinkedVercelDirectory(e){return findClosestDirectoryWithFile({start:e,directoryName:`.vercel`,fileName:`project.json`})}async function findClosestVercelOutputDirectory(e){return findClosestDirectoryWithFile({start:e,directoryName:`output`,fileName:`builds.json`})}export{findClosestLinkedVercelDirectory,findClosestVercelOutputDirectory};
+import{stat}from"node:fs/promises";import{dirname,join}from"node:path";async function fileExists(t){try{return(await stat(t)).isFile()}catch(e){if(e instanceof Error&&`code`in e&&e.code===`ENOENT`)return!1;throw e}}async function findClosestDirectoryWithFile(e){let n=e.start;for(;;){let r=join(n,e.directoryName);if(await fileExists(join(r,e.fileName)))return r;let i=dirname(n);if(i===n)return;n=i}}async function findClosestLinkedVercelDirectory(e){return findClosestDirectoryWithFile({start:e,directoryName:`.vercel`,fileName:`project.json`})}async function findClosestVercelOutputDirectory(e){return findClosestDirectoryWithFile({start:e,directoryName:`output`,fileName:`builds.json`})}export{findClosestLinkedVercelDirectory,findClosestVercelOutputDirectory};

package/dist/src/source-change/static-source-change.js

@@ -1 +1 @@
-import{join}from"node:path";import{readFile,rename,writeFile}from"node:fs/promises";import{checkAgentConfigSource}from"#source-change/agent-config-string-path.js";import{applyAgentModelSettingsToSource}from"#source-change/apply-agent-model-settings.js";import{applyModelNameToSource}from"#source-change/apply-model-name.js";function createStaticSourceChange(e){return{updateModelName:t=>updateAgentModelName(e,t),updateModelSettings:t=>updateAgentModelSettings(e,t)}}async function updateAgentModelSettings(n,r){let i=n.configModule;if(i===void 0)return{kind:`bail`,reason:`agent has no agent.ts config module to edit`,at:{logicalPath:`agent.ts`,line:1}};let o=join(n.agentRoot,i.logicalPath),s=await readFile(o,`utf8`),c=await applyAgentModelSettingsToSource(s,r);if(c.kind===`bail`)return{kind:`bail`,reason:c.reason,at:{logicalPath:i.logicalPath,line:c.line}};let l=await editedSourceBail(s,c.nextSource,i.logicalPath);return l===void 0?(await writeSourceIfChanged(o,s,c.nextSource),{kind:`applied`,changed:c.changed}):l}async function updateAgentModelName(n,r){let i=n.configModule;if(i===void 0)return{kind:`bail`,reason:`agent has no agent.ts config module to edit`,at:{logicalPath:`agent.ts`,line:1}};let a=join(n.agentRoot,i.logicalPath),s=await readFile(a,`utf8`),c=await applyModelNameToSource(s,r);if(c.kind===`bail`)return{kind:`bail`,reason:c.reason,at:{logicalPath:i.logicalPath,line:c.line}};let l=await editedSourceBail(s,c.nextSource,i.logicalPath);return l===void 0?(await writeSourceIfChanged(a,s,c.nextSource),{kind:`applied`,from:c.from,to:c.to}):l}async function writeSourceIfChanged(e,t,i){if(i===t)return;let a=`${e}.${process.pid}.eve-tmp`;await writeFile(a,i,`utf8`),await rename(a,e)}async function editedSourceBail(e,t,n){if(t===e)return;let r=await checkAgentConfigSource(t);if(r!==void 0)return{kind:`bail`,reason:`the edit produced source eve refuses to write (${r})`,at:{logicalPath:n,line:1}}}export{createStaticSourceChange};
+import{readFile,rename,writeFile}from"node:fs/promises";import{join}from"node:path";import{checkAgentConfigSource}from"#source-change/agent-config-string-path.js";import{applyAgentModelSettingsToSource}from"#source-change/apply-agent-model-settings.js";import{applyModelNameToSource}from"#source-change/apply-model-name.js";function createStaticSourceChange(e){return{updateModelName:t=>updateAgentModelName(e,t),updateModelSettings:t=>updateAgentModelSettings(e,t)}}async function updateAgentModelSettings(t,n){let i=t.configModule;if(i===void 0)return{kind:`bail`,reason:`agent has no agent.ts config module to edit`,at:{logicalPath:`agent.ts`,line:1}};let o=join(t.agentRoot,i.logicalPath),s=await readFile(o,`utf8`),c=await applyAgentModelSettingsToSource(s,n);if(c.kind===`bail`)return{kind:`bail`,reason:c.reason,at:{logicalPath:i.logicalPath,line:c.line}};let l=await editedSourceBail(s,c.nextSource,i.logicalPath);return l===void 0?(await writeSourceIfChanged(o,s,c.nextSource),{kind:`applied`,changed:c.changed}):l}async function updateAgentModelName(t,n){let i=t.configModule;if(i===void 0)return{kind:`bail`,reason:`agent has no agent.ts config module to edit`,at:{logicalPath:`agent.ts`,line:1}};let a=join(t.agentRoot,i.logicalPath),s=await readFile(a,`utf8`),c=await applyModelNameToSource(s,n);if(c.kind===`bail`)return{kind:`bail`,reason:c.reason,at:{logicalPath:i.logicalPath,line:c.line}};let l=await editedSourceBail(s,c.nextSource,i.logicalPath);return l===void 0?(await writeSourceIfChanged(a,s,c.nextSource),{kind:`applied`,from:c.from,to:c.to}):l}async function writeSourceIfChanged(e,r,i){if(i===r)return;let a=`${e}.${process.pid}.eve-tmp`;await writeFile(a,i,`utf8`),await rename(a,e)}async function editedSourceBail(e,t,n){if(t===e)return;let r=await checkAgentConfigSource(t);if(r!==void 0)return{kind:`bail`,reason:`the edit produced source eve refuses to write (${r})`,at:{logicalPath:n,line:1}}}export{createStaticSourceChange};

package/dist/src/svelte/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-DaH3cf8K.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-BXMIf5fR.js";
 
 export { defaultMessageReducer, useEveAgent };

package/dist/src/svelte/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-DaH3cf8K.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-BXMIf5fR.js";
 
 export { useEveAgent };

package/dist/src/tracing/local-instrumentation-runtime.js

@@ -1 +1 @@
-import{LocalTraceSpanProcessor}from"#tracing/local-trace-span-processor.js";import{ContextAgentTraceStateStore}from"#tracing/agent-trace-context-store.js";import{getInstrumentationRuntime,registerInstrumentationRuntime}from"#harness/instrumentation-runtime.js";import{context,trace}from"#compiled/@opentelemetry/api/index.js";import{registerOTel}from"#compiled/@vercel/otel/index.js";import{createAgentOtelInstrumentation}from"#tracing/agent-otel-provider.js";import{AgentTraceSpanProcessor}from"#tracing/agent-trace-span-processor.js";import{createInstrumentationHooks}from"#harness/instrumentation-lifecycle.js";import{requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings}from"#tracing/local-trace-retention.js";function installLocalInstrumentationRuntime(t){let n=getInstrumentationRuntime();if(n!==void 0)return n;let r=resolveLocalTraceRetentionSettings(),i=new AgentTraceSpanProcessor(r.enabled?[new LocalTraceSpanProcessor(t.appRoot)]:[]);registerOTel({autoDetectResources:!1,instrumentations:[],propagators:[`none`],serviceName:t.serviceName,spanProcessors:[i]});let a=trace.getTracer(`eve.registration`).startSpan(`eve.otel.registration`),o=trace.setSpan(context.active(),a),s=context.with(o,()=>trace.getActiveSpan()===a);if(a.end(),!i.isAttached()||!s)throw Error(`eve could not register OpenTelemetry because another runtime already exists.`);let c=createAgentOtelInstrumentation({captureContent:process.env.EVE_TRACES_CONTENT!==`off`,frameworkVersion:t.frameworkVersion,stateStore:new ContextAgentTraceStateStore,tracer:trace.getTracer(`eve.agent`,t.frameworkVersion)}),l={events:{"session.completed":releaseSessionTrace,"session.failed":releaseSessionTrace}};return requestPrune(),registerInstrumentationRuntime({forceFlush:()=>i.forceFlush(),hooks:createInstrumentationHooks([c.hook,l]),runInContext:c.runInContext});async function releaseSessionTrace(e){await i.forceFlush(),i.releaseSession(e.sessionId)&&requestPrune()}function requestPrune(){r.enabled&&requestLocalTraceStorePrune({activeTraceIds:i.activeTraceIds(),appRoot:t.appRoot,maxAgeMs:r.maxAgeMs,maxTotalBytes:r.maxTotalBytes,retainCount:r.retainCount})}}export{installLocalInstrumentationRuntime};
+import{ContextAgentTraceStateStore}from"#tracing/agent-trace-context-store.js";import{getInstrumentationRuntime,registerInstrumentationRuntime}from"#harness/instrumentation-runtime.js";import{context,trace}from"#compiled/@opentelemetry/api/index.js";import{registerOTel}from"#compiled/@vercel/otel/index.js";import{createAgentOtelInstrumentation}from"#tracing/agent-otel-provider.js";import{AgentTraceSpanProcessor}from"#tracing/agent-trace-span-processor.js";import{createInstrumentationHooks}from"#harness/instrumentation-lifecycle.js";import{requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings}from"#tracing/local-trace-retention.js";import{LocalTraceSpanProcessor}from"#tracing/local-trace-span-processor.js";function installLocalInstrumentationRuntime(t){let n=getInstrumentationRuntime();if(n!==void 0)return n;let r=resolveLocalTraceRetentionSettings(),i=new AgentTraceSpanProcessor(r.enabled?[new LocalTraceSpanProcessor(t.appRoot)]:[]);registerOTel({autoDetectResources:!1,instrumentations:[],propagators:[`none`],serviceName:t.serviceName,spanProcessors:[i]});let a=trace.getTracer(`eve.registration`).startSpan(`eve.otel.registration`),o=trace.setSpan(context.active(),a),s=context.with(o,()=>trace.getActiveSpan()===a);if(a.end(),!i.isAttached()||!s)throw Error(`eve could not register OpenTelemetry because another runtime already exists.`);let c=createAgentOtelInstrumentation({captureContent:process.env.EVE_TRACES_CONTENT!==`off`,frameworkVersion:t.frameworkVersion,stateStore:new ContextAgentTraceStateStore,tracer:trace.getTracer(`eve.agent`,t.frameworkVersion)}),l={events:{"session.completed":releaseSessionTrace,"session.failed":releaseSessionTrace}};return requestPrune(),registerInstrumentationRuntime({forceFlush:()=>i.forceFlush(),hooks:createInstrumentationHooks([c.hook,l]),runInContext:c.runInContext});async function releaseSessionTrace(e){await i.forceFlush(),i.releaseSession(e.sessionId)&&requestPrune()}function requestPrune(){r.enabled&&requestLocalTraceStorePrune({activeTraceIds:i.activeTraceIds(),appRoot:t.appRoot,maxAgeMs:r.maxAgeMs,maxTotalBytes:r.maxTotalBytes,retainCount:r.retainCount})}}export{installLocalInstrumentationRuntime};

package/dist/src/tracing/local-trace-reader.d.ts

@@ -36,13 +36,30 @@ export interface LocalTrace {
     /** Zero-based session window this trace holds, when the spans record one. */
     readonly window?: number;
 }
-/** Reads valid local traces, newest first, while ignoring malformed segments. */
-export declare function listLocalTraces(appRoot: string): Promise<LocalTrace[]>;
 /**
- * Reads one trace from its segments directory, or `undefined` when the trace
- * has no valid spans. Spans come back ordered by start time.
+ * Trace ids held by the spool, unordered. Empty when nothing has been written
+ * yet; any other read fault propagates.
+ */
+export declare function listLocalTraceIds(appRoot: string): Promise<string[]>;
+/**
+ * Instant one trace last received a span, or `undefined` once retention has
+ * pruned it. Reads the segments directory's mtime, so it stays cheap enough to
+ * poll a large spool without parsing any span.
+ */
+export declare function readLocalTraceActivityMs(appRoot: string, traceId: string): Promise<number | undefined>;
+/**
+ * Segment file names of one trace in read order, or `undefined` when the trace
+ * is gone. Segments are immutable and named for their span, so the order is
+ * stable across reads and a caller can treat names it has seen as parsed.
+ */
+export declare function listLocalTraceSegments(appRoot: string, traceId: string): Promise<string[] | undefined>;
+/**
+ * Spans held by one segment file. An oversized, unreadable, or malformed
+ * segment yields none, so a partial write never breaks a view.
  */
-export declare function readLocalTrace(root: string, traceId: string): Promise<LocalTrace | undefined>;
+export declare function readLocalTraceSegment(appRoot: string, traceId: string, fileName: string): Promise<LocalTraceSpan[]>;
+/** Reads valid local traces, newest first, while ignoring malformed segments. */
+export declare function listLocalTraces(appRoot: string): Promise<LocalTrace[]>;
 /** Sorts spans into timeline order: start, then end, then a stable tiebreak. */
 export declare function compareLocalTraceSpans(left: LocalTraceSpan, right: LocalTraceSpan): number;
 /** Builds a trace from already-parsed spans, deriving summary fields. */

package/dist/src/tracing/local-trace-reader.js

@@ -1 +1 @@
-import{join}from"node:path";import{readFile,readdir,stat}from"node:fs/promises";import{resolveLocalTraceSchemaDirectory}from"#tracing/local-trace-span-processor.js";const TRACE_ID_PATTERN=/^[0-9a-f]{32}$/u,SPAN_FILE_PATTERN=/^([0-9a-f]{16})\.otlp\.json$/u;async function listLocalTraces(e){let t=resolveLocalTraceSchemaDirectory(e),r;try{r=await readdir(t,{withFileTypes:!0})}catch(e){if(isMissing(e))return[];throw e}let o=[];for(let e of r){if(!e.isDirectory()||!TRACE_ID_PATTERN.test(e.name))continue;let n=await readLocalTrace(t,e.name).catch(()=>void 0);n!==void 0&&o.push(n)}return o.sort((e,t)=>e.startTimeNs===t.startTimeNs?e.traceId.localeCompare(t.traceId):e.startTimeNs>t.startTimeNs?-1:1)}async function readLocalTrace(i,a){let s=join(i,a,`segments`),c;try{c=await readdir(s,{withFileTypes:!0})}catch(e){if(isMissing(e))return;throw e}let l=new Map;for(let n of c.sort((e,t)=>e.name.localeCompare(t.name))){if(!n.isFile()||!SPAN_FILE_PATTERN.test(n.name))continue;let i;try{let a=join(s,n.name);if((await stat(a)).size>8388608)continue;i=await readFile(a,`utf8`)}catch{continue}for(let e of parseLocalTraceSegment(i,a))l.has(e.spanId)||l.set(e.spanId,e)}if(l.size!==0)return assembleLocalTrace(a,[...l.values()])}function compareLocalTraceSpans(e,t){return e.startTimeNs===t.startTimeNs?e.endTimeNs===t.endTimeNs?e.name.localeCompare(t.name)||e.spanId.localeCompare(t.spanId):e.endTimeNs<t.endTimeNs?-1:1:e.startTimeNs<t.startTimeNs?-1:1}function assembleLocalTrace(e,t){let n=[...t].sort(compareLocalTraceSpans),r=n.map(e=>e.attributes),i=distinctAttributes(r,`agent.session.id`);return{agentName:firstAttribute(r,`agent.name`),endTimeNs:n.reduce((e,t)=>t.endTimeNs>e?t.endTimeNs:e,0n),sessionId:i[0],sessionIds:i,spans:n,startTimeNs:n.reduce((e,t)=>t.startTimeNs<e?t.startTimeNs:e,n[0].startTimeNs),traceId:e,window:firstNumberAttribute(r,`agent.session.window`)}}function describeLocalTraceSpan(e){let t=[],n=stringSpanAttribute(e,`agent.turn.id`),r=valueSpanAttribute(e,`agent.step.index`),i=valueSpanAttribute(e,`agent.step.attempt`),a=stringSpanAttribute(e,`agent.action.kind`),o=stringSpanAttribute(e,`agent.action.name`),s=stringSpanAttribute(e,`agent.model.id`)??stringSpanAttribute(e,`gen_ai.request.model`);return e.name===`agent.turn`&&n!==void 0&&t.push(n),e.name===`agent.step`&&r!==void 0&&t.push(`step ${String(r)}${i===void 0?``:`, attempt ${String(i)}`}`),e.name===`agent.action`&&o!==void 0&&t.push(`${a??`action`}: ${o}`),s!==void 0&&e.name.includes(`do`)&&t.push(`model ${s}`),t}function parseLocalTraceSegment(e,t){try{let n=JSON.parse(e);if(!isRecord(n)||!Array.isArray(n.resourceSpans))return[];let r=[];for(let e of n.resourceSpans)if(!(!isRecord(e)||!Array.isArray(e.scopeSpans)))for(let n of e.scopeSpans){if(!isRecord(n)||!Array.isArray(n.spans))continue;let e=isRecord(n.scope)&&typeof n.scope.name==`string`?n.scope.name:void 0;for(let i of n.spans){let n=parseLocalTraceSpan(i,t,e);n!==void 0&&r.push(n)}}return r}catch{return[]}}function parseLocalTraceSpan(e,t,n){if(!isRecord(e)||e.traceId!==t||typeof e.spanId!=`string`||!/^[0-9a-f]{16}$/u.test(e.spanId)||typeof e.name!=`string`)return;let r=parseNanos(e.startTimeUnixNano),i=parseNanos(e.endTimeUnixNano);if(!(r===void 0||i===void 0||i<r))return{attributes:parseAttributes(e.attributes),endTimeNs:i,name:e.name,parentSpanId:typeof e.parentSpanId==`string`&&/^[0-9a-f]{16}$/u.test(e.parentSpanId)?e.parentSpanId:void 0,scope:n,spanId:e.spanId,startTimeNs:r,statusCode:parseStatusCode(e.status),traceId:t}}function parseAttributes(e){if(!Array.isArray(e))return{};let t={};for(let n of e){if(!isRecord(n)||typeof n.key!=`string`||!isRecord(n.value))continue;let e=parseAnyValue(n.value);e!==void 0&&(t[n.key]=e)}return t}function parseAnyValue(e){for(let t of[`stringValue`,`boolValue`,`intValue`,`doubleValue`])if(t in e)return e[t];if(isRecord(e.arrayValue)&&Array.isArray(e.arrayValue.values))return e.arrayValue.values.filter(isRecord).map(e=>parseAnyValue(e))}function parseNanos(e){if(!(typeof e!=`string`&&typeof e!=`number`))try{let t=BigInt(e);return t>=0n&&t<=18446744073709551615n?t:void 0}catch{return}}function parseStatusCode(e){return isRecord(e)?typeof e.code==`number`?e.code:e.code===`STATUS_CODE_ERROR`?2:0:0}function firstAttribute(e,t){for(let n of e){let e=n[t];if(typeof e==`string`&&e.length>0)return e}}function firstNumberAttribute(e,t){for(let n of e){let e=n[t];if(typeof e==`number`)return e;if(typeof e==`bigint`)return Number(e)}}function distinctAttributes(e,t){let n=new Set;for(let r of e){let e=r[t];typeof e==`string`&&e.length>0&&n.add(e)}return[...n]}function stringSpanAttribute(e,t){let n=e.attributes[t];return typeof n==`string`?n:void 0}function valueSpanAttribute(e,t){let n=e.attributes[t];return typeof n==`string`||typeof n==`number`?n:void 0}function isMissing(e){return e.code===`ENOENT`}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{assembleLocalTrace,compareLocalTraceSpans,describeLocalTraceSpan,listLocalTraces,parseLocalTraceSegment,readLocalTrace};
+import{readFile,readdir,stat}from"node:fs/promises";import{join}from"node:path";import{resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory}from"#tracing/local-trace-span-processor.js";const TRACE_ID_PATTERN=/^[0-9a-f]{32}$/u,SPAN_FILE_PATTERN=/^[0-9a-f]{16}\.otlp\.json$/u;async function listLocalTraceIds(e){let n;try{n=await readdir(resolveLocalTraceSchemaDirectory(e),{withFileTypes:!0})}catch(e){if(isMissing(e))return[];throw e}return n.filter(e=>e.isDirectory()&&TRACE_ID_PATTERN.test(e.name)).map(e=>e.name)}async function readLocalTraceActivityMs(e,t){try{return(await stat(resolveLocalTraceSegmentsDirectory(e,t))).mtimeMs}catch(e){if(isMissing(e))return;throw e}}async function listLocalTraceSegments(e,n){let r;try{r=await readdir(resolveLocalTraceSegmentsDirectory(e,n),{withFileTypes:!0})}catch(e){if(isMissing(e))return;throw e}return r.filter(e=>e.isFile()&&SPAN_FILE_PATTERN.test(e.name)).map(e=>e.name).sort((e,t)=>e.localeCompare(t))}async function readLocalTraceSegment(t,i,o){let s=join(resolveLocalTraceSegmentsDirectory(t,i),o),c;try{if((await stat(s)).size>8388608)return[];c=await readFile(s,`utf8`)}catch{return[]}return parseLocalTraceSegment(c,i)}async function listLocalTraces(e){let t=[];for(let n of await listLocalTraceIds(e)){let r=await readLocalTrace(e,n).catch(()=>void 0);r!==void 0&&t.push(r)}return t.sort((e,t)=>e.startTimeNs===t.startTimeNs?e.traceId.localeCompare(t.traceId):e.startTimeNs>t.startTimeNs?-1:1)}async function readLocalTrace(e,t){let n=await listLocalTraceSegments(e,t);if(n===void 0)return;let r=new Map;for(let i of n)for(let n of await readLocalTraceSegment(e,t,i))r.has(n.spanId)||r.set(n.spanId,n);if(r.size!==0)return assembleLocalTrace(t,[...r.values()])}function compareLocalTraceSpans(e,t){return e.startTimeNs===t.startTimeNs?e.endTimeNs===t.endTimeNs?e.name.localeCompare(t.name)||e.spanId.localeCompare(t.spanId):e.endTimeNs<t.endTimeNs?-1:1:e.startTimeNs<t.startTimeNs?-1:1}function assembleLocalTrace(e,t){let n=[...t].sort(compareLocalTraceSpans),r=n.map(e=>e.attributes),i=distinctAttributes(r,`agent.session.id`);return{agentName:firstAttribute(r,`agent.name`),endTimeNs:n.reduce((e,t)=>t.endTimeNs>e?t.endTimeNs:e,0n),sessionId:i[0],sessionIds:i,spans:n,startTimeNs:n.reduce((e,t)=>t.startTimeNs<e?t.startTimeNs:e,n[0].startTimeNs),traceId:e,window:firstNumberAttribute(r,`agent.session.window`)}}function describeLocalTraceSpan(e){let t=[],n=stringSpanAttribute(e,`agent.turn.id`),r=valueSpanAttribute(e,`agent.step.index`),i=valueSpanAttribute(e,`agent.step.attempt`),a=stringSpanAttribute(e,`agent.action.kind`),o=stringSpanAttribute(e,`agent.action.name`),s=stringSpanAttribute(e,`agent.model.id`)??stringSpanAttribute(e,`gen_ai.request.model`);return e.name===`agent.turn`&&n!==void 0&&t.push(n),e.name===`agent.step`&&r!==void 0&&t.push(`step ${String(r)}${i===void 0?``:`, attempt ${String(i)}`}`),e.name===`agent.action`&&o!==void 0&&t.push(`${a??`action`}: ${o}`),s!==void 0&&e.name.includes(`do`)&&t.push(`model ${s}`),t}function parseLocalTraceSegment(e,t){try{let n=JSON.parse(e);if(!isRecord(n)||!Array.isArray(n.resourceSpans))return[];let r=[];for(let e of n.resourceSpans)if(!(!isRecord(e)||!Array.isArray(e.scopeSpans)))for(let n of e.scopeSpans){if(!isRecord(n)||!Array.isArray(n.spans))continue;let e=isRecord(n.scope)&&typeof n.scope.name==`string`?n.scope.name:void 0;for(let i of n.spans){let n=parseLocalTraceSpan(i,t,e);n!==void 0&&r.push(n)}}return r}catch{return[]}}function parseLocalTraceSpan(e,t,n){if(!isRecord(e)||e.traceId!==t||typeof e.spanId!=`string`||!/^[0-9a-f]{16}$/u.test(e.spanId)||typeof e.name!=`string`)return;let r=parseNanos(e.startTimeUnixNano),i=parseNanos(e.endTimeUnixNano);if(!(r===void 0||i===void 0||i<r))return{attributes:parseAttributes(e.attributes),endTimeNs:i,name:e.name,parentSpanId:typeof e.parentSpanId==`string`&&/^[0-9a-f]{16}$/u.test(e.parentSpanId)?e.parentSpanId:void 0,scope:n,spanId:e.spanId,startTimeNs:r,statusCode:parseStatusCode(e.status),traceId:t}}function parseAttributes(e){if(!Array.isArray(e))return{};let t={};for(let n of e){if(!isRecord(n)||typeof n.key!=`string`||!isRecord(n.value))continue;let e=parseAnyValue(n.value);e!==void 0&&(t[n.key]=e)}return t}function parseAnyValue(e){for(let t of[`stringValue`,`boolValue`,`intValue`,`doubleValue`])if(t in e)return e[t];if(isRecord(e.arrayValue)&&Array.isArray(e.arrayValue.values))return e.arrayValue.values.filter(isRecord).map(e=>parseAnyValue(e))}function parseNanos(e){if(!(typeof e!=`string`&&typeof e!=`number`))try{let t=BigInt(e);return t>=0n&&t<=18446744073709551615n?t:void 0}catch{return}}function parseStatusCode(e){return isRecord(e)?typeof e.code==`number`?e.code:e.code===`STATUS_CODE_ERROR`?2:0:0}function firstAttribute(e,t){for(let n of e){let e=n[t];if(typeof e==`string`&&e.length>0)return e}}function firstNumberAttribute(e,t){for(let n of e){let e=n[t];if(typeof e==`number`)return e;if(typeof e==`bigint`)return Number(e)}}function distinctAttributes(e,t){let n=new Set;for(let r of e){let e=r[t];typeof e==`string`&&e.length>0&&n.add(e)}return[...n]}function stringSpanAttribute(e,t){let n=e.attributes[t];return typeof n==`string`?n:void 0}function valueSpanAttribute(e,t){let n=e.attributes[t];return typeof n==`string`||typeof n==`number`?n:void 0}function isMissing(e){return e.code===`ENOENT`}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{assembleLocalTrace,compareLocalTraceSpans,describeLocalTraceSpan,listLocalTraceIds,listLocalTraceSegments,listLocalTraces,parseLocalTraceSegment,readLocalTraceActivityMs,readLocalTraceSegment};

package/dist/src/tracing/local-trace-retention.js

@@ -1 +1 @@
-import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{readdir,rm,stat}from"node:fs/promises";import{resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory}from"#tracing/local-trace-span-processor.js";const log=createLogger(`harness.local-trace-retention`),LOCAL_TRACE_QUIESCENCE_MS=300*1e3,LOCAL_TRACE_MAX_AGE_MS=10080*60*1e3,LOCAL_TRACE_MAX_TOTAL_BYTES=512*1024*1024;function resolveLocalTraceRetentionSettings(e=process.env){return{enabled:!isDisabled(e.EVE_TRACES),maxAgeMs:readBound(e,`EVE_TRACES_MAX_AGE_MS`,LOCAL_TRACE_MAX_AGE_MS),maxTotalBytes:readBound(e,`EVE_TRACES_MAX_TOTAL_BYTES`,LOCAL_TRACE_MAX_TOTAL_BYTES),retainCount:readBound(e,`EVE_TRACES_RETAIN_COUNT`,20)}}async function pruneLocalTraceStore(e){let t=e.now??Date.now(),n=clampBound(e.maxAgeMs??LOCAL_TRACE_MAX_AGE_MS),r=clampBound(e.maxTotalBytes??LOCAL_TRACE_MAX_TOTAL_BYTES),a=clampCount(e.retainCount??20),o=await readStoredTraces(e.appRoot,t),s=[...o].sort((e,t)=>t.modifiedAtMs-e.modifiedAtMs),c=new Set(s.slice(0,a===!1?0:a)),l=new Set,u=o.reduce((e,t)=>e+t.byteSize,0),d=0,f=0,p=0;for(let a of s.toReversed()){let o=t-a.modifiedAtMs,s=e.activeTraceIds.has(a.traceId)||c.has(a)||o<=LOCAL_TRACE_QUIESCENCE_MS?void 0:n!==!1&&o>n?`maxAgeMs`:r!==!1&&u>r?`maxTotalBytes`:void 0;if(s===void 0){p+=1;continue}await rm(a.path,{force:!0,recursive:!0}),u-=a.byteSize,d+=a.byteSize,f+=1,l.add(s)}return{reasons:[...l],reclaimedBytes:d,removedTraces:f,retainedTraces:p}}const pruneRequest={input:{activeTraceIds:new Set,appRoot:``},requested:!1,running:void 0};function requestLocalTraceStorePrune(e){pruneRequest.input=e,pruneRequest.requested=!0,pruneRequest.running===void 0&&startPruning()}function startPruning(){pruneRequest.running=(async()=>{for(;pruneRequest.requested;)pruneRequest.requested=!1,report(await pruneLocalTraceStore(pruneRequest.input))})().catch(e=>{log.warn(`local trace retention failed`,{error:formatError(e)})}).finally(()=>{pruneRequest.running=void 0,pruneRequest.requested&&startPruning()})}function report(e){e.removedTraces!==0&&log.info(`pruned local traces`,{reasons:e.reasons.join(`,`),reclaimedBytes:e.reclaimedBytes,removedTraces:e.removedTraces,retainedTraces:e.retainedTraces})}async function readStoredTraces(e,t){let r=resolveLocalTraceSchemaDirectory(e),i=await readDirectoryEntries(r);return i===void 0?[]:(await Promise.all(i.filter(e=>e.isDirectory()).map(async i=>{let a=join(r,i.name),o=resolveLocalTraceSegmentsDirectory(e,i.name);await reapAbandonedTemporaryFiles(o,t);let c=await directoryMtime(o)??await directoryMtime(a);if(c!==void 0)return{byteSize:await directorySize(a),modifiedAtMs:c,path:a,traceId:i.name}}))).filter(e=>e!==void 0)}async function reapAbandonedTemporaryFiles(e,t){let r=await readDirectoryEntries(e);if(r!==void 0)for(let o of r){if(!o.isFile()||!o.name.includes(`.tmp-`))continue;let r=join(e,o.name);try{if(t-(await stat(r)).mtimeMs<=LOCAL_TRACE_QUIESCENCE_MS)continue;await rm(r,{force:!0})}catch{}}}async function directoryMtime(e){try{return(await stat(e)).mtimeMs}catch{return}}async function directorySize(e){let t=await readDirectoryEntries(e);if(t===void 0)return 0;let r=0;for(let i of t){let t=join(e,i.name);if(i.isDirectory()){r+=await directorySize(t);continue}try{r+=(await stat(t)).size}catch{}}return r}async function readDirectoryEntries(e){try{return await readdir(e,{withFileTypes:!0})}catch(e){if(e instanceof Error&&`code`in e&&(e.code===`ENOENT`||e.code===`ENOTDIR`))return;throw e}}function isDisabled(e){if(e===void 0)return!1;let t=e.trim().toLowerCase();return t===`off`||t===`false`||t===`0`}function readBound(e,t,n){let r=e[t];if(r===void 0)return n;let i=r.trim().toLowerCase();if(i===`off`||i===`false`)return!1;let a=Number(i);return!Number.isFinite(a)||a<0?(log.warn(`ignoring invalid local trace retention value`,{fallback:n,name:t,value:r}),n):a}function clampBound(e){return e!==!1&&Math.max(0,e)}function clampCount(e){return e!==!1&&Math.max(0,Math.trunc(e))}export{pruneLocalTraceStore,requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings};
+import{readdir,rm,stat}from"node:fs/promises";import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory}from"#tracing/local-trace-span-processor.js";const log=createLogger(`harness.local-trace-retention`),LOCAL_TRACE_QUIESCENCE_MS=300*1e3,LOCAL_TRACE_MAX_AGE_MS=10080*60*1e3,LOCAL_TRACE_MAX_TOTAL_BYTES=512*1024*1024;function resolveLocalTraceRetentionSettings(e=process.env){return{enabled:!isDisabled(e.EVE_TRACES),maxAgeMs:readBound(e,`EVE_TRACES_MAX_AGE_MS`,LOCAL_TRACE_MAX_AGE_MS),maxTotalBytes:readBound(e,`EVE_TRACES_MAX_TOTAL_BYTES`,LOCAL_TRACE_MAX_TOTAL_BYTES),retainCount:readBound(e,`EVE_TRACES_RETAIN_COUNT`,20)}}async function pruneLocalTraceStore(e){let n=e.now??Date.now(),r=clampBound(e.maxAgeMs??LOCAL_TRACE_MAX_AGE_MS),i=clampBound(e.maxTotalBytes??LOCAL_TRACE_MAX_TOTAL_BYTES),a=clampCount(e.retainCount??20),o=await readStoredTraces(e.appRoot,n),s=[...o].sort((e,t)=>t.modifiedAtMs-e.modifiedAtMs),c=new Set(s.slice(0,a===!1?0:a)),l=new Set,u=o.reduce((e,t)=>e+t.byteSize,0),d=0,f=0,p=0;for(let a of s.toReversed()){let o=n-a.modifiedAtMs,s=e.activeTraceIds.has(a.traceId)||c.has(a)||o<=LOCAL_TRACE_QUIESCENCE_MS?void 0:r!==!1&&o>r?`maxAgeMs`:i!==!1&&u>i?`maxTotalBytes`:void 0;if(s===void 0){p+=1;continue}await rm(a.path,{force:!0,recursive:!0}),u-=a.byteSize,d+=a.byteSize,f+=1,l.add(s)}return{reasons:[...l],reclaimedBytes:d,removedTraces:f,retainedTraces:p}}const pruneRequest={input:{activeTraceIds:new Set,appRoot:``},requested:!1,running:void 0};function requestLocalTraceStorePrune(e){pruneRequest.input=e,pruneRequest.requested=!0,pruneRequest.running===void 0&&startPruning()}function startPruning(){pruneRequest.running=(async()=>{for(;pruneRequest.requested;)pruneRequest.requested=!1,report(await pruneLocalTraceStore(pruneRequest.input))})().catch(e=>{log.warn(`local trace retention failed`,{error:formatError(e)})}).finally(()=>{pruneRequest.running=void 0,pruneRequest.requested&&startPruning()})}function report(e){e.removedTraces!==0&&log.info(`pruned local traces`,{reasons:e.reasons.join(`,`),reclaimedBytes:e.reclaimedBytes,removedTraces:e.removedTraces,retainedTraces:e.retainedTraces})}async function readStoredTraces(e,t){let n=resolveLocalTraceSchemaDirectory(e),r=await readDirectoryEntries(n);return r===void 0?[]:(await Promise.all(r.filter(e=>e.isDirectory()).map(async r=>{let i=join(n,r.name),o=resolveLocalTraceSegmentsDirectory(e,r.name);await reapAbandonedTemporaryFiles(o,t);let c=await directoryMtime(o)??await directoryMtime(i);if(c!==void 0)return{byteSize:await directorySize(i),modifiedAtMs:c,path:i,traceId:r.name}}))).filter(e=>e!==void 0)}async function reapAbandonedTemporaryFiles(e,r){let i=await readDirectoryEntries(e);if(i!==void 0)for(let o of i){if(!o.isFile()||!o.name.includes(`.tmp-`))continue;let i=join(e,o.name);try{if(r-(await stat(i)).mtimeMs<=LOCAL_TRACE_QUIESCENCE_MS)continue;await rm(i,{force:!0})}catch{}}}async function directoryMtime(e){try{return(await stat(e)).mtimeMs}catch{return}}async function directorySize(e){let t=await readDirectoryEntries(e);if(t===void 0)return 0;let r=0;for(let i of t){let t=join(e,i.name);if(i.isDirectory()){r+=await directorySize(t);continue}try{r+=(await stat(t)).size}catch{}}return r}async function readDirectoryEntries(t){try{return await readdir(t,{withFileTypes:!0})}catch(e){if(e instanceof Error&&`code`in e&&(e.code===`ENOENT`||e.code===`ENOTDIR`))return;throw e}}function isDisabled(e){if(e===void 0)return!1;let t=e.trim().toLowerCase();return t===`off`||t===`false`||t===`0`}function readBound(e,t,n){let r=e[t];if(r===void 0)return n;let i=r.trim().toLowerCase();if(i===`off`||i===`false`)return!1;let a=Number(i);return!Number.isFinite(a)||a<0?(log.warn(`ignoring invalid local trace retention value`,{fallback:n,name:t,value:r}),n):a}function clampBound(e){return e!==!1&&Math.max(0,e)}function clampCount(e){return e!==!1&&Math.max(0,Math.trunc(e))}export{pruneLocalTraceStore,requestLocalTraceStorePrune,resolveLocalTraceRetentionSettings};

package/dist/src/tracing/local-trace-span-processor.js

@@ -1 +1 @@
-import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{mkdir}from"node:fs/promises";import{atomicWriteFile}from"#shared/atomic-write-file.js";import{JsonTraceSerializer}from"#compiled/@opentelemetry/otlp-transformer/index.js";const log=createLogger(`harness.local-trace-span-processor`);function resolveLocalTraceStoreDirectory(e){return join(e,`.eve`,`traces`)}function resolveLocalTraceSchemaDirectory(e){return join(resolveLocalTraceStoreDirectory(e),`v1`)}function resolveLocalTraceSegmentsDirectory(e,t){return join(resolveLocalTraceSchemaDirectory(e),t,`segments`)}var LocalTraceSpanProcessor=class{#e;#t=Promise.resolve();#n=!1;constructor(e){this.#e=e}forceFlush(){return this.#t}onStart(){}onEnd(e){if(!isReadableSpan(e))return;let{spanId:n,traceId:r}=e.spanContext();if(!isHexId(r,32)||!isHexId(n,16))return;let i=JsonTraceSerializer.serializeRequest([e]);i!==void 0&&(this.#t=this.#t.then(async()=>{let e=resolveLocalTraceSegmentsDirectory(this.#e,r);await mkdir(e,{recursive:!0}),await atomicWriteFile(join(e,`${n}.otlp.json`),i)}).catch(e=>{this.#n||(this.#n=!0,log.warn(`local trace persistence failed`,{error:formatError(e)}))}))}shutdown(){return this.forceFlush()}};function isReadableSpan(e){return typeof e==`object`&&!!e&&`attributes`in e&&`spanContext`in e&&typeof e.spanContext==`function`}function isHexId(e,t){return e.length===t&&/^[0-9a-f]+$/u.test(e)}export{LocalTraceSpanProcessor,resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory};
+import{mkdir}from"node:fs/promises";import{createLogger,formatError}from"#internal/logging.js";import{join}from"node:path";import{atomicWriteFile}from"#shared/atomic-write-file.js";import{JsonTraceSerializer}from"#compiled/@opentelemetry/otlp-transformer/index.js";const log=createLogger(`harness.local-trace-span-processor`);function resolveLocalTraceStoreDirectory(e){return join(e,`.eve`,`traces`)}function resolveLocalTraceSchemaDirectory(e){return join(resolveLocalTraceStoreDirectory(e),`v1`)}function resolveLocalTraceSegmentsDirectory(e,t){return join(resolveLocalTraceSchemaDirectory(e),t,`segments`)}var LocalTraceSpanProcessor=class{#e;#t=Promise.resolve();#n=!1;constructor(e){this.#e=e}forceFlush(){return this.#t}onStart(){}onEnd(t){if(!isReadableSpan(t))return;let{spanId:n,traceId:r}=t.spanContext();if(!isHexId(r,32)||!isHexId(n,16))return;let i=JsonTraceSerializer.serializeRequest([t]);i!==void 0&&(this.#t=this.#t.then(async()=>{let t=resolveLocalTraceSegmentsDirectory(this.#e,r);await mkdir(t,{recursive:!0}),await atomicWriteFile(join(t,`${n}.otlp.json`),i)}).catch(e=>{this.#n||(this.#n=!0,log.warn(`local trace persistence failed`,{error:formatError(e)}))}))}shutdown(){return this.forceFlush()}};function isReadableSpan(e){return typeof e==`object`&&!!e&&`attributes`in e&&`spanContext`in e&&typeof e.spanContext==`function`}function isHexId(e,t){return e.length===t&&/^[0-9a-f]+$/u.test(e)}export{LocalTraceSpanProcessor,resolveLocalTraceSchemaDirectory,resolveLocalTraceSegmentsDirectory};

package/dist/src/vue/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-CyDt3Lny.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-k-XHfrJT.js";
 
 export { defaultMessageReducer, useEveAgent };

package/dist/src/vue/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-CyDt3Lny.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-k-XHfrJT.js";
 
 export { useEveAgent };

package/docs/channels/custom.mdx

@@ -48,6 +48,8 @@ Declare routes with the `POST()` and `GET()` helpers. Each route handler receive
 
 - `send(message, { auth, continuationToken, state?, title? })` starts or resumes a session. `title` overrides the new workflow session's display title without changing the model message. Returns a `Session`.
 - `cancel({ continuationToken, turnId? })` requests cancellation of the active turn on the session that owns the token. See [Cancel a turn](#cancel-a-turn).
+- `clear({ continuationToken })` removes the model-message history while preserving the session and its durable resources. See [Clear session context](#clear-session-context).
+- `compact({ continuationToken })` queues context compaction for the session that owns the token without sending model input. See [Compact a session](#compact-a-session).
 - `reset({ continuationToken, reason? })` retires the session that owns the token so the next `send()` starts a fresh session. See [Reset a session](#reset-a-session).
 - `getSession(sessionId)` looks up an existing session. The returned `Session` exposes `getEventStream({ startIndex? })` for streaming, `getStreamTailIndex()` for resolving the durable tail when a route wants to serve bounded reads, and `cancel({ turnId? })` for session-id-addressed cancellation.
 - `receive(channel, ...)` hands inbound work to a different channel for cross-channel hand-off.
@@ -86,6 +88,44 @@ Semantics:
 
 When you already hold a `Session` — returned by `send()` or `getSession(sessionId)` — call `session.cancel({ turnId? })` to request the same cancellation addressed by session id.
 
+## Clear session context
+
+Call `clear` with the channel-local continuation token to remove a session's durable model-message history without replacing the session:
+
+```ts
+import { defineChannel, POST } from "eve/channels";
+
+export default defineChannel({
+  routes: [
+    POST("/threads/:threadId/clear", async (_req, { clear, params }) => {
+      const result = await clear({ continuationToken: params.threadId });
+      return Response.json(result);
+    }),
+  ],
+});
+```
+
+`"accepted"` means the clear was queued. The stream emits `context.cleared` followed by `session.waiting`, after which the next ordinary message resumes the same session with no prior model messages. The system prompt, configured tools and skills, durable state, limits, continuation-token ownership, and session-scoped sandbox remain. `"no_active_session"` means the token has no current owner.
+
+## Compact a session
+
+Call `compact` with the channel-local continuation token to summarize durable conversation history without delivering a command to the model:
+
+```ts
+import { defineChannel, POST } from "eve/channels";
+
+export default defineChannel({
+  routes: [
+    POST("/threads/:threadId/compact", async (_req, { compact, params }) => {
+      const result = await compact({ continuationToken: params.threadId });
+      return Response.json(result);
+    }),
+  ],
+});
+```
+
+`"accepted"` means the durable session queued the operation. A successful compaction emits `compaction.requested` followed by `compaction.completed`, then the operation returns through `session.waiting`. If summarization fails, the stream returns through `session.waiting` without `compaction.completed` and preserves the previous history. If a turn is active, eve runs the compaction after that turn settles; it does not cancel the turn. `"no_active_session"` means the token has no current owner. Both outcomes are successful, and compaction never starts a session or appends a synthetic user message.
+
 ## Reset a session
 
 Identity-addressed channels can consume commands such as `/new` in their route, without sending the command to the model. Call `reset` with the same channel-local continuation token used by `send()`:
@@ -160,7 +200,7 @@ export default defineChannel({
 });
 ```
 
-`WS()` handlers receive the same helpers as HTTP route handlers: `send`, `cancel`, `reset`, `getSession`, `receive`, `params`, `waitUntil`, and `requestIp`. The returned hooks are eve-owned structural types compatible with Nitro/H3 websocket routing, including `upgrade`, `open`, `message`, `close`, and `error`.
+`WS()` handlers receive the same helpers as HTTP route handlers: `send`, `cancel`, `clear`, `compact`, `reset`, `getSession`, `receive`, `params`, `waitUntil`, and `requestIp`. The returned hooks are eve-owned structural types compatible with Nitro/H3 websocket routing, including `upgrade`, `open`, `message`, `close`, and `error`.
 
 ### Node upgrade server escape hatch
 

package/docs/channels/discord.mdx

@@ -4,27 +4,43 @@ description: "Reach your agent from Discord HTTP Interactions, including slash c
 type: integration
 ---
 
-The Discord channel wires your agent into Discord's HTTP Interactions, including slash and application commands, message components, and modal submissions. Discord enforces a three-second ACK deadline, so the channel verifies the Ed25519 signature headers, acknowledges the command right away, and runs the eve work in the background. See [Channels](./overview) for the contract this builds on.
+The Discord channel wires your agent into Discord's HTTP Interactions, including slash and application commands, message components, and modal submissions. Discord enforces a three-second ACK deadline, so the channel acknowledges the command right away and runs the eve work in the background. Credentials and inbound request verification run through [Vercel Connect](../guides/auth-and-route-protection), so Discord's bot token stays out of your environment and Connect verifies Discord's signature before forwarding an interaction to eve. See [Channels](./overview) for the contract this builds on.
 
-## Add the channel
+## Set up Discord
 
-```ts title="agent/channels/discord.ts"
-import { discordChannel } from "eve/channels/discord";
+Run the guided setup from your eve project:
 
-export default discordChannel();
+```bash
+pnpm eve add channel/discord
 ```
 
-```bash
-DISCORD_PUBLIC_KEY=...      # verifies X-Signature-Ed25519 + X-Signature-Timestamp
-DISCORD_APPLICATION_ID=...  # edits the deferred response and sends followups
-DISCORD_BOT_TOKEN=...       # proactive messages + fallback + typing indicators
+The setup guides you through creating a Discord application and bot, then:
+
+- validates the bot token;
+- creates a Vercel Connect client and attaches `/eve/v1/discord` as its trigger destination;
+- registers an application command with a required `message` option;
+- configures the Discord application's Interactions Endpoint URL;
+- scaffolds the channel with Connect-managed credentials; and
+- prints the bot installation URL.
+
+The command defaults to `/ask` with the description **Ask the eve agent**. You can edit both during setup. Discord global commands can take up to an hour to appear after registration.
+
+The generated channel looks like this:
+
+```ts title="agent/channels/discord.ts"
+import { connectDiscordCredentials } from "@vercel/connect/eve";
+import { discordChannel } from "eve/channels/discord";
+
+export default discordChannel({
+  credentials: connectDiscordCredentials("discord/my-agent"),
+});
 ```
 
-To skip env vars, pass the same values through `credentials: { applicationId, botToken, publicKey }`. The route is `POST /eve/v1/discord` by default. Paste that public URL into your Discord application's Interactions Endpoint URL.
+The route is `POST /eve/v1/discord` by default. Connect resolves the application ID and bot token lazily and verifies forwarded interactions with same-project Vercel OIDC.
 
-## Register a command
+### Configure Discord manually
 
-Registering commands is on you, not the channel. Use Discord's API or the Developer Portal. A string option named `message` lines up with eve's default prompt extraction:
+If you do not use the guided Connect setup, register a command with Discord's API or the Developer Portal. A string option named `message` lines up with eve's default prompt extraction:
 
 ```bash
 curl -X PUT "https://discord.com/api/v10/applications/$DISCORD_APPLICATION_ID/commands" \
@@ -33,7 +49,7 @@ curl -X PUT "https://discord.com/api/v10/applications/$DISCORD_APPLICATION_ID/co
     "options":[{"name":"message","description":"What should the agent do?","type":3,"required":true}]}]'
 ```
 
-Use guild commands during development for faster propagation.
+Then configure the public `https://…/eve/v1/discord` route as the application's Interactions Endpoint URL. Pass `credentials: { applicationId, botToken, publicKey }` to `discordChannel`, or set the corresponding `DISCORD_APPLICATION_ID`, `DISCORD_BOT_TOKEN`, and `DISCORD_PUBLIC_KEY` environment variables.
 
 ## How the channel handles messages
 
@@ -74,7 +90,7 @@ HITL renders as Discord components. Confirmations and options become buttons, `d
 
 ### Proactive sessions
 
-Start a session without an inbound interaction through `receive(discord, { message, target, auth })` from a schedule `run` handler, or `args.receive(discord, ...)` from another channel. The proactive target shape is `{ channelId, conversationId?, initialMessage? }`. Either path needs `DISCORD_BOT_TOKEN`.
+Start a session without an inbound interaction through `receive(discord, { message, target, auth })` from a schedule `run` handler, or `args.receive(discord, ...)` from another channel. The proactive target shape is `{ channelId, conversationId?, initialMessage? }`. Either path needs a bot token, supplied by Connect or `DISCORD_BOT_TOKEN`.
 
 ### Attachments
 

package/docs/channels/eve.mdx

@@ -18,13 +18,16 @@ export default eveChannel({
 
 ## Routes
 
-The application exposes a health route plus eve channel routes that inspect the agent, create sessions, send follow-ups, cancel turns, and stream events:
+The application exposes a health route plus eve channel routes that inspect the agent, create sessions, send follow-ups, cancel turns, compact or reset sessions, and stream events:
 
 - `GET /eve/v1/health`
 - `GET /eve/v1/info`
 - `POST /eve/v1/session` (start a session)
 - `POST /eve/v1/session/:sessionId` (send a follow-up)
 - `POST /eve/v1/session/:sessionId/cancel` (cancel the in-flight turn)
+- `POST /eve/v1/session/clear` (clear the continuation owner's model history)
+- `POST /eve/v1/session/compact` (compact the continuation owner's context)
+- `POST /eve/v1/session/reset` (retire the continuation owner)
 - `GET /eve/v1/session/:sessionId/stream` (stream events, NDJSON)
 
 Start a session with a minimal body. The response returns `sessionId` and the `continuationToken` you reuse for follow-ups:
@@ -54,6 +57,28 @@ curl -X POST https://<deployment>/eve/v1/session/ses_01h.../cancel
 
 Cancellation is asynchronous: `"accepted"` means a cancellation hook accepted the request. Confirm the effective outcome on the stream as `turn.cancelled` followed by `session.waiting` — never as a failure. Active local and remote subagents are cancelled recursively before the parent settles; their own streams carry their cancellation boundaries, and cancelled work does not emit `subagent.completed` on the parent. Content emitted before the cancel stays on the event stream, while durable model history keeps only content that had already settled. The session accepts the next message normally. When there is no resumable cancellation target (including an unknown session, a settled turn, or a duplicate cancel), the route responds with `"no_active_turn"` — also a success, so a stop button can fire and forget. A `turnId` naming any other turn is accepted and consumed as a no-op, so a guarded cancel racing a turn boundary cannot stop a turn the caller never saw.
 
+Clear the model-message history of the session that owns a continuation token:
+
+```bash
+curl -X POST https://<deployment>/eve/v1/session/clear \
+  -H "Content-Type: application/json" \
+  -d '{"continuationToken":"eve:7f3c..."}'
+# {"ok":true,"sessionId":"ses_01h...","status":"accepted"}
+```
+
+An accepted clear emits `context.cleared` followed by `session.waiting`. The next message resumes the same session without prior model messages; the system prompt, tools and skills, durable state, limits, and session-scoped sandbox remain.
+
+Compact the session that owns a continuation token without sending a message:
+
+```bash
+curl -X POST https://<deployment>/eve/v1/session/compact \
+  -H "Content-Type: application/json" \
+  -d '{"continuationToken":"eve:7f3c..."}'
+# {"ok":true,"sessionId":"ses_01h...","status":"accepted"}
+```
+
+Compaction is asynchronous. A successful operation emits `compaction.requested` and `compaction.completed`, then returns through `session.waiting`; when a turn is active, the operation waits for it to settle. If summarization fails, the session still returns to `session.waiting` with its previous history. `"no_active_session"` is the successful no-op response when the token has no owner.
+
 See [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming) for the full request and stream flow, including the complete event set.
 
 ## CORS

package/docs/concepts/default-harness.md

@@ -20,6 +20,10 @@ export default defineAgent({
 
 Compaction also preserves the framework's own tool state automatically. It resets read-before-write tracking (so a write afterward re-reads the file whose read evidence was summarized away) and re-injects the active todo list, so the model keeps its task list across the summary. There is no per-tool hook to configure.
 
+Clients and channels can also request compaction between turns. Call `ClientSession.compact()` or a custom route's `compact({ continuationToken })` helper. The request does not append a user message; if a turn is running, eve queues it until that turn settles. A successful manual compaction emits the same `compaction.requested` and `compaction.completed` events as automatic compaction, followed by `session.waiting`.
+
+To discard model-message history instead of summarizing it, call `ClientSession.clear()` or a custom route's `clear({ continuationToken })` helper. Clearing preserves the session identity, system prompt, configured tools and skills, durable state, limits, and sandbox. Its stream boundary is `context.cleared` followed by `session.waiting`.
+
 ## Built-in tools
 
 Built-in tools require no imports. The exact set depends on the agent and session. `agent` is available only in the root session; `load_skill` and `connection_search` appear only when the agent declares the corresponding resources; `ask_question` requires a session that can request user input; and `web_search` requires a supported model provider. The harness advertises only the tools available to the current session.