@rowan-agent/agent 0.15.5 → 0.16.1

package/dist/index.js

@@ -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." };
@@ -1247,6 +1250,56 @@ function createExtensionAPI(hooks, options, runtime, eventBus) {
       assertActive();
       hooks?.off(eventType, handler);
     },
+    config: {
+      get: async (scope) => {
+        assertActive();
+        return await options?.config?.get(scope) ?? null;
+      },
+      changed: (handler) => {
+        assertActive();
+        options?.config?.changed(handler);
+      }
+    },
+    state: {
+      run: (runId) => {
+        assertActive();
+        const store = options?.state?.run(runId);
+        return {
+          get: async (key) => {
+            assertActive();
+            return store?.get(key);
+          },
+          set: async (key, value) => {
+            assertActive();
+            assertJsonValue(value);
+            return store?.set(key, value);
+          },
+          delete: async (key) => {
+            assertActive();
+            return store?.delete(key);
+          }
+        };
+      },
+      agent: (agentId) => {
+        assertActive();
+        const store = options?.state?.agent(agentId);
+        return {
+          get: async (key) => {
+            assertActive();
+            return store?.get(key);
+          },
+          set: async (key, value) => {
+            assertActive();
+            assertJsonValue(value);
+            return store?.set(key, value);
+          },
+          delete: async (key) => {
+            assertActive();
+            return store?.delete(key);
+          }
+        };
+      }
+    },
     tool: {
       register: (tool) => {
         assertActive();
@@ -1257,6 +1310,25 @@ function createExtensionAPI(hooks, options, runtime, eventBus) {
         options?.unregisterTool?.(toolName);
       }
     },
+    capabilities: {
+      contribute: (contribution) => {
+        assertActive();
+        if (!contribution || typeof contribution !== "object") {
+          throw new TypeError("Capability contribution must be an object.");
+        }
+        if (contribution.kind !== "tool") {
+          throw new TypeError(`Unsupported capability contribution kind: "${contribution.kind}".`);
+        }
+        if (typeof contribution.name !== "string" || contribution.name.trim() === "") {
+          throw new TypeError("Capability contribution requires a non-empty name.");
+        }
+        if (typeof contribution.description !== "string") {
+          throw new TypeError("Capability contribution requires a description string.");
+        }
+        return options?.contributeCapability ? options.contributeCapability(contribution) : () => {
+        };
+      }
+    },
     registerProvider: (config) => {
       assertActive();
       options?.registerProvider?.(config);
@@ -1941,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,
@@ -1993,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) {
@@ -3731,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
@@ -3804,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.`);
@@ -4478,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,
@@ -4500,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 {
@@ -4518,7 +4604,9 @@ function assembleRegisteredExtensions(snapshot, runner, options = {}) {
         agentId: input.context.agentId,
         toolCallId: input.context.toolCallId,
         metadata: input.context.runMetadata,
-        answer: input.answer
+        answer: input.answer,
+        scope: input.context.scope,
+        turn: input.context.turn
       });
       if (decision.interaction !== void 0) {
         return { interaction: decision.interaction };
@@ -4534,7 +4622,9 @@ function assembleRegisteredExtensions(snapshot, runner, options = {}) {
           runId: input.context.runId,
           agentId: input.context.agentId,
           toolCallId: input.context.toolCallId,
-          metadata: input.context.runMetadata
+          metadata: input.context.runMetadata,
+          scope: input.context.scope,
+          turn: input.context.turn
         }
       );
       return fromLoopResult(result);
@@ -4547,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(
@@ -4560,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;
@@ -4792,6 +4881,126 @@ var HooksManager = class {
   }
 };
 
+// src/extensions/host.ts
+var InMemoryExtensionHost = class {
+  configs = /* @__PURE__ */ new Map();
+  agentState = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  constructor(options = {}) {
+    if (options.configs) {
+      for (const [scopeKey, extMap] of Object.entries(options.configs)) {
+        const map = /* @__PURE__ */ new Map();
+        for (const [extId, cfg] of Object.entries(extMap)) {
+          assertJsonValue(cfg);
+          map.set(extId, structuredClone(cfg));
+        }
+        this.configs.set(scopeKey, map);
+      }
+    }
+    if (options.agentState) {
+      for (const [agentId, extMap] of Object.entries(options.agentState)) {
+        const agentMap = /* @__PURE__ */ new Map();
+        for (const [extId, stateMap] of Object.entries(extMap)) {
+          const map = /* @__PURE__ */ new Map();
+          for (const [key, val] of Object.entries(stateMap)) {
+            assertJsonValue(val);
+            map.set(key, structuredClone(val));
+          }
+          agentMap.set(extId, map);
+        }
+        this.agentState.set(agentId, agentMap);
+      }
+    }
+  }
+  setConfig(extensionId, config, scope = { kind: "global" }) {
+    const scopeKey = scopeToKey(scope);
+    if (!this.configs.has(scopeKey)) {
+      this.configs.set(scopeKey, /* @__PURE__ */ new Map());
+    }
+    const scopeConfigs = this.configs.get(scopeKey);
+    if (config === null) {
+      scopeConfigs.delete(extensionId);
+    } else {
+      assertJsonValue(config);
+      scopeConfigs.set(extensionId, structuredClone(config));
+    }
+    this.notifyConfigChanged(extensionId, scope);
+  }
+  getConfig(extensionId, scope = { kind: "global" }) {
+    const globalConfig = this.configs.get("global")?.get(extensionId);
+    let merged = globalConfig ? { ...globalConfig } : null;
+    if (scope.kind === "team" || scope.kind === "project") {
+      const teamConfig = this.configs.get(`team:${scope.teamId}`)?.get(extensionId);
+      if (teamConfig) {
+        merged = { ...merged ?? {}, ...teamConfig };
+      }
+    }
+    if (scope.kind === "project") {
+      const projectConfig = this.configs.get(`project:${scope.teamId}:${scope.projectId}`)?.get(extensionId);
+      if (projectConfig) {
+        merged = { ...merged ?? {}, ...projectConfig };
+      }
+    }
+    return merged ? structuredClone(merged) : null;
+  }
+  onConfigChanged(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  notifyConfigChanged(extensionId, scope = { kind: "global" }) {
+    for (const listener of this.listeners) {
+      try {
+        listener(extensionId, scope);
+      } catch {
+      }
+    }
+  }
+  getAgentState(extensionId, agentId, key) {
+    const val = this.agentState.get(agentId)?.get(extensionId)?.get(key);
+    return val !== void 0 ? structuredClone(val) : void 0;
+  }
+  setAgentState(extensionId, agentId, key, value) {
+    assertJsonValue(value);
+    let agentMap = this.agentState.get(agentId);
+    if (!agentMap) {
+      agentMap = /* @__PURE__ */ new Map();
+      this.agentState.set(agentId, agentMap);
+    }
+    let extMap = agentMap.get(extensionId);
+    if (!extMap) {
+      extMap = /* @__PURE__ */ new Map();
+      agentMap.set(extensionId, extMap);
+    }
+    extMap.set(key, structuredClone(value));
+  }
+  deleteAgentState(extensionId, agentId, key) {
+    this.agentState.get(agentId)?.get(extensionId)?.delete(key);
+  }
+};
+function scopeToKey(scope) {
+  switch (scope.kind) {
+    case "global":
+      return "global";
+    case "team":
+      return `team:${scope.teamId}`;
+    case "project":
+      return `project:${scope.teamId}:${scope.projectId}`;
+  }
+}
+function resolveScopeFromMetadata(metadata) {
+  if (metadata) {
+    const teamId = typeof metadata.teamId === "string" ? metadata.teamId : void 0;
+    const projectId = typeof metadata.projectId === "string" ? metadata.projectId : void 0;
+    if (teamId && projectId) {
+      return { kind: "project", teamId, projectId };
+    }
+    if (teamId) {
+      return { kind: "team", teamId };
+    }
+  }
+  return { kind: "global" };
+}
+
 // src/extensions/runner.ts
 import { execFile } from "child_process";
 import { dirname as dirname5, resolve as resolve5 } from "path";
@@ -4934,11 +5143,17 @@ var ExtensionRunner = class {
   hooks;
   runtime;
   events;
+  host;
   cwd;
   abortController = new AbortController();
   _idle = true;
   // Per-extension tracking
   extensions = [];
+  // Run state: runId -> extensionId -> key -> value
+  runState = /* @__PURE__ */ new Map();
+  // Config change listeners: extensionId -> Set of handlers
+  configChangeListeners = /* @__PURE__ */ new Map();
+  hostUnsubscribers = [];
   // Phase management
   phases = /* @__PURE__ */ new Map();
   _phaseCache = null;
@@ -4947,6 +5162,8 @@ var ExtensionRunner = class {
   bound = false;
   // Error listeners
   errorListeners = /* @__PURE__ */ new Set();
+  // Capability change listeners
+  capabilityListeners = /* @__PURE__ */ new Set();
   /** Current agent context — set by the agent before each phase */
   currentContext;
   constructor(options) {
@@ -4954,6 +5171,15 @@ var ExtensionRunner = class {
     this.runtime = createExtensionRuntime();
     this.events = createEventBus();
     this.cwd = options?.cwd ?? process.cwd();
+    this.host = options?.host ?? new InMemoryExtensionHost();
+    if (this.host.onConfigChanged) {
+      const unsub = this.host.onConfigChanged((extensionId, scope) => {
+        this.notifyConfigChanged(extensionId, scope);
+      });
+      if (typeof unsub === "function") {
+        this.hostUnsubscribers.push(unsub);
+      }
+    }
   }
   /** Whether the agent is currently idle (not streaming). */
   get isIdle() {
@@ -5034,10 +5260,13 @@ var ExtensionRunner = class {
    */
   async loadExtensions(extensions) {
     for (const ext of extensions) {
+      const extensionId = ext.id ?? ext.manifest?.id ?? ext.name;
       const extension = {
+        id: extensionId,
         path: ext.path,
         tools: /* @__PURE__ */ new Map(),
         phases: /* @__PURE__ */ new Set(),
+        capabilities: /* @__PURE__ */ new Map(),
         cleanup: [],
         runtime: createExtensionRuntime()
       };
@@ -5047,6 +5276,9 @@ var ExtensionRunner = class {
         if (typeof disposer === "function") extension.disposer = disposer;
         this.extensions.push(extension);
         this._phaseCache = null;
+        if (extension.capabilities.size > 0) {
+          this.notifyCapabilitiesChanged();
+        }
       } catch (error) {
         await this.rollbackExtension(extension);
         const message = error instanceof Error ? error.message : String(error);
@@ -5063,14 +5295,67 @@ var ExtensionRunner = class {
   /** Dispose all active Extensions in reverse activation order. */
   async close() {
     this.abortController.abort();
+    for (const unsub of this.hostUnsubscribers) {
+      try {
+        unsub();
+      } catch {
+      }
+    }
+    this.hostUnsubscribers.length = 0;
+    this.configChangeListeners.clear();
+    this.runState.clear();
     for (const extension of [...this.extensions].reverse()) {
       await this.disposeExtension(extension, "This Extension Runtime has been closed.");
     }
     this.extensions.length = 0;
+    this.capabilityListeners.clear();
     this.phases.clear();
     this._phaseCache = null;
     this.runtime.invalidate("This Extension Runtime has been closed.");
   }
+  get extensionHost() {
+    return this.host;
+  }
+  notifyConfigChanged(extensionId, scope) {
+    const listeners = this.configChangeListeners.get(extensionId);
+    if (!listeners) return;
+    for (const listener of listeners) {
+      try {
+        listener(scope);
+      } catch (error) {
+        this.emitError({
+          extensionPath: "<runtime>",
+          event: "config_changed",
+          error: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : void 0
+        });
+      }
+    }
+  }
+  getRunState(runId, extensionId, key) {
+    const val = this.runState.get(runId)?.get(extensionId)?.get(key);
+    return val !== void 0 ? structuredClone(val) : void 0;
+  }
+  setRunState(runId, extensionId, key, value) {
+    assertJsonValue(value);
+    let runMap = this.runState.get(runId);
+    if (!runMap) {
+      runMap = /* @__PURE__ */ new Map();
+      this.runState.set(runId, runMap);
+    }
+    let extMap = runMap.get(extensionId);
+    if (!extMap) {
+      extMap = /* @__PURE__ */ new Map();
+      runMap.set(extensionId, extMap);
+    }
+    extMap.set(key, structuredClone(value));
+  }
+  deleteRunState(runId, extensionId, key) {
+    this.runState.get(runId)?.get(extensionId)?.delete(key);
+  }
+  dropRunState(runId) {
+    this.runState.delete(runId);
+  }
   // ---------------------------------------------------------------------------
   // Tool management
   // ---------------------------------------------------------------------------
@@ -5097,6 +5382,32 @@ var ExtensionRunner = class {
     return void 0;
   }
   // ---------------------------------------------------------------------------
+  // Capability management
+  // ---------------------------------------------------------------------------
+  /** Get all contributed capabilities across all extensions. */
+  getCapabilities() {
+    const result = [];
+    for (const ext of this.extensions) {
+      for (const contrib of ext.capabilities.values()) {
+        result.push({
+          extensionId: ext.id,
+          kind: contrib.kind,
+          name: contrib.name,
+          description: contrib.description
+        });
+      }
+    }
+    return Object.freeze(result);
+  }
+  /**
+   * Subscribe to capability changes (contributions added, removed, or extensions disposed).
+   * Returns an unsubscribe function.
+   */
+  onCapabilitiesChanged(listener) {
+    this.capabilityListeners.add(listener);
+    return () => this.capabilityListeners.delete(listener);
+  }
+  // ---------------------------------------------------------------------------
   // Phase management
   // ---------------------------------------------------------------------------
   getPhase(name) {
@@ -5182,7 +5493,39 @@ var ExtensionRunner = class {
     });
     return result?.input ?? input;
   }
+  async emitRunStart(event) {
+    try {
+      await this.hooks.emit("run_start", {
+        type: "run_start",
+        ...event
+      });
+    } catch (error) {
+      this.emitError({
+        extensionPath: "<runtime>",
+        event: "run_start",
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : void 0
+      });
+    }
+  }
+  async emitRunEnd(event) {
+    try {
+      await this.hooks.emit("run_end", {
+        type: "run_end",
+        ...event
+      });
+    } catch (error) {
+      this.emitError({
+        extensionPath: "<runtime>",
+        event: "run_end",
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : void 0
+      });
+    }
+  }
   async emitBeforeToolCall(tool, args, context) {
+    const scope = context?.scope ?? resolveScopeFromMetadata(context?.metadata);
+    const turn = context?.turn ?? {};
     const result = await this.emitHook("before_tool_call", {
       type: "before_tool_call",
       tool,
@@ -5191,11 +5534,15 @@ var ExtensionRunner = class {
       ...context?.agentId !== void 0 ? { agentId: context.agentId } : {},
       ...context?.toolCallId !== void 0 ? { toolCallId: context.toolCallId } : {},
       ...context?.metadata !== void 0 ? { metadata: context.metadata } : {},
-      ...context?.answer !== void 0 ? { answer: context.answer } : {}
+      ...context?.answer !== void 0 ? { answer: context.answer } : {},
+      scope,
+      turn
     });
     return result ?? { allow: true };
   }
   async emitAfterToolCall(tool, result, context) {
+    const scope = context?.scope ?? resolveScopeFromMetadata(context?.metadata);
+    const turn = context?.turn ?? {};
     const hookResult = await this.emitHook("after_tool_call", {
       type: "after_tool_call",
       tool,
@@ -5203,7 +5550,9 @@ var ExtensionRunner = class {
       ...context?.runId !== void 0 ? { runId: context.runId } : {},
       ...context?.agentId !== void 0 ? { agentId: context.agentId } : {},
       ...context?.toolCallId !== void 0 ? { toolCallId: context.toolCallId } : {},
-      ...context?.metadata !== void 0 ? { metadata: context.metadata } : {}
+      ...context?.metadata !== void 0 ? { metadata: context.metadata } : {},
+      scope,
+      turn
     });
     return hookResult?.result ?? result;
   }
@@ -5271,9 +5620,43 @@ var ExtensionRunner = class {
       unregisterProvider: (name) => this.unregisterProvider(name),
       registerTool: (tool) => this.registerTool(extension, tool),
       unregisterTool: (toolName) => this.unregisterTool(extension, toolName),
+      contributeCapability: (contribution) => this.contributeCapability(extension, contribution),
       context: extContext,
       manifest,
-      trackCleanup: (cleanup) => extension.cleanup.push(cleanup)
+      trackCleanup: (cleanup) => extension.cleanup.push(cleanup),
+      config: {
+        get: async (scope) => {
+          const effectiveScope = scope ?? { kind: "global" };
+          const res = await runner.host.getConfig(extension.id, effectiveScope);
+          return res ?? null;
+        },
+        changed: (handler) => {
+          let listeners = runner.configChangeListeners.get(extension.id);
+          if (!listeners) {
+            listeners = /* @__PURE__ */ new Set();
+            runner.configChangeListeners.set(extension.id, listeners);
+          }
+          listeners.add(handler);
+          extension.cleanup.push(() => {
+            listeners?.delete(handler);
+            if (listeners && listeners.size === 0) {
+              runner.configChangeListeners.delete(extension.id);
+            }
+          });
+        }
+      },
+      state: {
+        run: (runId) => ({
+          get: async (key) => runner.getRunState(runId, extension.id, key),
+          set: async (key, value) => runner.setRunState(runId, extension.id, key, value),
+          delete: async (key) => runner.deleteRunState(runId, extension.id, key)
+        }),
+        agent: (agentId) => ({
+          get: async (key) => runner.host.getAgentState(extension.id, agentId, key),
+          set: async (key, value) => runner.host.setAgentState(extension.id, agentId, key, value),
+          delete: async (key) => runner.host.deleteAgentState(extension.id, agentId, key)
+        })
+      }
     }, extension.runtime, this.events);
   }
   registerTool(extension, tool) {
@@ -5302,6 +5685,46 @@ var ExtensionRunner = class {
       extension.tools.delete(toolName);
     }
   }
+  contributeCapability(extension, contribution) {
+    const key = `${contribution.kind}:${contribution.name}`;
+    const entry = {
+      kind: contribution.kind,
+      name: contribution.name,
+      description: contribution.description
+    };
+    extension.capabilities.set(key, entry);
+    if (this.extensions.includes(extension)) {
+      this.notifyCapabilitiesChanged();
+    }
+    let disposed = false;
+    const dispose = () => {
+      if (disposed) return;
+      disposed = true;
+      if (extension.capabilities.get(key) === entry) {
+        extension.capabilities.delete(key);
+        if (this.extensions.includes(extension)) {
+          this.notifyCapabilitiesChanged();
+        }
+      }
+    };
+    extension.cleanup.push(dispose);
+    return dispose;
+  }
+  notifyCapabilitiesChanged() {
+    const capabilities = this.getCapabilities();
+    for (const listener of this.capabilityListeners) {
+      try {
+        listener(capabilities);
+      } catch (error) {
+        this.emitError({
+          extensionPath: "<runtime>",
+          event: "capabilities_changed",
+          error: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : void 0
+        });
+      }
+    }
+  }
   async registerPhase(extension, registration) {
     if (typeof registration === "string") {
       if (registration.length === 0) {
@@ -5388,6 +5811,8 @@ var ExtensionRunner = class {
   async disposeExtension(extension, message) {
     extension.runtime.invalidate(message);
     for (const name of extension.phases) this.phases.delete(name);
+    const hadCapabilities = extension.capabilities.size > 0;
+    extension.capabilities.clear();
     for (const cleanup of [...extension.cleanup].reverse()) {
       await Promise.resolve().then(() => cleanup()).catch(() => void 0);
     }
@@ -5395,6 +5820,9 @@ var ExtensionRunner = class {
       await Promise.resolve().then(() => extension.disposer()).catch(() => void 0);
     }
     this._phaseCache = null;
+    if (hadCapabilities) {
+      this.notifyCapabilitiesChanged();
+    }
   }
 };
 function createExtensionRunner(options) {
@@ -5425,6 +5853,8 @@ function readManifestSync(dir) {
     const rowan = pkg.rowan;
     if (!rowan) return void 0;
     return {
+      id: rowan.id ?? pkg.name,
+      name: pkg.name,
       entry: rowan.extensions?.[0]
     };
   } catch {
@@ -5507,13 +5937,15 @@ async function discoverExtensionsInDir(dir) {
   }
   return paths;
 }
-function loadExtensionFromFactory(factory, cwd, extensionPath = "<inline>") {
+function loadExtensionFromFactory(factory, cwd, extensionPath = "<inline>", options = {}) {
   const resolvedCwd = resolve6(cwd);
   const resolvedPath = isSyntheticPath(extensionPath) ? extensionPath : resolve6(resolvedCwd, extensionPath);
-  const name = isSyntheticPath(extensionPath) ? extensionPath : basename3(dirname6(resolvedPath)) || "unknown";
+  const name = options.name ?? (isSyntheticPath(extensionPath) ? extensionPath : basename3(dirname6(resolvedPath)) || "unknown");
   const manifestDir = isSyntheticPath(extensionPath) ? resolvedCwd : dirname6(resolvedPath);
   const manifest = readManifestSync(manifestDir);
+  const id = options.id ?? manifest?.id ?? name;
   return {
+    id,
     path: resolvedPath,
     name,
     factory,
@@ -5660,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;
   }
@@ -5692,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",
@@ -5726,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.`
@@ -5745,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 });
       }
