@aexol/spectral 0.8.2 → 0.8.6

package/dist/relay/auto-research.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Auto-research handler — sends an auto-research task through the existing
+ * AgentBridge (backend proxy) instead of spawning a separate spectral process.
+ *
+ * This ensures auto-research uses the same model and API keys as the active
+ * session — no separate subprocess, no missing API key errors.
+ *
+ * Flow:
+ *   1. Build the auto-research task prompt
+ *   2. Ensure session subscriber exists (borrows handleClientMessage pattern)
+ *   3. Emit auto_research_start via relay
+ *   4. Send task via manager.prompt() — goes through backend proxy with session's model
+ *   5. Attach a watcher subscriber to detect turn completion
+ *   6. On agent_end, scan for generated extensions and emit auto_research_complete
+ *   7. On error, emit auto_research_error
+ */
+import type { SessionStore } from "../server/storage.js";
+import type { SessionStreamManager, Subscriber } from "../server/session-stream.js";
+import type { RelayClient } from "./client.js";
+/** Input shape consumed by `handleAutoResearch`. */
+export interface AutoResearchInput {
+    projectId: string;
+    sessionId: string;
+}
+/** Dependencies injected by the dispatcher. */
+export interface AutoResearchDeps {
+    store: SessionStore;
+    manager: SessionStreamManager;
+    relay: Pick<RelayClient, "send">;
+    /** Subscriber map shared with handleClientMessage — ensures the session
+     *  already has a wire subscriber before we prompt. */
+    subscribers: Map<string, Subscriber>;
+    /** Project working directory (cwd from serve.ts). Used for file scanning. */
+    cwd: string;
+    /** Optional logger. Defaults to console.error. */
+    logger?: {
+        error: (...args: unknown[]) => void;
+    };
+}
+/**
+ * An extension discovered or generated by auto-research.
+ * Mirrors the shape in `ServerEvent["auto_research_complete"]["extensions"]`.
+ */
+export interface AutoResearchExtension {
+    name: string;
+    path: string;
+    description: string;
+    usesLLM?: boolean;
+    fileCount?: number;
+}
+/**
+ * Execute auto-research for a project through the existing AgentBridge.
+ *
+ * Caller (dispatcher) is fire-and-forget — this function is `void` and
+ * all errors are surfaced as `auto_research_error` events on the wire
+ * rather than thrown.
+ *
+ * This replaces the old subprocess-spawning approach. Instead of launching
+ * a separate spectral process (which lacks backend proxy credentials), we send
+ * the auto-research task through the session's existing AgentBridge. The agent
+ * uses the session's model, backend proxy, and all available tools.
+ */
+export declare function handleAutoResearch(input: AutoResearchInput, deps: AutoResearchDeps): void;
+//# sourceMappingURL=auto-research.d.ts.map

package/dist/relay/auto-research.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-research.d.ts","sourceRoot":"","sources":["../../src/relay/auto-research.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAM/C,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACjC;0DACsD;IACtD,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAksBD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,gBAAgB,GACrB,IAAI,CAmLN"}

package/dist/relay/auto-research.js

