@vibevibes/mcp 0.2.0 → 0.3.1

package/dist/tick-engine.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Tick Engine — server-side tick loop for experiences with netcode: "tick".
+ *
+ * Runs at a fixed tick rate, executing tool calls from the tick context.
+ * The tick engine provides the timing infrastructure; experiences define
+ * what happens each tick via their tool handlers.
+ */
+import type { ToolCtx, ToolEvent } from "@vibevibes/sdk";
+import type { EventEmitter } from "events";
+/** ToolEvent extended with observation field (computed server-side after tool execution). */
+interface TickToolEvent extends ToolEvent {
+    observation?: Record<string, unknown>;
+}
+/** Minimal Room interface — what the tick engine needs from a room. */
+export interface TickRoom {
+    readonly id: string;
+    readonly experienceId: string;
+    readonly config: Record<string, unknown>;
+    sharedState: Record<string, unknown>;
+    participantList(): string[];
+    broadcastToAll(message: Record<string, unknown>): void;
+    broadcastStateUpdate?(extra: {
+        changedBy: string;
+        tick?: unknown;
+    }, forceFullState?: boolean): void;
+    appendEvent(event: TickToolEvent): void;
+    enqueueExecution<T>(fn: () => Promise<T>): Promise<T>;
+}
+/** Minimal experience interface — what the tick engine needs. */
+export interface TickExperience {
+    module: {
+        manifest: {
+            id: string;
+        };
+        tools: Array<{
+            name: string;
+            input_schema?: {
+                parse?: (input: unknown) => unknown;
+            };
+            handler: (ctx: ToolCtx, input: unknown) => Promise<unknown>;
+        }>;
+        observe?: (state: Record<string, unknown>, event: TickToolEvent, actorId: string) => Record<string, unknown>;
+    };
+}
+export declare class TickEngine {
+    private room;
+    private experience;
+    private roomEvents;
+    private interval;
+    private tickCount;
+    private tickRateMs;
+    private startedAt;
+    private _running;
+    private _stopped;
+    private _stateSetThisTick;
+    constructor(room: TickRoom, experience: TickExperience, roomEvents: EventEmitter, tickRateMs?: number);
+    /** Start the tick loop. Uses self-correcting setTimeout to prevent timing drift. */
+    start(): void;
+    /** Schedule the next tick with drift correction. */
+    private scheduleNext;
+    /** Stop the tick loop. */
+    stop(): void;
+    /** Mark dirty — no-op in simplified engine, kept for API compat. */
+    markDirty(): void;
+    /** Get current tick status. */
+    getStatus(): {
+        enabled: boolean;
+        tickRateMs: number;
+        tickCount: number;
+    };
+    /** Execute one tick cycle. */
+    private tick;
+    /** Execute a tool call internally (no HTTP round-trip). */
+    executeTool(toolName: string, input: Record<string, unknown>, callerActorId?: string, expiredFlag?: {
+        value: boolean;
+    }): Promise<{
+        output?: unknown;
+        error?: string;
+    }>;
+}
+export {};

package/dist/tick-engine.js

