@cortexkit/aft-bridge 0.42.0 → 0.43.1

package/dist/subc-transport.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Subconscious (subc) transport — the daemon-backed alternative to the standalone
+ * NDJSON {@link BinaryBridge}. Implements the SAME {@link AftProjectTransport} /
+ * {@link AftTransportPool} interfaces the plugins consume, so the entire tool /
+ * hoisting / permission / UI surface stays transport-agnostic: only the ONE
+ * construction site (BridgePool vs SubcTransportPool) differs.
+ *
+ * Standalone model: one `aft` child process per project root, session passed
+ * per call. Subc model: ONE {@link SubcClient} per process (one authenticated
+ * daemon connection), and a route opened+cached per `(project_root, harness,
+ * session)` triple — exactly subc's {@link BindIdentity}. So the "pool" here is a
+ * route cache over a single client, not N child processes.
+ *
+ * This module is S2 of B-FINAL: the tool-call route only. The bg_events idle-wake
+ * subscription (S3) and the config gate that selects this transport (S4) build on
+ * top of it. subc-client is a build-time path dependency bundled into the
+ * published plugin dist; it is never a published runtime dependency.
+ */
+import { type BindIdentity, type RequestOptions, type RouteTarget } from "@cortexkit/subc-client";
+import type { StatusSnapshot } from "./bridge.js";
+import { type StatusBarCounts } from "./status-bar.js";
+import type { AftProjectTransport, AftTransportOptions, AftTransportPool, ToolCallArguments, ToolCallOptions, ToolCallResult } from "./transport.js";
+/** A held-open event subscription — the slice of subc-client's Subscription we use. */
+export interface SubcSubscriptionLike {
+    /** Cancel the subscription (sends Cancel; idempotent); the provider unwinds with StreamEnd. */
+    unsubscribe(): void;
+    /** Resolves on StreamEnd (intentional close); REJECTS on Error / route GOODBYE / socket drop. */
+    readonly closed: Promise<void>;
+}
+/**
+ * The minimal slice of {@link SubcClient} this transport depends on. Declared
+ * structurally so a test can inject a fake client through the pool's `connect`
+ * seam without standing up a daemon; the real `SubcClient` satisfies it.
+ */
+export interface SubcClientLike {
+    routeOpen(target: RouteTarget, identity: BindIdentity): Promise<number>;
+    request(routeChannel: number, body: unknown, opts?: RequestOptions): Promise<unknown>;
+    subscribe(routeChannel: number, body: unknown, onEvent: (event: Uint8Array) => void): SubcSubscriptionLike;
+    closeRouteChannel(channel: number, opts?: {
+        drain?: boolean;
+    }): Promise<void>;
+    close(): void;
+}
+export interface SubcTransportPoolOptions {
+    /** Absolute path to the subc connection file (user-tier `subc.connection_file`). */
+    connectionFile: string;
+    /** Harness identity carried in every BindIdentity ("opencode" | "pi" | …). */
+    harness: string;
+    /** Handshake timeout forwarded to SubcClient.connect. */
+    handshakeTimeoutMs?: number;
+    /**
+     * Connection factory seam. Defaults to the real `SubcClient.connect`. Tests
+     * inject a fake to exercise route caching / Rd reconnect without a daemon.
+     */
+    connect?: (opts: {
+        connectionFile: string;
+        handshakeTimeoutMs?: number;
+    }) => Promise<SubcClientLike>;
+    /**
+     * Called when an idle bg-completion WAKE arrives for `(projectRoot, session)`
+     * (a `{op:"bg_events"}` StreamData nudge), AND immediately after each
+     * (re)subscribe (the durable-outbox replay trigger). The nudge carries NO
+     * payload — the handler MUST force a DRAIN (bash_drain_completions) to fetch
+     * the actual completions. When set, the transport opens a dedicated bg_events
+     * subscription per session and drives its reconnect independently of tool
+     * calls (so an idle agent whose socket drops is still resubscribed + drained).
+     * Absent ⇒ no bg subscriptions are opened.
+     */
+    onBgEventsNudge?: (projectRoot: string, session: string) => void;
+    /** Test seam: backoff sleeper for the bg resubscribe loop (default real timer). */
+    bgBackoffSleep?: (ms: number) => Promise<void>;
+}
+/**
+ * One project root's view onto the shared subc client. Holds per-root status
+ * caches (mirroring BinaryBridge) and routes every call through the pool's single
+ * client, opening+caching a route per `(root, harness, session)`.
+ */
+declare class SubcTransport implements AftProjectTransport {
+    private readonly pool;
+    private readonly projectRoot;
+    private lastStatusBar;
+    private cachedStatus;
+    constructor(pool: SubcTransportPool, projectRoot: string);
+    getCwd(): string;
+    getStatusBar(): StatusBarCounts | undefined;
+    getCachedStatus(): StatusSnapshot | null;
+    cacheStatusSnapshot(snapshot: StatusSnapshot): void;
+    private captureStatusBar;
+    private identityFor;
+    toolCall(sessionId: string | undefined, name: string, rawArgs?: ToolCallArguments, options?: ToolCallOptions): Promise<ToolCallResult>;
+    /**
+     * Lifecycle / native-command path. Over subc there is no separate "native
+     * command" channel — every command rides the tool_provider route as a
+     * `{name, arguments}` Request and the module's gate decides validity (the 21
+     * core tools plus the `bash_drain_completions` / `bash_ack_completions` plumbing
+     * allowlist). The bind session is taken from `params.session_id` so a
+     * session-scoped command (drain/ack) reaches the matching route — the module
+     * re-injects the BIND session over any body session, so the route identity is
+     * what scopes it. `configure` is satisfied locally (binding is the configure).
+     */
+    send(command: string, params?: Record<string, unknown>, options?: AftTransportOptions): Promise<Record<string, unknown>>;
+    private splitOptions;
+}
+/**
+ * Route cache over one authenticated subc client. Implements {@link AftTransportPool}
+ * so it drops into the plugin in place of {@link BridgePool} behind the shared
+ * interface. One client per process; routes keyed by `(root, harness, session)`.
+ */
+export declare class SubcTransportPool implements AftTransportPool {
+    readonly harness: string;
+    private readonly connectionFile;
+    private readonly handshakeTimeoutMs?;
+    private readonly connectFn;
+    private readonly onBgEventsNudge?;
+    private readonly bgBackoffSleep;
+    private client;
+    /** Single-flight guard so concurrent first calls share one connect. */
+    private connecting;
+    /** Per-session lifecycle records keyed by a string built from root, harness, and session. */
+    private readonly sessions;
+    /**
+     * Consecutive NON-transient transport throws on the current client with no
+     * success in between. Resets to 0 on any successful request. Trips a client drop
+     * at {@link MAX_CONSECUTIVE_TRANSPORT_FAILURES} to recover a half-open socket
+     * whose timeouts never classify transient (B-#4).
+     */
+    private transportFailures;
+    /** Per-root transport facades returned by getBridge/getActiveBridgeForRoot. */
+    private readonly transports;
+    private shuttingDown;
+    constructor(options: SubcTransportPoolOptions);
+    /**
+     * Fail-loud presence check (memory: present-but-unconnectable must never silently
+     * downgrade to standalone). Returns false only when the file is genuinely absent.
+     */
+    static connectionAvailable(connectionFile: string): Promise<boolean>;
+    getBridge(projectRoot: string): SubcTransport;
+    getActiveBridgeForRoot(projectRoot: string): SubcTransport | null;
+    toolCall(projectRoot: string, runtime: {
+        sessionID?: string;
+    }, name: string, rawArgs?: ToolCallArguments, options?: ToolCallOptions): Promise<ToolCallResult>;
+    private getOrCreateSession;
+    private isCurrentSession;
+    private deleteSessionIfEmpty;
+    /**
+     * Open-or-reuse a route for `identity` and send `body` as a data-plane Request.
+     * Rd reconnect (mutation-safe by construction — NEVER auto-retries): on a
+     * transport-level {@link SubcCallError} the cached channel is discarded and the
+     * dead client cleared so the NEXT call re-establishes, but the failed call is
+     * surfaced to the agent unchanged (identical to a standalone bridge death). Only
+     * `SubcClient.request` transport failures throw here; a tool-level error comes
+     * back as a normal reply with `success:false` and is returned, not thrown.
+     */
+    routeRequest(identity: BindIdentity, body: Record<string, unknown>, timeoutMs?: number, onProgress?: RequestOptions["onProgress"]): Promise<unknown>;
+    private ensureClient;
+    /**
+     * Resolve the route channel for `identity`, returning BOTH the channel and the
+     * `RouteEntry` token that owns it. The route-entry token is the route-cache
+     * ownership guard: stale request failures can clear only the route they used,
+     * never a successor route in the same still-open session.
+     */
+    private routeChannel;
+    /**
+     * Open the dedicated bg_events subscription for `identity` once. Idempotent —
+     * a second call for the same identity is a no-op (one sub per session, the
+     * duplicate-sub guard from Oracle #2). No-op when no nudge handler is wired,
+     * during shutdown, or after the session has been closed.
+     */
+    private ensureBgSubscription;
+    /** Drop a dead client so the next call reconnects; preserves session records. */
+    private dropClient;
+    /** No-op over subc: config is read locally by AFT (wire tiers are ignored). */
+    setConfigureOverride(_key: string, _value: unknown): void;
+    /** No-op over subc: the daemon supervises the binary, not the plugin. */
+    replaceBinary(path: string): Promise<string>;
+    shutdown(): Promise<void>;
+    /**
+     * Tear down a single session's bg subscription (and tool route) — the
+     * per-session close hook (Oracle #5). Idempotent. Wired to OpenCode session-end
+     * / Pi equivalent in S4; until then, shutdown() covers teardown.
+     */
+    closeSession(projectRoot: string, session: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=subc-transport.d.ts.map

package/dist/subc-transport.d.ts.map

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