@aexol/spectral 0.8.2 → 0.8.5

package/dist/sdk/coding-agent/utils/mime.d.ts

@@ -0,0 +1,3 @@
+export declare function detectSupportedImageMimeType(buffer: Uint8Array): string | null;
+export declare function detectSupportedImageMimeTypeFromFile(filePath: string): Promise<string | null>;
+//# sourceMappingURL=mime.d.ts.map

package/dist/sdk/coding-agent/utils/mime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/mime.ts"],"names":[],"mappings":"AAKA,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAc9E;AAED,wBAAsB,oCAAoC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASnG"}

package/dist/sdk/coding-agent/utils/paths.d.ts

@@ -0,0 +1,31 @@
+export interface PathInputOptions {
+    /** Trim leading/trailing whitespace before normalization. */
+    trim?: boolean;
+    /** Expand leading `~` to a home directory. Defaults to true. */
+    expandTilde?: boolean;
+    /** Home directory used for `~` expansion. Defaults to `os.homedir()`. */
+    homeDir?: string;
+    /** Strip a leading `@`, used for CLI @file paths. */
+    stripAtPrefix?: boolean;
+    /** Normalize unicode space variants to regular spaces. */
+    normalizeUnicodeSpaces?: boolean;
+}
+/**
+ * Resolve a path to its canonical (real) form, following symlinks.
+ * Falls back to the raw path if resolution fails (e.g. the target does
+ * not exist yet), so that callers never crash on missing filesystem
+ * entries.
+ */
+export declare function canonicalizePath(path: string): string;
+/**
+ * Returns true if the value is NOT a package source (npm:, git:, etc.)
+ * or a remote URL protocol. Bare names, relative paths, and file: URLs
+ * are considered local.
+ */
+export declare function isLocalPath(value: string): boolean;
+export declare function normalizePath(input: string, options?: PathInputOptions): string;
+export declare function resolvePath(input: string, baseDir?: string, options?: PathInputOptions): string;
+export declare function getCwdRelativePath(filePath: string, cwd: string): string | undefined;
+export declare function formatPathRelativeToCwdOrAbsolute(filePath: string, cwd: string): string;
+export declare function markPathIgnoredByCloudSync(path: string): void;
+//# sourceMappingURL=paths.d.ts.map

package/dist/sdk/coding-agent/utils/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/paths.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,gBAAgB;IAChC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gEAAgE;IAChE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,0DAA0D;IAC1D,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAclD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAsBnF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,MAAsB,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAIlH;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASpF;AAED,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGvF;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAe7D"}

package/dist/sdk/coding-agent/utils/photon.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Photon image processing wrapper.
+ *
+ * This module provides a unified interface to @silvia-odwyer/photon-node for
+ * use in Node.js (development, npm run build).
+ */
+export type { PhotonImage as PhotonImageType } from "@silvia-odwyer/photon-node";
+/**
+ * Load the photon module asynchronously.
+ * Returns cached module on subsequent calls.
+ */
+export declare function loadPhoton(): Promise<typeof import("@silvia-odwyer/photon-node") | null>;
+//# sourceMappingURL=photon.d.ts.map

package/dist/sdk/coding-agent/utils/photon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"photon.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/photon.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,YAAY,EAAE,WAAW,IAAI,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAuFjF;;;GAGG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,cAAc,4BAA4B,CAAC,GAAG,IAAI,CAAC,CAuB9F"}

package/dist/sdk/coding-agent/utils/pi-user-agent.d.ts

@@ -0,0 +1,2 @@
+export declare function getPiUserAgent(version: string): string;
+//# sourceMappingURL=pi-user-agent.d.ts.map

package/dist/sdk/coding-agent/utils/pi-user-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-user-agent.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/pi-user-agent.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/sdk/coding-agent/utils/shell.d.ts

