minecraft-bedrock-mcp-server 0.1.0

package/dist/protocol/handshake.d.ts

@@ -0,0 +1,150 @@
+import { z } from "zod";
+/** A Script API module the behavior pack depends on, e.g. `@minecraft/server`. */
+export declare const ScriptModuleSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    version: string;
+}, {
+    name: string;
+    version: string;
+}>;
+/** A Script API module the behavior pack depends on. */
+export type ScriptModule = z.infer<typeof ScriptModuleSchema>;
+/**
+ * The request envelope for `POST /bridge/handshake`.
+ *
+ * Sent by the behavior pack on startup. The reported Script API module
+ * versions drive server-side capability negotiation, so tools that require an
+ * unavailable capability can fail fast with a clear error.
+ */
+export declare const HandshakeRequestSchema: z.ZodObject<{
+    /** Bridge protocol version the behavior pack implements. */
+    protocol_version: z.ZodString;
+    /** Version of the behavior pack itself. */
+    behavior_pack_version: z.ZodString;
+    /** Minecraft / BDS version, when the behavior pack can determine it. */
+    minecraft_version: z.ZodOptional<z.ZodString>;
+    /** Script API modules and versions the behavior pack imports. */
+    script_modules: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        version: string;
+    }, {
+        name: string;
+        version: string;
+    }>, "many">;
+    /** Stable identifier of the world the behavior pack is running in. */
+    world_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    protocol_version: string;
+    behavior_pack_version: string;
+    script_modules: {
+        name: string;
+        version: string;
+    }[];
+    world_id: string;
+    minecraft_version?: string | undefined;
+}, {
+    protocol_version: string;
+    behavior_pack_version: string;
+    script_modules: {
+        name: string;
+        version: string;
+    }[];
+    world_id: string;
+    minecraft_version?: string | undefined;
+}>;
+/** The request envelope for `POST /bridge/handshake`. */
+export type HandshakeRequest = z.infer<typeof HandshakeRequestSchema>;
+/**
+ * A subscription the server asks the behavior pack to re-arm.
+ *
+ * A behavior pack restart loses its Script API subscriptions; the handshake
+ * response replays the still-active ones so events resume without client
+ * involvement.
+ */
+export declare const ResyncSubscriptionSchema: z.ZodObject<{
+    subscription_id: z.ZodString;
+    event_type: z.ZodString;
+    filter: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    subscription_id: string;
+    event_type: string;
+    filter?: unknown;
+}, {
+    subscription_id: string;
+    event_type: string;
+    filter?: unknown;
+}>;
+/** A subscription the server asks the behavior pack to re-arm. */
+export type ResyncSubscription = z.infer<typeof ResyncSubscriptionSchema>;
+/**
+ * The response envelope for `POST /bridge/handshake`.
+ *
+ * A discriminated union on `accepted`: the server refuses a behavior pack
+ * whose bridge protocol major version is incompatible.
+ */
+export declare const HandshakeResponseSchema: z.ZodDiscriminatedUnion<"accepted", [z.ZodObject<{
+    accepted: z.ZodLiteral<true>;
+    /** Version of this MCP server. */
+    server_version: z.ZodString;
+    /** Bridge protocol version this server implements. */
+    protocol_version: z.ZodString;
+    /** Long-poll timeout the behavior pack should use for `GET /bridge/poll`. */
+    poll_timeout_ms: z.ZodNumber;
+    /** Subscriptions to re-arm after a behavior-pack restart. */
+    resync_subscriptions: z.ZodArray<z.ZodObject<{
+        subscription_id: z.ZodString;
+        event_type: z.ZodString;
+        filter: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        subscription_id: string;
+        event_type: string;
+        filter?: unknown;
+    }, {
+        subscription_id: string;
+        event_type: string;
+        filter?: unknown;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    protocol_version: string;
+    accepted: true;
+    server_version: string;
+    poll_timeout_ms: number;
+    resync_subscriptions: {
+        subscription_id: string;
+        event_type: string;
+        filter?: unknown;
+    }[];
+}, {
+    protocol_version: string;
+    accepted: true;
+    server_version: string;
+    poll_timeout_ms: number;
+    resync_subscriptions: {
+        subscription_id: string;
+        event_type: string;
+        filter?: unknown;
+    }[];
+}>, z.ZodObject<{
+    accepted: z.ZodLiteral<false>;
+    /** Human-readable reason the connection was refused. */
+    reason: z.ZodString;
+    /** Bridge protocol version this server implements, for diagnostics. */
+    server_protocol_version: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    accepted: false;
+    reason: string;
+    server_protocol_version: string;
+}, {
+    accepted: false;
+    reason: string;
+    server_protocol_version: string;
+}>]>;
+/** The response envelope for `POST /bridge/handshake`. */
+export type HandshakeResponse = z.infer<typeof HandshakeResponseSchema>;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/protocol/handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/protocol/handshake.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,kFAAkF;AAClF,eAAO,MAAM,kBAAkB;;;;;;;;;EAG7B,CAAC;AAEH,wDAAwD;AACxD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;IACjC,4DAA4D;;IAE5D,2CAA2C;;IAE3C,wEAAwE;;IAExE,iEAAiE;;;;;;;;;;;IAEjE,sEAAsE;;;;;;;;;;;;;;;;;;;;EAEtE,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;EAInC,CAAC;AAEH,kEAAkE;AAClE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;IAGhC,kCAAkC;;IAElC,sDAAsD;;IAEtD,6EAA6E;;IAE7E,6DAA6D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAK7D,wDAAwD;;IAExD,uEAAuE;;;;;;;;;;IAGzE,CAAC;AAEH,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/protocol/handshake.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { SubscriptionIdSchema } from "./event.js";
+/** A Script API module the behavior pack depends on, e.g. `@minecraft/server`. */
+export const ScriptModuleSchema = z.object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+});
+/**
+ * The request envelope for `POST /bridge/handshake`.
+ *
+ * Sent by the behavior pack on startup. The reported Script API module
+ * versions drive server-side capability negotiation, so tools that require an
+ * unavailable capability can fail fast with a clear error.
+ */
+export const HandshakeRequestSchema = z.object({
+    /** Bridge protocol version the behavior pack implements. */
+    protocol_version: z.string().min(1),
+    /** Version of the behavior pack itself. */
+    behavior_pack_version: z.string().min(1),
+    /** Minecraft / BDS version, when the behavior pack can determine it. */
+    minecraft_version: z.string().min(1).optional(),
+    /** Script API modules and versions the behavior pack imports. */
+    script_modules: z.array(ScriptModuleSchema),
+    /** Stable identifier of the world the behavior pack is running in. */
+    world_id: z.string().min(1),
+});
+/**
+ * A subscription the server asks the behavior pack to re-arm.
+ *
+ * A behavior pack restart loses its Script API subscriptions; the handshake
+ * response replays the still-active ones so events resume without client
+ * involvement.
+ */
+export const ResyncSubscriptionSchema = z.object({
+    subscription_id: SubscriptionIdSchema,
+    event_type: z.string().min(1),
+    filter: z.unknown().optional(),
+});
+/**
+ * The response envelope for `POST /bridge/handshake`.
+ *
+ * A discriminated union on `accepted`: the server refuses a behavior pack
+ * whose bridge protocol major version is incompatible.
+ */
+export const HandshakeResponseSchema = z.discriminatedUnion("accepted", [
+    z.object({
+        accepted: z.literal(true),
+        /** Version of this MCP server. */
+        server_version: z.string(),
+        /** Bridge protocol version this server implements. */
+        protocol_version: z.string(),
+        /** Long-poll timeout the behavior pack should use for `GET /bridge/poll`. */
+        poll_timeout_ms: z.number().int().positive(),
+        /** Subscriptions to re-arm after a behavior-pack restart. */
+        resync_subscriptions: z.array(ResyncSubscriptionSchema),
+    }),
+    z.object({
+        accepted: z.literal(false),
+        /** Human-readable reason the connection was refused. */
+        reason: z.string(),
+        /** Bridge protocol version this server implements, for diagnostics. */
+        server_protocol_version: z.string(),
+    }),
+]);
+//# sourceMappingURL=handshake.js.map

