agenthooksprotocol 0.0.0-stage → 0.1.0

package/src/server/hooks.ts

@@ -0,0 +1,205 @@
+import {
+  validateCapabilitiesRequest,
+  validateCapabilitiesResponse,
+  validateInterceptRequest,
+  validateInterceptResponse,
+} from "../draft/index.js";
+import {
+  PROTOCOL_VERSION,
+  parseObserveNotification,
+  type CapabilitiesRequest,
+  type CapabilitiesResponse,
+  type InterceptRequest,
+  type InterceptResponse,
+  type ObserveNotification,
+} from "../draft/generated.js";
+import { validateWire } from "../client/validation.js";
+
+/** A decoded canonical wire message, not a host execution boundary. */
+export type Message =
+  | InterceptRequest
+  | ObserveNotification
+  | CapabilitiesRequest;
+type ResultFields<T> = {
+  [K in keyof T as string extends K
+    ? never
+    : K extends "protocolVersion"
+      ? never
+      : K]: T[K];
+};
+export type InterceptResult = ResultFields<InterceptResponse["result"]>;
+export type CapabilitiesResult = ResultFields<CapabilitiesResponse["result"]>;
+export type Handler = (
+  message: Message,
+) =>
+  | InterceptResult
+  | CapabilitiesResult
+  | void
+  | Promise<InterceptResult | CapabilitiesResult | void>;
+
+function object(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function json(value: unknown, status = 200): Response {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+function error(
+  id: unknown,
+  code: number,
+  message: string,
+  notification: boolean,
+  status = 200,
+): Response {
+  return notification
+    ? new Response(null, { status: status === 200 ? 500 : status })
+    : json({ jsonrpc: "2.0", id, error: { code, message } }, status);
+}
+
+/** Check support without executing, resolving bodies, or composing host state. */
+function supported(
+  request: InterceptRequest,
+  response: InterceptResponse,
+): boolean {
+  const caps = request.params.capabilities;
+  return response.result.effects.every((effect) => {
+    if (!caps.effects.includes(effect.type)) return false;
+    if (effect.type === "modify") {
+      const target = caps.modify?.[effect.target];
+      return object(target) && target[effect.operation] === true;
+    }
+    if (effect.type === "inject") {
+      return (
+        caps.inject?.context.append === true &&
+        caps.inject.context.deliverAt.includes(effect.deliverAt)
+      );
+    }
+    if (effect.type === "flow") {
+      if (!caps.flow?.operations.includes(effect.operation)) return false;
+      if (effect.operation === "continue") {
+        const flow = caps.flow;
+        return (
+          typeof flow.remainingContinuations === "number" &&
+          flow.remainingContinuations > 0 &&
+          (flow.maxContinuations === undefined ||
+            (flow.continuationCount ?? 0) < flow.maxContinuations)
+        );
+      }
+    }
+    if (
+      effect.type === "return" &&
+      request.params.event.type === "user.elicitation.request"
+    ) {
+      const mode = request.params.event.elicitation.mode;
+      if (!caps.elicitation?.[mode]) return false;
+    }
+    return true;
+  });
+}
+
+/** Handle one HTTP POST. The application owns authentication and routing.
+ * Observe callbacks return void. No notification receives a JSON-RPC reply.
+ * HTTP framing errors use 4xx; evaluated RPC failures use 200. Exceptions and
+ * invalid callback results are replaced by fixed, credential-free errors.
+ */
+async function handle(request: Request, handler: Handler): Promise<Response> {
+  if (request.method !== "POST")
+    return new Response(null, { status: 405, headers: { allow: "POST" } });
+  if (
+    request.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() !==
+    "application/json"
+  )
+    return new Response(null, { status: 415 });
+  let raw: unknown;
+  try {
+    raw = JSON.parse(await request.text()) as unknown;
+  } catch {
+    return error(null, -32700, "Parse error", false, 400);
+  }
+  if (
+    !object(raw) ||
+    raw.jsonrpc !== "2.0" ||
+    typeof raw.method !== "string" ||
+    (Object.hasOwn(raw, "id") &&
+      typeof raw.id !== "string" &&
+      typeof raw.id !== "number" &&
+      raw.id !== null)
+  ) {
+    return error(null, -32600, "Invalid Request", false, 400);
+  }
+  const notification = !Object.hasOwn(raw, "id");
+  const id = notification ? null : raw.id;
+  if (
+    !["hooks/intercept", "hooks/observe", "hooks/capabilities"].includes(
+      raw.method,
+    )
+  ) {
+    return error(
+      id,
+      -32601,
+      "Method not found",
+      notification,
+      notification ? 400 : 200,
+    );
+  }
+  if (
+    object(raw.params) &&
+    typeof raw.params.protocolVersion === "string" &&
+    raw.params.protocolVersion !== PROTOCOL_VERSION
+  ) {
+    return error(
+      id,
+      -32001,
+      "Unsupported AHP protocol version",
+      notification,
+      notification ? 400 : 200,
+    );
+  }
+  try {
+    // Validation and snapshots can exhaust the stack on deeply nested external JSON.
+    const decoded =
+      raw.method === "hooks/intercept"
+        ? validateInterceptRequest(raw)
+        : raw.method === "hooks/capabilities"
+          ? validateCapabilitiesRequest(raw)
+          : validateWire("observe-notification", raw).length === 0
+            ? parseObserveNotification(raw)
+            : { ok: false as const };
+    if (!decoded.ok)
+      return error(
+        id,
+        -32602,
+        "Invalid params",
+        notification,
+        notification ? 400 : 200,
+      );
+    const message = decoded.value;
+    // Retain trusted correlation and advertisements if application code mutates its message.
+    const canonical = structuredClone(message);
+    const result = await handler(message);
+    if (canonical.method === "hooks/observe")
+      return new Response(null, { status: result === undefined ? 204 : 500 });
+    if (!object(result) || Object.hasOwn(result, "protocolVersion"))
+      throw new Error("Invalid result");
+    const envelope = {
+      jsonrpc: "2.0",
+      id: canonical.id,
+      result: { ...result, protocolVersion: PROTOCOL_VERSION },
+    };
+    if (canonical.method === "hooks/intercept") {
+      const response = validateInterceptResponse(envelope);
+      if (!response.ok || !supported(canonical, response.value))
+        throw new Error("Invalid result");
+      return json(response.value);
+    }
+    const response = validateCapabilitiesResponse(envelope);
+    if (!response.ok) throw new Error("Invalid result");
+    return json(response.value);
+  } catch {
+    return error(id, -32004, "Backend internal error", notification);
+  }
+}
+
+export const hooks = { handle };

package/src/server/index.ts

@@ -0,0 +1,18 @@
+export { hooks } from "./hooks.js";
+export type {
+  Message,
+  Handler,
+  InterceptResult,
+  CapabilitiesResult,
+} from "./hooks.js";
+export { attachments, UploadError } from "./attachments.js";
+export type { Upload } from "./attachments.js";
+export type {
+  ContentReference,
+  InterceptRequest,
+  ObserveNotification,
+  CapabilitiesRequest,
+  Effect,
+} from "../draft/generated.js";
+
+export { effects } from "../draft/generated.js";

package/src/server/node-crypto.d.ts

@@ -0,0 +1,7 @@
+// Node 20 incremental hashing, kept local to the server implementation.
+declare module "node:crypto" {
+  export function createHash(algorithm: "sha256"): {
+    update(data: Uint8Array): unknown;
+    digest(encoding: "hex"): string;
+  };
+}

package/src/server/stdio.ts

@@ -0,0 +1,81 @@
+import { stdin, stdout } from "node:process";
+import { Writable, type Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+export interface StdioOptions {
+  stdin?: Readable;
+  stdout?: Writable;
+  signal?: AbortSignal;
+}
+
+/** Serve UTF-8 NDJSON using an ordinary Web Request/Response handler.
+ * Requests run sequentially. Nonempty bodies are written regardless of status;
+ * physical CR/LF in response bodies becomes spaces to preserve line framing.
+ * Resolves at EOF after flushing output, without ending stdout. The streams are
+ * dedicated to this serving session: failure or abort destroys them. Handlers
+ * doing long-running work should honor request.signal. No process is exited.
+ */
+export async function serveStdio(
+  handler: (request: Request) => Response | Promise<Response>,
+  options: StdioOptions = {},
+): Promise<void> {
+  const output = options.stdout ?? stdout;
+  // A private sink waits for each write callback without ending caller stdout.
+  const sink = new Writable({
+    highWaterMark: 1,
+    write(chunk, _encoding, callback) {
+      output.write(chunk, callback);
+    },
+  });
+  const outputError = (error: Error) => sink.destroy(error);
+  const outputClosed = () => sink.destroy(new Error("Stdio output closed"));
+  output.on("error", outputError);
+  output.on("close", outputClosed);
+  try {
+    await pipeline(
+      options.stdin ?? stdin,
+      async function* (source, { signal }) {
+        const decoder = new TextDecoder();
+        let pending = "";
+        const respond = async (body: string) => {
+          const response = await handler(
+            new Request("http://localhost/", {
+              method: "POST",
+              headers: { "content-type": "application/json" },
+              body,
+              signal,
+            }),
+          );
+          const text = await response.text();
+          return text === "" ? "" : text.replace(/[\r\n]/g, " ") + "\n";
+        };
+        for await (const chunk of source) {
+          pending +=
+            typeof chunk === "string"
+              ? decoder.decode() + chunk
+              : decoder.decode(chunk, { stream: true });
+          let newline: number;
+          while ((newline = pending.indexOf("\n")) !== -1) {
+            const line = pending.slice(0, newline);
+            pending = pending.slice(newline + 1);
+            const reply = await respond(line);
+            if (reply !== "") yield reply;
+          }
+        }
+        pending += decoder.decode();
+        if (pending !== "") {
+          const reply = await respond(pending);
+          if (reply !== "") yield reply;
+        }
+      },
+      sink,
+      options.signal ? { signal: options.signal } : {},
+    );
+  } catch (error) {
+    output.destroy();
+    throw error;
+  } finally {
+    output.removeListener("error", outputError);
+    output.removeListener("close", outputClosed);
+  }
+}

package/src/transport.ts

@@ -0,0 +1,273 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { HookOperationalError, asOperationalError } from "./errors.js";
+import { NdjsonDecoder } from "./framing.js";
+import type { Lifecycle } from "./types.js";
+
+export interface LineTransport {
+  exchange(line: string, timeoutMs: number): Promise<string>;
+  close(): void;
+}
+
+function start(
+  command: string,
+  args: readonly string[],
+): ChildProcessWithoutNullStreams {
+  try {
+    const child = spawn(command, [...args], {
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    child.stderr.resume();
+    return child;
+  } catch (error) {
+    throw new HookOperationalError(
+      "SPAWN_ERROR",
+      `Could not spawn ${command}`,
+      { cause: error },
+    );
+  }
+}
+
+class PerEventTransport implements LineTransport {
+  readonly #command: string;
+  readonly #args: readonly string[];
+
+  constructor(command: string, args: readonly string[]) {
+    this.#command = command;
+    this.#args = args;
+  }
+
+  exchange(line: string, timeoutMs: number): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const decoder = new NdjsonDecoder();
+      let child: ChildProcessWithoutNullStreams | undefined;
+      let response: string | undefined;
+      let settled = false;
+      const finish = (error?: unknown): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (child !== undefined && child.exitCode === null) child.kill();
+        if (error !== undefined) reject(asOperationalError(error));
+        else resolve(response as string);
+      };
+      const timer = setTimeout(
+        () =>
+          finish(
+            new HookOperationalError(
+              "TIMEOUT",
+              `Hook exchange exceeded ${timeoutMs} ms`,
+            ),
+          ),
+        timeoutMs,
+      );
+      try {
+        child = start(this.#command, this.#args);
+        child.once("error", (error: Error) =>
+          finish(
+            new HookOperationalError(
+              "SPAWN_ERROR",
+              `Could not run ${this.#command}`,
+              { cause: error },
+            ),
+          ),
+        );
+        child.stdout.on("data", (chunk: Buffer) => {
+          try {
+            const frames = decoder.push(chunk);
+            if (
+              frames.length > 1 ||
+              (frames.length === 1 && response !== undefined)
+            ) {
+              throw new HookOperationalError(
+                "MALFORMED_JSON_RPC",
+                "Backend emitted multiple responses for one request",
+              );
+            }
+            if (frames.length === 1) response = frames[0];
+          } catch (error) {
+            finish(error);
+          }
+        });
+        child.once("close", (code: number | null) => {
+          if (settled) return;
+          try {
+            decoder.end();
+          } catch (error) {
+            finish(error);
+            return;
+          }
+          if (code !== 0) {
+            finish(
+              new HookOperationalError(
+                "IO_ERROR",
+                `Backend exited with status ${String(code)}`,
+              ),
+            );
+          } else if (response === undefined) {
+            finish(
+              new HookOperationalError(
+                "IO_ERROR",
+                "Backend exited before returning a response",
+              ),
+            );
+          } else {
+            finish();
+          }
+        });
+        child.stdin.once("error", (error: Error) =>
+          finish(
+            new HookOperationalError(
+              "IO_ERROR",
+              "Could not write hook request",
+              { cause: error },
+            ),
+          ),
+        );
+        child.stdin.end(`${line}\n`);
+      } catch (error) {
+        finish(error);
+      }
+    });
+  }
+
+  close(): void {}
+}
+
+class PersistentTransport implements LineTransport {
+  readonly #command: string;
+  readonly #args: readonly string[];
+  #child: ChildProcessWithoutNullStreams | undefined;
+  #decoder = new NdjsonDecoder();
+  #tail: Promise<void> = Promise.resolve();
+
+  constructor(command: string, args: readonly string[]) {
+    this.#command = command;
+    this.#args = args;
+  }
+
+  exchange(line: string, timeoutMs: number): Promise<string> {
+    const result = this.#tail.then(() => this.#exchangeNow(line, timeoutMs));
+    this.#tail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+
+  #exchangeNow(line: string, timeoutMs: number): Promise<string> {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (error?: unknown, response?: string): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        child.stdout.off("data", onData);
+        child.off("error", onError);
+        child.off("close", onClose);
+        child.stdin.off("error", onStdinError);
+        if (error !== undefined) {
+          this.#discard();
+          reject(asOperationalError(error));
+        } else {
+          resolve(response as string);
+        }
+      };
+      const timer = setTimeout(
+        () =>
+          finish(
+            new HookOperationalError(
+              "TIMEOUT",
+              `Hook exchange exceeded ${timeoutMs} ms`,
+            ),
+          ),
+        timeoutMs,
+      );
+      let child: ChildProcessWithoutNullStreams;
+      try {
+        if (this.#child === undefined || this.#child.exitCode !== null) {
+          this.#decoder = new NdjsonDecoder();
+          this.#child = start(this.#command, this.#args);
+        }
+        child = this.#child;
+      } catch (error) {
+        clearTimeout(timer);
+        reject(asOperationalError(error));
+        return;
+      }
+      const onData = (chunk: Buffer): void => {
+        try {
+          const frames = this.#decoder.push(chunk);
+          if (frames.length !== 1) {
+            if (frames.length > 1)
+              throw new HookOperationalError(
+                "MALFORMED_JSON_RPC",
+                "Backend emitted multiple responses for one request",
+              );
+            return;
+          }
+          finish(undefined, frames[0]);
+        } catch (error) {
+          finish(error);
+        }
+      };
+      const onError = (error: Error): void =>
+        finish(
+          new HookOperationalError(
+            "SPAWN_ERROR",
+            `Could not run ${this.#command}`,
+            { cause: error },
+          ),
+        );
+      const onClose = (): void => {
+        if (settled) return;
+        try {
+          this.#decoder.end();
+        } catch (error) {
+          finish(error);
+          return;
+        }
+        finish(
+          new HookOperationalError(
+            "IO_ERROR",
+            "Persistent backend exited before returning a response",
+          ),
+        );
+      };
+      const onStdinError = (error: Error): void =>
+        finish(
+          new HookOperationalError("IO_ERROR", "Could not write hook request", {
+            cause: error,
+          }),
+        );
+      child.stdout.on("data", onData);
+      child.once("error", onError);
+      child.once("close", onClose);
+      child.stdin.once("error", onStdinError);
+      child.stdin.write(`${line}\n`, (error?: Error | null) => {
+        if (error) onStdinError(error);
+      });
+    });
+  }
+
+  #discard(): void {
+    const child = this.#child;
+    this.#child = undefined;
+    this.#decoder = new NdjsonDecoder();
+    if (child !== undefined && child.exitCode === null) child.kill();
+  }
+
+  close(): void {
+    this.#discard();
+  }
+}
+
+export function createTransport(
+  command: string,
+  args: readonly string[],
+  lifecycle: Lifecycle,
+): LineTransport {
+  return lifecycle === "persistent"
+    ? new PersistentTransport(command, args)
+    : new PerEventTransport(command, args);
+}

