@kilnai/gateway-contracts

Shared HTTP and WebSocket frame contracts for the Kiln operator gateway.

Both the runtime gateway (@kilnai/runtime) and the operator clients (@kilnai/gui, @kilnai/native, @kilnai/tui, SDK, and widget) depend on this package so that frame shapes and shared operator projections are defined once and consumed by every surface. Neither side defines its own copy of these types; any shape change is made here and takes effect on the next build for all consumers.

Operator Event Presentation

Canonical session_event frames carry structured payload data for durable runtime facts. Operator surfaces must keep that structure for state derivation, but normal GUI/TUI rendering should not serialize the payload as raw JSON.

src/operator-event-presentation.ts owns the shared projection from canonical operator events to display-safe presentation:

• presentOperatorSessionEvent(event) maps an event to title, summary, tone, details, and compactText.
• presentOperatorEventPayload(kind, payload) supports projections when the consumer already has the event kind and payload separated.
• formatOperatorEventValue(value) is the compact scalar formatter for inline previews. Nested objects become Structured value instead of JSON text.

GUI and TUI may render those projections differently, but they should consume this shared presenter instead of duplicating event-specific display logic.

Operator Surface Capabilities

src/operator-surface-capability.ts defines the shared surface vocabulary and capability negotiation contract for CLI, TUI, GUI, native, IDE, SDK, widget, gateway, and runtime consumers.

Capability snapshots advertise what a surface can support without granting authority. The native surface starts with explicit capability slots for gateway attach, session projection, native window lifecycle, surface performance telemetry, embedded-browser host proof, and native cockpit contract readiness. Browser session projections use explicit transport labels such as snapshot-polling, cdp-screencast, electron-webcontents, webrtc, and hosted-url so surfaces can distinguish artifact monitors, frame streams, native embedded hosts, and remote live views without inferring behavior from package names or local feature flags.

src/operator-cockpit-benchmark.ts and src/operator-cockpit-target.ts define shared native cockpit benchmark contracts for high-density cockpit comparison. src/operator-cockpit-projection.ts defines the shared read-only cockpit projection over canonical events and explicit attach targets. GUI and native must use the same synthetic event fixtures, shared presentation baseline, shared read-only projection baseline, read-only instance/session/timeline/invocation/tool/resource/cost projections, explicit instance/session targets, read-only action intents, and cancellation request validation before any native cockpit or Rust hot-path claim is considered. The read-only projection baseline measures the same shared projection substrate later surfaces and Rust/WASM/sidecar candidates must match; it is not a browser-rendering benchmark. The shared read-only attach plan validates explicit local, remote, team, cloud, CI, or simulated gateway URLs and records planned HTTP/WebSocket connection intent without opening sockets. Resource links are projected as target-aware read-only resources carrying resourceUri, so surfaces can prepare open-resource affordances without parsing raw tool payloads. Read-only action intents are target-checked plans only; they do not dispatch gateway mutations and explicitly exclude cancellation. src/operator-cockpit-view-state.ts derives read-only focus/filter/replay cursor state from that same projection with explicit dispatch: not-dispatched and mutationDispatch: disabled metadata, and fails closed when targets do not resolve. Timeline filters use projected targets such as managedInvocationId, toolCallId, and resourceUri rather than raw event payload parsing. Session, managed-invocation, and tool-call filters require their enclosing instance/session target. measureOperatorCockpitReadOnlyViewStateBaseline measures only TypeScript view-state derivation over that shared projection substrate. It is contract measurement only and not a browser benchmark, native rendering benchmark, network attach benchmark, dispatch benchmark, or Rust/WASM/sidecar proof. createOperatorCockpitBenchmarkEvidenceReport is the shared promotion gate over those benchmark outputs. It records implemented evidence, missing evidence, promotion eligibility, and Rust-candidate eligibility while defaulting to contract-only recommendations when only shared TypeScript baselines exist. Phase 3 benchmark evidence is expressed through typed report contracts for browser rendering, native rendering, target clarity, interaction latency, and memory. These contracts are auditable metadata shapes only; they do not run benchmarks, attach to gateways, dispatch actions, or provide Rust proof. Phase 3 Slice 1 also adds runner admission/workload validation through createOperatorCockpitBenchmarkRunnerAdmission for web-gui and native-cockpit surfaces, browser-rendering and native-rendering runner kinds, and single-session-heavy/multi-session/multi-instance workloads. This contract keeps execution: not-started, mutationDispatch: disabled, and networkAttach: not-started, and fails closed on mismatched surface/runner pairs via surface-runner-mismatch. It also fails closed on contradictory or invalid fixture summaries (for example, activeManagedSessionCount > sessionCount) before workload thresholds are evaluated. Phase 3 Slice 2 adds orchestration planning through createOperatorCockpitBenchmarkRunnerOrchestrationPlan. Planning becomes planned only when both web and native admissions are already admitted for the same workload kind and fixture summary; otherwise it fails closed with typed blocked reasons. It keeps execution: not-started, mutationDispatch: disabled, networkAttach: not-started, and recommendation/evidence: not-promoted. It is not a rendering runner, network attach runner, dispatch mechanism, or Rust proof implementation.