package/dist/protocol/handshake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.js","sourceRoot":"","sources":["../../src/protocol/handshake.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,kFAAkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC3B,CAAC,CAAC;AAKH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,4DAA4D;IAC5D,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,2CAA2C;IAC3C,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxC,wEAAwE;IACxE,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC/C,iEAAiE;IACjE,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC;IAC3C,sEAAsE;IACtE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC5B,CAAC,CAAC;AAKH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,eAAe,EAAE,oBAAoB;IACrC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAKH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,kBAAkB,CAAC,UAAU,EAAE;IACtE,CAAC,CAAC,MAAM,CAAC;QACP,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;QACzB,kCAAkC;QAClC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;QAC1B,sDAAsD;QACtD,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE;QAC5B,6EAA6E;QAC7E,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;QAC5C,6DAA6D;QAC7D,oBAAoB,EAAE,CAAC,CAAC,KAAK,CAAC,wBAAwB,CAAC;KACxD,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;QAC1B,wDAAwD;QACxD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;QAClB,uEAAuE;QACvE,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE;KACpC,CAAC;CACH,CAAC,CAAC"}

package/dist/protocol/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The bridge protocol — the wire contract between the MCP server and the BDS
+ * behavior pack.
+ *
+ * This module is a self-contained leaf: it depends only on `zod` and nothing
+ * else in `src/`, so it can be extracted into a package shared with the
+ * behavior-pack repository without untangling dependencies.
+ */
+export * from "./protocol-version.js";
+export * from "./command.js";
+export * from "./result.js";
+export * from "./event.js";
+export * from "./handshake.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/protocol/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/dist/protocol/index.js

