@rowan-agent/agent 0.9.4 → 0.9.5

package/dist/index.d.ts

@@ -455,11 +455,11 @@ type ExtensionDisposer = () => void | Promise<void>;
 type ExtensionFactoryResult = void | ExtensionDisposer;
 type ExtensionFactory = (api: ExtensionAPI) => ExtensionFactoryResult | Promise<ExtensionFactoryResult>;
 
-/** Unified phase output — model decides routing via route. */
+/** Unified phase output — model-driven routing is optional; programmatic phases may normalize omission to stop. */
 type PhaseOutput = {
     message: string;
-    /** Route to next phase, or "continue" to re-execute current phase, or "stop" to end */
-    route: string;
+    /** Route to next phase, or "continue" to re-execute current phase, or "stop" to end. Undefined means no model route. */
+    route?: string;
     /** Phase name that produced this output */
     phase?: string;
     /** Tool calls from the model invocation (used by framework for route extraction) */

package/dist/index.js

@@ -91,12 +91,12 @@ function buildPhaseDirectiveMessage(phase, output) {
   const parts = [];
   parts.push(`<phase_content name="${escapeXml(phase.name)}">`);
   parts.push(phase.content);
-  if (output.results && output.results.length > 0) {
+  if (output.results && output.results.length > 0 || output.instruction) {
     parts.push(`  <prev_phase_outputs>`);
     if (output.instruction) {
       parts.push(`    <instruction>${escapeXml(output.instruction)}</instruction>`);
     }
-    for (const r of output.results) {
+    for (const r of output.results ?? []) {
       parts.push(`    <phase name="${escapeXml(r.name)}">`);
       if (r.output !== void 0) {
         parts.push(jsonToXml(r.output, 3));
@@ -172,18 +172,24 @@ function buildPhaseEntry(p) {
 function buildRouteDescription(availablePhases) {
   const phasesBlock = buildStructuredSection("phase", [
     ...availablePhases.map(buildPhaseEntry),
-    { name: "stop", description: "Terminate the workflow and return final result to the user" }
+    {
+      name: "stop",
+      description: "Explicitly finish the current user request or task when no further user input is needed"
+    }
   ]);
   return [
-    "Route execution to one or more phases concurrently, or stop execution.",
+    "Route is optional. Omit it when the current reply should wait for more user input and remain in the current phase.",
     "",
     "Rules:",
-    "- `decision` lists phase executions; use phase 'stop' to terminate.",
+    "- Call route only to continue execution immediately in one or more phases, or to explicitly stop.",
+    "- `decision` lists phase executions; a single target equal to the current phase starts another iteration of that phase.",
+    "- `stop` means the current user request or task is complete and no further user input is needed; `stop` must be the only target.",
     "- Each target may include `phase`, `reason`, `payload`.",
     "- A phase may appear multiple times as independent execution instances.",
     "- `payload` MUST match the phase's `payload_schema`",
     "- `instruction` is optional shared guidance for all phases.",
     "- Executions are independent and concurrent; order is irrelevant.",
+    "- Do not call route in the same response as an ordinary tool; finish ordinary tools first.",
     "",
     "<available_phases>",
     phasesBlock,
@@ -202,12 +208,13 @@ function createRouteTool(availablePhases) {
   return {
     name: PhaseRouteTool,
     description: buildRouteDescription(availablePhases),
-    promptSnippet: "Route to next phase on completion.",
+    promptSnippet: "Route is optional: omit it to remain in the current phase and wait for user input; use it for immediate phase execution or an explicit stop.",
     promptGuidelines: [
-      "Call route immediately when the phase is complete."
+      "Do not call route together with ordinary tools.",
+      "Use route(stop) only when the current user request or task is complete and no further user input is needed."
     ],
     parameters: Type.Object({
-      decision: Type.Array(DecisionTarget, { description: "Phase executions to start" }),
+      decision: Type.Array(DecisionTarget, { description: "Phase executions to start", minItems: 1 }),
       instruction: Type.Optional(Type.String({ description: "Overall instruction, passed as context" }))
     }),
     // No-op: this tool is intercepted by phases, never executed via tool execution
@@ -220,29 +227,35 @@ function createRouteTool(availablePhases) {
   };
 }
 function extractRouteCall(toolCalls) {
-  const routeCall = toolCalls.find((t) => t.name === PhaseRouteTool);
-  if (!routeCall) return void 0;
+  const routeCalls = toolCalls.filter((t) => t.name === PhaseRouteTool);
+  if (routeCalls.length !== 1) return void 0;
+  const routeCall = routeCalls[0];
   let args;
   if (typeof routeCall.args === "string") {
     try {
-      args = JSON.parse(routeCall.args);
+      const parsed = JSON.parse(routeCall.args);
+      args = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
     } catch {
-      return void 0;
+      return { decision: [{ phase: "" }] };
     }
   } else {
-    args = routeCall.args;
+    args = routeCall.args !== null && typeof routeCall.args === "object" ? routeCall.args : {};
   }
   const decisionRaw = args.decision;
   let decision = [];
   if (Array.isArray(decisionRaw)) {
     decision = decisionRaw.map((d) => {
-      const obj = d;
+      const obj = d !== null && typeof d === "object" ? d : {};
       return {
-        phase: typeof obj?.phase === "string" ? obj.phase : "stop",
+        // Empty phase is an invalid target sentinel. Never coerce malformed
+        // input to stop: only an explicit, valid stop target may terminate.
+        phase: typeof obj.phase === "string" ? obj.phase : "",
         reason: typeof obj?.reason === "string" ? obj.reason : void 0,
         payload: obj?.payload
       };
     });
+  } else if (decisionRaw !== void 0) {
+    decision = [{ phase: "" }];
   }
   return {
     decision,
@@ -765,6 +778,15 @@ function contentBlocksToMessageContent(blocks) {
   });
 }
 
+// src/loop/types.ts
+var DEFAULT_MAX_ATTEMPTS = 16;
+function validateMaxAttempts(value) {
+  if (value !== void 0 && (!Number.isInteger(value) || value <= 0)) {
+    throw new TypeError("maxAttempts must be a positive integer.");
+  }
+  return value;
+}
+
 // src/loop/errors.ts
 var EmptyResponseError = class extends Error {
   code = "empty_response";
@@ -882,7 +904,7 @@ async function collectStreamResult(input) {
       doneResponse = event.response;
       stopReason = event.response?.stopReason;
       const contentBlocks2 = lastPartial?.contentBlocks ?? [];
-      const hasContent2 = contentBlocks2.length > 0 || (event.response?.content?.length ?? 0) > 0;
+      const hasContent2 = contentBlocks2.length > 0 || (event.response?.content?.length ?? 0) > 0 || (event.response?.toolCalls?.length ?? 0) > 0;
       const shouldStoreContentParts = contentBlocks2.some((block) => block.type !== "text");
       if (activeMessageId && hasContent2 && shouldStoreContentParts) {
         input.message.replaceContent(activeMessageId, contentBlocksToMessageContent(contentBlocks2));
@@ -905,7 +927,7 @@ async function collectStreamResult(input) {
   if (activeMessageId) {
     await input.message.end(activeMessageId);
   }
-  const hasContent = (lastPartial?.contentBlocks?.length ?? 0) > 0 || (doneResponse?.content?.length ?? 0) > 0;
+  const hasContent = (lastPartial?.contentBlocks?.length ?? 0) > 0 || (doneResponse?.content?.length ?? 0) > 0 || (doneResponse?.toolCalls?.length ?? 0) > 0;
   if (!hasContent && stopReason !== "error" && stopReason !== "aborted") {
     throw new EmptyResponseError();
   }
@@ -1497,7 +1519,7 @@ function createDefaultPhase() {
     filePath: "",
     baseDir: "",
     skills: [],
-    content: "Execute tasks using current context.\nNo planning. No evaluation.\nRoute to next phase or stop when done."
+    content: "Execute tasks using current context.\nNo planning. No evaluation.\nOmit route when more user input is needed. Use route for immediate phase execution, or route(stop) only when the current user request or task is complete and no further user input is needed."
   };
 }
 
@@ -1821,6 +1843,31 @@ function applyFirstDecision(route, output) {
   if (first.reason) output.routeReason = first.reason;
   if (first.payload !== void 0) output.payload = normalizePayload(first.payload);
 }
+function resolveRouteDecision(route, registry) {
+  if (!route || route.decision.length === 0) return void 0;
+  const requestedCount = route.decision.length;
+  const hasStop = route.decision.some(({ phase }) => phase === "stop");
+  if (hasStop) {
+    if (requestedCount !== 1) return void 0;
+    return { ...route, requestedCount };
+  }
+  const decision = route.decision.filter(({ phase }) => registry.phases.has(phase));
+  if (decision.length === 0) return void 0;
+  return { ...route, decision, requestedCount };
+}
+function resolveModelRouteDecision(toolCalls, registry) {
+  return resolveRouteDecision(toolCalls ? extractRouteCall(toolCalls) : void 0, registry);
+}
+function resolveHookRouteDecision(output, registry) {
+  if (output.route === void 0 || output.route === "continue") return void 0;
+  return resolveRouteDecision({
+    decision: [{
+      phase: output.route,
+      ...output.routeReason ? { reason: output.routeReason } : {},
+      ...output.payload === void 0 ? {} : { payload: output.payload }
+    }]
+  }, registry);
+}
 function injectPhaseContent(phase, output, messages, mirror) {
   try {
     const phaseContent = phase.filePath ? readPhaseContent(phase) : phase.content ?? phase.description ?? "";
@@ -1952,12 +1999,13 @@ function createToolResultContent(result) {
     }
   ];
 }
-function createRouteToolResultContent(toolCall) {
+function createRouteToolResultContent(toolCall, error) {
   return [
     {
       type: "tool_result",
       toolUseId: toolCall.id,
-      content: '{"ok": true}'
+      content: error ? JSON.stringify({ ok: false, error }) : '{"ok": true}',
+      ...error ? { isError: true } : {}
     }
   ];
 }
@@ -1967,7 +2015,6 @@ async function executePhaseWithModel(ctx) {
   );
   let output = {
     message: "",
-    route: "stop",
     phase: ctx.phase.name,
     toolCalls: []
   };
@@ -1979,15 +2026,24 @@ async function executePhaseWithModel(ctx) {
     const collected = await ctx.execution.invokeModel(roundContext);
     output = {
       message: collected.text,
-      route: "stop",
       phase: ctx.phase.name,
-      toolCalls: collected.toolCalls
+      // A route decision sharing a model response with an ordinary Tool is
+      // rejected for this round. Keep ordinary calls visible so they can run,
+      // but do not let the route escape the error/re-decision boundary.
+      toolCalls: collected.toolCalls.some((candidate) => candidate.name === PhaseRouteTool) && collected.toolCalls.some((candidate) => candidate.name !== PhaseRouteTool) ? collected.toolCalls.filter((candidate) => candidate.name !== PhaseRouteTool) : collected.toolCalls
     };
     for (const toolCall of collected.toolCalls) {
       if (toolCall.name !== PhaseRouteTool) continue;
-      const messageId = ctx.messageManager.start("tool", createRouteToolResultContent(toolCall), {
-        phase: ctx.phase.name
-      });
+      const messageId = ctx.messageManager.start(
+        "tool",
+        createRouteToolResultContent(
+          toolCall,
+          collected.toolCalls.some((candidate) => candidate.name !== PhaseRouteTool) ? "Route must be called separately after ordinary tools finish; this route decision was ignored." : void 0
+        ),
+        {
+          phase: ctx.phase.name
+        }
+      );
       await ctx.messageManager.end(messageId);
     }
     const executableToolCalls = collected.toolCalls.filter(
@@ -2019,6 +2075,7 @@ async function startPhaseLoop(config, state) {
   return runPhaseLoop(config, state, registry);
 }
 async function runPhaseLoop(config, state, registry) {
+  const maxAttempts = validateMaxAttempts(config.maxAttempts) ?? DEFAULT_MAX_ATTEMPTS;
   const resumingSuspendedRun = state.status === "suspended" && Boolean(state.currentPhase);
   let currentPhaseId = resumingSuspendedRun ? state.currentPhase : registry.entryPhaseId;
   let isContinuing = resumingSuspendedRun ? state.continuation?.isContinuing ?? true : false;
@@ -2030,6 +2087,53 @@ async function runPhaseLoop(config, state, registry) {
   let previousPhaseInputMsgId;
   let previousResults = resumingSuspendedRun ? state.continuation?.previousResults?.map((result) => ({ ...result })) ?? [] : [];
   let pendingInstruction = resumingSuspendedRun ? state.continuation?.pendingInstruction : void 0;
+  const awaitInput = async (prompt, resumeAsContinuing) => {
+    if (!config.waitForInput) return void 0;
+    const preAbort = LoopGuard.checkAbort(config.signal);
+    if (preAbort.stopReason !== "none") {
+      removePhaseMessage(config.context.messages, previousPhaseMsgId);
+      removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
+      previousPhaseMsgId = void 0;
+      previousPhaseInputMsgId = void 0;
+      return {
+        type: "completed",
+        result: await completeRun(config, state, createOutcome.aborted())
+      };
+    }
+    const requestedAt = createTimestamp();
+    const inputRequest = {
+      phase: currentPhaseId,
+      prompt,
+      requestedAt
+    };
+    state.currentPhase = currentPhaseId;
+    state.status = "suspended";
+    state.attempt = 0;
+    state.continuation = {
+      isContinuing: resumeAsContinuing,
+      previousPayload,
+      previousResults: previousResults.map((result) => ({ ...result })),
+      pendingInstruction,
+      previousPhaseMessageId: previousPhaseMsgId
+    };
+    const userMessages = await config.waitForInput(state, inputRequest);
+    state.status = "running";
+    const abortResult = LoopGuard.checkAbort(config.signal);
+    if (abortResult.stopReason !== "none") {
+      removePhaseMessage(config.context.messages, previousPhaseMsgId);
+      removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
+      previousPhaseMsgId = void 0;
+      previousPhaseInputMsgId = void 0;
+      return {
+        type: "completed",
+        result: await completeRun(config, state, createOutcome.aborted())
+      };
+    }
+    for (const message of userMessages) {
+      config.context.messages.push(message);
+    }
+    return { type: "continued" };
+  };
   while (currentPhaseId) {
     const availablePhases = [];
     for (const [, phase2] of registry.phases) {
@@ -2043,6 +2147,19 @@ async function runPhaseLoop(config, state, registry) {
       previousPhaseInputMsgId = void 0;
       return completeRun(config, state, createOutcome.aborted());
     }
+    if (state.attempt >= maxAttempts) {
+      const input = await awaitInput(
+        `The autonomous Phase execution limit (${maxAttempts}) was reached. Provide input to continue.`,
+        false
+      );
+      if (input?.type === "completed") return input.result;
+      if (input?.type === "continued") {
+        isContinuing = false;
+        continue;
+      }
+      throw new Error("Phase execution reached maxAttempts but waitForInput is unavailable.");
+    }
+    state.attempt++;
     state.metrics.iterations++;
     if (needsCompaction(config.context.messages)) {
       const compacted = compactMessages(config.context.messages);
@@ -2143,13 +2260,9 @@ async function runPhaseLoop(config, state, registry) {
     }
     const runtime = { phase, config, state, execution, messageManager, registry, context: phaseContext };
     let output = await executePhase(runtime);
-    let routeDecision;
-    if (output.toolCalls && output.toolCalls.length > 0) {
-      routeDecision = extractRouteCall(output.toolCalls);
-      if (routeDecision) {
-        applyFirstDecision(routeDecision, output);
-      }
-    }
+    let modelRouteDecision = resolveModelRouteDecision(output.toolCalls, registry);
+    let routeDecision = modelRouteDecision;
+    if (routeDecision) applyFirstDecision(routeDecision, output);
     if (config.afterPhase) {
       const extAfter = await config.afterPhase(currentPhaseId, output);
       if (extAfter.abort) {
@@ -2161,52 +2274,30 @@ async function runPhaseLoop(config, state, registry) {
       }
       if (extAfter.retry && (phase.run || phase.factory)) {
         output = await executePhase(runtime);
-        routeDecision = output.toolCalls ? extractRouteCall(output.toolCalls) : void 0;
+        modelRouteDecision = resolveModelRouteDecision(output.toolCalls, registry);
+        routeDecision = modelRouteDecision;
         if (routeDecision) applyFirstDecision(routeDecision, output);
       }
       if (extAfter.output) {
+        const hookHasRoute = extAfter.output.route !== void 0;
         output = extAfter.output;
+        if (hookHasRoute) {
+          routeDecision = resolveHookRouteDecision(output, registry);
+        } else if (phase.run || phase.factory) {
+          output = { ...output, route: "stop" };
+          routeDecision = void 0;
+        } else {
+          routeDecision = modelRouteDecision;
+          if (routeDecision) applyFirstDecision(routeDecision, output);
+        }
       }
     }
-    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) {
-      if (config.waitForInput) {
-        const preAbort = LoopGuard.checkAbort(config.signal);
-        if (preAbort.stopReason !== "none") {
-          removePhaseMessage(config.context.messages, previousPhaseMsgId);
-          removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
-          previousPhaseMsgId = void 0;
-          previousPhaseInputMsgId = void 0;
-          return completeRun(config, state, createOutcome.aborted());
-        }
-        const requestedAt = createTimestamp();
-        const inputRequest = {
-          phase: currentPhaseId,
-          prompt: output.message,
-          requestedAt
-        };
-        state.status = "suspended";
-        state.continuation = {
-          isContinuing,
-          previousPayload,
-          previousResults: previousResults.map((result) => ({ ...result })),
-          pendingInstruction,
-          previousPhaseMessageId: previousPhaseMsgId
-        };
-        const userMessages = await config.waitForInput(state, inputRequest);
-        state.status = "running";
-        const abortResult2 = LoopGuard.checkAbort(config.signal);
-        if (abortResult2.stopReason !== "none") {
-          removePhaseMessage(config.context.messages, previousPhaseMsgId);
-          removePhaseMessage(config.context.messages, previousPhaseInputMsgId);
-          previousPhaseMsgId = void 0;
-          previousPhaseInputMsgId = void 0;
-          return completeRun(config, state, createOutcome.aborted());
-        }
-        for (const message of userMessages) {
-          config.context.messages.push(message);
-        }
+    if (phase.run || phase.factory) {
+      if (output.route === void 0 && !routeDecision) output = { ...output, route: "stop" };
+    } else if (!phase.target && output.route === void 0 && !routeDecision) {
+      const input = await awaitInput(output.message, true);
+      if (input?.type === "completed") return input.result;
+      if (input?.type === "continued") {
         isContinuing = true;
         continue;
       }
@@ -2220,7 +2311,7 @@ async function runPhaseLoop(config, state, registry) {
       isContinuing = true;
       continue;
     }
-    if (routeDecision && routeDecision.decision.length > 1) {
+    if (routeDecision && routeDecision.requestedCount > 1) {
       const contextSnapshot = snapshotMessages(config.context.messages);
       const parallelTasks = /* @__PURE__ */ new Map();
       const instanceIds = buildInstanceIds(routeDecision.decision.map((t) => t.phase));
@@ -2239,6 +2330,7 @@ async function runPhaseLoop(config, state, registry) {
           registry,
           pt,
           payload,
+          routeDecision.instruction,
           context,
           availablePhases,
           instanceId,
@@ -2251,7 +2343,7 @@ async function runPhaseLoop(config, state, registry) {
       }
       const successfulResults = await waitForBackgroundTasks(parallelTasks);
       previousResults = successfulResults.map((r) => ({ name: r.instanceId, output: r.payload }));
-      pendingInstruction = routeDecision.instruction;
+      pendingInstruction = void 0;
       const entryPhaseId = phase.target ?? registry.entryPhaseId;
       if (entryPhaseId === "stop") {
         removePhaseMessage(config.context.messages, previousPhaseMsgId);
@@ -2294,6 +2386,7 @@ async function runPhaseLoop(config, state, registry) {
     });
     previousPayload = output.payload;
     previousResults = output.payload !== void 0 ? [{ name: phase.name, output: output.payload }] : [];
+    pendingInstruction = phase.target ? void 0 : routeDecision?.instruction;
     currentPhaseId = targetPhaseId;
   }
   throw new Error("Phase machine exited without a stop or abort transition.");
@@ -2548,10 +2641,10 @@ function createPhaseExecution(config, state, phase, messageManager, toolExecutio
     }
   };
 }
-async function executeParallelPhase(config, state, registry, phase, payload, context, availablePhases, instanceId, groupId, index, count, sourcePhaseId) {
+async function executeParallelPhase(config, state, registry, phase, payload, instruction, context, availablePhases, instanceId, groupId, index, count, sourcePhaseId) {
   const messages = [...context];
   const allTools = buildToolsWithRouting(config, availablePhases);
-  const phaseTools = selectPhaseTools(allTools, phase.tools);
+  const phaseTools = selectPhaseTools(allTools, phase.tools, false);
   const phaseSkills = mergeSkills(config.context.skills, phase.skills);
   const systemPrompt = config.context.systemPrompt;
   const phaseContext = {
@@ -2578,7 +2671,10 @@ async function executeParallelPhase(config, state, registry, phase, payload, con
   const messageManager = createMessageManager({ messages }, config.onMessage, config.onMessageDelta);
   const phaseMsgId = injectPhaseContent(
     phase,
-    { results: payload !== void 0 ? [{ name: sourcePhaseId, output: payload }] : [] },
+    {
+      instruction,
+      results: payload !== void 0 ? [{ name: sourcePhaseId, output: payload }] : []
+    },
     messages
   );
   const toolExecutionManager = createToolExecutionManager();
@@ -2590,8 +2686,8 @@ async function executeParallelPhase(config, state, registry, phase, payload, con
   const resultPayload = decision?.decision[0]?.payload !== void 0 ? normalizePayload(decision.decision[0].payload) : output.payload;
   return { instanceId, phaseId: phase.name, payload: resultPayload, content: output.message };
 }
-function selectPhaseTools(candidates, names) {
-  const routing = candidates.filter(({ name }) => name === PhaseRouteTool);
+function selectPhaseTools(candidates, names, includeRouting = true) {
+  const routing = includeRouting ? candidates.filter(({ name }) => name === PhaseRouteTool) : [];
   const ordinary = candidates.filter(({ name }) => name !== PhaseRouteTool);
   return [...selectNamedResources(ordinary, names, "Tool"), ...routing];
 }
@@ -3040,6 +3136,7 @@ function validateConfigResolution(agentId, value) {
   throw new Error(`Config Provider returned an invalid resolution for Agent ${agentId}.`);
 }
 function snapshotConfig(config) {
+  validateMaxAttempts(config.maxAttempts);
   if (isAgentConfiguration(config)) return snapshotConfiguration(config);
   const definition = Object.freeze({
     ...config.definition,
@@ -5000,6 +5097,7 @@ function adaptExtensionTool2(input) {
 
 // src/runtime/configuration-snapshot.ts
 function resolveConfigurationSnapshot(registry, input) {
+  validateMaxAttempts(input.maxAttempts);
   const resolved = registry.resolveView(input.resourceView);
   const base = resolved.agents.find(({ name }) => name === input.definition.name);
   if (!base) {
@@ -5785,6 +5883,11 @@ function normalizePhaseRegistry(registry) {
   if (registry?.phases.has(DEFAULT_PHASE_ID) && registry.phases.get(DEFAULT_PHASE_ID)?.filePath !== "") {
     throw new TypeError(`Configured Phase collides with Rowan built-in Phase "${DEFAULT_PHASE_ID}".`);
   }
+  for (const [name] of registry?.phases ?? []) {
+    if (name === "stop" || name === "continue") {
+      throw new TypeError(`Configured Phase name "${name}" is reserved by Rowan routing controls.`);
+    }
+  }
   return {
     phases: new Map([
       [DEFAULT_PHASE_ID, createDefaultPhase()],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rowan-agent/agent",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "license": "MIT",
   "repository": {
     "type": "git",