eve 0.5.4 → 0.6.0-beta.3

package/dist/src/context/dynamic-skill-lifecycle.d.ts

@@ -0,0 +1,24 @@
+import type { ModelMessage } from "ai";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { ResolvedDynamicSkillResolver } from "#runtime/types.js";
+import type { ContextContainer } from "#context/container.js";
+import { ContextKey } from "#context/key.js";
+/**
+ * Durable pending skill announcement text. Set by
+ * {@link dispatchDynamicSkillEvent} whenever the dynamic skill manifest
+ * changes. Read by the tool-loop to inject the announcement into model
+ * context.
+ */
+export declare const PendingSkillAnnouncementKey: ContextKey<string>;
+/**
+ * Dispatches a stream event to dynamic skill resolvers. On a matching
+ * event: runs handlers, materializes resolved skills to the sandbox,
+ * cleans up removed skills, and stores a pending announcement for the
+ * tool-loop to inject.
+ */
+export declare function dispatchDynamicSkillEvent(input: {
+    readonly ctx: ContextContainer;
+    readonly resolvers: readonly ResolvedDynamicSkillResolver[];
+    readonly event: HandleMessageStreamEvent;
+    readonly messages: readonly ModelMessage[];
+}): Promise<void>;

package/dist/src/context/dynamic-skill-lifecycle.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{DynamicSkillManifestKey,SandboxKey}from"#context/keys.js";import{toErrorMessage}from"#shared/errors.js";import{ALLOWED_DYNAMIC_SKILL_EVENTS,isBrandedSkillEntry}from"#shared/dynamic-tool-definition.js";import{normalizeSkillPackage,writeSkillPackageToSandbox}from"#shared/skill-package.js";import{ContextKey}from"#context/key.js";import{buildResolveContext}from"#context/dynamic-resolve-context.js";import{BundleKey}from"#runtime/sessions/runtime-context-keys.js";import{formatAvailableSkillsSection}from"#execution/skills/instructions.js";const log=createLogger(`dynamic-skills`);function qualifyDynamicSkillNames(e,t,n){let r=Object.keys(n),i=[];if(r.length===0)return i;if(t||r.length===1)return i.push({name:e,entryKey:r[0],entry:n[r[0]]}),i;for(let t of r)i.push({name:`${e}__${t}`,entryKey:t,entry:n[t]});return i}function formatDynamicSkillAnnouncement(e){return formatAvailableSkillsSection(Object.values(e).flat())??``}const PendingSkillAnnouncementKey=new ContextKey(`eve.pendingSkillAnnouncement`);async function dispatchDynamicSkillEvent(e){let{ctx:a,resolvers:o,event:s,messages:c}=e;if(a.get(PendingSkillAnnouncementKey)===void 0){let e=a.get(DynamicSkillManifestKey);e!==void 0&&Object.keys(e).length>0&&a.setVirtualContext(PendingSkillAnnouncementKey,formatDynamicSkillAnnouncement(e))}if(!ALLOWED_DYNAMIC_SKILL_EVENTS.has(s.type))return;let l=o.filter(e=>e.eventNames.includes(s.type));if(l.length===0)return;let u=buildResolveContext(a,c),d=new Set(a.require(BundleKey).resolvedAgent.skills.map(e=>e.name)),f=a.get(DynamicSkillManifestKey)??{},p=[],m=await Promise.allSettled(l.map(async e=>{let t=e.events[s.type];if(t===void 0)return null;let n=await t(s,u);if(n==null)return{resolver:e,named:[]};let r,i;return isBrandedSkillEntry(n)?(r={_single:n},i=!0):(r=n,i=!1),{resolver:e,named:qualifyDynamicSkillNames(e.slug,i,r)}}));for(let e of m){if(e.status===`rejected`){log.error(`Dynamic skill resolver (${s.type}) threw — skipping.`,{error:toErrorMessage(e.reason)});continue}e.value!==null&&p.push({resolver:e.value.resolver,skills:e.value.named.map(({name:e,entry:t})=>normalizeSkillPackage({...t,name:e}))})}if(p.length===0)return;let h={...f};for(let{resolver:e,skills:t}of p)t.length===0?delete h[e.slug]:h[e.slug]=t.map(e=>({description:e.description,name:e.name}));let g=new Map;for(let[e,t]of Object.entries(h))for(let{name:n}of t){if(d.has(n))throw Error(`Dynamic skill "${n}" from resolver "${e}" conflicts with an authored skill.`);let t=g.get(n);if(t!==void 0)throw Error(`Dynamic skill "${n}" from resolver "${e}" conflicts with dynamic resolver "${t}".`);g.set(n,e)}let _=await a.require(SandboxKey).get();if(_!==null)for(let{skills:e}of p)for(let t of e)await writeSkillPackageToSandbox({sandbox:_,skill:t});a.set(DynamicSkillManifestKey,h),a.setVirtualContext(PendingSkillAnnouncementKey,formatDynamicSkillAnnouncement(h))}export{PendingSkillAnnouncementKey,dispatchDynamicSkillEvent};

package/dist/src/context/dynamic-tool-lifecycle.d.ts

@@ -0,0 +1,25 @@
+import { type ModelMessage } from "ai";
+import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { ResolvedDynamicToolResolver } from "#runtime/types.js";
+import type { ContextContainer } from "#context/container.js";
+import type { DurableDynamicToolMetadata } from "#context/keys.js";
+/**
+ * Reconstructs tool definitions from durable metadata using
+ * registered step functions. No resolver re-invocation — the
+ * execute function is looked up by step ID and called with stored
+ * closure vars.
+ */
+export declare function replayDynamicSessionTools(metadata: readonly DurableDynamicToolMetadata[], _resolvers: readonly ResolvedDynamicToolResolver[]): readonly HarnessToolDefinition[];
+/**
+ * Dispatches a stream event to dynamic tool resolvers. Each
+ * resolver's metadata replaces its slot (by slug) in the
+ * scope-appropriate durable key. The tool-loop calls
+ * {@link buildDynamicTools} to assemble the effective toolset.
+ */
+export declare function dispatchDynamicToolEvent(input: {
+    readonly ctx: ContextContainer;
+    readonly resolvers: readonly ResolvedDynamicToolResolver[];
+    readonly event: HandleMessageStreamEvent;
+    readonly messages: readonly ModelMessage[];
+}): Promise<void>;

