eve 0.44.4 → 0.45.0

package/dist/src/compiler/normalize-subagent.d.ts

@@ -1,39 +1,21 @@
-import { type AgentSourceManifest, type LocalSubagentSourceRef } from "#discover/manifest.js";
-import { type CompiledAgentNodeManifest, type CompiledAgentResources, type CompiledRemoteAgentNode, type CompiledSubagentEdge, type CompiledSubagentNode } from "#compiler/manifest.js";
-import { type ManifestCompileContext } from "#compiler/normalize-helpers.js";
-/**
- * Callback the subagent compiler uses to recurse into the per-node
- * manifest compiler. Injected by `normalize-manifest.ts` so this module
- * does not have to import the orchestrator (which would create a
- * circular dependency).
- */
-export type CompileAgentNodeManifestFn = (manifest: AgentSourceManifest, context: ManifestCompileContext, options?: {
-    readonly agentConfigDefinition?: unknown;
-    readonly externalDependencies?: readonly string[];
-    readonly allowRootOnlyConfig?: boolean;
-}) => Promise<CompiledAgentNodeManifest>;
-export type CompileAgentResourcesFn = (manifest: AgentSourceManifest, context: ManifestCompileContext, options?: {
-    readonly externalDependencies?: readonly string[];
-}) => Promise<CompiledAgentResources>;
-/**
- * Compiles every local subagent reachable from one parent node into a
- * flat node list and the parent→child edges that connect them.
- *
- * Recursive: each subagent may itself declare further subagents, which
- * are compiled depth-first via the injected `compileAgentNodeManifest`
- * callback.
- */
-export declare function compileSubagentGraph(input: {
-    readonly appRoot: string;
-    readonly compileAgentNodeManifest: CompileAgentNodeManifestFn;
-    readonly compileAgentResources: CompileAgentResourcesFn;
-    readonly context: ManifestCompileContext;
-    readonly externalDependencies?: readonly string[];
-    readonly parentAgentRoot: string;
-    readonly parentNodeId: string;
-    readonly subagents: readonly LocalSubagentSourceRef[];
-}): Promise<{
-    readonly edges: readonly CompiledSubagentEdge[];
-    readonly nodes: readonly CompiledSubagentNode[];
-    readonly remoteAgents: readonly CompiledRemoteAgentNode[];
-}>;
+import type { JsonObject } from "#shared/json.js";
+import { type DynamicToolEventName } from "#dynamic/definition.js";
+import type { LocalSubagentSourceRef } from "#discover/manifest.js";
+export type NormalizedSubagentConfig = {
+    readonly kind: "local";
+    readonly definition: unknown;
+} | {
+    readonly build?: {
+        readonly externalDependencies?: readonly string[];
+    };
+    readonly eventNames: readonly DynamicToolEventName[];
+    readonly kind: "dynamic";
+} | {
+    readonly description: string;
+    readonly kind: "remote";
+    readonly outputSchema?: JsonObject;
+    readonly path: string;
+    readonly url?: string;
+};
+export declare function normalizeSubagentConfig(value: unknown, message: string): NormalizedSubagentConfig;
+export declare function assertRemoteAgentDefinitionHasNoLocalPackageEntries(source: LocalSubagentSourceRef): void;

package/dist/src/compiler/normalize-subagent.js

@@ -1 +1 @@
-import{expectBoolean,expectFunction,expectObjectRecord,expectOnlyKnownKeys,expectString}from"#internal/authored-module.js";import{EVE_SESSION_ROUTE_PATH}from"#protocol/routes.js";import{join,relative}from"node:path";import{serializeOutputSchema}from"#shared/tool-schema.js";import{createCompiledSubagentNodeId}from"#compiler/manifest.js";import{loadModuleBackedDefinition}from"#compiler/normalize-helpers.js";import{createPathDerivedSourceId}from"#discover/manifest.js";import{isDynamicSentinel}from"#shared/dynamic-tool-definition.js";import{composeAgentSubagentSources}from"#compiler/normalize-extension.js";const ALLOWED_DYNAMIC_SUBAGENT_EVENTS=new Set([`session.started`,`turn.started`]);async function compileSubagentGraph(e){let t=[],n=[],r=[];for(let i of e.subagents){let a=await compileSubagentDefinition({appRoot:e.appRoot,compileAgentNodeManifest:e.compileAgentNodeManifest,compileAgentResources:e.compileAgentResources,context:e.context,externalDependencies:e.externalDependencies,parentAgentRoot:e.parentAgentRoot,parentNodeId:e.parentNodeId,source:i});if(a.kind===`remote`){r.push(a.node);continue}t.push(a.node,...a.descendants.nodes),n.push({childNodeId:a.node.nodeId,parentNodeId:e.parentNodeId},...a.descendants.edges)}return{edges:n,nodes:t,remoteAgents:r}}async function compileSubagentDefinition(e){let t=e.source.manifest.configModule;if(t===void 0)throw Error(`Subagent "${e.source.logicalPath}" is missing an agent config module.`);let n=createSubagentConfigModuleSourceRef(e.source,t,e.parentAgentRoot),r=await loadModuleBackedDefinition({agentRoot:e.source.manifest.agentRoot,displayPath:n.logicalPath,externalDependencies:e.externalDependencies,kind:`subagent config`,source:t}),i=normalizeDynamicSubagentDefinition(r,`Expected the dynamic subagent config export "${t.exportName??`default`}" from "${n.logicalPath}" to match the public eve shape.`);return i===void 0&&readAgentDefinitionKind(r)===`remote`?{kind:`remote`,node:compileRemoteAgent({parentAgentRoot:e.parentAgentRoot,source:e.source,value:r})}:{kind:`local`,...await compileLocalSubagent({...e,agentConfigDefinition:i===void 0?r:void 0,configResolver:i===void 0?void 0:{...t,...i.definition,build:i.build}})}}async function compileSubagent(e){let t=createCompiledSubagentNodeId(e.parentNodeId,e.source.sourceId),n=e.source.subagentId,r={...e.source.manifest,appRoot:e.appRoot},i=mergeExternalDependencies(e.externalDependencies,e.configResolver?.build?.externalDependencies),a={entryPath:e.source.entryPath,logicalPath:e.source.logicalPath,name:n,nodeId:t,rootPath:e.source.rootPath,sourceId:e.source.sourceId,sourceKind:`module`};if(e.configResolver===void 0){let n=await e.compileAgentNodeManifest(r,e.context,{agentConfigDefinition:e.agentConfigDefinition,allowRootOnlyConfig:!1,externalDependencies:i}),o=n.config.description;if(!o)throw Error(`Local subagent "${e.source.logicalPath}" is missing a "description" field on its agent config. Add \`description\` to \`defineAgent({ ... })\` so the parent agent can decide when to delegate to this subagent.`);let s=await compileSubagentGraph({appRoot:e.appRoot,compileAgentNodeManifest:e.compileAgentNodeManifest,context:e.context,compileAgentResources:e.compileAgentResources,externalDependencies:n.config.build?.externalDependencies??i,parentAgentRoot:e.source.manifest.agentRoot,parentNodeId:t,subagents:composeAgentSubagentSources(e.source.manifest)});return{descendants:s,node:{...a,agent:{...n,remoteAgents:[...s.remoteAgents]},description:o}}}let o=await e.compileAgentResources(r,e.context,{externalDependencies:i}),s=await compileSubagentGraph({appRoot:e.appRoot,compileAgentNodeManifest:e.compileAgentNodeManifest,context:e.context,compileAgentResources:e.compileAgentResources,externalDependencies:i,parentAgentRoot:e.source.manifest.agentRoot,parentNodeId:t,subagents:composeAgentSubagentSources(e.source.manifest)});return{descendants:s,node:{...a,agent:{...o,remoteAgents:[...s.remoteAgents]},configResolver:e.configResolver}}}const compileLocalSubagent=compileSubagent;function compileRemoteAgent(e){let t=e.source.manifest.configModule;if(t===void 0)throw Error(`Remote agent "${e.source.logicalPath}" is missing a config module.`);assertRemoteAgentDefinitionHasNoLocalPackageEntries(e.source);let n=createSubagentConfigModuleSourceRef(e.source,t,e.parentAgentRoot),r=normalizeRemoteAgentDefinition(e.value,`Expected the remote agent config export "${t.exportName??`default`}" from "${n.logicalPath}" to match the public eve shape.`),i={...n,description:r.description,entryPath:e.source.entryPath,name:e.source.subagentId,nodeId:e.source.sourceId,outputSchema:r.outputSchema,path:r.path,rootPath:e.source.rootPath};return r.url===void 0?i:{...i,url:r.url}}function normalizeDynamicSubagentDefinition(e,i){if(!isDynamicSentinel(e))return;let a=expectObjectRecord(e,i);expectOnlyKnownKeys(a,[`build`,`events`,`kind`],i);let o=a.build===void 0?void 0:normalizeDynamicSubagentBuild(a.build,i),s=expectObjectRecord(a.events,i),c=[];for(let[e,n]of Object.entries(s)){if(!ALLOWED_DYNAMIC_SUBAGENT_EVENTS.has(e))throw Error(`${i} Dynamic subagents support only "session.started" and "turn.started" handlers.`);expectFunction(n,i),c.push(e)}let l={definition:{eventNames:c}};return o!==void 0&&(l.build=o),l}function normalizeDynamicSubagentBuild(e,t){let a=expectObjectRecord(e,t);if(expectOnlyKnownKeys(a,[`externalDependencies`],t),a.externalDependencies===void 0)return{};if(!Array.isArray(a.externalDependencies))throw Error(t);return{externalDependencies:a.externalDependencies.map(e=>expectString(e,t))}}function mergeExternalDependencies(...e){return[...new Set(e.flatMap(e=>e??[]))]}function createSubagentConfigModuleSourceRef(e,t,n){let r=relative(n,join(e.manifest.agentRoot,t.logicalPath)).replaceAll(`\\`,`/`),i={logicalPath:r,sourceId:t.sourceId.startsWith(`ext:`)||t.sourceId.startsWith(`ext-override:`)?t.sourceId:createPathDerivedSourceId(r),sourceKind:`module`};return t.exportName!==void 0&&(i.exportName=t.exportName),i}function readAgentDefinitionKind(e){return typeof e!=`object`||!e?`local`:e.kind===`remote`?`remote`:`local`}function normalizeRemoteAgentDefinition(t,o){let s=expectObjectRecord(t,o);if(expectOnlyKnownKeys(s,[`auth`,`description`,`forwardPrincipal`,`headers`,`kind`,`outputSchema`,`path`,`url`],o),s.kind!==`remote`)throw Error(`${o} Expected "kind" to be "remote".`);return s.forwardPrincipal!==void 0&&expectBoolean(s.forwardPrincipal,`${o} Expected "forwardPrincipal" to be a boolean.`),{description:expectString(s.description,o),outputSchema:serializeOutputSchema(s.outputSchema),path:s.path===void 0?EVE_SESSION_ROUTE_PATH:expectString(s.path,o),url:typeof s.url==`function`?void 0:expectString(s.url,o)}}function assertRemoteAgentDefinitionHasNoLocalPackageEntries(e){let t=e.manifest,n=[t.connections.length>0?`connections/`:void 0,t.hooks.length>0?`hooks/`:void 0,t.instructions.length>0?`instructions`:void 0,t.lib.length>0?`lib/`:void 0,t.sandbox===null?void 0:`sandbox/`,t.sandboxWorkspaces.length>0?`sandbox/workspace/`:void 0,t.schedules.length>0?`schedules/`:void 0,t.skills.length>0?`skills/`:void 0,t.subagents.length>0?`subagents/`:void 0,t.tools.length>0?`tools/`:void 0].filter(e=>e!==void 0);if(n.length!==0)throw Error(`Remote subagent definition "${e.logicalPath}" cannot include local package entries. Remove unsupported entries: ${n.join(`, `)}.`)}export{compileSubagentGraph};
+import{expectBoolean,expectFunction,expectObjectRecord,expectOnlyKnownKeys,expectString}from"#internal/authored-module.js";import{EVE_SESSION_ROUTE_PATH}from"#protocol/routes.js";import{serializeOutputSchema}from"#tools/schema.js";import{isDynamicSentinel}from"#dynamic/definition.js";const ALLOWED_DYNAMIC_SUBAGENT_EVENTS=new Set([`session.started`,`turn.started`]);function normalizeSubagentConfig(s,c){if(isDynamicSentinel(s)){let e=expectObjectRecord(s,c);expectOnlyKnownKeys(e,[`build`,`events`,`kind`],c);let r=expectObjectRecord(e.events,c),i=[];for(let[e,n]of Object.entries(r)){if(!ALLOWED_DYNAMIC_SUBAGENT_EVENTS.has(e))throw Error(`${c} Dynamic subagents support only "session.started" and "turn.started" handlers.`);expectFunction(n,c),i.push(e)}let a=e.build===void 0?void 0:normalizeDynamicSubagentBuild(e.build,c);return a===void 0?{eventNames:i,kind:`dynamic`}:{build:a,eventNames:i,kind:`dynamic`}}if(typeof s==`object`&&s&&s.kind===`remote`){let t=expectObjectRecord(s,c);expectOnlyKnownKeys(t,[`auth`,`description`,`forwardPrincipal`,`headers`,`kind`,`outputSchema`,`path`,`url`],c),t.forwardPrincipal!==void 0&&expectBoolean(t.forwardPrincipal,`${c} Expected "forwardPrincipal" to be a boolean.`);let o=serializeOutputSchema(t.outputSchema);return{description:expectString(t.description,c),kind:`remote`,outputSchema:o,path:t.path===void 0?EVE_SESSION_ROUTE_PATH:expectString(t.path,c),url:typeof t.url==`function`?void 0:expectString(t.url,c)}}return{definition:s,kind:`local`}}function assertRemoteAgentDefinitionHasNoLocalPackageEntries(e){let t=e.manifest,n=[t.connections.length>0?`connections/`:void 0,t.hooks.length>0?`hooks/`:void 0,t.instructions.length>0?`instructions`:void 0,t.lib.length>0?`lib/`:void 0,t.sandbox===null?void 0:`sandbox/`,t.sandboxWorkspaces.length>0?`sandbox/workspace/`:void 0,t.schedules.length>0?`schedules/`:void 0,t.skills.length>0?`skills/`:void 0,t.subagents.length>0?`subagents/`:void 0,t.tools.length>0?`tools/`:void 0].filter(e=>e!==void 0);if(n.length>0)throw Error(`Remote subagent definition "${e.logicalPath}" cannot include local package entries. Remove unsupported entries: ${n.join(`, `)}.`)}function normalizeDynamicSubagentBuild(e,t){let i=expectObjectRecord(e,t);if(expectOnlyKnownKeys(i,[`externalDependencies`],t),i.externalDependencies===void 0)return{};if(!Array.isArray(i.externalDependencies))throw Error(t);return{externalDependencies:i.externalDependencies.map(e=>expectString(e,t))}}export{assertRemoteAgentDefinitionHasNoLocalPackageEntries,normalizeSubagentConfig};

