mafia-studio-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Resonance Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# mafia-studio-protocol
+
+Shared wire protocol types for [MafiaStudio](https://github.com/The-Resonance-Lab/MafiaStudio) realtime.
+
+Types-only — no runtime. You almost never import this directly; it's re-exported through [`mafia-studio-adapter`](https://www.npmjs.com/package/mafia-studio-adapter).
+
+## What's in here
+
+- Frame envelope (`UniversalFrame`, `ServerFrame`)
+- Phase names, action names, message channels
+- Seat roles, participant types, factions
+- Room welcome / message / phase-change / move-result / game-over payloads
+
+## Version
+
+`0.1.x` — the protocol is still evolving. Adapter and realtime both pin the same minor.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,204 @@
+export declare const PROTOCOL_VERSION: 1;
+export type PhaseName = "LOBBY" | "NIGHT_0" | "DAY_DISCUSSION" | "DAY_VOTE" | "NIGHT" | "REVEAL" | "GAME_OVER";
+export type SeatRole = "town" | "mafia" | "detective";
+export type ParticipantType = "human" | "persona" | "empty";
+export type MessageChannel = "public" | "mafia_whisper" | "system";
+export type Faction = "town" | "mafia";
+export type MafiaActionName = "post_message" | "stay_quiet" | "vote_for" | "abstain" | "whisper_to_mafia" | "nominate_kill" | "investigate" | "accuse";
+export type MoveKind = "vote_for" | "abstain" | "nominate_kill" | "investigate" | "timeout";
+export type MoveResultKind = "vote_tally" | "kill_result" | "investigation_result" | "timeout" | "merged";
+export type ErrorCode = "TURN_DEADLINE_MISSED" | "PHASE_ADVANCED" | "PHASE_DISALLOWS_ACTION" | "UNKNOWN_ACTION" | "SEAT_TAKEN" | "TABLE_CLOSED" | "AUTH_FAILED" | "RATE_LIMITED" | "INTERNAL";
+export interface PhaseConfig {
+    night_0_ms: number;
+    day_discussion_ms: number;
+    day_vote_ms: number;
+    night_ms: number;
+    reveal_ms: number;
+}
+export declare const DEFAULT_PHASE_CONFIG: PhaseConfig;
+export declare const ALLOWED_ACTIONS_BY_PHASE: Record<PhaseName, Partial<Record<SeatRole, MafiaActionName[]>>>;
+/** Minimal structural mirror of emocentric's ContextEvent. Adapter casts between the two. */
+export interface WireContextEvent<TRaw = unknown> {
+    id: string;
+    occurredAt: string;
+    platform: string;
+    channelId?: string;
+    actor: {
+        id: string;
+        displayName?: string;
+        metadata?: Record<string, unknown>;
+    };
+    payload: WirePayload;
+    raw?: TRaw;
+    metadata?: Record<string, unknown>;
+}
+/** Aligned with emocentric's Payload shapes so the adapter can pass through
+ *  the ContextEvent directly. We use `text` for chat and `action` for game
+ *  events (phase changes, move results); teams' personas naturally consume
+ *  both. */
+export type WirePayload = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "action";
+    name: string;
+    description?: string;
+    data?: Record<string, unknown>;
+};
+export interface UniversalFrame<TData = unknown> {
+    v: typeof PROTOCOL_VERSION;
+    type: string;
+    seq: number;
+    at: string;
+    table_id: string;
+    data: TData;
+}
+export interface RoomWelcomeSeat {
+    seat_id: string;
+    seat_index: number;
+    label: string;
+    kind: ParticipantType;
+    alive: boolean;
+}
+export interface RoomWelcomeData {
+    seat_id: string;
+    seat_index: number;
+    seat_label: string;
+    /** Only revealed to the owning seat. Mafia see mafia; town see generic "town". */
+    seat_role: SeatRole;
+    /** Other-seat roles visible to this seat (mafia see fellow mafia). */
+    visible_roles?: Record<string, SeatRole>;
+    table: {
+        id: string;
+        name: string;
+        phase_config: PhaseConfig;
+        seats: RoomWelcomeSeat[];
+    };
+    phase: {
+        name: PhaseName;
+        started_at: string;
+        ends_at: string | null;
+        round: number;
+    };
+    resume?: {
+        last_seq: number;
+    };
+}
+export interface RoomMessageData {
+    message_id: string;
+    seat_id: string;
+    seat_label: string;
+    channel: MessageChannel;
+    text: string;
+    phase: PhaseName;
+    round: number;
+}
+export interface AgentTurnRequestData {
+    request_id: string;
+    context_event: WireContextEvent;
+    deadline_ms: number;
+    allowed_actions: MafiaActionName[];
+}
+export interface PhaseChangeData {
+    from: PhaseName | null;
+    to: PhaseName;
+    round: number;
+    started_at: string;
+    ends_at: string | null;
+    allowed_actions_by_role: Partial<Record<SeatRole, MafiaActionName[]>>;
+}
+export interface MoveResultData {
+    move_id: string;
+    kind: MoveResultKind;
+    phase: PhaseName;
+    round: number;
+    payload: Record<string, unknown>;
+}
+export interface RoundEndData {
+    round: number;
+    dead_seats: Array<{
+        seat_id: string;
+        seat_label: string;
+    }>;
+    next_phase: PhaseName;
+}
+export interface GameOverData {
+    winning_faction: Faction | null;
+    per_seat_outcomes: Array<{
+        seat_id: string;
+        seat_label: string;
+        role: SeatRole;
+        alive: boolean;
+        won: boolean;
+    }>;
+    scoring: Array<{
+        seat_id: string;
+        score: number;
+    }>;
+}
+export interface ErrorData {
+    code: ErrorCode;
+    request_id?: string;
+    message: string;
+}
+/** Runtime shape of every server → client frame. We keep `data` as `unknown`
+ *  in the base type so the engine can construct frames without contorting to
+ *  a discriminated union; consumers narrow via `frame.type` and cast `data`
+ *  to the matching interface below. */
+export type ServerFrame = UniversalFrame<unknown> & {
+    type: string;
+};
+export type ServerFrameData = RoomWelcomeData | RoomMessageData | AgentTurnRequestData | PhaseChangeData | MoveResultData | RoundEndData | GameOverData | ErrorData | {
+    ack_seq: number;
+};
+export interface AgentActionData {
+    request_id: string;
+    action: {
+        name: MafiaActionName;
+        params: Record<string, unknown>;
+    };
+}
+/** Wire-safe subset of emocentric's AgentResult — we accept anything JSON. */
+export interface AgentTelemetryData {
+    request_id: string;
+    context_event_id: string;
+    agent_result: Record<string, unknown>;
+}
+export interface AgentHeartbeatData {
+    process_ms_since_start: number;
+    queue_depth: number;
+}
+export interface ChatSendData {
+    text: string;
+}
+export interface MoveSubmitData {
+    kind: MoveKind;
+    params: Record<string, unknown>;
+}
+export interface ClientFrame<TData = unknown> {
+    v: typeof PROTOCOL_VERSION;
+    type: string;
+    seq: number;
+    at?: string;
+    data: TData;
+}
+export type PersonaClientFrame = (ClientFrame<AgentActionData> & {
+    type: "agent.action";
+}) | (ClientFrame<AgentTelemetryData> & {
+    type: "agent.telemetry";
+}) | (ClientFrame<AgentHeartbeatData> & {
+    type: "agent.heartbeat";
+});
+export type HumanClientFrame = (ClientFrame<ChatSendData> & {
+    type: "chat.send";
+}) | (ClientFrame<MoveSubmitData> & {
+    type: "move.submit";
+});
+export type AnyClientFrame = PersonaClientFrame | HumanClientFrame;
+/** Which S→C frame types the SSE monitor stream forwards. */
+export declare const MONITOR_STREAM_EVENTS: readonly ["room.message", "phase.change", "move.result", "round.end", "game.over", "agent.telemetry"];
+export declare function allowedActionsFor(phase: PhaseName, role: SeatRole): MafiaActionName[];
+export declare function isDeadlineForPhase(phase: PhaseName, config: PhaseConfig): number;
+export declare function nextPhaseName(current: PhaseName): PhaseName;
+export declare function phaseDurationMs(phase: PhaseName, config: PhaseConfig): number;
+export declare function defaultFallbackAction(allowed: readonly MafiaActionName[]): MafiaActionName;

