@rowan-agent/agent 0.9.15 → 0.9.17

package/dist/index.d.ts

@@ -886,6 +886,10 @@ interface ExtensionAPI {
         getNextPhase(): string | undefined;
         /** Get the message set by setMessage */
         getMessage(): string | undefined;
+        /** Phase Settings contributions registered by the Phase extension. */
+        settings: {
+            register(provider: PhaseSettingsProvider): void;
+        };
     };
 }
 /**
@@ -976,6 +980,85 @@ interface PhaseContext {
     /** Text to append after the system prompt */
     appendSystemPrompt?: string;
 }
+/** JSON-safe structural defaults declared by a Phase's `input` mapping. */
+type PhaseInput = Readonly<Record<string, JsonValue>>;
+/** JSON-safe option metadata exposed by a Phase to a host Settings surface. */
+interface PhaseSettingsOption {
+    value: string;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+}
+interface PhaseSettingsBadge {
+    label: string;
+    tone?: "neutral" | "success" | "review" | "danger";
+}
+interface PhaseSettingsItem {
+    id: string;
+    title: string;
+    description?: string;
+    badges?: readonly PhaseSettingsBadge[];
+}
+type PhaseSettingsControl = {
+    type: "boolean";
+    path: string;
+    label: string;
+    description?: string;
+} | {
+    type: "number";
+    path: string;
+    label: string;
+    description?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+    scale?: number;
+} | {
+    type: "select";
+    path: string;
+    label: string;
+    description?: string;
+    options: readonly PhaseSettingsOption[];
+} | {
+    type: "text";
+    path: string;
+    label: string;
+    description?: string;
+    placeholder?: string;
+    format?: "string" | "string-array" | "key-value";
+    multiline?: boolean;
+} | {
+    type: "collection";
+    path: string;
+    label: string;
+    description?: string;
+    items: readonly PhaseSettingsItem[];
+    fields: readonly PhaseSettingsControl[];
+    add?: {
+        label: string;
+        idLabel?: string;
+        fields: readonly PhaseSettingsControl[];
+    };
+    removeLabel?: string;
+};
+interface PhaseSettingsSection {
+    id: string;
+    title: string;
+    description?: string;
+    controls: readonly PhaseSettingsControl[];
+}
+/** Declarative, host-neutral Settings surface contributed by a Phase. */
+interface PhaseSettingsDefinition {
+    description?: string;
+    sections: readonly PhaseSettingsSection[];
+}
+/** Host context is intentionally opaque beyond the effective configuration. */
+interface PhaseSettingsContext {
+    configuration: Readonly<Record<string, unknown>>;
+    metadata?: Readonly<Record<string, unknown>>;
+}
+type PhaseSettingsProvider = (context: PhaseSettingsContext) => PhaseSettingsDefinition | Promise<PhaseSettingsDefinition>;
 /**
  * Loaded Phase object
  */
