@flamecast/protocol 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { Runtime, RuntimeNames, RuntimeConfigFor, RuntimeInstance, RuntimeInfo, SessionContext, SessionEndReason, } from "./runtime.js";
+export type { FileSystemEntry, PermissionRequestEvent, FilesystemSnapshotEvent, FilePreviewEvent, PermissionRespondAction, FsSnapshotAction, FilePreviewAction, SessionHostStartRequest, SessionHostStartResponse, SessionHostHealthResponse, SessionCallbackEvent, PermissionCallbackResponse, } from "./session-host.js";
+export type { AgentSpawn, AgentTemplate, AgentTemplateRuntime, Session, SessionLog, PendingPermission, PendingPermissionOption, FileSystemSnapshot, FilePreview, QueuedPromptResponse, PromptQueueItem, PromptQueueState, CreateSessionBody, RegisterAgentTemplateBody, PromptBody, PermissionResponseBody, WebhookConfig, WebhookEventType, WebhookPayload, } from "./session.js";
+export type { FlamecastStorage, SessionMeta, SessionRuntimeInfo, StoredSession, } from "./storage.js";
+export type { WsServerMessage, WsControlMessage, WsEventMessage, WsConnectedMessage, WsErrorMessage, WsPromptAction, WsPermissionRespondAction, WsCancelAction, WsTerminateAction, WsPingAction, WsQueueReorderAction, WsQueueClearAction, WsQueuePauseAction, WsQueueResumeAction, } from "./ws.js";
+export type { RuntimeHostStartSessionRequest, RuntimeHostStartSessionResponse, RuntimeHostSessionStatus, RuntimeHostHealthResponse, RuntimeHostPromptRequest, RuntimeHostPermissionResponse, } from "./runtime-host.js";
+export type { Channel, WsChannelServerMessage, WsChannelControlMessage, WsChannelConnectedMessage, WsSubscribedMessage, WsUnsubscribedMessage, WsChannelEventMessage, WsSessionCreatedMessage, WsSessionTerminatedMessage, WsChannelErrorMessage, WsPongMessage, WsSubscribeAction, WsUnsubscribeAction, WsChannelPromptAction, WsChannelPermissionRespondAction, WsChannelCancelAction, WsChannelTerminateAction, WsChannelQueueReorderAction, WsChannelQueueClearAction, WsChannelQueuePauseAction, WsChannelQueueResumeAction, WsChannelPingAction, } from "./ws-channels.js";

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime-host.d.ts

@@ -0,0 +1,28 @@
+export interface RuntimeHostStartSessionRequest {
+    sessionId: string;
+    command: string;
+    args: string[];
+    workspace: string;
+    setup?: string;
+    env?: Record<string, string>;
+    callbackUrl?: string;
+}
+export interface RuntimeHostStartSessionResponse {
+    acpSessionId: string;
+    sessionId: string;
+}
+export interface RuntimeHostSessionStatus {
+    sessionId: string;
+    status: "idle" | "running";
+}
+export interface RuntimeHostHealthResponse {
+    status: "ok";
+    sessions: RuntimeHostSessionStatus[];
+}
+export interface RuntimeHostPromptRequest {
+    text: string;
+}
+export interface RuntimeHostPermissionResponse {
+    optionId?: string;
+    outcome?: "cancelled";
+}

package/dist/runtime-host.js

@@ -0,0 +1,9 @@
+// ---------------------------------------------------------------------------
+// RuntimeHost HTTP contract
+//
+// A runtime-host is a long-lived process managing multiple sessions within a
+// single runtime instance (e.g. one per Docker container or E2B sandbox).
+// It exposes a single WebSocket endpoint implementing the ws-channels protocol
+// and session-scoped HTTP endpoints under /sessions/{sessionId}/...
+// ---------------------------------------------------------------------------
+export {};

package/dist/runtime.d.ts

