@pentoshi/clai 3.9.2 → 3.9.4

package/dist/interactive-session/config.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Interactive-session configuration: documented defaults, validated ranges, and
+ * a runtime kill switch. Every value is validated before a slot is reserved or a
+ * process is launched so an out-of-range setting can never produce a live child.
+ */
+import { type SessionOperation, type TerminalDimensions } from "./types.js";
+export interface InteractiveSessionConfig {
+    enabled: boolean;
+    liveSessionLimit: number;
+    quietIntervalMs: number;
+    startDeadlineMs: number;
+    sendDeadlineMs: number;
+    closeDeadlineMs: number;
+    gracefulCloseMs: number;
+    pageBytes: number;
+    memoryWindowBytes: number;
+    queuedInputBytes: number;
+    artifactCaptureBytes: number;
+    artifactChunkBytes: number;
+    persistenceQueueBytes: number;
+    /** Undefined disables the timeout. */
+    idleTimeoutMs: number | undefined;
+    lifetimeTimeoutMs: number | undefined;
+    /** Behavior when artifact capture reaches its limit. */
+    onOutputLimit: "terminate" | "continue";
+    /** Max bytes retained for cross-chunk secret matching. */
+    redactionOverlapBytes: number;
+}
+interface Range {
+    readonly min: number;
+    readonly max: number;
+}
+export declare const INTERACTIVE_SESSION_RANGES: {
+    readonly liveSessionLimit: {
+        readonly min: 1;
+        readonly max: 32;
+    };
+    readonly quietIntervalMs: {
+        readonly min: 25;
+        readonly max: 5000;
+    };
+    readonly startDeadlineMs: {
+        readonly min: 100;
+        readonly max: 120000;
+    };
+    readonly sendDeadlineMs: {
+        readonly min: 100;
+        readonly max: 120000;
+    };
+    readonly closeDeadlineMs: {
+        readonly min: 100;
+        readonly max: 120000;
+    };
+    readonly gracefulCloseMs: {
+        readonly min: 0;
+        readonly max: 30000;
+    };
+    readonly pageBytes: {
+        readonly min: 1024;
+        readonly max: 1048576;
+    };
+    readonly memoryWindowBytes: {
+        readonly min: 65536;
+        readonly max: 16777216;
+    };
+    readonly queuedInputBytes: {
+        readonly min: 1024;
+        readonly max: 1048576;
+    };
+    readonly artifactCaptureBytes: {
+        readonly min: 1048576;
+        readonly max: 1073741824;
+    };
+    readonly artifactChunkBytes: {
+        readonly min: 65536;
+        readonly max: 16777216;
+    };
+    readonly persistenceQueueBytes: {
+        readonly min: 65536;
+        readonly max: 16777216;
+    };
+    readonly idleTimeoutMs: {
+        readonly min: 1000;
+        readonly max: 86400000;
+    };
+    readonly lifetimeTimeoutMs: {
+        readonly min: 1000;
+        readonly max: 604800000;
+    };
+    readonly redactionOverlapBytes: {
+        readonly min: 256;
+        readonly max: 65536;
+    };
+};
+export type RangedConfigField = keyof typeof INTERACTIVE_SESSION_RANGES;
+export declare const DIMENSION_RANGE: Range;
+export declare const DEFAULT_DIMENSIONS: TerminalDimensions;
+/** Hard cap for a blocking read wait, independent of send deadlines. */
+export declare const MAX_READ_WAIT_MS = 30000;
+export declare const MAX_LIST_SUMMARIES = 50;
+export declare const INTERACTIVE_SESSION_DEFAULTS: InteractiveSessionConfig;
+/** Env kill switch. Disables only the seven interactive tools. */
+export declare const KILL_SWITCH_ENV = "CLAI_DISABLE_INTERACTIVE_SESSIONS";
+export type InteractiveSessionOverrides = Partial<InteractiveSessionConfig>;
+/**
+ * Resolve the effective configuration. Throws `INVALID_CONFIGURATION` for any
+ * out-of-range value so callers fail before allocating resources.
+ */
+export declare function resolveInteractiveSessionConfig(overrides?: InteractiveSessionOverrides, operation?: SessionOperation): InteractiveSessionConfig;
+export declare function isInteractiveSessionsEnabled(config?: InteractiveSessionConfig): boolean;
+/** Per-operation timeout override, validated against the same bounds. */
+export declare function resolveDeadline(field: "startDeadlineMs" | "sendDeadlineMs" | "closeDeadlineMs", override: number | undefined, config: InteractiveSessionConfig, operation: SessionOperation): number;
+export declare function resolveQuietInterval(override: number | undefined, config: InteractiveSessionConfig, operation: SessionOperation): number;
+export declare function resolveOptionalTimeout(field: "idleTimeoutMs" | "lifetimeTimeoutMs", override: number | undefined, config: InteractiveSessionConfig, operation: SessionOperation): number | undefined;
+/** Validate requested dimensions before any lookup or process mutation. */
+export declare function resolveDimensions(columns: number | undefined, rows: number | undefined, operation: SessionOperation): TerminalDimensions;
+export declare function clampReadWait(waitMs: number | undefined): number;
+export {};

