agenthooksprotocol 0.1.0__tar.gz → 0.2.0__tar.gz

{agenthooksprotocol-0.1.0/src/agenthooksprotocol.egg-info → agenthooksprotocol-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agenthooksprotocol
-Version: 0.1.0
+Version: 0.2.0
 Summary: Official non-normative Python SDK for the Agent Hooks Protocol
 Author: Agent Hooks Protocol maintainers
 License: 
@@ -228,10 +228,10 @@ A typed, asynchronous SDK for the [Agent Hooks Protocol](https://github.com/agen
 
 ## Install
 
-The distribution name is `agenthooksprotocol`. Until the first PyPI release, install a pinned Git commit:
+Install the published `agenthooksprotocol` package from [PyPI](https://pypi.org/project/agenthooksprotocol/):
 
 ```sh
-python -m pip install 'agenthooksprotocol[http] @ git+https://github.com/agenthooksprotocol/python-sdk.git@<commit-sha>'
+python -m pip install 'agenthooksprotocol[http]'
 ```
 
 HTTPX is an opt-in dependency (`[http]`). Pydantic is an independent opt-in integration (`[pydantic]`); neither a web framework nor Pydantic is needed for the core SDK or stdio.
@@ -260,7 +260,7 @@ async def review(existing_arguments):
         return result  # Host validation and authorization still precede execution.
 ```
 
-Generated `Input` objects are distinct from canonical wire events. They flatten only protocol-owned wrappers, never application arguments, and `to_wire()` performs the shared mapping. `path` and `origin` remain separate required facts. Optional host IDs, timestamps, parent IDs, and other facts are retained; `event_id=` overrides an input ID. The SDK supplies type/source and the configured session manifest. Low-level `dispatch` still accepts canonical dictionaries.
+Generated `Input` objects are distinct from canonical wire events. They flatten only protocol-owned wrappers, never application arguments, and `to_wire()` performs the shared mapping. `path` and `origin` remain separate required facts. Optional host IDs, timestamps, parent IDs, and other facts are retained; `event_id=` overrides an input ID. The SDK supplies type/source and the configured session manifest. Low-level `dispatch` accepts canonical dictionaries.
 
 Capability builders are immutable: reusing a base declaration does not widen it. `intercept()` deliberately advertises **both intercept and observe**; `observe()` is observation-only. `modify_input(replace=True)` supplies both the effect grant and operation block. Empty operations and observation effect grants are rejected; boundary compatibility is validated before delivery. Form and URL elicitation grants are explicit (`elicitation_form()` / `elicitation_url()`). Raw manifests retain their exact modes; omission never implies permission. Per-call `capabilities=` only narrows configured grants.
 
@@ -269,7 +269,7 @@ Runnable, statically checked consumer programs live in [`examples/`](examples):
 - `typed_tool.py`: JSON registration, generated tool input, typed grants, initial state, real in-process ASGI handler, borrowed HTTP client, and explicit application decoding.
 - `common_cases.py`: rewrite/allow, deny, invalid application shape, host policy, occurrence narrowing, native initial state, and fail-open/fail-closed reports. The host operation is an in-memory execution recorder, not a shell.
 - `stdio_tool.py` / `stdio_backend.py`: a real owned backend process using the same public Handler, denial, and child cleanup.
-- `upload.py`: streamed binary upload, metadata no-read behavior, independent upload credentials, verified descriptor, and caller-owned immutable storage.
+- `upload.py`: streamed binary upload, metadata no-read behavior, independent upload credentials, verified upload receipt, and caller-owned immutable storage.
 
 - `lifecycle.py`: caller-owned task groups, operation-owned observations, interrupted requests, idempotent close, and proof that an owned subprocess was reaped.
 - `http_auth.py`: real loopback HTTP, canonical backend callbacks, registration `tokenEnv` resolution, and separate content-upload authorization. Its standard-library HTTP routing is example host code, not a production server.
@@ -313,7 +313,7 @@ The default `auth.EnvironmentAuthProvider` resolves bearer `tokenEnv` or optiona
 
 ## Static host manifest
 
-Configure `Hooks(config, *, source, manifest=full_manifest, transport=None, auth_provider=None)` with a complete canonical static manifest, **or** use the existing `capabilities=event_declarations` option. These options are mutually exclusive. The full manifest supplies the same event/mode/effect authority used for admission; it is not backend discovery. `hooks.manifest` returns a detached snapshot.
+Configure `Hooks(config, *, source, manifest=full_manifest, transport=None, auth_provider=None)` with a complete canonical static manifest, **or** use `capabilities=event_declarations`. These options are mutually exclusive. The full manifest supplies the same event/mode/effect authority used for admission; it is not backend discovery. `hooks.manifest` returns a detached snapshot.
 
 The event-map shorthand advertises only explicitly declared events and modes. Its derived manifest records a gap for every omitted canonical event and for host-level facilities that the map cannot establish (transports, authentication, tool paths, content categories, limits, and managed policy). Empty lists do not mean universal support. Use a full manifest to declare those facilities accurately; explicit full manifests are preserved rather than augmented with assumed support.
 
@@ -329,7 +329,7 @@ The attachment receiver verifies byte length and digest through EOF before commi
 
 ## Body-bound boundaries
 
-Use `ContentContext` for MCP elicitation and compaction bodies. Its asynchronous `resolve(reference)` and `upload(bytes)` functions are trusted storage/transport adapters, not application-schema callbacks. `upload` must return a verified receiver-allocated immutable descriptor after storage commit. The SDK verifies referenced bytes and replacement descriptors before publishing an accepted state.
+Use `ContentContext` for MCP elicitation and compaction bodies. Its asynchronous `resolve(reference)` and `upload(bytes)` functions are trusted storage/transport adapters, not application-schema callbacks. `upload` must return a verified `ContentUploadReceipt` (`ref`, `size`, `sha256`) after storage commit. The SDK checks receipt length and digest against the actual uploaded bytes. `resolve` receives only `{ "ref": ... }` and must resolve immutable bytes within its authorized storage scope; event metadata is not an integrity authority. The SDK detects changes to previously resolved bytes.
 
 Bindings are explicit paths within the canonical event:
 
@@ -346,11 +346,11 @@ Pass `content=context` to the named boundary. An elicitation result needs the or
 
 `OwnedContentSource(stream, max_bytes=..., timeout=...)` wraps an async native `read(size)`/`receive(size)` stream with `aclose()`. Construction does not read. Size/hash expectations are optional and verified, not trusted. Generated inputs expose named `bind_<slot>_source(source)` methods; repeated content slots additionally require `index=`. For example, `input.bind_items_source(source, index=0)` binds an existing metadata item without putting the stream into wire JSON.
 
-Pass the bound input to a named hook method with `uploads={backend_id: authorized_upload_callback}`. Each callback receives immutable bytes and returns a receiver-allocated canonical content reference; it can use `auth.AuthenticatedHTTPTransport.upload(..., authentication=upload_binding)`. Metadata, omit, and unmatched receivers consume no bytes and require no uploader. Selected body delivery snapshots once within limits, hashes actual raw bytes, uploads independently for each authorized destination, and verifies references before event delivery. Missing receiver authorization fails before reading. Source bindings derive from shared generated metadata; advanced `ContentSources` and existing canonical references/resolvers remain available.
+Pass the bound input to a named hook method with `uploads={backend_id: authorized_upload_callback}`. Each callback receives immutable bytes and returns a receiver-allocated canonical upload receipt; it can use `auth.AuthenticatedHTTPTransport.upload(..., authentication=upload_binding)`. Metadata, omit, and unmatched receivers consume no bytes and require no uploader. Selected body delivery snapshots once within limits, hashes actual raw bytes, uploads independently for each authorized destination, and verifies receipts before event delivery. Missing receiver authorization fails before reading. Use `ContentSources` to supply explicit source bindings, or `ContentContext` to resolve canonical references.
 
-Ownership transfers to the source wrapper, then to the hook operation when passed. Streams close on success, failure, cancellation, and unused selection; snapshots release when the call finishes. Sources are single-operation values, not concurrently reusable. Call `aclose()` or use an async context manager for a source that never reaches a hook call. Cleanup is shielded and bounded separately from the operation budget.
+Ownership transfers to the source wrapper, then to the hook operation when passed. Streams close on success, failure, cancellation, and unused selection; snapshots release when the call finishes. Closed wrappers also release their reader, so retaining a source or result does not retain the reader’s input buffer. Sources are single-operation values, not concurrently reusable. Call `aclose()` or use an async context manager for a source that never reaches a hook call. Cleanup is shielded and bounded separately from the operation budget.
 
-For custom transport integrations, `begin(canonical_request)` returns a `PendingInvocation` with separate acquisition, cancellation, and acceptance. `exchange(canonical_request)` uses the same settlement engine. Content-aware pending invocations use `await accept_content()`; this keeps upload completion and cancellation inside the publication boundary. The ordinary named-method path does this automatically.
+For custom transport integrations, `begin(canonical_request)` returns a `PendingInvocation` with separate acquisition, cancellation, and acceptance. `exchange(canonical_request)` uses the same settlement engine. Content-aware pending invocations use `await accept_content()`; this keeps upload completion and cancellation inside the publication boundary. The ordinary named-method path does this automatically. Pending invocations retain selected bytes only until acceptance, cancellation, acquisition/finalization failure, or harness close. Failed finalization may be retried and resolves fresh bytes. Harness tracking is weak: dropping a pending invocation does not keep its prepared payload alive. Terminal handles also detach their resolver/uploader context, so retained handles do not retain the caller’s backing store. Returned references continue to resolve in caller-owned storage; cleanup never clears that persistent store.
 
 ## Generated models and provenance
 
@@ -368,3 +368,134 @@ uv run python -m build
 ```
 
 Integration tests also use a matching sibling `../agent-hooks-protocol` checkout for shared fixtures and public synthetic certificates. The installed runtime uses its bundled schemas and does not need that checkout. No SDK API executes host tools on your behalf.
+
+### Typed composed payloads
+
+Generated facade constructors retain nested model types through schema
+compositions. MCP connection `gaps` parameters accept lists of typed gap models,
+and HTTP, SSE, stdio, and custom connection objects expose typed location and gap
+attributes. `ModelVisibleItem` has composed content constructors with typed roles.
+
+Facade objects are mappings with read-only attributes.
+Optional attributes return `None` when absent; mapping membership still records
+presence. Attributes conflicting with mapping methods use a trailing underscore
+(such as `items_`), so `dict.items()` keeps working. Wire parsers return lossless mappings, not hydrated facade instances.
+
+Use generated nested models for typed constructor arguments. Wire constructors, dictionary decoding, and runtime parsing
+check location/evidence alternatives and other structural schema constraints. Application
+JSON, native payloads, and extension values remain intentionally dynamic.
+
+Upload receipts and event references are distinct. To attach a successful upload,
+use `content.reference(receipt)` (or `{"ref": receipt["ref"]}`). Never attach the
+receipt itself: body-selected content carries only the ref, with no outer `size`
+or `sha256`. Metadata-only content and body gaps may still disclose size/digest.
+
+### Structural model decoding and effect-family support
+
+```python
+from agenthooksprotocol import ContentReference, capability, effect
+
+caps = capability.Capabilities.from_dict({"effects": ["deny", "vendor.custom"]})
+assert caps.supports(capability.EffectName.DENY)
+assert caps.supports("vendor.custom")
+assert effect.EffectName is capability.EffectName
+reference = ContentReference.from_dict({"ref": "opaque", "vendor": {"version": 2}})
+```
+
+`supports(effect)` is available on generic and incoming capability models. It
+checks the advertised `effects` list only. Nested grants do not imply family
+support. The result is **not authorization**: it does not check target, operation,
+mode, contextual restrictions, or permission. `EffectName` contains schema-derived
+known identifiers; custom family identifiers remain ordinary strings.
+
+Wire-model keyword constructors and `Model.from_dict(mapping)` validate with
+the same structural descriptor engine as generated `parse_*` functions. The
+original composition is retained, including required members, explicit nulls,
+literals, closed enums, forbidden combinations, and union ambiguity. This is the
+SDK's structural contract, not complete contextual protocol validation.
+`from_dict` does not supply omitted wire literals or defaults. It validates once
+and privately hydrates nested typed models without recursively calling public
+constructors. For example, a decoded HTTP connection supports
+`connection.gaps[0].reason`, just like a constructed connection. Union selection
+reuses memoized descriptor checks from that decode; subtrees are not repeatedly
+validated during hydration. Extension/application values remain ordinary JSON
+values. Descriptors and hydration metadata are cached.
+
+Invalid wire models raise `ValueError`; validation failures carry `result`,
+`diagnostics`, and `raw` attributes. Use `parse_*` when you need the full result on
+both success and failure, including unknown-variant warnings and lossless raw
+values. Open extension values remain intact. Finite `Decimal` values are retained;
+non-finite numbers and non-JSON values are rejected. Parsing raw JSON through
+`parse_*` retains decimal precision; decoding it first with standard-library
+`json.loads` cannot recover precision already lost to a float.
+
+Provide valid enum/literal values and all required wire members to `from_dict`. A null candidate, a candidate with
+`{"value": null}`, and a candidate with `{"value": 0}` remain distinct; omitting a
+required candidate is an error. Generated input projections and capability grant
+builders are construction helpers, not wire decode entrypoints; their final wire
+objects are validated at the dispatch/parse boundary. Direct dictionary
+mutation, standard-library `json.loads`, TypedDict annotations, and type assertions
+are not SDK validation entrypoints. Re-parse after manually mutating a mapping.
+
+Wire constructors also privately hydrate nested mappings: for example,
+`capability.Capabilities(effects=["modify"], modify={}).modify.input` returns
+`None`, not an attribute error. Already typed child models retain their identity;
+plain nested mappings become typed models after the constructor's single cached
+validation pass. Family queries include all generated per-occurrence capability
+models, such as `capability.ToolBeforeCapabilities`.
+
+Constructor aliases cannot silently overwrite wire keys. Supplying both
+`tool_name=` and `toolName=` raises `TypeError`, even if the values agree. For
+optional/defaulted fields, a lone wire spelling (for example `addressForm=` or
+`protocolVersion=`) is used and validated rather than replaced by a default.
+Required constructor parameters use their documented Python spelling;
+use `from_dict` to decode complete wire-keyed objects. In `from_dict`, distinct
+keys such as `toolName` and `tool_name` remain distinct wire/extension keys.
+
+### Owned attachments
+
+The owned attachment APIs in this section are not included in the published 0.1.1 package.
+
+Use `Attachment.from_bytes(data)` for immutable Python `bytes`, or
+`Attachment.lazy(async_loader, aclose=async_cleanup)` to defer reading. Bind it
+with the typed input's `bind_*_source` method on an item without a body reference.
+Content IDs, media types, and other metadata belong on the content item. See the
+runnable [file attachment example](examples/file_attachment.py).
+
+Dispatch transfers ownership once. Metadata-only and unmatched deliveries do not
+invoke the loader. Selected body deliveries share one immutable snapshot, with
+receiver-specific references. Successful results own the bytes **or still-unread
+loader**, independent of `Hooks` shutdown. Use `async with result:` or
+`await result.aclose()` and read with
+`await result.attachments.read("context.compact.before.items[0]")`. Cleanup runs
+for unopened sources too. Do not reuse an attachment across invocations; create a
+new attachment (which can share the same immutable `bytes`) instead.
+
+The default accepted size is 4 MiB and lazy loading timeout is 30 seconds;
+constructors accept `max_bytes` and lazy construction accepts `timeout`. Loaders
+must bound their own allocations. `Attachment(async_stream, ...)` also supports
+the bounded `read(size)`/`receive(max_bytes)` source contract. Stream cleanup
+is shielded and bounded to one second. Cancellation and failure never retry a
+loader. Python mutable buffers are rejected, and reads
+return immutable bytes.
+
+Remote body delivery requires an authorized receiver uploader through
+`uploads={backend_id: async_upload}`. The uploader supplies a reference that the
+receiver can read.
+Metadata-only delivery and result reads require no uploader.
+
+Attachments own their immutable bytes directly. A lazy loader's `bytes` object
+becomes the attachment snapshot; upload and result reads borrow that same object.
+Receiver applications manage upload storage.
+
+Compaction text and elicitation JSON effects read selected attachment
+owners. An accepted replacement creates a new effective attachment; subsequent
+deliveries and the result use that owner. Original attachment size bounds also
+apply to replacements. Generated candidates are available through
+`await result.attachments.read("candidate")`. Binary/file editing is not supported.
+Elicitation results require their original request correlation context;
+`ContentContext.attachments` can provide the original request owner without a
+resolver. A resolver is an optional
+adapter for externally supplied references.
+
+Results are invocation-local, not session archives.

{agenthooksprotocol-0.1.0 → agenthooksprotocol-0.2.0}/README.md

@@ -4,10 +4,10 @@ A typed, asynchronous SDK for the [Agent Hooks Protocol](https://github.com/agen
 
 ## Install
 
-The distribution name is `agenthooksprotocol`. Until the first PyPI release, install a pinned Git commit:
+Install the published `agenthooksprotocol` package from [PyPI](https://pypi.org/project/agenthooksprotocol/):
 
 ```sh
-python -m pip install 'agenthooksprotocol[http] @ git+https://github.com/agenthooksprotocol/python-sdk.git@<commit-sha>'
+python -m pip install 'agenthooksprotocol[http]'
 ```
 
 HTTPX is an opt-in dependency (`[http]`). Pydantic is an independent opt-in integration (`[pydantic]`); neither a web framework nor Pydantic is needed for the core SDK or stdio.
@@ -36,7 +36,7 @@ async def review(existing_arguments):
         return result  # Host validation and authorization still precede execution.
 ```
 
-Generated `Input` objects are distinct from canonical wire events. They flatten only protocol-owned wrappers, never application arguments, and `to_wire()` performs the shared mapping. `path` and `origin` remain separate required facts. Optional host IDs, timestamps, parent IDs, and other facts are retained; `event_id=` overrides an input ID. The SDK supplies type/source and the configured session manifest. Low-level `dispatch` still accepts canonical dictionaries.
+Generated `Input` objects are distinct from canonical wire events. They flatten only protocol-owned wrappers, never application arguments, and `to_wire()` performs the shared mapping. `path` and `origin` remain separate required facts. Optional host IDs, timestamps, parent IDs, and other facts are retained; `event_id=` overrides an input ID. The SDK supplies type/source and the configured session manifest. Low-level `dispatch` accepts canonical dictionaries.
 
 Capability builders are immutable: reusing a base declaration does not widen it. `intercept()` deliberately advertises **both intercept and observe**; `observe()` is observation-only. `modify_input(replace=True)` supplies both the effect grant and operation block. Empty operations and observation effect grants are rejected; boundary compatibility is validated before delivery. Form and URL elicitation grants are explicit (`elicitation_form()` / `elicitation_url()`). Raw manifests retain their exact modes; omission never implies permission. Per-call `capabilities=` only narrows configured grants.
 
@@ -45,7 +45,7 @@ Runnable, statically checked consumer programs live in [`examples/`](examples):
 - `typed_tool.py`: JSON registration, generated tool input, typed grants, initial state, real in-process ASGI handler, borrowed HTTP client, and explicit application decoding.
 - `common_cases.py`: rewrite/allow, deny, invalid application shape, host policy, occurrence narrowing, native initial state, and fail-open/fail-closed reports. The host operation is an in-memory execution recorder, not a shell.
 - `stdio_tool.py` / `stdio_backend.py`: a real owned backend process using the same public Handler, denial, and child cleanup.
-- `upload.py`: streamed binary upload, metadata no-read behavior, independent upload credentials, verified descriptor, and caller-owned immutable storage.
+- `upload.py`: streamed binary upload, metadata no-read behavior, independent upload credentials, verified upload receipt, and caller-owned immutable storage.
 
 - `lifecycle.py`: caller-owned task groups, operation-owned observations, interrupted requests, idempotent close, and proof that an owned subprocess was reaped.
 - `http_auth.py`: real loopback HTTP, canonical backend callbacks, registration `tokenEnv` resolution, and separate content-upload authorization. Its standard-library HTTP routing is example host code, not a production server.
@@ -89,7 +89,7 @@ The default `auth.EnvironmentAuthProvider` resolves bearer `tokenEnv` or optiona
 
 ## Static host manifest
 
-Configure `Hooks(config, *, source, manifest=full_manifest, transport=None, auth_provider=None)` with a complete canonical static manifest, **or** use the existing `capabilities=event_declarations` option. These options are mutually exclusive. The full manifest supplies the same event/mode/effect authority used for admission; it is not backend discovery. `hooks.manifest` returns a detached snapshot.
+Configure `Hooks(config, *, source, manifest=full_manifest, transport=None, auth_provider=None)` with a complete canonical static manifest, **or** use `capabilities=event_declarations`. These options are mutually exclusive. The full manifest supplies the same event/mode/effect authority used for admission; it is not backend discovery. `hooks.manifest` returns a detached snapshot.
 
 The event-map shorthand advertises only explicitly declared events and modes. Its derived manifest records a gap for every omitted canonical event and for host-level facilities that the map cannot establish (transports, authentication, tool paths, content categories, limits, and managed policy). Empty lists do not mean universal support. Use a full manifest to declare those facilities accurately; explicit full manifests are preserved rather than augmented with assumed support.
 
@@ -105,7 +105,7 @@ The attachment receiver verifies byte length and digest through EOF before commi
 
 ## Body-bound boundaries
 
-Use `ContentContext` for MCP elicitation and compaction bodies. Its asynchronous `resolve(reference)` and `upload(bytes)` functions are trusted storage/transport adapters, not application-schema callbacks. `upload` must return a verified receiver-allocated immutable descriptor after storage commit. The SDK verifies referenced bytes and replacement descriptors before publishing an accepted state.
+Use `ContentContext` for MCP elicitation and compaction bodies. Its asynchronous `resolve(reference)` and `upload(bytes)` functions are trusted storage/transport adapters, not application-schema callbacks. `upload` must return a verified `ContentUploadReceipt` (`ref`, `size`, `sha256`) after storage commit. The SDK checks receipt length and digest against the actual uploaded bytes. `resolve` receives only `{ "ref": ... }` and must resolve immutable bytes within its authorized storage scope; event metadata is not an integrity authority. The SDK detects changes to previously resolved bytes.
 
 Bindings are explicit paths within the canonical event:
 
@@ -122,11 +122,11 @@ Pass `content=context` to the named boundary. An elicitation result needs the or
 
 `OwnedContentSource(stream, max_bytes=..., timeout=...)` wraps an async native `read(size)`/`receive(size)` stream with `aclose()`. Construction does not read. Size/hash expectations are optional and verified, not trusted. Generated inputs expose named `bind_<slot>_source(source)` methods; repeated content slots additionally require `index=`. For example, `input.bind_items_source(source, index=0)` binds an existing metadata item without putting the stream into wire JSON.
 
-Pass the bound input to a named hook method with `uploads={backend_id: authorized_upload_callback}`. Each callback receives immutable bytes and returns a receiver-allocated canonical content reference; it can use `auth.AuthenticatedHTTPTransport.upload(..., authentication=upload_binding)`. Metadata, omit, and unmatched receivers consume no bytes and require no uploader. Selected body delivery snapshots once within limits, hashes actual raw bytes, uploads independently for each authorized destination, and verifies references before event delivery. Missing receiver authorization fails before reading. Source bindings derive from shared generated metadata; advanced `ContentSources` and existing canonical references/resolvers remain available.
+Pass the bound input to a named hook method with `uploads={backend_id: authorized_upload_callback}`. Each callback receives immutable bytes and returns a receiver-allocated canonical upload receipt; it can use `auth.AuthenticatedHTTPTransport.upload(..., authentication=upload_binding)`. Metadata, omit, and unmatched receivers consume no bytes and require no uploader. Selected body delivery snapshots once within limits, hashes actual raw bytes, uploads independently for each authorized destination, and verifies receipts before event delivery. Missing receiver authorization fails before reading. Use `ContentSources` to supply explicit source bindings, or `ContentContext` to resolve canonical references.
 
-Ownership transfers to the source wrapper, then to the hook operation when passed. Streams close on success, failure, cancellation, and unused selection; snapshots release when the call finishes. Sources are single-operation values, not concurrently reusable. Call `aclose()` or use an async context manager for a source that never reaches a hook call. Cleanup is shielded and bounded separately from the operation budget.
+Ownership transfers to the source wrapper, then to the hook operation when passed. Streams close on success, failure, cancellation, and unused selection; snapshots release when the call finishes. Closed wrappers also release their reader, so retaining a source or result does not retain the reader’s input buffer. Sources are single-operation values, not concurrently reusable. Call `aclose()` or use an async context manager for a source that never reaches a hook call. Cleanup is shielded and bounded separately from the operation budget.
 
-For custom transport integrations, `begin(canonical_request)` returns a `PendingInvocation` with separate acquisition, cancellation, and acceptance. `exchange(canonical_request)` uses the same settlement engine. Content-aware pending invocations use `await accept_content()`; this keeps upload completion and cancellation inside the publication boundary. The ordinary named-method path does this automatically.
+For custom transport integrations, `begin(canonical_request)` returns a `PendingInvocation` with separate acquisition, cancellation, and acceptance. `exchange(canonical_request)` uses the same settlement engine. Content-aware pending invocations use `await accept_content()`; this keeps upload completion and cancellation inside the publication boundary. The ordinary named-method path does this automatically. Pending invocations retain selected bytes only until acceptance, cancellation, acquisition/finalization failure, or harness close. Failed finalization may be retried and resolves fresh bytes. Harness tracking is weak: dropping a pending invocation does not keep its prepared payload alive. Terminal handles also detach their resolver/uploader context, so retained handles do not retain the caller’s backing store. Returned references continue to resolve in caller-owned storage; cleanup never clears that persistent store.
 
 ## Generated models and provenance
 
@@ -144,3 +144,134 @@ uv run python -m build
 ```
 
 Integration tests also use a matching sibling `../agent-hooks-protocol` checkout for shared fixtures and public synthetic certificates. The installed runtime uses its bundled schemas and does not need that checkout. No SDK API executes host tools on your behalf.
+
+### Typed composed payloads
+
+Generated facade constructors retain nested model types through schema
+compositions. MCP connection `gaps` parameters accept lists of typed gap models,
+and HTTP, SSE, stdio, and custom connection objects expose typed location and gap
+attributes. `ModelVisibleItem` has composed content constructors with typed roles.
+
+Facade objects are mappings with read-only attributes.
+Optional attributes return `None` when absent; mapping membership still records
+presence. Attributes conflicting with mapping methods use a trailing underscore
+(such as `items_`), so `dict.items()` keeps working. Wire parsers return lossless mappings, not hydrated facade instances.
+
+Use generated nested models for typed constructor arguments. Wire constructors, dictionary decoding, and runtime parsing
+check location/evidence alternatives and other structural schema constraints. Application
+JSON, native payloads, and extension values remain intentionally dynamic.
+
+Upload receipts and event references are distinct. To attach a successful upload,
+use `content.reference(receipt)` (or `{"ref": receipt["ref"]}`). Never attach the
+receipt itself: body-selected content carries only the ref, with no outer `size`
+or `sha256`. Metadata-only content and body gaps may still disclose size/digest.
+
+### Structural model decoding and effect-family support
+
+```python
+from agenthooksprotocol import ContentReference, capability, effect
+
+caps = capability.Capabilities.from_dict({"effects": ["deny", "vendor.custom"]})
+assert caps.supports(capability.EffectName.DENY)
+assert caps.supports("vendor.custom")
+assert effect.EffectName is capability.EffectName
+reference = ContentReference.from_dict({"ref": "opaque", "vendor": {"version": 2}})
+```
+
+`supports(effect)` is available on generic and incoming capability models. It
+checks the advertised `effects` list only. Nested grants do not imply family
+support. The result is **not authorization**: it does not check target, operation,
+mode, contextual restrictions, or permission. `EffectName` contains schema-derived
+known identifiers; custom family identifiers remain ordinary strings.
+
+Wire-model keyword constructors and `Model.from_dict(mapping)` validate with
+the same structural descriptor engine as generated `parse_*` functions. The
+original composition is retained, including required members, explicit nulls,
+literals, closed enums, forbidden combinations, and union ambiguity. This is the
+SDK's structural contract, not complete contextual protocol validation.
+`from_dict` does not supply omitted wire literals or defaults. It validates once
+and privately hydrates nested typed models without recursively calling public
+constructors. For example, a decoded HTTP connection supports
+`connection.gaps[0].reason`, just like a constructed connection. Union selection
+reuses memoized descriptor checks from that decode; subtrees are not repeatedly
+validated during hydration. Extension/application values remain ordinary JSON
+values. Descriptors and hydration metadata are cached.
+
+Invalid wire models raise `ValueError`; validation failures carry `result`,
+`diagnostics`, and `raw` attributes. Use `parse_*` when you need the full result on
+both success and failure, including unknown-variant warnings and lossless raw
+values. Open extension values remain intact. Finite `Decimal` values are retained;
+non-finite numbers and non-JSON values are rejected. Parsing raw JSON through
+`parse_*` retains decimal precision; decoding it first with standard-library
+`json.loads` cannot recover precision already lost to a float.
+
+Provide valid enum/literal values and all required wire members to `from_dict`. A null candidate, a candidate with
+`{"value": null}`, and a candidate with `{"value": 0}` remain distinct; omitting a
+required candidate is an error. Generated input projections and capability grant
+builders are construction helpers, not wire decode entrypoints; their final wire
+objects are validated at the dispatch/parse boundary. Direct dictionary
+mutation, standard-library `json.loads`, TypedDict annotations, and type assertions
+are not SDK validation entrypoints. Re-parse after manually mutating a mapping.
+
+Wire constructors also privately hydrate nested mappings: for example,
+`capability.Capabilities(effects=["modify"], modify={}).modify.input` returns
+`None`, not an attribute error. Already typed child models retain their identity;
+plain nested mappings become typed models after the constructor's single cached
+validation pass. Family queries include all generated per-occurrence capability
+models, such as `capability.ToolBeforeCapabilities`.
+
+Constructor aliases cannot silently overwrite wire keys. Supplying both
+`tool_name=` and `toolName=` raises `TypeError`, even if the values agree. For
+optional/defaulted fields, a lone wire spelling (for example `addressForm=` or
+`protocolVersion=`) is used and validated rather than replaced by a default.
+Required constructor parameters use their documented Python spelling;
+use `from_dict` to decode complete wire-keyed objects. In `from_dict`, distinct
+keys such as `toolName` and `tool_name` remain distinct wire/extension keys.
+
+### Owned attachments
+
+The owned attachment APIs in this section are not included in the published 0.1.1 package.
+
+Use `Attachment.from_bytes(data)` for immutable Python `bytes`, or
+`Attachment.lazy(async_loader, aclose=async_cleanup)` to defer reading. Bind it
+with the typed input's `bind_*_source` method on an item without a body reference.
+Content IDs, media types, and other metadata belong on the content item. See the
+runnable [file attachment example](examples/file_attachment.py).
+
+Dispatch transfers ownership once. Metadata-only and unmatched deliveries do not
+invoke the loader. Selected body deliveries share one immutable snapshot, with
+receiver-specific references. Successful results own the bytes **or still-unread
+loader**, independent of `Hooks` shutdown. Use `async with result:` or
+`await result.aclose()` and read with
+`await result.attachments.read("context.compact.before.items[0]")`. Cleanup runs
+for unopened sources too. Do not reuse an attachment across invocations; create a
+new attachment (which can share the same immutable `bytes`) instead.
+
+The default accepted size is 4 MiB and lazy loading timeout is 30 seconds;
+constructors accept `max_bytes` and lazy construction accepts `timeout`. Loaders
+must bound their own allocations. `Attachment(async_stream, ...)` also supports
+the bounded `read(size)`/`receive(max_bytes)` source contract. Stream cleanup
+is shielded and bounded to one second. Cancellation and failure never retry a
+loader. Python mutable buffers are rejected, and reads
+return immutable bytes.
+
+Remote body delivery requires an authorized receiver uploader through
+`uploads={backend_id: async_upload}`. The uploader supplies a reference that the
+receiver can read.
+Metadata-only delivery and result reads require no uploader.
+
+Attachments own their immutable bytes directly. A lazy loader's `bytes` object
+becomes the attachment snapshot; upload and result reads borrow that same object.
+Receiver applications manage upload storage.
+
+Compaction text and elicitation JSON effects read selected attachment
+owners. An accepted replacement creates a new effective attachment; subsequent
+deliveries and the result use that owner. Original attachment size bounds also
+apply to replacements. Generated candidates are available through
+`await result.attachments.read("candidate")`. Binary/file editing is not supported.
+Elicitation results require their original request correlation context;
+`ContentContext.attachments` can provide the original request owner without a
+resolver. A resolver is an optional
+adapter for externally supplied references.
+
+Results are invocation-local, not session archives.

{agenthooksprotocol-0.1.0 → agenthooksprotocol-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agenthooksprotocol"
-version = "0.1.0"
+version = "0.2.0"
 description = "Official non-normative Python SDK for the Agent Hooks Protocol"
 readme = "README.md"
 requires-python = ">=3.11"

{agenthooksprotocol-0.1.0 → agenthooksprotocol-0.2.0}/src/agenthooksprotocol/__init__.py

@@ -15,6 +15,10 @@ from . import (
     tool,
     transport,
 )
+from .attachment import (
+    Attachment as Attachment,
+    AttachmentContents as AttachmentContents,
+)
 from ._content import ContentContext as ContentContext
 from ._models import *  # noqa: F403
 from ._models import __all__ as _model_names
@@ -36,6 +40,8 @@ from .runtime import (
 )
 
 __all__ = list(_model_names) + [
+    "Attachment",
+    "AttachmentContents",
     "ContentContext",
     "OwnedContentSource",
     "ContentSources",