@proj-airi/plugin-protocol 0.9.0-alpha.18

package/dist/types/index.mjs

@@ -0,0 +1,88 @@
+import { defineEventa } from "@moeru/eventa";
+//#region src/types/events.ts
+let MessageHeartbeatKind = /* @__PURE__ */ function(MessageHeartbeatKind) {
+	MessageHeartbeatKind["Ping"] = "ping";
+	MessageHeartbeatKind["Pong"] = "pong";
+	return MessageHeartbeatKind;
+}({});
+let MessageHeartbeat = /* @__PURE__ */ function(MessageHeartbeat) {
+	MessageHeartbeat["Ping"] = "🩵";
+	MessageHeartbeat["Pong"] = "💛";
+	return MessageHeartbeat;
+}({});
+let WebSocketEventSource = /* @__PURE__ */ function(WebSocketEventSource) {
+	WebSocketEventSource["Server"] = "proj-airi:server-runtime";
+	WebSocketEventSource["StageWeb"] = "proj-airi:stage-web";
+	WebSocketEventSource["StageTamagotchi"] = "proj-airi:stage-tamagotchi";
+	return WebSocketEventSource;
+}({});
+let ContextUpdateStrategy = /* @__PURE__ */ function(ContextUpdateStrategy) {
+	ContextUpdateStrategy["ReplaceSelf"] = "replace-self";
+	ContextUpdateStrategy["AppendSelf"] = "append-self";
+	return ContextUpdateStrategy;
+}({});
+const moduleAuthenticate = defineEventa("module:authenticate");
+const moduleAuthenticated = defineEventa("module:authenticated");
+const moduleCompatibilityRequest = defineEventa("module:compatibility:request");
+const moduleCompatibilityResult = defineEventa("module:compatibility:result");
+const registryModulesSync = defineEventa("registry:modules:sync");
+const registryModulesHealthUnhealthy = defineEventa("registry:modules:health:unhealthy");
+const registryModulesHealthHealthy = defineEventa("registry:modules:health:healthy");
+const error = defineEventa("error");
+/** Permission-check failure event. See `ModulePermissionError`. */
+const errorPermission = defineEventa("error:permission");
+const moduleAnnounce = defineEventa("module:announce");
+const moduleAnnounced = defineEventa("module:announced");
+const moduleDeAnnounced = defineEventa("module:de-announced");
+/** Permission declaration lifecycle event. See `ModulePermissionsDeclareEvent`. */
+const modulePermissionsDeclare = defineEventa("module:permissions:declare");
+/** Permission request lifecycle event. See `ModulePermissionsRequestEvent`. */
+const modulePermissionsRequest = defineEventa("module:permissions:request");
+/** Permission grant lifecycle event. See `ModulePermissionsGrantedEvent`. */
+const modulePermissionsGranted = defineEventa("module:permissions:granted");
+/** Permission denial lifecycle event. See `ModulePermissionsDeniedEvent`. */
+const modulePermissionsDenied = defineEventa("module:permissions:denied");
+/** Current permission snapshot event. See `ModulePermissionsCurrentEvent`. */
+const modulePermissionsCurrent = defineEventa("module:permissions:current");
+const modulePrepared = defineEventa("module:prepared");
+const moduleConfigurationNeeded = defineEventa("module:configuration:needed");
+const moduleStatus = defineEventa("module:status");
+const moduleConfigurationValidateRequest = defineEventa("module:configuration:validate:request");
+const moduleConfigurationValidateResponse = defineEventa("module:configuration:validate:response");
+const moduleConfigurationValidateStatus = defineEventa("module:configuration:validate:status");
+const moduleConfigurationPlanRequest = defineEventa("module:configuration:plan:request");
+const moduleConfigurationPlanResponse = defineEventa("module:configuration:plan:response");
+const moduleConfigurationPlanStatus = defineEventa("module:configuration:plan:status");
+const moduleConfigurationCommit = defineEventa("module:configuration:commit");
+const moduleConfigurationCommitStatus = defineEventa("module:configuration:commit:status");
+const moduleConfigurationConfigured = defineEventa("module:configuration:configured");
+const moduleContributeCapabilityOffer = defineEventa("module:contribute:capability:offer");
+const moduleContributeCapabilityConfigurationNeeded = defineEventa("module:contribute:capability:configuration:needed");
+const moduleContributeCapabilityConfigurationValidateRequest = defineEventa("module:contribute:capability:configuration:validate:request");
+const moduleContributeCapabilityConfigurationValidateResponse = defineEventa("module:contribute:capability:configuration:validate:response");
+const moduleContributeCapabilityConfigurationValidateStatus = defineEventa("module:contribute:capability:configuration:validate:status");
+const moduleContributeCapabilityConfigurationPlanRequest = defineEventa("module:contribute:capability:configuration:plan:request");
+const moduleContributeCapabilityConfigurationPlanResponse = defineEventa("module:contribute:capability:configuration:plan:response");
+const moduleContributeCapabilityConfigurationPlanStatus = defineEventa("module:contribute:capability:configuration:plan:status");
+const moduleContributeCapabilityConfigurationCommit = defineEventa("module:contribute:capability:configuration:commit");
+const moduleContributeCapabilityConfigurationCommitStatus = defineEventa("module:contribute:capability:configuration:commit:status");
+const moduleContributeCapabilityConfigurationConfigured = defineEventa("module:contribute:capability:configuration:configured");
+const moduleContributeCapabilityActivated = defineEventa("module:contribute:capability:activated");
+const moduleStatusChange = defineEventa("module:status:change");
+const moduleConfigure = defineEventa("module:configure");
+const uiConfigure = defineEventa("ui:configure");
+const inputText = defineEventa("input:text");
+const inputTextVoice = defineEventa("input:text:voice");
+const inputVoice = defineEventa("input:voice");
+const outputGenAiChatToolCall = defineEventa("output:gen-ai:chat:tool-call");
+const outputGenAiChatMessage = defineEventa("output:gen-ai:chat:message");
+const outputGenAiChatComplete = defineEventa("output:gen-ai:chat:complete");
+const sparkNotify = defineEventa("spark:notify");
+const sparkEmit = defineEventa("spark:emit");
+const sparkCommand = defineEventa("spark:command");
+const transportConnectionHeartbeat = defineEventa("transport:connection:heartbeat");
+const contextUpdate = defineEventa("context:update");
+//#endregion
+export { ContextUpdateStrategy, MessageHeartbeat, MessageHeartbeatKind, WebSocketEventSource, contextUpdate, error, errorPermission, inputText, inputTextVoice, inputVoice, moduleAnnounce, moduleAnnounced, moduleAuthenticate, moduleAuthenticated, moduleCompatibilityRequest, moduleCompatibilityResult, moduleConfigurationCommit, moduleConfigurationCommitStatus, moduleConfigurationConfigured, moduleConfigurationNeeded, moduleConfigurationPlanRequest, moduleConfigurationPlanResponse, moduleConfigurationPlanStatus, moduleConfigurationValidateRequest, moduleConfigurationValidateResponse, moduleConfigurationValidateStatus, moduleConfigure, moduleContributeCapabilityActivated, moduleContributeCapabilityConfigurationCommit, moduleContributeCapabilityConfigurationCommitStatus, moduleContributeCapabilityConfigurationConfigured, moduleContributeCapabilityConfigurationNeeded, moduleContributeCapabilityConfigurationPlanRequest, moduleContributeCapabilityConfigurationPlanResponse, moduleContributeCapabilityConfigurationPlanStatus, moduleContributeCapabilityConfigurationValidateRequest, moduleContributeCapabilityConfigurationValidateResponse, moduleContributeCapabilityConfigurationValidateStatus, moduleContributeCapabilityOffer, moduleDeAnnounced, modulePermissionsCurrent, modulePermissionsDeclare, modulePermissionsDenied, modulePermissionsGranted, modulePermissionsRequest, modulePrepared, moduleStatus, moduleStatusChange, outputGenAiChatComplete, outputGenAiChatMessage, outputGenAiChatToolCall, registryModulesHealthHealthy, registryModulesHealthUnhealthy, registryModulesSync, sparkCommand, sparkEmit, sparkNotify, transportConnectionHeartbeat, uiConfigure };
+
+//# sourceMappingURL=index.mjs.map