package/dist/src/context/dynamic-tool-lifecycle.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{LiveStepToolsKey,SessionDynamicToolMetadataKey,TurnDynamicToolMetadataKey}from"#context/keys.js";import{toErrorMessage}from"#shared/errors.js";import{jsonSchema,zodSchema}from"ai";import{ALLOWED_DYNAMIC_TOOL_EVENTS,isBrandedToolEntry}from"#shared/dynamic-tool-definition.js";import{buildCallbackContext}from"#context/build-callback-context.js";import{buildResolveContext}from"#context/dynamic-resolve-context.js";import{normalizeJsonSchemaDefinition}from"#internal/json-schema.js";const log=createLogger(`dynamic-tools`);function toHarnessToolDefinition(e,t){return{description:t.description,execute:e=>t.execute(e,buildCallbackContext()),inputSchema:convertInputSchema(t.inputSchema),name:e,needsApproval:t.needsApproval,outputSchema:convertOptionalOutputSchema(t.outputSchema),...t.toModelOutput===void 0?{}:{toModelOutput:t.toModelOutput}}}function convertInputSchema(e){return typeof e==`object`&&e&&`~standard`in e?zodSchema(e):jsonSchema(e)}function convertOptionalOutputSchema(e){if(e!==void 0)return typeof e==`object`&&e&&`~standard`in e?zodSchema(e):jsonSchema(e)}function qualifyDynamicToolNames(e,t,n){let r=Object.keys(n),i=[];if(r.length===0)return i;if(t)return i.push({name:e,entryKey:r[0],entry:n[r[0]]}),i;for(let t of r)i.push({name:`${e}__${t}`,entryKey:t,entry:n[t]});return i}function replayDynamicSessionTools(e,t){let n=[];for(let t of e){if(!t.executeStepFnName||!t.closureVars){log.warn(`Dynamic tool "${t.name}" has no registered step function — skipping on this step. The bundler transform may not have processed this tool file.`);continue}let e=lookupStepFunction(t.executeStepFnName);if(!e){log.warn(`Dynamic tool "${t.name}" references step function "${t.executeStepFnName}" which is not registered — skipping on this step.`);continue}n.push({description:t.description,execute:n=>e(t.closureVars,n,buildCallbackContext()),inputSchema:jsonSchema(t.inputSchema),name:t.name,outputSchema:t.outputSchema===void 0?void 0:jsonSchema(t.outputSchema)})}return n}function getStepRegistry(){let e=Symbol.for(`@workflow/core//registeredSteps`),t=globalThis,n=t[e];return n===void 0&&(n=new Map,t[e]=n),n}function lookupStepFunction(e){try{return getStepRegistry().get(e)||null}catch{return null}}function registerStepFunction(e,t){getStepRegistry().set(e,t)}function safeSerialize(e){try{return JSON.parse(JSON.stringify(e))}catch{return{}}}function durableKeyForEvent(e){switch(e){case`session.started`:return SessionDynamicToolMetadataKey;case`turn.started`:return TurnDynamicToolMetadataKey;default:return}}async function resolveToolsFromEvent(e,t,n,r){let a=await Promise.allSettled(t.map(async t=>{let i=t.events[n.type];if(i===void 0)return null;let a=await i(n,buildResolveContext(e,r));if(a==null)return null;let o,s;return isBrandedToolEntry(a)?(o={_single:a},s=!0):(o=a,s=!1),{resolver:t,entries:o,isSingle:s}})),o=[],s=[];for(let e of a){if(e.status===`rejected`){log.error(`Dynamic tool resolver (${n.type}) threw — skipping.`,{error:toErrorMessage(e.reason)});continue}if(e.value===null)continue;let{resolver:t,entries:r,isSingle:a}=e.value,c=qualifyDynamicToolNames(t.slug,a,r);for(let{name:e,entryKey:n,entry:r}of c){s.push(toHarnessToolDefinition(e,r));let i=`__executeStepFn`in r?r.__executeStepFn:void 0,a=`__closureVars`in r?r.__closureVars:void 0,c=i?.stepId,l=a===void 0?void 0:safeSerialize(a);if(c===void 0){let e=`eve:framework-dynamic:${t.slug}:${n}`,i=r.execute.bind(r);registerStepFunction(e,(e,t,n)=>i(t,n)),c=e,l={}}o.push({name:e,description:r.description,inputSchema:normalizeJsonSchemaDefinition(r.inputSchema),outputSchema:r.outputSchema===void 0?void 0:normalizeJsonSchemaDefinition(r.outputSchema,`output`),resolverSlug:t.slug,entryKey:n,executeStepFnName:c,closureVars:l})}}return{metadata:o,liveTools:s}}async function dispatchDynamicToolEvent(e){let{ctx:n,resolvers:r,event:i,messages:a}=e;if(!ALLOWED_DYNAMIC_TOOL_EVENTS.has(i.type))return;let o=r.filter(e=>e.eventNames.includes(i.type));if(o.length===0)return;let{metadata:c,liveTools:l}=await resolveToolsFromEvent(n,o,i,a);if(i.type===`step.started`){n.setVirtualContext(LiveStepToolsKey,l);return}let u=durableKeyForEvent(i.type);if(u===void 0)return;let d=new Set(o.map(e=>e.slug)),f=(n.get(u)??[]).filter(e=>!d.has(e.resolverSlug));n.set(u,[...f,...c])}export{dispatchDynamicToolEvent,replayDynamicSessionTools};

package/dist/src/context/hook-lifecycle.d.ts

@@ -0,0 +1,14 @@
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { RuntimeHookRegistry } from "#runtime/hooks/registry.js";
+import type { ContextContainer } from "./container.js";
+/**
+ * Fans one runtime stream event out to every matching subscriber.
+ * Errors propagate — harness error paths convert them into the
+ * recoverable `turn.failed` cascade. Caller must hold an active ALS
+ * scope so hooks see the same context as the rest of the step.
+ */
+export declare function dispatchStreamEventHooks(input: {
+    readonly ctx: ContextContainer;
+    readonly registry: RuntimeHookRegistry;
+    readonly event: HandleMessageStreamEvent;
+}): Promise<void>;

package/dist/src/context/hook-lifecycle.js

@@ -0,0 +1 @@
+import{ContinuationTokenKey}from"./keys.js";import{getAdapterKind}from"#channel/adapter.js";import{buildCallbackContext}from"#context/build-callback-context.js";import{BundleKey,ChannelKey}from"#runtime/sessions/runtime-context-keys.js";async function dispatchStreamEventHooks(e){let t=e.registry.streamEventsByType.get(e.event.type)??[],n=e.registry.streamEventsWildcard;if(t.length===0&&n.length===0)return;let r=buildHookContext(e.ctx);for(let n of t)await n.handler(e.event,r);for(let t of n)await t.handler(e.event,r)}function buildHookContext(i){let a=i.require(BundleKey),o=i.get(ChannelKey),s=i.get(ContinuationTokenKey),c=o===void 0?void 0:getAdapterKind(o);return{...buildCallbackContext(),agent:{name:a.resolvedAgent.config.name??`agent`,nodeId:a.nodeId},channel:{kind:c,continuationToken:s}}}export{dispatchStreamEventHooks};

package/dist/src/context/key.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Read-only view over the active context.
+ *
+ * Used by context providers and codec deserialization to read values
+ * without mutating durable context.
+ */
+export interface ContextReader {
+    get<T>(key: ContextKey<T>): T | undefined;
+    require<T>(key: ContextKey<T>): T;
+    has<T>(key: ContextKey<T>): boolean;
+}
+/**
+ * Read/write view over the active context.
+ *
+ * Extends {@link ContextReader} with durable write operations. This is
+ * the narrow contract shared by {@link AlsContext} and the channel-facing
+ * `ContextAccessor`.
+ */
+export interface ContextAccessor extends ContextReader {
+    set<T>(key: ContextKey<T>, updater: T | ((current: T | undefined) => T)): T;
+    ensure<T>(key: ContextKey<T>, create: () => T): T;
+}
+/**
+ * Serialization hooks for one context key.
+ *
+ * `deserialize` receives the already-hydrated durable context so codecs can
+ * depend on earlier durable keys such as the compiled runtime bundle.
+ */
+export interface ContextKeyCodec<T> {
+    serialize(value: T): unknown;
+    deserialize(data: unknown, ctx: ContextReader): T | Promise<T>;
+}
+export interface ContextKeyOptions<T> {
+    readonly codec?: ContextKeyCodec<T>;
+}
+/**
+ * Typed key that identifies a named context slot.
+ */
+export declare class ContextKey<T> {
+    readonly name: string;
+    readonly codec?: ContextKeyCodec<T>;
+    constructor(name: string, options?: ContextKeyOptions<T>);
+}
+/**
+ * Looks up a registered key by name. Returns `undefined` for unknown names.
+ */
+export declare function resolveKey(name: string): ContextKey<unknown> | undefined;

