agenthooksprotocol 0.1.0 → 0.2.0

package/src/draft/index.ts

@@ -233,7 +233,7 @@ export type {
 
 export type {
   UploadConfiguration,
-  BodyReference,
+  ContentUploadReceipt,
   NormalizedContentInput,
   NormalizedContentView,
 } from "../content-upload.js";
@@ -244,3 +244,8 @@ export type {
   ObservationEvent,
   ObservationNotification,
 } from "../observation.js";
+
+export { contentReference } from "../content-upload.js";
+
+export { effectNames, supports } from "./generated.js";
+export type { EffectName } from "./generated.js";

package/src/draft/schemas.ts

@@ -2671,16 +2671,6 @@ export const schemas = [
             type: "string",
             minLength: 1,
           },
-          size: {
-            type: "integer",
-            minimum: 0,
-          },
-          sha256: {
-            type: "string",
-            pattern: "^[a-f0-9]{64}$",
-            minLength: 64,
-            maxLength: 64,
-          },
           synthesized: {
             type: "boolean",
             description:
@@ -2688,6 +2678,18 @@ export const schemas = [
           },
         },
         additionalProperties: false,
+        allOf: [
+          {
+            not: {
+              required: ["size"],
+            },
+          },
+          {
+            not: {
+              required: ["sha256"],
+            },
+          },
+        ],
       },
       {
         type: "object",
@@ -2881,27 +2883,29 @@ export const schemas = [
     $id: "https://agenthooksprotocol.org/schemas/draft/content-reference.schema.json",
     title: "AHP content-reference (Draft)",
     type: "object",
-    required: ["ref", "size", "sha256"],
+    required: ["ref"],
     properties: {
       ref: {
         type: "string",
         minLength: 1,
       },
-      size: {
-        type: "integer",
-        minimum: 0,
-      },
-      sha256: {
-        type: "string",
-        pattern: "^[a-f0-9]{64}$",
-        minLength: 64,
-        maxLength: 64,
-      },
     },
     additionalProperties: false,
     $comment: "Mutable AHP draft. ",
     description:
-      "Receiver-allocated immutable bytes. The HTTP 201 upload response returns this descriptor. ref is opaque, not a URL or authorization grant; access is authorized by credential-derived scope. size counts exact octets and sha256 is their lowercase SHA-256 hex digest. Senders verify both before publication. A retry may allocate another ref; changed bytes require a new ref, not a new item id.",
+      "Receiver-allocated immutable content reference. ref is opaque, not a URL or authorization grant; access is authorized by credential-derived scope. Upload size and digest belong only in the separate content-upload-receipt, never this event reference.",
+    allOf: [
+      {
+        not: {
+          required: ["size"],
+        },
+      },
+      {
+        not: {
+          required: ["sha256"],
+        },
+      },
+    ],
   },
   {
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -2939,6 +2943,33 @@ export const schemas = [
     description:
       "Select by descriptor category; reasoning takes its own category, otherwise classify by media type, not enclosing message role. Unlisted categories use required default. Selection never grants authorization.",
   },
+  {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://agenthooksprotocol.org/schemas/draft/content-upload-receipt.schema.json",
+    title: "AHP ContentUploadReceipt (Draft)",
+    type: "object",
+    required: ["ref", "size", "sha256"],
+    properties: {
+      ref: {
+        type: "string",
+        minLength: 1,
+      },
+      size: {
+        type: "integer",
+        minimum: 0,
+      },
+      sha256: {
+        type: "string",
+        pattern: "^[a-f0-9]{64}$",
+        minLength: 64,
+        maxLength: 64,
+      },
+    },
+    additionalProperties: false,
+    $comment: "Mutable AHP draft. ",
+    description:
+      "HTTP 201 upload confirmation. ref identifies receiver-allocated immutable bytes; size counts exact octets and sha256 is their lowercase SHA-256 digest. Senders verify both before publishing only ref in an event body. This receipt is not event acknowledgement or proof of durable storage.",
+  },
   {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     $id: "https://agenthooksprotocol.org/schemas/draft/content-upload.schema.json",
@@ -3166,6 +3197,111 @@ export const schemas = [
     ],
     title: "AHP Effect (Draft)",
   },
+  {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://agenthooksprotocol.org/schemas/draft/event.schema.json",
+    title: "AHP Event (Draft)",
+    $comment:
+      "Mutable AHP draft. One shared event union; intercept eligibility is constrained at the request level.",
+    oneOf: [
+      {
+        $ref: "tool-before.schema.json",
+      },
+      {
+        $ref: "tool-after.schema.json",
+      },
+      {
+        $ref: "session-start.schema.json",
+      },
+      {
+        $ref: "session-end.schema.json",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/config.change.before",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/config.change.after",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/turn.start",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/turn.finish.before",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/turn.end",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/turn.progress",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/model.request.before",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/model.response.after",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/model.error",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/model.switch.before",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/model.switch.after",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/tool.permission.request",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/tool.permission.resolved",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/tool.progress",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/tool.batch.after",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/context.compact.before",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/context.compact.after",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/task.change.before",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/task.change.after",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/user.attention",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/user.elicitation.request",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/user.elicitation.result",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/user.message.inbound",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/user.message.outbound",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/workspace.change.before",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/workspace.change.after",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/file.changed",
+      },
+      {
+        $ref: "catalogue-event.schema.json#/$defs/hook.failure",
+      },
+    ],
+  },
   {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     $id: "https://agenthooksprotocol.org/schemas/draft/execution-event.schema.json",
@@ -6400,6 +6536,7 @@ export const schemas = [
                 $ref: "common.schema.json#/$defs/protocolVersion",
               },
               event: {
+                $ref: "event.schema.json",
                 oneOf: [
                   {
                     $ref: "tool-before.schema.json",
@@ -7546,104 +7683,7 @@ export const schemas = [
                 $ref: "common.schema.json#/$defs/protocolVersion",
               },
               event: {
-                oneOf: [
-                  {
-                    $ref: "tool-before.schema.json",
-                  },
-                  {
-                    $ref: "tool-after.schema.json",
-                  },
-                  {
-                    $ref: "session-start.schema.json",
-                  },
-                  {
-                    $ref: "session-end.schema.json",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/config.change.before",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/config.change.after",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/turn.start",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/turn.finish.before",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/turn.end",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/turn.progress",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/model.request.before",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/model.response.after",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/model.error",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/model.switch.before",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/model.switch.after",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/tool.permission.request",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/tool.permission.resolved",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/tool.progress",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/tool.batch.after",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/context.compact.before",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/context.compact.after",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/task.change.before",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/task.change.after",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/user.attention",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/user.elicitation.request",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/user.elicitation.result",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/user.message.inbound",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/user.message.outbound",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/workspace.change.before",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/workspace.change.after",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/file.changed",
-                  },
-                  {
-                    $ref: "catalogue-event.schema.json#/$defs/hook.failure",
-                  },
-                ],
+                $ref: "event.schema.json",
               },
             },
           },

package/src/draft-runtime.ts

@@ -1,5 +1,5 @@
 import { validateEffect } from "./draft/index.js";
-import { validateBodyReference, type BodyReference } from "./content-upload.js";
+import { validateUploadReceipt, type ContentUploadReceipt } from "./content-upload.js";
 /** Synthetic semantic harness. Wire acceptance remains the canonical validator's job. */
 import { stageResponse, object, type PendingState } from "./draft-atomic.js";
 import type { Effect, Capabilities } from "./draft/index.js";
@@ -211,7 +211,7 @@ export interface ContentView {
 /** Receiver storage scoped by the host's authenticated principal, not wire claims. */
 export class ContentReceiver {
   private stored = new Map<string, Uint8Array>();
-  async upload(scope: string, bytes: Uint8Array): Promise<BodyReference> {
+  async upload(scope: string, bytes: Uint8Array): Promise<ContentUploadReceipt> {
     if (!scope || !(bytes instanceof Uint8Array))
       throw Error("Authenticated scope and binary bytes required");
     const snapshot = bytes.slice();
@@ -239,7 +239,7 @@ export async function prepareContent(
     mode: "intercept" | "observe";
     failClosed: boolean;
     timeoutMs?: number;
-    upload(bytes: Uint8Array): Promise<BodyReference>;
+    upload(bytes: Uint8Array): Promise<ContentUploadReceipt>;
   },
 ): Promise<ContentView[]> {
   const result: ContentView[] = [];
@@ -257,7 +257,7 @@ export async function prepareContent(
           await crypto.subtle.digest("SHA-256", bytes),
         );
         let timer: ReturnType<typeof setTimeout> | undefined;
-        let confirmed: BodyReference;
+        let confirmed: ContentUploadReceipt;
         try {
           confirmed = await Promise.race([
             options.upload(bytes.slice()),
@@ -274,10 +274,8 @@ export async function prepareContent(
         const sha256 = Array.from(hash, (byte) =>
           byte.toString(16).padStart(2, "0"),
         ).join("");
-        const body = validateBodyReference(confirmed, bytes.length, sha256);
+        const body = validateUploadReceipt(confirmed, bytes.length, sha256);
         view.ref = body.ref;
-        view.sizeBytes = body.size;
-        view.sha256 = body.sha256;
       } catch {
         view.gap = "transfer_failed";
       }
@@ -350,10 +348,10 @@ export function actualTaskChange<T>(
     after: structuredClone(after),
   };
 }
-export { uploadContent, prepareWireContent } from "./content-upload.js";
+export { uploadContent, prepareWireContent, contentReference } from "./content-upload.js";
 export type {
   UploadConfiguration,
-  BodyReference,
+  ContentUploadReceipt,
   NormalizedContentInput,
   NormalizedContentView,
 } from "./content-upload.js";

package/src/server/attachments.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import {
-  parseContentReference,
-  type ContentReference,
+  parseContentUploadReceipt,
+  type ContentUploadReceipt,
 } from "../draft/generated.js";
 import { validateWire } from "../client/validation.js";
 
@@ -113,10 +113,10 @@ function parse(request: Request): Upload {
  * 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)
+function response(descriptor: ContentUploadReceipt): Response {
+  if (validateWire("content-upload-receipt", descriptor).length !== 0)
     throw new UploadError("Invalid content descriptor");
-  const decoded = parseContentReference(descriptor);
+  const decoded = parseContentUploadReceipt(descriptor);
   if (!decoded.ok || !Number.isSafeInteger(decoded.value.size))
     throw new UploadError("Invalid content descriptor");
   return new Response(JSON.stringify(decoded.value), {

package/src/server/hooks.ts

@@ -92,8 +92,9 @@ function supported(
       effect.type === "return" &&
       request.params.event.type === "user.elicitation.request"
     ) {
-      const mode = request.params.event.elicitation.mode;
-      if (!caps.elicitation?.[mode]) return false;
+      const elicitation = request.params.event.elicitation;
+      if (!object(elicitation) || typeof elicitation.mode !== "string") return false;
+      if (!caps.elicitation?.[elicitation.mode]) return false;
     }
     return true;
   });

package/src/server/index.ts

@@ -9,6 +9,8 @@ export { attachments, UploadError } from "./attachments.js";
 export type { Upload } from "./attachments.js";
 export type {
   ContentReference,
+  ContentUploadReceipt,
+  Event,
   InterceptRequest,
   ObserveNotification,
   CapabilitiesRequest,
@@ -16,3 +18,6 @@ export type {
 } from "../draft/generated.js";
 
 export { effects } from "../draft/generated.js";
+
+export { effectNames, supports } from "../draft/generated.js";
+export type { EffectName } from "../draft/generated.js";