package/src/types.ts

@@ -0,0 +1,124 @@
+export const PROTOCOL_VERSION = "draft" as const;
+export const INTERCEPT_METHOD = "hooks/intercept" as const;
+export const TOOL_KINDS = [
+  "shell",
+  "file_read",
+  "file_write",
+  "file_edit",
+  "search",
+  "fetch",
+  "task",
+  "mcp",
+  "other",
+] as const;
+
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+export type JsonObject = { [key: string]: JsonValue };
+export type ToolKind = (typeof TOOL_KINDS)[number];
+
+export interface SessionContext {
+  id: string;
+  cwd?: string;
+  workspaceRoots?: string[];
+  model?: string;
+  agent?: { id: string; type?: string };
+}
+
+export interface ToolContext {
+  callId: string;
+  name: string;
+  kind: ToolKind;
+  input: JsonObject;
+  mcp?: JsonObject;
+}
+
+export interface NativeContext {
+  provider: string;
+  eventName: string;
+  payload: JsonObject;
+}
+
+export interface ToolBeforeEvent {
+  id: string;
+  source: string;
+  type: "tool.before";
+  time: string;
+  session: SessionContext;
+  tool: ToolContext;
+  native?: NativeContext;
+  extensions?: JsonObject;
+}
+
+export interface InterceptRequest {
+  jsonrpc: "2.0";
+  id: string;
+  method: "hooks/intercept";
+  params: {
+    protocolVersion: "draft";
+    event: ToolBeforeEvent;
+    capabilities: { effects: ["deny"] };
+  };
+}
+
+export type DenyEffect = {
+  type: "deny";
+  reason: string;
+  code?: string;
+  extensions?: JsonObject;
+};
+export type InterceptResult =
+  | { protocolVersion: "draft"; effects: [] }
+  | { protocolVersion: "draft"; effects: [DenyEffect] };
+
+export interface InterceptResponse {
+  jsonrpc: "2.0";
+  id: string;
+  result: InterceptResult;
+}
+
+export type FailurePolicy = "fail-open" | "fail-closed";
+export type Lifecycle = "per_event" | "persistent";
+
+export interface HookBackend {
+  command: string;
+  args?: readonly string[];
+  timeoutMs: number;
+  failurePolicy: FailurePolicy;
+  retries?: number;
+  lifecycle?: Lifecycle;
+  name?: string;
+}
+
+export interface ToolBeforeInput {
+  source: string;
+  eventId?: string;
+  time?: string;
+  session: Omit<SessionContext, "id"> & { id?: string };
+  tool: Omit<ToolContext, "callId"> & { callId?: string };
+  native?: NativeContext;
+  extensions?: JsonObject;
+}
+
+export interface HookFailure {
+  backend: string;
+  policy: FailurePolicy;
+  code: string;
+  message: string;
+}
+
+export interface ToolBeforeOutcome {
+  decision: "continue" | "deny";
+  event: ToolBeforeEvent;
+  failures: HookFailure[];
+  denial?: {
+    backend: string;
+    reason: string;
+    code?: string;
+    extensions?: JsonObject;
+    operational: boolean;
+  };
+}
+
+export type IdKind = "event" | "session" | "call";
+export type IdGenerator = (kind: IdKind) => string;