@geminixiang/mikan 1.0.0-beta.13 → 1.0.0-beta.15

package/dist/harness/extensions/registry.d.ts

@@ -6,18 +6,65 @@
  * are logged and swallowed so a broken extension cannot take down a run.
  */
 import type { AgentTool } from "@earendil-works/pi-agent-core";
-import type { MikanHookMap, MikanHookName } from "./types.js";
+import type { BeforeAgentStartHookEvent, BeforeAgentStartHookResult, ExtensionCommand, ExtensionCommandContext, ExtensionDisposer, MikanHookMap, MikanHookName, ToolResultHookEvent, ToolResultHookResult } from "./types.js";
+/**
+ * Parse `/name args…` slash-command text. Returns undefined when the text is
+ * not a slash command with a valid name (`COMMAND_NAME_PATTERN`).
+ */
+export declare function parseCommandInput(text: string): {
+    name: string;
+    args: string;
+} | undefined;
 export declare class ExtensionRegistry {
     private handlers;
     private tools;
+    private commands;
+    private disposers;
     register<T extends MikanHookName>(owner: string, hook: T, handler: MikanHookMap[T]): void;
     registerTool(tool: AgentTool): void;
+    /**
+     * Register an extension command. Invalid names throw (surfaces as an
+     * activation error for that extension); a duplicate name is logged and
+     * ignored so the first registration wins, mirroring hook isolation.
+     */
+    registerCommand(owner: string, command: ExtensionCommand): void;
+    registerDisposer(owner: string, disposer: ExtensionDisposer): void;
     getContributedTools(): AgentTool[];
+    /** Registered commands, for inventory surfaces. */
+    getCommands(): ExtensionCommand[];
+    /**
+     * Run the handler for `/name`, if an extension registered it. Returns true
+     * when a matching command exists — including when its handler threw (the
+     * command was consumed; the error is logged and reported to the user).
+     */
+    dispatchCommand(name: string, context: ExtensionCommandContext): Promise<boolean>;
+    /**
+     * Run all registered disposers in reverse registration order (LIFO).
+     * Disposer errors are logged and never propagate. Idempotent: disposers
+     * run once and the list is cleared.
+     */
+    dispose(): Promise<void>;
     hasHandlers(hook: MikanHookName): boolean;
     /**
      * Run handlers in registration order. Returns the first non-undefined
      * result. Handler errors are logged and skipped.
      */
     emit<T extends MikanHookName>(hook: T, event: Parameters<MikanHookMap[T]>[0]): Promise<Awaited<ReturnType<MikanHookMap[T]>> | undefined>;
+    /**
+     * Dispatch `before_agent_start` with merge semantics: `systemPrompt` and
+     * `prompt` rewrites chain (each handler sees the event as rewritten by
+     * earlier handlers), while `block` from ANY handler wins so a policy
+     * extension cannot be shadowed by registration order. The first block's
+     * reason is kept. Returns undefined when no handler changed anything.
+     */
+    emitBeforeAgentStart(event: BeforeAgentStartHookEvent): Promise<BeforeAgentStartHookResult | undefined>;
+    /**
+     * Dispatch `tool_result` with chaining semantics: each handler sees the
+     * content/isError as rewritten by earlier handlers, so e.g. a redaction
+     * extension processes the output of upstream rewriters instead of the
+     * original. Returns the accumulated override, or undefined when no handler
+     * changed anything.
+     */
+    emitToolResult(event: ToolResultHookEvent): Promise<ToolResultHookResult | undefined>;
 }
 //# sourceMappingURL=registry.d.ts.map

package/dist/harness/extensions/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/harness/extensions/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAM9D,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAOd;IACF,OAAO,CAAC,KAAK,CAAmB;IAEhC,QAAQ,CAAC,CAAC,SAAS,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAExF;IAED,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAElC;IAED,mBAAmB,IAAI,SAAS,EAAE,CAEjC;IAED,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAExC;IAED;;;OAGG;IACG,IAAI,CAAC,CAAC,SAAS,aAAa,EAChC,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACpC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAe3D;CACF"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/harness/extensions/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAIpB;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAI1F;AAMD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CASd;IACF,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,QAAQ,CAAmE;IACnF,OAAO,CAAC,SAAS,CAA6D;IAE9E,QAAQ,CAAC,CAAC,SAAS,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAExF;IAED,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAElC;IAED;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAc9D;IAED,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAEjE;IAED,mBAAmB,IAAI,SAAS,EAAE,CAEjC;IAED,mDAAmD;IACnD,WAAW,IAAI,gBAAgB,EAAE,CAEhC;IAED;;;;OAIG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC,CAetF;IAED;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAa7B;IAED,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAExC;IAED;;;OAGG;IACG,IAAI,CAAC,CAAC,SAAS,aAAa,EAChC,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACpC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAe3D;IAED;;;;;;OAMG;IACG,oBAAoB,CACxB,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,0BAA0B,GAAG,SAAS,CAAC,CA6BjD;IAED;;;;;;OAMG;IACG,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAuB1F;CACF"}

package/dist/harness/extensions/registry.js

@@ -1,4 +1,15 @@
 import * as log from "../../log.js";
