@rowan-agent/agent 0.8.4 → 0.8.6

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import Type from 'typebox';
 import * as _rowan_agent_models from '@rowan-agent/models';
 import { LlmContentPart, ContentBlock, ModelRef, ModelConfig, StreamFn } from '@rowan-agent/models';
 export { ModelConfig, ModelRef, StreamFn } from '@rowan-agent/models';
+import Type from 'typebox';
 
 type AgentMessage = {
     id: string;
@@ -78,6 +78,11 @@ type PhaseExecution = {
  * Extension types — simplified for the new hook-based system.
  */
 
+interface SourceInfo {
+    source: string;
+    baseDir?: string;
+    displayName?: string;
+}
 /** Phase run function type for extensions */
 type PhaseRun = (context: PhaseContext, execution: PhaseExecution) => Promise<PhaseOutput | void>;
 /** Phase definition shape used by extensions */
@@ -135,6 +140,28 @@ interface ToolExecutionResult$1 {
     /** Whether this is an error result */
     isError?: boolean;
 }
+/**
+ * Registered tool with source metadata.
+ */
+interface RegisteredTool {
+    definition: ToolDefinition;
+    sourceInfo: SourceInfo;
+}
+/**
+ * Structured extension error with attribution.
+ */
+interface ExtensionError {
+    /** Path of the extension that caused the error */
+    extensionPath: string;
+    /** Event or operation that caused the error */
+    event: string;
+    /** Error message */
+    error: string;
+    /** Optional stack trace */
+    stack?: string;
+}
+/** Error listener callback type. */
+type ExtensionErrorListener = (error: ExtensionError) => void;
 type ExecOptions = {
     /** Working directory for the command. Defaults to cwd passed to runtime. */
     cwd?: string;
@@ -150,6 +177,18 @@ type ExecResult = {
     stdout: string;
     stderr: string;
 };
+/**
+ * Shared runtime state created by loader, used during registration and runtime.
+ * All ExtensionAPI instances reference this shared state.
+ *
+ * It only owns the lifetime guard shared by captured Extension API objects.
+ */
+interface ExtensionRuntime {
+    /** Throws when this extension instance is stale after runtime replacement. */
+    assertActive: () => void;
+    /** Marks this extension instance as stale after runtime replacement or reload. */
+    invalidate: (message?: string) => void;
+}
 /**
  * Result of loading extensions from filesystem.
  * The runner takes these and creates Extension tracking objects.
@@ -274,6 +313,17 @@ type HookEventType = HookEvent["type"];
 type HookHandler<K extends HookEventType> = (event: Extract<HookEvent, {
     type: K;
 }>) => HookResultMap[K] | Promise<HookResultMap[K]> | void | Promise<void>;
+declare class HooksManager {
+    private handlers;
+    on<K extends HookEventType>(eventType: K, handler: HookHandler<K>): void;
+    off<K extends HookEventType>(eventType: K, handler: HookHandler<K>): void;
+    emit<K extends HookEventType>(eventType: K, event: Extract<HookEvent, {
+        type: K;
+    }>): Promise<void>;
+    emitFirst<K extends HookEventType>(eventType: K, event: Extract<HookEvent, {
+        type: K;
+    }>): Promise<HookResultMap[K] | undefined>;
+}
 
 /**
  * @module extensions/context
@@ -424,7 +474,9 @@ interface ExtensionAPI {
  * Extension factory function.
  * Receives ExtensionAPI for registering hooks, phases, and providers.
  */
-type ExtensionFactory = (api: ExtensionAPI) => void | Promise<void>;
+type ExtensionDisposer = () => void | Promise<void>;
+type ExtensionFactoryResult = void | ExtensionDisposer;
+type ExtensionFactory = (api: ExtensionAPI) => ExtensionFactoryResult | Promise<ExtensionFactoryResult>;
 
 /** Unified phase output — model decides routing via route. */
 type PhaseOutput = {
@@ -467,6 +519,9 @@ type PhaseExecutionIdentity = Readonly<{
     agentId: string;
     runId: string;
     executionId: string;
+    /** Opaque metadata captured at the durable boundary; Rowan does not decode it. */
+    agentMetadata?: Readonly<Record<string, unknown>>;
+    runMetadata?: Readonly<Record<string, unknown>>;
 }>;
 /** Everything a phase needs to execute */
 interface PhaseContext {
@@ -565,6 +620,108 @@ type CoreToolContext = {
     maxBashOutputBytes?: number;
 };
 
+type PhaseRegistrySelection = Readonly<{
+    entryPhaseId: string | null;
+    phaseIds: readonly string[];
+}>;
+type AgentDefinition = Readonly<{
+    name: string;
+    description: string;
+    content: string;
+    tools?: readonly string[];
+    skills?: readonly string[];
+    phases?: PhaseRegistrySelection;
+    context?: readonly string[];
+    model?: ModelRef;
+}>;
+/** Parse one Markdown definition using the same frontmatter vocabulary as Phase resources. */
+declare function parseAgentDefinition(raw: string): AgentDefinition;
+
+type ResourceKind = "agent" | "tool" | "skill" | "phase";
+type ResourceSourceId = string;
+/** Rowan-native contribution aliases. Hosts may adapt their domain handlers to
+ * these existing Tool/Phase lifecycles without importing host Scope types. */
+type ToolContribution = Tool;
+type PhaseContribution = Phase;
+type ResourceView = Readonly<{
+    agents: readonly ResourceSourceId[];
+    tools: readonly ResourceSourceId[];
+    skills: readonly ResourceSourceId[];
+    phases: readonly ResourceSourceId[];
+}>;
+type ResourceRef = Readonly<{
+    kind: ResourceKind;
+    sourceId: ResourceSourceId;
+    name: string;
+}>;
+type ResourceDiagnostic = Readonly<{
+    kind: "invalid" | "missing" | "collision";
+    sourceId: ResourceSourceId;
+    message: string;
+    path?: string;
+}>;
+type LoadResult = Readonly<{
+    revision: string;
+    registered: readonly ResourceRef[];
+    skipped: readonly ResourceDiagnostic[];
+}>;
+type LoadInput<T> = Readonly<{
+    sourceId: ResourceSourceId;
+    directory?: string;
+    values?: readonly T[];
+}>;
+type ResolvedResourceView = Readonly<{
+    agents: readonly AgentDefinition[];
+    tools: readonly Tool[];
+    skills: readonly Skill[];
+    phases: readonly Phase[];
+    revisions: Readonly<Record<ResourceKind, readonly string[]>>;
+    refs: Readonly<Record<ResourceKind, readonly ResourceRef[]>>;
+}>;
+type ResourceRegistryErrorCode = "invalid_source_id" | "invalid_resource_name" | "resource_collision" | "resource_input_missing" | "resource_directory_not_supported" | "unknown_resource_source" | "implicit_source_protected";
+declare class ResourceRegistryError extends Error {
+    readonly code: ResourceRegistryErrorCode;
+    constructor(code: ResourceRegistryErrorCode, message: string);
+}
+type RegistryValue = AgentDefinition | Tool | Skill | Phase;
+/**
+ * Runtime Resource Registry source transaction and view resolver.
+ *
+ * Directory normalization is intentionally added by the typed loader slice;
+ * this first module owns only the atomic source/revision/collision semantics.
+ */
+declare class ResourceRegistry {
+    private readonly sources;
+    /** Sources registered by the bootstrap boundary (currently Extensions). */
+    private readonly implicitSources;
+    private revisionSequence;
+    loadAgents(input: LoadInput<AgentDefinition>): Promise<LoadResult>;
+    loadSkills(input: LoadInput<Skill>): Promise<LoadResult>;
+    loadPhases(input: LoadInput<Phase>): Promise<LoadResult>;
+    loadTools(input: Readonly<{
+        sourceId: ResourceSourceId;
+        values: readonly ToolContribution[];
+    }>): Promise<LoadResult>;
+    unload(input: Readonly<{
+        kind: ResourceKind;
+        sourceId: ResourceSourceId;
+    }>): Promise<LoadResult>;
+    resolveView(view: ResourceView): ResolvedResourceView;
+    /** Mark one already-loaded source as implicit for every Resource View. */
+    protected markImplicit(kind: ResourceKind, sourceId: ResourceSourceId): void;
+    /** Bootstrap-only helper for replacing an implicit contribution source. */
+    protected replaceImplicit<T extends RegistryValue>(kind: ResourceKind, sourceId: ResourceSourceId, values: readonly T[]): Promise<LoadResult>;
+    protected hasImplicit(kind: ResourceKind, sourceId: ResourceSourceId): boolean;
+    private withImplicit;
+    private collect;
+    private commit;
+    private resolveKind;
+    private resolveRevisions;
+    private resolveRefs;
+    private sourcesFor;
+    private nextRevision;
+}
+
 /** Durable and transient DTOs owned by the event-driven Agent Runtime. */
 declare const opaqueIdBrand: unique symbol;
 type OpaqueId<Kind extends string> = string & {
@@ -865,6 +1022,260 @@ type ToolProgress = Readonly<{
 }>;
 type RunEvent = DurableRunEvent | MessageDelta | ToolProgress;
 
+/**
+ * Extension runner — manages extension loading and hook execution.
+ *
+ * Architecture reference: PI's ExtensionRunner
+ * - Per-extension tracking via Extension objects
+ * - Shared ExtensionRuntime with invalidate/assertActive
+ * - Direct `on()` API for hook registration
+ * - Error listener pattern for structured error handling
+ * - Tool registration support
+ */
+
+type ExtensionRunnerOptions = {
+    entryPhaseId?: string | null;
+    cwd?: string;
+};
+/**
+ * Manages extensions and provides hooks for the agent loop.
+ *
+ * Features:
+ * - Per-extension tracking (handlers, tools, phases)
+ * - Shared runtime with lifecycle protection (invalidate/assertActive)
+ * - Error listener pattern for structured error handling
+ * - Direct hook API and extension-loaded hook API
+ * - Tool registration for LLM-callable tools
+ * - EventBus for inter-extension communication
+ *
+ * @example
+ * ```ts
+ * const runner = createExtensionRunner();
+ *
+ * // Direct hook registration
+ * const unsub = runner.on("before_tool_call", (event) => {
+ *   return { allow: false, reason: "Blocked" };
+ * });
+ *
+ * // Error handling
+ * runner.onError((error) => {
+ *   console.error(`Extension error in ${error.extensionPath}:`, error.error);
+ * });
+ *
+ * // Load extensions
+ * await runner.loadExtensions(extensions);
+ * runner.bind();
+ * ```
+ */
+declare class ExtensionRunner {
+    readonly hooks: HooksManager;
+    readonly runtime: ExtensionRuntime;
+    readonly events: EventBus;
+    private readonly cwd;
+    private readonly abortController;
+    private _idle;
+    private readonly extensions;
+    private readonly phases;
+    private _phaseCache;
+    private readonly pendingProviders;
+    private bound;
+    private readonly errorListeners;
+    /** Current agent context — set by the agent before each phase */
+    currentContext?: AgentContext;
+    constructor(options?: ExtensionRunnerOptions);
+    /** Whether the agent is currently idle (not streaming). */
+    get isIdle(): boolean;
+    /** Set idle state — called by the agent loop. */
+    setIdle(idle: boolean): void;
+    /** Abort signal for the current runner instance. */
+    get signal(): AbortSignal;
+    /** Abort the current runner operation. */
+    abort(): void;
+    /**
+     * Register an error listener.
+     * Returns an unsubscribe function.
+     */
+    onError(listener: ExtensionErrorListener): () => void;
+    /**
+     * Emit a structured extension error to all listeners.
+     */
+    emitError(error: ExtensionError): void;
+    /**
+     * Mark all extension contexts as stale.
+     * After calling this, any captured ExtensionAPI or ExtensionContext will throw
+     * on use. Used during runtime replacement or reload.
+     */
+    invalidate(message?: string): void;
+    /**
+     * Subscribe to a specific hook event type.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const unsub = runner.on("before_tool_call", (event) => {
+     *   return { allow: false, reason: "Blocked" };
+     * });
+     * unsub(); // Cancel subscription
+     * ```
+     */
+    on<K extends HookEventType>(type: K, handler: HookHandler<K>): () => void;
+    /**
+     * Load and initialize extensions.
+     * Creates Extension tracking objects and calls each factory with an ExtensionAPI.
+     */
+    loadExtensions(extensions: LoadedExtension[]): Promise<void>;
+    /** Dispose all active Extensions in reverse activation order. */
+    close(): Promise<void>;
+    /** Get all registered tools from all extensions. */
+    getAllRegisteredTools(): RegisteredTool[];
+    /**
+     * Get a tool definition by name. Returns undefined if not found.
+     */
+    getToolDefinition(toolName: string): RegisteredTool["definition"] | undefined;
+    getPhase(name: string): Phase | undefined;
+    getPhases(): Phase[];
+    createPhaseRegistry(input?: {
+        entryPhaseId?: string | null;
+    }): PhaseRegistry;
+    /** Adapt an extension RegisteredPhase to the core Phase type. */
+    private adaptToPhase;
+    /**
+     * Bind the runner — flushes pending provider registrations and
+     * replaces runtime stubs with real implementations.
+     */
+    bind(): void;
+    /**
+     * Generic emit — fire-and-forget for any event type.
+     */
+    emit<K extends HookEventType>(eventType: K, event: Parameters<HookHandler<K>>[0]): Promise<void>;
+    /**
+     * Unified hook emission — returns the first non-undefined result.
+     */
+    private emitHook;
+    emitBeforePhase(phaseId: string, input: PhaseContext): Promise<{
+        abort?: any;
+        skip?: any;
+        input?: PhaseContext;
+    }>;
+    emitAfterPhase(phaseId: string, output: PhaseOutput): Promise<{
+        abort?: any;
+        retry?: PhaseContext;
+        output?: PhaseOutput;
+    }>;
+    emitBeforePrompt(phaseId: string, input: PhaseContext): Promise<PhaseContext>;
+    emitBeforeToolCall(tool: Tool$1, args: unknown): Promise<{
+        allow: boolean;
+        reason?: string;
+    }>;
+    emitAfterToolCall(tool: Tool$1, result: ToolResult): Promise<ToolResult>;
+    /**
+     * Create an ExtensionAPI for a specific extension.
+     * Registration methods write to the extension tracking object.
+     * Action methods delegate to the shared runtime.
+     */
+    private createExtensionAPI;
+    private registerTool;
+    private registerPhase;
+    private registerProvider;
+    private unregisterProvider;
+    private flushPendingProviders;
+    private getRegisteredPhase;
+    private collectRegisteredPhases;
+    private rollbackExtension;
+    private disposeExtension;
+}
+
+type ExtensionContribution = LoadedExtension;
+type ExtensionLoadInput = LoadInput<ExtensionContribution>;
+type ExtensionActivationError = Readonly<{
+    path: string;
+    error: string;
+}>;
+type ExtensionActivationResult = Readonly<{
+    active: readonly string[];
+    errors: readonly ExtensionActivationError[];
+    revision?: string;
+    registered?: readonly string[];
+    skipped?: readonly ResourceDiagnostic[];
+}>;
+type ExtensionLifetimeErrorCode = "extensions_frozen" | "extensions_closed";
+declare class ExtensionLifetimeError extends Error {
+    readonly code: ExtensionLifetimeErrorCode;
+    constructor(code: ExtensionLifetimeErrorCode, message: string);
+}
+/** Runtime-global Extension activation and lifetime boundary. */
+declare class RuntimeExtensionLifetime {
+    private readonly runner;
+    private frozen;
+    private closed;
+    constructor(options?: {
+        cwd?: string;
+    });
+    activate(extensions: readonly LoadedExtension[]): Promise<ExtensionActivationResult>;
+    tools(): readonly RegisteredTool[];
+    phases(): readonly Phase[];
+    get extensionRunner(): ExtensionRunner;
+    close(): Promise<void>;
+}
+/** Bootstrap-only Registry facade; its Extension method disappears after init. */
+declare class RuntimeBootstrapRegistry extends ResourceRegistry {
+    private readonly extensions;
+    private readonly extensionSourceId;
+    constructor(extensions?: RuntimeExtensionLifetime);
+    /** Install Rowan-owned implicit resources before any host source is read. */
+    ensureCoreResources(): Promise<void>;
+    loadExtensions(input: readonly LoadedExtension[] | ExtensionLoadInput): Promise<ExtensionActivationResult>;
+    get extensionRunner(): ExtensionRunner;
+    get extensionTools(): readonly RegisteredTool[];
+    get extensionPhases(): readonly Phase[];
+    closeExtensions(): Promise<void>;
+}
+
+type DefinitionLayer = Readonly<{
+    description?: string;
+    content?: string;
+    model?: ModelRef;
+    tools?: readonly string[];
+    skills?: readonly string[];
+    phases?: PhaseRegistrySelection;
+}>;
+type AgentConfiguration = Readonly<{
+    identity: string;
+    definition: Readonly<{
+        name: string;
+        layer?: DefinitionLayer;
+    }>;
+    resourceView: ResourceView;
+    contexts?: readonly ContextCandidate[];
+    cwd?: string;
+    maxAttempts?: number;
+    model: ModelConfig | ModelRef;
+    stream?: StreamFn;
+}>;
+type ConfigurationSnapshot = Readonly<{
+    identity: string;
+    definition: AgentDefinition;
+    resources: Readonly<{
+        tools: readonly Tool[];
+        skills: readonly Skill[];
+        phases?: PhaseRegistry;
+        revisions: Readonly<Record<ResourceKind, readonly string[]>>;
+        refs: Readonly<Record<ResourceKind, readonly ResourceRef[]>>;
+    }>;
+    contexts: readonly ContextCandidate[];
+    resourceView: ResourceView;
+    cwd?: string;
+    maxAttempts?: number;
+    model: ModelConfig | ModelRef;
+    stream?: StreamFn;
+}>;
+/** Resolve one Definition request into one immutable, source-qualified snapshot. */
+declare function resolveConfigurationSnapshot(registry: ResourceRegistry, input: AgentConfiguration): ConfigurationSnapshot;
+/** Materialize the immutable resolver output at the legacy execution seam.
+ * The conversion is intentionally one-way: callers cannot feed concrete
+ * candidate bags back through the public configuration request. */
+declare function materializeConfigurationSnapshot(snapshot: ConfigurationSnapshot): AgentConfig;
+
 type UserInput = string | Readonly<{
     content: UserContent;
     metadata?: Metadata;
@@ -872,6 +1283,10 @@ type UserInput = string | Readonly<{
 type ToolInvocationContext = Readonly<{
     agentId: AgentId;
     runId: RunId;
+    /** Opaque JSON metadata captured from the Agent and Run records. Rowan does
+     * not interpret host/domain fields. */
+    agentMetadata?: Metadata;
+    runMetadata?: Metadata;
     toolCallId: ToolCallId;
     reportProgress(progress: JsonValue): void;
 }>;
@@ -881,6 +1296,10 @@ type Tool = Readonly<{
     parameters: Type.TSchema;
     execute(args: JsonValue, context: ToolInvocationContext, signal: AbortSignal): Promise<ToolExecutionResult>;
 }>;
+type ContextCandidate = Readonly<{
+    name: string;
+    value: JsonValue;
+}>;
 type BeforeToolCall = (input: Readonly<{
     tool: Tool;
     args: JsonValue;
@@ -903,17 +1322,21 @@ type AfterToolCall = (input: Readonly<{
     context: ToolInvocationContext;
     signal: AbortSignal;
 }>) => ToolExecutionResult | Promise<ToolExecutionResult>;
-type AgentDefinitionContext = Readonly<{
-    systemPrompt: string;
+type AgentResources = Readonly<{
     tools: readonly Tool[];
     skills: readonly Skill[];
     phases?: PhaseRegistry;
+    contexts?: readonly ContextCandidate[];
+    /** Source-qualified snapshot metadata retained for restart/recovery checks. */
+    resourceView?: ResourceView;
+    resourceRefs?: readonly ResourceRef[];
+    resourceRevisions?: Readonly<Record<ResourceKind, readonly string[]>>;
 }>;
 type AgentConfig = Readonly<{
     identity: string;
-    context: AgentDefinitionContext;
+    definition: AgentDefinition;
+    resources: AgentResources;
     cwd?: string;
-    extensions?: readonly LoadedExtension[];
     maxAttempts?: number;
     beforeToolCall?: BeforeToolCall;
     afterToolCall?: AfterToolCall;
@@ -924,6 +1347,8 @@ type AgentConfig = Readonly<{
     model: ModelRef;
     stream: StreamFn;
 })>;
+/** Definition-reference request accepted at the public Runtime seam. */
+type AgentConfigRequest = AgentConfig | AgentConfiguration;
 type AgentRecord = Readonly<{
     id: AgentId;
     metadata?: Metadata;
@@ -1070,7 +1495,7 @@ type RunBoundary = Readonly<{
 }>;
 type ConfigResolution = Readonly<{
     kind: "available";
-    config: AgentConfig;
+    config: AgentConfigRequest;
 } | {
     kind: "deferred";
     retryAfterMs?: number;
@@ -1088,7 +1513,7 @@ interface ConfigProvider {
     put(input: {
         agentId: AgentId;
         agentMetadata?: Metadata;
-        config: AgentConfig;
+        config: AgentConfigRequest;
         operationId: string;
         signal: AbortSignal;
     }): Promise<ConfigPutResult>;
@@ -1219,6 +1644,7 @@ type AgentRuntimeOptions = Readonly<{
     store: DurableStore;
     configs?: ConfigProvider;
     concurrency?: number;
+    bootstrap?: (registry: RuntimeBootstrapRegistry) => void | Promise<void>;
 }>;
 type DurableConsumer = Readonly<{
     caughtUp: Promise<void>;
@@ -1242,11 +1668,22 @@ interface AgentRun {
     cancel(reason?: string): Promise<RunBoundary>;
 }
 interface AgentRuntime$1 {
-    createAgent(config: AgentConfig, options?: {
+    loadAgents(input: LoadInput<AgentDefinition>): Promise<LoadResult>;
+    loadSkills(input: LoadInput<Skill>): Promise<LoadResult>;
+    loadPhases(input: LoadInput<Phase>): Promise<LoadResult>;
+    loadTools(input: Readonly<{
+        sourceId: string;
+        values: readonly Tool[];
+    }>): Promise<LoadResult>;
+    unload(input: Readonly<{
+        kind: ResourceKind;
+        sourceId: string;
+    }>): Promise<LoadResult>;
+    createAgent(config: AgentConfigRequest, options?: {
         idempotencyKey?: string;
         metadata?: Metadata;
     }): Promise<AgentId>;
-    updateAgentConfig(agentId: AgentId, config: AgentConfig, options: {
+    updateAgentConfig(agentId: AgentId, config: AgentConfigRequest, options: {
         idempotencyKey: string;
     }): Promise<void>;
     start(agentId: AgentId, input: UserInput, options: {
@@ -1287,16 +1724,28 @@ declare class AgentRuntime implements AgentRuntime$1 {
     private readonly executions;
     private readonly consumers;
     private readonly transientEvents;
+    private readonly resources;
     private heartbeat?;
     private pumping;
     private closed;
     private constructor();
     static init(options: AgentRuntimeOptions): Promise<AgentRuntime>;
-    createAgent(config: AgentConfig, options?: {
+    loadAgents(input: LoadInput<AgentDefinition>): Promise<LoadResult>;
+    loadSkills(input: LoadInput<Skill>): Promise<LoadResult>;
+    loadPhases(input: LoadInput<Phase>): Promise<LoadResult>;
+    loadTools(input: Readonly<{
+        sourceId: string;
+        values: readonly Tool[];
+    }>): Promise<LoadResult>;
+    unload(input: Readonly<{
+        kind: ResourceKind;
+        sourceId: string;
+    }>): Promise<LoadResult>;
+    createAgent(config: AgentConfigRequest, options?: {
         idempotencyKey?: string;
         metadata?: Metadata;
     }): Promise<AgentId>;
-    updateAgentConfig(agentId: AgentId, config: AgentConfig, options: {
+    updateAgentConfig(agentId: AgentId, config: AgentConfigRequest, options: {
         idempotencyKey: string;
     }): Promise<void>;
     start(agentId: AgentId, input: UserInput, options: {
@@ -1344,6 +1793,7 @@ declare class AgentRuntime implements AgentRuntime$1 {
         signal?: AbortSignal;
     }): Promise<RunBoundary>;
     private assertOpen;
+    private materializeConfig;
     private startHeartbeat;
 }
 
@@ -1678,7 +2128,7 @@ declare class InMemoryConfigProvider implements ConfigProvider {
     put(input: {
         agentId: AgentId;
         agentMetadata?: Metadata;
-        config: AgentConfig;
+        config: AgentConfigRequest;
         operationId: string;
         signal: AbortSignal;
     }): Promise<ConfigPutResult>;
@@ -1806,6 +2256,17 @@ declare function loadExtensionsFromPath(path: string): Promise<{
     }>;
 }>;
 
+/** Parsed frontmatter result */
+interface FrontmatterResult<T = Record<string, unknown>> {
+    frontmatter: T;
+    body: string;
+}
+/**
+ * Parse YAML frontmatter from markdown content.
+ * Parse YAML frontmatter and return the markdown body after the closing delimiter.
+ */
+declare function parseFrontmatter<T = Record<string, unknown>>(raw: string): FrontmatterResult<T>;
+
 declare function createCoreTools(input?: CoreToolContext): Tool[];
 
-export { type AfterToolCall, type AgentConfig, type AgentDefinitionContext, type AgentId, type AgentListCursor, type AgentRecord, type AgentRun, AgentRuntime, type AgentRuntimeOptions, type AgentSummary, type AnyRuntimeError, type AssistantContent, type AssistantMessage, type BeforeToolCall, type ConfigProvider, type ConfigPutResult, type ConfigResolution, type ConfigToken, type CoreToolContext, type DurableConsumer, type DurableRunEvent, type DurableStore, type DurableToolResult, type EventCursor, type EventId, type ExecutionCheckpoint, type ExecutionId, type ExecutionToken, type ExtensionAPI, type ExtensionFactory, type HookEvent, type HookEventType, type HookHandler, InMemoryConfigProvider, InMemoryStore, type InputRequest, type InputRequestId, type InputRequiredCommit, type JsonObject, type JsonPrimitive, type JsonValue, type LoadExtensionsResult, type LoadedExtension, type Message, type MessageBase, type MessageCommitted, type MessageContent, type MessageDelta, type MessageId, type Metadata, type OpaqueId, type Outcome, type OwnerLease, type OwnerToken, type Page, type Phase, type PhaseContext, type PhaseExecutionIdentity, type PhaseInvocation, type PhaseOutput, type PhaseRegistry, type PhaseState, type RunBoundary, type RunClaim, type RunEvent, type RunFailure, type RunId, type RunListCursor, type RunRecord, type RunSnapshot, type RunState, type RunStateChanged, type RunSummary, RuntimeError, type RuntimeErrorCode, type RuntimeErrorDetails, type Skill, SqliteStore, type TextContent, type ThinkingContent, type Tool, type ToolCallId, type ToolCallSnapshot, type ToolCallState, type ToolDefinition, type ToolExecutionResult, type ToolInvocationContext, type ToolMessage, type ToolMessageContent, type ToolProgress, type ToolResultContent, type ToolStateChanged, type ToolUseContent, type UserContent, type UserInput, type UserMessage, brandConfigToken, createCoreTools, isRuntimeError, loadExtensionsFromPath as loadExtensions, loadPhases, loadSkills };
+export { type AfterToolCall, type AgentConfig, type AgentConfigRequest, type AgentConfiguration, type AgentDefinition, type AgentId, type AgentListCursor, type AgentRecord, type AgentResources, type AgentRun, AgentRuntime, type AgentRuntimeOptions, type AgentSummary, type AnyRuntimeError, type AssistantContent, type AssistantMessage, type BeforeToolCall, type ConfigProvider, type ConfigPutResult, type ConfigResolution, type ConfigToken, type ConfigurationSnapshot, type ContextCandidate, type CoreToolContext, type DefinitionLayer, type DurableConsumer, type DurableRunEvent, type DurableStore, type DurableToolResult, type EventCursor, type EventId, type ExecutionCheckpoint, type ExecutionId, type ExecutionToken, type ExtensionAPI, type ExtensionActivationError, type ExtensionActivationResult, type ExtensionContribution, type ExtensionDisposer, type ExtensionFactory, type ExtensionFactoryResult, ExtensionLifetimeError, type ExtensionLifetimeErrorCode, type ExtensionLoadInput, type FrontmatterResult, type HookEvent, type HookEventType, type HookHandler, InMemoryConfigProvider, InMemoryStore, type InputRequest, type InputRequestId, type InputRequiredCommit, type JsonObject, type JsonPrimitive, type JsonValue, type LoadExtensionsResult, type LoadInput, type LoadResult, type LoadedExtension, type Message, type MessageBase, type MessageCommitted, type MessageContent, type MessageDelta, type MessageId, type Metadata, type OpaqueId, type Outcome, type OwnerLease, type OwnerToken, type Page, type Phase, type PhaseContext, type PhaseContribution, type PhaseExecutionIdentity, type PhaseInvocation, type PhaseOutput, type PhaseRegistry, type PhaseRegistrySelection, type PhaseState, type ResolvedResourceView, type ResourceDiagnostic, type ResourceKind, type ResourceRef, ResourceRegistry, ResourceRegistryError, type ResourceRegistryErrorCode, type ResourceSourceId, type ResourceView, type RunBoundary, type RunClaim, type RunEvent, type RunFailure, type RunId, type RunListCursor, type RunRecord, type RunSnapshot, type RunState, type RunStateChanged, type RunSummary, RuntimeBootstrapRegistry, RuntimeError, type RuntimeErrorCode, type RuntimeErrorDetails, RuntimeExtensionLifetime, type Skill, SqliteStore, type TextContent, type ThinkingContent, type Tool, type ToolCallId, type ToolCallSnapshot, type ToolCallState, type ToolContribution, type ToolDefinition, type ToolExecutionResult, type ToolInvocationContext, type ToolMessage, type ToolMessageContent, type ToolProgress, type ToolResultContent, type ToolStateChanged, type ToolUseContent, type UserContent, type UserInput, type UserMessage, brandConfigToken, createCoreTools, isRuntimeError, loadExtensionsFromPath as loadExtensions, loadPhases, loadSkills, materializeConfigurationSnapshot, parseAgentDefinition, parseFrontmatter, resolveConfigurationSnapshot };