@@ -1,6 +1,6 @@
 /**
  * Auto-research handler — sends an auto-research task through the existing
- * AgentBridge (backend proxy) instead of spawning a separate pi process.
+ * AgentBridge (backend proxy) instead of spawning a separate spectral process.
  *
  * This ensures auto-research uses the same model and API keys as the active
  * session — no separate subprocess, no missing API key errors.
@@ -282,17 +282,16 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
         "",
         "## Pi Extension API Reference (HARD-CODED — DO NOT RESEARCH)",
         "",
-        "You are running inside **pi**, a coding agent harness. You do NOT need to research",
-        "what pi is or how it works — this knowledge is provided here. Jump straight to",
-        "analyzing the project and generating extensions.",
+        "This section is the canonical extension API. Use it directly — do NOT research",
+        "spectral internals. For the full guide, see `cli-node/docs/extensions.md` in the spectral repo.",
         "",
         "### Extension Entry Point",
         "",
         "Every extension is a TypeScript file exporting a single default `activate` function:",
         "",
         "```typescript",
-        "import type { ExtensionAPI } from \"@mariozechner/pi-coding-agent\";",
-        "export default function activate(pi: ExtensionAPI): void {",
+        "import type { ExtensionAPI, ToolDefinition } from \"@aexol/spectral\";",
+        "export default function activate(ext: ExtensionAPI): void {",
         "  // Register tools, commands, event handlers here",
         "}",
         "```",
@@ -300,94 +299,215 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
         "Extensions live in: `.spectral/extensions/` (project-local) or `~/.spectral/agent/extensions/` (user-global).",
         "Auto-research generates extensions into `.spectral/extensions/auto-research/<name>/`.",
         "",
-        "### Tools (pi.registerTool)",
+        "### Tools: ext.registerTool(tool)",
         "",
-        "The primary extension mechanism. Tools become available to the agent during conversations.",
+        "The primary extension mechanism. Tools become callable by the LLM.",
         "",
         "```typescript",
         "import { Type } from \"typebox\";  // Built-in, zero-dependency schema validation",
         "",
-        "pi.registerTool({",
-        "  name: \"tool_name\",                // snake_case, unique",
-        "  description: \"What this tool does\", // Used by the agent to decide when to call",
-        "  parameters: Type.Object({           // TypeBox schema for typed params",
-        "    input: Type.String({ description: \"The input to process\" }),",
-        "    // Optional params: Type.Optional(Type.String())",
-        "  }),",
-        "  handler: async (params, ctx) => {",
-        "    // ctx.session?.cwd — current working directory",
-        "    // ctx.bash(cmd) — run shell commands",
-        "    // ctx.read(path) — read files",
-        "    // ctx.write(path, content) — write files",
+        "ext.registerTool({",
+        "  name: \"tool_name\",                // snake_case, globally unique",
+        "  label: \"Tool Name\",                // Human-readable label for UI",
+        "  description: \"What this tool does\", // Used by the LLM to decide when to call",
+        "  parameters: {                       // JSON Schema object (required)",
+        "    type: \"object\",",
+        "    properties: {",
+        "      input: { type: \"string\", description: \"The input to process\" },",
+        "      mode: { type: \"string\", enum: [\"fast\", \"deep\"] },",
+        "    },",
+        "    required: [\"input\"],",
+        "  },",
+        "  // OR use TypeBox for richer schemas:",
+        "  // parameters: Type.Object({",
+        "  //   input: Type.String({ description: \"\" }),",
+        "  //   mode: Type.Optional(Type.Union([Type.Literal(\"fast\"), Type.Literal(\"deep\")])),",
+        "  // }),",
+        "  async execute(toolCallId, params, signal, onUpdate, ctx) {",
+        "    // toolCallId — unique call identifier (string)",
+        "    // params     — validated against your schema",
+        "    // signal     — AbortSignal | undefined",
+        "    // onUpdate   — send partial results (params) => void",
+        "    // ctx        — ExtensionContext",
+        "",
+        "    // For long operations, stream partial updates:",
+        "    onUpdate?.({ stage: \"starting\", progress: 0 });",
+        "    // ... work ...",
+        "    onUpdate?.({ stage: \"done\", progress: 100 });",
+        "",
         "    return {",
         "      content: [{ type: \"text\", text: \"Result string\" }],",
-        "      // isError: true  // set this to signal failure",
+        "      details: {},  // arbitrary structured data",
         "    };",
         "  },",
+        "  executionMode: \"sequential\",       // optional: \"sequential\" | \"parallel\"",
+        "  promptSnippet: \"One-liner for prompt\", // optional",
+        "  promptGuidelines: [\"Extra guidance\"],  // optional: appended to system prompt",
+        "  prepareArguments(args) {             // optional: shim args before validation",
+        "    return args;",
+        "  },",
         "});",
         "```",
         "",
-        "### Commands (pi.registerCommand)",
+        "**Error handling:** Return error content, don't throw:",
+        "",
+        "```typescript",
+        "async execute() {",
+        "  try {",
+        "    // ... work ...",
+        "  } catch (err: any) {",
+        "    return {",
+        "      content: [{ type: \"text\", text: `Error: ${err.message}` }],",
+        "      details: { isError: true },",
+        "    };",
+        "  }",
+        "}",
+        "```",
+        "",
+        "### Commands: ext.registerCommand(name, options)",
         "",
-        "Custom slash commands the user can type:",
+        "Register slash-commands invoked as `/command-name`:",
         "",
         "```typescript",
-        "pi.registerCommand({",
+        "ext.registerCommand({",
         "  name: \"my-command\",",
         "  description: \"What /my-command does\",",
-        "  execute: async (args: string[], ctx) => {",
+        "  async execute(args: string, ctx: ExtensionContext) {",
         "    return { content: [{ type: \"text\", text: \"Done\" }] };",
         "  },",
         "});",
         "```",
         "",
-        "### Event Interception (pi.on)",
-        "",
-        "React to agent lifecycle events. Available events: `tool_call` (before a tool runs),",
-        "`session_start`, `session_shutdown`, `context` (prompt assembly), `before_agent_start`.",
+        "### Events: ext.on(eventType, handler)",
+        "",
+        "Hook into the agent lifecycle. Handlers can observe, modify (return result), or block.",
+        "",
+        "| Event | When | Return type |",
+        "|-------|------|-------------|",
+        "| `resources_discover` | After session start | `ResourcesDiscoverResult` — add skill/prompt/theme paths |",
+        "| `session_start` | Session loaded | — (void) |",
+        "| `session_before_switch` | Before switching session | `SessionBeforeSwitchResult` — can cancel |",
+        "| `session_before_fork` | Before forking | `SessionBeforeForkResult` — can cancel |",
+        "| `session_before_compact` | Before compaction | `SessionBeforeCompactResult` — can cancel/provide compaction |",
+        "| `session_compact` | After compaction | — |",
+        "| `session_before_tree` | Before tree navigation | `SessionBeforeTreeResult` — can cancel/provide summary |",
+        "| `session_tree` | After tree navigation | — |",
+        "| `session_shutdown` | Extension runtime teardown | — |",
+        "| `before_agent_start` | After user prompt, before LLM call | `BeforeAgentStartEventResult` — modify system prompt |",
+        "| `agent_start` | Agent loop starts | — |",
+        "| `agent_end` | Agent loop ends | — |",
+        "| `turn_start` | Each turn starts | — |",
+        "| `turn_end` | Each turn ends | — |",
+        "| `message_start` | Message begins | — |",
+        "| `message_update` | Token-by-token streaming | — |",
+        "| `message_end` | Message finalizes | `MessageEndEventResult` — replace message |",
+        "| `tool_execution_start` | Tool starts executing | — |",
+        "| `tool_execution_update` | Tool sends partial result | — |",
+        "| `tool_execution_end` | Tool finishes | — |",
+        "| `tool_call` | Before tool executes | `ToolCallEventResult` — block/modify input |",
+        "| `tool_result` | After tool executes | `ToolResultEventResult` — modify result |",
+        "| `model_select` | Model changes | — |",
+        "| `user_bash` | User runs ! command | `UserBashEventResult` — override execution |",
+        "| `input` | User input received | `InputEventResult` — transform/block/continue |",
+        "| `context` | Before each LLM call | `ContextEventResult` — modify messages |",
+        "| `before_provider_request` | Before provider API call | Replace payload |",
+        "| `after_provider_response` | After provider API response | — |",
         "",
         "```typescript",
-        "pi.on(\"tool_call\", (event) => {",
-        "  // event.name — tool being called",
-        "  // event.params — tool arguments",
-        "  // Can modify or observe tool calls",
+        "ext.on(\"before_agent_start\", (event, ctx) => {",
+        "  // Inject extra instructions into every turn:",
+        "  return { systemPrompt: event.systemPrompt + \"\\nExtra rules...\" };",
+        "});",
+        "",
+        "ext.on(\"tool_call\", (event, ctx) => {",
+        "  // event.name, event.params, event.toolCallId",
+        "  // Return { blocked: true, reason: \"...\" } to block",
+        "  // Return { params: {...} } to mutate input",
         "});",
         "```",
         "",
-        "### Model Access (LLM-powered extensions)",
+        "### Actions: ext.sendMessage / ext.sendUserMessage / ext.exec",
+        "",
+        "```typescript",
+        "// Send custom messages into the session stream:",
+        "ext.sendMessage({ customType: \"my-event\", content: \"Something happened!\", display: \"Notification\", details: {} });",
+        "ext.sendUserMessage(\"Continue with the task.\");",
+        "",
+        "// Run a shell command:",
+        "const result = await ext.exec(\"npm\", [\"test\"], { cwd: \"/path\" });",
+        "// result.exitCode, result.stdout, result.stderr",
+        "```",
+        "",
+        "### Model / Thinking Control",
+        "",
+        "```typescript",
+        "// Get/set thinking level (off | minimal | low | medium | high)",
+        "ext.getThinkingLevel();",
+        "ext.setThinkingLevel(\"high\");",
+        "",
+        "// Tool visibility management",
+        "ext.getActiveTools();    // string[] — currently enabled tool names",
+        "ext.getAllTools();       // ToolInfo[] — all registered tools",
+        "ext.setActiveTools([\"bash\", \"read\", \"write\", \"edit\", \"my_tool\"]);",
+        "```",
+        "",
+        "### CLI Flags: ext.registerFlag",
+        "",
+        "```typescript",
+        "ext.registerFlag(\"api-endpoint\", { description: \"Override API endpoint\", type: \"string\" });",
+        "const endpoint = ext.getFlag(\"api-endpoint\") as string;",
+        "```",
         "",
-        "Extensions can call LLMs to build AI-powered features:",
+        "### Provider Registration: ext.registerProvider",
         "",
         "```typescript",
-        "// Discover available models",
-        "const models = pi.modelRegistry.list();",
-        "const model = pi.modelRegistry.find(\"claude-sonnet-4-5\");",
+        "ext.registerProvider(\"my-proxy\", {",
+        "  baseUrl: \"https://proxy.example.com\",",
+        "  apiKey: \"sk-...\",",
+        "  api: \"anthropic-messages\",",
+        "  models: [{ id: \"custom\", name: \"Custom\", reasoning: false, input: [\"text\"],",
+        "    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },",
+        "    contextWindow: 200000, maxTokens: 16384 }],",
+        "});",
+        "```",
         "",
-        "// Switch the active model for the current turn",
-        "const switched = pi.setModel(model.id);  // returns false if no API key",
+        "### Keyboard Shortcuts: ext.registerShortcut",
         "",
-        "// For complex multi-step AI pipelines, spawn a subagent:",
-        "// (see subagent extension pattern below)",
+        "```typescript",
+        "ext.registerShortcut(\"ctrl+shift+k\", { description: \"Run custom action\", handler(ctx) { /* ... */ } });",
         "```",
         "",