@@ -0,0 +1,90 @@
+/**
+ * A Runtime knows how to ensure a SessionHost exists for a given session
+ * and how to route HTTP/WS traffic to it.
+ *
+ * Intentionally minimal for MVP. Covers start/forward/terminate via HTTP
+ * semantics. May be split into explicit lifecycle methods later.
+ */
+export interface Runtime<TConfig extends Record<string, unknown> = {}> {
+    /** If true, only a single instance is allowed (e.g., local/node runtimes). Default: false. */
+    readonly onlyOne?: boolean;
+    fetchSession(sessionId: string, request: Request): Promise<Response>;
+    /**
+     * Proxy an instance-scoped request directly to the runtime instance.
+     *
+     * This is intended for runtime-level surfaces such as filesystem browsing
+     * or aggregate traces that should exist independently of any one session.
+     */
+    fetchInstance?(instanceId: string, request: Request): Promise<Response>;
+    /** Start (or resume) a runtime instance. Creates the instance if it doesn't exist. */
+    start?(instanceId: string): Promise<void>;
+    /** Stop a specific runtime instance and tear down its resources. */
+    stop?(instanceId: string): Promise<void>;
+    /** Pause a runtime instance (sessions survive, resources freeze). */
+    pause?(instanceId: string): Promise<void>;
+    /** Delete a runtime instance and permanently remove its resources. */
+    delete?(instanceId: string): Promise<void>;
+    /** Query the live status of an instance from the actual runtime (e.g. Docker). */
+    getInstanceStatus?(instanceId: string): Promise<"running" | "stopped" | "paused" | undefined>;
+    /** Return the WebSocket URL for a running instance's runtime-host. */
+    getWebsocketUrl?(instanceId: string): string | undefined;
+    /** Return the default working directory for new sessions on this runtime. */
+    getDefaultCwd?(): string | undefined;
+    dispose?(): Promise<void>;
+    /**
+     * Return runtime-specific metadata for a session that should be persisted
+     * for recovery after a server restart. Called after session creation.
+     */
+    getRuntimeMeta?(sessionId: string): Record<string, unknown> | null;
+    /**
+     * Re-register a previously-running session after a server restart.
+     *
+     * Called during recovery with the runtime-specific metadata that was persisted
+     * when the session was originally created. Returns `true` if the session is
+     * still alive and was successfully re-registered, `false` otherwise.
+     *
+     * Runtimes that don't support reconnection can omit this method; the recovery
+     * logic will fall back to a health-check probe against the persisted hostUrl.
+     */
+    reconnect?(sessionId: string, runtimeMeta: Record<string, unknown> | null): Promise<boolean>;
+}
+/** Persisted state of a runtime instance. */
+export interface RuntimeInstance {
+    name: string;
+    typeName: string;
+    status: "running" | "stopped" | "paused";
+    /** WebSocket URL of the runtime-host for this instance (set when running). */
+    websocketUrl?: string;
+}
+/** Aggregated info for a runtime type and its instances. */
+export interface RuntimeInfo {
+    typeName: string;
+    onlyOne: boolean;
+    instances: RuntimeInstance[];
+}
+/** Extract string keys from a runtime registry `R`. */
+export type RuntimeNames<R> = Extract<keyof R, string>;
+/**
+ * Union of valid runtime config objects for a given registry.
+ * Each branch carries the `provider` key narrowed to the specific runtime name
+ * plus the runtime's own config fields.
+ */
+export type RuntimeConfigFor<R extends Record<string, Runtime<Record<string, unknown>>>> = {
+    [K in keyof R]: R[K] extends Runtime<infer C> ? {
+        provider: K;
+        setup?: string;
+    } & C : never;
+}[keyof R];
+/** Minimal session context exposed to event handlers. */
+export interface SessionContext<R extends Record<string, Runtime<Record<string, unknown>>>> {
+    id: string;
+    agentName: string;
+    runtime: RuntimeNames<R>;
+    spawn: {
+        command: string;
+        args: string[];
+    };
+    startedAt: string;
+}
+/** Reason a session ended. */
+export type SessionEndReason = "terminated" | "error" | "idle_timeout" | "agent_exit";

package/dist/runtime.js

@@ -0,0 +1 @@
+export {};

package/dist/session-host-zod.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export declare const SessionHostStartRequestSchema: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodArray<z.ZodString>;
+    workspace: z.ZodString;
+    setup: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    callbackUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;

package/dist/session-host-zod.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export const SessionHostStartRequestSchema = z.object({
+    command: z.string(),
+    args: z.array(z.string()),
+    workspace: z.string(),
+    setup: z.string().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    callbackUrl: z.string().optional(),
+});

package/dist/session-host.d.ts

