@proj-airi/server-shared

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

Usage

``shell
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
`

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

How to use the events in distributed use cases?

$3

#### 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