+        "### The ExtensionContext (ctx)",
+        "",
+        "Passed to every execute/handler. Key properties:",
+        "",
+        "| Property/method | Description |",
+        "|-----------------|-------------|",
+        "| `ctx.cwd` | Current working directory (string) |",
+        "| `ctx.hasUI` | Whether interactive UI is available (boolean) |",
+        "| `ctx.model` | Current model object (Model \\| undefined) |",
+        "| `ctx.modelRegistry` | List/find available models |",
+        "| `ctx.signal` | Current AbortSignal (undefined if no stream) |",
+        "| `ctx.abort()` | Abort the current operation |",
+        "| `ctx.isIdle()` | Whether the agent is not streaming |",
+        "| `ctx.getSystemPrompt()` | Get the full system prompt (string) |",
+        "| `ctx.getContextUsage()` | Token usage info |",
+        "| `ctx.compact(options?)` | Trigger context compaction |",
+        "| `ctx.shutdown()` | Gracefully exit |",
+        "| `ctx.ui.select(prompt, choices)` | Ask the user to pick from a list |",
+        "| `ctx.ui.confirm(prompt)` | Ask the user Yes/No |",
+        "| `ctx.ui.notify(message)` | Show a notification |",
+        "",
         "### Available Packages (npm dependencies)",
         "",
         "Extensions run as Node.js TypeScript modules. These packages are available:",