package/dist/src/context/key.js

@@ -0,0 +1 @@
+const KEY_REGISTRY_GLOBAL_KEY=Symbol.for(`eve.context-key-registry`),globalKeyRegistryContainer=globalThis;globalKeyRegistryContainer[KEY_REGISTRY_GLOBAL_KEY]===void 0&&(globalKeyRegistryContainer[KEY_REGISTRY_GLOBAL_KEY]=new Map);const keyRegistry=globalKeyRegistryContainer[KEY_REGISTRY_GLOBAL_KEY];var ContextKey=class{name;codec;constructor(e,t={}){this.name=e,this.codec=t.codec;let n=keyRegistry.get(e);if(n!==void 0&&n.codec===void 0!=(this.codec===void 0))throw Error(`ContextKey name collision: "${e}" is already registered ${n.codec?`with`:`without`} a codec, but a key ${this.codec?`with`:`without`} a codec is being registered under the same name. This silently breaks context serialization — use a distinct name.`);keyRegistry.set(e,this)}};function resolveKey(e){return keyRegistry.get(e)}export{ContextKey,resolveKey};

package/dist/src/context/keys.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Leaf context keys — no codec, no runtime imports. Safe to import from any
+ * tier. Codec-carrying keys (`ChannelKey`, `BundleKey`) live in
+ * `#runtime/sessions/runtime-context-keys.ts`.
+ */
+import type { SystemModelMessage } from "ai";
+import type { JsonObject } from "#shared/json.js";
+import type { ChannelInstrumentationProjection, SessionAuthContext, SessionCallback, SessionCapabilities, SessionParent, SessionTurn } from "#channel/types.js";
+import { ContextKey } from "#context/key.js";
+import type { SandboxAccess } from "#sandbox/state.js";
+import type { RunMode } from "#shared/run-mode.js";
+export type { SessionAuthContext, SessionParent, SessionTurn } from "#channel/types.js";
+/**
+ * Auth metadata on the active session.
+ *
+ * `current` is the caller of the most recent request.
+ * `initiator` is the caller who originally created the session.
+ */
+export interface SessionAuth {
+    readonly current: SessionAuthContext | null;
+    readonly initiator: SessionAuthContext | null;
+}
+/**
+ * Internal session metadata seeded into the context container under
+ * {@link SessionKey}.
+ *
+ * This is not the shape authored code observes. Tools, hooks, and channel
+ * events receive the `SessionContext.session` projection (via `ctx.session`),
+ * whose session id is exposed as `id`, not `sessionId`.
+ */
+export interface Session {
+    readonly auth: SessionAuth;
+    readonly parent?: SessionParent;
+    readonly sessionId: string;
+    readonly turn: SessionTurn;
+}
+export declare const AuthKey: ContextKey<SessionAuthContext | null>;
+export declare const InitiatorAuthKey: ContextKey<SessionAuthContext | null>;
+export declare const SessionIdKey: ContextKey<string>;
+export declare const ContinuationTokenKey: ContextKey<string>;
+export declare const ChannelInstrumentationKey: ContextKey<ChannelInstrumentationProjection>;
+export declare const ModeKey: ContextKey<RunMode>;
+export declare const ParentSessionKey: ContextKey<SessionParent>;
+/**
+ * Session-level capability flags (see {@link SessionCapabilities}). Set
+ * on root runs by channel routes and inherited pointwise by subagent
+ * dispatch so HITL readiness flows through a conversation chain.
+ */
+export declare const CapabilitiesKey: ContextKey<SessionCapabilities>;
+/**
+ * Optional framework-owned terminal callback metadata for this session.
+ */
+export declare const SessionCallbackKey: ContextKey<SessionCallback>;
+export declare const SessionKey: ContextKey<Session>;
+export declare const SandboxKey: ContextKey<SandboxAccess>;
+export interface DurableDynamicToolMetadata {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JsonObject;
+    readonly outputSchema?: JsonObject;
+    readonly resolverSlug: string;
+    readonly entryKey: string;
+    readonly executeStepFnName?: string;
+    readonly closureVars?: Record<string, unknown>;
+}
+/**
+ * Session-scoped dynamic tool metadata (from `session.started`).
+ * Persists for the session lifetime.
+ */
+export declare const SessionDynamicToolMetadataKey: ContextKey<readonly DurableDynamicToolMetadata[]>;
+/**
+ * Turn-scoped dynamic tool metadata (from `turn.started`).
+ * Replaced each turn.
+ */
+export declare const TurnDynamicToolMetadataKey: ContextKey<readonly DurableDynamicToolMetadata[]>;
+/**
+ * Virtual (non-serialized) live step-scoped tool definitions from
+ * `step.started` resolvers. Carries original execute closures so
+ * framework tools (which lack bundler step-function metadata) work.
+ * Re-resolved every step — no cross-step persistence needed.
+ */
+export declare const LiveStepToolsKey: ContextKey<import("#harness/execute-tool.js").HarnessToolDefinition[]>;
+/**
+ * Durable metadata for one session-scoped dynamic skill.
+ */
+export interface DurableDynamicSkillMetadata {
+    readonly name: string;
+    readonly description: string;
+}
+/**
+ * Durable map from resolver slug to the qualified skills it last produced.
+ * Used to diff on re-resolution, clean up removed skills from the sandbox,
+ * and rebuild the model-visible announcement across turns.
+ */
+export declare const DynamicSkillManifestKey: ContextKey<Record<string, readonly DurableDynamicSkillMetadata[]>>;
+/**
+ * Durable session-scoped instruction messages (from `session.started`
+ * resolvers). Keyed by resolver slug. Persists for the session lifetime.
+ */
+export declare const SessionDynamicInstructionsKey: ContextKey<Record<string, readonly SystemModelMessage[]>>;
+/**
+ * Durable turn-scoped instruction messages (from `turn.started`
+ * resolvers). Keyed by resolver slug. Replaced each turn.
+ */
+export declare const TurnDynamicInstructionsKey: ContextKey<Record<string, readonly SystemModelMessage[]>>;

package/dist/src/context/keys.js

