eve 0.38.0 → 0.38.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # eve
 
+## 0.38.2
+
+### Patch Changes
+
+- 250d67a: Bump `@workflow/*` packages to the latest 5.0.0 betas (`core` beta.42, `errors` beta.17, `world` beta.27, `world-local` beta.36, `world-vercel` beta.38, `world-postgres` beta.34). The development Workflow world now advertises spec version 6 (slot-numbered event ids), matching the updated local world.
+- f9f29d3: Surface AI Gateway model catalog request failures during compilation instead of reporting unavailable models as missing metadata. Models with eve-owned metadata continue to compile without the catalog.
+- 77de320: Let background task children send intermediate progress to their parent with `task_update`, using the existing local and remote child-to-parent transports. Remote task HITL is now presented only by the parent channel, finished agents continue through their original subagent tool with `agentId`, and the redundant `task_send` tool has been removed.
+- 88f6ca9: Configure MCP channel endpoints with `route`, default them to `/eve/v1/mcp`, and derive OAuth protected-resource metadata paths from the MCP resource identifier.
+- fe1ad3b: Search by item name when suggesting registry matches, so path typos such as `channels/slack` can still suggest `channel/slack`.
+
+## 0.38.1
+
+### Patch Changes
+
+- d23467d: Allow extensions to contribute namespaced subagents, including their tools, configuration access, nested subagents, and directory-mount overrides.
+- cb2fa2a: Configure MCP channel endpoints with `route`, default them to `/eve/v1/mcp`, and derive OAuth protected-resource metadata paths from the MCP resource identifier.
+
 ## 0.38.0
 
 ### Minor Changes

package/dist/src/cli/commands/registry.js