@@ -0,0 +1,14 @@
+/**
+ * The bridge protocol — the wire contract between the MCP server and the BDS
+ * behavior pack.
+ *
+ * This module is a self-contained leaf: it depends only on `zod` and nothing
+ * else in `src/`, so it can be extracted into a package shared with the
+ * behavior-pack repository without untangling dependencies.
+ */
+export * from "./protocol-version.js";
+export * from "./command.js";
+export * from "./result.js";
+export * from "./event.js";
+export * from "./handshake.js";
+//# sourceMappingURL=index.js.map

package/dist/protocol/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/dist/protocol/protocol-version.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Version of the bridge protocol implemented by this server — the contract
+ * between the MCP server and the BDS behavior pack.
+ *
+ * Semantic versioning applies. The behavior pack and server are compatible
+ * when they share the same major version; the major is negotiated during the
+ * handshake (see `handshake.ts`).
+ */
+export declare const PROTOCOL_VERSION = "1.0.0";
+/** Extracts the major version from a semver string, or `null` if unparseable. */
+export declare function parseMajor(version: string): number | null;
+/**
+ * Whether a peer's protocol version is compatible with this server's.
+ *
+ * Compatibility requires an equal, parseable major version.
+ */
+export declare function isProtocolCompatible(peerVersion: string): boolean;
+//# sourceMappingURL=protocol-version.d.ts.map

package/dist/protocol/protocol-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-version.d.ts","sourceRoot":"","sources":["../../src/protocol/protocol-version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAIxC,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIzD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAIjE"}

package/dist/protocol/protocol-version.js

