agenthooksprotocol 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agenthooksprotocol
-Version: 0.2.0
+Version: 0.4.0
 Summary: Official non-normative Python SDK for the Agent Hooks Protocol
 Author: Agent Hooks Protocol maintainers
 License: 
@@ -266,6 +266,7 @@ Capability builders are immutable: reusing a base declaration does not widen it.
 
 Runnable, statically checked consumer programs live in [`examples/`](examples):
 
+- `value_codecs.py`: independent argument/result/provenance codecs, admission-time invariants, and a form schema derived from its answer type.
 - `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.
@@ -282,9 +283,15 @@ Generated constructors build JSON-shaped protocol values. Generated `TypedDict`
 
 Capabilities explicitly grant effects and target operations. Supply event capabilities at harness construction; a per-occurrence capability override can narrow them, never widen them. `initial_state` carries the host's native prior decision for one occurrence. A hook-supplied result is a candidate, not an assertion that an operation executed. The host owns its ordinary input validation and actual execution.
 
+Supply `input_codec=`, `result_codec=`, and optional `provenance_codec=` to a named hook method or `dispatch` to declare caller types. Complete staged values are decoded and validated before publication. Object merge is shallow: omitted fields remain unchanged, literal null is retained, and nested values replace whole values. An invalid response publishes none of its effects; earlier accepted responses remain visible to later interceptors. A codec must preserve the wire data it receives, including opaque extra fields. Lossy serialization rejects admission rather than dropping fields.
+
+`result.decoded_input` exposes the declared argument value. `result.decoded_candidate` is an application `Candidate[Result, Provenance]`, or `None` when there is no candidate. Its value can itself be `None`; optional provenance is omitted from `candidate.to_dict()` when absent. Raw `input` and `candidate` views remain detached snapshots. For explicitly selected opaque host slots, use `event_codecs={("params",): codec}` with event-relative paths. Unspecified native, provider, task, permission, and discovery values are not interpreted.
+
+For forms, construct `PydanticFormContract(TypeAdapter(Answer))` from one answer declaration. `request(message)` derives the restricted MCP schema; `result_codec()` decodes the complete MCP result and its accepted answer while preserving opaque result metadata. Unsupported shapes and schema constraints are rejected during construction. Decline, cancel, and URL results have no form content. See [`examples/value_codecs.py`](examples/value_codecs.py).
+
 After settlement, explicitly decode effective input with `result.decode_input(codec)`. A codec implements `encode(value)` and `decode(json_value)`; `IdentityCodec` copies JSON. The optional `integrations.pydantic.PydanticCodec` accepts a Pydantic `TypeAdapter`. A decoding error does not retroactively reject protocol effects: retain the settled result, raw effective input, accepted responses, and diagnostics, and report host-level rejection without executing.
 
-`result.permission` is the generated `Permission` enum (`NONE`, `ALLOW`, `ASK`, `DENY`) read from canonical settlement, not an independent decision engine. `NONE` is not approval; `ASK` needs host approval; interruption never authorizes execution. `result.input` is detached accepted JSON, not a claim that backend modifications satisfy an application's original type. `decode_input(codec)` remains an explicit, post-settlement host check. Candidate, canonical event, accepted responses, and diagnostics remain accessible.
+`result.permission` is the generated `Permission` enum (`NONE`, `ALLOW`, `ASK`, `DENY`) read from canonical settlement, not an independent decision engine. `NONE` is not approval; `ASK` needs host approval; interruption never authorizes execution. `result.input` is detached accepted JSON. Declared codecs validate accepted modifications; without a declared codec, the host supplies application validation. `decode_input(codec)` remains an explicit, post-settlement host check. Candidate, canonical event, accepted responses, and diagnostics remain accessible.
 
 `state.initial(Permission.ALLOW)` represents a native decision **already made for this exact occurrence**, not an authorization shortcut. Its default candidate is absent (`null`); `state.Candidate(value=None)` instead means a supplied JSON-null result. Optional typed provenance records facts, not authenticated identity or execution proof. Canonical modifications still invalidate candidates/approval as specified.
 
@@ -327,36 +334,69 @@ Observation is one-way. It does not acquire effect authority and never waits for
 
 The attachment receiver verifies byte length and digest through EOF before committing caller-provided immutable storage. Receiver-allocated references are published only after authorization and successful storage commit. Applications choose storage durability and retention.
 
-## 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 `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:
-
-| Boundary | Binding |
-| --- | --- |
-| `user_elicitation_request` | `{"request": ("elicitation", "request")}` |
-| `user_elicitation_result` | `{"content": ("elicitation", "result")}` plus `original_request` |
-| `context_compact_before` | `{"instructions": ("instructions",)}` |
-| `context_compact_after` | `{"summary": ("summary",)}` |
-
-Pass `content=context` to the named boundary. An elicitation result needs the original canonical request snapshot; the SDK does not fabricate correlation, form/URL support, or MCP defaults. Metadata and omitted selections do not read body bytes. Changed bodies receive new immutable references, and a changed compaction input invalidates an earlier supplied summary.
-
-### Lazy owned sources
-
-`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.
+## Inline messages and specialized boundaries
 
-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.
+Model-visible inputs contain canonical messages with a `role` and ordered
+`parts`. Supported roles are `system`, `developer`, `user`, `assistant`, and
+`tool`. A text part has `kind="text"`, `mediaType="text/plain"`, and inline
+`text`. Serialized JSON is ordinary text. An attachment part has
+`kind="attachment"`, a non-text/non-JSON media type, and an immutable binary
+body. Construction supplies missing message/part IDs and marks them
+`synthesized=True`; explicit IDs remain stable.
 
-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.
+```python
+from agenthooksprotocol import Attachment
+
+input = {
+    "trigger": "manual",
+    "items": [{"role": "user", "parts": [
+        {"kind": "text", "text": "Review this report."},
+        {"kind": "attachment", "mediaType": "application/pdf",
+         "body": Attachment.from_bytes(pdf_bytes)},
+    ]}],
+}
+result = await hooks.context_compact_before(input, uploads=authorized_uploads)
+async with result:
+    data = await result.attachments.read("context.compact.before.items_parts[0][1]")
+```
 
-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.
+Named hook methods also accept canonical dictionaries with the same direct
+attachment bodies. The runtime collects sources and creates receiver-specific
+references internally. Construction and metadata/omit projection do not read
+or upload attachments. Only schema-owned slots are projected; native payloads,
+extensions, and application arguments are opaque. Selection is a ceiling for
+each receiver's view: metadata/omit views contain no inline text or attachment
+references. Independent receivers apply their own content selections.
+
+Compaction `instructions` and `summary` are canonical text-part lists.
+Replacement substitutes the list; merge appends in order. Model-visible message
+list targets (`prompt`, `request`, `response`, and tool `output`) have the same
+list operations. Tool output edits operate on `tool.after.items`; application
+structures are serialized as text parts. Standalone `content` edits require the
+boundary context: `user.message.outbound` uses a message list, and accepted form
+answers at `user.elicitation.result` use an MCP answer object. Object targets such as tool input and workspace changes use shallow object merge. A response settles
+atomically, and each serial receiver sees the committed state. Changed
+compaction instructions invalidate an earlier supplied summary.
+
+MCP elicitation `request` and `result` contain selected text parts whose `text`
+is the serialized complete MCP JSON payload. The SDK validates parsed payloads,
+mode grants, form answers, and correlation without inserting defaults. Result
+edits require `original_request=` with the original canonical intercept request
+snapshot; answer-object merge is shallow. Elicitation request bodies are immutable
+to modification effects. No text/JSON upload callback is needed. Metadata and omit selections
+cannot authorize body-dependent effects.
+
+For custom transports, `begin(canonical_request, value_codecs=ValueCodecs(...))` separates acquisition,
+cancellation, and acceptance; `exchange(canonical_request)` uses the same
+settlement engine. Elicitation correlation can be supplied through
+`ContentContext(original_request=..., bindings={"content": ("elicitation", "result")},
+principal=authenticated_identity)` and `await pending.accept_content()`.
 
 ## Generated models and provenance
 
 Semantic namespaces (`event`, `tool`, `effect`, `capability`, and registration models) and all named event boundaries come from schema metadata, not a selected handwritten helper list. Constructors may supply fixed protocol literals; parsers never repair missing input. Open fields are retained for forward-compatible JSON round trips.
 
-The low-level `generated` module exports the full schema's typed models, `parse_<root>` / `encode_<root>` codecs, `PROTOCOL_VERSION`, `SCHEMA_REVISION`, and JSON types. `ahp-codegen.lock.json` records immutable generator provenance. Change canonical schemas and generator source in the protocol repository rather than editing generated files.
+The `wire` namespace exposes canonical JSON-shaped request, notification, effect, and response types with structural codecs. Server callbacks use these raw wire contracts. The low-level `generated` module exports the full schema's typed models, `parse_<root>` / `encode_<root>` codecs, `PROTOCOL_VERSION`, `SCHEMA_REVISION`, and JSON types. `ahp-codegen.lock.json` records immutable generator provenance. Change canonical schemas and generator source in the protocol repository rather than editing generated files.
 
 ## Development
 
@@ -374,12 +414,12 @@ Integration tests also use a matching sibling `../agent-hooks-protocol` checkout
 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.
+attributes. `ModelVisibleItem` is a canonical message with a typed role and ordered parts.
 
 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.
+presence. Omitted and explicit-empty response effects are both neutral; decoded effects provide an empty list without modifying the source wire object. Attributes conflicting with mapping methods use a trailing underscore
+(such as `items_`), so `dict.items()` keeps working. Raw wire parsers return lossless mappings. `response.response_for_request(event_type, raw)` returns the generated contextual response selected by the originating event type, not by payload shape.
 
 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
@@ -413,13 +453,7 @@ 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.
+`from_dict` checks complete wire values and preserves optional-field presence. Decoded known nested values expose the same attributes as constructed values, such as `connection.gaps[0].reason`. Extension and application bags remain intact and do not acquire effect or attachment authority.
 
 Invalid wire models raise `ValueError`; validation failures carry `result`,
 `diagnostics`, and `raw` attributes. Use `parse_*` when you need the full result on
@@ -437,12 +471,7 @@ 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`.
+Nested model attributes expose declared protocol fields. For example, `capability.Capabilities(effects=["modify"], modify={}).modify.input` is `None` when that grant is absent. Family queries are available on generic and per-occurrence capability models.
 
 Constructor aliases cannot silently overwrite wire keys. Supplying both
 `tool_name=` and `toolName=` raises `TypeError`, even if the values agree. For