@@ -0,0 +1,30 @@
+export interface ShellConfig {
+    shell: string;
+    args: string[];
+}
+/**
+ * Resolve shell configuration based on platform and an optional explicit shell path.
+ * Resolution order:
+ * 1. User-specified shellPath
+ * 2. On Windows: Git Bash in known locations, then bash on PATH
+ * 3. On Unix: /bin/bash, then bash on PATH, then fallback to sh
+ */
+export declare function getShellConfig(customShellPath?: string): ShellConfig;
+export declare function getShellEnv(): NodeJS.ProcessEnv;
+/**
+ * Sanitize binary output for display/storage.
+ * Removes characters that crash string-width or cause display issues:
+ * - Control characters (except tab, newline, carriage return)
+ * - Lone surrogates
+ * - Unicode Format characters (crash string-width due to a bug)
+ * - Characters with undefined code points
+ */
+export declare function sanitizeBinaryOutput(str: string): string;
+export declare function trackDetachedChildPid(pid: number): void;
+export declare function untrackDetachedChildPid(pid: number): void;
+export declare function killTrackedDetachedChildren(): void;
+/**
+ * Kill a process and all its children (cross-platform)
+ */
+export declare function killProcessTree(pid: number): void;
+//# sourceMappingURL=shell.d.ts.map

package/dist/sdk/coding-agent/utils/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/shell.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;CACf;AAyCD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,WAAW,CAqDpE;AAED,wBAAgB,WAAW,IAAI,MAAM,CAAC,UAAU,CAY/C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA8BxD;AAQD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED,wBAAgB,2BAA2B,IAAI,IAAI,CAKlD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAyBjD"}

package/dist/sdk/coding-agent/utils/sleep.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Sleep helper that respects abort signal.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

package/dist/sdk/coding-agent/utils/sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/sleep.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAcrE"}

package/dist/sdk/coding-agent/utils/syntax-highlight.d.ts

@@ -0,0 +1,12 @@
+export type HighlightFormatter = (text: string) => string;
+export type HighlightTheme = Partial<Record<string, HighlightFormatter>>;
+export interface HighlightOptions {
+    language?: string;
+    ignoreIllegals?: boolean;
+    languageSubset?: string[];
+    theme?: HighlightTheme;
+}
+export declare function renderHighlightedHtml(html: string, theme?: HighlightTheme): string;
+export declare function highlight(code: string, options?: HighlightOptions): string;
+export declare function supportsLanguage(name: string): boolean;
+//# sourceMappingURL=syntax-highlight.d.ts.map

package/dist/sdk/coding-agent/utils/syntax-highlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-highlight.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/syntax-highlight.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAC1D,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,cAAc,CAAC;CACvB;AAoED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,cAAmB,GAAG,MAAM,CAoDtF;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAQ9E;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD"}

package/dist/sdk/coding-agent/utils/tools-manager.d.ts

@@ -0,0 +1,3 @@
+export declare function getToolPath(tool: "fd" | "rg"): string | null;
+export declare function ensureTool(tool: "fd" | "rg", silent?: boolean): Promise<string | undefined>;
+//# sourceMappingURL=tools-manager.d.ts.map

package/dist/sdk/coding-agent/utils/tools-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-manager.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/tools-manager.ts"],"names":[],"mappings":"AAoFA,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAmB5D;AA8ND,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,GAAE,OAAe,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA2CxG"}

package/dist/sdk/coding-agent/utils/version-check.d.ts

@@ -0,0 +1,15 @@
+export interface LatestPiRelease {
+    version: string;
+    packageName?: string;
+    note?: string;
+}
+export declare function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined;
+export declare function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean;
+export declare function getLatestPiRelease(currentVersion: string, options?: {
+    timeoutMs?: number;
+}): Promise<LatestPiRelease | undefined>;
+export declare function getLatestPiVersion(currentVersion: string, options?: {
+    timeoutMs?: number;
+}): Promise<string | undefined>;
+export declare function checkForNewPiVersion(currentVersion: string): Promise<LatestPiRelease | undefined>;
+//# sourceMappingURL=version-check.d.ts.map

package/dist/sdk/coding-agent/utils/version-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/version-check.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAsBD,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcpG;AAED,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAM/F;AAED,wBAAsB,kBAAkB,CACvC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CA4BtC;AAED,wBAAsB,kBAAkB,CACvC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE7B;AAED,wBAAsB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAUvG"}

package/dist/sdk/coding-agent/utils/windows-self-update.d.ts

@@ -0,0 +1,3 @@
+export declare function cleanupWindowsSelfUpdateQuarantine(packageDir: string): void;
+export declare function quarantineWindowsNativeDependencies(packageDir: string): void;
+//# sourceMappingURL=windows-self-update.d.ts.map

