@brainferno/mcp-bridge-protocol 0.1.0

package/dist/apps.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The five Creative Cloud hosts this server drives: which *lane* reaches each
+ * one, which in-app *panel* (if any) it needs, and which scripting *engine*
+ * runs the work.
+ *
+ * There is no single automation surface across all five, so the server routes
+ * each app down one of three lanes:
+ *   - "socket":    an in-app panel dials out to the bridge hub. Photoshop and
+ *                  Premiere Pro use a UXP panel; After Effects and Audition use
+ *                  a CEP panel. UXP plugins cannot listen on a socket, so the
+ *                  panel is always the client and the hub the server.
+ *   - "os-script": no panel — the server injects ExtendScript from outside via
+ *                  `osascript 'do javascript'` (macOS) or COM `DoJavaScript`
+ *                  (Windows). Illustrator has no public UXP, so this is its only
+ *                  complete surface.
+ *
+ * This mapping is deliberate and current (2026): Illustrator UXP is Adobe
+ * internal-only, and Premiere's ExtendScript/CEP surface is being removed in
+ * favor of UXP — so Premiere is UXP and Illustrator is os-script ExtendScript,
+ * not the other way around.
+ */
+export declare const APP_IDS: readonly ["after_effects", "premiere", "photoshop", "illustrator", "audition"];
+export type AppId = (typeof APP_IDS)[number];
+/** How the server reaches a host. */
+export type Lane = "socket" | "os-script";
+/** Which in-app panel technology hosts the bridge client, when there is one. */
+export type PanelKind = "uxp" | "cep";
+/** Which scripting engine the host's commands ultimately run in. */
+export type ScriptEngine = "uxp-batchplay" | "premierepro-api" | "extendscript";
+export interface AppInfo {
+    id: AppId;
+    /** Human-readable name, used in tool descriptions and error messages. */
+    displayName: string;
+    lane: Lane;
+    /** The panel that dials into the hub, for socket-lane apps. */
+    panel?: PanelKind;
+    engine: ScriptEngine;
+    /**
+     * Application name as AppleScript sees it, for the macOS os-script lane.
+     * Undefined where no such lane exists.
+     */
+    appleScriptName?: string;
+    /**
+     * Windows COM ProgID for the os-script lane. Bind a versioned ProgID at
+     * runtime (e.g. "Illustrator.Application.30") when multiple versions coexist.
+     */
+    winProgId?: string;
+}
+export declare const APPS: Record<AppId, AppInfo>;
+export declare function appInfo(id: AppId): AppInfo;

package/dist/apps.js

@@ -0,0 +1,71 @@
+/**
+ * The five Creative Cloud hosts this server drives: which *lane* reaches each
+ * one, which in-app *panel* (if any) it needs, and which scripting *engine*
+ * runs the work.
+ *
+ * There is no single automation surface across all five, so the server routes
+ * each app down one of three lanes:
+ *   - "socket":    an in-app panel dials out to the bridge hub. Photoshop and
+ *                  Premiere Pro use a UXP panel; After Effects and Audition use
+ *                  a CEP panel. UXP plugins cannot listen on a socket, so the
+ *                  panel is always the client and the hub the server.
+ *   - "os-script": no panel — the server injects ExtendScript from outside via
+ *                  `osascript 'do javascript'` (macOS) or COM `DoJavaScript`
+ *                  (Windows). Illustrator has no public UXP, so this is its only
+ *                  complete surface.
+ *
+ * This mapping is deliberate and current (2026): Illustrator UXP is Adobe
+ * internal-only, and Premiere's ExtendScript/CEP surface is being removed in
+ * favor of UXP — so Premiere is UXP and Illustrator is os-script ExtendScript,
+ * not the other way around.
+ */
+export const APP_IDS = ["after_effects", "premiere", "photoshop", "illustrator", "audition"];
+export const APPS = {
+    after_effects: {
+        id: "after_effects",
+        displayName: "After Effects",
+        lane: "socket",
+        panel: "cep",
+        engine: "extendscript",
+        // os-script is a documented emergency fallback, not the primary lane.
+        appleScriptName: "Adobe After Effects",
+    },
+    premiere: {
+        id: "premiere",
+        displayName: "Premiere Pro",
+        lane: "socket",
+        panel: "uxp",
+        engine: "premierepro-api",
+        // No appleScriptName / winProgId: Premiere has no AppleScript or COM DOM.
+    },
+    audition: {
+        id: "audition",
+        displayName: "Audition",
+        lane: "socket",
+        panel: "cep",
+        engine: "extendscript",
+        // No appleScriptName / winProgId: Audition has no AppleScript or COM DOM.
+    },
+    photoshop: {
+        id: "photoshop",
+        displayName: "Photoshop",
+        lane: "socket",
+        panel: "uxp",
+        engine: "uxp-batchplay",
+        // COM/AppleScript ExtendScript is a possible fallback lane, not primary.
+        appleScriptName: "Adobe Photoshop",
+        winProgId: "Photoshop.Application",
+    },
+    illustrator: {
+        id: "illustrator",
+        displayName: "Illustrator",
+        lane: "os-script",
+        engine: "extendscript",
+        appleScriptName: "Adobe Illustrator",
+        winProgId: "Illustrator.Application",
+    },
+};
+export function appInfo(id) {
+    return APPS[id];
+}
+//# sourceMappingURL=apps.js.map

