Assistant Protocol Package

@maya/assistant-protocol is the shared TypeScript contract package for Maya assistant protocol shapes. The root export stays on stable app-level contracts; the official subentry owns official-shaped Claude web request validators, response payload types, SSE payload helpers, default model/tool manifests, settings/project/directory DTOs, and evidence scenario metadata.

Install

pnpm add @maya/assistant-protocol

The package has no runtime dependency on a browser, server, or network client. It validates and transforms plain JavaScript objects.

Exports

Export	Purpose
@maya/assistant-protocol	Stable app-level protocol contracts and defaults without Official*, storage, chunk, or wire payload exports.
@maya/assistant-protocol/auth	Auth-start request helpers and auth payload types for lightweight login consumers.
@maya/assistant-protocol/official	Official-shaped wire DTOs, request helpers, auth helpers, stream helpers, settings/project/directory metadata, and default manifests.
@maya/assistant-protocol/package.json	Package metadata for tooling.

Request Helpers

Protocol request helpers enforce official key boundaries before adapters serialize JSON. Use them at every UI, backend, evidence, and test boundary that creates a request body.

import { officialChatCompletionRequestBody } from '@maya/assistant-protocol/official';

const body = officialChatCompletionRequestBody({
  prompt: 'hello',
  timezone: 'UTC',
  locale: 'en-US',
  model: 'claude-sonnet-4-5',
  effort: 'default',
  thinking_mode: 'off',
  tools: [],
  turn_message_uuids: {
    human_message_uuid: crypto.randomUUID(),
    assistant_message_uuid: crypto.randomUUID(),
  },
  attachments: [],
  files: [],
  sync_sources: [],
  rendering_mode: 'messages',
  create_conversation_params: {
    name: '',
    model: 'claude-sonnet-4-5',
    include_conversation_preferences: true,
    paprika_mode: null,
    compass_mode: null,
    tool_search_mode: 'off',
    is_temporary: false,
    enabled_imagine: true,
  },
});

Stream Helpers

SSE helpers keep event parsing and local UI chunks aligned:

• officialChatStreamPayloadBody validates raw data: payloads.
• officialChatStreamPayload converts local chunks back to official-shaped payloads for mock streams.
• chatStreamChunkFromOfficialPayload converts official-shaped events to UI-friendly ChatResponseChunk values.
• event-type tuples such as officialChatStreamEventTypes are used by contract, evidence, and protocol-key verifiers.

Evidence Coupling

The package is the source of truth for request-key arrays and evidence scenario ids. Capture and verification scripts import the same helpers as the web adapter and backend validation paths, so request shape drift is caught statically or in local contract tests instead of becoming an undocumented UI behavior.

Canonical package docs stay in .docs/packages/assistant-protocol.md. The tarball intentionally excludes package-root README.md, dist/docs/*, and docs/* copies so the protocol package does not publish a second documentation truth. node tools/verify-docs-api-parity.mjs enforces entry-level docs parity for every protocol package export; the large official wire symbol inventory has a single source of truth in projects/claude-protocol/src/official.ts and generated declarations. Run node tools/smoke-consumer.mjs --pack-only and pnpm security:supply-chain after changing package exports, metadata, or publish contents.