+const COMMAND_NAME_PATTERN = /^[a-z0-9_-]+$/i;
+/**
+ * Parse `/name args…` slash-command text. Returns undefined when the text is
+ * not a slash command with a valid name (`COMMAND_NAME_PATTERN`).
+ */
+export function parseCommandInput(text) {
+    const match = /^\/(\S+)(?:\s+([\s\S]*))?$/.exec(text.trim());
+    if (!match || !COMMAND_NAME_PATTERN.test(match[1]))
+        return undefined;
+    return { name: match[1], args: match[2]?.trim() ?? "" };
+}
 export class ExtensionRegistry {
     constructor() {
         this.handlers = {
@@ -8,8 +19,12 @@ export class ExtensionRegistry {
             message_end: [],
             turn_end: [],
             session_compact: [],
+            agent_error: [],
+            budget_exceeded: [],
         };
         this.tools = [];
+        this.commands = new Map();
+        this.disposers = [];
     }
     register(owner, hook, handler) {
         this.handlers[hook].push({ owner, handler });
@@ -17,9 +32,74 @@ export class ExtensionRegistry {
     registerTool(tool) {
         this.tools.push(tool);
     }
+    /**
+     * Register an extension command. Invalid names throw (surfaces as an
+     * activation error for that extension); a duplicate name is logged and
+     * ignored so the first registration wins, mirroring hook isolation.
+     */
+    registerCommand(owner, command) {
+        if (!COMMAND_NAME_PATTERN.test(command.name)) {
+            throw new Error(`Invalid extension command name: ${JSON.stringify(command.name)}`);
+        }
+        const key = command.name.toLowerCase();
+        const existing = this.commands.get(key);
+        if (existing) {
+            log.logWarning(`Extension command "/${command.name}" already registered by ${existing.owner}`, `ignoring registration from ${owner}`);
+            return;
+        }
+        this.commands.set(key, { owner, command });
+    }
+    registerDisposer(owner, disposer) {
+        this.disposers.push({ owner, disposer });
+    }
     getContributedTools() {
         return [...this.tools];
     }
+    /** Registered commands, for inventory surfaces. */
+    getCommands() {
+        return [...this.commands.values()].map((entry) => entry.command);
+    }
+    /**
+     * Run the handler for `/name`, if an extension registered it. Returns true
+     * when a matching command exists — including when its handler threw (the
+     * command was consumed; the error is logged and reported to the user).
+     */
+    async dispatchCommand(name, context) {
+        const entry = this.commands.get(name.toLowerCase());
+        if (!entry)
+            return false;
+        try {
+            await entry.command.handler(context);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log.logWarning(`Extension command "/${entry.command.name}" failed (${entry.owner})`, message);
+            try {
+                await context.respond(`Command /${entry.command.name} failed: ${message}`);
+            }
+            catch {
+                // The reply channel itself failed; the log line above is the record.
+            }
+        }
+        return true;
+    }
+    /**
+     * Run all registered disposers in reverse registration order (LIFO).
+     * Disposer errors are logged and never propagate. Idempotent: disposers
+     * run once and the list is cleared.
+     */
+    async dispose() {
+        const disposers = this.disposers;
+        this.disposers = [];
+        for (const { owner, disposer } of disposers.toReversed()) {
+            try {
+                await disposer();
+            }
+            catch (err) {
+                log.logWarning(`Extension disposer failed (${owner})`, err instanceof Error ? err.message : String(err));
+            }
+        }
+    }
     hasHandlers(hook) {
         return this.handlers[hook].length > 0;
     }
@@ -41,5 +121,71 @@ export class ExtensionRegistry {
         }
         return undefined;
     }
+    /**
+     * Dispatch `before_agent_start` with merge semantics: `systemPrompt` and
+     * `prompt` rewrites chain (each handler sees the event as rewritten by
+     * earlier handlers), while `block` from ANY handler wins so a policy
+     * extension cannot be shadowed by registration order. The first block's
+     * reason is kept. Returns undefined when no handler changed anything.
+     */
+    async emitBeforeAgentStart(event) {
+        const chained = { ...event };
+        const merged = {};
+        for (const { owner, handler } of this.handlers.before_agent_start) {
+            try {
+                const result = await handler(chained);
+                if (!result)
+                    continue;
+                if (result.systemPrompt !== undefined) {
+                    merged.systemPrompt = result.systemPrompt;
+                    chained.systemPrompt = result.systemPrompt;
+                }
+                if (result.prompt !== undefined) {
+                    merged.prompt = result.prompt;
+                    chained.prompt = result.prompt;
+                }
+                if (result.block && !merged.block) {
+                    merged.block = true;
+                    merged.reason = result.reason;
+                }
+            }
+            catch (err) {
+                log.logWarning(`Extension hook "before_agent_start" failed (${owner})`, err instanceof Error ? err.message : String(err));
+            }
+        }
+        return merged.systemPrompt !== undefined || merged.prompt !== undefined || merged.block
+            ? merged
+            : undefined;
+    }
+    /**
+     * Dispatch `tool_result` with chaining semantics: each handler sees the
+     * content/isError as rewritten by earlier handlers, so e.g. a redaction
+     * extension processes the output of upstream rewriters instead of the
+     * original. Returns the accumulated override, or undefined when no handler
+     * changed anything.
+     */
+    async emitToolResult(event) {
+        const chained = { ...event };
+        const merged = {};
+        for (const { owner, handler } of this.handlers.tool_result) {
+            try {
+                const result = await handler(chained);
+                if (!result)
+                    continue;
+                if (result.content !== undefined) {
+                    merged.content = result.content;
+                    chained.content = result.content;
+                }
+                if (result.isError !== undefined) {
+                    merged.isError = result.isError;
+                    chained.isError = result.isError;
+                }
+            }
+            catch (err) {
+                log.logWarning(`Extension hook "tool_result" failed (${owner})`, err instanceof Error ? err.message : String(err));
+            }
+        }
+        return merged.content !== undefined || merged.isError !== undefined ? merged : undefined;
+    }
 }
 //# sourceMappingURL=registry.js.map

package/dist/harness/extensions/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/harness/extensions/registry.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AAOpC,MAAM,OAAO,iBAAiB;IAA9B;QACU,aAAQ,GAAiB;YAC/B,kBAAkB,EAAE,EAAE;YACtB,SAAS,EAAE,EAAE;YACb,WAAW,EAAE,EAAE;YACf,WAAW,EAAE,EAAE;YACf,QAAQ,EAAE,EAAE;YACZ,eAAe,EAAE,EAAE;SACpB,CAAC;QACM,UAAK,GAAgB,EAAE,CAAC;IAyClC,CAAC;IAvCC,QAAQ,CAA0B,KAAa,EAAE,IAAO,EAAE,OAAwB;QAChF,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,YAAY,CAAC,IAAe;QAC1B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,mBAAmB;QACjB,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,WAAW,CAAC,IAAmB;QAC7B,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IACxC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CACR,IAAO,EACP,KAAqC;QAErC,KAAK,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACrD,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAO,OAAuC,CAAC,KAAK,CAAC,CAAC;gBACrE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,OAAO,MAA8C,CAAC;gBACxD,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,GAAG,CAAC,UAAU,CACZ,mBAAmB,IAAI,aAAa,KAAK,GAAG,EAC5C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CACjD,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF","sourcesContent":["/**\n * Hook registry and dispatch for mikan extensions.\n *\n * The registry collects hook handlers and contributed tools from activated\n * extensions and dispatches events from the harness runner. Handler failures\n * are logged and swallowed so a broken extension cannot take down a run.\n */\nimport type { AgentTool } from \"@earendil-works/pi-agent-core\";\nimport * as log from \"../../log.js\";\nimport type { MikanHookMap, MikanHookName } from \"./types.js\";\n\ntype HookHandlers = {\n  [T in MikanHookName]: Array<{ owner: string; handler: MikanHookMap[T] }>;\n};\n\nexport class ExtensionRegistry {\n  private handlers: HookHandlers = {\n    before_agent_start: [],\n    tool_call: [],\n    tool_result: [],\n    message_end: [],\n    turn_end: [],\n    session_compact: [],\n  };\n  private tools: AgentTool[] = [];\n\n  register<T extends MikanHookName>(owner: string, hook: T, handler: MikanHookMap[T]): void {\n    this.handlers[hook].push({ owner, handler });\n  }\n\n  registerTool(tool: AgentTool): void {\n    this.tools.push(tool);\n  }\n\n  getContributedTools(): AgentTool[] {\n    return [...this.tools];\n  }\n\n  hasHandlers(hook: MikanHookName): boolean {\n    return this.handlers[hook].length > 0;\n  }\n\n  /**\n   * Run handlers in registration order. Returns the first non-undefined\n   * result. Handler errors are logged and skipped.\n   */\n  async emit<T extends MikanHookName>(\n    hook: T,\n    event: Parameters<MikanHookMap[T]>[0],\n  ): Promise<Awaited<ReturnType<MikanHookMap[T]>> | undefined> {\n    for (const { owner, handler } of this.handlers[hook]) {\n      try {\n        const result = await (handler as (input: unknown) => unknown)(event);\n        if (result !== undefined) {\n          return result as Awaited<ReturnType<MikanHookMap[T]>>;\n        }\n      } catch (err) {\n        log.logWarning(\n          `Extension hook \"${hook}\" failed (${owner})`,\n          err instanceof Error ? err.message : String(err),\n        );\n      }\n    }\n    return undefined;\n  }\n}\n"]}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/harness/extensions/registry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Hook registry and dispatch for mikan extensions.\n *\n * The registry collects hook handlers and contributed tools from activated\n * extensions and dispatches events from the harness runner. Handler failures\n * are logged and swallowed so a broken extension cannot take down a run.\n */\nimport type { AgentTool } from \"@earendil-works/pi-agent-core\";\nimport * as log from \"../../log.js\";\nimport type {\n  BeforeAgentStartHookEvent,\n  BeforeAgentStartHookResult,\n  ExtensionCommand,\n  ExtensionCommandContext,\n  ExtensionDisposer,\n  MikanHookMap,\n  MikanHookName,\n  ToolResultHookEvent,\n  ToolResultHookResult,\n} from \"./types.js\";\n\nconst COMMAND_NAME_PATTERN = /^[a-z0-9_-]+$/i;\n\n/**\n * Parse `/name args…` slash-command text. Returns undefined when the text is\n * not a slash command with a valid name (`COMMAND_NAME_PATTERN`).\n */\nexport function parseCommandInput(text: string): { name: string; args: string } | undefined {\n  const match = /^\\/(\\S+)(?:\\s+([\\s\\S]*))?$/.exec(text.trim());\n  if (!match || !COMMAND_NAME_PATTERN.test(match[1])) return undefined;\n  return { name: match[1], args: match[2]?.trim() ?? \"\" };\n}\n\ntype HookHandlers = {\n  [T in MikanHookName]: Array<{ owner: string; handler: MikanHookMap[T] }>;\n};\n\nexport class ExtensionRegistry {\n  private handlers: HookHandlers = {\n    before_agent_start: [],\n    tool_call: [],\n    tool_result: [],\n    message_end: [],\n    turn_end: [],\n    session_compact: [],\n    agent_error: [],\n    budget_exceeded: [],\n  };\n  private tools: AgentTool[] = [];\n  private commands = new Map<string, { owner: string; command: ExtensionCommand }>();\n  private disposers: Array<{ owner: string; disposer: ExtensionDisposer }> = [];\n\n  register<T extends MikanHookName>(owner: string, hook: T, handler: MikanHookMap[T]): void {\n    this.handlers[hook].push({ owner, handler });\n  }\n\n  registerTool(tool: AgentTool): void {\n    this.tools.push(tool);\n  }\n\n  /**\n   * Register an extension command. Invalid names throw (surfaces as an\n   * activation error for that extension); a duplicate name is logged and\n   * ignored so the first registration wins, mirroring hook isolation.\n   */\n  registerCommand(owner: string, command: ExtensionCommand): void {\n    if (!COMMAND_NAME_PATTERN.test(command.name)) {\n      throw new Error(`Invalid extension command name: ${JSON.stringify(command.name)}`);\n    }\n    const key = command.name.toLowerCase();\n    const existing = this.commands.get(key);\n    if (existing) {\n      log.logWarning(\n        `Extension command \"/${command.name}\" already registered by ${existing.owner}`,\n        `ignoring registration from ${owner}`,\n      );\n      return;\n    }\n    this.commands.set(key, { owner, command });\n  }\n\n  registerDisposer(owner: string, disposer: ExtensionDisposer): void {\n    this.disposers.push({ owner, disposer });\n  }\n\n  getContributedTools(): AgentTool[] {\n    return [...this.tools];\n  }\n\n  /** Registered commands, for inventory surfaces. */\n  getCommands(): ExtensionCommand[] {\n    return [...this.commands.values()].map((entry) => entry.command);\n  }\n\n  /**\n   * Run the handler for `/name`, if an extension registered it. Returns true\n   * when a matching command exists — including when its handler threw (the\n   * command was consumed; the error is logged and reported to the user).\n   */\n  async dispatchCommand(name: string, context: ExtensionCommandContext): Promise<boolean> {\n    const entry = this.commands.get(name.toLowerCase());\n    if (!entry) return false;\n    try {\n      await entry.command.handler(context);\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      log.logWarning(`Extension command \"/${entry.command.name}\" failed (${entry.owner})`, message);\n      try {\n        await context.respond(`Command /${entry.command.name} failed: ${message}`);\n      } catch {\n        // The reply channel itself failed; the log line above is the record.\n      }\n    }\n    return true;\n  }\n\n  /**\n   * Run all registered disposers in reverse registration order (LIFO).\n   * Disposer errors are logged and never propagate. Idempotent: disposers\n   * run once and the list is cleared.\n   */\n  async dispose(): Promise<void> {\n    const disposers = this.disposers;\n    this.disposers = [];\n    for (const { owner, disposer } of disposers.toReversed()) {\n      try {\n        await disposer();\n      } catch (err) {\n        log.logWarning(\n          `Extension disposer failed (${owner})`,\n          err instanceof Error ? err.message : String(err),\n        );\n      }\n    }\n  }\n\n  hasHandlers(hook: MikanHookName): boolean {\n    return this.handlers[hook].length > 0;\n  }\n\n  /**\n   * Run handlers in registration order. Returns the first non-undefined\n   * result. Handler errors are logged and skipped.\n   */\n  async emit<T extends MikanHookName>(\n    hook: T,\n    event: Parameters<MikanHookMap[T]>[0],\n  ): Promise<Awaited<ReturnType<MikanHookMap[T]>> | undefined> {\n    for (const { owner, handler } of this.handlers[hook]) {\n      try {\n        const result = await (handler as (input: unknown) => unknown)(event);\n        if (result !== undefined) {\n          return result as Awaited<ReturnType<MikanHookMap[T]>>;\n        }\n      } catch (err) {\n        log.logWarning(\n          `Extension hook \"${hook}\" failed (${owner})`,\n          err instanceof Error ? err.message : String(err),\n        );\n      }\n    }\n    return undefined;\n  }\n\n  /**\n   * Dispatch `before_agent_start` with merge semantics: `systemPrompt` and\n   * `prompt` rewrites chain (each handler sees the event as rewritten by\n   * earlier handlers), while `block` from ANY handler wins so a policy\n   * extension cannot be shadowed by registration order. The first block's\n   * reason is kept. Returns undefined when no handler changed anything.\n   */\n  async emitBeforeAgentStart(\n    event: BeforeAgentStartHookEvent,\n  ): Promise<BeforeAgentStartHookResult | undefined> {\n    const chained: BeforeAgentStartHookEvent = { ...event };\n    const merged: BeforeAgentStartHookResult = {};\n    for (const { owner, handler } of this.handlers.before_agent_start) {\n      try {\n        const result = await handler(chained);\n        if (!result) continue;\n        if (result.systemPrompt !== undefined) {\n          merged.systemPrompt = result.systemPrompt;\n          chained.systemPrompt = result.systemPrompt;\n        }\n        if (result.prompt !== undefined) {\n          merged.prompt = result.prompt;\n          chained.prompt = result.prompt;\n        }\n        if (result.block && !merged.block) {\n          merged.block = true;\n          merged.reason = result.reason;\n        }\n      } catch (err) {\n        log.logWarning(\n          `Extension hook \"before_agent_start\" failed (${owner})`,\n          err instanceof Error ? err.message : String(err),\n        );\n      }\n    }\n    return merged.systemPrompt !== undefined || merged.prompt !== undefined || merged.block\n      ? merged\n      : undefined;\n  }\n\n  /**\n   * Dispatch `tool_result` with chaining semantics: each handler sees the\n   * content/isError as rewritten by earlier handlers, so e.g. a redaction\n   * extension processes the output of upstream rewriters instead of the\n   * original. Returns the accumulated override, or undefined when no handler\n   * changed anything.\n   */\n  async emitToolResult(event: ToolResultHookEvent): Promise<ToolResultHookResult | undefined> {\n    const chained: ToolResultHookEvent = { ...event };\n    const merged: ToolResultHookResult = {};\n    for (const { owner, handler } of this.handlers.tool_result) {\n      try {\n        const result = await handler(chained);\n        if (!result) continue;\n        if (result.content !== undefined) {\n          merged.content = result.content;\n          chained.content = result.content;\n        }\n        if (result.isError !== undefined) {\n          merged.isError = result.isError;\n          chained.isError = result.isError;\n        }\n      } catch (err) {\n        log.logWarning(\n          `Extension hook \"tool_result\" failed (${owner})`,\n          err instanceof Error ? err.message : String(err),\n        );\n      }\n    }\n    return merged.content !== undefined || merged.isError !== undefined ? merged : undefined;\n  }\n}\n"]}