package/dist/apps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps.js","sourceRoot":"","sources":["../src/apps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,CAAU,CAAC;AA+BtG,MAAM,CAAC,MAAM,IAAI,GAA2B;IAC1C,aAAa,EAAE;QACb,EAAE,EAAE,eAAe;QACnB,WAAW,EAAE,eAAe;QAC5B,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,KAAK;QACZ,MAAM,EAAE,cAAc;QACtB,sEAAsE;QACtE,eAAe,EAAE,qBAAqB;KACvC;IACD,QAAQ,EAAE;QACR,EAAE,EAAE,UAAU;QACd,WAAW,EAAE,cAAc;QAC3B,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,KAAK;QACZ,MAAM,EAAE,iBAAiB;QACzB,0EAA0E;KAC3E;IACD,QAAQ,EAAE;QACR,EAAE,EAAE,UAAU;QACd,WAAW,EAAE,UAAU;QACvB,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,KAAK;QACZ,MAAM,EAAE,cAAc;QACtB,0EAA0E;KAC3E;IACD,SAAS,EAAE;QACT,EAAE,EAAE,WAAW;QACf,WAAW,EAAE,WAAW;QACxB,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,KAAK;QACZ,MAAM,EAAE,eAAe;QACvB,yEAAyE;QACzE,eAAe,EAAE,iBAAiB;QAClC,SAAS,EAAE,uBAAuB;KACnC;IACD,WAAW,EAAE;QACX,EAAE,EAAE,aAAa;QACjB,WAAW,EAAE,aAAa;QAC1B,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,cAAc;QACtB,eAAe,EAAE,mBAAmB;QACpC,SAAS,EAAE,yBAAyB;KACrC;CACF,CAAC;AAEF,MAAM,UAAU,OAAO,CAAC,EAAS;IAC/B,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC;AAClB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @brainferno/mcp-bridge-protocol — the frozen contract shared by the server and every
+ * in-app panel: the five hosts, and the v2 wire frames (zod-validated).
+ * See docs/protocol.md. Changes here ripple into every panel.
+ */
+export * from "./apps.js";
+export * from "./protocol.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @brainferno/mcp-bridge-protocol — the frozen contract shared by the server and every
+ * in-app panel: the five hosts, and the v2 wire frames (zod-validated).
+ * See docs/protocol.md. Changes here ripple into every panel.
+ */
+export * from "./apps.js";
+export * from "./protocol.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Wire protocol (v2) between this server's hub and the companion panel running
+ * inside each Creative Cloud application.
+ *
+ * The panel is the client: it dials in to the bridge port, announces which
+ * application it lives in (and authenticates), then waits for commands. Keeping
+ * the panel on the connecting side is not a preference — UXP plugins cannot
+ * listen on a socket, only dial out — and it keeps the one listener the whole
+ * system trusts on the server side, where it can be hardened.
+ *
+ * Commands are *named*, not raw script: the server sends `{name, params}` and
+ * the panel maps the name to a local function. UXP restricts `eval`, and the
+ * Premiere UXP API has no script engine at all, so shipping script strings does
+ * not work there. The generic `eval` command (params `{script}`) is the escape
+ * hatch panels on an ExtendScript engine implement via `evalScript`, which is a
+ * host API rather than JS `eval`.
+ *
+ * Every panel->server frame is validated against a zod schema before use; the
+ * hub never trusts the shape of a frame from the wire.
+ */
+import { z } from "zod";
+export declare const PROTOCOL_VERSION = 2;
+/** How long the server will wait for a command result, by command weight. */
+export type TimeoutClass = "fast" | "slow" | "render";
+/** Panel -> server, the first frame on every connection (within the deadline). */
+export declare const helloFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"hello">;
+    protocolVersion: z.ZodNumber;
+    appId: z.ZodEnum<["after_effects", "premiere", "photoshop", "illustrator", "audition"]>;
+    /** Host build string, e.g. "24.6.1" — informational. */
+    hostVersion: z.ZodOptional<z.ZodString>;
+    /** Panel plugin version, so the server can detect version drift. */
+    panelVersion: z.ZodOptional<z.ZodString>;
+    /** Shared secret; may instead ride the upgrade URL as `?token=`. */
+    token: z.ZodOptional<z.ZodString>;
+    /** Command names this panel implements, for capability gating. */
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    type: "hello";
+    protocolVersion: number;
+    appId: "after_effects" | "premiere" | "photoshop" | "illustrator" | "audition";
+    hostVersion?: string | undefined;
+    panelVersion?: string | undefined;
+    token?: string | undefined;
+    capabilities?: string[] | undefined;
+}, {
+    type: "hello";
+    protocolVersion: number;
+    appId: "after_effects" | "premiere" | "photoshop" | "illustrator" | "audition";
+    hostVersion?: string | undefined;
+    panelVersion?: string | undefined;
+    token?: string | undefined;
+    capabilities?: string[] | undefined;
+}>;
+/** Panel -> server, the outcome of one command. */
+export declare const resultFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"result">;
+    id: z.ZodString;
+    ok: z.ZodBoolean;
+    value: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        line: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        line?: number | undefined;
+    }, {
+        code: string;
+        message: string;
+        line?: number | undefined;
+    }>>;
+    /** Cheap state snapshot returned on mutations, to keep the agent oriented. */
+    appState: z.ZodOptional<z.ZodObject<{
+        activeDocument: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        selection: z.ZodOptional<z.ZodUnknown>;
+        dirty: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        dirty?: boolean | undefined;
+        activeDocument?: string | null | undefined;
+        selection?: unknown;
+    }, {
+        dirty?: boolean | undefined;
+        activeDocument?: string | null | undefined;
+        selection?: unknown;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: "result";
+    id: string;
+    ok: boolean;
+    value?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        line?: number | undefined;
+    } | undefined;
+    appState?: {
+        dirty?: boolean | undefined;
+        activeDocument?: string | null | undefined;
+        selection?: unknown;
+    } | undefined;
+}, {
+    type: "result";
+    id: string;
+    ok: boolean;
+    value?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        line?: number | undefined;
+    } | undefined;
+    appState?: {
+        dirty?: boolean | undefined;
+        activeDocument?: string | null | undefined;
+        selection?: unknown;
+    } | undefined;
+}>;
+/** Panel -> server, incremental progress for a long-running command. */
+export declare const progressFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"progress">;
+    id: z.ZodString;
+    progress: z.ZodOptional<z.ZodNumber>;
+    total: z.ZodOptional<z.ZodNumber>;
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "progress";
+    id: string;
+    message?: string | undefined;
+    progress?: number | undefined;
+    total?: number | undefined;
+}, {
+    type: "progress";
+    id: string;
+    message?: string | undefined;
+    progress?: number | undefined;
+    total?: number | undefined;
+}>;
+/** Panel -> server, liveness. */
+export declare const pongFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"pong">;
+    ts: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "pong";
+    ts?: number | undefined;
+}, {
+    type: "pong";
+    ts?: number | undefined;
+}>;
+export declare const pingFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+    ts: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "ping";
+    ts?: number | undefined;
+}, {
+    type: "ping";
+    ts?: number | undefined;
+}>;
+/** Panel -> server, graceful shutdown (e.g. the kill switch was engaged). */
+export declare const byeFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"bye">;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "bye";
+    reason?: string | undefined;
+}, {
+    type: "bye";
+    reason?: string | undefined;
+}>;
+declare const panelFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"hello">;
+    protocolVersion: z.ZodNumber;
+    appId: z.ZodEnum<["after_effects", "premiere", "photoshop", "illustrator", "audition"]>;
+    /** Host build string, e.g. "24.6.1" — informational. */
+    hostVersion: z.ZodOptional<z.ZodString>;
+    /** Panel plugin version, so the server can detect version drift. */
+    panelVersion: z.ZodOptional<z.ZodString>;
+    /** Shared secret; may instead ride the upgrade URL as `?token=`. */
+    token: z.ZodOptional<z.ZodString>;
+    /** Command names this panel implements, for capability gating. */
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    type: "hello";
+    protocolVersion: number;
+    appId: "after_effects" | "premiere" | "photoshop" | "illustrator" | "audition";
+    hostVersion?: string | undefined;
+    panelVersion?: string | undefined;
+    token?: string | undefined;
+    capabilities?: string[] | undefined;
+}, {
+    type: "hello";
+    protocolVersion: number;
+    appId: "after_effects" | "premiere" | "photoshop" | "illustrator" | "audition";
+    hostVersion?: string | undefined;
+    panelVersion?: string | undefined;
+    token?: string | undefined;
+    capabilities?: string[] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"result">;
+    id: z.ZodString;
+    ok: z.ZodBoolean;
+    value: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        line: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        line?: number | undefined;
+    }, {
+        code: string;
+        message: string;
+        line?: number | undefined;
+    }>>;
+    /** Cheap state snapshot returned on mutations, to keep the agent oriented. */
+    appState: z.ZodOptional<z.ZodObject<{
+        activeDocument: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        selection: z.ZodOptional<z.ZodUnknown>;
+        dirty: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        dirty?: boolean | undefined;
+        activeDocument?: string | null | undefined;
+        selection?: unknown;
+    }, {
+        dirty?: boolean | undefined;
+        activeDocument?: string | null | undefined;
+        selection?: unknown;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: "result";
+    id: string;
+    ok: boolean;
+    value?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        line?: number | undefined;
+    } | undefined;
+    appState?: {
+        dirty?: boolean | undefined;
+        activeDocument?: string | null | undefined;
+        selection?: unknown;
+    } | undefined;
+}, {
+    type: "result";
+    id: string;
+    ok: boolean;
+    value?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        line?: number | undefined;
+    } | undefined;
+    appState?: {
+        dirty?: boolean | undefined;
+        activeDocument?: string | null | undefined;
+        selection?: unknown;
+    } | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"progress">;
+    id: z.ZodString;
+    progress: z.ZodOptional<z.ZodNumber>;
+    total: z.ZodOptional<z.ZodNumber>;
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "progress";
+    id: string;
+    message?: string | undefined;
+    progress?: number | undefined;
+    total?: number | undefined;
+}, {
+    type: "progress";
+    id: string;
+    message?: string | undefined;
+    progress?: number | undefined;
+    total?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"pong">;
+    ts: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "pong";
+    ts?: number | undefined;
+}, {
+    type: "pong";
+    ts?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+    ts: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "ping";
+    ts?: number | undefined;
+}, {
+    type: "ping";
+    ts?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"bye">;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "bye";
+    reason?: string | undefined;
+}, {
+    type: "bye";
+    reason?: string | undefined;
+}>]>;
+export type HelloFrame = z.infer<typeof helloFrameSchema>;
+export type ResultFrame = z.infer<typeof resultFrameSchema>;
+export type ProgressFrame = z.infer<typeof progressFrameSchema>;
+export type PanelFrame = z.infer<typeof panelFrameSchema>;
+/** Server -> panel, accepting the hello. */
+export interface WelcomeFrame {
+    type: "welcome";
+    protocolVersion: number;
+    serverVersion: string;
+    heartbeatIntervalMs: number;
+}
+/** Server -> panel, a named command to run. */
+export interface CmdFrame {
+    type: "cmd";
+    id: string;
+    name: string;
+    params: unknown;
+    timeoutClass: TimeoutClass;
+}
+export interface ServerPingFrame {
+    type: "ping";
+    ts: number;
+}
+export interface ServerByeFrame {
+    type: "bye";
+    reason: string;
+}
+export type ServerFrame = WelcomeFrame | CmdFrame | ServerPingFrame | ServerByeFrame;
+/**
+ * Parses and validates a raw text frame from a panel. Throws a descriptive
+ * Error on anything that is not a well-formed panel frame — callers drop the
+ * frame rather than trusting a partially-shaped object.
+ */
+export declare function parsePanelFrame(raw: string): PanelFrame;
+export {};

