agenthooksprotocol 0.0.0-bootstrap.0

package/src/compaction.ts

@@ -0,0 +1,196 @@
+import { validateEffect } from "./draft/index.js";
+/** Serial host-side text compaction. Responses commit atomically. Only `applied`
+ * permits downstream use. Upload immutable UTF-8 bodies before wire exposure. */
+export interface CompactionEffect {
+  type: string;
+  target?: string;
+  operation?: string;
+  value?: unknown;
+  text?: string;
+  reason?: string;
+}
+export interface CompactionObserver {
+  supplier: string;
+  run: (snapshot: any) => unknown;
+}
+export interface CompactionHook {
+  supplier: string;
+  failurePolicy: "fail-open" | "fail-closed";
+  run: (snapshot: any) => CompactionEffect[];
+}
+const copy = <T>(v: T): T => structuredClone(v);
+export function compactionCapabilities(
+  boundary: "before" | "after",
+  observeOnly = false,
+): any {
+  if (boundary !== "before" && boundary !== "after")
+    throw new Error("unknown boundary");
+  if (observeOnly) return { effects: [], modify: {} };
+  return {
+    effects: [
+      "modify",
+      "message",
+      ...(boundary === "before" ? ["return", "deny"] : []),
+    ],
+    modify: {
+      [boundary === "before" ? "instructions" : "summary"]: {
+        replace: true,
+        merge: false,
+      },
+    },
+  };
+}
+export function runCompaction(
+  instructions: string,
+  before: CompactionHook[] = [],
+  after: CompactionHook[] = [],
+  options: {
+    generate?: (instructions: string) => string;
+    itemId?: string;
+    observeOnly?: boolean;
+    observers?: CompactionObserver[];
+  } = {},
+): any {
+  const itemId = options.itemId ?? "summary-1";
+  if (typeof instructions !== "string" || typeof itemId !== "string" || !itemId)
+    throw new Error("invalid input");
+  for (const h of [...before, ...after])
+    if (
+      typeof h.supplier !== "string" ||
+      !h.supplier ||
+      !["fail-open", "fail-closed"].includes(h.failurePolicy) ||
+      typeof h.run !== "function"
+    )
+      throw new Error("invalid hook");
+  if (options.observers && !options.observeOnly)
+    throw new Error("observers require observeOnly");
+  for (const o of options.observers ?? [])
+    if (
+      typeof o.supplier !== "string" ||
+      !o.supplier ||
+      typeof o.run !== "function"
+    )
+      throw new Error("invalid observer");
+  let state: any = {
+    instructions,
+    candidate: null,
+    summary: null,
+    bodies: {},
+    messages: [],
+    denied: false,
+  };
+  const seen: any[] = [],
+    failures: any[] = [];
+  const summary = (staged: any, body: string) => {
+    const ref =
+      "urn:ahp:compaction:utf8:" +
+      Array.from(new TextEncoder().encode(body), (b) =>
+        b.toString(16).padStart(2, "0"),
+      ).join("");
+    staged.bodies[ref] = body;
+    return { id: itemId, ref };
+  };
+  const pipeline = (boundary: "before" | "after", hooks: CompactionHook[]) => {
+    const caps = compactionCapabilities(
+      boundary,
+      options.observeOnly === true && boundary === "after",
+    );
+    for (const hook of hooks) {
+      const snapshot = { ...copy(state), boundary, capabilities: caps };
+      seen.push(copy(snapshot));
+      try {
+        const effects = hook.run(copy(snapshot));
+        if (!Array.isArray(effects)) throw new Error("effects must be array");
+        const staged = copy(state);
+        for (const e of effects) {
+          if (
+            !e ||
+            typeof e !== "object" ||
+            !validateEffect(e).ok ||
+            !caps.effects.includes(e.type)
+          )
+            throw new Error("unsupported effect");
+          if (e.type === "modify") {
+            if (
+              e.target !==
+                (boundary === "before" ? "instructions" : "summary") ||
+              e.operation !== "replace" ||
+              typeof e.value !== "string"
+            )
+              throw new Error("invalid modification");
+            if (boundary === "before") staged.instructions = e.value;
+            else staged.summary = summary(staged, e.value);
+          } else if (
+            e.type === "deny" &&
+            (typeof e.reason !== "string" || !e.reason)
+          )
+            throw new Error("denial requires reason");
+          else if (e.type === "return" && typeof e.value !== "string")
+            throw new Error("summary must be text");
+          else if (e.type === "message" && typeof e.text !== "string")
+            throw new Error("message must be text");
+        }
+        if (staged.instructions !== state.instructions) staged.candidate = null;
+        for (const e of effects) {
+          if (e.type === "return")
+            staged.candidate = { body: e.value, supplier: hook.supplier };
+          else if (e.type === "deny") staged.denied = true;
+          else if (e.type === "message") staged.messages.push(e.text);
+        }
+        state = staged;
+      } catch {
+        failures.push({ boundary, supplier: hook.supplier });
+        if (
+          hook.failurePolicy === "fail-closed" &&
+          !(options.observeOnly && boundary === "after")
+        )
+          return false;
+      }
+      if (state.denied) return false;
+    }
+    return true;
+  };
+  let generated = false,
+    applied = false,
+    provenance: any = null;
+  if (pipeline("before", before)) {
+    let body: string;
+    if (state.candidate !== null) {
+      body = state.candidate.body;
+      provenance = { kind: "supplied", supplier: state.candidate.supplier };
+    } else {
+      body = (options.generate ?? ((v) => "summary:" + v))(state.instructions);
+      if (typeof body !== "string")
+        throw new Error("generator must return text");
+      generated = true;
+      provenance = { kind: "generated" };
+    }
+    state.summary = summary(state, body);
+    applied = options.observeOnly ? true : pipeline("after", after);
+  }
+  const result = { ...state, seen, failures, generated, provenance, applied };
+  if (options.observeOnly && applied) {
+    for (const observer of [...after, ...(options.observers ?? [])]) {
+      const snapshot = {
+        ...copy(state),
+        boundary: "after",
+        applied: true,
+        generated,
+        provenance: copy(provenance),
+        capabilities: compactionCapabilities("after", true),
+      };
+      seen.push(copy(snapshot));
+      const notify = observer.run;
+      // Scheduling never calls user code inline or awaits its returned promise.
+      // Browser/Node observers must yield for I/O; blocking native work belongs
+      // in a host worker. The unref'd timer cannot keep Node alive on shutdown.
+      const timer = setTimeout(() => {
+        void Promise.resolve()
+          .then(() => notify(snapshot))
+          .catch(() => {});
+      }, 0);
+      (timer as unknown as { unref?: () => void }).unref?.();
+    }
+  }
+  return result;
+}

