@wrenai/genbi 0.0.1

package/dist-server/server/native-sessions.d.ts

@@ -0,0 +1,374 @@
+import type { EnrichmentBinding } from "./enrichment.js";
+import { InteractiveTerminalManager } from "./interactive-terminal.js";
+import type { InteractiveLaunchSpec, InteractiveTarget, InteractiveTerminalSession } from "./interactive-terminal.js";
+import { type NativeSessionRow, type NativeSetupRecoveryCode, type NativeSetupRecoveryRow, type NativeSetupRecoveryState, type Store } from "./db.js";
+import { type NativeArtifactService, type NativeMcpDescriptor, type NativeMcpHealth } from "./native-artifacts.js";
+import { NATIVE_PURPOSES } from "./native-dispatch-registry.js";
+import type { NativePurpose, NativeRuntimeBinding, NativeVendor } from "./native-dispatch-registry.js";
+import type { NativeSessionStateBase } from "./native-session-workspace.js";
+import type { NativeWrenRuntime } from "./native-wren-runtime.js";
+export declare const NATIVE_VENDORS: readonly ["claude", "codex"];
+export { NATIVE_PURPOSES };
+export type { NativePurpose, NativeVendor };
+export declare const NATIVE_SETUP_RECOVERY_MCP_TOOL_NAME = "report_setup_recovery";
+/** Set only from the sealed, BFF-revalidated Setup bootstrap root at PTY launch. */
+export declare const NATIVE_SETUP_BOOTSTRAP_ROOT_ENV_VAR = "WARBLE_SETUP_BOOTSTRAP_ROOT";
+/** A browser must attach a newly-created PTY promptly or it is an orphan. */
+export declare const NATIVE_SESSION_INITIAL_ATTACHMENT_GRACE_MS = 15000;
+/**
+ * Ordinary navigation and idle browser detaches keep an already-authorized
+ * PTY reconnectable for this product TTL.  This is intentionally much longer
+ * than the never-attached orphan cleanup below: a Session is a live tool, not
+ * a 60-second page view.  It remains process-local; a BFF restart cannot
+ * recover this PTY without a separately sealed provider resume contract.
+ */
+export declare const NATIVE_SESSION_IDLE_TTL_MS: number;
+/** @deprecated Use `NATIVE_SESSION_IDLE_TTL_MS`. Retained for test/API compatibility. */
+export declare const NATIVE_SESSION_POST_CLAIM_DETACH_GRACE_MS: number;
+/**
+ * The producer deliberately sees only a sealed binding identity, never a caller-supplied path.
+ * After materialization, the BFF adds the canonical bound root to Codex's read-only permission
+ * profile so WREN_PROJECT_HOME can resolve through the exact server-owned binding.
+ */
+export declare function grantCodexBoundProjectRead(cwd: string, projectPath: string, dataRoots?: readonly string[]): void;
+interface CodexWrenHome {
+    readonly home: string;
+    readonly dataRoots: readonly string[];
+}
+export interface NativeSetupRecoveryReport {
+    readonly version: "1";
+    readonly sequence: number;
+    readonly phase: "connect" | "context";
+    readonly state: NativeSetupRecoveryState;
+    readonly code: NativeSetupRecoveryCode;
+    readonly decision?: {
+        readonly kind: "continue_or_stop";
+        readonly choices: readonly ["continue", "stop"];
+    };
+}
+export interface NativeSessionLaunch {
+    readonly row: NativeSessionRow;
+    /** Absent when a Setup launch failed before a terminal became attachable. */
+    readonly capability?: string;
+    /** Browser-only secret for a future restart-safe Setup recovery action. */
+    readonly recoveryCapability?: string;
+}
+/** Browser-safe lifecycle projection. No provider handle, credential, or terminal bytes are exposed. */
+export interface NativeSessionLifecycle {
+    readonly liveAction: "reattach" | "resume" | "restart";
+    /** True only for a still-available sealed provider conversation. */
+    readonly resumeAvailable: boolean;
+    readonly reason?: string;
+}
+/**
+ * Every independent reason `resumeAvailable` can fail closed for. Each one
+ * gets its own user-facing sentence in `nativeSessionLifecycle` below — the
+ * lifecycle reason must never assert a specific cause the caller has not
+ * actually distinguished.
+ */
+export type NativeSessionResumeUnavailableCause = "not_terminal" | "runtime_settings_correction" | "scope_stale" | "workspace_unavailable" | "no_resume_handle";
+/** Discriminated projection of why a row can or cannot resume. No identifiers travel in either branch. */
+export type NativeSessionResumeAvailability = {
+    readonly available: true;
+} | {
+    readonly available: false;
+    readonly cause: NativeSessionResumeUnavailableCause;
+};
+/**
+ * The accepted native-launch schema deliberately has no `resume` field for
+ * either current target.  `readNativeLaunchSpec` rejects unknown fields, so
+ * this matrix is a deterministic statement about the sealed contract rather
+ * than a claim based on a browser-supplied handle.
+ */
+export declare function nativeSessionLifecycle(row: Pick<NativeSessionRow, "status" | "vendor">, resumeAvailability?: NativeSessionResumeAvailability): NativeSessionLifecycle;
+/** Browser intent is explicit: reconnecting is never mistaken for a new TUI. */
+export type NativeSessionLaunchIntent = "open_existing" | "start_separate" | "resume";
+export declare class NativeSetupRecoveryError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export interface NativeVendorReadiness {
+    readonly available: boolean;
+    readonly reason?: string;
+}
+/** Browser-safe producer compatibility state. It intentionally contains no path or process detail. */
+export interface NativeProducerReadiness {
+    readonly available: boolean;
+    readonly category?: "native_session_producer_incompatible";
+}
+export interface NativePurposeReadiness {
+    readonly scopeKind: "bootstrap" | "bound_project";
+    readonly profile: string;
+    readonly target?: InteractiveTarget;
+    readonly targetLabel?: string;
+    readonly available: boolean;
+    readonly reason?: string;
+    readonly producer?: NativeProducerReadiness;
+    /** Compatibility shape retained empty; native target authority is `target`. */
+    readonly vendors: Record<NativeVendor, NativeVendorReadiness>;
+}
+export type NativeSessionReadiness = {
+    readonly runtime: NativeRuntimeBinding;
+    readonly purposes: Record<NativePurpose, NativePurposeReadiness>;
+    /** Health of the host-owned GenBI MCP endpoint; never includes a credential. */
+    readonly mcp: NativeMcpHealth;
+} & Record<NativePurpose, NativePurposeReadiness>;
+export interface NativeSessionServiceOptions {
+    readonly store: Store;
+    readonly terminalManager: () => Promise<InteractiveTerminalManager>;
+    readonly getBinding: () => EnrichmentBinding | undefined;
+    readonly workspaceRoot: string | undefined;
+    /** BFF-owned external state root, initialized once from the configured DB path. */
+    readonly materializationState?: NativeSessionStateBase;
+    readonly irPaths: Readonly<Record<NativePurpose, string | undefined>>;
+    /**
+     * The IR a session actually dispatches from, compiled for the binding it is
+     * about to run against.
+     *
+     * `irPaths` are the profiles' eval goldens: a golden is this profile compiled
+     * against warble's own example project, with that project's schema baked into
+     * `context_binding.resolved`. Dispatching one told a session on a real project
+     * that its models were jaffle-shop's, while the CLI in its cwd resolved the
+     * user's — the agent that noticed refused to draft anything, correctly.
+     *
+     * Goldens remain right for the producer contract probe, which asks whether
+     * this Warble can dispatch these profile shapes at all and has no user
+     * project in view. They are wrong the moment a session has a binding.
+     */
+    readonly resolveDispatchIr?: (purpose: NativePurpose, binding: EnrichmentBinding | undefined) => Promise<string>;
+    readonly warbleBin: string;
+    /** Absolute server-configured Wren shim for native Codex sessions; never a request input. */
+    readonly wrenShim?: string;
+    /** Read-only probe used by readiness; creation remains the final authority. */
+    readonly terminalHostAvailable?: () => Promise<boolean>;
+    /** Test seam for the local executable probe. */
+    readonly executableAvailable?: (vendor: NativeVendor) => boolean;
+    /** Test seam for the configured local Warble producer probe. */
+    readonly producerAvailable?: () => boolean;
+    /** Test seam for the server-filtered, session-local Wren profile store. */
+    readonly prepareCodexWrenHome?: (input: {
+        readonly runtime: NativeWrenRuntime;
+        readonly projectPath: string;
+        readonly cwd: string;
+    }) => CodexWrenHome;
+    /** When configured, bound native sessions use the accepted v4 MCP+welcome descriptor; v2 remains compatible for callers without it. */
+    readonly artifactService?: NativeArtifactService;
+    /** Server-owned product idle TTL after a successful browser attachment disconnects. */
+    readonly idleTtlMs?: number;
+    /** @deprecated Compatibility alias for `idleTtlMs`. */
+    readonly postClaimDetachGraceMs?: number;
+    /** Bounded post-settlement duplicate-delivery window; test seam only. */
+    readonly startSeparateReplayTtlMs?: number;
+    /** Maximum retained settled start-separate action results; test seam only. */
+    readonly startSeparateReplayLimit?: number;
+    /** Test seam for the fixed, server-owned Warble dispatch only. */
+    readonly dispatch?: (input: NativeDispatchInput) => Promise<void>;
+}
+export interface NativeDispatchInput {
+    readonly warbleBin: string;
+    /** Server-owned resolved producer identity captured by the compatibility preflight. */
+    readonly producer?: NativeProducerIdentity;
+    readonly irPath: string;
+    readonly target: InteractiveTarget;
+    readonly cwd: string;
+    readonly purpose: NativePurpose;
+    /** Exact v2 scope descriptor. It must never contain connection material. */
+    readonly scope: Record<string, unknown>;
+    /** Exact v4 MCP descriptor, transported separately through --native-mcp. */
+    readonly mcp?: NativeMcpDescriptor;
+}
+type NativeProviderLaunch = {
+    readonly kind: "initial";
+    readonly sessionId: string;
+} | {
+    readonly kind: "resume";
+    readonly handle: string;
+} | undefined;
+/** A deliberately small public classification; never expose process or filesystem detail. */
+export declare function nativeSessionLaunchFailure(error: unknown): string;
+declare const NATIVE_PRODUCER_CATEGORY: "native_session_producer_incompatible";
+/** Stable browser-safe code for an action UUID fenced by changed Runtime/binding scope. */
+export declare const NATIVE_SESSION_LAUNCH_ACTION_STALE_CODE = "native_session_launch_action_stale";
+/** Deliberately expose only this deterministic replay fence, never process detail. */
+export declare function nativeSessionLaunchErrorCode(error: unknown): typeof NATIVE_SESSION_LAUNCH_ACTION_STALE_CODE | undefined;
+/** Never serialize this server-owned executable path to the browser. */
+export interface NativeProducerIdentity {
+    readonly executable: string;
+    readonly identity: string;
+}
+export interface NativeProducerPreflightResult {
+    readonly available: boolean;
+    readonly category?: typeof NATIVE_PRODUCER_CATEGORY;
+    /** Server-only resolved executable and content identity for the eventual launch. */
+    readonly producer?: NativeProducerIdentity;
+    /** Server-only: fixed fields plus a content digest; never a command path or process output. */
+    readonly diagnostic: string;
+}
+/**
+ * Exercises the exact, file-only native dispatch boundary against the
+ * configured executable. No model, vendor CLI, project workspace, or real
+ * credential is involved. The emitted launch spec is parsed by the same
+ * validator used just before a PTY starts.
+ */
+export declare function probeNativeSessionProducer(input: {
+    readonly warbleBin: string;
+    readonly irPaths: Readonly<Record<NativePurpose, string | undefined>>;
+    readonly wrenShim?: string;
+}): Promise<NativeProducerPreflightResult>;
+/**
+ * Strict parser for the public v2/v4 producer contracts. V4 deliberately
+ * omits the host-issued scope; Setup exposes only its separately authorized
+ * bootstrap root, which is revalidated against the durable host configuration.
+ */
+export declare function readNativeLaunchSpec(cwd: string, purpose: NativePurpose, vendor: NativeVendor, scopeId: string, binding?: EnrichmentBinding, mcp?: NativeMcpDescriptor, materializationState?: NativeSessionStateBase, authorizedWorkspace?: string, providerLaunch?: NativeProviderLaunch): InteractiveLaunchSpec;
+/**
+ * Materializes only host-owned, short-lived producer inputs. The scope and
+ * MCP descriptor deliberately stay in separate exclusive files because the
+ * public Warble v4 contract parses them through distinct flags and keeps the
+ * credential out of the scope schema and every argv value.
+ */
+export declare function dispatchNativeArtifacts(input: NativeDispatchInput): Promise<void>;
+export declare class NativeSessionService {
+    private readonly options;
+    private readonly sessions;
+    private readonly leaseTimers;
+    /** Open/reconnect coalescing only lasts while a matching launch is in flight. */
+    private readonly launches;
+    /** Bounded post-settlement delivery replay, fenced to the captured server scope. */
+    private readonly startSeparateReplays;
+    /** In-process duplicate delivery fence for one durable provider-resume action. */
+    private readonly resumeLaunches;
+    private readonly artifactCredentials;
+    /** Kept only while the owning BFF and PTY remain live; never reconstructed from SQLite. */
+    private readonly recoveryCapabilities;
+    private readonly idleTtlMs;
+    private readonly startSeparateReplayTtlMs;
+    private readonly startSeparateReplayLimit;
+    private fixtureMaterializationState;
+    constructor(options: NativeSessionServiceOptions);
+    /** Existing injected producer seams are test-only and preserve old unit fixtures. */
+    private legacyFixtureMode;
+    /**
+     * Production must inject the DB-derived base at BFF startup. Existing unit
+     * seams have no BFF database path, so give only those injected producers an
+     * external throwaway state root; browser/API routes can never take this path.
+     */
+    private materializationState;
+    /**
+     * Test-injected producers retain their historical seam. Production always
+     * invokes the actual configured executable and logs only the redacted,
+     * content-addressed diagnostic; the browser never receives it.
+     */
+    private productionProducerPreflight;
+    /**
+     * SQLite is the durable source of truth, but a native PTY and its attach
+     * capability are deliberately process-local.  A BFF restart (or a lease
+     * expiry racing a browser reconnect) can therefore leave an old durable
+     * `detached` row behind after its process-local terminal is gone.  Reconcile
+     * that impossible "live" projection at every browser-visible read instead
+     * of letting the client repeatedly open a WebSocket to a missing PTY.
+     */
+    list(): NativeSessionRow[];
+    get(id: string): NativeSessionRow | undefined;
+    runtime(id: string): InteractiveTerminalSession | undefined;
+    recovery(id: string): NativeSetupRecoveryRow | undefined;
+    private reconcileMissingTerminal;
+    /** A legacy persisted Runtime must be repaired before it can authorize a PTY. */
+    private assertRuntimeDispatchable;
+    /**
+     * Reopen only a still-live session in the exact server-owned scope.  In
+     * particular, a setup session never inherits the active project binding,
+     * while a bound-purpose session cannot cross a generation or revision.
+     */
+    openOrCreate(input: {
+        purpose: NativePurpose;
+        vendor?: NativeVendor;
+    }): Promise<NativeSessionLaunch>;
+    /** Opens the exact row selected by the browser after revalidating its scope. */
+    openExisting(input: {
+        purpose: NativePurpose;
+        id: string;
+        vendor?: NativeVendor;
+    }): Promise<NativeSessionLaunch>;
+    /**
+     * Starts a separate TUI even when a matching session is live.  The caller's
+     * action id is intentionally part of the single-flight key: retries of one
+     * click coalesce, while a later intentional launch receives new durable and
+     * browser-scoped authority.
+     */
+    startSeparate(input: {
+        purpose: NativePurpose;
+        idempotencyKey: string;
+        vendor?: NativeVendor;
+    }): Promise<NativeSessionLaunch>;
+    /**
+     * Continues only a sealed Claude conversation. This creates a new durable
+     * process row and materialization root; it never reattaches or relabels a
+     * fresh conversation as a resume.
+     */
+    resume(input: {
+        id: string;
+        idempotencyKey: string;
+    }): Promise<NativeSessionLaunch>;
+    /** Browser-visible resume state uses the same current-scope fence as launch, plus *why* when it fails. */
+    resumeAvailability(row: NativeSessionRow): NativeSessionResumeAvailability;
+    /** Thin boolean projection kept for callers that only need a yes/no. */
+    resumeAvailable(row: NativeSessionRow): boolean;
+    /**
+     * Codex exposes the current thread UUID to hooks. Warble's isolated hook writes
+     * only that UUID under this session's BFF-owned materialization. The BFF reads
+     * no global Codex state and persists only a provider-bound encrypted envelope.
+     */
+    private captureCodexResumeHandle;
+    private resumeScope;
+    private resumeWorkspaceAvailable;
+    private resumeReserved;
+    private recoverReservedResume;
+    private failReservedResume;
+    private matchesOpenScope;
+    /**
+     * A start-separate action is browser-scoped by its unguessable UUID. This
+     * BFF has no user principal beyond its local browser capability boundary, so
+     * its captured Runtime/binding scope is also the authorization fence.
+     */
+    private replayStartSeparate;
+    private replayIsUsable;
+    private trimStartSeparateReplays;
+    private clearStartSeparateReplaysForSession;
+    private singleFlight;
+    readiness(): Promise<NativeSessionReadiness>;
+    create(input: {
+        purpose: NativePurpose;
+        vendor?: NativeVendor;
+    }, binding?: EnrichmentBinding | undefined, capturedRuntime?: NativeRuntimeBinding, resumed?: {
+        readonly row: NativeSessionRow;
+        readonly handle: string;
+    }): Promise<NativeSessionLaunch>;
+    attach(id: string, capability: string): InteractiveTerminalSession | undefined;
+    detach(id: string): void;
+    stop(id: string, capability: string): boolean;
+    private revokeCapabilities;
+    /** Called after the store's atomic runtime switch fence has committed. */
+    revokeRuntimeCapabilities(ids: readonly string[]): void;
+    /** Called after the store advances the bound-project generation. */
+    revokeBindingCapabilities(ids: readonly string[]): void;
+    /**
+     * Records only the producer's closed redacted report. Completion remains a
+     * host decision supplied by the canonical-artifact validator at the route.
+     */
+    reportSetupRecovery(sessionId: string, value: unknown, completionValidated: boolean): NativeSetupRecoveryRow;
+    /**
+     * Recovery never resumes a process-owned PTY. Once a terminal session has
+     * ended/interrupted, a fenced action creates a fresh Setup session and its
+     * new terminal/MCP/recovery capabilities. Live terminals must be handled in
+     * their owning browser tab and are rejected here.
+     */
+    actOnSetupRecovery(input: {
+        id: string;
+        capability: string;
+        expectedVersion: number;
+        action: "retry" | "continue" | "stop";
+    }): Promise<NativeSessionLaunch | undefined>;
+    private clearLease;
+    private armLease;
+}