AGENTS.md

1# Schema Package Guide
2 
3`@opencode-ai/schema` owns browser-safe wire and storage contracts shared by protocol, server, core, and generated SDKs. Keep runtime behavior, service layers, side effects, and host-local implementation details in the domain package that owns them.
4 
5## Package Boundary
6 
7- Preserve the dependency direction: `@opencode-ai/schema <- @opencode-ai/protocol <- @opencode-ai/server`.
8- Schema values should be serializable contract definitions, not service implementations or runtime registries.
9- A domain may keep a minimal public wire contract here when SDK generation needs it, but do not move the broader runtime model into Schema just because an event is public. `plugin.added` is the current example: Schema may own the minimum browser-safe event payload, while plugin runtime behavior stays outside Schema.
10- The root barrel exports canonical current domain contracts. Specialized event modules, manifests, infrastructure modules, and V1 contracts use direct entrypoints instead of becoming first-class root exports.
11 
12## Current Versus V1
13 
14- Current contracts are unversioned: use names like `Session`, `Permission`, `Question`, and identifiers like `Permission.Request`.
15- Legacy contracts retained for active compatibility, persistence, or migration are explicitly `V1`: use names like `SessionV1`, `PermissionV1`, and identifiers like `PermissionV1.Request`.
16- Do not preserve `V2` as the permanent name for the replacement architecture. Remove `V2` from current namespaces, brands, and identifiers as the contracts are normalized.
17- Retained V1 contracts should live under a dedicated `src/v1/` subtree once the V1 isolation PR runs. New/current code must not depend on that subtree.
18- V1 coexistence is temporary. Keep compatibility entrypoints only where migration requires them, and delete the V1 subtree when the legacy runtime is retired.
19- `@opencode-ai/protocol` and `@opencode-ai/sdk-next` are current `/api/...` surfaces.
20 
21## Events
22 
23- Classify event definitions by protocol role before adding them to a public manifest: `current`, `shared transitional`, or `V1-only`.
24- Being emitted by V1 is not enough to include an event in Protocol or SDK Next.
25- Keep clearly V1-only events, such as `message.updated` and `message.part.*`, out of the current Protocol/SDK Next event surface unless a current-client requirement is documented.
26- Keep compatibility events available only to the existing App/TUI/CLI compatibility surface while they are still needed.
27- Preserve a single canonical event definition. Do not duplicate definitions for generation convenience.
28 
29## Module Shape
30 
31- Use one canonical exported value for each contract. Avoid bridge aliases such as `PluginID`, `PluginEvent`, `PtyInfo`, `PtyEvent`, and `SessionTodoInfo`.
32- Prefer importing the schema module namespace and reading canonical members, for example `Plugin.ID` or `SessionTodo.Info`.
33- Core may compose Schema contracts with runtime behavior into a deliberate domain facade, but the facade must re-export the exact canonical Schema value. Do not create a second schema identity.
34- Use flat top-level exports plus the package's existing namespace projection pattern, for example `export * as SessionMessage from "./session-message"`.
35- Keep standalone ID modules only when they prevent real cycles or heavy dependency edges. Inline one-off IDs into their owning contract module when no cycle exists.
36 
37## Naming
38 
39- Exported schema values and namespace objects use `PascalCase`.
40- Schema-building functions and combinators use `camelCase`.
41- The package's static-method combinator is `statics(...)`.
42- Keep descriptive schema value names such as `PositiveInt`, `NonNegativeInt`, `AbsolutePath`, `RelativePath`, and `DateTimeUtcFromMillis`.
43 
44## Optional Fields And Defaults
45 
46- Use the package `optional(...)` helper for optional object properties, including nested structs and event payloads, so encoded objects omit `undefined` keys.
47- Use raw `Schema.optional(...)` only when preserving `undefined` as an explicitly encoded property is intentional and documented.
48- External convenience defaults are normally decode-only with `Schema.withDecodingDefault(...)`.
49- Add constructor defaults only when the domain value itself requires construction-time normalization.
50 
51## Public Types
52 
53- Public `Schema.Struct` records use same-name interfaces:
54 
55```ts
56  export interface Info extends Schema.Schema.Type<typeof Info> {}
57  export const Info = Schema.Struct({ ... })
58```
59 
60- Use type aliases for unions, scalars, arrays, branded scalar types, and event payload helper types.
61- Closed documented string sets use `Schema.Literals(...)`. If arbitrary strings are valid, document the field as arbitrary rather than listing a closed set.
62 
63## Mutability
64 
65- Public Schema contracts are readonly by default.
66- Do not use `Schema.mutable(...)` in public contracts for runtime convenience.
67- Runtime code that needs mutation should opt in at the boundary with `Types.DeepMutable`, a purpose-built draft type, or another explicit mutable API.
68 
69## Unknown Values
70 
71- Current public contracts avoid `Schema.Any`.
72- Use `Schema.Json` for values that must be JSON-serializable.
73- Use `Schema.Unknown` for genuinely opaque values that require consumer-side narrowing.
74- Keep `Schema.Any` only at an explicitly unsafe compatibility boundary with a documented reason.
75 
76## IDs And Identifiers
77 
78- Current ID constructors expose `create()`.
79- Directional constructors such as `ascending()` or `descending()` remain only where ordering semantics are part of the public contract or compatibility requires the old method.
80- New generated ID schemas must validate exactly the prefix they emit, including the underscore.
81- Do not tighten legacy loose ID validators without an explicit compatibility and migration decision; existing callers and tests may rely on accepted non-canonical IDs.
82- Reusable exported public schemas get stable, domain-qualified identifiers such as `Model.Ref` or `Agent.Color`.
83- Public schema identifiers and brands must be unique and stable. Private one-use nested schemas may remain anonymous.
84 
85## Tests For Contract Changes
86 
87- Add focused tests when changing contract behavior or generated surface.
88- Cover optional properties omitting `undefined`, no accidental current-contract `Schema.Any`, stable and unique public identifiers, exact facade/schema identity, and current Protocol manifests excluding V1-only events.
89