@rowan-agent/agent 0.8.6 → 0.8.7

package/README.md

@@ -11,24 +11,39 @@ import {
   AgentRuntime,
   createCoreTools,
   InMemoryStore,
+  loadPhases,
+  loadSkills,
 } from "@rowan-agent/agent";
 
+const skills = await loadSkills("./.rowan/skills");
+const phases = await loadPhases("./.rowan/phases");
 const runtime = await AgentRuntime.init({
   store: new InMemoryStore(),
 });
 
 const agentId = await runtime.createAgent({
   identity: "example:v1", // Stable config snapshot identity, not the Agent ID
-  model: { provider: "openai", id: "gpt-4o" },
-  stream,
+  model: {
+    provider: "openai",
+    id: "gpt-4o",
+    protocol: "openai-responses",
+    baseUrl: "https://api.openai.com/v1",
+    apiKey: process.env.OPENAI_API_KEY!,
+  },
   definition: {
     name: "workspace-assistant",
     description: "Assist with the current workspace.",
-    content: "You are helpful.",
+    prompt: "You are helpful.",
+    contexts: ["workspace"],
   },
   resources: {
     tools: createCoreTools({ root: process.cwd() }),
-    skills: [],
+    skills,
+    contexts: [{
+      name: "workspace",
+      value: { root: process.cwd() },
+    }],
+    phases,
   },
 });
 
