@keeptrusts/agent 0.1.0 adapter status

:::danger Do not adopt version 0.1.0

This unlisted page is retained as a version-specific implementation record, not as a supported runtime-adapter guide. Use the supported TypeScript Agent Workflow for new integrations.

:::

The 0.1.0 Agent SDK implements gateway transport and request-context helpers, but its ordinary Node.js entrypoint and several higher-level API helpers are not production-ready. Use this page to distinguish implemented adapter code from an end-to-end supported integration.

Adapter map

Runtime concern	Current implementation	Status
OpenAI-compatible model traffic	createOpenAIAgentTransport	Implemented and unit-tested; package entrypoint limitation still applies.
Custom fetch model traffic	createKeeptrustsFetch	Implemented and unit-tested. Add your own Content-Type for JSON bodies.
Agent identity and correlation	withTracing, createTracingHeaders	Implemented with AsyncLocalStorage, UUID request IDs, and W3C traceparent.
Existing-call wrapper	withKeeptrustsContext	Adds agent and tracing headers to a request object with a headers field.
Claude and Codex configuration	buildClaudeConfig, buildCodexConfig	Object builders only; no adapter executable or orchestration is included.
Event and spend reads	getAgentEvents, getAgentStats, getSpendAttribution	Exported, but incompatible with current API response contracts.
Evidence collection	buildEvidenceBundle and related helpers	Exported, but incompatible with current trail routes and shapes.
MCP tool discovery	createMcpGatewayClient, getMcpTools	Not protocol-compliant with the published streamable-HTTP endpoint.

Request context lifecycle

The implemented transport path is:

1. withTracing(agentId, callback) creates a UUID x-request-id and a W3C traceparent and stores them in an async context.
2. createKeeptrustsFetch reads that context at request time.
3. The transport adds x-keeptrusts-agent-id, x-request-id, and traceparent to the gateway request.
4. It adds Authorization: Bearer <gatewayApiKey> unless the caller already supplied authorization or selected authScheme: "none".

Generate a new context for each logical model request. A request ID used with the trail lookup route must be a UUID; the default generated by withTracing satisfies that requirement.

The gateway does not retain that hyphenated UUID text unchanged on a control-plane decision event. It stores the UUID as 32 lowercase hexadecimal characters without hyphens. The trail lookup parses either UUID notation, but GET /v1/events?request_id=... performs an exact text match. Remove the hyphens from context.requestId before using it as an event filter.

Credential handling

The adapter's gatewayApiKey authorizes model traffic at the gateway. The control-plane bearerToken authorizes agent, event, and trail APIs. They are not interchangeable contracts.

buildClaudeConfig and buildCodexConfig place the gateway credential in the child environment under the key KEEPTRUSTS_API_TOKEN. Do not mistake that generated child-process value for the control-plane bearer token.

Claude and Codex builder boundary

The builders default to local files named ./claude-agent-adapter.mjs and ./codex-agent-adapter.mjs. Those files are not included in @keeptrusts/agent. The returned objects are useful only when your application already owns a compatible adapter process and explicitly supplies its command, arguments, and environment.

Operational checks

For a supported direct gateway integration:

1. Confirm the request uses a gateway access token, not the control-plane token.
2. Confirm x-keeptrusts-agent-id is the ID of an existing agent.
3. Confirm x-request-id is a UUID you retain for event correlation.
4. Query /v1/events with an authenticated control-plane token, a required since value, the agent ID, and the request ID with UUID hyphens removed.
5. Read event fields as event_id, timestamp, event_attribution, and event_cost_attribution.

Next steps

• Supported TypeScript Agent Workflow
• Agent SDK Configuration
• Agent SDK Observability
• Agent SDK MCP Boundary