package/dist/harness/extensions/types.d.ts

@@ -17,27 +17,58 @@
  * }
  * ```
  *
- * Hooks run in registration order. For hooks with results, the first
- * non-undefined result wins (v1 semantics; later versions may merge).
+ * Hooks run in registration order. Result semantics are per hook:
+ * `tool_call` keeps v1's first-non-undefined-wins; `before_agent_start` and
+ * `tool_result` chain — each handler sees the event as rewritten by earlier
+ * handlers, and for `before_agent_start` a `block` from any handler wins.
  * Hook errors are logged and never crash a run.
  */
 import type { AgentMessage, AgentTool, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, ImageContent, Model, TextContent } from "@earendil-works/pi-ai";
 import type { MikanSkill } from "../skills.js";
 import type { CompactionEntry } from "../types.js";
+/**
+ * Platform provenance of the run a hook event belongs to. Interactive runs
+ * carry the triggering message's identity (usable with `api.react` and for
+ * per-user policy); autonomous runs (schedules/events) have no triggering
+ * platform message, so only `kind` and `platform` are set.
+ */
+export interface RunOrigin {
+    kind: "interactive" | "event";
+    /** Platform adapter name serving this run (e.g. "slack"). */
+    platform?: string;
+    /** Platform message id of the triggering message; pass to `api.react`. */
+    messageTs?: string;
+    userId?: string;
+    userName?: string;
+    threadTs?: string;
+    /** Attachments already downloaded to host paths (extensions run on host). */
+    attachments?: {
+        name: string;
+        localPath: string;
+    }[];
+}
 export interface BeforeAgentStartHookEvent {
     prompt: string;
     images?: ImageContent[];
     systemPrompt: string;
+    origin?: RunOrigin;
 }
 export interface BeforeAgentStartHookResult {
     /** Replace the system prompt for this turn. */
     systemPrompt?: string;
+    /** Rewrite the user prompt for this turn. */
+    prompt?: string;
+    /** Block the turn entirely; the model is never called and nothing persists. */
+    block?: boolean;
+    /** Shown to the user when the turn is blocked. */
+    reason?: string;
 }
 export interface ToolCallHookEvent {
     toolCallId: string;
     toolName: string;
     args: unknown;
+    origin?: RunOrigin;
 }
 export interface ToolCallHookResult {
     /** Block the tool call; the model receives an error tool result instead. */
@@ -50,25 +81,51 @@ export interface ToolResultHookEvent {
     args: unknown;
     content: (TextContent | ImageContent)[];
     isError: boolean;
+    origin?: RunOrigin;
+}
+export interface ToolResultHookResult {
+    /** Replace the tool result content sent back to the model (e.g. redaction). */
+    content?: (TextContent | ImageContent)[];
+    /** Override the tool result error flag. */
+    isError?: boolean;
 }
 export interface MessageEndHookEvent {
     message: AgentMessage;
+    origin?: RunOrigin;
 }
 export interface TurnEndHookEvent {
     messages: AgentMessage[];
+    origin?: RunOrigin;
 }
 export interface SessionCompactHookEvent {
     entry: CompactionEntry;
     reason: "threshold" | "overflow" | "manual";
 }
+/** A turn settled with an error after retries were exhausted (or none applied). */
+export interface AgentErrorHookEvent {
+    errorMessage: string;
+    origin?: RunOrigin;
+}
+/** The run budget circuit breaker tripped and the run was aborted. */
+export interface BudgetExceededHookEvent {
+    /** Which cap was hit, e.g. "cost 2.01 USD >= 2 USD limit". */
+    reason: string;
+    tokens: number;
+    costUsd: number;
+    llmCalls: number;
+    durationMs: number;
+    origin?: RunOrigin;
+}
 /** Map of hook names to handler signatures. */
 export interface MikanHookMap {
     before_agent_start: (event: BeforeAgentStartHookEvent) => BeforeAgentStartHookResult | undefined | void | Promise<BeforeAgentStartHookResult | undefined | void>;
     tool_call: (event: ToolCallHookEvent) => ToolCallHookResult | undefined | void | Promise<ToolCallHookResult | undefined | void>;
-    tool_result: (event: ToolResultHookEvent) => void | Promise<void>;
+    tool_result: (event: ToolResultHookEvent) => ToolResultHookResult | undefined | void | Promise<ToolResultHookResult | undefined | void>;
     message_end: (event: MessageEndHookEvent) => void | Promise<void>;
     turn_end: (event: TurnEndHookEvent) => void | Promise<void>;
     session_compact: (event: SessionCompactHookEvent) => void | Promise<void>;
+    agent_error: (event: AgentErrorHookEvent) => void | Promise<void>;
+    budget_exceeded: (event: BudgetExceededHookEvent) => void | Promise<void>;
 }
 export type MikanHookName = keyof MikanHookMap;
 /**
@@ -100,10 +157,11 @@ export interface ExtensionScheduleInfo {
 /**
  * Event-file payload the harness hands to the embedder's schedule store.
  * Mirrors mikan's event-file shape; `platform` may be omitted when the
- * embedder runs a single platform.
+ * embedder runs a single platform. `immediate` backs `api.triggerRun` —
+ * the event fires as soon as the embedder's watcher picks it up.
  */
 export interface ExtensionSchedulePayload {
-    type: "one-shot" | "periodic";
+    type: "one-shot" | "periodic" | "immediate";
     conversationId: string;
     text: string;
     platform?: string;
@@ -111,6 +169,31 @@ export interface ExtensionSchedulePayload {
     schedule?: string;
     timezone?: string;
 }
+/** Cleanup callback run when the harness instance owning the extension is discarded. */
+export type ExtensionDisposer = () => void | Promise<void>;
+/** Context handed to an extension command handler for one invocation. */
+export interface ExtensionCommandContext {
+    /** Text after the command name, trimmed ("" when none). */
+    args: string;
+    conversationId: string;
+    userId?: string;
+    userName?: string;
+    /** Reply in the conversation the command was sent from. */
+    respond(text: string): Promise<void>;
+}
+/**
+ * A chat command contributed by an extension (`/name args…`). Dispatched
+ * deterministically by the embedder — no model call, no agent-session entry
+ * (the triggering message still syncs to chat history).
+ * Built-in commands always win over extension commands of the same name.
+ */
+export interface ExtensionCommand {
+    /** Command name without the leading slash; `[a-z0-9_-]+`, case-insensitive match. */
+    name: string;
+    /** One-line description for inventory surfaces. */
+    description?: string;
+    handler: (context: ExtensionCommandContext) => void | Promise<void>;
+}
 /**
  * Persistence backend for extension schedules, injected by the embedder
  * (mikan backs this with event files watched by its EventsWatcher).
@@ -139,6 +222,8 @@ export interface ExtensionHostServices {
     postMessage?: (conversationId: string, text: string, platform?: string) => Promise<void>;
     /** Add an emoji reaction to a message; enables `api.react`. */
     addReaction?: (conversationId: string, messageTs: string, emoji: string, platform?: string) => Promise<void>;
+    /** Upload a host file into a conversation; enables `api.uploadFile`. */
+    uploadFile?: (conversationId: string, filePath: string, title?: string, platform?: string) => Promise<void>;
     /** Resolve read-only secrets for an extension slug; enables `api.secrets`. */
     resolveSecrets?: (slug: string) => Record<string, string>;
 }
@@ -159,6 +244,17 @@ export interface MikanExtensionApi {
     on<T extends MikanHookName>(hook: T, handler: MikanHookMap[T]): void;
     /** Contribute an additional agent tool. */
     registerTool(tool: AgentTool): void;
+    /**
+     * Contribute a chat command (`/name`). Dispatched without a model call;
+     * built-in commands and earlier registrations of the same name win.
+     */
+    registerCommand(command: ExtensionCommand): void;
+    /**
+     * Register cleanup to run when this harness instance is discarded
+     * (`/pi-new`, session eviction, shutdown). Alternative to returning a
+     * disposer from `activate`. Disposers run in reverse registration order.
+     */
+    onDispose(disposer: ExtensionDisposer): void;
     /** Extension-scoped logging that lands in mikan's structured log. */
     log(message: string): void;
     /** Context about the conversation this harness instance serves. */
@@ -214,19 +310,34 @@ export interface MikanExtensionApi {
         list(): Promise<ExtensionScheduleInfo[]>;
     };
     /**
-     * Post text into this conversation without triggering an agent run.
-     * Available when the embedder provides platform messaging.
+     * Post text into a conversation without triggering an agent run. Defaults
+     * to this conversation; pass `conversationId` to post elsewhere (pairs
+     * with `sharedDataDir` for cross-conversation applications). Available
+     * when the embedder provides platform messaging.
      */
-    notify(text: string): Promise<void>;
+    notify(text: string, options?: {
+        conversationId?: string;
+    }): Promise<void>;
     /**
      * Add an emoji reaction to a message in this conversation. `messageTs` is
-     * the platform message id the extension read from an event; `emoji` is a
-     * short name without colons. Available when the embedder provides reaction
-     * support.
+     * the platform message id the extension read from an event (see
+     * `RunOrigin.messageTs`); `emoji` is a short name without colons.
+     * Available when the embedder provides reaction support.
      */
     react(messageTs: string, emoji: string): Promise<void>;
+    /**
+     * Upload a host-side file into this conversation without an agent run.
+     * Available when the embedder provides file uploads for the platform.
+     */
+    uploadFile(filePath: string, title?: string): Promise<void>;
+    /**
+     * Fire an autonomous agent run in this conversation as soon as possible.
+     * Like a schedule, the run does not inherit conversation history — write
+     * `text` self-contained. Backed by the embedder's schedule store.
+     */
+    triggerRun(text: string): Promise<void>;
 }
-export type MikanExtensionActivate = (api: MikanExtensionApi) => void | Promise<void>;
+export type MikanExtensionActivate = (api: MikanExtensionApi) => void | ExtensionDisposer | Promise<void | ExtensionDisposer>;
 export interface MikanExtensionModule {
     name?: string;
     activate: MikanExtensionActivate;

package/dist/harness/extensions/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/harness/extensions/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/harness/extensions/types.ts"],"names":[],"mappings":"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"}

package/dist/harness/extensions/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/harness/extensions/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * mikan extension system, v1.\n *\n * Extensions are ES modules that export an `activate` function (either as\n * the default export or a named `activate` export, optionally wrapped in an\n * object that also carries a `name`). `activate` receives a\n * {@link MikanExtensionApi} and registers hooks and tools.\n *\n * ```js\n * // extensions/audit.mjs\n * export default function activate(api) {\n *   api.on(\"tool_call\", ({ toolName, args }) => {\n *     if (toolName === \"bash\" && String(args.command).includes(\"rm -rf /\")) {\n *       return { block: true, reason: \"destructive command\" };\n *     }\n *   });\n * }\n * ```\n *\n * Hooks run in registration order. For hooks with results, the first\n * non-undefined result wins (v1 semantics; later versions may merge).\n * Hook errors are logged and never crash a run.\n */\nimport type { AgentMessage, AgentTool, ThinkingLevel } from \"@earendil-works/pi-agent-core\";\nimport type { Api, ImageContent, Model, TextContent } from \"@earendil-works/pi-ai\";\nimport type { MikanSkill } from \"../skills.js\";\nimport type { CompactionEntry } from \"../types.js\";\n\nexport interface BeforeAgentStartHookEvent {\n  prompt: string;\n  images?: ImageContent[];\n  systemPrompt: string;\n}\n\nexport interface BeforeAgentStartHookResult {\n  /** Replace the system prompt for this turn. */\n  systemPrompt?: string;\n}\n\nexport interface ToolCallHookEvent {\n  toolCallId: string;\n  toolName: string;\n  args: unknown;\n}\n\nexport interface ToolCallHookResult {\n  /** Block the tool call; the model receives an error tool result instead. */\n  block?: boolean;\n  reason?: string;\n}\n\nexport interface ToolResultHookEvent {\n  toolCallId: string;\n  toolName: string;\n  args: unknown;\n  content: (TextContent | ImageContent)[];\n  isError: boolean;\n}\n\nexport interface MessageEndHookEvent {\n  message: AgentMessage;\n}\n\nexport interface TurnEndHookEvent {\n  messages: AgentMessage[];\n}\n\nexport interface SessionCompactHookEvent {\n  entry: CompactionEntry;\n  reason: \"threshold\" | \"overflow\" | \"manual\";\n}\n\n/** Map of hook names to handler signatures. */\nexport interface MikanHookMap {\n  before_agent_start: (\n    event: BeforeAgentStartHookEvent,\n  ) =>\n    | BeforeAgentStartHookResult\n    | undefined\n    | void\n    | Promise<BeforeAgentStartHookResult | undefined | void>;\n  tool_call: (\n    event: ToolCallHookEvent,\n  ) => ToolCallHookResult | undefined | void | Promise<ToolCallHookResult | undefined | void>;\n  tool_result: (event: ToolResultHookEvent) => void | Promise<void>;\n  message_end: (event: MessageEndHookEvent) => void | Promise<void>;\n  turn_end: (event: TurnEndHookEvent) => void | Promise<void>;\n  session_compact: (event: SessionCompactHookEvent) => void | Promise<void>;\n}\n\nexport type MikanHookName = keyof MikanHookMap;\n\n// ── v2: schedules ────────────────────────────────────────────────────────────\n\n/**\n * A schedule contributed by an extension. Fires an autonomous agent run in\n * this conversation with `text` as the task prompt (the run does not inherit\n * conversation history — write `text` self-contained).\n */\nexport type ExtensionScheduleSpec =\n  | {\n      type: \"periodic\";\n      /** Cron expression (croner syntax). */\n      schedule: string;\n      /** IANA timezone, e.g. \"Asia/Taipei\". */\n      timezone: string;\n      text: string;\n      /** Target platform; optional when only one platform is running. */\n      platform?: string;\n    }\n  | {\n      type: \"one-shot\";\n      /** ISO 8601 timestamp with offset. */\n      at: string;\n      text: string;\n      platform?: string;\n    };\n\nexport interface ExtensionScheduleInfo {\n  /** Extension-chosen schedule name. */\n  name: string;\n  spec: ExtensionScheduleSpec;\n}\n\n/**\n * Event-file payload the harness hands to the embedder's schedule store.\n * Mirrors mikan's event-file shape; `platform` may be omitted when the\n * embedder runs a single platform.\n */\nexport interface ExtensionSchedulePayload {\n  type: \"one-shot\" | \"periodic\";\n  conversationId: string;\n  text: string;\n  platform?: string;\n  at?: string;\n  schedule?: string;\n  timezone?: string;\n}\n\n// ── v2: embedder-injected services ───────────────────────────────────────────\n\n/**\n * Persistence backend for extension schedules, injected by the embedder\n * (mikan backs this with event files watched by its EventsWatcher).\n * Filenames are fully qualified by the harness (`ext-<slug>-<name>.json`).\n */\nexport interface ExtensionScheduleStore {\n  write(filename: string, payload: ExtensionSchedulePayload): Promise<void>;\n  delete(filename: string): Promise<boolean>;\n  /** List all schedule files, harness filters by ownership prefix. */\n  list(): Promise<Array<{ filename: string; payload: ExtensionSchedulePayload }>>;\n}\n\n/**\n * Host services injected into extensions by the embedder. All fields are\n * optional: the corresponding api surface throws an informative error when\n * the running context does not provide the service.\n */\nexport interface ExtensionHostServices {\n  /** State dir for per-extension data dirs; defaults to `~/.mikan`. */\n  stateDir?: string;\n  /** Schedule persistence; enables `api.schedules`. */\n  scheduleStore?: ExtensionScheduleStore;\n  /** Post a message to a conversation without an agent run; enables `api.notify`. */\n  postMessage?: (conversationId: string, text: string, platform?: string) => Promise<void>;\n  /** Add an emoji reaction to a message; enables `api.react`. */\n  addReaction?: (\n    conversationId: string,\n    messageTs: string,\n    emoji: string,\n    platform?: string,\n  ) => Promise<void>;\n  /** Resolve read-only secrets for an extension slug; enables `api.secrets`. */\n  resolveSecrets?: (slug: string) => Record<string, string>;\n}\n\n// ── v2: manifest ─────────────────────────────────────────────────────────────\n\n/**\n * Optional `manifest.json` next to a directory-form extension's entrypoint.\n * `name` is the display name only; the slug (data dir, secrets, schedule\n * ownership) always derives from the install path so identity is\n * admin-controlled and stable across manifest edits.\n */\nexport interface ExtensionManifest {\n  name?: string;\n  version?: string;\n  description?: string;\n}\n\n/** API handed to an extension's `activate` function. */\nexport interface MikanExtensionApi {\n  /** Register a hook handler. */\n  on<T extends MikanHookName>(hook: T, handler: MikanHookMap[T]): void;\n  /** Contribute an additional agent tool. */\n  registerTool(tool: AgentTool): void;\n  /** Extension-scoped logging that lands in mikan's structured log. */\n  log(message: string): void;\n  /** Context about the conversation this harness instance serves. */\n  readonly context: {\n    readonly conversationId: string;\n    readonly workspaceDir: string;\n    readonly model: Model<Api>;\n    readonly thinkingLevel: ThinkingLevel;\n  };\n  /**\n   * Host-only filesystem locations owned by this extension (never mounted\n   * into sandbox containers). Which one you use is a declaration: `dataDir`\n   * for conversation-scoped state (the safe default — isolation for free),\n   * `sharedDataDir` for deliberately cross-conversation state (you own tenant\n   * partitioning and concurrency). See `LAYOUT.md`.\n   */\n  readonly paths: {\n    /**\n     * This conversation's private data directory\n     * (`conversations/<conversationId>/extension-data/<slug>`), created on\n     * first access. Default choice: co-located with the conversation, so it\n     * disappears when the conversation is deleted.\n     */\n    readonly dataDir: string;\n    /**\n     * Data shared across all conversations this extension serves\n     * (`global/extension-data/<slug>`), created on first access. Explicit\n     * opt-in for multi-conversation applications (e.g. a PM tool with\n     * cross-channel views); key rows by conversation id yourself.\n     */\n    readonly sharedDataDir: string;\n  };\n  /**\n   * Read-only secrets from the embedder's vault\n   * (mikan: `<stateDir>/vaults/extensions/<slug>/env`).\n   */\n  readonly secrets: {\n    get(key: string): string | undefined;\n    /** Secret names only, never values. */\n    list(): string[];\n  };\n  /**\n   * Named schedules owned by this extension + conversation. Backed by the\n   * embedder's schedule store; in mikan these become event files that fire\n   * autonomous agent runs (hot-reloaded, persisted across restarts).\n   */\n  readonly schedules: {\n    /** Create or replace a named schedule. */\n    upsert(name: string, spec: ExtensionScheduleSpec): Promise<void>;\n    /** Delete a named schedule. Returns false when it did not exist. */\n    delete(name: string): Promise<boolean>;\n    /** Schedules owned by this extension in this conversation. */\n    list(): Promise<ExtensionScheduleInfo[]>;\n  };\n  /**\n   * Post text into this conversation without triggering an agent run.\n   * Available when the embedder provides platform messaging.\n   */\n  notify(text: string): Promise<void>;\n  /**\n   * Add an emoji reaction to a message in this conversation. `messageTs` is\n   * the platform message id the extension read from an event; `emoji` is a\n   * short name without colons. Available when the embedder provides reaction\n   * support.\n   */\n  react(messageTs: string, emoji: string): Promise<void>;\n}\n\nexport type MikanExtensionActivate = (api: MikanExtensionApi) => void | Promise<void>;\n\nexport interface MikanExtensionModule {\n  name?: string;\n  activate: MikanExtensionActivate;\n}\n\nexport interface LoadedExtension {\n  name: string;\n  path: string;\n  /** Filesystem-safe identifier used for data dirs, secrets, and schedules. */\n  slug: string;\n  version?: string;\n  description?: string;\n  /** Skills discovered under the extension's `skills/` directory. */\n  skills: MikanSkill[];\n}\n\nexport interface ExtensionLoadError {\n  path: string;\n  error: string;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/harness/extensions/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * mikan extension system, v1.\n *\n * Extensions are ES modules that export an `activate` function (either as\n * the default export or a named `activate` export, optionally wrapped in an\n * object that also carries a `name`). `activate` receives a\n * {@link MikanExtensionApi} and registers hooks and tools.\n *\n * ```js\n * // extensions/audit.mjs\n * export default function activate(api) {\n *   api.on(\"tool_call\", ({ toolName, args }) => {\n *     if (toolName === \"bash\" && String(args.command).includes(\"rm -rf /\")) {\n *       return { block: true, reason: \"destructive command\" };\n *     }\n *   });\n * }\n * ```\n *\n * Hooks run in registration order. Result semantics are per hook:\n * `tool_call` keeps v1's first-non-undefined-wins; `before_agent_start` and\n * `tool_result` chain — each handler sees the event as rewritten by earlier\n * handlers, and for `before_agent_start` a `block` from any handler wins.\n * Hook errors are logged and never crash a run.\n */\nimport type { AgentMessage, AgentTool, ThinkingLevel } from \"@earendil-works/pi-agent-core\";\nimport type { Api, ImageContent, Model, TextContent } from \"@earendil-works/pi-ai\";\nimport type { MikanSkill } from \"../skills.js\";\nimport type { CompactionEntry } from \"../types.js\";\n\n/**\n * Platform provenance of the run a hook event belongs to. Interactive runs\n * carry the triggering message's identity (usable with `api.react` and for\n * per-user policy); autonomous runs (schedules/events) have no triggering\n * platform message, so only `kind` and `platform` are set.\n */\nexport interface RunOrigin {\n  kind: \"interactive\" | \"event\";\n  /** Platform adapter name serving this run (e.g. \"slack\"). */\n  platform?: string;\n  /** Platform message id of the triggering message; pass to `api.react`. */\n  messageTs?: string;\n  userId?: string;\n  userName?: string;\n  threadTs?: string;\n  /** Attachments already downloaded to host paths (extensions run on host). */\n  attachments?: { name: string; localPath: string }[];\n}\n\nexport interface BeforeAgentStartHookEvent {\n  prompt: string;\n  images?: ImageContent[];\n  systemPrompt: string;\n  origin?: RunOrigin;\n}\n\nexport interface BeforeAgentStartHookResult {\n  /** Replace the system prompt for this turn. */\n  systemPrompt?: string;\n  /** Rewrite the user prompt for this turn. */\n  prompt?: string;\n  /** Block the turn entirely; the model is never called and nothing persists. */\n  block?: boolean;\n  /** Shown to the user when the turn is blocked. */\n  reason?: string;\n}\n\nexport interface ToolCallHookEvent {\n  toolCallId: string;\n  toolName: string;\n  args: unknown;\n  origin?: RunOrigin;\n}\n\nexport interface ToolCallHookResult {\n  /** Block the tool call; the model receives an error tool result instead. */\n  block?: boolean;\n  reason?: string;\n}\n\nexport interface ToolResultHookEvent {\n  toolCallId: string;\n  toolName: string;\n  args: unknown;\n  content: (TextContent | ImageContent)[];\n  isError: boolean;\n  origin?: RunOrigin;\n}\n\nexport interface ToolResultHookResult {\n  /** Replace the tool result content sent back to the model (e.g. redaction). */\n  content?: (TextContent | ImageContent)[];\n  /** Override the tool result error flag. */\n  isError?: boolean;\n}\n\nexport interface MessageEndHookEvent {\n  message: AgentMessage;\n  origin?: RunOrigin;\n}\n\nexport interface TurnEndHookEvent {\n  messages: AgentMessage[];\n  origin?: RunOrigin;\n}\n\nexport interface SessionCompactHookEvent {\n  entry: CompactionEntry;\n  reason: \"threshold\" | \"overflow\" | \"manual\";\n}\n\n/** A turn settled with an error after retries were exhausted (or none applied). */\nexport interface AgentErrorHookEvent {\n  errorMessage: string;\n  origin?: RunOrigin;\n}\n\n/** The run budget circuit breaker tripped and the run was aborted. */\nexport interface BudgetExceededHookEvent {\n  /** Which cap was hit, e.g. \"cost 2.01 USD >= 2 USD limit\". */\n  reason: string;\n  tokens: number;\n  costUsd: number;\n  llmCalls: number;\n  durationMs: number;\n  origin?: RunOrigin;\n}\n\n/** Map of hook names to handler signatures. */\nexport interface MikanHookMap {\n  before_agent_start: (\n    event: BeforeAgentStartHookEvent,\n  ) =>\n    | BeforeAgentStartHookResult\n    | undefined\n    | void\n    | Promise<BeforeAgentStartHookResult | undefined | void>;\n  tool_call: (\n    event: ToolCallHookEvent,\n  ) => ToolCallHookResult | undefined | void | Promise<ToolCallHookResult | undefined | void>;\n  tool_result: (\n    event: ToolResultHookEvent,\n  ) => ToolResultHookResult | undefined | void | Promise<ToolResultHookResult | undefined | void>;\n  message_end: (event: MessageEndHookEvent) => void | Promise<void>;\n  turn_end: (event: TurnEndHookEvent) => void | Promise<void>;\n  session_compact: (event: SessionCompactHookEvent) => void | Promise<void>;\n  agent_error: (event: AgentErrorHookEvent) => void | Promise<void>;\n  budget_exceeded: (event: BudgetExceededHookEvent) => void | Promise<void>;\n}\n\nexport type MikanHookName = keyof MikanHookMap;\n\n// ── v2: schedules ────────────────────────────────────────────────────────────\n\n/**\n * A schedule contributed by an extension. Fires an autonomous agent run in\n * this conversation with `text` as the task prompt (the run does not inherit\n * conversation history — write `text` self-contained).\n */\nexport type ExtensionScheduleSpec =\n  | {\n      type: \"periodic\";\n      /** Cron expression (croner syntax). */\n      schedule: string;\n      /** IANA timezone, e.g. \"Asia/Taipei\". */\n      timezone: string;\n      text: string;\n      /** Target platform; optional when only one platform is running. */\n      platform?: string;\n    }\n  | {\n      type: \"one-shot\";\n      /** ISO 8601 timestamp with offset. */\n      at: string;\n      text: string;\n      platform?: string;\n    };\n\nexport interface ExtensionScheduleInfo {\n  /** Extension-chosen schedule name. */\n  name: string;\n  spec: ExtensionScheduleSpec;\n}\n\n/**\n * Event-file payload the harness hands to the embedder's schedule store.\n * Mirrors mikan's event-file shape; `platform` may be omitted when the\n * embedder runs a single platform. `immediate` backs `api.triggerRun` —\n * the event fires as soon as the embedder's watcher picks it up.\n */\nexport interface ExtensionSchedulePayload {\n  type: \"one-shot\" | \"periodic\" | \"immediate\";\n  conversationId: string;\n  text: string;\n  platform?: string;\n  at?: string;\n  schedule?: string;\n  timezone?: string;\n}\n\n// ── v3: commands and lifecycle ───────────────────────────────────────────────\n\n/** Cleanup callback run when the harness instance owning the extension is discarded. */\nexport type ExtensionDisposer = () => void | Promise<void>;\n\n/** Context handed to an extension command handler for one invocation. */\nexport interface ExtensionCommandContext {\n  /** Text after the command name, trimmed (\"\" when none). */\n  args: string;\n  conversationId: string;\n  userId?: string;\n  userName?: string;\n  /** Reply in the conversation the command was sent from. */\n  respond(text: string): Promise<void>;\n}\n\n/**\n * A chat command contributed by an extension (`/name args…`). Dispatched\n * deterministically by the embedder — no model call, no agent-session entry\n * (the triggering message still syncs to chat history).\n * Built-in commands always win over extension commands of the same name.\n */\nexport interface ExtensionCommand {\n  /** Command name without the leading slash; `[a-z0-9_-]+`, case-insensitive match. */\n  name: string;\n  /** One-line description for inventory surfaces. */\n  description?: string;\n  handler: (context: ExtensionCommandContext) => void | Promise<void>;\n}\n\n// ── v2: embedder-injected services ───────────────────────────────────────────\n\n/**\n * Persistence backend for extension schedules, injected by the embedder\n * (mikan backs this with event files watched by its EventsWatcher).\n * Filenames are fully qualified by the harness (`ext-<slug>-<name>.json`).\n */\nexport interface ExtensionScheduleStore {\n  write(filename: string, payload: ExtensionSchedulePayload): Promise<void>;\n  delete(filename: string): Promise<boolean>;\n  /** List all schedule files, harness filters by ownership prefix. */\n  list(): Promise<Array<{ filename: string; payload: ExtensionSchedulePayload }>>;\n}\n\n/**\n * Host services injected into extensions by the embedder. All fields are\n * optional: the corresponding api surface throws an informative error when\n * the running context does not provide the service.\n */\nexport interface ExtensionHostServices {\n  /** State dir for per-extension data dirs; defaults to `~/.mikan`. */\n  stateDir?: string;\n  /** Schedule persistence; enables `api.schedules`. */\n  scheduleStore?: ExtensionScheduleStore;\n  /** Post a message to a conversation without an agent run; enables `api.notify`. */\n  postMessage?: (conversationId: string, text: string, platform?: string) => Promise<void>;\n  /** Add an emoji reaction to a message; enables `api.react`. */\n  addReaction?: (\n    conversationId: string,\n    messageTs: string,\n    emoji: string,\n    platform?: string,\n  ) => Promise<void>;\n  /** Upload a host file into a conversation; enables `api.uploadFile`. */\n  uploadFile?: (\n    conversationId: string,\n    filePath: string,\n    title?: string,\n    platform?: string,\n  ) => Promise<void>;\n  /** Resolve read-only secrets for an extension slug; enables `api.secrets`. */\n  resolveSecrets?: (slug: string) => Record<string, string>;\n}\n\n// ── v2: manifest ─────────────────────────────────────────────────────────────\n\n/**\n * Optional `manifest.json` next to a directory-form extension's entrypoint.\n * `name` is the display name only; the slug (data dir, secrets, schedule\n * ownership) always derives from the install path so identity is\n * admin-controlled and stable across manifest edits.\n */\nexport interface ExtensionManifest {\n  name?: string;\n  version?: string;\n  description?: string;\n}\n\n/** API handed to an extension's `activate` function. */\nexport interface MikanExtensionApi {\n  /** Register a hook handler. */\n  on<T extends MikanHookName>(hook: T, handler: MikanHookMap[T]): void;\n  /** Contribute an additional agent tool. */\n  registerTool(tool: AgentTool): void;\n  /**\n   * Contribute a chat command (`/name`). Dispatched without a model call;\n   * built-in commands and earlier registrations of the same name win.\n   */\n  registerCommand(command: ExtensionCommand): void;\n  /**\n   * Register cleanup to run when this harness instance is discarded\n   * (`/pi-new`, session eviction, shutdown). Alternative to returning a\n   * disposer from `activate`. Disposers run in reverse registration order.\n   */\n  onDispose(disposer: ExtensionDisposer): void;\n  /** Extension-scoped logging that lands in mikan's structured log. */\n  log(message: string): void;\n  /** Context about the conversation this harness instance serves. */\n  readonly context: {\n    readonly conversationId: string;\n    readonly workspaceDir: string;\n    readonly model: Model<Api>;\n    readonly thinkingLevel: ThinkingLevel;\n  };\n  /**\n   * Host-only filesystem locations owned by this extension (never mounted\n   * into sandbox containers). Which one you use is a declaration: `dataDir`\n   * for conversation-scoped state (the safe default — isolation for free),\n   * `sharedDataDir` for deliberately cross-conversation state (you own tenant\n   * partitioning and concurrency). See `LAYOUT.md`.\n   */\n  readonly paths: {\n    /**\n     * This conversation's private data directory\n     * (`conversations/<conversationId>/extension-data/<slug>`), created on\n     * first access. Default choice: co-located with the conversation, so it\n     * disappears when the conversation is deleted.\n     */\n    readonly dataDir: string;\n    /**\n     * Data shared across all conversations this extension serves\n     * (`global/extension-data/<slug>`), created on first access. Explicit\n     * opt-in for multi-conversation applications (e.g. a PM tool with\n     * cross-channel views); key rows by conversation id yourself.\n     */\n    readonly sharedDataDir: string;\n  };\n  /**\n   * Read-only secrets from the embedder's vault\n   * (mikan: `<stateDir>/vaults/extensions/<slug>/env`).\n   */\n  readonly secrets: {\n    get(key: string): string | undefined;\n    /** Secret names only, never values. */\n    list(): string[];\n  };\n  /**\n   * Named schedules owned by this extension + conversation. Backed by the\n   * embedder's schedule store; in mikan these become event files that fire\n   * autonomous agent runs (hot-reloaded, persisted across restarts).\n   */\n  readonly schedules: {\n    /** Create or replace a named schedule. */\n    upsert(name: string, spec: ExtensionScheduleSpec): Promise<void>;\n    /** Delete a named schedule. Returns false when it did not exist. */\n    delete(name: string): Promise<boolean>;\n    /** Schedules owned by this extension in this conversation. */\n    list(): Promise<ExtensionScheduleInfo[]>;\n  };\n  /**\n   * Post text into a conversation without triggering an agent run. Defaults\n   * to this conversation; pass `conversationId` to post elsewhere (pairs\n   * with `sharedDataDir` for cross-conversation applications). Available\n   * when the embedder provides platform messaging.\n   */\n  notify(text: string, options?: { conversationId?: string }): Promise<void>;\n  /**\n   * Add an emoji reaction to a message in this conversation. `messageTs` is\n   * the platform message id the extension read from an event (see\n   * `RunOrigin.messageTs`); `emoji` is a short name without colons.\n   * Available when the embedder provides reaction support.\n   */\n  react(messageTs: string, emoji: string): Promise<void>;\n  /**\n   * Upload a host-side file into this conversation without an agent run.\n   * Available when the embedder provides file uploads for the platform.\n   */\n  uploadFile(filePath: string, title?: string): Promise<void>;\n  /**\n   * Fire an autonomous agent run in this conversation as soon as possible.\n   * Like a schedule, the run does not inherit conversation history — write\n   * `text` self-contained. Backed by the embedder's schedule store.\n   */\n  triggerRun(text: string): Promise<void>;\n}\n\nexport type MikanExtensionActivate = (\n  api: MikanExtensionApi,\n) => void | ExtensionDisposer | Promise<void | ExtensionDisposer>;\n\nexport interface MikanExtensionModule {\n  name?: string;\n  activate: MikanExtensionActivate;\n}\n\nexport interface LoadedExtension {\n  name: string;\n  path: string;\n  /** Filesystem-safe identifier used for data dirs, secrets, and schedules. */\n  slug: string;\n  version?: string;\n  description?: string;\n  /** Skills discovered under the extension's `skills/` directory. */\n  skills: MikanSkill[];\n}\n\nexport interface ExtensionLoadError {\n  path: string;\n  error: string;\n}\n"]}