Managed child invocation events carry an operator-facing OperatorManagedAgentCapabilitySnapshot. The snapshot records the admitted route id/health, provider-model proof, adapter/execution mode, authority profile, context mode, resource-plane availability, and child identity. SDK, widget, GUI, TUI, CLI, and future consumers should display or audit this snapshot instead of recomputing provider health or model capability from live configuration after the fact.

Presentation Intent

src/presentation-intent.ts defines the closed semantic display contract for model/tool-proposed rich output. A tool may include metadata.presentationIntent or an equivalent structured envelope field, but the shared presenter validates it before any operator surface sees it as toolPresentation.presentationIntent.

Allowed intent kinds are intentionally small:

• summary
• comparison_table
• risk_matrix
• timeline
• resource_bundle
• diagnostic_report

Invalid or unsupported intents are ignored and the tool falls back to normal typed output projection. Presentation intent never grants authority, never selects arbitrary UI components, and never accepts HTML/CSS/JS/JSX/SVG payloads. GUI, TUI, CLI, SDK/widget, and future surfaces receive the same validated data and degrade to formatPresentationIntentAsText() when a native rich renderer is not available.

Operator Empty State Copy

The shared operator empty-state phrase catalog lives in src/operator-empty-state.ts. GUI uses it for the empty transcript rotation; TUI uses the same copy for its idle input placeholder because the terminal surface has no separate empty transcript canvas.

Keep this copy short, command-oriented, and Kiln-native. It may lean cyberpunk in tone, but it must stay original and avoid copying exact lines or named character voice from external games.

Operator Workspace Explorer

The shared read-only workspace explorer contract lives in src/workspace.ts. It defines governed directory snapshots, file-preview snapshots, VCS status, and typed workspace errors for all operator surfaces.

Consumers should treat this as navigation and preview state only:

• OperatorWorkspaceDirectorySnapshot is a bounded directory listing rooted at the active working directory.
• OperatorWorkspaceTreeEntry may carry optional vcs status so GUI, TUI, CLI, and future surfaces can render working-tree state consistently.
• OperatorWorkspaceFileSnapshot carries conservative previews for text/code, Markdown, JSON, supported web images, or explicit unsupported/binary states.
• Workspace previews must not create session events, approval requests, provider tool calls, changed-file entries, or working-tree mutations.

VCS status is the current working tree. It is deliberately separate from session-scoped Changed files, which is durable runtime evidence emitted by tools and session events.

Operator Themes

The shared operator theme catalog lives in src/operator-themes.ts. OPERATOR_THEME_NAMES, labels, palettes, and validation helpers are consumed by the GUI, TUI, CLI config parsing, and runtime operator-surface tools. Add or remove operator themes here first, then update each renderer to consume the same contract instead of maintaining a private list.

The catalog is intentionally curated as Kiln identity, not a generic collection of popular editor themes:

• kiln-dark / Kiln Obsidian: the default near-black control surface.
• kiln-graphite: a slightly lifted dark surface for brighter environments.
• kiln-light / Kiln Paper: the light counterpart for OS or operator preference.
• system-follow: a polarity resolver for surfaces that can observe OS theme.

system-follow is part of the contract for config parity. GUI resolves it against the browser/OS color preference; TUI accepts it but maps it to a terminal-safe dark palette.