package/dist/interactive-session/config.js

@@ -0,0 +1,141 @@
+/**
+ * Interactive-session configuration: documented defaults, validated ranges, and
+ * a runtime kill switch. Every value is validated before a slot is reserved or a
+ * process is launched so an out-of-range setting can never produce a live child.
+ */
+import { throwSessionError, } from "./types.js";
+export const INTERACTIVE_SESSION_RANGES = {
+    liveSessionLimit: { min: 1, max: 32 },
+    quietIntervalMs: { min: 25, max: 5_000 },
+    startDeadlineMs: { min: 100, max: 120_000 },
+    sendDeadlineMs: { min: 100, max: 120_000 },
+    closeDeadlineMs: { min: 100, max: 120_000 },
+    gracefulCloseMs: { min: 0, max: 30_000 },
+    pageBytes: { min: 1_024, max: 1_048_576 },
+    memoryWindowBytes: { min: 65_536, max: 16_777_216 },
+    queuedInputBytes: { min: 1_024, max: 1_048_576 },
+    artifactCaptureBytes: { min: 1_048_576, max: 1_073_741_824 },
+    artifactChunkBytes: { min: 65_536, max: 16_777_216 },
+    persistenceQueueBytes: { min: 65_536, max: 16_777_216 },
+    idleTimeoutMs: { min: 1_000, max: 86_400_000 },
+    lifetimeTimeoutMs: { min: 1_000, max: 604_800_000 },
+    redactionOverlapBytes: { min: 256, max: 65_536 },
+};
+export const DIMENSION_RANGE = { min: 2, max: 1_000 };
+export const DEFAULT_DIMENSIONS = { columns: 80, rows: 24 };
+/** Hard cap for a blocking read wait, independent of send deadlines. */
+export const MAX_READ_WAIT_MS = 30_000;
+export const MAX_LIST_SUMMARIES = 50;
+export const INTERACTIVE_SESSION_DEFAULTS = {
+    enabled: true,
+    liveSessionLimit: 4,
+    quietIntervalMs: 250,
+    startDeadlineMs: 10_000,
+    sendDeadlineMs: 30_000,
+    closeDeadlineMs: 10_000,
+    gracefulCloseMs: 2_000,
+    pageBytes: 12_000,
+    memoryWindowBytes: 1_048_576,
+    queuedInputBytes: 65_536,
+    artifactCaptureBytes: 67_108_864,
+    artifactChunkBytes: 1_048_576,
+    persistenceQueueBytes: 1_048_576,
+    idleTimeoutMs: undefined,
+    lifetimeTimeoutMs: undefined,
+    onOutputLimit: "terminate",
+    redactionOverlapBytes: 4_096,
+};
+/** Env kill switch. Disables only the seven interactive tools. */
+export const KILL_SWITCH_ENV = "CLAI_DISABLE_INTERACTIVE_SESSIONS";
+function envDisabled() {
+    const raw = process.env[KILL_SWITCH_ENV];
+    if (raw === undefined)
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+function invalid(field, message, operation) {
+    throwSessionError({
+        code: "INVALID_CONFIGURATION",
+        operation,
+        message,
+        details: { field },
+    });
+}
+function checkRange(field, value, operation) {
+    const { min, max } = INTERACTIVE_SESSION_RANGES[field];
+    if (!Number.isInteger(value) || value < min || value > max) {
+        invalid(field, `${field} must be an integer between ${min} and ${max}.`, operation);
+    }
+    return value;
+}
+/**
+ * Resolve the effective configuration. Throws `INVALID_CONFIGURATION` for any
+ * out-of-range value so callers fail before allocating resources.
+ */
+export function resolveInteractiveSessionConfig(overrides = {}, operation = "start") {
+    const merged = { ...INTERACTIVE_SESSION_DEFAULTS, ...overrides };
+    for (const field of Object.keys(INTERACTIVE_SESSION_RANGES)) {
+        const value = merged[field];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "number") {
+            invalid(field, `${field} must be a number.`, operation);
+        }
+        checkRange(field, value, operation);
+    }
+    if (merged.artifactChunkBytes > merged.artifactCaptureBytes) {
+        invalid("artifactChunkBytes", "artifactChunkBytes cannot exceed artifactCaptureBytes.", operation);
+    }
+    if (merged.onOutputLimit !== "terminate" && merged.onOutputLimit !== "continue") {
+        invalid("onOutputLimit", "onOutputLimit must be terminate or continue.", operation);
+    }
+    return { ...merged, enabled: merged.enabled && !envDisabled() };
+}
+export function isInteractiveSessionsEnabled(config = resolveInteractiveSessionConfig()) {
+    return config.enabled;
+}
+/** Per-operation timeout override, validated against the same bounds. */
+export function resolveDeadline(field, override, config, operation) {
+    if (override === undefined)
+        return config[field];
+    return checkRange(field, override, operation);
+}
+export function resolveQuietInterval(override, config, operation) {
+    if (override === undefined)
+        return config.quietIntervalMs;
+    return checkRange("quietIntervalMs", override, operation);
+}
+export function resolveOptionalTimeout(field, override, config, operation) {
+    if (override === undefined)
+        return config[field];
+    return checkRange(field, override, operation);
+}
+/** Validate requested dimensions before any lookup or process mutation. */
+export function resolveDimensions(columns, rows, operation) {
+    const resolved = {
+        columns: columns ?? DEFAULT_DIMENSIONS.columns,
+        rows: rows ?? DEFAULT_DIMENSIONS.rows,
+    };
+    for (const [field, value] of Object.entries(resolved)) {
+        if (!Number.isInteger(value) ||
+            value < DIMENSION_RANGE.min ||
+            value > DIMENSION_RANGE.max) {
+            throwSessionError({
+                code: "INVALID_REQUEST",
+                operation,
+                message: `${field} must be an integer between ${DIMENSION_RANGE.min} and ${DIMENSION_RANGE.max}.`,
+                details: { field },
+            });
+        }
+    }
+    return resolved;
+}
+export function clampReadWait(waitMs) {
+    if (waitMs === undefined)
+        return 0;
+    if (!Number.isFinite(waitMs) || waitMs < 0)
+        return 0;
+    return Math.min(Math.floor(waitMs), MAX_READ_WAIT_MS);
+}
+//# sourceMappingURL=config.js.map