@@ -126,7 +141,7 @@ await runtime.loadAgents({
   values: [{
     name: "workspace-assistant",
     description: "Assist with the current workspace.",
-    content: "You are helpful.",
+    prompt: "You are helpful.",
   }],
 });
 await runtime.loadTools({
@@ -143,8 +158,13 @@ const agentId = await runtime.createAgent({
     skills: [],
     phases: [],
   },
-  model: { provider: "openai", id: "gpt-4o" },
-  stream,
+  model: {
+    provider: "openai",
+    id: "gpt-4o",
+    protocol: "openai-responses",
+    baseUrl: "https://api.openai.com/v1",
+    apiKey: process.env.OPENAI_API_KEY!,
+  },
 });
 ```
 
@@ -156,4 +176,53 @@ Tool and `default` Phase are always available and cannot be overridden.
 Extensions are Runtime-global. Load them only during `AgentRuntime.init()` via
 `bootstrap`; after initialization they are frozen until the Runtime closes.
 Definition name lists narrow the selected Tools, Skills, and Phases: omission
-inherits all candidates, `[]` selects none, and missing names are skipped.
+inherits all candidates, `[]` selects none, and missing names are skipped. The
+same rule applies to `definition.contexts`.
+
+### Resources and Definition
+
+`resources` and `definition` have different jobs:
+
+- `resources` supplies the concrete candidates available to one Agent. Its
+  Tools contain executable `execute()` functions; Skills and Phases contain
+  their loaded content; Contexts contain JSON-safe values.
+- `definition` declares which candidates this Agent uses. `tools`, `skills`,
+  `contexts`, and `phases` are name-based selectors; they cannot create a
+  resource that is absent from `resources`.
+
+For a single-process embedding, provide concrete resources directly and omit
+the selectors when the Agent should use everything:
+
+```ts
+const agentId = await runtime.createAgent({
+  identity: "workspace:v1",
+  definition: {
+    name: "workspace-assistant",
+    description: "Assist with the current workspace.",
+    prompt: "You are helpful.",
+  },
+  resources: { tools, skills, contexts, phases },
+  model,
+});
+```
+
+Use selectors when several Agents share a candidate pool:
+
+```ts
+definition: {
+  name: "read-only-assistant",
+  description: "Inspect the workspace without changing it.",
+  prompt: "You are helpful.",
+  tools: ["read"],
+  contexts: ["workspace"],
+  phases: { entryPhaseId: "review", phaseIds: ["review"] },
+}
+```
+
+For process-boundary persistence, use the Resource Registry form shown above:
+`resourceView` stores stable source IDs instead of executable resource
+closures, and the Runtime resolves those sources into an immutable
+Configuration Snapshot. This lets a restarted Runtime resolve the same
+resource revisions while keeping each Run pinned to the snapshot that created
+it. Direct `resources` are simpler for embedding; `resourceView` is the
+declarative form for shared, reloadable, and restart-resolvable resources.

package/dist/index.d.ts

@@ -627,11 +627,11 @@ type PhaseRegistrySelection = Readonly<{
 type AgentDefinition = Readonly<{
     name: string;
     description: string;
-    content: string;
+    prompt: string;
     tools?: readonly string[];
     skills?: readonly string[];
     phases?: PhaseRegistrySelection;
-    context?: readonly string[];
+    contexts?: readonly string[];
     model?: ModelRef;
 }>;
 /** Parse one Markdown definition using the same frontmatter vocabulary as Phase resources. */
@@ -1233,7 +1233,7 @@ declare class RuntimeBootstrapRegistry extends ResourceRegistry {
 
 type DefinitionLayer = Readonly<{
     description?: string;
-    content?: string;
+    prompt?: string;
     model?: ModelRef;
     tools?: readonly string[];
     skills?: readonly string[];

package/dist/index.js

@@ -1045,13 +1045,15 @@ import { dirname as dirname3, join, resolve as resolve3 } from "path";
 import { parseModelRef } from "@rowan-agent/models";
 function assertAgentDefinition(value) {
   if (!isRecord(value)) throw new TypeError("config.definition is invalid");
+  if ("content" in value) throw new TypeError("definition.content is not supported; use definition.prompt");
+  if ("context" in value) throw new TypeError("definition.context is not supported; use definition.contexts");
   requiredString(value.name, "definition.name");
   requiredString(value.description, "definition.description");
-  requiredString(value.content, "definition.content");
+  requiredString(value.prompt, "definition.prompt");
   optionalStringList(value.tools, "definition.tools");
   optionalStringList(value.skills, "definition.skills");
   optionalPhaseRegistrySelection(value.phases, "definition.phases");
-  optionalStringList(value.context, "definition.context");
+  optionalStringList(value.contexts, "definition.contexts");
   if ("extensions" in value) throw new TypeError("definition.extensions is not supported; Extensions are Runtime-global");
   if ("entryPhase" in value) throw new TypeError("definition.entryPhase is not supported; use definition.phases.entryPhaseId");
   if (value.model !== void 0) {
@@ -1064,17 +1066,19 @@ function parseAgentDefinition(raw) {
   const { frontmatter, body } = parseFrontmatter(raw);
   return normalizeAgentDefinition(frontmatter, body);
 }
-function normalizeAgentDefinition(frontmatter, content, options = {}) {
+function normalizeAgentDefinition(frontmatter, prompt, options = {}) {
+  if (frontmatter.content !== void 0) throw new TypeError("content is not supported; use prompt and the document body");
+  if (frontmatter.context !== void 0) throw new TypeError("context is not supported; use contexts");
   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 normalizedPrompt = requiredString(prompt, "prompt");
   const tools = optionalStringList(frontmatter.tools, "tools");
   const skills = optionalStringList(frontmatter.skills, "skills");
   const phases = optionalPhaseRegistrySelection(frontmatter.phases, "phases");
   if (frontmatter.extensions !== void 0) {
     throw new TypeError("extensions is not supported; Extensions are Runtime-global");
   }
-  const context = optionalStringList(frontmatter.context, "context");
+  const contexts = optionalStringList(frontmatter.contexts, "contexts");
   if (frontmatter.entryPhase !== void 0) {
     throw new TypeError("entryPhase is not supported; use phases.entryPhaseId");
   }
@@ -1082,11 +1086,11 @@ function normalizeAgentDefinition(frontmatter, content, options = {}) {
   return {
     name,
     description,
-    content: normalizedContent,
+    prompt: normalizedPrompt,
     ...tools ? { tools } : {},
     ...skills ? { skills } : {},
     ...phases ? { phases } : {},
-    ...context ? { context } : {},
+    ...contexts ? { contexts } : {},
     ...model ? { model } : {}
   };
 }
@@ -1273,7 +1277,7 @@ async function loadPhase(targetPath) {
     isolated: metadata.isolated,
     filePath: resolved,
     baseDir,
-    content: definition.content,
+    content: definition.prompt,
     model: definition.model
   };
   const codePath = await discoverPhaseCode(baseDir);
@@ -2784,6 +2788,9 @@ function assertAgentConfigRequest(config) {
   if (!config.definition || typeof config.definition.name !== "string" || config.definition.name.trim() === "") {
     throw new TypeError("config.definition.name must be non-empty");
   }
+  if (config.definition.layer && "content" in config.definition.layer) {
+    throw new TypeError("definition.layer.content is not supported; use definition.layer.prompt");
+  }
   const view = config.resourceView;
   if (!view || !Array.isArray(view.agents) || !Array.isArray(view.tools) || !Array.isArray(view.skills) || !Array.isArray(view.phases)) {
     throw new TypeError("config.resourceView is invalid");
@@ -2901,7 +2908,7 @@ function snapshotConfig(config) {
         phaseIds: Object.freeze([...config.definition.phases.phaseIds])
       })
     } : {},
-    ...config.definition.context ? { context: Object.freeze([...config.definition.context]) } : {}
+    ...config.definition.contexts ? { contexts: Object.freeze([...config.definition.contexts]) } : {}
   });
   const resources = Object.freeze({
     ...config.resources,
@@ -3365,7 +3372,7 @@ function resolveDefinitionContext(config, assembled = {}) {
   );
   const contexts = selectNamedResources(
     config.resources.contexts ?? [],
-    config.definition.context,
+    config.definition.contexts,
     "Context"
   );
   const candidateRegistry = assembled.phases ?? config.resources.phases;
@@ -3381,7 +3388,7 @@ function resolveDefinitionContext(config, assembled = {}) {
     console.warn(`Phase entry "${requestedEntry}" is not available; Rowan will use "default".`);
   }
   return {
-    systemPrompt: [config.definition.content, buildContextDescription(contexts)].filter((section) => section.length > 0).join("\n\n"),
+    systemPrompt: [config.definition.prompt, buildContextDescription(contexts)].filter((section) => section.length > 0).join("\n\n"),
     tools,
     skills,
     phases: { phases, entryPhaseId }
@@ -4568,6 +4575,7 @@ var ResourceRegistry = class {
     assertSourceId(sourceId);
     const names = /* @__PURE__ */ new Set();
     for (const value of values) {
+      if (kind === "agent") assertAgentDefinition(value);
       assertNamedResource(value, kind, sourceId);
       if (isImplicitCoreName(kind, value.name) && sourceId !== "rowan.core") {
         throw new ResourceRegistryError(
@@ -4922,7 +4930,7 @@ function resolveConfigurationSnapshot(registry, input) {
   const tools = selectNamedResources(resolved.tools, definition.tools, "Tool");
   const skills = selectNamedResources(resolved.skills, definition.skills, "Skill");
   const phases = resolvePhases(resolved.phases, definition.phases);
-  const contexts = selectNamedResources(input.contexts ?? [], base.context, "Context");
+  const contexts = selectNamedResources(input.contexts ?? [], base.contexts, "Context");
   return {
     identity: input.identity,
     definition,
@@ -4973,7 +4981,7 @@ function applyDefinitionLayer(base, layer) {
   return {
     ...base,
     ...layer.description === void 0 ? {} : { description: layer.description },
-    ...layer.content === void 0 ? {} : { content: layer.content },
+    ...layer.prompt === void 0 ? {} : { prompt: layer.prompt },
     ...layer.model === void 0 ? {} : { model: layer.model },
     ...layer.tools === void 0 ? {} : { tools: intersectNames(base.tools, layer.tools, "Tool") },
     ...layer.skills === void 0 ? {} : { skills: intersectNames(base.skills, layer.skills, "Skill") },

package/package.json

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