@@ -0,0 +1 @@
+import{ContextKey}from"#context/key.js";const AuthKey=new ContextKey(`eve.auth`),InitiatorAuthKey=new ContextKey(`eve.initiatorAuth`),SessionIdKey=new ContextKey(`eve.sessionId`),ContinuationTokenKey=new ContextKey(`eve.continuationToken`),ChannelInstrumentationKey=new ContextKey(`eve.channelInstrumentation`),ModeKey=new ContextKey(`eve.mode`),ParentSessionKey=new ContextKey(`eve.parentSession`),CapabilitiesKey=new ContextKey(`eve.capabilities`),SessionCallbackKey=new ContextKey(`eve.sessionCallback`),SessionKey=new ContextKey(`eve.session`),SandboxKey=new ContextKey(`eve.sandbox`),SessionDynamicToolMetadataKey=new ContextKey(`eve.sessionDynamicToolMetadata`),TurnDynamicToolMetadataKey=new ContextKey(`eve.turnDynamicToolMetadata`),LiveStepToolsKey=new ContextKey(`eve.liveStepTools`),DynamicSkillManifestKey=new ContextKey(`eve.dynamicSkillManifest`),SessionDynamicInstructionsKey=new ContextKey(`eve.sessionDynamicInstructions`),TurnDynamicInstructionsKey=new ContextKey(`eve.turnDynamicInstructions`);export{AuthKey,CapabilitiesKey,ChannelInstrumentationKey,ContinuationTokenKey,DynamicSkillManifestKey,InitiatorAuthKey,LiveStepToolsKey,ModeKey,ParentSessionKey,SandboxKey,SessionCallbackKey,SessionDynamicInstructionsKey,SessionDynamicToolMetadataKey,SessionIdKey,SessionKey,TurnDynamicInstructionsKey,TurnDynamicToolMetadataKey};

package/dist/src/context/node.d.ts

@@ -0,0 +1,7 @@
+import type { ContextReader } from "#context/provider.js";
+/**
+ * Returns the active runtime node from the compiled bundle on the
+ * context. The bundle is already resolved to the correct node (root or
+ * subagent) at run start.
+ */
+export declare function getActiveRuntimeNode(ctx: ContextReader): import("../runtime/graph.js").ResolvedRuntimeAgentNode;

package/dist/src/context/node.js

@@ -0,0 +1 @@
+import{BundleKey}from"#runtime/sessions/runtime-context-keys.js";function getActiveRuntimeNode(e){return e.require(BundleKey).graph.root}export{getActiveRuntimeNode};

package/dist/src/context/provider.d.ts

@@ -0,0 +1,27 @@
+import type { HarnessSession } from "#harness/types.js";
+import type { ContextContainer } from "#context/container.js";
+import type { ContextKey } from "#context/key.js";
+export type { ContextReader } from "#context/key.js";
+/**
+ * Value returned by a framework provider's `create` method.
+ *
+ * `value` is the live step-local instance stored on the context. `session`
+ * carries an optional harness session patch produced while deriving that
+ * value.
+ */
+export interface ProviderResult<T> {
+    readonly value: T;
+    readonly session?: HarnessSession;
+}
+/**
+ * Framework-only provider contract.
+ *
+ * Framework providers may derive virtual values from context, observe the
+ * current harness session, and optionally commit mutable provider-owned state
+ * back onto the harness session after the authored step completes.
+ */
+export interface FrameworkContextProvider<T> {
+    readonly key: ContextKey<T>;
+    create(ctx: ContextContainer, session: HarnessSession): ProviderResult<T> | undefined | Promise<ProviderResult<T> | undefined>;
+    commit?(value: T, session: HarnessSession): HarnessSession | Promise<HarnessSession>;
+}

package/dist/src/context/provider.js

@@ -0,0 +1 @@
+export{};

package/dist/src/context/providers/connection.d.ts

@@ -0,0 +1,12 @@
+import { ContextKey } from "#context/key.js";
+import type { ConnectionRegistry } from "#runtime/connections/types.js";
+import type { FrameworkContextProvider } from "#context/provider.js";
+/**
+ * Context key for the per-session connection registry.
+ *
+ * Created as a derived key (no codec) because the registry holds live
+ * client instances that cannot be serialized across step boundaries.
+ * The `connectionProvider` reconstructs it each step.
+ */
+export declare const ConnectionRegistryKey: ContextKey<ConnectionRegistry>;
+export declare const connectionProvider: FrameworkContextProvider<ConnectionRegistry>;

package/dist/src/context/providers/connection.js

@@ -0,0 +1 @@
+import{ContextKey}from"#context/key.js";import{BundleKey}from"#runtime/sessions/runtime-context-keys.js";import{ConnectionRegistryImpl}from"#runtime/connections/registry.js";import{getActiveRuntimeNode}from"#context/node.js";const ConnectionRegistryKey=new ContextKey(`eve.connectionRegistry`),connectionProvider={key:ConnectionRegistryKey,create(e,t){if(e.get(BundleKey)===void 0)return;let n=getActiveRuntimeNode(e).agent?.connections;if(!(!n||n.length===0))return{value:new ConnectionRegistryImpl(n)}}};export{ConnectionRegistryKey,connectionProvider};

package/dist/src/context/providers/sandbox.d.ts

@@ -0,0 +1,3 @@
+import type { SandboxAccess } from "#sandbox/state.js";
+import type { FrameworkContextProvider } from "#context/provider.js";
+export declare const sandboxProvider: FrameworkContextProvider<SandboxAccess>;

package/dist/src/context/providers/sandbox.js

@@ -0,0 +1 @@
+import{getAdapterKind}from"#channel/adapter.js";import{SandboxKey,SessionIdKey}from"#context/keys.js";import{contextStorage}from"#context/container.js";import{BundleKey,ChannelKey}from"#runtime/sessions/runtime-context-keys.js";import{getActiveRuntimeNode}from"#context/node.js";import{ensureSandboxAccess}from"#execution/sandbox/ensure.js";const sandboxProvider={key:SandboxKey,async create(e,t){let r=e.get(BundleKey);if(r===void 0)return;let i=getActiveRuntimeNode(e),a=i.sandboxRegistry,o=e.require(SessionIdKey),s=e.get(ChannelKey),c=s?.state,l=c?.sandboxSessionId??o,u=c?.parentSandboxState;return{value:await ensureSandboxAccess({compiledArtifactsSource:r.compiledArtifactsSource,nodeId:i.nodeId,registry:a,runOnSession:async t=>await contextStorage.run(e,t),sessionId:l,state:t.sandboxState??u??null,tags:{agent:resolveTagAgentName({bundle:r,node:i}),channel:resolveTagChannelKind(s),sessionId:o}})}},async commit(e,t){let n=await e.captureState();return{...t,sandboxState:n}}};function resolveTagAgentName(e){let t=e.node,n=e.bundle;return t.agent?.config?.name??n.resolvedAgent?.config?.name??t.nodeId??`unknown`}function resolveTagChannelKind(t){return t===void 0?`unknown`:getAdapterKind(t)}export{sandboxProvider};

package/dist/src/context/providers/session.d.ts

@@ -0,0 +1,3 @@
+import { type Session } from "#context/keys.js";
+import type { FrameworkContextProvider } from "#context/provider.js";
+export declare const sessionProvider: FrameworkContextProvider<Session>;

package/dist/src/context/providers/session.js

@@ -0,0 +1 @@
+import{AuthKey,InitiatorAuthKey,ParentSessionKey,SessionIdKey,SessionKey}from"#context/keys.js";const sessionProvider={key:SessionKey,create(e){let t=e.require(AuthKey);return{value:Object.freeze({auth:{current:t,initiator:e.get(InitiatorAuthKey)??t},parent:e.get(ParentSessionKey),sessionId:e.require(SessionIdKey),turn:{id:`turn-${crypto.randomUUID()}`,sequence:0}})}}};export{sessionProvider};