@@ -0,0 +1,28 @@
+/**
+ * Version of the bridge protocol implemented by this server — the contract
+ * between the MCP server and the BDS behavior pack.
+ *
+ * Semantic versioning applies. The behavior pack and server are compatible
+ * when they share the same major version; the major is negotiated during the
+ * handshake (see `handshake.ts`).
+ */
+export const PROTOCOL_VERSION = "1.0.0";
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/;
+/** Extracts the major version from a semver string, or `null` if unparseable. */
+export function parseMajor(version) {
+    const match = SEMVER.exec(version);
+    if (!match)
+        return null;
+    return Number(match[1]);
+}
+/**
+ * Whether a peer's protocol version is compatible with this server's.
+ *
+ * Compatibility requires an equal, parseable major version.
+ */
+export function isProtocolCompatible(peerVersion) {
+    const peerMajor = parseMajor(peerVersion);
+    const ourMajor = parseMajor(PROTOCOL_VERSION);
+    return peerMajor !== null && ourMajor !== null && peerMajor === ourMajor;
+}
+//# sourceMappingURL=protocol-version.js.map

package/dist/protocol/protocol-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-version.js","sourceRoot":"","sources":["../../src/protocol/protocol-version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;AAExC,MAAM,MAAM,GAAG,kCAAkC,CAAC;AAElD,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC9C,OAAO,SAAS,KAAK,IAAI,IAAI,QAAQ,KAAK,IAAI,IAAI,SAAS,KAAK,QAAQ,CAAC;AAC3E,CAAC"}

package/dist/protocol/result.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+/**
+ * An error reported by the behavior pack for a failed command.
+ *
+ * `code` is a free-form string at the protocol layer — the behavior pack may
+ * report codes the server does not enumerate. The server narrows it to a known
+ * {@link import("../errors/error-codes.js").ErrorCode} where possible.
+ */
+export declare const CommandErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    details?: unknown;
+}, {
+    code: string;
+    message: string;
+    details?: unknown;
+}>;
+/** An error reported by the behavior pack for a failed command. */
+export type CommandError = z.infer<typeof CommandErrorSchema>;
+/**
+ * The result of a command, reported by the behavior pack via
+ * `POST /bridge/result`.
+ *
+ * Modeled as a discriminated union on `status`: an `ok` result carries a
+ * `result` payload and an `error` result carries an `error` — the two are
+ * mutually exclusive by construction.
+ */
+export declare const CommandResultSchema: z.ZodDiscriminatedUnion<"status", [z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodLiteral<"ok">;
+    result: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    status: "ok";
+    id: string;
+    result?: unknown;
+}, {
+    status: "ok";
+    id: string;
+    result?: unknown;
+}>, z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodLiteral<"error">;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        details?: unknown;
+    }, {
+        code: string;
+        message: string;
+        details?: unknown;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    status: "error";
+    id: string;
+}, {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    status: "error";
+    id: string;
+}>]>;
+/** The result of a command, reported by the behavior pack. */
+export type CommandResult = z.infer<typeof CommandResultSchema>;
+//# sourceMappingURL=result.d.ts.map

package/dist/protocol/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/protocol/result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;EAI7B,CAAC;AAEH,mEAAmE;AACnE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAW9B,CAAC;AAEH,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/protocol/result.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { CommandIdSchema } from "./command.js";
+/**
+ * An error reported by the behavior pack for a failed command.
+ *
+ * `code` is a free-form string at the protocol layer — the behavior pack may
+ * report codes the server does not enumerate. The server narrows it to a known
+ * {@link import("../errors/error-codes.js").ErrorCode} where possible.
+ */
+export const CommandErrorSchema = z.object({
+    code: z.string().min(1),
+    message: z.string(),
+    details: z.unknown().optional(),
+});
+/**
+ * The result of a command, reported by the behavior pack via
+ * `POST /bridge/result`.
+ *
+ * Modeled as a discriminated union on `status`: an `ok` result carries a
+ * `result` payload and an `error` result carries an `error` — the two are
+ * mutually exclusive by construction.
+ */
+export const CommandResultSchema = z.discriminatedUnion("status", [
+    z.object({
+        id: CommandIdSchema,
+        status: z.literal("ok"),
+        result: z.unknown(),
+    }),
+    z.object({
+        id: CommandIdSchema,
+        status: z.literal("error"),
+        error: CommandErrorSchema,
+    }),
+]);
+//# sourceMappingURL=result.js.map

