Scitrera Ecosystem Messaging Spec

A universal ChatMessage / ToolCall JSON schema, streaming-event vocabulary, and session attach/recovery protocol for AI agent platforms — transport-agnostic shapes for chat messages, tool calls/results, incremental updates, coherent snapshots, and cursor-based replay, with reference implementations in Go, Python, and TypeScript that are fixture-for-fixture compatible.

It is the wire/at-rest contract used across the Scitrera AI platform, but the schema itself is generic and dependency-light; any agent runtime, frontend, or storage layer can adopt it.

Layout

Path	Purpose
docs/UNIVERSAL_MESSAGE_SPEC.md	Normative spec (v1.0) — the source of truth
docs/SESSION_PROTOCOL.md	Normative session attach/snapshot/replay protocol
docs/TOOL_CATALOG_PROTOCOL.md	Deterministic tool publication, discovery, exact-reference, lease, and cursor contract
docs/WORKSPACE_EXECUTION_PROTOCOL.md	Workspace-view identity and live tool-host binding contract
go/testdata/tool_catalog/	Canonical cross-language tool catalog fixtures
go/testdata/session/	Canonical cross-language session protocol fixtures
go/testdata/workspace_execution/	Canonical cross-language workspace execution fixtures
go/	Go implementation — module github.com/scitrera/ecosystem-messaging-spec/go
python/	Pydantic v2 implementation — scitrera-messaging-spec (PyPI)
typescript/	TS types + pure reducer — @scitrera/messaging-spec (npm)

All three expose the same schema, the same streaming event vocabulary, and an apply_event / applyEvent reducer with matching fixtures.

Install

Go

go get github.com/scitrera/ecosystem-messaging-spec/go

import spec "github.com/scitrera/ecosystem-messaging-spec/go"

m := spec.NewChatMessage("msg_1", spec.RoleAssistant)
m.Content = []spec.ContentPart{spec.NewTextPart("hello")}

Python

pip install scitrera-messaging-spec

from scitrera_messaging_spec import ChatMessage, TextPart
m = ChatMessage(id="msg_1", role="assistant", content=[TextPart(text="hello")])

TypeScript

npm install @scitrera/messaging-spec

import { makeChatMessage } from "@scitrera/messaging-spec";
const m = makeChatMessage({ id: "msg_1", role: "assistant",
  content: [{ type: "text", text: "hello" }] });

See the per-language READMEs (go/, python/, typescript/) and the normative spec for the full schema and the streaming-event reducer.

Status

ChatMessage schema v1.0 is stable across all three languages. Tool transport and session management have independent schema/protocol versions so compatible features do not force a chat-message version bump. See the normative documents for their shapes and versioning rules.

License

Apache-2.0 — see LICENSE and NOTICE.