@gea-ai/contract
Portable public contracts and shared TypeScript payload types for GEA.
This package owns shared contract-first schemas, inferred TypeScript types, and ORPC contract routers that can be consumed by ORPC implementations and public SDK packages.
Route implementations should import these contracts and use @orpc/server
contract implementers instead of redefining route-local input schemas. Shared
RPC payload types that need to cross package boundaries, such as agent chat
messages and common ORPC error shapes, also live here so web, CLI, SDK, agent,
and ORPC packages derive the same API surface.
Agent snapshots describe native Connector requirements and their exposed
operations. Feishu declares the existing platform Connector's call operation;
its Tool receives lark-cli argv and optional stdin. The platform owns CLI
execution and Connection credentials. Business identity is selected by --as bot
or --as user in each command's argv. Agent and Extension host-command
contributions and Computer CLI preparation are removed.
Already published snapshots remain loadable for Channel operation. Parsing
discards their retired Agent commands and Extension command-contribution
metadata without changing stored artifacts or their hashes. Those fields grant
no execution capability; rebuild an old Agent to declare the Feishu Connector.
agentNodeSnapshotMetadataSchema reuses the canonical model, schema version,
environment, and Computer fields for retained metadata readers. Version summaries
and shared-secret protection can validate those fields independently of execution
admission; runnable snapshots still use the complete snapshot schemas.
Ordinary Computer commands.run and custom Tool command permissions remain
separate capabilities for Agents that explicitly enable a Computer.
App Server absolute-path fields accept POSIX and Windows drive paths, including the verbatim drive form returned by Rust canonicalization on Windows. The contract preserves the native path rather than rewriting project identity; relative and drive-relative paths remain invalid.
Worker contract objects retain concrete Zod schemas and cached field identity.
Private Connector, Core, Session, Channel, and initialization diagnostic subtrees
also use deferredSchemaShape getters: their complete construction expressions stay in
the getter so importing an unused branch does not build its helper schemas.
Keep shared helpers cached, and keep cross-schema .shape reads inside getters;
reading .shape snapshots every field of that object. Composition methods in the
pinned Zod version preserve raw getters, but object spreads evaluate them.
After a contract release, release the SDK against it and rebuild applications to
include these initialization savings.
Model boundary types
@gea-ai/contract/model-contracts owns AgentModelMessage, AgentModelUsage
and AgentFinishReason. Context and Worker AI usage use these structural
contracts. Existing ai message/usage/finish types remain assignable, and the
context API names and generics are preserved. Coordinate contract-before-SDK
releases when migrating these shared types.
Benchmarks API preparation
@gea-ai/contract/benchmarks-api exports independent Project-scoped schemas for
Benchmarks, versions, cases, uploads and runs. @gea-ai/contract/benchmarks-openapi
exports their standalone OpenAPI 3.1 document. These are prepared contracts;
the new routes are not served yet. See the contract boundary
for publishing, scopes, idempotency, JSON limits and pagination semantics.
Public HTTP identity projections
AgentHttpSession from @gea-ai/contract/agent-http-api (also reused by the
ORPC AppAgentSession) now includes optional nullable owner with user_id and
display_name. Administrative list/detail guarantee the property; ordinary and
local producers may omit it. MemberHttpMember / MemberHttpList from
@gea-ai/contract/member-http-api include optional user_id, returned only with
include_user_id=true on member list/detail. These inferred types are canonical
for SDK consumers; no parallel Agent SDK DTO or member HTTP client exists.
Member email is a required nullable contact field (string | null), including
for members created without a real email. Consumers must accept explicit null;
internal authentication handles are not part of this public contact field.
Regenerate external OpenAPI SDKs to expose the query and nullable email. Old member
requests retain the same fields, with nullable email; session clients rejecting unknown fields
must update their schema before consuming administrative responses.