-        "- `@mariozechner/pi-coding-agent` — ExtensionAPI type",
-        "- `@mariozechner/pi-ai` — AI types and utilities",
+        "- `@aexol/spectral` — ExtensionAPI, all event types, ToolDefinition, defineTool, type guards",
         "- `typebox` — Zero-dependency runtime type validation",
         "- All `node:*` built-ins: `fs`, `path`, `child_process`, `os`, `crypto`, etc.",
         "- Any npm package already in the project's node_modules",
         "",
-        "```typescript",
-        "import * as fs from \"node:fs\";",
-        "import * as path from \"node:path\";",
-        "import { execSync } from \"node:child_process\";",
-        "```",
-        "",
-        "### Pi's Built-in Tools (what the agent already has)",
+        "### spectral's Built-in Tools (what the agent already has — DO NOT reimplement)",
         "",
-        "The agent already has these tools — do NOT reimplement them:",
         "- `read` — Read file contents",
         "- `write` — Create/overwrite files",
         "- `edit` — Precise text replacement in files",
@@ -395,44 +515,29 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
         "- `grep` — Search file contents with regex",
         "- `find` — Search files by name/pattern",
         "- `ls` — List directory contents",
+        "- `subagent` — Spawn isolated sub-agents",
         "- `recall` — Recall compressed memory observations",