package/src/content-upload.ts

@@ -0,0 +1,205 @@
+/** Normative HTTP content upload. Event authentication is deliberately not an input. */
+export interface UploadConfiguration {
+  endpoint: string;
+  auth?: { type: "bearer"; tokenEnv: string; [key: string]: unknown };
+  timeoutMs?: number;
+  maxBytes?: number;
+  [key: string]: unknown;
+}
+export interface BodyReference {
+  ref: string;
+  size: number;
+  sha256: string;
+}
+/** Check the receiver descriptor before exposing a body reference. */
+export function validateBodyReference(
+  value: unknown,
+  size: number,
+  sha256: string,
+): BodyReference {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw Error("Invalid upload descriptor");
+  const body = value as Record<string, unknown>;
+  if (
+    Object.keys(body).some((key) => !["ref", "size", "sha256"].includes(key)) ||
+    typeof body.ref !== "string" ||
+    !body.ref ||
+    !Number.isSafeInteger(body.size) ||
+    body.size !== size ||
+    typeof body.sha256 !== "string" ||
+    !/^[a-f0-9]{64}$/.test(body.sha256) ||
+    body.sha256 !== sha256
+  )
+    throw Error("Unconfirmed bytes");
+  return { ref: body.ref, size, sha256 };
+}
+export async function uploadContent(
+  config: UploadConfiguration,
+  bytes: Uint8Array,
+  options: {
+    resolveToken?: (name: string) => string | undefined;
+    allowLoopback?: boolean;
+  } = {},
+): Promise<BodyReference> {
+  if (
+    !config ||
+    typeof config.endpoint !== "string" ||
+    (config.timeoutMs !== undefined &&
+      (!Number.isSafeInteger(config.timeoutMs) || config.timeoutMs <= 0)) ||
+    (config.maxBytes !== undefined &&
+      (!Number.isSafeInteger(config.maxBytes) || config.maxBytes < 0))
+  )
+    throw Error("Invalid upload configuration");
+  const url = new URL(config.endpoint);
+  if (
+    url.username ||
+    url.password ||
+    url.hash ||
+    (url.protocol !== "https:" &&
+      !(
+        options.allowLoopback &&
+        url.protocol === "http:" &&
+        ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)
+      ))
+  )
+    throw Error("Unsafe upload endpoint");
+  if (!(bytes instanceof Uint8Array)) throw Error("Invalid content bytes");
+  const snapshot = new Uint8Array(bytes);
+  if (snapshot.length > (config.maxBytes ?? 52428800))
+    throw Error("Upload size limit");
+  const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", snapshot));
+  const sha256 = Array.from(hash, (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");
+  const headers: Record<string, string> = {
+    "content-type": "application/octet-stream",
+    "content-length": String(snapshot.length),
+    "ahp-content-sha256": sha256,
+  };
+  if (config.auth !== undefined) {
+    if (
+      !config.auth ||
+      config.auth.type !== "bearer" ||
+      typeof config.auth.tokenEnv !== "string" ||
+      !/^[A-Za-z_][A-Za-z0-9_]*$/.test(config.auth.tokenEnv)
+    )
+      throw Error("Invalid upload authentication");
+    const token = options.resolveToken?.(config.auth.tokenEnv);
+    if (typeof token !== "string" || !token)
+      throw Error("Missing upload credential");
+    headers.authorization = `Bearer ${token}`;
+  }
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: snapshot,
+    redirect: "error",
+    signal: AbortSignal.timeout(config.timeoutMs ?? 15000),
+  });
+  if (
+    response.status !== 201 ||
+    response.headers
+      .get("content-type")
+      ?.split(";")[0]
+      ?.trim()
+      .toLowerCase() !== "application/json"
+  ) {
+    await response.body?.cancel();
+    throw Error(`Content upload failed: HTTP ${response.status}`);
+  }
+  return validateBodyReference(await response.json(), snapshot.length, sha256);
+}
+export interface NormalizedContentInput {
+  id: string;
+  kind: string;
+  mediaType: string;
+  ref?: string;
+  bytes?: Uint8Array;
+  category?: string;
+  role?: string;
+  parentItemId?: string;
+  synthesized?: boolean;
+}
+export interface NormalizedContentView {
+  id: string;
+  kind: string;
+  mediaType: string;
+  category?: string;
+  role?: string;
+  parentItemId?: string;
+  synthesized?: boolean;
+  selection: "body" | "metadata" | "omit";
+  body?: BodyReference;
+  gap?: { reason: string };
+}
+/** Select once per subscriber. Return no body reference until upload confirms availability. */
+export async function prepareWireContent(
+  items: readonly NormalizedContentInput[],
+  options: {
+    subscription?: string;
+    selection: Record<string, "body" | "metadata" | "omit">;
+    authorized: (item: NormalizedContentInput) => boolean;
+    upload: (bytes: Uint8Array) => Promise<BodyReference>;
+    mode: "intercept" | "observe";
+    failClosed: boolean;
+    timeoutMs?: number;
+    maxBytes?: number;
+  },
+): Promise<NormalizedContentView[]> {
+  const result: NormalizedContentView[] = [];
+  for (const item of items) {
+    const { id, kind, mediaType, category, role, parentItemId, synthesized } =
+      item;
+    const view: NormalizedContentView = {
+      id,
+      kind,
+      mediaType,
+      ...(synthesized === undefined ? {} : { synthesized }),
+      ...(category ? { category } : {}),
+      ...(role ? { role } : {}),
+      ...(parentItemId ? { parentItemId } : {}),
+      selection:
+        options.selection[category ?? kind] ??
+        options.selection.default ??
+        "metadata",
+    };
+    if (view.selection === "body") {
+      if (!options.authorized(item))
+        view.gap = { reason: "permission_withheld" };
+      else if (item.bytes === undefined)
+        view.gap = { reason: "source_unavailable" };
+      else if (item.bytes.length > (options.maxBytes ?? 52428800))
+        view.gap = { reason: "limit_exceeded" };
+      else
+        try {
+          const bytes = new Uint8Array(item.bytes);
+          let timer: ReturnType<typeof setTimeout> | undefined;
+          let body: BodyReference;
+          try {
+            body = await Promise.race([
+              options.upload(bytes.slice()),
+              new Promise<never>((_, reject) => {
+                timer = setTimeout(
+                  () => reject(Error("Upload timeout")),
+                  options.timeoutMs ?? 15000,
+                );
+              }),
+            ]);
+          } finally {
+            if (timer !== undefined) clearTimeout(timer);
+          }
+          const hash = Array.from(
+            new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)),
+            (byte) => byte.toString(16).padStart(2, "0"),
+          ).join("");
+          view.body = validateBodyReference(body, bytes.length, hash);
+        } catch {
+          view.gap = { reason: "transfer_failed" };
+        }
+      if (view.gap && options.mode === "intercept" && options.failClosed)
+        throw Error(`Content delivery failure: ${view.gap.reason}`);
+    }
+    result.push(view);
+  }
+  return result;
+}

