@goodfoot/agent-hooks 1.0.0

package/dist/core/transport.js

@@ -0,0 +1,231 @@
+/**
+ * Transport abstraction and the shared driver.
+ *
+ * Core owns the try/catch skeleton — stdin read, JSON parse, handler
+ * invocation, outcome classification, buffered single-write emission, process
+ * exit — and has **no knowledge of exit codes or stdout policy**: every wire
+ * decision is delegated to the agent's {@link Transport.finalize}, a pure
+ * mapping from {@link HookOutcome} to `{ stdout?, stderr?, exitCode }`. Agent
+ * transports are data-heavy adapters; they must not re-implement driver logic.
+ * @module
+ * @example
+ * ```typescript
+ * const transport: Transport<MyOutput> = {
+ *   finalize: (outcome) => {
+ *     if (outcome.kind === "response") {
+ *       return { stdout: JSON.stringify(outcome.output ?? {}), exitCode: 0 };
+ *     }
+ *     return { stderr: "blocked", exitCode: 2 };
+ *   },
+ * };
+ *
+ * await drive(transport, myHook);
+ * ```
+ */
+import { logger } from "./logger.js";
+import { parseStdinJson, readStdin } from "./stdin.js";
+/**
+ * Error thrown by a hook handler to signal an intentional block.
+ *
+ * `drive()` classifies a caught {@link HookBlockError} **before** consulting
+ * the `unexpectedError` policy: it always routes to the `block` outcome,
+ * under every policy value, so an advisory event's in-flight block decision
+ * survives a crash mid-computation. Any other throw is subject to policy as
+ * usual. Agents may subclass or re-export this class; each agent's transport
+ * owns the wire translation of the `block` outcome.
+ */
+export class HookBlockError extends Error {
+    /**
+     * Optional structured fields carried alongside the block reason (e.g.
+     * extra wire fields the agent's translation may forward).
+     */
+    fields;
+    /**
+     * @param message - The block reason; becomes the error `message`.
+     * @param fields - Optional additional structured fields.
+     */
+    constructor(message, fields) {
+        super(message);
+        this.name = "HookBlockError";
+        this.fields = fields;
+    }
+}
+/** Exit code used only if a transport's finalize itself throws under the default policy. */
+const FALLBACK_EXIT_ERROR = 1;
+/** Exit code used only if a transport's finalize itself throws under the "continue" policy. */
+const FALLBACK_EXIT_SUCCESS = 0;
+/**
+ * Reports an unexpected error through the caller's diagnostic sink and the
+ * runtime logger. Both are best-effort: this function never throws, so a
+ * broken sink or logger cannot itself fail the "continue" policy it backs.
+ * @param onUnexpectedError - The caller's optional diagnostic callback
+ * @param error - The unexpected error
+ * @param phase - The runtime phase in which the error occurred
+ */
+function reportUnexpectedError(onUnexpectedError, error, phase) {
+    try {
+        onUnexpectedError?.(error, phase);
+    }
+    catch {
+        // Diagnostic sinks must not recursively fail the invocation.
+    }
+    try {
+        logger.logError(error, `Unexpected error in ${phase} phase (fail-open)`, { phase });
+    }
+    catch {
+        // The logger itself may be the thing that failed (e.g. log file write).
+    }
+}
+/**
+ * Clears logger context and closes any open log file, surfacing cleanup
+ * failures through the same policy path as both source runtimes.
+ */
+function cleanup(policy, onUnexpectedError) {
+    try {
+        logger.clearContext();
+        logger.close();
+    }
+    catch (error) {
+        if (policy !== "continue") {
+            throw error;
+        }
+        reportUnexpectedError(onUnexpectedError, error, "cleanup");
+    }
+}
+/**
+ * Classifies a caught value into an outcome.
+ *
+ * Precedence is the mechanism of record: `error instanceof HookBlockError`
+ * routes to the `block` outcome **before** policy is consulted, mirroring the
+ * precedence codex-hooks' runtime already gives `BlockError`. Every other
+ * throw is subject to policy: `"continue"` swallows it into the empty
+ * response; the default `"error"` policy yields `handlerError`.
+ */
+function classify(error, phase, policy, onUnexpectedError) {
+    if (error instanceof HookBlockError) {
+        return { kind: "block", error };
+    }
+    if (policy === "continue") {
+        reportUnexpectedError(onUnexpectedError, error, phase);
+        return { kind: "response", output: undefined };
+    }
+    return { kind: "handlerError", error, phase };
+}
+/**
+ * Writes an unexpected (non-handler, runtime-owned) error's stacktrace to
+ * stderr. Used for cleanup/finalize failures under the default `"error"`
+ * policy, which exit with code 1 — these are not the handler's own
+ * intentional signal.
+ */
+function writeUnexpectedErrorStderr(error) {
+    if (error instanceof Error) {
+        process.stderr.write(`${error.stack ?? error.message}\n`);
+    }
+    else {
+        process.stderr.write(`${String(error)}\n`);
+    }
+}
+/**
+ * Last-resort logger shutdown used only when the transport's finalize itself
+ * threw — a broken mapping must not mask the original failure.
+ */
+function cleanupQuietly() {
+    try {
+        logger.clearContext();
+        logger.close();
+    }
+    catch {
+        // Nothing left to do; exiting immediately after.
+    }
+}
+/**
+ * Runs one hook invocation end to end: reads stdin, parses JSON, invokes the
+ * handler, classifies the outcome, maps it once through the transport, writes
+ * the resulting streams buffered (at most one write per stream), and exits
+ * with the transport's exit code.
+ *
+ * Malformed/unreadable stdin is classified at its phase (`read`/`parse`) like
+ * any other unexpected failure and logged identically to both source
+ * runtimes; each agent's transport decides the wire shape for that
+ * classification.
+ *
+ * @param transport - The agent's wire adapter.
+ * @param hookFn - The hook function to execute (from a factory built on
+ * {@link defineHook}).
+ * @returns Never resolves normally: the process exits inside this function.
+ */
+export async function drive(transport, hookFn) {
+    const policy = hookFn.unexpectedError ?? "error";
+    const onUnexpectedError = hookFn.onUnexpectedError;
+    const outcome = await (async () => {
+        let stdinContent;
+        try {
+            stdinContent = await readStdin();
+        }
+        catch (error) {
+            logger.logError(error, "Failed to read stdin");
+            return classify(error, "read", policy, onUnexpectedError);
+        }
+        let input;
+        try {
+            input = parseStdinJson(stdinContent);
+        }
+        catch (error) {
+            logger.logError(error, "Failed to parse stdin JSON");
+            return classify(error, "parse", policy, onUnexpectedError);
+        }
+        logger.setContext(hookFn.eventName, input);
+        const context = hookFn.createContext?.(input) ?? { logger };
+        try {
+            const result = await hookFn(input, context);
+            if (result === null || result === undefined) {
+                return { kind: "response", output: undefined };
+            }
+            const raw = transport.rawStdout?.(result);
+            return raw !== undefined ? { kind: "rawStdout", stdout: raw } : { kind: "response", output: result };
+        }
+        catch (error) {
+            return classify(error, "handler", policy, onUnexpectedError);
+        }
+    })();
+    let finalized;
+    try {
+        finalized = transport.finalize(outcome);
+    }
+    catch (error) {
+        if (policy === "continue") {
+            reportUnexpectedError(onUnexpectedError, error, "serialize");
+            cleanupQuietly();
+            process.exit(FALLBACK_EXIT_SUCCESS);
+        }
+        writeUnexpectedErrorStderr(error);
+        cleanupQuietly();
+        process.exit(FALLBACK_EXIT_ERROR);
+    }
+    try {
+        cleanup(policy, onUnexpectedError);
+    }
+    catch (error) {
+        writeUnexpectedErrorStderr(error);
+        process.exit(FALLBACK_EXIT_ERROR);
+    }
+    if (finalized.stderr !== undefined) {
+        process.stderr.write(finalized.stderr);
+    }
+    if (finalized.stdout !== undefined) {
+        try {
+            process.stdout.write(finalized.stdout);
+        }
+        catch (error) {
+            if (policy === "continue") {
+                reportUnexpectedError(onUnexpectedError, error, "write");
+                cleanupQuietly();
+                process.exit(FALLBACK_EXIT_SUCCESS);
+            }
+            writeUnexpectedErrorStderr(error);
+            cleanupQuietly();
+            process.exit(FALLBACK_EXIT_ERROR);
+        }
+    }
+    process.exit(finalized.exitCode);
+}