-        "- `mcp` — MCP server gateway (if MCP extension is active)",
+        "- `mcp` — MCP server gateway",
+        "- `kanban_list/get/create/update/move/next/delete` — Kanban board (if bound)",
         "",
         "### Extension File Structure",
         "",
-        "Each extension is a directory under `.spectral/extensions/auto-research/`:",
-        "",
         "```",
         ".spectral/extensions/auto-research/",
         "  <extension-name>/",
-        "    index.ts          # Entry point — default export activate(pi)",
+        "    index.ts          # Entry point — default export activate(ext)",
         "    utils.ts          # [optional] Helper functions",
         "    state.json        # [optional] Persisted state (for stateful extensions)",
         "```",
         "",
-        "### Handler Return Types",
-        "",
-        "All handlers (tools, commands) return content blocks:",
-        "",
-        "```typescript",
-        "// Success:",
-        "return { content: [{ type: \"text\", text: \"Result\" }] };",
-        "",
-        "// Error:",
-        "return {",
-        "  content: [{ type: \"text\", text: \"Error message\" }],",
-        "  isError: true,",
-        "};",
-        "```",
-        "",
         "### Common Extension Patterns",
         "",
-        "1. **Shell wrapper** — Use `ctx.bash()` inside a tool handler to run commands",
-        "2. **File processor** — Use `ctx.read()`/`ctx.write()` to process project files",
-        "3. **LLM-powered** — Use `pi.modelRegistry` to call AI models for smart processing",
-        "4. **Event listener** — Use `pi.on()` to react to agent lifecycle events",
+        "1. **Shell wrapper** — Use `execSync` from \"node:child_process\" to run project commands",
+        "2. **File processor** — Use `node:fs` to read/write project files",
+        "3. **LLM-powered** — Use `ext.modelRegistry` to call AI models for smart processing",
+        "4. **Event listener** — Use `ext.on()` to react to agent lifecycle events",
         "5. **Stateful** — Use `node:fs` to persist state as JSON between calls",