package/dist/sdk/coding-agent/utils/windows-self-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-self-update.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/windows-self-update.ts"],"names":[],"mappings":"AAiDA,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAU3E;AAED,wBAAgB,mCAAmC,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAsB5E"}

package/dist/server/agent-bridge.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Per-connection pi SDK lifecycle.
+ *
+ * One `AgentBridge` instance per active WebSocket connection. Wraps:
+ *  - `createAgentSession` (in-memory session manager — we own persistence in
+ *    SQLite; pi doesn't need to write its own JSONL files).
+ *  - `subscribe` listener that translates pi `AgentSessionEvent`s into our
+ *    own `ServerEvent` wire format and pushes them through a caller-supplied
+ *    sink.
+ *  - `prompt(text)` to send user input.
+ *  - `dispose()` for clean teardown on WS close.
+ *
+ * Event mapping (pi → wire):
+ *  - `message_start` (assistant)        → emit our own `message_start` with a
+ *    fresh UUID `messageId`. Pi's AssistantMessage has no stable id field, so
+ *    we mint one per turn and use it for all subsequent deltas/tool events
+ *    until `message_end`.
+ *  - `message_update` w/ inner text_delta / thinking_delta → wire `text_delta`
+ *    or `thinking_delta` carrying the `delta` and our `messageId`.
+ *  - `tool_execution_start`             → wire `tool_call`.
+ *  - `tool_execution_end`               → wire `tool_result`.
+ *  - `message_end` (assistant)          → wire `message_end` and persist the
+ *    final assembled text + JSONL of every WIRE event we emitted for this
+ *    message into SQLite. Content is taken from the final
+ *    `AssistantMessage.content` (concatenating `text` blocks); we fall back
+ *    to the `text_delta` accumulator when the provider didn't populate
+ *    final blocks (e.g. deepseek via openai-compatible).
+ *  - `agent_end`                        → wire `agent_end`.
+ *
+ * Persistence shape:
+ *  `events_jsonl` is the newline-delimited JSON of the wire-format
+ *  `ServerEvent`s we emitted for this message — NOT raw pi
+ *  `AgentSessionEvent`s. This guarantees the client's `parseWireEvents`
+ *  reducer can rehydrate the turn after a refresh using the exact same
+ *  reducer it uses for the live broadcast.
+ *
+ * Errors thrown synchronously from `session.prompt()` (e.g. no model
+ * configured) are caught by the caller in `routes.ts` and re-emitted as
+ * `{type:"error"}`.
+ *
+ * History rehydration:
+ *  On first attach to a previously-created session (e.g. after a server
+ *  restart), the SessionStreamManager passes the full SQLite transcript
+ *  to the AgentBridge via `AgentBridgeOptions.history`. Before
+ *  `createAgentSession` is called, each message is appended to the
+ *  in-memory SessionManager so the LLM sees the full conversation
+ *  context from the very first prompt. Multi-turn conversations within
+ *  a single pi session also work normally (the same AgentSession
+ *  instance is reused across `prompt()` calls).
+ */
+import { type AgentSessionEvent } from "../sdk/coding-agent/index.js";
+import { fetchAllowedModels as defaultFetchAllowedModels } from "../relay/models-fetch.js";
+import type { SessionMemorySnapshot } from "./storage.js";
+import type { ImageAttachment, ServerEvent, WireMessage } from "./wire.js";
+/** Optional override for fetchAllowedModels (tests inject a mock). */
+export type FetchAllowedModelsFn = typeof defaultFetchAllowedModels;
+export interface AgentBridgeOptions {
+    /** Working directory pi will operate in (used by built-in tools). */
+    cwd: string;
+    /** Pi config / agent dir. Defaults to ~/.spectral/agent (pi default). */
+    agentDir?: string;
+    /**
+     * Backend base URL (no trailing slash). All inference is proxied through
+     * `${backendUrl}/v1` — pi NEVER reads `~/.spectral/agent/auth.json` and NEVER
+     * holds raw provider API keys; the backend authenticates the machine via
+     * `machineJwt` and uses its own centralized provider credentials.
+     */
+    backendUrl: string;
+    /**
+     * Bearer token used to authenticate with the backend's `/v1/*` endpoints
+     * AND with the GraphQL `availableBaseModels` query. Issued by
+     * `ensureMachineRegistered` and persisted in `machine.json`.
+     */
+    machineJwt: string;
+    /** Sink for outbound wire events. Synchronous; the bridge does not buffer. */
+    emit: (event: ServerEvent) => void;
+    /**
+     * Called when an assistant message completes, after `message_end` is
+     * emitted. The bridge passes the accumulated text content and the JSONL
+     * of every pi event captured for this message. Caller is expected to
+     * persist this to SQLite.
+     */
+    onAssistantMessageComplete: (msg: {
+        messageId: string;
+        content: string;
+        eventsJsonl: string;
+    }) => void;
+    /**
+     * Called when the bridge decides to skip persisting an empty intermediate
+     * message. Caller should clean up any stub row inserted at message_start.
+     */
+    onAssistantMessageSkipped?: (messageId: string) => void;
+    /**
+     * Called when pi or an extension throws asynchronously (e.g. from
+     * `prompt`). Caller can choose how to surface to the client. The bridge
+     * also emits `{type:"error"}` on the wire as a fallback.
+     */
+    onError?: (err: Error) => void;
+    /**
+     * Optional session history to rehydrate into pi's in-memory session
+     * before the first prompt. Populated from SQLite by the session-stream
+     * manager when attaching to a previously-created session (so the LLM
+     * sees the full conversation transcript from the beginning). Omitted for
+     * brand-new sessions (no history) and for tests that don't need it.
+     */
+    history?: WireMessage[];
+    /**
+     * Optional persisted observational-memory snapshot restored after message
+     * history rehydration so the next prompt still sees compacted memory after
+     * reconnect/server restart.
+     */
+    memorySnapshot?: SessionMemorySnapshot | null;
+    /**
+     * Test seam — override the model whitelist fetch. Production code never
+     * sets this; tests inject a stub returning a synthetic list so `start()`
+     * can run without a live backend.
+     */
+    fetchAllowedModels?: FetchAllowedModelsFn;
+}
+export declare class AgentBridge {
+    private session?;
+    private sessionManager?;
+    private unsubscribe?;
+    private pending?;
+    private disposed;
+    private readonly opts;
+    /**
+     * Pi's model registry. Built lazily in `start()` so we can resolve a
+     * `modelId` (envelope-supplied or SQLite-persisted) to a concrete `Model`
+     * via `registry.getAll().find(m => m.id === modelId)` before invoking
+     * `session.setModel()`. Phase 3 (Available Models whitelist).
+     */
+    private modelRegistry?;
+    /**
+     * Raw allowed models list from the backend, preserved in sortOrder.
+     * Used by `getFirstAvailableModelId()` to return the backend-curated
+     * top pick when no explicit model selection is made.
+     */
+    private allowedModels?;
+    /**
+     * Last `modelId` we successfully applied via `session.setModel()`, or
+     * `undefined` if we never applied one (pi falls back to its own settings
+     * file in that case, matching pre-Phase-3 behaviour). Tracked so repeated
+     * envelopes carrying the same modelId don't churn pi's internal state.
+     */
+    private lastAppliedModelId?;
+    /** Current model's credit rates (from availableBaseModels), used for token_usage. */
+    private activeCreditRates;
+    private readonly memoryRuntime;
+    private memoryPhase;
+    constructor(opts: AgentBridgeOptions);
+    /**
+     * Create the pi session, wire up subscription, and return.
+     * Throws on creation failure (caller should surface to client).
+     */
+    start(): Promise<void>;
+    private proxyProviderForAllowedModel;
+    private refreshAllowedModels;
+    /**
+     * Register one synthetic provider per upstream API shape. Anthropic models
+     * go to `${backendUrl}/v1/messages` (Messages API); everything else (OpenAI,
+     * Google, Cerebras, etc.) goes to `${backendUrl}/v1/chat/completions`
+     * (OpenAI-compatible API). The backend supports both endpoints natively
+     * (verified in F1).
+     *
+     * Pi will send `Authorization: Bearer ${apiKey}` (because `authHeader: true`)
+     * which carries the machine JWT — the only credential the backend trusts.
+     *
+     * The `id` we register is the raw `modelId` (e.g. `claude-3-5-haiku-latest`),
+     * which is exactly what the backend expects in `body.model`.
+     */
+    private registerSyntheticProviders;
+    /**
+     * Apply a sticky model selection to the underlying pi session, if it
+     * differs from what was last applied. No-ops when:
+     *  - `modelId` is null/undefined (caller passed nothing to apply)
+     *  - the same modelId was already applied to this session
+     *  - the registry can't resolve the modelId (emits an `error` wire event
+     *    so the client surfaces the failure, but does NOT throw — the caller
+     *    is expected to drop the prompt)
+     *
+     * Returns true when the requested model is now in effect (either because
+     * we just applied it or because it was already applied). Returns false
+     * on resolution failure so the caller can skip `prompt()` and avoid
+     * driving pi against the wrong model.
+     *
+     * Phase 3 (Available Models whitelist).
+     */
+    /**
+     * Return the modelId of the first available model from the backend
+     * whitelist (preserving the backend's sortOrder, which is the same
+     * ordering the frontend uses in its model picker). Returns `undefined`
+     * when no models are available (e.g. backend unreachable at startup).
+     *
+     * Used by `SessionStreamManager.prompt()` as a defense-in-depth
+     * default when neither the envelope nor SQLite supply a modelId.
+     */
+    getFirstAvailableModelId(): string | undefined;
+    /**
+     * Return current session context usage from pi's built-in estimator.
+     * Used after compaction and session start to push updated context-window
+     * stats to the frontend without waiting for the next assistant turn.
+     */
+    getContextUsage(): {
+        tokens: number | null;
+        contextWindow: number;
+        percent: number | null;
+    } | undefined;
+    getSessionBranch(): Array<{
+        type: string;
+        id: string;
+        timestamp?: string;
+        message?: unknown;
+        content?: unknown;
+        customType?: string;
+        summary?: unknown;
+        fromId?: string;
+        data?: unknown;
+        details?: unknown;
+        firstKeptEntryId?: string;
+    }>;
+    getMemoryActivity(): {
+        phase: "idle" | "observing" | "compacting" | "reflecting" | "pruning";
+        inFlight: {
+            observer: boolean;
+            compaction: boolean;
+            reflection: boolean;
+            pruner: boolean;
+        };
+    };
+    private updateMemoryPhase;
+    setModel(modelId: string | null | undefined): Promise<boolean>;
+    /**
+     * Map a frontend reasoning-effort string to pi's ThinkingLevel.
+     * Frontend sends: xhigh | high | medium | low | minimal | none | undefined
+     * Pi expects:   "high" | "medium" | "low" | "minimal" | "off"
+     *
+     * Mapping:
+     *   xhigh   → high    (pi doesn't have xhigh, default to max)
+     *   high    → high
+     *   medium  → medium
+     *   low     → low
+     *   minimal → minimal
+     *   none    → off
+     *   undefined → no-op (pi keeps whatever it has currently)
+     */
+    private mapReasoningEffortToThinkingLevel;
+    /**
+     * Set the reasoning/thinking effort level for the next prompt.
+     * Pass `undefined` to leave pi's current level unchanged.
+     *
+     * The caller (SessionStreamManager) is responsible for persisting the
+     * value to SQLite; this method only applies it to pi's in-memory session.
+     */
+    setReasoningEffort(effort: string | undefined): void;
+    /**
+     * Forward a user message to pi. Resolves when the full turn ends.
+     * The caller is responsible for persisting the user message to SQLite
+     * BEFORE invoking this — we don't do it here because pi's `prompt` may
+     * fail and we still want the user message recorded.
+     *
+     * When `images` is non-empty, each base64-encoded attachment is converted
+     * to a pi `ImageContent` block and passed as `options.images` to
+     * `session.prompt()`. If the current model does not support image inputs,
+     * images are instead converted to text placeholders so the conversation
+     * can continue without errors.
+     */
+    prompt(text: string, images?: ImageAttachment[]): Promise<void>;
+    /**
+     * Manually compact the session context via pi's built-in compaction.
+     * Pi generates a summary of older conversation history, preserving the
+     * most recent ~20K tokens verbatim. Compaction events are forwarded to
+     * the wire through `handleEvent()`.
+     *
+     * `customInstructions` can inject guidance into the compaction prompt
+     * so the summary captures information relevant to the current task.
+     */
+    compact(customInstructions?: string): Promise<void>;
+    dispose(): void;
+    /**
+     * Emit a wire event AND record it in the pending message's audit log so
+     * the persisted JSONL exactly matches the live broadcast. Use this in
+     * place of `this.opts.emit` for any event that should appear in
+     * `events_jsonl` for the current assistant message.
+     */
+    private emitAndBuffer;
+    /**
+     * Finalize the current `pending` assistant message: persist its assembled
+     * content + wire events (including any tool_call / tool_result events that
+     * arrived after `message_end`) to SQLite via `onAssistantMessageComplete`.
+     *
+     * Idempotent: marks the pending as `finalized` on first call; subsequent
+     * calls are no-ops (guards against double-persisting when both
+     * `message_start` and `agent_end` would otherwise finalize the same pending).
+     *
+     * Skips empty framing-only messages (messages with no text, thinking, or
+     * tool events that contribute nothing the client can render).
+     */
+    private finalizePendingMessage;
+    /**
+     * Subscriber callback. Public so tests can drive event flow without
+     * spinning up a real pi session — production code never calls this
+     * directly; pi's `subscribe()` does, via the closure registered in
+     * `start()`.
+     */
+    handleEvent(ev: AgentSessionEvent): void;
+}
+//# sourceMappingURL=agent-bridge.d.ts.map

package/dist/server/agent-bridge.d.ts.map

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

package/dist/server/handlers/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Typed errors thrown by REST handlers.
+ *
+ * Each error carries a stable `code` that the relay envelope dispatcher
+ * (Batch 3) maps to a wire-level status. Until then, the handlers throw
+ * and the relay loop just acks — Batch 3 will catch and translate.
+ *
+ * Why typed errors instead of returning `{ ok: false, code }` discriminated
+ * unions? Two reasons:
+ *  - The handlers are also called directly from unit tests; `throw` lets
+ *    tests use `expect(...).rejects.toThrow(NotFoundError)` ergonomically.
+ *  - The Batch 3 dispatcher needs a single `try/catch` boundary; a sum
+ *    type per handler would force every handler to return its own variant.
+ */
+export type HandlerErrorCode = "BAD_REQUEST" | "NOT_FOUND";
+export declare class HandlerError extends Error {
+    readonly code: HandlerErrorCode;
+    constructor(code: HandlerErrorCode, message: string);
+}
+export declare class BadRequestError extends HandlerError {
+    constructor(message: string);
+}
+export declare class NotFoundError extends HandlerError {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/server/handlers/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,WAAW,CAAC;AAE3D,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;gBACpB,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM;CAKpD;AAED,qBAAa,eAAgB,SAAQ,YAAY;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,aAAc,SAAQ,YAAY;gBACjC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/server/handlers/paths-autocomplete.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Filesystem autocomplete for project path creation.
+ *
+ * When a user types a partial path in the New Project form, the browser
+ * sends `GET /api/paths/autocomplete?prefix=<partial>`. This handler
+ * expands the prefix (tilde → $HOME, relative → absolute), lists the
+ * containing directory, and returns up to 10 directory suggestions whose
+ * basenames start with the typed partial segment.
+ *
+ * Two strategies:
+ *   1. If the expanded prefix exists on disk as a directory — show its
+ *      immediate children (trailing separator is implicit). This is the
+ *      natural behaviour when the user has already typed a real directory
+ *      and wants to drill deeper.
+ *   2. Otherwise — split into parent + basename prefix and do a
+ *      starts-with match so the user can filter siblings while typing.
+ *
+ * Dotfiles are excluded — they are rarely intentional project roots.
+ * Symlinks to directories ARE included (readdirSync with withFileTypes
+ * returns true for both real dirs and symlink dirs).
+ *
+ * Thread-safety: synchronous, called from the relay-dispatcher hot path.
+ * fs ops block the event loop for microseconds on local SSDs; the form
+ * is typed by a single human, so this is perfectly fine.
+ */
+export interface PathAutocompleteResult {
+    suggestions: string[];
+    expandedPrefix: string;
+}
+/**
+ * List directory suggestions for the given path prefix.
+ *
+ * Examples (assume $HOME=/Users/alice, dirs are `projects`, `proj-old`,
+ * `Documents`, `.config`):
+ *   prefix="~"         → expanded="/Users/alice" (exists as dir)
+ *                        → children of /Users/alice/  ["projects","proj-old","Documents"]
+ *   prefix="~/pro"     → expanded="/Users/alice/pro" (does NOT exist)
+ *                        → starts-with "pro" in /Users/alice/  ["projects","proj-old"]
+ *   prefix="~/projects/" → expanded="/Users/alice/projects/" (exists as dir)
+ *                        → children of /Users/alice/projects/
+ *   prefix="~/projects/sr" → expanded="/Users/alice/projects/sr" (does NOT exist)
+ *                        → starts-with "sr" in /Users/alice/projects/
+ */
+export declare function handlePathAutocomplete(prefix: string): PathAutocompleteResult;
+//# sourceMappingURL=paths-autocomplete.d.ts.map

package/dist/server/handlers/paths-autocomplete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths-autocomplete.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/paths-autocomplete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAgCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,CA+B7E"}

package/dist/server/handlers/projects.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pure REST handlers for `/api/projects/*`.
+ *
+ * Extracted from the deleted Hono `routes.ts` so the relay envelope dispatcher
+ * (Batch 3) can call them with a parsed payload instead of a Hono context.
+ *
+ * Contract:
+ *  - Inputs are already-parsed JSON objects (or `unknown` shapes the handler
+ *    validates). The dispatcher upstream parses the relay envelope body.
+ *  - Outputs are the wire shapes the landing client already expects, so the
+ *    Batch 3 dispatcher can JSON-stringify them straight into the response
+ *    envelope without remapping.
+ *  - Errors are thrown as typed `HandlerError` subclasses; the dispatcher
+ *    maps `BAD_REQUEST` → 400-equivalent and `NOT_FOUND` → 404-equivalent.
+ *  - Stream teardown on project delete is the caller's responsibility — the
+ *    handler returns the cascaded session ids so the dispatcher can hand
+ *    them to `SessionStreamManager.disposeProjectStreams` BEFORE the SQL
+ *    cascade has already torn down (in our model the cascade has already
+ *    happened by the time we return; that's intentional and matches the
+ *    old route's ordering — the manager is best-effort cleanup).
+ */
+import type { SessionStore } from "../storage.js";
+import type { WireProject, WireSessionSummary } from "../wire.js";
+export interface CreateProjectInputRaw {
+    name?: unknown;
+    path?: unknown;
+}
+export interface UpdateProjectInputRaw {
+    name?: unknown;
+    path?: unknown;
+}
+export declare function handleListProjects(store: SessionStore): WireProject[];
+export declare function handleCreateProject(store: SessionStore, body: CreateProjectInputRaw): WireProject;
+export declare function handleGetProject(store: SessionStore, id: string): WireProject;
+export declare function handleUpdateProject(store: SessionStore, id: string, body: UpdateProjectInputRaw): WireProject;
+export interface DeleteProjectResult {
+    /** Session ids that belonged to the project (cascade-deleted). */
+    sessionIds: string[];
+}
+export declare function handleDeleteProject(store: SessionStore, id: string): DeleteProjectResult;
+export interface BindStudioInputRaw {
+    studioProjectId?: unknown;
+    studioTeamId?: unknown;
+    studioProjectName?: unknown;
+}
+export interface BindStudioResult {
+    project: WireProject;
+    studioProjectId: string;
+    studioProjectName: string;
+    studioTeamId?: string;
+}
+/**
+ * Bind a local project directory to an Aexol Studio project by writing
+ * `.aexol/aexol.jsonc` into the project's filesystem path.
+ */
+export declare function handleBindStudioProject(store: SessionStore, id: string, body: BindStudioInputRaw): Promise<BindStudioResult>;
+export declare function handleListSessionsByProject(store: SessionStore, id: string): WireSessionSummary[];
+//# sourceMappingURL=projects.d.ts.map

package/dist/server/handlers/projects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/projects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIlE,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,EAAE,CAErE;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,qBAAqB,GAC1B,WAAW,CAYb;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,CAI7E;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,qBAAqB,GAC1B,WAAW,CAwBb;AAED,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,GACT,mBAAmB,CAMrB;AAED,MAAM,WAAW,kBAAkB;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,WAAW,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAoC3B;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,GACT,kBAAkB,EAAE,CAItB"}