@rowan-agent/agent 0.9.14 → 0.9.16

package/dist/index.d.ts

@@ -566,6 +566,25 @@ type PhaseExecution = {
     executeTool(context: AgentContext, toolCall: ToolCall): Promise<ToolResult>;
     executeTools(context: AgentContext, toolCalls: readonly ToolCall[]): Promise<readonly ToolResult[]>;
     interaction: PhaseInteractionDriver;
+    /** Message lifecycle manager for streaming updates from programmatic phases */
+    messages: PhaseMessageManager;
+};
+/** Message lifecycle manager for streaming updates */
+type PhaseMessageManager = {
+    /** Get all visible messages in the transcript */
+    visible(): AgentMessage[];
+    /** Reserve the eventual message identity before stream deltas arrive. */
+    reserve(role: "assistant" | "tool", metadata?: Record<string, unknown>): string;
+    /** Start a new message stream, returns message id */
+    start(role: "assistant" | "tool", content: AgentMessage["content"], metadata?: Record<string, unknown>): string;
+    /** Stream a text delta */
+    update(messageId: string, delta: string): Promise<void>;
+    /** Replace the active message content with model-native content parts */
+    replaceContent(messageId: string, content: string | LlmContentPart[]): void;
+    /** End the message stream, appends to transcript */
+    end(messageId: string): Promise<void>;
+    /** Drop an unstarted stream that produced no content. */
+    discard(messageId: string): void;
 };
 
 /**
@@ -867,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;
+        };
     };
 }
 /**
@@ -957,6 +980,83 @@ interface PhaseContext {
     /** Text to append after the system prompt */
     appendSystemPrompt?: string;
 }
+/** 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
  */
@@ -989,7 +1089,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>;
@@ -2626,6 +2726,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.
  *
@@ -2679,4 +2785,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 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 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

@@ -1055,6 +1055,7 @@ function createExtensionAPI(hooks, options, runtime, eventBus) {
   let outputPayload = phaseIn?.state?.payload;
   let nextPhase;
   let outputMessage;
+  let settingsProvider;
   return {
     on: (eventType, handler) => {
       assertActive();
@@ -1115,7 +1116,20 @@ function createExtensionAPI(hooks, options, runtime, eventBus) {
         nextPhase = id;
       },
       getNextPhase: () => nextPhase,
-      getMessage: () => outputMessage
+      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);
+        }
+      }
     }
   };
 }
@@ -1627,12 +1641,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 +1769,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.`);
 }
@@ -2784,6 +2812,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 +2858,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) {
@@ -2882,6 +2910,7 @@ function createPhaseExecution(config, state, phase, messageManager, toolExecutio
   const interaction = createPhaseInteractionDriver(state, phase.name, config.signal);
   return {
     interaction,
+    messages: messageManager,
     snapshot() {
       return {
         systemPrompt: config.context.systemPrompt,
@@ -8824,6 +8853,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.14",
+  "version": "0.9.16",
   "license": "MIT",
   "repository": {
     "type": "git",