-        "6. **Subagent** — Spawn pi subprocesses for isolated analysis tasks",
+        "6. **Subagent** — Use the `subagent` tool for isolated analysis tasks",
         "",
         "---",
         "",
@@ -451,8 +556,8 @@ function buildAutoResearchTask(projectPath, projectName, preRunContext = null) {
         "   - Could LLM-powered extensions improve developer workflows?",
         "",
         "3. **Extension Generation** — Create extension .ts files:",
-        "   - Use `pi.registerTool()` for simple tools with TypeBox validation",
-        "   - Use `pi.registerCommand()` for custom slash commands",
+        "   - Use `ext.registerTool()` for simple tools with TypeBox validation",
+        "   - Use `ext.registerCommand()` for custom slash commands",
         "   - For LLM-powered extensions, use `ctx.modelRegistry` to call models",
         "   - Create files under `.spectral/extensions/auto-research/<name>/`",
         "   - Each extension needs an `index.ts` that registers its tools/commands",
@@ -580,7 +685,7 @@ const AR_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes — generous for LLM-based a
  * rather than thrown.
  *
  * This replaces the old subprocess-spawning approach. Instead of launching
- * a separate pi process (which lacks backend proxy credentials), we send
+ * a separate spectral process (which lacks backend proxy credentials), we send
  * the auto-research task through the session's existing AgentBridge. The agent
  * uses the session's model, backend proxy, and all available tools.
  */

package/dist/relay/client.d.ts

@@ -0,0 +1,126 @@
+/**
+ * RelayClient — long-lived WebSocket connection to the Aexol backend's
+ * `/agent-connection` endpoint.
+ *
+ * Responsibilities:
+ *  - Open and maintain a single WS to the relay, authenticated with the
+ *    machine JWT via `Authorization: Bearer <jwt>`.
+ *  - Reply `{kind:"pong"}` to backend `{kind:"ping"}`. Backend closes
+ *    `4408 heartbeat-timeout` if it doesn't hear from us within 90s; we
+ *    rely on the backend pings rather than emitting our own (single source
+ *    of liveness, no jitter on our side).
+ *  - **Watchdog timer:** tracks `lastActivityMs` on every received frame /
+ *    ping. Every 15 s, if no activity within `WATCHDOG_MS` (120 s = 2×
+ *    backend timeout), force-closes the socket (4001 "watchdog-timeout")
+ *    and triggers a reconnect. Detects silent backend death (Docker OOM
+ *    kill, network partition without TCP RST) where the socket stays open
+ *    but no data flows.
+ *  - **Pre-reconnect health check:** before opening a new WS, does a quick
+ *    HTTP GET to `backendUrl/health` with a 5 s timeout. If the backend is
+ *    unhealthy or unreachable, skips the WS attempt and re-schedules. This
+ *    avoids a slow TCP connect timeout (up to 75 s on some platforms) when
+ *    the backend is down.
+ *  - On unexpected close, reconnect forever with exponential backoff +
+ *    ±20% jitter, capped at 30s. There is no "give up" state — if the
+ *    machine is offline for hours, we just keep trying. Operators can
+ *    `Ctrl-C` to stop.
+ *  - Buffer outbound frames in a small queue while the socket is closed.
+ *    Capped at 100 frames; oldest is dropped on overflow.
+ *
+ * Events (typed via `RelayClientEvents`):
+ *  - `open`            - connected and welcomed
+ *  - `welcome`         - backend `{kind:"welcome"}` frame
+ *  - `frame`           - any non-pong, non-welcome frame
+ *  - `close`           - socket closed (we may reconnect after)
+ *  - `error`           - non-fatal error (parse failure, send failure)
+ *  - `reconnect-scheduled` - emitted with the delay in ms before each retry
+ *
+ * Threading model: `node:events` is single-threaded; all callbacks fire on
+ * the same event loop turn. Listeners must be cheap.
+ */
+import { EventEmitter } from "node:events";
+import WebSocket from "ws";
+export interface RelayClientOptions {
+    /** Full WS URL, e.g. wss://api.aexol.ai/agent-connection */
+    relayUrl: string;
+    /** Bearer JWT for the WS handshake. */
+    machineJwt: string;
+    /**
+     * Backend HTTP(S) base URL for the pre-reconnect health check
+     * (`GET <backendUrl>/health`). When omitted, the health check is
+     * skipped (tests, local-only deploys without a /health endpoint).
+     */
+    backendUrl?: string;
+    /**
+     * Override the WebSocket constructor (tests inject a fake or a wrapper).
+     * Default: `ws` package's `WebSocket`.
+     */
+    webSocketImpl?: typeof WebSocket;
+    /**
+     * Override `fetch` (tests inject a stub for health checks).
+     * Default: global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Optional logger. Defaults to console. Tests pass a noop.
+     */
+    logger?: Pick<Console, "log" | "warn" | "error">;
+    /**
+     * Override `process.exit` for tests. Called when the backend evicts us
+     * with `replaced-by-newer-registration` to avoid a reconnect ping-pong.
+     * Default: `process.exit`.
+     */
+    exit?: (code: number) => never;
+}
+/** Strongly-typed event surface. Used for ergonomic `.on(...)` callsites. */
+export interface RelayFrame {
+    /** Echoed-out shape; concrete type varies by Batch. */
+    kind?: string;
+    [key: string]: unknown;
+}
+export declare class RelayClient extends EventEmitter {
+    private readonly relayUrl;
+    private readonly machineJwt;
+    private readonly backendUrl;
+    private readonly WS;
+    private readonly fetchImpl;
+    private readonly logger;
+    private readonly exit;
+    private ws;
+    private disposed;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private sendQueue;
+    /** Timestamp of last received frame / ping — drives the watchdog. */
+    private lastActivityMs;
+    private watchdogTimer;
+    constructor(opts: RelayClientOptions);
+    /** Open the connection. Idempotent — calling twice is a no-op. */
+    connect(): void;
+    /**
+     * Send a frame. If the socket is open it goes immediately; otherwise
+     * it's queued (capped at 100 — oldest dropped) and flushed on the next
+     * successful `open`.
+     *
+     * Returns `true` if the frame was sent or queued, `false` if it was
+     * dropped due to dispose.
+     */
+    send(frame: RelayFrame | string): boolean;
+    /**
+     * Close the connection and stop reconnecting. After dispose, this client
+     * is dead — create a new one to reconnect.
+     */
+    dispose(): void;
+    private openSocket;
+    private startWatchdog;
+    private stopWatchdog;
+    /**
+     * Pre-reconnect health check: quick HTTP GET to `<backendUrl>/health`.
+     * Returns true when the backend is reachable (or when no backendUrl is
+     * configured, which skips the check entirely). Returns false when the
+     * backend is unhealthy/down — the caller should re-schedule.
+     */
+    private healthCheck;
+    private scheduleReconnect;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/relay/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/relay/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,SAAS,MAAM,IAAI,CAAC;AAqB3B,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;OAEG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACjD;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;CAChC;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,WAAY,SAAQ,YAAY;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAmB;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAE/C,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,SAAS,CAAgB;IAEjC,qEAAqE;IACrE,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,aAAa,CAA+B;gBAExC,IAAI,EAAE,kBAAkB;IAWpC,kEAAkE;IAClE,OAAO,IAAI,IAAI;IAMf;;;;;;;OAOG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO;IAqBzC;;;OAGG;IACH,OAAO,IAAI,IAAI;IA2Bf,OAAO,CAAC,UAAU;IAgHlB,OAAO,CAAC,aAAa;IAsBrB,OAAO,CAAC,YAAY;IAOpB;;;;;OAKG;YACW,WAAW;YA8BX,iBAAiB;CAmDhC"}