@rowan-agent/agent 0.5.3 → 0.5.5

package/README.md

@@ -50,6 +50,7 @@ class Agent {
   appendMessages(messages: AgentMessage[]): void;
   runWithUserInput(input: string, options?: RunOptions): Promise<RunResult>;
   runWithMessage(message: AgentMessage, options?: RunOptions): Promise<RunResult>;
+  resetInitialization(): void;
 
   // Context and transcript
   getContext(): AgentContext;
@@ -140,6 +141,8 @@ const second = await agent.run();
 await agent.runWithMessage(createMessage("user", "what changed since last turn?"));
 ```
 
+The agent uses `context.phases.entryPhaseId` only until the first successful run completes. Later turns start from the normalized `default` phase so long-lived agents do not repeat one-time entry work. Call `agent.resetInitialization()` when the next run should use `entryPhaseId` again.
+
 Transcript helpers return snapshots, so callers can inspect or edit history without accidentally mutating the agent until they call a setter.
 
 ```ts
@@ -202,6 +205,7 @@ The terminal result produced when the loop completes — carries the final messa
 type Outcome = {
   id: string;
   message: string;
+  payload?: unknown;
   toolResults?: Array<{
     toolCallId: string;
     toolName: string;
@@ -341,7 +345,7 @@ Per iteration:
   5. Transition, continue, or stop
 ```
 
-**`entryPhaseId`** specifies which phase the loop enters first. When phases are loaded from `.rowan/phases/`, the first discovered phase becomes the entry. When none are configured, the Agent normalises to `"default"`. This field is an internal routing hint for the phase loop — it is **not** exposed to the LLM, since the agent does not need to know which phase is the entry point to make routing decisions.
+**`entryPhaseId`** specifies which phase the loop enters for an uninitialized Agent. When phases are loaded from `.rowan/phases/`, the first discovered phase becomes the entry. When none are configured, the Agent normalises to `"default"`. After a successful run, later turns start from `"default"` until `agent.resetInitialization()` is called. This field is an internal routing hint for the phase loop — it is **not** exposed to the LLM, since the agent does not need to know which phase is the entry point to make routing decisions.
 
 ### Example Phase Flow
 
@@ -775,4 +779,4 @@ type LoopMetrics = {
 
 ## Version
 
-Current version: **0.4.11**
+Current version: **0.5.5**

package/dist/index.d.ts

@@ -1357,7 +1357,8 @@ type AgentStatus = {
     context: AgentContext;
     model: LlmModelRef;
     tools: Tool[];
-    isRunning: boolean;
+    initialized: boolean;
+    running: boolean;
     currentResult?: RunResult;
     error?: string;
 };
@@ -1381,6 +1382,7 @@ declare class Agent {
     appendMessages(messages: AgentMessage[]): void;
     runWithUserInput(input: string, options?: RunOptions): Promise<RunResult>;
     runWithMessage(message: AgentMessage, options?: RunOptions): Promise<RunResult>;
+    resetInitialization(): void;
     getContext(): AgentContext;
     setContext(context: AgentContext): void;
     updateContext(updater: (context: AgentContext) => AgentContext): void;
@@ -1745,13 +1747,6 @@ declare class EmptyResponseError extends Error {
     readonly code = "empty_response";
     constructor(message?: string);
 }
-/** Error thrown when a routed phase needs a route tool call but the model did not emit one. */
-declare class MissingRouteToolCallError extends Error {
-    readonly code = "missing_route_tool_call";
-    readonly phase: string;
-    readonly toolCallNames: string[];
-    constructor(phase: string, toolCallNames: string[]);
-}
 
 interface SystemPromptOptions {
     /** Base system prompt. */
@@ -1806,4 +1801,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, EmptyResponseError, 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, MissingRouteToolCallError, 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, loadPhase, loadPhases, messageContentText, parseModelRef, registerConfigModels, reloadPhases, resetGlobalHooks, resolveDefaultModel, resolveInWorkspace, 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, EmptyResponseError, 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, loadPhase, loadPhases, messageContentText, parseModelRef, registerConfigModels, reloadPhases, resetGlobalHooks, resolveDefaultModel, resolveInWorkspace, resolveWorkspacePaths, serializeSkills };

package/dist/index.js

@@ -21,19 +21,6 @@ var EmptyResponseError = class extends Error {
     this.name = "EmptyResponseError";
   }
 };
-var MissingRouteToolCallError = class extends Error {
-  code = "missing_route_tool_call";
-  phase;
-  toolCallNames;
-  constructor(phase, toolCallNames) {
-    super(
-      `Phase "${phase}" requires a route tool call, but the model did not emit one.`
-    );
-    this.name = "MissingRouteToolCallError";
-    this.phase = phase;
-    this.toolCallNames = toolCallNames;
-  }
-};
 var LoopGuard = {
   /** Returns abort result if signal is aborted */
   checkAbort(signal) {
@@ -85,7 +72,11 @@ function extractToolResults(transcript) {
 }
 var createOutcome = {
   phaseNotFound(output) {
-    return { id: createId("out"), message: `Phase "${output.phase ?? "Unknown"}" not found.` };
+    return {
+      id: createId("out"),
+      message: `Phase "${output.phase ?? "Unknown"}" not found.`,
+      display: true
+    };
   },
   default(output, transcript) {
     const toolResults = transcript ? extractToolResults(transcript) : [];
@@ -102,11 +93,17 @@ var createOutcome = {
     }
     return outcome;
   },
+  phase(output, transcript) {
+    return {
+      ...this.default(output, transcript),
+      display: true
+    };
+  },
   aborted() {
     return { id: createId("out"), message: "Agent run aborted." };
   },
   error(message) {
-    return { id: createId("out"), message };
+    return { id: createId("out"), message, display: true };
   }
 };
 
@@ -196,9 +193,13 @@ async function collectStreamResult(input) {
   let stopReason;
   let doneResponse;
   for await (const event of input.events) {
-    const abortResult = LoopGuard.checkAbort(input.config.signal);
-    if (abortResult.stopReason !== "none") {
-      return { text: abortResult.message, contentBlocks: [], toolCalls: [], stopReason: "aborted" };
+    const abortResult2 = LoopGuard.checkAbort(input.config.signal);
+    if (abortResult2.stopReason !== "none") {
+      if (activeMessageId) {
+        await input.message.end(activeMessageId);
+        activeMessageId = void 0;
+      }
+      return { text: abortResult2.message, contentBlocks: [], toolCalls: [], stopReason: "aborted" };
     }
     if (event.type === "model_requested") {
       input.config.emit?.({
@@ -249,6 +250,14 @@ async function collectStreamResult(input) {
       }
     }
   }
+  const abortResult = LoopGuard.checkAbort(input.config.signal);
+  if (abortResult.stopReason !== "none") {
+    if (activeMessageId) {
+      await input.message.end(activeMessageId);
+      activeMessageId = void 0;
+    }
+    return { text: abortResult.message, contentBlocks: [], toolCalls: [], stopReason: "aborted" };
+  }
   if (activeMessageId) {
     await input.message.end(activeMessageId);
   }
@@ -1753,11 +1762,19 @@ function createRunResult(config, state, outcome) {
   };
 }
 async function completeRun(config, state, outcome) {
+  if (outcome.display) {
+    const messages = createMessageManager(config.context, config.emit, config.onMessage);
+    const messageId = messages.start("assistant", outcome.message, { outcomeId: outcome.id });
+    await messages.end(messageId);
+  }
   state.metrics.endedAt = createTimestamp();
   state.metrics.durationMs = Date.now() - state.metrics.startedAtMs;
   await config.onOutcome?.(outcome);
   return createRunResult(config, state, outcome);
 }
+function createTerminalOutcome(phase, output, transcript) {
+  return phase.run || phase.factory ? createOutcome.phase(output, transcript) : createOutcome.default(output, transcript);
+}
 function buildToolsWithRouting(config, availablePhases) {
   const tools = [...config.context.tools];
   if (availablePhases.length > 0) {
@@ -1991,10 +2008,34 @@ async function runPhaseLoop(config, state, registry) {
     const routeToolAvailable = phaseContext.tools.some((tool) => tool.name === PhaseRouteTool);
     const routeRequired = !phase.target && !phase.run && !phase.factory && routeToolAvailable && registry.phases.size > 1;
     if (routeRequired && !routeDecision) {
-      throw new MissingRouteToolCallError(
-        currentPhaseId,
-        output.toolCalls?.map((toolCall) => toolCall.name) ?? []
-      );
+      if (config.waitForInput) {
+        const preAbort = LoopGuard.checkAbort(config.signal);
+        if (preAbort.stopReason !== "none") {
+          config.emit?.({ type: "phase_end", phase: currentPhaseId, ts: createTimestamp() });
+          removePhaseMessage(config.context.messages, previousPhaseMsgId);
+          previousPhaseMsgId = void 0;
+          return completeRun(config, state, createOutcome.aborted());
+        }
+        config.emit?.({ type: "user_prompt_requested", phase: currentPhaseId, ts: createTimestamp() });
+        const userMessages = await config.waitForInput();
+        const abortResult2 = LoopGuard.checkAbort(config.signal);
+        if (abortResult2.stopReason !== "none") {
+          config.emit?.({ type: "phase_end", phase: currentPhaseId, ts: createTimestamp() });
+          removePhaseMessage(config.context.messages, previousPhaseMsgId);
+          previousPhaseMsgId = void 0;
+          return completeRun(config, state, createOutcome.aborted());
+        }
+        for (const message of userMessages) {
+          config.context.messages.push(message);
+        }
+        removePhaseMessage(config.context.messages, previousPhaseMsgId);
+        previousPhaseMsgId = void 0;
+        isContinuing = true;
+        continue;
+      }
+      config.emit?.({ type: "phase_end", phase: currentPhaseId, ts: createTimestamp() });
+      removePhaseMessage(config.context.messages, previousPhaseMsgId);
+      return completeRun(config, state, createOutcome.default(output, config.context.messages));
     }
     if (output.route === "continue") {
       isContinuing = true;
@@ -2020,7 +2061,7 @@ async function runPhaseLoop(config, state, registry) {
       pendingInstruction = routeDecision.instruction;
       const entryPhaseId = phase.target ?? registry.entryPhaseId;
       if (entryPhaseId === "stop") {
-        return completeRun(config, state, createOutcome.default(output, config.context.messages));
+        return completeRun(config, state, createTerminalOutcome(phase, output, config.context.messages));
       }
       currentPhaseId = entryPhaseId;
       previousPayload = void 0;
@@ -2036,7 +2077,7 @@ async function runPhaseLoop(config, state, registry) {
     }
     if (nextRoute === "stop") {
       if (routeToolCalled) removePhaseMessage(config.context.messages, previousPhaseMsgId);
-      return completeRun(config, state, createOutcome.default(output, config.context.messages));
+      return completeRun(config, state, createTerminalOutcome(phase, output, config.context.messages));
     }
     const targetPhaseId = nextRoute;
     if (!registry.phases.has(targetPhaseId)) {
@@ -3439,7 +3480,8 @@ var Agent = class {
       context: prepareAgentContext(context),
       model: this.options.model,
       tools: this.options.context.tools ?? [],
-      isRunning: false
+      initialized: false,
+      running: false
     };
   }
   subscribe(listener) {
@@ -3458,13 +3500,32 @@ var Agent = class {
     this.setMessages([...this.options.context.messages, ...snapshotMessages(messages)]);
   }
   runWithUserInput(input, options) {
+    const activeRun = this.activeRun;
+    if (activeRun?.resume) {
+      activeRun.resume([createMessage("user", input)]);
+      return activeRun.promise;
+    }
+    if (activeRun) {
+      return Promise.reject(new Error("Agent is already running."));
+    }
     this.appendUserMessage(input);
     return this.run(options);
   }
   runWithMessage(message, options) {
+    const activeRun = this.activeRun;
+    if (activeRun?.resume) {
+      activeRun.resume([message]);
+      return activeRun.promise;
+    }
+    if (activeRun) {
+      return Promise.reject(new Error("Agent is already running."));
+    }
     this.appendMessage(message);
     return this.run(options);
   }
+  resetInitialization() {
+    this.state.initialized = false;
+  }
   getContext() {
     return prepareAgentContext(this.options.context);
   }
@@ -3679,31 +3740,30 @@ var Agent = class {
     const message = error instanceof Error ? error.message : "Agent run failed.";
     this.state.error = message;
   }
-  async runWithLifecycle(executor) {
+  runWithLifecycle(executor) {
     if (this.activeRun) {
-      throw new Error("Agent is already running.");
+      return Promise.reject(new Error("Agent is already running."));
     }
-    let resolvePromise;
     const abortController = new AbortController();
-    const promise = new Promise((resolve7) => {
-      resolvePromise = resolve7;
+    const waitForInput = () => new Promise((resolve7) => {
+      const activeRun = this.activeRun;
+      activeRun.resume = (messages) => {
+        activeRun.resume = void 0;
+        resolve7(messages);
+      };
     });
-    this.activeRun = { promise, resolve: resolvePromise, abortController };
-    this.state.isRunning = true;
-    try {
-      const result = await executor(abortController.signal);
-      resolvePromise(result);
-      return result;
-    } catch (error) {
+    const promise = Promise.resolve().then(() => executor({ signal: abortController.signal, waitForInput })).catch((error) => {
       this.handleRunFailure(error, abortController.signal.aborted);
-      resolvePromise(void 0);
       throw error;
-    } finally {
+    }).finally(() => {
       this.finishRun();
-    }
+    });
+    this.activeRun = { promise, abortController };
+    this.state.running = true;
+    return promise;
   }
   finishRun() {
-    this.state.isRunning = false;
+    this.state.running = false;
     this.activeRun = void 0;
   }
   async loadExtensions(extensions, cwd) {
@@ -3725,22 +3785,30 @@ var Agent = class {
     this.loadedExtensions = extensions;
     this.loadedExtensionsCwd = cwd;
   }
-  async run(config) {
-    const resolved = this.resolveRunConfig(config);
-    const extensions = resolved.extensions ?? [];
-    await this.loadExtensions(extensions, resolved.cwd);
-    const runContext = prepareAgentContext(resolved.context, this.extensionRunner);
-    const sessionId = resolved.sessionId ?? this.state.sessionId;
-    this.options = resolved;
-    if (sessionId) {
-      this.state.sessionId = sessionId;
-    }
-    this.state.context = runContext;
-    this.state.model = resolved.model;
-    this.state.tools = runContext.tools ?? [];
-    this.state.currentResult = void 0;
-    this.state.error = void 0;
-    return this.runWithLifecycle(async (signal) => {
+  run(config) {
+    return this.runWithLifecycle(async ({ signal, waitForInput }) => {
+      const resolved = this.resolveRunConfig(config);
+      const extensions = resolved.extensions ?? [];
+      await this.loadExtensions(extensions, resolved.cwd);
+      const runContext = prepareAgentContext(resolved.context, this.extensionRunner);
+      const entryPhaseId = this.state.initialized ? DEFAULT_PHASE_ID : runContext.phases?.entryPhaseId ?? DEFAULT_PHASE_ID;
+      const loopContext = {
+        ...runContext,
+        phases: {
+          ...runContext.phases,
+          entryPhaseId
+        }
+      };
+      const sessionId = resolved.sessionId ?? this.state.sessionId;
+      this.options = resolved;
+      if (sessionId) {
+        this.state.sessionId = sessionId;
+      }
+      this.state.context = runContext;
+      this.state.model = resolved.model;
+      this.state.tools = runContext.tools ?? [];
+      this.state.currentResult = void 0;
+      this.state.error = void 0;
       const emit = (event) => {
         this.processEvents(event);
       };
@@ -3763,7 +3831,7 @@ var Agent = class {
         return this.handleAfterToolCall(input.tool, result2);
       };
       const result = await runAgentLoop({
-        context: runContext,
+        context: loopContext,
         sessionId: sessionId ?? createId("ses"),
         model: resolved.model,
         stream: resolved.stream,
@@ -3777,7 +3845,8 @@ var Agent = class {
         emit,
         onMessage: resolved.onMessage,
         onOutcome: resolved.onOutcome,
-        onModelTranscript: resolved.onModelTranscript
+        onModelTranscript: resolved.onModelTranscript,
+        waitForInput
       });
       const nextContext = {
         ...prepareAgentContext(resolved.context),
@@ -3786,6 +3855,7 @@ var Agent = class {
       this.state.sessionId = result.sessionId;
       this.state.context = prepareAgentContext(nextContext, this.extensionRunner);
       this.state.currentResult = result;
+      this.state.initialized = true;
       this.options = {
         ...resolved,
         sessionId: result.sessionId,
@@ -3795,7 +3865,9 @@ var Agent = class {
     });
   }
   abort(reason = "Aborted by caller.") {
-    this.activeRun?.abortController.abort(reason);
+    const activeRun = this.activeRun;
+    activeRun?.resume?.([]);
+    activeRun?.abortController.abort(reason);
   }
   /**
    * Get formatted skill content for LLM consumption.
@@ -4422,7 +4494,6 @@ export {
   ExtensionRunner,
   HooksManager,
   LocalJsonlSessionManager,
-  MissingRouteToolCallError,
   appendUserTurn,
   buildModelRequest,
   buildSystemPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rowan-agent/agent",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,7 +23,7 @@
     "build": "tsup"
   },
   "dependencies": {
-    "@rowan-agent/models": "0.4.11",
+    "@rowan-agent/models": "0.5.5",
     "jiti": "2.7.0",
     "typebox": "^1.0.0",
     "yaml": "^2.7.0"