Metadata-Version: 2.4
Name: agent-workflow-contracts
Version: 1.3.0
Summary: Shared frozen wire contracts for agent workflows
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic
Requires-Dist: hank-model-authority<2,>=1.6.1

# agent_workflow_contracts

Dependency-neutral frozen pydantic wire models shared by the gateway, the
product agent runtimes, and any external consumer. No gateway imports —
that is the point of the split.

Owner doc: [`docs/reference/agent-workflow-contract-normalization-design.md`](../../../docs/reference/agent-workflow-contract-normalization-design.md) — parent package README's owner page.

`AgentOperationSnapshot.execution_class` records the operation's work-kind.
Optional `role` and `effort` declarations participate in its semantic identity;
they do not resolve a model here. Both fields are omitted when `None`, preserving
historical snapshot dumps and sealed admitted-task digests.

`awaiting_approval` is an attempt settlement awaiting a human decision, not
success or failure. It retains the exact admitted task identity, provenance,
and observed usage, with a reason but no analytical outcome or result values.
Executable approval binding and continuation belong to the gateway approval
owner, not these wire contracts.

`ids.DecisionId` / `ids.parse_decision_id` accept exactly four declared families:
`dec_<32 lowercase hex>`, lowercase UUID4 (version 4 and RFC variant),
`approval-batch-<32 lowercase hex>`, and
`approval-late-existing-<one-or-more lowercase hex>`. Parsing preserves the
supplied identity without conversion; `new_decision_id` mints only `dec_` ids.

`models.PreviewDigest` is the strict string union used by
`GateDecisionRef.preview_digest`: native bare `<64 lowercase hex>` argument
hashes, `sha256:<64 lowercase hex>` content digests, or
`hmac-sha256-v1:<key-id>:<64 lowercase hex>` argument MACs. HMAC key ids
contain 1–64 characters drawn from `[A-Za-z0-9_.-]`.
The global `Digest` contract remains SHA-256-only. `GateDecisionRef` requires
`preview_digest`, `preview_ref`, and `resolving_acts`. Its `diff_base` is present
only when a review base exists and is omitted otherwise; native projection
belongs to the edge owner, not these contracts.

| File | What it is |
|---|---|
| `models.py` | Frozen `WireModel` contracts including `CapabilityBind`, `AdmittedTask`, `TaskResult`, `DeliveryEnvelopeV1`/`V2`, `WorkflowView`, `PublishedOutput`, and `ContentHandle` |
| `ids.py` | Declared `DecisionId` grammars and `dec_`-only minting |
| `ticker_contract.py`, `research_file_contract.py` | Typed ticker and research-file identifier contracts |
| `skill_runs.py` | Skill-run identifier grammar, parser, and sole minter |
| `plan_preview.py` | Plan identifier grammar and minter, and strict `PlanPreviewRef` identity |
| `artifact_identity.py` | Typed artifact refs, kind-specific identity validation, and run-scoped artifact minting |
| `next_call.py` | Canonical `NextCall` / `next_call` contracts for next and repair tool calls |
| `tool_registration.py` | Dependency-neutral static tool-registration contracts |
| `context_refs.py` | exact door-readback ref minter (`read_back_refs`), bounded persist-envelope delta projector (`project_persist_envelope_delta`), and report-door analyst receipt (`project_report_envelope_receipt`) shared by the gateway runner, pipeline stages, and named children |
| `schema.py` | `public_json_schemas()` / `public_schema_bundle()` / `export_public_json_schemas()` |
| `generated/` | **build output** — JSON Schemas, `agent-workflow-contracts.d.ts`, the schema bundle, and delivery-envelope goldens. Regenerate from the checkout with `.venv/bin/python3 scripts/generate_agent_workflow_contracts.py`; do not hand-edit. |

Consumers and lifecycle: `../../agent-gateway/docs/api-reference.md` (section "Workflow Delivery Contracts")
The embedding application owns the workflow executor that admits and persists
these contracts.
