@rowan-agent/agent 0.8.7 → 0.9.1

package/dist/index.d.ts

@@ -83,23 +83,6 @@ interface SourceInfo {
     baseDir?: string;
     displayName?: string;
 }
-/** Phase run function type for extensions */
-type PhaseRun = (context: PhaseContext, execution: PhaseExecution) => Promise<PhaseOutput | void>;
-/** Phase definition shape used by extensions */
-type PhaseDefinition = {
-    name: string;
-    description: string;
-    run?: PhaseRun;
-    tools?: string[];
-    skills?: string[];
-    target?: string;
-    input?: Record<string, string>;
-    model?: string;
-};
-type PhaseRegistration = Omit<PhaseDefinition, 'run'> & {
-    /** Optional execution override — takes over model invocation */
-    run?: PhaseRun;
-};
 /**
  * Tool definition for registering LLM-callable tools via `api.registerTool()`.
  *
@@ -214,12 +197,6 @@ interface LoadedExtension {
 interface ExtensionManifest {
     entry?: string;
     name?: string;
-    phase?: {
-        name?: string;
-        description?: string;
-        tools?: string[];
-        skills?: string[];
-    };
 }
 
 /**
@@ -438,8 +415,8 @@ interface ExtensionAPI {
     off<K extends HookEventType>(eventType: K, handler: HookHandler<K>): void;
     /** Register a custom LLM-callable tool. */
     registerTool(tool: ToolDefinition): void;
-    /** Register a custom phase. */
-    registerPhase(registration: PhaseRegistration): void;
+    /** Register a Phase directory bundle. */
+    registerPhase(path: string): Promise<void>;
     /** Register a model provider. */
     registerProvider(config: _rowan_agent_models.ProviderConfig): void;
     /** Unregister a model provider. */