@@ -992,8 +1075,8 @@ interface Phase {
     skills?: Skill[];
     /** Forced next phase */
     target?: string;
-    /** Expected input fields (key → description) */
-    input?: Record<string, string>;
+    /** Structural JSON-safe input defaults */
+    input?: PhaseInput;
     /** If true, phase gets a fresh context when executed in parallel */
     isolated?: boolean;
     /** Path to PHASE.md file */
@@ -1008,7 +1091,7 @@ interface Phase {
     disableAutoInvocation?: boolean;
     /** Do not expose this Phase to direct user invocation. */
     disableImplicitInvocation?: boolean;
-    /** ExtensionAPI factory function (default export pattern) */
+    /** ExtensionAPI factory function used for registration or programmatic execution. */
     factory?: (api: ExtensionAPI) => Promise<void>;
     /** Direct run function */
     run?: (context: PhaseContext, execution: PhaseExecution) => Promise<PhaseOutput | void>;
@@ -1517,6 +1600,7 @@ type InvocationCatalogEntry = Readonly<{
     kind: "phase" | "skill";
     name: string;
     description: string;
+    input?: Phase["input"];
     core?: boolean;
     disableAutoInvocation: boolean;
     disableImplicitInvocation: boolean;
@@ -2645,6 +2729,12 @@ declare function loadSkills(targetPath: string): Promise<Skill[]>;
  * If a directory is provided, the loader reads its PHASE.md.
  */
 declare function loadPhase(targetPath: string): Promise<Phase>;
+/**
+ * Collect and evaluate the Settings provider registered through the Phase's
+ * ExtensionAPI namespace. Settings discovery never reads a direct module
+ * export; the Phase contributes through `api.phase.settings.register()`.
+ */
+declare function loadPhaseSettings(phase: Phase, context: PhaseSettingsContext): Promise<PhaseSettingsDefinition | undefined>;
 /**
  * Load all phases from the target directory.
  *
@@ -2698,4 +2788,4 @@ declare function parseFrontmatter<T = Record<string, unknown>>(raw: string): Fro
 
 declare function createCoreTools(input?: CoreToolContext): Tool[];
 
-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, COMPACT_PHASE_ID, type ConfigProvider, type ConfigPutResult, type ConfigResolution, type ConfigToken, type ConfigurationSnapshot, type ContextCandidate, type ContextCompactionRecord, type ContextStatus, type CoreToolContext, DEFAULT_PHASE_ID, 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 HistorySeed, type HookEvent, type HookEventType, type HookHandler, InMemoryConfigProvider, InMemoryStore, type InputRequest, type InputRequestId, type InputRequiredCommit, type InvocationCatalogEntry, type InvocationSource, 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 MessageRevised, type MessageRevisionResult, type Metadata, type OpaqueId, type Outcome, type OwnerLease, type OwnerToken, type Page, type Phase, type PhaseContext, type PhaseContribution, type PhaseExecution, type PhaseExecutionIdentity, type PhaseInteraction, PhaseInteractionBoundary, PhaseInteractionCancelledError, type PhaseInteractionDriver, type PhaseInteractionKind, type PhaseInteractionState, type PhaseInteractionStatus, type PhaseInvocation, type PhaseMessageManager, type PhaseOutput, type PhaseRegistry, type PhaseRegistrySelection, type PhaseState, type PhaseStatus, type PhaseStatusState, type ResolvedResourceView, type ResourceDiagnostic, type ResourceKind, type ResourceRef, ResourceRegistry, ResourceRegistryError, type ResourceRegistryErrorCode, type ResourceSourceId, type ResourceView, type RetentionResult, 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, STOP_PHASE_ID, type Skill, SqliteStore, type TextContent, type ThinkingContent, type ThinkingDelta, type Tool, type ToolCallId, type ToolCallSnapshot, type ToolCallState, type ToolContribution, type ToolDefinition, type ToolExecutionResult$1 as ToolExecutionResult, type ToolInvocationContext, type ToolMessage, type ToolMessageContent, type ToolProgress, type ToolResultContent, type ToolStateChanged, type ToolUseContent, type UserContent, type UserInput, type UserMessage, brandConfigToken, createCompactPhase, createCorePhases, createCoreTools, createDefaultPhase, createStopPhase, isRuntimeError, loadExtensionsFromPath as loadExtensions, loadPhase, loadPhases, loadSkill, loadSkills, materializeConfigurationSnapshot, parseAgentDefinition, parseFrontmatter, resolveConfigurationSnapshot };
+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, COMPACT_PHASE_ID, type ConfigProvider, type ConfigPutResult, type ConfigResolution, type ConfigToken, type ConfigurationSnapshot, type ContextCandidate, type ContextCompactionRecord, type ContextStatus, type CoreToolContext, DEFAULT_PHASE_ID, 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 HistorySeed, type HookEvent, type HookEventType, type HookHandler, InMemoryConfigProvider, InMemoryStore, type InputRequest, type InputRequestId, type InputRequiredCommit, type InvocationCatalogEntry, type InvocationSource, 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 MessageRevised, type MessageRevisionResult, type Metadata, type OpaqueId, type Outcome, type OwnerLease, type OwnerToken, type Page, type Phase, type PhaseContext, type PhaseContribution, type PhaseExecution, type PhaseExecutionIdentity, type PhaseInput, type PhaseInteraction, PhaseInteractionBoundary, PhaseInteractionCancelledError, type PhaseInteractionDriver, type PhaseInteractionKind, type PhaseInteractionState, type PhaseInteractionStatus, type PhaseInvocation, type PhaseMessageManager, type PhaseOutput, type PhaseRegistry, type PhaseRegistrySelection, type PhaseSettingsBadge, type PhaseSettingsContext, type PhaseSettingsControl, type PhaseSettingsDefinition, type PhaseSettingsItem, type PhaseSettingsOption, type PhaseSettingsProvider, type PhaseSettingsSection, type PhaseState, type PhaseStatus, type PhaseStatusState, type ResolvedResourceView, type ResourceDiagnostic, type ResourceKind, type ResourceRef, ResourceRegistry, ResourceRegistryError, type ResourceRegistryErrorCode, type ResourceSourceId, type ResourceView, type RetentionResult, 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, STOP_PHASE_ID, type Skill, SqliteStore, type TextContent, type ThinkingContent, type ThinkingDelta, type Tool, type ToolCallId, type ToolCallSnapshot, type ToolCallState, type ToolContribution, type ToolDefinition, type ToolExecutionResult$1 as ToolExecutionResult, type ToolInvocationContext, type ToolMessage, type ToolMessageContent, type ToolProgress, type ToolResultContent, type ToolStateChanged, type ToolUseContent, type UserContent, type UserInput, type UserMessage, brandConfigToken, createCompactPhase, createCorePhases, createCoreTools, createDefaultPhase, createStopPhase, isRuntimeError, loadExtensionsFromPath as loadExtensions, loadPhase, loadPhaseSettings, loadPhases, loadSkill, loadSkills, materializeConfigurationSnapshot, parseAgentDefinition, parseFrontmatter, resolveConfigurationSnapshot };

package/dist/index.js

@@ -2,8 +2,8 @@
 import { chmod, mkdir, readFile as readFile2, stat, writeFile } from "fs/promises";
 import { basename as basename2, dirname as dirname2, relative as relative2, resolve as resolve2 } from "path";
 import { tmpdir } from "os";
-import Type2 from "typebox";
-import Schema from "typebox/schema";
+import Type3 from "typebox";
+import Schema2 from "typebox/schema";
 
 // src/harness/context/resource-formatter.ts
 function escapeXml(value) {
@@ -95,6 +95,13 @@ function buildPhaseDirectiveMessage(phase, output) {
   const parts = [];
   parts.push(`<phase_content name="${escapeXml(phase.name)}">`);
   parts.push(phase.content);
+  if (output.payload !== void 0) {
+    const payload = jsonToXml(output.payload, 2);
+    parts.push("  <phase_input>");
+    if (payload) parts.push(payload);
+    else if (output.payload === null) parts.push("    null");
+    parts.push("  </phase_input>");
+  }
   if (output.results && output.results.length > 0 || output.instruction) {
     parts.push(`  <prev_phase_outputs>`);
     if (output.instruction) {
@@ -161,15 +168,147 @@ function normalizeRelativePath(path) {
 }
 
 // src/harness/tools/route-tool.ts
+import Type2 from "typebox";
+
+// src/runtime/json.ts
+function isPlainObject(value) {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function hasOnlyDataProperties(value) {
+  return Reflect.ownKeys(value).every((key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return Boolean(descriptor && "value" in descriptor);
+  });
+}
+function visit(value, seen) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (typeof value !== "object" || seen.has(value)) return false;
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (Object.getPrototypeOf(value) !== Array.prototype || !hasOnlyDataProperties(value)) return false;
+      if (Reflect.ownKeys(value).some((key) => key !== "length" && typeof key !== "string")) return false;
+      for (let index = 0; index < value.length; index += 1) {
+        if (!Object.prototype.hasOwnProperty.call(value, index) || !visit(value[index], seen)) return false;
+      }
+      return true;
+    }
+    if (!isPlainObject(value) || !hasOnlyDataProperties(value)) return false;
+    if (Reflect.ownKeys(value).some((key) => typeof key !== "string")) return false;
+    if (Object.prototype.hasOwnProperty.call(value, "toJSON")) return false;
+    return Object.keys(value).every((key) => visit(value[key], seen));
+  } finally {
+    seen.delete(value);
+  }
+}
+function isJsonValue(value) {
+  return visit(value, /* @__PURE__ */ new Set());
+}
+function assertJsonValue(value, argument = "value") {
+  if (!isJsonValue(value)) throw new TypeError(`${argument} must be JSON-safe`);
+}
+function canonicalJson(value) {
+  assertJsonValue(value);
+  const encode = (candidate) => {
+    if (candidate === null || typeof candidate !== "object") return JSON.stringify(candidate);
+    if (Array.isArray(candidate)) return `[${candidate.map(encode).join(",")}]`;
+    const object = candidate;
+    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${encode(object[key])}`).join(",")}}`;
+  };
+  return encode(value);
+}
+function utf8ByteLength(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+function assertUtf8ByteLimit(value, limit, argument = "value") {
+  if (utf8ByteLength(value) > limit) throw new RangeError(`${argument} exceeds ${limit} UTF-8 bytes`);
+}
+
+// src/harness/phases/input.ts
 import Type from "typebox";
+import Schema from "typebox/schema";
+function parsePhaseInput(value) {
+  if (value === void 0) return void 0;
+  if (!isJsonValue(value) || value === null || Array.isArray(value)) {
+    throw new TypeError("input must be a JSON-safe object");
+  }
+  return value;
+}
+function phaseInputSchema(input) {
+  return schemaForObject(input);
+}
+function preparePhasePayload(input, payload) {
+  if (payload !== void 0 && !isJsonValue(payload)) {
+    throw new TypeError("Phase payload must be JSON-safe");
+  }
+  if (input === void 0 || payload === void 0) {
+    if (input === void 0) return payload;
+    return mergeDefaultObject(input, {});
+  }
+  const validator = Schema.Compile(phaseInputSchema(input));
+  if (!validator.Check(payload)) {
+    throw new TypeError("Phase payload does not match the Phase input definition");
+  }
+  return mergeDefaultObject(input, payload);
+}
+function schemaForValue(value) {
+  if (value === null) return Type.Unknown();
+  if (typeof value === "string") return Type.String();
+  if (typeof value === "boolean") return Type.Boolean();
+  if (typeof value === "number") return Type.Number();
+  if (Array.isArray(value)) {
+    if (value.length === 0) return Type.Array(Type.Unknown());
+    const schemas = value.map(schemaForValue);
+    const unique = new Map(schemas.map((schema) => [JSON.stringify(schema), schema]));
+    const item = unique.size === 1 ? [...unique.values()][0] : Type.Union([...unique.values()]);
+    return Type.Array(item);
+  }
+  if (!isJsonObject(value)) throw new TypeError("Phase input values must be JSON-safe");
+  return schemaForObject(value);
+}
+function schemaForObject(value) {
+  const keys = Object.keys(value);
+  if (keys.length === 0) return Type.Record(Type.String(), Type.Unknown());
+  const properties = Object.fromEntries(keys.map((key) => [key, schemaForValue(value[key])]));
+  return Type.Partial(Type.Object(properties), { additionalProperties: false });
+}
+function mergeDefaultObject(defaults, payload) {
+  const result = {};
+  for (const [key, value] of Object.entries(payload)) {
+    const defaultValue = defaults[key];
+    result[key] = defaultValue !== void 0 && isJsonObject(defaultValue) && isJsonObject(value) ? mergeDefaultObject(defaultValue, value) : cloneJsonValue(value);
+  }
+  for (const [key, value] of Object.entries(defaults)) {
+    if (!Object.prototype.hasOwnProperty.call(payload, key)) {
+      result[key] = cloneJsonValue(value);
+    }
+  }
+  return result;
+}
+function cloneJsonValue(value) {
+  if (Array.isArray(value)) return value.map(cloneJsonValue);
+  if (isJsonObject(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, cloneJsonValue(item)]));
+  }
+  return value;
+}
+function isJsonObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/harness/tools/route-tool.ts
 var PhaseRouteTool = "route";
 function buildPhaseEntry(p) {
   const entry = { name: p.name, description: p.description };
   if (p.tools && p.tools.length > 0) {
     entry.available_tools = p.tools.join(", ");
   }
-  if (p.input && Object.keys(p.input).length > 0) {
-    entry.required_input = Object.entries(p.input).map(([key, desc]) => `- ${key}: ${desc}`).join("\n");
+  if (p.input !== void 0) {
+    entry.payload_schema = JSON.stringify(phaseInputSchema(p.input));
+  } else {
+    entry.payload_schema = "any JSON-safe value";
   }
   return entry;
 }
@@ -203,14 +342,20 @@ function buildRouteDescription(availablePhases) {
 }
 function createRouteTool(availablePhases) {
   const routablePhases = availablePhases.filter(({ name }) => name !== "stop");
-  const DecisionTarget = Type.Object({
-    phase: Type.Union([
-      ...routablePhases.map((p) => Type.Literal(p.name)),
-      Type.Literal("stop")
-    ]),
-    reason: Type.Optional(Type.String({ description: "Brief reason for this decision" })),
-    payload: Type.Optional(Type.Unknown({ description: "Structured input for the target phase" }))
-  });
+  const decisionTargets = [
+    ...routablePhases.map((phase) => Type2.Object({
+      phase: Type2.Literal(phase.name),
+      reason: Type2.Optional(Type2.String({ description: "Brief reason for this decision" })),
+      payload: Type2.Optional(
+        phase.input === void 0 ? Type2.Unknown({ description: "Any JSON-safe value for the target phase" }) : phaseInputSchema(phase.input)
+      )
+    })),
+    Type2.Object({
+      phase: Type2.Literal("stop"),
+      reason: Type2.Optional(Type2.String({ description: "Brief reason for this decision" })),
+      payload: Type2.Optional(Type2.Unknown({ description: "Optional stop payload" }))
+    })
+  ];
   return {
     name: PhaseRouteTool,
     description: buildRouteDescription(availablePhases),
@@ -219,9 +364,9 @@ function createRouteTool(availablePhases) {
       "Do not call route together with ordinary tools.",
       "Use route(stop) only when the current user request or task is complete; the Stop Phase will provide the final user-facing conclusion."
     ],
-    parameters: Type.Object({
-      decision: Type.Array(DecisionTarget, { description: "Phase executions to start", minItems: 1 }),
-      instruction: Type.Optional(Type.String({ description: "Overall instruction, passed as context" }))
+    parameters: Type2.Object({
+      decision: Type2.Array(Type2.Union(decisionTargets), { description: "Phase executions to start", minItems: 1 }),
+      instruction: Type2.Optional(Type2.String({ description: "Overall instruction, passed as context" }))
     }),
     // No-op: this tool is intercepted by phases, never executed via tool execution
     execute: async (_, context) => ({
@@ -274,37 +419,37 @@ var DEFAULT_MAX_READ_BYTES = 50 * 1024;
 var DEFAULT_MAX_READ_LINES = 2e3;
 var DEFAULT_BASH_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_BASH_OUTPUT_BYTES = 64e3;
-var ReadArgsSchema = Type2.Object({
-  path: Type2.String({ description: "Path to the file to read." }),
-  offset: Type2.Optional(Type2.Number({ description: "1-based line to start from." })),
-  limit: Type2.Optional(Type2.Number({ description: "Maximum number of lines." }))
+var ReadArgsSchema = Type3.Object({
+  path: Type3.String({ description: "Path to the file to read." }),
+  offset: Type3.Optional(Type3.Number({ description: "1-based line to start from." })),
+  limit: Type3.Optional(Type3.Number({ description: "Maximum number of lines." }))
 });
-var ReadArgsValidator = Schema.Compile(ReadArgsSchema);
-var WriteArgsSchema = Type2.Object({
-  path: Type2.String({ description: "Path to the file to write." }),
-  content: Type2.String({ description: "Complete file contents." })
+var ReadArgsValidator = Schema2.Compile(ReadArgsSchema);
+var WriteArgsSchema = Type3.Object({
+  path: Type3.String({ description: "Path to the file to write." }),
+  content: Type3.String({ description: "Complete file contents." })
 });
-var WriteArgsValidator = Schema.Compile(WriteArgsSchema);
-var EditArgsSchema = Type2.Object({
-  path: Type2.String({ description: "Path to the file to edit." }),
-  edits: Type2.Array(Type2.Object({
-    oldText: Type2.String({ description: "Exact unique text to replace." }),
-    newText: Type2.String({ description: "Replacement text." })
+var WriteArgsValidator = Schema2.Compile(WriteArgsSchema);
+var EditArgsSchema = Type3.Object({
+  path: Type3.String({ description: "Path to the file to edit." }),
+  edits: Type3.Array(Type3.Object({
+    oldText: Type3.String({ description: "Exact unique text to replace." }),
+    newText: Type3.String({ description: "Replacement text." })
   }), { description: "One or more non-overlapping replacements." })
 });
-var EditArgsValidator = Schema.Compile(EditArgsSchema);
-var BashArgsSchema = Type2.Object({
-  command: Type2.String({ description: "Bash command to execute." }),
-  timeout: Type2.Optional(Type2.Number({ description: "Timeout in seconds." }))
+var EditArgsValidator = Schema2.Compile(EditArgsSchema);
+var BashArgsSchema = Type3.Object({
+  command: Type3.String({ description: "Bash command to execute." }),
+  timeout: Type3.Optional(Type3.Number({ description: "Timeout in seconds." }))
 });
-var BashArgsValidator = Schema.Compile(BashArgsSchema);
+var BashArgsValidator = Schema2.Compile(BashArgsSchema);
 var validatorCache = /* @__PURE__ */ new WeakMap();
 function validatorFor(schema) {
   const cached = validatorCache.get(schema);
   if (cached) {
     return cached;
   }
-  const validator = Schema.Compile(schema);
+  const validator = Schema2.Compile(schema);
   validatorCache.set(schema, validator);
   return validator;
 }
@@ -1055,6 +1200,7 @@ function createExtensionAPI(hooks, options, runtime, eventBus) {
   let outputPayload = phaseIn?.state?.payload;
   let nextPhase;
   let outputMessage;
+  let settingsProvider;
   return {
     on: (eventType, handler) => {
       assertActive();
@@ -1115,65 +1261,22 @@ function createExtensionAPI(hooks, options, runtime, eventBus) {
         nextPhase = id;
       },
       getNextPhase: () => nextPhase,
-      getMessage: () => outputMessage
-    }
-  };
-}
-
-// src/runtime/json.ts
-function isPlainObject(value) {
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-function hasOnlyDataProperties(value) {
-  return Reflect.ownKeys(value).every((key) => {
-    const descriptor = Object.getOwnPropertyDescriptor(value, key);
-    return Boolean(descriptor && "value" in descriptor);
-  });
-}
-function visit(value, seen) {
-  if (value === null || typeof value === "boolean" || typeof value === "string") return true;
-  if (typeof value === "number") return Number.isFinite(value);
-  if (typeof value !== "object" || seen.has(value)) return false;
-  seen.add(value);
-  try {
-    if (Array.isArray(value)) {
-      if (Object.getPrototypeOf(value) !== Array.prototype || !hasOnlyDataProperties(value)) return false;
-      if (Reflect.ownKeys(value).some((key) => key !== "length" && typeof key !== "string")) return false;
-      for (let index = 0; index < value.length; index += 1) {
-        if (!Object.prototype.hasOwnProperty.call(value, index) || !visit(value[index], seen)) return false;
+      getMessage: () => outputMessage,
+      settings: {
+        register: (provider) => {
+          assertActive();
+          if (typeof provider !== "function") {
+            throw new Error("Phase Settings registration requires a provider function.");
+          }
+          if (settingsProvider) {
+            throw new Error("A Phase may register only one Settings provider.");
+          }
+          settingsProvider = provider;
+          options?.registerSettings?.(provider);
+        }
       }
-      return true;
     }
-    if (!isPlainObject(value) || !hasOnlyDataProperties(value)) return false;
-    if (Reflect.ownKeys(value).some((key) => typeof key !== "string")) return false;
-    if (Object.prototype.hasOwnProperty.call(value, "toJSON")) return false;
-    return Object.keys(value).every((key) => visit(value[key], seen));
-  } finally {
-    seen.delete(value);
-  }
-}
-function isJsonValue(value) {
-  return visit(value, /* @__PURE__ */ new Set());
-}
-function assertJsonValue(value, argument = "value") {
-  if (!isJsonValue(value)) throw new TypeError(`${argument} must be JSON-safe`);
-}
-function canonicalJson(value) {
-  assertJsonValue(value);
-  const encode = (candidate) => {
-    if (candidate === null || typeof candidate !== "object") return JSON.stringify(candidate);
-    if (Array.isArray(candidate)) return `[${candidate.map(encode).join(",")}]`;
-    const object = candidate;
-    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${encode(object[key])}`).join(",")}}`;
   };
-  return encode(value);
-}
-function utf8ByteLength(value) {
-  return new TextEncoder().encode(value).byteLength;
-}
-function assertUtf8ByteLimit(value, limit, argument = "value") {
-  if (utf8ByteLength(value) > limit) throw new RangeError(`${argument} exceeds ${limit} UTF-8 bytes`);
 }
 
 // src/harness/phases/interactions.ts
@@ -1607,13 +1710,21 @@ async function loadPhase(targetPath) {
   warnResourceDiagnostics("phase", resolved, diagnostics);
   const baseDir = dirname4(resolved);
   const skills = await loadPhaseSkills(baseDir);
+  let input;
+  try {
+    input = parsePhaseInput(metadata.input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    warnResourceDiagnostics("phase", resolved, [message]);
+    throw new ResourceMetadataError("invalid_metadata", message);
+  }
   const phase = {
     name,
     description: description.description,
     tools: definition.tools ? [...definition.tools] : void 0,
     skills,
     target: metadata.target,
-    input: metadata.input,
+    ...input === void 0 ? {} : { input },
     isolated: metadata.isolated,
     filePath: resolved,
     baseDir,
@@ -1627,12 +1738,24 @@ async function loadPhase(targetPath) {
     const code = await loadPhaseCode(codePath);
     if (code.factory) {
       phase.factory = code.factory;
-    } else if (code.run) {
+    }
+    if (code.run) {
       phase.run = code.run;
     }
   }
   return phase;
 }
+async function loadPhaseSettings(phase, context) {
+  if (!phase.factory) return void 0;
+  let provider;
+  const api = createExtensionAPI(void 0, {
+    registerSettings: (candidate) => {
+      provider = candidate;
+    }
+  });
+  await phase.factory(api);
+  return provider ? provider(context) : void 0;
+}
 async function loadPhaseSkills(baseDir) {
   const entries = await readdir2(baseDir, { withFileTypes: true });
   const skills = [];
@@ -1743,13 +1866,15 @@ async function loadPhaseCode(codePath) {
     moduleCache: false,
     tryNative: false
   });
-  const mod = await jiti.import(codePath, { default: true });
-  const fn = typeof mod === "function" ? mod : mod?.default;
-  if (typeof fn === "function") {
-    return { factory: fn };
-  }
-  if (typeof mod?.run === "function") {
-    return { run: mod.run };
+  const mod = await jiti.import(codePath);
+  const namespace = mod && typeof mod === "object" ? mod : {};
+  const fn = typeof mod === "function" ? mod : namespace.default;
+  const run = namespace.run;
+  if (typeof fn === "function" || typeof run === "function") {
+    return {
+      ...typeof fn === "function" ? { factory: fn } : {},
+      ...typeof run === "function" ? { run } : {}
+    };
   }
   throw new Error(`Phase code at "${codePath}" must export a default function or a run() function.`);
 }
@@ -2163,9 +2288,21 @@ function resolveRouteDecision(route, registry) {
     if (requestedCount !== 1) return void 0;
     return { ...route, requestedCount };
   }
-  const decision = route.decision.filter(({ phase }) => registry.phases.has(phase));
+  const decision = route.decision.flatMap((candidate) => {
+    const target = registry.phases.get(candidate.phase);
+    if (!target) return [];
+    try {
+      const payload = preparePhasePayload(target.input, normalizePayload(candidate.payload));
+      return [{
+        ...candidate,
+        ...payload === void 0 ? {} : { payload }
+      }];
+    } catch {
+      return [];
+    }
+  });
   if (decision.length === 0) return void 0;
-  return { ...route, decision, requestedCount };
+  return { ...route, decision, requestedCount: decision.length };
 }
 function resolveModelRouteDecision(toolCalls, registry) {
   return resolveRouteDecision(toolCalls ? extractRouteCall(toolCalls) : void 0, registry);
@@ -2400,7 +2537,8 @@ async function runPhaseLoop(config, state, registry) {
   if (resumingSuspendedRun) {
     state.status = "running";
   }
-  let previousPayload = resumingSuspendedRun ? state.continuation?.previousPayload : void 0;
+  const initialPayload = !resumingSuspendedRun ? config.execution.runMetadata?.phasePayload : void 0;
+  let previousPayload = resumingSuspendedRun ? state.continuation?.previousPayload : initialPayload;
   let previousPhaseMsgId = resumingSuspendedRun ? state.continuation?.previousPhaseMessageId : void 0;
   let previousPhaseInputMsgId;
   let previousResults = resumingSuspendedRun ? state.continuation?.previousResults?.map((result) => ({ ...result })) ?? [] : [];
@@ -2491,6 +2629,9 @@ async function runPhaseLoop(config, state, registry) {
     if (!phase) {
       throw new Error(`Phase "${currentPhaseId}" not found`);
     }
+    if (previousPayload !== void 0 || phase.input !== void 0) {
+      previousPayload = preparePhasePayload(phase.input, previousPayload);
+    }
     state.currentPhase = currentPhaseId;
     const allTools = buildToolsWithRouting(config, availablePhases);
     const messageManager = createMessageManager(config.context, config.onMessage, config.onMessageDelta);
@@ -2556,7 +2697,7 @@ async function runPhaseLoop(config, state, registry) {
       const lastMessageBeforePhase = config.context.messages.at(-1);
       previousPhaseMsgId = injectPhaseContent(
         phase,
-        { results: previousResults, instruction: pendingInstruction },
+        { results: previousResults, instruction: pendingInstruction, payload: previousPayload },
         config.context.messages,
         phaseContext.messages
       );
@@ -2602,6 +2743,7 @@ async function runPhaseLoop(config, state, registry) {
         output = extAfter.output;
         if (hookHasRoute) {
           routeDecision = resolveHookRouteDecision(output, registry);
+          if (routeDecision) applyFirstDecision(routeDecision, output);
         } else if (phase.run || phase.factory) {
           output = { ...output, route: "stop" };
           routeDecision = void 0;
@@ -2708,7 +2850,7 @@ async function runPhaseLoop(config, state, registry) {
       }
       currentPhaseId = STOP_PHASE_ID;
       previousPayload = output.payload;
-      previousResults = output.payload !== void 0 ? [{ name: phase.name, output: output.payload }] : [];
+      previousResults = [];
       pendingInstruction = phase.target ? void 0 : routeDecision?.instruction;
       continue;
     }
@@ -2725,8 +2867,10 @@ async function runPhaseLoop(config, state, registry) {
       to: targetPhaseId,
       ts: createTimestamp()
     });
-    previousPayload = output.payload;
-    previousResults = output.payload !== void 0 ? [{ name: phase.name, output: output.payload }] : [];
+    const targetPhase = registry.phases.get(targetPhaseId);
+    const targetPayload = !phase.target && routeDecision ? routeDecision.decision[0]?.payload : output.payload;
+    previousPayload = preparePhasePayload(targetPhase?.input, targetPayload);
+    previousResults = [];
     pendingInstruction = phase.target ? void 0 : routeDecision?.instruction;
     currentPhaseId = targetPhaseId;
   }
@@ -2784,6 +2928,14 @@ async function withRetry(fn, options = {}) {
 }
 async function executePhase(ctx) {
   const { phase, config, execution, registry, context } = ctx;
+  if (phase.run) {
+    const output = resolvePhaseOutput(await phase.run(context, execution));
+    output.phase = phase.name;
+    if (output.message === "Phase completed.") {
+      output.message = `${phase.name} phase completed.`;
+    }
+    return output;
+  }
   if (phase.factory) {
     const api = createExtensionAPI(void 0, {
       registerPhase: async () => {
@@ -2822,14 +2974,6 @@ async function executePhase(ctx) {
       payload: api.phase.getPayload()
     };
   }
-  if (phase.run) {
-    const output = resolvePhaseOutput(await phase.run(context, execution));
-    output.phase = phase.name;
-    if (output.message === "Phase completed.") {
-      output.message = `${phase.name} phase completed.`;
-    }
-    return output;
-  }
   return executePhaseWithModel(ctx);
 }
 async function executeToolCall(input) {
@@ -2995,6 +3139,7 @@ function createPhaseExecution(config, state, phase, messageManager, toolExecutio
 }
 async function executeParallelPhase(config, state, registry, phase, payload, instruction, context, availablePhases, instanceId, groupId, index, count, sourcePhaseId) {
   const messages = [...context];
+  const effectivePayload = preparePhasePayload(phase.input, payload);
   const allTools = buildToolsWithRouting(config, availablePhases);
   const phaseTools = selectPhaseTools(allTools, phase.tools, false);
   const phaseSkills = mergeSkills(config.context.skills, phase.skills);
@@ -3017,7 +3162,7 @@ async function executeParallelPhase(config, state, registry, phase, payload, ins
       current: phase.name,
       available: Array.from(registry.phases.keys()),
       iterations: 0,
-      payload
+      payload: effectivePayload
     }
   };
   const messageManager = createMessageManager({ messages }, config.onMessage, config.onMessageDelta);
@@ -3025,7 +3170,8 @@ async function executeParallelPhase(config, state, registry, phase, payload, ins
     phase,
     {
       instruction,
-      results: payload !== void 0 ? [{ name: sourcePhaseId, output: payload }] : []
+      payload: effectivePayload,
+      results: []
     },
     messages
   );
@@ -5863,6 +6009,7 @@ var AgentRuntime = class _AgentRuntime {
         kind: "phase",
         name: phase.name,
         description: phase.description,
+        ...phase.input === void 0 ? {} : { input: phase.input },
         ...phase.core ? { core: true } : {},
         disableAutoInvocation: phase.disableAutoInvocation ?? false,
         disableImplicitInvocation: phase.disableImplicitInvocation ?? false,
@@ -8825,6 +8972,7 @@ export {
   isRuntimeError,
   loadExtensionsFromPath as loadExtensions,
   loadPhase,
+  loadPhaseSettings,
   loadPhases,
   loadSkill,
   loadSkills,

package/package.json

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