agenthooksprotocol 0.1.0 → 0.2.0

package/src/client/hooks.ts

@@ -23,7 +23,7 @@ import {
   validateInterceptResponse,
 } from "../draft/index.js";
 import { BackendTransport } from "./transport.js";
-import { ContentManager, ContentSource } from "./content.js";
+import { Attachment, ContentManager, ContentSource } from "./content.js";
 import { composeResponseAsync, normalizeEffects } from "./composition.js";
 import { auth } from "./auth.js";
 import { validateWire } from "./validation.js";
@@ -107,6 +107,12 @@ const matches = (selector: string, type: string) =>
   selector === type ||
   (selector.endsWith(".*") && selector.slice(0, -2) === type.split(".")[0]);
 
+type ElicitationLifetime = {
+  id: string;
+  sessionId: string | undefined;
+  retired: boolean;
+};
+
 /** Configuration-driven, harness-facing AHP client. No host operation is executed. */
 export class Hooks {
   readonly initialized: Promise<void>;
@@ -121,9 +127,12 @@ export class Hooks {
   private closed?: Promise<void>;
   private readonly elicitations = new Map<
     string,
-    { event: any; bytes: Uint8Array }
+    { event: any; owner: Attachment; size: number; release: () => Promise<void> }
   >();
   private elicitationBytes = 0;
+  // Tokens exist only for active calls, including preparation before any bytes
+  // can be retained. Retirement invalidates those calls without tombstones.
+  private readonly activeElicitations = new Set<ElicitationLifetime>();
 
   constructor(config: unknown, options: HooksOptions) {
     this.options = {
@@ -431,23 +440,64 @@ export class Hooks {
           : 64 * 1024 * 1024,
       allowLoopback: true,
     });
-    manager.own(input);
-    manager.own(options.contentSources);
+    try {
+      manager.own([input, options.contentSources]);
+    } catch (error) {
+      await manager.close().catch(() => {});
+      throw error;
+    }
     this.managers.add(manager);
     const signal = combineSignals(this.lifetime.signal, options.signal);
+    const exchange: ElicitationLifetime | undefined =
+      type === "user.elicitation.request"
+        ? {
+            id: input.id ?? randomUUID(),
+            sessionId: (input as any).session?.id,
+            retired: false,
+          }
+        : undefined;
+    if (exchange) this.activeElicitations.add(exchange);
+    let completed = false;
+    let returnedContent: BoundaryResult<K>["content"];
+
     const work = (async () => {
       // Calls after close are misuse. Active calls return interruption evidence.
       this.lifetime.signal.throwIfAborted();
       await this.initialized;
-      return this.run(type, input, options, signal, manager);
+      return this.run(type, input, options, signal, manager, exchange);
     })();
     this.pending.add(work);
     try {
-      return await work;
+      const result = await work;
+      completed = true;
+      if (result.content && !result.interrupted) {
+        manager.transfer(result.content);
+        returnedContent = result.content;
+      }
+      return result;
     } finally {
-      await manager.close();
-      this.managers.delete(manager);
-      this.pending.delete(work);
+      // Terminal exchanges retire even when validation or cancellation bypasses run.
+      if (type === "user.elicitation.result")
+        this.forgetElicitation((input as any).parentEventId);
+      if (
+        type === "user.elicitation.request" &&
+        (!completed || signal.aborted) &&
+        input.id
+      )
+        this.forgetElicitation(input.id);
+      if (type === "session.end")
+        this.retireSessionElicitations((input as any).session?.id);
+      if (exchange) this.activeElicitations.delete(exchange);
+      try {
+        if (completed) await manager.close();
+        else await manager.close().catch(() => {});
+      } catch (error) {
+        await returnedContent?.close().catch(() => {});
+        throw error;
+      } finally {
+        this.managers.delete(manager);
+        this.pending.delete(work);
+      }
     }
   }
 
@@ -457,12 +507,13 @@ export class Hooks {
     options: BoundaryOptions,
     signal: AbortSignal,
     manager: ContentManager,
+    exchange?: ElicitationLifetime,
   ): Promise<BoundaryResult<K>> {
     let event: any = cloneInput({
       ...input,
       type,
       source: this.options.source,
-      id: input.id ?? randomUUID(),
+      id: exchange?.id ?? input.id ?? randomUUID(),
       time: input.time ?? new Date().toISOString(),
     });
     bindContentSources(type, event, options.contentSources);
@@ -494,7 +545,7 @@ export class Hooks {
     };
     if (signal.aborted)
       return {
-        event,
+        event: await resultEvent(event, manager),
         response: {
           jsonrpc: "2.0",
           id: requestId,
@@ -512,7 +563,10 @@ export class Hooks {
         observations: Promise.resolve([]),
         interrupted: true,
       } as BoundaryResult<K>;
-    const originalRequest = this.elicitationFor(event);
+    const localSources = new Set<ReadableStream<Uint8Array>>();
+    let correlation: { event: Event; owner: Attachment; release: () => Promise<void> } | undefined;
+    let originalRequest: Event | undefined;
+
     let effects: Effect[] = [];
     let state = structuredClone(options.initialState);
     // A supplied snapshot is input to the first receiver, not a newly accepted
@@ -559,6 +613,8 @@ export class Hooks {
         advertised.modes.includes(r.subscription.mode),
     );
     try {
+      correlation = this.elicitationFor(event, manager);
+      originalRequest = correlation?.event;
       // Validate a metadata-only view before any delivery (this does not consume bytes).
       const metadata = await manager.prepare(
         event,
@@ -632,11 +688,8 @@ export class Hooks {
             projected.elicitation?.request?.selection === "body" &&
             event.elicitation?.request?.body instanceof ReadableStream
           ) {
-            const bytes = await manager.readBody(
-              event.elicitation.request.body,
-              signal,
-            );
-            this.rememberElicitation(event, bytes);
+            const retained = await manager.retainBody(event.elicitation.request.body, signal);
+            this.rememberElicitation(event, retained, exchange!);
           }
           const request = {
             jsonrpc: "2.0",
@@ -691,7 +744,13 @@ export class Hooks {
             );
           const staged = await raceAbort(
             composeResponseAsync(event, effects, decoded.value, caps, {
-              readContent: (body) => manager.readBody(body, deadline),
+              readContent: (body) => originalRequest && body === (originalRequest as any).elicitation.request.body
+                ? correlation!.owner.read(deadline)
+                : manager.readBody(body, deadline),
+              ownContent: (body) => {
+                manager.own(body);
+                localSources.add(body);
+              },
               selectedEvent: projected,
               state,
               ...(originalRequest
@@ -771,40 +830,34 @@ export class Hooks {
         const jobs = observations.map((route) =>
           this.observe(route, snapshot, manager, signal),
         );
-        observed = Promise.all(jobs)
-          .then((results) =>
-            results.filter(
-              (result): result is DeliveryError => result !== undefined,
-            ),
-          )
-          .finally(async () => {
-            await manager.close();
-            this.managers.delete(manager);
-          });
+        observed = Promise.all(jobs).then((results) =>
+          results.filter(
+            (result): result is DeliveryError => result !== undefined,
+          ),
+        );
         await observed;
-      } else {
-        await manager.close();
-        this.managers.delete(manager);
       }
       interrupted ||= signal.aborted;
       if (type === "user.elicitation.result")
         this.forgetElicitation(event.parentEventId);
       if (
         type === "user.elicitation.request" &&
-        (interrupted || effects.some((e) => e.type === "deny"))
+        (interrupted ||
+          errors.length > 0 ||
+          (await observed).length > 0 ||
+          effects.some((e) => e.type === "deny"))
       )
         this.forgetElicitation(event.id);
       if (type === "session.end")
-        for (const [id, entry] of this.elicitations)
-          if (entry.event.session?.id === event.session?.id)
-            this.forgetElicitation(id);
+        this.retireSessionElicitations(event.session?.id);
       const response = {
         jsonrpc: "2.0",
         id: requestId,
         result: { protocolVersion: "draft", effects },
       } as InterceptResponse;
       return {
-        event,
+        event: await resultEvent(event, manager, localSources),
+        content: manager.resultContent(event),
         response,
         state: snapshotState(state),
         get permission() {
@@ -819,9 +872,13 @@ export class Hooks {
         interrupted,
       } as BoundaryResult<K>;
     } catch (error) {
-      await manager.close();
+      if (type === "user.elicitation.request")
+        this.forgetElicitation(requestId);
+      await manager.close().catch(() => {});
       this.managers.delete(manager);
       throw error;
+    } finally {
+      await correlation?.release().catch(() => {});
     }
   }
 
@@ -887,44 +944,79 @@ export class Hooks {
     }
   }
 
-  private rememberElicitation(event: any, bytes: Uint8Array): void {
-    if (this.elicitations.has(event.id)) return;
+  private rememberElicitation(
+    event: any,
+    retained: { owner: Attachment; size: number; release: () => Promise<void> },
+    exchange: ElicitationLifetime,
+  ): void {
+    if (exchange.retired || this.lifetime.signal.aborted || this.elicitations.has(event.id)) {
+      void retained.release().catch(() => {});
+      return;
+    }
     const limit = this.options.maxContentBytes ?? 64 * 1024 * 1024;
-    if (bytes.byteLength > limit)
+    if (retained.size > limit) {
+      void retained.release().catch(() => {});
       throw new Error("Elicitation request exceeds retention budget");
-    while (
-      this.elicitationBytes + bytes.byteLength > limit ||
+    }
+    if (
+      this.elicitationBytes + retained.size > limit ||
       this.elicitations.size >= 128
-    )
-      this.forgetElicitation(this.elicitations.keys().next().value!);
-    const stored = cloneInput(event);
-    delete stored.elicitation.request.body;
-    this.elicitations.set(event.id, { event: stored, bytes });
-    this.elicitationBytes += bytes.byteLength;
+    ) {
+      void retained.release().catch(() => {});
+      throw new Error("Active elicitation exchanges exceed retention budget");
+    }
+    // Pending exchanges retain correlation facts and a lease on the same owner.
+    const stored = {
+      type: event.type,
+      id: event.id,
+      source: event.source,
+      session: event.session ? { id: event.session.id } : undefined,
+      elicitation: {
+        mode: event.elicitation.mode,
+        server: event.elicitation.server,
+        request: { mediaType: event.elicitation.request.mediaType },
+      },
+    };
+    this.elicitations.set(event.id, { event: stored, ...retained });
+    this.elicitationBytes += retained.size;
   }
-  private elicitationFor(event: any): Event | undefined {
+  private elicitationFor(event: any, manager: ContentManager): {
+    event: Event; owner: Attachment; release: () => Promise<void>;
+  } | undefined {
     if (event.type !== "user.elicitation.result") return undefined;
     const entry = this.elicitations.get(event.parentEventId);
     if (!entry) return undefined;
-    const copy = cloneInput(entry.event),
-      bytes = entry.bytes.slice();
-    copy.elicitation.request.body = new ReadableStream<Uint8Array>({
-      start(c) {
-        c.enqueue(bytes);
-        c.close();
-      },
-    });
-    return copy;
+    const copy = cloneInput(entry.event);
+    copy.elicitation.request.body = entry.owner.stream;
+    return { event: copy, owner: entry.owner, release: manager.lease(entry.owner) };
+  }
+  /** End an abandoned host elicitation exchange without delivering a result. */
+  discardElicitation(requestEventId: string): void {
+    this.forgetElicitation(requestEventId);
+  }
+
+  private retireSessionElicitations(sessionId: string | undefined): void {
+    for (const exchange of this.activeElicitations)
+      if (exchange.sessionId === sessionId) exchange.retired = true;
+    for (const [id, entry] of this.elicitations)
+      if (entry.event.session?.id === sessionId) this.forgetElicitation(id);
   }
+
   private forgetElicitation(id: string): void {
+    for (const exchange of this.activeElicitations)
+      if (exchange.id === id) exchange.retired = true;
     const entry = this.elicitations.get(id);
-    if (entry) this.elicitationBytes -= entry.bytes.byteLength;
+    if (entry) {
+      this.elicitationBytes -= entry.size;
+      void entry.release().catch(() => {});
+    }
     this.elicitations.delete(id);
   }
 
   /** Cancel pending work and release SDK-owned resources; injected stores remain owned by the host. */
   close(): Promise<void> {
     if (!this.closed) {
+      for (const exchange of this.activeElicitations) exchange.retired = true;
       this.lifetime.abort(new Error("Hooks closed"));
       this.closed = (async () => {
         await this.initialized.catch(() => {});
@@ -936,6 +1028,7 @@ export class Hooks {
         await Promise.allSettled([...this.managers].map((m) => m.close()));
         await Promise.allSettled([...this.pending]);
         this.authContexts.clear();
+        await Promise.allSettled([...this.elicitations.values()].map(entry => entry.release()));
         this.elicitations.clear();
         this.elicitationBytes = 0;
       })();
@@ -1150,6 +1243,39 @@ export class Hooks {
   }
 }
 
+// Return independent copies of prepared or synthesized payloads. Never read an
+// unselected producer stream solely to construct a result.
+async function resultEvent(
+  value: any,
+  manager: ContentManager,
+  localSources = new Set<ReadableStream<Uint8Array>>(),
+): Promise<any> {
+  if (value instanceof ContentSource) value = value.stream;
+  if (value instanceof ReadableStream) {
+    return manager.resultBody(value, localSources.has(value));
+  }
+  if (Array.isArray(value))
+    return Promise.all(
+      value.map((child) => resultEvent(child, manager, localSources)),
+    );
+  if (value && typeof value === "object") {
+    const entries = await Promise.all(
+      Object.entries(value).map(async ([key, child]) =>
+        [key, await resultEvent(child, manager, localSources)] as const),
+    );
+    const copy = Object.fromEntries(
+      entries.filter(([, child]) => child !== undefined),
+    );
+    if (
+      (value.body instanceof ReadableStream || value.body instanceof ContentSource) &&
+      !copy.body
+    )
+      copy.selection = "metadata";
+    return copy;
+  }
+  return value;
+}
+
 function cloneInput(value: any): any {
   if (value instanceof ContentSource) return value.stream;
   if (value instanceof ReadableStream) return value;
@@ -1217,13 +1343,15 @@ function combineSignals(first: AbortSignal, second?: AbortSignal): AbortSignal {
   return second ? AbortSignal.any([first, second]) : first;
 }
 function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
-  if (signal.aborted) return Promise.reject(signal.reason);
   return new Promise((resolve, reject) => {
     const abort = () => reject(signal.reason);
     signal.addEventListener("abort", abort, { once: true });
     promise
       .then(resolve, reject)
       .finally(() => signal.removeEventListener("abort", abort));
+    // The operation already exists: own its rejection even if cancellation
+    // occurred synchronously while constructing it.
+    if (signal.aborted) abort();
   });
 }
 

package/src/client/index.ts

@@ -26,3 +26,5 @@ export {
   CapabilityBuilder,
 } from "../draft/generated.js";
 export type * from "../draft/generated.js";
+
+export { effectNames, supports } from "../draft/generated.js";

package/src/client/types.ts

@@ -5,19 +5,19 @@ import type {
   ContentSourceBinding,
   DeliveryDiagnosticCode,
 } from "../draft/generated.js";
-import type { ContentSource } from "./content.js";
+import type { AttachmentContent, ContentSource } from "./content.js";
 import type {
   Capabilities,
   ContentReference,
   ExecutionEventContextCompactBefore,
   InterceptResponse,
   InterceptRequest,
-  ObserveNotification,
+  Event,
   StaticCapabilityManifest,
 } from "../draft/generated.js";
 import type { AuthProvider, DeliveryAuthProvider } from "./auth.js";
 
-export type Event = ObserveNotification["params"]["event"];
+export type { Event } from "../draft/generated.js";
 export type { EventType } from "../draft/generated.js";
 /** Remove generated JSON extension index signatures while preserving named fields. */
 type Fields<T> = {
@@ -139,6 +139,9 @@ export type BoundaryState = ReadonlyState<
   NonNullable<InterceptRequest["params"]["state"]>
 >;
 export interface BoundaryResult<K extends EventType = EventType> {
+  /** Present for owned Attachments. Effective local bodies by content item id,
+   * including unread lazy sources. Close explicitly, independently of Hooks. */
+  readonly content?: AttachmentContent;
   /** Accepted effective input, with occurrence identity and static envelope supplied.
    * Body streams are owned delivery resources, not reusable output streams. */
   event: HarnessEvent<K>;

package/src/content-upload.ts

@@ -1,3 +1,5 @@
+import type { ContentReference, ContentUploadReceipt } from "./draft/generated.js";
+export type { ContentReference, ContentUploadReceipt } from "./draft/generated.js";
 /** Normative HTTP content upload. Event authentication is deliberately not an input. */
 export interface UploadConfiguration {
   endpoint: string;
@@ -6,17 +8,16 @@ export interface UploadConfiguration {
   maxBytes?: number;
   [key: string]: unknown;
 }
-export interface BodyReference {
-  ref: string;
-  size: number;
-  sha256: string;
+/** Explicitly discard upload confirmation metadata before publishing a reference. */
+export function contentReference(receipt: ContentUploadReceipt): ContentReference {
+  return { ref: receipt.ref };
 }
-/** Check the receiver descriptor before exposing a body reference. */
-export function validateBodyReference(
+/** Verify the upload receipt against the exact sent bytes before publication. */
+export function validateUploadReceipt(
   value: unknown,
   size: number,
   sha256: string,
-): BodyReference {
+): ContentUploadReceipt {
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw Error("Invalid upload descriptor");
   const body = value as Record<string, unknown>;
@@ -40,7 +41,7 @@ export async function uploadContent(
     resolveToken?: (name: string) => string | undefined;
     allowLoopback?: boolean;
   } = {},
-): Promise<BodyReference> {
+): Promise<ContentUploadReceipt> {
   if (
     !config ||
     typeof config.endpoint !== "string" ||
@@ -107,7 +108,7 @@ export async function uploadContent(
     await response.body?.cancel();
     throw Error(`Content upload failed: HTTP ${response.status}`);
   }
-  return validateBodyReference(await response.json(), snapshot.length, sha256);
+  return validateUploadReceipt(await response.json(), snapshot.length, sha256);
 }
 export interface NormalizedContentInput {
   id: string;
@@ -129,7 +130,7 @@ export interface NormalizedContentView {
   parentItemId?: string;
   synthesized?: boolean;
   selection: "body" | "metadata" | "omit";
-  body?: BodyReference;
+  body?: ContentReference;
   gap?: { reason: string };
 }
 /** Select once per subscriber. Return no body reference until upload confirms availability. */
@@ -139,7 +140,7 @@ export async function prepareWireContent(
     subscription?: string;
     selection: Record<string, "body" | "metadata" | "omit">;
     authorized: (item: NormalizedContentInput) => boolean;
-    upload: (bytes: Uint8Array) => Promise<BodyReference>;
+    upload: (bytes: Uint8Array) => Promise<ContentUploadReceipt>;
     mode: "intercept" | "observe";
     failClosed: boolean;
     timeoutMs?: number;
@@ -174,7 +175,7 @@ export async function prepareWireContent(
         try {
           const bytes = new Uint8Array(item.bytes);
           let timer: ReturnType<typeof setTimeout> | undefined;
-          let body: BodyReference;
+          let body: ContentUploadReceipt;
           try {
             body = await Promise.race([
               options.upload(bytes.slice()),
@@ -192,7 +193,7 @@ export async function prepareWireContent(
             new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)),
             (byte) => byte.toString(16).padStart(2, "0"),
           ).join("");
-          view.body = validateBodyReference(body, bytes.length, hash);
+          view.body = contentReference(validateUploadReceipt(body, bytes.length, hash));
         } catch {
           view.gap = { reason: "transfer_failed" };
         }

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

@@ -1,11 +1,11 @@
 {
   "sourceRepository": "agenthooksprotocol/agent-hooks-protocol",
-  "sourceCommit": "472c16e97cfd456d98cefa0c2a3d23df2f57dbcf",
+  "sourceCommit": "05b4750cb2dccf17d75236182d6971f3cbe97e1f",
   "schemaRevision": "draft",
   "protocolVersion": "draft",
   "generatorVersion": "0.1.0",
   "language": "typescript",
-  "schemaManifestSha256": "050852ec662d5a29c80d8951252b54a5fa48bb5e6c7ce08d88c45e614964a60a",
+  "schemaManifestSha256": "b397a3c4d613a67396f1727190052ce2f3bb208cdfa03e066f0c045525f25451",
   "documents": [
     {
       "path": "schema/draft/capabilities-request.schema.json",
@@ -29,16 +29,20 @@
     },
     {
       "path": "schema/draft/content-item.schema.json",
-      "sha256": "ef15f47f3f57f3004e89046a79429944b5361e302719f4f45bbf819667a13a38"
+      "sha256": "21ce30d451d6fe20eb56cf09108fe33500e40839669d2922911dd9b0b8cfe762"
     },
     {
       "path": "schema/draft/content-reference.schema.json",
-      "sha256": "24221c52d428c6104ce6f526f278d000169777f866adbc2c2de90a635469d692"
+      "sha256": "32b345818648f2d28dd0175705a85b22569ea535867349262e055bb3e3999e87"
     },
     {
       "path": "schema/draft/content-selection.schema.json",
       "sha256": "fe57bce4a7a6c7a8d51728634349621ba327b5ef118bc60b1c330260392e2a62"
     },
+    {
+      "path": "schema/draft/content-upload-receipt.schema.json",
+      "sha256": "02e04375b2e4764eea0e70299a9ae29f0d49b407dca797f49299a3cb2d7613dc"
+    },
     {
       "path": "schema/draft/content-upload.schema.json",
       "sha256": "a405adb54b8de11f3814840f7cbcd54d76cdcc2e25d00942f1c1755eb05c6753"
@@ -51,6 +55,10 @@
       "path": "schema/draft/effect.schema.json",
       "sha256": "1448151926563244194ed56b15e3074ddfc8ec8c10889f2e42ab49d66be2d031"
     },
+    {
+      "path": "schema/draft/event.schema.json",
+      "sha256": "7b19aa60dc775b23b74d78aad2cdc634e07c454c68f1a60b125c3e4ff391f1f9"
+    },
     {
       "path": "schema/draft/execution-event.schema.json",
       "sha256": "d9b13cf28e20eced629cfe8eb822eb6dfb2ac453fe14e6d2334c2f4b2793512a"
@@ -73,7 +81,7 @@
     },
     {
       "path": "schema/draft/intercept-request.schema.json",
-      "sha256": "fbd5ed20681d918c8647382de6a2bc07de14a7ac57f756e68d2f3293043d534e"
+      "sha256": "179c6afd7092bcb1fa91522e6fbe6f63aa28d5dfbef35c9aa661304028ba48c9"
     },
     {
       "path": "schema/draft/intercept-response.schema.json",
@@ -89,7 +97,7 @@
     },
     {
       "path": "schema/draft/observe-notification.schema.json",
-      "sha256": "27255ccd1a6d0fa788161825f4df74f7e0b3c074a8dc7c8cdeb7e07df11d55cf"
+      "sha256": "770dd91480b4a0a0e8a3565e3724ab5d77bbede19faff223e10a8e442f926a62"
     },
     {
       "path": "schema/draft/registration.schema.json",