@adhd/agent-engine-orchestrator 2.1.0

package/src/plugins/loader.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { EngineLogger } from '../interfaces.js';
+import type { IHookRegistry } from '@adhd/agent-base-types';
+declare const pluginEntrySchema: z.ZodObject<{
+    module: z.ZodString;
+    config: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+export declare const agentMcpConfigFileSchema: z.ZodObject<{
+    plugins: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        module: z.ZodString;
+        config: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>>>>;
+}, z.core.$strip>;
+export type AgentMcpConfigFile = z.infer<typeof agentMcpConfigFileSchema>;
+export type PluginEntry = z.infer<typeof pluginEntrySchema>;
+/**
+ * Find the active agent-mcp config file.
+ * @param configPathOverride — explicit path; pass null/undefined to skip.
+ * @param configPathFromEnv — config.plugins.configPath value (injected instead of importing config).
+ * @param logger — injected logger.
+ */
+export declare function findConfigFile(configPathOverride: string | null | undefined, configPathFromEnv: string | undefined, logger?: EngineLogger): string | null;
+/**
+ * Read, parse, and validate the agent-mcp config file.
+ * @param configPathOverride — forwarded to findConfigFile
+ * @param configPathFromEnv — config.plugins.configPath injection
+ * @param logger — injected logger
+ */
+export declare function loadConfigFile(configPathOverride: string | null | undefined, configPathFromEnv: string | undefined, logger?: EngineLogger): AgentMcpConfigFile;
+export declare function resolveSpecifier(specifier: string): Promise<string>;
+/**
+ * Discovers and installs all external plugins. Never throws.
+ *
+ * @param hooks — hook registry
+ * @param db — database handle
+ * @param overrides — explicit values for testability
+ *   `configPath`    — forwarded to findConfigFile
+ *   `pluginEntries` — explicit module list (replaces config.plugins.entries)
+ * @param configPathFromEnv — config.plugins.configPath injection
+ * @param logger — injected logger
+ */
+export declare function loadExternalPlugins(hooks: IHookRegistry, db: unknown, overrides?: {
+    configPath?: string | null;
+    pluginEntries?: string[];
+}, configPathFromEnv?: string, pluginEntriesFromEnv?: string[], logger?: EngineLogger): Promise<void>;
+export {};
+//# sourceMappingURL=loader.d.ts.map

package/src/plugins/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../../../../packages/agent/agent-engine-orchestrator/src/plugins/loader.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EACV,aAAa,EAId,MAAM,wBAAwB,CAAC;AAIhC,QAAA,MAAM,iBAAiB;;;iBAGrB,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;iBAEnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAuB5D;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC7C,iBAAiB,EAAE,MAAM,GAAG,SAAS,EACrC,MAAM,CAAC,EAAE,YAAY,GACpB,MAAM,GAAG,IAAI,CAkCf;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC7C,iBAAiB,EAAE,MAAM,GAAG,SAAS,EACrC,MAAM,CAAC,EAAE,YAAY,GACpB,kBAAkB,CA8BpB;AAID,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBzE;AAqFD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,aAAa,EACpB,EAAE,EAAE,OAAO,EACX,SAAS,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EACpE,iBAAiB,CAAC,EAAE,MAAM,EAC1B,oBAAoB,CAAC,EAAE,MAAM,EAAE,EAC/B,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/src/plugins/loader.js

@@ -0,0 +1,174 @@
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+// ── Config file schema ────────────────────────────────────────────────────────
+const pluginEntrySchema = z.object({
+    module: z.string().min(1, 'module must be a non-empty string'),
+    config: z.record(z.string(), z.unknown()).optional().default({}),
+});
+export const agentMcpConfigFileSchema = z.object({
+    plugins: z.array(pluginEntrySchema).optional().default([]),
+});
+// ── Config file discovery ─────────────────────────────────────────────────────
+/**
+ * Find the active agent-mcp config file.
+ * @param configPathOverride — explicit path; pass null/undefined to skip.
+ * @param configPathFromEnv — config.plugins.configPath value (injected instead of importing config).
+ * @param logger — injected logger.
+ */
+export function findConfigFile(configPathOverride, configPathFromEnv, logger) {
+    const log = logger ?? { info: () => { }, warn: () => { }, error: () => { }, debug: () => { } };
+    const explicit = configPathOverride !== undefined
+        ? configPathOverride
+        : configPathFromEnv;
+    if (explicit) {
+        if (!existsSync(explicit)) {
+            log.warn({ path: explicit }, 'AGENT_MCP_CONFIG points to a file that does not exist — ignoring');
+            return null;
+        }
+        return explicit;
+    }
+    const local = resolve(process.cwd(), 'agent-mcp.config.json');
+    if (existsSync(local))
+        return local;
+    const nested = resolve(process.cwd(), '.adhd', 'agent-mcp', 'config.json');
+    if (existsSync(nested))
+        return nested;
+    const globalAdhd = resolve(homedir(), '.adhd', 'agent-mcp', 'config.json');
+    if (existsSync(globalAdhd))
+        return globalAdhd;
+    // Back-compat: the published 2.0.1 loader used ~/.agent-mcp/config.json. The engine
+    // refactor moved the global path under ~/.adhd/ and stopped checking the old one, so a
+    // user's existing global plugin config would silently stop loading. Keep honouring it.
+    // See BUG-ORCH-014.
+    const globalLegacy = resolve(homedir(), '.agent-mcp', 'config.json');
+    if (existsSync(globalLegacy))
+        return globalLegacy;
+    return null;
+}
+/**
+ * Read, parse, and validate the agent-mcp config file.
+ * @param configPathOverride — forwarded to findConfigFile
+ * @param configPathFromEnv — config.plugins.configPath injection
+ * @param logger — injected logger
+ */
+export function loadConfigFile(configPathOverride, configPathFromEnv, logger) {
+    const log = logger ?? { info: () => { }, warn: () => { }, error: () => { }, debug: () => { } };
+    const configPath = findConfigFile(configPathOverride, configPathFromEnv, logger);
+    if (!configPath)
+        return { plugins: [] };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+    }
+    catch (err) {
+        log.error({ configPath, err }, 'Failed to read/parse agent-mcp config file — no config-file plugins will load');
+        return { plugins: [] };
+    }
+    const result = agentMcpConfigFileSchema.safeParse(raw);
+    if (!result.success) {
+        log.error({ configPath, issues: result.error.flatten().fieldErrors }, 'agent-mcp config file failed schema validation — no config-file plugins will load');
+        return { plugins: [] };
+    }
+    log.info({ configPath, pluginCount: result.data.plugins.length }, 'Loaded agent-mcp config file');
+    return result.data;
+}
+// ── Module resolution ─────────────────────────────────────────────────────────
+export async function resolveSpecifier(specifier) {
+    if (specifier.startsWith('/') ||
+        specifier.startsWith('./') ||
+        specifier.startsWith('../')) {
+        return pathToFileURL(resolve(specifier)).href;
+    }
+    const bases = [process.cwd(), new URL('.', import.meta.url).pathname];
+    for (const base of bases) {
+        try {
+            const req = createRequire(base + '/');
+            return pathToFileURL(req.resolve(specifier)).href;
+        }
+        catch {
+            // try next base
+        }
+    }
+    throw new Error(`Cannot resolve plugin "${specifier}" from cwd (${process.cwd()}) or server directory. ` +
+        `Install it in your project: npm install ${specifier}`);
+}
+// ── Single plugin load ────────────────────────────────────────────────────────
+async function loadOnePlugin(hooks, db, entry, logger) {
+    const { module: specifier, config: rawConfig } = entry;
+    let resolved;
+    try {
+        resolved = await resolveSpecifier(specifier);
+    }
+    catch (err) {
+        logger.error({ specifier, err }, 'Plugin resolution failed — skipping');
+        return;
+    }
+    let mod;
+    try {
+        mod = (await import(resolved));
+    }
+    catch (err) {
+        logger.error({ specifier, resolved, err }, 'Plugin import failed — skipping');
+        return;
+    }
+    let validatedConfig = rawConfig ?? {};
+    if (mod.configSchema && typeof mod.configSchema.safeParse === 'function') {
+        const result = mod.configSchema.safeParse(rawConfig ?? {});
+        if (!result.success) {
+            const issues = result.error?.flatten?.() ?? result.error;
+            logger.error({ specifier, issues }, 'Plugin config failed schema validation — skipping. ' +
+                "Fix the 'config' block for this plugin in your agent-mcp config file.");
+            return;
+        }
+        validatedConfig = result.data;
+    }
+    const factory = (mod.createPlugin ?? mod.default);
+    if (typeof factory !== 'function') {
+        logger.error({ specifier }, 'Plugin does not export a createPlugin factory (as default or named export) — skipping. ' +
+            'Expected: export default function createPlugin(ctx): Plugin { ... }');
+        return;
+    }
+    let plugin;
+    try {
+        const ctx = { db, config: validatedConfig };
+        plugin = await factory(ctx);
+    }
+    catch (err) {
+        logger.error({ specifier, err }, 'Plugin factory threw during instantiation — skipping');
+        return;
+    }
+    try {
+        await plugin.install(hooks);
+        logger.info({ plugin: plugin.name, specifier }, 'External plugin installed');
+    }
+    catch (err) {
+        logger.error({ specifier, plugin: plugin.name, err }, 'Plugin install() threw — skipping');
+    }
+}
+/**
+ * Discovers and installs all external plugins. Never throws.
+ *
+ * @param hooks — hook registry
+ * @param db — database handle
+ * @param overrides — explicit values for testability
+ *   `configPath`    — forwarded to findConfigFile
+ *   `pluginEntries` — explicit module list (replaces config.plugins.entries)
+ * @param configPathFromEnv — config.plugins.configPath injection
+ * @param logger — injected logger
+ */
+export async function loadExternalPlugins(hooks, db, overrides, configPathFromEnv, pluginEntriesFromEnv, logger) {
+    const log = logger ?? { info: () => { }, warn: () => { }, error: () => { }, debug: () => { } };
+    const configFile = loadConfigFile(overrides?.configPath, configPathFromEnv, logger);
+    const legacyEntries = (overrides?.pluginEntries ?? pluginEntriesFromEnv ?? []).map((module) => ({ module, config: {} }));
+    const allEntries = [...configFile.plugins, ...legacyEntries];
+    if (allEntries.length === 0)
+        return;
+    for (const entry of allEntries) {
+        await loadOnePlugin(hooks, db, entry, log);
+    }
+}
+//# sourceMappingURL=loader.js.map

