@pellux/goodvibes-sdk 0.18.14 → 0.18.16

package/dist/_internal/platform/hooks/dispatcher.js

@@ -0,0 +1,376 @@
+import { readFileSync, statSync } from 'fs';
+import { dirname } from 'path';
+import { matchesEventPath, matchesMatcher } from '@pellux/goodvibes-sdk/platform/hooks/matcher';
+import { getHookPointContract } from '@pellux/goodvibes-sdk/platform/hooks/contracts';
+import { HookActivityTracker } from '@pellux/goodvibes-sdk/platform/hooks/activity';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import * as commandRunner from '@pellux/goodvibes-sdk/platform/hooks/runners/command';
+import * as promptRunner from './runners/prompt.js';
+import * as agentRunner from './runners/agent.js';
+import * as httpRunner from '@pellux/goodvibes-sdk/platform/hooks/runners/http';
+import * as tsRunner from '@pellux/goodvibes-sdk/platform/hooks/runners/typescript';
+import { fireTriggers } from '@pellux/goodvibes-sdk/platform/workflow/trigger-executor';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+/** Global timeout: if cumulative hook time exceeds this, skip remaining */
+const GLOBAL_TIMEOUT_MS = 120_000;
+function runHook(hook, event, deps, hooksBaseDirectory) {
+    switch (hook.type) {
+        case 'command': return commandRunner.run(hook, event);
+        case 'prompt': return promptRunner.run(hook, event, deps.toolLLM ?? null);
+        case 'agent':
+            if (!deps.agentManager) {
+                return Promise.resolve({ ok: false, error: 'agent hook runner is not configured in this runtime' });
+            }
+            return agentRunner.run(hook, event, deps.agentManager);
+        case 'http': return httpRunner.run(hook, event);
+        case 'ts': {
+            const projectRoot = deps.projectRoot ?? hooksBaseDirectory;
+            if (!projectRoot) {
+                return Promise.resolve({ ok: false, error: 'ts hook runner requires an explicit project root' });
+            }
+            return tsRunner.run(hook, event, projectRoot);
+        }
+        default:
+            return Promise.resolve({ ok: false, error: `unknown hook type: ${hook.type}` });
+    }
+}
+export class HookDispatcher {
+    hooks = new Map();
+    chains = [];
+    triggerManager = null;
+    hooksBaseDirectory = null;
+    runnerDeps;
+    activityTracker;
+    constructor(runnerDeps = {}, activityTracker = new HookActivityTracker()) {
+        this.runnerDeps = runnerDeps;
+        this.activityTracker = activityTracker;
+    }
+    /** Attach a TriggerManager so hook events automatically fire matching triggers. */
+    setTriggerManager(tm) {
+        this.triggerManager = tm;
+    }
+    /** Load hooks from hooks.json file */
+    loadFromFile(filePath) {
+        this.hooksBaseDirectory = dirname(filePath);
+        try {
+            // Warn if hooks.json is world-writable — it is a trust boundary.
+            try {
+                const st = statSync(filePath);
+                // st.mode & 0o002 is the world-writable bit
+                if ((st.mode & 0o002) !== 0) {
+                    logger.info('HookDispatcher: hooks.json is world-writable — only load trusted hooks files', { filePath });
+                }
+            }
+            catch {
+                // Stat failure is non-fatal; proceed with load
+            }
+            const raw = readFileSync(filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            const VALID_HOOK_TYPES = new Set(['command', 'prompt', 'agent', 'http', 'ts']);
+            // Validate and load hooks
+            if (parsed.hooks !== undefined) {
+                if (typeof parsed.hooks !== 'object' || parsed.hooks === null || Array.isArray(parsed.hooks)) {
+                    logger.info('HookDispatcher: hooks.json "hooks" field must be an object, skipping', { filePath });
+                }
+                else {
+                    for (const [pattern, defs] of Object.entries(parsed.hooks)) {
+                        if (!Array.isArray(defs)) {
+                            logger.info('HookDispatcher: hook pattern value must be an array, skipping', { filePath, pattern });
+                            continue;
+                        }
+                        for (const def of defs) {
+                            if (typeof def !== 'object' || def === null) {
+                                logger.info('HookDispatcher: hook definition must be an object, skipping', { filePath, pattern });
+                                continue;
+                            }
+                            const d = def;
+                            if (typeof d.type !== 'string' || !VALID_HOOK_TYPES.has(d.type)) {
+                                logger.info('HookDispatcher: hook missing valid "type" field, skipping', { filePath, pattern, type: d.type });
+                                continue;
+                            }
+                            if (typeof d.match !== 'string') {
+                                logger.info('HookDispatcher: hook missing "match" field, skipping', { filePath, pattern });
+                                continue;
+                            }
+                            this.register(pattern, d);
+                        }
+                    }
+                }
+            }
+            // Validate and load chains
+            if (parsed.chains !== undefined) {
+                if (!Array.isArray(parsed.chains)) {
+                    logger.info('HookDispatcher: hooks.json "chains" field must be an array, skipping', { filePath });
+                }
+                else {
+                    for (const chain of parsed.chains) {
+                        if (typeof chain !== 'object' || chain === null) {
+                            logger.info('HookDispatcher: chain entry must be an object, skipping', { filePath });
+                            continue;
+                        }
+                        const c = chain;
+                        if (typeof c.name !== 'string') {
+                            logger.info('HookDispatcher: chain missing "name" field, skipping', { filePath });
+                            continue;
+                        }
+                        if (!Array.isArray(c.steps)) {
+                            logger.info('HookDispatcher: chain missing "steps" array, skipping', { filePath, name: c.name });
+                            continue;
+                        }
+                        if (typeof c.action !== 'object' || c.action === null) {
+                            logger.info('HookDispatcher: chain missing "action" object, skipping', { filePath, name: c.name });
+                            continue;
+                        }
+                        const action = c.action;
+                        if (typeof action.type !== 'string' || !VALID_HOOK_TYPES.has(action.type)) {
+                            logger.info('HookDispatcher: chain action missing valid "type" field, skipping', { filePath, name: c.name });
+                            continue;
+                        }
+                        if (typeof action.match !== 'string') {
+                            logger.info('HookDispatcher: chain action missing "match" field, skipping', { filePath, name: c.name });
+                            continue;
+                        }
+                        this.registerChain(c);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            logger.error('HookDispatcher: failed to load hooks file', {
+                filePath,
+                error: summarizeError(err),
+            });
+        }
+    }
+    /** Register a hook programmatically */
+    register(eventPattern, hook) {
+        const existing = this.hooks.get(eventPattern);
+        if (existing) {
+            existing.push(hook);
+        }
+        else {
+            this.hooks.set(eventPattern, [hook]);
+        }
+    }
+    /** Register a chain programmatically */
+    registerChain(chain) {
+        this.chains.push(chain);
+    }
+    /**
+     * Fire an event and run all matching hooks.
+     *
+     * All matching hooks run sequentially. For Pre phase, the first deny sets
+     * the aggregated decision; subsequent hooks still execute (for
+     * logging/auditing) but their deny decisions don't change the outcome.
+     * For all hooks: additionalContext strings are concatenated.
+     * Once hooks are auto-removed after first execution.
+     * Async hooks fire and forget.
+     */
+    async fire(event) {
+        const contract = getHookPointContract(event.path);
+        const matchingEntries = [];
+        for (const [pattern, defs] of this.hooks.entries()) {
+            if (matchesEventPath(pattern, event.path)) {
+                for (const hook of defs) {
+                    const specificValue = event.specific;
+                    if (matchesMatcher(hook.matcher, specificValue)) {
+                        matchingEntries.push({ pattern, hook });
+                    }
+                }
+            }
+        }
+        if (matchingEntries.length === 0) {
+            return { ok: true };
+        }
+        const aggregated = { ok: true };
+        const contextParts = [];
+        let updatedInput;
+        const onceToRemove = [];
+        const startTime = Date.now();
+        for (const { pattern, hook } of matchingEntries) {
+            // Global timeout check
+            if (Date.now() - startTime > GLOBAL_TIMEOUT_MS) {
+                logger.error('HookDispatcher: global timeout exceeded, skipping remaining hooks', {
+                    path: event.path,
+                });
+                break;
+            }
+            // Async hooks fire and forget
+            if (hook.async) {
+                const asyncStart = Date.now();
+                runHook(hook, event, this.runnerDeps, this.hooksBaseDirectory)
+                    .then((result) => {
+                    this.activityTracker.record(event, {
+                        pattern,
+                        hookName: hook.name,
+                        hookType: hook.type,
+                        result,
+                        durationMs: Date.now() - asyncStart,
+                        async: true,
+                    });
+                })
+                    .catch((err) => {
+                    const message = summarizeError(err);
+                    logger.error('HookDispatcher: async hook error', {
+                        path: event.path,
+                        error: message,
+                    });
+                    this.activityTracker.record(event, {
+                        pattern,
+                        hookName: hook.name,
+                        hookType: hook.type,
+                        result: { ok: false, error: message },
+                        durationMs: Date.now() - asyncStart,
+                        async: true,
+                    });
+                });
+                if (hook.once)
+                    onceToRemove.push({ pattern, hook });
+                continue;
+            }
+            let result;
+            const hookStart = Date.now();
+            try {
+                result = await runHook(hook, event, this.runnerDeps, this.hooksBaseDirectory);
+            }
+            catch (err) {
+                const message = summarizeError(err);
+                logger.error('HookDispatcher: hook threw unexpectedly', {
+                    path: event.path,
+                    error: message,
+                });
+                result = { ok: false, error: message };
+            }
+            this.activityTracker.record(event, {
+                pattern,
+                hookName: hook.name,
+                hookType: hook.type,
+                result,
+                durationMs: Date.now() - hookStart,
+                async: false,
+            });
+            if (hook.once)
+                onceToRemove.push({ pattern, hook });
+            if (!result.ok) {
+                aggregated.ok = false;
+                if (!aggregated.error)
+                    aggregated.error = result.error;
+            }
+            // For Pre hooks: first deny wins
+            if ((contract?.canDeny ?? event.phase === 'Pre') && result.decision === 'deny') {
+                if (aggregated.decision !== 'deny') {
+                    aggregated.decision = 'deny';
+                    aggregated.reason = result.reason;
+                }
+            }
+            else if (result.decision && (contract?.canDeny ?? event.phase === 'Pre') && aggregated.decision !== 'deny') {
+                aggregated.decision = result.decision;
+                if (result.reason)
+                    aggregated.reason = result.reason;
+            }
+            // Last updatedInput wins
+            if (result.updatedInput && (contract?.canMutateInput ?? true)) {
+                updatedInput = result.updatedInput;
+            }
+            if (result.additionalContext && (contract?.canInjectContext ?? true)) {
+                contextParts.push(result.additionalContext);
+            }
+        }
+        // Remove once hooks
+        for (const { pattern, hook } of onceToRemove) {
+            const defs = this.hooks.get(pattern);
+            if (defs) {
+                const idx = defs.indexOf(hook);
+                if (idx !== -1)
+                    defs.splice(idx, 1);
+                if (defs.length === 0)
+                    this.hooks.delete(pattern);
+            }
+        }
+        if (updatedInput)
+            aggregated.updatedInput = updatedInput;
+        if (contextParts.length > 0)
+            aggregated.additionalContext = contextParts.join('\n');
+        // Fire matching triggers (fire-and-forget)
+        if (this.triggerManager) {
+            fireTriggers(event, this.triggerManager).catch((err) => {
+                logger.debug('HookDispatcher: trigger fire error', {
+                    path: event.path,
+                    error: summarizeError(err),
+                });
+            });
+        }
+        return aggregated;
+    }
+    /** Get all registered hooks (for debugging/inspection) */
+    getHooks() {
+        return new Map(this.hooks);
+    }
+    /** Get all registered chains */
+    getChains() {
+        return [...this.chains];
+    }
+    /** Remove all hooks (for testing) */
+    clear() {
+        this.hooks.clear();
+        this.chains = [];
+    }
+    /**
+     * List all registered hooks as a flat array with their event pattern included.
+     */
+    listHooks() {
+        const result = [];
+        for (const [pattern, defs] of this.hooks.entries()) {
+            for (const hook of defs) {
+                result.push({ pattern, hook });
+            }
+        }
+        return result;
+    }
+    /**
+     * Enable a named hook (sets enabled: true).
+     * Returns true if found, false if no hook with that name exists.
+     */
+    enableHook(name) {
+        for (const defs of this.hooks.values()) {
+            for (const hook of defs) {
+                if (hook.name === name) {
+                    hook.enabled = true;
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Disable a named hook (sets enabled: false).
+     * Returns true if found, false if no hook with that name exists.
+     */
+    disableHook(name) {
+        for (const defs of this.hooks.values()) {
+            for (const hook of defs) {
+                if (hook.name === name) {
+                    hook.enabled = false;
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Remove a named hook from the registry.
+     * Returns true if removed, false if not found.
+     */
+    unregister(name) {
+        for (const [pattern, defs] of this.hooks.entries()) {
+            const idx = defs.findIndex((h) => h.name === name);
+            if (idx !== -1) {
+                defs.splice(idx, 1);
+                if (defs.length === 0)
+                    this.hooks.delete(pattern);
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/dist/_internal/platform/hooks/hook-api.d.ts

@@ -0,0 +1,72 @@
+import type { HookPointContract } from '@pellux/goodvibes-sdk/platform/hooks/contracts';
+import type { HookChain, HookDefinition, HookType } from '@pellux/goodvibes-sdk/platform/hooks/types';
+import type { HookAuthoringAction, HookConfigInspection, HookSimulationResult } from './workbench.js';
+export interface HookContractRecord extends HookPointContract {
+}
+export interface HookWorkbenchApi {
+    getFilePath(): string;
+    listManagedHooks(): Array<{
+        pattern: string;
+        hook: HookDefinition;
+    }>;
+    listManagedChains(): HookChain[];
+    listRecentActions(limit?: number): HookAuthoringAction[];
+    load(path?: string): void;
+    reload(path?: string): Promise<void>;
+    scaffoldHook(name: string, match: string, type: HookType): Promise<HookDefinition>;
+    scaffoldChain(name: string, matches: readonly string[]): Promise<HookChain>;
+    remove(name: string): Promise<boolean>;
+    toggle(name: string, enabled: boolean): Promise<boolean>;
+    simulate(eventPath: string, payload?: Record<string, unknown>): HookSimulationResult;
+    inspect(path: string): HookConfigInspection;
+    export(path: string): Promise<string>;
+    import(path: string, strategy?: 'merge' | 'replace'): Promise<void>;
+}
+export interface HookApiDispatcher {
+    listHooks(): Array<{
+        pattern: string;
+        hook: HookDefinition;
+    }>;
+    listChains(): HookChain[];
+}
+export interface HookApiWorkbenchRuntime {
+    getHooksFilePath(): string;
+    listManagedHooks(): Array<{
+        pattern: string;
+        hook: HookDefinition;
+    }>;
+    listManagedChains(): HookChain[];
+    listRecentActions(limit?: number): HookAuthoringAction[];
+    loadManagedConfig(path?: string): void;
+    loadAndApplyManagedHooks(path?: string): Promise<void>;
+    scaffoldHook(name: string, match: string, type: HookType): HookDefinition;
+    scaffoldChain(name: string, matches: readonly string[]): HookChain;
+    removeManagedEntry(name: string): boolean;
+    toggleManagedHook(name: string, enabled: boolean): boolean;
+    simulate(eventPath: string, payload?: Record<string, unknown>): HookSimulationResult;
+    inspectManagedConfig(path: string): HookConfigInspection;
+    exportManagedConfig(path: string): Promise<string>;
+    importManagedConfig(path: string, strategy?: 'merge' | 'replace'): void;
+    saveManagedConfig(path?: string): Promise<void>;
+}
+export interface HookContractSource {
+    listContracts(): readonly HookPointContract[];
+}
+export interface HookApi {
+    contracts(filter?: string): readonly HookContractRecord[];
+    dispatcher: {
+        listHooks(): Array<{
+            pattern: string;
+            hook: HookDefinition;
+        }>;
+        listChains(): HookChain[];
+    };
+    workbench: HookWorkbenchApi;
+}
+export interface CreateHookApiOptions {
+    readonly dispatcher: HookApiDispatcher;
+    readonly workbench: HookApiWorkbenchRuntime;
+    readonly listContracts: HookContractSource['listContracts'];
+}
+export declare function createHookApi(options: CreateHookApiOptions): HookApi;
+//# sourceMappingURL=hook-api.d.ts.map

package/dist/_internal/platform/hooks/hook-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-api.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/hooks/hook-api.ts"],"names":[],"mappings":"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"}

package/dist/_internal/platform/hooks/hook-api.js

@@ -0,0 +1,98 @@
+function normalizeFilter(filter) {
+    const value = filter?.trim().toLowerCase();
+    return value && value.length > 0 ? value : null;
+}
+export function createHookApi(options) {
+    return {
+        contracts(filter) {
+            const query = normalizeFilter(filter);
+            const contracts = options.listContracts();
+            if (!query) {
+                return contracts;
+            }
+            return contracts.filter((contract) => (contract.pattern.toLowerCase().includes(query)
+                || contract.description.toLowerCase().includes(query)
+                || contract.authority.toLowerCase().includes(query)
+                || contract.executionMode.toLowerCase().includes(query)));
+        },
+        dispatcher: {
+            listHooks() {
+                return options.dispatcher.listHooks();
+            },
+            listChains() {
+                return options.dispatcher.listChains();
+            },
+        },
+        workbench: {
+            getFilePath() {
+                return options.workbench.getHooksFilePath();
+            },
+            listManagedHooks() {
+                return options.workbench.listManagedHooks();
+            },
+            listManagedChains() {
+                return options.workbench.listManagedChains();
+            },
+            listRecentActions(limit = 8) {
+                return options.workbench.listRecentActions(limit);
+            },
+            load(path) {
+                options.workbench.loadManagedConfig(path);
+            },
+            reload(path) {
+                return options.workbench.loadAndApplyManagedHooks(path);
+            },
+            async scaffoldHook(name, match, type) {
+                options.workbench.loadManagedConfig();
+                const hook = options.workbench.scaffoldHook(name, match, type);
+                await options.workbench.saveManagedConfig();
+                await options.workbench.loadAndApplyManagedHooks();
+                return hook;
+            },
+            async scaffoldChain(name, matches) {
+                options.workbench.loadManagedConfig();
+                const chain = options.workbench.scaffoldChain(name, matches);
+                await options.workbench.saveManagedConfig();
+                await options.workbench.loadAndApplyManagedHooks();
+                return chain;
+            },
+            async remove(name) {
+                options.workbench.loadManagedConfig();
+                const removed = options.workbench.removeManagedEntry(name);
+                if (!removed) {
+                    return false;
+                }
+                await options.workbench.saveManagedConfig();
+                await options.workbench.loadAndApplyManagedHooks();
+                return true;
+            },
+            async toggle(name, enabled) {
+                options.workbench.loadManagedConfig();
+                const changed = options.workbench.toggleManagedHook(name, enabled);
+                if (!changed) {
+                    return false;
+                }
+                await options.workbench.saveManagedConfig();
+                await options.workbench.loadAndApplyManagedHooks();
+                return true;
+            },
+            simulate(eventPath, payload = {}) {
+                options.workbench.loadManagedConfig();
+                return options.workbench.simulate(eventPath, payload);
+            },
+            inspect(path) {
+                return options.workbench.inspectManagedConfig(path);
+            },
+            export(path) {
+                options.workbench.loadManagedConfig();
+                return options.workbench.exportManagedConfig(path);
+            },
+            async import(path, strategy = 'merge') {
+                options.workbench.loadManagedConfig();
+                options.workbench.importManagedConfig(path, strategy);
+                await options.workbench.saveManagedConfig();
+                await options.workbench.loadAndApplyManagedHooks();
+            },
+        },
+    };
+}

package/dist/_internal/platform/hooks/index.d.ts

@@ -0,0 +1,19 @@
+export { HookDispatcher } from './dispatcher.js';
+export { ChainEngine } from './chain-engine.js';
+export { HookActivityTracker } from '@pellux/goodvibes-sdk/platform/hooks/activity';
+export { HookWorkbench, createHookWorkbench } from './workbench.js';
+export { createHookApi } from './hook-api.js';
+export type { CreateHookApiOptions, HookApi, HookApiDispatcher, HookApiWorkbenchRuntime, HookContractRecord, HookContractSource, HookWorkbenchApi, } from './hook-api.js';
+export type { HookPhase, HookCategory, HookEventPath, HookEvent, HookResult, HookType, HookDefinition, ChainStep, HookChain, HooksConfig, } from '@pellux/goodvibes-sdk/platform/hooks/types';
+export type { HookActivityRecord } from '@pellux/goodvibes-sdk/platform/hooks/activity';
+export type { HookAuthoringAction, HookConfigInspection, HookSimulationResult } from './workbench.js';
+export type { HookExecutionMode, HookAuthority, HookPointContract } from '@pellux/goodvibes-sdk/platform/hooks/contracts';
+import type { AgentManager } from '../tools/agent/index.js';
+export { listHookPointContracts, getHookPointContract, parseHookPath, } from '@pellux/goodvibes-sdk/platform/hooks/contracts';
+import { HookActivityTracker } from '@pellux/goodvibes-sdk/platform/hooks/activity';
+import { HookDispatcher } from './dispatcher.js';
+export declare function createHookDispatcher(config?: {
+    readonly agentManager?: Pick<AgentManager, 'spawn' | 'getStatus' | 'cancel'>;
+    readonly activityTracker?: HookActivityTracker;
+}): HookDispatcher;
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EACV,oBAAoB,EACpB,OAAO,EACP,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,SAAS,EACT,UAAU,EACV,QAAQ,EACR,cAAc,EACd,SAAS,EACT,SAAS,EACT,WAAW,GACZ,MAAM,4CAA4C,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AACxF,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtG,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AAC1H,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,aAAa,GACd,MAAM,gDAAgD,CAAC;AAExD,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,wBAAgB,oBAAoB,CAAC,MAAM,GAAE;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC,CAAC;IAC7E,QAAQ,CAAC,eAAe,CAAC,EAAE,mBAAmB,CAAC;CAC3C,GAAG,cAAc,CAKtB"}

package/dist/_internal/platform/hooks/index.js

@@ -0,0 +1,11 @@
+export { HookDispatcher } from './dispatcher.js';
+export { ChainEngine } from './chain-engine.js';
+export { HookActivityTracker } from '@pellux/goodvibes-sdk/platform/hooks/activity';
+export { HookWorkbench, createHookWorkbench } from './workbench.js';
+export { createHookApi } from './hook-api.js';
+export { listHookPointContracts, getHookPointContract, parseHookPath, } from '@pellux/goodvibes-sdk/platform/hooks/contracts';
+import { HookActivityTracker } from '@pellux/goodvibes-sdk/platform/hooks/activity';
+import { HookDispatcher } from './dispatcher.js';
+export function createHookDispatcher(config = {}) {
+    return new HookDispatcher({ agentManager: config.agentManager }, config.activityTracker);
+}

package/dist/_internal/platform/hooks/runners/agent.d.ts

@@ -0,0 +1,16 @@
+import type { HookDefinition, HookResult, HookEvent } from '@pellux/goodvibes-sdk/platform/hooks/types';
+import type { AgentManager } from '../../tools/agent/index.js';
+/**
+ * Agent hook runner — spawns a subagent via AgentManager and waits for
+ * completion up to the hook's configured timeout.
+ *
+ * The hook's `prompt` field (with `$ARGUMENTS` replaced by the event JSON)
+ * becomes the agent task description.
+ *
+ * Since AgentManager currently registers agents synchronously and doesn't
+ * execute them in a true background thread, the hook marks the agent as
+ * completed immediately and returns a success result.  When real background
+ * execution is wired the status polling loop below will take effect.
+ */
+export declare function run(hook: HookDefinition, event: HookEvent, manager: Pick<AgentManager, 'spawn' | 'getStatus' | 'cancel'>): Promise<HookResult>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/_internal/platform/hooks/runners/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/hooks/runners/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,4CAA4C,CAAC;AAExG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG/D;;;;;;;;;;;GAWG;AACH,wBAAsB,GAAG,CACvB,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC,GAC5D,OAAO,CAAC,UAAU,CAAC,CAuErB"}