package/dist/interactive-session/config.js.map

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

package/dist/interactive-session/input-policy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Contextual policy for later interactive input.
+ *
+ * Generic tool classification cannot decide this: the risk of a keystroke depends
+ * on the owning session, the exact bytes, and whether they are being submitted.
+ * Risk is monotonic with the shell boundary — a command sent into a session is
+ * never rated lower than the same command run through `shell.exec`.
+ */
+import type { RiskDecision } from "../safety/classifier.js";
+import type { EngagementScope } from "../store/scope.js";
+import type { SessionInput, SessionTransportKind } from "./types.js";
+export interface InputPolicyContext {
+    readonly ownerId: string;
+    readonly sessionId: string;
+    readonly transport: SessionTransportKind;
+    readonly input: SessionInput;
+    readonly scope?: EngagementScope | undefined;
+}
+export declare function classifyInteractiveInput(context: InputPolicyContext): RiskDecision;
+/** Redacted, bounded description shown in a confirmation preview. */
+export declare function describeInput(input: SessionInput): string;
+export interface ApprovalBinding {
+    readonly ownerId: string;
+    readonly sessionId: string;
+    readonly input: SessionInput;
+    readonly decision: RiskDecision["level"];
+}
+export declare class ApprovalTokenVault {
+    private readonly now;
+    private readonly tokens;
+    constructor(now?: () => number);
+    mint(binding: ApprovalBinding): string;
+    /**
+     * Validate and invalidate atomically. Any change to owner, session, bytes,
+     * kind, submit behavior, or decision fails, and a token is single-use so a
+     * concurrent replay cannot deliver the same input twice.
+     */
+    consume(token: string | undefined, binding: ApprovalBinding): boolean;
+    /** Expiry sweep; single-use semantics make stale tokens unusable anyway. */
+    private sweep;
+}