package/dist/harness/index.d.ts

@@ -9,11 +9,11 @@ export { FileCredentialStore, defaultAuthPath } from "./auth.js";
 export { DEFAULT_HTTP_IDLE_TIMEOUT_MS, configureHttpDispatcher, parseHttpIdleTimeoutMs, } from "./http.js";
 export { MikanModels, defaultModelsJsonPath, type CreateMikanModelsOptions } from "./models.js";
 export { SessionStore, loadSessionFileEntries, parseSessionFileEntries } from "./session-store.js";
-export { MikanAgentSession, type CompactionReason, type HarnessEvent, type HarnessEventListener, type MikanAgentSessionOptions, } from "./runner.js";
+export { MikanAgentSession, type CompactionReason, type HarnessEvent, type HarnessEventListener, type MikanAgentSessionOptions, type PromptBlockedOutcome, } from "./runner.js";
 export { formatSkillsForPrompt, loadSkillsFromDir, parseFrontmatter, type LoadSkillsResult, type MikanSkill, type SkillDiagnostic, } from "./skills.js";
 export { DEFAULT_BUDGET_SETTINGS, DEFAULT_EVENT_BUDGET, DEFAULT_RETRY_SETTINGS, resolveHarnessSettings, type BudgetSettings, type CompactionSettings, type HarnessSettings, type RetrySettings, } from "./settings.js";