package/src/plugins/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../../../../packages/agent/agent-engine-orchestrator/src/plugins/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,iFAAiF;AAEjF,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,mCAAmC,CAAC;IAC9D,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;CACjE,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;CAC3D,CAAC,CAAC;AAwBH,iFAAiF;AAEjF;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,kBAA6C,EAC7C,iBAAqC,EACrC,MAAqB;IAErB,MAAM,GAAG,GAAG,MAAM,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAkB,CAAC;IAC3G,MAAM,QAAQ,GACZ,kBAAkB,KAAK,SAAS;QAC9B,CAAC,CAAC,kBAAkB;QACpB,CAAC,CAAC,iBAAiB,CAAC;IACxB,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,GAAG,CAAC,IAAI,CACN,EAAE,IAAI,EAAE,QAAQ,EAAE,EAClB,kEAAkE,CACnE,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,uBAAuB,CAAC,CAAC;IAC9D,IAAI,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAEpC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;IAC3E,IAAI,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IAEtC,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;IAC3E,IAAI,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC;IAE9C,oFAAoF;IACpF,uFAAuF;IACvF,uFAAuF;IACvF,oBAAoB;IACpB,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;IACrE,IAAI,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,YAAY,CAAC;IAElD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,kBAA6C,EAC7C,iBAAqC,EACrC,MAAqB;IAErB,MAAM,GAAG,GAAG,MAAM,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAkB,CAAC;IAC3G,MAAM,UAAU,GAAG,cAAc,CAAC,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,CAAC,CAAC;IACjF,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAExC,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,KAAK,CACP,EAAE,UAAU,EAAE,GAAG,EAAE,EACnB,+EAA+E,CAChF,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACzB,CAAC;IAED,MAAM,MAAM,GAAG,wBAAwB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,GAAG,CAAC,KAAK,CACP,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,EAC1D,mFAAmF,CACpF,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACzB,CAAC;IAED,GAAG,CAAC,IAAI,CACN,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EACvD,8BAA8B,CAC/B,CAAC;IACF,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,SAAiB;IACtD,IACE,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC;QACzB,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC;QAC1B,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAC3B,CAAC;QACD,OAAO,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;IAED,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IAEtE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;YACtC,OAAO,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;QACpD,CAAC;QAAC,MAAM,CAAC;YACP,gBAAgB;QAClB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,0BAA0B,SAAS,eAAe,OAAO,CAAC,GAAG,EAAE,yBAAyB;QACtF,2CAA2C,SAAS,EAAE,CACzD,CAAC;AACJ,CAAC;AAED,iFAAiF;AAEjF,KAAK,UAAU,aAAa,CAC1B,KAAoB,EACpB,EAAW,EACX,KAAkB,EAClB,MAAoB;IAEpB,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IAEvD,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,qCAAqC,CAAC,CAAC;QACxE,OAAO;IACT,CAAC;IAED,IAAI,GAAiB,CAAC;IACtB,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAiB,CAAC;IACjD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CACV,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,EAC5B,iCAAiC,CAClC,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,eAAe,GAA4B,SAAS,IAAI,EAAE,CAAC;IAE/D,IAAI,GAAG,CAAC,YAAY,IAAI,OAAO,GAAG,CAAC,YAAY,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;QACzE,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,MAAM,CAAC,KAAK,CAAC;YACzD,MAAM,CAAC,KAAK,CACV,EAAE,SAAS,EAAE,MAAM,EAAE,EACrB,qDAAqD;gBACnD,uEAAuE,CAC1E,CAAC;YACF,OAAO;QACT,CAAC;QACD,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC;IAChC,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,OAAO,CAEnC,CAAC;IACd,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,CAAC,KAAK,CACV,EAAE,SAAS,EAAE,EACb,yFAAyF;YACvF,qEAAqE,CACxE,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,GAAkB,EAAE,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;QAC3D,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CACV,EAAE,SAAS,EAAE,GAAG,EAAE,EAClB,sDAAsD,CACvD,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC5B,MAAM,CAAC,IAAI,CACT,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,EAClC,2BAA2B,CAC5B,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CACV,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,EACvC,mCAAmC,CACpC,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAoB,EACpB,EAAW,EACX,SAAoE,EACpE,iBAA0B,EAC1B,oBAA+B,EAC/B,MAAqB;IAErB,MAAM,GAAG,GAAG,MAAM,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAkB,CAAC;IAC3G,MAAM,UAAU,GAAG,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,CAAC,CAAC;IAEpF,MAAM,aAAa,GAAkB,CACnC,SAAS,EAAE,aAAa,IAAI,oBAAoB,IAAI,EAAE,CACvD,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAE5C,MAAM,UAAU,GAAkB,CAAC,GAAG,UAAU,CAAC,OAAO,EAAE,GAAG,aAAa,CAAC,CAAC;IAC5E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAEpC,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,aAAa,CAAC,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/src/plugins/usage-plugin.d.ts

