@adecore/agent-contracts

The Zod schemas and TypeScript types that an agent chat host and its clients share: the frames on the wire, the requests and events, a chat and its items, providers and their models, accounts, tasks, worktrees and usage. The package opens no connection, starts no process and makes no permission decision. It runs in a browser, a preload and a Node or Bun backend alike.

import { AGENT_REQUEST_SCHEMAS, parseRequest } from '@adecore/agent-contracts';

@adecore/agents is a host that answers these requests, and @adecore/agents-react draws a chat from them. Either side can be your own: the schemas are the contract, not the implementations.

Install

bun

bun add @adecore/agent-contracts

npm

npm install @adecore/agent-contracts

pnpm

pnpm add @adecore/agent-contracts

Zod 4 comes along as a dependency. There is no CSS and there are no words to load.

A first check

A schema parses what crosses a boundary and throws on what does not fit. A type inferred from a schema describes the parsed output.

import { AGENT_REQUEST_SCHEMAS, ChatAttachmentUploadSchema } from '@adecore/agent-contracts';
import type { ChatSendPayload } from '@adecore/agent-contracts/chat';

const message: ChatSendPayload = {
    chatId: 'chat-1',
    text: 'Read the attached note.',
    attachments: [ChatAttachmentUploadSchema.parse({ name: 'note.txt', mime: 'text/plain', data: 'SGVsbG8=' })]
};

const payload = AGENT_REQUEST_SCHEMAS['chat.send'].payload.parse(message);
const result = AGENT_REQUEST_SCHEMAS['chat.send'].result.parse({ queued: false });

.parse() throws a ZodError; .safeParse() answers { success, data } or { success, error }. Object schemas are z.object, so a parse strips keys the schema does not know. Few fields have a default: an optional field that was left out stays absent, and the reader decides what absent means. The pages say it where that matters, such as an account without enabled, which is on.

Entry points

The root exports everything below. Each group also has a subpath of its own, which a bundler can split on.

Import	What it holds
@adecore/agent-contracts/envelope	The frames: request, reply, event, WireError, parseRequest, parseServerFrame. See Protocol.
@adecore/agent-contracts/port	FramePort, types only.
@adecore/agent-contracts/protocol	AGENT_REQUEST_SCHEMAS, AGENT_EVENT_SCHEMAS, EmptySchema and their key types.
@adecore/agent-contracts/chat	A chat, its items, events, attachments, requests, bookmarks, forks. See Conversation.
@adecore/agent-contracts/model	Models, catalogs, selections, capabilities, runtime modes, resumeCommandFor.
@adecore/agent-contracts/provider-accounts	Account ids, records, variables, statuses and the account requests.
@adecore/agent-contracts/agent	AgentKind, AgentStatus, a terminal agent's info and its approvals.
@adecore/agent-contracts/task	Tasks between chats and TaskChangedEventSchema.
@adecore/agent-contracts/worktree	Git worktree metadata and the work in one.
@adecore/agent-contracts/usage	Token totals, usage summaries, prices, plan limits.
@adecore/agent-contracts/visual	A chat's visuals, the bridge to their page, its theme and its bootstrap. See Visuals.
@adecore/agent-contracts/ids	SessionIdSchema and SessionId.
@adecore/agent-contracts/text	clipText.

The source has every field with a comment on what it means.

Where to go next

• Protocol: frames, the request and event tables, replay after a reconnect, and adding requests of your own.
• Conversation: a chat's info and items, attachments, approvals and questions, bookmarks and checkpoints.
• Visuals: pages an agent publishes in a chat, the bridge between a page and the app, and the theme it is drawn in.
• Providers and accounts: agent kinds, model catalogs, capabilities, runtime modes and accounts.
• Tasks and usage: tasks between chats, worktrees, token totals, summaries and plan limits.