agenthooksprotocol 0.0.0-bootstrap.0

package/src/hook-runner.ts

@@ -0,0 +1,310 @@
+import { randomUUID } from "node:crypto";
+import { HookOperationalError, asOperationalError } from "./errors.js";
+import { createTransport, type LineTransport } from "./transport.js";
+import {
+  INTERCEPT_METHOD,
+  PROTOCOL_VERSION,
+  type HookBackend,
+  type HookFailure,
+  type IdGenerator,
+  type InterceptRequest,
+  type ToolBeforeEvent,
+  type ToolBeforeInput,
+  type ToolBeforeOutcome,
+} from "./types.js";
+import {
+  assertJsonObject,
+  parseInterceptRequest,
+  parseInterceptResponse,
+} from "./validation.js";
+
+interface Registration {
+  config: Required<
+    Pick<
+      HookBackend,
+      | "command"
+      | "args"
+      | "timeoutMs"
+      | "failurePolicy"
+      | "retries"
+      | "lifecycle"
+    >
+  > &
+    Pick<HookBackend, "name">;
+  transport: LineTransport;
+}
+
+function validateBackend(backend: HookBackend): Registration["config"] {
+  if (backend === null || typeof backend !== "object")
+    throw new HookOperationalError(
+      "INVALID_CONFIG",
+      "Backend configuration must be an object",
+    );
+  if (typeof backend.command !== "string" || backend.command.length === 0)
+    throw new HookOperationalError(
+      "INVALID_CONFIG",
+      "Backend command must be a non-empty string",
+    );
+  const args = backend.args === undefined ? [] : [...backend.args];
+  if (!args.every((arg) => typeof arg === "string"))
+    throw new HookOperationalError(
+      "INVALID_CONFIG",
+      "Backend args must be strings",
+    );
+  if (!Number.isInteger(backend.timeoutMs) || backend.timeoutMs <= 0)
+    throw new HookOperationalError(
+      "INVALID_CONFIG",
+      "Backend timeoutMs must be a positive integer",
+    );
+  if (
+    backend.failurePolicy !== "fail-open" &&
+    backend.failurePolicy !== "fail-closed"
+  )
+    throw new HookOperationalError(
+      "INVALID_CONFIG",
+      "Backend failurePolicy must be explicit",
+    );
+  const retries = backend.retries ?? 0;
+  if (!Number.isInteger(retries) || retries < 0 || retries > 10)
+    throw new HookOperationalError(
+      "INVALID_CONFIG",
+      "Backend retries must be an integer from 0 through 10",
+    );
+  const lifecycle = backend.lifecycle ?? "per_event";
+  if (lifecycle !== "per_event" && lifecycle !== "persistent")
+    throw new HookOperationalError("INVALID_CONFIG", "Unsupported lifecycle");
+  return backend.name === undefined
+    ? {
+        command: backend.command,
+        args,
+        timeoutMs: backend.timeoutMs,
+        failurePolicy: backend.failurePolicy,
+        retries,
+        lifecycle,
+      }
+    : {
+        command: backend.command,
+        args,
+        timeoutMs: backend.timeoutMs,
+        failurePolicy: backend.failurePolicy,
+        retries,
+        lifecycle,
+        name: backend.name,
+      };
+}
+
+function snapshot<T>(value: T, label: string): T {
+  assertJsonObject(value, label);
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+export class ToolBeforeRunner {
+  readonly #ids: IdGenerator;
+  readonly #registrations: Registration[] = [];
+  #tail: Promise<void> = Promise.resolve();
+
+  constructor(options: { idGenerator?: IdGenerator } = {}) {
+    this.#ids = options.idGenerator ?? ((kind) => `${kind}_${randomUUID()}`);
+  }
+
+  register(backend: HookBackend): () => void {
+    const config = validateBackend(backend);
+    const registration: Registration = {
+      config,
+      transport: createTransport(config.command, config.args, config.lifecycle),
+    };
+    this.#registrations.push(registration);
+    return () => {
+      const index = this.#registrations.indexOf(registration);
+      if (index !== -1) this.#registrations.splice(index, 1);
+      registration.transport.close();
+    };
+  }
+
+  intercept(input: ToolBeforeInput): Promise<ToolBeforeOutcome> {
+    const result = this.#tail.then(() => this.#interceptNow(input));
+    this.#tail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+
+  async #interceptNow(input: ToolBeforeInput): Promise<ToolBeforeOutcome> {
+    if (
+      input === null ||
+      typeof input !== "object" ||
+      input.session === null ||
+      typeof input.session !== "object" ||
+      input.tool === null ||
+      typeof input.tool !== "object"
+    ) {
+      throw new HookOperationalError(
+        "INVALID_CONFIG",
+        "Tool input, session, and tool must be objects",
+      );
+    }
+    const session = {
+      id: this.#providedId(input.session.id, "session"),
+      ...(input.session.cwd === undefined ? {} : { cwd: input.session.cwd }),
+      ...(input.session.workspaceRoots === undefined
+        ? {}
+        : { workspaceRoots: input.session.workspaceRoots }),
+      ...(input.session.model === undefined
+        ? {}
+        : { model: input.session.model }),
+      ...(input.session.agent === undefined
+        ? {}
+        : { agent: input.session.agent }),
+    };
+    const tool = {
+      callId: this.#providedId(input.tool.callId, "call"),
+      name: input.tool.name,
+      kind: input.tool.kind,
+      input: snapshot(input.tool.input, "tool.input"),
+      ...(input.tool.mcp === undefined
+        ? {}
+        : { mcp: snapshot(input.tool.mcp, "tool.mcp") }),
+    };
+    const event: ToolBeforeEvent = {
+      id: this.#providedId(input.eventId, "event"),
+      source: input.source,
+      type: "tool.before",
+      time: input.time ?? new Date().toISOString(),
+      session,
+      tool,
+      ...(input.native === undefined
+        ? {}
+        : { native: snapshot(input.native, "native") }),
+      ...(input.extensions === undefined
+        ? {}
+        : { extensions: snapshot(input.extensions, "extensions") }),
+    };
+    parseInterceptRequest(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        id: event.id,
+        method: INTERCEPT_METHOD,
+        params: {
+          protocolVersion: PROTOCOL_VERSION,
+          event,
+          capabilities: { effects: ["deny"] },
+        },
+      }),
+    );
+    const failures: HookFailure[] = [];
+    const registrations = [...this.#registrations];
+    for (const registration of registrations) {
+      const request: InterceptRequest = {
+        jsonrpc: "2.0",
+        id: event.id,
+        method: INTERCEPT_METHOD,
+        params: {
+          protocolVersion: PROTOCOL_VERSION,
+          event,
+          capabilities: { effects: ["deny"] },
+        },
+      };
+      const line = JSON.stringify(request);
+      parseInterceptRequest(line);
+      let lastError: HookOperationalError | undefined;
+      const deadline = Date.now() + registration.config.timeoutMs;
+      for (
+        let attempt = 0;
+        attempt <= registration.config.retries;
+        attempt += 1
+      ) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+          lastError = new HookOperationalError(
+            "TIMEOUT",
+            `Hook exchange exceeded ${registration.config.timeoutMs} ms`,
+          );
+          break;
+        }
+        try {
+          const responseLine = await registration.transport.exchange(
+            line,
+            remainingMs,
+          );
+          const response = parseInterceptResponse(responseLine, event.id);
+          const effect = response.effects[0];
+          if (effect !== undefined) {
+            const denial = {
+              backend: this.#backendName(registration),
+              reason: effect.reason,
+              operational: false,
+              ...(effect.code === undefined ? {} : { code: effect.code }),
+              ...(effect.extensions === undefined
+                ? {}
+                : { extensions: effect.extensions }),
+            };
+            return { decision: "deny", event, failures, denial };
+          }
+          lastError = undefined;
+          break;
+        } catch (error) {
+          lastError = asOperationalError(error);
+          registration.transport.close();
+        }
+      }
+      if (lastError !== undefined) {
+        const failure: HookFailure = {
+          backend: this.#backendName(registration),
+          policy: registration.config.failurePolicy,
+          code: lastError.code,
+          message: lastError.message,
+        };
+        failures.push(failure);
+        if (registration.config.failurePolicy === "fail-closed") {
+          return {
+            decision: "deny",
+            event,
+            failures,
+            denial: {
+              backend: failure.backend,
+              reason: `Operational failure: ${failure.code}`,
+              operational: true,
+            },
+          };
+        }
+      }
+    }
+    return { decision: "continue", event, failures };
+  }
+
+  #providedId(
+    value: string | undefined,
+    kind: "event" | "session" | "call",
+  ): string {
+    if (value !== undefined) {
+      if (typeof value !== "string" || value.length === 0)
+        throw new HookOperationalError(
+          "INVALID_CONFIG",
+          `${kind} ID must be a non-empty string`,
+        );
+      return value;
+    }
+    return this.#generatedId(kind);
+  }
+
+  #generatedId(kind: "event" | "session" | "call"): string {
+    const value = this.#ids(kind);
+    if (typeof value !== "string" || value.length === 0)
+      throw new HookOperationalError(
+        "INVALID_CONFIG",
+        `Generated ${kind} ID must be a non-empty string`,
+      );
+    return value;
+  }
+
+  #backendName(registration: Registration): string {
+    return registration.config.name ?? registration.config.command;
+  }
+
+  close(): void {
+    for (const registration of this.#registrations)
+      registration.transport.close();
+    this.#registrations.length = 0;
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./errors.js";
+export * from "./framing.js";
+export * from "./hook-runner.js";
+export * from "./types.js";
+export * from "./validation.js";
+export * from "./elicitation.js";
+
+export * from "./compaction.js";

package/src/observation.ts

@@ -0,0 +1,65 @@
+/** One-way delivery of an already-settled boundary. */
+export interface ObservationSubscription {
+  id: string;
+  mode: "intercept" | "observe";
+}
+export interface ObservationEvent {
+  id: string;
+  source: string;
+  type: string;
+  [key: string]: unknown;
+}
+export interface ObservationNotification {
+  jsonrpc: "2.0";
+  method: "hooks/observe";
+  params: { protocolVersion: "draft"; event: ObservationEvent };
+}
+/** The host supplies matching subscriptions and invoked intercept subscription IDs.
+ * prepare MUST apply existing content permissions/selections and confirm uploads.
+ * Its failure drops only this best-effort delivery, never reopens the decision.
+ * schedule MUST enqueue without awaiting work; it must not keep interrupted
+ * execution alive. This injection supports browser and server host schedulers. */
+export function dispatchObservations(
+  event: ObservationEvent,
+  subscriptions: readonly ObservationSubscription[],
+  called: ReadonlySet<string>,
+  prepare: (
+    event: ObservationEvent,
+    subscription: ObservationSubscription,
+  ) => Promise<ObservationEvent>,
+  notify: (
+    notification: ObservationNotification,
+    subscription: ObservationSubscription,
+  ) => unknown,
+  schedule: (work: () => void) => void,
+): void {
+  const snapshot = structuredClone(event);
+  for (const subscription of structuredClone(subscriptions)) {
+    if (
+      subscription.mode !== "observe" &&
+      !(subscription.mode === "intercept" && !called.has(subscription.id))
+    )
+      continue;
+    schedule(() => {
+      void Promise.resolve()
+        .then(() => prepare(structuredClone(snapshot), subscription))
+        .then((projected) => {
+          if (
+            ["id", "source", "type"].some(
+              (key) => projected[key] !== snapshot[key],
+            )
+          )
+            throw Error("Observation changed boundary identity");
+          return notify(
+            {
+              jsonrpc: "2.0",
+              method: "hooks/observe",
+              params: { protocolVersion: "draft", event: projected },
+            },
+            subscription,
+          );
+        })
+        .catch(() => {});
+    });
+  }
+}

package/src/server/attachments.ts

@@ -0,0 +1,128 @@
+import { createHash } from "node:crypto";
+import {
+  parseContentReference,
+  type ContentReference,
+} from "../draft/generated.js";
+import { validateWire } from "../client/validation.js";
+
+/** Safe protocol upload failure; applications can map status to an HTTP response. */
+export class UploadError extends Error {
+  readonly status = 400;
+  constructor(message: string) {
+    super(message);
+    this.name = "UploadError";
+  }
+}
+export interface Upload {
+  /** Consume to successful EOF before committing storage or confirming availability. */
+  body: ReadableStream<Uint8Array>;
+  /** Declared framing, not independently verified until body reaches successful EOF. */
+  size: number;
+  sha256: string;
+}
+
+/** Synchronous framing checks; bytes are read and verified only on consumer demand.
+ * The application owns authorization, storage, reference allocation and commit.
+ * A storage writer must propagate stream errors and await successful EOF.
+ */
+function parse(request: Request): Upload {
+  const length = request.headers.get("content-length");
+  const sha256 = request.headers.get("ahp-content-sha256");
+  if (
+    request.method !== "POST" ||
+    request.headers.get("content-type")?.toLowerCase() !==
+      "application/octet-stream" ||
+    request.headers.has("content-encoding") ||
+    request.headers.has("transfer-encoding") ||
+    length === null ||
+    !/^[0-9]+$/.test(length) ||
+    !Number.isSafeInteger(Number(length)) ||
+    sha256 === null ||
+    !/^[0-9a-f]{64}$/.test(sha256) ||
+    request.bodyUsed ||
+    request.body?.locked
+  ) {
+    throw new UploadError("Invalid upload framing");
+  }
+  const size = Number(length);
+  const hash = createHash("sha256");
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let count = 0;
+  const body = new ReadableStream<Uint8Array>(
+    {
+      async pull(controller) {
+        try {
+          reader ??= request.body?.getReader();
+          const chunk = reader
+            ? await reader.read()
+            : { done: true as const, value: undefined };
+          if (chunk.done) {
+            reader?.releaseLock();
+            if (count !== size) throw new UploadError("Upload length mismatch");
+            if (hash.digest("hex") !== sha256)
+              throw new UploadError("Upload hash mismatch");
+            controller.close();
+            return;
+          }
+          if (
+            !(chunk.value instanceof Uint8Array) ||
+            chunk.value.byteLength > size - count
+          )
+            throw new UploadError("Upload length mismatch");
+          // Snapshot mutable producer buffers before hashing and handing them to storage.
+          const bytes = new Uint8Array(chunk.value);
+          count += bytes.byteLength;
+          hash.update(bytes);
+          controller.enqueue(bytes);
+        } catch (cause) {
+          controller.error(
+            cause instanceof UploadError
+              ? cause
+              : new UploadError("Upload body read failed"),
+          );
+          try {
+            await reader?.cancel();
+          } catch {
+            /* Do not mask the validation failure. */
+          }
+          try {
+            reader?.releaseLock();
+          } catch {
+            /* Reader may already have released its lock. */
+          }
+        }
+      },
+      async cancel(reason) {
+        if (reader) {
+          try {
+            await reader.cancel(reason);
+          } finally {
+            reader.releaseLock();
+          }
+        } else {
+          await request.body?.cancel(reason);
+        }
+      },
+    },
+    { highWaterMark: 0 },
+  );
+  return { body, size, sha256 };
+}
+
+/** Validate and format a descriptor. This does not verify bytes or commit storage.
+ * Call only after an authorized storage write consumed body to successful EOF
+ * and the immutable reference is synchronously available to the receiver.
+ */
+function response(descriptor: ContentReference): Response {
+  if (validateWire("content-reference", descriptor).length !== 0)
+    throw new UploadError("Invalid content descriptor");
+  const decoded = parseContentReference(descriptor);
+  if (!decoded.ok || !Number.isSafeInteger(decoded.value.size))
+    throw new UploadError("Invalid content descriptor");
+  return new Response(JSON.stringify(decoded.value), {
+    status: 201,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+export const attachments = { parse, response };