@shawnowen/comet-mcp 2.3.1 → 2.4.2

package/dist/window-bindings.d.ts

@@ -0,0 +1,160 @@
+export type CodexBindingStatus = "active" | "completed" | "stale" | "reaped" | "conflict";
+export type CodexSessionRole = "session_agent" | "worktree_orchestrator" | "fleet_orchestrator";
+export type ProfileOwnershipDomain = "agent" | "human" | "shared_legacy" | "unknown";
+export interface CodexSessionIdentity {
+    codexSessionId: string;
+    projectThreadId: string;
+    projectThreadFamily?: string;
+    worktreePath: string;
+    repoSlug: string;
+    branchName: string;
+    sessionKey: string;
+    role: CodexSessionRole;
+}
+export interface CodexIdentityInput {
+    codexSessionId?: string;
+    projectThreadId?: string;
+    projectThreadFamily?: string;
+    worktreePath?: string;
+    repoSlug?: string;
+    branchName?: string;
+    sessionKey?: string;
+    role?: string;
+    strict?: boolean;
+    fallbackAgentId?: string;
+    fallbackTaskThreadId?: string;
+}
+export interface CodexIdentityContext {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}
+export interface CodexWindowBinding extends CodexSessionIdentity {
+    bindingId: string;
+    runIds: string[];
+    windowId: number;
+    tabGroupId: number | null;
+    targetId: string | null;
+    profileId: string;
+    profileAlias: string | null;
+    profileOwner: ProfileOwnershipDomain;
+    sidecarContextKey: string;
+    status: CodexBindingStatus;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * ISO 8601 timestamp first recorded when a reap cycle found this binding's
+     * window absent from the live CDP set. Cleared when the window reappears.
+     * Drives the TTL grace period in {@link CodexWindowBindingStore.reapExpiredBindings}.
+     * Optional/absent on pre-existing records (backward-compatible).
+     */
+    missingSince?: string;
+}
+export interface RunBindingIndexEntry {
+    runId: string;
+    bindingId: string;
+    updatedAt: string;
+}
+export interface WindowBindingSnapshot {
+    version: 1;
+    bindings: Record<string, CodexWindowBinding>;
+    runBindingIndex: Record<string, RunBindingIndexEntry>;
+    updatedAt: string;
+}
+export interface CreateBindingInput extends CodexSessionIdentity {
+    windowId: number;
+    tabGroupId?: number | null;
+    targetId?: string | null;
+    profileId?: string;
+    profileAlias?: string | null;
+    profileOwner?: ProfileOwnershipDomain;
+    runIds?: string[];
+    sidecarContextKey?: string;
+}
+export interface CreateOrReuseResult {
+    binding: CodexWindowBinding;
+    action: "created" | "reused" | "repaired";
+}
+export interface BindingMutationOptions {
+    targetBindingId?: string;
+    reason?: string;
+    audit?: boolean;
+}
+/** Options for {@link CodexWindowBindingStore.reapExpiredBindings}. */
+export interface ReapOptions {
+    /** Distinct windowIds currently live in the browser (CDP). */
+    liveWindowIds: Iterable<number>;
+    /** Grace period in ms a binding may stay missing before it is reaped. */
+    ttlMs: number;
+    /** Injectable clock (ms epoch). Defaults to Date.now(). */
+    now?: number;
+    /**
+     * Archive callback invoked BEFORE a binding is deleted (e.g. recovery
+     * snapshot + ORPHAN_REAPED alert). If it throws, the binding is NOT deleted
+     * that cycle (fail-safe).
+     */
+    archive?: (binding: CodexWindowBinding) => Promise<void>;
+    /**
+     * Predicate for profile-owned bindings the auto-reaper must skip.
+     * Default: profileOwner is set and not "agent".
+     */
+    isProfileOwned?: (binding: CodexWindowBinding) => boolean;
+}
+/** Per-cycle counts returned by {@link CodexWindowBindingStore.reapExpiredBindings}. */
+export interface ReapCycleResult {
+    evaluated: number;
+    newlyMissing: number;
+    retainedLive: number;
+    reaped: number;
+    skippedOwned: number;
+    reapedBindingIds: string[];
+}
+export declare class WindowBindingConflictError extends Error {
+    readonly conflicts: CodexWindowBinding[];
+    constructor(message: string, conflicts: CodexWindowBinding[]);
+}
+export declare class CodexIdentityError extends Error {
+    readonly missingFields: string[];
+    constructor(message: string, missingFields: string[]);
+}
+export declare function resolveCodexSessionRole(role?: string): CodexSessionRole;
+export declare function deriveCodexSessionIdentity(input?: CodexIdentityInput, context?: CodexIdentityContext): CodexSessionIdentity;
+export declare function isBindingInWorktreeScope(caller: CodexSessionIdentity, binding: CodexWindowBinding): boolean;
+export declare function canReadBinding(caller: CodexSessionIdentity, binding: CodexWindowBinding): boolean;
+export declare function canMutateBinding(caller: CodexSessionIdentity, binding: CodexWindowBinding, options?: BindingMutationOptions): boolean;
+export declare function assertBindingMutationAllowed(caller: CodexSessionIdentity, binding: CodexWindowBinding, options?: BindingMutationOptions): void;
+export declare function normalizeProfileOwner(owner?: string): ProfileOwnershipDomain;
+export declare function assertBindingProfileAllowed(identity: CodexSessionIdentity, binding: Pick<CodexWindowBinding, "profileId" | "profileOwner">): void;
+export declare class CodexWindowBindingStore {
+    private readonly file;
+    private readonly dir;
+    private readonly lockDir;
+    constructor(storePath?: string);
+    get path(): string;
+    load(): Promise<WindowBindingSnapshot>;
+    list(): Promise<CodexWindowBinding[]>;
+    get(bindingId: string): Promise<CodexWindowBinding | null>;
+    findActiveByIdentity(identity: CodexSessionIdentity): Promise<CodexWindowBinding | null>;
+    findByRunId(runId: string): Promise<CodexWindowBinding | null>;
+    createOrReuse(input: CreateBindingInput): Promise<CreateOrReuseResult>;
+    addRunId(bindingId: string, runId: string): Promise<CodexWindowBinding>;
+    transition(bindingId: string, status: Exclude<CodexBindingStatus, "conflict">): Promise<CodexWindowBinding>;
+    transitionByRunId(runId: string, status: Exclude<CodexBindingStatus, "conflict">): Promise<CodexWindowBinding | null>;
+    classifyConflicts(): Promise<CodexWindowBinding[]>;
+    markStaleForMissingWindows(liveWindowIds: Iterable<number>): Promise<CodexWindowBinding[]>;
+    /**
+     * Reconcile every binding against the live window set and reap (delete) those
+     * whose window has been missing for at least {@link ReapOptions.ttlMs}.
+     *
+     * - Window live → clear `missingSince`, reactivate if the reaper marked it stale, retain.
+     * - Window missing, no `missingSince` → record `missingSince=now`, mark stale, retain (grace starts).
+     * - Window missing ≥ TTL, profile-owned → skip.
+     * - Window missing ≥ TTL, not owned → `archive()` then delete.
+     *
+     * Atomic + file-locked + idempotent. A no-op when nothing needs changing.
+     */
+    reapExpiredBindings(opts: ReapOptions): Promise<ReapCycleResult>;
+    private assertNoActiveConflicts;
+    private findActiveConflicts;
+}
+export declare const windowBindingStore: CodexWindowBindingStore;
+//# sourceMappingURL=window-bindings.d.ts.map