@@ -0,0 +1,102 @@
+export interface FileSystemEntryGitInfo {
+    branch: string;
+    origin?: string;
+}
+export interface FileSystemEntry {
+    path: string;
+    type: "file" | "directory" | "symlink" | "other";
+    /** Present when the entry is a directory that is a git repository. */
+    git?: FileSystemEntryGitInfo;
+}
+export interface PermissionRequestEvent {
+    requestId: string;
+    toolCallId: string;
+    title: string;
+    kind?: string;
+    options: Array<{
+        optionId: string;
+        name: string;
+        kind: string;
+    }>;
+}
+export interface FilesystemSnapshotEvent {
+    snapshot: {
+        root: string;
+        entries: FileSystemEntry[];
+    };
+}
+export interface FilePreviewEvent {
+    path: string;
+    content: string;
+}
+export interface PermissionRespondAction {
+    action: "permission.respond";
+    requestId: string;
+    response: {
+        optionId: string;
+    };
+}
+export interface FsSnapshotAction {
+    action: "fs.snapshot";
+    path?: string;
+}
+export interface FilePreviewAction {
+    action: "file.preview";
+    path: string;
+}
+/** Union of all events the session-host can POST to the control plane. */
+export type SessionCallbackEvent = {
+    type: "permission_request";
+    data: PermissionRequestEvent;
+} | {
+    type: "session_end";
+    data: {
+        exitCode: number | null;
+    };
+} | {
+    type: "end_turn";
+    data: {
+        promptResponse: unknown;
+    };
+} | {
+    type: "agent_message";
+    data: {
+        sessionUpdate: unknown;
+    };
+} | {
+    type: "error";
+    data: {
+        message: string;
+    };
+};
+/** Response from the control plane for a permission_request callback. */
+export type PermissionCallbackResponse = {
+    optionId: string;
+} | {
+    outcome: "cancelled";
+} | {
+    deferred: true;
+};
+export interface SessionHostStartRequest {
+    /** Flamecast-level session ID (used for callbacks to the control plane). */
+    sessionId?: string;
+    command: string;
+    args: string[];
+    workspace: string;
+    setup?: string;
+    env?: Record<string, string>;
+    callbackUrl?: string;
+}
+export interface SessionHostStartResponse {
+    acpSessionId: string;
+    /** Set by the runtime after proxying the response from the runtime-host. */
+    hostUrl: string;
+    /** Set by the runtime after proxying the response from the runtime-host. */
+    websocketUrl: string;
+    /** The Flamecast-level session ID (echoed back from the runtime-host). */
+    sessionId?: string;
+}
+export interface SessionHostHealthResponse {
+    status: "idle" | "running";
+    sessionId?: string;
+}

package/dist/session-host.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// Shared types for filesystem entries (used by snapshot events)
+// ---------------------------------------------------------------------------
+export {};

package/dist/session.d.ts

