agenthooksprotocol 0.5.0__tar.gz → 0.6.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.5.0/src/agenthooksprotocol.egg-info → agenthooksprotocol-0.6.0}/PKG-INFO +23 -5
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/README.md +22 -4
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/pyproject.toml +1 -1
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_grants.py +250 -144
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_hooks.py +8 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/__init__.py +11 -3
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/ahp-codegen.lock.json +3 -3
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/capability.py +17 -1
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/catalogue.py +32 -22
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/generated.py +2 -1
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/schemas.json +7 -0
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/server/__init__.py +10 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/_handlers.py +46 -2
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/hooks.py +59 -11
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/stdio.py +2 -2
- agenthooksprotocol-0.6.0/src/agenthooksprotocol/transports/stdio.py +297 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0/src/agenthooksprotocol.egg-info}/PKG-INFO +23 -5
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/SOURCES.txt +4 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_owned_content_hooks.py +2 -2
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_public_hooks.py +3 -1
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_sdk_unification.py +3 -1
- agenthooksprotocol-0.6.0/tests/test_server_catch_all.py +101 -0
- agenthooksprotocol-0.6.0/tests/test_server_error_codes.py +171 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_session_manifest.py +3 -3
- agenthooksprotocol-0.6.0/tests/test_stdio_env.py +153 -0
- agenthooksprotocol-0.6.0/tests/test_stdio_transport.py +132 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_subscribes.py +2 -1
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_typed_capabilities.py +31 -2
- agenthooksprotocol-0.5.0/src/agenthooksprotocol/server/__init__.py +0 -8
- agenthooksprotocol-0.5.0/src/agenthooksprotocol/transports/stdio.py +0 -92
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/LICENSE +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/setup.cfg +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/__init__.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_boundaries.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_content.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_diagnostics.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_elicitation.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_host_metadata.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_interop_content.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_interop_hooks.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/capability.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/content.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/effect.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/event.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/registration.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/subscription.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/tool.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_models/transport.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/_outcomes.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/attachment.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/auth.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/candidate.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/codec.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/compaction.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/content.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/contract.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/diagnostics.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/effect.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/elicitation.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/event.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/integrations/__init__.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/integrations/pydantic.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/interop.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lifecycle.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lifecycle_client.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lifecycle_server.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/lineage.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/observation_chain.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/path.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/permission.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/py.typed +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/registration.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/response.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/runtime.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/_admission.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/_framing.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/_json.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/_slots.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/asgi.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/server/attachments.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/state.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/subscription.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/tool.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/transport.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/transports/__init__.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/transports/http.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol/wire.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/dependency_links.txt +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/requires.txt +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/src/agenthooksprotocol.egg-info/top_level.txt +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_attachments.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_catalogue.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_codec.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_compaction.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_compaction_wire.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_consumer_outcomes.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_content.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_content_lifetime.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_content_receipts.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_correlated_core.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_declared_contracts.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_elicitation_adapter.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_event_types.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_fixture_public.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_handwritten_surface.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_host_metadata.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_inline_messages.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_integration.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_integration_edges.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_interop.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_lifecycle.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_lifecycle_auth.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_observation.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_observation_chain_transport.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_owned_content.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_package.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_public_content.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_public_contract_surface.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_public_examples.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_public_server.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_registration_auth.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_safety.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_schema_corrections.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_shared_materialization.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_structural_facade.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_typed_contract_regressions.py +0 -0
- {agenthooksprotocol-0.5.0 → agenthooksprotocol-0.6.0}/tests/test_upload_planning.py +0 -0
{agenthooksprotocol-0.5.0/src/agenthooksprotocol.egg-info → agenthooksprotocol-0.6.0}/PKG-INFO
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: agenthooksprotocol
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.6.0
|
|
4
4
|
Summary: Official non-normative Python SDK for the Agent Hooks Protocol
|
|
5
5
|
Author: Agent Hooks Protocol maintainers
|
|
6
6
|
License:
|
|
@@ -266,14 +266,30 @@ async def review(existing_arguments):
|
|
|
266
266
|
|
|
267
267
|
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 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.
|
|
268
268
|
|
|
269
|
-
|
|
269
|
+
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.
|
|
270
|
+
|
|
271
|
+
```python
|
|
272
|
+
from agenthooksprotocol import capability
|
|
273
|
+
|
|
274
|
+
capabilities = capability.HostCapabilities(
|
|
275
|
+
tool_before=capability.ToolBeforeCapabilities(
|
|
276
|
+
intercept=capability.ToolBeforeIntercept(
|
|
277
|
+
allow=True, deny=True, modify_input=capability.Modify.REPLACE
|
|
278
|
+
),
|
|
279
|
+
observe=True, # intercept and observe
|
|
280
|
+
),
|
|
281
|
+
session_end=capability.SessionEndCapabilities(observe=True), # observe only
|
|
282
|
+
)
|
|
283
|
+
assert capabilities.to_wire()["tool.before"]["modes"] == ["intercept", "observe"]
|
|
284
|
+
assert capabilities.to_wire()["session.end"] == {"modes": ["observe"]}
|
|
285
|
+
```
|
|
270
286
|
|
|
271
287
|
Runnable, statically checked consumer programs live in [`examples/`](examples):
|
|
272
288
|
|
|
273
289
|
- `value_codecs.py`: independent argument/result/provenance codecs, admission-time invariants, and a form schema derived from its answer type.
|
|
274
290
|
- `typed_tool.py`: JSON registration, generated tool input, typed grants, initial state, real in-process ASGI handler, borrowed HTTP client, and explicit application decoding.
|
|
275
291
|
- `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.
|
|
276
|
-
- `stdio_tool.py` / `stdio_backend.py`: a real owned backend process using the same public
|
|
292
|
+
- `stdio_tool.py` / `stdio_backend.py`: a real owned backend process using the same public `hooks.Handlers`, denial, and child cleanup.
|
|
277
293
|
- `upload.py`: streamed binary upload, metadata no-read behavior, independent upload credentials, verified upload receipt, and caller-owned immutable storage.
|
|
278
294
|
|
|
279
295
|
- `lifecycle.py`: caller-owned task groups, operation-owned observations, interrupted requests, idempotent close, and proof that an owned subprocess was reaped.
|
|
@@ -322,19 +338,21 @@ The same remaining budget covers queue/readiness waits, provider waits, selected
|
|
|
322
338
|
|
|
323
339
|
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.
|
|
324
340
|
|
|
341
|
+
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.
|
|
342
|
+
|
|
325
343
|
## Static host manifest
|
|
326
344
|
|
|
327
345
|
`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.
|
|
328
346
|
|
|
329
347
|
Configure `Hooks(config, *, source, capabilities=capability.HostCapabilities(...), manifest_metadata=HostManifestMetadata(...))`. 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.
|
|
330
348
|
|
|
331
|
-
The frozen, keyword-only host capability model advertises only explicitly declared events and modes. Each event
|
|
349
|
+
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.
|
|
332
350
|
|
|
333
351
|
`await hooks.session_start(event.SessionStartInput(session=..., trigger="startup", harness=..., permission_mode="default", items=[]))` needs only occurrence-specific host facts. The SDK supplies `manifest`, `type`, and `source`, and supplies `id`/`time` when absent; `event_id=` takes precedence over a supplied ID. Caller payload fields cannot override the configured type, source, or manifest. Configuration, manifest snapshots, and delivered occurrences are independent copies. See [`examples/session_manifest.py`](examples/session_manifest.py) for a runnable, typechecked receiver example.
|
|
334
352
|
|
|
335
353
|
## Backend servers
|
|
336
354
|
|
|
337
|
-
`from agenthooksprotocol.server import hooks` exposes event-correlated callback maps. Configure `hooks.Handlers(intercept=hooks.InterceptHandlers(tool_before=before), observe=hooks.ObserveHandlers(tool_before=observer))`. A tool interception callback accepts `hooks.ToolBeforeContext` and returns `hooks.ToolBeforeReply`; an observation callback accepts `hooks.ToolBeforeObserveContext` and returns `None`. Callbacks can be synchronous or asynchronous. Contexts expose the typed event, full params/envelope, and detached raw evidence; interception contexts also expose request-time capabilities and state. Reply envelopes and correlation IDs belong to the server.
|
|
355
|
+
`from agenthooksprotocol.server import hooks` exposes event-correlated callback maps. Configure `hooks.Handlers(intercept=hooks.InterceptHandlers(tool_before=before), observe=hooks.ObserveHandlers(tool_before=observer))`. A tool interception callback accepts `hooks.ToolBeforeContext` and returns `hooks.ToolBeforeReply`; an observation callback accepts `hooks.ToolBeforeObserveContext` and returns `None`. Callbacks can be synchronous or asynchronous. Contexts expose the typed event, full params/envelope, and detached raw evidence; interception contexts also expose request-time capabilities and state. Reply envelopes and correlation IDs belong to the server. `hooks.ObserveHandlers(any=observer)` adds an optional catch-all that receives a `hooks.AnyObserveContext` for observed events without their own observer field. `from agenthooksprotocol.server import serve` is the AnyIO stdio server (`server.stdio.serve`).
|
|
338
356
|
|
|
339
357
|
`hooks.ToolBeforeReply(effects=(hooks.ReplaceInput(arguments), effect.Allow()))` preserves effect order. `hooks.ToolBeforeReply()` is a valid no-op. Reply types constrain event-specific controls; runtime validation still checks canonical/contextual legality and dynamic request grants. Tool contexts provide `decode_input(codec)` and `decode_candidate(result_codec, provenance_codec)` for caller-owned application types without discarding original wire evidence. The same dispatcher serves stdio and the framework-neutral ASGI adapter; ASGI does not require Starlette or FastAPI.
|
|
340
358
|
|
|
@@ -42,14 +42,30 @@ async def review(existing_arguments):
|
|
|
42
42
|
|
|
43
43
|
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 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.
|
|
44
44
|
|
|
45
|
-
|
|
45
|
+
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.
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
from agenthooksprotocol import capability
|
|
49
|
+
|
|
50
|
+
capabilities = capability.HostCapabilities(
|
|
51
|
+
tool_before=capability.ToolBeforeCapabilities(
|
|
52
|
+
intercept=capability.ToolBeforeIntercept(
|
|
53
|
+
allow=True, deny=True, modify_input=capability.Modify.REPLACE
|
|
54
|
+
),
|
|
55
|
+
observe=True, # intercept and observe
|
|
56
|
+
),
|
|
57
|
+
session_end=capability.SessionEndCapabilities(observe=True), # observe only
|
|
58
|
+
)
|
|
59
|
+
assert capabilities.to_wire()["tool.before"]["modes"] == ["intercept", "observe"]
|
|
60
|
+
assert capabilities.to_wire()["session.end"] == {"modes": ["observe"]}
|
|
61
|
+
```
|
|
46
62
|
|
|
47
63
|
Runnable, statically checked consumer programs live in [`examples/`](examples):
|
|
48
64
|
|
|
49
65
|
- `value_codecs.py`: independent argument/result/provenance codecs, admission-time invariants, and a form schema derived from its answer type.
|
|
50
66
|
- `typed_tool.py`: JSON registration, generated tool input, typed grants, initial state, real in-process ASGI handler, borrowed HTTP client, and explicit application decoding.
|
|
51
67
|
- `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.
|
|
52
|
-
- `stdio_tool.py` / `stdio_backend.py`: a real owned backend process using the same public
|
|
68
|
+
- `stdio_tool.py` / `stdio_backend.py`: a real owned backend process using the same public `hooks.Handlers`, denial, and child cleanup.
|
|
53
69
|
- `upload.py`: streamed binary upload, metadata no-read behavior, independent upload credentials, verified upload receipt, and caller-owned immutable storage.
|
|
54
70
|
|
|
55
71
|
- `lifecycle.py`: caller-owned task groups, operation-owned observations, interrupted requests, idempotent close, and proof that an owned subprocess was reaped.
|
|
@@ -98,19 +114,21 @@ The same remaining budget covers queue/readiness waits, provider waits, selected
|
|
|
98
114
|
|
|
99
115
|
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.
|
|
100
116
|
|
|
117
|
+
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.
|
|
118
|
+
|
|
101
119
|
## Static host manifest
|
|
102
120
|
|
|
103
121
|
`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.
|
|
104
122
|
|
|
105
123
|
Configure `Hooks(config, *, source, capabilities=capability.HostCapabilities(...), manifest_metadata=HostManifestMetadata(...))`. 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.
|
|
106
124
|
|
|
107
|
-
The frozen, keyword-only host capability model advertises only explicitly declared events and modes. Each event
|
|
125
|
+
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.
|
|
108
126
|
|
|
109
127
|
`await hooks.session_start(event.SessionStartInput(session=..., trigger="startup", harness=..., permission_mode="default", items=[]))` needs only occurrence-specific host facts. The SDK supplies `manifest`, `type`, and `source`, and supplies `id`/`time` when absent; `event_id=` takes precedence over a supplied ID. Caller payload fields cannot override the configured type, source, or manifest. Configuration, manifest snapshots, and delivered occurrences are independent copies. See [`examples/session_manifest.py`](examples/session_manifest.py) for a runnable, typechecked receiver example.
|
|
110
128
|
|
|
111
129
|
## Backend servers
|
|
112
130
|
|
|
113
|
-
`from agenthooksprotocol.server import hooks` exposes event-correlated callback maps. Configure `hooks.Handlers(intercept=hooks.InterceptHandlers(tool_before=before), observe=hooks.ObserveHandlers(tool_before=observer))`. A tool interception callback accepts `hooks.ToolBeforeContext` and returns `hooks.ToolBeforeReply`; an observation callback accepts `hooks.ToolBeforeObserveContext` and returns `None`. Callbacks can be synchronous or asynchronous. Contexts expose the typed event, full params/envelope, and detached raw evidence; interception contexts also expose request-time capabilities and state. Reply envelopes and correlation IDs belong to the server.
|
|
131
|
+
`from agenthooksprotocol.server import hooks` exposes event-correlated callback maps. Configure `hooks.Handlers(intercept=hooks.InterceptHandlers(tool_before=before), observe=hooks.ObserveHandlers(tool_before=observer))`. A tool interception callback accepts `hooks.ToolBeforeContext` and returns `hooks.ToolBeforeReply`; an observation callback accepts `hooks.ToolBeforeObserveContext` and returns `None`. Callbacks can be synchronous or asynchronous. Contexts expose the typed event, full params/envelope, and detached raw evidence; interception contexts also expose request-time capabilities and state. Reply envelopes and correlation IDs belong to the server. `hooks.ObserveHandlers(any=observer)` adds an optional catch-all that receives a `hooks.AnyObserveContext` for observed events without their own observer field. `from agenthooksprotocol.server import serve` is the AnyIO stdio server (`server.stdio.serve`).
|
|
114
132
|
|
|
115
133
|
`hooks.ToolBeforeReply(effects=(hooks.ReplaceInput(arguments), effect.Allow()))` preserves effect order. `hooks.ToolBeforeReply()` is a valid no-op. Reply types constrain event-specific controls; runtime validation still checks canonical/contextual legality and dynamic request grants. Tool contexts provide `decode_input(codec)` and `decode_candidate(result_codec, provenance_codec)` for caller-owned application types without discarding original wire evidence. The same dispatcher serves stdio and the framework-neutral ASGI adapter; ASGI does not require Starlette or FastAPI.
|
|
116
134
|
|