agenthooksprotocol 0.7.1__tar.gz → 0.9.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {agenthooksprotocol-0.7.1/src/agenthooksprotocol.egg-info → agenthooksprotocol-0.9.0}/PKG-INFO +19 -2
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/README.md +18 -1
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/pyproject.toml +1 -1
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_hooks.py +63 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/__init__.py +43 -4
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/ahp-codegen.lock.json +4 -4
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/auth.py +44 -11
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/generated.py +19 -2
- agenthooksprotocol-0.9.0/src/agenthooksprotocol/headers.py +129 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/schemas.json +50 -2
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0/src/agenthooksprotocol.egg-info}/PKG-INFO +19 -2
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/SOURCES.txt +2 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_event_types.py +1 -0
- agenthooksprotocol-0.9.0/tests/test_registration_headers.py +527 -0
- agenthooksprotocol-0.9.0/tests/test_subscribes.py +177 -0
- agenthooksprotocol-0.7.1/tests/test_subscribes.py +0 -76
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/LICENSE +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/setup.cfg +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/__init__.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_boundaries.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_content.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_diagnostics.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_elicitation.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_grants.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_host_metadata.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_interop_content.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_interop_hooks.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/capability.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/content.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/effect.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/event.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/registration.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/subscription.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/tool.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_models/transport.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_outcomes.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/_validator.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/attachment.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/candidate.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/capability.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/catalogue.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/codec.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/compaction.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/content.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/contract.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/diagnostics.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/effect.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/elicitation.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/event.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/integrations/__init__.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/integrations/pydantic.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/interop.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lifecycle.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lifecycle_client.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lifecycle_server.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/lineage.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/observation_chain.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/path.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/permission.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/py.typed +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/registration.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/response.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/runtime.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/__init__.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_admission.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_framing.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_handlers.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_json.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/_slots.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/asgi.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/attachments.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/hooks.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/server/stdio.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/state.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/subscription.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/tool.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transport.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transports/__init__.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transports/http.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/transports/stdio.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol/wire.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/dependency_links.txt +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/requires.txt +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/src/agenthooksprotocol.egg-info/top_level.txt +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_attachments.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_catalogue.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_codec.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_compaction.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_compaction_wire.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_consumer_outcomes.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_content.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_content_lifetime.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_content_receipts.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_correlated_core.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_declared_contracts.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_elicitation_adapter.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_fixture_public.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_handwritten_surface.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_harness_identity.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_host_metadata.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_inline_messages.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_integration.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_integration_edges.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_interop.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_lifecycle.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_lifecycle_auth.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_observation.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_observation_chain_transport.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_owned_content.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_owned_content_hooks.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_package.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_public_content.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_public_contract_surface.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_public_examples.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_public_hooks.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_public_server.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_registration_auth.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_safety.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_schema_corrections.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_sdk_unification.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_server_catch_all.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_server_error_codes.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_session_manifest.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_shared_materialization.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_stdio_env.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_stdio_transport.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_structural_facade.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_typed_capabilities.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_typed_contract_regressions.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_upload_planning.py +0 -0
- {agenthooksprotocol-0.7.1 → agenthooksprotocol-0.9.0}/tests/test_validator_optimization.py +0 -0
{agenthooksprotocol-0.7.1/src/agenthooksprotocol.egg-info → agenthooksprotocol-0.9.0}/PKG-INFO
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: agenthooksprotocol
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.9.0
|
|
4
4
|
Summary: Official non-normative Python SDK for the Agent Hooks Protocol
|
|
5
5
|
Author: Agent Hooks Protocol maintainers
|
|
6
6
|
License:
|
|
@@ -269,7 +269,7 @@ async def review(existing_arguments):
|
|
|
269
269
|
return result # Host validation and authorization still precede execution.
|
|
270
270
|
```
|
|
271
271
|
|
|
272
|
-
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, the configured harness identity, and the configured session manifest. Full canonical wire events must include a matching `harness` identity. Low-level `dispatch` accepts canonical dictionaries and an `event_name: EventType`. `from agenthooksprotocol.event import EventType` exposes the catalogue-derived literal type shared by `dispatch`, `subscribes`, and contextual response parsing. Canonical name literals are accepted directly; static checking rejects dynamic strings, unknown names, and selectors in these event-name positions. Registration selectors remain separate and support their documented wildcard matching.
|
|
272
|
+
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, the configured harness identity, and the configured session manifest. Full canonical wire events must include a matching `harness` identity. Low-level `dispatch` accepts canonical dictionaries and an `event_name: EventType`. `from agenthooksprotocol.event import EventType` exposes the catalogue-derived literal type shared by `dispatch`, `subscribes`, `intercepts`, and contextual response parsing. Canonical name literals are accepted directly; static checking rejects dynamic strings, unknown names, and selectors in these event-name positions. Registration selectors remain separate and support their documented wildcard matching.
|
|
273
273
|
|
|
274
274
|
Host capabilities are frozen, keyword-only dataclasses; there are no builder functions. Each event has its own `<Event>Capabilities` declaration. Events that support interception take `intercept=<Event>Intercept(...)` grants, and every declaration takes `observe`, which defaults to `False`, so to advertise both modes you must pass `observe=True` explicitly. Observation-only events such as `SessionEndCapabilities(observe=True)` accept only the flag. `modify_input=capability.Modify.REPLACE` supplies both the effect grant and its operation block, and form/URL elicitation grants are explicit (`elicitation=capability.Elicitation.FORM`, `URL`, or `FORM_AND_URL`). Interception without a control grant and declarations with neither mode are rejected at construction; boundary compatibility is validated before delivery. Omission never implies permission. Per-call `capabilities=` only narrows configured grants.
|
|
275
275
|
|
|
@@ -343,12 +343,29 @@ The same remaining budget covers queue/readiness waits, provider waits, selected
|
|
|
343
343
|
|
|
344
344
|
The default `auth.EnvironmentAuthProvider` resolves bearer `tokenEnv` or optional `resolve_credential` tokenRef callbacks at delivery time. OAuth bindings require an explicit provider. Missing configured secrets and unsupported mechanisms fail closed. Anonymous success stays anonymous; an explicit provider can authorize challenge discovery under host trust policy. Interception may replay at most once after an eligible 401 Bearer challenge, retaining request identity and serialized body; observations/uploads are never automatically replayed. Upload bindings are independent: event credentials are never an upload fallback. Transport-owned TLS/workload integration is not replaced by this provider.
|
|
345
345
|
|
|
346
|
+
HTTP registrations accept `transport.headers`, for example:
|
|
347
|
+
|
|
348
|
+
```json
|
|
349
|
+
{"type":"http","url":"https://policy.example/hooks","headers":{"X-Tenant":"engineering","X-Api-Key":{"valueEnv":"POLICY_API_KEY"},"X-Gateway":{"valueRef":"vault/policy"}}}
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
All valid HTTP field names are supported, including `Authorization`, `Cookie`, `Origin`, and protocol headers. Literal API keys and cookies are supported. Values must be safe HTTP field values (no CR, LF, or NUL); this HTTPX transport supports Latin-1 header bytes, including non-ASCII values such as `café`. There is no additional SDK header-size limit. Duplicate names are compared case-insensitively: the last property in configuration iteration order wins.
|
|
353
|
+
|
|
354
|
+
Transport defaults and authentication are applied first, then configured registration headers override them case-insensitively, including `Content-Type` and `Authorization`. Configured `Authorization`, whether literal or referenced, suppresses provider acquisition, discovery, challenges, and retries. A failed explicit secret lookup fails delivery; it never falls back to OAuth.
|
|
355
|
+
|
|
356
|
+
`valueEnv` and `valueRef` reuse the bearer secret lookup helper and `Hooks(..., resolve_credential=callback)` callback. The optional contextual `header_resolver.resolve(context)` API remains available for harnesses needing backend, destination, purpose, cancellation, and deadline context. Values resolve once per event or upload operation, are reused on an allowed authentication retry, and rotate on subsequent operations. Errors redact values and references.
|
|
357
|
+
|
|
358
|
+
Configured headers apply to both event POSTs and backend content uploads, overriding upload defaults and authentication as well. They are not installed globally on borrowed clients, discovery/token requests, or other backends. Existing transport redirect behavior is unchanged (SDK HTTP transports already disable automatic redirects). Custom injected transports retain responsibility for their transport contract.
|
|
359
|
+
|
|
360
|
+
|
|
346
361
|
Registered stdio backends start with a minimal base environment rather than the full host environment. The base is an allowlist of host variables: `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `LANG`, `LC_*`, `TZ`, `TMPDIR`, `TEMP` and `TMP`, plus `SYSTEMROOT`, `WINDIR`, `COMSPEC`, `PATHEXT`, `USERPROFILE`, `APPDATA`, `LOCALAPPDATA` and `PROGRAMDATA` on Windows, where names match case-insensitively. The registration's `transport.env` entries are applied on top as literal strings, with no interpolation, and override base values. `tokenEnv` is still resolved in the host environment and credentials are never copied into the child. Env values are never logged. `Hooks(..., inherit_environment=True)` is an SDK-level opt-out that starts from the full host environment instead. `transports.StdioTransport(..., env=..., inherit_environment=...)` exposes the same controls.
|
|
347
362
|
|
|
348
363
|
## Static host manifest
|
|
349
364
|
|
|
350
365
|
`hooks.subscribes("tool.before")` is a pure synchronous static-interest lookup. Use it before expensive input preparation: `False` means no eligible intercept or observe subscription selects the configured event. Exact selectors, `*`, and prefix selectors such as `tool.*` use the same matching as dispatch. Unknown or unconfigured events return `False`. Payload filters are conservatively ignored, so `True` means potential interest, not permission or guaranteed delivery. The lookup does not prepare input, authenticate, upload content, initialize transports, or contact backends.
|
|
351
366
|
|
|
367
|
+
`hooks.intercepts("model.response.after")` is `subscribes` restricted to intercept subscriptions. Use it to decide whether to withhold streamed output until interceptors settle.
|
|
368
|
+
|
|
352
369
|
Configure `Hooks(config, *, source, harness=event.Harness(name="example", version="1"), capabilities=capability.HostCapabilities(...), manifest_metadata=HostManifestMetadata(...))`. The required `source`, `harness`, and `capabilities` configure one host. Harness name and version identify the emitter on every event; SDK-generated events use a detached snapshot of that identity. Typed host capabilities are the sole source of event modes and effect grants. Optional metadata declares transport/authentication facilities, tool paths, content categories, limits, managed policy, gaps, correlation fields, and opaque extras without granting event authority. Metadata cannot contain events or override known fields through extras. `hooks.manifest` returns a detached canonical snapshot.
|
|
353
370
|
|
|
354
371
|
The frozen, keyword-only host capability model advertises only explicitly declared events and modes. Each event has its own declaration type: `ToolBeforeCapabilities(intercept=..., observe=True)` accepts typed interception options and an observation flag, while observation-only events such as `SessionEndCapabilities(observe=True)` accept only the flag. Empty declarations, empty interception, and invalid option values are rejected at construction, while an empty `HostCapabilities()` grants nothing and elicitation-only interception is a valid facility declaration. `Modify.REPLACE`, `Modify.MERGE`, and `Modify.REPLACE_AND_MERGE` declare complete modification grants. `HostCapabilities.to_wire()` returns fresh canonical declarations directly; it does not parse JSON. Runtime admission still validates registration, request-time grants, and responses. The derived manifest records gaps for omitted events and host-level facilities not supplied through metadata. Explicit empty metadata collections declare no such facility; they do not mean universal support.
|
|
@@ -45,7 +45,7 @@ async def review(existing_arguments):
|
|
|
45
45
|
return result # Host validation and authorization still precede execution.
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
-
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, the configured harness identity, and the configured session manifest. Full canonical wire events must include a matching `harness` identity. Low-level `dispatch` accepts canonical dictionaries and an `event_name: EventType`. `from agenthooksprotocol.event import EventType` exposes the catalogue-derived literal type shared by `dispatch`, `subscribes`, and contextual response parsing. Canonical name literals are accepted directly; static checking rejects dynamic strings, unknown names, and selectors in these event-name positions. Registration selectors remain separate and support their documented wildcard matching.
|
|
48
|
+
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, the configured harness identity, and the configured session manifest. Full canonical wire events must include a matching `harness` identity. Low-level `dispatch` accepts canonical dictionaries and an `event_name: EventType`. `from agenthooksprotocol.event import EventType` exposes the catalogue-derived literal type shared by `dispatch`, `subscribes`, `intercepts`, and contextual response parsing. Canonical name literals are accepted directly; static checking rejects dynamic strings, unknown names, and selectors in these event-name positions. Registration selectors remain separate and support their documented wildcard matching.
|
|
49
49
|
|
|
50
50
|
Host capabilities are frozen, keyword-only dataclasses; there are no builder functions. Each event has its own `<Event>Capabilities` declaration. Events that support interception take `intercept=<Event>Intercept(...)` grants, and every declaration takes `observe`, which defaults to `False`, so to advertise both modes you must pass `observe=True` explicitly. Observation-only events such as `SessionEndCapabilities(observe=True)` accept only the flag. `modify_input=capability.Modify.REPLACE` supplies both the effect grant and its operation block, and form/URL elicitation grants are explicit (`elicitation=capability.Elicitation.FORM`, `URL`, or `FORM_AND_URL`). Interception without a control grant and declarations with neither mode are rejected at construction; boundary compatibility is validated before delivery. Omission never implies permission. Per-call `capabilities=` only narrows configured grants.
|
|
51
51
|
|
|
@@ -119,12 +119,29 @@ The same remaining budget covers queue/readiness waits, provider waits, selected
|
|
|
119
119
|
|
|
120
120
|
The default `auth.EnvironmentAuthProvider` resolves bearer `tokenEnv` or optional `resolve_credential` tokenRef callbacks at delivery time. OAuth bindings require an explicit provider. Missing configured secrets and unsupported mechanisms fail closed. Anonymous success stays anonymous; an explicit provider can authorize challenge discovery under host trust policy. Interception may replay at most once after an eligible 401 Bearer challenge, retaining request identity and serialized body; observations/uploads are never automatically replayed. Upload bindings are independent: event credentials are never an upload fallback. Transport-owned TLS/workload integration is not replaced by this provider.
|
|
121
121
|
|
|
122
|
+
HTTP registrations accept `transport.headers`, for example:
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{"type":"http","url":"https://policy.example/hooks","headers":{"X-Tenant":"engineering","X-Api-Key":{"valueEnv":"POLICY_API_KEY"},"X-Gateway":{"valueRef":"vault/policy"}}}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
All valid HTTP field names are supported, including `Authorization`, `Cookie`, `Origin`, and protocol headers. Literal API keys and cookies are supported. Values must be safe HTTP field values (no CR, LF, or NUL); this HTTPX transport supports Latin-1 header bytes, including non-ASCII values such as `café`. There is no additional SDK header-size limit. Duplicate names are compared case-insensitively: the last property in configuration iteration order wins.
|
|
129
|
+
|
|
130
|
+
Transport defaults and authentication are applied first, then configured registration headers override them case-insensitively, including `Content-Type` and `Authorization`. Configured `Authorization`, whether literal or referenced, suppresses provider acquisition, discovery, challenges, and retries. A failed explicit secret lookup fails delivery; it never falls back to OAuth.
|
|
131
|
+
|
|
132
|
+
`valueEnv` and `valueRef` reuse the bearer secret lookup helper and `Hooks(..., resolve_credential=callback)` callback. The optional contextual `header_resolver.resolve(context)` API remains available for harnesses needing backend, destination, purpose, cancellation, and deadline context. Values resolve once per event or upload operation, are reused on an allowed authentication retry, and rotate on subsequent operations. Errors redact values and references.
|
|
133
|
+
|
|
134
|
+
Configured headers apply to both event POSTs and backend content uploads, overriding upload defaults and authentication as well. They are not installed globally on borrowed clients, discovery/token requests, or other backends. Existing transport redirect behavior is unchanged (SDK HTTP transports already disable automatic redirects). Custom injected transports retain responsibility for their transport contract.
|
|
135
|
+
|
|
136
|
+
|
|
122
137
|
Registered stdio backends start with a minimal base environment rather than the full host environment. The base is an allowlist of host variables: `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `LANG`, `LC_*`, `TZ`, `TMPDIR`, `TEMP` and `TMP`, plus `SYSTEMROOT`, `WINDIR`, `COMSPEC`, `PATHEXT`, `USERPROFILE`, `APPDATA`, `LOCALAPPDATA` and `PROGRAMDATA` on Windows, where names match case-insensitively. The registration's `transport.env` entries are applied on top as literal strings, with no interpolation, and override base values. `tokenEnv` is still resolved in the host environment and credentials are never copied into the child. Env values are never logged. `Hooks(..., inherit_environment=True)` is an SDK-level opt-out that starts from the full host environment instead. `transports.StdioTransport(..., env=..., inherit_environment=...)` exposes the same controls.
|
|
123
138
|
|
|
124
139
|
## Static host manifest
|
|
125
140
|
|
|
126
141
|
`hooks.subscribes("tool.before")` is a pure synchronous static-interest lookup. Use it before expensive input preparation: `False` means no eligible intercept or observe subscription selects the configured event. Exact selectors, `*`, and prefix selectors such as `tool.*` use the same matching as dispatch. Unknown or unconfigured events return `False`. Payload filters are conservatively ignored, so `True` means potential interest, not permission or guaranteed delivery. The lookup does not prepare input, authenticate, upload content, initialize transports, or contact backends.
|
|
127
142
|
|
|
143
|
+
`hooks.intercepts("model.response.after")` is `subscribes` restricted to intercept subscriptions. Use it to decide whether to withhold streamed output until interceptors settle.
|
|
144
|
+
|
|
128
145
|
Configure `Hooks(config, *, source, harness=event.Harness(name="example", version="1"), capabilities=capability.HostCapabilities(...), manifest_metadata=HostManifestMetadata(...))`. The required `source`, `harness`, and `capabilities` configure one host. Harness name and version identify the emitter on every event; SDK-generated events use a detached snapshot of that identity. Typed host capabilities are the sole source of event modes and effect grants. Optional metadata declares transport/authentication facilities, tool paths, content categories, limits, managed policy, gaps, correlation fields, and opaque extras without granting event authority. Metadata cannot contain events or override known fields through extras. `hooks.manifest` returns a detached canonical snapshot.
|
|
129
146
|
|
|
130
147
|
The frozen, keyword-only host capability model advertises only explicitly declared events and modes. Each event has its own declaration type: `ToolBeforeCapabilities(intercept=..., observe=True)` accepts typed interception options and an observation flag, while observation-only events such as `SessionEndCapabilities(observe=True)` accept only the flag. Empty declarations, empty interception, and invalid option values are rejected at construction, while an empty `HostCapabilities()` grants nothing and elicitation-only interception is a valid facility declaration. `Modify.REPLACE`, `Modify.MERGE`, and `Modify.REPLACE_AND_MERGE` declare complete modification grants. `HostCapabilities.to_wire()` returns fresh canonical declarations directly; it does not parse JSON. Runtime admission still validates registration, request-time grants, and responses. The derived manifest records gaps for omitted events and host-level facilities not supplied through metadata. Explicit empty metadata collections declare no such facility; they do not mean universal support.
|
|
@@ -654,6 +654,7 @@ class Hooks(BoundaryMixin):
|
|
|
654
654
|
transport: Any = None,
|
|
655
655
|
resolve_credential: Any = None,
|
|
656
656
|
auth_provider: Any = None,
|
|
657
|
+
header_resolver: Any = None,
|
|
657
658
|
max_concurrent_uploads: int = 8,
|
|
658
659
|
inherit_environment: bool = False,
|
|
659
660
|
) -> None:
|
|
@@ -672,6 +673,7 @@ class Hooks(BoundaryMixin):
|
|
|
672
673
|
transport=transport,
|
|
673
674
|
resolve_credential=resolve_credential,
|
|
674
675
|
auth_provider=auth_provider,
|
|
676
|
+
header_resolver=header_resolver,
|
|
675
677
|
max_concurrent_uploads=max_concurrent_uploads,
|
|
676
678
|
inherit_environment=inherit_environment,
|
|
677
679
|
)
|
|
@@ -687,6 +689,7 @@ class Hooks(BoundaryMixin):
|
|
|
687
689
|
transport: Any = None,
|
|
688
690
|
resolve_credential: Any = None,
|
|
689
691
|
auth_provider: Any = None,
|
|
692
|
+
header_resolver: Any = None,
|
|
690
693
|
max_concurrent_uploads: int = 8,
|
|
691
694
|
inherit_environment: bool = False,
|
|
692
695
|
) -> None:
|
|
@@ -703,6 +706,17 @@ class Hooks(BoundaryMixin):
|
|
|
703
706
|
self._upload_limiter = anyio.Semaphore(max_concurrent_uploads)
|
|
704
707
|
self.validator = Validator()
|
|
705
708
|
self._lineage = TaskLineage(self.validator)
|
|
709
|
+
from .headers import validate_headers
|
|
710
|
+
|
|
711
|
+
registered_backends = config.get("hooks", []) if isinstance(config, dict) else []
|
|
712
|
+
for backend in registered_backends if isinstance(registered_backends, list) else []:
|
|
713
|
+
transport_config = (
|
|
714
|
+
backend.get("transport", {}) if isinstance(backend, dict) else {}
|
|
715
|
+
)
|
|
716
|
+
if isinstance(transport_config, dict) and transport_config.get("type") == "http":
|
|
717
|
+
validate_headers(transport_config.get("headers", {}))
|
|
718
|
+
self._header_resolver = header_resolver
|
|
719
|
+
self._resolve_credential = resolve_credential
|
|
706
720
|
self.validator.validate("registration", config)
|
|
707
721
|
if (
|
|
708
722
|
not isinstance(source, str)
|
|
@@ -781,6 +795,21 @@ class Hooks(BoundaryMixin):
|
|
|
781
795
|
for subscription in backend["subscriptions"]
|
|
782
796
|
)
|
|
783
797
|
|
|
798
|
+
def intercepts(self, event: EventType) -> bool:
|
|
799
|
+
"""Report whether any intercept subscription the host granted selects the event.
|
|
800
|
+
|
|
801
|
+
Payload-dependent filters are not evaluated.
|
|
802
|
+
"""
|
|
803
|
+
declaration = self.capabilities.get(event)
|
|
804
|
+
if declaration is None or "intercept" not in declaration["modes"]:
|
|
805
|
+
return False
|
|
806
|
+
return any(
|
|
807
|
+
subscription["mode"] == "intercept"
|
|
808
|
+
and any(_matches(selector, event) for selector in subscription["events"])
|
|
809
|
+
for backend in self.config["hooks"]
|
|
810
|
+
for subscription in backend["subscriptions"]
|
|
811
|
+
)
|
|
812
|
+
|
|
784
813
|
@property
|
|
785
814
|
def manifest(self) -> dict[str, Any]:
|
|
786
815
|
"""Return a detached snapshot of the configured static host manifest."""
|
|
@@ -863,6 +892,38 @@ class Hooks(BoundaryMixin):
|
|
|
863
892
|
if isinstance(self._injected, dict)
|
|
864
893
|
else self._injected
|
|
865
894
|
)
|
|
895
|
+
from .transports.http import HTTPTransport
|
|
896
|
+
|
|
897
|
+
config = backend["transport"]
|
|
898
|
+
if (
|
|
899
|
+
config["type"] == "http"
|
|
900
|
+
and config.get("headers")
|
|
901
|
+
and isinstance(transport, HTTPTransport)
|
|
902
|
+
):
|
|
903
|
+
from .auth import AuthenticatedHTTPTransport
|
|
904
|
+
|
|
905
|
+
# Keep borrowed client lifetime and programmatic metadata,
|
|
906
|
+
# but do not bypass the registration's endpoint scope.
|
|
907
|
+
if transport.url != config["url"]:
|
|
908
|
+
raise ProtocolError("HTTP registration endpoint mismatch")
|
|
909
|
+
transport = AuthenticatedHTTPTransport(
|
|
910
|
+
config["url"],
|
|
911
|
+
backend=backend,
|
|
912
|
+
resolve_credential=(
|
|
913
|
+
self._resolve_credential
|
|
914
|
+
if self._resolve_credential is not None
|
|
915
|
+
else getattr(transport, "resolve_credential", None)
|
|
916
|
+
),
|
|
917
|
+
client=transport._ready(),
|
|
918
|
+
headers=transport.headers,
|
|
919
|
+
auth_provider=getattr(
|
|
920
|
+
transport, "auth_provider", self._auth_provider
|
|
921
|
+
),
|
|
922
|
+
header_resolver=self._header_resolver or getattr(
|
|
923
|
+
transport, "header_resolver", None
|
|
924
|
+
),
|
|
925
|
+
validator=self.validator,
|
|
926
|
+
)
|
|
866
927
|
else:
|
|
867
928
|
config = backend["transport"]
|
|
868
929
|
if config["type"] == "stdio":
|
|
@@ -882,7 +943,9 @@ class Hooks(BoundaryMixin):
|
|
|
882
943
|
transport = AuthenticatedHTTPTransport(
|
|
883
944
|
config["url"],
|
|
884
945
|
backend=backend,
|
|
946
|
+
resolve_credential=self._resolve_credential,
|
|
885
947
|
auth_provider=self._auth_provider,
|
|
948
|
+
header_resolver=self._header_resolver,
|
|
886
949
|
validator=self.validator,
|
|
887
950
|
)
|
|
888
951
|
self._owned.append(transport)
|