@@ -454,48 +483,65 @@ 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.
-
+`Attachment.lazy(async_loader, aclose=async_cleanup)` to defer reading. Put
+`attachment` directly in an attachment part's `body`. Named `Hooks` methods
+accept both dictionary inputs and typed event inputs with the same owner.
+For a custom `OwnedContentSource`, use the host-only `content.OwnedAttachment(source)` wrapper in an attachment part's body. This wrapper does not read the source and is not a wire value. The SDK transfers and closes its source under the same invocation ownership rules.
+
+Metadata belongs on the part. See the runnable
+[file attachment example](examples/file_attachment.py).
+
+Dispatch transfers ownership once. Successful results retain the exact owner,
+including an unread loader, independently of `Hooks` shutdown. Callers close
+returned content owners with `async with result:` or `await result.aclose()`.
+Cleanup runs for unopened sources too. Create a new attachment for each
+invocation; eager attachments can share the same immutable `bytes` object.
+
+The default accepted size is 4 MiB and lazy loading timeout is 30 seconds.
+Constructors accept `max_bytes`; lazy construction accepts `timeout`. Loaders
+must bound their own allocations. `Attachment(async_stream, ...)` supports
+bounded `read(size)`/`receive(max_bytes)` streams. Stream cleanup is shielded and
+bounded to one second. Cancellation and failure never retry a loader. Mutable
+buffers are rejected, and reads return immutable bytes.
+
+Selected remote binary delivery requires an authorized uploader through
+`uploads={backend_id: async_upload}`. Each uploader receives the exact owner's
+immutable bytes and returns a committed receipt with `ref`, `size`, and `sha256`.
+The SDK validates the receipt against the actual bytes before sending the event.
+Upload callbacks remain caller-authorized and scoped to their backend; event
+credentials do not authorize uploads to another destination.
+
+`Hooks(..., max_concurrent_uploads=8)` bounds concurrent binary uploads.
+The value must be a positive integer. Before serial interception
+begins, the SDK prepares uploads for body-selected attachment slots in all
+matched subscriptions, including observers. One attachment owner is read once
+for multiple subscribers. Metadata, omit, and unmatched selections do not read
+or upload its bytes. Result reads and metadata-only delivery require no uploader.
+
+Only confirmed receipts are reused, for the exact attachment owner and backend
+ID/subscription index. An uncalled interceptor receives a settled observation
+with its confirmed reference after denial or stop. Upload failures are handled by
+the affected subscription's failure policy when its delivery is reached; they
+do not prevent independent destinations from preparing their uploads. An upload
+can commit even if an earlier interceptor later removes the attachment or halts
+the chain. Receiver applications manage separate storage durability and retention.
+Cancellation cancels and joins pending upload work and closes invocation-owned
+sources. Overlapping reads join one materialization and receive the same immutable
+bytes or terminal error. Cancelling one reader leaves materialization active for
+other readers; the last cancelled reader or owner closure cancels and joins it.
+The attachment owns its single pending materialization independently of readers.
+A cancelled reader returns and releases its upload permit while another reader
+continues. The last reader or owner closure joins cleanup; completed workers are
+not retained.
+
+Attachments are the sole byte owners. Binary/file editing is not supported.
 Results are invocation-local, not session archives.
