agenomic-typescript

Imported from treansai/agenomic-typescript (AGENTS.md). Install upstream with npx skills add treansai/agenomic-typescript. Copyright stays with the author.

AGENTS.md

Decisions that would otherwise live in code comments. Keep entries short and factual.

Protect

• Request helper: tools.ts exports fetchJson (transport only), acceptJson (2xx or typed ToolExecutionError from { error: { code, message } }, invalid_response on a non JSON 2xx body) and requestJson. ToolsResource.request and every protect.ts method go through them so there is no untyped path; the RMP resources in rmp.ts keep their own local-first helper because their offline mode must not throw.
• ToolCallResult.result is T | null: 202 pending and 403 denied envelopes carry result: null (design section 5). router.call still returns T because pending and denied always throw; invoke callers must null check.
• Two 403 bodies exist on invoke: an invoke envelope ({ result: null, agenomic: { record_id, ... } }) becomes ToolCallDenied; a plain { error } body (capability lapse, permit invalid, run not active) stays a ToolExecutionError with the server code. readEnvelope decides on the presence of agenomic.record_id.
• authorizeLocal accepts the decision on a 2xx body or on a 403 body that carries decision or protect (the gateway answers 200 local/gateway, 202 pending, 403 denied). The 403 gate tests for the presence of the key ("decision" in body), not for a string value: a 403 carrying decision: null or a number is an admission denial and used to fall through to acceptJson and surface as a generic http_error, which hid the denial from ToolCallDenied and from router.calls. Only local, gateway and pending are recognized; every other string, a missing field or a non string is denied (design section 9, no fallback).
• Pending and denied are admission outcomes, not tool outcomes: the router pushes the envelope to router.calls and throws regardless of raiseOnError. Synthesized local-path envelopes use real enum values only (source: unrouted, fidelity: contract_only, external_state: none) so hasRealCalls stays false.
• The permit is opaque to the SDK ({ document, signature } records) and forwarded verbatim in report-local; the SDK never inspects or verifies it (design D6).
• beforeAction receives the call identity (ToolActionIntent) and is awaited before any request on both paths, including the re-POST issued by resume; a throw aborts locally and leaves no evidence row. It cannot approve.
• ToolsResource.client is public readonly (it was private) so the router can poll client.protect.approvals without a second HTTP helper.
• ToolActionIntent.executionPoint is runtime_local whenever a local function is registered for the tool, even if the gateway later answers gateway: the hook sees the intended execution point before any request, not the final routing.
• Synthesized local-path envelopes set agenomic.decision to the outcome (protect.outcome, else require_approval for pending and deny for denied) so the field means the same thing as on gateway envelopes; the local authorize verb (pending, denied) lives in LocalAuthorization.decision only.
• resume runs through the same private dispatch as call with a resume argument (no instance flag) so concurrent calls on the same router never lose their idempotency key.
• resume looks the call identity up in a private map keyed by approval_id filled when ToolApprovalPending is thrown; an approval id the router never saw throws unknown_approval rather than guessing a body. The re-POST sends the identical body with the original Idempotency-Key (docs/protect/integration.md section 6: the middleware never records a 202, so the key is free to replay the cached 200 once the call executed). Statuses approved and consumed both re-issue exactly once, which is the behaviour the Python SDK also implements: a consumed approval already executed, so the replay recovers the stored result, and a 409 on that replay throws ToolExecutionError("conflict", ..., 409) rather than a denial that would suggest nothing ran. pending polls until timeoutMs (elapsed time is checked before sleeping so timeoutMs: 0 cannot loop); rejected, expired and unknown strings throw ToolCallDenied with that status as code (fail closed).
• The consumed recovery contract is verified against a real gateway, not only against an HTTP fixture: examples/protect-consumed-recovery.ts is the manual harness (closure criterion 3 of the 2026-09-15 Protect campaign), run with the built bundle, and examples/11_protect_consumed_recovery.py in agenomic-python is its twin asserting the same contract so a divergence fails an assertion on one side. Observed on a gateway with Postgres and two user owned API keys: on the gateway executed path (invoke, where the SDK sends the Idempotency-Key derived from run, repetition and logical call id) a resume over a consumed approval answers HTTP 200 and replays the stored result with no second effect; on the runtime local path (local/authorize, which carries no idempotency key) the same resume answers HTTP 409 and throws ToolExecutionError("conflict", ..., 409). Both branches of the contract are real and path dependent, not credential dependent, and both SDKs produce them identically. Keep both; narrowing resume to one branch would break the other execution point.
• resume claims the approval in a resuming set before its first await and releases it in a finally, then deletes its pending map entry before re-issuing. The deletion alone was not enough: two concurrent resumes of the same approval both read the map entry before either reached the deletion after the polling loop, both re-POSTed, and on the runtime local path, which carries no idempotency key, that executed the local function twice. A second resume while one is in flight now throws ToolExecutionError("resume_in_flight"); a resume that timed out has released its claim, so retrying after a timeout still works. Calling resume twice in sequence still ends in unknown_approval. The consumed path is reachable only from a second holder of the same identity, which the harness builds by having two routers issue the identical logicalCallId and both receive the same 202 and approval id. This is deliberate: a router must not invent an identity it never held.
• The pending map stores a deep snapshot of the arguments (snapshotArgs, structuredClone with a JSON round trip fallback). The identity kept the caller's object by reference, so mutating the arguments after the 202 made resume send a different payload under the logical call id and idempotency key that were approved: the replay would no longer be the approved request.
• An empty 2xx body is invalid_response, not {}. fetchJson leaves parsed undefined when the text is empty, so acceptJson refuses it like any other non JSON 2xx body. Turning it into an empty object let exported requestJson and the less strictly validated tool methods accept a response that carried no JSON at all. benchmarks.ts keeps its own 204 handling and is unaffected.
• protect.ts subclasses the RMP ProtectResource so alerts, actionPlan, recommendations and notify keep their local-first behaviour; rmp.ts exposes client as protected for that reason. index.ts exports the subclass under the single public name ProtectResource.
• Path segments in protect.ts are encodeURIComponent-encoded like rmp.ts; policies.* take (policyId, version) and build policy_id@version (crm%402.0.0), the format handlers_policies.rs splits on the first @.
• Wire mirrors in protect.ts follow crates/agenomic-api-types/src/lib.rs (PolicySummary, PolicyDetailResponse, SimulateResponse, PolicyDiffResponse, PolicyBinding, ProtectDecisionDto, ProtectApproval, ProtectRestriction, KillSwitchResponse, OverlayResponse, CatalogResponse, CoverageResponse, ProtectMetricsSummary) and agenomic-policy/src/intent.rs (ProtectDecisionDocument mirrors Decision, ProtectDecision mirrors InvocationDecision). Uuids and timestamps are strings; enums whose Rust side is a plain String (scope_kind, binding status, restriction kind) stay string on read and are literal unions on the write side only. Single-record responses are read bare, as the gateway sends them (record(res, "id", ...), "text" for the overlay), and an enveloped body is an invalid_response: accepting both hid a wire mismatch. The three policy transitions (register, release, deprecate) are the exception, answering PolicyResponse { policy }, so they go through policyRecord(res) and return a typed PolicyRecord. List responses require the documented array key and raise invalid_response when it is absent, so an empty list and a shape mismatch stay distinct. decisions.list is the one paginated read and returns { decisions, next_cursor? }; policies.register also accepts the YAML or JSON text, sent as { document_text }; bindings.list carries the status filter.
• OpenAI overlay: applyOverlay is a pure function returning the same object when the overlay is already present (messages[0] is the system overlay, or instructions equals or starts with the overlay text followed by a blank line), so double instrumentation and retries are idempotent and the caller's request object is never mutated. For responses.create the recorded model_call.input becomes { instructions, input } whenever instructions is present, otherwise input, so the trace reflects the injected request.

