@proj-airi/server-shared

The shared type definitions for all server-side packages of Project AIRI.

Usage

ni @proj-airi/server-shared -D # from @antfu/ni, can be installed via `npm i -g @antfu/ni`
pnpm i @proj-airi/server-shared -D
yarn i @proj-airi/server-shared -D
npm i @proj-airi/server-shared -D

import type { WebSocketEvents } from '@proj-airi/server-shared'

How to use the events in distributed use cases?

Scenarios

Minecraft agent

1. Urgent combat (witch attack)

• Minecraft sends spark:notify (kind=alarm, urgency=immediate, payload hp/location/gear, destinations=["character"]).
• Character spark:emit working ("Seen it").
• Character issues spark:command with interrupt=force and options (retreat vs push).
• Minecraft spark:emit working ("Pillared up; healing") then done/blocked as it executes.
• Optional context:update for summary/memory.

2. Prep plan (Ender Dragon)

• Discord/user intent triggers character spark:command to Minecraft (intent=plan, interrupt=soft, steps gather beds/pots/gear, fallback).
• Optional context:update with tips (lane='game').
• Minecraft streams spark:emit progress.
• If ambushed, Minecraft raises new spark:notify (alarm/immediate) to preempt.
• Character revises with another spark:command.
• Completion via spark:emit done + summary note.

3. Routine nudge

• Minecraft signals low food via spark:notify (kind=reminder, urgency=soon, destinations=["character"]).
• Character defers to next tick and sends spark:command (interrupt=soft, intent=plan: "gather food nearby").
• Minecraft spark:emit queued/working then done.

4. Multi-step command while researching (plan + live control)

[!NOTE] Using intent=plan keeps the loop alive even with un-finalized ideas—similar to TODO scaffolding in coding agents—while richer guidance is still being researched.

• Character receives a user goal (e.g., fortify base) and issues an initial spark:command to Minecraft (interrupt=soft, intent=plan, steps to gather materials) so the agent keeps working.
• Character simultaneously performs memory/search/design tasks outside the game loop (wiki lookup, prior notes).
• As insights arrive, character sends context:update (lane='game', hints/ideas) to enrich the sub-agent without preemption.
• If an urgent event occurs during prep, Minecraft raises spark:notify (alarm) → character responds with a short spark:emit working and a spark:command (interrupt=force) to handle it (e.g., retreat, block up).
• Once design is ready, character sends a refined spark:command (intent=proposal (or action), interrupt=soft) with structured options/steps/fallbacks.
• Minecraft streams spark:emit progress; when complete, character summarizes via spark:emit or context:update for memory.

License

MIT