tutti/docs/conventions/api-contracts.md

API Contracts

Use OpenAPI as the single source of truth for daemon HTTP contracts.

Source Of Truth

The canonical daemon API contract lives at:

services/tuttid/api/openapi/tuttid.v1.yaml

Generated outputs derive from that spec for:

• Go transport types and server contract code under services/tuttid/api/generated
• TypeScript client output under packages/clients/tuttid-ts/src/generated

Shared workbench snapshot schemas are the one exception inside the OpenAPI components section. Their canonical source lives at:

packages/workbench/snapshot/src/schema.json

The OpenAPI WorkbenchSnapshot* component schemas are synchronized from that shared package so the open-source desktop and TSH can reuse the same workbench snapshot contract while tuttid still exposes a normal OpenAPI transport contract. The daemon workspace service also consumes a generated Go contract file derived from the same shared snapshot sources for schema-version, enum, and limit validation.

WorkbenchSnapshot* is an explicit shared-contract exception to the usual "generated code stays in transport" default. When it avoids duplicate hand-maintained mirrors, the synchronized Go snapshot contract may be reused inside packages/workbench/service, with services/tuttid/service/workspace consuming that shared package as a host adapter. This exception applies to the shared workbench snapshot contract only, not to arbitrary generated request or response DTOs.

The shared business event stream contract is the other explicit repository exception to the HTTP OpenAPI source-of-truth rule. Its canonical sources live at:

packages/events/protocol/schemas/**/*.json
packages/events/protocol/definitions/**/*.event.json

Those file-based sources generate:

• TypeScript protocol contracts, validators, and topic registry metadata under packages/events/protocol/src/generated
• Go transport contracts and topic registry metadata under services/tuttid/api/events/generated

This exception is limited to the shared business event protocol boundary. The shared package owns the schema-first event sources and the generated TypeScript-facing protocol surface. The daemon still owns its WebSocket route, its authoritative event catalog composition, and the generated Go transport outputs that live under services/tuttid/api/events/generated.

This exception does not create a second source of truth for daemon HTTP routes or a license to hand-maintain competing event DTOs in desktop or daemon code.

Repository Rules

• change the OpenAPI spec before changing daemon HTTP request or response shapes
• change packages/workbench/snapshot/src/schema.json before changing WorkbenchSnapshot* component schemas in the OpenAPI spec
• do not hand-maintain parallel transport DTOs once the generated boundary exists
• do not hand-edit OpenAPI WorkbenchSnapshot* schemas; run the sync command instead
• do not hand-edit the daemon workbench snapshot contract constants; run the Go sync command instead
• do not hand-edit generated business event protocol TypeScript or Go outputs; run the event protocol generator instead
• do not assume generated Go structs enforce every OpenAPI or JSON Schema constraint at runtime
• keep generated code limited to the transport layer
• exception: the synchronized Go WorkbenchSnapshot* contract may be reused in packages/workbench/service, with host adapters such as services/tuttid/service/workspace consuming that shared package, because it is a repository-owned shared contract rather than an arbitrary route-local DTO
• exception: the shared business event protocol sources live in packages/events/protocol, while daemon-owned generated Go transport outputs live in services/tuttid/api/events/generated; keep daemon-side event-route orchestration, catalog composition, and business workflows hand-written
• keep business rules, orchestration, and persistence hand-written
• keep compatibility aliases such as /healthz out of the versioned generated client surface unless they are part of the intended public contract

Agent Provider And Target Identity

Agent provider values are an open, validated execution identity. OpenAPI, generated clients, AgentGUI, and Workbench must preserve an unknown valid provider string instead of coercing it to a built-in provider. Closed enums are appropriate only for preferences that intentionally select among built-in defaults.

AgentTarget.launchRef is a discriminated union. builtin_local is the canonical built-in discriminator and agent_extension identifies a fixed, verified extension installation. The daemon may accept legacy local_cli data while reading durable state, but API output and new writes must never emit it. Add a new union member before adding a new launch mechanism; do not overload a provider string with launch or installation state.

Agent Provider CLI Update Status

Provider status is local by default. includeUpdates is the explicit opt-in for cached remote update discovery. refresh bypasses only local readiness; refreshUpdates bypasses only update metadata and has no effect unless includeUpdates is also true. Keep includeNetwork independent from both.

Every provider status carries a provider-neutral update object. Nullable updateAvailable distinguishes unchecked or non-comparable state from a known up-to-date result. Remote discovery errors belong in update reasonCode and must not turn a valid local readiness snapshot into an HTTP failure.

