agenthooksprotocol 0.0.0-bootstrap.0

package/src/client/index.ts

@@ -0,0 +1,28 @@
+/** Harness-facing, configuration-driven API for the complete canonical draft catalogue. */
+export { Hooks } from "./hooks.js";
+export * from "./types.js";
+export * from "./auth.js";
+export * from "./content.js";
+export * from "./composition.js";
+export * from "./transport.js";
+export type {
+  Registration,
+  Capabilities,
+  StaticCapabilityManifest,
+  Effect,
+  InterceptResponse,
+  Authentication,
+  ContentSelection,
+  ContentUpload,
+} from "../draft/generated.js";
+
+export {
+  Permission,
+  state,
+  effects,
+  contentSlots,
+  capabilities,
+  events,
+  CapabilityBuilder,
+} from "../draft/generated.js";
+export type * from "../draft/generated.js";

package/src/client/transport.ts

@@ -0,0 +1,408 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import type {
+  Backend,
+  HttpTransport,
+  StdioTransport,
+} from "../draft/generated.js";
+import { HookOperationalError } from "../errors.js";
+import { NdjsonDecoder } from "../framing.js";
+
+type Fetcher = (url: string, init: RequestInit) => Promise<Response>;
+type Pending = {
+  message: any;
+  notification: boolean;
+  resolve(value: unknown): void;
+  reject(error: unknown): void;
+  response?: unknown;
+};
+type ProcessState = {
+  child: ChildProcessWithoutNullStreams;
+  closed: Promise<void>;
+  pending: Map<unknown, Pending>;
+  stopped: boolean;
+};
+
+function failure(message: string): Error {
+  return new HookOperationalError("IO_ERROR", message);
+}
+
+/** Validate only the JSON-RPC envelope; the caller validates method-specific results. */
+function responseFor(value: any, message: any): unknown {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    value.jsonrpc !== "2.0" ||
+    "result" in value === "error" in value ||
+    "method" in value ||
+    !("id" in value)
+  ) {
+    throw new HookOperationalError(
+      "MALFORMED_JSON_RPC",
+      "Expected one JSON-RPC response",
+    );
+  }
+  if (value.id !== message.id) {
+    throw new HookOperationalError(
+      "ID_MISMATCH",
+      "Backend response ID does not match request",
+    );
+  }
+  if (
+    "error" in value &&
+    (!value.error ||
+      typeof value.error !== "object" ||
+      !Number.isInteger(value.error.code) ||
+      typeof value.error.message !== "string")
+  ) {
+    throw new HookOperationalError(
+      "MALFORMED_JSON_RPC",
+      "Malformed JSON-RPC error",
+    );
+  }
+  return value;
+}
+
+/** Client-side transport. Deadlines are supplied by the caller's AbortSignal. */
+export class BackendTransport {
+  readonly #transport: StdioTransport | HttpTransport;
+  readonly #fetcher: Fetcher;
+  readonly #controllers = new Set<AbortController>();
+  readonly #processes = new Set<ProcessState>();
+  #process: ProcessState | undefined;
+  #tail: Promise<unknown> = Promise.resolve();
+  #closed = false;
+  #closing: Promise<void> | undefined;
+
+  constructor(backend: Backend, fetcher: Fetcher) {
+    const transport = backend.transport;
+    if (transport.type !== "http" && transport.type !== "stdio") {
+      throw new HookOperationalError(
+        "INVALID_CONFIG",
+        "Unsupported backend transport",
+      );
+    }
+    if (
+      transport.type === "stdio" &&
+      transport.lifecycle !== "persistent" &&
+      transport.lifecycle !== "per_event"
+    ) {
+      throw new HookOperationalError(
+        "INVALID_CONFIG",
+        "Unsupported stdio lifecycle",
+      );
+    }
+    this.#transport = transport as StdioTransport | HttpTransport;
+    this.#fetcher = fetcher;
+  }
+
+  request(message: any, signal?: AbortSignal): Promise<unknown> {
+    return this.#send(message, false, signal);
+  }
+
+  async notify(message: any, signal?: AbortSignal): Promise<void> {
+    await this.#send(message, true, signal);
+  }
+
+  #send(
+    message: any,
+    notification: boolean,
+    signal?: AbortSignal,
+  ): Promise<unknown> {
+    if (this.#closed)
+      return Promise.reject(failure("Backend transport is closed"));
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    if (signal?.aborted) abort();
+    else signal?.addEventListener("abort", abort, { once: true });
+    this.#controllers.add(controller);
+    let started = false;
+    const run = async () => {
+      controller.signal.throwIfAborted();
+      started = true;
+      return this.#transport.type === "http"
+        ? this.#http(message, notification, controller.signal)
+        : this.#stdio(message, notification, controller.signal);
+    };
+    // This revision permits only one outstanding intercept per persistent
+    // backend. Keep the queue occupied through process shutdown on cancellation.
+    const stdio = this.#transport.type === "stdio";
+    const work = stdio ? this.#tail.then(run) : run();
+    if (stdio) this.#tail = work.catch(() => {});
+    // Also interrupt queued calls, and fetch implementations which ignore cancellation.
+    return new Promise((resolve, reject) => {
+      const cancel = () => reject(controller.signal.reason);
+      controller.signal.addEventListener("abort", cancel, { once: true });
+      if (controller.signal.aborted) cancel();
+      work.then(resolve, reject).finally(() => {
+        controller.signal.removeEventListener("abort", cancel);
+      });
+    }).finally(async () => {
+      // Retire queued work immediately, but reap an active SDK child before
+      // completing its cancelled operation. The queue remains occupied too.
+      if (stdio && started && controller.signal.aborted)
+        await work.catch(() => {});
+      signal?.removeEventListener("abort", abort);
+      this.#controllers.delete(controller);
+    });
+  }
+
+  async #http(
+    message: any,
+    notification: boolean,
+    signal: AbortSignal,
+  ): Promise<unknown> {
+    const transport = this.#transport as HttpTransport;
+    const response = await this.#fetcher(transport.url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(message),
+      redirect: "error",
+      signal,
+    });
+    try {
+      signal.throwIfAborted();
+      if (notification) {
+        if (response.status !== 202 && response.status !== 204) {
+          throw failure(
+            `Unexpected notification HTTP status ${response.status}`,
+          );
+        }
+        await this.#responseText(response, signal, 0);
+        return;
+      }
+      if (response.status !== 200)
+        throw failure(`Unexpected request HTTP status ${response.status}`);
+      if (
+        response.headers
+          .get("content-type")
+          ?.split(";")[0]
+          ?.trim()
+          .toLowerCase() !== "application/json"
+      ) {
+        throw new HookOperationalError(
+          "MALFORMED_JSON_RPC",
+          "Backend response must use application/json",
+        );
+      }
+      // Match the SDK's 1 MiB NDJSON frame budget rather than buffering unbounded JSON.
+      const text = await this.#responseText(response, signal, 1024 * 1024);
+      signal.throwIfAborted();
+      let decoded: unknown;
+      try {
+        decoded = JSON.parse(text);
+      } catch {
+        throw new HookOperationalError(
+          "MALFORMED_JSON",
+          "Malformed backend response",
+        );
+      }
+      return responseFor(decoded, message);
+    } finally {
+      // Also release rejected responses and late results from fetchers that ignore abort.
+      // A custom stream's cancellation hook must not hold a deadline or close hostage.
+      if (response.body && !response.body.locked)
+        void response.body.cancel().catch(() => {});
+    }
+  }
+
+  async #responseText(
+    response: Response,
+    signal: AbortSignal,
+    limit: number,
+  ): Promise<string> {
+    if (!response.body) return "";
+    const reader = response.body.getReader();
+    const cancel = () => {
+      void reader.cancel(signal.reason).catch(() => {});
+    };
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let bytes = 0;
+    let text = "";
+    signal.addEventListener("abort", cancel, { once: true });
+    try {
+      signal.throwIfAborted();
+      while (true) {
+        const chunk = await reader.read();
+        signal.throwIfAborted();
+        if (chunk.done) return text + decoder.decode();
+        bytes += chunk.value.byteLength;
+        if (bytes > limit)
+          throw failure(
+            limit === 0
+              ? "Notification response must be empty"
+              : "HTTP JSON-RPC frame exceeds 1 MiB",
+          );
+        text += decoder.decode(chunk.value, { stream: true });
+      }
+    } finally {
+      signal.removeEventListener("abort", cancel);
+      void reader.cancel().catch(() => {});
+      reader.releaseLock();
+    }
+  }
+
+  #start(): ProcessState {
+    const transport = this.#transport as StdioTransport;
+    const child = spawn(transport.command, transport.args ?? [], {
+      cwd: transport.cwd,
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let onClose!: () => void;
+    const state: ProcessState = {
+      child,
+      stopped: false,
+      pending: new Map(),
+      closed: new Promise<void>((resolve) => {
+        onClose = resolve;
+      }),
+    };
+    const decoder = new NdjsonDecoder();
+    const fail = (error: unknown) => {
+      for (const pending of state.pending.values()) pending.reject(error);
+      state.pending.clear();
+      this.#stop(state);
+    };
+    child.stderr.resume();
+    child.on("error", fail);
+    child.stdin.on("error", fail);
+    child.stdout.on("error", fail);
+    child.stdout.on("data", (chunk: Uint8Array) => {
+      try {
+        const lines = decoder.push(chunk);
+        for (const line of lines) {
+          const value = JSON.parse(line);
+          if (transport.lifecycle === "persistent") {
+            // Validate protocol output, but ignore replies to abandoned/unknown IDs.
+            const response = responseFor(value, { id: value?.id });
+            const pending = state.pending.get(value.id);
+            if (pending) pending.resolve(response);
+          } else {
+            const pending = state.pending.values().next().value;
+            if (
+              !pending ||
+              pending.notification ||
+              pending.response !== undefined
+            )
+              throw failure("Unexpected backend response");
+            pending.response = responseFor(value, pending.message);
+          }
+        }
+      } catch (error) {
+        fail(error);
+      }
+    });
+    child.on("close", (code: number | null) => {
+      try {
+        decoder.end();
+        for (const pending of state.pending.values()) {
+          if (code !== 0)
+            throw failure(`Backend exited with status ${String(code)}`);
+          if (!pending.notification) {
+            if (pending.response === undefined)
+              throw failure("Backend exited without a response");
+          }
+          pending.resolve(pending.response);
+        }
+      } catch (error) {
+        for (const pending of state.pending.values()) pending.reject(error);
+      }
+      state.pending.clear();
+      state.stopped = true;
+      if (this.#process === state) this.#process = undefined;
+      this.#processes.delete(state);
+      onClose();
+    });
+    this.#processes.add(state);
+    this.#process = state;
+    return state;
+  }
+
+  #stop(state: ProcessState): void {
+    if (this.#process === state) this.#process = undefined;
+    if (!state.stopped) {
+      state.stopped = true;
+      // Do not let an uncooperative backend retain owned processes after cancellation.
+      state.child.kill("SIGKILL");
+      // Descendants can inherit these pipes even after the SDK child exits.
+      // Retire our handles so reaping does not wait for external descendants.
+      state.child.stdin.destroy();
+      state.child.stdout.destroy();
+      state.child.stderr.destroy();
+    }
+  }
+
+  async #stdio(
+    message: any,
+    notification: boolean,
+    signal: AbortSignal,
+  ): Promise<unknown> {
+    const wire = JSON.stringify(message) + "\n";
+    const state = this.#process ?? this.#start();
+    const perEvent =
+      (this.#transport as StdioTransport).lifecycle === "per_event";
+    if (!notification && state.pending.has(message.id))
+      throw failure("Duplicate pending JSON-RPC request ID");
+    try {
+      return await new Promise<unknown>((resolve, reject) => {
+        let pending: Pending | undefined;
+        const cleanup = () => {
+          signal.removeEventListener("abort", abort);
+          if (pending && state.pending.get(message.id) === pending)
+            state.pending.delete(message.id);
+        };
+        const abort = () => {
+          cleanup();
+          reject(signal.reason);
+          // Abandoning an ID alone would leave the old intercept running when
+          // the queue advances. Kill and reap it before starting another call.
+          this.#stop(state);
+        };
+        const finish = (value: unknown) => {
+          cleanup();
+          resolve(value);
+        };
+        const fail = (error: unknown) => {
+          cleanup();
+          reject(error);
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        if (!notification || perEvent) {
+          pending = { message, notification, resolve: finish, reject: fail };
+          state.pending.set(message.id, pending);
+        }
+        const written = (error?: Error | null) => {
+          if (error) fail(error);
+          else if (notification && !perEvent) finish(undefined);
+        };
+        if (perEvent) state.child.stdin.end(wire, written);
+        else state.child.stdin.write(wire, written);
+      });
+    } catch (error) {
+      this.#stop(state);
+      throw error;
+    } finally {
+      if (perEvent || state.stopped) {
+        this.#stop(state);
+        await state.closed;
+      }
+    }
+  }
+
+  close(): Promise<void> {
+    if (this.#closing) return this.#closing;
+    this.#closed = true;
+    for (const controller of this.#controllers)
+      controller.abort(failure("Backend transport is closed"));
+    const processes = [...this.#processes];
+    for (const state of processes) this.#stop(state);
+    this.#closing = Promise.all(processes.map((state) => state.closed)).then(
+      () => {},
+    );
+    return this.#closing;
+  }
+}

package/src/client/types.ts

@@ -0,0 +1,173 @@
+import type {
+  EventInputs,
+  EventType,
+  Permission,
+  ContentSourceBinding,
+  DeliveryDiagnosticCode,
+} from "../draft/generated.js";
+import type { ContentSource } from "./content.js";
+import type {
+  Capabilities,
+  ContentReference,
+  ExecutionEventContextCompactBefore,
+  InterceptResponse,
+  InterceptRequest,
+  ObserveNotification,
+  StaticCapabilityManifest,
+} from "../draft/generated.js";
+import type { AuthProvider, DeliveryAuthProvider } from "./auth.js";
+
+export type Event = ObserveNotification["params"]["event"];
+export type { EventType } from "../draft/generated.js";
+/** Remove generated JSON extension index signatures while preserving named fields. */
+type Fields<T> = {
+  [K in keyof T as string extends K
+    ? never
+    : number extends K
+      ? never
+      : K]: T[K];
+};
+/** Harness content bodies may be owned streams instead of uploaded references. */
+export type HarnessValue<T> = T extends ContentReference
+  ? ContentReference | ContentSource | ReadableStream<Uint8Array>
+  : T extends readonly (infer V)[]
+    ? HarnessValue<V>[]
+    : T extends { selection: string }
+      ? Omit<
+          { [K in keyof Fields<T>]: HarnessValue<Fields<T>[K]> },
+          "selection"
+        > & { selection?: T["selection"] }
+      : T extends object
+        ? keyof Fields<T> extends never
+          ? T
+          : { [K in keyof Fields<T>]: HarnessValue<Fields<T>[K]> }
+        : T;
+// The generated compact-before JsonValue intersection includes impossible
+// primitive/array event branches. Remove those branches before mapping content
+// bodies; otherwise Omit sees their shared keys and loses canonical fields.
+type CompactBeforeObject = Exclude<
+  ExecutionEventContextCompactBefore,
+  string | number | boolean | readonly unknown[]
+>;
+export type HarnessEvent<K extends EventType = EventType> =
+  K extends "context.compact.before"
+    ? Omit<HarnessValue<CompactBeforeObject>, "trigger"> &
+        Pick<CompactBeforeObject, "trigger">
+    : HarnessValue<Extract<Event, { type: K }>>;
+/** Passing a body stream transfers its read/cancel ownership to the SDK.
+ * Keep host execution data separately; canonical effects carry accepted rewrites. */
+export type BoundaryInput<K extends EventType> = K extends EventType
+  ? Omit<HarnessEvent<K>, "type" | "source" | "id" | "time" | "manifest"> & {
+      id?: string;
+      time?: string;
+    }
+  : never;
+/** Generated, flattened host facts for named boundary calls. */
+export type EventInput<K extends EventType> = HarnessValue<EventInputs[K]>;
+/** Explicit delivery authority for one event. Effects remain separately granted. */
+export interface EventGrant {
+  modes: ("intercept" | "observe")[];
+  capabilities?: Capabilities;
+}
+/** A plain capability value grants interception only. Omitted events grant nothing. */
+export type EventCapabilities = Partial<
+  Record<EventType, Capabilities | EventGrant>
+>;
+export interface HooksOptions {
+  source: string;
+  /** A static manifest, or explicit event declarations. Plain Capabilities
+   * entries grant intercept only; use EventGrant to opt into observe. Omitted
+   * events, delivery modes, effects and elicitation form/url grants stay absent. */
+  capabilities: StaticCapabilityManifest | EventCapabilities;
+  auth?: AuthProvider | DeliveryAuthProvider;
+  /** Trusted HTTP network adapter (for example, host-managed TLS). The SDK still
+   * owns protocol/authentication and cancellation. Scope transport credentials
+   * to their exact destination; upload requests must not inherit event TLS identity.
+   * OAuth discovery/token requests use the separate auth({ fetch }) override. */
+  fetch?: typeof globalThis.fetch;
+  /** Bound the immutable raw-content snapshot held by each boundary. */
+  maxContentBytes?: number;
+  /** Best-effort observation budget, bounded by the operation signal. */
+  observationTimeoutMs?: number;
+}
+export interface BoundaryOptions {
+  /** Generated named slots bind owned sources to producer descriptors, without refs. */
+  contentSources?: readonly ContentSourceBinding<
+    ContentSource | ReadableStream<Uint8Array>
+  >[];
+  /** Canonical pending state before any interceptor runs. */
+  initialState?: InterceptRequest["params"]["state"];
+  /** One operation budget: queue, authentication, content, delivery and observations. */
+  signal?: AbortSignal;
+  /** Complete narrowed advertisement; omitted controls stay absent. */
+  capabilities?: Capabilities;
+}
+/** Structured SDK delivery evidence; messages and credential material are excluded. */
+export interface DeliveryDiagnostic extends Omit<DeliveryError, "code"> {
+  code: DeliveryDiagnosticCode;
+}
+export interface DeliveryError {
+  backendId: string;
+  subscriptionIndex: number;
+  phase: "preparation" | "interception" | "observation";
+  code:
+    | "PREPARATION_FAILED"
+    | "DELIVERY_FAILED"
+    | "DEADLINE_EXCEEDED"
+    | "INTERRUPTED";
+  failurePolicy?: "fail-open" | "fail-closed";
+  syntheticDenial: boolean;
+}
+/** Immutable JSON snapshot, including nested candidate values and extensions. */
+// Bound recursive JSON extension types for TypeScript; runtime freezing has no
+// depth limit. Six levels cover the canonical containers and nested JSON data.
+type StateDepth = [0, 0, 1, 2, 3, 4, 5];
+type ReadonlyState<T, D extends number = 6> = T extends
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  ? T
+  : D extends 0
+    ? Readonly<T>
+    : T extends object
+      ? { readonly [P in keyof T]: ReadonlyState<T[P], StateDepth[D]> }
+      : T;
+/** Canonical pending state after the last accepted settlement. */
+export type BoundaryState = ReadonlyState<
+  NonNullable<InterceptRequest["params"]["state"]>
+>;
+export interface BoundaryResult<K extends EventType = EventType> {
+  /** Accepted effective input, with occurrence identity and static envelope supplied.
+   * Body streams are owned delivery resources, not reusable output streams. */
+  event: HarnessEvent<K>;
+  /** Effective canonical effects. The harness enacts them; the SDK executes no operation. */
+  response: InterceptResponse;
+  /** Detached, deeply frozen canonical state; no effects replay is needed.
+   * An interrupted boundary must not execute, even if earlier accepted state
+   * contains a candidate or permission. With no acceptance, initialState is
+   * preserved (or the neutral candidate/permission state is returned). */
+  readonly state: BoundaryState;
+  /** Canonical settled permission. None is not approval; interruption forbids execution. */
+  readonly permission: `${Permission}`;
+  /** Accepted tool arguments, not the original proposal. Validate in host code before use. */
+  readonly input: unknown;
+  /** All interception and observation delivery diagnostics. */
+  diagnostics: DeliveryDiagnostic[];
+  errors: DeliveryError[];
+  /** Compatibility view of observation diagnostics; already settled when the call returns. */
+  observations: Promise<DeliveryError[]>;
+  interrupted: boolean;
+}
+export interface ConfigurationIssue {
+  path: string;
+  code: string;
+}
+export class ConfigurationError extends Error {
+  readonly code = "INVALID_CONFIGURATION";
+  constructor(readonly issues: readonly ConfigurationIssue[]) {
+    super("Hook configuration could not be resolved");
+    this.name = "ConfigurationError";
+  }
+}

package/src/client/validation.ts

@@ -0,0 +1,24 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { fullFormats } from "ajv-formats/dist/formats.js";
+import { schemas } from "../draft/schemas.js";
+
+let registry: Ajv2020 | undefined;
+/** Validate against the checked-in canonical schema without coercion. */
+export function validateWire(name: string, value: unknown): string[] {
+  if (!registry) {
+    registry = new Ajv2020({
+      allErrors: true,
+      strict: false,
+      ownProperties: true,
+    });
+    registry.addFormat("uri", fullFormats.uri);
+    registry.addFormat("date-time", fullFormats["date-time"]);
+    for (const schema of schemas) registry.addSchema(schema);
+  }
+  const validate = registry.getSchema(
+    `https://agenthooksprotocol.org/schemas/draft/${name}.schema.json`,
+  );
+  if (!validate) return ["Unknown protocol schema"];
+  if (validate(value)) return [];
+  return (validate.errors ?? []).map((e) => `${e.instancePath}: ${e.keyword}`);
+}