@aexol/spectral 0.9.15 → 0.9.17

package/dist/memory/unified-compaction.js

@@ -0,0 +1,332 @@
+/**
+ * Unified Compaction — single LLM call replacing both:
+ *   1. Core spectral generateSummary() (narrative conversation summary)
+ *   2. Sync catch-up observer (observation extraction from gap entries)
+ *
+ * Uses a text-based delimited output format (compatible with any model
+ * without requiring native structured-output support):
+ *
+ *   ===NARRATIVE===
+ *   ## Goal
+ *   ...
+ *
+ *   ===OBSERVATIONS===
+ *   [YYYY-MM-DD HH:MM] [relevance] Content line
+ *   ...
+ */
+import { completeSimple } from "../sdk/ai/index.js";
+import { extractFileOpsFromMessage, computeFileLists, createFileOps, formatFileOperations, } from "../sdk/coding-agent/core/compaction/utils.js";
+import { hashId } from "./ids.js";
+import { nowTimestamp, truncateRecordContent } from "./serialize.js";
+import { debugLog } from "./debug-log.js";
+// ============================================================================
+// Section Delimiters
+// ============================================================================
+const NARRATIVE_SECTION = "===NARRATIVE===";
+const OBSERVATIONS_SECTION = "===OBSERVATIONS===";
+// ============================================================================
+// Prompt Templates
+// ============================================================================
+const UNIFIED_SYSTEM_PROMPT = `You are a context compression agent. Your task has TWO complementary outputs that MUST be produced together in a single response.
+
+TASK A — NARRATIVE SUMMARY: Create a structured checkpoint of the conversation progress. This is what another LLM reads to understand where the work stands.
+
+TASK B — FACTUAL MEMORY: Extract timestamped observations (single-line facts with relevance tags). These records are the assistant's ONLY memory of this conversation after the raw messages fall out of context.
+
+Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured result using the EXACT format specified.`;
+function buildUnifiedPrompt(conversationText, previousSummary, customInstructions, currentTime) {
+    let prompt = `<conversation>\n${conversationText}\n</conversation>\n\n`;
+    if (previousSummary) {
+        prompt += `<previous-summary>\n${previousSummary}\n</previous-summary>\n\n`;
+    }
+    prompt += `Current local time: ${currentTime}\n\n`;
+    prompt += `Output your response in TWO sections delimited by the exact markers shown below.
+
+SECTION A — ${NARRATIVE_SECTION}
+
+Produce a structured context checkpoint summary using this EXACT format:
+
+## Goal
+[What is the user trying to accomplish? Can be multiple items. If updating a previous summary, preserve existing goals and add new ones.]
+
+## Constraints & Preferences
+- [Any constraints, preferences, or requirements mentioned by user]
+- [Or "(none)" if none were mentioned]
+[When updating: preserve existing constraints, add new ones.]
+
+## Progress
+### Done
+- [x] [Completed tasks/changes. Preserve previously completed items, add newly completed ones.]
+
+### In Progress
+- [ ] [Current work. Update based on progress.]
+
+### Blocked
+- [Issues preventing progress, if any. Remove blockers that have been resolved.]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale]
+[Preserve all previous decisions, add new ones.]
+
+## Next Steps
+1. [Ordered list of what should happen next. Update based on current state.]
+
+## Critical Context
+- [Any data, examples, or references needed to continue]
+- [Or "(none)" if not applicable]
+
+Keep each section concise. Preserve exact file paths, function names, and error messages.
+${customInstructions ? `\nAdditional focus for the narrative: ${customInstructions}` : ""}
+
+SECTION B — ${OBSERVATIONS_SECTION}
+
+Extract NEW timestamped facts from the conversation. Each observation must be on its own line in this exact format:
+
+[YYYY-MM-DD HH:MM] [relevance] Single-line plain prose fact. No markdown, no bullets.
+
+Do NOT restate facts already captured in the <previous-summary>. Skip routine, low-information events (tool-call acks, status updates).
+
+OBSERVATION CONTENT RULES:
+- Single line of plain prose. No markdown, no bullets, no code fences, no XML/HTML tags, no emojis.
+- Preserve user assertions exactly. When the user STATES something about themselves, their project, or their environment, capture it as an assertion. When the user ASKS something, capture it as a question.
+- Use precise action verbs (completed, resolved, implemented, chose, configured etc.).
+- Mark concrete completions explicitly: "completed: implemented X at path/to/file.ts; user confirmed tests pass."
+- Split compound statements into separate observations (one fact per line).
+- Group repeated similar tool calls into a single observation.
+- Preserve exact file paths, function names, line numbers, error messages (verbatim), package names, identifiers.
+- Use the timestamp from the closest conversation message. Fall back to the current local time if no message timestamp applies.
+
+RELEVANCE LEVELS (pick one per observation):
+- critical: user identity, role, persistent preferences, explicit corrections, concrete completions that future runs MUST NOT redo.
+- high: non-trivial technical decisions, architectural direction, unresolved blockers, key constraints.
+- medium: task-level context that helps within the current work. Default when unsure between medium and high.
+- low: routine tool-call acks, repetitive status updates, trivially re-derivable content. Skip these unless they carry unique detail.
+
+Do NOT default everything to "high" or "critical". Most observations should be "medium". Use "low" only for truly routine items.
+
+Focus areas for observations:
+- User identity, preferences, constraints, corrections.
+- Project goals, architectural decisions, rationale.
+- File paths and line numbers of changes.
+- Error messages (verbatim).
+- Completed work that should not be redone.
+- Named identifiers (package names, function/variable names, ticket IDs, commit SHAs).`;
+    return prompt;
+}
+// ============================================================================
+// Conversation Serialization
+// ============================================================================
+const TOOL_RESULT_MAX_CHARS = 2000;
+const VISION_DESCRIPTION_PREFIX = "[Image description from ";
+function stripVisionBlocks(text) {
+    if (!text.includes(VISION_DESCRIPTION_PREFIX))
+        return text;
+    const lines = text.split("\n");
+    const kept = [];
+    let skipping = false;
+    for (const line of lines) {
+        if (!skipping && line.startsWith(VISION_DESCRIPTION_PREFIX)) {
+            skipping = true;
+            continue;
+        }
+        if (skipping) {
+            if (line === "]") {
+                skipping = false;
+            }
+            continue;
+        }
+        kept.push(line);
+    }
+    return kept.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+function serializeMessagesForUnified(messages) {
+    const parts = [];
+    for (const msg of messages) {
+        if (msg.role === "user") {
+            const content = typeof msg.content === "string"
+                ? msg.content
+                : Array.isArray(msg.content)
+                    ? msg.content.filter((c) => c.type === "text").map(c => c.text).join("")
+                    : "";
+            const cleaned = stripVisionBlocks(content);
+            if (cleaned)
+                parts.push(`[User]: ${cleaned}`);
+        }
+        else if (msg.role === "assistant" && "content" in msg && Array.isArray(msg.content)) {
+            const textParts = [];
+            const toolParts = [];
+            for (const block of msg.content) {
+                if (block.type === "text" && "text" in block) {
+                    textParts.push(block.text);
+                }
+                else if (block.type === "toolCall" && "name" in block) {
+                    const args = block.arguments;
+                    const argsStr = Object.keys(args).sort().map(k => `${k}=${JSON.stringify(args[k])}`).join(", ");
+                    toolParts.push(`${block.name}(${argsStr})`);
+                }
+            }
+            const combined = [...textParts, ...(toolParts.length ? [`[Tools: ${toolParts.join("; ")}]`] : [])];
+            if (combined.length)
+                parts.push(`[Assistant]: ${combined.join("\n")}`);
+        }
+        else if (msg.role === "toolResult") {
+            const text = Array.isArray(msg.content)
+                ? msg.content.filter((c) => c.type === "text").map(c => c.text).join("")
+                : typeof msg.content === "string" ? msg.content : "";
+            if (text) {
+                const truncated = text.length > TOOL_RESULT_MAX_CHARS
+                    ? `${text.slice(0, TOOL_RESULT_MAX_CHARS)}\n[...truncated]`
+                    : text;
+                parts.push(`[Tool result]: ${truncated}`);
+            }
+        }
+        else if (msg.role === "compactionSummary" && "summary" in msg) {
+            parts.push(`[Previous compaction summary]: ${msg.summary}`);
+        }
+    }
+    return parts.join("\n\n");
+}
+// ============================================================================
+// Output Parsing
+// ============================================================================
+const OBSERVATION_LINE_RE = /^\[(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2})\]\s*\[(low|medium|high|critical)\]\s*(.+)$/i;
+function parseObservations(text) {
+    const results = [];
+    const lines = text.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#") || trimmed === OBSERVATIONS_SECTION)
+            continue;
+        const match = trimmed.match(OBSERVATION_LINE_RE);
+        if (match) {
+            results.push({
+                timestamp: match[1],
+                relevance: match[2].toLowerCase(),
+                content: match[3].trim(),
+            });
+        }
+    }
+    return results;
+}
+function normalizeObservation(raw) {
+    const content = truncateRecordContent(raw.content);
+    if (!content)
+        return undefined;
+    const validRelevance = ["low", "medium", "high", "critical"];
+    const relevance = validRelevance.includes(raw.relevance)
+        ? raw.relevance
+        : "medium";
+    return {
+        id: hashId(content),
+        content,
+        timestamp: raw.timestamp,
+        relevance,
+    };
+}
+/**
+ * Generate a unified compaction result: narrative summary + observations
+ * in a single LLM call. Uses delimited text output for broad model compatibility.
+ */
+export async function generateUnifiedCompaction(input) {
+    const { messagesToSummarize, gapChunk, model, apiKey, headers, signal, previousSummary, customInstructions, thinkingLevel, reserveTokens, } = input;
+    const maxTokens = Math.min(Math.floor(0.8 * reserveTokens), model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY);
+    // Build conversation text
+    const parts = [];
+    const coreText = serializeMessagesForUnified(messagesToSummarize);
+    if (coreText)
+        parts.push(coreText);
+    if (gapChunk?.trim()) {
+        parts.push(`\n--- Gap entries (unobserved raw conversation) ---\n${gapChunk}`);
+    }
+    const conversationText = parts.join("\n\n");
+    const currentTime = nowTimestamp();
+    const userPrompt = buildUnifiedPrompt(conversationText, previousSummary, customInstructions, currentTime);
+    const promptMessages = [
+        {
+            role: "user",
+            content: [{ type: "text", text: userPrompt }],
+            timestamp: Date.now(),
+        },
+    ];
+    const options = { maxTokens, signal, apiKey, headers };
+    if (model.reasoning && thinkingLevel && thinkingLevel !== "off") {
+        options.reasoning = thinkingLevel;
+    }
+    debugLog("unified_compaction.start", {
+        messageCount: messagesToSummarize.length,
+        hasGap: !!gapChunk?.trim(),
+        conversationLength: conversationText.length,
+    });
+    const response = await completeSimple(model, { systemPrompt: UNIFIED_SYSTEM_PROMPT, messages: promptMessages }, options);
+    if (response.stopReason === "error") {
+        throw new Error(`Unified compaction failed: ${response.errorMessage || "Unknown error"}`);
+    }
+    if (response.stopReason === "aborted") {
+        throw new Error("Unified compaction aborted");
+    }
+    const fullText = response.content
+        .filter((c) => c.type === "text")
+        .map((c) => c.text)
+        .join("\n");
+    // Parse the two sections
+    const narrativeIdx = fullText.indexOf(NARRATIVE_SECTION);
+    const obsIdx = fullText.indexOf(OBSERVATIONS_SECTION);
+    let narrativeSummary;
+    let rawObservationsText;
+    if (narrativeIdx >= 0 && obsIdx >= 0) {
+        // Both sections present
+        if (narrativeIdx < obsIdx) {
+            narrativeSummary = fullText.slice(narrativeIdx + NARRATIVE_SECTION.length, obsIdx).trim();
+        }
+        else {
+            narrativeSummary = fullText.slice(narrativeIdx + NARRATIVE_SECTION.length).trim();
+        }
+        rawObservationsText = fullText.slice(obsIdx + OBSERVATIONS_SECTION.length).trim();
+    }
+    else if (narrativeIdx >= 0) {
+        // Only narrative
+        narrativeSummary = fullText.slice(narrativeIdx + NARRATIVE_SECTION.length).trim();
+        rawObservationsText = "";
+    }
+    else if (obsIdx >= 0) {
+        // Only observations (unusual but handle gracefully)
+        narrativeSummary = fullText.slice(0, obsIdx).trim();
+        rawObservationsText = fullText.slice(obsIdx + OBSERVATIONS_SECTION.length).trim();
+    }
+    else {
+        // No delimiters found — treat entire output as narrative
+        debugLog("unified_compaction.no_delimiters", { textLength: fullText.length });
+        narrativeSummary = fullText;
+        rawObservationsText = "";
+    }
+    // Parse observations
+    const rawObservations = parseObservations(rawObservationsText);
+    const observations = [];
+    const seen = new Set();
+    for (const raw of rawObservations) {
+        const normalized = normalizeObservation(raw);
+        if (normalized && !seen.has(normalized.id)) {
+            seen.add(normalized.id);
+            observations.push(normalized);
+        }
+    }
+    // Compute file operations
+    const fileOps = createFileOps();
+    for (const msg of messagesToSummarize) {
+        extractFileOpsFromMessage(msg, fileOps);
+    }
+    const { readFiles, modifiedFiles } = computeFileLists(fileOps);
+    // Append file operations to narrative
+    const fullNarrativeSummary = narrativeSummary + formatFileOperations(readFiles, modifiedFiles);
+    debugLog("unified_compaction.result", {
+        narrativeLength: fullNarrativeSummary.length,
+        observationCount: observations.length,
+        rawObservationLines: rawObservations.length,
+    });
+    return {
+        narrativeSummary: fullNarrativeSummary,
+        observations,
+        readFiles,
+        modifiedFiles,
+    };
+}