package/dist/protocol/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/protocol/result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAKH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE;IAChE,CAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,eAAe;QACnB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;QACvB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;KACpB,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,eAAe;QACnB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;QAC1B,KAAK,EAAE,kBAAkB;KAC1B,CAAC;CACH,CAAC,CAAC"}

package/dist/queue/command-id.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Correlation identifier for a queued command (`cmd_<ULID>`).
+ *
+ * A plain `string` alias: the wire protocol carries these as strings, and a
+ * branded type would force casts at every protocol boundary for no real
+ * safety gain here.
+ */
+export type CommandId = string;
+/** Identifier for an event subscription (`sub_<ULID>`). */
+export type SubscriptionId = string;
+/** Creates a new command identifier. */
+export declare function newCommandId(): CommandId;
+/** Creates a new subscription identifier. */
+export declare function newSubscriptionId(): SubscriptionId;
+//# sourceMappingURL=command-id.d.ts.map

package/dist/queue/command-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-id.d.ts","sourceRoot":"","sources":["../../src/queue/command-id.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAkCpC,wCAAwC;AACxC,wBAAgB,YAAY,IAAI,SAAS,CAExC;AAED,6CAA6C;AAC7C,wBAAgB,iBAAiB,IAAI,cAAc,CAElD"}

package/dist/queue/command-id.js

@@ -0,0 +1,38 @@
+import { randomInt } from "node:crypto";
+const CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const TIMESTAMP_LENGTH = 10;
+const RANDOMNESS_LENGTH = 16;
+/** Encodes a millisecond timestamp as 10 Crockford base32 characters. */
+function encodeTimestamp(timestamp) {
+    let remaining = timestamp;
+    let encoded = "";
+    for (let i = 0; i < TIMESTAMP_LENGTH; i += 1) {
+        encoded = CROCKFORD_BASE32.charAt(remaining % 32) + encoded;
+        remaining = Math.floor(remaining / 32);
+    }
+    return encoded;
+}
+/** Generates 16 Crockford base32 characters of cryptographic randomness. */
+function encodeRandomness() {
+    let encoded = "";
+    for (let i = 0; i < RANDOMNESS_LENGTH; i += 1) {
+        encoded += CROCKFORD_BASE32.charAt(randomInt(32));
+    }
+    return encoded;
+}
+/**
+ * Generates a ULID — a 26-character, lexicographically sortable identifier
+ * combining a 48-bit timestamp with 80 bits of randomness.
+ */
+function ulid() {
+    return encodeTimestamp(Date.now()) + encodeRandomness();
+}
+/** Creates a new command identifier. */
+export function newCommandId() {
+    return `cmd_${ulid()}`;
+}
+/** Creates a new subscription identifier. */
+export function newSubscriptionId() {
+    return `sub_${ulid()}`;
+}
+//# sourceMappingURL=command-id.js.map

package/dist/queue/command-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-id.js","sourceRoot":"","sources":["../../src/queue/command-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAcxC,MAAM,gBAAgB,GAAG,kCAAkC,CAAC;AAC5D,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B,yEAAyE;AACzE,SAAS,eAAe,CAAC,SAAiB;IACxC,IAAI,SAAS,GAAG,SAAS,CAAC;IAC1B,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,gBAAgB,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,SAAS,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC;QAC5D,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,4EAA4E;AAC5E,SAAS,gBAAgB;IACvB,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,iBAAiB,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9C,OAAO,IAAI,gBAAgB,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,SAAS,IAAI;IACX,OAAO,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,gBAAgB,EAAE,CAAC;AAC1D,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,YAAY;IAC1B,OAAO,OAAO,IAAI,EAAE,EAAE,CAAC;AACzB,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,IAAI,EAAE,EAAE,CAAC;AACzB,CAAC"}

package/dist/queue/command-queue.d.ts