package/dist/src/context/run-step.d.ts

@@ -0,0 +1,23 @@
+import type { HarnessSession, StepResult } from "#harness/types.js";
+import { type ContextContainer } from "#context/container.js";
+interface ContextScopeResult<T> {
+    readonly result: T;
+    readonly session: HarnessSession;
+}
+/**
+ * Runs `callback` inside a fully-initialized ALS scope with all framework
+ * providers (session, connection, sandbox) built and committed.
+ *
+ * The callback receives the enriched session and must return both its own
+ * result and the (possibly mutated) session so provider commit hooks can
+ * persist provider-owned state (e.g. sandbox snapshots).
+ */
+export declare function withContextScope<T>(ctx: ContextContainer, harnessSession: HarnessSession, callback: (session: HarnessSession) => Promise<ContextScopeResult<T>>): Promise<ContextScopeResult<T>>;
+/**
+ * Runs one harness step inside the unified context.
+ *
+ * Delegates to {@link withContextScope} for provider lifecycle, then
+ * reassembles the {@link StepResult}.
+ */
+export declare function runStep(ctx: ContextContainer, harnessSession: HarnessSession, callback: (session: HarnessSession) => Promise<StepResult>): Promise<StepResult>;
+export {};

package/dist/src/context/run-step.js

@@ -0,0 +1 @@
+import{contextStorage}from"#context/container.js";import{connectionProvider}from"#context/providers/connection.js";import{sandboxProvider}from"#context/providers/sandbox.js";import{sessionProvider}from"#context/providers/session.js";const frameworkProviders=[sessionProvider,connectionProvider,sandboxProvider];async function withContextScope(t,n,r){let a=n;t.clearVirtualContext();for(let e of frameworkProviders){let n=await e.create(t,a);n!==void 0&&(t.setVirtualContext(e.key,n.value),n.session!==void 0&&(a=n.session))}let o=await contextStorage.run(t,()=>r(a)),s=o.session;for(let e of frameworkProviders)e.commit&&t.has(e.key)&&(s=await e.commit(t.require(e.key),s));return s===o.session?o:{result:o.result,session:s}}async function runStep(e,t,n){let{result:r,session:i}=await withContextScope(e,t,async e=>{let t=await n(e);return{result:t.next,session:t.session}});return{next:r,session:i}}export{runStep,withContextScope};

package/dist/src/context/serialize.d.ts

@@ -0,0 +1,15 @@
+import { type AlsContext, ContextContainer } from "#context/container.js";
+/**
+ * Serializes every value in the context to a plain JSON record.
+ *
+ * Keys with a codec are run through `codec.serialize`; keys without one
+ * are stored as-is (they must already be JSON-safe).
+ */
+export declare function serializeContext(ctx: AlsContext): Record<string, unknown>;
+/**
+ * Deserializes a plain JSON record into a fresh context container.
+ *
+ * Each entry is matched to a registered {@link ContextKey} by name.
+ * Unknown entries (no registered key) are dropped with a warning.
+ */
+export declare function deserializeContext(data: Record<string, unknown>): Promise<ContextContainer>;

package/dist/src/context/serialize.js

@@ -0,0 +1 @@
+import{createLogger,logError}from"#internal/logging.js";import{ContextContainer}from"#context/container.js";import{resolveKey}from"#context/key.js";import{BundleKey}from"#runtime/sessions/runtime-context-keys.js";const log=createLogger(`context.serialize`);function serializeContext(e){let t={};for(let[n,r]of e.entries())try{t[n.name]=n.codec?n.codec.serialize(r):r}catch(e){throw logError(log,`failed to serialize context key`,e,{key:n.name}),e}return t}async function deserializeContext(e){let i=new ContextContainer,a=e[BundleKey.name];if(a!==void 0){let e=BundleKey.codec;if(e===void 0)throw Error(`Context key "eve.bundle" is missing a codec.`);i.set(BundleKey,await e.deserialize(a,i))}for(let[t,a]of Object.entries(e)){if(a===void 0||t===BundleKey.name)continue;let e=resolveKey(t);if(e===void 0){log.warn(`dropping unknown context key during deserialization`,{key:t});continue}try{i.set(e,e.codec?await e.codec.deserialize(a,i):a)}catch(e){throw logError(log,`failed to deserialize context key`,e,{key:t}),e}}return i}export{deserializeContext,serializeContext};

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

@@ -0,0 +1,34 @@
+import { type DiscoverDiagnostic } from "#discover/diagnostics.js";
+import { type ConnectionSourceRef } from "#discover/manifest.js";
+import type { ProjectSource, ProjectSourceEntry } from "#discover/project-source.js";
+/**
+ * Shared diagnostic emitted when the authored `connections/` root is not a
+ * directory.
+ */
+export declare const DISCOVER_CONNECTIONS_DIRECTORY_INVALID = "discover/connections-directory-invalid";
+/**
+ * Discovery diagnostic emitted when a connection exists in both file form
+ * (`connections/<name>.ts`) and folder form (`connections/<name>/`).
+ */
+export declare const DISCOVER_CONNECTION_FILE_FOLDER_COLLISION = "discover/connection-file-folder-collision";
+/**
+ * Discovery diagnostic emitted when a folder-form connection contains no
+ * `connection.ts` definition module.
+ */
+export declare const DISCOVER_CONNECTION_FOLDER_EMPTY = "discover/connection-folder-empty";
+/**
+ * Result of discovering authored connection sources from a single agent root.
+ */
+interface DiscoverConnectionSourcesResult {
+    connections: ConnectionSourceRef[];
+    diagnostics: DiscoverDiagnostic[];
+}
+/**
+ * Discovers authored connections under `agent/connections/`.
+ */
+export declare function discoverConnectionSources(input: {
+    rootEntries: readonly ProjectSourceEntry[];
+    rootPath: string;
+    source: ProjectSource;
+}): Promise<DiscoverConnectionSourcesResult>;
+export {};

package/dist/src/discover/connections.js