package/dist/core/types.js

@@ -0,0 +1,10 @@
+/**
+ * Shared core types for `@goodfoot/agent-hooks`.
+ *
+ * Core is agent-neutral: it owns the policy vocabulary, the hook-function
+ * shape, and the context contract, but never an event list — each agent
+ * (Claude Code, Codex, Antigravity) injects its own event names and its own
+ * advisory allow-list through {@link HookPolicyGate}.
+ * @module
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@goodfoot/agent-hooks` root export.
+ *
+ * Exposes the agent-neutral core only: the {@link defineHook} factory
+ * primitive, the transport/driver pair ({@link Transport}, {@link drive}),
+ * {@link HookBlockError}, the Logger, env utilities, and stdin helpers.
+ *
+ * Per-agent entry points (`@goodfoot/agent-hooks/claude-code`, `/codex`,
+ * `/antigravity`) are added to the package `exports` map only in the step
+ * that lands their implementation — never pre-declared.
+ * @module
+ */
+export { defineHook } from "./core/define-hook.js";
+export { CLAUDE_ENV_VARS, getEnvFilePath, getProjectDir, isRemoteEnvironment, persistEnvVar, persistEnvVars, } from "./core/env.js";
+export { LOG_LEVELS, Logger, logger, } from "./core/logger.js";
+export { parseStdinJson, readStdin } from "./core/stdin.js";
+export { HookBlockError, } from "./core/transport.js";