@@ -0,0 +1,90 @@
+import type { Command } from "../protocol/command.js";
+import type { CommandResult } from "../protocol/result.js";
+import type { CommandThrottle } from "./command-throttle.js";
+/** A request to enqueue a command and await its correlated result. */
+export interface EnqueueRequest {
+    /** Command kind — the MCP tool name, e.g. `mc_block_set`. */
+    readonly kind: string;
+    /** Command payload, validated against the tool's input schema by the caller. */
+    readonly payload: unknown;
+    /** Server-side correlation id linking the originating request to this command. */
+    readonly correlationId: string;
+    /** How long, in milliseconds, to await a result before failing. */
+    readonly timeoutMs: number;
+}
+/** Options for a long-poll dequeue. */
+export interface DequeueOptions {
+    /** Maximum number of commands to return in one batch. */
+    readonly max: number;
+    /** How long, in milliseconds, to hold the poll open while the queue is empty. */
+    readonly timeoutMs: number;
+    /** Aborts the poll when the underlying HTTP connection closes. */
+    readonly signal: AbortSignal;
+}
+/** A point-in-time snapshot of queue state, for health checks and metrics. */
+export interface CommandQueueStats {
+    /** Commands enqueued but not yet dequeued. */
+    readonly depth: number;
+    /** Commands dequeued but not yet settled. */
+    readonly inFlight: number;
+    /** Whether a behavior pack is currently considered connected. */
+    readonly bridgeConnected: boolean;
+}
+/**
+ * In-memory command queue bridging MCP tool calls to the behavior pack.
+ *
+ * Tool calls enqueue commands and await their correlated results; the behavior
+ * pack drains commands via a long poll and reports results back. The queue is
+ * not persisted across restarts.
+ */
+export interface CommandQueue {
+    /**
+     * Enqueues a command and resolves with the behavior pack's result.
+     *
+     * Resolves with a {@link CommandResult} (`ok` or `error`) once the pack
+     * reports one. Rejects with a `BridgeError` when the bridge itself cannot
+     * complete the command: `COMMAND_THROTTLED`, `QUEUE_FULL`,
+     * `BRIDGE_DISCONNECTED`, or `COMMAND_TIMEOUT`.
+     */
+    enqueueAndAwait(request: EnqueueRequest): Promise<CommandResult>;
+    /**
+     * Long-poll dequeue for the behavior pack.
+     *
+     * Resolves immediately with up to `max` commands when work is available,
+     * otherwise holds the poll open until a command arrives, `timeoutMs`
+     * elapses, or the request is aborted — resolving with `[]` in the latter
+     * two cases.
+     */
+    dequeue(options: DequeueOptions): Promise<Command[]>;
+    /**
+     * Delivers a result reported by the behavior pack.
+     *
+     * @returns `false` if no pending command matches `result.id` — typically a
+     *   result that arrived after the command's deadline.
+     */
+    settle(result: CommandResult): boolean;
+    /** Returns a snapshot of queue state. */
+    stats(): CommandQueueStats;
+    /**
+     * Rejects all pending commands and releases parked polls. Used during
+     * graceful shutdown; the queue must not be used afterwards.
+     */
+    close(): void;
+}
+/** Configuration for {@link createCommandQueue}. */
+export interface CommandQueueOptions {
+    /** Per-kind throttle protecting the behavior pack's script watchdog. */
+    readonly throttle: CommandThrottle;
+    /** Maximum outstanding commands before enqueue fails with `QUEUE_FULL`. */
+    readonly maxOutstanding: number;
+    /**
+     * Milliseconds after the last poll during which the behavior pack is still
+     * considered connected. Should exceed the poll timeout.
+     */
+    readonly livenessWindowMs: number;
+    /** Clock source, injectable for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/** Creates an in-memory {@link CommandQueue}. */
+export declare function createCommandQueue(options: CommandQueueOptions): CommandQueue;
+//# sourceMappingURL=command-queue.d.ts.map

package/dist/queue/command-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-queue.d.ts","sourceRoot":"","sources":["../../src/queue/command-queue.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAEjE;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAErD;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC;IAEvC,yCAAyC;IACzC,KAAK,IAAI,iBAAiB,CAAC;IAE3B;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAiBD,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA8J7E"}