@farmslot/protocol 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to `@farmslot/protocol` are tracked here.
+
+## Unreleased
+
+- Active-development baseline; add user-facing changes here before release or package publication.

package/README.md

@@ -0,0 +1,213 @@
+# @farmslot/protocol
+
+Shared TypeScript contract for Farmslot gateway, nodes, recipes, runners, and
+artifact packages.
+
+This package is intentionally small at runtime: it exports protocol constants,
+TypeScript types, and validation helpers. It does **not** execute recipes, talk
+to browsers/devices, or contain project-specific actions.
+
+## Canonical documents
+
+The npm package is a consumable API surface. The source-of-truth architecture is
+published on the Farmslot docs site:
+
+- [Recipe Protocol v1](https://farmslot.io/docs/reference/recipe-protocol-v1) — canonical recipe schema, action vocabulary, graph rules, artifacts, and quality rules.
+- [Recipe Runner Protocol](https://farmslot.io/docs/reference/recipe-runner-protocol) — runner-facing manifest and artifact guidance.
+- [Recipe Composition Quality](https://farmslot.io/docs/reference/recipe-composition-quality) — how to keep flows concise, reusable, and reviewable.
+
+If this README conflicts with the public Recipe Protocol v1 reference, the protocol reference wins.
+
+## Install
+
+```bash
+yarn add @farmslot/protocol
+# or
+npm install @farmslot/protocol
+```
+
+## Main exports
+
+```ts
+import {
+  OFFICIAL_RECIPE_ACTIONS,
+  RECIPE_PROTOCOL_SCHEMA_VERSION,
+  getRecipeActionManifestActionNames,
+  getRecipeWorkflowActions,
+  validateArtifactManifestDocument,
+  validateRecipeActionManifestDocument,
+  validateRecipeArtifactPackage,
+  validateRecipeDocument,
+  validateRecipeWithManifest,
+  type OfficialActionName,
+  type RecipeActionManifestDocument,
+} from '@farmslot/protocol';
+```
+
+## Public API map
+
+| Import path                       | Use for                                                                                            |
+| --------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `@farmslot/protocol`              | Preferred root import for common constants, validators, helpers, and shared types.                 |
+| `@farmslot/protocol/types`        | Compatibility import for all shared domain data contracts.                                         |
+| `@farmslot/protocol/types/*.js`   | Focused domain imports such as runs, slots, reviews, family observability, resources, and recipes. |
+| `@farmslot/protocol/methods`      | Compatibility import for all Gateway RPC method contracts.                                         |
+| `@farmslot/protocol/methods/*.js` | Focused RPC imports for one method family such as run, slot, fleet, dispatch, or chat.             |
+
+Prefer focused domain imports when they make ownership clearer. Keep root exports stable for application ergonomics and backwards compatibility.
+
+Key responsibilities:
+
+- define the stable Recipe Protocol v1 action vocabulary;
+- validate recipe documents and workflow graph shape;
+- validate action manifests declared by project runners;
+- validate recipe usage against a manifest;
+- validate runner artifact packages (`recipe.json`, `summary.json`, `trace.json`, `artifact-manifest.json`);
+- share gateway/node/run family types used by Farmslot apps.
+
+## Source layout
+
+The protocol package is organized by contract ownership:
+
+| Path                           | Owns                                                                                 |
+| ------------------------------ | ------------------------------------------------------------------------------------ |
+| `src/index.ts`                 | Package root export surface. Keep it stable and intentional.                         |
+| `src/version.ts`               | Node↔Gateway protocol compatibility version.                                         |
+| `src/frames.ts`                | WebSocket request/response/event frame shapes and binary relay magic bytes.          |
+| `src/events.ts`                | Gateway event names and event payload map.                                           |
+| `src/methods/registry.ts`      | Canonical RPC method string registry.                                                |
+| `src/methods/*.ts`             | Domain-specific RPC params/results and typed method-name maps.                       |
+| `src/types/*.ts`               | Domain-specific data contracts for runs, slots, recipes, reviews, resources, etc.    |
+| `src/types/index.ts`           | Domain type barrel for compatibility; new code should still edit the owner file.     |
+| `src/recipe-compat.ts`         | Recipe Protocol v1 validation, manifest validation, and artifact-package validation. |
+| `src/step-io.ts`               | Worker/runner step IO and artifact reference contracts.                              |
+| `src/agent-roles.ts`           | Agent role labels/window/ranking helpers shared by Gateway and clients.              |
+| `src/github-ref.ts`            | Canonical GitHub PR ref parsing/formatting helpers.                                  |
+| `src/run-family-readiness.ts`  | Shared run-family readiness projection helpers.                                      |
+| `src/surfaces.ts`              | Command Center surface registry used by safe chat/tool routing.                      |
+| `src/tmux-worker-watchlist.ts` | Shared tmux worker watchlist predicates.                                             |
+
+Compatibility barrels (`src/methods.ts`, `src/types.ts`, `src/methods/index.ts`,
+and `src/types/index.ts`) are allowed because this is a consumed package. They
+should only re-export owner modules; do not put implementation logic in barrels.
+
+## Export and versioning rules
+
+- Public package imports must continue to work for:
+  - `@farmslot/protocol`
+  - `@farmslot/protocol/types`
+  - `@farmslot/protocol/methods`
+  - domain imports such as `@farmslot/protocol/types/runs.js`.
+- Add new fields as optional unless every caller is upgraded in the same PR.
+- Bump `PROTOCOL_VERSION` in `src/version.ts` when node↔gateway methods, events,
+  binary frames, or required payload fields change.
+- Keep `package.json` `exports` aligned with any new domain directories.
+- Do not export service internals, UI-only state, or project-specific concepts.
+
+## Recipe validation
+
+```ts
+import { validateRecipeDocument } from '@farmslot/protocol';
+
+const result = validateRecipeDocument(recipeJson);
+if (result.status === 'invalid') {
+  throw new Error(result.findings.map((finding) => finding.message).join('\n'));
+}
+```
+
+`validateRecipeDocument` checks protocol-level structure. It does not prove that
+a project runner can execute every action. Use `validateRecipeWithManifest` for
+that.
+
+## Action manifest validation
+
+Every runner publishes a manifest describing what it can actually execute.
+Official actions come from `OFFICIAL_RECIPE_ACTIONS`; project actions must be
+namespaced, for example `example.trade.place_order` or `checkout.ensure_cart`.
+
+```ts
+import {
+  validateRecipeActionManifestDocument,
+  validateRecipeWithManifest,
+  type RecipeActionManifestDocument,
+} from '@farmslot/protocol';
+
+const manifest: RecipeActionManifestDocument = {
+  runner_protocol_version: 1,
+  action_registry_version: 1,
+  supported_official_actions: ['command', 'wait', 'end'],
+  custom_actions: [
+    {
+      name: 'example.echo',
+      description: 'Echoes a message for adapter smoke tests.',
+      schema: { type: 'object', required: ['message'] },
+    },
+  ],
+};
+
+const manifestResult = validateRecipeActionManifestDocument(manifest);
+const recipeResult = validateRecipeWithManifest(recipeJson, manifest);
+```
+
+A valid manifest must stay honest: declare only actions the runner implements,
+and keep custom actions durable enough to reuse across tasks.
+
+## Artifact package validation
+
+Recipe runs should emit a portable evidence package. Use protocol validation
+before a gateway or reviewer trusts the result.
+
+```ts
+import { validateRecipeArtifactPackage } from '@farmslot/protocol';
+
+const result = validateRecipeArtifactPackage({
+  manifest: artifactManifestJson,
+  artifactPaths: ['recipe.json', 'summary.json', 'trace.json', 'artifact-manifest.json'],
+  recipe: recipeJson,
+});
+```
+
+## Maintenance rules
+
+These rules keep the public contract small and stable:
+
+1. **Protocol owns vocabulary, not project behavior.** Do not add wallet, Perps,
+   checkout, or app-specific actions to the official action list.
+2. **Parameterize before multiplying.** Prefer one configurable action/flow over
+   many near-duplicates.
+3. **Fail closed.** Unknown actions, undeclared preconditions, invalid artifact
+   paths, and malformed manifests should produce validation errors, not warnings
+   that execution ignores.
+4. **No fabricated proof.** Protocol fields must support real user-visible proof;
+   setup can prepare fixtures, but proof-phase recipes must not fake UI/app state.
+5. **Artifacts must be portable.** Paths are relative, secrets are redacted, and
+   summaries/traces must be useful outside the original machine.
+6. **Docs and types move together.** Any field or rule change must update
+   the public Recipe Protocol v1 reference, tests, and exported types in the same PR.
+7. **Tests cover every domain contract.** Domain files need focused tests, and
+   package quality must run the full `src/**/*.test.ts` set.
+8. **Barrels are compatibility only.** Add logic to `src/methods/*`,
+   `src/types/*`, or focused helper owners, never to compatibility barrels.
+
+## Change checklist
+
+Before merging protocol changes:
+
+1. Identify the owner module (`src/types/*`, `src/methods/*`, or focused helper).
+2. Update the owner types/helpers and colocated tests.
+3. Update compatibility exports only if a new public owner module is introduced.
+4. Update canonical docs when Recipe Protocol v1, runner artifacts, or public APIs change.
+5. Run full protocol quality and any affected package/service quality.
+
+## Local quality
+
+From the Farmslot repository root:
+
+```bash
+yarn workspace @farmslot/protocol quality
+# or, for protocol tests through Command Center wiring:
+yarn test:protocol
+```
+
+Do not publish a protocol version unless these pass and the canonical docs match
+the exported API.

package/dist/agent-roles.d.ts

@@ -0,0 +1,15 @@
+import { AGENT_ROLES, type AgentRole, type FlowType } from './types.js';
+export { AGENT_ROLES };
+export declare const AGENT_ROLE_LABELS: Record<AgentRole, string>;
+export declare const AGENT_ROLE_SHORT_LABELS: Record<AgentRole, string>;
+export declare const AGENT_ROLE_WINDOWS: Record<AgentRole, string | null>;
+export declare const AGENT_ROLE_RANKS: Record<AgentRole, number>;
+export declare function primaryRoleForFlow(flowType?: FlowType | string | null): AgentRole;
+export declare function contextIdFor(role: AgentRole): string;
+export declare function agentRoleLabel(role: AgentRole): string;
+export declare function agentRoleShortLabel(role: AgentRole): string;
+export declare function agentRoleWindow(role: AgentRole): string | null;
+export declare function agentRoleRank(role: AgentRole): number;
+export declare function signalFileForTask(taskFile?: string | null): string | null;
+export declare function agentContextTaskFile(taskFile?: string | null, activeTaskFile?: string | null): string | null;
+//# sourceMappingURL=agent-roles.d.ts.map

package/dist/agent-roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-roles.d.ts","sourceRoot":"","sources":["../src/agent-roles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAExE,OAAO,EAAE,WAAW,EAAE,CAAC;AAEvB,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAQvD,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAQ7D,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAQ/D,CAAC;AAKF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAQtD,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAQjF;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEpD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEtD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAE3D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAE9D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CASrD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAazE;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,EACxB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,GAC7B,MAAM,GAAG,IAAI,CAEf"}

package/dist/agent-roles.js

@@ -0,0 +1,101 @@
+import { AGENT_ROLES } from './types.js';
+export { AGENT_ROLES };
+export const AGENT_ROLE_LABELS = {
+    primary: 'Primary',
+    dev: 'Dev',
+    'fix-bug': 'Bugfix',
+    review: 'Review',
+    'self-review': 'Self-review',
+    'self-review-fix': 'Self-review fix',
+    'ci-fix': 'CI fix',
+};
+export const AGENT_ROLE_SHORT_LABELS = {
+    primary: 'MAIN',
+    dev: 'DEV',
+    'fix-bug': 'BUG',
+    review: 'REV',
+    'self-review': 'S-REV',
+    'self-review-fix': 'S-FIX',
+    'ci-fix': 'CI',
+};
+export const AGENT_ROLE_WINDOWS = {
+    primary: null,
+    dev: 'dev',
+    'fix-bug': 'bugfix',
+    review: 'review',
+    'self-review': 'self-review',
+    'self-review-fix': null, // runs in the primary worker's window, not a separate one
+    'ci-fix': 'ci-fix',
+};
+// Rank groups keep the flow-owned worker first, then optional review/fix loops
+// in the order they are normally spawned. Gaps leave room for new intermediate
+// roles without reordering persisted/UI state.
+export const AGENT_ROLE_RANKS = {
+    primary: 0,
+    dev: 1,
+    'fix-bug': 2,
+    review: 3,
+    'self-review': 10,
+    'self-review-fix': 20,
+    'ci-fix': 30,
+};
+export function primaryRoleForFlow(flowType) {
+    if (flowType === 'dev')
+        return 'dev';
+    if (flowType === 'fix-bug')
+        return 'fix-bug';
+    if (flowType === 'review-pr')
+        return 'review';
+    // Non-worker orchestration flows (pr-complete, merge-main) and null/undefined
+    // reuse the default session window instead of claiming a role-scoped worker window.
+    if (!flowType || flowType === 'pr-complete' || flowType === 'merge-main')
+        return 'primary';
+    throw new Error(`primaryRoleForFlow: unknown flow type '${flowType}'`);
+}
+export function contextIdFor(role) {
+    return role;
+}
+export function agentRoleLabel(role) {
+    return AGENT_ROLE_LABELS[role];
+}
+export function agentRoleShortLabel(role) {
+    return AGENT_ROLE_SHORT_LABELS[role] ?? role.toUpperCase();
+}
+export function agentRoleWindow(role) {
+    return AGENT_ROLE_WINDOWS[role];
+}
+export function agentRoleRank(role) {
+    const rank = AGENT_ROLE_RANKS[role];
+    if (rank === undefined) {
+        console.warn(`[agent-roles] unknown role rank for '${role}' — this may indicate a gateway/UI version mismatch`);
+        return 99;
+    }
+    return rank;
+}
+export function signalFileForTask(taskFile) {
+    if (!taskFile)
+        return null;
+    const trimmed = taskFile.trim();
+    if (!trimmed)
+        return null;
+    // Only derive from scoped task paths. A bare "TASK.md" has no stable
+    // context directory; explicit bare signalFile values are resolved by the
+    // gateway beside the already-resolved task file instead.
+    if (trimmed.startsWith('/') || !trimmed.includes('/'))
+        return null;
+    const normalized = trimmed.replace(/\/+$/, '');
+    const separator = normalized.lastIndexOf('/');
+    if (separator < 0)
+        return null;
+    return `${normalized.slice(0, separator)}/SIGNAL.json`;
+}
+export function agentContextTaskFile(taskFile, activeTaskFile) {
+    return scopedAgentTaskFile(taskFile) ?? scopedAgentTaskFile(activeTaskFile);
+}
+function scopedAgentTaskFile(taskFile) {
+    const candidate = taskFile?.trim();
+    if (!candidate || candidate.startsWith('/') || !candidate.includes('/'))
+        return null;
+    return candidate;
+}
+//# sourceMappingURL=agent-roles.js.map

package/dist/agent-roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-roles.js","sourceRoot":"","sources":["../src/agent-roles.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,265 @@
+import type { TmuxWorkerRef } from './methods/tmux.js';
+import type { TaskProgressResult } from './methods.js';
+import type { WorkerSignal } from './signal.js';
+import type { CIWatchFixProgress, CIWatchFixTrigger, CIWatchPhase } from './step-io.js';
+import type { AgentRole, BacklogItem, ChatMessage, FleetStatus, MachineHealth, MonitorViolation, PendingDecision, PRStatus, QueueItem, ResourceStateUpdate, Run, ScriptComplete, ScriptOutput, SlotStatus, StreamFrame, StreamStatus, TerminalData } from './types.js';
+export declare const Events: {
+    readonly FLEET_UPDATED: "fleet.updated";
+    readonly SLOT_CHANGED: "slot.changed";
+    readonly SCRIPT_OUTPUT: "script.output";
+    readonly SCRIPT_COMPLETE: "script.complete";
+    readonly FLEET_REFRESH_SCHEDULED: "fleet.refresh.scheduled";
+    readonly FLEET_REFRESH_SLOT_UPDATE: "fleet.refresh.slot-update";
+    readonly FLEET_REFRESH_SUMMARY: "fleet.refresh.summary";
+    readonly TERMINAL_DATA: "terminal.data";
+    readonly TERMINAL_MODE: "terminal.mode";
+    readonly TERMINAL_EXITED: "terminal.exited";
+    readonly PR_UPDATED: "pr.updated";
+    readonly DECISION_NEW: "decision.new";
+    readonly DECISION_RESOLVED: "decision.resolved";
+    readonly DECISION_UPDATED: "decision.updated";
+    readonly MONITOR_VIOLATION: "monitor.violation";
+    readonly NODE_CONNECTED: "node.connected";
+    readonly NODE_DISCONNECTED: "node.disconnected";
+    readonly NODE_VERSION_MISMATCH: "node.version.mismatch";
+    readonly TASK_PROGRESS_UPDATED: "task.progress.updated";
+    readonly WORKER_SIGNAL: "worker.signal";
+    readonly WORKSPACE_METRO_DATA: "workspace.metro.data";
+    readonly STREAM_FRAME: "stream.frame";
+    readonly STREAM_STATUS: "stream.status";
+    readonly QUEUE_UPDATED: "queue.updated";
+    readonly BACKLOG_UPDATED: "backlog.updated";
+    readonly CI_CHECK_UPDATED: "ci.check.updated";
+    readonly RUN_CREATED: "run.created";
+    readonly RUN_UPDATED: "run.updated";
+    readonly RUN_COMPLETED: "run.completed";
+    readonly RUN_STEP_COMPLETED: "run.step.completed";
+    readonly RUN_DECISION_NEW: "run.decision.new";
+    readonly RUN_DECISION_RESOLVED: "run.decision.resolved";
+    readonly RUN_DECISION_UPDATED: "run.decision.updated";
+    readonly RUN_DELETED: "run.deleted";
+    readonly RUN_IMPROVEMENT_FAILED: "run.improvement.failed";
+    readonly HELLO: "hello";
+    readonly CHAT_RESPONSE: "chat.response";
+    readonly CHAT_MEMORY_SAVED: "chat.memory.saved";
+    readonly COPILOT_OBSERVER_NOTIFICATION: "copilot.observer.notification";
+    readonly NODE_HEALTH_UPDATED: "node.health.updated";
+    readonly RESOURCE_STATUS_UPDATED: "resource.status.updated";
+    readonly RESOURCE_RELAUNCHED: "resource.relaunched";
+    readonly FLEET_THUMBNAILS_UPDATED: "fleet.thumbnails.updated";
+    readonly GITHUB_RATE_LIMIT: "github.rateLimit";
+    readonly LLM_AUTH_LOGIN_PROGRESS: "llm.auth.login.progress";
+};
+export interface FleetUpdatedPayload {
+    fleet: FleetStatus;
+}
+export interface SlotChangedPayload {
+    slot: SlotStatus;
+}
+export interface ScriptOutputPayload extends ScriptOutput {
+}
+export interface ScriptCompletePayload extends ScriptComplete {
+}
+export interface TerminalDataPayload extends TerminalData {
+}
+export interface TerminalModePayload {
+    slotId?: string;
+    worker?: TmuxWorkerRef;
+    runId?: string;
+    role?: AgentRole;
+    contextId?: string;
+    mode: string;
+}
+export interface TerminalExitedPayload {
+    slotId?: string;
+    worker?: TmuxWorkerRef;
+    runId?: string;
+    role?: AgentRole;
+    contextId?: string;
+    exitCode: number;
+}
+export interface PRUpdatedPayload {
+    pr: PRStatus;
+}
+export interface DecisionNewPayload {
+    decision?: PendingDecision;
+    slotId?: string | null;
+    runId?: string;
+    id?: string;
+    type?: string;
+    title?: string;
+    description?: string;
+    context?: Record<string, unknown>;
+    actions?: PendingDecision['actions'];
+    createdAt?: string;
+}
+export interface DecisionResolvedPayload {
+    id?: string;
+    decisionId?: string;
+}
+export interface DecisionUpdatedPayload {
+    decision: PendingDecision;
+    runId?: string;
+}
+export interface MonitorViolationPayload {
+    violation: MonitorViolation;
+}
+export interface NodeConnectedPayload {
+    machine: string;
+    pid: number;
+    protocolVersion?: string;
+    versionMatch?: boolean;
+}
+export interface NodeDisconnectedPayload {
+    machine: string;
+}
+export interface NodeVersionMismatchPayload {
+    machine: string;
+    nodeVersion: string;
+    gatewayVersion: string;
+}
+export interface TaskProgressUpdatedPayload {
+    slotId: string;
+    runId: string | null;
+    role?: AgentRole;
+    contextId?: string;
+    progress: TaskProgressResult;
+}
+export interface WorkerSignalPayload {
+    slotId: string;
+    runId?: string | null;
+    role?: AgentRole;
+    contextId?: string;
+    signal: WorkerSignal;
+}
+export interface WorkspaceMetroDataPayload {
+    slotId: string;
+    data: string;
+}
+export interface StreamFramePayload extends StreamFrame {
+}
+export interface StreamStatusPayload extends StreamStatus {
+}
+export interface QueueUpdatedPayload {
+    items: QueueItem[];
+}
+export interface BacklogUpdatedPayload {
+    items: BacklogItem[];
+}
+export interface CiCheckSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    pending: number;
+}
+export interface CiCheckUpdatedPayload {
+    runId: string;
+    prNumber: number;
+    checkSummary: CiCheckSummary;
+    recommendation: string;
+    passedNames: string[];
+    failedNames: string[];
+    pendingNames: string[];
+    pollCount: number;
+    pollIntervalMs?: number;
+    lastCheckedAt?: string;
+    phase?: CIWatchPhase;
+    fixInProgress?: boolean;
+    fixTrigger?: CIWatchFixTrigger;
+    fixProgress?: CIWatchFixProgress;
+    activeTaskFile?: string | null;
+    nextPollAt?: string | null;
+    lastSignalAt?: string | null;
+    dedupReason?: string | null;
+    lastFixCommitSha?: string | null;
+    timeoutWindowStartedAt?: string;
+    lastProgressAt?: string;
+    lastProgressReason?: string;
+}
+export interface RunCreatedPayload {
+    run: Run;
+}
+export interface RunUpdatedPayload {
+    run: Run;
+}
+export interface RunCompletedPayload {
+    run: Run;
+}
+export interface RunStepCompletedPayload {
+    runId: string;
+    stepName: string;
+    run?: Run;
+}
+export interface RunDecisionNewPayload {
+    runId: string;
+    decision: PendingDecision;
+    slotId?: string | null;
+}
+export interface RunDecisionResolvedPayload {
+    runId: string;
+    decisionId: string;
+}
+export interface RunImprovementFailedPayload {
+    runId: string;
+    error: string;
+}
+export interface RunDeletedPayload {
+    runId: string;
+}
+export interface HelloPayload {
+    fleet: FleetStatus | null;
+}
+export interface ChatResponsePayload {
+    sessionId: string;
+    seq?: number;
+    state: 'delta' | 'final' | 'error' | 'aborted';
+    text?: string;
+    statusText?: string;
+    message?: ChatMessage;
+    suggestedActions?: ChatMessage['suggestedActions'];
+    errorMessage?: string;
+}
+export interface ChatMemorySavedPayload {
+    path: string;
+    sessionId?: string;
+}
+export interface CopilotObserverNotificationPayload {
+    id: string;
+    ts: string;
+    type: string;
+    severity: 'warn' | 'error';
+    summary: string;
+    slotId?: string;
+    runId?: string;
+}
+export interface NodeHealthUpdatedPayload {
+    machine: string;
+    health: MachineHealth;
+}
+export interface ResourceStatusUpdatedPayload {
+    slotId: string;
+    resources: ResourceStateUpdate[];
+}
+export interface ResourceRelaunchedPayload {
+    slotId: string;
+    resourceId: string;
+    oldPid: number;
+    newPid: number;
+    at: string;
+}
+export interface GitHubRateLimitPayload {
+    remaining: number;
+    limit: number;
+    resetAt: string;
+    percentUsed: number;
+}
+export interface FleetThumbnail {
+    data: string;
+    width: number;
+    height: number;
+    ts: number;
+}
+export interface FleetThumbnailsUpdatedPayload {
+    thumbnails: Record<string, FleetThumbnail>;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}