@@ -0,0 +1,15 @@
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import type { EngineLogger } from '../interfaces.js';
+import type { IHookRegistry, Plugin } from '@adhd/agent-base-types';
+export declare class UsagePlugin implements Plugin {
+    private readonly db;
+    readonly name = "usage";
+    private readonly accumulators;
+    private readonly logger;
+    constructor(db: BetterSQLite3Database<any>, logger?: EngineLogger);
+    install(hooks: IHookRegistry): void;
+    private onTaskStart;
+    private onModelResponse;
+    private onTerminal;
+}
+//# sourceMappingURL=usage-plugin.d.ts.map

package/src/plugins/usage-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-plugin.d.ts","sourceRoot":"","sources":["../../../../../../packages/agent/agent-engine-orchestrator/src/plugins/usage-plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAIxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EACV,aAAa,EACb,MAAM,EAMP,MAAM,wBAAwB,CAAC;AA2BhC,qBAAa,WAAY,YAAW,MAAM;IAQtC,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPrB,QAAQ,CAAC,IAAI,WAAW;IAExB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;gBAInB,EAAE,EAAE,qBAAqB,CAAC,GAAG,CAAC,EAC/C,MAAM,CAAC,EAAE,YAAY;IAKvB,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAUnC,OAAO,CAAC,WAAW;IAqBnB,OAAO,CAAC,eAAe;IAqFvB,OAAO,CAAC,UAAU;CA0BnB"}