package/dist/relay/dispatcher.d.ts

@@ -48,7 +48,7 @@ import type { RelayClient } from "./client.js";
  * `id` is populated when the route had an `:id` placeholder.
  */
 interface RouteMatch {
-    route: "list_projects" | "create_project" | "update_project" | "delete_project" | "bind_studio" | "list_project_sessions" | "create_session" | "get_session" | "update_session" | "delete_session" | "get_session_memory" | "get_session_memory_details" | "compact_session" | "remember_and_delete_session" | "fork_session" | "list_path_autocomplete" | "pick_directory" | "enqueue_prompt" | "get_prompt_queue" | "remove_prompt" | "clear_prompt_queue" | "list_mcp_status" | "get_settings" | "put_settings";
+    route: "list_projects" | "create_project" | "update_project" | "delete_project" | "bind_studio" | "list_project_sessions" | "create_session" | "get_session" | "update_session" | "delete_session" | "get_session_memory" | "get_session_memory_details" | "compact_session" | "remember_and_delete_session" | "fork_session" | "list_path_autocomplete" | "pick_directory" | "search_project_files" | "enqueue_prompt" | "get_prompt_queue" | "remove_prompt" | "clear_prompt_queue" | "list_mcp_status" | "get_settings" | "put_settings";
     id?: string;
     /** Parsed query params, if the path carried a `?...` suffix. */
     query?: URLSearchParams;

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

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/relay/dispatcher.js

@@ -43,6 +43,7 @@ import { BadRequestError, NotFoundError } from "../server/handlers/errors.js";
 import { handleListMcpStatus } from "../server/handlers/mcp-status.js";
 import { handlePathAutocomplete } from "../server/handlers/paths-autocomplete.js";
 import { handlePickDirectory } from "../server/handlers/paths-pick-directory.js";
+import { handleSearchProjectFiles } from "../server/handlers/files-search.js";
 import { handleBindStudioProject, handleCreateProject, handleDeleteProject, handleListProjects, handleListSessionsByProject, handleUpdateProject, } from "../server/handlers/projects.js";
 import { handleCompactSession, handleCreateSession, handleDeleteSession, handleForkSession, handleRememberAndDeleteSession, handleGetSessionDetail, handleGetSessionMemoryDetails, handleGetSessionMemoryStatus, handleUpdateSession, } from "../server/handlers/sessions.js";
 import { handleClearPromptQueue, handleEnqueuePrompt, handleGetPromptQueue, handleRemovePrompt, } from "../server/handlers/queue.js";
@@ -101,6 +102,14 @@ export function matchRoute(method, path) {
             return { route: "create_session" };
         return null;
     }
+    // /api/projects/:id/files/search
+    const projectFilesMatch = /^\/api\/projects\/([^/]+)\/files\/search$/.exec(cleanPath);
+    if (projectFilesMatch) {
+        const id = decodeURIComponent(projectFilesMatch[1]);
+        if (method === "GET")
+            return { route: "search_project_files", id, query };
+        return null;
+    }
     // /api/projects/:id/bind-studio
     const bindStudioMatch = /^\/api\/projects\/([^/]+)\/bind-studio$/.exec(cleanPath);
     if (bindStudioMatch) {
@@ -406,6 +415,10 @@ async function dispatchRoute(match, body, deps) {
         }
         case "pick_directory":
             return handlePickDirectory();
+        case "search_project_files": {
+            const searchQuery = match.query?.get("query") ?? "";
+            return handleSearchProjectFiles(store, id, searchQuery);
+        }
         case "enqueue_prompt":
             return handleEnqueuePrompt(store, manager, id, asObject(body));
         case "get_prompt_queue":

package/dist/server/handlers/files-search.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Project file search for the agent composer `@` mention dropdown.
+ *
+ * `GET /api/projects/:id/files/search?query=<query>` returns files whose
+ * relative path contains the query (case-insensitive). Results are limited
+ * to `MAX_RESULTS` and common generated directories are always excluded.
+ *
+ * The handler is synchronous-style but returns a Promise because `glob`
+ * exposes an async API.
+ */
+import type { SessionStore } from "../storage.js";
+export interface ProjectFileSearchResult {
+    /** Absolute filesystem path. */
+    path: string;
+    /** Path relative to the project root (POSIX separators). */
+    relativePath: string;
+    /** Filename (basename). */
+    name: string;
+}
+/**
+ * Search files in a project whose relative path contains `query`
+ * (case-insensitive). Returns an empty array when the project has no
+ * files, when the query is empty, or when the project path is unreadable.
+ */
+export declare function handleSearchProjectFiles(store: SessionStore, projectId: string, query: string): Promise<ProjectFileSearchResult[]>;
+//# sourceMappingURL=files-search.d.ts.map

package/dist/server/handlers/files-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files-search.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/files-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,WAAW,uBAAuB;IACtC,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAyBD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAqDpC"}

package/dist/server/handlers/files-search.js

@@ -0,0 +1,89 @@
+/**
+ * Project file search for the agent composer `@` mention dropdown.
+ *
+ * `GET /api/projects/:id/files/search?query=<query>` returns files whose
+ * relative path contains the query (case-insensitive). Results are limited
+ * to `MAX_RESULTS` and common generated directories are always excluded.
+ *
+ * The handler is synchronous-style but returns a Promise because `glob`
+ * exposes an async API.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { glob } from "glob";
+import { NotFoundError } from "./errors.js";
+/** Maximum number of suggestions shown in the composer dropdown. */
+const MAX_RESULTS = 20;
+/**
+ * Directories/patterns that are never useful as `@` mention targets.
+ * These are applied in addition to the project's own `.gitignore`.
+ */
+const ALWAYS_IGNORE = [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/.next/**",
+    "**/.nuxt/**",
+    "**/.svelte-kit/**",
+    "**/.astro/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.spectral/**",
+    "**/.vscode/**",
+    "**/.idea/**",
+    "**/coverage/**",
+    "**/*.log",
+];
+/**
+ * Search files in a project whose relative path contains `query`
+ * (case-insensitive). Returns an empty array when the project has no
+ * files, when the query is empty, or when the project path is unreadable.
+ */
+export async function handleSearchProjectFiles(store, projectId, query) {
+    const project = store.getProject(projectId);
+    if (!project) {
+        throw new NotFoundError("Project not found");
+    }
+    const projectPath = project.path;
+    const trimmedQuery = query.trim();
+    if (!trimmedQuery) {
+        return [];
+    }
+    const ignorePatterns = [...ALWAYS_IGNORE];
+    // Read root .gitignore when present. Nested .gitignores are ignored for
+    // now — this keeps the search fast and the implementation small; the
+    // hard-coded ALWAYS_IGNORE already catches the largest generated dirs.
+    try {
+        const gitignore = readFileSync(join(projectPath, ".gitignore"), "utf8");
+        const patterns = gitignore
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line && !line.startsWith("#"));
+        ignorePatterns.push(...patterns);
+    }
+    catch {
+        // .gitignore missing or unreadable — proceed without it.
+    }
+    const lowerQuery = trimmedQuery.toLowerCase();
+    let matches;
+    try {
+        matches = await glob("**/*", {
+            cwd: projectPath,
+            nodir: true,
+            dot: false,
+            ignore: ignorePatterns,
+        });
+    }
+    catch {
+        // Project path unreadable or not a directory — return empty rather
+        // than crashing the composer dropdown.
+        return [];
+    }
+    const filtered = matches
+        .filter((relativePath) => relativePath.toLowerCase().includes(lowerQuery))
+        .slice(0, MAX_RESULTS);
+    return filtered.map((relativePath) => ({
+        path: join(projectPath, relativePath),
+        relativePath,
+        name: relativePath.split("/").pop() ?? relativePath,
+    }));
+}

package/dist/server/inter-agent-broker.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Inter-agent communication broker for `spectral serve`.
+ *
+ * Provides project-scoped, channel-based messaging between active agent
+ * sessions running in the same spectral process on the same machine. Messages
+ * are durably backed by SQLite so they survive reconnects and can be polled by
+ * sessions that were not attached when the message was sent.
+ *
+ * The broker is intentionally process-local: subscriptions are in-memory
+ * inside the `spectral serve` daemon. Cross-process delivery on the same
+ * machine happens through the shared SQLite backing when each process creates
+ * its own broker instance pointing at the same `sessions.db`.
+ */
+import type { SessionStore } from "./storage.js";
+export interface InterAgentMessage {
+    /** Unique message id (UUID). */
+    id: string;
+    /** Owning project. */
+    projectId: string;
+    /** Logical channel within the project (e.g. "memory", "task-handoff"). */
+    channel: string;
+    /** Session that sent the message. */
+    senderSessionId: string;
+    /** Optional human-readable sender name. */
+    senderName?: string;
+    /** When set, the message is a private direct message; otherwise broadcast. */
+    recipientSessionId?: string;
+    /** Message kind used to route interpretation (e.g. "observation"). */
+    kind: string;
+    /** Opaque JSON payload. */
+    payload: string;
+    /** Timestamp (ms since epoch) when the message was created. */
+    createdAt: number;
+    /** Timestamp (ms) when the recipient first polled it, if ever. */
+    deliveredAt?: number;
+    /** Timestamp (ms) after which the message may be garbage collected. */
+    expiresAt?: number;
+}
+export interface InterAgentSendInput {
+    projectId: string;
+    channel: string;
+    senderSessionId: string;
+    senderName?: string;
+    /** Omit for broadcast. */
+    recipientSessionId?: string;
+    kind: string;
+    payload: string;
+    /** Default: 24 hours. Set to 0 to disable expiry. */
+    ttlSeconds?: number;
+}
+export interface InterAgentPollInput {
+    projectId: string;
+    /** Filter by channel. Omit to poll all channels in the project. */
+    channel?: string;
+    /** Poll only messages addressed to this session (or broadcast). Omit to poll all. */
+    recipientSessionId?: string;
+    /** Only return messages created after this timestamp (exclusive). */
+    since?: number;
+    /** Maximum messages to return. Default 100. */
+    limit?: number;
+    /** Mark returned messages as delivered. Default true. */
+    markDelivered?: boolean;
+}
+export interface InterAgentSubscribeInput {
+    sessionId: string;
+    projectId: string;
+    channel?: string;
+    handler: (msg: InterAgentMessage) => void;
+}
+export interface InterAgentBrokerOptions {
+    store: SessionStore;
+    /** Default TTL in seconds for messages that don't specify one. Default 86400. */
+    defaultTtlSeconds?: number;
+}
+/**
+ * In-process broker for inter-session messages.
+ *
+ * All public methods are synchronous because the underlying `SessionStore`
+ * uses better-sqlite3. Live subscribers are called synchronously from `send`.
+ */
+export declare class InterAgentBroker {
+    private readonly store;
+    private readonly defaultTtlSeconds;
+    /**
+     * In-process subscriptions keyed by `projectId:channel`. Each active session
+     * in the current process registers a handler here to receive live pushes.
+     */
+    private readonly subscriptions;
+    constructor(opts: InterAgentBrokerOptions);
+    /**
+     * Send a message. Persists it to SQLite and synchronously pushes it to any
+     * in-process subscribers whose session/channel filters match.
+     */
+    send(input: InterAgentSendInput): InterAgentMessage;
+    /**
+     * Poll for messages matching the filter. By default marks returned messages
+     * as delivered so they won't be returned again on subsequent polls.
+     */
+    poll(input: InterAgentPollInput): InterAgentMessage[];
+    /**
+     * Subscribe a session to live pushes for a project/channel. Returns an
+     * unsubscribe function. Subscriptions are in-process only.
+     */
+    subscribe(input: InterAgentSubscribeInput): () => void;
+    /**
+     * Delete expired messages from the backing store. Call periodically.
+     */
+    cleanup(maxAgeSeconds?: number): void;
+    private pushToSubscribers;
+}
+//# sourceMappingURL=inter-agent-broker.d.ts.map

package/dist/server/inter-agent-broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inter-agent-broker.d.ts","sourceRoot":"","sources":["../../src/server/inter-agent-broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,YAAY,CAAC;IACpB,iFAAiF;IACjF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAE3C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4D;gBAE9E,IAAI,EAAE,uBAAuB;IAKzC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,iBAAiB;IAyBnD;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,iBAAiB,EAAE;IAWrD;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,IAAI;IA4BtD;;OAEG;IACH,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAQrC,OAAO,CAAC,iBAAiB;CAqB1B"}