@@ -0,0 +1,151 @@
+/**
+ * Tick Engine — server-side tick loop for experiences with netcode: "tick".
+ *
+ * Runs at a fixed tick rate, executing tool calls from the tick context.
+ * The tick engine provides the timing infrastructure; experiences define
+ * what happens each tick via their tool handlers.
+ */
+// ── Tick Engine ───────────────────────────────────────────────────────────────
+const TICK_ACTOR_ID = "_tick-engine";
+const TICK_OWNER = "_system";
+export class TickEngine {
+    room;
+    experience;
+    roomEvents;
+    interval = null;
+    tickCount = 0;
+    tickRateMs;
+    startedAt = 0;
+    _running = false;
+    _stopped = false;
+    _stateSetThisTick = false;
+    constructor(room, experience, roomEvents, tickRateMs = 50) {
+        this.room = room;
+        this.experience = experience;
+        this.roomEvents = roomEvents;
+        this.tickRateMs = tickRateMs;
+    }
+    /** Start the tick loop. Uses self-correcting setTimeout to prevent timing drift. */
+    start() {
+        if (this.interval)
+            return;
+        this._stopped = false;
+        this.tickCount = 0;
+        this.startedAt = Date.now();
+        this.scheduleNext();
+    }
+    /** Schedule the next tick with drift correction. */
+    scheduleNext() {
+        if (this._stopped)
+            return;
+        const expected = this.startedAt + (this.tickCount + 1) * this.tickRateMs;
+        const delay = Math.max(0, expected - Date.now());
+        this.interval = setTimeout(() => {
+            this.tick().then(() => this.scheduleNext(), () => this.scheduleNext());
+        }, delay);
+    }
+    /** Stop the tick loop. */
+    stop() {
+        this._stopped = true;
+        this._running = false;
+        if (this.interval) {
+            clearTimeout(this.interval);
+            this.interval = null;
+        }
+    }
+    /** Mark dirty — no-op in simplified engine, kept for API compat. */
+    markDirty() { }
+    /** Get current tick status. */
+    getStatus() {
+        return {
+            enabled: this.interval !== null,
+            tickRateMs: this.tickRateMs,
+            tickCount: this.tickCount,
+        };
+    }
+    /** Execute one tick cycle. */
+    async tick() {
+        if (this._running)
+            return;
+        this._running = true;
+        try {
+            this.tickCount++;
+        }
+        finally {
+            this._running = false;
+        }
+    }
+    /** Execute a tool call internally (no HTTP round-trip). */
+    async executeTool(toolName, input, callerActorId, expiredFlag) {
+        const tool = this.experience.module.tools.find((t) => t.name === toolName);
+        if (!tool) {
+            return { error: `Tool '${toolName}' not found` };
+        }
+        const actorId = callerActorId || TICK_ACTOR_ID;
+        const owner = callerActorId || TICK_OWNER;
+        try {
+            let validatedInput = input;
+            if (tool.input_schema?.parse) {
+                validatedInput = tool.input_schema.parse(input);
+            }
+            const self = this;
+            const ctxBase = {
+                roomId: this.room.id,
+                actorId,
+                owner,
+                state: null,
+                setState: (newState) => {
+                    if (expiredFlag?.value)
+                        return;
+                    self.room.sharedState = newState;
+                    self._stateSetThisTick = true;
+                },
+                timestamp: Date.now(),
+                memory: {},
+                setMemory: () => { },
+            };
+            Object.defineProperty(ctxBase, 'state', {
+                get() { return self.room.sharedState; },
+                enumerable: true,
+                configurable: true,
+            });
+            const ctx = ctxBase;
+            const output = await tool.handler(ctx, validatedInput);
+            const event = {
+                id: `tick-${this.tickCount}-${toolName}-${Math.random().toString(36).slice(2, 6)}`,
+                ts: Date.now(),
+                actorId: TICK_ACTOR_ID,
+                owner: TICK_OWNER,
+                tool: toolName,
+                input: validatedInput,
+                output,
+            };
+            if (this.experience.module.observe) {
+                try {
+                    event.observation = this.experience.module.observe(this.room.sharedState, event, actorId);
+                }
+                catch {
+                    // Don't fail tick if observe throws
+                }
+            }
+            this.room.appendEvent(event);
+            this.roomEvents.emit(`room:${this.room.id}`);
+            return { output };
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            const event = {
+                id: `tick-${this.tickCount}-${toolName}-${Math.random().toString(36).slice(2, 6)}`,
+                ts: Date.now(),
+                actorId: TICK_ACTOR_ID,
+                owner: TICK_OWNER,
+                tool: toolName,
+                input,
+                error: errorMsg,
+            };
+            this.room.appendEvent(event);
+            this.roomEvents.emit(`room:${this.room.id}`);
+            return { error: errorMsg };
+        }
+    }
+}