@a5c-ai/babysitter-sdk 0.0.29 → 0.0.30

package/dist/cli/nodeTaskRunner.js

@@ -1,9 +1,14 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runNodeTaskFromCli = runNodeTaskFromCli;
+const path_1 = __importDefault(require("path"));
 const tasks_1 = require("../storage/tasks");
 const env_1 = require("../runner/env");
 const nodeRunner_1 = require("../runner/nodeRunner");
+const runtime_1 = require("../runtime/hooks/runtime");
 async function runNodeTaskFromCli(options) {
     const task = options.task ?? (await loadTaskDefinition(options.runDir, options.effectId));
     const hydration = (0, env_1.hydrateCliNodeTaskEnv)(task, {
@@ -11,6 +16,22 @@ async function runNodeTaskFromCli(options) {
         envOverrides: options.envOverrides,
         baseEnv: options.baseEnv ?? process.env,
     });
+    const runId = extractRunIdFromPath(options.runDir);
+    const taskStartTime = Date.now();
+    // Compute project root for hook calls (parent of .a5c dir where plugins/ is located)
+    // runDir is like: /path/to/project/.a5c/runs/<runId>
+    // So we need 3 levels up: runs -> .a5c -> project
+    const projectRoot = path_1.default.dirname(path_1.default.dirname(path_1.default.dirname(options.runDir)));
+    // Call on-task-start hook
+    await (0, runtime_1.callRuntimeHook)("on-task-start", {
+        runId,
+        effectId: options.effectId,
+        taskId: extractInvocationKey(task) || options.effectId,
+        kind: "node",
+    }, {
+        cwd: projectRoot,
+        logger: options.logger,
+    });
     const result = await (0, nodeRunner_1.runNodeTask)({
         ...options,
         task,
@@ -26,6 +47,17 @@ async function runNodeTaskFromCli(options) {
             result,
         });
     }
+    // Call on-task-complete hook
+    await (0, runtime_1.callRuntimeHook)("on-task-complete", {
+        runId,
+        effectId: options.effectId,
+        taskId: extractInvocationKey(task) || options.effectId,
+        status: result.exitCode === 0 ? "ok" : "error",
+        duration: Date.now() - taskStartTime,
+    }, {
+        cwd: projectRoot,
+        logger: options.logger,
+    });
     return {
         ...result,
         hydratedKeys: hydration.hydratedKeys,
@@ -44,3 +76,10 @@ function extractInvocationKey(task) {
     const raw = task?.invocationKey;
     return typeof raw === "string" && raw.trim().length > 0 ? raw : undefined;
 }
+function extractRunIdFromPath(runDir) {
+    // Extract runId from path like .a5c/runs/<runId> or absolute path ending with runId
+    const normalized = path_1.default.normalize(runDir);
+    const parts = normalized.split(path_1.default.sep);
+    // Get the last non-empty part
+    return parts[parts.length - 1] || "unknown";
+}

package/dist/hooks/dispatcher.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Hook Dispatcher
+ * Executes shell hooks from Node.js
+ */
+import type { HookDispatcherOptions, HookResult } from "./types";
+/**
+ * Call a hook by dispatching to the shell hook-dispatcher.sh
+ */
+export declare function callHook(options: HookDispatcherOptions): Promise<HookResult>;
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/hooks/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/hooks/dispatcher.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EACV,qBAAqB,EACrB,UAAU,EAEX,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,UAAU,CAAC,CAkHrB"}

package/dist/hooks/dispatcher.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Hook Dispatcher
+ * Executes shell hooks from Node.js
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callHook = callHook;
+const node_child_process_1 = require("node:child_process");
+const path = __importStar(require("node:path"));
+/**
+ * Call a hook by dispatching to the shell hook-dispatcher.sh
+ */
+async function callHook(options) {
+    const { hookType, payload, cwd = process.cwd(), timeout = 30000, throwOnFailure = false, } = options;
+    // Find the hook-dispatcher.sh script
+    // Assume it's in plugins/babysitter/hooks/hook-dispatcher.sh
+    const dispatcherPath = path.join(cwd, "plugins", "babysitter", "hooks", "hook-dispatcher.sh");
+    const payloadJson = JSON.stringify(payload);
+    const startTime = Date.now();
+    return new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)("bash", [dispatcherPath, hookType], {
+            cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout,
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        // Send payload via stdin
+        child.stdin.write(payloadJson);
+        child.stdin.end();
+        // Collect output
+        child.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        // Handle timeout
+        const timeoutHandle = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+        }, timeout);
+        child.on("error", (error) => {
+            clearTimeout(timeoutHandle);
+            const result = {
+                hookType,
+                success: false,
+                error: `Failed to spawn hook dispatcher: ${error.message}`,
+                executedHooks: [],
+            };
+            if (throwOnFailure) {
+                reject(new Error(result.error));
+            }
+            else {
+                resolve(result);
+            }
+        });
+        child.on("close", (exitCode) => {
+            clearTimeout(timeoutHandle);
+            const duration = Date.now() - startTime;
+            if (timedOut) {
+                const result = {
+                    hookType,
+                    success: false,
+                    error: `Hook execution timed out after ${timeout}ms`,
+                    executedHooks: [],
+                };
+                if (throwOnFailure) {
+                    reject(new Error(result.error));
+                }
+                else {
+                    resolve(result);
+                }
+                return;
+            }
+            // Parse execution results from stderr
+            const executedHooks = parseHookExecutionSummary(stderr);
+            const result = {
+                hookType,
+                success: exitCode === 0,
+                output: stdout ? tryParseJson(stdout) : undefined,
+                error: exitCode !== 0
+                    ? `Hook dispatcher exited with code ${exitCode}`
+                    : undefined,
+                executedHooks,
+            };
+            if (throwOnFailure && !result.success) {
+                reject(new Error(result.error ||
+                    `Hook ${hookType} failed with exit code ${exitCode}`));
+            }
+            else {
+                resolve(result);
+            }
+        });
+    });
+}
+/**
+ * Parse hook execution summary from stderr output
+ * Looks for lines like: "plugin:logger.sh:success"
+ */
+function parseHookExecutionSummary(stderr) {
+    const results = [];
+    const lines = stderr.split("\n");
+    for (const line of lines) {
+        // Look for summary lines: "location:hookname:status[:exitcode]"
+        const match = line.match(/^(per-repo|per-user|plugin):([^:]+):([^:]+)(?::(\d+))?$/);
+        if (match) {
+            const [, location, hookName, status, exitCodeStr] = match;
+            results.push({
+                hookPath: `unknown`, // We don't have full path in summary
+                hookName,
+                hookLocation: location,
+                status: status,
+                exitCode: exitCodeStr ? parseInt(exitCodeStr, 10) : undefined,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Try to parse JSON, return raw string if it fails
+ */
+function tryParseJson(str) {
+    try {
+        return JSON.parse(str);
+    }
+    catch {
+        return str.trim();
+    }
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Hook System API
+ * Public interface for calling hooks from process files
+ */
+export { callHook, } from "./dispatcher";
+export type { HookType, HookResult, HookExecutionResult, HookPayload, HookDispatcherOptions, OnRunStartPayload, OnRunCompletePayload, OnRunFailPayload, OnTaskStartPayload, OnTaskCompletePayload, OnStepDispatchPayload, OnIterationStartPayload, OnIterationEndPayload, OnBreakpointPayload, PreCommitPayload, PreBranchPayload, PostPlanningPayload, OnScorePayload, } from "./types";
+/**
+ * Helper function to create hook payloads with proper typing
+ */
+export declare function createHookPayload<T extends {
+    hookType: string;
+}>(payload: T): T & {
+    timestamp: string;
+};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,GACT,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,QAAQ,EACR,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,GACf,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC9D,OAAO,EAAE,CAAC,GACT,CAAC,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAK3B"}

package/dist/hooks/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Hook System API
+ * Public interface for calling hooks from process files
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callHook = void 0;
+exports.createHookPayload = createHookPayload;
+var dispatcher_1 = require("./dispatcher");
+Object.defineProperty(exports, "callHook", { enumerable: true, get: function () { return dispatcher_1.callHook; } });
+/**
+ * Helper function to create hook payloads with proper typing
+ */
+function createHookPayload(payload) {
+    return {
+        ...payload,
+        timestamp: new Date().toISOString(),
+    };
+}

package/dist/hooks/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Hook System Types
+ * Type definitions for the generalized hook system
+ */
+export type HookType = "on-run-start" | "on-run-complete" | "on-run-fail" | "on-task-start" | "on-task-complete" | "on-step-dispatch" | "on-iteration-start" | "on-iteration-end" | "on-breakpoint" | "pre-commit" | "pre-branch" | "post-planning" | "on-score" | string;
+export interface HookResult {
+    hookType: HookType;
+    success: boolean;
+    output?: unknown;
+    error?: string;
+    executedHooks: HookExecutionResult[];
+}
+export interface HookExecutionResult {
+    hookPath: string;
+    hookName: string;
+    hookLocation: "per-repo" | "per-user" | "plugin";
+    status: "success" | "failed";
+    exitCode?: number;
+    error?: string;
+}
+export interface OnRunStartPayload {
+    hookType: "on-run-start";
+    runId: string;
+    processId: string;
+    entry: string;
+    inputs?: unknown;
+    timestamp: string;
+}
+export interface OnRunCompletePayload {
+    hookType: "on-run-complete";
+    runId: string;
+    status: "completed";
+    output?: unknown;
+    duration: number;
+    timestamp: string;
+}
+export interface OnRunFailPayload {
+    hookType: "on-run-fail";
+    runId: string;
+    status: "failed";
+    error: string;
+    duration: number;
+    timestamp: string;
+}
+export interface OnTaskStartPayload {
+    hookType: "on-task-start";
+    runId: string;
+    effectId: string;
+    taskId: string;
+    kind: string;
+    label?: string;
+    timestamp: string;
+}
+export interface OnTaskCompletePayload {
+    hookType: "on-task-complete";
+    runId: string;
+    effectId: string;
+    taskId: string;
+    status: "ok" | "error" | "timeout";
+    result?: unknown;
+    duration: number;
+    timestamp: string;
+}
+export interface OnStepDispatchPayload {
+    hookType: "on-step-dispatch";
+    runId: string;
+    stepId: string;
+    action: string;
+    timestamp: string;
+}
+export interface OnIterationStartPayload {
+    hookType: "on-iteration-start";
+    runId: string;
+    iteration: number;
+    timestamp: string;
+}
+export interface OnIterationEndPayload {
+    hookType: "on-iteration-end";
+    runId: string;
+    iteration: number;
+    status: "completed" | "failed" | "waiting";
+    timestamp: string;
+}
+export interface OnBreakpointPayload {
+    hookType: "on-breakpoint";
+    question: string;
+    title?: string;
+    runId?: string;
+    reason?: string;
+    context?: {
+        runId?: string;
+        files?: Array<{
+            path: string;
+            format: "markdown" | "code";
+            language?: string;
+        }>;
+    };
+}
+export interface PreCommitPayload {
+    hookType: "pre-commit";
+    runId: string;
+    files: string[];
+    message: string;
+    author?: string;
+    timestamp: string;
+}
+export interface PreBranchPayload {
+    hookType: "pre-branch";
+    runId: string;
+    branch: string;
+    base: string;
+    timestamp: string;
+}
+export interface PostPlanningPayload {
+    hookType: "post-planning";
+    runId: string;
+    planFile: string;
+    timestamp: string;
+}
+export interface OnScorePayload {
+    hookType: "on-score";
+    runId: string;
+    target: string;
+    score?: number;
+    metrics?: Record<string, unknown>;
+    timestamp: string;
+}
+export type HookPayload = OnRunStartPayload | OnRunCompletePayload | OnRunFailPayload | OnTaskStartPayload | OnTaskCompletePayload | OnStepDispatchPayload | OnIterationStartPayload | OnIterationEndPayload | OnBreakpointPayload | PreCommitPayload | PreBranchPayload | PostPlanningPayload | OnScorePayload | {
+    hookType: string;
+    [key: string]: unknown;
+};
+export interface HookDispatcherOptions {
+    /**
+     * Hook type to execute (e.g., "on-run-start", "pre-commit")
+     */
+    hookType: HookType;
+    /**
+     * Payload to pass to hooks (will be JSON.stringify'd and sent via stdin)
+     */
+    payload: HookPayload;
+    /**
+     * Working directory for hook execution (defaults to process.cwd())
+     */
+    cwd?: string;
+    /**
+     * Timeout in milliseconds for hook execution (defaults to 30000)
+     */
+    timeout?: number;
+    /**
+     * Whether to throw on hook execution failures (defaults to false)
+     */
+    throwOnFailure?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/hooks/types.d.ts.map

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

package/dist/hooks/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Hook System Types
+ * Type definitions for the generalized hook system
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -7,4 +7,5 @@ export * from "./runner";
 export * from "./cli/nodeTaskRunner";
 export * from "./cli/main";
 export * from "./testing";
+export * from "./hooks";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -23,3 +23,4 @@ __exportStar(require("./runner"), exports);
 __exportStar(require("./cli/nodeTaskRunner"), exports);
 __exportStar(require("./cli/main"), exports);
 __exportStar(require("./testing"), exports);
+__exportStar(require("./hooks"), exports);

package/dist/runtime/createRun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createRun.d.ts","sourceRoot":"","sources":["../../src/runtime/createRun.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAEjE,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkDnF"}
+{"version":3,"file":"createRun.d.ts","sourceRoot":"","sources":["../../src/runtime/createRun.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGjE,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAyEnF"}

package/dist/runtime/createRun.js

@@ -10,6 +10,7 @@ const journal_1 = require("../storage/journal");
 const lock_1 = require("../storage/lock");
 const paths_1 = require("../storage/paths");
 const ulids_1 = require("../storage/ulids");
+const runtime_1 = require("./hooks/runtime");
 async function createRun(options) {
     const runId = options.runId ?? (0, ulids_1.nextUlid)();
     validateRunId(runId);
@@ -54,6 +55,23 @@ async function createRun(options) {
             await (0, lock_1.releaseRunLock)(runDir);
         }
     }
+    // Call on-run-start hook
+    const entryString = metadata.entrypoint.exportName
+        ? `${metadata.entrypoint.importPath}#${metadata.entrypoint.exportName}`
+        : metadata.entrypoint.importPath;
+    // Call hook from project root (parent of .a5c dir) where plugins/ is located
+    // runDir is like: /path/to/project/.a5c/runs/<runId>
+    // So we need 3 levels up: runs -> .a5c -> project
+    const projectRoot = path_1.default.dirname(path_1.default.dirname(path_1.default.dirname(runDir)));
+    await (0, runtime_1.callRuntimeHook)("on-run-start", {
+        runId,
+        processId: metadata.processId,
+        entry: entryString,
+        inputs: options.inputs,
+    }, {
+        cwd: projectRoot,
+        logger: options.logger,
+    });
     return {
         runId,
         runDir,

package/dist/runtime/hooks/runtime.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Runtime hook integration helpers
+ *
+ * Provides safe hook calling with error handling for SDK runtime.
+ * Hook failures are logged but do not break orchestration.
+ */
+import type { HookType, HookResult } from "../../hooks/types";
+export interface RuntimeHookOptions {
+    cwd: string;
+    timeout?: number;
+    logger?: (message: string) => void;
+}
+/**
+ * Safely call a hook from SDK runtime with error handling.
+ *
+ * Hook failures are logged but do not throw - orchestration continues.
+ *
+ * @param hookType - The type of hook to call
+ * @param payload - The hook payload
+ * @param options - Runtime options (cwd, timeout, logger)
+ * @returns HookResult with execution details
+ */
+export declare function callRuntimeHook(hookType: HookType, payload: Record<string, unknown>, options: RuntimeHookOptions): Promise<HookResult>;
+/**
+ * Create a hook payload with automatic timestamp.
+ */
+export declare function createRuntimeHookPayload<T extends Record<string, unknown>>(hookType: HookType, data: T): T & {
+    hookType: HookType;
+    timestamp: string;
+};
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime/hooks/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/runtime/hooks/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,UAAU,CAAC,CA2CrB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,CAAC,GACN,CAAC,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAM/C"}

package/dist/runtime/hooks/runtime.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Runtime hook integration helpers
+ *
+ * Provides safe hook calling with error handling for SDK runtime.
+ * Hook failures are logged but do not break orchestration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callRuntimeHook = callRuntimeHook;
+exports.createRuntimeHookPayload = createRuntimeHookPayload;
+const dispatcher_1 = require("../../hooks/dispatcher");
+/**
+ * Safely call a hook from SDK runtime with error handling.
+ *
+ * Hook failures are logged but do not throw - orchestration continues.
+ *
+ * @param hookType - The type of hook to call
+ * @param payload - The hook payload
+ * @param options - Runtime options (cwd, timeout, logger)
+ * @returns HookResult with execution details
+ */
+async function callRuntimeHook(hookType, payload, options) {
+    const { cwd, timeout = 30000, logger } = options;
+    try {
+        // Ensure timestamp is present
+        const fullPayload = {
+            ...payload,
+            hookType,
+            timestamp: payload.timestamp || new Date().toISOString(),
+        };
+        const result = await (0, dispatcher_1.callHook)({
+            hookType,
+            payload: fullPayload,
+            cwd,
+            timeout,
+        });
+        // Log hook execution if logger provided
+        if (logger && result.executedHooks.length > 0) {
+            logger(`[hooks] Executed ${result.executedHooks.length} hook(s) for ${hookType}`);
+        }
+        return result;
+    }
+    catch (error) {
+        // Hook failures should not break orchestration
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (logger) {
+            logger(`[hooks] Hook execution failed for ${hookType}: ${errorMessage}`);
+        }
+        // Return a failure result instead of throwing
+        return {
+            hookType,
+            success: false,
+            error: errorMessage,
+            executedHooks: [],
+        };
+    }
+}
+/**
+ * Create a hook payload with automatic timestamp.
+ */
+function createRuntimeHookPayload(hookType, data) {
+    return {
+        ...data,
+        hookType,
+        timestamp: new Date().toISOString(),
+    };
+}

package/dist/runtime/intrinsics/hook.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Hook Intrinsic
+ * Allows process files to call hooks directly
+ */
+import type { InternalProcessContext } from "../processContext";
+import type { HookResult } from "../../hooks/types";
+export interface HookIntrinsicOptions {
+    /**
+     * Optional label for this hook invocation (for journal/logging)
+     */
+    label?: string;
+    /**
+     * Timeout in milliseconds (defaults to 30000)
+     */
+    timeout?: number;
+    /**
+     * Whether to throw on hook failures (defaults to false)
+     */
+    throwOnFailure?: boolean;
+}
+/**
+ * Run a hook from within a process
+ * This is exposed as ctx.hook() in process files
+ */
+export declare function runHookIntrinsic(hookType: string, payload: Record<string, unknown>, context: InternalProcessContext, options?: HookIntrinsicOptions): Promise<HookResult>;
+//# sourceMappingURL=hook.d.ts.map

package/dist/runtime/intrinsics/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../src/runtime/intrinsics/hook.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,sBAAsB,EAC/B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,UAAU,CAAC,CAwCrB"}