@sayknow-cli/coding-agent 0.4.2 → 0.4.3

package/dist/types/sdk/bus/index.d.ts

@@ -0,0 +1,508 @@
+/**
+ * Notifications extension.
+ *
+ * Hosts a per-session loopback WebSocket notification server (the Rust core via
+ * N-API) and bridges SKC session events + the `ask` tool to it so a remote client
+ * (e.g. a Telegram bot) can both see action-needed signals and answer them
+ * through SDK-native session capabilities:
+ *
+ * - `ask` (interactive): registers an {@link AskAnswerSource}; the ask tool races
+ *   the local UI against a remote reply. First valid answer wins; a local answer
+ *   aborts the remote wait (and broadcasts `action_resolved` resolvedBy=local).
+ * - `ask` (workflow gate): observes emitted workflow gates and resolves the real
+ *   gate on a remote reply via `ctx.workflowGate`.
+ * - `turn_end` -> `action_needed` (kind `idle`, deduped per turn).
+ * - `session_shutdown` -> `session_closed` frame, stop server, deregister answer source.
+ *
+ * Enable with Settings notifications config, `SKC_NOTIFICATIONS=1` (a token is
+ * generated), or `SKC_NOTIFICATIONS_TOKEN`.
+ */
+import type { Tool } from "@sayknow-cli/ai";
+import { NotificationServer } from "@sayknow-cli/natives";
+import { Settings } from "../../config/settings";
+import type { ExtensionAPI, ExtensionContext } from "../../extensibility/extensions";
+import { type WorkflowGateEmitter, type WorkflowGateTerminalProof } from "../../modes/shared/agent-wire/workflow-gate-broker";
+import type { AgentSessionEvent } from "../../session/agent-session";
+import type { AskAnswerSourceResult, AskRemoteControl } from "../../tools";
+import { SessionSdkHost } from "../host";
+import { CursorRegistry, RevisionStore } from "../host/query";
+import { type SdkStartupFailure } from "../startup-capability";
+import { type NotificationConfig } from "./config";
+import { NotificationSessionController } from "./session-control";
+import { type EnsureDaemonResult } from "./telegram-daemon";
+/** Where a `session_create` should run. Discriminated by `kind`. */
+export type SessionCreateTarget = {
+    kind: "existing_path";
+    path: string;
+} | {
+    kind: "worktree";
+    repo: string;
+    branch: string;
+} | {
+    kind: "plain_dir";
+    path: string;
+};
+/** Identifies the session a `session_close` targets. */
+export interface SessionCloseTarget {
+    sessionId: string;
+    /** Expected SKC-managed tmux session name (defense-in-depth match). */
+    tmuxSession?: string;
+    /** Expected `@skc-session-state-file` tag (defense-in-depth match). */
+    sessionStateFile?: string;
+}
+/** Identifies the session a `session_resume` targets. */
+export interface SessionResumeTarget {
+    sessionIdOrPrefix: string;
+    /** Optional repo/working-dir hint to disambiguate matches. */
+    path?: string;
+}
+/** Create a new session. */
+export interface SessionCreateFrame {
+    type: "session_create";
+    requestId: string;
+    /** Deterministic lifecycle marker preallocated by the daemon before spawn. */
+    lifecycleRequestId: string;
+    /** Session id the daemon preallocated and propagates to the child. */
+    intendedSessionId: string;
+    /** Telegram update id (idempotency key on the daemon side). */
+    updateId: number;
+    chatId: string;
+    /** Control-endpoint token authorizing this frame. */
+    token: string;
+    target: SessionCreateTarget;
+    /** Reserved for a future capability transport; any supplied value is rejected before lifecycle acceptance. */
+    startupPromptRef?: string;
+    /** Model profile preset to activate for the spawned session (--mpreset). */
+    modelPreset?: string;
+}
+/** Close (hard-kill, history preserved) a session. */
+export interface SessionCloseFrame {
+    type: "session_close";
+    requestId: string;
+    updateId: number;
+    chatId: string;
+    token: string;
+    target: SessionCloseTarget;
+    /** Required force-only close flag; false/omitted is rejected by daemon policy. */
+    force?: boolean;
+}
+/** Resume a session (reattach if alive, else cold-restart from history). */
+export interface SessionResumeFrame {
+    type: "session_resume";
+    requestId: string;
+    updateId: number;
+    chatId: string;
+    token: string;
+    target: SessionResumeTarget;
+    /** Reserved for a future capability transport; any supplied value is rejected before lifecycle acceptance. */
+    startupPromptRef?: string;
+}
+/** Any client -> ingress lifecycle request frame. */
+export type SessionLifecycleRequest = SessionCreateFrame | SessionCloseFrame | SessionResumeFrame;
+/** Terminal status of a lifecycle request. */
+export type LifecycleStatus = "ok" | "error";
+/** A connected session's per-session endpoint, returned to the control client. */
+export interface LifecycleEndpoint {
+    url: string;
+    token: string;
+}
+/** The Telegram topic/thread a session is surfaced in. */
+export interface LifecycleTopic {
+    chatId: string;
+    threadId: string;
+}
+/** How a create request was correlated to its spawned session. */
+export type MatchedBy = "spawn_marker" | "session_ready";
+/** Response to a successful `session_create`. */
+export interface SessionCreateResponseFrame {
+    type: "session_create_response";
+    requestId: string;
+    status: LifecycleStatus;
+    lifecycleRequestId: string;
+    sessionId: string;
+    matchedBy: MatchedBy;
+    endpoint: LifecycleEndpoint;
+    topic: LifecycleTopic;
+    target: SessionCreateTarget;
+}
+/** Response to a successful `session_close`. */
+export interface SessionCloseResponseFrame {
+    type: "session_close_response";
+    requestId: string;
+    status: LifecycleStatus;
+    sessionId: string;
+    processGone: boolean;
+    historyPreserved: boolean;
+    endpointStale: boolean;
+}
+/** Whether a resume reattached to a live session or cold-restarted a dead one. */
+export type ResumeMode = "reattached" | "cold_restarted";
+/** Response to a successful `session_resume`. */
+export interface SessionResumeResponseFrame {
+    type: "session_resume_response";
+    requestId: string;
+    status: LifecycleStatus;
+    sessionId: string;
+    mode: ResumeMode;
+    endpoint: LifecycleEndpoint;
+    topic: LifecycleTopic;
+}
+/** Machine-readable reason a lifecycle request failed. */
+export type LifecycleErrorReason = "unauthorized" | "rate_limited" | "duplicate_conflict" | "invalid_target" | "ambiguous_target" | "spawn_failed" | "discovery_timeout" | "readiness_timeout" | "close_refused" | "not_found" | "terminal_uncertain" | "unsupported_platform";
+/** A candidate returned with an `ambiguous_target` resume error. */
+export interface ResumeCandidate {
+    sessionId: string;
+    path?: string;
+    /** Last-activity epoch-millis (session history file mtime), if known. */
+    mtimeMs?: number;
+}
+/** A structured lifecycle error frame. */
+export interface SessionLifecycleErrorFrame {
+    type: "session_lifecycle_error";
+    requestId: string;
+    status: LifecycleStatus;
+    reason: LifecycleErrorReason;
+    message: string;
+    candidates?: ResumeCandidate[];
+}
+/** Any ingress -> client lifecycle response frame. */
+export type SessionLifecycleResponse = SessionCreateResponseFrame | SessionCloseResponseFrame | SessionResumeResponseFrame | SessionLifecycleErrorFrame;
+/**
+ * Replayable per-session readiness signal (mirror of the Rust `session_ready`
+ * frame). Buffered and replayed to late clients so WS-open alone never implies
+ * the session is live and surfaced.
+ */
+export interface SessionReadyFrame {
+    type: "session_ready";
+    sessionId: string;
+    lifecycleRequestId?: string;
+    startupPromptRef?: string;
+    repo?: string;
+    branch?: string;
+    title?: string;
+}
+/**
+ * Best-effort real repository name (no git spawn): resolves the main worktree
+ * root directory so linked worktrees report the repo (e.g. `sayknow-cli`)
+ * instead of the worktree directory (e.g. `feat-foo-01047f11`).
+ */
+export declare function readGitRepoName(cwd: string): string | undefined;
+interface PendingInteractiveAsk {
+    resolve: (result: AskAnswerSourceResult) => void;
+    options: string[];
+    controls: readonly AskRemoteControl[];
+    actionId?: string;
+    retireForDirectControl: () => RetireStatus;
+    reissue: () => boolean;
+    complete: (actionId: string) => void;
+    completeDirect: () => void;
+    fail: (actionId: string) => void;
+}
+interface UnattendedGatePresentation {
+    gateId: string;
+    sessionId: string;
+    question: string;
+    options: string[];
+    controls: readonly AskRemoteControl[];
+    multi: boolean;
+    allowEmpty: boolean;
+    navigationLabel?: "Next" | "Done";
+    selectedOptions: string[];
+    workflowGateId?: string;
+    onActivated?: (actionId: string, lease: {
+        actionId: string;
+        registrationEpoch: number;
+    }) => void;
+    onClosed?: () => void;
+}
+type RetireStatus = "retired" | "already_terminal" | "claimed" | "stale";
+type DirectControlOutcome = "accepted" | "rejected" | "unknown";
+export declare class PresentationArbiter {
+    #private;
+    private readonly server;
+    private readonly redact;
+    private readonly tag;
+    private readonly presentations;
+    private readonly routes;
+    private active;
+    private readonly queue;
+    private readonly retries;
+    private readonly retiredProofs;
+    private readonly directControls;
+    /** Explicit terminal proof for a direct control fenced before native publication. */
+    private readonly queuedDirectControls;
+    private retryTimer;
+    private retryTimerGateId;
+    private retryTimerGeneration;
+    private readonly terminalCancellationTimers;
+    private headGeneration;
+    private observedHead;
+    static readonly maxRegistrationAttempts = 3;
+    static readonly retryBaseDelayMs = 50;
+    static readonly retryMaxDelayMs = 1000;
+    /** Bound an unavailable interactive answer source without discarding its head silently. */
+    static readonly terminalCancellationDelayMs = 250;
+    /** Revalidates the live endpoint queue head before bounded recovery. */
+    reconcile(): void;
+    /** Explicit production recovery for a previously exhausted endpoint queue head. */
+    recover(gateId?: string): void;
+    hasActivePresentation(): boolean;
+    retireForDirectControl(gateId: string): RetireStatus;
+    prepareDirectControl(gateId: string): {
+        status: "retired" | "queued";
+        ordinal: number;
+    } | {
+        status: "claimed" | "stale";
+    };
+    finishDirectControl(gateId: string, prepared: {
+        status: "retired" | "queued";
+        ordinal: number;
+    }, outcome: DirectControlOutcome): void;
+    constructor(server: NotificationServer, redact: () => boolean, tag: string);
+    retain(presentation: UnattendedGatePresentation): void;
+    routeFor(actionId: string): string | undefined;
+    presentationFor(actionId: string): UnattendedGatePresentation | undefined;
+    /** The native generic claim has already resolved this old action. */
+    toggle(actionId: string, label: string): boolean;
+    /** Clears an interactive route only when it is still the route that settled. */
+    completeInteractive(gateId: string, actionId: string): void;
+    /** Clears an interactive presentation after its route was retired for direct control. */
+    completeDirect(gateId: string): void;
+    reissueAfterFailure(actionId: string): void;
+    reissue(gateId: string): string | undefined;
+    closeInteraction(actionId: string, reason: string): boolean;
+    complete(gateId: string): WorkflowGateTerminalProof;
+    cancelInteractive(): void;
+    cancel(gateId: string, reason: string): void;
+    dispose(): void;
+}
+interface SessionRuntime {
+    server: NotificationServer;
+    host: SessionSdkHost;
+    /** Owns stateRoot-backed revisions and removes their spills on terminal shutdown. */
+    revisions: RevisionStore;
+    /** Releases all snapshot pins before the revision store is closed. */
+    cursors: CursorRegistry;
+    /** Current endpoint session identity; never re-key an existing host across a switch. */
+    id: string;
+    idleSeq: number;
+    /** Interactive asks awaiting a remote answer, by action id. */
+    pendingInteractive: Map<string, PendingInteractiveAsk>;
+    /** Deregisters this session's ask answer source. */
+    disposeAnswerSource: () => void;
+    /** Deregisters this session's Telegram file sink. */
+    disposeFileSink: () => void;
+    /** Deregisters this session's workflow-gate listener. */
+    disposeGateListener: () => void;
+    /** Whether notification-only delivery and answer resources are active. */
+    notificationsActive: boolean;
+    /** Set as soon as terminal teardown is requested, before startup settles. */
+    stopping: boolean;
+    /** Recreates notification-only resources after `/notify on`. */
+    enableNotifications: () => void;
+    /** Deregisters canonical workflow-gate terminal cleanup. */
+    disposeGateTerminalController: () => void;
+    disposeAckRecoveryParticipant: () => void;
+    disposeGateEmitterListener: () => void;
+    /** Aborts and fences side turns while notification delivery is disabled. */
+    disableEphemeralTurns: () => void;
+    waitForGateResolutionQuiescence: () => Promise<void>;
+    trackGateResolution: <T>(resolution: Promise<T>) => Promise<T>;
+    workflowGate?: WorkflowGateEmitter;
+    gatePresentations?: PresentationArbiter;
+    redact: boolean;
+    /** Last stable policy's redaction state, retained while provisional policy is held. */
+    committedRedact: boolean;
+    /** Provisional policy suppresses delivery without changing committed-side effects. */
+    policySuspended: boolean;
+    /** Monotonic policy epoch fences asynchronous notification delivery. */
+    policyGeneration: number;
+    /** True only after the exact host generation was registered with the broker index. */
+    brokerRegistrationActive: boolean;
+    /** Terminal cleanup proof retained across retries; each owner is released at most once after proof. */
+    hostStopped: boolean;
+    serverStopped: boolean;
+    brokerRegistrationReleased: boolean;
+    verbosity: "lean" | "verbose";
+    sessionTag: string;
+    /** Whether the agent loop is currently running (drives the typing indicator). */
+    busy: boolean;
+    /** Prompt command/turn identities awaiting their corresponding agent_start. */
+    pendingPromptCorrelations: Array<{
+        commandId: string;
+        turnId: string;
+    }>;
+    /** Identity bound to the agent lifecycle currently in flight. */
+    activePromptCorrelation?: {
+        commandId: string;
+        turnId: string;
+    };
+    /** Records a correlated prompt terminal boundary after agent unwind. */
+    /** Atomically claims a correlated prompt terminal boundary after agent unwind. */
+    recordPromptTerminal: (correlation: {
+        commandId: string;
+        turnId: string;
+    } | undefined) => boolean;
+    /** Records correlated lifecycle frames for replay and delivers them only to the accepted requester after acknowledgement. */
+    emitPromptLifecycle: (correlation: {
+        commandId: string;
+        turnId: string;
+    } | undefined, frame: {
+        type: "agent_start" | "agent_end";
+        sessionId: string;
+        commandId?: string;
+        turnId?: string;
+    } | {
+        type: "agent_failed";
+        sessionId: string;
+        commandId: string;
+        turnId: string;
+        error: {
+            code: string;
+            message: string;
+        };
+    }) => void;
+    /** Publishes one canonical agent-wire event to the client that owns the active prompt. */
+    emitPromptEvent: (event: AgentSessionEvent) => void;
+    /** Inbound Telegram update ids injected but not yet consumed by a turn. */
+    pendingInbound: Set<number>;
+    /** Latest assistant text of the in-flight turn (from message_update). */
+    currentTurnText?: string;
+    /** Assistant text already flushed before an ask this turn (turn-scoped dedupe
+     * so turn_end does not re-emit the pre-ask lead-in). Reset each turn. */
+    preAskFlushedText?: string;
+    /** Live streaming: opt-in flag, monotonic per-turn ref, and emit throttle state. */
+    stream: boolean;
+    turnSeq?: number;
+    liveRef?: string;
+    lastLiveAt?: number;
+    lastLiveText?: string;
+    /** True between turn_end and the next turn_start: drops late async message_update
+     * frames so a stale live edit can never be emitted after the finalized turn. */
+    turnClosed?: boolean;
+    /** Finalized while provisional policy was held; flush exactly once on stable activation. */
+    pendingFinal?: {
+        text?: string;
+        messageRef?: string;
+    };
+    /** Durable gates emitted while ownership is provisional; presented only after stable activation. */
+    deferredGatePresentations: Array<() => void>;
+    /** SDK control frames received during provisional ownership; replayed only after stable activation. */
+    deferredInboundControls: Array<() => void>;
+    /** Started tool calls awaiting a terminal activity frame, keyed by tool call id. */
+    inFlightTools: Map<string, {
+        toolName: string;
+        args: unknown;
+    }>;
+    /** Cancels the postmortem cleanup that emits `session_closed` on process teardown. */
+    cancelPostmortemCleanup: () => void;
+    /** Disposes side-turn resources when their owning logical session becomes unavailable. */
+    abortEphemeralTurns: () => void;
+}
+/** Stable projection of the tool-owned safe-display seam (never the full Tool surface). */
+type SafeSummaryTool = Pick<Tool, "safeSummary" | "safeSummaryFields">;
+export declare function projectToolSummary(tool: SafeSummaryTool | undefined, kind: "args" | "result", value: unknown): string | undefined;
+type SessionStartStatus = "started" | "already" | "disabled" | "failed";
+type SessionStartResult = {
+    status: SessionStartStatus;
+    runtime?: SessionRuntime;
+    failure?: SdkStartupFailure;
+    suppressExtensionError?: boolean;
+};
+export declare function notificationsEnabled(): boolean;
+/** Workflow-gate answer shape. */
+interface GateAnswer {
+    selected: string[];
+    other?: boolean;
+    custom?: string;
+}
+/**
+ * Discriminated result of mapping a client answer to a workflow-gate answer.
+ * `ok: false` means the reply is invalid and the caller must close the exact
+ * claim/receipt and reissue the interaction rather than durably accepting it.
+ */
+type GateAnswerResult = {
+    ok: true;
+    answer: GateAnswer;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Map a client answer to the workflow-gate answer shape.
+ *
+ * The protocol defines a numeric reply as an option index, so a number outside
+ * `options` is invalid: it must NOT be converted into free text that passes the
+ * ask schema and triggers a misleading success acknowledgement.
+ * Only JSON strings enter the free-text/Other path.
+ */
+export declare function mapAnswerToGate(answerJson: string, options: string[]): GateAnswerResult;
+interface NotificationControlCommandPayload {
+    name?: unknown;
+    action?: unknown;
+    level?: unknown;
+    global?: unknown;
+    selector?: unknown;
+    instructions?: unknown;
+}
+export interface NotificationControlCommandResult {
+    status: "ok" | "error" | "unavailable";
+    message: string;
+    modelChoices?: Array<{
+        selector: string;
+        label: string;
+    }>;
+}
+export declare function executeNotificationControlCommand(command: NotificationControlCommandPayload | undefined, ctx: ExtensionContext, api: ExtensionAPI, expectedSessionId?: string): Promise<NotificationControlCommandResult>;
+interface EphemeralTurnAuthority {
+    sessionId: string;
+    endpointDigest: string;
+    eventGeneration: number;
+}
+/** Host-owned, bounded idempotency and cancellation lifecycle for v3 side turns. */
+export declare class EphemeralTurnHost {
+    #private;
+    constructor(sendTo: (connectionId: string, frame: Record<string, unknown>) => void, execute: (question: string, signal: AbortSignal) => Promise<{
+        replyText: string;
+    }>, now?: () => number);
+    configureAuthority(authority: EphemeralTurnAuthority): void;
+    disable(): void;
+    enable(): void;
+    dispose(): void;
+    handle(connectionId: string, frame: Record<string, unknown>): boolean;
+    sessionUnavailable(sessionId: string): void;
+    /** Testable event-ring eviction boundary; tombstones remain idempotency authority. */
+    evictTerminalEvents(): void;
+}
+/**
+ * Ensures every configured chat-provider daemon is ready before the SDK
+ * publishes session identity. A rejected ensure is startup-fatal: presenting
+ * an identity for a transport that never became available is false success.
+ */
+export declare function ensureConfiguredProviderDaemons(settings: Settings, cfg: NotificationConfig, ensureProviderDaemon?: (provider: "discord" | "slack", settings: Settings) => Promise<unknown>): Promise<void>;
+export declare function createNotificationsExtension(api: ExtensionAPI, options?: {
+    settings?: Settings;
+    ensureTelegramDaemon?: (input: {
+        settings: Settings;
+        cwd: string;
+        sessionId: string;
+    }) => Promise<EnsureDaemonResult>;
+    ensureProviderDaemon?: (provider: "discord" | "slack", settings: Settings) => Promise<unknown>;
+    /** Suppress auto-delivery for a SKC-spawned child under `sessionScope=primary`. */
+    spawnedBySkc?: boolean;
+    controller?: NotificationSessionController;
+    /** Whether this host mode can own the root SDK endpoint. Default: true. */
+    sdkHostModeSupported?: boolean;
+    onSdkRequest?: (kind: "control" | "query", connectionId: string, frame: Record<string, unknown>) => void;
+    runEphemeralTurn?: (promptText: string, signal: AbortSignal) => Promise<{
+        replyText: string;
+    }>;
+    /** Observes settlement of optional session-branch startup after reconciliation completes. */
+    onBranchStartupSettled?: (receipt: {
+        sessionId: string;
+        status: SessionStartResult["status"];
+    }) => void;
+    readNotificationFile?: (path: string) => Promise<Buffer>;
+    readNotificationDiffStat?: (cwd: string) => Promise<string | undefined>;
+}): void;
+export {};

package/dist/types/sdk/bus/lifecycle-commands.d.ts

@@ -0,0 +1,69 @@
+import type { SessionCloseTarget, SessionCreateTarget, SessionLifecycleResponse, SessionResumeTarget } from "./index";
+export type LifecycleCommandVerb = "session_create" | "session_close" | "session_resume";
+/** A parsed, validated lifecycle command (transport identity added by caller). */
+export type ParsedLifecycleCommand = {
+    kind: "create";
+    target: SessionCreateTarget;
+    modelPreset?: string;
+} | {
+    kind: "close";
+    target: SessionCloseTarget;
+} | {
+    kind: "resume";
+    target: SessionResumeTarget;
+} | {
+    kind: "recent";
+    which: "create" | "resume" | "all";
+} | {
+    kind: "usage";
+    message: string;
+} | {
+    kind: "reject";
+    reason: "invalid_target" | "prompt_unsupported";
+    message: string;
+} | {
+    kind: "none";
+};
+/** True when the text begins with any /session_* token, regardless of addressability. */
+export declare function isLifecycleCommandLikeText(text: string | undefined): boolean;
+/** True when the text begins an addressable /session_* command (cheap pre-gate). */
+export declare function isLifecycleCommandText(text: string | undefined, ctx?: {
+    chatType?: string;
+    botUsername?: string;
+}): boolean;
+/**
+ * Parse a paired-chat message into a lifecycle command. Returns `none` for
+ * non-lifecycle text, `usage`/`reject` for malformed input (no side effect), or
+ * a validated `create`/`close`/`resume`/`recent` intent.
+ *
+ * The caller MUST have already enforced paired-chat authorization; this function
+ * performs grammar + target validation only.
+ */
+export declare function parseLifecycleCommand(text: string | undefined, ctx?: {
+    chatType?: string;
+    botUsername?: string;
+}): ParsedLifecycleCommand;
+/** The canonical usage text (exported for the daemon's help replies). */
+export declare function lifecycleUsage(): string;
+/**
+ * Shared target validator reused at the policy/effect boundary (after paired-chat
+ * auth, before any side effect). Returns null when valid, or an `invalid_target`
+ * reason. The orchestrator remains authoritative; this is a defensive pre-check
+ * the parser and any other entry point share.
+ */
+export declare function validateLifecycleTarget(verb: LifecycleCommandVerb, target: SessionCreateTarget | SessionCloseTarget | SessionResumeTarget): {
+    ok: true;
+} | {
+    ok: false;
+    reason: "invalid_target";
+    message: string;
+};
+export declare function normalizeLifecyclePath(value: string): string | undefined;
+/**
+ * Map a lifecycle response/error to a user-facing Telegram message (G010).
+ *
+ * Only derives text from sessionId, mode, reason, a safe message, and candidate
+ * {sessionId,path} — never a token or prompt. Each error reason gets tailored,
+ * actionable copy; an "in progress" pending response is surfaced distinctly.
+ */
+export declare function formatLifecycleOutcome(r: SessionLifecycleResponse): string;

package/dist/types/sdk/bus/lifecycle-control-runtime.d.ts

@@ -0,0 +1,113 @@
+import { type OwnerIsolationProbe } from "../../skc-runtime/tmux-owner-isolation";
+import { type SkcTmuxSessionStatus } from "../../skc-runtime/tmux-sessions";
+import type { ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest, SessionLifecycleResponse } from "./index";
+import { type AuditEvent, type CreateEffectResult, type LedgerStore, type LifecycleOutcome, type OrchestratorDeps, type ResumeEffectResult } from "./lifecycle-orchestrator";
+/** Minimal view of the native control server this runtime depends on. */
+export interface ControlServerLike {
+    onLifecycleRequest(cb: (err: Error | null, req: {
+        kind: string;
+        requestId: string;
+        payloadJson: string;
+    }) => void): void;
+    respond(responseJson: string): void;
+}
+/**
+ * A startable control server (the native NotificationControlServer, or a fake in
+ * tests). Extends {@link ControlServerLike} with the start/stop lifecycle the
+ * daemon owns.
+ */
+export interface LifecycleControlServer extends ControlServerLike {
+    start(): Promise<unknown>;
+    stop(): void;
+}
+/** Factory the daemon uses to construct a control server bound to its ownership. */
+export type LifecycleControlServerFactory = (input: {
+    token: string;
+    ownerId: string;
+    agentDir: string;
+}) => LifecycleControlServer;
+export declare function fileLedgerStore(idempotencyFile: string): LedgerStore;
+/** Append-only JSONL audit sink (0600). Never receives tokens or raw prompts. */
+export declare function fileAudit(auditPath: string): (e: AuditEvent) => void;
+/** Simple per-chat sliding-window create rate limiter. */
+export declare function createRateLimiter(maxPerWindow: number, windowMs: number): (chatId: string, nowMs: number) => boolean;
+/** Build the `skc` argv for a create target (existing path / worktree / dir).
+ *
+ *  The launched session id is carried via `SKC_SESSION_ID` in the child env (see
+ *  {@link daemonSpawnCreate}); the root `skc` launcher has no `--session-id`
+ *  flag, so it must never appear in argv. Only flags the launch parser actually
+ *  supports are emitted (`--worktree <branch>` for worktree targets,
+ *  `--mpreset <profile>` for model presets). */
+export declare function buildCreateArgv(frame: SessionCreateFrame, _ids: {
+    intendedSessionId: string;
+    startupPromptRef?: string;
+}): {
+    cwd: string;
+    args: string[];
+};
+/** Real daemon-safe tmux launcher: canonical owner-isolation plan + SKC tags. */
+export declare function daemonSpawnCreate(env?: NodeJS.ProcessEnv, opts?: {
+    ownerIsolationProbe?: OwnerIsolationProbe;
+}): (frame: SessionCreateFrame, ids: {
+    lifecycleRequestId: string;
+    intendedSessionId: string;
+    startupPromptRef?: string;
+}) => Promise<CreateEffectResult>;
+/** Real force-close effect (SKC-managed only, id-matched). */
+export declare function daemonCloseSession(env?: NodeJS.ProcessEnv, deps?: {
+    forceClose?: (name: string, env: NodeJS.ProcessEnv, expectedSessionId?: string, sessionStateFile?: string) => Promise<void>;
+    findSession?: (name: string, env: NodeJS.ProcessEnv) => SkcTmuxSessionStatus | undefined;
+}): (target: {
+    sessionId: string;
+    tmuxSession?: string;
+    sessionStateFile?: string;
+}) => Promise<{
+    processGone: boolean;
+}>;
+/** Real resume effect: reattach if a live SKC session matches; else resolve the
+ *  prefix against saved history and fail closed (`ambiguous`/`notFound`) before
+ *  cold-restarting exactly one resolved session via the daemon-safe launcher. */
+export declare function daemonResumeSession(env?: NodeJS.ProcessEnv, opts?: {
+    agentDir?: string;
+    /** Explicit managed root for isolated tests. */
+    sessionsRoot?: string;
+    listSessions?: (env: NodeJS.ProcessEnv) => SkcTmuxSessionStatus[];
+    ownerIsolationProbe?: OwnerIsolationProbe;
+}): (target: {
+    sessionIdOrPrefix: string;
+    path?: string;
+}) => Promise<ResumeEffectResult | {
+    ambiguous: ResumeCandidate[];
+} | {
+    notFound: true;
+}>;
+/** Translate an orchestrator outcome into a wire response frame. */
+export declare function outcomeToResponse(frame: SessionLifecycleRequest, outcome: LifecycleOutcome): SessionLifecycleResponse;
+/**
+ * Wire a control server's lifecycle requests through the orchestrator.
+ *
+ * Handlers run on a single serial queue (a promise chain): the daemon owns the
+ * one control endpoint, so serializing here makes each request's ledger
+ * read -> classify -> write atomic with respect to every other request. Two
+ * identical updates that arrive nearly simultaneously can no longer both
+ * classify as `new` and both spawn — the second sees the first's persisted
+ * `in_progress`/`success` entry and re-acks instead.
+ */
+export declare function attachLifecycleControl(server: ControlServerLike, deps: OrchestratorDeps): void;
+/** Assemble real orchestrator deps for the daemon (ledger/audit under agentDir). */
+export declare function buildOrchestratorDeps(input: {
+    pairedChatId: string;
+    agentNotificationsDir: string;
+    /** Required in-memory, 32-byte audit-v2 redaction key. */
+    auditRedactionKey: Uint8Array;
+    /** Root of saved session histories (`<agentDir>/sessions`), for resume resolution. */
+    sessionsRoot?: string;
+    /** Agent directory used for readonly managed-session resume resolution. */
+    agentDir?: string;
+    env?: NodeJS.ProcessEnv;
+}): OrchestratorDeps;
+/**
+ * Default production factory: a real native NotificationControlServer bound to
+ * the daemon's control token, owner id, and agent dir.
+ */
+export declare const createNativeControlServer: LifecycleControlServerFactory;