+
+### Advanced validation and dispatch
+
+`runtime.Validator` validates bundled canonical schemas and structural codecs. It does not establish request correlation, effect grants, host approval, or permission to execute. Use `Hooks` for complete interception admission.
+
+`server.hooks.Engine` is the framework-neutral backend dispatcher. Supply an explicit validator or static harness manifest when needed. Engine callbacks return protocol effects; the receiving harness validates authority and settles them atomically.
+
+Host session counters (`turns`, `modelRequests`, `toolCalls`, `inputTokens`, `outputTokens`, and extra counter names) are exact nonnegative integers. The SDK preserves supplied values and does not infer counters from events.

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

@@ -42,6 +42,7 @@ Capability builders are immutable: reusing a base declaration does not widen it.
 
 Runnable, statically checked consumer programs live in [`examples/`](examples):
 
+- `value_codecs.py`: independent argument/result/provenance codecs, admission-time invariants, and a form schema derived from its answer type.
 - `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.
@@ -58,9 +59,15 @@ Generated constructors build JSON-shaped protocol values. Generated `TypedDict`
 
 Capabilities explicitly grant effects and target operations. Supply event capabilities at harness construction; a per-occurrence capability override can narrow them, never widen them. `initial_state` carries the host's native prior decision for one occurrence. A hook-supplied result is a candidate, not an assertion that an operation executed. The host owns its ordinary input validation and actual execution.
 
+Supply `input_codec=`, `result_codec=`, and optional `provenance_codec=` to a named hook method or `dispatch` to declare caller types. Complete staged values are decoded and validated before publication. Object merge is shallow: omitted fields remain unchanged, literal null is retained, and nested values replace whole values. An invalid response publishes none of its effects; earlier accepted responses remain visible to later interceptors. A codec must preserve the wire data it receives, including opaque extra fields. Lossy serialization rejects admission rather than dropping fields.
+
+`result.decoded_input` exposes the declared argument value. `result.decoded_candidate` is an application `Candidate[Result, Provenance]`, or `None` when there is no candidate. Its value can itself be `None`; optional provenance is omitted from `candidate.to_dict()` when absent. Raw `input` and `candidate` views remain detached snapshots. For explicitly selected opaque host slots, use `event_codecs={("params",): codec}` with event-relative paths. Unspecified native, provider, task, permission, and discovery values are not interpreted.
+
+For forms, construct `PydanticFormContract(TypeAdapter(Answer))` from one answer declaration. `request(message)` derives the restricted MCP schema; `result_codec()` decodes the complete MCP result and its accepted answer while preserving opaque result metadata. Unsupported shapes and schema constraints are rejected during construction. Decline, cancel, and URL results have no form content. See [`examples/value_codecs.py`](examples/value_codecs.py).
+
 After settlement, explicitly decode effective input with `result.decode_input(codec)`. A codec implements `encode(value)` and `decode(json_value)`; `IdentityCodec` copies JSON. The optional `integrations.pydantic.PydanticCodec` accepts a Pydantic `TypeAdapter`. A decoding error does not retroactively reject protocol effects: retain the settled result, raw effective input, accepted responses, and diagnostics, and report host-level rejection without executing.
 
-`result.permission` is the generated `Permission` enum (`NONE`, `ALLOW`, `ASK`, `DENY`) read from canonical settlement, not an independent decision engine. `NONE` is not approval; `ASK` needs host approval; interruption never authorizes execution. `result.input` is detached accepted JSON, not a claim that backend modifications satisfy an application's original type. `decode_input(codec)` remains an explicit, post-settlement host check. Candidate, canonical event, accepted responses, and diagnostics remain accessible.
+`result.permission` is the generated `Permission` enum (`NONE`, `ALLOW`, `ASK`, `DENY`) read from canonical settlement, not an independent decision engine. `NONE` is not approval; `ASK` needs host approval; interruption never authorizes execution. `result.input` is detached accepted JSON. Declared codecs validate accepted modifications; without a declared codec, the host supplies application validation. `decode_input(codec)` remains an explicit, post-settlement host check. Candidate, canonical event, accepted responses, and diagnostics remain accessible.
 
 `state.initial(Permission.ALLOW)` represents a native decision **already made for this exact occurrence**, not an authorization shortcut. Its default candidate is absent (`null`); `state.Candidate(value=None)` instead means a supplied JSON-null result. Optional typed provenance records facts, not authenticated identity or execution proof. Canonical modifications still invalidate candidates/approval as specified.
 
@@ -103,36 +110,69 @@ Observation is one-way. It does not acquire effect authority and never waits for
 
 The attachment receiver verifies byte length and digest through EOF before committing caller-provided immutable storage. Receiver-allocated references are published only after authorization and successful storage commit. Applications choose storage durability and retention.
 
-## 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 `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:
-
-| Boundary | Binding |
-| --- | --- |
-| `user_elicitation_request` | `{"request": ("elicitation", "request")}` |
-| `user_elicitation_result` | `{"content": ("elicitation", "result")}` plus `original_request` |
-| `context_compact_before` | `{"instructions": ("instructions",)}` |
-| `context_compact_after` | `{"summary": ("summary",)}` |
-
-Pass `content=context` to the named boundary. An elicitation result needs the original canonical request snapshot; the SDK does not fabricate correlation, form/URL support, or MCP defaults. Metadata and omitted selections do not read body bytes. Changed bodies receive new immutable references, and a changed compaction input invalidates an earlier supplied summary.
-
-### Lazy owned sources
-
-`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.
+## Inline messages and specialized boundaries
 
-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.
+Model-visible inputs contain canonical messages with a `role` and ordered
+`parts`. Supported roles are `system`, `developer`, `user`, `assistant`, and
+`tool`. A text part has `kind="text"`, `mediaType="text/plain"`, and inline
+`text`. Serialized JSON is ordinary text. An attachment part has
+`kind="attachment"`, a non-text/non-JSON media type, and an immutable binary
+body. Construction supplies missing message/part IDs and marks them
+`synthesized=True`; explicit IDs remain stable.
 
-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.
+```python
+from agenthooksprotocol import Attachment
+
+input = {
+    "trigger": "manual",
+    "items": [{"role": "user", "parts": [
+        {"kind": "text", "text": "Review this report."},
+        {"kind": "attachment", "mediaType": "application/pdf",
+         "body": Attachment.from_bytes(pdf_bytes)},
+    ]}],
+}
+result = await hooks.context_compact_before(input, uploads=authorized_uploads)
+async with result:
+    data = await result.attachments.read("context.compact.before.items_parts[0][1]")
+```
 
-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.
+Named hook methods also accept canonical dictionaries with the same direct
+attachment bodies. The runtime collects sources and creates receiver-specific
+references internally. Construction and metadata/omit projection do not read
+or upload attachments. Only schema-owned slots are projected; native payloads,
+extensions, and application arguments are opaque. Selection is a ceiling for
+each receiver's view: metadata/omit views contain no inline text or attachment
+references. Independent receivers apply their own content selections.
+
+Compaction `instructions` and `summary` are canonical text-part lists.
+Replacement substitutes the list; merge appends in order. Model-visible message
+list targets (`prompt`, `request`, `response`, and tool `output`) have the same
+list operations. Tool output edits operate on `tool.after.items`; application
+structures are serialized as text parts. Standalone `content` edits require the
+boundary context: `user.message.outbound` uses a message list, and accepted form
+answers at `user.elicitation.result` use an MCP answer object. Object targets such as tool input and workspace changes use shallow object merge. A response settles
+atomically, and each serial receiver sees the committed state. Changed
+compaction instructions invalidate an earlier supplied summary.
+
+MCP elicitation `request` and `result` contain selected text parts whose `text`
+is the serialized complete MCP JSON payload. The SDK validates parsed payloads,
+mode grants, form answers, and correlation without inserting defaults. Result
+edits require `original_request=` with the original canonical intercept request
+snapshot; answer-object merge is shallow. Elicitation request bodies are immutable
+to modification effects. No text/JSON upload callback is needed. Metadata and omit selections
+cannot authorize body-dependent effects.
+
+For custom transports, `begin(canonical_request, value_codecs=ValueCodecs(...))` separates acquisition,
+cancellation, and acceptance; `exchange(canonical_request)` uses the same
+settlement engine. Elicitation correlation can be supplied through
+`ContentContext(original_request=..., bindings={"content": ("elicitation", "result")},
+principal=authenticated_identity)` and `await pending.accept_content()`.
 
 ## Generated models and provenance
 
 Semantic namespaces (`event`, `tool`, `effect`, `capability`, and registration models) and all named event boundaries come from schema metadata, not a selected handwritten helper list. Constructors may supply fixed protocol literals; parsers never repair missing input. Open fields are retained for forward-compatible JSON round trips.
 
-The low-level `generated` module exports the full schema's typed models, `parse_<root>` / `encode_<root>` codecs, `PROTOCOL_VERSION`, `SCHEMA_REVISION`, and JSON types. `ahp-codegen.lock.json` records immutable generator provenance. Change canonical schemas and generator source in the protocol repository rather than editing generated files.
+The `wire` namespace exposes canonical JSON-shaped request, notification, effect, and response types with structural codecs. Server callbacks use these raw wire contracts. The low-level `generated` module exports the full schema's typed models, `parse_<root>` / `encode_<root>` codecs, `PROTOCOL_VERSION`, `SCHEMA_REVISION`, and JSON types. `ahp-codegen.lock.json` records immutable generator provenance. Change canonical schemas and generator source in the protocol repository rather than editing generated files.
 
 ## Development
 
@@ -150,12 +190,12 @@ Integration tests also use a matching sibling `../agent-hooks-protocol` checkout
 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.
+attributes. `ModelVisibleItem` is a canonical message with a typed role and ordered parts.
 
 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.
+presence. Omitted and explicit-empty response effects are both neutral; decoded effects provide an empty list without modifying the source wire object. Attributes conflicting with mapping methods use a trailing underscore
+(such as `items_`), so `dict.items()` keeps working. Raw wire parsers return lossless mappings. `response.response_for_request(event_type, raw)` returns the generated contextual response selected by the originating event type, not by payload shape.
 
 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
@@ -189,13 +229,7 @@ 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.
+`from_dict` checks complete wire values and preserves optional-field presence. Decoded known nested values expose the same attributes as constructed values, such as `connection.gaps[0].reason`. Extension and application bags remain intact and do not acquire effect or attachment authority.
 
 Invalid wire models raise `ValueError`; validation failures carry `result`,
 `diagnostics`, and `raw` attributes. Use `parse_*` when you need the full result on
@@ -213,12 +247,7 @@ 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`.
+Nested model attributes expose declared protocol fields. For example, `capability.Capabilities(effects=["modify"], modify={}).modify.input` is `None` when that grant is absent. Family queries are available on generic and per-occurrence capability models.
 
 Constructor aliases cannot silently overwrite wire keys. Supplying both
 `tool_name=` and `toolName=` raises `TypeError`, even if the values agree. For