@@ -0,0 +1 @@
+import{join}from"node:path";import{createDiscoverErrorDiagnostic}from"#discover/diagnostics.js";import{normalizeLogicalPath}from"#discover/filesystem.js";import{createConnectionSourceRef}from"#discover/manifest.js";import{DISCOVER_MODULE_SLOT_COLLISION,createConnectionNameDiagnostic,createModuleSlotCollisionDiagnostic,readSortedDirectoryEntries}from"#discover/grammar.js";import{collectNamedSlotCandidates}from"#discover/slots.js";const DISCOVER_CONNECTIONS_DIRECTORY_INVALID=`discover/connections-directory-invalid`,DISCOVER_CONNECTION_FILE_FOLDER_COLLISION=`discover/connection-file-folder-collision`,DISCOVER_CONNECTION_FOLDER_EMPTY=`discover/connection-folder-empty`;async function discoverConnectionSources(c){let l=`connections`,u=join(c.rootPath,l),d=c.rootEntries.find(e=>e.name===l);if(d===void 0)return{connections:[],diagnostics:[]};if(!d.isDirectory())return{connections:[],diagnostics:[createDiscoverErrorDiagnostic({code:DISCOVER_CONNECTIONS_DIRECTORY_INVALID,message:`Expected "${u}" to be a directory of authored connections.`,sourcePath:u})]};let f=await readSortedDirectoryEntries(c.source,u),p=[],m=[],h=new Set;for(let t of collectNamedSlotCandidates(f,{allowMarkdown:!1,allowModules:!0})){let r=normalizeLogicalPath(join(l,t.slotName));if(t.moduleFileNames.length>1){h.add(t.slotName),m.push(createModuleSlotCollisionDiagnostic(u,r,t.moduleFileNames));continue}let[a]=t.moduleFileNames;if(a===void 0)continue;h.add(t.slotName);let o=createConnectionNameDiagnostic(t.slotName,join(u,a));if(o!==null){m.push(o);continue}p.push(createConnectionSourceRef({connectionName:t.slotName,logicalPath:join(l,a)}))}for(let i of f){if(!i.isDirectory())continue;let o=i.name,s=join(u,o);if(h.has(o)){m.push(createDiscoverErrorDiagnostic({code:DISCOVER_CONNECTION_FILE_FOLDER_COLLISION,message:`Connection "${o}" is defined twice. Found both file-form "connections/${o}.ts" and folder-form "connections/${o}/". Use one form, not both.`,sourcePath:s}));let e=p.findIndex(e=>e.connectionName===o);e!==-1&&p.splice(e,1);continue}let d=createConnectionNameDiagnostic(o,s);if(d!==null){m.push(d);continue}let f=collectFolderConnectionModuleCandidates(await readSortedDirectoryEntries(c.source,s));if(f.length>1){m.push(createDiscoverErrorDiagnostic({code:DISCOVER_MODULE_SLOT_COLLISION,message:`Found multiple connection definition modules inside "${normalizeLogicalPath(join(l,o))}": `+f.map(e=>`"${e}"`).join(`, `),sourcePath:s}));continue}let[g]=f;if(g===void 0){m.push(createDiscoverErrorDiagnostic({code:DISCOVER_CONNECTION_FOLDER_EMPTY,message:`Connection folder "connections/${o}/" contains no "connection.ts" definition. Add "connections/${o}/connection.ts" or use the file form "connections/${o}.ts".`,sourcePath:s}));continue}p.push(createConnectionSourceRef({connectionName:o,logicalPath:join(l,o,g)}))}return{connections:p,diagnostics:m}}function collectFolderConnectionModuleCandidates(e){let t=e.filter(e=>e.isFile()),n=[];for(let e of collectNamedSlotCandidates(t,{allowMarkdown:!1,allowModules:!0}))e.slotName===`connection`&&n.push(...e.moduleFileNames);return n}export{DISCOVER_CONNECTIONS_DIRECTORY_INVALID,DISCOVER_CONNECTION_FILE_FOLDER_COLLISION,DISCOVER_CONNECTION_FOLDER_EMPTY,discoverConnectionSources};

package/dist/src/discover/diagnostics.d.ts

@@ -0,0 +1,53 @@
+import { z } from "#compiled/zod/index.js";
+/**
+ * Structured discovery diagnostic severity.
+ */
+export type DiscoverDiagnosticSeverity = z.infer<typeof discoverDiagnosticSeveritySchema>;
+/**
+ * Zod schema for structured discovery diagnostic severities.
+ */
+export declare const discoverDiagnosticSeveritySchema: z.ZodUnion<readonly [z.ZodLiteral<"error">, z.ZodLiteral<"warning">]>;
+/**
+ * Structured discovery diagnostic emitted while classifying authored sources.
+ */
+export type DiscoverDiagnostic = z.infer<typeof discoverDiagnosticSchema>;
+/**
+ * Zod schema for one structured discovery diagnostic.
+ */
+export declare const discoverDiagnosticSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    severity: z.ZodUnion<readonly [z.ZodLiteral<"error">, z.ZodLiteral<"warning">]>;
+    sourcePath: z.ZodString;
+}, z.core.$strict>;
+/**
+ * Summary counts emitted alongside discovery manifests and CLI output.
+ */
+export type DiscoverDiagnosticsSummary = z.infer<typeof discoverDiagnosticsSummarySchema>;
+/**
+ * Zod schema for discovery diagnostic summary counts.
+ */
+export declare const discoverDiagnosticsSummarySchema: z.ZodObject<{
+    errors: z.ZodNumber;
+    warnings: z.ZodNumber;
+}, z.core.$strict>;
+/**
+ * Root-resolution error code emitted when discovery cannot locate an Eve agent.
+ */
+export declare const DISCOVER_PROJECT_NOT_FOUND = "discover/project-not-found";
+/**
+ * Creates an error-level discovery diagnostic.
+ */
+export declare function createDiscoverErrorDiagnostic(input: Omit<DiscoverDiagnostic, "severity">): DiscoverDiagnostic;
+/**
+ * Creates a warning-level discovery diagnostic.
+ */
+export declare function createDiscoverWarningDiagnostic(input: Omit<DiscoverDiagnostic, "severity">): DiscoverDiagnostic;
+/**
+ * Summarizes discovery diagnostics into error and warning counts.
+ */
+export declare function summarizeDiscoverDiagnostics(diagnostics: readonly DiscoverDiagnostic[]): DiscoverDiagnosticsSummary;
+/**
+ * Returns whether discovery diagnostics include at least one error.
+ */
+export declare function hasDiscoverErrors(diagnostics: readonly DiscoverDiagnostic[]): boolean;

package/dist/src/discover/diagnostics.js

@@ -0,0 +1 @@
+import{z}from"#compiled/zod/index.js";const discoverDiagnosticSeveritySchema=z.union([z.literal(`error`),z.literal(`warning`)]),discoverDiagnosticSchema=z.object({code:z.string(),message:z.string(),severity:discoverDiagnosticSeveritySchema,sourcePath:z.string()}).strict(),discoverDiagnosticsSummarySchema=z.object({errors:z.number().finite(),warnings:z.number().finite()}).strict(),DISCOVER_PROJECT_NOT_FOUND=`discover/project-not-found`;function createDiscoverErrorDiagnostic(e){return{...e,severity:`error`}}function createDiscoverWarningDiagnostic(e){return{...e,severity:`warning`}}function summarizeDiscoverDiagnostics(e){return e.reduce((e,t)=>(t.severity===`error`?e.errors+=1:e.warnings+=1,e),{errors:0,warnings:0})}function hasDiscoverErrors(e){return e.some(e=>e.severity===`error`)}export{DISCOVER_PROJECT_NOT_FOUND,createDiscoverErrorDiagnostic,createDiscoverWarningDiagnostic,discoverDiagnosticSchema,discoverDiagnosticSeveritySchema,discoverDiagnosticsSummarySchema,hasDiscoverErrors,summarizeDiscoverDiagnostics};

package/dist/src/discover/discover-agent.d.ts