package/src/draft/README.md

@@ -0,0 +1,16 @@
+# Draft entrypoint
+
+`agenthooksprotocol/draft` provides generated models and codecs for the
+canonical draft catalogue, schema-backed validators, and reference runtime
+helpers. It is separate from the root deny/no-effect `tool.before` stdio runner;
+generated catalogue coverage is not full runtime support.
+
+See the [draft API guide](../../DRAFT-API.md) for validation, local versus wire
+identity, receiver-allocated content uploads, preparation callbacks, and runtime
+limits. `draftCodecs` is permissive decoding, not authorization validation.
+
+Protocol authority lives in the sibling repository's
+[`spec/draft`](../../../../../agent-hooks-protocol/spec/draft/index.md) and
+[`schema/draft`](../../../../../agent-hooks-protocol/schema/draft/manifest.json).
+Generated files in this directory must be regenerated from that source, not
+edited to define a different protocol contract.

package/src/draft/ahp-codegen.lock.json

@@ -0,0 +1,123 @@
+{
+  "sourceRepository": "agenthooksprotocol/agent-hooks-protocol",
+  "sourceCommit": "472c16e97cfd456d98cefa0c2a3d23df2f57dbcf",
+  "schemaRevision": "draft",
+  "protocolVersion": "draft",
+  "generatorVersion": "0.1.0",
+  "language": "typescript",
+  "schemaManifestSha256": "050852ec662d5a29c80d8951252b54a5fa48bb5e6c7ce08d88c45e614964a60a",
+  "documents": [
+    {
+      "path": "schema/draft/capabilities-request.schema.json",
+      "sha256": "c139a439d0e21bc59bd2e69b596e684484ba0052a7fdf6f2ec0810d1a5fad299"
+    },
+    {
+      "path": "schema/draft/capabilities-response.schema.json",
+      "sha256": "9e3b33d4bde82670770ad598dd70bb276bda120c4429783747dc91defc6911a8"
+    },
+    {
+      "path": "schema/draft/capabilities.schema.json",
+      "sha256": "c29b8effdb09a492bc791885ece3d59a824c4082771c782f41cacbb2304fc103"
+    },
+    {
+      "path": "schema/draft/catalogue-event.schema.json",
+      "sha256": "06ed4bc91478a93c8edc3b454d58e18e581f537c65fd1688f1533bd058bdbf4e"
+    },
+    {
+      "path": "schema/draft/common.schema.json",
+      "sha256": "d46f541db8a5f2a401a6b2b77f1d93e75076847e8f2b2e5d5ed201b8562107e5"
+    },
+    {
+      "path": "schema/draft/content-item.schema.json",
+      "sha256": "ef15f47f3f57f3004e89046a79429944b5361e302719f4f45bbf819667a13a38"
+    },
+    {
+      "path": "schema/draft/content-reference.schema.json",
+      "sha256": "24221c52d428c6104ce6f526f278d000169777f866adbc2c2de90a635469d692"
+    },
+    {
+      "path": "schema/draft/content-selection.schema.json",
+      "sha256": "fe57bce4a7a6c7a8d51728634349621ba327b5ef118bc60b1c330260392e2a62"
+    },
+    {
+      "path": "schema/draft/content-upload.schema.json",
+      "sha256": "a405adb54b8de11f3814840f7cbcd54d76cdcc2e25d00942f1c1755eb05c6753"
+    },
+    {
+      "path": "schema/draft/deny-effect.schema.json",
+      "sha256": "8ff24b87d1e58764ba1d200446732a216bf72d870a5f4cba72f704020622cd90"
+    },
+    {
+      "path": "schema/draft/effect.schema.json",
+      "sha256": "1448151926563244194ed56b15e3074ddfc8ec8c10889f2e42ab49d66be2d031"
+    },
+    {
+      "path": "schema/draft/execution-event.schema.json",
+      "sha256": "d9b13cf28e20eced629cfe8eb822eb6dfb2ac453fe14e6d2334c2f4b2793512a"
+    },
+    {
+      "path": "schema/draft/extensions.schema.json",
+      "sha256": "5722deafc1bf750e19e033702659fecd6a0804e598d114ebbd9aef9daac48835"
+    },
+    {
+      "path": "schema/draft/interaction-event.schema.json",
+      "sha256": "34550586dde5748f14df80e8879b5eec5e3b2ae5353ef84b0208e9248d6a0fb2"
+    },
+    {
+      "path": "schema/draft/intercept-deny-response.schema.json",
+      "sha256": "74f024322660b73e370ad086bde82edf0f94bbe7c440592de4ea083e292bcbf6"
+    },
+    {
+      "path": "schema/draft/intercept-no-effect-response.schema.json",
+      "sha256": "65429ed03e5580fbd906331f57d60042c18f97eb43d1103140ed9e7101642c16"
+    },
+    {
+      "path": "schema/draft/intercept-request.schema.json",
+      "sha256": "fbd5ed20681d918c8647382de6a2bc07de14a7ac57f756e68d2f3293043d534e"
+    },
+    {
+      "path": "schema/draft/intercept-response.schema.json",
+      "sha256": "9b71855630e8f5194631395ba907696dea3cd232884aaea783bfe9341711404f"
+    },
+    {
+      "path": "schema/draft/json-rpc-message.schema.json",
+      "sha256": "721a8e485e855863915c982368830d28091b8fd83f61e077d12c539714940ffa"
+    },
+    {
+      "path": "schema/draft/mcp-elicitation.schema.json",
+      "sha256": "52473b9e5dda9c514081319c9543d03a6ac85997a8fa98355b00502819f99e69"
+    },
+    {
+      "path": "schema/draft/observe-notification.schema.json",
+      "sha256": "27255ccd1a6d0fa788161825f4df74f7e0b3c074a8dc7c8cdeb7e07df11d55cf"
+    },
+    {
+      "path": "schema/draft/registration.schema.json",
+      "sha256": "3788ae90ee2aa057473ed03833f5310584d531e90a7f50b00541b013ab0a1c11"
+    },
+    {
+      "path": "schema/draft/schema.json",
+      "sha256": "191b1fd79f7550f69e6f2bb39ec7953fac727eed5721c7a36fb30d8fc029e8d0"
+    },
+    {
+      "path": "schema/draft/session-end.schema.json",
+      "sha256": "9d42bb96f2114e6b31db34f2fc1f40244c45e259c0dd27d2e3d1ea85bdc98cbc"
+    },
+    {
+      "path": "schema/draft/session-start.schema.json",
+      "sha256": "11da44d294f939941f19caa4b614a0e48743ceafdb3da70a5eb020a003bc3580"
+    },
+    {
+      "path": "schema/draft/task-workspace-event.schema.json",
+      "sha256": "9a11955ba26ca3d2d7f9362f82460d8247f77720d2991b54117b88b42338be21"
+    },
+    {
+      "path": "schema/draft/tool-after.schema.json",
+      "sha256": "a5f110d150df12ed4bb0ae7e4b8fd7b5dbb3973da7499a8f9931184c6824408a"
+    },
+    {
+      "path": "schema/draft/tool-before.schema.json",
+      "sha256": "8edb0bb32cd96b3e15e7a82d64f964b746cd51e3d98b0270d55a3e30ac57aef6"
+    }
+  ]
+}