@agentplugins/core 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @agentplugins/core
+
+> Core types, validation, and plugin registry for [AgentPlugins](https://github.com/espetro/agentplugins).
+
+`@agentplugins/core` defines the universal plugin manifest (`PluginManifest`), runs schema validation, and exposes the adapter registry that platform adapters register themselves with. It is the **Port** in AgentPlugins's Ports & Adapters (Hexagonal) architecture.
+
+## Installation
+
+```bash
+npm install @agentplugins/core
+```
+
+Peer dependency: none. Runtime: Node 20+.
+
+## What's in the box
+
+- **`PluginManifest`** — the universal TypeScript shape every plugin declares against.
+- **`definePlugin(manifest)`** — identity helper that returns the manifest as-is, with type inference.
+- **`validateManifest(manifest)`** — runs structural + semantic checks and returns a list of `ValidationIssue` (severity-tagged).
+- **`AdapterRegistry`** — central registry where adapters self-register; consumers query it by platform name.
+- **`wrapInlineHandlers(manifest)`** — converts inline handler strings into the format each platform expects.
+- **`UNIVERSAL_HOOK_NAMES`**, **`ALL_TARGETS`** — canonical enums for hooks and target platforms.
+
+## Quick start
+
+```typescript
+import { definePlugin, validateManifest, AdapterRegistry } from '@agentplugins/core';
+
+const manifest = definePlugin({
+  name: 'my-plugin',
+  version: '0.1.0',
+  targets: ['claude', 'opencode'],
+  hooks: {
+    sessionStart: {
+      handler: {
+        type: 'inline',
+        handler: async () => ({ additionalContext: 'Plugin loaded.' }),
+      },
+    },
+  },
+});
+
+const issues = validateManifest(manifest);
+if (issues.some(i => i.severity === 'error')) {
+  throw new Error('Invalid plugin manifest');
+}
+```
+
+## Related packages
+
+- [`@agentplugins/cli`](https://www.npmjs.com/package/@agentplugins/cli) — build, validate, and scaffold plugins.
+- [`@agentplugins/adapter-claude`](https://www.npmjs.com/package/@agentplugins/adapter-claude) and the other 6 platform adapters.
+- Root repo: <https://github.com/espetro/agentplugins>
+
+## License
+
+MIT

package/dist/hook-wrapper.d.ts

@@ -0,0 +1,36 @@
+/**
+ * AgentPlugins Hook Wrapper Generator
+ *
+ * Generates Node.js scripts that wrap inline handlers for command-based platforms.
+ * These scripts communicate via JSON stdin/stdout following the Codex/Gemini protocol.
+ */
+import type { HookContext, HookResult } from './types.js';
+export interface WrapperOptions {
+    /** Target platform flavor for output format */
+    platform: 'codex' | 'claude' | 'copilot' | 'gemini' | 'kimi';
+    /** Hook name */
+    hookName: string;
+    /** Unique identifier for this wrapper */
+    wrapperId: string;
+}
+/**
+ * Generate a Node.js wrapper script that:
+ * 1. Reads JSON context from stdin
+ * 2. Calls the inline handler
+ * 3. Writes JSON result to stdout
+ * 4. Exits with appropriate code (0=success, 2=block)
+ *
+ * The inline handler is serialized as a string and embedded in the script.
+ */
+export declare function generateHookWrapper(_handlerSource: string, options: WrapperOptions): string;
+/**
+ * Generate the shared handlers module that exports all inline handlers.
+ * This is imported by each individual wrapper script.
+ */
+export declare function generateHandlersModule(handlers: Map<string, (ctx: HookContext) => Promise<HookResult>>): string;
+/**
+ * Serialize an inline handler to a string that can be embedded in a wrapper.
+ * Returns null if the handler cannot be serialized.
+ */
+export declare function serializeHandler(handler: (ctx: HookContext) => Promise<HookResult>): string | null;
+//# sourceMappingURL=hook-wrapper.d.ts.map

package/dist/hook-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-wrapper.d.ts","sourceRoot":"","sources":["../src/hook-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC7D,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,cAAc,GACtB,MAAM,CA8IR;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,GAC/D,MAAM,CA6BR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,IAAI,CAWlG"}

package/dist/hook-wrapper.js

@@ -0,0 +1,207 @@
+/**
+ * AgentPlugins Hook Wrapper Generator
+ *
+ * Generates Node.js scripts that wrap inline handlers for command-based platforms.
+ * These scripts communicate via JSON stdin/stdout following the Codex/Gemini protocol.
+ */
+/**
+ * Generate a Node.js wrapper script that:
+ * 1. Reads JSON context from stdin
+ * 2. Calls the inline handler
+ * 3. Writes JSON result to stdout
+ * 4. Exits with appropriate code (0=success, 2=block)
+ *
+ * The inline handler is serialized as a string and embedded in the script.
+ */
+export function generateHookWrapper(_handlerSource, options) {
+    const { platform, hookName, wrapperId } = options;
+    return `#!/usr/bin/env node
+/**
+ * AgentPlugins Auto-Generated Hook Wrapper
+ * Platform: ${platform}
+ * Hook: ${hookName}
+ * ID: ${wrapperId}
+ *
+ * DO NOT EDIT — This file is regenerated on each build.
+ */
+
+const { handler } = require('./__agentplugins_handlers__.js');
+
+async function main() {
+  // Read JSON context from stdin
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let ctx;
+  try {
+    ctx = JSON.parse(input || '{}');
+  } catch {
+    ctx = {};
+  }
+
+  // Normalize context fields across platforms
+  const normalizedCtx = normalizeContext(ctx, '${hookName}');
+
+  try {
+    const result = await handler(normalizedCtx);
+
+    if (!result) {
+      // No result = allow operation to continue
+      process.exit(0);
+    }
+
+    // Output result as JSON
+    const output = formatOutput(result, '${platform}', '${hookName}');
+    if (output) {
+      console.log(JSON.stringify(output));
+    }
+
+    // Exit with blocking code if needed
+    if (result.block || result.continue === false) {
+      process.exit(${platform === 'gemini' || platform === 'copilot' ? 2 : 0});
+    }
+
+    process.exit(0);
+  } catch (err) {
+    // On error, output system message and exit
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    console.error(errorMsg);
+
+    ${platform === 'copilot' ? `
+    // Copilot is fail-closed: errors deny the operation
+    console.log(JSON.stringify({ systemMessage: \`Hook error: \${errorMsg}\` }));
+    process.exit(2);
+    ` : platform === 'gemini' ? `
+    // Gemini: non-zero exit = warning (not block)
+    process.exit(1);
+    ` : `
+    // Other platforms: error is logged but doesn't block
+    process.exit(0);
+    `}
+  }
+}
+
+function normalizeContext(ctx, eventName) {
+  return {
+    event: eventName,
+    cwd: ctx.cwd ?? ctx.workingDirectory ?? process.cwd(),
+    sessionId: ctx.session_id ?? ctx.sessionId ?? ctx.sessionID,
+    model: ctx.model ?? ctx.model_name,
+    permissionMode: ctx.permission_mode ?? ctx.permissionMode,
+    toolName: ctx.tool_name ?? ctx.toolName ?? ctx.tool,
+    toolInput: ctx.tool_input ?? ctx.toolInput ?? ctx.args,
+    userPrompt: ctx.user_prompt ?? ctx.userPrompt ?? ctx.prompt,
+    source: ctx.source,
+    transcriptPath: ctx.transcript_path ?? ctx.transcriptPath,
+    agentId: ctx.agent_id ?? ctx.agentId,
+    agentType: ctx.agent_type ?? ctx.agentType ?? ctx.agent,
+    turnId: ctx.turn_id ?? ctx.turnId,
+    // Pass through any extra fields
+    ...ctx,
+  };
+}
+
+function formatOutput(result, platform, hookName) {
+  if (!result) return null;
+
+  switch (platform) {
+    case 'codex':
+      // Codex format: hookSpecificOutput with additionalContext
+      if (result.additionalContext) {
+        return {
+          hookSpecificOutput: {
+            hookEventName: hookName.charAt(0).toUpperCase() + hookName.slice(1),
+            additionalContext: result.additionalContext,
+          },
+          ...(result.systemMessage ? { systemMessage: result.systemMessage } : {}),
+          ...(result.continue === false ? { continue: false, stopReason: result.reason } : {}),
+        };
+      }
+      return {
+        ...(result.systemMessage ? { systemMessage: result.systemMessage } : {}),
+        ...(result.continue === false ? { continue: false, stopReason: result.reason } : {}),
+      };
+
+    case 'gemini':
+      // Gemini format: JSON output, exit 2 to block
+      return {
+        ...(result.systemMessage ? { systemMessage: result.systemMessage } : {}),
+        ...(result.additionalContext ? { additionalContext: result.additionalContext } : {}),
+      };
+
+    case 'copilot':
+      // Copilot format: similar to codex
+      return {
+        ...(result.systemMessage ? { systemMessage: result.systemMessage } : {}),
+        ...(result.additionalContext ? { additionalContext: result.additionalContext } : {}),
+        ...(result.continue === false ? { continue: false } : {}),
+      };
+
+    case 'claude':
+    case 'kimi':
+    default:
+      // Generic format
+      return {
+        ...(result.systemMessage ? { systemMessage: result.systemMessage } : {}),
+        ...(result.additionalContext ? { additionalContext: result.additionalContext } : {}),
+        ...(result.continue === false ? { continue: false } : {}),
+      };
+  }
+}
+
+main();
+`;
+}
+/**
+ * Generate the shared handlers module that exports all inline handlers.
+ * This is imported by each individual wrapper script.
+ */
+export function generateHandlersModule(handlers) {
+    const entries = [];
+    for (const [id, handler] of handlers) {
+        // Serialize the handler — note: this requires the handler to be serializable
+        // For complex handlers, users should use 'command' type instead
+        entries.push(`  '${id}': ${handler.toString()},`);
+    }
+    return `/**
+ * AgentPlugins Auto-Generated Handlers Module
+ *
+ * DO NOT EDIT — This file is regenerated on each build.
+ */
+
+exports.handler = handler;
+
+const handlers = {
+${entries.join('\n')}
+};
+
+async function handler(ctx) {
+  const handlerFn = handlers[process.env.AGENTPLUGINS_HOOK_ID];
+  if (!handlerFn) {
+    throw new Error(\`Unknown hook ID: \${process.env.AGENTPLUGINS_HOOK_ID}\`);
+  }
+  return handlerFn(ctx);
+}
+`;
+}
+/**
+ * Serialize an inline handler to a string that can be embedded in a wrapper.
+ * Returns null if the handler cannot be serialized.
+ */
+export function serializeHandler(handler) {
+    try {
+        const str = handler.toString();
+        // Basic validation: must look like a function
+        if (!str.includes('function') && !str.includes('=>')) {
+            return null;
+        }
+        return str;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=hook-wrapper.js.map

package/dist/hook-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-wrapper.js","sourceRoot":"","sources":["../src/hook-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,cAAsB,EACtB,OAAuB;IAEvB,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAElD,OAAO;;;eAGM,QAAQ;WACZ,QAAQ;SACV,SAAS;;;;;;;;;;;;;;;;;;;;;;;iDAuB+B,QAAQ;;;;;;;;;;;2CAWd,QAAQ,OAAO,QAAQ;;;;;;;qBAO7C,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;;;;;;;;;MAStE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC;;;;KAI1B,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC;;;KAG3B,CAAC,CAAC,CAAC;;;KAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyEJ,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAgE;IAEhE,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,QAAQ,EAAE,CAAC;QACrC,6EAA6E;QAC7E,gEAAgE;QAChE,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;IAED,OAAO;;;;;;;;;EASP,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;;;;;CAUnB,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAkD;IACjF,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC/B,8CAA8C;QAC9C,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACrD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AgentPlugins Core
+ *
+ * The Port — universal plugin interface for AI agent harnesses.
+ */
+export type { PluginManifest, TargetPlatform, Skill, MCPServerConfig, ToolDefinition, ToolParameterSchema, ToolParameter, ToolContext, ToolResult, UserConfigOption, UniversalHooks, UniversalHookName, HookDefinition, HookHandler, CommandHookHandler, HttpHookHandler, InlineHookHandler, HookContext, HookResult, PlatformAdapter, HandlerType, ValidationIssue, AdapterOutput, FileOutput, BuildConfig, } from './types.js';
+export type { FileOutput as AdapterFile } from './types.js';
+export { Severity } from './types.js';
+import type { PluginManifest } from './types.js';
+export { ALL_TARGETS, UNIVERSAL_HOOK_NAMES } from './types.js';
+export { validateUniversal, validateForPlatform, getPlatformConstraints, } from './validation.js';
+export type { PlatformConstraints } from './validation.js';
+export { registerAdapter, hasAdapter, loadAdapter, loadAllAdapters, getRegisteredPlatforms, registerBuiltinAdapters, } from './registry.js';
+export { generateHookWrapper, generateHandlersModule, serializeHandler, } from './hook-wrapper.js';
+export type { WrapperOptions } from './hook-wrapper.js';
+/**
+ * Convenience function to define a plugin with TypeScript intellisense.
+ */
+export declare function definePlugin(manifest: PluginManifest): PluginManifest;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EACV,cAAc,EACd,cAAc,EACd,KAAK,EACL,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,eAAe,EACf,WAAW,EACX,eAAe,EACf,aAAa,EACb,UAAU,EACV,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,UAAU,IAAI,WAAW,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAG/D,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3D,OAAO,EACL,eAAe,EACf,UAAU,EACV,WAAW,EACX,eAAe,EACf,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,cAAc,CAErE"}

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * AgentPlugins Core
+ *
+ * The Port — universal plugin interface for AI agent harnesses.
+ */
+export { Severity } from './types.js';
+// Constants
+export { ALL_TARGETS, UNIVERSAL_HOOK_NAMES } from './types.js';
+// Validation
+export { validateUniversal, validateForPlatform, getPlatformConstraints, } from './validation.js';
+// Registry
+export { registerAdapter, hasAdapter, loadAdapter, loadAllAdapters, getRegisteredPlatforms, registerBuiltinAdapters, } from './registry.js';
+// Hook Wrapper Generation
+export { generateHookWrapper, generateHandlersModule, serializeHandler, } from './hook-wrapper.js';
+/**
+ * Convenience function to define a plugin with TypeScript intellisense.
+ */
+export function definePlugin(manifest) {
+    return manifest;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgCH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKtC,YAAY;AACZ,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE/D,aAAa;AACb,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,WAAW;AACX,OAAO,EACL,eAAe,EACf,UAAU,EACV,WAAW,EACX,eAAe,EACf,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAEvB,0BAA0B;AAC1B,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAG3B;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,QAAwB;IACnD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/profiling-hof.d.ts

@@ -0,0 +1,11 @@
+import type { HookContext, HookResult } from './types.js';
+/**
+ * Higher-order function that wraps an inline hook handler with timing instrumentation.
+ *
+ * @param handler - The inline hook handler to wrap
+ * @param hookName - Name of the hook event (e.g. 'preToolUse')
+ * @param platform - Platform identifier (e.g. 'opencode', 'pimono')
+ * @returns The same handler, wrapped with timing and profiling
+ */
+export declare function withTiming<T extends (ctx: HookContext) => Promise<HookResult>>(handler: T, hookName: string, platform: string): T;
+//# sourceMappingURL=profiling-hof.d.ts.map

package/dist/profiling-hof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiling-hof.d.ts","sourceRoot":"","sources":["../src/profiling-hof.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgB1D;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,CAAC,SAAS,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,EACnD,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAqEnD"}

package/dist/profiling-hof.js

@@ -0,0 +1,80 @@
+import { createHookId, startTimer, emitProfilingEvent, shouldProfile, getProfilingOutput, } from './profiling.js';
+/**
+ * Sequence counter for ordering profiling events within a session.
+ * Incremented on each withTiming call.
+ */
+let sequenceCounter = 0;
+/**
+ * Higher-order function that wraps an inline hook handler with timing instrumentation.
+ *
+ * @param handler - The inline hook handler to wrap
+ * @param hookName - Name of the hook event (e.g. 'preToolUse')
+ * @param platform - Platform identifier (e.g. 'opencode', 'pimono')
+ * @returns The same handler, wrapped with timing and profiling
+ */
+export function withTiming(handler, hookName, platform) {
+    return (async (ctx) => {
+        // Inject timing fields into context before handler execution
+        const hookId = createHookId();
+        const timestamp = Date.now();
+        const getElapsed = startTimer();
+        ctx.timestamp = timestamp;
+        ctx.hookId = hookId;
+        let result;
+        let error;
+        try {
+            result = await handler(ctx);
+        }
+        catch (err) {
+            error = err instanceof Error ? err.message : String(err);
+            // Emit error profiling event when profiling is enabled
+            if (shouldProfile()) {
+                const event = {
+                    type: 'hook_invocation',
+                    hookName,
+                    hookId,
+                    sequenceId: ++sequenceCounter,
+                    timestamp,
+                    hookDurationMs: getElapsed(),
+                    platform,
+                    sessionId: ctx.sessionId,
+                    toolName: ctx.toolName,
+                    error,
+                };
+                try {
+                    emitProfilingEvent(event, getProfilingOutput());
+                }
+                catch {
+                    // profiling failure must never break the hook
+                }
+            }
+            throw err;
+        }
+        // Record duration after handler completes
+        const hookDurationMs = getElapsed();
+        ctx.hookDurationMs = hookDurationMs;
+        // Emit profiling event when profiling is enabled
+        if (shouldProfile()) {
+            const event = {
+                type: 'hook_invocation',
+                hookName,
+                hookId,
+                sequenceId: ++sequenceCounter,
+                timestamp,
+                hookDurationMs,
+                platform,
+                sessionId: ctx.sessionId,
+                toolName: ctx.toolName,
+                result,
+            };
+            try {
+                emitProfilingEvent(event, getProfilingOutput());
+            }
+            catch {
+                // profiling failure must never break the hook
+            }
+        }
+        return result;
+    });
+}
+//# sourceMappingURL=profiling-hof.js.map

package/dist/profiling-hof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiling-hof.js","sourceRoot":"","sources":["../src/profiling-hof.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,kBAAkB,GAEnB,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AACH,IAAI,eAAe,GAAG,CAAC,CAAC;AAExB;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAExB,OAAU,EAAE,QAAgB,EAAE,QAAgB;IAC9C,OAAO,CAAC,KAAK,EAAE,GAAgB,EAAuB,EAAE;QACtD,6DAA6D;QAC7D,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,UAAU,GAAG,UAAU,EAAE,CAAC;QAEhC,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC;QAC1B,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC;QAEpB,IAAI,MAAkB,CAAC;QACvB,IAAI,KAAyB,CAAC;QAE9B,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAEzD,uDAAuD;YACvD,IAAI,aAAa,EAAE,EAAE,CAAC;gBACpB,MAAM,KAAK,GAAmB;oBAC5B,IAAI,EAAE,iBAAiB;oBACvB,QAAQ;oBACR,MAAM;oBACN,UAAU,EAAE,EAAE,eAAe;oBAC7B,SAAS;oBACT,cAAc,EAAE,UAAU,EAAE;oBAC5B,QAAQ;oBACR,SAAS,EAAE,GAAG,CAAC,SAAS;oBACxB,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,KAAK;iBACN,CAAC;gBACF,IAAI,CAAC;oBACH,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,EAAE,CAAC,CAAC;gBAClD,CAAC;gBAAC,MAAM,CAAC;oBACP,8CAA8C;gBAChD,CAAC;YACH,CAAC;YAED,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,0CAA0C;QAC1C,MAAM,cAAc,GAAG,UAAU,EAAE,CAAC;QACpC,GAAG,CAAC,cAAc,GAAG,cAAc,CAAC;QAEpC,iDAAiD;QACjD,IAAI,aAAa,EAAE,EAAE,CAAC;YACpB,MAAM,KAAK,GAAmB;gBAC5B,IAAI,EAAE,iBAAiB;gBACvB,QAAQ;gBACR,MAAM;gBACN,UAAU,EAAE,EAAE,eAAe;gBAC7B,SAAS;gBACT,cAAc;gBACd,QAAQ;gBACR,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,MAAM;aACP,CAAC;YACF,IAAI,CAAC;gBACH,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,EAAE,CAAC,CAAC;YAClD,CAAC;YAAC,MAAM,CAAC;gBACP,8CAA8C;YAChD,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,CAAM,CAAC;AACV,CAAC"}

package/dist/profiling.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Profiling event emitted as JSONL for external profiler consumption.
+ * Mirrors schemas/profiling-event.json.
+ */
+export interface ProfilingEvent {
+    /** Discriminator: always "hook_invocation" */
+    type: 'hook_invocation';
+    /** Name of the hook being invoked */
+    hookName: string;
+    /** Unique identifier for this hook invocation instance */
+    hookId: string;
+    /** Monotonically increasing sequence number for ordering events */
+    sequenceId: number;
+    /** Unix epoch timestamp in milliseconds when the hook was invoked */
+    timestamp: number;
+    /** Duration of the hook execution in milliseconds */
+    hookDurationMs: number;
+    /** Platform on which the hook ran (e.g. 'python', 'node', 'cli') */
+    platform: string;
+    /** Optional session identifier to correlate events */
+    sessionId?: string;
+    /** Optional name of the tool/agent associated with this hook invocation */
+    toolName?: string;
+    /** Optional result payload returned by the hook */
+    result?: object;
+    /** Optional error message if the hook invocation failed */
+    error?: string;
+}
+/**
+ * Generates a unique hook invocation ID using crypto.randomUUID().
+ */
+export declare function createHookId(): string;
+/**
+ * Creates a timer. When the returned function is called, it returns
+ * the elapsed milliseconds since the timer was created (via Date.now()).
+ */
+export declare function startTimer(): () => number;
+/**
+ * Writes a profiling event as a single JSONL line.
+ *
+ * - If `destination` is `'stderr'`, writes to `process.stderr` (without newline — JSONL
+ *   consumers typically handle line separation; we add `\n` for readability).
+ * - If `destination` is a file path, appends a JSONL line via `fs.appendFileSync`.
+ */
+export declare function emitProfilingEvent(event: ProfilingEvent, destination: string): void;
+/**
+ * Reads the `AGENTBRIDGE_PROFILING_OUTPUT` environment variable.
+ * Returns `'stderr'` if the variable is not set.
+ */
+export declare function getProfilingOutput(): string;
+/**
+ * Returns `true` when profiling is enabled (i.e. the
+ * `AGENTBRIDGE_PROFILING_OUTPUT` environment variable is set to a non-empty value).
+ */
+export declare function shouldProfile(): boolean;
+/**
+ * Creates a session-scoped sequence ID counter.
+ * Returns `next()` which yields a monotonically increasing integer per session.
+ * Used by generated wrappers to produce `sequenceId` values in profiling events.
+ */
+export declare function createSequenceId(): {
+    next: () => number;
+};
+//# sourceMappingURL=profiling.d.ts.map

package/dist/profiling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiling.d.ts","sourceRoot":"","sources":["../src/profiling.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,IAAI,EAAE,iBAAiB,CAAC;IACxB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,MAAM,CAGzC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,MAAM,GAClB,IAAI,CAQN;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAGvC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI;IAAE,IAAI,EAAE,MAAM,MAAM,CAAA;CAAE,CAGzD"}

package/dist/profiling.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+const PROFILING_ENV_VAR = 'AGENTBRIDGE_PROFILING_OUTPUT';
+/**
+ * Generates a unique hook invocation ID using crypto.randomUUID().
+ */
+export function createHookId() {
+    return crypto.randomUUID();
+}
+/**
+ * Creates a timer. When the returned function is called, it returns
+ * the elapsed milliseconds since the timer was created (via Date.now()).
+ */
+export function startTimer() {
+    const start = Date.now();
+    return () => Date.now() - start;
+}
+/**
+ * Writes a profiling event as a single JSONL line.
+ *
+ * - If `destination` is `'stderr'`, writes to `process.stderr` (without newline — JSONL
+ *   consumers typically handle line separation; we add `\n` for readability).
+ * - If `destination` is a file path, appends a JSONL line via `fs.appendFileSync`.
+ */
+export function emitProfilingEvent(event, destination) {
+    const line = JSON.stringify(event) + '\n';
+    if (destination === 'stderr') {
+        process.stderr.write(line);
+    }
+    else {
+        fs.appendFileSync(destination, line, 'utf-8');
+    }
+}
+/**
+ * Reads the `AGENTBRIDGE_PROFILING_OUTPUT` environment variable.
+ * Returns `'stderr'` if the variable is not set.
+ */
+export function getProfilingOutput() {
+    return process.env[PROFILING_ENV_VAR] ?? 'stderr';
+}
+/**
+ * Returns `true` when profiling is enabled (i.e. the
+ * `AGENTBRIDGE_PROFILING_OUTPUT` environment variable is set to a non-empty value).
+ */
+export function shouldProfile() {
+    const value = process.env[PROFILING_ENV_VAR];
+    return value !== undefined && value !== '';
+}
+/**
+ * Creates a session-scoped sequence ID counter.
+ * Returns `next()` which yields a monotonically increasing integer per session.
+ * Used by generated wrappers to produce `sequenceId` values in profiling events.
+ */
+export function createSequenceId() {
+    let counter = 0;
+    return { next: () => ++counter };
+}
+//# sourceMappingURL=profiling.js.map

package/dist/profiling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiling.js","sourceRoot":"","sources":["../src/profiling.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,MAAM,iBAAiB,GAAG,8BAA8B,CAAC;AA+BzD;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;AAClC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAqB,EACrB,WAAmB;IAEnB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAE1C,IAAI,WAAW,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;SAAM,CAAC;QACN,EAAE,CAAC,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,QAAQ,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC7C,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC;AACnC,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * AgentPlugins Adapter Registry
+ *
+ * Central registry for all platform adapters.
+ * Adapters register themselves; the CLI and build system look them up here.
+ */
+import type { PlatformAdapter, TargetPlatform } from './types.js';
+/**
+ * Register a platform adapter factory.
+ * Called by each adapter package during initialization.
+ */
+export declare function registerAdapter(platform: TargetPlatform, factory: () => Promise<PlatformAdapter>): void;
+/**
+ * Check if an adapter is registered for a platform.
+ */
+export declare function hasAdapter(platform: TargetPlatform): boolean;
+/**
+ * Load a platform adapter asynchronously.
+ */
+export declare function loadAdapter(platform: TargetPlatform): Promise<PlatformAdapter>;
+/**
+ * Load all registered adapters.
+ */
+export declare function loadAllAdapters(): Promise<Map<TargetPlatform, PlatformAdapter>>;
+/**
+ * Get list of registered platforms.
+ */
+export declare function getRegisteredPlatforms(): TargetPlatform[];
+/**
+ * Import and register all built-in adapters.
+ * This is a convenience function that auto-registers all official adapters.
+ */
+export declare function registerBuiltinAdapters(): Promise<void>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIlE;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,GACtC,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAE5D;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CASpF;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAMrF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,cAAc,EAAE,CAEzD;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC,CAuB7D"}