Vault

• Agents Vault is an optional commercial module; the contract is agenomic-cloud/docs/vault/openapi.yaml. The SDK surface is public and inert without the add-on. client.vault is the admin namespace (API key); client.vault.runtime and the client.tools.execute / executionStatus shortcuts use the runtime token. Credentials never cross surfaces: the transport reads the API key only for admin routes and the vrt_ token only for /v1/vault/runtime/*, and caller headers named authorization, proxy-authorization or x-api-key are dropped for vault calls. A runtime token that does not start with vrt_ is refused when the client is built, so an org API key cannot be wired into an agent runtime by mistake.
• Auth header: the OpenAPI declares x-api-key for admin routes; the SDK sends authorization: Bearer <apiKey> like every other resource, which the gateway accepts as the same credential (services/api-gateway/src/auth.rs). Runtime routes take Bearer vrt_... as documented.
• Read types are snake_case wire mirrors of the OpenAPI schemas (like protect.ts); inputs are camelCase. Fields the server sends as null are typed | null although the OpenAPI declares them plain strings (handlers_vault.rs serializes Option without skipping). BindingContent and ProviderDescriptor stay in wire shape on input. List filters (environment, provider_id, agent_id, binding_id, state, limit, action_id) come from the handler query structs, not from the OpenAPI, which documents no query parameters.
• Error classes extend ToolExecutionError through VaultError so existing catches keep working. The server's error code is a free string in the OpenAPI; the mapping in vault/mapping.ts follows VaultError::code in agenomic-vault/src/error.rs plus capability_* from agenomic-capabilities. Rate limiting is too_many_requests (HTTP 429, Retry-After), not documented in the OpenAPI. A lock is capability_not_entitled, capability_not_in_edition or capability_disabled and is relayed as VaultNotEntitledError; the SDK never computes entitlement and status() returns the server's answer unchanged.
• The runtime execute response is not what the OpenAPI says: 403 carries either a denied body (policy) or a plain { error } (entitlement, permission), and 409 carries either a plain { error } (vault_* refusals) or a refused body. interpretExecution decides on the body (status plus the matching HTTP status and action_id), and any 2xx that is not a consistent finished/succeeded body is invalid_response: fail closed, never a success.
• outcome_unknown arrives as a 200 finished body with state: outcome_unknown and as a 409 vault_outcome_unknown; both are VaultOutcomeUnknownError and neither is retried. A resend of a denied actionId returns a finished/refused body whose error_class is the comma-joined reason codes (runtime.rs mark_refused); it maps back to VaultPolicyDeniedError. State failed (the destination answered an error) throws VaultExecutionFailedError carrying the server-filtered body; tools.execute returns only for succeeded.
• Retries: the transport resends the identical serialized body, so actionId cannot change between attempts. Reads and executions are idempotent and retry on a network fault, 502, 503, 504 and vault_backend_unavailable / vault_destination_unavailable; 429 retries for every request (the throttle runs before processing); admin writes never retry after a fault. The SDK's own timeout does not retry (the server may still be executing; getExecution reads it). Execute timeout is deadlineMs (default 30 s) plus 15 s.
• Secrets: Sensitive keeps bytes in a module-private WeakMap, has an own enumerable redacted field only so structuredClone yields the constant mask, and has no accessor; the request serializer substitutes the text through a JSON.stringify replacer that reads the holder (toJSON runs first), only for the three secret-write routes (allowSensitive). A plain string is refused (sensitive_required), a Sensitive anywhere else is refused (sensitive_refused, including tool arguments). The transport builds errors from routing facts and never attaches a cause; server text is scrubbed against the request's secrets in raw, JSON-escaped, URL, base64, base64url and hex forms, and so is the parsed body of a secret write. Log events carry no body, header or token. RuntimeToken (returned by runtimeIdentities.issue) is masked the same way and takeOnce() hands the text out once; it is an enrollment credential, not a vault secret value. The transport keeps the client in a #private field so client.vault stays serializable.
• secrets.rotate starts a rotation job (POST /secrets/{id}/rotations, overlap_seconds); secrets.addVersion is the older POST /secrets/{id}/versions. The nine paths added later (rotations x5, revocations/{id}/retry|lift, executions/{action_id}/resolve, runtime/grants/{id}/delegations) need a server that implements them; the docs say so. resolve never re-sends.
• Replay is client side because the vault OpenAPI has no replay route: vault.replay.fixtures makes a client that answers execute and getExecution from fixtures and nothing else. It holds no runtime token (combining them is refused at construction), has no fetch, and a missing fixture is VaultReplayFixtureMissingError; admin and grant calls throw VaultReplayUnavailableError and are never sent live. Each outcome kind synthesizes the wire answer the server gives and goes through the same mapping as a live call; the per-actionId idempotency of the server (settled answers repeat, a different request on a used actionId is a 409) is mirrored.
• Not done: receipt signature verification (the contract defines no verification procedure), lint (this repo has no linter; tsc --strict is the static gate), a CHANGELOG (the repo has none).

Release

• The npm package is @treansai/agenomic-typescript; the SDK identity string is not. SDK_METADATA.name in utils.ts and the sdk default in benchmarks.ts stay "agenomic-typescript" because that value is a protocol constant the cloud matches on (agenomic-cloud/crates/agenomic-onboarding/src/enroll.rs, AgenomicTypescript => "agenomic-typescript"), paired with agenomic-python. Scoping the registry name must not move the wire value.
• build runs tsup before typecheck, not after. examples/protect-consumed-recovery.ts imports from ../dist/index.js (deliberately: it is the harness that runs against the built bundle) and tsconfig.json includes examples/**/*.ts, so tsc --noEmit on a checkout with no dist fails with 21 unresolved-member errors. The old order made pnpm build impossible from a clean clone, which is exactly what CI has.
• Publishing goes through npm publish, not pnpm publish: OIDC trusted publishing landed in pnpm 10.17 and packageManager pins 10.0.0. The workflow upgrades the npm CLI only when the runner image ships one below 11.5.1, the version that added trusted publishing.
• The release job packs with npm pack and publishes the resulting tarball rather than the working directory, so the artifact attached to the GitHub release is byte-for-byte the one on the registry. That holds from 0.1.2 onward: 0.1.1 is the hand-published bootstrap, so its registry copy carries no provenance and is not the tarball its GitHub release attaches.
• The tag trigger is not the authorization. on: push: tags matches a name, not a history, so a v* tag on any unmerged branch would otherwise check out that commit and publish it under the package name, with review and branch protection bypassed. The job fetches main and refuses unless the checked out commit is reachable from it, which is why checkout runs at fetch-depth: 0. The ancestry test uses git rev-parse HEAD rather than GITHUB_SHA so it reads the same for a lightweight and an annotated tag.
• No npm token exists in the repository. id-token: write plus the npm environment is the whole credential; the bootstrap that had to precede it is in docs/release.md.
• npm publish is handed ./artifacts/<name>.tgz, never artifacts/<name>.tgz. npm-package-arg only treats a spec as a file when it starts with ., /, ~/, a drive letter or file:; a bare a/b.tgz falls through to the hosted-git shorthand parser and npm tries to clone github.com/artifacts/<name>.tgz. Verified on npm 10.9.8, 11.19.1 and 12.0.2: the bare form exits 128, the ./ form resolves the tarball. find ./artifacts is what keeps the prefix.
• The publish step skips when the version is already on the registry instead of failing. The tag-vs-package.json guard already makes a mismatched tag impossible, so the only way to reach publish with a published version is replaying the same tag, which is either the bootstrap handover or a re-run of a failed job. Failing there would cost the GitHub release, which is the part still worth producing.

