@pentoshi/clai 3.11.7 → 3.11.9

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,26 @@
+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;
+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;
+    consume(token: string | undefined, binding: ApprovalBinding): boolean;
+    private sweep;
+}

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

@@ -0,0 +1,70 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { maskSecret } from "../llm/provider.js";
+import { classifyInteractiveInput as classifyInput, } from "../safety/classifier.js";
+export function classifyInteractiveInput(context) {
+    return classifyInput(context);
+}
+export function describeInput(input) {
+    if (input.kind === "eof")
+        return "close session input (EOF)";
+    if (input.kind === "control")
+        return `control: ${input.control}`;
+    if (input.kind === "secret") {
+        return `${input.submit === "enter" ? "submit" : "type"}: [secret]`;
+    }
+    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}`;
+}
+const TOKEN_TTL_MS = 60_000;
+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 === "secret" ? input.value : input.kind === "control" ? input.control : "",
+        input.kind === "text" || input.kind === "secret" ? 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;
+    }
+    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);
+    }
+    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,118 @@
+/**
+ * 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;
+    private readonly ownerActivations;
+    private readonly pendingStarts;
+    private readonly lateLaunches;
+    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 startManaged;
+    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>;
+    activateOwner(ownerId: string): Promise<void>;
+    private awaitOwnerActivation;
+    closeAll(reason?: TerminationReason): Promise<CloseAllResult>;
+    private closeOwnerSessions;
+    private finalizeRecord;
+    private finalize;
+    private authorizeCommand;
+    private authorizeInput;
+    private registerPendingStart;
+    private trackLateLaunch;
+    private cancelPendingStarts;
+    private releaseUnmanagedTransport;
+    private throwIfCancelled;
+    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;