Consumer contract

Changelog

Canonical public changelog for the Hydracept consumer contract. It records changes external consumers can observe through the public surface: the CLI, the Python and TypeScript SDKs, MCP, capability descriptors, pricing fields, receipts, and the documented HTTP contract. It is not a log of every internal 0.x implementation detail.

Each entry must state: CLI version; SDK versions; agent pack / plugin version where relevant; new capabilities; contract changes; fixes; deprecations; removals; and migration notes.

Stability guarantees are described in the trust center and the repository compatibility policy. Package releases are published on PyPI and the public export repository.

0.4.3 — released 2026-09-22

Status: shipped. hydracept 0.4.3 is published to PyPI. @hydracept/sdk 0.3.5, @hydracept/elements 0.1.2, and Hydracept.Client 0.3.5 are unchanged. Agent pack 0.1.1. New capabilities: none. 0.4.3 is a contract and reliability release.

Contract changes

• MCP capability input. Every hosted MCP capability tool (hydracept_quote_capability, estimate_capability, hydracept_invoke, hydracept_run, hydracept_submit_job) now accepts input as an alias for body, matching the stdio client. Passing both is a typed INVALID_ARGUMENT. Previously an undeclared top-level input was dropped and the capability reported a missing field for what was really an envelope mistake.
• Terminal run payload. A terminal-successful stdio hydracept_run returns the leading contract (status, typedOutput/artifacts, pricing, jobId, receiptId, nextAction) without the App interaction / presentation envelope. The sealed receipt and full provenance remain on hydracept_get_receipt and hydracept_job_inspect; the App still attaches on non-terminal jobs, human gates, and the hydracept_ui_* adapters.
• Platform-owned output budget. Callers no longer compute maxOutputTokens; the runtime derives an explicit cap from the model limits and context window with a per-schema floor, and enforces the response schema on the transport where the provider supports it.

Fixes

• A provider length stop is classified OutputLimitReached (terminal) instead of a repair loop that truncated again; per-attempt finish_reason and provider diagnostics are retained.
• The public catalog no longer advertises a durable-job token budget.

Migration notes

• Omit maxOutputTokens unless a deliberate cap is intended; treat OutputLimitReached as terminal and re-run with a smaller input or a larger cap.
• MCP callers: pass capability input under body, or under input as an alias, but not both.

0.4.2 — released 2026-09-18

Status: shipped. hydracept 0.4.2 is published to PyPI. SDKs unchanged (@hydracept/sdk 0.3.5, Hydracept.Client 0.3.5). New capabilities: none.

• stdio MCP hydracept_run, hydracept_invoke, and hydracept_quote_capability accept input as an alias for body; passing both is a typed INVALID_ARGUMENT.
• {"input": {...}} is accepted as the capability input, and an unknown field fails with UNKNOWN_INPUT_FIELD naming the allowed set.
• capabilities find and resolve matches carry a server-projected runHint (cli/sdk/mcp, requiredInputFields, and a structured --input-file variant).
• run/quote/estimate accept repeatable --set key=value.
• hydracept_status fails with a typed tool error; version --json mirrors apiRevision/apiRevisionState/agentPack and gains --refresh.

0.4.1 — released 2026-09-18

Status: shipped. hydracept 0.4.1 is published to PyPI. New capabilities: none.

• python -m hydracept smoke text probes a synchronous text capability (text.translate.v1 by default) through the same coercion path as run.
• doctor reports public_text_capabilities from the live catalog and names the text smoke probe.

0.4.0 — released 2026-09-17

Status: shipped. New capabilities: none. 0.4 is a consumer-contract and public-surface release, not a capability-count expansion.

Contract changes

• Output persistence contract. Commands and tools that accept out / --out now behave deterministically on success: plain text results are written as a UTF-8 text file, structured results as canonical JSON, and binary/media results as the original artifact bytes. Persistence failure is never reported as successful output, and an ambiguous direct out for multiple artifacts is rejected before writing. Results expose requestedOutputPath, persistedOutputPath, persistedMediaType, and persistedSha256.
• Capability descriptor canonicalization. The same canonical descriptor powers CLI capabilities describe, MCP capability describe, SDK discovery, and agent-context. Where applicable it includes key, description, readiness, billing modes, constraints, canvas / size floor, required inputs, optional inputs, simple-input coercions, example input, supported execution modes, output kind, deferred-processing support, and next action / recovery hints.
• Error taxonomy. Errors now distinguish UNKNOWN_CAPABILITY, CAPABILITY_UNAVAILABLE, WORKSPACE_CAPABILITY_DISABLED, CAPABILITY_NOT_CONFIGURED, INVALID_INPUT, AUTH_REQUIRED, BUDGET_EXCEEDED, PROVIDER_UNAVAILABLE, and TRANSPORT_AMBIGUOUS. A capability key is resolved before workspace policy, so a typo is never reported as a workspace permission problem. Unknown keys return the offending key and ranked suggestions when high-confidence matches exist.
• Value-level recovery. Validation failures point at the actual invalid value and its correction, such as supplying a non-empty --prompt or using --input-file, instead of generic capability discovery.
• Quote/run coercion parity. If a capability supports an ergonomic input coercion in run, the same coercion is available in capabilities quote unless the capability explicitly documents why quoting needs different information.
• Pricing vocabulary. Quote and receipt output use one shared vocabulary: billingMode (managed | byok), chargeState (charged | covered | provider_billed_directly | unavailable), customerChargeUsd, providerCostUsd, and, where shown, managedEquivalentChargeUsd. Managed execution reconciles to provider cost + 6%; BYOK reports a 0% Hydracept fee and is billed directly by the provider; covered execution is labeled Covered by Hydracept, not as a retail price.
• MCP runtime states. MCP runtime presentation uses current, reload_available, incompatible, not_started, and unreachable. Only incompatible and unreachable are warning-shaped; a working but stale MCP process reports reload available.

Deprecations

• Public copy and fields that implied a Hydracept-assigned capability retail or list price are removed or deprecated. Use the canonical pricing vocabulary above.

Removals

• Generic actualCost is no longer part of the public receipt vocabulary. Use providerCostUsd and customerChargeUsd, with managedEquivalentChargeUsd where a managed-equivalent figure is shown explicitly.

Migration notes

• Move from actualCost, retailPrice, or catalogPrice to providerCostUsd, customerChargeUsd, billingMode, and chargeState.
• Handle a rejected or failed --out persistence result instead of assuming a file was written.
• Match UNKNOWN_CAPABILITY (and optionally its suggestions) instead of a bare not-found response.
• Treat reload_available MCP runtime output as informational, not as an error.

← Hydracept home