@rowan-agent/agent 0.16.0 → 0.16.2

package/README.md

@@ -183,10 +183,12 @@ const agentId = await runtime.createAgent({
 Each `load*()` call replaces one source atomically; use `directory` or inline
 `values`. `resourceView` controls visibility, so same-name resources can live
 in isolated sources but collide when selected together. The Runtime supplies the
-core `read`/`bash`/`edit`/`write`/`route` Tools itself, and its `rowan.core`
-source — like an Extension's `rowan.extensions` — is implicit in every view, so
-a Definition can select a built-in Phase without naming that source. Core names
-cannot be claimed by another source.
+core `read`/`bash`/`edit`/`write` Tools and built-in `default`/`stop`/`compact` Phases.
+Host-defined resources (including Tools and Phases registered by Extensions) replace
+built-ins by name, retaining the built-in status (replaced Core Tools remain always
+available without explicit Definition selection; replaced Core Phases retain their
+built-in role). Reserved control names (`route` for Tools, `continue` for Phases)
+cannot be claimed by host sources.
 
 Extensions are Runtime-global. Load them only during `AgentRuntime.init()` via
 `bootstrap`; after initialization they are frozen until the Runtime closes.

package/dist/index.d.ts

@@ -269,6 +269,10 @@ interface ToolDefinition {
     description: string;
     /** Parameter schema (JSON Schema) */
     parameters: Record<string, unknown>;
+    /** Optional: one-line snippet shown in the system prompt tool list */
+    promptSnippet?: string;
+    /** Optional: additional guidelines appended to system prompt */
+    promptGuidelines?: string[];
     /** Execute the tool */
     execute: (args: unknown, context: ToolInvocationContext, signal?: AbortSignal) => Promise<ToolExecutionResult$1>;
     /** Optional: per-tool execution mode override */
@@ -955,6 +959,8 @@ type Tool$1 = Readonly<{
     core?: boolean;
     description: string;
     parameters: Type.TSchema;
+    promptSnippet?: string;
+    promptGuidelines?: readonly string[];
     execute(args: JsonValue, context: ToolInvocationContext, signal: AbortSignal): Promise<ToolExecutionResult>;
 }>;
 type ContextCandidate = Readonly<{

package/dist/index.js

@@ -738,8 +738,8 @@ function createReadTool(context) {
 [truncated]` : formatted;
       const archivePath = await spillResult(context, "read", fullFormatted);
       content += `
-Full result: ${archivePath}
-Offset: 0`;
+
+[Full result: ${archivePath}, offset 0]`;
       if (lineTruncated) {
         content += `
 Showing lines ${requestedOffset}-${selectedLineEnd} of ${sourceLines.length}. Use offset=${selectedLineEnd + 1} to continue.`;
@@ -896,8 +896,8 @@ function createBashTool(context) {
 [truncated]` : output;
         const archivePath = await spillResult(context, "bash", output);
         content += `
-Full result: ${archivePath}
-Offset: 0`;
+
+[Full result: ${archivePath}, offset 0]`;
         return toolResult({
           context: toolContext,
           toolName: "bash",
@@ -925,12 +925,15 @@ function createCoreTools(input = {}) {
 }
 
 // src/runtime/core-tools.ts
+var CORE_TOOL_NAMES = /* @__PURE__ */ new Set(["read", "edit", "write", "bash"]);
 function createRuntimeCoreTools(input = {}) {
   return createCoreTools(input).map((tool) => ({
     name: tool.name,
     core: true,
     description: tool.description,
     parameters: tool.parameters,
+    ...tool.promptSnippet ? { promptSnippet: tool.promptSnippet } : {},
+    ...tool.promptGuidelines ? { promptGuidelines: tool.promptGuidelines } : {},
     execute: async (args, context, signal) => {
       const result = await tool.execute(args, { skills: [], toolCallId: context.toolCallId }, signal);
       return result.ok ? { ok: true, content: result.content } : { ok: false, content: result.content, error: result.error ?? "Tool failed." };
@@ -2010,6 +2013,7 @@ async function loadPhaseCode(codePath) {
 var DEFAULT_PHASE_ID = "default";
 var STOP_PHASE_ID = "stop";
 var COMPACT_PHASE_ID = "compact";
+var CORE_PHASE_NAMES = /* @__PURE__ */ new Set([DEFAULT_PHASE_ID, STOP_PHASE_ID, COMPACT_PHASE_ID]);
 function createDefaultPhase() {
   return {
     name: DEFAULT_PHASE_ID,
@@ -2062,7 +2066,7 @@ function createCompactPhase() {
         kind: "compacting",
         message: "Compacting conversation context."
       });
-      const tools = context.tools.filter((tool) => tool.core && (tool.name === "read" || tool.name === "bash"));
+      const tools = context.tools.filter((tool) => tool.name === "read" || tool.name === "bash");
       const working = { ...context, tools, skills: [...context.skills], messages: [...context.messages] };
       const instructions = compactInstructions(context);
       if (instructions) {
@@ -3800,7 +3804,7 @@ function resolveConfigurationSnapshot(registry, input) {
   const selectedContexts = selectNamedResources(input.contexts ?? [], base.contexts, "Context");
   const additionalContexts = deduplicateContexts(input.additionalContexts ?? [], selectedContexts);
   const definition = applyDefinitionLayer(base, layer);
-  const tools = selectNamedResources(resolved.tools, definition.tools, "Tool");
+  const tools = resolveTools(resolved.tools, definition.tools);
   const skills = mergeSkills(
     selectNamedResources(resolved.skills, definition.skills, "Skill"),
     definition.bundledSkills
@@ -3873,11 +3877,20 @@ function intersectPhaseSelection(parent, layer) {
     phaseIds: layer.phaseIds.filter((name) => parentNames.has(name))
   };
 }
+function resolveCoreResources(candidates, selection, coreNames, kind) {
+  const core = candidates.filter((item) => item.core || coreNames.has(item.name));
+  const authoredSelection = selection ? selection.filter((name) => !coreNames.has(name)) : void 0;
+  const authored = candidates.filter((item) => !coreNames.has(item.name) && !item.core);
+  return [
+    ...core.map((item) => item.core ? item : { ...item, core: true }),
+    ...selectNamedResources(authored, authoredSelection, kind)
+  ];
+}
+function resolveTools(candidates, selection) {
+  return resolveCoreResources(candidates, selection, CORE_TOOL_NAMES, "Tool");
+}
 function resolvePhases(candidates, selection) {
-  const coreNames = /* @__PURE__ */ new Set([DEFAULT_PHASE_ID, STOP_PHASE_ID, COMPACT_PHASE_ID]);
-  const core = candidates.filter((phase) => phase.core || coreNames.has(phase.name));
-  const authored = candidates.filter((phase) => !coreNames.has(phase.name) && !phase.core);
-  const selected = [...core, ...selectNamedResources(authored, selection?.phaseIds, "Phase")];
+  const selected = resolveCoreResources(candidates, selection?.phaseIds, CORE_PHASE_NAMES, "Phase");
   const entryPhaseId = selection?.entryPhaseId ?? null;
   if (entryPhaseId !== null && entryPhaseId !== DEFAULT_PHASE_ID && !selected.some(({ name }) => name === entryPhaseId)) {
     console.warn(`Phase entry "${entryPhaseId}" is not available and will be skipped.`);
@@ -4547,6 +4560,8 @@ function projectTool(tool, agentId, runId) {
     ...tool.core ? { core: true } : {},
     description: tool.description,
     parameters: tool.parameters,
+    ...tool.promptSnippet ? { promptSnippet: tool.promptSnippet } : {},
+    ...tool.promptGuidelines ? { promptGuidelines: [...tool.promptGuidelines] } : {},
     execute: async (args, context, signal) => {
       const result = await tool.execute(args, {
         agentId,
@@ -4569,10 +4584,12 @@ function assembleRegisteredExtensions(snapshot, runner, options = {}) {
     root: snapshot.cwd,
     ...options.toolArchiveDir ? { archiveDir: options.toolArchiveDir } : {}
   });
-  const coreNames = new Set(coreTools.map((tool) => tool.name));
+  const replacingNames = new Set(
+    snapshot.resources.tools.filter((tool) => tool.core).map((tool) => tool.name)
+  );
   const tools = [
-    ...snapshot.resources.tools.filter((tool) => !coreNames.has(tool.name)),
-    ...coreTools
+    ...snapshot.resources.tools,
+    ...coreTools.filter((tool) => !replacingNames.has(tool.name))
   ];
   const context = resolveDefinitionContext(snapshot, tools);
   return {
@@ -4620,8 +4637,9 @@ function assembleRegisteredExtensions(snapshot, runner, options = {}) {
 function resolveDefinitionContext(snapshot, assembled) {
   const coreTools = assembled.filter((tool) => tool.core);
   const authoredTools = assembled.filter((tool) => !tool.core);
+  const authoredSelection = snapshot.definition.tools ? snapshot.definition.tools.filter((name) => !assembled.some((t) => t.core && t.name === name)) : void 0;
   const tools = [
-    ...selectNamedResources(authoredTools, snapshot.definition.tools, "Tool"),
+    ...selectNamedResources(authoredTools, authoredSelection, "Tool"),
     ...coreTools
   ];
   const skills = mergeSkills(
@@ -4633,14 +4651,12 @@ function resolveDefinitionContext(snapshot, assembled) {
     ...snapshot.additionalContexts
   ];
   const phaseCandidates = [...snapshot.resources.phases?.phases.values() ?? []];
-  const coreNames = /* @__PURE__ */ new Set([DEFAULT_PHASE_ID, STOP_PHASE_ID, COMPACT_PHASE_ID]);
+  const corePhases = phaseCandidates.filter((phase) => phase.core);
+  const authoredPhases = phaseCandidates.filter((phase) => !phase.core);
+  const authoredPhaseIds = snapshot.definition.phases?.phaseIds ? snapshot.definition.phases.phaseIds.filter((name) => !corePhases.some((p) => p.name === name)) : void 0;
   const selectedPhases = [
-    ...phaseCandidates.filter((phase) => phase.core || coreNames.has(phase.name)),
-    ...selectNamedResources(
-      phaseCandidates.filter((phase) => !phase.core && !coreNames.has(phase.name)),
-      snapshot.definition.phases?.phaseIds,
-      "Phase"
-    )
+    ...corePhases,
+    ...selectNamedResources(authoredPhases, authoredPhaseIds, "Phase")
   ];
   const phases = new Map(selectedPhases.map((phase) => [phase.name, phase]));
   const requestedEntry = snapshot.definition.phases ? snapshot.definition.phases.entryPhaseId : snapshot.resources.phases?.entryPhaseId ?? null;
@@ -6076,8 +6092,16 @@ var ResourceRegistry = class {
   }
   withImplicit(kind, sourceIds) {
     const combined = [...sourceIds];
+    let hasCore = false;
     for (const sourceId of this.implicitSources.get(kind) ?? []) {
-      if (!combined.includes(sourceId)) combined.push(sourceId);
+      if (sourceId === "rowan.core") {
+        hasCore = true;
+      } else if (!combined.includes(sourceId)) {
+        combined.push(sourceId);
+      }
+    }
+    if (hasCore && !combined.includes("rowan.core")) {
+      combined.push("rowan.core");
     }
     return combined;
   }
@@ -6108,6 +6132,12 @@ var ResourceRegistry = class {
           `${capitalize(kind)} resource "${value.name}" is reserved by Rowan core.`
         );
       }
+      if (kind === "phase" && value.name === "continue") {
+        throw new ResourceRegistryError(
+          "resource_collision",
+          `Phase resource "continue" is reserved by Rowan routing controls.`
+        );
+      }
       if (names.has(value.name)) {
         throw new ResourceRegistryError(
           "resource_collision",
@@ -6142,6 +6172,12 @@ var ResourceRegistry = class {
     for (const source of this.sourcesFor(kind, sourceIds)) {
       for (const value of source.values) {
         if (names.has(value.name)) {
+          if (source.sourceId === "rowan.core") {
+            continue;
+          }
+          if (source.sourceId === "rowan.extensions" && isCoreResourceName(kind, value.name)) {
+            continue;
+          }
           throw new ResourceRegistryError(
             "resource_collision",
             `Duplicate ${capitalize(kind)} resource "${value.name}" in Resource View.`
@@ -6161,7 +6197,15 @@ var ResourceRegistry = class {
     const refs = [];
     for (const source of this.sourcesFor(kind, sourceIds)) {
       for (const value of source.values) {
-        if (seenNames.has(value.name)) throw new ResourceRegistryError("resource_collision", `Duplicate ${capitalize(kind)} resource "${value.name}" in Resource View.`);
+        if (seenNames.has(value.name)) {
+          if (source.sourceId === "rowan.core") {
+            continue;
+          }
+          if (source.sourceId === "rowan.extensions" && isCoreResourceName(kind, value.name)) {
+            continue;
+          }
+          throw new ResourceRegistryError("resource_collision", `Duplicate ${capitalize(kind)} resource "${value.name}" in Resource View.`);
+        }
         seenNames.add(value.name);
         refs.push({ kind, sourceId: source.sourceId, name: value.name });
       }
@@ -6231,7 +6275,10 @@ function capitalize(value) {
   return value.charAt(0).toUpperCase() + value.slice(1);
 }
 function isImplicitCoreName(kind, name) {
-  return kind === "tool" && name === "route" || kind === "phase" && (name === "default" || name === "stop" || name === "compact");
+  return kind === "tool" && name === "route";
+}
+function isCoreResourceName(kind, name) {
+  return kind === "tool" && CORE_TOOL_NAMES.has(name) || kind === "phase" && CORE_PHASE_NAMES.has(name);
 }
 async function loadDirectoryValues(kind, directory, sourceId) {
   const root = resolve7(directory);
@@ -6466,6 +6513,8 @@ function adaptExtensionTool(input) {
     name: definition.name,
     description: definition.description,
     parameters: definition.parameters,
+    ...definition.promptSnippet ? { promptSnippet: definition.promptSnippet } : {},
+    ...definition.promptGuidelines ? { promptGuidelines: definition.promptGuidelines } : {},
     execute: async (args, context, signal) => {
       const result = await definition.execute(args, context, signal);
       const content = JSON.parse(JSON.stringify(result.content));
@@ -6527,7 +6576,7 @@ async function spillLargeToolResult(result, archiveDir, toolName) {
   const serialized = typeof result.content === "string" ? result.content : JSON.stringify(result.content, null, 2);
   if (serialized === void 0) return result;
   const bytes = new TextEncoder().encode(serialized);
-  if (bytes.byteLength <= MAX_INLINE_TOOL_RESULT_BYTES || /\nFull result:\s+\S+/.test(serialized)) {
+  if (bytes.byteLength <= MAX_INLINE_TOOL_RESULT_BYTES || /(?:\[Full result:\s+[^\]]+\]|\nFull result:\s+\S+)/.test(serialized)) {
     return result;
   }
   const toolDir = archiveDir;
@@ -6542,8 +6591,8 @@ async function spillLargeToolResult(result, archiveDir, toolName) {
     ...result,
     content: `${preview}
 [truncated]
-Full result: ${path}
-Offset: 0`
+
+[Full result: ${path}, offset 0]`
   };
 }
 var AgentRuntime = class _AgentRuntime {
@@ -8059,23 +8108,29 @@ function isContextOverflowError(error) {
 }
 function normalizePhaseRegistry(registry) {
   const core = createCorePhases();
-  const coreNames = new Set(core.map(({ name }) => name));
-  for (const [name, phase] of registry?.phases ?? []) {
-    if (coreNames.has(name) && !phase.core) {
-      throw new TypeError(`Configured Phase collides with Rowan built-in Phase "${name}".`);
-    }
-  }
+  const coreNames = CORE_PHASE_NAMES;
   for (const [name] of registry?.phases ?? []) {
     if (name === "continue") {
       throw new TypeError(`Configured Phase name "${name}" is reserved by Rowan routing controls.`);
     }
   }
-  const authored = [...registry?.phases ?? []].filter(([name, phase]) => !coreNames.has(name) || phase.core === false);
+  const configuredPhases = registry?.phases ?? /* @__PURE__ */ new Map();
+  const phases = /* @__PURE__ */ new Map();
+  for (const corePhase of core) {
+    const configured = configuredPhases.get(corePhase.name);
+    if (configured) {
+      phases.set(corePhase.name, configured.core ? configured : { ...configured, core: true });
+    } else {
+      phases.set(corePhase.name, corePhase);
+    }
+  }
+  for (const [name, phase] of configuredPhases) {
+    if (!coreNames.has(name)) {
+      phases.set(name, phase);
+    }
+  }
   return {
-    phases: new Map([
-      ...core.map((phase) => [phase.name, phase]),
-      ...authored
-    ]),
+    phases,
     entryPhaseId: registry?.entryPhaseId ?? DEFAULT_PHASE_ID
   };
 }

package/package.json

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