@@ -230,48 +259,65 @@ 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.
-
+`Attachment.lazy(async_loader, aclose=async_cleanup)` to defer reading. Put
+`attachment` directly in an attachment part's `body`. Named `Hooks` methods
+accept both dictionary inputs and typed event inputs with the same owner.
+For a custom `OwnedContentSource`, use the host-only `content.OwnedAttachment(source)` wrapper in an attachment part's body. This wrapper does not read the source and is not a wire value. The SDK transfers and closes its source under the same invocation ownership rules.
+
+Metadata belongs on the part. See the runnable
+[file attachment example](examples/file_attachment.py).
+
+Dispatch transfers ownership once. Successful results retain the exact owner,
+including an unread loader, independently of `Hooks` shutdown. Callers close
+returned content owners with `async with result:` or `await result.aclose()`.
+Cleanup runs for unopened sources too. Create a new attachment for each
+invocation; eager attachments can share the same immutable `bytes` object.
+
+The default accepted size is 4 MiB and lazy loading timeout is 30 seconds.
+Constructors accept `max_bytes`; lazy construction accepts `timeout`. Loaders
+must bound their own allocations. `Attachment(async_stream, ...)` supports
+bounded `read(size)`/`receive(max_bytes)` streams. Stream cleanup is shielded and
+bounded to one second. Cancellation and failure never retry a loader. Mutable
+buffers are rejected, and reads return immutable bytes.
+
+Selected remote binary delivery requires an authorized uploader through
+`uploads={backend_id: async_upload}`. Each uploader receives the exact owner's
+immutable bytes and returns a committed receipt with `ref`, `size`, and `sha256`.
+The SDK validates the receipt against the actual bytes before sending the event.
+Upload callbacks remain caller-authorized and scoped to their backend; event
+credentials do not authorize uploads to another destination.
+
+`Hooks(..., max_concurrent_uploads=8)` bounds concurrent binary uploads.
+The value must be a positive integer. Before serial interception
+begins, the SDK prepares uploads for body-selected attachment slots in all
+matched subscriptions, including observers. One attachment owner is read once
+for multiple subscribers. Metadata, omit, and unmatched selections do not read
+or upload its bytes. Result reads and metadata-only delivery require no uploader.
+
+Only confirmed receipts are reused, for the exact attachment owner and backend
+ID/subscription index. An uncalled interceptor receives a settled observation
+with its confirmed reference after denial or stop. Upload failures are handled by
+the affected subscription's failure policy when its delivery is reached; they
+do not prevent independent destinations from preparing their uploads. An upload
+can commit even if an earlier interceptor later removes the attachment or halts
+the chain. Receiver applications manage separate storage durability and retention.
+Cancellation cancels and joins pending upload work and closes invocation-owned
+sources. Overlapping reads join one materialization and receive the same immutable
+bytes or terminal error. Cancelling one reader leaves materialization active for
+other readers; the last cancelled reader or owner closure cancels and joins it.
+The attachment owns its single pending materialization independently of readers.
+A cancelled reader returns and releases its upload permit while another reader
+continues. The last reader or owner closure joins cleanup; completed workers are
+not retained.
+
+Attachments are the sole byte owners. Binary/file editing is not supported.
 Results are invocation-local, not session archives.
+
+### Advanced validation and dispatch
+
+`runtime.Validator` validates bundled canonical schemas and structural codecs. It does not establish request correlation, effect grants, host approval, or permission to execute. Use `Hooks` for complete interception admission.
+
+`server.hooks.Engine` is the framework-neutral backend dispatcher. Supply an explicit validator or static harness manifest when needed. Engine callbacks return protocol effects; the receiving harness validates authority and settles them atomically.
+
+Host session counters (`turns`, `modelRequests`, `toolCalls`, `inputTokens`, `outputTokens`, and extra counter names) are exact nonnegative integers. The SDK preserves supplied values and does not infer counters from events.

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

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