@rowan-agent/agent 0.4.11 → 0.5.0

package/README.md

@@ -50,6 +50,11 @@ class Agent {
   waitForIdle(): Promise<void>;
   flushEvents(): Promise<void>;
   readonly status: AgentStatus;
+
+  // Resource loading — replaces standalone loadSkills/loadPhases/loadExtensions
+  static loadSkills(targetPath: string): Promise<Skill[]>;
+  static loadPhases(targetPath: string): Promise<PhaseRegistry>;
+  static loadExtensions(targetPath: string): Promise<LoadExtensionsResult>;
 }
 ```
 
@@ -60,12 +65,8 @@ type AgentOptions = {
   context: AgentContext;
   model: LlmModelRef;
   stream: StreamFn;
-  cwd?: string;
-  rowanDir?: string;     // project-local Rowan directory, default: ".rowan"
+  extensions?: LoadedExtension[];
   sessionId?: string;
-  phases?: PhaseRegistry;
-  extensions?: ExtensionRunnerRef;
-  signal?: AbortSignal;
   maxAttempts?: number;
 
   // Lifecycle hooks
@@ -99,6 +100,8 @@ type AgentContext = {
   messages: AgentMessage[];
   tools: Tool[];
   skills: Skill[];
+  // Optional custom phases; Agent merges them with its built-in "default" phase.
+  phases?: PhaseRegistry;
 };
 ```
 
@@ -239,12 +242,9 @@ await session.branch(entryId);
 Skills are `SKILL.md` knowledge bundles that get injected into the agent context, extending its domain knowledge without changing code.
 
 ```ts
-import { loadSkill, loadSkills, resolveSkillPath } from "@rowan-agent/agent";
+import { Agent } from "@rowan-agent/agent";
 
-const skills = await loadSkills(workspace);
-const skill = await loadSkill(path, workspace);
-const path = resolveSkillPath("example", workspace);
-// → <rowanDir>/skills/example/SKILL.md
+const skills = await Agent.loadSkills("/User/Skills");
 ```
 
 ## Phases
@@ -257,7 +257,7 @@ Each phase's `PHASE.md` content is injected as a system message, giving the LLM
 
 ```
 Per iteration:
-  1. Hot-reload phase configs from disk (PHASE.md)
+  1. Read Agent-normalized `context.phases`
   2. Inject phase instructions as system message
   3. Execute phase (factory | run | LLM fallback)
   4. Extract routing decision from route tool call
@@ -402,15 +402,17 @@ Each target gets a forked copy of the current messages (or empty if `isolated: t
 The extension system lets plugins register lifecycle hooks, tools, phases, model providers, and cross-plugin events. Plugins are discovered from `<workspace>/.rowan/extensions`.
 
 ```ts
-import { createExtensionRunner, discoverAndLoadExtensions } from "@rowan-agent/agent";
+import { Agent } from "@rowan-agent/agent";
 
-const { extensions } = await discoverAndLoadExtensions(cwd);
-const runner = createExtensionRunner({ cwd });
-await runner.loadExtensions(extensions);
+const { extensions } = await Agent.loadExtensions(`${cwd}/.rowan/extensions`);
+// Pass extensions to the Agent constructor — they are loaded and bound internally
+const agent = new Agent({ context, model, stream, extensions });
 ```
 
 ### ExtensionRunner
 
+`ExtensionRunner` is used internally by Agent when extensions are passed via the constructor or `run()`. The Agent manages the runner lifecycle — load, bind, invalidate — automatically.
+
 ```ts
 class ExtensionRunner {
   readonly hooks: HooksManager;  // 19 lifecycle hook types
@@ -462,7 +464,7 @@ export default function myPlugin(rowan: ExtensionAPI) {
 
 Multi-provider model configuration via `.rowan/config.yaml`. Supports multiple API providers, per-model settings, environment variable interpolation, and per-phase model overrides.
 
-Config is loaded from the runtime Rowan directory, which defaults to `.rowan` and can be set when constructing `Agent` via `rowanDir`.
+Config is loaded from the runtime Rowan directory, which defaults to `.rowan`.
 
 ### Config File
 
@@ -636,13 +638,13 @@ const request = buildModelRequest({ systemPrompt, messages, tools });
 
 ## Workspace
 
-Workspace resolution uses the current project for both source and binary runs. The project Rowan directory defaults to `<cwd>/.rowan`; pass `rowanDir` to resolve another project-local directory.
+Workspace resolution uses the current project root. The project Rowan directory defaults to `<cwd>/.rowan`; pass `rowanDir` to resolve another project-local directory.
 
 ```ts
 import { resolveWorkspacePaths, resolveInWorkspace } from "@rowan-agent/agent";
 
 const workspace = resolveWorkspacePaths();