Runtime

• tools.ts imports randomUUID from node:crypto like utils.ts does, rather than reaching for the crypto global. The global is only exposed unflagged from Node 19, so logicalCallId generation threw ReferenceError: crypto is not defined on Node 18 while engines.node promised >=18. One file was using a different source for the same primitive than the rest of the SDK.
• CI gates Node 20, 22 and 24, not the declared >=18 floor. Node 18 has been end of life since April 2025 and, with the import above fixed, it passes every test except one benchmarks HTTP case that lands at 5027ms against vitest's 5000ms default. The floor is left at >=18 because the SDK does work there; gating it would mean loosening the timeout for every test to cover a runtime nobody should be on.

Managed prompts

• Scope: references, digests, rendering, client.prompts (get, resolve, resolveAgent, workspaceId), client.bindings (create, get) and offline bundle reading. Publishing, drafts, aliases, channels, experiments and the LangGraph adapter are Python only, and no SDK exposes a channel promote or rollback: channel moves need a signed-in session and the SDKs hold API keys.
• Bundle signatures are not verified. The signature is ed25519 over BLAKE3, node:crypto has no BLAKE3 and the package keeps zod as its only runtime dependency, so PromptBundle.fromDocument and readPromptBundleFile require expectedBundleDigest (the prompt_bundle_digest of the export), expectedWorkspaceId and expectedAgentId. A missing pin, including from untyped JavaScript, throws bundle_untrusted_key; there is no flag to load an unpinned document. signatureVerified is always false, a signed export is accepted only through the pin, and the governance step is not applied because the pin is the operator's approval. The bundle digest is required rather than the manifest digest because only the artifact set covers child manifests and their prompts.
• The load order is the Python one: JSON subset, schema and member types, a signed document without expires_at refused, pin present, expiry (only YYYY-MM-DDTHH:MM:SSZ), every prompt content digest, the artifact set against the embedded digest then the pin, every manifest digest and expectedManifestDigest, the exact closure (missing or extra prompts, a child whose release or genome differs from its pin, a child manifest of another agent, an unreachable child, a prompt key that is not its own prompt_id:version), then scope. The closure walk compares a pin every time it meets one and deduplicates only the traversal: a child or a prompt named by more than one pin (two manifests, two slots, a slot and a fragment) is refused when any of those pins differs from the single record the bundle carries, whichever pin the walk meets first. fromOnlineResponse runs the same checks without a pin and refuses a document carrying signature.
• A verified bundle keeps a deep-frozen JSON copy taken right after the subset check, so mutating the caller's object afterwards cannot change what was verified. ManagedPromptVersion objects are deep-frozen too, and their validation result lives in a WeakMap; a version object the SDK did not build (a spread copy, a hand-made literal) is validated again and its digest compared with contentDigest before it renders.
• Name-keyed maps never use in or a write on a plain object: membership is Object.hasOwn, render values live in a Map, the fragments map of a version is Object.create(null), and scrubSecretsJson builds objects with Object.fromEntries. A variable, partial or fragment may be named __proto__, constructor or toString (vectors R063 to R066 and T069). renderText, renderMessages and compose also take a Map of variables for that reason.
• get digest-verifies every record of the fetched closure before validating the content, so a tampered fragment reports prompt_digest_mismatch with its ref, as the digest verification of RFC 0012 requires for every downloaded entry, instead of the validation item fragment_digest_mismatch. Content that is otherwise invalid fails closed with the same top-level codes as the Python SDK: prompt_secret_detected when any secret was found, prompt_content_too_large for the size and count limits, prompt_kind_mismatch, prompt_fragment_cycle, prompt_fragment_depth_exceeded, and prompt_template_invalid otherwise.
• Server codes map to the error classes through one explicit table, not by prefix, because no prefix separates them (execution_binding_conflict is a binding error, prompt_draft_conflict is not). Only the five classes of the minimal surface exist; any other code is a plain ApiError.
• Registry, verification and render failures of the prompt resources are ApiError (invalid arguments throw Error or TypeError before any request): acceptApiJson maps the { error: { code, message, details } } envelope (adding request_id, capability, reason and required_plan to details), a non-JSON error body to http_error and a non-JSON success to invalid_response, and the ToolExecutionError that fetchJson throws for transport_error and cloud_required is re-raised as ApiError with the same code and status. tools.ts and protect.ts keep ToolExecutionError. There is no retry and no outage fallback in this SDK; the first failure is raised. A binding answer is checked down to every child pin (a record with a string prompt_manifest_digest) before the artifacts are compared with it, so a malformed child is invalid_response, as in Python, and not a TypeError. The artifacts are then compared with the binding in both directions, over the union of the two child id sets: a child the binding pins and the artifacts lack, and a child the artifacts carry and the binding does not pin, both raise manifest_digest_mismatch (actual or expected is null). A manifest pins a child by release and genome only, so the binding is the document that ties a child manifest digest to the execution, and a child outside it would render prompts no binding vouches for. The registry builds the artifacts from the binding's own children, so an honest answer always has equal sets.
• The workspace comes from GET /v1/whoami, read once per client (a WeakMap keyed by the client; a failed read is forgotten so the next call asks again). It is never taken from the document being verified, and a version whose canonical_uri names another workspace raises workspace_mismatch.
• Aliases are resolved on every call and their target is never cached; verified versions are cached in memory per resource, keyed by workspace and prompt_id:version, least recently used first out above 1024 entries.
• bindings.create sends exactly thread_key, scope, selector, runtime_client, include and, when given, expect, because the registry refuses unknown members, and no Idempotency-Key: the route is create-or-get on the thread key. runtime_client.sdk is the SDK_METADATA.name protocol constant and sdk_version is null, the package having no version constant. threadKey and executionKey hash agenomic.thread_key/v1, the workspace and the id with NUL separators, exactly like the Python SDK (the test pins Python's output). An id holding a lone surrogate throws TypeError, as Python's UTF-8 encoding refuses it, because node:crypto would hash it as U+FFFD and give two different ids the same key, so two threads would share one binding.
• JsonExchange.headers carries the response headers for routes that answer an ETag; no route of the minimal surface needs it yet.
• RenderOptions.expectKind, RenderedPrompt.expandedTemplate and RenderedPrompt.renderedDocument exist for the conformance vectors: kind_mismatch is checked after validation and before variable binding, and the vectors assert the expanded template and the rendered document.
• scanSecrets builds one UTF-16 to code point index per scanned string and reads every finding offset from it. Counting the code points of the prefix for each match made a scan quadratic in the number of findings, so content near the 262144 byte limit filled with short secret-shaped tokens took seconds (tests/prompt-secrets.test.ts).
• tests/fixtures/spec-vectors/ is a byte copy of the SPEC prompt vectors made by scripts/sync-spec-vectors.sh; the harness checks SPEC_VECTORS.lock and MANIFEST.json before running any vector. .gitleaks.toml keeps the default rules and allowlists that directory only, because vectors R058, R059, S008, S009 and S014 hold deliberately fake tokens that the secret scanner must detect. Tests build secret-shaped strings at runtime instead of writing them literally.
• Registry response goldens are wire shapes, not consistent documents (their manifests and closures disagree), so tests/prompt-fixtures.ts builds bundles, versions and bindings with real digests.
• examples/prompts-render.ts imports ../dist/index.js and runs with node --experimental-strip-types after pnpm build, like the Protect harness, because Node cannot resolve the extensionless imports of src/.
• The code table also maps bundle_signature_invalid and bundle_ungoverned to PromptIntegrityError although this SDK never raises them, so a code keeps the class it has in the Python SDK; docs/prompts.md says they are never raised here.
• A version object the SDK did not build is validated again with its fragments' kinds taken from their kind, but only "fragment" is passed on as a prompt kind. A fetched fragment has kind "text" (the registry version answer carries no prompt kind, as in Python), so passing "text" would refuse an unchanged copy with fragment_not_fragment; the pin digest and the fragment_not_text check still apply.
• CHANGELOG.md starts with the managed prompts work: the repository had no changelog for 0.1.1 and earlier, and those entries are not reconstructed. It is not shipped: files lists dist, README.md and LICENSE, and npm pack on npm 10.9.8 and 11.21.0 leaves a root CHANGELOG.md out, so the packed file set the CI asserts is unchanged.

Knowledge bases

• Scope: the read and publish surface of the Agenomic Cloud knowledge base API plus agent-scoped retrieval (src/knowledge.ts). Knowledge base creation and settings, collections, document edits, version creation and approval, sources, retrieval events and evaluations are Python only. tests/fixtures/knowledge/ holds byte copies of the API contract fixtures; refresh them only when the contract changes.
• client.knowledge is a KnowledgeClient built like client.prompts: it calls fetchJson and maps every answer through the prompts acceptApiJson (exported for this, not from index.ts), so refusals are ApiError with the gateway code and details, transport_error and cloud_required are re-raised as ApiError, and invalid arguments throw Error or TypeError before any request. No typed knowledge error classes exist; the code table is unchanged.
• Uploads go through fetchRaw, which shares fetchJson's exchange (base URL, bearer, client headers, body parsing) and sends a Uint8Array<ArrayBuffer>; the SDK copies the caller's bytes first, so mutating them after the call cannot change what was sent, and the lib DOM BodyInit type refuses a SharedArrayBuffer-backed view. application/octet-stream is the default content type because the gateway treats it as undeclared and infers the format from the path extension. Every x-agenomic-* header value is percent-encoded UTF-8 as RFC 3986 requires (encodeURIComponent plus !'()*, so the value equals Python's quote(value, safe="")) and the gateway percent-decodes them all; only the document path keeps / unencoded. Tags are encoded one by one and joined with literal commas, so a tag may not hold a comma.
• Responses are the contract shapes: lists need their array key (knowledge_bases, documents, versions, results, matches, retrievals), single records need their wrapper member, and an answer for another kb_id, document, section, version, job or agent is invalid_response. The wire types are hand-mirrored snake_case interfaces; options are camelCase and converted, and request bodies omit absent members because the gateway refuses unknown ones and the filter and execution members are checked against their lists first.
• Versions are normalized to numbers ("v3" and "3" become 3) with the server grammar; routes whose path names a version take numbers only. An absent version is left out, so the gateway answers with the published version.
• publish, rollback and putAgentKnowledge send If-Match as a quoted integer (publication_generation, the agent config revision). No Idempotency-Key header is sent; there is no retry in this SDK.
• KnowledgeBaseHandle.getSection with a heading sends documentId as the document of the get_section query operation in one request (the query route matches the document id first, then path, file name and title) and keeps only matches of that id; no match is knowledge_section_not_found with status 0.
• waitForJob polls getJob until succeeded, failed or cancelled and returns the job; past timeoutMs it throws knowledge_job_timeout with status 0. Elapsed time is checked before sleeping, so timeoutMs: 0 returns or throws after one read.
• knowledgeTool returns a plain { name, description, parameters, execute } object, with no framework dependency and a JSON schema whose argument names (query, top_k) match the Python tool. execute renders the gateway's delimited context (escaping and the untrusted-data preamble are the server's) and one citation line per result built from ids, path and URI with control characters removed; includeContext: false returns citations only. A gateway refusal returns knowledge search failed: <code> so the model reads it; cloud_required and argument errors reject. With agentId, version is refused and the execution identity comes from the options merged with the per-call context.execution.
• knowledge.retrieve joins TrackingEventType (a type union, no runtime allowlist exists in this SDK).

