@cortexkit/aft-bridge 0.18.5

package/README.md

@@ -0,0 +1,33 @@
+# @cortexkit/aft-bridge
+
+Shared NDJSON transport, binary resolution, and ONNX runtime helpers used by AFT
+agent-host plugins (OpenCode, Pi, and future MCP-based hosts).
+
+This package is **not** intended for direct end-user consumption — it powers
+[`@cortexkit/aft-opencode`](https://www.npmjs.com/package/@cortexkit/aft-opencode)
+and [`@cortexkit/aft-pi`](https://www.npmjs.com/package/@cortexkit/aft-pi).
+
+## What it owns
+
+- **Transport** — `BinaryBridge` (one persistent `aft` child process), `BridgePool`
+  (one bridge per canonical project root), wire envelope and push-frame types.
+- **Binary resolution** — versioned cache, npm platform package lookup, PATH /
+  cargo fallback, GitHub release download with SHA-256 verification.
+- **ONNX runtime** — auto-download for supported targets, install detection and
+  version probing, manual-install hints for unsupported platforms.
+
+## What it does not own
+
+Host-specific behaviour stays in the plugin packages:
+
+- Configuration loading (each host has its own conventions and config paths).
+- Permission UX (`ctx.ask()` and prompt rendering belong to the host SDK).
+- Tool registration and rendering.
+- Notifications, slash commands, and TUI integration.
+- Session-ID lookup and per-request session injection.
+
+## Versioning
+
+Released in lock-step with `@cortexkit/aft-opencode` and `@cortexkit/aft-pi`.
+The bridge protocol is versioned end-to-end: a plugin running an older bridge
+package will detect a newer `aft` binary and refuse to talk to it.

package/dist/active-logger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Internal helper that lets shared modules call simple `log/warn/error`
+ * functions without threading a {@link Logger} through every signature.
+ *
+ * The host (OpenCode plugin, Pi plugin) calls {@link setActiveLogger} once at
+ * startup before constructing any {@link BridgePool}. Internal callers use
+ * {@link log}/{@link warn}/{@link error} which forward to the active logger.
+ *
+ * If no logger has been set, calls fall back to `console.error` so we never
+ * silently drop diagnostics.
+ */
+import type { Logger, LogMeta } from "./logger.js";
+export declare function setActiveLogger(logger: Logger): void;
+export declare function getActiveLogger(): Logger | undefined;
+export declare function getLogFilePath(): string | undefined;
+export declare function log(message: string, meta?: LogMeta): void;
+export declare function warn(message: string, meta?: LogMeta): void;
+export declare function error(message: string, meta?: LogMeta): void;
+export declare function sessionLog(sessionId: string | undefined, message: string): void;
+export declare function sessionWarn(sessionId: string | undefined, message: string): void;
+export declare function sessionError(sessionId: string | undefined, message: string): void;
+//# sourceMappingURL=active-logger.d.ts.map

package/dist/active-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-logger.d.ts","sourceRoot":"","sources":["../src/active-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAInD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED,wBAAgB,eAAe,IAAI,MAAM,GAAG,SAAS,CAEpD;AAED,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnD;AAED,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAMzD;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAM1D;AAED,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAM3D;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/E;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhF;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEjF"}

package/dist/bridge.d.ts

@@ -0,0 +1,146 @@
+import type { BgCompletion } from "./protocol.js";
+/**
+ * Compare two semver version strings (major.minor.patch plus pre-release).
+ * Returns: negative if a < b, 0 if equal, positive if a > b.
+ */
+export declare function compareSemver(a: string, b: string): number;
+/** Single configure-time warning produced by the Rust side. */
+export interface ConfigureWarning {
+    code?: string;
+    message: string;
+    [key: string]: unknown;
+}
+/** Context passed to {@link BridgeOptions.onConfigureWarnings} after the first successful configure. */
+export interface ConfigureWarningsContext {
+    projectRoot: string;
+    sessionId?: string | null;
+    client?: unknown;
+    warnings: ConfigureWarning[];
+}
+export interface BridgeOptions {
+    /** Request timeout in milliseconds. Default: 30000 */
+    timeoutMs?: number;
+    /** Maximum restart attempts before giving up. Default: 3 */
+    maxRestarts?: number;
+    /** Minimum binary version required (semver). If the binary is older, onVersionMismatch is called. */
+    minVersion?: string;
+    /** Called when binary version is older than minVersion. Receives (binaryVersion, minVersion). */
+    onVersionMismatch?: (binaryVersion: string, minVersion: string) => void;
+    /** Called after the first successful configure returns user-visible warnings. */
+    onConfigureWarnings?: (context: ConfigureWarningsContext) => void | Promise<void>;
+    /** Called for server-pushed background bash completions. */
+    onBashCompletion?: (completion: BashCompletedPayload, bridge: BinaryBridge) => void | Promise<void>;
+    /**
+     * Prefix for user-facing error messages thrown by the bridge (e.g. timeout,
+     * stdin-write, configure-failure errors). Hosts pass their own tag so the
+     * agent and operators see consistent attribution. Defaults to `[aft-bridge]`.
+     */
+    errorPrefix?: string;
+}
+export interface BashCompletedPayload extends BgCompletion {
+    type: "bash_completed";
+    session_id: string;
+}
+export interface BridgeRequestOptions {
+    onProgress?: (chunk: {
+        kind: "stdout" | "stderr";
+        text: string;
+    }) => void;
+    /** Per-call transport timeout in milliseconds. Defaults to the bridge-wide timeout. */
+    transportTimeoutMs?: number;
+    /**
+     * Skip the "kill the child process on timeout" behavior for this request.
+     *
+     * The default (false) treats a transport-level timeout as evidence the bridge
+     * is wedged — Rust normally responds well within the budget, so silence past
+     * the deadline almost always means a stuck child. Killing forces a clean
+     * respawn on the next call.
+     *
+     * Some commands enforce their own timeouts on the Rust side (notably `bash`,
+     * which uses a watchdog thread to terminate the child shell and return a
+     * timeout response). For those, a transport timeout means the response was
+     * lost or queued behind something else — the bridge itself is still healthy
+     * and should keep its warm state (LSP servers, semantic index, callers
+     * cache, undo history). Pass `keepBridgeOnTimeout: true` to reject the
+     * request without tearing down the bridge.
+     */
+    keepBridgeOnTimeout?: boolean;
+}
+interface SendOptions extends BridgeRequestOptions {
+    timeoutMs?: number;
+    configureWarningClient?: unknown;
+}
+/**
+ * Manages a persistent `aft` child process, communicating via NDJSON over
+ * stdin/stdout. Lazy-spawns on first `send()` call. Handles crash detection
+ * with exponential backoff auto-restart.
+ */
+export declare class BinaryBridge {
+    private static readonly RESTART_RESET_MS;
+    /** How many recent stderr lines to keep for crash diagnostics. */
+    private static readonly STDERR_TAIL_MAX;
+    private binaryPath;
+    private cwd;
+    private process;
+    private pending;
+    private nextId;
+    private stdoutBuffer;
+    /** Ring buffer of the last N stderr lines, cleared on every spawn. */
+    private stderrTail;
+    private _restartCount;
+    private _shuttingDown;
+    private timeoutMs;
+    private maxRestarts;
+    private configured;
+    private _configurePromise;
+    private configOverrides;
+    private minVersion;
+    private onVersionMismatch;
+    private onConfigureWarnings;
+    private onBashCompletion;
+    /** Notification clients keyed by session_id for async configure warning pushes. */
+    private configureWarningClients;
+    private restartResetTimer;
+    private errorPrefix;
+    constructor(binaryPath: string, cwd: string, options?: BridgeOptions, configOverrides?: Record<string, unknown>);
+    /** Number of times the binary has been restarted after a crash. */
+    get restartCount(): number;
+    /** Whether the child process is currently alive. */
+    isAlive(): boolean;
+    hasPendingRequests(): boolean;
+    /**
+     * Send a command to the binary and return the parsed response.
+     * Lazy-spawns the binary on first call.
+     */
+    send(command: string, params?: Record<string, unknown>, options?: SendOptions): Promise<Record<string, unknown>>;
+    private deliverConfigureWarnings;
+    /**
+     * Handle the `configure_warnings` push frame the Rust binary emits after
+     * configure has returned. The frame carries the warnings produced by the
+     * deferred file walk + missing-binary detection. Forwards to the same
+     * `onConfigureWarnings` handler used for synchronous warnings so plugins
+     * don't need to know about the async path.
+     */
+    private handleConfigureWarningsFrame;
+    /** Kill the child process and reject all pending requests. */
+    shutdown(): Promise<void>;
+    /** Query binary version and compare against minVersion. Calls onVersionMismatch if outdated. */
+    private checkVersion;
+    private ensureSpawned;
+    private spawnProcess;
+    private pushStderrLine;
+    /**
+     * Format the current stderr tail for inclusion in error messages. Returns
+     * empty string when nothing has been captured (e.g., silent SIGKILL from
+     * macOS amfid) so the caller can safely concatenate unconditionally.
+     */
+    private formatStderrTail;
+    private onStdoutData;
+    private handleTimeout;
+    private handleCrash;
+    private rejectAllPending;
+    private scheduleRestartCountReset;
+    private clearRestartResetTimer;
+}
+export {};
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

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

package/dist/downloader.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Auto-download the AFT binary from GitHub releases.
+ *
+ * Resolution order (in resolver.ts):
+ *   1. Cached binary in ~/.cache/aft/bin/
+ *   2. npm platform package (@cortexkit/aft-darwin-arm64, etc.)
+ *   3. PATH lookup (which aft)
+ *   4. ~/.cargo/bin/aft
+ *   5. Auto-download from GitHub releases (this module)
+ *
+ * Cache dir respects XDG_CACHE_HOME on Linux/macOS and LOCALAPPDATA on Windows.
+ */
+/** Get the cache directory, respecting XDG_CACHE_HOME / LOCALAPPDATA. */
+export declare function getCacheDir(): string;
+/** Binary name for the current platform. */
+export declare function getBinaryName(): string;
+/** Return the cached binary path if it exists, otherwise null.
+ *  Checks the version-specific cache directory only.
+ *  The legacy flat cache (~/.cache/aft/bin/aft) is intentionally NOT checked
+ *  because it can be overwritten by other instances, corrupting running processes. */
+export declare function getCachedBinaryPath(version?: string): string | null;
+/**
+ * Download the AFT binary for the current platform from GitHub releases.
+ *
+ * @param version - Git tag to download from (e.g. "v0.1.0"). If omitted,
+ *   fetches the latest release tag via the GitHub API.
+ * @returns Absolute path to the downloaded binary, or null on failure.
+ */
+export declare function downloadBinary(version?: string): Promise<string | null>;
+/**
+ * Ensure the AFT binary is available: check cache, then download if needed.
+ * This is the main entry point called by the resolver.
+ */
+export declare function ensureBinary(version?: string): Promise<string | null>;
+//# sourceMappingURL=downloader.d.ts.map

package/dist/downloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloader.d.ts","sourceRoot":"","sources":["../src/downloader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,yEAAyE;AACzE,wBAAgB,WAAW,IAAI,MAAM,CASpC;AAED,4CAA4C;AAC5C,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;sFAGsF;AACtF,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAInE;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgH7E;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgB3E"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @cortexkit/aft-bridge
+ *
+ * Shared transport, binary resolution, and ONNX runtime helpers for AFT
+ * agent-host plugins. Public surface intentionally narrow — host policies
+ * (config loading, permission UX, tool registration, notifications) stay in
+ * each host plugin.
+ */
+export { setActiveLogger } from "./active-logger.js";
+export type { BashCompletedPayload, BridgeOptions, BridgeRequestOptions, ConfigureWarning, ConfigureWarningsContext, } from "./bridge.js";
+export { BinaryBridge, compareSemver } from "./bridge.js";
+export { downloadBinary, ensureBinary, getBinaryName, getCacheDir, getCachedBinaryPath, } from "./downloader.js";
+export type { Logger, LogMeta } from "./logger.js";
+export { cleanupOnnxRuntime, ensureOnnxRuntime, getManualInstallHint, isOrtAutoDownloadSupported, } from "./onnx-runtime.js";
+export { PLATFORM_ARCH_MAP, PLATFORM_ASSET_MAP } from "./platform.js";
+export type { PoolOptions } from "./pool.js";
+export { BridgePool } from "./pool.js";
+export type { AftErrorResponse, AftPushFrame, AftRequestEnvelope, AftResponse, AftSuccessResponse, BashCompletedFrame, BgCompletion, ConfigureWarningFrame, PermissionAskFrame, ProgressFrame, } from "./protocol.js";
+export { findBinary, findBinarySync, platformKey } from "./resolver.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EACV,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EACL,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,EACX,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACtE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}