package/src/plugins/usage-plugin.js

@@ -0,0 +1,140 @@
+import { eq, sql } from 'drizzle-orm';
+import { taskUsageTable } from "@adhd/agent-store-runtime";
+import { nowIso } from '../utils/timestamps.js';
+const SEVERITY = {
+    length: 3,
+    tool_calls: 2,
+    stop: 1,
+    unknown: 0,
+};
+function mostSevere(a, b) {
+    const sa = SEVERITY[a ?? ''] ?? 0;
+    const sb = SEVERITY[b ?? ''] ?? 0;
+    return sa >= sb ? a ?? 'unknown' : b ?? 'unknown';
+}
+export class UsagePlugin {
+    db;
+    name = 'usage';
+    accumulators = new Map();
+    logger;
+    constructor(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    db, logger) {
+        this.db = db;
+        this.logger = logger ?? { info: () => { }, warn: () => { }, error: () => { }, debug: () => { } };
+    }
+    install(hooks) {
+        hooks.register('task:start', (payload) => this.onTaskStart(payload));
+        hooks.register('post:model_response', (payload) => this.onModelResponse(payload));
+        hooks.register('task:completed', (payload) => this.onTerminal(payload));
+        hooks.register('task:failed', (payload) => this.onTerminal(payload));
+        hooks.register('task:cancelled', (payload) => this.onTerminal(payload));
+    }
+    onTaskStart(payload) {
+        try {
+            const { executionContext } = payload;
+            const provider = executionContext.agentDefinition.provider;
+            this.accumulators.set(executionContext.taskId, {
+                startedAt: Date.now(),
+                rootTaskId: payload.rootTaskId ?? null,
+                agentName: executionContext.agentName,
+                providerType: provider.type,
+                model: ('model' in provider && provider.model) || 'default',
+                mostSevereStopReason: 'unknown',
+                maxTokens: 'maxTokens' in provider && typeof provider.maxTokens === 'number'
+                    ? provider.maxTokens
+                    : null,
+            });
+        }
+        catch (err) {
+            this.logger.error({ err }, 'UsagePlugin: task:start handler failed');
+        }
+    }
+    onModelResponse(payload) {
+        try {
+            const { executionContext, tokenUsage, toolCallCount } = payload;
+            const taskId = executionContext.taskId;
+            const acc = this.accumulators.get(taskId);
+            const inputTokens = tokenUsage?.inputTokens ?? 0;
+            const outputTokens = tokenUsage?.outputTokens ?? 0;
+            const toolCalls = toolCallCount ?? 0;
+            const incoming = tokenUsage?.stopReason ?? 'unknown';
+            if (acc) {
+                acc.mostSevereStopReason = mostSevere(acc.mostSevereStopReason, incoming);
+            }
+            const provider = executionContext.agentDefinition.provider;
+            this.db
+                .insert(taskUsageTable)
+                .values({
+                taskId,
+                rootTaskId: acc?.rootTaskId ?? null,
+                agentName: acc?.agentName ?? executionContext.agentName,
+                providerType: acc?.providerType ?? provider.type,
+                model: acc?.model ??
+                    (('model' in provider && provider.model) || 'default'),
+                inputTokens,
+                outputTokens,
+                toolCallCount: toolCalls,
+                modelCalls: 1,
+                latencyMs: 0,
+                isComplete: 0,
+                stopReason: acc?.mostSevereStopReason ?? incoming,
+                maxTokens: acc?.maxTokens ?? null,
+                cacheReadTokens: tokenUsage?.cacheReadTokens ?? null,
+                cacheCreationTokens: tokenUsage?.cacheCreationTokens ?? null,
+                uncachedInputTokens: tokenUsage?.uncachedInputTokens ?? null,
+                reasoningTokens: tokenUsage?.reasoningTokens ?? null,
+                // First call for this task: its input IS the peak so far.
+                peakContextTokens: inputTokens,
+                peakContextAt: 1,
+                createdAt: nowIso(),
+            })
+                .onConflictDoUpdate({
+                target: taskUsageTable.taskId,
+                set: {
+                    inputTokens: sql `${taskUsageTable.inputTokens} + ${inputTokens}`,
+                    outputTokens: sql `${taskUsageTable.outputTokens} + ${outputTokens}`,
+                    toolCallCount: sql `${taskUsageTable.toolCallCount} + ${toolCalls}`,
+                    modelCalls: sql `${taskUsageTable.modelCalls} + 1`,
+                    stopReason: acc?.mostSevereStopReason ?? incoming,
+                    cacheReadTokens: sql `COALESCE(${taskUsageTable.cacheReadTokens}, 0) + ${tokenUsage?.cacheReadTokens ?? 0}`,
+                    cacheCreationTokens: sql `COALESCE(${taskUsageTable.cacheCreationTokens}, 0) + ${tokenUsage?.cacheCreationTokens ?? 0}`,
+                    uncachedInputTokens: sql `COALESCE(${taskUsageTable.uncachedInputTokens}, 0) + ${tokenUsage?.uncachedInputTokens ?? 0}`,
+                    reasoningTokens: sql `COALESCE(${taskUsageTable.reasoningTokens}, 0) + ${tokenUsage?.reasoningTokens ?? 0}`,
+                    // PEAK, not sum. Every other column here accumulates; this one must not —
+                    // conflating cumulative-billed with peak-context is what made a 715K run look
+                    // like a 715K context when the real high-water mark was 43K (FINDING-ORCH-007).
+                    peakContextTokens: sql `MAX(COALESCE(${taskUsageTable.peakContextTokens}, 0), ${inputTokens})`,
+                    // Record WHICH call peaked, but only when this call is the new peak.
+                    peakContextAt: sql `CASE WHEN ${inputTokens} > COALESCE(${taskUsageTable.peakContextTokens}, 0) THEN ${taskUsageTable.modelCalls} + 1 ELSE ${taskUsageTable.peakContextAt} END`,
+                },
+            })
+                .run();
+        }
+        catch (err) {
+            this.logger.error({ err }, 'UsagePlugin: post:model_response handler failed');
+        }
+    }
+    onTerminal(payload) {
+        try {
+            const taskId = payload.executionContext.taskId;
+            const acc = this.accumulators.get(taskId);
+            const latencyMs = acc ? Date.now() - acc.startedAt : 0;
+            const rootTaskId = acc?.rootTaskId ?? payload.executionContext.rootTaskId ?? null;
+            this.db
+                .update(taskUsageTable)
+                .set({
+                latencyMs,
+                rootTaskId,
+                isComplete: 1,
+            })
+                .where(eq(taskUsageTable.taskId, taskId))
+                .run();
+            this.accumulators.delete(taskId);
+        }
+        catch (err) {
+            this.logger.error({ err }, 'UsagePlugin: terminal handler failed');
+        }
+    }
+}
+//# sourceMappingURL=usage-plugin.js.map