package/dist/interactive-session/input-policy.js

@@ -0,0 +1,163 @@
+/**
+ * Contextual policy for later interactive input.
+ *
+ * Generic tool classification cannot decide this: the risk of a keystroke depends
+ * on the owning session, the exact bytes, and whether they are being submitted.
+ * Risk is monotonic with the shell boundary — a command sent into a session is
+ * never rated lower than the same command run through `shell.exec`.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { classifyShellCommand } from "../safety/classifier.js";
+import { maskSecret } from "../llm/provider.js";
+/** Controls that only move a cursor or redraw a prompt carry no risk. */
+const SAFE_CONTROLS = new Set([
+    "escape",
+    "tab",
+    "backspace",
+    "up",
+    "down",
+    "left",
+    "right",
+    "interrupt",
+    "suspend",
+    "eof",
+]);
+/**
+ * Short, unambiguous REPL answers. Everything outside this set is treated as
+ * unknown submitted text and therefore requires confirmation.
+ */
+const RECOGNIZED_ANSWER_RE = /^(y|n|yes|no|q|quit|exit|:q|:q!|help|\?|\d+(\.\d+)?|true|false|none|null)$/i;
+/** REPL constructs that destroy data or escape the interpreter irreversibly. */
+const REPL_DESTRUCTIVE_PATTERNS = [
+    /\bshutil\s*\.\s*rmtree\b/i,
+    /\bos\s*\.\s*(remove|unlink|rmdir)\b/i,
+    /\bfs\s*\.\s*(unlink|rm|rmdir)Sync?\b/i,
+    /\bDROP\s+(TABLE|DATABASE|SCHEMA)\b/i,
+    /\bTRUNCATE\s+TABLE\b/i,
+    /\bDELETE\s+FROM\b(?![\s\S]*\bWHERE\b)/i,
+    /\bRemove-Item\b[\s\S]*-Recurse/i,
+];
+/** REPL constructs that mutate state or reach outside the interpreter. */
+const REPL_MUTATOR_PATTERNS = [
+    /\bos\s*\.\s*system\b/i,
+    /\bsubprocess\s*\.\s*(run|call|Popen|check_output)\b/i,
+    /\bchild_process\b/i,
+    /\brequire\s*\(\s*['"]fs['"]\s*\)/i,
+    /\b(eval|exec)\s*\(/i,
+    /\bopen\s*\([^)]*['"][wa]\+?['"]/i,
+    /\bInvoke-(Expression|WebRequest|RestMethod)\b/i,
+    /\b(UPDATE|INSERT\s+INTO|ALTER\s+TABLE|GRANT|REVOKE)\b/i,
+    /\bpip\s+install\b|\bnpm\s+(install|i)\b/i,
+];
+const EXFILTRATION_PATTERNS = [
+    /\b(curl|wget)\b[\s\S]*\|\s*(sh|bash|zsh|python)/i,
+    /\bbase64\b[\s\S]*\|\s*(curl|wget|nc)\b/i,
+];
+export function classifyInteractiveInput(context) {
+    const { input } = context;
+    if (input.kind === "eof") {
+        return { level: "safe", reason: "Closing session input has no command effect" };
+    }
+    if (input.kind === "control") {
+        return SAFE_CONTROLS.has(input.control)
+            ? { level: "safe", reason: "Terminal navigation control" }
+            : { level: "confirm", reason: "Unrecognized terminal control" };
+    }
+    const text = input.text;
+    if (text.trim().length === 0) {
+        return { level: "safe", reason: "Whitespace-only input has no command effect" };
+    }
+    if (EXFILTRATION_PATTERNS.some((pattern) => pattern.test(text))) {
+        return {
+            level: "block",
+            reason: "Input pipes remote content into an interpreter or exports local data",
+        };
+    }
+    if (REPL_DESTRUCTIVE_PATTERNS.some((pattern) => pattern.test(text))) {
+        return { level: "block", reason: "Input matches a destructive REPL pattern" };
+    }
+    // Never rate an interactive command below the shell boundary for the same text.
+    const shellDecision = classifyShellCommand(text, context.scope ? { scope: context.scope } : {});
+    if (shellDecision.level !== "safe")
+        return shellDecision;
+    if (REPL_MUTATOR_PATTERNS.some((pattern) => pattern.test(text))) {
+        return { level: "confirm", reason: "Input mutates state through an interpreter" };
+    }
+    if (RECOGNIZED_ANSWER_RE.test(text.trim())) {
+        return { level: "safe", reason: "Recognized prompt answer" };
+    }
+    return {
+        level: "confirm",
+        reason: "Submitted interactive text is not recognized as read-only",
+    };
+}
+/** Redacted, bounded description shown in a confirmation preview. */
+export function describeInput(input) {
+    if (input.kind === "eof")
+        return "close session input (EOF)";
+    if (input.kind === "control")
+        return `control: ${input.control}`;
+    const trimmed = input.text.trim();
+    const preview = trimmed.length > 120 ? `${trimmed.slice(0, 120)}…` : trimmed;
+    const body = /^[\x20-\x7e]*$/.test(preview) ? preview : maskSecret(preview);
+    return `${input.submit === "enter" ? "submit" : "type"}: ${body}`;
+}
+// --- Approval tokens ----------------------------------------------------
+const TOKEN_TTL_MS = 60_000;
+/** Per-process key: digests are never persisted, logged, or returned. */
+const digestKey = randomBytes(32);
+function bindingDigest(binding) {
+    const { input } = binding;
+    const parts = [
+        binding.ownerId,
+        binding.sessionId,
+        input.kind,
+        input.kind === "text" ? input.text : input.kind === "control" ? input.control : "",
+        input.kind === "text" ? input.submit : "",
+        binding.decision,
+    ];
+    return createHmac("sha256", digestKey).update(parts.join("\u0000")).digest("hex");
+}
+export class ApprovalTokenVault {
+    now;
+    tokens = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    mint(binding) {
+        this.sweep();
+        const token = randomBytes(24).toString("base64url");
+        this.tokens.set(token, {
+            digest: bindingDigest(binding),
+            expiresAt: this.now() + TOKEN_TTL_MS,
+        });
+        return token;
+    }
+    /**
+     * Validate and invalidate atomically. Any change to owner, session, bytes,
+     * kind, submit behavior, or decision fails, and a token is single-use so a
+     * concurrent replay cannot deliver the same input twice.
+     */
+    consume(token, binding) {
+        if (!token)
+            return false;
+        const entry = this.tokens.get(token);
+        if (!entry)
+            return false;
+        this.tokens.delete(token);
+        if (entry.expiresAt <= this.now())
+            return false;
+        const expected = Buffer.from(bindingDigest(binding), "utf8");
+        const actual = Buffer.from(entry.digest, "utf8");
+        return expected.length === actual.length && timingSafeEqual(expected, actual);
+    }
+    /** Expiry sweep; single-use semantics make stale tokens unusable anyway. */
+    sweep() {
+        const now = this.now();
+        for (const [token, entry] of this.tokens) {
+            if (entry.expiresAt <= now)
+                this.tokens.delete(token);
+        }
+    }
+}
+//# sourceMappingURL=input-policy.js.map

package/dist/interactive-session/input-policy.js.map

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

package/dist/interactive-session/manager.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Interactive session manager: the single owner of persistent interactive
+ * process lifecycle.
+ *
+ * Ownership is conversation-scoped. Every operation requires an owner id, and a
+ * lookup for another owner is indistinguishable from a missing session so the
+ * manager cannot be used as an existence oracle. Direct user-terminal handoff is
+ * outside this contract by design.
+ */
+import type { EngagementScope } from "../store/scope.js";
+import { type InteractiveSessionConfig, type InteractiveSessionOverrides } from "./config.js";
+import { RecoveryJournal, type ReconciliationEntry } from "./recovery-journal.js";
+import { type Clock } from "./runtime.js";
+import { SessionTelemetry } from "./telemetry.js";
+import { type SessionTransportFactory } from "./transport.js";
+import { type CloseAllResult, type CloseOwnerResult, type CloseRequest, type CloseResult, type ListResult, type ReadRequest, type ReadResult, type ResizeRequest, type ResizeResult, type SendRequest, type SendResult, type SessionInput, type SessionOperation, type StartRequest, type StartResult, type StatusResult, type TerminationReason } from "./types.js";
+/** Confirmation surface for a `confirm`-level action. Previews are redacted. */
+export type ConfirmPreview = (request: {
+    readonly title: string;
+    readonly description: string;
+    readonly reason: string;
+}) => Promise<boolean>;
+export interface ManagerRequestExtras {
+    readonly confirm?: ConfirmPreview | undefined;
+    readonly scope?: EngagementScope | undefined;
+}
+export interface InteractiveSessionManagerDeps {
+    readonly config?: InteractiveSessionOverrides | undefined;
+    readonly transports?: SessionTransportFactory | undefined;
+    readonly clock?: Clock | undefined;
+    readonly journal?: RecoveryJournal | undefined;
+    readonly telemetry?: SessionTelemetry | undefined;
+    readonly artifactBaseDir?: string | undefined;
+}
+export declare class InteractiveSessionManager {
+    private readonly registry;
+    private readonly runtimes;
+    private readonly approvals;
+    private readonly telemetry;
+    private readonly journal;
+    private readonly cleanup;
+    private readonly transports;
+    private readonly clock;
+    private readonly baseConfig;
+    private readonly artifactBaseDir;
+    private readonly ownerCloses;
+    constructor(deps?: InteractiveSessionManagerDeps);
+    get config(): InteractiveSessionConfig;
+    /** Reconcile crashed-session records. Must run before tools are enabled. */
+    reconcileOrphans(): ReconciliationEntry[];
+    ptyCapability(): Promise<{
+        available: boolean;
+        reason?: string | undefined;
+    }>;
+    start(request: StartRequest & ManagerRequestExtras): Promise<StartResult>;
+    private launchError;
+    private launchWithDeadline;
+    send(request: SendRequest & ManagerRequestExtras): Promise<SendResult>;
+    private sendError;
+    /**
+     * Acceptance is all-or-nothing under the mutation lock: either the whole action
+     * is reserved within the backpressure bound, or no sequence or queue state
+     * changes at all.
+     */
+    private accept;
+    private assertControlSupported;
+    /**
+     * Quiet detection starts at delivery completion: only output observed after
+     * this point resets the quiet timer, while the absolute deadline never extends.
+     */
+    private gather;
+    read(request: ReadRequest): Promise<ReadResult>;
+    private waitForOutput;
+    status(request: {
+        ownerId: string;
+        id: string;
+    }): StatusResult;
+    list(request: {
+        ownerId: string;
+    }): ListResult;
+    resize(request: ResizeRequest): Promise<ResizeResult>;
+    close(request: CloseRequest): Promise<CloseResult>;
+    /** Owner cancellation: closes every live session owned by a conversation. */
+    cancelOwner(ownerId: string): Promise<CloseOwnerResult>;
+    /**
+     * Fence an owner synchronously, then start one tracked close. Callers rebinding
+     * a conversation id must fence before the old id becomes unreachable.
+     */
+    beginCloseOwner(ownerId: string, reason?: TerminationReason): Promise<CloseOwnerResult>;
+    /** Await any teardown already started for an owner. */
+    awaitOwnerClose(ownerId: string): Promise<void>;
+    closeAll(reason?: TerminationReason): Promise<CloseAllResult>;
+    private closeOwnerSessions;
+    private finalizeRecord;
+    private finalize;
+    private authorizeCommand;
+    private authorizeInput;
+    private assertOwner;
+    private assertNotFenced;
+    private assertEnabled;
+    private notFound;
+    private requireRuntime;
+}
+/** Strict validation of the dependent input fields before acceptance. */
+export declare function validateInput(input: SessionInput | undefined, operation: SessionOperation): SessionInput;
+/** Process-wide manager, mirroring the existing process-wide job manager. */
+export declare const interactiveSessionManager: InteractiveSessionManager;