@@ -5815,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);
@@ -5983,6 +6446,12 @@ var RuntimeExtensionLifetime = class {
   get extensionRunner() {
     return this.runner;
   }
+  get extensionHost() {
+    return this.runner.extensionHost;
+  }
+  dropRunState(runId) {
+    this.runner.dropRunState(runId);
+  }
   async close() {
     if (this.closed) return;
     this.closed = true;
@@ -5996,6 +6465,9 @@ var RuntimeBootstrapRegistry = class extends ResourceRegistry {
   }
   extensions;
   extensionSourceId = "rowan.extensions";
+  get extensionHost() {
+    return this.extensions.extensionHost;
+  }
   /** Install Rowan-owned implicit resources before any host source is read. */
   async ensureCoreResources() {
     await this.replaceImplicit("tool", "rowan.core", [createRouteTool([])]);
@@ -6041,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));
@@ -6134,11 +6608,14 @@ var AgentRuntime = class _AgentRuntime {
   autoCompactionRuns = /* @__PURE__ */ new Set();
   consumers = /* @__PURE__ */ new Map();
   transientEvents = new TransientRunEventHub();
+  host;
   resources;
+  startedRuns = /* @__PURE__ */ new Set();
   heartbeat;
   pumping = false;
   closed = false;
   constructor(options, owned, resources) {
+    this.host = options.host;
     this.owned = owned;
     this.commands = new ConfigCommandService(owned, options.configs, String(owned.lease.token).split(":")[0]);
     this.storeIncarnation = String(owned.lease.token).split(":")[0];
@@ -6148,10 +6625,12 @@ var AgentRuntime = class _AgentRuntime {
   static async init(options) {
     if (!options.store) throw new TypeError("AgentRuntime requires a DurableStore");
     const configs = options.configs ?? new InMemoryConfigProvider();
+    const host = options.host ?? new InMemoryExtensionHost();
     const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
     if (!Number.isInteger(concurrency) || concurrency <= 0) throw new TypeError("concurrency must be a positive integer");
     const owned = await options.store.openOwner({ ownerId: createId("owner"), leaseMs: OWNER_LEASE_MS });
-    const runtime = new _AgentRuntime({ ...options, configs, concurrency }, owned, new RuntimeBootstrapRegistry());
+    const extensions = new RuntimeExtensionLifetime({ host });
+    const runtime = new _AgentRuntime({ ...options, configs, concurrency, host }, owned, new RuntimeBootstrapRegistry(extensions));
     try {
       await runtime.resources.ensureCoreResources();
       await options.bootstrap?.(runtime.resources);
@@ -6164,6 +6643,20 @@ var AgentRuntime = class _AgentRuntime {
       throw error;
     }
   }
+  async handleRunEnd(runId, agentId, outcome) {
+    if (this.startedRuns.has(runId)) {
+      this.startedRuns.delete(runId);
+      try {
+        await this.resources.extensionRunner.emitRunEnd({
+          runId,
+          agentId,
+          outcome
+        });
+      } catch {
+      }
+    }
+    this.resources.extensionRunner.dropRunState(runId);
+  }
   async loadAgents(input) {
     this.assertOpen();
     return this.resources.loadAgents(input);
@@ -6374,6 +6867,14 @@ var AgentRuntime = class _AgentRuntime {
     });
     return { caughtUp: subscription.caughtUp.promise, done: subscription.done.promise, stop: () => controller.abort() };
   }
+  listCapabilities() {
+    this.assertOpen();
+    return this.resources.extensionRunner.getCapabilities();
+  }
+  onCapabilitiesChanged(listener) {
+    this.assertOpen();
+    return this.resources.extensionRunner.onCapabilitiesChanged(listener);
+  }
   async close() {
     if (this.closed) return;
     this.closed = true;
@@ -6417,6 +6918,11 @@ var AgentRuntime = class _AgentRuntime {
     const active = this.executions.get(runId);
     if (active) this.transientEvents.clear(runId, active.executionId);
     active?.controller.abort();
+    if (this.startedRuns.has(runId)) {
+      await this.handleRunEnd(runId, snapshot.agentId, { id: createId("out"), status: "cancelled", message: reason ?? "Agent run stopped." });
+    } else {
+      this.resources.extensionRunner.dropRunState(runId);
+    }
     return boundaryFromSnapshot(await this.owned.snapshotRun(runId));
   }
   async pump() {
@@ -6528,6 +7034,19 @@ var AgentRuntime = class _AgentRuntime {
       const controller = new AbortController();
       this.executions.set(run.id, { controller, executionId });
       if (this.cancellationRequested.has(run.id)) controller.abort();
+      if (!this.startedRuns.has(run.id)) {
+        this.startedRuns.add(run.id);
+        const turn = typeof run.input === "object" && run.input !== null && !Array.isArray(run.input) ? run.input : {};
+        try {
+          await this.resources.extensionRunner.emitRunStart({
+            runId: run.id,
+            agentId: run.agentId,
+            metadata: run.metadata ?? {},
+            turn
+          });
+        } catch {
+        }
+      }
       const assembly = assembleRegisteredExtensions(config, this.resources.extensionRunner, {
         toolArchiveDir: this.archiveDirFor(run.agentId)
       });
@@ -6754,6 +7273,11 @@ var AgentRuntime = class _AgentRuntime {
           ...output && hasVisibleAssistantText(output) ? { output } : {}
         });
         this.transientEvents.clear(run.id, claim.execution.executionId);
+        await this.handleRunEnd(run.id, run.agentId, {
+          id: createId("out"),
+          status: "cancelled",
+          message: reason
+        });
         return;
       }
       if (result.type === "input_required") {
@@ -6789,33 +7313,53 @@ var AgentRuntime = class _AgentRuntime {
         const output = latestAssistant(run, result.messages, executionContext.messages.length);
         await this.owned.commitOutcome({ runId: run.id, execution: claim.execution, expectedRevision: executionRevision, outcome: durableOutcome(result.outcome), ...output ? { output } : {} });
         this.transientEvents.clear(run.id, claim.execution.executionId, true);
+        await this.handleRunEnd(run.id, run.agentId, result.outcome);
         return;
       }
       const failure = { code: "execution_failed", message: result.error instanceof Error ? result.error.message : "Execution failed." };
       await this.owned.commitOutcome({ runId: run.id, execution: claim.execution, expectedRevision: executionRevision, failure });
       this.transientEvents.clear(run.id, claim.execution.executionId);
+      await this.handleRunEnd(run.id, run.agentId, {
+        id: createId("out"),
+        status: "failed",
+        message: failure.message,
+        error: failure
+      });
     } catch (error) {
       if (!claim && error instanceof RuntimeError && ["run_state_conflict", "runtime_ownership_lost", "run_not_found"].includes(error.code)) return;
       if (claim) {
         if (this.cancellationRequested.has(run.id)) {
+          const reason = this.cancellationReasons.get(run.id) ?? "Agent run stopped.";
           await this.owned.cancelRun({
             runId: run.id,
             expectedRevision: executionRevision,
-            reason: this.cancellationReasons.get(run.id) ?? "Agent run stopped."
+            reason
           }).catch(() => void 0);
+          await this.handleRunEnd(run.id, run.agentId, {
+            id: createId("out"),
+            status: "cancelled",
+            message: reason
+          });
           return;
         }
+        const failureMessage = error instanceof Error ? error.message : "Execution failed.";
         await this.owned.commitOutcome({
           runId: run.id,
           execution: claim.execution,
           expectedRevision: executionRevision,
-          failure: { code: "execution_failed", message: error instanceof Error ? error.message : "Execution failed." }
+          failure: { code: "execution_failed", message: failureMessage }
         }).catch(async (commitError) => {
           await this.owned.cancelRun({
             runId: run.id,
             reason: commitError instanceof Error ? commitError.message : "Run failure could not be committed."
           }).catch(() => void 0);
         });
+        await this.handleRunEnd(run.id, run.agentId, {
+          id: createId("out"),
+          status: "failed",
+          message: failureMessage,
+          error: { code: "execution_failed", message: failureMessage }
+        });
         return;
       }
       throw error;
@@ -6838,6 +7382,8 @@ var AgentRuntime = class _AgentRuntime {
     return { result: batch.results[0], revision: batch.revision };
   }
   async executeToolBatch(input) {
+    const scope = resolveScopeFromMetadata(input.run.metadata);
+    const turn = typeof input.run.input === "object" && input.run.input !== null && !Array.isArray(input.run.input) ? input.run.input : {};
     const checkpoint = input.driver?.checkpoint();
     const isSuspensionResume = checkpoint && typeof checkpoint === "object" && checkpoint.kind === "tool_call_suspension";
     const suspension = isSuspensionResume ? checkpoint : void 0;
@@ -6864,6 +7410,8 @@ var AgentRuntime = class _AgentRuntime {
           ...input.agentMetadata === void 0 ? {} : { agentMetadata: input.agentMetadata },
           ...input.run.metadata === void 0 ? {} : { runMetadata: input.run.metadata },
           toolCallId,
+          scope,
+          turn,
           interaction: createRunInteractionDriver({
             currentPhase: "default",
             attempt: 0,
@@ -6951,6 +7499,8 @@ var AgentRuntime = class _AgentRuntime {
             ...input.agentMetadata === void 0 ? {} : { agentMetadata: input.agentMetadata },
             ...input.run.metadata === void 0 ? {} : { runMetadata: input.run.metadata },
             toolCallId,
+            scope,
+            turn,
             interaction: createToolInteractionDriver(input.driver, {
               toolCallId,
               toolCallIds,
@@ -7105,6 +7655,8 @@ var AgentRuntime = class _AgentRuntime {
         ...input.agentMetadata === void 0 ? {} : { agentMetadata: input.agentMetadata },
         ...input.run.metadata === void 0 ? {} : { runMetadata: input.run.metadata },
         toolCallId,
+        scope,
+        turn,
         interaction: createToolInteractionDriver(input.driver, {
           toolCallId,
           ...suspension?.toolCallIds === void 0 ? {} : { toolCallIds: suspension.toolCallIds },
@@ -7556,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
   };
 }
@@ -10620,6 +11178,7 @@ export {
   DEFAULT_PHASE_ID,
   ExtensionLifetimeError,
   InMemoryConfigProvider,
+  InMemoryExtensionHost,
   InMemoryStore,
   ResourceRegistry,
   ResourceRegistryError,