@@ -0,0 +1,30 @@
+import type { DiscoverDiagnostic } from "#discover/diagnostics.js";
+import { type AgentSourceManifest } from "#discover/manifest.js";
+import { type ProjectSource } from "#discover/project-source.js";
+/**
+ * Input for discovering the authored agent source graph from resolved roots.
+ */
+interface DiscoverAgentInput {
+    agentRoot: string;
+    appRoot: string;
+    /**
+     * Optional {@link ProjectSource} used for all filesystem reads. Defaults
+     * to a disk-backed source so disk callers keep their current behaviour.
+     * Tests that want to run discovery against an in-memory tree pass a
+     * memory-backed source.
+     */
+    source?: ProjectSource;
+}
+/**
+ * Result of discovering one authored agent source graph.
+ */
+interface DiscoverAgentResult {
+    diagnostics: DiscoverDiagnostic[];
+    manifest: AgentSourceManifest;
+}
+/**
+ * Discovers the current agent's authored source graph without importing authored
+ * modules.
+ */
+export declare function discoverAgent(input: DiscoverAgentInput): Promise<DiscoverAgentResult>;
+export {};

package/dist/src/discover/discover-agent.js

@@ -0,0 +1 @@
+import{join,resolve}from"node:path";import{classifyAgentRootEntry}from"#discover/filesystem.js";import{createDiskProjectSource}from"#discover/project-source.js";import{createAgentSourceManifest}from"#discover/manifest.js";import{DISCOVER_CHANNELS_DIRECTORY_INVALID,DISCOVER_HOOKS_DIRECTORY_INVALID,DISCOVER_TOOLS_DIRECTORY_INVALID,createChannelNameDiagnostic,createHookNameDiagnostic,createToolNameDiagnostic,createUnsupportedRootDirectoryDiagnostics,discoverFlatModuleSource,discoverInstructionsSource,discoverNamedSourceDirectory,readSortedDirectoryEntries}from"#discover/grammar.js";import{discoverConnectionSources}from"#discover/connections.js";import{discoverSubagents}from"#discover/discover-subagent.js";import{discoverLibSources}from"#discover/lib.js";import{discoverSandboxSource}from"#discover/sandbox.js";import{discoverScheduleSources}from"#discover/schedules.js";import{discoverSkills}from"#discover/skills.js";async function discoverAgent(o){let s=o.source??createDiskProjectSource(),c=resolve(o.appRoot),l=resolve(o.agentRoot),u=[],d=await tryReadPackageJsonName(s,c),f=await readSortedDirectoryEntries(s,l);u.push(...createUnsupportedRootDirectoryDiagnostics({classifyEntry:classifyAgentRootEntry,createUnsupportedDirectoryMessage(e){return`Ignoring unsupported directory "${e}/" in the agent root.`},rootEntries:f,rootPath:l}));let p=await discoverInstructionsSource({rootEntries:f,rootPath:l,source:s});u.push(...p.diagnostics);let m=discoverFlatModuleSource({rootEntries:f,rootPath:l,slotName:`agent`});u.push(...m.diagnostics);let h=await discoverNamedSourceDirectory({directoryName:`channels`,invalidDirectoryCode:DISCOVER_CHANNELS_DIRECTORY_INVALID,invalidDirectoryMessage:`Expected "${join(l,`channels`)}" to be a directory of authored channels.`,recursive:!0,rootEntries:f,rootPath:l,source:s,validateSegment:createChannelNameDiagnostic});u.push(...h.diagnostics);let g=await discoverLibSources({agentRoot:l,rootEntries:f,source:s});u.push(...g.diagnostics);let _=await discoverScheduleSources({agentRoot:l,rootEntries:f,source:s});u.push(..._.diagnostics);let v=await discoverConnectionSources({rootEntries:f,rootPath:l,source:s});u.push(...v.diagnostics);let y=await discoverSandboxSource({rootEntries:f,rootPath:l,source:s});u.push(...y.diagnostics);let b=await discoverNamedSourceDirectory({directoryName:`tools`,invalidDirectoryCode:DISCOVER_TOOLS_DIRECTORY_INVALID,invalidDirectoryMessage:`Expected "${join(l,`tools`)}" to be a directory of authored tools.`,recursive:!0,rootEntries:f,rootPath:l,source:s,validateSegment:createToolNameDiagnostic});u.push(...b.diagnostics);let x=await discoverNamedSourceDirectory({directoryName:`hooks`,invalidDirectoryCode:DISCOVER_HOOKS_DIRECTORY_INVALID,invalidDirectoryMessage:`Expected "${join(l,`hooks`)}" to be a directory of authored hooks.`,recursive:!0,rootEntries:f,rootPath:l,source:s,validateSegment:createHookNameDiagnostic});u.push(...x.diagnostics);let S=await discoverSkills({agentRoot:l,source:s});u.push(...S.diagnostics);let C=await discoverSubagents({agentRoot:l,appRoot:c,source:s});u.push(...C.diagnostics);let w={agentRoot:l,appRoot:c,channels:h.sources,connections:v.connections,packageName:d,diagnostics:u,hooks:x.sources,lib:g.lib,instructions:p.instructions,sandbox:y.sandbox,sandboxWorkspaces:y.sandboxWorkspace===null?[]:[y.sandboxWorkspace],schedules:_.schedules,skills:S.skills,tools:b.sources,subagents:C.subagents};return m.module!==void 0&&(w.configModule=m.module),{diagnostics:u,manifest:createAgentSourceManifest(w)}}async function tryReadPackageJsonName(t,n){try{let r=join(n,`package.json`),i=JSON.parse(await t.readTextFile(r)).name;if(typeof i!=`string`||i.length===0)return;let a=i.lastIndexOf(`/`);return a===-1?i:i.slice(a+1)}catch{return}}export{discoverAgent};

package/dist/src/discover/discover-subagent.d.ts

@@ -0,0 +1,36 @@
+import { type DiscoverDiagnostic } from "#discover/diagnostics.js";
+import { type SubagentSourceRef } from "#discover/manifest.js";
+import { type ProjectSource } from "#discover/project-source.js";
+/**
+ * Diagnostics emitted while discovering subagent source graphs.
+ */
+export declare const DISCOVER_LOCAL_SUBAGENT_SCHEDULES_INVALID = "discover/local-subagent-schedules-invalid";
+export declare const DISCOVER_REQUIRED_SUBAGENT_CONFIG_MODULE_MISSING = "discover/required-subagent-config-module-missing";
+export declare const DISCOVER_SUBAGENTS_DIRECTORY_INVALID = "discover/subagents-directory-invalid";
+/**
+ * Input for discovering subagent entries beneath one authored source root.
+ */
+interface DiscoverSubagentsInput {
+    agentRoot: string;
+    appRoot: string;
+    /**
+     * Optional {@link ProjectSource} used for all filesystem reads. Defaults
+     * to a disk-backed source so disk callers keep their current behaviour.
+     */
+    source?: ProjectSource;
+    subagentsDirectoryPath?: string;
+    subagentsLogicalPath?: string;
+}
+/**
+ * Result of discovering local subagent packages.
+ */
+interface DiscoverSubagentsResult {
+    diagnostics: DiscoverDiagnostic[];
+    subagents: SubagentSourceRef[];
+}
+/**
+ * Discovers local subagent packages recursively without importing authored
+ * modules.
+ */
+export declare function discoverSubagents(input: DiscoverSubagentsInput): Promise<DiscoverSubagentsResult>;
+export {};

package/dist/src/discover/discover-subagent.js