@@ -0,0 +1,129 @@
+import type { FileSystemEntry } from "./session-host.js";
+export interface AgentSpawn {
+    command: string;
+    args: string[];
+}
+export interface AgentTemplateRuntime {
+    provider: string;
+    image?: string;
+    dockerfile?: string;
+    setup?: string;
+    env?: Record<string, string>;
+}
+export interface AgentTemplate {
+    id: string;
+    name: string;
+    spawn: AgentSpawn;
+    runtime: AgentTemplateRuntime;
+    env?: Record<string, string>;
+}
+export interface SessionLog {
+    timestamp: string;
+    type: string;
+    data: Record<string, unknown>;
+}
+export interface PendingPermissionOption {
+    optionId: string;
+    name: string;
+    kind: string;
+}
+export interface PendingPermission {
+    requestId: string;
+    toolCallId: string;
+    title: string;
+    kind?: string;
+    options: PendingPermissionOption[];
+}
+export interface FileSystemSnapshot {
+    root: string;
+    /** The absolute path of the directory being listed. Absent for legacy recursive snapshots. */
+    path?: string;
+    /** If the listed directory is inside a git repo, the absolute path to the repo root. */
+    gitPath?: string;
+    entries: FileSystemEntry[];
+    truncated: boolean;
+    maxEntries: number;
+}
+export interface FilePreview {
+    path: string;
+    content: string;
+    truncated: boolean;
+    maxChars: number;
+}
+export interface QueuedPromptResponse {
+    queued: true;
+    queueId: string;
+    position: number;
+}
+export interface PromptQueueItem {
+    queueId: string;
+    text: string;
+    enqueuedAt: string;
+    position: number;
+}
+export interface PromptQueueState {
+    processing: boolean;
+    paused: boolean;
+    items: PromptQueueItem[];
+    size: number;
+}
+export interface Session {
+    id: string;
+    agentName: string;
+    spawn: AgentSpawn;
+    startedAt: string;
+    lastUpdatedAt: string;
+    status: "active" | "killed";
+    logs: SessionLog[];
+    pendingPermission: PendingPermission | null;
+    fileSystem: FileSystemSnapshot | null;
+    promptQueue: PromptQueueState | null;
+    websocketUrl?: string;
+    /** Runtime instance name this session is scoped to. */
+    runtime?: string;
+}
+export interface CreateSessionBody {
+    /** Client-generated session ID. If omitted the server generates one. */
+    sessionId?: string;
+    cwd?: string;
+    agentTemplateId?: string;
+    spawn?: AgentSpawn;
+    name?: string;
+    /** Runtime instance name to run this session on. Required for multi-instance runtimes. */
+    runtimeInstance?: string;
+    webhooks?: Omit<WebhookConfig, "id">[];
+}
+export interface RegisterAgentTemplateBody {
+    name: string;
+    spawn: AgentSpawn;
+    runtime?: AgentTemplateRuntime;
+    env?: Record<string, string>;
+}
+export interface PromptBody {
+    text: string;
+}
+export type PermissionResponseBody = {
+    optionId: string;
+} | {
+    outcome: "cancelled";
+};
+/** Event types deliverable via webhooks. */
+export type WebhookEventType = "permission_request" | "end_turn" | "error" | "session_end";
+/** Webhook registration — per-session or global. */
+export interface WebhookConfig {
+    /** Stable internal ID assigned at registration. */
+    id: string;
+    url: string;
+    secret: string;
+    events?: WebhookEventType[];
+}
+/** Payload delivered to webhook endpoints. */
+export interface WebhookPayload {
+    sessionId: string;
+    eventId: string;
+    timestamp: string;
+    event: {
+        type: WebhookEventType;
+        data: Record<string, unknown>;
+    };
+}

package/dist/session.js

@@ -0,0 +1 @@
+export {};

package/dist/storage.d.ts

@@ -0,0 +1,50 @@
+import type { RuntimeInstance } from "./runtime.js";
+import type { AgentTemplate, Session, WebhookConfig } from "./session.js";
+/** Durable slice of {@link Session} (everything except runtime-only state). */
+export type SessionMeta = Omit<Session, "fileSystem" | "logs" | "promptQueue">;
+/** Runtime connection info persisted alongside a session for recovery after restart. */
+export interface SessionRuntimeInfo {
+    hostUrl: string;
+    websocketUrl: string;
+    runtimeName: string;
+    runtimeMeta?: Record<string, unknown> | null;
+}
+/** Storage view of a session, including durable routing metadata. */
+export interface StoredSession {
+    meta: SessionMeta;
+    runtimeInfo: SessionRuntimeInfo | null;
+    webhooks: WebhookConfig[];
+}
+/**
+ * Durable backing store for orchestrator state. Runtime (child process, ACP stream)
+ * stays in memory; storage is the source of truth for metadata.
+ */
+export interface FlamecastStorage {
+    /**
+     * Synchronize the constructor-provided template set.
+     * Managed templates are upserted and any previously managed templates that are
+     * no longer present are pruned. User-registered templates are preserved.
+     */
+    seedAgentTemplates(templates: AgentTemplate[]): Promise<void>;
+    listAgentTemplates(): Promise<AgentTemplate[]>;
+    getAgentTemplate(id: string): Promise<AgentTemplate | null>;
+    saveAgentTemplate(template: AgentTemplate): Promise<void>;
+    updateAgentTemplate(id: string, patch: {
+        name?: string;
+        spawn?: AgentTemplate["spawn"];
+        runtime?: Partial<AgentTemplate["runtime"]>;
+        env?: Record<string, string>;
+    }): Promise<AgentTemplate | null>;
+    createSession(meta: SessionMeta, runtimeInfo?: SessionRuntimeInfo, webhooks?: WebhookConfig[]): Promise<void>;
+    updateSession(id: string, patch: Partial<Pick<SessionMeta, "lastUpdatedAt" | "pendingPermission">>): Promise<void>;
+    getSessionMeta(id: string): Promise<SessionMeta | null>;
+    getStoredSession(id: string): Promise<StoredSession | null>;
+    /** Return all sessions (active + killed), ordered by lastUpdatedAt desc. */
+    listAllSessions(): Promise<SessionMeta[]>;
+    /** Return active sessions with their persisted runtime connection info for recovery. */
+    listActiveSessionsWithRuntime(): Promise<StoredSession[]>;
+    finalizeSession(id: string, reason: "terminated"): Promise<void>;
+    saveRuntimeInstance(instance: RuntimeInstance): Promise<void>;
+    listRuntimeInstances(): Promise<RuntimeInstance[]>;
+    deleteRuntimeInstance(name: string): Promise<void>;
+}