@@ -552,8 +529,8 @@ interface Phase {
     description: string;
     /** Restricted tools (undefined = all tools available) */
     tools?: string[];
-    /** Restricted skills (undefined = all skills available) */
-    skills?: string[];
+    /** Skills bundled directly inside this phase directory. Inline phases may omit this (equivalent to []). */
+    skills?: Skill[];
     /** Forced next phase */
     target?: string;
     /** Expected input fields (key → description) */
@@ -613,6 +590,10 @@ type AgentContext = {
     phases?: PhaseRegistry;
 };
 
+/**
+ * `root` anchors relative paths and the Bash working directory. It is not a
+ * filesystem sandbox: core Tools use the permissions of the host process.
+ */
 type CoreToolContext = {
     root?: string;
     maxReadBytes?: number;
@@ -1176,6 +1157,7 @@ declare class ExtensionRunner {
     private createExtensionAPI;
     private registerTool;
     private registerPhase;
+    private loadRegisteredPhase;
     private registerProvider;
     private unregisterProvider;
     private flushPendingProviders;
@@ -2222,8 +2204,15 @@ declare class RuntimeError<Code extends RuntimeErrorCode = RuntimeErrorCode> ext
 }
 declare function isRuntimeError(value: unknown): value is AnyRuntimeError;
 
+declare function loadSkill(path: string): Promise<Skill>;
 declare function loadSkills(targetPath: string): Promise<Skill[]>;
 
+/**
+ * Load a single phase from a PHASE.md file or phase directory.
+ *
+ * If a directory is provided, the loader reads its PHASE.md.
+ */
+declare function loadPhase(targetPath: string): Promise<Phase>;
 /**
  * Load all phases from the target directory.
  *
@@ -2269,4 +2258,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, type ConfigProvider, type ConfigPutResult, type ConfigResolution, type ConfigToken, type ConfigurationSnapshot, type ContextCandidate, type CoreToolContext, 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 HookEvent, type HookEventType, type HookHandler, InMemoryConfigProvider, InMemoryStore, type InputRequest, type InputRequestId, type InputRequiredCommit, 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 Metadata, type OpaqueId, type Outcome, type OwnerLease, type OwnerToken, type Page, type Phase, type PhaseContext, type PhaseContribution, type PhaseExecutionIdentity, type PhaseInvocation, type PhaseOutput, type PhaseRegistry, type PhaseRegistrySelection, type PhaseState, type ResolvedResourceView, type ResourceDiagnostic, type ResourceKind, type ResourceRef, ResourceRegistry, ResourceRegistryError, type ResourceRegistryErrorCode, type ResourceSourceId, type ResourceView, 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, type Skill, SqliteStore, type TextContent, type ThinkingContent, type Tool, type ToolCallId, type ToolCallSnapshot, type ToolCallState, type ToolContribution, type ToolDefinition, type ToolExecutionResult, type ToolInvocationContext, type ToolMessage, type ToolMessageContent, type ToolProgress, type ToolResultContent, type ToolStateChanged, type ToolUseContent, type UserContent, type UserInput, type UserMessage, brandConfigToken, createCoreTools, isRuntimeError, loadExtensionsFromPath as loadExtensions, loadPhases, 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, type ConfigProvider, type ConfigPutResult, type ConfigResolution, type ConfigToken, type ConfigurationSnapshot, type ContextCandidate, type CoreToolContext, 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 HookEvent, type HookEventType, type HookHandler, InMemoryConfigProvider, InMemoryStore, type InputRequest, type InputRequestId, type InputRequiredCommit, 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 Metadata, type OpaqueId, type Outcome, type OwnerLease, type OwnerToken, type Page, type Phase, type PhaseContext, type PhaseContribution, type PhaseExecutionIdentity, type PhaseInvocation, type PhaseOutput, type PhaseRegistry, type PhaseRegistrySelection, type PhaseState, type ResolvedResourceView, type ResourceDiagnostic, type ResourceKind, type ResourceRef, ResourceRegistry, ResourceRegistryError, type ResourceRegistryErrorCode, type ResourceSourceId, type ResourceView, 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, type Skill, SqliteStore, type TextContent, type ThinkingContent, type Tool, type ToolCallId, type ToolCallSnapshot, type ToolCallState, type ToolContribution, type ToolDefinition, type ToolExecutionResult, type ToolInvocationContext, type ToolMessage, type ToolMessageContent, type ToolProgress, type ToolResultContent, type ToolStateChanged, type ToolUseContent, type UserContent, type UserInput, type UserMessage, brandConfigToken, createCoreTools, isRuntimeError, loadExtensionsFromPath as loadExtensions, loadPhase, loadPhases, loadSkill, loadSkills, materializeConfigurationSnapshot, parseAgentDefinition, parseFrontmatter, resolveConfigurationSnapshot };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/harness/tools/index.ts
 import { mkdir, readFile as readFile2, stat, writeFile } from "fs/promises";
-import { basename as basename2, dirname as dirname2, isAbsolute as isAbsolute2, relative as relative2, resolve as resolve2, sep as sep2 } from "path";
+import { basename as basename2, dirname as dirname2, relative as relative2, resolve as resolve2 } from "path";
 import Type2 from "typebox";
 import Schema from "typebox/schema";
 
@@ -164,9 +164,6 @@ function buildPhaseEntry(p) {
   if (p.tools && p.tools.length > 0) {
     entry.available_tools = p.tools.join(", ");
   }
-  if (p.skills && p.skills.length > 0) {
-    entry.available_skills = p.skills.join(", ");
-  }
   if (p.input && Object.keys(p.input).length > 0) {
     entry.required_input = Object.entries(p.input).map(([key, desc]) => `- ${key}: ${desc}`).join("\n");
   }
@@ -311,9 +308,6 @@ function resolveCoreToolPath(context, path = ".") {
   const inputPath = normalizeCoreToolInputPath(path);
   const absolutePath = resolve2(root, inputPath);
   const relativePath = relative2(root, absolutePath);
-  if (relativePath === ".." || relativePath.startsWith(`..${sep2}`) || isAbsolute2(relativePath)) {
-    throw new Error(`Path escapes workspace root: ${path}`);
-  }
   return {
     root,
     inputPath,
@@ -468,7 +462,7 @@ async function captureStream(stream, maxBytes) {
 function createReadTool(context) {
   return {
     name: "read",
-    description: "Read a file in the workspace.",
+    description: "Read a file using the host process filesystem permissions.",
     parameters: ReadArgsSchema,
     promptSnippet: "Read file contents.",
     promptGuidelines: ["Read files before editing them."],
@@ -539,7 +533,7 @@ function createReadTool(context) {
 function createWriteTool(context) {
   return {
     name: "write",
-    description: "Create or overwrite a file in the workspace.",
+    description: "Create or overwrite a file using the host process filesystem permissions.",
     parameters: WriteArgsSchema,
     promptSnippet: "Create or overwrite files.",
     promptGuidelines: ["Use edit for partial changes."],
@@ -591,7 +585,7 @@ function applyEditReplacements(current, edits) {
 function createEditTool(context) {
   return {
     name: "edit",
-    description: "Apply exact text replacements to a workspace file.",
+    description: "Apply exact text replacements using the host process filesystem permissions.",
     parameters: EditArgsSchema,
     promptSnippet: "Apply exact text replacements.",
     promptGuidelines: ["Read the file first; each oldText must match exactly once."],
@@ -627,7 +621,7 @@ function createEditTool(context) {
 function createBashTool(context) {
   return {
     name: "bash",
-    description: "Run a bash command in the workspace.",
+    description: "Run a bash command with the host process filesystem permissions; root is the working directory.",
     parameters: BashArgsSchema,
     promptSnippet: "Run shell commands.",
     promptGuidelines: ["Use read/write/edit for file operations."],
@@ -985,9 +979,9 @@ function createExtensionAPI(hooks, options, runtime, eventBus) {
       assertActive();
       options?.registerTool?.(tool);
     },
-    registerPhase: (registration) => {
+    registerPhase: async (registration) => {
       assertActive();
-      options?.registerPhase?.(registration);
+      await options?.registerPhase?.(registration);
     },
     registerProvider: (config) => {
       assertActive();
@@ -1037,9 +1031,9 @@ function createExtensionAPI(hooks, options, runtime, eventBus) {
 }
 
 // src/harness/phases/loader.ts
-import { existsSync, statSync } from "fs";
-import { readdir } from "fs/promises";
-import { dirname as dirname3, join, resolve as resolve3 } from "path";
+import { existsSync as existsSync2, statSync as statSync2 } from "fs";
+import { readdir as readdir2 } from "fs/promises";
+import { dirname as dirname4, join as join2, resolve as resolve4 } from "path";
 
 // src/harness/definitions.ts
 import { parseModelRef } from "@rowan-agent/models";
@@ -1126,9 +1120,8 @@ function optionalStringList(value, field) {
 function optionalPhaseRegistrySelection(value, field) {
   if (value === void 0) return void 0;
   if (!isRecord(value)) throw new TypeError(`${field} must be an object`);
-  if (!("entryPhaseId" in value)) throw new TypeError(`${field}.entryPhaseId is required`);
   if (!("phaseIds" in value)) throw new TypeError(`${field}.phaseIds is required`);
-  const entryPhaseId = value.entryPhaseId;
+  const entryPhaseId = value.entryPhaseId ?? null;
   if (entryPhaseId !== null && (typeof entryPhaseId !== "string" || entryPhaseId.trim() === "")) {
     throw new TypeError(`${field}.entryPhaseId must be a non-empty string or null`);
   }
@@ -1203,19 +1196,6 @@ function validateDescription(value) {
   }
   return { description: value, warnings: [], missing: false };
 }
-function validateSkillReferences(value) {
-  if (value === void 0) return [];
-  if (!Array.isArray(value)) return ["skills must be an array"];
-  const errors = [];
-  for (const [index, skillId] of value.entries()) {
-    if (typeof skillId !== "string") {
-      errors.push(`skills[${index}] must be a string`);
-      continue;
-    }
-    errors.push(...validateResourceId(skillId, `skills[${index}]`));
-  }
-  return errors;
-}
 function validatePhaseTarget(value) {
   if (value === void 0) return [];
   if (typeof value !== "string") return ["target must be a string"];
@@ -1228,11 +1208,91 @@ function warnResourceDiagnostics(kind, filePath, diagnostics) {
   }
 }
 
+// src/harness/skills.ts
+import { existsSync, statSync } from "fs";
+import { readdir } from "fs/promises";
+import { dirname as dirname3, join, resolve as resolve3 } from "path";
+var SKILL_MARKER = "SKILL.md";
+function resolveSkillPath(input) {
+  const resolved = resolve3(input);
+  return existsSync(resolved) && statSync(resolved).isDirectory() ? join(resolved, SKILL_MARKER) : resolved;
+}
+async function loadSkill(path) {
+  const resolved = resolveSkillPath(path);
+  let loaded;
+  try {
+    loaded = await loadMarkdown(resolved);
+  } catch (error) {
+    if (!(error instanceof FrontmatterParseError)) throw error;
+    warnResourceDiagnostics("skill", resolved, [`frontmatter could not be parsed: ${error.message}`]);
+    throw new ResourceMetadataError("parse_failed", error.message);
+  }
+  const { frontmatter, body } = loaded;
+  const metadata = frontmatter;
+  const id = inferResourceName(resolved, SKILL_MARKER);
+  const frontmatterName = typeof metadata.name === "string" ? metadata.name : void 0;
+  const name = frontmatterName || id;
+  const description = validateDescription(metadata.description);
+  const diagnostics = validateResourceId(id);
+  if (frontmatterName && frontmatterName !== id) {
+    diagnostics.push(...validateResourceName(frontmatterName, id));
+  }
+  diagnostics.push(...description.warnings);
+  warnResourceDiagnostics("skill", resolved, diagnostics);
+  if (description.missing) {
+    throw new ResourceMetadataError("invalid_metadata", "description is required");
+  }
+  return {
+    name,
+    description: description.description,
+    filePath: resolved,
+    baseDir: dirname3(resolved),
+    content: body,
+    disableModelInvocation: metadata["disable-model-invocation"] === true
+  };
+}
+async function loadSkills(targetPath) {
+  const skillsDir = resolve3(targetPath);
+  if (existsSync(skillsDir) && statSync(skillsDir).isFile()) {
+    try {
+      return [await loadSkill(skillsDir)];
+    } catch (error) {
+      if (error instanceof ResourceMetadataError) return [];
+      throw error;
+    }
+  }
+  if (existsSync(join(skillsDir, SKILL_MARKER))) {
+    try {
+      return [await loadSkill(skillsDir)];
+    } catch (error) {
+      if (error instanceof ResourceMetadataError) return [];
+      throw error;
+    }
+  }
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  const skills = [];
+  for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory()) continue;
+    const skillFile = join(skillsDir, entry.name, SKILL_MARKER);
+    if (!existsSync(skillFile)) continue;
+    try {
+      const skill = await loadSkill(skillFile);
+      skills.push(skill);
+    } catch (error) {
+      if (error instanceof ResourceMetadataError) continue;
+      console.warn(`Failed to load skill "${entry.name}":`, error);
+    }
+  }
+  return skills;
+}
+
 // src/harness/phases/loader.ts
 var PHASE_MARKER = "PHASE.md";
+var SKILL_MARKER2 = "SKILL.md";
+var RESOURCE_MARKERS = /* @__PURE__ */ new Set([PHASE_MARKER, SKILL_MARKER2]);
 function resolvePhasePath(input) {
-  const resolved = resolve3(input);
-  return existsSync(resolved) && statSync(resolved).isDirectory() ? join(resolved, PHASE_MARKER) : resolved;
+  const resolved = resolve4(input);
+  return existsSync2(resolved) && statSync2(resolved).isDirectory() ? join2(resolved, PHASE_MARKER) : resolved;
 }
 async function loadPhase(targetPath) {
   const resolved = resolvePhasePath(targetPath);
@@ -1250,7 +1310,9 @@ async function loadPhase(targetPath) {
   const frontmatterName = typeof metadata.name === "string" ? metadata.name : void 0;
   let definition;
   try {
-    definition = normalizeAgentDefinition(metadata, body, { fallbackName: directoryName });
+    const phaseMetadata = { ...metadata };
+    delete phaseMetadata.skills;
+    definition = normalizeAgentDefinition(phaseMetadata, body, { fallbackName: directoryName });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     warnResourceDiagnostics("phase", resolved, [message]);
@@ -1263,15 +1325,15 @@ async function loadPhase(targetPath) {
     diagnostics.push(...validateResourceName(frontmatterName, directoryName));
   }
   diagnostics.push(...description.warnings);
-  diagnostics.push(...validateSkillReferences(metadata.skills));
   diagnostics.push(...validatePhaseTarget(metadata.target));
   warnResourceDiagnostics("phase", resolved, diagnostics);
-  const baseDir = dirname3(resolved);
+  const baseDir = dirname4(resolved);
+  const skills = await loadPhaseSkills(baseDir);
   const phase = {
     name,
     description: description.description,
     tools: definition.tools ? [...definition.tools] : void 0,
-    skills: definition.skills ? [...definition.skills] : void 0,
+    skills,
     target: metadata.target,
     input: metadata.input,
     isolated: metadata.isolated,
@@ -1291,6 +1353,54 @@ async function loadPhase(targetPath) {
   }
   return phase;
 }
+async function loadPhaseSkills(baseDir) {
+  const entries = await readdir2(baseDir, { withFileTypes: true });
+  const skills = [];
+  for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
+    const entryPath = join2(baseDir, entry.name);
+    if (!entry.isDirectory()) {
+      if (RESOURCE_MARKERS.has(entry.name) && entry.name !== PHASE_MARKER) {
+        throw invalidPhaseBundle(`resource marker ${entry.name} is not valid at the phase root`);
+      }
+      continue;
+    }
+    const markers = await findResourceMarkers(entryPath);
+    const directSkillPath = join2(entryPath, SKILL_MARKER2);
+    const hasDirectSkill = markers.includes(directSkillPath);
+    if (!hasDirectSkill) {
+      if (markers.length > 0) {
+        throw invalidPhaseBundle(`resource marker ${markers[0]} is not a direct child Skill`);
+      }
+      continue;
+    }
+    const nestedMarkers = markers.filter((marker) => marker !== directSkillPath);
+    if (nestedMarkers.length > 0) {
+      throw invalidPhaseBundle(`resource marker ${nestedMarkers[0]} is nested below a Skill bundle`);
+    }
+    const skill = await loadSkill(directSkillPath);
+    if (skills.some((candidate) => candidate.name === skill.name)) {
+      throw invalidPhaseBundle(`duplicate bundled Skill name "${skill.name}"`);
+    }
+    skills.push(skill);
+  }
+  return skills;
+}
+async function findResourceMarkers(directory) {
+  const entries = await readdir2(directory, { withFileTypes: true });
+  const markers = [];
+  for (const entry of entries) {
+    const entryPath = join2(directory, entry.name);
+    if (entry.isDirectory()) {
+      markers.push(...await findResourceMarkers(entryPath));
+    } else if (RESOURCE_MARKERS.has(entry.name)) {
+      markers.push(entryPath);
+    }
+  }
+  return markers;
+}
+function invalidPhaseBundle(message) {
+  return new ResourceMetadataError("invalid_metadata", message);
+}
 function readPhaseContent(phase) {
   return formatResourceOutput({
     type: "phase",
@@ -1302,8 +1412,8 @@ function readPhaseContent(phase) {
 }
 async function loadPhases(targetPath) {
   const phases = /* @__PURE__ */ new Map();
-  const phasesDir = resolve3(targetPath);
-  if (existsSync(phasesDir) && statSync(phasesDir).isFile()) {
+  const phasesDir = resolve4(targetPath);
+  if (existsSync2(phasesDir) && statSync2(phasesDir).isFile()) {
     try {
       const phase = await loadPhase(phasesDir);
       phases.set(phase.name, phase);
@@ -1312,7 +1422,7 @@ async function loadPhases(targetPath) {
     }
     return { phases, entryPhaseId: null };
   }
-  if (existsSync(join(phasesDir, PHASE_MARKER))) {
+  if (existsSync2(join2(phasesDir, PHASE_MARKER))) {
     try {
       const phase = await loadPhase(phasesDir);
       phases.set(phase.name, phase);
@@ -1321,11 +1431,11 @@ async function loadPhases(targetPath) {
     }
     return { phases, entryPhaseId: null };
   }
-  const entries = await readdir(phasesDir, { withFileTypes: true });
+  const entries = await readdir2(phasesDir, { withFileTypes: true });
   for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
     if (!entry.isDirectory()) continue;
-    const phaseFile = join(phasesDir, entry.name, PHASE_MARKER);
-    if (!existsSync(phaseFile)) continue;
+    const phaseFile = join2(phasesDir, entry.name, PHASE_MARKER);
+    if (!existsSync2(phaseFile)) continue;
     try {
       const phase = await loadPhase(phaseFile);
       phases.set(phase.name, phase);
@@ -1339,8 +1449,8 @@ async function loadPhases(targetPath) {
 async function discoverPhaseCode(baseDir) {
   const candidates = ["index.ts", "index.js"];
   for (const candidate of candidates) {
-    const fullPath = join(baseDir, candidate);
-    if (existsSync(fullPath)) {
+    const fullPath = join2(baseDir, candidate);
+    if (existsSync2(fullPath)) {
       return fullPath;
     }
   }
@@ -1372,6 +1482,7 @@ function createDefaultPhase() {
     description: "Executes concrete task operations and produces artifacts.",
     filePath: "",
     baseDir: "",
+    skills: [],
     content: "Execute tasks using current context.\nNo planning. No evaluation.\nRoute to next phase or stop when done."
   };
 }
@@ -1426,7 +1537,7 @@ function buildSystemPrompt(options) {
   }
   const guidelines = guidelinesList.map((g) => `- ${g}`).join("\n");
   const skillsSection = skillsBlock ? `The following skills provide specialized instructions for specific tasks.
-Read the full skill file when the task matches its description.
+Use the read tool to load a skill's file when the task matches its description.
 When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md) and use that absolute path in tool commands.
 
 ${skillsBlock}
@@ -1929,7 +2040,7 @@ async function runPhaseLoop(config, state, registry) {
     const toolExecutionManager = createToolExecutionManager();
     const execution = createPhaseExecution(config, state, phase, messageManager, toolExecutionManager, registry);
     const phaseTools = selectPhaseTools(allTools, phase.tools);
-    const phaseSkills = selectNamedResources(config.context.skills, phase.skills, "Skill");
+    const phaseSkills = phase.name === DEFAULT_PHASE_ID ? config.context.skills : phase.skills ?? [];
     let phaseContext = {
       systemPrompt: config.context.systemPrompt,
       messages: messageManager.visible(),
@@ -2208,7 +2319,7 @@ async function withRetry(fn, options = {}) {
       }
       const delayMs = getRetryDelay(attempt, baseDelayMs, maxDelayMs);
       options.onRetry?.(attempt, error, delayMs);
-      await new Promise((resolve7) => setTimeout(resolve7, delayMs));
+      await new Promise((resolve8) => setTimeout(resolve8, delayMs));
       if (options.signal?.aborted) {
         throw lastError;
       }
@@ -2220,7 +2331,7 @@ async function executePhase(ctx) {
   const { phase, config, execution, registry, context } = ctx;
   if (phase.factory) {
     const api = createExtensionAPI(void 0, {
-      registerPhase: () => {
+      registerPhase: async () => {
       },
       registerProvider: () => {
       },
@@ -2242,7 +2353,7 @@ async function executePhase(ctx) {
           config.context.messages.push(createMessage(role, content));
         },
         getAvailableTools: () => config.context.tools.map((t) => ({ name: t.name, description: t.description })),
-        getAvailableSkills: () => config.context.skills.map((s) => ({ name: s.name, description: s.description })),
+        getAvailableSkills: () => context.skills.map((s) => ({ name: s.name, description: s.description })),
         getPhaseContent: (id) => registry.phases.get(id)?.content ?? "",
         getAvailablePhases: () => Array.from(registry.phases.keys())
       },
@@ -2420,7 +2531,7 @@ async function executeParallelPhase(config, state, registry, phase, payload, con
   const messages = [...context];
   const allTools = buildToolsWithRouting(config, availablePhases);
   const phaseTools = selectPhaseTools(allTools, phase.tools);
-  const phaseSkills = selectNamedResources(config.context.skills, phase.skills, "Skill");
+  const phaseSkills = phase.name === DEFAULT_PHASE_ID ? config.context.skills : phase.skills ?? [];
   const systemPrompt = config.context.systemPrompt;
   const phaseContext = {
     systemPrompt,
@@ -2914,6 +3025,7 @@ function snapshotConfig(config) {
     ...config.resources,
     tools: Object.freeze([...config.resources.tools]),
     skills: Object.freeze([...config.resources.skills]),
+    ...config.resources.phases ? { phases: snapshotPhaseRegistry(config.resources.phases) } : {},
     ...config.resources.resourceView ? {
       resourceView: Object.freeze({
         agents: Object.freeze([...config.resources.resourceView.agents]),
@@ -2937,6 +3049,20 @@ function snapshotConfig(config) {
   });
   return Object.freeze({ ...config, definition, resources });
 }
+function snapshotPhaseRegistry(registry) {
+  const phases = /* @__PURE__ */ new Map();
+  for (const [name, phase] of registry.phases) phases.set(name, snapshotPhase(phase));
+  return { phases, entryPhaseId: registry.entryPhaseId };
+}
+function snapshotPhase(phase) {
+  return Object.freeze({
+    ...phase,
+    ...phase.tools ? { tools: Object.freeze([...phase.tools]) } : {},
+    skills: Object.freeze((phase.skills ?? []).map((skill) => Object.freeze({ ...skill }))),
+    ...phase.input ? { input: Object.freeze({ ...phase.input }) } : {},
+    ...phase.model ? { model: Object.freeze({ ...phase.model }) } : {}
+  });
+}
 function snapshotConfiguration(config) {
   const layer = config.definition.layer;
   const definition = Object.freeze({
@@ -3436,11 +3562,11 @@ function fromLoopResult(result) {
 var MAX_BUFFERED_EVENTS = 128;
 var MAX_BUFFERED_TEXT = 64 * 1024;
 function deferred() {
-  let resolve7;
+  let resolve8;
   const promise = new Promise((done) => {
-    resolve7 = done;
+    resolve8 = done;
   });
-  return { promise, resolve: resolve7 };
+  return { promise, resolve: resolve8 };
 }
 var TransientRunEventSubscription = class {
   queue = [];
@@ -3626,6 +3752,7 @@ var HooksManager = class {
 
 // src/extensions/runner.ts
 import { execFile } from "child_process";
+import { dirname as dirname5, resolve as resolve5 } from "path";
 import {
   registerModel,
   unregisterProviderModels,
@@ -3657,9 +3784,6 @@ function createExtensionRuntime() {
   };
 }
 
-// src/extensions/runner.ts
-import { parseModelRef as parseModelRef2 } from "@rowan-agent/models";
-
 // src/extensions/event-bus.ts
 function createEventBus() {
   const listeners = /* @__PURE__ */ new Map();
@@ -3703,7 +3827,7 @@ function createEventBus() {
 
 // src/extensions/runner.ts
 async function execCommand(command, args, cwd, options) {
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     const child = execFile(
       command,
       args,
@@ -3718,7 +3842,7 @@ async function execCommand(command, args, cwd, options) {
           reject(new Error("Command was aborted"));
           return;
         }
-        resolve7({
+        resolve8({
           exitCode: typeof error?.code === "number" ? error.code : error ? 1 : 0,
           stdout: stdout ?? "",
           stderr: stderr ?? ""
@@ -3955,17 +4079,10 @@ var ExtensionRunner = class {
   adaptToPhase(reg) {
     const def = reg.definition;
     return {
-      name: def.name,
-      description: def.description,
-      tools: def.tools,
-      skills: def.skills,
-      target: def.target,
-      input: def.input,
-      run: def.run,
-      filePath: "",
-      baseDir: "",
-      content: "",
-      ...def.model ? { model: parseModelRef2(def.model) } : {}
+      ...def,
+      ...def.tools ? { tools: [...def.tools] } : {},
+      skills: def.skills ? [...def.skills] : [],
+      ...def.input ? { input: { ...def.input } } : {}
     };
   }
   // ---------------------------------------------------------------------------
@@ -4127,36 +4244,20 @@ var ExtensionRunner = class {
     });
   }
   registerPhase(extension, registration) {
-    if (typeof registration.name !== "string" || registration.name.length === 0) {
-      throw new Error(`Phase registration requires a "name" field.`);
-    }
-    const name = registration.name;
-    const description = validateDescription(registration.description);
-    const errors = validateResourceId(name, "name");
-    if (description.missing) errors.push(...description.warnings);
-    errors.push(...validateSkillReferences(registration.skills));
-    errors.push(...validatePhaseTarget(registration.target));
-    if (errors.length > 0) {
-      throw new Error(`Invalid phase registration "${name}": ${errors.join("; ")}`);
-    }
-    if (description.warnings.length > 0) {
-      warnResourceDiagnostics("phase", `extension ${extension.path}`, description.warnings);
+    if (typeof registration !== "string" || registration.length === 0) {
+      throw new Error(`Phase registration requires a directory path.`);
     }
+    return this.loadRegisteredPhase(extension, registration);
+  }
+  async loadRegisteredPhase(extension, registration) {
+    const extensionBase = extension.path.startsWith("<") ? this.cwd : dirname5(extension.path);
+    const phase = await loadPhase(resolve5(extensionBase, registration));
+    const name = phase.name;
     if (this.phases.has(name)) {
       throw new Error(`Duplicate phase name: ${name}`);
     }
-    const definition = {
-      name,
-      description: description.description,
-      run: registration.run,
-      ...registration.tools ? { tools: registration.tools.slice() } : {},
-      ...registration.skills ? { skills: registration.skills.slice() } : {},
-      ...registration.target ? { target: registration.target } : {},
-      ...registration.input ? { input: { ...registration.input } } : {},
-      ...registration.model ? { model: registration.model } : {}
-    };
     const registered = {
-      definition,
+      definition: phase,
       source: { extensionPath: extension.path }
     };
     this.phases.set(name, registered);
@@ -4215,10 +4316,10 @@ function createExtensionRunner(options) {
 }
 
 // src/extensions/loader.ts
-import { existsSync as existsSync2, readFileSync } from "fs";
-import { readdir as readdir2, readFile as readFile3, stat as stat2 } from "fs/promises";
+import { existsSync as existsSync3, readFileSync } from "fs";
+import { readdir as readdir3, readFile as readFile3, stat as stat2 } from "fs/promises";
 import { fileURLToPath } from "url";
-import { basename as basename3, dirname as dirname4, extname as extname2, join as join2, resolve as resolve4 } from "path";
+import { basename as basename3, dirname as dirname6, extname as extname2, join as join3, resolve as resolve6 } from "path";
 import { createJiti } from "jiti";
 function isExtensionFile(path) {
   const extension = extname2(path).toLowerCase();
@@ -4228,8 +4329,8 @@ function isSyntheticPath(path) {
   return path.startsWith("<") && path.endsWith(">");
 }
 function readManifestSync(dir) {
-  const manifestPath = join2(dir, "package.json");
-  if (!existsSync2(manifestPath)) {
+  const manifestPath = join3(dir, "package.json");
+  if (!existsSync3(manifestPath)) {
     return void 0;
   }
   try {
@@ -4238,8 +4339,7 @@ function readManifestSync(dir) {
     const rowan = pkg.rowan;
     if (!rowan) return void 0;
     return {
-      entry: rowan.extensions?.[0],
-      phase: rowan.phase
+      entry: rowan.extensions?.[0]
     };
   } catch {
     return void 0;
@@ -4251,7 +4351,7 @@ function jitiAliases() {
     return {};
   }
   const agentSourcePath = fileURLToPath(new URL("../index.ts", moduleUrl));
-  if (!existsSync2(agentSourcePath)) {
+  if (!existsSync3(agentSourcePath)) {
     return {};
   }
   return { "@rowan-agent/agent": agentSourcePath };
@@ -4272,28 +4372,28 @@ async function loadExtensionModule(extensionPath) {
   return typeof module === "function" ? module : void 0;
 }
 async function readPackageManifest(path) {
-  if (!existsSync2(path)) {
+  if (!existsSync3(path)) {
     return void 0;
   }
   const content = await readFile3(path, "utf8");
   return JSON.parse(content);
 }
 async function resolveExtensionEntries(dir) {
-  const manifest = await readPackageManifest(join2(dir, "package.json"));
+  const manifest = await readPackageManifest(join3(dir, "package.json"));
   const declared = manifest?.rowan?.extensions;
   if (declared && declared.length > 0) {
-    return declared.map((entry) => resolve4(dir, entry));
+    return declared.map((entry) => resolve6(dir, entry));
   }
   for (const name of ["index.ts", "index.js"]) {
-    const entry = join2(dir, name);
-    if (existsSync2(entry)) {
+    const entry = join3(dir, name);
+    if (existsSync3(entry)) {
       return [entry];
     }
   }
   return void 0;
 }
 async function discoverExtensionsInDir(dir) {
-  const entries = await readdir2(dir, { withFileTypes: true }).catch((error) => {
+  const entries = await readdir3(dir, { withFileTypes: true }).catch((error) => {
     if (error.code === "ENOENT") {
       return [];
     }
@@ -4301,7 +4401,7 @@ async function discoverExtensionsInDir(dir) {
   });
   const paths = [];
   for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
-    const entryPath = join2(dir, entry.name);
+    const entryPath = join3(dir, entry.name);
     if ((entry.isFile() || entry.isSymbolicLink()) && isExtensionFile(entry.name)) {
       paths.push(entryPath);
       continue;
@@ -4319,10 +4419,10 @@ async function discoverExtensionsInDir(dir) {
   return paths;
 }
 function loadExtensionFromFactory(factory, cwd, extensionPath = "<inline>") {
-  const resolvedCwd = resolve4(cwd);
-  const resolvedPath = isSyntheticPath(extensionPath) ? extensionPath : resolve4(resolvedCwd, extensionPath);
-  const name = isSyntheticPath(extensionPath) ? extensionPath : basename3(dirname4(resolvedPath)) || "unknown";
-  const manifestDir = isSyntheticPath(extensionPath) ? resolvedCwd : dirname4(resolvedPath);
+  const resolvedCwd = resolve6(cwd);
+  const resolvedPath = isSyntheticPath(extensionPath) ? extensionPath : resolve6(resolvedCwd, extensionPath);
+  const name = isSyntheticPath(extensionPath) ? extensionPath : basename3(dirname6(resolvedPath)) || "unknown";
+  const manifestDir = isSyntheticPath(extensionPath) ? resolvedCwd : dirname6(resolvedPath);
   const manifest = readManifestSync(manifestDir);
   return {
     path: resolvedPath,
@@ -4334,9 +4434,9 @@ function loadExtensionFromFactory(factory, cwd, extensionPath = "<inline>") {
 async function loadExtensions(paths, cwd) {
   const extensions = [];
   const errors = [];
-  const resolvedCwd = resolve4(cwd);
+  const resolvedCwd = resolve6(cwd);
   for (const path of paths) {
-    const resolvedPath = resolve4(resolvedCwd, path);
+    const resolvedPath = resolve6(resolvedCwd, path);
     try {
       const factory = await loadExtensionModule(resolvedPath);
       if (!factory) {
@@ -4357,10 +4457,10 @@ async function loadExtensions(paths, cwd) {
   return { extensions, errors };
 }
 async function loadExtensionsFromPath(path) {
-  const resolvedPath = resolve4(path);
+  const resolvedPath = resolve6(path);
   const info = await stat2(resolvedPath);
   if (!info.isDirectory()) {
-    return loadExtensions([resolvedPath], dirname4(resolvedPath));
+    return loadExtensions([resolvedPath], dirname6(resolvedPath));
   }
   const entries = await resolveExtensionEntries(resolvedPath) ?? await discoverExtensionsInDir(resolvedPath);
   return loadExtensions(entries, resolvedPath);
@@ -4368,87 +4468,7 @@ async function loadExtensionsFromPath(path) {
 
 // src/runtime/resource-registry.ts
 import { stat as stat3, readdir as readdir4 } from "fs/promises";
-import { join as join4, resolve as resolve6 } from "path";
-
-// src/harness/skills.ts
-import { existsSync as existsSync3, statSync as statSync2 } from "fs";
-import { readdir as readdir3 } from "fs/promises";
-import { dirname as dirname5, join as join3, resolve as resolve5 } from "path";
-var SKILL_MARKER = "SKILL.md";
-function resolveSkillPath(input) {
-  const resolved = resolve5(input);
-  return existsSync3(resolved) && statSync2(resolved).isDirectory() ? join3(resolved, SKILL_MARKER) : resolved;
-}
-async function loadSkill(path) {
-  const resolved = resolveSkillPath(path);
-  let loaded;
-  try {
-    loaded = await loadMarkdown(resolved);
-  } catch (error) {
-    if (!(error instanceof FrontmatterParseError)) throw error;
-    warnResourceDiagnostics("skill", resolved, [`frontmatter could not be parsed: ${error.message}`]);
-    throw new ResourceMetadataError("parse_failed", error.message);
-  }
-  const { frontmatter, body } = loaded;
-  const metadata = frontmatter;
-  const id = inferResourceName(resolved, SKILL_MARKER);
-  const frontmatterName = typeof metadata.name === "string" ? metadata.name : void 0;
-  const name = frontmatterName || id;
-  const description = validateDescription(metadata.description);
-  const diagnostics = validateResourceId(id);
-  if (frontmatterName && frontmatterName !== id) {
-    diagnostics.push(...validateResourceName(frontmatterName, id));
-  }
-  diagnostics.push(...description.warnings);
-  warnResourceDiagnostics("skill", resolved, diagnostics);
-  if (description.missing) {
-    throw new ResourceMetadataError("invalid_metadata", "description is required");
-  }
-  return {
-    name,
-    description: description.description,
-    filePath: resolved,
-    baseDir: dirname5(resolved),
-    content: body,
-    disableModelInvocation: metadata["disable-model-invocation"] === true
-  };
-}
-async function loadSkills(targetPath) {
-  const skillsDir = resolve5(targetPath);
-  if (existsSync3(skillsDir) && statSync2(skillsDir).isFile()) {
-    try {
-      return [await loadSkill(skillsDir)];
-    } catch (error) {
-      if (error instanceof ResourceMetadataError) return [];
-      throw error;
-    }
-  }
-  if (existsSync3(join3(skillsDir, SKILL_MARKER))) {
-    try {
-      return [await loadSkill(skillsDir)];
-    } catch (error) {
-      if (error instanceof ResourceMetadataError) return [];
-      throw error;
-    }
-  }
-  const entries = await readdir3(skillsDir, { withFileTypes: true });
-  const skills = [];
-  for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
-    if (!entry.isDirectory()) continue;
-    const skillFile = join3(skillsDir, entry.name, SKILL_MARKER);
-    if (!existsSync3(skillFile)) continue;
-    try {
-      const skill = await loadSkill(skillFile);
-      skills.push(skill);
-    } catch (error) {
-      if (error instanceof ResourceMetadataError) continue;
-      console.warn(`Failed to load skill "${entry.name}":`, error);
-    }
-  }
-  return skills;
-}
-
-// src/runtime/resource-registry.ts
+import { join as join4, resolve as resolve7 } from "path";
 var ResourceRegistryError = class extends Error {
   code;
   constructor(code, message) {
@@ -4592,11 +4612,12 @@ var ResourceRegistry = class {
       names.add(value.name);
     }
     const revision = this.nextRevision(kind, sourceId);
+    const snapshottedValues = values.map((value) => snapshotResourceValue(kind, value));
     const record = {
       kind,
       sourceId,
       revision,
-      values: Object.freeze([...values])
+      values: Object.freeze(snapshottedValues)
     };
     let bySource = this.sources.get(kind);
     if (!bySource) {
@@ -4666,6 +4687,18 @@ var ResourceRegistry = class {
     return `${kind}:${sourceId}:${this.revisionSequence}`;
   }
 };
+function snapshotResourceValue(kind, value) {
+  if (kind !== "phase") return value;
+  const phase = value;
+  const snapshot = {
+    ...phase,
+    ...phase.tools ? { tools: Object.freeze([...phase.tools]) } : {},
+    skills: Object.freeze((phase.skills ?? []).map((skill) => Object.freeze({ ...skill }))),
+    ...phase.input ? { input: Object.freeze({ ...phase.input }) } : {},
+    ...phase.model ? { model: Object.freeze({ ...phase.model }) } : {}
+  };
+  return Object.freeze(snapshot);
+}
 function assertSourceId(sourceId) {
   if (typeof sourceId !== "string" || !SOURCE_ID.test(sourceId)) {
     throw new ResourceRegistryError("invalid_source_id", `Invalid resource source "${String(sourceId)}".`);
@@ -4687,7 +4720,7 @@ function isImplicitCoreName(kind, name) {
   return kind === "tool" && name === "route" || kind === "phase" && name === "default";
 }
 async function loadDirectoryValues(kind, directory, sourceId) {
-  const root = resolve6(directory);
+  const root = resolve7(directory);
   let rootInfo;
   try {
     rootInfo = await stat3(root);
@@ -5009,9 +5042,8 @@ function intersectPhaseSelection(parent, layer) {
 }
 function resolvePhases(candidates, selection) {
   const selected = selectNamedResources(candidates, selection?.phaseIds, "Phase");
-  if (selected.length === 0 && selection === void 0) return void 0;
   const entryPhaseId = selection?.entryPhaseId ?? null;
-  if (entryPhaseId !== null && !selected.some(({ name }) => name === entryPhaseId)) {
+  if (entryPhaseId !== null && entryPhaseId !== DEFAULT_PHASE_ID && !selected.some(({ name }) => name === entryPhaseId)) {
     console.warn(`Phase entry "${entryPhaseId}" is not available and will be skipped.`);
     return { phases: new Map(selected.map((phase) => [phase.name, phase])), entryPhaseId: null };
   }
@@ -5626,7 +5658,7 @@ function boundaryFromSnapshot(snapshot) {
   }
 }
 function delay(ms) {
-  return new Promise((resolve7) => setTimeout(resolve7, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 function normalizePhaseRegistry(registry) {
   if (registry?.phases.has(DEFAULT_PHASE_ID) && registry.phases.get(DEFAULT_PHASE_ID)?.filePath !== "") {
@@ -5653,13 +5685,13 @@ function toJsonValue(value) {
   return value;
 }
 function deferred2() {
-  let resolve7;
+  let resolve8;
   let reject;
   const promise = new Promise((res, rej) => {
-    resolve7 = (value) => res(value);
+    resolve8 = (value) => res(value);
     reject = rej;
   });
-  return { promise, resolve: resolve7, reject };
+  return { promise, resolve: resolve8, reject };
 }
 
 // src/runtime/durable-store.ts
@@ -7137,7 +7169,9 @@ export {
   createCoreTools2 as createCoreTools,
   isRuntimeError,
   loadExtensionsFromPath as loadExtensions,
+  loadPhase,
   loadPhases,
+  loadSkill,
   loadSkills,
   materializeConfigurationSnapshot,
   parseAgentDefinition,

package/package.json

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