@runenv/agent-contracts

Strict, versioned Zod wire contracts shared by RunEnv Agent Guard clients, broker services, and the RunEnv control plane.

Installation

npm install @runenv/agent-contracts

Current package version: @runenv/[email protected]. See CHANGELOG.md for release notes.

Quick start

Parse every external payload at the boundary while it is still unknown:

import {
  agentChangeControlPreviewResponseSchema,
  type AgentChangeControlPreviewResponse,
} from '@runenv/agent-contracts'

export function parsePreview(
  payload: unknown
): AgentChangeControlPreviewResponse {
  return agentChangeControlPreviewResponseSchema.parse(payload)
}

Use safeParse() when validation failure should be handled without an exception:

import { exposureUploadSchema } from '@runenv/agent-contracts'

const result = exposureUploadSchema.safeParse(payload)
if (!result.success) {
  console.error(result.error.issues)
} else {
  sendValidatedUpload(result.data)
}

The schemas validate or reject data; they do not sanitize an unsafe payload. Build redacted wire payloads before parsing them.

Contract families

| Family | Version | Purpose | | --- | --- | --- | | Exposure diagnostics | EXPOSURE_SCHEMA_VERSION = 1 | Device-local exposure reports and privacy-preserving upload DTOs | | Agent Guard broker | v1 | Capabilities, previews, permits, execution status, cancellation, and rollback responses | | Agent Change Control | AGENT_CHANGE_CONTROL_CONTRACT_VERSION = 2 | Governed preview, approval, execution, verification, compensation, event, policy, and control-state DTOs | | Private Gateway | PRIVATE_GATEWAY_CONTRACT_VERSION = 1 | Enrollment, key rotation, heartbeat, leased jobs, credential references, results, and request proofs |

All contract families are exported from the package root.

Exposure diagnostics

exposureReportSchema validates a bounded device-local diagnostic report. A local report may contain relative paths and keyed credential fingerprints and must not be transmitted.

Before publication, transform the report with toExposureUpload() from @runenv/agent-edge, then validate it with exposureUploadSchema. The upload contract:

• accepts keyed path hashes instead of finding paths;
• omits credential fingerprints;
• requires report-scoped keyed finding IDs;
• removes relative paths from skipped-file metadata;
• caps findings and skipped entries at 500 each; and
• caps scanned bytes at PostgreSQL's signed INTEGER maximum.

Scanner truncation is explicit. ENTRY_LIMIT means the bounded directory-entry budget was exhausted, including ignored, unsupported, unreadable, and symbolic-link entries.

Agent Guard broker contracts

The v1 broker exports exact response schemas for capability discovery, action preview, permit acquisition, execution, status polling, cancellation, and rollback. MCP-specific object schemas preserve the same exact permit and rollback union semantics required at runtime.

Shared safety primitives include:

• agentActionArgumentsSchema for credentialless, JSON-only provider arguments;
• agentPublicJsonSchema for bounded public response bodies;
• agentPublicTextSchema and agentPublicUrlSchema for credential-pattern rejection;
• agentActionNameSchema, agentIdempotencyKeySchema, agentCuidSchema, and agentRiskSchema for shared wire fields.

Agent Change Control v2

The v2 surface models the full governed-change lifecycle for GitHub, Kubernetes, and legacy HTTPS connectors:

• scoped capabilities and connector health;
• server-derived targets and exact-change previews;
• risk factors, preconditions, approval slots, verification, and compensation plans;
• pending and ready permit variants with exact-consent URLs;
• queued through terminal action state, provider-I/O disposition, retry guidance, and signed receipts;
• bounded event timelines, cancellation, compensation, exposure publication, and connector tests;
• non-authoritative policy simulation and effective control-state reporting; and
• a bounded error-code contract that states whether provider I/O may have occurred and whether retry is safe.

Unknown outcomes can advertise only read-only reconciliation guidance. A blind write retry is rejected by the schema.

Private Gateway contracts

Private Gateway schemas bind job envelopes and result attestations to exact gateway, organization, project, connector revision, credential source, package artifact, authority hashes, and control-state snapshots.

Credential references support environment variables, HashiCorp Vault KV v2 references, and Kubernetes projected service accounts. They identify where a gateway resolves a credential; secret values and arbitrary commands are not valid fields. Enrollment and rotation pin Ed25519 signing keys, X25519 encryption keys, and the expected @runenv/private-gateway package identity.

Security guarantees

• Object DTOs are strict. Unknown fields fail validation instead of being silently dropped.
• Public JSON is bounded to 8 levels, 200 entries per object or array, 4,000 characters per string, and 64,000 serialized bytes.
• Credential-shaped field names may contain only the literal [REDACTED] marker in public JSON and action arguments.
• Public text rejects known credential patterns. Public URLs allow only HTTP or HTTPS and reject user information, credential parameters, and credential-shaped path or fragment values.
• IDs, arrays, text, event pages, TTLs, and byte counts are bounded before serialization or expensive processing.
• Approval unions, permit states, compensation availability, terminal outcomes, and retry guidance are cross-checked with schema refinements.
• Private Gateway envelopes accept references and cryptographic bindings, not plaintext connector credentials.

These contracts are a validation boundary, not an authorization system. Callers must still authenticate, authorize, scope database lookups, transform sensitive data, and enforce policy before constructing a response.

Compatibility

• Node.js 20 or newer
• ECMAScript modules (import)
• TypeScript declarations included
• Zod 4 runtime dependency

Strict DTOs intentionally reject unrecognized fields. Coordinate contract upgrades across producers and consumers, and check the exported version constants before exchanging versioned payloads.

License

Apache-2.0. See LICENSE and NOTICE.