package/dist/storage.js

@@ -0,0 +1 @@
+export {};

package/dist/verify.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Verify an incoming webhook signature.
+ *
+ * Usage:
+ *   const body = await req.text();
+ *   const sig = req.headers.get("X-Flamecast-Signature")!;
+ *   if (!verifyWebhookSignature(secret, body, sig)) return new Response("unauthorized", { status: 401 });
+ */
+export declare function verifyWebhookSignature(secret: string, body: string, signature: string): boolean;
+/** Sign a webhook payload body. Returns the full signature string including the "sha256=" prefix. */
+export declare function signWebhookPayload(secret: string, body: string): string;

package/dist/verify.js

@@ -0,0 +1,19 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Verify an incoming webhook signature.
+ *
+ * Usage:
+ *   const body = await req.text();
+ *   const sig = req.headers.get("X-Flamecast-Signature")!;
+ *   if (!verifyWebhookSignature(secret, body, sig)) return new Response("unauthorized", { status: 401 });
+ */
+export function verifyWebhookSignature(secret, body, signature) {
+    const expected = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
+    if (expected.length !== signature.length)
+        return false;
+    return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
+}
+/** Sign a webhook payload body. Returns the full signature string including the "sha256=" prefix. */
+export function signWebhookPayload(secret, body) {
+    return "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
+}

package/dist/ws-channels.d.ts