-export { ExtensionRegistry } from "./extensions/registry.js";
+export { ExtensionRegistry, parseCommandInput } from "./extensions/registry.js";
 export { defaultExtensionDirs, extensionSlug, listInstalledExtensions, loadExtensions, validateExtension, type ExtensionValidation, type InstalledExtensionInfo, type LoadExtensionsOptions, type LoadExtensionsResult, } from "./extensions/loader.js";
-export type { BeforeAgentStartHookEvent, BeforeAgentStartHookResult, ExtensionHostServices, ExtensionLoadError, ExtensionManifest, ExtensionScheduleInfo, ExtensionSchedulePayload, ExtensionScheduleSpec, ExtensionScheduleStore, LoadedExtension, MessageEndHookEvent, MikanExtensionActivate, MikanExtensionApi, MikanExtensionModule, MikanHookMap, MikanHookName, SessionCompactHookEvent, ToolCallHookEvent, ToolCallHookResult, ToolResultHookEvent, TurnEndHookEvent, } from "./extensions/types.js";
+export type { AgentErrorHookEvent, BeforeAgentStartHookEvent, BeforeAgentStartHookResult, BudgetExceededHookEvent, ExtensionCommand, ExtensionCommandContext, ExtensionDisposer, ExtensionHostServices, ExtensionLoadError, ExtensionManifest, ExtensionScheduleInfo, ExtensionSchedulePayload, ExtensionScheduleSpec, ExtensionScheduleStore, LoadedExtension, MessageEndHookEvent, MikanExtensionActivate, MikanExtensionApi, MikanExtensionModule, MikanHookMap, MikanHookName, RunOrigin, SessionCompactHookEvent, ToolCallHookEvent, ToolCallHookResult, ToolResultHookEvent, ToolResultHookResult, TurnEndHookEvent, } from "./extensions/types.js";
 export { CURRENT_SESSION_VERSION, type BranchSummaryEntry, type CompactionEntry, type CustomEntry, type CustomMessageEntry, type SessionContext, type SessionEntry, type SessionFileEntry, type SessionHeader, type SessionInfoEntry, type SessionMessageEntry, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map