SDK wire conformance (PRA-04, PRA-05, D8, D9)

The gateway DTOs are the source of truth; SDK public signatures stay stable.

• /v1/traces and /v1/traces/batch take {agent_id: UUID, external_id, payload, events:[{event_type, payload}]} (batch wraps in {items}). SDK envelopes use agent://org/name, so both SDKs resolve the reference to the registered agent UUID (UUID passthrough, explicit agent_ids/agentIds map, else GET /v1/agents matching slug or name against the last path segment; cached). Unknown agent raises instead of sending a body the gateway rejects.
• Python upload_bundle sends JSON {agent_id, version, hash:"", metadata, archive_base64} (the server recomputes the Merkle hash and accepts an empty one). version is a new optional kwarg, default parsed from name-X.Y.Z.bundle....
• There is no gateway ATEP segment route. upload_atep_segment reads the segment and posts each event to POST /v1/governance/events with source: "atep".
• get_replay_report uses /v1/replay-jobs/{id}/report.
• Python TrackingResource.start gains baseline, allowed_tools (merged into baseline) and parent_session_id, sent only when set.
• TS TrackingEventType now equals the Python vocabulary; the gateway accepts any type string.
• TS sendTraceToHttp keeps posting to the given endpoint URL; the agent lookup derives the base by stripping /v1/traces.