Provider auth status distinguishes credential presence from remote proof: configured means local credentials exist, authenticated means a provider-backed operation succeeded, required means authentication is known to be missing or rejected, and unknown means no settled evidence exists. Clients may use availability.status to decide launchability; they must not coerce configured to authenticated for display or analytics.

update is an explicit action id, not an alias for install. The daemon may offer it only when both the provider descriptor and the resolved installation prove a supported managed source. See Agent Provider CLI Updates.

Error Contract

Daemon API failures should use the shared protocol-error shape in ApiErrorDetails instead of relying on raw natural-language messages.

Rules:

• classify daemon-facing API failures through services/tuttid/apierrors
• treat code as the stable top-level contract for programmatic handling
• use reason to narrow copy lookup within a stable code
• use params only for structured interpolation or machine-readable context
• keep developerMessage diagnostic; it is not a user-facing copy contract
• use correlationId for cross-layer diagnostics when a request needs traceable failure context
• do not make renderer UX depend on exact developerMessage strings
• keep status-code mapping and transport validation at the api seam even when apierrors classifies the failure

Current canonical ApiErrorDetails fields are:

• code
• reason
• params
• retryable
• developerMessage
• correlationId

TypeScript consumers should normalize transport failures through @tutti-os/client-tuttid-ts instead of re-inspecting raw response payloads in each feature. Renderer and preload code may use code, reason, params, and retryable for behavior and i18n lookup, while developerMessage and correlationId remain diagnostic support fields.

Resolved Defaults

When a route returns resolved defaults or effective settings, the response must carry daemon-owned truth rather than echoing request input back to the client.

Rules:

• use explicit fields such as effectiveSettings for daemon-resolved values
• do not mirror request settings back in a response just to help clients keep local fallback state alive
• return null or omit a field when the daemon cannot resolve it
• do not synthesize fallback defaults in renderer code when the daemon leaves a field unresolved

composer-options follows this rule: request settings are input overrides, while response effectiveSettings is the only contract for resolved homepage composer defaults.

The same endpoint accepts an optional section: core returns the model, reasoning, speed, permission, and effective-settings projection; capabilities returns skills, commands, and capability-catalog data; omitted or full preserves the combined response for compatibility. Sectioned responses are additive projections, not alternate sources of resolved settings.

Desktop Agent Conversation Detail Mode

agentConversationDetailMode is a global desktop preference, not a provider-specific composer default. Keep it on the top-level desktop preferences contract and the matching desktop preferences event payload; do not place it under agentComposerDefaultsByProvider.

The stored value is the enum coding | general. Daemon and desktop shared normalizers must treat missing, empty, or unknown values as coding so migrated profiles keep the engineering-oriented default. coding does not inject extra prompt guidance; it leaves provider defaults intact. general injects the Codex-style Non-technical UI developer instruction section for new agent sessions. For Codex app-server sessions, inject this through the session-scoped Codex config before thread creation, not as a repeated per-turn turn/start.collaborationMode.settings.developer_instructions override. The same Codex session config should also include a Tutti-owned diagnostic marker under [tutti] conversationDetailMode = "coding" | "general" so runtime inspection can distinguish the global Tutti setting from Codex's own desktop preferences. Do not confuse that with Codex collaboration mode presets: when collaborationMode/list returns Default or Plan developer_instructions, the Codex app-server adapter must pass the active preset instructions in turn/start.collaborationMode.settings.developer_instructions so the active mode matches Codex App behavior. Plan Mode and explicit planning-only flows remain higher priority than conversation detail mode prompt guidance.

Deleted Agent Conversation Retention

deletedAgentConversationRetentionDays is a device-global desktop preference and must stay aligned across the OpenAPI DesktopPreferences schema and the desktop preferences event schema. It is the closed integer set 15 | 30; the daemon normalizes missing durable values to 30 and rejects other transport values. The renderer must publish the complete preference object through the existing authoritative preference event flow rather than storing this setting locally.

The Workspace deleted-conversation collection is /v1/workspaces/{workspaceID}/deleted-agent-sessions:

• GET lists topmost deleted Session components: either a canonical root or a child whose parent is not deleted. searchQuery searches titles only; projectPath selects one exact original project, while projectScope=unscoped selects Sessions without a project. Omitting both is the all-project default. cursor and limit provide stable updatedAtUnixMs DESC, agentSessionId ASC paging.
• The list response includes filtered totalCount, unfiltered workspaceTotalCount, and all original non-empty project paths as projectOptions, including paths whose project registration is unavailable. A row explicitly reports whether it is restorable and why a legacy tombstone is unavailable.
• POST .../{agentSessionID}/restore restores the exact complete component without starting provider work. DELETE .../{agentSessionID} permanently removes one topmost deleted component, and collection DELETE permanently removes every topmost deleted component in that Workspace regardless of visible filters.