-// → { mode: "source" | "binary", cwd: string, rowanDir: string }
+// → { cwd: string, rowanDir: string }
 
 const custom = resolveWorkspacePaths({ rowanDir: ".rowan-project" });
 // → custom.rowanDir is <cwd>/.rowan-project
@@ -666,7 +668,7 @@ type LoopMetrics = {
 | Type | Description |
 |------|-------------|
 | `Agent` | Main agent facade |
-| `AgentContext` | System prompt, messages, tools, skills |
+| `AgentContext` | System prompt, messages, tools, skills, phases |
 | `AgentMessage` | Typed message with role, content, metadata |
 | `AgentEvent` | Discriminated union of 13 event types |
 | `Tool` / `ToolResult` | Tool definition and execution result |
@@ -694,4 +696,4 @@ type LoopMetrics = {
 
 ## Version
 
-Current version: **0.4.6**
+Current version: **0.4.11**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _rowan_agent_models from '@rowan-agent/models';
-import { LlmRequest, LlmResponse, LlmModelRef, LlmModelUsage, StreamFn, AgentEventListener, ToolCall, ToolResult, AgentMessage, Outcome, Skill as Skill$1, ContentBlock, ProviderConfig, Protocol, ModelCost, AgentEvent, LlmMessage } from '@rowan-agent/models';
+import { LlmRequest, LlmResponse, LlmModelRef, LlmModelUsage, AgentMessage, Skill as Skill$1, ToolResult, Outcome, ContentBlock, ToolCall, ProviderConfig, StreamFn, AgentEventListener, Protocol, ModelCost, AgentEvent, LlmMessage } from '@rowan-agent/models';
 export { AgentEvent, AgentEventListener, AgentMessage, LlmModelRef, Outcome, Skill, StreamFn, ToolResult, createDispatchStream, registerBuiltInApiProviders } from '@rowan-agent/models';
 import Type from 'typebox';
 
@@ -23,9 +23,6 @@ type ModelTranscript = {
     response: LlmResponse;
 };
 
-type BeforePhaseHook = (phaseId: string, input: PhaseContext) => Promise<BeforePhaseHookResult>;
-type AfterPhaseHook = (phaseId: string, output: PhaseOutput) => Promise<AfterPhaseHookResult>;
-type BeforePromptHook = (phaseId: string, input: PhaseContext) => Promise<PhaseContext>;
 type LoopMetrics = {
     /** Number of phase iterations executed. */
     iterations: number;
@@ -54,37 +51,6 @@ type SessionState = {
     metrics: LoopMetrics;
     status: "idle" | "running" | "completed" | "aborted" | "failed";
 };
-type AgentConfig = {
-    context: AgentContext;
-    sessionId?: string;
-    model: LlmModelRef;
-    stream: StreamFn;
-    signal?: AbortSignal;
-    emit?: AgentEventListener;
-    phases?: PhaseRegistry;
-    runtime?: AgentRuntimePort;
-    beforeToolCall?: BeforeToolCall;
-    afterToolCall?: AfterToolCall;
-    beforePhase?: BeforePhaseHook;
-    afterPhase?: AfterPhaseHook;
-    beforePrompt?: BeforePromptHook;
-    maxAttempts?: number;
-    onModelTranscript?: (transcript: ModelTranscript, meta: {
-        phase: string;
-        model: LlmModelRef;
-    }) => Promise<void>;
-    onMessage?: (message: AgentMessage) => Promise<void>;
-    onOutcome?: (outcome: Outcome) => Promise<void>;
-    sessionState?: SessionState;
-};
-type ToolRunnerInput = {
-    config: AgentConfig;
-    toolCall: ToolCall;
-};
-type ToolRunner = (input: ToolRunnerInput) => Promise<ToolResult>;
-type AgentRuntimePort = {
-    tools?: ToolRunner;
-};
 
 type ToolContext = Pick<AgentContext, "skills"> & {
     toolCallId: string;
@@ -112,6 +78,8 @@ type AgentContext = {
     tools: Tool[];
     /** Skills available for this run. */
     skills: Skill$1[];
+    /** Custom phases for this run. Agent normalizes this with the built-in default phase. */
+    phases?: PhaseRegistry;
 };
 type BeforeToolCall = (input: {
     tool: Tool;
@@ -238,7 +206,7 @@ interface Phase {
 interface PhaseRegistry {
     /** Map of phase id to Phase object */
     phases: Map<string, Phase>;
-    /** Entry phase id (null if no phases defined) */
+    /** Entry phase id (null until Agent applies its default phase) */
     entryPhaseId: string | null;
 }
 
@@ -387,10 +355,8 @@ type HandlerFn = (...args: unknown[]) => Promise<unknown>;
  * Tracks what each extension registered for attribution and cleanup.
  */
 interface Extension {
-    /** Extension path (may be synthetic like `<builtin:phase:chat>`) */
+    /** Extension path (may be synthetic like `<inline>`) */
     path: string;
-    /** Resolved absolute path */
-    resolvedPath: string;
     /** Source info for error messages */
     sourceInfo: SourceInfo;
     /** Event handlers registered by this extension */
@@ -403,7 +369,7 @@ interface Extension {
 /**
  * Create an Extension object with empty collections.
  */
-declare function createExtension(extensionPath: string, resolvedPath: string, sourceInfo: SourceInfo): Extension;
+declare function createExtension(extensionPath: string, sourceInfo: SourceInfo): Extension;
 /**
  * Shared runtime state created by loader, used during registration and runtime.
  * All ExtensionAPI instances reference this shared state.
@@ -459,7 +425,6 @@ type LoadExtensionsResult = {
  */
 interface LoadedExtension {
     path: string;
-    resolvedPath: string;
     name: string;
     factory: ExtensionFactory;
     manifest?: ExtensionManifest;
@@ -1342,48 +1307,11 @@ declare class ExtensionRunner {
 }
 declare function createExtensionRunner(options?: ExtensionRunnerOptions): ExtensionRunner;
 
-/**
- * Extension loader — discovers and loads extensions from the filesystem.
- *
- * Uses the new LoadedExtension type that works with ExtensionRunner.
- */
-
-/**
- * Load a single extension from a factory function.
- */
-declare function loadExtensionFromFactory(factory: ExtensionFactory, cwd: string, extensionPath?: string): LoadedExtension;
-/**
- * Load extensions from file paths.
- */
-declare function loadExtensions(paths: string[], cwd: string): Promise<{
-    extensions: LoadedExtension[];
-    errors: Array<{
-        path: string;
-        error: string;
-    }>;
-}>;
-/**
- * Discover and load extensions from .rowan/extensions directory.
- */
-declare function discoverAndLoadExtensions(cwd: string): Promise<{
-    extensions: LoadedExtension[];
-    errors: Array<{
-        path: string;
-        error: string;
-    }>;
-}>;
-
-type ExtensionRunnerRef = {
-    current?: ExtensionRunner;
-};
 type AgentOptions = {
     context: AgentContext;
     model: LlmModelRef;
     stream: StreamFn;
-    cwd?: string;
-    rowanDir?: string;
-    phases?: PhaseRegistry;
-    extensionRunnerRef?: ExtensionRunnerRef;
+    extensions?: LoadedExtension[];
     sessionId?: string;
     maxAttempts?: number;
     beforeToolCall?: BeforeToolCall;
@@ -1395,7 +1323,7 @@ type AgentOptions = {
         model: LlmModelRef;
     }) => Promise<void>;
 };
-type RunOptions = Partial<AgentConfig> & Pick<AgentConfig, "context">;
+type RunOptions = Partial<AgentOptions>;
 type AgentStatus = {
     sessionId?: string;
     context: AgentContext;
@@ -1412,6 +1340,11 @@ declare class Agent {
     private readonly pendingListenerTasks;
     private readonly listenerErrors;
     private activeRun?;
+    private extensionRunner?;
+    private loadedExtensions?;
+    static loadSkills(targetPath: string): Promise<AgentContext["skills"]>;
+    static loadPhases(targetPath: string): Promise<PhaseRegistry>;
+    static loadExtensions(targetPath: string): Promise<LoadExtensionsResult>;
     constructor(options: AgentOptions);
     subscribe(listener: AgentEventListener): Unsubscribe;
     private emitToListeners;
@@ -1443,16 +1376,9 @@ declare class Agent {
      */
     private handleBeforePrompt;
     private handleRunFailure;
-    /**
-     * Discover and load phases and skills from the workspace.
-     *
-     * - Auto-discovers file-based phases from .rowan/phases/
-     * - Auto-discovers skills from .rowan/skills/
-     * - Merges with CLI-provided phases and skills
-     */
-    private discoverResources;
     private runWithLifecycle;
     private finishRun;
+    private loadExtensions;
     run(config?: RunOptions): Promise<RunResult>;
     abort(reason?: string): void;
     /**
@@ -1688,28 +1614,19 @@ type CoreToolContext = {
 };
 declare function createCoreTools(input?: CoreToolContext): Tool[];
 
-type RuntimeMode = "source" | "binary";
 type WorkspacePaths = {
-    mode: RuntimeMode;
     cwd: string;
     rowanDir: string;
 };
 type ResolveWorkspaceOptions = {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
-    execPath?: string;
-    entrypoint?: string;
     homeDir?: string;
-    mode?: RuntimeMode;
     rowanDir?: string;
 };
 declare function resolveWorkspacePaths(options?: ResolveWorkspaceOptions): WorkspacePaths;
 declare function resolveInWorkspace(path: string, rootOrPaths: string | Pick<WorkspacePaths, "cwd">): string;
 
-declare function resolveSkillPath(input: string, workspace?: WorkspacePaths): string;
-declare function loadSkill(path: string, workspace?: WorkspacePaths): Promise<Skill$1>;
-declare function loadSkills(workspace?: WorkspacePaths, paths?: string[]): Promise<Skill$1[]>;
-
 type ModelConfigFromFile = {
     id: string;
     name?: string;
@@ -1776,18 +1693,6 @@ declare class AgentEventStream extends EventStream<AgentEvent, AgentMessage[]> {
     constructor();
 }
 
-/**
- * Load all phases from .rowan/phases directory.
- *
- * Scans for subdirectories containing PHASE.md files.
- * Returns PhaseRegistry with entryPhaseId:
- * - null by default (caller must explicitly set to start from a specific phase)
- * - Set to a specific phase id to start from that phase
- *
- * When entryPhaseId is null, AgentLoop starts from "none" phase.
- */
-declare function loadPhases(workspace?: WorkspacePaths, paths?: string[]): Promise<PhaseRegistry>;
-
 interface SystemPromptOptions {
     /** Base system prompt. */
     systemPrompt: string;
@@ -1841,4 +1746,4 @@ declare function buildModelRequest(input: ModelRequestInput, options?: {
     model?: LlmModelRef;
 }): LlmRequest;
 
-export { type AbortEvent, type AfterPhaseEvent, type AfterPhaseHookResult, type AfterPhaseResult, type AfterToolCallEvent, type AfterToolCallResult, Agent, type AgentConfigFile, type AgentContext, type AgentEndEvent, AgentEventStream, type AgentOptions, type AgentStartEvent, type AgentStatus, type BeforePhaseEvent, type BeforePhaseHookResult, type BeforePhaseResult, type BeforePromptEvent, type BeforePromptResult, type BeforeToolCallEvent, type BeforeToolCallResult, type EventBus, EventStream, type ExecOptions, type ExecResult, type ExecutionTurn, type Extension, type ExtensionAPI, type ExtensionContext, type ExtensionError, type ExtensionErrorListener, type ExtensionFactory, type ExtensionManifest, type ExtensionPackageManifest, ExtensionRunner, type ExtensionRunnerOptions, type ExtensionRunnerRef, type ExtensionRuntime, type ExtensionUtils, HookError, type HookEvent, type HookEventType, type HookHandler, type HookResultMap, HooksManager, type LoadExtensionsResult, type LoadedExtension, LocalJsonlSessionManager, type LoopMetrics, type MessageEndEvent, type MessageStartEvent, type MessageUpdateEvent, type ModelConfigFromFile, type ModelTranscript, type Phase, type PhaseContext, type PhaseDefinition, type PhaseExecution, type PhaseOutput, type PhaseRegistration, type PhaseRegistry, type PhaseRun, type PhaseState, type ProviderConfigFromFile, type QueueUpdateEvent, type RegisteredPhase, type RegisteredTool, type RunOptions, type RunResult, type SavePointEvent, type Session, type SessionListItem, type SettledEvent, type SourceInfo, type Tool, type ToolDefinition, type ToolExecutionEndEvent, type ToolExecutionResult, type ToolExecutionStartEvent, type ToolExecutionUpdateEvent, type TurnEndEvent, type TurnStartEvent, type WorkspacePaths, appendUserTurn, buildModelRequest, buildSystemPrompt, conversationMessages, createCoreTools, createEventBus, createExtension, createExtensionAPI, createExtensionRunner, createExtensionRuntime, createId, createMessage, createSession, createSourceInfo, createTimestamp, discoverAndLoadExtensions, getGlobalHooks, interpolateEnvVars, latestUserInput, loadConfigFile, loadExtensionFromFactory, loadExtensions, loadPhases, loadSkill, loadSkills, messageContentText, parseModelRef, registerConfigModels, resetGlobalHooks, resolveDefaultModel, resolveInWorkspace, resolveSkillPath, resolveWorkspacePaths, serializeSkills };
+export { type AbortEvent, type AfterPhaseEvent, type AfterPhaseHookResult, type AfterPhaseResult, type AfterToolCallEvent, type AfterToolCallResult, Agent, type AgentConfigFile, type AgentContext, type AgentEndEvent, AgentEventStream, type AgentOptions, type AgentStartEvent, type AgentStatus, type BeforePhaseEvent, type BeforePhaseHookResult, type BeforePhaseResult, type BeforePromptEvent, type BeforePromptResult, type BeforeToolCallEvent, type BeforeToolCallResult, type EventBus, EventStream, type ExecOptions, type ExecResult, type ExecutionTurn, type Extension, type ExtensionAPI, type ExtensionContext, type ExtensionError, type ExtensionErrorListener, type ExtensionFactory, type ExtensionManifest, type ExtensionPackageManifest, ExtensionRunner, type ExtensionRunnerOptions, type ExtensionRuntime, type ExtensionUtils, HookError, type HookEvent, type HookEventType, type HookHandler, type HookResultMap, HooksManager, type LoadExtensionsResult, type LoadedExtension, LocalJsonlSessionManager, type LoopMetrics, type MessageEndEvent, type MessageStartEvent, type MessageUpdateEvent, type ModelConfigFromFile, type ModelTranscript, type Phase, type PhaseContext, type PhaseDefinition, type PhaseExecution, type PhaseOutput, type PhaseRegistration, type PhaseRegistry, type PhaseRun, type PhaseState, type ProviderConfigFromFile, type QueueUpdateEvent, type RegisteredPhase, type RegisteredTool, type RunOptions, type RunResult, type SavePointEvent, type Session, type SessionListItem, type SettledEvent, type SourceInfo, type Tool, type ToolDefinition, type ToolExecutionEndEvent, type ToolExecutionResult, type ToolExecutionStartEvent, type ToolExecutionUpdateEvent, type TurnEndEvent, type TurnStartEvent, type WorkspacePaths, appendUserTurn, buildModelRequest, buildSystemPrompt, conversationMessages, createCoreTools, createEventBus, createExtension, createExtensionAPI, createExtensionRunner, createExtensionRuntime, createId, createMessage, createSession, createSourceInfo, createTimestamp, getGlobalHooks, interpolateEnvVars, latestUserInput, loadConfigFile, messageContentText, parseModelRef, registerConfigModels, resetGlobalHooks, resolveDefaultModel, resolveInWorkspace, resolveWorkspacePaths, serializeSkills };