@@ -0,0 +1,124 @@
+/** A channel identifier, e.g. "session:abc", "agent:xyz:fs", "agents". */
+export type Channel = string;
+export interface WsChannelConnectedMessage {
+    type: "connected";
+    connectionId: string;
+}
+export interface WsSubscribedMessage {
+    type: "subscribed";
+    channel: Channel;
+}
+export interface WsUnsubscribedMessage {
+    type: "unsubscribed";
+    channel: Channel;
+}
+export interface WsChannelEventMessage {
+    type: "event";
+    channel: Channel;
+    sessionId: string;
+    agentId: string;
+    seq: number;
+    event: {
+        type: string;
+        data: Record<string, unknown>;
+        timestamp: string;
+    };
+}
+export interface WsSessionCreatedMessage {
+    type: "session.created";
+    sessionId: string;
+    agentId: string;
+}
+export interface WsSessionTerminatedMessage {
+    type: "session.terminated";
+    sessionId: string;
+    agentId: string;
+}
+export interface WsChannelErrorMessage {
+    type: "error";
+    message: string;
+    channel?: Channel;
+}
+export interface WsPongMessage {
+    type: "pong";
+}
+export type WsChannelServerMessage = WsChannelConnectedMessage | WsSubscribedMessage | WsUnsubscribedMessage | WsChannelEventMessage | WsSessionCreatedMessage | WsSessionTerminatedMessage | WsChannelErrorMessage | WsPongMessage;
+export interface WsSubscribeAction {
+    action: "subscribe";
+    channel: Channel;
+    /** Optional sequence number — replay only events with seq > since. */
+    since?: number;
+}
+export interface WsUnsubscribeAction {
+    action: "unsubscribe";
+    channel: Channel;
+}
+export interface WsChannelPromptAction {
+    action: "prompt";
+    sessionId: string;
+    text: string;
+}
+export interface WsChannelPermissionRespondAction {
+    action: "permission.respond";
+    sessionId: string;
+    requestId: string;
+    body: {
+        optionId: string;
+    } | {
+        outcome: "cancelled";
+    };
+}
+export interface WsChannelCancelAction {
+    action: "cancel";
+    sessionId: string;
+    queueId?: string;
+}
+export interface WsChannelTerminateAction {
+    action: "terminate";
+    sessionId: string;
+}
+export interface WsChannelQueueReorderAction {
+    action: "queue.reorder";
+    sessionId: string;
+    order: string[];
+}
+export interface WsChannelQueueClearAction {
+    action: "queue.clear";
+    sessionId: string;
+}
+export interface WsChannelQueuePauseAction {
+    action: "queue.pause";
+    sessionId: string;
+}
+export interface WsChannelQueueResumeAction {
+    action: "queue.resume";
+    sessionId: string;
+}
+export interface WsChannelPingAction {
+    action: "ping";
+}
+export interface WsChannelTerminalCreateAction {
+    action: "terminal.create";
+    /** Optional session ID — if provided, terminal opens in that session's workspace. */
+    sessionId?: string;
+    /** Shell command to run (defaults to /bin/sh). */
+    data?: string;
+    cols?: number;
+    rows?: number;
+}
+export interface WsChannelTerminalInputAction {
+    action: "terminal.input";
+    terminalId: string;
+    data: string;
+}
+export interface WsChannelTerminalResizeAction {
+    action: "terminal.resize";
+    terminalId: string;
+    cols: number;
+    rows: number;
+}
+export interface WsChannelTerminalKillAction {
+    action: "terminal.kill";
+    terminalId: string;
+}
+export type WsChannelControlMessage = WsSubscribeAction | WsUnsubscribeAction | WsChannelPromptAction | WsChannelPermissionRespondAction | WsChannelCancelAction | WsChannelTerminateAction | WsChannelQueueReorderAction | WsChannelQueueClearAction | WsChannelQueuePauseAction | WsChannelQueueResumeAction | WsChannelPingAction | WsChannelTerminalCreateAction | WsChannelTerminalInputAction | WsChannelTerminalResizeAction | WsChannelTerminalKillAction;

package/dist/ws-channels.js

@@ -0,0 +1,7 @@
+// ---------------------------------------------------------------------------
+// Multi-session WebSocket adapter — channel-based protocol (SMI-1704)
+//
+// These types define the multiplexed WS endpoint at ws://host/ws.
+// The existing per-session types in ws.ts remain unchanged for backward compat.
+// ---------------------------------------------------------------------------
+export {};

package/dist/ws-zod.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export declare const WsServerMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"event">;
+    timestamp: z.ZodString;
+    event: z.ZodObject<{
+        type: z.ZodString;
+        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        timestamp: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"connected">;
+    sessionId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    message: z.ZodString;
+}, z.core.$strip>]>;
+export declare const WsControlMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
+    action: z.ZodLiteral<"prompt">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"permission.respond">;
+    requestId: z.ZodString;
+    body: z.ZodUnion<readonly [z.ZodObject<{
+        optionId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        outcome: z.ZodLiteral<"cancelled">;
+    }, z.core.$strip>]>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"cancel">;
+    queueId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"terminate">;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"ping">;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"queue.reorder">;
+    order: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"queue.clear">;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"queue.pause">;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"queue.resume">;
+}, z.core.$strip>]>;