package/dist/types/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/types/events.ts"],"sourcesContent":["import type { AssistantMessage, CommonContentPart, Message, ToolMessage, UserMessage } from '@xsai/shared-chat'\n\nimport { defineEventa } from '@moeru/eventa'\n\nexport interface DiscordGuildMember {\n  nickname: string\n  displayName: string\n  id: string\n}\n\nexport interface Discord {\n  guildMember?: DiscordGuildMember\n  guildId?: string\n  guildName?: string\n  channelId?: string\n}\n\nexport interface PluginIdentity {\n  /**\n   * Stable plugin identifier (shared across instances).\n   * Example: \"telegram-bot\", \"stage-tamagotchi\".\n   */\n  id: string\n  /**\n   * Optional semantic version for the plugin.\n   * Example: \"0.8.1-beta.7\".\n   */\n  version?: string\n  /**\n   * Optional labels attached to the plugin manifest.\n   * Example: { env: \"prod\", app: \"telegram\", devtools: \"true\" }.\n   */\n  labels?: Record<string, string>\n}\n\nexport interface ModuleIdentity {\n  /**\n   * Unique module instance id for this module run (per process/deployment).\n   * Example: \"telegram-01\", \"stage-ui-2f7c9\".\n   */\n  id: string\n  /**\n   * Module identity kind. For now only plugin-backed modules are supported.\n   */\n  kind: 'plugin'\n  /**\n   * Plugin identity associated with this module instance.\n   */\n  plugin: PluginIdentity\n  /**\n   * K8s-style labels for routing and policy selectors.\n   * Example: { env: \"prod\", app: \"telegram\", devtools: \"true\" }.\n   */\n  labels?: Record<string, string>\n}\n\nexport type MetadataEventSource = ModuleIdentity\n\n/**\n * Static schema metadata for module configuration.\n * This is transport-friendly and can be paired with a JSON Schema-like object.\n *\n * Example:\n *  {\n *    id: \"airi.config.stage-ui\",\n *    version: 2,\n *    schema: { type: \"object\", properties: { model: { type: \"string\" } }, required: [\"model\"] },\n *  }\n */\nexport interface ModuleConfigSchema {\n  id: string\n  version: number\n  /**\n   * Optional JSON Schema-like descriptor for tooling/validation.\n   * Keep it JSON-serializable and avoid runtime-only values.\n   */\n  schema?: Record<string, unknown>\n}\n\n/**\n * Module dependency declaration.\n *\n * Use this during prepare/probe to describe what a module needs before\n * it can decide its dynamic contributions. Dependencies can change at\n * runtime if peers go offline.\n *\n * Example:\n *  { role: \"llm:orchestrator\", min: \"v1\", optional: true }\n */\nexport interface ModuleDependency {\n  /**\n   * Logical dependency role (preferred over hard-coded plugin ids).\n   * Example: \"llm:orchestrator\"\n   */\n  role: string\n  /**\n   * Optional dependency flag.\n   */\n  optional?: boolean\n  /**\n   * Version constraint hints.\n   */\n  version?: string\n  min?: string\n  max?: string\n  /**\n   * Additional constraint metadata (JSON-serializable).\n   */\n  constraints?: Record<string, unknown>\n}\n\n/**\n * Dynamic contributions emitted by a module after configuration.\n *\n * Unlike static manifests, contributions can be updated or revoked at\n * runtime. This is where capabilities, provider registrations, and UI\n * extensions should be declared.\n *\n * Example:\n *  {\n *    capabilities: [\"context.aggregate\"],\n *    providers: [{ id: \"vscode-context\", type: \"context-source\" }],\n *    ui: { widgets: [\"context-summary-panel\"] }\n *  }\n */\nexport interface ModuleContribution {\n  /**\n   * Dynamic capabilities exposed by the module.\n   */\n  capabilities?: string[]\n  /**\n   * Provider registry contributions (shape defined by the host).\n   */\n  providers?: Array<Record<string, unknown>>\n  /**\n   * UI contribution descriptors (widgets, toolbar items, etc).\n   */\n  ui?: Record<string, unknown>\n  /**\n   * Hook registrations (event handlers, interceptors, etc).\n   */\n  hooks?: Array<Record<string, unknown>>\n  /**\n   * Additional resources or metadata.\n   */\n  resources?: Record<string, unknown>\n}\n\n/**\n * Lifecycle phases for module orchestration and UX.\n */\nexport type ModulePhase\n  = | 'announced'\n    | 'preparing'\n    | 'prepared'\n    | 'configuration-needed'\n    | 'configured'\n    | 'ready'\n    | 'failed'\n\nexport type Localizable\n  = | string\n    | {\n    /**\n     * Localization key owned by the module.\n     * Example: \"config.deprecated.model_driver.legacy\"\n     */\n      key: string\n      /**\n       * Fallback display string when translation is unavailable.\n       */\n      fallback?: string\n      /**\n       * Params for string interpolation.\n       */\n      params?: Record<string, string | number | boolean>\n    }\n\nexport interface ModuleConfigNotice {\n  /**\n   * Machine-friendly key for analytics or client-side mapping.\n   */\n  code?: string\n  /**\n   * Human readable message or localization key.\n   */\n  message?: Localizable\n  /**\n   * JSON pointer or dotted path in config.\n   * Example: \"driver.legacyModelPath\"\n   */\n  path?: string\n  /**\n   * Suggested replacement path or alternative.\n   */\n  replacedBy?: string\n  /**\n   * Version since the notice applies.\n   */\n  since?: number\n  /**\n   * Link to docs or migration guide.\n   */\n  link?: string\n}\n\nexport interface ModuleConfigStep {\n  /**\n   * Suggested action to complete configuration.\n   * Use code for UI rendering or message for fallback.\n   */\n  code?: string\n  message?: Localizable\n  /**\n   * Optional targeted field(s).\n   */\n  paths?: string[]\n}\n\nexport interface ModuleConfigPlan {\n  /**\n   * Schema that this plan targets.\n   */\n  schema: ModuleConfigSchema\n  /**\n   * Missing required paths for current schema/version.\n   */\n  missing?: string[]\n  /**\n   * Invalid fields with reasons (runtime validation result).\n   */\n  invalid?: Array<{ path: string, reason: string }>\n  /**\n   * Recommended defaults computed at runtime (may be environment-specific).\n   */\n  defaults?: Record<string, unknown>\n  /**\n   * Deprecated fields/behaviors detected in current config.\n   */\n  deprecated?: Array<string | ModuleConfigNotice>\n  /**\n   * Suggested migration steps between schema versions.\n   */\n  migrations?: Array<{\n    from: number\n    to: number\n    steps?: Array<string | ModuleConfigStep>\n    notes?: Array<string | ModuleConfigNotice>\n  }>\n  /**\n   * Human- or UI-friendly next actions to resolve partial config.\n   */\n  nextSteps?: Array<string | ModuleConfigStep>\n  /**\n   * Non-blocking issues that should be shown to the user/operator.\n   */\n  warnings?: Array<string | ModuleConfigNotice>\n}\n\nexport interface ModuleConfigValidation {\n  /**\n   * Overall validation status.\n   *\n   * - valid: all required fields present and valid.\n   * - partial: config is structurally OK but missing required fields; can be fixed by patches.\n   * - invalid: one or more fields are present but invalid (type/range/format); requires correction.\n   */\n  status: 'partial' | 'valid' | 'invalid'\n  /**\n   * Missing required fields (only for partial/invalid).\n   */\n  missing?: string[]\n  /**\n   * Invalid fields with reasons (only for invalid).\n   */\n  invalid?: Array<{ path: string, reason: Localizable }>\n  /**\n   * Non-blocking issues (e.g., deprecations, best-practice notices).\n   */\n  warnings?: Array<string | ModuleConfigNotice>\n}\n\n/**\n * Config payload envelope for plan/apply/validate/commit.\n *\n * Example:\n *  {\n *    configId: \"stage-ui-live2d\",\n *    revision: 12,\n *    schemaVersion: 2,\n *    full: { model: \"Hiyori\", driver: { type: \"live2d\" } },\n *  }\n */\nexport interface ModuleConfigEnvelope<C = Record<string, unknown>> {\n  configId: string\n  /**\n   * Monotonic revision number for this configId.\n   */\n  revision: number\n  /**\n   * Schema version this config targets.\n   */\n  schemaVersion: number\n  /**\n   * Optional source identity (who produced this config).\n   */\n  source?: ModuleIdentity\n  /**\n   * Full config payload (use when first applying or rehydrating).\n   */\n  full?: C\n  /**\n   * Partial patch payload (use when updating or filling missing fields).\n   */\n  patch?: Partial<C>\n  /**\n   * If patch is used, baseRevision should be set for optimistic concurrency.\n   */\n  baseRevision?: number\n}\n\nexport interface ModuleCapability {\n  /**\n   * Stable capability id within a module.\n   * Example: \"memory.write\", \"vision.ocr\".\n   */\n  id: string\n  /**\n   * Human-friendly name.\n   */\n  name?: string\n  /**\n   * Optional localized description.\n   */\n  description?: Localizable\n  /**\n   * Capability-specific config schema (if needed).\n   */\n  configSchema?: ModuleConfigSchema\n  /**\n   * Additional metadata for tooling/UI.\n   */\n  metadata?: Record<string, unknown>\n}\n\nexport type ModulePermissionArea = 'apis' | 'resources' | 'capabilities' | 'processors' | 'pipelines'\n\nexport interface ModulePermissionSpec<\n  Area extends ModulePermissionArea = ModulePermissionArea,\n  Action extends string = string,\n> {\n  key: string\n  actions: Action[]\n  /**\n   * Human-facing explanation for consent/permission UI.\n   * Prefer i18n key form over raw strings for localization.\n   */\n  reason?: Localizable\n  /**\n   * Optional short display label for permission prompts.\n   * Prefer i18n key form over raw strings for localization.\n   */\n  label?: Localizable\n  required?: boolean\n  metadata?: Record<string, unknown>\n  area?: Area\n}\n\nexport interface ModulePermissionDeclaration {\n  apis?: ModulePermissionSpec<'apis', 'invoke' | 'emit'>[]\n  resources?: ModulePermissionSpec<'resources', 'read' | 'write' | 'subscribe'>[]\n  capabilities?: ModulePermissionSpec<'capabilities', 'wait' | 'snapshot'>[]\n  processors?: ModulePermissionSpec<'processors', 'register' | 'execute' | 'manage'>[]\n  pipelines?: ModulePermissionSpec<'pipelines', 'hook' | 'process' | 'emit' | 'manage'>[]\n}\n\nexport type ModulePermissionGrant = ModulePermissionDeclaration\n\n/**\n * Describes a single authorization failure produced by host-side permission checks.\n *\n * Protocol expectations:\n * - `area`, `action`, and `key` identify the denied operation\n * - `reason` is intended for user-facing or diagnostic context and may be localized\n * - `recoverable` indicates whether the caller may reasonably retry after obtaining consent,\n *   reconfiguration, or a state change\n * - plugins should not treat `reason` as a stable machine-readable code\n */\nexport interface ModulePermissionError {\n  area: ModulePermissionArea\n  action: string\n  key: string\n  reason?: Localizable\n  recoverable?: boolean\n}\n\nexport type RouteTargetExpression\n  = | { type: 'and', all: RouteTargetExpression[] }\n    | { type: 'or', any: RouteTargetExpression[] }\n    | { type: 'glob', glob: string, inverted?: boolean }\n    | { type: 'ids', ids: string[], inverted?: boolean }\n    | { type: 'plugin', plugins: string[], inverted?: boolean }\n    | { type: 'instance', instances: string[], inverted?: boolean }\n    | { type: 'label', selectors: string[], inverted?: boolean }\n    | { type: 'module', modules: string[], inverted?: boolean }\n    | { type: 'source', sources: string[], inverted?: boolean }\n\nexport interface RouteConfig {\n  destinations?: Array<string | RouteTargetExpression>\n  bypass?: boolean\n}\n\nexport enum MessageHeartbeatKind {\n  Ping = 'ping',\n  Pong = 'pong',\n}\n\nexport enum MessageHeartbeat {\n  Ping = '🩵',\n  Pong = '💛',\n}\n\nexport enum WebSocketEventSource {\n  Server = 'proj-airi:server-runtime',\n  StageWeb = 'proj-airi:stage-web',\n  StageTamagotchi = 'proj-airi:stage-tamagotchi',\n}\n\ninterface InputSource {\n  'stage-web': boolean\n  'stage-tamagotchi': boolean\n  'discord': Discord\n}\n\ninterface OutputSource {\n  'gen-ai:chat': {\n    message: UserMessage\n    contexts: Record<string, ContextUpdate<Record<string, any>, string | CommonContentPart[]>[]>\n    composedMessage: Array<Message>\n    input?: InputEventEnvelope\n  }\n}\n\nexport enum ContextUpdateStrategy {\n  ReplaceSelf = 'replace-self',\n  AppendSelf = 'append-self',\n}\n\nexport interface ContextUpdateDestinationAll {\n  all: true\n}\n\nexport interface ContextUpdateDestinationList {\n  include?: Array<string>\n  exclude?: Array<string>\n}\n\nexport type ContextUpdateDestinationFilter\n  = | ContextUpdateDestinationAll\n    | ContextUpdateDestinationList\n\nexport interface ContextUpdate<\n  Metadata extends Record<string, any> = Record<string, unknown>,\n  // eslint-disable-next-line ts/no-unnecessary-type-constraint\n  Content extends any = undefined,\n> {\n  id: string\n  /**\n   * Can be the same if same update sends multiple time as attempts\n   * and trials, (e.g. notified first but not ACKed, then retried).\n   */\n  contextId: string\n  lane?: string\n  ideas?: Array<string>\n  hints?: Array<string>\n  strategy: ContextUpdateStrategy\n  text: string\n  content?: Content\n  destinations?: Array<string> | ContextUpdateDestinationFilter\n  metadata?: Metadata\n}\n\nexport interface InputMessageOverrides {\n  sessionId?: string\n  messagePrefix?: string\n}\n\nexport type InputContextUpdate\n  = Omit<ContextUpdate<Record<string, unknown>, string | CommonContentPart[]>, 'id' | 'contextId'>\n    & Partial<Pick<ContextUpdate<Record<string, unknown>, string | CommonContentPart[]>, 'id' | 'contextId'>>\n\nexport interface WebSocketEventInputTextBase {\n  text: string\n  textRaw?: string\n  overrides?: InputMessageOverrides\n  contextUpdates?: InputContextUpdate[]\n}\n\nexport type WebSocketEventInputText = WebSocketEventInputTextBase & Partial<WithInputSource<'stage-web' | 'stage-tamagotchi' | 'discord'>>\n\nexport interface WebSocketEventInputTextVoiceBase {\n  transcription: string\n  textRaw?: string\n  overrides?: InputMessageOverrides\n  contextUpdates?: InputContextUpdate[]\n}\n\nexport type WebSocketEventInputTextVoice = WebSocketEventInputTextVoiceBase & Partial<WithInputSource<'stage-web' | 'stage-tamagotchi' | 'discord'>>\n\nexport interface WebSocketEventInputVoiceBase {\n  audio: ArrayBuffer\n  overrides?: InputMessageOverrides\n  contextUpdates?: InputContextUpdate[]\n}\n\nexport type WebSocketEventInputVoice = WebSocketEventInputVoiceBase & Partial<WithInputSource<'stage-web' | 'stage-tamagotchi' | 'discord'>>\n\nexport type InputEventData = WebSocketEventInputText | WebSocketEventInputTextVoice | WebSocketEventInputVoice\n\nexport type InputEventEnvelope\n  = | { type: 'input:text', data: WebSocketEventInputText }\n    | { type: 'input:text:voice', data: WebSocketEventInputTextVoice }\n    | { type: 'input:voice', data: WebSocketEventInputVoice }\n\nexport interface EventBaseMetadata {\n  source?: ModuleIdentity\n  event?: {\n    id?: string\n    parentId?: string\n  }\n}\n\nexport type WithInputSource<Source extends keyof InputSource> = {\n  [S in Source]: InputSource[S]\n}\n\nexport type WithOutputSource<Source extends keyof OutputSource> = {\n  [S in Source]: OutputSource[S]\n}\n\n// Module orchestration (local or remote transport):\n//\n// 1) module:authenticate → module:authenticated\n// 2) registry:modules:sync (host → module bootstrap)\n// 3) module:announce (identity, deps, config schema)\n// 4) module:prepared\n// 5) module:configuration:* (validate/plan/commit flow)\n// 6) module:configuration:configured\n// 7) module:contribute:capability:offer (repeat per capability)\n// 8) module:contribute:capability:configuration:* (optional)\n// 9) module:contribute:capability:activated\n// 10) module:status (ready)\n// 11) module:status:change (to re-run phases)\n\ninterface ModuleAuthenticateEvent {\n  token: string\n}\n\ninterface ModuleAuthenticatedEvent {\n  authenticated: boolean\n}\n\ninterface ModuleCompatibilityRequestEvent {\n  protocolVersion: string\n  apiVersion: string\n  supportedProtocolVersions?: string[]\n  supportedApiVersions?: string[]\n}\n\ninterface ModuleCompatibilityResultEvent {\n  protocolVersion: string\n  apiVersion: string\n  mode: 'exact' | 'downgraded' | 'rejected'\n  reason?: string\n}\n\ninterface RegistryModulesSyncEvent {\n  modules: Array<{\n    name: string\n    index?: number\n    identity: ModuleIdentity\n  }>\n}\n\ninterface ErrorEvent {\n  message: string\n}\n\ninterface ErrorPermissionEvent {\n  identity?: ModuleIdentity\n  error: ModulePermissionError\n}\n\ninterface ModuleAnnounceEvent<C = undefined> {\n  name: string\n  identity: ModuleIdentity\n  possibleEvents: Array<(keyof ProtocolEvents<C>)>\n  permissions?: ModulePermissionDeclaration\n  configSchema?: ModuleConfigSchema\n  dependencies?: ModuleDependency[]\n}\ninterface ModuleAnnouncedEvent {\n  name: string\n  index?: number\n  identity: ModuleIdentity\n}\n\ninterface ModuleDeAnnouncedEvent {\n  name: string\n  index?: number\n  identity: ModuleIdentity\n  reason?: string\n}\n\ninterface RegistryModulesHealthUnhealthyEvent {\n  name: string\n  index?: number\n  identity: ModuleIdentity\n  reason?: string\n}\n\ninterface RegistryModulesHealthHealthyEvent {\n  name: string\n  index?: number\n  identity: ModuleIdentity\n\n}\n\n/**\n * Emitted when a module declares the permissions it may need.\n *\n * Typical use cases:\n * - manifest-time declaration for installation, review, and audit surfaces\n * - runtime declaration when a module can only discover optional integrations later\n *\n * Protocol expectations:\n * - this event communicates intent only and does not grant access\n * - hosts may record, display, audit, or validate this declaration before any request is approved\n * - plugins must not assume any declared permission is usable until it appears in current grants\n * - `source` indicates whether the declaration originated from static manifest data or runtime code\n */\ninterface ModulePermissionsDeclareEvent {\n  identity: ModuleIdentity\n  requested: ModulePermissionDeclaration\n  source: 'manifest' | 'runtime'\n}\n\n/**\n * Emitted when a module actively asks the host to approve some or all declared permissions.\n *\n * Typical use cases:\n * - deferred consent before first use of a sensitive API or resource\n * - requesting optional capabilities only when a feature is enabled by the user\n *\n * Protocol expectations:\n * - hosts may prompt the user, auto-approve, partially approve, or deny the request\n * - plugins must treat this as a request for evaluation, not as confirmation of access\n * - plugins should provide a user-facing `reason` when approval UX needs explanatory context\n * - the host response may later be expressed through granted, denied, and current permission events\n */\ninterface ModulePermissionsRequestEvent {\n  identity: ModuleIdentity\n  requested: ModulePermissionDeclaration\n  reason?: string\n}\n\n/**\n * Emitted after the host approves additional permissions for a module.\n *\n * Typical use cases:\n * - notifying the runtime that a previous permission request succeeded\n * - allowing plugin code to resume or unlock gated features\n *\n * Protocol expectations:\n * - `granted` may be narrower than the corresponding request\n * - plugins must inspect the granted payload instead of assuming the full request was approved\n * - `revision` increments when the permission snapshot changes and may be used to invalidate cached state\n * - hosts may emit this event before or together with an updated current snapshot\n */\ninterface ModulePermissionsGrantedEvent {\n  identity: ModuleIdentity\n  granted: ModulePermissionGrant\n  revision: number\n}\n\n/**\n * Emitted when some requested permissions are rejected or remain unavailable.\n *\n * Typical use cases:\n * - surfacing partial denials after a consent flow\n * - explaining why a feature must stay disabled or degraded\n *\n * Protocol expectations:\n * - `denied` describes the requested permissions that are not available after evaluation\n * - plugins must handle denial gracefully and should provide fallback behavior when feasible\n * - `reason` is intended for diagnostics or UX context and should not be treated as a stable machine-readable code\n * - `revision` identifies the permission-state version associated with this denial result\n */\ninterface ModulePermissionsDeniedEvent {\n  identity: ModuleIdentity\n  denied: ModulePermissionDeclaration\n  reason?: string\n  revision: number\n}\n\n/**\n * Emitted with the module's reconciled current permission snapshot.\n *\n * Typical use cases:\n * - bootstrapping plugin runtime state after startup or reload\n * - synchronizing UI/debug tools with the final requested vs granted view\n *\n * Protocol expectations:\n * - this is the authoritative event for \"what is currently allowed\"\n * - `requested` is the normalized declaration baseline known to the host\n * - `granted` is the currently granted subset that authorization checks should follow\n * - plugins should prefer this snapshot over local assumptions when reconciling runtime state\n */\ninterface ModulePermissionsCurrentEvent {\n  identity: ModuleIdentity\n  requested: ModulePermissionDeclaration\n  granted: ModulePermissionGrant\n  revision: number\n}\n\ninterface ModulePreparedEvent {\n  identity: ModuleIdentity\n  missingDependencies?: ModuleDependency[]\n}\n\ninterface ModuleConfigurationNeededEvent<C = undefined> {\n  identity: ModuleIdentity\n  schema?: ModuleConfigSchema\n  current?: ModuleConfigEnvelope<C>\n  reason?: string\n}\n\ninterface ModuleStatusEvent {\n  identity: ModuleIdentity\n  phase: ModulePhase\n  reason?: string\n  details?: Record<string, unknown>\n}\n\ninterface ModuleConfigurationValidateRequestEvent<C = undefined> {\n  identity: ModuleIdentity\n  current?: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleConfigurationValidateResponseEvent<C = undefined> {\n  identity: ModuleIdentity\n  validation: ModuleConfigValidation\n  plan?: ModuleConfigPlan\n  current?: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleConfigurationValidateStatusEvent {\n  identity: ModuleIdentity\n  state: 'queued' | 'working' | 'done' | 'failed'\n  note?: string\n  progress?: number\n}\n\ninterface ModuleConfigurationPlanRequestEvent<C = undefined> {\n  identity: ModuleIdentity\n  plan?: ModuleConfigPlan\n  current?: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleConfigurationPlanResponseEvent<C = undefined> {\n  identity: ModuleIdentity\n  plan: ModuleConfigPlan\n  current?: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleConfigurationPlanStatusEvent {\n  identity: ModuleIdentity\n  state: 'queued' | 'working' | 'done' | 'failed'\n  note?: string\n  progress?: number\n}\n\ninterface ModuleConfigurationCommitEvent<C = undefined> {\n  identity: ModuleIdentity\n  config: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleConfigurationCommitStatusEvent {\n  identity: ModuleIdentity\n  state: 'queued' | 'working' | 'done' | 'failed'\n  note?: string\n  progress?: number\n}\n\ninterface ModuleConfigurationConfiguredEvent<C = undefined> {\n  identity: ModuleIdentity\n  config: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleContributeCapabilityOfferEvent {\n  identity: ModuleIdentity\n  capability: ModuleCapability\n}\n\ninterface ModuleContributeCapabilityConfigurationNeededEvent<C = undefined> {\n  identity: ModuleIdentity\n  capabilityId: string\n  schema?: ModuleConfigSchema\n  current?: ModuleConfigEnvelope<C>\n  reason?: string\n}\n\ninterface ModuleContributeCapabilityConfigurationValidateRequestEvent<C = undefined> {\n  identity: ModuleIdentity\n  capabilityId: string\n  current?: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleContributeCapabilityConfigurationValidateResponseEvent<C = undefined> {\n  identity: ModuleIdentity\n  capabilityId: string\n  validation: ModuleConfigValidation\n  plan?: ModuleConfigPlan\n  current?: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleContributeCapabilityConfigurationValidateStatusEvent {\n  identity: ModuleIdentity\n  capabilityId: string\n  state: 'queued' | 'working' | 'done' | 'failed'\n  note?: string\n  progress?: number\n}\n\ninterface ModuleContributeCapabilityConfigurationPlanRequestEvent<C = undefined> {\n  identity: ModuleIdentity\n  capabilityId: string\n  plan?: ModuleConfigPlan\n  current?: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleContributeCapabilityConfigurationPlanResponseEvent<C = undefined> {\n  identity: ModuleIdentity\n  capabilityId: string\n  plan: ModuleConfigPlan\n  current?: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleContributeCapabilityConfigurationPlanStatusEvent {\n  identity: ModuleIdentity\n  capabilityId: string\n  state: 'queued' | 'working' | 'done' | 'failed'\n  note?: string\n  progress?: number\n}\n\ninterface ModuleContributeCapabilityConfigurationCommitEvent<C = undefined> {\n  identity: ModuleIdentity\n  capabilityId: string\n  config: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleContributeCapabilityConfigurationCommitStatusEvent {\n  identity: ModuleIdentity\n  capabilityId: string\n  state: 'queued' | 'working' | 'done' | 'failed'\n  note?: string\n  progress?: number\n}\n\ninterface ModuleContributeCapabilityConfigurationConfiguredEvent<C = undefined> {\n  identity: ModuleIdentity\n  capabilityId: string\n  config: ModuleConfigEnvelope<C>\n}\n\ninterface ModuleContributeCapabilityActivatedEvent {\n  identity: ModuleIdentity\n  capabilityId: string\n  active: boolean\n  reason?: string\n}\n\ninterface ModuleStatusChangeEvent {\n  identity: ModuleIdentity\n  phase: ModulePhase\n  reason?: string\n  details?: Record<string, unknown>\n}\n\ninterface ModuleConfigureEvent<C = undefined> {\n  config: C | Record<string, unknown>\n}\n\ninterface UiConfigureEvent<C = undefined> {\n  moduleName: string\n  moduleIndex?: number\n  config: C | Record<string, unknown>\n}\n\ntype OutputGenAiChatToolCallEvent = {\n  toolCalls: ToolMessage[]\n} & Partial<WithInputSource<'stage-web' | 'stage-tamagotchi' | 'discord'>> & Partial<WithOutputSource<'gen-ai:chat'>>\n\ntype OutputGenAiChatMessageEvent = {\n  message: AssistantMessage\n} & Partial<WithInputSource<'stage-web' | 'stage-tamagotchi' | 'discord'>> & Partial<WithOutputSource<'gen-ai:chat'>>\n\ninterface OutputGenAiChatUsage {\n  promptTokens: number\n  completionTokens: number\n  totalTokens: number\n  source: 'provider-based' | 'estimate-based'\n}\n\ntype OutputGenAiChatCompleteEvent = {\n  message: AssistantMessage\n  toolCalls: ToolMessage[]\n  usage: OutputGenAiChatUsage\n} & Partial<WithInputSource<'stage-web' | 'stage-tamagotchi' | 'discord'>> & Partial<WithOutputSource<'gen-ai:chat'>>\n\ninterface SparkNotifyEvent {\n  id: string\n  eventId: string\n  lane?: string\n  kind: 'alarm' | 'ping' | 'reminder'\n  urgency: 'immediate' | 'soon' | 'later'\n  headline: string\n  note?: string\n  payload?: Record<string, unknown>\n  ttlMs?: number\n  requiresAck?: boolean\n  destinations: Array<string>\n  metadata?: Record<string, unknown>\n}\n\ninterface SparkEmitEvent {\n  id: string\n  eventId?: string\n  state: 'queued' | 'working' | 'done' | 'dropped' | 'blocked' | 'expired'\n  note?: string\n  destinations: Array<string>\n  metadata?: Record<string, unknown>\n}\n\ninterface SparkCommandGuidanceOption {\n  label: string\n  steps: Array<string>\n  rationale?: string\n  possibleOutcome?: Array<string>\n  risk?: 'high' | 'medium' | 'low' | 'none'\n  fallback?: Array<string>\n  triggers?: Array<string>\n}\n\ninterface SparkCommandGuidance {\n  type: 'proposal' | 'instruction' | 'memory-recall'\n  /**\n   * Personas can be used to adjust the behavior of sub-agents.\n   * For example, when using as NPC in games, or player in Minecraft,\n   * the persona can help define the character's traits and decision-making style.\n   *\n   * Example:\n   *  persona: {\n   *    \"bravery\": \"high\",\n   *    \"cautiousness\": \"low\",\n   *    \"friendliness\": \"medium\"\n   *  }\n   */\n  persona?: Record<string, 'very-high' | 'high' | 'medium' | 'low' | 'very-low'>\n  options: Array<SparkCommandGuidanceOption>\n}\n\ninterface SparkCommandEvent {\n  id: string\n  eventId?: string\n  parentEventId?: string\n  commandId: string\n  interrupt: 'force' | 'soft' | false\n  priority: 'critical' | 'high' | 'normal' | 'low'\n  intent: 'plan' | 'proposal' | 'action' | 'pause' | 'resume' | 'reroute' | 'context'\n  ack?: string\n  guidance?: SparkCommandGuidance\n  contexts?: Array<ContextUpdate>\n  destinations: Array<string>\n}\n\ninterface TransportConnectionHeartbeatEvent {\n  kind: MessageHeartbeatKind\n  message: MessageHeartbeat | string\n  at?: number\n}\n\ntype ContextUpdateEvent = ContextUpdate\n\nexport const moduleAuthenticate = defineEventa<ModuleAuthenticateEvent>('module:authenticate')\nexport const moduleAuthenticated = defineEventa<ModuleAuthenticatedEvent>('module:authenticated')\nexport const moduleCompatibilityRequest = defineEventa<ModuleCompatibilityRequestEvent>('module:compatibility:request')\nexport const moduleCompatibilityResult = defineEventa<ModuleCompatibilityResultEvent>('module:compatibility:result')\nexport const registryModulesSync = defineEventa<RegistryModulesSyncEvent>('registry:modules:sync')\nexport const registryModulesHealthUnhealthy = defineEventa<RegistryModulesHealthUnhealthyEvent>('registry:modules:health:unhealthy')\nexport const registryModulesHealthHealthy = defineEventa<RegistryModulesHealthHealthyEvent>('registry:modules:health:healthy')\n\nexport const error = defineEventa<ErrorEvent>('error')\n/** Permission-check failure event. See `ModulePermissionError`. */\nexport const errorPermission = defineEventa<ErrorPermissionEvent>('error:permission')\n\nexport const moduleAnnounce = defineEventa<ModuleAnnounceEvent>('module:announce')\nexport const moduleAnnounced = defineEventa<ModuleAnnouncedEvent>('module:announced')\nexport const moduleDeAnnounced = defineEventa<ModuleDeAnnouncedEvent>('module:de-announced')\n\n/** Permission declaration lifecycle event. See `ModulePermissionsDeclareEvent`. */\nexport const modulePermissionsDeclare = defineEventa<ModulePermissionsDeclareEvent>('module:permissions:declare')\n/** Permission request lifecycle event. See `ModulePermissionsRequestEvent`. */\nexport const modulePermissionsRequest = defineEventa<ModulePermissionsRequestEvent>('module:permissions:request')\n/** Permission grant lifecycle event. See `ModulePermissionsGrantedEvent`. */\nexport const modulePermissionsGranted = defineEventa<ModulePermissionsGrantedEvent>('module:permissions:granted')\n/** Permission denial lifecycle event. See `ModulePermissionsDeniedEvent`. */\nexport const modulePermissionsDenied = defineEventa<ModulePermissionsDeniedEvent>('module:permissions:denied')\n/** Current permission snapshot event. See `ModulePermissionsCurrentEvent`. */\nexport const modulePermissionsCurrent = defineEventa<ModulePermissionsCurrentEvent>('module:permissions:current')\n\nexport const modulePrepared = defineEventa<ModulePreparedEvent>('module:prepared')\nexport const moduleConfigurationNeeded = defineEventa<ModuleConfigurationNeededEvent>('module:configuration:needed')\nexport const moduleStatus = defineEventa<ModuleStatusEvent>('module:status')\n\nexport const moduleConfigurationValidateRequest = defineEventa<ModuleConfigurationValidateRequestEvent>('module:configuration:validate:request')\nexport const moduleConfigurationValidateResponse = defineEventa<ModuleConfigurationValidateResponseEvent>('module:configuration:validate:response')\nexport const moduleConfigurationValidateStatus = defineEventa<ModuleConfigurationValidateStatusEvent>('module:configuration:validate:status')\nexport const moduleConfigurationPlanRequest = defineEventa<ModuleConfigurationPlanRequestEvent>('module:configuration:plan:request')\nexport const moduleConfigurationPlanResponse = defineEventa<ModuleConfigurationPlanResponseEvent>('module:configuration:plan:response')\nexport const moduleConfigurationPlanStatus = defineEventa<ModuleConfigurationPlanStatusEvent>('module:configuration:plan:status')\nexport const moduleConfigurationCommit = defineEventa<ModuleConfigurationCommitEvent>('module:configuration:commit')\nexport const moduleConfigurationCommitStatus = defineEventa<ModuleConfigurationCommitStatusEvent>('module:configuration:commit:status')\nexport const moduleConfigurationConfigured = defineEventa<ModuleConfigurationConfiguredEvent>('module:configuration:configured')\n\nexport const moduleContributeCapabilityOffer = defineEventa<ModuleContributeCapabilityOfferEvent>('module:contribute:capability:offer')\nexport const moduleContributeCapabilityConfigurationNeeded = defineEventa<ModuleContributeCapabilityConfigurationNeededEvent>('module:contribute:capability:configuration:needed')\nexport const moduleContributeCapabilityConfigurationValidateRequest = defineEventa<ModuleContributeCapabilityConfigurationValidateRequestEvent>('module:contribute:capability:configuration:validate:request')\nexport const moduleContributeCapabilityConfigurationValidateResponse = defineEventa<ModuleContributeCapabilityConfigurationValidateResponseEvent>('module:contribute:capability:configuration:validate:response')\nexport const moduleContributeCapabilityConfigurationValidateStatus = defineEventa<ModuleContributeCapabilityConfigurationValidateStatusEvent>('module:contribute:capability:configuration:validate:status')\nexport const moduleContributeCapabilityConfigurationPlanRequest = defineEventa<ModuleContributeCapabilityConfigurationPlanRequestEvent>('module:contribute:capability:configuration:plan:request')\nexport const moduleContributeCapabilityConfigurationPlanResponse = defineEventa<ModuleContributeCapabilityConfigurationPlanResponseEvent>('module:contribute:capability:configuration:plan:response')\nexport const moduleContributeCapabilityConfigurationPlanStatus = defineEventa<ModuleContributeCapabilityConfigurationPlanStatusEvent>('module:contribute:capability:configuration:plan:status')\nexport const moduleContributeCapabilityConfigurationCommit = defineEventa<ModuleContributeCapabilityConfigurationCommitEvent>('module:contribute:capability:configuration:commit')\nexport const moduleContributeCapabilityConfigurationCommitStatus = defineEventa<ModuleContributeCapabilityConfigurationCommitStatusEvent>('module:contribute:capability:configuration:commit:status')\nexport const moduleContributeCapabilityConfigurationConfigured = defineEventa<ModuleContributeCapabilityConfigurationConfiguredEvent>('module:contribute:capability:configuration:configured')\nexport const moduleContributeCapabilityActivated = defineEventa<ModuleContributeCapabilityActivatedEvent>('module:contribute:capability:activated')\n\nexport const moduleStatusChange = defineEventa<ModuleStatusChangeEvent>('module:status:change')\n\nexport const moduleConfigure = defineEventa<ModuleConfigureEvent>('module:configure')\n\nexport const uiConfigure = defineEventa<UiConfigureEvent>('ui:configure')\n\nexport const inputText = defineEventa<WebSocketEventInputText>('input:text')\nexport const inputTextVoice = defineEventa<WebSocketEventInputTextVoice>('input:text:voice')\nexport const inputVoice = defineEventa<WebSocketEventInputVoice>('input:voice')\n\nexport const outputGenAiChatToolCall = defineEventa<OutputGenAiChatToolCallEvent>('output:gen-ai:chat:tool-call')\nexport const outputGenAiChatMessage = defineEventa<OutputGenAiChatMessageEvent>('output:gen-ai:chat:message')\nexport const outputGenAiChatComplete = defineEventa<OutputGenAiChatCompleteEvent>('output:gen-ai:chat:complete')\n\nexport const sparkNotify = defineEventa<SparkNotifyEvent>('spark:notify')\nexport const sparkEmit = defineEventa<SparkEmitEvent>('spark:emit')\nexport const sparkCommand = defineEventa<SparkCommandEvent>('spark:command')\n\nexport const transportConnectionHeartbeat = defineEventa<TransportConnectionHeartbeatEvent>('transport:connection:heartbeat')\nexport const contextUpdate = defineEventa<ContextUpdateEvent>('context:update')\n\n// Thanks to:\n//\n// A little hack for creating extensible discriminated unions : r/typescript\n// https://www.reddit.com/r/typescript/comments/1064ibt/a_little_hack_for_creating_extensible/\nexport interface ProtocolEvents<C = undefined> {\n  'error': ErrorEvent\n  'error:permission': ErrorPermissionEvent\n\n  'module:authenticate': ModuleAuthenticateEvent\n  'module:authenticated': ModuleAuthenticatedEvent\n  /**\n   * Plugin asks host to negotiate protocol + API compatibility.\n   */\n  'module:compatibility:request': ModuleCompatibilityRequestEvent\n  /**\n   * Host replies with accepted mode/result for protocol + API compatibility.\n   */\n  'module:compatibility:result': ModuleCompatibilityResultEvent\n  /**\n   * Server-side registry sync for known online modules.\n   * Sent to newly authenticated peers to bootstrap module discovery.\n   */\n  'registry:modules:sync': RegistryModulesSyncEvent\n  /**\n   * Broadcast when a module's heartbeat expires (unhealthy).\n   */\n  'registry:modules:health:unhealthy': RegistryModulesHealthUnhealthyEvent\n  /**\n   * Broadcast when a previously unhealthy module resumes heartbeating (healthy again).\n   */\n  'registry:modules:health:healthy': RegistryModulesHealthHealthyEvent\n  /**\n   * Broadcast to all peers when a module announces itself, with its identity, static metadata, and declared dependencies.\n   * Host can use this to decide when to prepare/configure modules based on their needs and capabilities.\n   * Module that registering self can use this to declare its presence and what it offers, and to trigger orchestration flows in the host or other modules.\n   *\n   *\n   * NOTICE: Modules that would love to discover peers SHOULD NOT wait or listen to this event, instead\n   * module:announced or module:de-announced, or registry:modules:sync and registry:modules:health:* events for more reliable discovery and tracking.\n   */\n  'module:announce': ModuleAnnounceEvent<C>\n  'module:permissions:declare': ModulePermissionsDeclareEvent\n  'module:permissions:request': ModulePermissionsRequestEvent\n  'module:permissions:granted': ModulePermissionsGrantedEvent\n  'module:permissions:denied': ModulePermissionsDeniedEvent\n  'module:permissions:current': ModulePermissionsCurrentEvent\n  /**\n   * Broadcast to all peers when a module successfully announces.\n   */\n  'module:announced': ModuleAnnouncedEvent\n  /**\n   * Broadcast to all peers when a module is unregistered (disconnect, heartbeat expiry, error, etc).\n   */\n  'module:de-announced': ModuleDeAnnouncedEvent\n  /**\n   * Prepare completed. Host can move into config apply/validate.\n   *\n   * Example:\n   *  module:prepared { missingDependencies: [] }\n   */\n  'module:prepared': ModulePreparedEvent\n  /**\n   * Module needs configuration to proceed to prepared/configured.\n   */\n  'module:configuration:needed': ModuleConfigurationNeededEvent<C>\n  /**\n   * Lifecycle status updates for orchestration/UX.\n   *\n   * Example:\n   *  module:status { phase: \"ready\" }\n   */\n  'module:status': ModuleStatusEvent\n  /**\n   * Ask the module to validate current config (host → module).\n   */\n  'module:configuration:validate:request': ModuleConfigurationValidateRequestEvent<C>\n  /**\n   * Validation response (module → host), with optional plan suggestions.\n   */\n  'module:configuration:validate:response': ModuleConfigurationValidateResponseEvent<C>\n  /**\n   * Status updates for validation (module → host).\n   */\n  'module:configuration:validate:status': ModuleConfigurationValidateStatusEvent\n  /**\n   * Configuration planning request (host → module).\n   */\n  'module:configuration:plan:request': ModuleConfigurationPlanRequestEvent<C>\n  /**\n   * Configuration planning response (module → host).\n   */\n  'module:configuration:plan:response': ModuleConfigurationPlanResponseEvent<C>\n  /**\n   * Status updates for planning (module → host).\n   */\n  'module:configuration:plan:status': ModuleConfigurationPlanStatusEvent\n  /**\n   * Commit a config as \"active\" (host → module).\n   */\n  'module:configuration:commit': ModuleConfigurationCommitEvent<C>\n  /**\n   * Status updates for commit (module → host).\n   */\n  'module:configuration:commit:status': ModuleConfigurationCommitStatusEvent\n  /**\n   * Configuration fully applied and active (module → host).\n   */\n  'module:configuration:configured': ModuleConfigurationConfiguredEvent<C>\n  /**\n   * Capability offer emitted after module configuration.\n   */\n  'module:contribute:capability:offer': ModuleContributeCapabilityOfferEvent\n  /**\n   * Capability needs configuration before activation.\n   */\n  'module:contribute:capability:configuration:needed': ModuleContributeCapabilityConfigurationNeededEvent<C>\n  'module:contribute:capability:configuration:validate:request': ModuleContributeCapabilityConfigurationValidateRequestEvent<C>\n  'module:contribute:capability:configuration:validate:response': ModuleContributeCapabilityConfigurationValidateResponseEvent<C>\n  'module:contribute:capability:configuration:validate:status': ModuleContributeCapabilityConfigurationValidateStatusEvent\n  'module:contribute:capability:configuration:plan:request': ModuleContributeCapabilityConfigurationPlanRequestEvent<C>\n  'module:contribute:capability:configuration:plan:response': ModuleContributeCapabilityConfigurationPlanResponseEvent<C>\n  'module:contribute:capability:configuration:plan:status': ModuleContributeCapabilityConfigurationPlanStatusEvent\n  'module:contribute:capability:configuration:commit': ModuleContributeCapabilityConfigurationCommitEvent<C>\n  'module:contribute:capability:configuration:commit:status': ModuleContributeCapabilityConfigurationCommitStatusEvent\n  'module:contribute:capability:configuration:configured': ModuleContributeCapabilityConfigurationConfiguredEvent<C>\n  'module:contribute:capability:activated': ModuleContributeCapabilityActivatedEvent\n  /**\n   * Request a phase transition (module → host).\n   */\n  'module:status:change': ModuleStatusChangeEvent\n  /**\n   * Push configuration down to module (host → module).\n   */\n  'module:configure': ModuleConfigureEvent<C>\n\n  'ui:configure': UiConfigureEvent<C>\n\n  'input:text': WebSocketEventInputText\n  'input:text:voice': WebSocketEventInputTextVoice\n  'input:voice': WebSocketEventInputVoice\n\n  'output:gen-ai:chat:tool-call': OutputGenAiChatToolCallEvent\n  'output:gen-ai:chat:message': OutputGenAiChatMessageEvent\n  'output:gen-ai:chat:complete': OutputGenAiChatCompleteEvent\n\n  /**\n   * Spark used for allowing agents in a network to raise an event toward the other destinations (e.g. character).\n   *\n   * DO:\n   * - Use notify for episodic events (alarms/pings/reminders) with minimal payload.\n   * - Use command for high-level intent; let sub-agents translate into their own state machines.\n   * - Use emit for ack/progress/completion; include ids for tracing/dedupe.\n   * - Route via destinations; keep payloads small; use context:update for richer ideas.\n   * - Dedupe/log via id/eventId for observability.\n   *\n   * DOn't:\n   * - Stream high-frequency telemetry here (keep a separate channel).\n   * - Stuff large blobs into payload/contexts; prefer refs/summaries.\n   * - Assume exactly-once; add retry/ack on critical paths. You may rely on id/eventId for dedupe.\n   * - Allow untrusted agents to broadcast without auth/capability checks.\n   *\n   * Examples:\n   * - Minecraft attack/death: kind=alarm, urgency=immediate (fast bubble-up).\n   *   e.g., fromAgent='minecraft', headline='Under attack by witch', payload includes hp/location/gear.\n   * - Cat bowl empty from HomeAssistant: kind=alarm, urgency=soon.\n   * - IM/email \"read now\": kind=ping, urgency=immediate.\n   * - Action Required email: kind=reminder, urgency=later.\n   *\n   * destinations controls routing (e.g. ['character'], ['character','minecraft-agent']).\n   */\n  'spark:notify': SparkNotifyEvent\n\n  /**\n   * Acknowledgement/progress/state for a spark or command (bidirectional).\n   * Examples:\n   * - Character: state=working, note=\"Seen it, responding\".\n   * - Sub-agent: state=done, note=\"Healed and safe\".\n   * - Sub-agent: state=blocked/dropped with note when it cannot comply.\n   * - Minecraft: state=working, note=\"Pillared up; healing\" in reply to a command.\n   */\n  'spark:emit': SparkEmitEvent\n\n  /**\n   * Character issues instructions or context to a sub-agent.\n   * interrupt: force = hard preempt; soft = merge/queue.\n   * Examples:\n   * - Witch attack: interrupt=force, priority=critical, intent=action with options (aggressive/cautious).\n   *   e.g., options to block/retreat vs push with shield/sword, with fallback steps.\n   * - Prep plan: interrupt=soft, priority=high, intent=plan with steps/fallbacks.\n   * - Contextual hints: intent=context with contextPatch ideas/hints.\n   */\n  'spark:command': SparkCommandEvent\n\n  'transport:connection:heartbeat': TransportConnectionHeartbeatEvent\n\n  'context:update': ContextUpdateEvent\n}\n\nexport type ProtocolEventOf<E, C = undefined> = E extends keyof ProtocolEvents<C>\n  ? Omit<ProtocolEvents<C>[E], 'metadata'> & { metadata?: Record<string, unknown> }\n  : never\n"],"mappings":";;AA4ZA,IAAY,uBAAL,yBAAA,sBAAA;AACL,sBAAA,UAAA;AACA,sBAAA,UAAA;;KACD;AAED,IAAY,mBAAL,yBAAA,kBAAA;AACL,kBAAA,UAAA;AACA,kBAAA,UAAA;;KACD;AAED,IAAY,uBAAL,yBAAA,sBAAA;AACL,sBAAA,YAAA;AACA,sBAAA,cAAA;AACA,sBAAA,qBAAA;;KACD;AAiBD,IAAY,wBAAL,yBAAA,uBAAA;AACL,uBAAA,iBAAA;AACA,uBAAA,gBAAA;;KACD;AAqiBD,MAAa,qBAAqB,aAAsC,sBAAsB;AAC9F,MAAa,sBAAsB,aAAuC,uBAAuB;AACjG,MAAa,6BAA6B,aAA8C,+BAA+B;AACvH,MAAa,4BAA4B,aAA6C,8BAA8B;AACpH,MAAa,sBAAsB,aAAuC,wBAAwB;AAClG,MAAa,iCAAiC,aAAkD,oCAAoC;AACpI,MAAa,+BAA+B,aAAgD,kCAAkC;AAE9H,MAAa,QAAQ,aAAyB,QAAQ;;AAEtD,MAAa,kBAAkB,aAAmC,mBAAmB;AAErF,MAAa,iBAAiB,aAAkC,kBAAkB;AAClF,MAAa,kBAAkB,aAAmC,mBAAmB;AACrF,MAAa,oBAAoB,aAAqC,sBAAsB;;AAG5F,MAAa,2BAA2B,aAA4C,6BAA6B;;AAEjH,MAAa,2BAA2B,aAA4C,6BAA6B;;AAEjH,MAAa,2BAA2B,aAA4C,6BAA6B;;AAEjH,MAAa,0BAA0B,aAA2C,4BAA4B;;AAE9G,MAAa,2BAA2B,aAA4C,6BAA6B;AAEjH,MAAa,iBAAiB,aAAkC,kBAAkB;AAClF,MAAa,4BAA4B,aAA6C,8BAA8B;AACpH,MAAa,eAAe,aAAgC,gBAAgB;AAE5E,MAAa,qCAAqC,aAAsD,wCAAwC;AAChJ,MAAa,sCAAsC,aAAuD,yCAAyC;AACnJ,MAAa,oCAAoC,aAAqD,uCAAuC;AAC7I,MAAa,iCAAiC,aAAkD,oCAAoC;AACpI,MAAa,kCAAkC,aAAmD,qCAAqC;AACvI,MAAa,gCAAgC,aAAiD,mCAAmC;AACjI,MAAa,4BAA4B,aAA6C,8BAA8B;AACpH,MAAa,kCAAkC,aAAmD,qCAAqC;AACvI,MAAa,gCAAgC,aAAiD,kCAAkC;AAEhI,MAAa,kCAAkC,aAAmD,qCAAqC;AACvI,MAAa,gDAAgD,aAAiE,oDAAoD;AAClL,MAAa,yDAAyD,aAA0E,8DAA8D;AAC9M,MAAa,0DAA0D,aAA2E,+DAA+D;AACjN,MAAa,wDAAwD,aAAyE,6DAA6D;AAC3M,MAAa,qDAAqD,aAAsE,0DAA0D;AAClM,MAAa,sDAAsD,aAAuE,2DAA2D;AACrM,MAAa,oDAAoD,aAAqE,yDAAyD;AAC/L,MAAa,gDAAgD,aAAiE,oDAAoD;AAClL,MAAa,sDAAsD,aAAuE,2DAA2D;AACrM,MAAa,oDAAoD,aAAqE,wDAAwD;AAC9L,MAAa,sCAAsC,aAAuD,yCAAyC;AAEnJ,MAAa,qBAAqB,aAAsC,uBAAuB;AAE/F,MAAa,kBAAkB,aAAmC,mBAAmB;AAErF,MAAa,cAAc,aAA+B,eAAe;AAEzE,MAAa,YAAY,aAAsC,aAAa;AAC5E,MAAa,iBAAiB,aAA2C,mBAAmB;AAC5F,MAAa,aAAa,aAAuC,cAAc;AAE/E,MAAa,0BAA0B,aAA2C,+BAA+B;AACjH,MAAa,yBAAyB,aAA0C,6BAA6B;AAC7G,MAAa,0BAA0B,aAA2C,8BAA8B;AAEhH,MAAa,cAAc,aAA+B,eAAe;AACzE,MAAa,YAAY,aAA6B,aAAa;AACnE,MAAa,eAAe,aAAgC,gBAAgB;AAE5E,MAAa,+BAA+B,aAAgD,iCAAiC;AAC7H,MAAa,gBAAgB,aAAiC,iBAAiB"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@proj-airi/plugin-protocol",
+  "type": "module",
+  "version": "0.9.0-alpha.18",
+  "description": "Plugin protocol event definitions and shared websocket types for Project AIRI",
+  "author": {
+    "name": "Moeru AI Project AIRI Team",
+    "email": "airi@moeru.ai",
+    "url": "https://github.com/moeru-ai"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/moeru-ai/airi.git",
+    "directory": "packages/plugin-protocol"
+  },
+  "exports": {
+    "./types": {
+      "types": "./dist/types/index.d.mts",
+      "default": "./dist/types/index.mjs"
+    }
+  },
+  "main": "./dist/types/index.mjs",
+  "types": "./dist/types/index.d.mts",
+  "files": [
+    "README.md",
+    "dist",
+    "package.json"
+  ],
+  "dependencies": {
+    "@moeru/eventa": "1.0.0-alpha.14",
+    "@xsai/shared-chat": "0.4.0-beta.13"
+  },
+  "scripts": {
+    "dev": "pnpm run build",
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}