@rowan-agent/agent 0.8.4 → 0.8.5

package/README.md

@@ -21,8 +21,12 @@ const agentId = await runtime.createAgent({
   identity: "example:v1", // Stable config snapshot identity, not the Agent ID
   model: { provider: "openai", id: "gpt-4o" },
   stream,
-  context: {
-    systemPrompt: "You are helpful.",
+  definition: {
+    name: "workspace-assistant",
+    description: "Assist with the current workspace.",
+    content: "You are helpful.",
+  },
+  resources: {
     tools: createCoreTools({ root: process.cwd() }),
     skills: [],
   },
@@ -68,7 +72,8 @@ lifecycles, and Owner fencing.
 
 ## Tool lifecycle
 
-Tools are supplied through `AgentConfig.context.tools` and persist through:
+Tools are supplied as `AgentConfig.resources.tools`, selected by the
+Definition, and persist through:
 
 `pending → running → completed | failed | indeterminate`
 
@@ -101,5 +106,7 @@ checkpoints; transient events never enter the Durable Store.
 
 ## Resources
 
-`loadSkills()`, `loadPhases()`, and `loadExtensions()` load workspace resources.
-Pass the resulting resources through `AgentConfig.context` or `extensions`.
+`loadSkills()`, `loadPhases()`, and `loadExtensions()` load Resource Candidates.
+Pass them through `AgentConfig.resources`; the Definition's optional name lists
+select from them after Extension assembly. Omitted lists inherit all candidates,
+`[]` selects none, and missing names warn and are skipped.

package/dist/index.d.ts

@@ -865,6 +865,20 @@ type ToolProgress = Readonly<{
 }>;
 type RunEvent = DurableRunEvent | MessageDelta | ToolProgress;
 
+type AgentDefinition = Readonly<{
+    name: string;
+    description: string;
+    content: string;
+    tools?: readonly string[];
+    skills?: readonly string[];
+    phases?: readonly string[];
+    extensions?: readonly string[];
+    entryPhase?: string;
+    model?: ModelRef;
+}>;
+/** Parse one Markdown definition using the same frontmatter vocabulary as Phase resources. */
+declare function parseAgentDefinition(raw: string): AgentDefinition;
+
 type UserInput = string | Readonly<{
     content: UserContent;
     metadata?: Metadata;
@@ -903,17 +917,17 @@ type AfterToolCall = (input: Readonly<{
     context: ToolInvocationContext;
     signal: AbortSignal;
 }>) => ToolExecutionResult | Promise<ToolExecutionResult>;
-type AgentDefinitionContext = Readonly<{
-    systemPrompt: string;
+type AgentResources = Readonly<{
     tools: readonly Tool[];
     skills: readonly Skill[];
     phases?: PhaseRegistry;
+    extensions?: readonly LoadedExtension[];
 }>;
 type AgentConfig = Readonly<{
     identity: string;
-    context: AgentDefinitionContext;
+    definition: AgentDefinition;
+    resources: AgentResources;
     cwd?: string;
-    extensions?: readonly LoadedExtension[];
     maxAttempts?: number;
     beforeToolCall?: BeforeToolCall;
     afterToolCall?: AfterToolCall;
@@ -1806,6 +1820,17 @@ declare function loadExtensionsFromPath(path: string): Promise<{
     }>;
 }>;
 
+/** Parsed frontmatter result */
+interface FrontmatterResult<T = Record<string, unknown>> {
+    frontmatter: T;
+    body: string;
+}
+/**
+ * Parse YAML frontmatter from markdown content.
+ * Parse YAML frontmatter and return the markdown body after the closing delimiter.
+ */
+declare function parseFrontmatter<T = Record<string, unknown>>(raw: string): FrontmatterResult<T>;
+
 declare function createCoreTools(input?: CoreToolContext): Tool[];
 
-export { type AfterToolCall, type AgentConfig, type AgentDefinitionContext, type AgentId, type AgentListCursor, type AgentRecord, type AgentRun, AgentRuntime, type AgentRuntimeOptions, type AgentSummary, type AnyRuntimeError, type AssistantContent, type AssistantMessage, type BeforeToolCall, type ConfigProvider, type ConfigPutResult, type ConfigResolution, type ConfigToken, type CoreToolContext, type DurableConsumer, type DurableRunEvent, type DurableStore, type DurableToolResult, type EventCursor, type EventId, type ExecutionCheckpoint, type ExecutionId, type ExecutionToken, type ExtensionAPI, type ExtensionFactory, type HookEvent, type HookEventType, type HookHandler, InMemoryConfigProvider, InMemoryStore, type InputRequest, type InputRequestId, type InputRequiredCommit, type JsonObject, type JsonPrimitive, type JsonValue, type LoadExtensionsResult, 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 PhaseExecutionIdentity, type PhaseInvocation, type PhaseOutput, type PhaseRegistry, type PhaseState, type RunBoundary, type RunClaim, type RunEvent, type RunFailure, type RunId, type RunListCursor, type RunRecord, type RunSnapshot, type RunState, type RunStateChanged, type RunSummary, RuntimeError, type RuntimeErrorCode, type RuntimeErrorDetails, type Skill, SqliteStore, type TextContent, type ThinkingContent, type Tool, type ToolCallId, type ToolCallSnapshot, type ToolCallState, 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 };
+export { type AfterToolCall, type AgentConfig, 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 CoreToolContext, type DurableConsumer, type DurableRunEvent, type DurableStore, type DurableToolResult, type EventCursor, type EventId, type ExecutionCheckpoint, type ExecutionId, type ExecutionToken, type ExtensionAPI, type ExtensionFactory, 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 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 PhaseExecutionIdentity, type PhaseInvocation, type PhaseOutput, type PhaseRegistry, type PhaseState, type RunBoundary, type RunClaim, type RunEvent, type RunFailure, type RunId, type RunListCursor, type RunRecord, type RunSnapshot, type RunState, type RunStateChanged, type RunSummary, RuntimeError, type RuntimeErrorCode, type RuntimeErrorDetails, type Skill, SqliteStore, type TextContent, type ThinkingContent, type Tool, type ToolCallId, type ToolCallSnapshot, type ToolCallState, 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, parseAgentDefinition, parseFrontmatter };

package/dist/index.js

@@ -1015,7 +1015,92 @@ function createExtensionAPI(hooks, options, runtime, eventBus) {
 import { existsSync, statSync } from "fs";
 import { readdir } from "fs/promises";
 import { dirname as dirname3, join, resolve as resolve3 } from "path";
+
+// src/harness/definitions.ts
 import { parseModelRef } from "@rowan-agent/models";
+function assertAgentDefinition(value) {
+  if (!isRecord(value)) throw new TypeError("config.definition is invalid");
+  requiredString(value.name, "definition.name");
+  requiredString(value.description, "definition.description");
+  requiredString(value.content, "definition.content");
+  optionalStringList(value.tools, "definition.tools");
+  optionalStringList(value.skills, "definition.skills");
+  optionalStringList(value.phases, "definition.phases");
+  optionalStringList(value.extensions, "definition.extensions");
+  optionalString(value.entryPhase, "definition.entryPhase");
+  if (value.model !== void 0) {
+    if (!isRecord(value.model) || typeof value.model.provider !== "string" || value.model.provider.trim() === "" || typeof value.model.id !== "string" || value.model.id.trim() === "") {
+      throw new TypeError("definition.model must be a valid model reference");
+    }
+  }
+}
+function parseAgentDefinition(raw) {
+  const { frontmatter, body } = parseFrontmatter(raw);
+  return normalizeAgentDefinition(frontmatter, body);
+}
+function normalizeAgentDefinition(frontmatter, content, options = {}) {
+  const name = frontmatter.name === void 0 && options.fallbackName ? options.fallbackName : requiredString(frontmatter.name, "name");
+  const description = requiredString(frontmatter.description, "description");
+  const normalizedContent = requiredString(content, "content");
+  const tools = optionalStringList(frontmatter.tools, "tools");
+  const skills = optionalStringList(frontmatter.skills, "skills");
+  const phases = optionalStringList(frontmatter.phases, "phases");
+  const extensions = optionalStringList(frontmatter.extensions, "extensions");
+  const entryPhase = optionalString(frontmatter.entryPhase, "entryPhase");
+  const model = optionalModel(frontmatter.model);
+  return {
+    name,
+    description,
+    content: normalizedContent,
+    ...tools ? { tools } : {},
+    ...skills ? { skills } : {},
+    ...phases ? { phases } : {},
+    ...extensions ? { extensions } : {},
+    ...entryPhase ? { entryPhase } : {},
+    ...model ? { model } : {}
+  };
+}
+function requiredString(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${field} is required`);
+  }
+  return value.trim();
+}
+function optionalString(value, field) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+function optionalStringList(value, field) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value)) throw new TypeError(`${field} must be an array of strings`);
+  const names = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, item] of value.entries()) {
+    if (typeof item !== "string" || item.trim() === "") {
+      throw new TypeError(`${field}[${index}] must be a non-empty string`);
+    }
+    const name = item.trim();
+    if (seen.has(name)) continue;
+    seen.add(name);
+    names.push(name);
+  }
+  return names;
+}
+function optionalModel(value) {
+  const source = optionalString(value, "model");
+  if (!source) return void 0;
+  const model = parseModelRef(source);
+  if (!model || model.provider.trim() === "" || model.id.trim() === "") {
+    throw new TypeError("model must be a valid model reference");
+  }
+  return model;
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 
 // src/harness/resource-validation.ts
 var MAX_RESOURCE_ID_LENGTH = 64;
@@ -1113,8 +1198,16 @@ async function loadPhase(targetPath) {
   const { frontmatter, body } = loaded;
   const metadata = frontmatter;
   const frontmatterName = typeof metadata.name === "string" ? metadata.name : void 0;
-  const name = frontmatterName || directoryName;
-  const description = validateDescription(metadata.description);
+  let definition;
+  try {
+    definition = normalizeAgentDefinition(metadata, body, { fallbackName: directoryName });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    warnResourceDiagnostics("phase", resolved, [message]);
+    throw new ResourceMetadataError("invalid_metadata", message);
+  }
+  const name = definition.name;
+  const description = validateDescription(definition.description);
   const diagnostics = validateResourceId(directoryName);
   if (frontmatterName && frontmatterName !== directoryName) {
     diagnostics.push(...validateResourceName(frontmatterName, directoryName));
@@ -1123,22 +1216,19 @@ async function loadPhase(targetPath) {
   diagnostics.push(...validateSkillReferences(metadata.skills));
   diagnostics.push(...validatePhaseTarget(metadata.target));
   warnResourceDiagnostics("phase", resolved, diagnostics);
-  if (description.missing) {
-    throw new ResourceMetadataError("invalid_metadata", "description is required");
-  }
   const baseDir = dirname3(resolved);
   const phase = {
     name,
     description: description.description,
-    tools: metadata.tools,
-    skills: metadata.skills,
+    tools: definition.tools ? [...definition.tools] : void 0,
+    skills: definition.skills ? [...definition.skills] : void 0,
     target: metadata.target,
     input: metadata.input,
     isolated: metadata.isolated,
     filePath: resolved,
     baseDir,
-    content: body,
-    model: parseModelRef(metadata.model)
+    content: definition.content,
+    model: definition.model
   };
   const codePath = await discoverPhaseCode(baseDir);
   if (codePath) {
@@ -1236,6 +1326,31 @@ function createDefaultPhase() {
   };
 }
 
+// src/harness/resource-selection.ts
+function selectNamedResources(candidates, names, kind) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    if (byName.has(candidate.name)) {
+      throw new TypeError(`Duplicate ${kind} candidate "${candidate.name}".`);
+    }
+    byName.set(candidate.name, candidate);
+  }
+  if (names === void 0) return [...candidates];
+  const selected = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    if (seen.has(name)) continue;
+    seen.add(name);
+    const candidate = byName.get(name);
+    if (!candidate) {
+      console.warn(`${kind} "${name}" is not available and will be skipped.`);
+      continue;
+    }
+    selected.push(candidate);
+  }
+  return selected;
+}
+
 // src/harness/context/system-prompt.ts
 function buildSystemPrompt(options) {
   const { systemPrompt, promptGuidelines, appendSystemPrompt, tools, skills } = options;
@@ -1763,8 +1878,8 @@ async function runPhaseLoop(config, state, registry) {
     const messageManager = createMessageManager(config.context, config.onMessage, config.onMessageDelta);
     const toolExecutionManager = createToolExecutionManager();
     const execution = createPhaseExecution(config, state, phase, messageManager, toolExecutionManager, registry);
-    const phaseTools = phase.tools ? allTools.filter((t) => t.name === PhaseRouteTool || phase.tools.includes(t.name)) : allTools;
-    const phaseSkills = phase.skills ? config.context.skills.filter((s) => phase.skills.includes(s.name)) : config.context.skills;
+    const phaseTools = selectPhaseTools(allTools, phase.tools);
+    const phaseSkills = selectNamedResources(config.context.skills, phase.skills, "Skill");
     let phaseContext = {
       systemPrompt: config.context.systemPrompt,
       messages: messageManager.visible(),
@@ -2254,8 +2369,8 @@ function createPhaseExecution(config, state, phase, messageManager, toolExecutio
 async function executeParallelPhase(config, state, registry, phase, payload, context, availablePhases, instanceId, groupId, index, count, sourcePhaseId) {
   const messages = [...context];
   const allTools = buildToolsWithRouting(config, availablePhases);
-  const phaseTools = phase.tools ? allTools.filter((t) => t.name === PhaseRouteTool || phase.tools.includes(t.name)) : allTools;
-  const phaseSkills = phase.skills ? config.context.skills.filter((s) => phase.skills.includes(s.name)) : config.context.skills;
+  const phaseTools = selectPhaseTools(allTools, phase.tools);
+  const phaseSkills = selectNamedResources(config.context.skills, phase.skills, "Skill");
   const systemPrompt = config.context.systemPrompt;
   const phaseContext = {
     systemPrompt,
@@ -2293,6 +2408,11 @@ async function executeParallelPhase(config, state, registry, phase, payload, con
   const resultPayload = decision?.decision[0]?.payload !== void 0 ? normalizePayload(decision.decision[0].payload) : output.payload;
   return { instanceId, phaseId: phase.name, payload: resultPayload, content: output.message };
 }
+function selectPhaseTools(candidates, names) {
+  const routing = candidates.filter(({ name }) => name === PhaseRouteTool);
+  const ordinary = candidates.filter(({ name }) => name !== PhaseRouteTool);
+  return [...selectNamedResources(ordinary, names, "Tool"), ...routing];
+}
 async function waitForBackgroundTasks(backgroundTasks) {
   const entries = Array.from(backgroundTasks.entries());
   const results = await Promise.allSettled(entries.map(([, t]) => t.promise));
@@ -2523,29 +2643,29 @@ function createMetrics() {
     startedAtMs: Date.now()
   };
 }
-function isRecord(value) {
+function isRecord2(value) {
   return value !== null && typeof value === "object" && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
 }
 function isCheckpointData(value) {
-  if (!isRecord(value) || typeof value.currentPhase !== "string" || !Number.isInteger(value.attempt)) return false;
+  if (!isRecord2(value) || typeof value.currentPhase !== "string" || !Number.isInteger(value.attempt)) return false;
   if (!isMetrics(value.metrics)) return false;
   if (value.continuation !== void 0 && !isContinuation(value.continuation)) return false;
   return true;
 }
 function isMetrics(value) {
-  if (!isRecord(value)) return false;
-  return Number.isInteger(value.iterations) && Array.isArray(value.phaseTransitions) && value.phaseTransitions.every((transition) => isRecord(transition) && typeof transition.from === "string" && typeof transition.to === "string" && typeof transition.ts === "string") && Number.isInteger(value.compactionCount) && Number.isInteger(value.retryCount) && typeof value.startedAt === "string" && Number.isFinite(value.startedAtMs) && (value.endedAt === void 0 || typeof value.endedAt === "string") && (value.durationMs === void 0 || Number.isFinite(value.durationMs));
+  if (!isRecord2(value)) return false;
+  return Number.isInteger(value.iterations) && Array.isArray(value.phaseTransitions) && value.phaseTransitions.every((transition) => isRecord2(transition) && typeof transition.from === "string" && typeof transition.to === "string" && typeof transition.ts === "string") && Number.isInteger(value.compactionCount) && Number.isInteger(value.retryCount) && typeof value.startedAt === "string" && Number.isFinite(value.startedAtMs) && (value.endedAt === void 0 || typeof value.endedAt === "string") && (value.durationMs === void 0 || Number.isFinite(value.durationMs));
 }
 function isContinuation(value) {
-  if (!isRecord(value) || typeof value.isContinuing !== "boolean" || !Array.isArray(value.previousResults)) return false;
+  if (!isRecord2(value) || typeof value.isContinuing !== "boolean" || !Array.isArray(value.previousResults)) return false;
   if (value.previousPayload !== void 0 && !isJsonValue(value.previousPayload)) return false;
-  return value.previousResults.every((result) => isRecord(result) && typeof result.name === "string" && (result.output === void 0 || isJsonValue(result.output))) && (value.pendingInstruction === void 0 || typeof value.pendingInstruction === "string") && (value.previousPhaseMessageId === void 0 || typeof value.previousPhaseMessageId === "string");
+  return value.previousResults.every((result) => isRecord2(result) && typeof result.name === "string" && (result.output === void 0 || isJsonValue(result.output))) && (value.pendingInstruction === void 0 || typeof value.pendingInstruction === "string") && (value.previousPhaseMessageId === void 0 || typeof value.previousPhaseMessageId === "string");
 }
 
 // src/runtime/contracts.ts
 var METADATA_LIMIT = 64 * 1024;
 var IDENTITY_LIMIT = 256;
-function isRecord2(value) {
+function isRecord3(value) {
   if (value === null || typeof value !== "object") return false;
   const prototype = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
@@ -2554,7 +2674,7 @@ function hasOnlyKeys(value, allowed) {
   return Reflect.ownKeys(value).every((key) => typeof key === "string" && allowed.includes(key));
 }
 function isMetadata(value) {
-  if (!isRecord2(value) || !isJsonValue(value)) return false;
+  if (!isRecord3(value) || !isJsonValue(value)) return false;
   try {
     assertUtf8ByteLimit(canonicalJson(value), METADATA_LIMIT, "metadata");
     return true;
@@ -2566,23 +2686,23 @@ function assertMetadata(value, argument) {
   if (!isMetadata(value)) throw new TypeError(`${argument} must be a JSON-safe metadata object`);
 }
 function isText(value) {
-  return isRecord2(value) && value.type === "text" && typeof value.text === "string";
+  return isRecord3(value) && value.type === "text" && typeof value.text === "string";
 }
 function isImage(value) {
-  return isRecord2(value) && value.type === "image" && typeof value.data === "string" && typeof value.mimeType === "string";
+  return isRecord3(value) && value.type === "image" && typeof value.data === "string" && typeof value.mimeType === "string";
 }
 function isUserContent(value) {
   return typeof value === "string" || Array.isArray(value) && value.every((part) => isText(part) || isImage(part));
 }
 function normalizeUserInput(input) {
   const normalized = typeof input === "string" ? { content: input } : input;
-  if (!isRecord2(normalized) || !hasOnlyKeys(normalized, ["content", "metadata"]) || !isUserContent(normalized.content)) throw new TypeError("input must contain only valid UserContent");
+  if (!isRecord3(normalized) || !hasOnlyKeys(normalized, ["content", "metadata"]) || !isUserContent(normalized.content)) throw new TypeError("input must contain only valid UserContent");
   if (normalized.metadata !== void 0) assertMetadata(normalized.metadata, "input.metadata");
   assertJsonValue(normalized, "input");
   return normalized;
 }
 function isToolResult(value) {
-  if (!isRecord2(value) || !isJsonValue(value.content) || typeof value.ok !== "boolean") return false;
+  if (!isRecord3(value) || !isJsonValue(value.content) || typeof value.ok !== "boolean") return false;
   const expected = value.ok ? ["content", "ok"] : ["content", "error", "ok"];
   if (JSON.stringify(Object.keys(value).sort()) !== JSON.stringify(expected)) return false;
   return value.ok || typeof value.error === "string";
@@ -2590,8 +2710,11 @@ function isToolResult(value) {
 function assertAgentConfig(config) {
   if (typeof config.identity !== "string" || config.identity.length === 0) throw new TypeError("config.identity must be non-empty");
   assertUtf8ByteLimit(config.identity, IDENTITY_LIMIT, "config.identity");
-  if (!config.context || typeof config.context.systemPrompt !== "string") throw new TypeError("config.context is invalid");
-  for (const tool of config.context.tools) projectToolDefinition(tool);
+  assertAgentDefinition(config.definition);
+  if (!config.resources || !Array.isArray(config.resources.tools) || !Array.isArray(config.resources.skills)) {
+    throw new TypeError("config.resources is invalid");
+  }
+  for (const tool of config.resources.tools) projectToolDefinition(tool);
 }
 function assertToolExecutionResult(value) {
   if (!isToolResult(value)) throw new TypeError("Tool result must be JSON-safe and contain no Runtime identity");
@@ -2599,7 +2722,7 @@ function assertToolExecutionResult(value) {
 function projectToolDefinition(tool) {
   if (typeof tool.name !== "string" || tool.name.length === 0 || typeof tool.description !== "string") throw new TypeError("Tool definition is invalid");
   assertJsonValue(tool.parameters, "tool.parameters");
-  if (!isRecord2(tool.parameters)) throw new TypeError("tool.parameters must be a JSON object");
+  if (!isRecord3(tool.parameters)) throw new TypeError("tool.parameters must be a JSON object");
   return { name: tool.name, description: tool.description, parameters: JSON.parse(canonicalJson(tool.parameters)) };
 }
 
@@ -2666,7 +2789,7 @@ function brandConfigToken(raw) {
   return raw;
 }
 function validateConfigResolution(agentId, value) {
-  if (!isRecord3(value) || typeof value.kind !== "string") {
+  if (!isRecord4(value) || typeof value.kind !== "string") {
     throw new Error(`Config Provider returned an invalid resolution for Agent ${agentId}.`);
   }
   if (value.kind === "deferred") {
@@ -2679,18 +2802,26 @@ function validateConfigResolution(agentId, value) {
     };
   }
   if (value.kind === "unavailable" && typeof value.reason === "string") return { kind: "unavailable", reason: value.reason };
-  if (value.kind === "available" && isRecord3(value.config) && typeof value.config.identity === "string") {
+  if (value.kind === "available" && isRecord4(value.config) && typeof value.config.identity === "string") {
     return { kind: "available", config: value.config };
   }
   throw new Error(`Config Provider returned an invalid resolution for Agent ${agentId}.`);
 }
 function snapshotConfig(config) {
-  const context = Object.freeze({
-    ...config.context,
-    tools: Object.freeze([...config.context.tools]),
-    skills: Object.freeze([...config.context.skills])
+  const definition = Object.freeze({
+    ...config.definition,
+    ...config.definition.tools ? { tools: Object.freeze([...config.definition.tools]) } : {},
+    ...config.definition.skills ? { skills: Object.freeze([...config.definition.skills]) } : {},
+    ...config.definition.phases ? { phases: Object.freeze([...config.definition.phases]) } : {},
+    ...config.definition.extensions ? { extensions: Object.freeze([...config.definition.extensions]) } : {}
   });
-  return Object.freeze({ ...config, context });
+  const resources = Object.freeze({
+    ...config.resources,
+    tools: Object.freeze([...config.resources.tools]),
+    skills: Object.freeze([...config.resources.skills]),
+    ...config.resources.extensions ? { extensions: Object.freeze([...config.resources.extensions]) } : {}
+  });
+  return Object.freeze({ ...config, definition, resources });
 }
 function assertConfigIdentity(identity) {
   if (typeof identity !== "string" || identity.length === 0) throw new TypeError("config.identity must be non-empty");
@@ -2705,7 +2836,7 @@ function throwIfAborted(signal) {
   error.name = "AbortError";
   throw error;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return value !== null && typeof value === "object";
 }
 
@@ -3628,12 +3759,19 @@ function createExtensionRunner(options) {
 
 // src/runtime/extensions.ts
 async function assembleExtensions(config) {
-  if (!config.extensions?.length) return { context: config.context };
+  const selectedExtensions = selectNamedResources(
+    config.resources.extensions ?? [],
+    config.definition.extensions,
+    "Extension"
+  );
+  if (selectedExtensions.length === 0) {
+    return { context: resolveDefinitionContext(config) };
+  }
   const runner = createExtensionRunner({ cwd: config.cwd });
-  await runner.loadExtensions([...config.extensions]);
+  await runner.loadExtensions(selectedExtensions);
   runner.bind();
   const extensionTools = runner.getAllRegisteredTools().map(adaptExtensionTool);
-  const tools = [...config.context.tools];
+  const tools = [...config.resources.tools];
   const names = new Set(tools.map((tool) => tool.name));
   for (const tool of extensionTools) {
     if (names.has(tool.name)) throw new TypeError(`Extension Tool collides with Context Tool "${tool.name}"`);
@@ -3641,9 +3779,10 @@ async function assembleExtensions(config) {
     tools.push(tool);
   }
   const extensionPhases = runner.createPhaseRegistry({ entryPhaseId: null });
-  const phases = mergePhases(config.context.phases, extensionPhases);
+  const phases = mergePhases(config.resources.phases, extensionPhases);
+  const context = resolveDefinitionContext(config, { tools, phases });
   return {
-    context: { ...config.context, tools, ...phases ? { phases } : {} },
+    context,
     beforePhase: (phaseId, input) => runner.emitBeforePhase(phaseId, input),
     afterPhase: (phaseId, output) => runner.emitAfterPhase(phaseId, output),
     beforePrompt: (phaseId, input) => runner.emitBeforePrompt(phaseId, input),
@@ -3657,11 +3796,41 @@ async function assembleExtensions(config) {
       const result = await runner.emitAfterToolCall(tool, toLoopResult(input.result, input.context.toolCallId, input.tool.name));
       return fromLoopResult(result);
     },
-    setContext: (context) => {
-      runner.currentContext = context;
+    setContext: (context2) => {
+      runner.currentContext = context2;
     }
   };
 }
+function resolveDefinitionContext(config, assembled = {}) {
+  const tools = selectNamedResources(
+    assembled.tools ?? config.resources.tools,
+    config.definition.tools,
+    "Tool"
+  );
+  const skills = selectNamedResources(
+    config.resources.skills,
+    config.definition.skills,
+    "Skill"
+  );
+  const candidateRegistry = assembled.phases ?? config.resources.phases;
+  const selectedPhases = selectNamedResources(
+    [...candidateRegistry?.phases.values() ?? []],
+    config.definition.phases,
+    "Phase"
+  );
+  const phases = new Map(selectedPhases.map((phase) => [phase.name, phase]));
+  const requestedEntry = config.definition.entryPhase ?? candidateRegistry?.entryPhaseId ?? null;
+  const entryPhaseId = requestedEntry === DEFAULT_PHASE_ID ? DEFAULT_PHASE_ID : requestedEntry && phases.has(requestedEntry) ? requestedEntry : null;
+  if (requestedEntry && requestedEntry !== DEFAULT_PHASE_ID && !phases.has(requestedEntry)) {
+    console.warn(`Phase entry "${requestedEntry}" is not available; Rowan will use "default".`);
+  }
+  return {
+    systemPrompt: config.definition.content,
+    tools,
+    skills,
+    phases: { phases, entryPhaseId }
+  };
+}
 function mergePhases(base, extension) {
   if (!base && extension.phases.size === 0) return void 0;
   const phases = new Map(base?.phases ?? []);
@@ -4010,29 +4179,28 @@ var AgentRuntime = class _AgentRuntime {
       }
       const executionId = createId("exec");
       claim = await this.owned.claimRun({ runId: run.id, expectedRevision: run.revision, executionId, configToken: token });
+      executionRevision = claim.run.revision;
       const controller = new AbortController();
       this.executions.set(run.id, { controller, executionId });
       const config = resolution.config;
       const assembly = await assembleExtensions(config);
-      const executionConfig = {
-        ...config,
-        context: assembly.context,
-        ...assembly.beforeToolCall ? { beforeToolCall: assembly.beforeToolCall } : {},
-        ...assembly.afterToolCall ? { afterToolCall: assembly.afterToolCall } : {}
-      };
-      executionRevision = claim.run.revision;
       let toolQueue = Promise.resolve();
       const model = "stream" in config && config.stream ? config.model : { provider: config.model.provider, id: config.model.id };
       const stream = "stream" in config && config.stream ? config.stream : createModelStream(config.model);
       const executionContext = projectModelContext({
         context: {
-          ...executionConfig.context,
-          phases: normalizePhaseRegistry(executionConfig.context.phases)
+          ...assembly.context,
+          phases: normalizePhaseRegistry(assembly.context.phases)
         },
         messages: claim.history,
         agentId: run.agentId,
         runId: run.id
       });
+      const executionTools = {
+        tools: assembly.context.tools,
+        beforeToolCall: assembly.beforeToolCall ?? config.beforeToolCall,
+        afterToolCall: assembly.afterToolCall ?? config.afterToolCall
+      };
       const result = await executeOnce({
         canonicalMessages: executionContext.messages,
         context: executionContext,
@@ -4043,7 +4211,7 @@ var AgentRuntime = class _AgentRuntime {
         },
         model,
         stream,
-        maxAttempts: executionConfig.maxAttempts,
+        maxAttempts: config.maxAttempts,
         checkpoint: claim.run.checkpoint,
         signal: controller.signal,
         beforePhase: assembly.beforePhase,
@@ -4070,7 +4238,7 @@ var AgentRuntime = class _AgentRuntime {
                 run,
                 execution: claim.execution,
                 expectedRevision: executionRevision,
-                config: executionConfig,
+                toolConfig: executionTools,
                 toolCalls: [toolCall],
                 signal: controller.signal
               });
@@ -4086,7 +4254,7 @@ var AgentRuntime = class _AgentRuntime {
                 run,
                 execution: claim.execution,
                 expectedRevision: executionRevision,
-                config: executionConfig,
+                toolConfig: executionTools,
                 toolCalls,
                 signal: controller.signal
               });
@@ -4165,7 +4333,7 @@ var AgentRuntime = class _AgentRuntime {
     return { results, revision };
   }
   async executeReservedTool(input) {
-    const durableTool = input.config.context.tools.find((candidate) => candidate.name === input.toolCall.name);
+    const durableTool = input.toolConfig.tools.find((candidate) => candidate.name === input.toolCall.name);
     const providerToolCallId = input.toolCall.id;
     const toolCallId = input.tool.id;
     let revision = input.expectedRevision;
@@ -4200,8 +4368,8 @@ var AgentRuntime = class _AgentRuntime {
       }
     };
     try {
-      if (input.config.beforeToolCall) {
-        const decision = await input.config.beforeToolCall({ tool: durableTool, args: toJsonValue(input.toolCall.args), context, signal: input.signal });
+      if (input.toolConfig.beforeToolCall) {
+        const decision = await input.toolConfig.beforeToolCall({ tool: durableTool, args: toJsonValue(input.toolCall.args), context, signal: input.signal });
         if (!decision.allow) {
           const failed = await this.owned.commitToolResult({ runId: input.run.id, execution: input.execution, expectedRevision: revision, toolCallId, state: "failed", result: { ok: false, content: null, error: decision.reason } });
           return { result: protocolFailure(decision.reason), revision: failed.run.revision };
@@ -4218,7 +4386,7 @@ var AgentRuntime = class _AgentRuntime {
     try {
       let result = await durableTool.execute(toJsonValue(input.toolCall.args), context, input.signal);
       assertToolExecutionResult(result);
-      if (input.config.afterToolCall) result = await input.config.afterToolCall({ tool: durableTool, result, context, signal: input.signal });
+      if (input.toolConfig.afterToolCall) result = await input.toolConfig.afterToolCall({ tool: durableTool, result, context, signal: input.signal });
       assertToolExecutionResult(result);
       const committed = await this.owned.commitToolResult({ runId: input.run.id, execution: input.execution, expectedRevision: revision, toolCallId, state: result.ok ? "completed" : "failed", result });
       return {
@@ -6121,5 +6289,7 @@ export {
   isRuntimeError,
   loadExtensionsFromPath as loadExtensions,
   loadPhases,
-  loadSkills
+  loadSkills,
+  parseAgentDefinition,
+  parseFrontmatter
 };

package/package.json

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