package/dist/ws-zod.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Server → Client message schemas
+// ---------------------------------------------------------------------------
+const WsEventMessageSchema = z.object({
+    type: z.literal("event"),
+    timestamp: z.string(),
+    event: z.object({
+        type: z.string(),
+        data: z.record(z.string(), z.unknown()),
+        timestamp: z.string(),
+    }),
+});
+const WsConnectedMessageSchema = z.object({
+    type: z.literal("connected"),
+    sessionId: z.string(),
+});
+const WsErrorMessageSchema = z.object({
+    type: z.literal("error"),
+    message: z.string(),
+});
+export const WsServerMessageSchema = z.union([
+    WsEventMessageSchema,
+    WsConnectedMessageSchema,
+    WsErrorMessageSchema,
+]);
+// ---------------------------------------------------------------------------
+// Client → Server message schemas
+// ---------------------------------------------------------------------------
+const WsPromptActionSchema = z.object({
+    action: z.literal("prompt"),
+    text: z.string(),
+});
+const WsPermissionRespondActionSchema = z.object({
+    action: z.literal("permission.respond"),
+    requestId: z.string(),
+    body: z.union([
+        z.object({ optionId: z.string() }),
+        z.object({ outcome: z.literal("cancelled") }),
+    ]),
+});
+const WsCancelActionSchema = z.object({
+    action: z.literal("cancel"),
+    queueId: z.string().optional(),
+});
+const WsTerminateActionSchema = z.object({
+    action: z.literal("terminate"),
+});
+const WsPingActionSchema = z.object({
+    action: z.literal("ping"),
+});
+const WsQueueReorderActionSchema = z.object({
+    action: z.literal("queue.reorder"),
+    order: z.array(z.string()),
+});
+const WsQueueClearActionSchema = z.object({
+    action: z.literal("queue.clear"),
+});
+const WsQueuePauseActionSchema = z.object({
+    action: z.literal("queue.pause"),
+});
+const WsQueueResumeActionSchema = z.object({
+    action: z.literal("queue.resume"),
+});
+export const WsControlMessageSchema = z.union([
+    WsPromptActionSchema,
+    WsPermissionRespondActionSchema,
+    WsCancelActionSchema,
+    WsTerminateActionSchema,
+    WsPingActionSchema,
+    WsQueueReorderActionSchema,
+    WsQueueClearActionSchema,
+    WsQueuePauseActionSchema,
+    WsQueueResumeActionSchema,
+]);

package/dist/ws.d.ts

@@ -0,0 +1,55 @@
+export interface WsEventMessage {
+    type: "event";
+    timestamp: string;
+    event: {
+        type: string;
+        data: Record<string, unknown>;
+        timestamp: string;
+    };
+}
+export interface WsConnectedMessage {
+    type: "connected";
+    sessionId: string;
+}
+export interface WsErrorMessage {
+    type: "error";
+    message: string;
+}
+export type WsServerMessage = WsEventMessage | WsConnectedMessage | WsErrorMessage;
+export interface WsPromptAction {
+    action: "prompt";
+    text: string;
+}
+export interface WsPermissionRespondAction {
+    action: "permission.respond";
+    requestId: string;
+    body: {
+        optionId: string;
+    } | {
+        outcome: "cancelled";
+    };
+}
+export interface WsCancelAction {
+    action: "cancel";
+    queueId?: string;
+}
+export interface WsTerminateAction {
+    action: "terminate";
+}
+export interface WsPingAction {
+    action: "ping";
+}
+export interface WsQueueReorderAction {
+    action: "queue.reorder";
+    order: string[];
+}
+export interface WsQueueClearAction {
+    action: "queue.clear";
+}
+export interface WsQueuePauseAction {
+    action: "queue.pause";
+}
+export interface WsQueueResumeAction {
+    action: "queue.resume";
+}
+export type WsControlMessage = WsPromptAction | WsPermissionRespondAction | WsCancelAction | WsTerminateAction | WsPingAction | WsQueueReorderAction | WsQueueClearAction | WsQueuePauseAction | WsQueueResumeAction;

package/dist/ws.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// Server → Client messages (WebSocket only — real-time events)
+// ---------------------------------------------------------------------------
+export {};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@flamecast/protocol",
+  "version": "0.1.1",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./session-host": {
+      "types": "./dist/session-host.d.ts",
+      "import": "./dist/session-host.js"
+    },
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "import": "./dist/session.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js"
+    },
+    "./ws": {
+      "types": "./dist/ws.d.ts",
+      "import": "./dist/ws.js"
+    },
+    "./ws/channels": {
+      "types": "./dist/ws-channels.d.ts",
+      "import": "./dist/ws-channels.js"
+    },
+    "./ws/zod": {
+      "types": "./dist/ws-zod.d.ts",
+      "import": "./dist/ws-zod.js"
+    },
+    "./session-host/zod": {
+      "types": "./dist/session-host-zod.d.ts",
+      "import": "./dist/session-host-zod.js"
+    },
+    "./verify": {
+      "types": "./dist/verify.d.ts",
+      "import": "./dist/verify.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:package": "tsc"
+  }
+}