spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/sessions.d.ts

@@ -0,0 +1,412 @@
+import { type ReviewDiffFile } from '@spexcode/spec-core';
+import { type ConfigPreset, type SpecLite } from '@spexcode/spec-core';
+import { type Harness, type TurnFailure, type DispatchResult, type PaneProbe } from './harness.js';
+import { envSessionId, type RawRecord, type SessionLifecycle, type SessionProposal } from '@spexcode/spec-core';
+import { type SessionWeb } from './session-web.js';
+import { type SentDispatchReceipt } from './session-timeline.js';
+export declare const TMUX_SOCK: string;
+export type { DispatchResult };
+export type Lifecycle = SessionLifecycle;
+export type Proposal = SessionProposal;
+export type DisplayStatus = 'working' | 'idle' | 'offline' | 'starting' | 'review' | 'done' | 'close-pending' | 'parked' | 'error' | 'asking' | 'queued' | 'unknown' | 'corrupt' | 'retired';
+export type Liveness = 'online' | 'starting' | 'offline' | 'unknown';
+export type Session = {
+    id: string;
+    node: string | null;
+    branch: string | null;
+    path: string;
+    label: string;
+    title: string;
+    raw: {
+        name: string | null;
+        title: string | null;
+    };
+    parent: string | null;
+    harness: string;
+    capabilities: {
+        headless: boolean;
+    };
+    launcher: string | null;
+    lifecycle: Lifecycle;
+    proposal: Proposal | null;
+    merges: number;
+    status: DisplayStatus;
+    liveness: Liveness;
+    note: string | null;
+    archived: boolean;
+    archiveHazard?: string | null;
+    prompt: string | null;
+    promptPreview: string | null;
+    created: number;
+    activity: string | null;
+    sortKey: number | null;
+    files?: string[];
+    web?: SessionWeb[];
+    zcodeChildSessionIds?: string[];
+};
+export type CloseSource = {
+    kind: 'unverified-session-claim';
+    id: string;
+} | {
+    kind: 'user';
+};
+export type SessionClosure = {
+    id: string;
+    closedAt: string;
+};
+export declare function findSessionClosure(selector: string): SessionClosure | null;
+export declare const HEADLINE_PREVIEW_COLUMNS = 60;
+export declare const deriveLabel: (r: {
+    name?: string | null;
+    node?: string | null;
+    title?: string | null;
+    branch?: string | null;
+    id: string;
+}) => string;
+export declare const deriveTitle: (r: {
+    name?: string | null;
+    activity?: string | null;
+    note?: string | null;
+    promptPreview?: string | null;
+    node?: string | null;
+    title?: string | null;
+    branch?: string | null;
+    id: string;
+}) => string;
+export declare const deriveHeadline: (r: {
+    name?: string | null;
+    activity?: string | null;
+    note?: string | null;
+    promptPreview?: string | null;
+    node?: string | null;
+    title?: string | null;
+    branch?: string | null;
+    id: string;
+}) => string;
+export declare const sessionLabel: (s: Session) => string;
+export declare const sessionTitle: (s: Session) => string;
+export declare const sessionHeadline: (s: Session) => string;
+export declare function alive(id: string): Promise<boolean>;
+export type SessRec = {
+    session: string;
+    governed: boolean;
+    worktreePath: string;
+    branch: string | null;
+    node: string | null;
+    title: string | null;
+    name: string | null;
+    parent: string | null;
+    status: Lifecycle;
+    proposal: Proposal | null;
+    merges: number;
+    note: string | null;
+    sortKey: number | null;
+    createdAt: number;
+    harness: string;
+    harnessSessionId: string | null;
+    stopped: boolean;
+    archived: boolean;
+    coldProof?: string | null;
+    adapterRecovery?: string | null;
+    launcher: string | null;
+    launchCmd: string | null;
+    launchOwner: string | null;
+    createRequestId?: string | null;
+    createPayloadHash?: string | null;
+    zcodeChildSessionIds?: string[];
+    base?: string | null;
+    launchReadinessPending?: LaunchReadinessPending | null;
+};
+type LaunchReadinessOriginal = Pick<SessRec, 'status' | 'proposal' | 'note' | 'stopped' | 'archived' | 'coldProof' | 'adapterRecovery'>;
+type LaunchReadinessPending = {
+    version: 1;
+    startedAt: number;
+    original: LaunchReadinessOriginal;
+};
+export declare const OWNED_QUEUE_RAW_STATUS = "launch-queued";
+export declare function backendLaunchAuthority(env?: {
+    SPEXCODE_API_URL?: string;
+    PORT?: string;
+}): string;
+export declare function rawLifecycleStatus(rec: Pick<SessRec, 'status' | 'launchOwner'>): string;
+export declare function canDrainQueued(rec: Pick<SessRec, 'status' | 'launchOwner'>, authority?: string): boolean;
+export declare class SessionRecordUnusable extends Error {
+    readonly code: 'corrupt' | 'retired';
+    readonly session: string;
+    constructor(code: 'corrupt' | 'retired', session: string, message: string);
+}
+export declare function withSessionRecordLockSync<T>(id: string, body: () => T): T;
+export declare function withSessionInputLock<T>(id: string, body: () => T): T | null;
+export declare function fromRaw(raw: RawRecord & {
+    launch_owner?: string;
+}): SessRec;
+export type WatchSource = 'manual' | 'parent';
+export type SessionWatch = {
+    target: string;
+    createdAt: string;
+};
+export declare function subscribeSessionWatch(watcher: string, targets: string[], source?: WatchSource): Promise<{
+    watched: string[];
+}>;
+export declare function listSessionWatches(watcher: string): SessionWatch[];
+export declare function cancelSessionWatch(watcher: string, targets: string[]): number;
+export type SessionReparentResult = {
+    children: string[];
+    parent: string | null;
+    notified: string[];
+};
+export declare function reparentSessionRecords(rawChildren: string[], parent: string | null): Promise<SessionReparentResult>;
+export type LiveSnap = {
+    probeFailed: boolean;
+    windows: Map<string, PaneProbe>;
+    titles: Map<string, string>;
+    sockets: Set<string>;
+    unproven: Set<string>;
+};
+export declare const TMUX_PANE_FORMAT = "#{session_name}\\037#{pane_pid}\\037#{pane_title}";
+export declare function parseLivePanes(out: string): Map<string, {
+    panePid?: number;
+    title?: string;
+}>;
+export declare function needsCodexProcScan(windowed: {
+    harness: string;
+    hasPid: boolean;
+}[]): boolean;
+export declare function hotSignature(): Promise<string>;
+export declare function warmSignature(): Promise<string>;
+export declare function paneActivity(harness: Harness, paneTitle: string | null | undefined): string | null;
+export declare function selfSummary(paneTitle: string): string | null;
+export declare const BOOT_GRACE_MS = 45000;
+export declare function liveness(rec: SessRec, snap: LiveSnap): Liveness;
+export type ReviewIdentity = {
+    id: string;
+    node: string | null;
+    branch: string | null;
+    label: string;
+};
+export declare function reviewIdentity(id: string): ReviewIdentity | null;
+export declare function toSession(rec: SessRec, status: DisplayStatus, lv: Liveness, activity?: string | null): Session;
+export type ZCodeChildSessionLink = {
+    sessionId: string;
+    childSessionId: string;
+    alreadyLinked: boolean;
+};
+export declare function linkZCodeChildSession(sessionId: string, childSessionId: unknown): Promise<ZCodeChildSessionLink | null>;
+export declare function renameSession(id: string, name: string): Promise<boolean>;
+export declare function setSessionSort(id: string, key: number | null): Promise<boolean>;
+export declare function sessionPrompt(id: string): Promise<string | null>;
+export declare function listSessions(includeArchived?: boolean): Promise<Session[]>;
+export type ApiBaseSource = 'flag' | 'worker-env' | 'record' | 'env-fallback' | 'default';
+export type ApiBaseInfo = {
+    url: string;
+    source: ApiBaseSource;
+};
+export declare function optionArgv(argv?: readonly string[]): readonly string[];
+export declare const apiBaseInfo: () => Promise<ApiBaseInfo>;
+export declare const apiBase: () => Promise<string>;
+export declare const ownSessionId: typeof envSessionId;
+export type MsgSender = {
+    id: string;
+    label: string | null;
+};
+export declare function withSenderHint(text: string, sender: MsgSender | null): string;
+export declare function withPeerSenderHint(text: string, sender: MsgSender | null, sshAddress: string, machineId: string): string;
+export declare const withNoteReplyHint: (text: string) => string;
+export declare const withTerminalReplyHint: (text: string) => string;
+export declare const slugify: (s: string | null) => string;
+export declare const nodeFromPrompt: (prompt: string) => string | null;
+type CommandPreset = Pick<ConfigPreset, 'name' | 'body'>;
+type CommandSpec = Pick<SpecLite, 'id' | 'path'>;
+export declare function composeCommandPrompt(raw: string, presets: CommandPreset[], specs: CommandSpec[]): string;
+export declare function resolveCommandPrompt(raw: string, loadedSpecs?: CommandSpec[]): Promise<string>;
+type SessionPromptTarget = Pick<SessRec, 'session' | 'harness'>;
+type SessionPromptOptions = {
+    from?: string;
+    replyVia?: 'note';
+    loadedSpecs?: CommandSpec[];
+    suffix?: string;
+};
+export type ComposedSessionPrompt = {
+    text: string;
+    replyVia?: 'note';
+};
+export declare function composeSessionPrompt(raw: string, target: SessionPromptTarget, opts?: SessionPromptOptions): Promise<ComposedSessionPrompt>;
+export declare function titleFromPrompt(prompt: string): string | null;
+export declare function launcherCmd(rec: SessRec): string | undefined;
+export type LaunchBlock = {
+    code: 'no-worktree' | 'no-branch' | 'no-launcher';
+    message: string;
+};
+export declare function launchPreflight(rec: SessRec): LaunchBlock | null;
+export declare function launchScript(id: string, tail: string, harness?: Harness, cmd?: string): string;
+export declare const drainQueue: () => Promise<void>;
+export declare function superviseQueue(intervalMs?: number): void;
+export declare function superviseDelivery(intervalMs?: number): void;
+export declare function turnFailureNote(harness: string, failure: TurnFailure): string;
+export declare function turnFailureRetryDelay(failures: number): number;
+export declare function reconcileTurnFailureObservers(): void;
+export declare function superviseTurnFailures(intervalMs?: number): void;
+export declare function assertProjectMatch(verb: string): Promise<void>;
+export type SessionCreateFailureCode = 'session_create_timeout' | 'session_create_cancelled' | 'session_create_failed' | 'session_create_cleanup_failed' | 'session_create_key_reused';
+type SessionCreateFailureStatus = 400 | 408 | 409 | 500 | 504;
+type SessionCreatePhase = 'request' | 'creation-lock' | 'launcher-resolution' | 'target-resolution' | 'git-worktree' | 'materialize' | 'record-write' | 'launcher-queue' | 'cleanup';
+export declare class SessionCreateError extends Error {
+    readonly code: SessionCreateFailureCode;
+    readonly phase: SessionCreatePhase;
+    readonly status: SessionCreateFailureStatus;
+    constructor(code: SessionCreateFailureCode, phase: SessionCreatePhase, message: string, status: SessionCreateFailureStatus);
+}
+type SessionCreateRequestOptions = {
+    requestKey?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export type SessionCreateRequestResult = {
+    status: 201;
+    session: Session;
+} | {
+    status: SessionCreateFailureStatus;
+    error: string;
+    code?: SessionCreateFailureCode;
+    phase?: SessionCreatePhase;
+};
+export declare function sessionCreateTimeoutMs(env?: NodeJS.ProcessEnv): number;
+export declare function sessionIdForCreateKey(key: string): string;
+export declare function sessionCreateRequest(body: unknown, options?: SessionCreateRequestOptions): Promise<SessionCreateRequestResult>;
+export declare function createSession(prompt: string, launcher?: string, name?: string, base?: string): Promise<Session>;
+export declare function spawnerClause(p: SessRec | null): string;
+export declare function pendingSessionCreateWorktreePaths(): Set<string>;
+export declare function bootstrapMaterialize(rec: SessRec, doMaterialize?: (proj: string) => unknown): void;
+type ResumeOptions = {
+    force?: boolean;
+    guard?: boolean;
+};
+export declare const resumeSession: (id: string, opts?: ResumeOptions) => Promise<{
+    ok: boolean;
+    error?: string;
+    refused?: boolean;
+    info?: string;
+}>;
+export declare function markState(status: Lifecycle, opts?: {
+    proposal?: Proposal;
+    note?: string;
+    sessionId?: string;
+}): boolean;
+export declare const markDone: (proposal?: Proposal, sessionId?: string, note?: string) => boolean;
+export declare const markError: (sessionId?: string) => boolean;
+export declare function markTurnFailure(sessionId: string | undefined, note: string): boolean;
+export declare function markHeadlessTurnFailure(sessionId: string, harness: string, exitCode: string): boolean;
+export declare function markHarnessSessionId(sessionId: string | undefined, harnessSessionId: string | undefined): boolean;
+export declare function markIdle(sessionId?: string): boolean;
+export declare function mergeReadiness(proposal?: 'merge' | 'nothing'): {
+    ready: boolean;
+    reason?: string;
+};
+export type ReviewEvalFacts = {
+    freshPass: number;
+    freshFail: number;
+    needReview: number;
+    blind: number;
+};
+export type ReviewEvalGate = ({
+    phase: 'ready';
+} & ReviewEvalFacts) | {
+    phase: 'unavailable' | 'loading' | 'updating' | 'error';
+};
+export type ReviewGates = {
+    conflictsWithMain: boolean;
+    lint: {
+        errorCount: number;
+        warningCount: number;
+    };
+};
+export type ReviewPayload = {
+    id: string;
+    node: string | null;
+    branch: string | null;
+    label: string;
+    ahead: number;
+    dirtyNonRuntime: number;
+    diff: ReviewDiffFile[];
+    gates: ReviewGates;
+    proposal: {
+        kind: Proposal | null;
+        note: string | null;
+    };
+};
+export declare function reviewPayload(id: string): Promise<ReviewPayload | null>;
+export type MergeSessionResult = {
+    dispatched: true;
+} | {
+    dispatched: false;
+    reason: string;
+    code?: 'session_merge_not_proposed';
+    status?: 409;
+};
+export declare function mergeSession(id: string): Promise<MergeSessionResult>;
+export declare const stopSession: (id: string) => Promise<boolean>;
+export declare const archiveSession: (id: string, on?: boolean) => Promise<boolean>;
+export declare const closeSession: (id: string, rawSource?: unknown) => Promise<boolean>;
+export type CorruptRecordQuarantineWitness = {
+    adapter: string;
+    thread: string | null;
+    tmux: string;
+    worktree: string;
+    branch: string;
+};
+export type CorruptRecordQuarantineResult = {
+    id: string;
+    bundle: string;
+    sha256: string;
+    observedAt: string;
+};
+export declare function quarantineCorruptRecord(id: string, rawWitness: unknown): Promise<CorruptRecordQuarantineResult>;
+export declare function restoreQuarantinedRecord(id: string): Promise<CorruptRecordQuarantineResult>;
+export type CaptureResult = {
+    ok: true;
+    pane: string;
+} | {
+    ok: false;
+    reason: 'unknown' | 'offline' | 'capture-failed';
+};
+export declare function captureSessionResult(id: string): Promise<CaptureResult>;
+export declare const STATUS_GLYPH: Record<DisplayStatus, string>;
+export declare function matchesSelector(s: Session, q: string, own?: string | null, cwd?: string): boolean;
+export declare function selectSessions(all: Session[], selectors: string[], statuses?: string[], own?: string | null, cwd?: string): Session[];
+export declare function selectChildren(all: Session[], parent: string): Session[];
+export type Resolved = {
+    ok: Session;
+} | {
+    ambiguous: Session[];
+} | {
+    none: true;
+};
+export declare function resolveSession(selector: string, sessions: Session[], own?: string | null, cwd?: string): Resolved;
+export declare function displayWidth(s: string): number;
+export declare function truncWidth(s: string, max: number): string;
+export declare const padWidth: (s: string, w: number) => string;
+export declare const NOTE_BOARD_LIMIT = 50;
+export declare function statusLegend(color?: boolean): string;
+export type SessionTableScope = {
+    kind: 'sessions';
+} | {
+    kind: 'children';
+    parent: string;
+};
+export declare function formatTable(sessions: Session[], color?: boolean, scope?: SessionTableScope): string;
+type DispatchIdempotency = SentDispatchReceipt;
+type DispatchAcceptCode = 'dispatch_key_reused' | 'session_merge_not_proposed';
+type AcceptedDispatch = DispatchResult & {
+    replayed?: boolean;
+    code?: DispatchAcceptCode;
+};
+type SendTextOptions = {
+    replyVia?: 'note';
+    idempotency?: DispatchIdempotency;
+    acceptGuard?: (record: SessRec) => Promise<void>;
+    deferDrain?: boolean;
+};
+export declare function sendText(id: string, text: string, from?: string, opts?: SendTextOptions): Promise<AcceptedDispatch>;
+export declare function drainSession(id: string): Promise<void>;
+export declare function interruptSession(id: string): Promise<DispatchResult>;
+export declare function rawKey(id: string, key: string | string[]): Promise<boolean>;