package/src/plugins/usage-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-plugin.js","sourceRoot":"","sources":["../../../../../../packages/agent/agent-engine-orchestrator/src/plugins/usage-plugin.ts"],"names":[],"mappings":"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"}

package/src/providers/anthropic.d.ts

@@ -0,0 +1,35 @@
+import type { ProviderConfig } from "../validation/index.js";
+import type { TokenUsage } from "@adhd/agent-base-types";
+import type { EngineLogger, EngineConfig } from "../interfaces.js";
+import type { LLMProvider, ProviderChatRequest, ProviderChatResponse } from "./types.js";
+/**
+ * Anthropic is the ONE provider whose headline `input_tokens` EXCLUDES cached tokens —
+ * it reports only the uncached tail after the last cache breakpoint. OpenAI, DeepSeek and
+ * Gemini all report an INCLUSIVE headline.
+ *
+ * So the true total input Anthropic processed is:
+ *   input_tokens + cache_read_input_tokens + cache_creation_input_tokens
+ *
+ * Storing the raw `input_tokens` in the same column as the other providers' inclusive
+ * headline systematically UNDER-COUNTS Anthropic spend (on a cache-warm run most input
+ * lives in cache_read) and makes budget caps bite openai-provider agents far sooner than
+ * anthropic ones for identical real usage. See BUG-ORCH-010.
+ */
+export declare function normaliseAnthropicUsage(sdkUsage: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_input_tokens?: number | null;
+    cache_creation_input_tokens?: number | null;
+}, stopReason: string, maxTokens: number): TokenUsage;
+export declare class AnthropicProvider implements LLMProvider {
+    private readonly client;
+    private readonly providerConfig;
+    private readonly useOauthIdentity;
+    private readonly logger;
+    private readonly config;
+    constructor(providerConfig: Extract<ProviderConfig, {
+        type: "anthropic";
+    }>, config: EngineConfig, logger: EngineLogger);
+    chat(request: ProviderChatRequest): Promise<ProviderChatResponse>;
+}
+//# sourceMappingURL=anthropic.d.ts.map

package/src/providers/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../../../../../packages/agent/agent-engine-orchestrator/src/providers/anthropic.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEnE,OAAO,KAAK,EACR,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EAEvB,MAAM,YAAY,CAAC;AAsBpB;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACnC,QAAQ,EAAE;IACN,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C,EACD,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAClB,UAAU,CAeZ;AAsGD,qBAAa,iBAAkB,YAAW,WAAW;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiD;IAChF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;gBAGlC,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC,EAC9D,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY;IAgClB,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA2G1E"}