@@ -0,0 +1 @@
+import{join,relative,resolve}from"node:path";import{createDiscoverErrorDiagnostic}from"#discover/diagnostics.js";import{classifyLocalSubagentEntry,getDirectoryEntryType,getSupportedModuleBaseName,normalizeLogicalPath}from"#discover/filesystem.js";import{createDiskProjectSource}from"#discover/project-source.js";import{createAgentSourceManifest,createLocalSubagentSourceRef,createModuleSourceRef}from"#discover/manifest.js";import{DISCOVER_HOOKS_DIRECTORY_INVALID,DISCOVER_TOOLS_DIRECTORY_INVALID,createHookNameDiagnostic,createToolNameDiagnostic,createUnsupportedRootDirectoryDiagnostics,discoverFlatModuleSource,discoverInstructionsSource,discoverNamedSourceDirectory,readSortedDirectoryEntries}from"#discover/grammar.js";import{discoverConnectionSources}from"#discover/connections.js";import{discoverLibSources}from"#discover/lib.js";import{discoverSandboxSource}from"#discover/sandbox.js";import{discoverSkills}from"#discover/skills.js";const DISCOVER_LOCAL_SUBAGENT_SCHEDULES_INVALID=`discover/local-subagent-schedules-invalid`,DISCOVER_REQUIRED_SUBAGENT_CONFIG_MODULE_MISSING=`discover/required-subagent-config-module-missing`,DISCOVER_SUBAGENTS_DIRECTORY_INVALID=`discover/subagents-directory-invalid`;async function discoverSubagents(i){let a=i.source??createDiskProjectSource(),l=resolve(i.agentRoot),u=resolve(i.subagentsDirectoryPath??join(l,`subagents`)),d=normalizeLogicalPath(i.subagentsLogicalPath??relative(l,u)),f=await a.stat(u);if(f===`missing`)return{diagnostics:[],subagents:[]};if(f!==`directory`)return{diagnostics:[createDiscoverErrorDiagnostic({code:DISCOVER_SUBAGENTS_DIRECTORY_INVALID,message:`Expected "${u}" to be a directory of authored subagents.`,sourcePath:u})],subagents:[]};let p=await readSortedDirectoryEntries(a,u),m=[],h=[];for(let t of p){if(t.isFile()){let n=getSupportedModuleBaseName(t.name);if(n===null)continue;h.push(discoverSingleFileSubagent({agentRoot:l,appRoot:i.appRoot,subagentId:n,subagentLogicalPath:join(d,t.name),subagentPath:join(u,t.name)}));continue}if(!t.isDirectory())continue;let n=await discoverLocalSubagentPackage({appRoot:i.appRoot,source:a,subagentId:t.name,subagentLogicalPath:join(d,t.name),subagentRoot:join(u,t.name)});m.push(...n.diagnostics),h.push(n.subagent)}return{diagnostics:m,subagents:h}}function discoverSingleFileSubagent(e){let t=createModuleSourceRef({logicalPath:e.subagentLogicalPath}),n=createAgentSourceManifest({agentId:e.subagentId,agentRoot:e.agentRoot,appRoot:e.appRoot,configModule:t});return createLocalSubagentSourceRef({entryPath:e.subagentPath,logicalPath:e.subagentLogicalPath,manifest:n,rootPath:e.agentRoot,subagentId:e.subagentId})}async function discoverLocalSubagentPackage(t){let n=[],r=await readSortedDirectoryEntries(t.source,t.subagentRoot);n.push(...createUnsupportedRootDirectoryDiagnostics({classifyEntry:classifyLocalSubagentEntry,createUnsupportedDirectoryMessage(e){return`Ignoring unsupported directory "${e}/" in the local subagent root.`},rootEntries:r,rootPath:t.subagentRoot}));let a=await discoverInstructionsSource({required:!1,rootEntries:r,rootPath:t.subagentRoot,source:t.source});n.push(...a.diagnostics);let o=discoverFlatModuleSource({missingDiagnostic:{code:DISCOVER_REQUIRED_SUBAGENT_CONFIG_MODULE_MISSING,message:`Expected one authored subagent config module at "agent.ts", "agent.cts", "agent.mts", "agent.js", "agent.cjs", or "agent.mjs".`},rootEntries:r,rootPath:t.subagentRoot,slotName:`agent`});n.push(...o.diagnostics);let s=await discoverConnectionSources({rootEntries:r,rootPath:t.subagentRoot,source:t.source});n.push(...s.diagnostics);let c=await discoverSandboxSource({rootEntries:r,rootPath:t.subagentRoot,source:t.source});n.push(...c.diagnostics);let d=await discoverNamedSourceDirectory({directoryName:`tools`,invalidDirectoryCode:DISCOVER_TOOLS_DIRECTORY_INVALID,invalidDirectoryMessage:`Expected "${join(t.subagentRoot,`tools`)}" to be a directory of authored tools.`,recursive:!0,rootEntries:r,rootPath:t.subagentRoot,source:t.source,validateSegment:createToolNameDiagnostic});n.push(...d.diagnostics);let g=await discoverNamedSourceDirectory({directoryName:`hooks`,invalidDirectoryCode:DISCOVER_HOOKS_DIRECTORY_INVALID,invalidDirectoryMessage:`Expected "${join(t.subagentRoot,`hooks`)}" to be a directory of authored hooks.`,recursive:!0,rootEntries:r,rootPath:t.subagentRoot,source:t.source,validateSegment:createHookNameDiagnostic});n.push(...g.diagnostics);let _=await discoverLibSources({agentRoot:t.subagentRoot,rootEntries:r,source:t.source});n.push(..._.diagnostics),n.push(...createLocalSubagentScheduleDiagnostics(t.subagentRoot,r));let v=await discoverSkills({agentRoot:t.subagentRoot,source:t.source});n.push(...v.diagnostics);let y=await discoverSubagents({agentRoot:t.subagentRoot,appRoot:t.appRoot,source:t.source});n.push(...y.diagnostics);let b={agentRoot:t.subagentRoot,appRoot:t.appRoot,connections:s.connections,diagnostics:n,hooks:g.sources,lib:_.lib,instructions:a.instructions,sandbox:c.sandbox,sandboxWorkspaces:c.sandboxWorkspace===null?[]:[c.sandboxWorkspace],skills:v.skills,tools:d.sources,subagents:y.subagents};o.module!==void 0&&(b.configModule=o.module);let x=createAgentSourceManifest(b);return{diagnostics:n,subagent:createLocalSubagentSourceRef({entryPath:t.subagentRoot,logicalPath:t.subagentLogicalPath,manifest:x,rootPath:t.subagentRoot,subagentId:t.subagentId})}}function createLocalSubagentScheduleDiagnostics(t,n){return n.flatMap(n=>classifyLocalSubagentEntry(n.name,getDirectoryEntryType(n))===`invalid-schedules-directory`?[createDiscoverErrorDiagnostic({code:DISCOVER_LOCAL_SUBAGENT_SCHEDULES_INVALID,message:`Local subagent packages cannot define schedules at "${join(t,n.name)}".`,sourcePath:join(t,n.name)})]:[])}export{DISCOVER_LOCAL_SUBAGENT_SCHEDULES_INVALID,DISCOVER_REQUIRED_SUBAGENT_CONFIG_MODULE_MISSING,DISCOVER_SUBAGENTS_DIRECTORY_INVALID,discoverSubagents};