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.

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.5.5 — 2026-11-01

• Docs: the packaged Python client's agent skill now states that audio artifact format is not SFX-specific. Audio artifacts default to Ogg (audio/ogg, .ogg); outputFormatPreference (for example mp3_44100_128) requests another supported format, and the artifact mediaType and filename match what the API returns. The previous copy implied the rule was limited to audio.sfx.generate.v1.

0.5.4 — 2026-10-28

• Receipts: every receipt includes an Ed25519 seal (algorithm, keyId, publicKey, receiptHash, signature, signedAt). receiptHash is SHA-256 over canonical JSON without the seal; signature signs the same bytes, so a stored receipt can be verified against GET /v1/public/receipts/verification-key and checked for tampering.
• HTTP: a voice quote and receipt now report the voice that actually ran (voiceIdSource=managed_default when the managed default was used) and the executed model (eleven_v4). An explicit voiceId is still reported as caller.
• HTTP: video.generate.v1 on gemini-omni-1.1-flash requests a silent MP4 by default. When Google omits per-request usage, a completed video's provider cost is priced from the pinned Google rate schedule and marked estimated, rather than remaining unknown.
• CLI: hydracept keys create --print-env writes the one-time credential and server environment values (HYDRACEPT_API_KEY, HYDRACEPT_PROJECT, HYDRACEPT_ENVIRONMENT, HYDRACEPT_API_URL). The secret is stdout-only, a warning is written to stderr, and the flag is mutually exclusive with --json and --configure.
• CLI / diagnostics: hydracept keys verify --json checks the typed /v1/diagnostics/session credential contract without executing a capability or reserving spend. It reports the effective project, environment, auth method, scopes, expiry, and credential id where available; revoked or expired keys return 401. The key is read from HYDRACEPT_API_KEY or stdin, not a command-line argument.

0.5.3 — 2026-10-19

• MCP (hosted): POST /mcp/compact lists eleven hydracept_* tools. POST /mcp and POST /mcp/full keep main-compatible tool names and input schemas (38 tools; resolve_capability, request_capability_quote, and get_capability_request_quote stay listed). Matching hydracept_* names work on tools/call only on full surfaces.
• MCP: compact adds hydracept_jobs_find for lost job ids and hydracept_cancel_job for explicit cancellation. The readiness tool is hydracept_workspace_status on compact; full surfaces keep the compatible hydracept_status list name, and the new name works on tools/call. Cancellation never promises upstream work stopped or that incurred cost was refunded.
• MCP (stdio, PyPI 0.5.3): default full; compact opt-in via HYDRACEPT_MCP_TOOL_PROFILE=compact or --tool-profile compact. Richer tool and parameter descriptions on tools/list.

0.5.2 — 2026-10-07

Client packages hydracept (PyPI), @hydracept/sdk (npm), and Hydracept.Client (NuGet) 0.5.2. README samples now run, type-check under tsc --strict, and compile exactly as written. The Python stdio MCP server and skill lead with agent execution: resolve_capability takes the user's words and estimate_capability is no longer an MCP tool. All three packages include LICENSE.

Migration

• None. Minimum supported client stays 0.5.1.

0.5.1 — 2026-10-05

hydracept init no longer uploads provider keys unless you pass --adopt-keys (or confirm on a TTY). Python, TypeScript, and C# invoke helpers send a unique idempotencyKey by default.

Migration

• Restore prior init adoption: hydracept init --apply --yes --adopt-keys openai,anthropic or hydracept connections adopt.

0.5.0 — 2026-10-02 (breaking)

Legacy runtime HTTP routes removed (POST /v1/invocations, invocation lifecycle GETs, legacy POST /v1/jobs). SDKs (@hydracept/sdk, hydracept, Hydracept.Client) bumped to 0.5.0.

Migration

• Submit via POST /v1/capabilities/{key}/invoke|jobs; poll GET /v1/jobs/{jobId} for status, receipt, and cancel.
• Stream invoke SSE: GET /v1/executions/{executionId}/events (not /v1/invocations/.../events).

0.4.6 — folded into 0.5.0 (2026-09-28)

Status: not published to PyPI; changes shipped in the 0.5.0 breaking release.

Fixes

• hydracept init prints identity-assertion email and comped-beta hints when GitHub noreply email is unverified (localIdentity.emailHint).

0.4.5 — released 2026-09-28

Status: shipped on PyPI, npm @hydracept/sdk, and NuGet Hydracept.Client.

Contract changes

• Provider cost accounting is explicit and auditable: pricing.providerCost is structured provider cost evidence (amount null when unknown, never 0, with basis/status and a pinned priceScheduleId for usage-priced cost).
• providerCostUsd is now Hydracept's actual provider cost; the upstream retail price basis moved to the new providerPriceBasisUsd (providerCostBasis: "provider-cost").

Fixes

• An estimate is never promoted to actual provider cost, and a failed or unknown-cost operation is no longer reported as $0.

Migration notes

• Consumers that read providerCostUsd as the upstream price basis should read providerPriceBasisUsd; providerCostUsd now reports provider cost.

0.4.4 — released 2026-09-25

Status: shipped on PyPI (hydracept 0.4.4).

Fixes

• connections adopt --from-env-file resolves absolute env file paths outside --project-root.
• setup-grant create prints the issued token when not using --json.

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