@@ -1 +1 @@
-import{hasInteractiveTerminal}from"./preconditions.js";import{serializeHeadlessSetupEvent}from"./setup-headless.js";import{runDeclaredSetups}from"./registry-declared-setups.js";import{runRegistryPackage}from"./registry-package.js";import{eveMetadataFromRegistryItem,parseOfficialRegistrySearchMetadata}from"./registry-metadata.js";import{printRegistrySearchResults,registryViewText}from"./registry-presentation.js";import{addRegistryMappings,readRegistryConfig}from"./registry-project.js";import{errorMessage,resolveRegistryItemForAdd,runRegistryAction,setupReminder,setupResumeCommand}from"./registry-recovery.js";import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{createPrompter}from"#setup/prompter.js";import{WizardCancelledError}from"#setup/step.js";import{addRegistryItems,getRegistryItems,searchRegistries}from"#compiled/shadcn-registry/index.js";import semver from"#compiled/semver/index.js";const defaultAddCommandDependencies={createPrompter,hasInteractiveTerminal,loadSetupCommandRunner:async()=>(await import(`./registry-setup-command.js`)).runRegistrySetupCommand};function resolveOfficialRegistryUrl(e=process.env.EVE_DEV_OFFICIAL_REGISTRY_URL){if(e===void 0)return`https://eve.dev/r`;let t;try{t=new URL(e)}catch{throw Error(`EVE_DEV_OFFICIAL_REGISTRY_URL must be an HTTP(S) URL.`)}if(t.protocol!==`http:`&&t.protocol!==`https:`)throw Error(`EVE_DEV_OFFICIAL_REGISTRY_URL must be an HTTP(S) URL.`);if(t.username!==``||t.password!==``)throw Error(`EVE_DEV_OFFICIAL_REGISTRY_URL must not include credentials.`);if(t.search!==``||t.hash!==``)throw Error(`EVE_DEV_OFFICIAL_REGISTRY_URL must not include a query or fragment.`);return t.pathname=t.pathname.replace(/\/+$/,``),t.toString().replace(/\/$/,``)}const OFFICIAL_REGISTRY=resolveOfficialRegistryUrl(),OFFICIAL_CATALOG=`${OFFICIAL_REGISTRY}/registry.json`,SKILLS_REGISTRY=`@skills`;function isRegistryAddress(e){return e.startsWith(`@`)||/^https?:\/\//.test(e)}function itemAddress(e){return isRegistryAddress(e)?e:`${OFFICIAL_REGISTRY}/${e}.json`}async function installOfficialRegistryItem(e,t,n={}){let r=await readEveRegistryConfig(e);await addRegistryItems([itemAddress(t)],{config:r,cwd:e,overwrite:n.overwrite})}function assertCompatibleEveVersion(e){if(e===void 0)return;let t=resolveInstalledPackageInfo().version;if(semver.validRange(e)===null)throw Error(`Registry item has an invalid eve version requirement: ${e}.`);if(!semver.subset(t,e))throw Error(`This registry item requires eve ${e}, but this project is using eve ${t}. Upgrade eve and run the command again.`)}function isOfficialItemAddress(e){return e.startsWith(`${OFFICIAL_REGISTRY}/`)}function withBuiltInRegistries(e){return{...e,registries:{[SKILLS_REGISTRY]:`https://www.skills.sh/r/{name}?agent=eve`,...e.registries}}}async function readEveRegistryConfig(e){return withBuiltInRegistries(await readRegistryConfig(e))}function configuredRegistrySources(e){return Object.keys(e.registries??{})}function validateRegistrySource(e){if(e!==void 0&&!isRegistryAddress(e))throw Error(`Registry sources must be a namespace or URL: ${e}`)}async function loadOfficialSearchMetadata(){let e=await fetch(OFFICIAL_CATALOG);if(!e.ok)throw Error(`Could not read the eve registry (${e.status}).`);return parseOfficialRegistrySearchMetadata(await e.json())}function searchItemAddress(e){return e.registry===OFFICIAL_CATALOG?e.name:e.addCommandArgument}function enrichSearchItem(e,t){let n=searchItemAddress(e);return{item:e,address:n,...t.get(n)}}function registrySourceLabel(e){return e===OFFICIAL_CATALOG?`eve`:e===SKILLS_REGISTRY?`skills.sh`:e}function searchPresentationSections(e,t,n){return e.flatMap(e=>{let r=t.get(e);return r===void 0?[]:[{label:registrySourceLabel(e),items:r.items.map(e=>enrichSearchItem(e,n)),total:r.pagination.total}]})}async function printAddSuggestions(e,t,n){try{let{resultsBySource:r,sources:i,metadataByAddress:a}=await searchRegistryCatalog(t,{limit:5,query:n}),s=searchPresentationSections(i,r,a);if(s.every(e=>e.items.length===0))return;e.log(`Did you mean?`),printRegistrySearchResults(e,{query:n,sections:s})}catch{}}async function searchRegistryCatalog(e,t){validateRegistrySource(t.source);let n=await readEveRegistryConfig(e),r=t.source?[t.source]:[OFFICIAL_CATALOG,...configuredRegistrySources(n).filter(e=>t.query!==void 0||e!==SKILLS_REGISTRY)],i=await Promise.all(r.map(async e=>{try{return{result:await searchRegistries([e],{config:n,limit:t.limit??100,query:t.query}),source:e}}catch(t){return{error:t,source:e}}})),a=[],o=new Map;for(let e of i)if(`error`in e)a.push({message:errorMessage(e.error),registry:e.source});else{let t=e.result.errors??[];if(a.push(...t),t.length===0){let t=e.result.items.filter(t=>t.registry===e.source);o.set(e.source,{...e.result,items:t,pagination:{...e.result.pagination,total:e.result.items.length===t.length?e.result.pagination.total:0}})}}let s=new Map(a.map(e=>[`${e.registry}\0${e.message}`,e])),c=o.has(OFFICIAL_CATALOG)?await loadOfficialSearchMetadata():new Map,l=o.get(OFFICIAL_CATALOG);l!==void 0&&l.items.sort((e,t)=>{let rank=e=>c.get(searchItemAddress(e))?.implementation===`native`?0:1;return rank(e)-rank(t)});let d=[...o.values()];return{config:n,result:{items:d.flatMap(e=>e.items),pagination:{hasMore:d.some(e=>e.pagination.hasMore),limit:t.limit??100,offset:0,total:d.reduce((e,t)=>e+t.pagination.total,0)},...s.size>0?{errors:[...s.values()]}:{}},resultsBySource:o,sources:r,metadataByAddress:c}}function registryManifestTitle(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=e.title;return typeof t==`string`?t:void 0}async function browseRegistryCatalog(e,t={}){let{config:n,result:r}=await searchRegistryCatalog(e,t),i=await Promise.all(r.items.map(async e=>{let[t]=await getRegistryItems([e.addCommandArgument],{config:n});return t}));return{items:r.items.map((e,t)=>{let n={address:e.registry===OFFICIAL_CATALOG?e.name:e.addCommandArgument,name:e.name,source:e.registry===OFFICIAL_CATALOG?`Vercel`:e.registry},r=registryManifestTitle(i[t]);return r!==void 0&&(n.title=r),e.type!==void 0&&(n.type=e.type),e.description!==void 0&&(n.description=e.description),n}),total:r.pagination.total,errors:r.errors??[]}}async function browseRegistryItems(e,t,n,r,i={}){let{result:a,resultsBySource:s,sources:c,metadataByAddress:l}=await searchRegistryCatalog(t,{limit:i.limit,query:n,source:r}),u=a.errors??[];if(i.json||s.size>0){let t=a.items.map(e=>({...e,...l.get(searchItemAddress(e))})),r={query:n,sections:searchPresentationSections(c,s,l)};i.json&&(r.json={...a,items:t}),printRegistrySearchResults(e,r)}for(let t of u)e.error(`${t.registry}: ${t.message}`);u.length>0&&(process.exitCode=1)}async function getRegistryItemManifest(e,t){let n=await readEveRegistryConfig(e),r=await getRegistryItems([itemAddress(t)],{config:n});return r.length===1?r[0]:r}async function installRegistryItem(e,t,n={},r=defaultAddCommandDependencies){let i,a=[],o={error:e=>{i=e},log:e=>a.push(e)},s=process.exitCode,c=await runAddCommand(o,e,t,{...n,yes:n.prompter===void 0||n.yes,setupAuthorized:n.prompter!==void 0},r);if(process.exitCode=s,i!==void 0)throw Error(i);let l={output:a};return c!==void 0&&(l.setup=c),l}async function runAddCommand(e,a,o,s,c=defaultAddCommandDependencies){return runRegistryAction(e,a,async()=>{let l=await readEveRegistryConfig(a),u=itemAddress(o);if(s.skipInstall===!0){if(s.overwrite===!0)throw Error(`--overwrite cannot be used with --skip-install.`);if(s.skipSetup===!0)throw Error(`--skip-install cannot be used with --skip-setup.`);if(!isOfficialItemAddress(u))throw Error(`Setup flows are currently supported only for official eve registry items.`)}let f=await resolveRegistryItemForAdd(e,async()=>(await getRegistryItems([u],{config:l}))[0],()=>printAddSuggestions(e,a,o));if(!f.found)return;let p=f.item,m=isOfficialItemAddress(u)?eveMetadataFromRegistryItem(p):void 0;if(assertCompatibleEveVersion(m?.requires),m?.components!==void 0){if(!isOfficialItemAddress(u))throw Error(`Registry packages require the official eve registry.`);let t=await runRegistryPackage({logger:e,appRoot:a,item:o,components:m.components,config:l,options:s,dependencies:c,operations:{itemAddress,metadata:eveMetadataFromRegistryItem,assertCompatibleVersion:assertCompatibleEveVersion,runSetups:({item:t,setups:r,prompter:i})=>runDeclaredSetups({logger:e,appRoot:a,item:t,setups:r,options:{yes:s.yes,nonInteractive:s.nonInteractive,answers:s.answers,prompter:i,signal:s.signal},dependencies:c,cancelledReminder:setupReminder(t,`cancelled`),resumeCommand:setupResumeCommand(t)}),setupReminder:e=>setupReminder(e,`skipped`)}});return t===!1?void 0:t}if(s.skipInstall===!0){if(m?.setup===void 0)throw Error(`Registry item "${o}" does not declare a setup flow.`);let t=await runDeclaredSetups({logger:e,appRoot:a,item:o,setups:m.setup,options:s,dependencies:c,cancelledReminder:setupReminder(o,`cancelled`),resumeCommand:setupResumeCommand(o)});return t===!1?void 0:t}if(await addRegistryItems([u],{config:l,cwd:a,overwrite:s.overwrite,silent:s.silent}),m?.setup===void 0)return;let h=c.hasInteractiveTerminal?.()??defaultAddCommandDependencies.hasInteractiveTerminal();if(s.nonInteractive&&e.log(serializeHeadlessSetupEvent({version:1,type:`progress`,message:s.skipInstall?`Setup ${o}`:`Installed ${o}`})),s.skipSetup===!0||!s.nonInteractive&&!s.yes&&!h&&s.setupAuthorized!==!0){e.log(setupReminder(o,`skipped`));return}if(!s.nonInteractive&&!s.yes&&s.setupAuthorized!==!0)try{if(await(s.prompter??c.createPrompter?.()??defaultAddCommandDependencies.createPrompter()).select({message:`Set up ${o} now?`,initialValue:`yes`,options:[{value:`yes`,label:`Yes`},{value:`no`,label:`No`}]})===`no`){e.log(setupReminder(o,`skipped`));return}}catch(t){if(!(t instanceof WizardCancelledError))throw t;e.log(setupReminder(o,`cancelled`));return}let g=await runDeclaredSetups({logger:e,appRoot:a,item:o,setups:m.setup,options:s,dependencies:c,cancelledReminder:setupReminder(o,`cancelled`),resumeCommand:setupResumeCommand(o)});return g!==!1&&s.nonInteractive&&e.log(serializeHeadlessSetupEvent({version:1,type:`completed`,item:o,completedItems:[o],...g.deploymentRequired===!0?{deploymentRequired:!0,next:{command:`eve`,args:[`deploy`]}}:{}})),g===!1?void 0:g})}async function runRegistryAddCommand(e,t,n){await runRegistryAction(e,t,async()=>{let r=await addRegistryMappings(t,n);for(let t of r.skippedBuiltIn)e.log(`Skipped ${t} because it is built in.`);for(let t of r.skippedExisting)e.log(`Skipped ${t} because it is already configured.`);r.added.length>0&&e.log(`Added ${r.added.join(`, `)} to package.json.`)})}async function runRegistryListCommand(e,t,n,r={}){await runRegistryAction(e,t,()=>browseRegistryItems(e,t,void 0,n,r))}async function runRegistrySearchCommand(e,t,n,r,i={}){await runRegistryAction(e,t,()=>browseRegistryItems(e,t,n,r,{...i,limit:i.limit??10}))}async function runRegistryViewCommand(e,t,n,r={}){await runRegistryAction(e,t,async()=>{let i=await readEveRegistryConfig(t),a=await getRegistryItems([itemAddress(n)],{config:i}),o=a.length===1?a[0]:a;e.log(r.json?JSON.stringify(o,null,2):registryViewText(n,o))})}export{browseRegistryCatalog,getRegistryItemManifest,installOfficialRegistryItem,installRegistryItem,resolveOfficialRegistryUrl,runAddCommand,runRegistryAddCommand,runRegistryListCommand,runRegistrySearchCommand,runRegistryViewCommand};
+import{hasInteractiveTerminal}from"./preconditions.js";import{serializeHeadlessSetupEvent}from"./setup-headless.js";import{runDeclaredSetups}from"./registry-declared-setups.js";import{runRegistryPackage}from"./registry-package.js";import{eveMetadataFromRegistryItem,parseOfficialRegistrySearchMetadata}from"./registry-metadata.js";import{printRegistrySearchResults,registryViewText}from"./registry-presentation.js";import{addRegistryMappings,readRegistryConfig}from"./registry-project.js";import{errorMessage,resolveRegistryItemForAdd,runRegistryAction,setupReminder,setupResumeCommand}from"./registry-recovery.js";import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{createPrompter}from"#setup/prompter.js";import{WizardCancelledError}from"#setup/step.js";import{addRegistryItems,getRegistryItems,searchRegistries}from"#compiled/shadcn-registry/index.js";import semver from"#compiled/semver/index.js";const defaultAddCommandDependencies={createPrompter,hasInteractiveTerminal,loadSetupCommandRunner:async()=>(await import(`./registry-setup-command.js`)).runRegistrySetupCommand};function resolveOfficialRegistryUrl(e=process.env.EVE_DEV_OFFICIAL_REGISTRY_URL){if(e===void 0)return`https://eve.dev/r`;let t;try{t=new URL(e)}catch{throw Error(`EVE_DEV_OFFICIAL_REGISTRY_URL must be an HTTP(S) URL.`)}if(t.protocol!==`http:`&&t.protocol!==`https:`)throw Error(`EVE_DEV_OFFICIAL_REGISTRY_URL must be an HTTP(S) URL.`);if(t.username!==``||t.password!==``)throw Error(`EVE_DEV_OFFICIAL_REGISTRY_URL must not include credentials.`);if(t.search!==``||t.hash!==``)throw Error(`EVE_DEV_OFFICIAL_REGISTRY_URL must not include a query or fragment.`);return t.pathname=t.pathname.replace(/\/+$/,``),t.toString().replace(/\/$/,``)}const OFFICIAL_REGISTRY=resolveOfficialRegistryUrl(),OFFICIAL_CATALOG=`${OFFICIAL_REGISTRY}/registry.json`,SKILLS_REGISTRY=`@skills`;function isRegistryAddress(e){return e.startsWith(`@`)||/^https?:\/\//.test(e)}function itemAddress(e){return isRegistryAddress(e)?e:`${OFFICIAL_REGISTRY}/${e}.json`}async function installOfficialRegistryItem(e,t,n={}){let r=await readEveRegistryConfig(e);await addRegistryItems([itemAddress(t)],{config:r,cwd:e,overwrite:n.overwrite})}function assertCompatibleEveVersion(e){if(e===void 0)return;let t=resolveInstalledPackageInfo().version;if(semver.validRange(e)===null)throw Error(`Registry item has an invalid eve version requirement: ${e}.`);if(!semver.subset(t,e))throw Error(`This registry item requires eve ${e}, but this project is using eve ${t}. Upgrade eve and run the command again.`)}function isOfficialItemAddress(e){return e.startsWith(`${OFFICIAL_REGISTRY}/`)}function withBuiltInRegistries(e){return{...e,registries:{[SKILLS_REGISTRY]:`https://www.skills.sh/r/{name}?agent=eve`,...e.registries}}}async function readEveRegistryConfig(e){return withBuiltInRegistries(await readRegistryConfig(e))}function configuredRegistrySources(e){return Object.keys(e.registries??{})}function validateRegistrySource(e){if(e!==void 0&&!isRegistryAddress(e))throw Error(`Registry sources must be a namespace or URL: ${e}`)}async function loadOfficialSearchMetadata(){let e=await fetch(OFFICIAL_CATALOG);if(!e.ok)throw Error(`Could not read the eve registry (${e.status}).`);return parseOfficialRegistrySearchMetadata(await e.json())}function searchItemAddress(e){return e.registry===OFFICIAL_CATALOG?e.name:e.addCommandArgument}function enrichSearchItem(e,t){let n=searchItemAddress(e);return{item:e,address:n,...t.get(n)}}function registrySourceLabel(e){return e===OFFICIAL_CATALOG?`eve`:e===SKILLS_REGISTRY?`skills.sh`:e}function searchPresentationSections(e,t,n){return e.flatMap(e=>{let r=t.get(e);return r===void 0?[]:[{label:registrySourceLabel(e),items:r.items.map(e=>enrichSearchItem(e,n)),total:r.pagination.total}]})}async function printAddSuggestions(e,t,n){try{let r=n.split(`/`).at(-1)||n,{resultsBySource:i,sources:a,metadataByAddress:s}=await searchRegistryCatalog(t,{limit:5,query:r}),c=searchPresentationSections(a,i,s);if(c.every(e=>e.items.length===0))return;e.log(`Did you mean?`),printRegistrySearchResults(e,{query:r,sections:c})}catch{}}async function searchRegistryCatalog(e,t){validateRegistrySource(t.source);let n=await readEveRegistryConfig(e),r=t.source?[t.source]:[OFFICIAL_CATALOG,...configuredRegistrySources(n).filter(e=>t.query!==void 0||e!==SKILLS_REGISTRY)],i=await Promise.all(r.map(async e=>{try{return{result:await searchRegistries([e],{config:n,limit:t.limit??100,query:t.query}),source:e}}catch(t){return{error:t,source:e}}})),a=[],o=new Map;for(let e of i)if(`error`in e)a.push({message:errorMessage(e.error),registry:e.source});else{let t=e.result.errors??[];if(a.push(...t),t.length===0){let t=e.result.items.filter(t=>t.registry===e.source);o.set(e.source,{...e.result,items:t,pagination:{...e.result.pagination,total:e.result.items.length===t.length?e.result.pagination.total:0}})}}let s=new Map(a.map(e=>[`${e.registry}\0${e.message}`,e])),c=o.has(OFFICIAL_CATALOG)?await loadOfficialSearchMetadata():new Map,l=o.get(OFFICIAL_CATALOG);l!==void 0&&l.items.sort((e,t)=>{let rank=e=>c.get(searchItemAddress(e))?.implementation===`native`?0:1;return rank(e)-rank(t)});let d=[...o.values()];return{config:n,result:{items:d.flatMap(e=>e.items),pagination:{hasMore:d.some(e=>e.pagination.hasMore),limit:t.limit??100,offset:0,total:d.reduce((e,t)=>e+t.pagination.total,0)},...s.size>0?{errors:[...s.values()]}:{}},resultsBySource:o,sources:r,metadataByAddress:c}}function registryManifestTitle(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=e.title;return typeof t==`string`?t:void 0}async function browseRegistryCatalog(e,t={}){let{config:n,result:r}=await searchRegistryCatalog(e,t),i=await Promise.all(r.items.map(async e=>{let[t]=await getRegistryItems([e.addCommandArgument],{config:n});return t}));return{items:r.items.map((e,t)=>{let n={address:e.registry===OFFICIAL_CATALOG?e.name:e.addCommandArgument,name:e.name,source:e.registry===OFFICIAL_CATALOG?`Vercel`:e.registry},r=registryManifestTitle(i[t]);return r!==void 0&&(n.title=r),e.type!==void 0&&(n.type=e.type),e.description!==void 0&&(n.description=e.description),n}),total:r.pagination.total,errors:r.errors??[]}}async function browseRegistryItems(e,t,n,r,i={}){let{result:a,resultsBySource:s,sources:c,metadataByAddress:l}=await searchRegistryCatalog(t,{limit:i.limit,query:n,source:r}),u=a.errors??[];if(i.json||s.size>0){let t=a.items.map(e=>({...e,...l.get(searchItemAddress(e))})),r={query:n,sections:searchPresentationSections(c,s,l)};i.json&&(r.json={...a,items:t}),printRegistrySearchResults(e,r)}for(let t of u)e.error(`${t.registry}: ${t.message}`);u.length>0&&(process.exitCode=1)}async function getRegistryItemManifest(e,t){let n=await readEveRegistryConfig(e),r=await getRegistryItems([itemAddress(t)],{config:n});return r.length===1?r[0]:r}async function installRegistryItem(e,t,n={},r=defaultAddCommandDependencies){let i,a=[],o={error:e=>{i=e},log:e=>a.push(e)},s=process.exitCode,c=await runAddCommand(o,e,t,{...n,yes:n.prompter===void 0||n.yes,setupAuthorized:n.prompter!==void 0},r);if(process.exitCode=s,i!==void 0)throw Error(i);let l={output:a};return c!==void 0&&(l.setup=c),l}async function runAddCommand(e,a,o,s,c=defaultAddCommandDependencies){return runRegistryAction(e,a,async()=>{let l=await readEveRegistryConfig(a),u=itemAddress(o);if(s.skipInstall===!0){if(s.overwrite===!0)throw Error(`--overwrite cannot be used with --skip-install.`);if(s.skipSetup===!0)throw Error(`--skip-install cannot be used with --skip-setup.`);if(!isOfficialItemAddress(u))throw Error(`Setup flows are currently supported only for official eve registry items.`)}let f=await resolveRegistryItemForAdd(e,async()=>(await getRegistryItems([u],{config:l}))[0],()=>printAddSuggestions(e,a,o));if(!f.found)return;let p=f.item,m=isOfficialItemAddress(u)?eveMetadataFromRegistryItem(p):void 0;if(assertCompatibleEveVersion(m?.requires),m?.components!==void 0){if(!isOfficialItemAddress(u))throw Error(`Registry packages require the official eve registry.`);let t=await runRegistryPackage({logger:e,appRoot:a,item:o,components:m.components,config:l,options:s,dependencies:c,operations:{itemAddress,metadata:eveMetadataFromRegistryItem,assertCompatibleVersion:assertCompatibleEveVersion,runSetups:({item:t,setups:r,prompter:i})=>runDeclaredSetups({logger:e,appRoot:a,item:t,setups:r,options:{yes:s.yes,nonInteractive:s.nonInteractive,answers:s.answers,prompter:i,signal:s.signal},dependencies:c,cancelledReminder:setupReminder(t,`cancelled`),resumeCommand:setupResumeCommand(t)}),setupReminder:e=>setupReminder(e,`skipped`)}});return t===!1?void 0:t}if(s.skipInstall===!0){if(m?.setup===void 0)throw Error(`Registry item "${o}" does not declare a setup flow.`);let t=await runDeclaredSetups({logger:e,appRoot:a,item:o,setups:m.setup,options:s,dependencies:c,cancelledReminder:setupReminder(o,`cancelled`),resumeCommand:setupResumeCommand(o)});return t===!1?void 0:t}if(await addRegistryItems([u],{config:l,cwd:a,overwrite:s.overwrite,silent:s.silent}),m?.setup===void 0)return;let h=c.hasInteractiveTerminal?.()??defaultAddCommandDependencies.hasInteractiveTerminal();if(s.nonInteractive&&e.log(serializeHeadlessSetupEvent({version:1,type:`progress`,message:s.skipInstall?`Setup ${o}`:`Installed ${o}`})),s.skipSetup===!0||!s.nonInteractive&&!s.yes&&!h&&s.setupAuthorized!==!0){e.log(setupReminder(o,`skipped`));return}if(!s.nonInteractive&&!s.yes&&s.setupAuthorized!==!0)try{if(await(s.prompter??c.createPrompter?.()??defaultAddCommandDependencies.createPrompter()).select({message:`Set up ${o} now?`,initialValue:`yes`,options:[{value:`yes`,label:`Yes`},{value:`no`,label:`No`}]})===`no`){e.log(setupReminder(o,`skipped`));return}}catch(t){if(!(t instanceof WizardCancelledError))throw t;e.log(setupReminder(o,`cancelled`));return}let g=await runDeclaredSetups({logger:e,appRoot:a,item:o,setups:m.setup,options:s,dependencies:c,cancelledReminder:setupReminder(o,`cancelled`),resumeCommand:setupResumeCommand(o)});return g!==!1&&s.nonInteractive&&e.log(serializeHeadlessSetupEvent({version:1,type:`completed`,item:o,completedItems:[o],...g.deploymentRequired===!0?{deploymentRequired:!0,next:{command:`eve`,args:[`deploy`]}}:{}})),g===!1?void 0:g})}async function runRegistryAddCommand(e,t,n){await runRegistryAction(e,t,async()=>{let r=await addRegistryMappings(t,n);for(let t of r.skippedBuiltIn)e.log(`Skipped ${t} because it is built in.`);for(let t of r.skippedExisting)e.log(`Skipped ${t} because it is already configured.`);r.added.length>0&&e.log(`Added ${r.added.join(`, `)} to package.json.`)})}async function runRegistryListCommand(e,t,n,r={}){await runRegistryAction(e,t,()=>browseRegistryItems(e,t,void 0,n,r))}async function runRegistrySearchCommand(e,t,n,r,i={}){await runRegistryAction(e,t,()=>browseRegistryItems(e,t,n,r,{...i,limit:i.limit??10}))}async function runRegistryViewCommand(e,t,n,r={}){await runRegistryAction(e,t,async()=>{let i=await readEveRegistryConfig(t),a=await getRegistryItems([itemAddress(n)],{config:i}),o=a.length===1?a[0]:a;e.log(r.json?JSON.stringify(o,null,2):registryViewText(n,o))})}export{browseRegistryCatalog,getRegistryItemManifest,installOfficialRegistryItem,installRegistryItem,resolveOfficialRegistryUrl,runAddCommand,runRegistryAddCommand,runRegistryListCommand,runRegistrySearchCommand,runRegistryViewCommand};

package/dist/src/cli/dev/tui/tool-presentation.js

@@ -1 +1 @@
-import{summarizeToolArgs,summarizeToolResult}from"./tool-format.js";import{diffWriteDetail}from"./line-diff.js";import{stripTerminalControls}from"#cli/ui/terminal-text.js";const WRITE_FILE_VERB=`Write`,DELEGATE_VERB=`Delegate`,FINAL_OUTPUT_TITLE=`Return final output`,BUILTIN_TOOL_COPY={agent:{verb:`Delegate`,pastVerb:`Delegated`,argKey:`message`,singularNoun:`task`,pluralNoun:`tasks`},ask_question:{verb:`Ask`,pastVerb:`Asked`,argKey:`prompt`,singularNoun:`question`,pluralNoun:`questions`},bash:{verb:`Run`,pastVerb:`Ran`,argKey:`command`,singularNoun:`command`,pluralNoun:`commands`},connection_search:{verb:`Discover`,pastVerb:`Discovered`,argKey:`keywords`,singularNoun:`tool search`,pluralNoun:`tool searches`},glob:{verb:`Glob`,pastVerb:`Globbed`,argKey:`pattern`,singularNoun:`pattern`,pluralNoun:`patterns`},grep:{verb:`Grep`,pastVerb:`Grepped`,argKey:`pattern`,singularNoun:`pattern`,pluralNoun:`patterns`},load_skill:{verb:`Load`,pastVerb:`Loaded`,argKey:`skill`,singularNoun:`skill`,pluralNoun:`skills`},read_file:{verb:`Read`,pastVerb:`Read`,argKey:`filePath`,singularNoun:`file`,pluralNoun:`files`},task_cancel:{verb:`Cancel`,pastVerb:`Cancelled`,argKey:`taskIds`,extractItem:taskIdsArg,singularNoun:`task`,pluralNoun:`tasks`},task_peek:{verb:`Check`,pastVerb:`Checked`,argKey:`taskIds`,extractItem:taskIdsArg,singularNoun:`task`,pluralNoun:`tasks`},task_send:{verb:`Send`,pastVerb:`Sent`,argKey:`taskId`,singularNoun:`task`,pluralNoun:`tasks`},task_sleep:{verb:`Pause`,pastVerb:`Paused`,argKey:`seconds`,extractItem:sleepSecondsArg,singularNoun:`pause`,pluralNoun:`pauses`},web_fetch:{verb:`Fetch`,pastVerb:`Fetched`,argKey:`url`,singularNoun:`URL`,pluralNoun:`URLs`},web_search:{verb:`Search`,pastVerb:`Searched`,argKey:`query`,extractItem:e=>salientArg(e,`objective`)??salientArg(e,`search_query`)??salientArg(e,`searchQuery`)??webSearchActionArg(e),singularNoun:`query`,pluralNoun:`queries`}};function presentWriteFileTool(a,o,s){let c=readWriteFileInput(a,o);if(c===void 0)return{title:a,subtitle:summarizeToolArgs(o),summarizeResult:summarizeToolResult};let l=diffWriteDetail(s?.previousContent,c.content,s?.existed).map(e=>e.kind===`gap`?e:{...e,text:stripTerminalControls(e.text)});return{title:`${WRITE_FILE_VERB} ${salientLine(c.path)??c.path}`,doneTitle:`Wrote ${salientLine(c.path)??c.path}`,subtitle:``,summarizeResult:()=>void 0,detail:l,keepDetailWhenDone:!0}}function readWriteFileInput(e,t){if(toolBaseName(e)!==`write_file`||typeof t!=`object`||!t||Array.isArray(t))return;let n=t,r=n.filePath,i=n.content;if(!(typeof r!=`string`||r.trim().length===0)&&typeof i==`string`)return{path:r,content:i}}function presentTool(n,r,i){let c=toolBaseName(n);if(c===`todo`)return presentTodoTool(r);if(c===`write_file`)return presentWriteFileTool(n,r,i);if(i?.isSubagent===!0)return{title:`${DELEGATE_VERB} ${c}`,doneTitle:`Delegated ${c}`,subtitle:salientArg(r,`message`)??``,summarizeResult:()=>void 0};if(c===`final_output`)return{title:FINAL_OUTPUT_TITLE,subtitle:``,summarizeResult:()=>void 0};let l=BUILTIN_TOOL_COPY[c];if(l!==void 0){let e=salientArg(r,l.argKey)??l.extractItem?.(r);if(e!==void 0)return{title:`${l.verb} ${e}`,doneTitle:`${l.pastVerb} ${e}`,subtitle:``,summarizeResult:()=>void 0,group:{verb:l.verb,pastVerb:l.pastVerb,singularNoun:l.singularNoun,pluralNoun:l.pluralNoun,item:e}}}return{title:n,subtitle:summarizeToolArgs(r),summarizeResult:summarizeToolResult}}function presentPreparingTool(e,t){let n=toolBaseName(e);if(n===`final_output`)return{title:FINAL_OUTPUT_TITLE,subtitle:``,summarizeResult:()=>void 0};if(t?.isSubagent===!0)return{title:`${DELEGATE_VERB} ${n} …`,subtitle:``,summarizeResult:()=>void 0};let r=n===`write_file`?WRITE_FILE_VERB:BUILTIN_TOOL_COPY[n]?.verb;return{title:r===void 0?e:`${r} …`,subtitle:r===void 0?`preparing…`:``,summarizeResult:()=>void 0}}function isPanelRoutedTool(e){let t=toolBaseName(e);return t===`todo`||t===`ask_question`}function toolBaseName(e){return e.split(/[.:/]/u).at(-1)??e}function presentTodoTool(e){let t=typeof e==`object`&&e&&!Array.isArray(e)?e.todos:void 0;return Array.isArray(t)?{title:`Update todo list`,subtitle:`${t.length} task${t.length===1?``:`s`}`,summarizeResult:()=>void 0}:{title:`Read todo list`,subtitle:``,summarizeResult:()=>void 0}}function webSearchActionArg(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=e.action;if(typeof t!=`object`||!t||Array.isArray(t))return;let n=t,r=n.queries;if(Array.isArray(r)){let e=r.filter(e=>typeof e==`string`).map(salientLine).filter(e=>e!==void 0).join(`, `);if(e.length>0)return e}for(let e of[`query`,`url`,`pattern`]){let t=n[e];if(typeof t==`string`){let e=salientLine(t);if(e!==void 0)return e}}}function taskIdsArg(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=e.taskIds;if(!Array.isArray(t))return;let n=t.filter(e=>typeof e==`string`);if(n.length!==0)return salientLine(n.join(`, `))}function sleepSecondsArg(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=e.seconds;if(!(typeof t!=`number`||!Number.isFinite(t)))return`${String(t)}s`}function salientArg(e,t){if(typeof e!=`object`||!e||Array.isArray(e))return;let n=e[t];if(typeof n==`string`)return salientLine(n)}function salientLine(e){let t=stripTerminalControls(e).split(/\r?\n/u).find(e=>e.trim().length>0)?.trim()??``;return t.length>0?t:void 0}export{isPanelRoutedTool,presentPreparingTool,presentTool,readWriteFileInput,toolBaseName};
+import{summarizeToolArgs,summarizeToolResult}from"./tool-format.js";import{diffWriteDetail}from"./line-diff.js";import{stripTerminalControls}from"#cli/ui/terminal-text.js";const WRITE_FILE_VERB=`Write`,DELEGATE_VERB=`Delegate`,FINAL_OUTPUT_TITLE=`Return final output`,BUILTIN_TOOL_COPY={agent:{verb:`Delegate`,pastVerb:`Delegated`,argKey:`message`,singularNoun:`task`,pluralNoun:`tasks`},ask_question:{verb:`Ask`,pastVerb:`Asked`,argKey:`prompt`,singularNoun:`question`,pluralNoun:`questions`},bash:{verb:`Run`,pastVerb:`Ran`,argKey:`command`,singularNoun:`command`,pluralNoun:`commands`},connection_search:{verb:`Discover`,pastVerb:`Discovered`,argKey:`keywords`,singularNoun:`tool search`,pluralNoun:`tool searches`},glob:{verb:`Glob`,pastVerb:`Globbed`,argKey:`pattern`,singularNoun:`pattern`,pluralNoun:`patterns`},grep:{verb:`Grep`,pastVerb:`Grepped`,argKey:`pattern`,singularNoun:`pattern`,pluralNoun:`patterns`},load_skill:{verb:`Load`,pastVerb:`Loaded`,argKey:`skill`,singularNoun:`skill`,pluralNoun:`skills`},read_file:{verb:`Read`,pastVerb:`Read`,argKey:`filePath`,singularNoun:`file`,pluralNoun:`files`},task_cancel:{verb:`Cancel`,pastVerb:`Cancelled`,argKey:`taskIds`,extractItem:taskIdsArg,singularNoun:`task`,pluralNoun:`tasks`},task_peek:{verb:`Check`,pastVerb:`Checked`,argKey:`taskIds`,extractItem:taskIdsArg,singularNoun:`task`,pluralNoun:`tasks`},task_sleep:{verb:`Pause`,pastVerb:`Paused`,argKey:`seconds`,extractItem:sleepSecondsArg,singularNoun:`pause`,pluralNoun:`pauses`},task_update:{verb:`Update`,pastVerb:`Updated`,argKey:`message`,singularNoun:`parent`,pluralNoun:`parents`},web_fetch:{verb:`Fetch`,pastVerb:`Fetched`,argKey:`url`,singularNoun:`URL`,pluralNoun:`URLs`},web_search:{verb:`Search`,pastVerb:`Searched`,argKey:`query`,extractItem:e=>salientArg(e,`objective`)??salientArg(e,`search_query`)??salientArg(e,`searchQuery`)??webSearchActionArg(e),singularNoun:`query`,pluralNoun:`queries`}};function presentWriteFileTool(a,o,s){let c=readWriteFileInput(a,o);if(c===void 0)return{title:a,subtitle:summarizeToolArgs(o),summarizeResult:summarizeToolResult};let l=diffWriteDetail(s?.previousContent,c.content,s?.existed).map(e=>e.kind===`gap`?e:{...e,text:stripTerminalControls(e.text)});return{title:`${WRITE_FILE_VERB} ${salientLine(c.path)??c.path}`,doneTitle:`Wrote ${salientLine(c.path)??c.path}`,subtitle:``,summarizeResult:()=>void 0,detail:l,keepDetailWhenDone:!0}}function readWriteFileInput(e,t){if(toolBaseName(e)!==`write_file`||typeof t!=`object`||!t||Array.isArray(t))return;let n=t,r=n.filePath,i=n.content;if(!(typeof r!=`string`||r.trim().length===0)&&typeof i==`string`)return{path:r,content:i}}function presentTool(n,r,i){let c=toolBaseName(n);if(c===`todo`)return presentTodoTool(r);if(c===`write_file`)return presentWriteFileTool(n,r,i);if(i?.isSubagent===!0)return{title:`${DELEGATE_VERB} ${c}`,doneTitle:`Delegated ${c}`,subtitle:salientArg(r,`message`)??``,summarizeResult:()=>void 0};if(c===`final_output`)return{title:FINAL_OUTPUT_TITLE,subtitle:``,summarizeResult:()=>void 0};let l=BUILTIN_TOOL_COPY[c];if(l!==void 0){let e=salientArg(r,l.argKey)??l.extractItem?.(r);if(e!==void 0)return{title:`${l.verb} ${e}`,doneTitle:`${l.pastVerb} ${e}`,subtitle:``,summarizeResult:()=>void 0,group:{verb:l.verb,pastVerb:l.pastVerb,singularNoun:l.singularNoun,pluralNoun:l.pluralNoun,item:e}}}return{title:n,subtitle:summarizeToolArgs(r),summarizeResult:summarizeToolResult}}function presentPreparingTool(e,t){let n=toolBaseName(e);if(n===`final_output`)return{title:FINAL_OUTPUT_TITLE,subtitle:``,summarizeResult:()=>void 0};if(t?.isSubagent===!0)return{title:`${DELEGATE_VERB} ${n} …`,subtitle:``,summarizeResult:()=>void 0};let r=n===`write_file`?WRITE_FILE_VERB:BUILTIN_TOOL_COPY[n]?.verb;return{title:r===void 0?e:`${r} …`,subtitle:r===void 0?`preparing…`:``,summarizeResult:()=>void 0}}function isPanelRoutedTool(e){let t=toolBaseName(e);return t===`todo`||t===`ask_question`}function toolBaseName(e){return e.split(/[.:/]/u).at(-1)??e}function presentTodoTool(e){let t=typeof e==`object`&&e&&!Array.isArray(e)?e.todos:void 0;return Array.isArray(t)?{title:`Update todo list`,subtitle:`${t.length} task${t.length===1?``:`s`}`,summarizeResult:()=>void 0}:{title:`Read todo list`,subtitle:``,summarizeResult:()=>void 0}}function webSearchActionArg(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=e.action;if(typeof t!=`object`||!t||Array.isArray(t))return;let n=t,r=n.queries;if(Array.isArray(r)){let e=r.filter(e=>typeof e==`string`).map(salientLine).filter(e=>e!==void 0).join(`, `);if(e.length>0)return e}for(let e of[`query`,`url`,`pattern`]){let t=n[e];if(typeof t==`string`){let e=salientLine(t);if(e!==void 0)return e}}}function taskIdsArg(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=e.taskIds;if(!Array.isArray(t))return;let n=t.filter(e=>typeof e==`string`);if(n.length!==0)return salientLine(n.join(`, `))}function sleepSecondsArg(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=e.seconds;if(!(typeof t!=`number`||!Number.isFinite(t)))return`${String(t)}s`}function salientArg(e,t){if(typeof e!=`object`||!e||Array.isArray(e))return;let n=e[t];if(typeof n==`string`)return salientLine(n)}function salientLine(e){let t=stripTerminalControls(e).split(/\r?\n/u).find(e=>e.trim().length>0)?.trim()??``;return t.length>0?t:void 0}export{isPanelRoutedTool,presentPreparingTool,presentTool,readWriteFileInput,toolBaseName};

package/dist/src/compiled/.vendor-stamp.json

@@ -36,12 +36,12 @@
     "@vercel/otel": "2.1.3",
     "@vercel/sandbox-drives": "2.10.0-beta.0",
     "@vercel/sandbox": "2.8.0",
-    "@workflow/core": "5.0.0-beta.41",
-    "@workflow/errors": "5.0.0-beta.16",
+    "@workflow/core": "5.0.0-beta.42",
+    "@workflow/errors": "5.0.0-beta.17",
     "@workflow/serde": "5.0.0-beta.2",
-    "@workflow/world": "5.0.0-beta.26",
-    "@workflow/world-local": "5.0.0-beta.35",
-    "@workflow/world-vercel": "5.0.0-beta.37",
+    "@workflow/world": "5.0.0-beta.27",
+    "@workflow/world-local": "5.0.0-beta.36",
+    "@workflow/world-vercel": "5.0.0-beta.38",
     "zod": "4.4.3",
     "zod-validation-error": "5.0.0"
   },

package/dist/src/compiled/@workflow/core/events-consumer.d.ts

@@ -45,6 +45,16 @@ export interface EventsConsumerOptions {
      * downstream subscribe() calls have a chance to cancel the check first.
      */
     onUnconsumedEvent: (event: Event) => void;
+    /**
+     * Callback invoked when an event is skipped because it repeats an event
+     * class the walk already consumed for the same entity. `firstEventType` is
+     * the type that recorded the class, which is the one the workflow observed.
+     * Diagnostics only: skipping is a normal outcome, not an error — though a
+     * `firstEventType` differing from `event.eventType` says the two writers
+     * decided the entity's outcome differently, which is worth more than an
+     * info log.
+     */
+    onDuplicateEvent?: (event: Event, firstEventType: Event['eventType']) => void;
     /**
      * Returns the current promise queue. The unconsumed event check is chained
      * onto this queue so it only fires after all pending async work (e.g.,
@@ -87,8 +97,17 @@ export declare class EventsConsumer {
      * rather than parked for a consumer that cannot exist.
      */
     private readonly resolved;
+    /**
+     * `<class>:<correlationId>` for every event class the walk has already
+     * consumed, mapped to the event type that recorded it. The type is kept so a
+     * repeat that decided the same class *differently* (a `step_failed` behind a
+     * `step_completed`) can be reported as more than a re-commit. See
+     * {@link EventsConsumer.firstEventTypeOfClass}.
+     */
+    private readonly seenEventClasses;
     private onConsumedEvent?;
     private onUnconsumedEvent;
+    private onDuplicateEvent?;
     private getPromiseQueue;
     private isDeliveryIdle;
     private pendingUnconsumedCheck;
@@ -153,8 +172,86 @@ export declare class EventsConsumer {
      * replay diverged.
      */
     private park;
+    /**
+     * The key `event`'s class is tracked under, or `undefined` for the event
+     * types that belong to no class (`hook_received`, `hook_conflict`,
+     * `attr_set`, `run_created`) and are therefore never skipped.
+     *
+     * Run events carry no correlation id. They are classes of the run itself, so
+     * they all key off the same bucket.
+     */
+    private eventClassKey;
+    /**
+     * Remembers that `event`'s class is now decided for its entity, if the type
+     * belongs to a class. First writer wins: the recorded type is the one the
+     * workflow observed, and a later repeat is measured against it.
+     */
+    private recordEventClass;
+    /**
+     * The type that already decided `event`'s class for the same entity, or
+     * `undefined` when nothing has: a second `step_created` for one step, a
+     * second terminal outcome, a second `step_started` after the step's result is
+     * already in the log.
+     *
+     * Such an event is committed but inert. Concurrent replays write into one
+     * log without a currency guard, so a replay working from a prefix that
+     * predates another replay's write can commit its own copy of work the log
+     * already records. That copy cannot change what the workflow observed: the
+     * outcome was decided by the first event of the class and every later replay
+     * reads that same event at the same log position, so ignoring the straggler
+     * is deterministic across replays.
+     *
+     * Classes are tracked separately, so passing one does not suppress another.
+     * A step whose result is in the log still reaches its `step_created` and
+     * `step_started` consumers if it has yet to see those classes.
+     *
+     * Consulted only after every registered callback has declined the event, so
+     * it can never take an event a consumer wanted. A retry's `step_started` is
+     * claimed by the step's live consumer and counts as an attempt exactly as
+     * before, and a second `step_created` reaching a step that has not finished
+     * is likewise consumed rather than skipped; only the copies nobody claims are
+     * skipped.
+     *
+     * Unlike the divergence report, this does *not* wait out the deferred window
+     * first, and it does not need to. The window buys time for a consumer that
+     * has yet to register, and no such consumer can want this event: the class
+     * was recorded by a consumption in this same replay, which means the entity's
+     * consumer was registered and took an event of this class, and correlation
+     * ids are minted from a monotonic ULID per body position, so nothing later in
+     * the body registers a second consumer under this id. Waiting would cost
+     * `getDeferredCheckDelayMs()` per straggler per replay for information that
+     * cannot arrive — 0.75% of production runs carry at least one straggler, and
+     * the p99 among those carries 155.
+     *
+     * The invariant to preserve if hook identity ever becomes caller-supplied
+     * (an idempotency key rather than a minted id): two `createHook` calls in one
+     * body could then share a correlation id, and the second consumer's
+     * `hook_created` would be a repeat of a class this replay already recorded.
+     * That would make skipping wrong for `hook_created`, and is the reason the
+     * class map lives next to the event types rather than being inferred.
+     */
+    private firstEventTypeOfClass;
+    /** Steps the walk over a repeat of an already-consumed class. */
+    private skipDuplicateEvent;
     private handleEndOfLog;
     private scheduleUnconsumedCheck;
+    /**
+     * Decide what a still-unconsumed event is, now that the promise queue has
+     * drained and the delivery gate says the VM is not mid-reaction.
+     *
+     * `mayPark` is false only for the end-of-log recheck of an event {@link park}
+     * already holds. Nothing in the first branch applies to one of those: it is
+     * not the event at the cursor, so the identity guard is not meaningful, and
+     * it is parked already.
+     *
+     * A duplicate class never arrives here. {@link consume} steps over one in the
+     * pass that offered it, before this check is ever scheduled, and a class
+     * recorded while the check was in flight can only have been recorded by a
+     * consumption inside {@link consume}, whose next pass re-offers this event
+     * and steps over it there — leaving the identity guard above to drop the
+     * in-flight check.
+     */
+    private resolveUnconsumedEvent;
     /**
      * Run `fn` once no data delivery is in flight, polling the way
      * `scheduleWhenIdle` does: let the promise queue drain, re-check a timer

package/dist/src/compiled/@workflow/core/index.js

@@ -1,2 +1,2 @@
-import{$n as e,F as t,Jn as n,Kn as r,Mn as i,N as a,Qn as o,T as s,Vn as c,Wn as l,X as u,Y as d,Zn as f,er as p,qn as m}from"../../_chunks/workflow/wait-until-CT1ve8qB.js";import{i as h,u as g}from"../../_chunks/workflow/dist-xQXN70ED.js";import{a as _,i as v,r as y,t as b}from"../../_chunks/workflow/attribute-changes-DZtQkszH.js";import"../../_chunks/workflow/dist-CPlyFOVo.js";import{n as x}from"../../_chunks/workflow/resume-hook-CYtSorp6.js";import{t as S}from"../../_chunks/workflow/sleep-C1P0OWBm.js";function C(e){v(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,C)}function w(e){v(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,w)}function T({schema:e}={}){function t(e){v(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await x(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
-`)}`)}return await x(t,r.value)}}}async function E(e,t={}){let n=u.getStore(),r=n?.workflowMetadata?.workflowRunId;if(!r)throw new h(`setAttributes() must be called from a 'use workflow' or 'use step' function. Calling it from plain host code is not supported.`);let i=b(e,t);if(i.length!==0){if(n.runReadyBarrier)try{await n.runReadyBarrier}catch{}await(await l()).events.create(r,{eventType:`attr_set`,specVersion:5,eventData:{changes:i,writer:{type:`step`,stepId:n.stepMetadata.stepId,attempt:n.stepMetadata.attempt},...t.allowReservedAttributes===!0?{allowReservedAttributes:!0}:{}}})}}function D(){let e=u.getStore();return e||y(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,D),e.stepMetadata}function O(){let e=u.getStore();return e||_(`getWorkflowMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-workflow-metadata`,O),e.workflowMetadata}function k(l={}){let h=u.getStore();h||_(`getWritable()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-writable`,k);let{namespace:g}=l,v=h.workflowMetadata.workflowRunId,y=d(v,g);h.writables??=new Map;let b=h.writables,x=b.get(y);if(x)return x.writable;let S=t(a(globalThis,h.ops,v,h.encryptionKey,!0,h.runReadyBarrier),h.encryptionKey),C=new s(v,y,h.runReadyBarrier),w=r();return h.ops.push(w.promise),m(S.readable,C,w).catch(()=>{}),n(S.writable,w),Object.defineProperty(S.writable,f,{value:y,writable:!1}),Object.defineProperty(S.writable,p,{value:v,writable:!1}),h.workflowDeploymentId&&Object.defineProperty(S.writable,o,{value:h.workflowDeploymentId,writable:!1}),i(h.encryptionKey)&&Object.defineProperty(S.writable,e,{value:c(h.encryptionKey.keyPair.publicKey),writable:!1}),b.set(y,{writable:S.writable,state:w}),S.writable}export{h as FatalError,g as RetryableError,C as createHook,w as createWebhook,T as defineHook,D as getStepMetadata,O as getWorkflowMetadata,k as getWritable,E as setAttributes,S as sleep};
+import{E as e,I as t,P as n,X as r,Z as i,ar as a,cr as o,fr as s,hr as c,lr as l,mr as u,nr as d,pr as f,qn as p,sr as m}from"../../_chunks/workflow/wait-until-BPSgt1Wg.js";import{i as h,u as g}from"../../_chunks/workflow/dist-CqvWKNQv.js";import{a as _,i as v,r as y,t as b}from"../../_chunks/workflow/attribute-changes-B8K0pwpH.js";import"../../_chunks/workflow/dist-BRGbNjhD.js";import{n as x}from"../../_chunks/workflow/resume-hook-DO_MuJlY.js";import{t as S}from"../../_chunks/workflow/sleep-7TgF3i-e.js";function C(e){v(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,C)}function w(e){v(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,w)}function T({schema:e}={}){function t(e){v(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await x(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
+`)}`)}return await x(t,r.value)}}}async function E(e,t={}){let n=i.getStore(),r=n?.workflowMetadata?.workflowRunId;if(!r)throw new h(`setAttributes() must be called from a 'use workflow' or 'use step' function. Calling it from plain host code is not supported.`);let o=b(e,t);if(o.length!==0){if(n.runReadyBarrier)try{await n.runReadyBarrier}catch{}await(await a()).events.create(r,{eventType:`attr_set`,specVersion:6,eventData:{changes:o,writer:{type:`step`,stepId:n.stepMetadata.stepId,attempt:n.stepMetadata.attempt},...t.allowReservedAttributes===!0?{allowReservedAttributes:!0}:{}}})}}function D(){let e=i.getStore();return e||y(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,D),e.stepMetadata}function O(){let e=i.getStore();return e||_(`getWorkflowMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-workflow-metadata`,O),e.workflowMetadata}function k(a={}){let h=i.getStore();h||_(`getWritable()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-writable`,k);let{namespace:g}=a,v=h.workflowMetadata.workflowRunId,y=r(v,g);h.writables??=new Map;let b=h.writables,x=b.get(y);if(x)return x.writable;let S=t(n(globalThis,h.ops,v,h.encryptionKey,!0,h.runReadyBarrier),h.encryptionKey),C=new e(v,y,h.runReadyBarrier),w=m();return h.ops.push(w.promise),o(S.readable,C,w).catch(()=>{}),l(S.writable,w),Object.defineProperty(S.writable,s,{value:y,writable:!1}),Object.defineProperty(S.writable,c,{value:v,writable:!1}),h.workflowDeploymentId&&Object.defineProperty(S.writable,f,{value:h.workflowDeploymentId,writable:!1}),p(h.encryptionKey)&&Object.defineProperty(S.writable,u,{value:d(h.encryptionKey.keyPair.publicKey),writable:!1}),b.set(y,{writable:S.writable,state:w}),S.writable}export{h as FatalError,g as RetryableError,C as createHook,w as createWebhook,T as defineHook,D as getStepMetadata,O as getWorkflowMetadata,k as getWritable,E as setAttributes,S as sleep};

package/dist/src/compiled/@workflow/core/private.js

@@ -1 +1 @@
-import{a as e,i as t,n,o as r,r as i,s as a,t as o}from"../../_chunks/workflow/private-UQtz8ZcW.js";export{o as awaitEarlierDeliveries,n as getStepFunction,i as hasParkedCommittedDelivery,t as isDeliveryIdle,e as registerDeliveryBarrier,r as registerStepFunction,a as scheduleWhenIdle};
+import{a as e,i as t,n,o as r,r as i,s as a,t as o}from"../../_chunks/workflow/private-z_2Kcwee.js";export{o as awaitEarlierDeliveries,n as getStepFunction,i as hasParkedCommittedDelivery,t as isDeliveryIdle,e as registerDeliveryBarrier,r as registerStepFunction,a as scheduleWhenIdle};

package/dist/src/compiled/@workflow/core/runtime/constants.d.ts

@@ -85,6 +85,41 @@ export declare const MAX_MAX_INLINE_STEPS = 16;
  * one-time warning so misconfiguration is observable.
  */
 export declare function getMaxInlineSteps(): number;
+/**
+ * Upper bound on the serialized step input that resilient step dispatch will
+ * inline into the queue message's `stepInput`.
+ *
+ * Vercel Queues has no hard message-size cap (bodies above its ~256 KB
+ * inline threshold transparently spill to S3-backed storage), so this bound
+ * is a cost/latency choice, not a rejection guard: the message also carries
+ * the runId, stepId, stepName, and trace carrier alongside CBOR framing
+ * overhead, and staying under the queue's inline threshold keeps step
+ * messages on its fast inline path instead of paying an S3 store+fetch
+ * double-hop for bytes that already live in the event log. Above this size
+ * the dispatch falls back to the sequential path (`step_created` write, then
+ * a payload-less queue message). Matches `MAX_INLINE_RESUME_PAYLOAD_BYTES`
+ * on the resilient hook resume path.
+ */
+export declare const MAX_RESILIENT_STEP_INPUT_BYTES: number;
+/**
+ * Whether resilient step dispatch is enabled: the suspension handler
+ * parallelizes each newly created step's `step_created` event write with its
+ * step-execution queue publish, carrying the serialized step input in the
+ * queue message (`stepInput`) so the consumer can idempotently re-ensure the
+ * event if the direct write failed transiently. Mirrors the resilient start
+ * (`runInput`) and resilient hook resume (`hookInput`) patterns.
+ *
+ * **Off by default.** Enable via `WORKFLOW_RESILIENT_STEP_DISPATCH=1`.
+ *
+ * The queue publish races the create's verdict, and a create can come back
+ * refused — as a duplicate this replay should stop pursuing, or as a stale
+ * write on a World that refuses rather than reports. Either way the message
+ * carrying the payload is already out, so the consumer can materialize a step
+ * whose create was refused, and nothing orders the verdict before the
+ * consumer's redelivery re-ensure. Enabling this trades that window for the
+ * latency the parallel publish saves.
+ */
+export declare function isResilientStepDispatchEnabled(): boolean;
 /**
  * Optional client-side override for the server-supplied per-run event ceiling.
  * When set to a positive integer, the runtime clamps the server's limit *down*

package/dist/src/compiled/@workflow/core/runtime/helpers.d.ts

@@ -90,13 +90,11 @@ export declare function healthCheck(world: World, options?: HealthCheckOptions):
  * same array. The set is updated alongside `target`.
  *
  * Events are appended in the order the World returned them, and are not
- * re-sorted: a World's canonical order is its own, and the runtime cannot
- * reproduce it from event ids alone. `world-vercel` orders by event id, while
- * `world-local` orders by `(createdAt, eventId)` and deliberately re-mints keys
- * so that the two diverge. Every append source is already in canonical order
- * relative to the tail (a cursor-delimited page, or a write-response delta), so
- * receipt order is the order to keep. Nothing downstream may assume the tail is
- * the newest event — see {@link latestEventStateUpdatedAt}.
+ * re-sorted. Every append source is already in canonical order relative to the
+ * tail (a cursor-delimited page, or a write-response delta), so receipt order is
+ * the order to keep, and re-sorting here would only cost a pass over the log.
+ * Nothing downstream may assume the tail is the newest event — see
+ * {@link maxEventSlot}.
  */
 export declare function appendUniqueEvents(target: Event[], events: readonly Event[], targetIds?: Set<string>): void;
 /**
@@ -107,8 +105,12 @@ export declare function appendUniqueEvents(target: Event[], events: readonly Eve
  * `preloadedEvents` is loaded `sortOrder: 'asc'` and is never re-sorted
  * client-side, so a `hook_received` spliced in by the lazy-resume consumer must
  * land in `eventId` order — a plain `push` would place a late-committing
- * earlier event after events that sort before it, corrupting replay. Event IDs
- * are ULIDs, so lexicographic string order matches commit order.
+ * earlier event after events that sort before it, corrupting replay.
+ *
+ * Lexicographic string order is the log's order: a slot id is a fixed-width
+ * zero-padded position, so comparing the strings compares the positions. This
+ * needs no parse of its own for that reason, and the comparison is exact rather
+ * than a reconstruction.
  */
 export declare function insertEventByEventId(target: Event[], event: Event): void;
 /**
@@ -132,70 +134,76 @@ export interface LoadedEventLog {
     events: Event[];
     cursor: string | null;
 }
-/**
- * Whether the optimistic-concurrency guard for event creation is enabled.
- * **On by default** where the runtime executes: replay-context creates send a
- * `stateUpdatedAt` snapshot (and can be rejected with 412 by a supporting
- * backend) unless `WORKFLOW_PRECONDITION_GUARD` is set to `0`. Backends without
- * guard support ignore the snapshot, so enabling by default is
- * backward-compatible.
- */
-export declare function isPreconditionGuardEnabled(): boolean;
 /**
  * Whether a replay refuses to run over a log with a hole in it (see
  * {@link findEventSlotGap}). **On by default**; set
  * `WORKFLOW_SLOT_GAP_CHECK=0` to replay across holes instead.
  *
- * The switch exists because the check trades one failure for another. A hole is
- * a position claimed by a write that then failed, so most of them stand for an
- * event that never happened and replaying past one is correct. But a hole
- * standing for an event that *did* happen is indistinguishable from that, and
- * replaying past that one produces a run whose result is wrong with nothing to
- * show for it. Failing loudly is the recoverable side of the trade, and this is
- * the way back out if a fleet turns out to carry benign holes.
+ * A World that allocates a position at the moment it commits leaves no hole
+ * behind when a write fails, so density is a property the log has by
+ * construction rather than one this check maintains. What the check is for is
+ * the reads and the Worlds where that does not hold, and by the time it runs
+ * the benign explanations are spent: a position missing because a concurrent
+ * commit is not visible yet clears on a re-read, which is what
+ * {@link settleEventSlotGap} does first.
+ *
+ * What is left is a hole that persists, and its two causes are
+ * indistinguishable from the log. Either a World allocated the position outside
+ * the commit and lost the write, in which case nothing happened there and
+ * replaying past it is correct, or an event that did happen is missing, in
+ * which case replaying past it decides a branch on absence and produces a wrong
+ * result with nothing to show for it. Failing is the recoverable side of that
+ * trade, and this is the way back out if a fleet turns out to carry holes of
+ * the first kind.
  */
 export declare function isSlotGapCheckEnabled(): boolean;
-/**
- * The `stateUpdatedAt` value to send with a replay-context event creation: the
- * *maximum* ULID time (epoch ms) over the events the runtime has loaded. Returns
- * `undefined` when there are no events or that id is not a decodable ULID.
- *
- * It is the maximum rather than the tail's because the loaded log is in the
- * World's canonical order, which is not necessarily event-id order (see
- * {@link appendUniqueEvents}). The maximum is what lets the count sent alongside
- * it be read as "events at or below this watermark": every loaded event is at or
- * below it, so the count is exactly `events.length`. Reading the tail instead
- * would understate the watermark on a World whose order is not id-ordered, which
- * is safe (it can only weaken detection) but needlessly imprecise.
- *
- * The maximum is found by lexicographic id comparison, decoding only once: the
- * 26-character Crockford ULID encodes its timestamp in the leading 10
- * characters, so the greatest id also carries the greatest time.
- *
- * Granularity: snapshots are epoch-milliseconds, and the backend allows an
- * equal-timestamp snapshot (an up-to-date client must not be rejected). Two
- * out-of-band events landing in the same millisecond where only the first was
- * loaded therefore pass this half of the guard undetected — that is exactly
- * the hole `stateEventCount` closes, since the count of events at or below the
- * watermark differs even when the watermarks are equal.
- */
-export declare function latestEventStateUpdatedAt(events: Event[]): number | undefined;
 /**
  * Merge the events a bump-and-report write handed back into the log it was
  * derived from, and answer how many of them were new.
  *
  * Unlike {@link appendUniqueEvents}, this re-sorts. The reported events occupy
  * slots *below* the write that reported them, so appending them would put them
- * after events they precede — and on a slot-numbered run the id order is the
- * World's canonical order, so restoring it is well defined rather than a guess.
- * A run that is not slot-numbered cannot produce this report in the first
- * place; the sort is skipped rather than applied to ids it cannot order.
+ * after events they precede. Sorting by id restores the World's canonical order
+ * rather than guessing at it: a slot id is that order, written down.
  */
 export declare function mergeReportedEvents(target: Event[], events: readonly Event[]): number;
+/** What {@link absorbSkippedSlotReport} did with a write's report. */
+export interface SkippedSlotReport {
+    /** How many of the reported events were new to the log. Zero if dropped. */
+    added: number;
+    /** How many events the report offered, whether or not they were taken. */
+    offered: number;
+    /** The report was truncated, so it was dropped whole instead of merged. */
+    truncated: boolean;
+}
+/**
+ * Apply a write's skipped-slot report to the log it was derived from, deciding
+ * whether the report may be taken at all.
+ *
+ * Every replay-context write can come back carrying the events on the slots it
+ * skipped over, and every caller wants the same thing from them: fold them in
+ * so the writes that follow name a position above them, and so the replay
+ * resuming from this log sees them without a reload.
+ *
+ * The one policy is that a **truncated report is dropped whole**. It covers a
+ * span of positions but carries only some of the events on them, so merging it
+ * would raise the log's highest position past a position whose event is
+ * missing. Later writes read that maximum to say what they have seen, so each
+ * would claim a position it never saw, and the World only reports the span a
+ * write skips — it would never send the missing one. Dropping costs one more
+ * round of the same events on the next write and keeps the log a prefix of the
+ * truth, which the note above {@link mergeReportedEvents} explains is always an
+ * available answer.
+ *
+ * Callers that log do so from the returned counts; the decision is not theirs
+ * to re-derive.
+ */
+export declare function absorbSkippedSlotReport(target: Event[], result: {
+    events?: readonly Event[];
+    hasMore?: boolean;
+}): SkippedSlotReport;
 /**
- * The highest slot the loaded log occupies, or `undefined` when the run is not
- * slot-numbered. A run keeps the id scheme it was created under, so one event
- * settles it for the whole log.
+ * The highest slot the loaded log occupies, or `undefined` for an empty log.
  *
  * The maximum, not the count, and the two are not interchangeable even though
  * a healthy log makes them equal. A World hands a position to the insert that
@@ -208,8 +216,13 @@ export declare function mergeReportedEvents(target: Event[], events: readonly Ev
  *
  * A hole below the maximum is therefore a property of the read, not of the log,
  * which is what lets {@link settleEventSlotGap} re-read instead of giving up.
+ *
+ * @throws if any event id carries no slot. Every World the runtime replays
+ * against numbers events by slot, so an id that does not is a broken log rather
+ * than an older one, and a maximum derived by skipping it would understate the
+ * log to every write that reads it.
  */
-export declare function maxEventSlot(events: Event[]): number | undefined;
+export declare function maxEventSlot(events: readonly Event[]): number | undefined;
 /** A position the log skips over, described well enough to name in an error. */
 export interface EventSlotGap {
     /** The lowest slot below the log's maximum that no event occupies. */
@@ -222,8 +235,8 @@ export interface EventSlotGap {
 /**
  * The hole in a loaded log, or `undefined` when there is none to find.
  *
- * On a slot-numbered run the World allocates every position, so a log that
- * holds `n` events below slot `n` is missing one. That matters before a replay
+ * The World allocates every position, so a log that holds `n` events below slot
+ * `n` is missing one. That matters before a replay
  * and nowhere else: the replay reads the log as the complete record of what has
  * happened, and an absent position is indistinguishable from an event that
  * never occurred. The branch it would have decided gets decided the other way,
@@ -240,8 +253,10 @@ export interface EventSlotGap {
  * legitimately begins at the second slot and fills in on its own. Every replay
  * that races a run's own start would otherwise report a hole.
  *
- * Returns `undefined` for a log this cannot read as slots at all: an empty one,
- * or a run numbered by ULID, where positions carry no density to check.
+ * Returns `undefined` for an empty log, which has no density to check.
+ *
+ * @throws if any event id carries no slot, for the reason {@link maxEventSlot}
+ * gives.
  */
 export declare function findEventSlotGap(events: readonly Event[]): EventSlotGap | undefined;
 /**
@@ -274,42 +289,39 @@ export declare function settleEventSlotGap(runId: string, loaded: LoadedEventLog
     gap: EventSlotGap | undefined;
 }>;
 /**
- * The precondition snapshot a replay-context event creation sends, describing
- * the event log the replay derived the event from.
- *
- * On a slot-numbered run this is `eventCount`, optionally with the set of
- * correlation ids the writer is blocked on. On a ULID-numbered run it is the
- * `stateUpdatedAt` / `stateEventCount` / `stateCursor` triple, whose three
- * fields are one indivisible unit: the backend reads the count only relative to
- * the watermark, and returns its inline delta only relative to the cursor.
- * Passing them as a single object is what keeps them from drifting apart at a
- * call site.
+ * How much of its run's log a replay-context event creation had loaded when it
+ * decided to write, as the highest slot that log occupies.
+ *
+ * One integer says it because the World keeps its positions dense: a writer
+ * that names slot N is claiming to hold every event from 1 to N and nothing
+ * above. The World answers by numbering the write above whatever the log has
+ * actually reached and handing back the events on the slots in between — the
+ * ones this writer decided without.
+ *
+ * Density is the World's invariant, not a claim about this particular read. A
+ * reader that is short of a position it holds no event for names a lower N,
+ * which understates what it has seen and only costs it a wider report. Naming
+ * a position it cannot account for is the direction that is unsafe, which is
+ * why {@link slotSnapshotParams} takes the maximum rather than the count.
+ *
+ * Its own object rather than a bare number so a call site cannot half-send it,
+ * and so the empty case spreads to nothing.
  */
-export interface PreconditionSnapshotParams {
-    stateUpdatedAt?: number;
-    stateEventCount?: number;
-    stateCursor?: string;
+export interface SlotSnapshotParams {
     eventCount?: number;
 }
 /**
- * Build the precondition snapshot to attach to a replay-context event creation.
- *
- * Returns an empty object — no guard, backend behaves as before — when the
- * guard is disabled or the watermark is not derivable. All three fields fail
- * open together: a count without a watermark is meaningless to the backend, and
- * a cursor without either would invite a delta nobody asked for.
- *
- * `stateEventCount` is `events.length` because the watermark is the log's
- * *maximum* ULID time, so every loaded event is at or below it regardless of the
- * order the World returned them in.
- *
- * Both fields are therefore invariant under permutation of the log: a maximum is
- * order-independent, and the length is set cardinality once `appendUniqueEvents`
- * has deduped by event id. Two replays that consume the same events in different
- * orders send an identical snapshot, so this guard detects that a log is missing
- * an event and can never detect that a replay consumed one in a different order.
+ * Build the slot snapshot to attach to a replay-context event creation.
+ *
+ * Empty for an empty log, which is the state a `run_created` write is issued
+ * from: there is no position held yet to name.
+ *
+ * The maximum rather than the length, for the reason {@link maxEventSlot}
+ * gives: a partially-read log holds fewer events than its highest position, and
+ * counting those would make the write claim to have seen less than it has, so
+ * the World would report the same events back on every attempt.
  */
-export declare function preconditionSnapshotParams(events: Event[], cursor?: string | null): PreconditionSnapshotParams;
+export declare function slotSnapshotParams(events: readonly Event[]): SlotSnapshotParams;
 /**
  * The events a rejecting World attached to a `PreconditionFailedError`, when it
  * returned the ones the client's snapshot was missing inline.
@@ -335,6 +347,28 @@ export type EventCreator = (data: CreateEventRequest, params?: CreateEventParams
  * based on the presence of a `__health` query parameter.
  */
 export declare function withHealthCheck(handler: (req: Request) => Promise<Response>, worldSpecVersion?: number): (req: Request) => Promise<Response>;
+/**
+ * Idempotency key for a step's background-dispatch queue message, scoped to
+ * the step's IDENTITY — correlation id plus (hashed) step name — rather than
+ * the bare correlation id.
+ *
+ * The scoping matters for resilient step dispatch under the precondition
+ * guard: a guard-rejected `step_created` leaves its (revoked) step message in
+ * flight, and the corrected replay may re-derive the same correlation id for
+ * a DIFFERENT step. Under a bare-correlationId key the corrected replay's
+ * dispatch would silently dedupe against the revoked in-flight message —
+ * which then resolves `skipped` against the re-created entity (the server's
+ * stepName fence rejects its bare start) — and the legitimate step would
+ * never be executed. Scoping by step name keeps every dedup property that
+ * matters (crash recovery re-dispatch, concurrent handlers, the delayed
+ * retry sharing the suspension re-dispatch's key — all name the same step)
+ * while letting the corrected schedule's dispatch through.
+ *
+ * Every producer of a step-dispatch (or step-retry) message must use this
+ * key. Cross-version mixing is not a concern: queue messages are pinned to
+ * the deployment that produced them, so one run never sees two key schemes.
+ */
+export declare function stepDispatchIdempotencyKey(correlationId: string, stepName: string): string;
 /**
  * Queues a message to the specified queue with tracing.
  */