package/dist/protocol.js

@@ -0,0 +1,98 @@
+/**
+ * Wire protocol (v2) between this server's hub and the companion panel running
+ * inside each Creative Cloud application.
+ *
+ * The panel is the client: it dials in to the bridge port, announces which
+ * application it lives in (and authenticates), then waits for commands. Keeping
+ * the panel on the connecting side is not a preference — UXP plugins cannot
+ * listen on a socket, only dial out — and it keeps the one listener the whole
+ * system trusts on the server side, where it can be hardened.
+ *
+ * Commands are *named*, not raw script: the server sends `{name, params}` and
+ * the panel maps the name to a local function. UXP restricts `eval`, and the
+ * Premiere UXP API has no script engine at all, so shipping script strings does
+ * not work there. The generic `eval` command (params `{script}`) is the escape
+ * hatch panels on an ExtendScript engine implement via `evalScript`, which is a
+ * host API rather than JS `eval`.
+ *
+ * Every panel->server frame is validated against a zod schema before use; the
+ * hub never trusts the shape of a frame from the wire.
+ */
+import { z } from "zod";
+import { APP_IDS } from "./apps.js";
+export const PROTOCOL_VERSION = 2;
+const errorSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+    line: z.number().int().optional(),
+});
+const appStateSchema = z.object({
+    activeDocument: z.string().nullable().optional(),
+    selection: z.unknown().optional(),
+    dirty: z.boolean().optional(),
+});
+/** Panel -> server, the first frame on every connection (within the deadline). */
+export const helloFrameSchema = z.object({
+    type: z.literal("hello"),
+    protocolVersion: z.number().int(),
+    appId: z.enum(APP_IDS),
+    /** Host build string, e.g. "24.6.1" — informational. */
+    hostVersion: z.string().optional(),
+    /** Panel plugin version, so the server can detect version drift. */
+    panelVersion: z.string().optional(),
+    /** Shared secret; may instead ride the upgrade URL as `?token=`. */
+    token: z.string().optional(),
+    /** Command names this panel implements, for capability gating. */
+    capabilities: z.array(z.string()).optional(),
+});
+/** Panel -> server, the outcome of one command. */
+export const resultFrameSchema = z.object({
+    type: z.literal("result"),
+    id: z.string(),
+    ok: z.boolean(),
+    value: z.unknown().optional(),
+    error: errorSchema.optional(),
+    /** Cheap state snapshot returned on mutations, to keep the agent oriented. */
+    appState: appStateSchema.optional(),
+});
+/** Panel -> server, incremental progress for a long-running command. */
+export const progressFrameSchema = z.object({
+    type: z.literal("progress"),
+    id: z.string(),
+    progress: z.number().optional(),
+    total: z.number().optional(),
+    message: z.string().optional(),
+});
+/** Panel -> server, liveness. */
+export const pongFrameSchema = z.object({ type: z.literal("pong"), ts: z.number().optional() });
+export const pingFrameSchema = z.object({ type: z.literal("ping"), ts: z.number().optional() });
+/** Panel -> server, graceful shutdown (e.g. the kill switch was engaged). */
+export const byeFrameSchema = z.object({ type: z.literal("bye"), reason: z.string().optional() });
+const panelFrameSchema = z.discriminatedUnion("type", [
+    helloFrameSchema,
+    resultFrameSchema,
+    progressFrameSchema,
+    pongFrameSchema,
+    pingFrameSchema,
+    byeFrameSchema,
+]);
+/**
+ * Parses and validates a raw text frame from a panel. Throws a descriptive
+ * Error on anything that is not a well-formed panel frame — callers drop the
+ * frame rather than trusting a partially-shaped object.
+ */
+export function parsePanelFrame(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("frame was not valid JSON");
+    }
+    const result = panelFrameSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`invalid panel frame: ${result.error.issues.map((i) => i.message).join("; ")}`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAKlC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAEH,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAChD,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACjC,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC;AAEH,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACjC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;IACtB,wDAAwD;IACxD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,oEAAoE;IACpE,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACnC,oEAAoE;IACpE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,kEAAkE;IAClE,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC;AAEH,mDAAmD;AACnD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACzB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE;IACf,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC7B,KAAK,EAAE,WAAW,CAAC,QAAQ,EAAE;IAC7B,8EAA8E;IAC9E,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE;CACpC,CAAC,CAAC;AAEH,wEAAwE;AACxE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IAC3B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAEH,iCAAiC;AACjC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAChG,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAEhG,6EAA6E;AAC7E,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAElG,MAAM,gBAAgB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACpD,gBAAgB;IAChB,iBAAiB;IACjB,mBAAmB;IACnB,eAAe;IACf,eAAe;IACf,cAAc;CACf,CAAC,CAAC;AAoCH;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IACD,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@brainferno/mcp-bridge-protocol",
+  "version": "0.1.0",
+  "description": "Shared hosts + wire protocol (v2) for brainferno-mcp-bridge",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "license": "Apache-2.0",
+  "author": "Vincent Parker (Brainferno, LLC)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Brainferno/brainferno-mcp-bridge.git",
+    "directory": "packages/protocol"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}