package/dist/src/compiler/normalize-tool.d.ts

@@ -18,6 +18,7 @@ export type CompiledToolEntry = {
     readonly kind: "workflow-tool";
     readonly maxSubagents?: number;
 } | {
+    readonly definition: CompiledToolDefinition;
     readonly kind: "web-search-tool";
     readonly provider: "exa" | "parallel";
 } | {
@@ -36,4 +37,4 @@ export type CompiledToolEntry = {
  * directories into a slug-safe single segment. Authored `name` fields
  * are rejected by the normalizer.
  */
-export declare function compileToolEntry(agentRoot: string, source: ToolSourceRef, options?: ModuleBackedDefinitionLoadOptions): Promise<CompiledToolEntry>;
+export declare function compileToolEntry(_agentRoot: string, source: ToolSourceRef, options: ModuleBackedDefinitionLoadOptions): Promise<CompiledToolEntry>;

package/dist/src/compiler/normalize-tool.js

@@ -1 +1 @@
-import{stripLogicalPathExtension}from"#discover/filesystem.js";import{loadModuleBackedDefinition}from"#compiler/normalize-helpers.js";import{normalizeToolDefinition}from"#internal/authored-definition/schema-backed.js";async function compileToolEntry(e,t,n={}){let r=normalizeToolDefinition(await loadModuleBackedDefinition({agentRoot:e,externalDependencies:n.externalDependencies,kind:`tool`,source:t}),`Expected the tool export "${t.exportName??`default`}" from "${t.logicalPath}" to match the public eve shape.`),i=stripLogicalPathExtension(t.logicalPath).replace(/^tools\//,``).replaceAll(`/`,`-`);if(r.kind===`disabled`)return{kind:`disabled`,name:i};if(r.kind===`workflow-tool`)return{kind:`workflow-tool`,maxSubagents:r.maxSubagents};if(r.kind===`web-search-tool`){if(i!==`web_search`)throw Error(`The webSearch() definition must be exported from "tools/web_search.ts", not "${t.logicalPath}".`);return{kind:`web-search-tool`,provider:r.provider}}return r.kind===`dynamic-tool`?{kind:`dynamic-tool`,definition:{eventNames:[...r.eventNames],exportName:t.exportName,logicalPath:t.logicalPath,slug:i,sourceId:t.sourceId,sourceKind:`module`}}:{kind:`tool`,definition:{description:r.definition.description,execution:r.definition.execution,exportName:t.exportName,inputSchema:r.definition.inputSchema??null,logicalPath:t.logicalPath,name:i,outputSchema:r.definition.outputSchema,sourceId:t.sourceId,sourceKind:`module`}}}export{compileToolEntry};
+import{stripLogicalPathExtension}from"#discover/filesystem.js";import{loadModuleBackedDefinition}from"#compiler/normalize-helpers.js";import{normalizeToolDefinition}from"#internal/authored-definition/schema-backed.js";async function compileToolEntry(e,t,n){let r=normalizeToolDefinition(await loadModuleBackedDefinition({binding:n.binding,kind:`tool`,loadNamespace:n.loadNamespace,source:t}),`Expected the tool export "${t.exportName??`default`}" from "${t.logicalPath}" to match the public eve shape.`),i=stripLogicalPathExtension(t.logicalPath).replace(/^tools\//,``).replaceAll(`/`,`-`);if(r.kind===`disabled`)return{kind:`disabled`,name:i};if(r.kind===`workflow-tool`)return{kind:`workflow-tool`,maxSubagents:r.maxSubagents};if(r.kind===`web-search-tool`){if(i!==`web_search`)throw Error(`The webSearch() definition must be exported from "tools/web_search.ts", not "${t.logicalPath}".`);return{definition:{description:`Search the web for real-time information. Use this to find up-to-date information about current events, recent developments, or topics that may have changed since the knowledge cutoff.`,exportName:t.exportName,hasExecute:!1,hasModelOutputProjection:!1,inputSchema:null,logicalPath:t.logicalPath,name:i,sourceId:t.sourceId,sourceKind:`module`,requiresApproval:!1},kind:`web-search-tool`,provider:r.provider}}return r.kind===`dynamic-tool`?{kind:`dynamic-tool`,definition:{eventNames:[...r.eventNames],exportName:t.exportName,logicalPath:t.logicalPath,slug:i,sourceId:t.sourceId,sourceKind:`module`}}:{kind:`tool`,definition:{description:r.definition.description,execution:r.definition.execution,exportName:t.exportName,hasExecute:!0,hasModelOutputProjection:r.definition.hasModelOutputProjection,inputSchema:r.definition.inputSchema??null,logicalPath:t.logicalPath,name:i,outputSchema:r.definition.outputSchema,requiresApproval:r.definition.hasApproval,sourceId:t.sourceId,sourceKind:`module`}}}export{compileToolEntry};

package/dist/src/compiler/project-sources.d.ts

@@ -0,0 +1,71 @@
+import type { AgentSourceManifest, ConnectionSourceRef, InstructionsSourceRef, LocalSubagentSourceRef, ResolvedExtensionMount, ScheduleSourceRef, SkillSourceRef } from "#discover/manifest.js";
+import type { ModuleSourceRef } from "#shared/source-ref.js";
+import type { AgentModuleCandidate, AgentResourceCandidate, AgentSourceCandidate, AgentSourceLayer, AgentSourceOwner } from "#compiler/source-graph.js";
+export type ProjectedModuleSource = {
+    readonly candidate: AgentModuleCandidate;
+    readonly kind: "connection";
+    readonly source: ConnectionSourceRef;
+} | {
+    readonly candidate: AgentModuleCandidate;
+    readonly kind: "channel" | "config" | "extension" | "hook" | "instructions" | "instrumentation" | "sandbox" | "schedule" | "skill" | "tool";
+    readonly source: ModuleSourceRef;
+};
+export type ProjectedResourceSource = {
+    readonly candidate: AgentResourceCandidate;
+    readonly kind: "instructions";
+    readonly source: InstructionsSourceRef;
+} | {
+    readonly candidate: AgentResourceCandidate;
+    readonly kind: "schedule";
+    readonly source: ScheduleSourceRef;
+} | {
+    readonly candidate: AgentResourceCandidate;
+    readonly kind: "skill";
+    readonly source: SkillSourceRef;
+};
+export type ProjectedSource = ProjectedModuleSource | ProjectedResourceSource;
+export interface ProjectedSubagentSource {
+    readonly candidate: AgentResourceCandidate;
+    readonly extensionScope?: {
+        readonly namespace: string;
+        readonly sourceRoot: string;
+    };
+    readonly owner: AgentSourceOwner;
+    readonly source: LocalSubagentSourceRef;
+}
+export interface ProjectedAgentSources {
+    readonly candidates: readonly AgentSourceCandidate[];
+    readonly resources: readonly ProjectedResourceSource[];
+    readonly subagents: readonly ProjectedSubagentSource[];
+}
+export declare function projectAgentSources(input: {
+    readonly externalDependencies: readonly string[];
+    readonly extensionScope?: {
+        readonly namespace: string;
+        readonly sourceRoot: string;
+    };
+    readonly layer?: AgentSourceLayer;
+    readonly manifest: AgentSourceManifest;
+    readonly nodeId: string;
+    readonly owner?: AgentSourceOwner;
+}): ProjectedAgentSources;
+export declare function projectSelectedSources(input: {
+    readonly candidates: Iterable<AgentSourceCandidate>;
+    readonly resources: readonly ProjectedResourceSource[];
+}): readonly ProjectedSource[];
+export declare function createFilesystemModuleCandidate(input: {
+    readonly externalDependencies: readonly string[];
+    readonly extension?: ResolvedExtensionMount;
+    readonly extensionScope?: {
+        readonly namespace: string;
+        readonly sourceRoot: string;
+    };
+    readonly layer: AgentSourceLayer;
+    readonly logicalPath: string;
+    readonly nodeId: string;
+    readonly owner: AgentSourceOwner;
+    readonly source: ModuleSourceRef;
+    readonly sourceId?: string;
+    readonly sourceRoot: string;
+}): AgentModuleCandidate;
+export declare function qualifyExtensionLogicalPath(logicalPath: string, namespace: string): string;

package/dist/src/compiler/project-sources.js

@@ -0,0 +1 @@
+import{join}from"node:path";import{stripLogicalPathExtension}from"#discover/filesystem.js";import{canonicalSourceSlot}from"#compiler/source-graph.js";const MODULE_KIND_BY_SLOT_ROOT={agent:`config`,channels:`channel`,extensions:`extension`,hooks:`hook`,instructions:`instructions`,instrumentation:`instrumentation`,sandbox:`sandbox`,schedules:`schedule`,skills:`skill`,tools:`tool`};function projectAgentSources(e){let t=e.owner??{kind:`application`},n=[],r=[],i=[];projectManifest({externalDependencies:e.externalDependencies,candidates:n,extensionScope:e.extensionScope,layer:e.layer??`application`,manifest:e.manifest,nodeId:e.nodeId,owner:t,resources:r,subagents:i});for(let t of[...e.manifest.resolvedExtensions].sort((e,t)=>e.namespace.localeCompare(t.namespace))){let a={kind:`extension`,namespace:t.namespace,packageName:t.packageName};projectManifest({externalDependencies:mergeDependencies(e.externalDependencies,t.externalDependencies),candidates:n,extension:t,layer:`extension-package`,manifest:t.manifest,nodeId:e.nodeId,owner:a,resources:r,sourceIdPrefix:`ext:${t.namespace}:`,subagents:i}),t.overrides!==void 0&&projectManifest({externalDependencies:e.externalDependencies,candidates:n,extension:t,layer:`extension-override`,manifest:t.overrides,nodeId:e.nodeId,owner:{kind:`application`},resources:r,sourceIdPrefix:`ext-override:${t.namespace}:`,subagents:i})}return{candidates:n,resources:r,subagents:i}}function projectSelectedSources(e){let t=new Map(e.resources.map(e=>[e.candidate.sourceId,e])),n=[];for(let r of e.candidates)if(isModuleCandidate(r))n.push(projectModuleCandidate(r));else{let e=t.get(r.sourceId);e!==void 0&&n.push(e)}return n}function createFilesystemModuleCandidate(t){return{backing:{externalDependencies:[...t.externalDependencies],...t.owner.kind===`extension`&&(t.extension!==void 0||t.extensionScope!==void 0)?{extensionScope:{namespace:t.extension?.namespace??t.extensionScope.namespace,sourceRoot:t.extension?.sourceRoot??t.extensionScope.sourceRoot}}:{},kind:`filesystem`,sourcePath:join(t.sourceRoot,t.source.logicalPath)},exportName:t.source.exportName,form:`direct`,layer:t.layer,logicalPath:t.logicalPath,nodeId:t.nodeId,owner:t.owner,sourceId:t.sourceId??t.source.sourceId}}function projectManifest(t){let qualify=e=>t.extension===void 0?e:qualifyExtensionLogicalPath(e,t.extension.namespace),sourceId=e=>`${t.sourceIdPrefix??``}${e}`,pushModule=(e,n)=>{let r=n??qualify(e.logicalPath),i=createFilesystemModuleCandidate({externalDependencies:t.externalDependencies,extension:t.extension,extensionScope:t.extensionScope,layer:t.layer,logicalPath:r,nodeId:t.nodeId,owner:t.owner,source:e,sourceId:sourceId(e.sourceId),sourceRoot:t.manifest.agentRoot});t.candidates.push(i)},pushResource=(n,r)=>{let i=qualify(r.logicalPath),a={...r,...r.sourceKind===`skill-package`?{name:t.extension===void 0?r.name:`${t.extension.namespace}__${r.name}`}:{},logicalPath:i,sourceId:sourceId(r.sourceId)},o={backing:{kind:`resource`,sourcePath:r.sourceKind===`skill-package`?r.skillFilePath:join(t.manifest.agentRoot,r.logicalPath)},form:`direct`,layer:t.layer,logicalPath:i,nodeId:t.nodeId,owner:t.owner,sourceId:a.sourceId};t.candidates.push(o),t.resources.push({candidate:o,kind:n,source:a})};if(t.extension===void 0&&t.manifest.configModule!==void 0){let e=t.manifest.configModule.logicalPath;pushModule(t.manifest.configModule,canonicalSourceSlot(e)===`agent`?void 0:`agent.ts`)}if(t.manifest.instrumentation!==void 0&&pushModule(t.manifest.instrumentation),t.extension===void 0)for(let e of t.manifest.extensions)pushModule(e);for(let e of t.manifest.channels)pushModule(e);for(let e of t.manifest.connections)pushModule(e);for(let e of t.manifest.hooks)pushModule(e);t.manifest.sandbox!==null&&pushModule(t.manifest.sandbox);for(let e of t.manifest.tools)pushModule(e);for(let e of t.manifest.instructions)e.sourceKind===`module`?pushModule(e):pushResource(`instructions`,e);for(let e of t.manifest.schedules)e.sourceKind===`module`?pushModule(e):pushResource(`schedule`,e);for(let e of t.manifest.skills)e.sourceKind===`module`?pushModule(e):pushResource(`skill`,e);for(let e of t.manifest.subagents){let n=t.extension===void 0?e.subagentId:`${t.extension.namespace}__${e.subagentId}`,r=t.extension===void 0?e.logicalPath:qualifyExtensionLogicalPath(e.logicalPath,t.extension.namespace),i={...e,logicalPath:r,sourceId:sourceId(e.sourceId),subagentId:n},a={backing:{kind:`resource`,sourcePath:e.entryPath},form:`direct`,layer:t.layer,logicalPath:r,nodeId:t.nodeId,owner:t.owner,sourceId:i.sourceId};t.candidates.push(a),t.subagents.push({candidate:a,...t.extension===void 0&&t.extensionScope===void 0?{}:{extensionScope:t.extension===void 0?t.extensionScope:{namespace:t.extension.namespace,sourceRoot:t.extension.sourceRoot}},owner:t.owner,source:i})}}function projectModuleCandidate(e){let t={exportName:e.exportName,logicalPath:e.logicalPath,sourceId:e.sourceId,sourceKind:`module`},i=canonicalSourceSlot(e.logicalPath);if(i.startsWith(`connections/`))return{candidate:e,kind:`connection`,source:{...t,connectionName:deriveConnectionName(e.logicalPath)}};let a=MODULE_KIND_BY_SLOT_ROOT[i.split(`/`,1)[0]];if(a===void 0)throw Error(`Agent module source slot "${e.logicalPath}" is not compiled yet.`);return{candidate:e,kind:a,source:t}}function isModuleCandidate(e){return e.backing.kind!==`resource`}function qualifyExtensionLogicalPath(e,t){let n=e.split(`/`);if(n.length<2)return e;let r=n[0];return r===`sandbox`||r===`extensions`||r===`lib`?e:(n[1]=`${t}__${n[1]}`,n.join(`/`))}function deriveConnectionName(e){let n=stripLogicalPathExtension(e).replace(/^connections\//,``);return n.endsWith(`/connection`)?n.slice(0,-11):n}function mergeDependencies(...e){return[...new Set(e.flat())]}export{createFilesystemModuleCandidate,projectAgentSources,projectSelectedSources,qualifyExtensionLogicalPath};

package/dist/src/compiler/remote-agent-node.d.ts

@@ -2,6 +2,7 @@ import { z } from "#compiled/zod/index.js";
 import type { JsonObject } from "#shared/json.js";
 import type { Node } from "#shared/node.js";
 import type { ModuleSourceRef } from "#shared/source-ref.js";
+import type { AgentSourceOwner, CompiledModuleBinding } from "#compiler/source-graph.js";
 export interface CompiledDynamicSubagentDefinition extends Readonly<ModuleSourceRef> {
     readonly build?: {
         readonly externalDependencies?: readonly string[];
@@ -15,8 +16,15 @@ export interface CompiledDynamicSubagentDefinition extends Readonly<ModuleSource
  */
 export type CompiledRemoteAgentNode = Readonly<ModuleSourceRef & Node & {
     description: string;
+    backing: {
+        readonly kind: "resource";
+        readonly sourcePath: string;
+    };
+    binding: CompiledModuleBinding;
     entryPath: string;
     name: string;
+    owner: AgentSourceOwner;
+    parentNodeId: string;
     outputSchema?: JsonObject;
     path: string;
     rootPath: string;

package/dist/src/compiler/remote-agent-node.js

@@ -1 +1 @@
-import{z}from"#compiled/zod/index.js";import{jsonObjectSchema}from"#shared/json-schemas.js";const compiledRemoteAgentNodeSchema=z.object({description:z.string(),entryPath:z.string(),exportName:z.string().optional(),logicalPath:z.string(),name:z.string(),nodeId:z.string(),outputSchema:jsonObjectSchema.optional(),path:z.string(),rootPath:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`),url:z.string().optional()}).strict();export{compiledRemoteAgentNodeSchema};
+import{z}from"#compiled/zod/index.js";import{jsonObjectSchema}from"#shared/json-schemas.js";const compiledRemoteAgentNodeSchema=z.object({backing:z.object({kind:z.literal(`resource`),sourcePath:z.string()}).strict(),binding:z.object({backing:z.discriminatedUnion(`kind`,[z.object({externalDependencies:z.array(z.string()).readonly(),extensionScope:z.object({namespace:z.string(),sourceRoot:z.string()}).strict().optional(),kind:z.literal(`filesystem`),sourcePath:z.string()}).strict(),z.object({kind:z.literal(`programmatic`),moduleId:z.string(),registryId:z.string(),revision:z.string(),semanticRevision:z.string().optional()}).strict()]),logicalPath:z.string(),owner:z.discriminatedUnion(`kind`,[z.object({kind:z.literal(`application`)}).strict(),z.object({feature:z.string(),kind:z.literal(`framework`)}).strict(),z.object({kind:z.literal(`extension`),namespace:z.string(),packageName:z.string()}).strict()])}).strict(),description:z.string(),entryPath:z.string(),exportName:z.string().optional(),logicalPath:z.string(),name:z.string(),nodeId:z.string(),owner:z.discriminatedUnion(`kind`,[z.object({kind:z.literal(`application`)}).strict(),z.object({feature:z.string(),kind:z.literal(`framework`)}).strict(),z.object({kind:z.literal(`extension`),namespace:z.string(),packageName:z.string()}).strict()]),parentNodeId:z.string(),outputSchema:jsonObjectSchema.optional(),path:z.string(),rootPath:z.string(),sourceId:z.string(),sourceKind:z.literal(`module`),url:z.string().optional()}).strict();export{compiledRemoteAgentNodeSchema};

package/dist/src/compiler/source-graph.d.ts

@@ -0,0 +1,153 @@
+import { type JsonObject } from "#shared/json.js";
+export type ProgrammaticModuleNamespace = Readonly<Record<string, unknown>>;
+export interface ProgrammaticModuleLoadContext {
+    readonly dependencies: Readonly<Record<string, ProgrammaticModuleNamespace>>;
+    readonly parameters: JsonObject;
+}
+export interface ProgrammaticAgentModule {
+    readonly exportName?: string;
+    readonly loadNamespace: (context: ProgrammaticModuleLoadContext) => Promise<ProgrammaticModuleNamespace>;
+    readonly logicalPath: string;
+    readonly semanticRevision?: string;
+}
+export interface ProgrammaticAgentSource {
+    readonly id: string;
+    readonly modules: readonly ProgrammaticAgentModule[];
+    readonly revision: string;
+}
+export interface AgentSourceRegistration {
+    readonly applyTo: "root" | "all-local-nodes";
+    readonly source: ProgrammaticAgentSource;
+}
+export interface AgentSourceRegistryOptions {
+    readonly templates?: readonly ProgrammaticAgentSource[];
+}
+export interface RegisteredProgrammaticTemplate {
+    readonly module: ProgrammaticAgentModule;
+    readonly source: ProgrammaticAgentSource;
+}
+export interface AgentSourceRegistry {
+    readonly registrations: readonly AgentSourceRegistration[];
+    readonly sources: ReadonlyMap<string, ProgrammaticAgentSource>;
+    readonly templates: ReadonlyMap<string, RegisteredProgrammaticTemplate>;
+}
+export type AgentSourceOwner = {
+    readonly kind: "application";
+} | {
+    readonly feature: string;
+    readonly kind: "framework";
+} | {
+    readonly kind: "extension";
+    readonly namespace: string;
+    readonly packageName: string;
+};
+export type AgentSourceLayer = "framework-default" | "extension-package" | "extension-override" | "application";
+export type AgentSourceForm = "derived" | "direct";
+export type AgentModuleBacking = {
+    readonly externalDependencies: readonly string[];
+    readonly extensionScope?: {
+        readonly namespace: string;
+        readonly sourceRoot: string;
+    };
+    readonly kind: "filesystem";
+    readonly sourcePath: string;
+} | {
+    readonly dependencies?: Readonly<Record<string, string>>;
+    readonly kind: "programmatic";
+    readonly moduleId: string;
+    readonly parameters?: JsonObject;
+    readonly registryId: string;
+    readonly revision: string;
+    readonly semanticRevision?: string;
+};
+export type AgentSourceBacking = AgentModuleBacking | {
+    readonly kind: "resource";
+    readonly sourcePath: string;
+};
+export interface AgentModuleCandidate {
+    readonly backing: AgentModuleBacking;
+    readonly exportName?: string;
+    readonly form: AgentSourceForm;
+    readonly layer: AgentSourceLayer;
+    readonly logicalPath: string;
+    readonly nodeId: string;
+    readonly owner: AgentSourceOwner;
+    readonly sourceId: string;
+}
+export interface CompiledModuleBinding {
+    readonly backing: AgentModuleBacking;
+    readonly logicalPath: string;
+    readonly owner: AgentSourceOwner;
+}
+export interface AgentSourceDescriptor {
+    readonly backing: AgentSourceBacking;
+    readonly form: AgentSourceForm;
+    readonly layer: AgentSourceLayer;
+    readonly logicalPath: string;
+    readonly owner: AgentSourceOwner;
+    readonly sourceId: string;
+}
+export interface AgentResourceCandidate {
+    readonly backing: Extract<AgentSourceBacking, {
+        readonly kind: "resource";
+    }>;
+    readonly form: AgentSourceForm;
+    readonly layer: AgentSourceLayer;
+    readonly logicalPath: string;
+    readonly nodeId: string;
+    readonly owner: AgentSourceOwner;
+    readonly sourceId: string;
+}
+export type AgentSourceCandidate = AgentModuleCandidate | AgentResourceCandidate;
+export type AgentSourceCompositionEntry = {
+    readonly kind: "shadowed";
+    readonly source: AgentSourceDescriptor;
+    readonly winnerSourceId: string;
+} | {
+    readonly kind: "disabled";
+    readonly source: AgentSourceDescriptor;
+};
+export interface AgentSourceComposition {
+    readonly entries: readonly AgentSourceCompositionEntry[];
+}
+export interface ComposedAgentModuleCandidates {
+    readonly composition: AgentSourceComposition;
+    readonly selected: ReadonlyMap<string, AgentSourceCandidate>;
+}
+export declare function defineProgrammaticAgentSource(input: ProgrammaticAgentSource): ProgrammaticAgentSource;
+export declare function createAgentSourceRegistry(registrations: readonly AgentSourceRegistration[], options?: AgentSourceRegistryOptions): AgentSourceRegistry;
+export declare function createProgrammaticModuleCandidates(input: {
+    readonly layer: AgentSourceLayer;
+    readonly nodeId: string;
+    readonly owner: AgentSourceOwner;
+    readonly registration: AgentSourceRegistration;
+}): readonly AgentModuleCandidate[];
+export declare function instantiateProgrammaticTemplate(input: {
+    readonly anchor: AgentModuleCandidate;
+    readonly dependencies: Readonly<Record<string, AgentModuleCandidate>>;
+    readonly logicalPath: string;
+    readonly owner: AgentSourceOwner;
+    readonly parameters?: JsonObject;
+    readonly template: RegisteredProgrammaticTemplate;
+}): AgentModuleCandidate;
+export declare function composeAgentModuleCandidates(candidates: readonly AgentSourceCandidate[]): ComposedAgentModuleCandidates;
+export declare function disableComposedCandidate(input: {
+    readonly candidate: AgentSourceCandidate;
+    readonly composed: ComposedAgentModuleCandidates;
+}): ComposedAgentModuleCandidates;
+export declare function createCompiledModuleBinding(candidate: AgentModuleCandidate): CompiledModuleBinding;
+export declare function loadProgrammaticModuleNamespace(input: {
+    readonly backing: Extract<AgentModuleBacking, {
+        readonly kind: "programmatic";
+    }>;
+    readonly dependencyNamespaces?: Readonly<Record<string, ProgrammaticModuleNamespace>>;
+    readonly registries: readonly AgentSourceRegistry[];
+}): Promise<ProgrammaticModuleNamespace>;
+export declare function canonicalModuleSlot(logicalPath: string): string;
+/**
+ * Canonical composition slot for one logical path. Module extensions, folder
+ * forms, and skill packages collapse onto the same authored primitive identity.
+ */
+export declare function canonicalSourceSlot(logicalPath: string): string;
+export declare function validateProgrammaticLogicalPath(input: string): string;
+export declare function describeAgentSourceCandidate(candidate: AgentSourceCandidate): AgentSourceDescriptor;

package/dist/src/compiler/source-graph.js

@@ -0,0 +1 @@
+import{isAbsolute,posix}from"node:path";import{getSupportedModuleBaseName,normalizeLogicalPath,stripLogicalPathExtension}from"#discover/filesystem.js";import{parseJsonObject}from"#shared/json.js";var ImmutableProgrammaticSourceMap=class{#e;constructor(e){this.#e=new Map(e),Object.freeze(this)}get size(){return this.#e.size}get[Symbol.toStringTag](){return`ImmutableProgrammaticSourceMap`}[Symbol.iterator](){return this.#e[Symbol.iterator]()}entries(){return this.#e.entries()}forEach(e,t){this.#e.forEach((n,r)=>e.call(t,n,r,this))}get(e){return this.#e.get(e)}has(e){return this.#e.has(e)}keys(){return this.#e.keys()}values(){return this.#e.values()}};const LAYER_PRECEDENCE={"framework-default":0,"extension-package":1,"extension-override":2,application:3},FORM_PRECEDENCE={derived:0,direct:1},registeredProgrammaticTemplates=new WeakSet;function defineProgrammaticAgentSource(e){let t=expectNonEmpty(e.id,`Programmatic agent source id`),n=expectNonEmpty(e.revision,`Programmatic agent source "${t}" revision`),r=new Set,i=e.modules.map(e=>{let n=validateProgrammaticLogicalPath(e.logicalPath);if(r.has(n))throw Error(`Programmatic agent source "${t}" declares "${n}" more than once.`);r.add(n);let i=e.semanticRevision===void 0?void 0:expectNonEmpty(e.semanticRevision,`Programmatic module "${t}:${n}" semanticRevision`);return Object.freeze({exportName:e.exportName,loadNamespace:e.loadNamespace,logicalPath:n,semanticRevision:i})});return Object.freeze({id:t,modules:Object.freeze(i),revision:n})}function createAgentSourceRegistry(e,t={}){let n=new Map,r=new Map,addSource=e=>{let t=defineProgrammaticAgentSource(e);if(n.has(t.id))throw Error(`Programmatic agent source id "${t.id}" is registered more than once.`);return n.set(t.id,t),t},i=e.map(e=>{let t=addSource(e.source);return Object.freeze({applyTo:e.applyTo,source:t})});for(let e of t.templates??[]){let t=addSource(e);if(t.modules.length!==1)throw Error(`Programmatic template source "${t.id}" must register exactly one module.`);let n=Object.freeze({module:t.modules[0],source:t});registeredProgrammaticTemplates.add(n),r.set(t.id,n)}return Object.freeze({registrations:Object.freeze(i),sources:new ImmutableProgrammaticSourceMap(n),templates:new ImmutableProgrammaticSourceMap(r)})}function createProgrammaticModuleCandidates(e){return e.registration.source.modules.map(t=>{let n=`${e.registration.source.id}:${t.logicalPath}`;return Object.freeze({backing:Object.freeze({kind:`programmatic`,moduleId:t.logicalPath,registryId:e.registration.source.id,revision:e.registration.source.revision,semanticRevision:t.semanticRevision}),exportName:t.exportName,form:`direct`,layer:e.layer,logicalPath:t.logicalPath,nodeId:e.nodeId,owner:e.owner,sourceId:n})})}function instantiateProgrammaticTemplate(e){if(!registeredProgrammaticTemplates.has(e.template))throw Error(`Derived programmatic modules require a registered template.`);let t=validateProgrammaticLogicalPath(e.logicalPath),n=expectNonEmpty(e.anchor.sourceId,`Derived programmatic module anchor source id`),r=`${e.template.source.id}:${t}:from:${n}`;if(!Object.values(e.dependencies).some(e=>e.sourceId===n))throw Error(`Derived programmatic module "${r}" must include its anchor source as a dependency.`);let i=Object.freeze(Object.fromEntries(Object.entries(e.dependencies).sort(([e],[t])=>e.localeCompare(t)).map(([t,n])=>{if(expectNonEmpty(t,`Derived programmatic module dependency alias`),n.nodeId!==e.anchor.nodeId)throw Error(`Derived programmatic module "${r}" cannot depend on source "${n.sourceId}" from another node.`);return[t,n.sourceId]}))),o=Object.freeze(parseJsonObject(e.parameters??{}));return Object.freeze({backing:Object.freeze({dependencies:i,kind:`programmatic`,moduleId:e.template.module.logicalPath,parameters:o,registryId:e.template.source.id,revision:e.template.source.revision,semanticRevision:e.template.module.semanticRevision}),exportName:e.template.module.exportName,form:`derived`,layer:e.anchor.layer,logicalPath:t,nodeId:e.anchor.nodeId,owner:e.owner,sourceId:r})}function composeAgentModuleCandidates(e){let t=new Map,n=new Set;for(let r of e){if(n.has(r.sourceId))throw Error(`Agent source id "${r.sourceId}" is declared more than once in node "${r.nodeId}".`);n.add(r.sourceId);let e=canonicalSourceSlot(r.logicalPath),i=t.get(e)??[];i.push(r),t.set(e,i)}let r=new Map,i=[];for(let[e,n]of[...t].sort(([e],[t])=>e.localeCompare(t))){let t=new Set;for(let r of n){let n=`${r.layer}:${r.form}`;if(t.has(n))throw Error(`Agent source slot "${e}" has more than one ${r.layer} ${r.form} candidate.`);t.add(n)}let a=[...n].sort((e,t)=>LAYER_PRECEDENCE[t.layer]-LAYER_PRECEDENCE[e.layer]||FORM_PRECEDENCE[t.form]-FORM_PRECEDENCE[e.form]),c=a[0];r.set(e,c);for(let e of a.slice(1))i.push({kind:`shadowed`,source:describeAgentSourceCandidate(e),winnerSourceId:c.sourceId})}return validateSelectedCandidateDependencies(r),{composition:{entries:Object.freeze(i)},selected:r}}function disableComposedCandidate(e){let t=canonicalSourceSlot(e.candidate.logicalPath),n=new Map(e.composed.selected);if(n.get(t)?.sourceId!==e.candidate.sourceId)throw Error(`Only the selected source for "${t}" can disable that slot.`);if(!e.composed.composition.entries.some(t=>t.kind===`shadowed`&&t.winnerSourceId===e.candidate.sourceId))throw Error(`Source "${e.candidate.logicalPath}" disables a slot with no lower-precedence source.`);return n.delete(t),{composition:{entries:Object.freeze([...e.composed.composition.entries,{kind:`disabled`,source:describeAgentSourceCandidate(e.candidate)}])},selected:n}}function createCompiledModuleBinding(e){return Object.freeze({backing:e.backing,logicalPath:e.logicalPath,owner:e.owner})}async function loadProgrammaticModuleNamespace(e){let t=e.registries.map(t=>t.sources.get(e.backing.registryId)).filter(e=>e!==void 0);if(t.length!==1)throw Error(`Expected exactly one registered programmatic source "${e.backing.registryId}", found ${t.length}.`);let n=t[0];if(n.revision!==e.backing.revision)throw Error(`Programmatic source "${n.id}" revision mismatch: artifact requires "${e.backing.revision}", registry provides "${n.revision}".`);let r=n.modules.find(t=>t.logicalPath===e.backing.moduleId);if(r===void 0)throw Error(`Programmatic source "${n.id}" does not register module "${e.backing.moduleId}".`);if(r.semanticRevision!==e.backing.semanticRevision)throw Error(`Programmatic module "${n.id}:${r.logicalPath}" semantic revision does not match the compiled binding.`);let i=Object.fromEntries(Object.entries(e.backing.dependencies??{}).map(([t,i])=>{let a=e.dependencyNamespaces?.[t];if(a===void 0)throw Error(`Programmatic module "${n.id}:${r.logicalPath}" requires unresolved binding "${i}" as dependency "${t}".`);return[t,a]})),a=await r.loadNamespace({dependencies:Object.freeze(i),parameters:Object.freeze(e.backing.parameters??{})});if(typeof a!=`object`||!a)throw Error(`Programmatic module "${n.id}:${r.logicalPath}" loader must return a module namespace object.`);return a}function canonicalModuleSlot(e){return validateProgrammaticLogicalPath(e),canonicalSourceSlot(e)}function canonicalSourceSlot(e){let n=normalizeLogicalPath(e);if(n.length===0||n===`.`||n.startsWith(`../`)||n.includes(`/../`)||posix.normalize(n)!==n)throw Error(`Agent source logical path "${e}" is invalid.`);let a=stripLogicalPathExtension(n),o=a.match(/^connections\/([^/]+)\/connection$/);if(o!==null)return`connections/${o[1]}`;if(a===`sandbox/sandbox`)return`sandbox`;let s=a.match(/^skills\/([^/]+)\/SKILL$/);return s===null?a:`skills/${s[1]}`}function validateProgrammaticLogicalPath(a){if(a.length===0||isAbsolute(a)||a.includes(`\\`))throw Error(`Programmatic module logical path "${a}" must be a relative POSIX path.`);let o=normalizeLogicalPath(a);if(o===`.`||o.startsWith(`../`)||o.includes(`/../`)||posix.normalize(o)!==o)throw Error(`Programmatic module logical path "${a}" may not traverse directories.`);let s=o.split(`/`),c=s.at(-1);if(getSupportedModuleBaseName(c)===null)throw Error(`Programmatic module logical path "${a}" must use a supported JavaScript or TypeScript extension.`);let l=s[0],u=stripLogicalPathExtension(o);if(!(s.length===1&&[`agent`,`sandbox`,`instrumentation`].includes(u)||l===`sandbox`&&s.length===2&&getSupportedModuleBaseName(c)===`sandbox`||[`channels`,`connections`,`hooks`,`instructions`,`schedules`,`skills`,`tools`].includes(l)&&s.length>=2))throw Error(`Programmatic module logical path "${a}" does not select an eve module slot.`);return o}function describeAgentSourceCandidate(e){return Object.freeze({backing:e.backing,form:e.form,layer:e.layer,logicalPath:e.logicalPath,owner:e.owner,sourceId:e.sourceId})}function validateSelectedCandidateDependencies(e){let t=new Set([...e.values()].map(e=>e.sourceId));for(let n of e.values())if(n.backing.kind===`programmatic`){for(let e of Object.values(n.backing.dependencies??{}))if(!t.has(e))throw Error(`Derived programmatic source "${n.sourceId}" depends on unselected source "${e}".`)}}function expectNonEmpty(e,t){if(e.trim().length===0)throw Error(`${t} must be non-empty.`);return e}export{canonicalModuleSlot,canonicalSourceSlot,composeAgentModuleCandidates,createAgentSourceRegistry,createCompiledModuleBinding,createProgrammaticModuleCandidates,defineProgrammaticAgentSource,describeAgentSourceCandidate,disableComposedCandidate,instantiateProgrammaticTemplate,loadProgrammaticModuleNamespace,validateProgrammaticLogicalPath};

package/dist/src/compiler/validate-artifact.d.ts

@@ -0,0 +1,17 @@
+import type { CompiledAgentManifest, CompiledAgentNodeManifest, CompiledAgentResources } from "#compiler/manifest.js";
+import type { CompiledModuleMap } from "#compiler/module-map.js";
+type CompiledNode = CompiledAgentNodeManifest | CompiledAgentResources;
+/** Validates invariants that cannot be expressed by the serialized Zod shape. */
+export declare function validateCompiledAgentManifest(manifest: CompiledAgentManifest): void;
+/** Validates exact module-map parity with the manifest's required binding tables. */
+export declare function validateCompiledModuleMap(manifest: CompiledAgentManifest, moduleMap: CompiledModuleMap): void;
+/** Validates one node's bindings, composition, and route-plan integrity. */
+export declare function validateCompiledAgentResources(node: CompiledNode, options?: {
+    readonly additionalModuleSources?: readonly {
+        readonly logicalPath: string;
+        readonly sourceId: string;
+    }[];
+    readonly activeResourceSourceIds?: readonly string[];
+    readonly allowUnknownResourceWinners?: boolean;
+}): void;
+export {};

package/dist/src/compiler/validate-artifact.js

@@ -0,0 +1 @@
+import{ROOT_COMPILED_AGENT_NODE_ID}from"#compiler/manifest.js";import{collectModuleBindingsForManifest}from"#compiler/module-map.js";import{HOST_HTTP_INVENTORY}from"#framework/host-inventory.js";function validateCompiledAgentManifest(t){let n=new Map([[ROOT_COMPILED_AGENT_NODE_ID,t]]);for(let e of t.subagents)n.has(e.nodeId)&&fail(`subagent node id "${e.nodeId}" is duplicated`),n.set(e.nodeId,e.agent),validateSubagentRecord(e);validateSubagentTree(t,n),validateCompiledAgentResources(t,{activeResourceSourceIds:t.subagents.filter(t=>t.parentNodeId===ROOT_COMPILED_AGENT_NODE_ID).map(e=>e.sourceId)});for(let e of t.subagents)validateCompiledAgentResources(e.agent,{additionalModuleSources:e.configResolver===void 0?[]:[e.configResolver],activeResourceSourceIds:t.subagents.filter(t=>t.parentNodeId===e.nodeId).map(e=>e.sourceId)});for(let[e,r]of n)validateUniqueIdentities([...r.tools.map(e=>({identity:e.name,kind:`tool`})),...r.remoteAgents.map(e=>({identity:e.name,kind:`remote agent`})),...t.subagents.filter(t=>t.parentNodeId===e).map(e=>({identity:e.name,kind:`local agent`}))],`tool and subagent public name`)}function validateSubagentTree(t,n){let r=new Map(t.subagents.map(e=>[e.nodeId,e.parentNodeId]));for(let i of t.subagents){n.has(i.parentNodeId)||fail(`subagent node "${i.nodeId}" has missing parent "${i.parentNodeId}"`);let t=new Set,a=i.nodeId;for(;a!==ROOT_COMPILED_AGENT_NODE_ID;){t.has(a)&&fail(`subagent graph contains a cycle at node "${a}"`),t.add(a);let e=r.get(a);e===void 0&&fail(`subagent node "${i.nodeId}" is not reachable from the root`),a=e}}}function validateCompiledModuleMap(e,n){let r=new Map([[`__root__`,new Set(collectModuleBindingsForManifest(e).map(e=>e.sourceId))],...e.subagents.map(e=>[e.nodeId,new Set(collectModuleBindingsForManifest(e.agent).map(e=>e.sourceId))])]),i=Object.keys(n.nodes);(i.length!==r.size||i.some(e=>!r.has(e)))&&fail(`compiled module map node set does not match the manifest`);for(let[e,t]of r){let r=n.nodes[e];r===void 0&&fail(`compiled module map node "${e}" is missing`);let i=Object.keys(r.modules);(i.length!==t.size||i.some(e=>!t.has(e)))&&fail(`compiled module map sources for node "${e}" do not match its bindings`)}}function validateCompiledAgentResources(e,t={}){validateUniqueIdentities(e.tools.map(e=>({identity:e.name,kind:`tool`})),`tool name`),validateUniqueIdentities(e.dynamicTools.map(e=>({identity:e.slug,kind:`dynamic tool`})),`dynamic tool slug`),validateUniqueIdentities(e.skills.map(e=>({identity:e.name,kind:`skill`})),`skill name`),validateUniqueIdentities(e.dynamicSkills.map(e=>({identity:e.slug,kind:`dynamic skill`})),`dynamic skill slug`),validateUniqueIdentities(e.instructions.map(e=>({identity:e.name,kind:`instructions`})),`instructions name`),validateUniqueIdentities(e.dynamicInstructions.map(e=>({identity:e.slug,kind:`dynamic instructions`})),`dynamic instructions slug`),validateUniqueIdentities(e.connections.map(e=>({identity:e.connectionName,kind:`connection`})),`connection name`),validateUniqueIdentities(e.hooks.map(e=>({identity:e.slug,kind:`hook`})),`hook slug`),validateUniqueIdentities(e.schedules.map(e=>({identity:e.name,kind:`schedule`})),`schedule name`);let n=collectReferencedModuleSources(e);for(let e of t.additionalModuleSources??[])n.set(e.sourceId,{logicalPath:e.logicalPath});for(let[t,r]of n){let n=e.bindings[t];n===void 0&&fail(`module source "${t}" has no compiled binding`),validateBinding(t,r.logicalPath,n)}for(let t of Object.keys(e.bindings))n.has(t)||fail(`compiled binding "${t}" is not referenced by its node manifest`);validateProgrammaticBindingDependencies(e.bindings);let r=new Set([...n.keys(),...collectActiveResourceSourceIds(e),...e.remoteAgents.map(e=>e.sourceId),...t.activeResourceSourceIds??[]]),i=new Set;for(let n of e.sourceComposition.entries){if(n.kind===`disabled`){i.has(n.source.sourceId)&&fail(`disabled composition source "${n.source.sourceId}" is duplicated`),i.add(n.source.sourceId),e.bindings[n.source.sourceId]!==void 0&&fail(`disabled source "${n.source.sourceId}" retains an active binding`);continue}!r.has(n.winnerSourceId)&&!i.has(n.winnerSourceId)&&!e.sourceComposition.entries.some(e=>e.kind===`disabled`&&e.source.sourceId===n.winnerSourceId)&&t.allowUnknownResourceWinners!==!0&&fail(`shadowed source "${n.source.sourceId}" has dangling winner "${n.winnerSourceId}"`)}validateChannelRoutePlan(e);for(let t of e.remoteAgents)validateBinding(t.sourceId,t.logicalPath,t.binding),t.parentNodeId.length===0&&fail(`remote agent "${t.sourceId}" has no parent`)}function validateSubagentRecord(e){if((e.backing.kind!==`resource`||e.backing.sourcePath.length===0)&&fail(`subagent "${e.nodeId}" has no physical resource backing`),e.parentNodeId.length===0&&fail(`subagent "${e.nodeId}" has no parent`),e.configResolver!==void 0){let t=e.agent.bindings[e.configResolver.sourceId];t===void 0&&fail(`dynamic subagent "${e.nodeId}" config resolver has no binding`),validateBinding(e.configResolver.sourceId,e.configResolver.logicalPath,t)}}function validateBinding(e,t,n){n.logicalPath!==t&&fail(`compiled binding "${e}" targets "${n.logicalPath}", not "${t}"`),n.owner.kind===`extension`&&n.backing.kind===`filesystem`&&n.backing.extensionScope===void 0&&fail(`extension-owned filesystem binding "${e}" has no extension scope`)}function validateProgrammaticBindingDependencies(e){let t=new Set,n=new Set,visit=r=>{if(n.has(r))return;t.has(r)&&fail(`programmatic binding dependency cycle includes "${r}"`);let i=e[r];if(i===void 0&&fail(`programmatic binding dependency "${r}" is missing`),t.add(r),i.backing.kind===`programmatic`)for(let[t,n]of Object.entries(i.backing.dependencies??{}))t.trim().length===0&&fail(`programmatic binding "${r}" has an empty dependency alias`),e[n]===void 0&&fail(`programmatic binding "${r}" depends on missing binding "${n}"`),visit(n);t.delete(r),n.add(r)};for(let t of Object.keys(e))visit(t)}function collectReferencedModuleSources(e){let t=new Map,add=e=>{let n=t.get(e.sourceId);n!==void 0&&n.logicalPath!==e.logicalPath&&fail(`module source "${e.sourceId}" is referenced with two logical paths`),t.set(e.sourceId,{logicalPath:e.logicalPath})};`config`in e&&(add(e.config.source),e.config.model?.source!==void 0&&add(e.config.model.source),e.config.dynamicModel!==void 0&&add(e.config.dynamicModel));for(let t of e.channelRoutes.effective)add(t);for(let t of e.channelRoutes.shadowed)t.source.backing.kind!==`resource`&&add(t.source);for(let t of e.connections)add(t);for(let t of e.tools)add(t);for(let t of e.dynamicInstructions)add(t);for(let t of e.dynamicSkills)add(t);for(let t of e.dynamicTools)add(t);for(let t of e.hooks)add(t);for(let t of e.instructions)t.sourceKind===`module`&&add(t);e.instrumentation!==void 0&&add(e.instrumentation),e.workflowTool!==void 0&&add(e.workflowTool);for(let t of e.skills)t.sourceKind===`module`&&add(t);for(let t of e.schedules)t.sourceKind===`module`&&add(t);add(e.sandbox);for(let t of e.extensionMounts)add({logicalPath:t.mountLogicalPath,sourceId:t.mountSourceId});return t}function collectActiveResourceSourceIds(e){return[...e.instructions.filter(e=>e.sourceKind!==`module`).map(e=>e.sourceId),...e.skills.filter(e=>e.sourceKind!==`module`).map(e=>e.sourceId),...e.schedules.filter(e=>e.sourceKind!==`module`).map(e=>e.sourceId),...e.sandboxWorkspaces.map(e=>e.sourceId)]}function validateChannelRoutePlan(e){let t=new Set,r=new Set;for(let i of e.channelRoutes.effective){let a=routeIdentity(i);t.has(a)&&fail(`effective channel route "${a}" is duplicated`),t.add(a),r.add(i.sourceId),e.bindings[i.sourceId]===void 0&&fail(`effective channel route source "${i.sourceId}" has no binding`),HOST_HTTP_INVENTORY.find(e=>methodsOverlap(i.method,e.method)&&patternsOverlap(i.urlPath,e.path))!==void 0&&fail(`effective route ${i.method} ${i.urlPath} overlaps reserved host route`)}for(let t of e.channelRoutes.shadowed)r.has(t.winnerSourceId)||fail(`shadowed channel route has dangling winner "${t.winnerSourceId}"`);let i=new Set;for(let t of e.channelRoutes.preflight){let n=normalizePattern(t.urlPath);i.has(n)&&fail(`generated preflight "${n}" is duplicated`),i.add(n),t.sourceIds.length===0&&fail(`generated preflight "${n}" has no causes`);for(let r of t.sourceIds)e.channelRoutes.effective.find(e=>e.sourceId===r&&e.cors!==void 0&&e.method!==`WEBSOCKET`&&patternsOverlap(e.urlPath,t.urlPath))===void 0&&fail(`generated preflight "${n}" has invalid cause "${r}"`)}}function routeIdentity(e){return`${e.method} ${normalizePattern(e.urlPath)}`}function normalizePattern(e){return splitPath(e).map(e=>isParameter(e)?`:`:e).join(`/`)}function patternsOverlap(e,t){let n=splitPath(e),r=splitPath(t);return n.length===r.length&&n.every((e,t)=>e===r[t]||isParameter(e)||isParameter(r[t]))}function splitPath(e){return e.replace(/^\/+|\/+$/g,``).split(`/`)}function isParameter(e){return e.startsWith(`:`)||/^\[[^\]]+\]$/.test(e)}function methodsOverlap(e,t){return e===`ALL`||t===`ALL`||e===t}function validateUniqueIdentities(e,t){let n=new Map;for(let r of e){let e=n.get(r.identity);e!==void 0&&fail(`${t} "${r.identity}" is shared by ${e} and ${r.kind}`),n.set(r.identity,r.kind)}}function fail(e){throw Error(`Invalid compiled eve artifact: ${e}.`)}export{validateCompiledAgentManifest,validateCompiledAgentResources,validateCompiledModuleMap};

package/dist/src/compiler/workspace-resources.js

@@ -1 +1 @@
-import{createHash}from"node:crypto";import{cp,mkdir,readFile,readdir,rm}from"node:fs/promises";import{join,posix}from"node:path";import{normalizeLogicalPath}from"#discover/filesystem.js";import{ROOT_COMPILED_AGENT_NODE_ID,deriveResourceRootEntries}from"#compiler/manifest.js";import{normalizeSkillPackage,writeSkillPackageDirectory}from"#shared/skill-package.js";const RESOURCES_DIRECTORY=`workspace-resources`;async function materializeWorkspaceResources(e){let t=join(e.compileDirectoryPath,RESOURCES_DIRECTORY);await rm(t,{force:!0,recursive:!0});let n=await materializeNode({nodeId:ROOT_COMPILED_AGENT_NODE_ID,resourcesRoot:t,manifest:e.manifest}),r=await Promise.all(e.manifest.subagents.map(async e=>e.configResolver===void 0?{...e,agent:await materializeNode({nodeId:e.nodeId,resourcesRoot:t,manifest:e.agent})}:{...e,agent:await materializeNode({nodeId:e.nodeId,resourcesRoot:t,manifest:e.agent}),configResolver:e.configResolver}));return{...n,kind:e.manifest.kind,extensionMounts:e.manifest.extensionMounts,subagentEdges:e.manifest.subagentEdges,subagents:r,version:e.manifest.version}}function createResourceRoot(e,t,n){return{contentHash:n,logicalPath:normalizeLogicalPath(join(RESOURCES_DIRECTORY,t)),rootEntries:deriveResourceRootEntries({sandboxWorkspaces:e.sandboxWorkspaces,skills:e.skills})}}async function materializeNode(e){let t=join(e.resourcesRoot,e.nodeId);await mkdir(t,{recursive:!0});let r=join(t,`workspace`);for(let t of e.manifest.sandboxWorkspaces)await copyDirectoryContents({sourcePath:t.sourcePath,targetPath:r});for(let n of e.manifest.skills)await materializeSkill({nodeRoot:t,skill:n});let i=await hashWorkspaceResourceRoot(t);return{...e.manifest,skills:e.manifest.skills.map(stripSkillPackageFiles),workspaceResourceRoot:createResourceRoot(e.manifest,e.nodeId,i)}}async function materializeSkill(e){let n=join(e.nodeRoot,`skills`,e.skill.name);if(e.skill.sourceKind===`skill-package`){await cp(e.skill.rootPath,n,{recursive:!0});return}await writeSkillPackageDirectory({rootPath:e.nodeRoot,skill:normalizeSkillPackage(e.skill)})}function stripSkillPackageFiles(e){let{files:t,...n}=e;return n}async function copyDirectoryContents(e){let r=await readdir(e.sourcePath,{withFileTypes:!0});await mkdir(e.targetPath,{recursive:!0});for(let n of r)!n.isDirectory()&&!n.isFile()||await cp(join(e.sourcePath,n.name),join(e.targetPath,n.name),{recursive:!0})}async function hashWorkspaceResourceRoot(t){let n=await listWorkspaceResourceFiles({logicalDirectoryPath:`.`,sourceDirectoryPath:t});if(n.sort((e,t)=>e.logicalPath.localeCompare(t.logicalPath)),n.length===0)return;let i=createHash(`sha256`);i.update(`eve-workspace-resource-root-v1\0`);for(let e of n){let t=await readFile(e.sourcePath);i.update(e.logicalPath),i.update(`\0`),i.update(String(t.byteLength)),i.update(`\0`),i.update(t),i.update(`\0`)}return i.digest(`hex`)}async function listWorkspaceResourceFiles(e){let t=[],n=await readdir(e.sourceDirectoryPath,{withFileTypes:!0});for(let r of n){if(!r.isDirectory()&&!r.isFile())continue;let n=join(e.sourceDirectoryPath,r.name),i=posix.join(e.logicalDirectoryPath,r.name);if(r.isDirectory()){t.push(...await listWorkspaceResourceFiles({logicalDirectoryPath:i,sourceDirectoryPath:n}));continue}t.push({logicalPath:i,sourcePath:n})}return t}export{materializeWorkspaceResources};
+import{createHash}from"node:crypto";import{cp,mkdir,readFile,readdir,rm}from"node:fs/promises";import{join,posix}from"node:path";import{normalizeLogicalPath}from"#discover/filesystem.js";import{ROOT_COMPILED_AGENT_NODE_ID,deriveResourceRootEntries}from"#compiler/manifest.js";import{normalizeSkillPackage,writeSkillPackageDirectory}from"#shared/skill-package.js";const RESOURCES_DIRECTORY=`workspace-resources`;async function materializeWorkspaceResources(e){let t=join(e.compileDirectoryPath,RESOURCES_DIRECTORY);await rm(t,{force:!0,recursive:!0});let n=await materializeNode({nodeId:ROOT_COMPILED_AGENT_NODE_ID,resourcesRoot:t,manifest:e.manifest}),r=await Promise.all(e.manifest.subagents.map(async e=>e.configResolver===void 0?{...e,agent:await materializeNode({nodeId:e.nodeId,resourcesRoot:t,manifest:e.agent})}:{...e,agent:await materializeNode({nodeId:e.nodeId,resourcesRoot:t,manifest:e.agent}),configResolver:e.configResolver}));return{...n,kind:e.manifest.kind,extensionMounts:e.manifest.extensionMounts,subagents:r,version:e.manifest.version}}function createResourceRoot(e,t,n){return{contentHash:n,logicalPath:normalizeLogicalPath(join(RESOURCES_DIRECTORY,t)),rootEntries:deriveResourceRootEntries({sandboxWorkspaces:e.sandboxWorkspaces,skills:e.skills})}}async function materializeNode(e){let t=join(e.resourcesRoot,e.nodeId);await mkdir(t,{recursive:!0});let r=join(t,`workspace`);for(let t of e.manifest.sandboxWorkspaces)await copyDirectoryContents({sourcePath:t.sourcePath,targetPath:r});for(let n of e.manifest.skills)await materializeSkill({nodeRoot:t,skill:n});let i=await hashWorkspaceResourceRoot(t);return{...e.manifest,skills:e.manifest.skills.map(stripSkillPackageFiles),workspaceResourceRoot:createResourceRoot(e.manifest,e.nodeId,i)}}async function materializeSkill(e){let n=join(e.nodeRoot,`skills`,e.skill.name);if(e.skill.sourceKind===`skill-package`){await cp(e.skill.rootPath,n,{recursive:!0});return}await writeSkillPackageDirectory({rootPath:e.nodeRoot,skill:normalizeSkillPackage(e.skill)})}function stripSkillPackageFiles(e){let{files:t,...n}=e;return n}async function copyDirectoryContents(e){let r=await readdir(e.sourcePath,{withFileTypes:!0});await mkdir(e.targetPath,{recursive:!0});for(let n of r)!n.isDirectory()&&!n.isFile()||await cp(join(e.sourcePath,n.name),join(e.targetPath,n.name),{recursive:!0})}async function hashWorkspaceResourceRoot(t){let n=await listWorkspaceResourceFiles({logicalDirectoryPath:`.`,sourceDirectoryPath:t});if(n.sort((e,t)=>e.logicalPath.localeCompare(t.logicalPath)),n.length===0)return;let i=createHash(`sha256`);i.update(`eve-workspace-resource-root-v1\0`);for(let e of n){let t=await readFile(e.sourcePath);i.update(e.logicalPath),i.update(`\0`),i.update(String(t.byteLength)),i.update(`\0`),i.update(t),i.update(`\0`)}return i.digest(`hex`)}async function listWorkspaceResourceFiles(e){let t=[],n=await readdir(e.sourceDirectoryPath,{withFileTypes:!0});for(let r of n){if(!r.isDirectory()&&!r.isFile())continue;let n=join(e.sourceDirectoryPath,r.name),i=posix.join(e.logicalDirectoryPath,r.name);if(r.isDirectory()){t.push(...await listWorkspaceResourceFiles({logicalDirectoryPath:i,sourceDirectoryPath:n}));continue}t.push({logicalPath:i,sourcePath:n})}return t}export{materializeWorkspaceResources};

package/dist/src/connections/errors.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Typed error classes for the connection authorization lifecycle.
+ */
+/**
+ * User-facing authorization challenge payload.
+ */
+export interface ConnectionAuthorizationChallenge {
+    /**
+     * Optional URL the user should visit to complete authorization.
+     * Serves as the redirect target, the verification URL in device
+     * code flow, or the source for a QR code.
+     */
+    readonly url?: string;
+    /**
+     * Optional short code to display alongside `url` (device code flow).
+     */
+    readonly userCode?: string;
+    /**
+     * Optional ISO timestamp at which the authorization opportunity
+     * expires. When provided, the runtime clamps the authorization deadline to
+     * `min(configured_timeout, expiresAt)` so the turn cannot outlive
+     * the challenge.
+     */
+    readonly expiresAt?: string;
+    /**
+     * Optional human-readable call to action. When no `url` is
+     * available (e.g. CIBA, push-to-approve), this is what the channel
+     * should show as the primary affordance.
+     */
+    readonly instructions?: string;
+    /**
+     * Optional human-readable provider name for sign-in UI (e.g.
+     * `"Salesforce"`). Presentation-only: identity (the authorization
+     * scope, token cache keys, callback URLs) stays the path-derived
+     * name. Channels fall back to title-casing the scope name when
+     * absent.
+     */
+    readonly displayName?: string;
+}
+/**
+ * Options accepted by {@link ConnectionAuthorizationRequiredError}.
+ */
+export interface ConnectionAuthorizationRequiredErrorOptions {
+    /**
+     * Override for the default `Error.message`. Defaults to
+     * `Connection "{name}" requires authorization.` when omitted.
+     */
+    readonly message?: string;
+}
+/**
+ * Options accepted by {@link ConnectionAuthorizationFailedError}.
+ */
+export interface ConnectionAuthorizationFailedErrorOptions {
+    /**
+     * Override for the default `Error.message`. Defaults to
+     * `Connection "{name}" authorization failed.` when omitted.
+     */
+    readonly message?: string;
+    /**
+     * Stable machine-readable code describing why authorization failed.
+     *
+     * The runtime surfaces this code on the `authorization.completed`
+     * stream event and on the failed tool result the model sees. Use a
+     * short kebab- or snake-cased string (e.g. `"access_denied"`,
+     * `"invalid_grant"`).
+     *
+     * The runtime also emits a few reason codes itself, independently
+     * of authored throws:
+     *
+     * - `"principal_required"`: a `principalType: "user"` connection
+     *   was invoked without an authenticated user principal. Terminal.
+     * - `"app_not_installed"`: an authored `getToken` for a
+     *   `principalType: "app"` connection signalled the agent's own
+     *   credentials are missing. Terminal.
+     */
+    readonly reason?: string;
+    /**
+     * Controls whether the runtime re-prompts the user after this
+     * failure.
+     *
+     * Defaults to `true`; set `false` for terminal cases such as user
+     * denial (`reason: "access_denied"`).
+     */
+    readonly retryable?: boolean;
+}
+/**
+ * Thrown from a connection's `getToken` when no valid credential is
+ * available and authorization must be completed before the connection
+ * can be used. Covers both interactive OAuth (the runtime emits
+ * `authorization.required` and suspends the turn on a webhook) and
+ * non-interactive / out-of-band flows such as static API keys (the
+ * runtime emits `authorization.required` without suspending).
+ */
+export declare class ConnectionAuthorizationRequiredError extends Error {
+    readonly connectionName: string;
+    constructor(connectionName: string, options?: ConnectionAuthorizationRequiredErrorOptions);
+}
+/**
+ * Thrown when a connection's authorization fails.
+ *
+ * Retryable by default; pass `retryable: false` for terminal failures
+ * where starting a fresh authorization flow would be wrong.
+ */
+export declare class ConnectionAuthorizationFailedError extends Error {
+    readonly connectionName: string;
+    readonly reason?: string;
+    readonly retryable: boolean;
+    constructor(connectionName: string, options?: ConnectionAuthorizationFailedErrorOptions);
+}
+/**
+ * Type guard for {@link ConnectionAuthorizationRequiredError}.
+ *
+ * Uses `err.name` rather than `instanceof` because user code and
+ * framework internals can end up with different class identities
+ * after bundling (dual-instance hazard in Nitro output).
+ */
+export declare function isConnectionAuthorizationRequiredError(err: unknown): err is ConnectionAuthorizationRequiredError;
+/**
+ * Type guard for {@link ConnectionAuthorizationFailedError}.
+ *
+ * Uses `err.name` rather than `instanceof` because user code and
+ * framework internals can end up with different class identities
+ * after bundling (dual-instance hazard in Nitro output).
+ */
+export declare function isConnectionAuthorizationFailedError(err: unknown): err is ConnectionAuthorizationFailedError;

package/dist/src/connections/errors.js

@@ -0,0 +1 @@
+var ConnectionAuthorizationRequiredError=class extends Error{connectionName;constructor(e,t){super(t?.message??`Connection "${e}" requires authorization.`),this.name=`ConnectionAuthorizationRequiredError`,this.connectionName=e}},ConnectionAuthorizationFailedError=class extends Error{connectionName;reason;retryable;constructor(e,t){super(t?.message??`Connection "${e}" authorization failed.`),this.name=`ConnectionAuthorizationFailedError`,this.connectionName=e,this.reason=t?.reason,this.retryable=t?.retryable??!0}};function isConnectionAuthorizationRequiredError(e){return e instanceof Error&&e.name===`ConnectionAuthorizationRequiredError`}function isConnectionAuthorizationFailedError(e){return e instanceof Error&&e.name===`ConnectionAuthorizationFailedError`}export{ConnectionAuthorizationFailedError,ConnectionAuthorizationRequiredError,isConnectionAuthorizationFailedError,isConnectionAuthorizationRequiredError};

package/dist/src/context/build-base-tool-context.d.ts

@@ -1,5 +1,5 @@
-import type { SessionContext } from "#public/definitions/callback-context.js";
-import type { ToolExecuteOptions } from "#shared/tool-definition.js";
+import type { SessionContext } from "#context/session-context.js";
+import type { ToolExecuteOptions } from "#tools/definition.js";
 /** Base context shared by tool executors. */
 export type BaseToolContext = SessionContext & {
     readonly abortSignal: AbortSignal;

package/dist/src/context/build-callback-context.d.ts

@@ -1,4 +1,4 @@
-import type { SessionContext } from "#public/definitions/callback-context.js";
+import type { SessionContext } from "#context/session-context.js";
 /**
  * Builds a {@link SessionContext} from the active ALS scope.
  *

package/dist/src/context/build-dynamic-tools.js

@@ -1 +1 @@
-import{createLogger}from"#internal/logging.js";import{SessionDynamicToolMetadataKey,StepDynamicToolMetadataKey,TurnDynamicToolMetadataKey}from"#context/keys.js";import{toInputSchema,toOutputSchema}from"#shared/tool-schema.js";import{createToolExecuteWithAuth}from"#execution/tool-auth.js";import{callDurableDynamicCallback,lookupDurableDynamicCallback}from"#shared/durable-dynamic-tool-callbacks.js";const log=createLogger(`dynamic-tools`);function missingCallbackError(e,t){return Error(`Dynamic tool "${e.name}" cannot replay its ${t} callback because it is not registered in this process. The tool was removed or renamed since this call was parked, or its resolver did not run. Restore the tool definition or start a new session.`)}function buildReplayedApproval(e){let t=e.callbacks.approvalRequest;if(t===void 0)return;let n=lookupDurableDynamicCallback(e.name,`approvalRequest`),r=n===void 0?async()=>(log.error(missingCallbackError(e,`approvalRequest`).message),`user-approval`):async e=>await callDurableDynamicCallback(n,t.closure,e),i=e.callbacks.approvalResponse;if(i===void 0)return r;let a=lookupDurableDynamicCallback(e.name,`approvalResponse`);return{request:r,response:a===void 0?async()=>{let t=missingCallbackError(e,`approvalResponse`);return log.error(t.message),{reason:t.message,status:`rejected`}}:async e=>await callDurableDynamicCallback(a,i.closure,e)}}function replayDynamicTools(e){return e.map(e=>{let t=e.callbacks.execute,n=lookupDurableDynamicCallback(e.name,`execute`),r=e.callbacks.toModelOutput,s=r===void 0?void 0:lookupDurableDynamicCallback(e.name,`toModelOutput`);return{description:e.description,execute:createToolExecuteWithAuth({scope:e.name,execute:(r,i)=>{if(n===void 0)throw missingCallbackError(e,`execute`);return callDurableDynamicCallback(n,t.closure,r,i)}}),inputSchema:toInputSchema(e.inputSchema),name:e.name,approval:buildReplayedApproval(e),outputSchema:toOutputSchema(e.outputSchema),...r===void 0?{}:{toModelOutput:t=>{if(s===void 0)throw missingCallbackError(e,`toModelOutput`);return callDurableDynamicCallback(s,r.closure,t)}}}})}function buildResponseAuthorizationTools(e){let t=new Map;for(let n of e.context===void 0?[]:buildDynamicTools(e.context))t.has(n.name)||t.set(n.name,n);for(let[n,r]of e.authoredTools)t.has(n)||t.set(n,r);return t}function buildDynamicTools(e){let i=replayDynamicTools(e.get(StepDynamicToolMetadataKey)??[]),a=replayDynamicTools(e.get(TurnDynamicToolMetadataKey)??[]),o=replayDynamicTools(e.get(SessionDynamicToolMetadataKey)??[]);return[...i,...a,...o]}export{buildDynamicTools,buildResponseAuthorizationTools,replayDynamicTools};
+import{createLogger}from"#internal/logging.js";import{SessionDynamicToolMetadataKey,StepDynamicToolMetadataKey,TurnDynamicToolMetadataKey}from"#context/keys.js";import{toInputSchema,toOutputSchema}from"#tools/schema.js";import{createToolExecuteWithAuth}from"#execution/tool-auth.js";import{callDurableDynamicCallback,lookupDurableDynamicCallback}from"#tools/durable-callbacks.js";const log=createLogger(`dynamic-tools`);function missingCallbackError(e,t){return Error(`Dynamic tool "${e.name}" cannot replay its ${t} callback because it is not registered in this process. The tool was removed or renamed since this call was parked, or its resolver did not run. Restore the tool definition or start a new session.`)}function buildReplayedApproval(e){let t=e.callbacks.approvalRequest;if(t===void 0)return;let n=lookupDurableDynamicCallback(e.name,`approvalRequest`),r=n===void 0?async()=>(log.error(missingCallbackError(e,`approvalRequest`).message),`user-approval`):async e=>await callDurableDynamicCallback(n,t.closure,e),i=e.callbacks.approvalResponse;if(i===void 0)return r;let a=lookupDurableDynamicCallback(e.name,`approvalResponse`);return{request:r,response:a===void 0?async()=>{let t=missingCallbackError(e,`approvalResponse`);return log.error(t.message),{reason:t.message,status:`rejected`}}:async e=>await callDurableDynamicCallback(a,i.closure,e)}}function replayDynamicTools(e){return e.map(e=>{let t=e.callbacks.execute,n=lookupDurableDynamicCallback(e.name,`execute`),r=e.callbacks.toModelOutput,s=r===void 0?void 0:lookupDurableDynamicCallback(e.name,`toModelOutput`);return{description:e.description,execute:createToolExecuteWithAuth({scope:e.name,execute:(r,i)=>{if(n===void 0)throw missingCallbackError(e,`execute`);return callDurableDynamicCallback(n,t.closure,r,i)}}),inputSchema:toInputSchema(e.inputSchema),name:e.name,approval:buildReplayedApproval(e),outputSchema:toOutputSchema(e.outputSchema),...r===void 0?{}:{toModelOutput:t=>{if(s===void 0)throw missingCallbackError(e,`toModelOutput`);return callDurableDynamicCallback(s,r.closure,t)}}}})}function buildResponseAuthorizationTools(e){let t=new Map;for(let n of e.context===void 0?[]:buildDynamicTools(e.context))t.has(n.name)||t.set(n.name,n);for(let[n,r]of e.authoredTools)t.has(n)||t.set(n,r);return t}function buildDynamicTools(e){let i=replayDynamicTools(e.get(StepDynamicToolMetadataKey)??[]),a=replayDynamicTools(e.get(TurnDynamicToolMetadataKey)??[]),o=replayDynamicTools(e.get(SessionDynamicToolMetadataKey)??[]);return[...i,...a,...o]}export{buildDynamicTools,buildResponseAuthorizationTools,replayDynamicTools};