package/dist/index.js

@@ -0,0 +1,107 @@
+export const PROTOCOL_VERSION = 1;
+export const DEFAULT_PHASE_CONFIG = {
+    night_0_ms: 20_000,
+    day_discussion_ms: 180_000,
+    day_vote_ms: 60_000,
+    night_ms: 45_000,
+    reveal_ms: 15_000,
+};
+export const ALLOWED_ACTIONS_BY_PHASE = {
+    LOBBY: { town: [], mafia: [], detective: [] },
+    NIGHT_0: { town: [], mafia: ["whisper_to_mafia"], detective: [] },
+    DAY_DISCUSSION: {
+        town: ["post_message", "stay_quiet"],
+        mafia: ["post_message", "stay_quiet"],
+        detective: ["post_message", "stay_quiet"],
+    },
+    DAY_VOTE: {
+        town: ["vote_for", "abstain"],
+        mafia: ["vote_for", "abstain"],
+        detective: ["vote_for", "abstain"],
+    },
+    NIGHT: {
+        town: ["stay_quiet"],
+        mafia: ["whisper_to_mafia", "nominate_kill"],
+        detective: ["investigate"],
+    },
+    REVEAL: {
+        town: ["post_message", "stay_quiet"],
+        mafia: ["post_message", "stay_quiet"],
+        detective: ["post_message", "stay_quiet"],
+    },
+    GAME_OVER: { town: [], mafia: [], detective: [] },
+};
+// ============================================================================
+// Helpers
+// ============================================================================
+/** Which S→C frame types the SSE monitor stream forwards. */
+export const MONITOR_STREAM_EVENTS = [
+    "room.message",
+    "phase.change",
+    "move.result",
+    "round.end",
+    "game.over",
+    "agent.telemetry",
+];
+export function allowedActionsFor(phase, role) {
+    return ALLOWED_ACTIONS_BY_PHASE[phase][role] ?? [];
+}
+export function isDeadlineForPhase(phase, config) {
+    switch (phase) {
+        case "DAY_DISCUSSION":
+            return 15_000;
+        case "DAY_VOTE":
+            return 10_000;
+        case "NIGHT":
+            return 8_000;
+        case "REVEAL":
+            return 8_000;
+        case "NIGHT_0":
+            return 8_000;
+        default:
+            return 5_000;
+    }
+}
+export function nextPhaseName(current) {
+    switch (current) {
+        case "LOBBY":
+            return "NIGHT_0";
+        case "NIGHT_0":
+            return "DAY_DISCUSSION";
+        case "DAY_DISCUSSION":
+            return "DAY_VOTE";
+        case "DAY_VOTE":
+            return "REVEAL";
+        case "REVEAL":
+            return "NIGHT";
+        case "NIGHT":
+            return "DAY_DISCUSSION";
+        case "GAME_OVER":
+            return "GAME_OVER";
+    }
+}
+export function phaseDurationMs(phase, config) {
+    switch (phase) {
+        case "NIGHT_0":
+            return config.night_0_ms;
+        case "DAY_DISCUSSION":
+            return config.day_discussion_ms;
+        case "DAY_VOTE":
+            return config.day_vote_ms;
+        case "NIGHT":
+            return config.night_ms;
+        case "REVEAL":
+            return config.reveal_ms;
+        case "LOBBY":
+        case "GAME_OVER":
+            return 0;
+    }
+}
+export function defaultFallbackAction(allowed) {
+    if (allowed.includes("stay_quiet"))
+        return "stay_quiet";
+    if (allowed.includes("abstain"))
+        return "abstain";
+    return allowed[0] ?? "stay_quiet";
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "mafia-studio-protocol",
+  "version": "0.1.0",
+  "description": "Shared wire protocol types (frames, phases, action names) for MafiaStudio realtime and its team adapters.",
+  "keywords": ["mafia", "mafiastudio", "protocol", "websocket", "types"],
+  "license": "MIT",
+  "homepage": "https://github.com/The-Resonance-Lab/MafiaStudio",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/The-Resonance-Lab/MafiaStudio.git",
+    "directory": "packages/protocol"
+  },
+  "bugs": {
+    "url": "https://github.com/The-Resonance-Lab/MafiaStudio/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "5.6.3"
+  }
+}