Permanent-delete endpoints return only aggregate Session, Message, and payload byte counts. They use the daemon idle gate; restore does not. The API reports an idle conflict as service unavailable and a maintenance failure as a Workspace operation failure. Ordinary and typed high-risk confirmations are desktop interactions, not HTTP request fields. Canonical deletion, Tutti Mode cleanup, and the durable Session-scoped runtime/copied-attachment cleanup item commit together. Because the current runtime and copied-attachment roots are keyed only by Session ID, a pending item fences reuse of that ID across all Workspaces; filesystem cleanup failure does not change the successful HTTP result and is retried in a later idle window.

POST /v1/agent-maintenance/deleted-conversations/purge remains the daemon-wide maintenance sweep without a Workspace path. Automatic retention is daemon-owned and is not exposed as a second client scheduler. After an explicit daemon-wide sweep, the daemon may make a strictly bounded best-effort compaction attempt for a small database with substantial free pages; this optional post-step is not run by automatic maintenance and is not part of the aggregate response contract.

Desktop Lab Preferences

lab is a top-level desktop preference group and must stay on both the DesktopPreferences OpenAPI schema and the matching desktop preferences event payload. It is not renderer-local state and it is not part of provider-specific composer defaults.

The group owns:

• enabled: whether the hidden Lab settings tab is exposed after the developer panel is visible.
• features: per-experiment toggles such as AgentGUI composer worktree launch and workbench lab shortcuts.
• shortcuts: user-configured workbench shortcut bindings. Missing, empty, or over-length bindings normalize to unbound/null before publishing.

Renderer settings may optimistically update Lab preferences, but the daemon desktop preferences store and preferences.desktop.updated event remain the authoritative durability and broadcast path.

Runtime Validation

OpenAPI and generated files define the transport interface, but generated Go decoding is not a complete schema validator. In particular, ordinary struct decoding does not reject unknown JSON fields just because a schema says additionalProperties: false.

When a request schema relies on constraints that generated code does not enforce, choose one explicit validation strategy at the api seam:

• configure the generated decoder or runtime to enforce the constraint
• validate the raw request body against the canonical schema before mapping it to generated types
• add a narrow hand-written transport validator in api that checks only the missing generated-runtime guarantees

Do not push transport-shape validation into service. The service interface should receive transport-agnostic input that has already crossed the HTTP contract seam.

For WorkbenchSnapshot*, transport ownership still remains in api: HTTP decoding, route-specific validation strategy, and status-code mapping stay at the API seam even when host services consume the synchronized shared snapshot contract through packages/workbench/service.

Add route tests for schema constraints that matter to daemon behavior and are not obviously enforced by the generated runtime. Examples include unknown-field rejection, object closure, array size limits, and numeric min/max constraints.

Tooling Rules

• run pnpm generate:api when the OpenAPI contract changes
• run pnpm check:api-generated before finishing API contract changes; this also runs pnpm check:agent-protocol-enums, which fails when the closed agent turn/interaction enums in tuttid.v1.yaml drift from the activity.updated event schema (packages/events/protocol/definitions/agent/activity.updated.event.json)
• run pnpm sync:workbench-openapi-schema after changing the shared workbench snapshot schema
• run pnpm check:workbench-openapi-schema when you only need to check that the shared snapshot schema and OpenAPI component schemas are aligned
• run pnpm sync:workbench-go-contract after changing shared workbench snapshot schema or limits that daemon validation depends on
• run pnpm check:workbench-go-contract when you only need to check that the generated shared Go workbench snapshot contract is aligned with the shared snapshot sources
• run pnpm generate:event-protocol after changing shared business event protocol schemas or event-definition files
• run pnpm check:event-protocol-generated when you only need to check that the generated TypeScript and Go event protocol outputs are aligned with the shared event sources
• keep generator versions pinned in repository-managed dependencies or Go tool directives

Scope Guidance

Generate:

• path and method contracts
• transport request and response models
• server interfaces and route glue
• shared TypeScript SDK surface

Do not generate:

• daemon business logic
• daemon persistence adapters
• Electron lifecycle code
• renderer workflows
• desktop IPC contracts that are not direct HTTP projections