@pinet/broker-core 0.2.2 → 0.2.6

package/dist/schema.d.ts

@@ -1,6 +1,6 @@
 import { DatabaseSync } from "node:sqlite";
 import type { PinetMailClass } from "./mail-classification.js";
-import type { AgentInfo, ThreadInfo, BrokerMessage, InboxEntry, InboxReadOptions, InboxReadResult, InboxThreadUnreadSummary, DeliveredInboundMessageResult, BacklogEntry, BrokerDBInterface, InboundMessage, ChannelAssignment, TaskAssignmentInfo, TaskAssignmentKind, TaskAssignmentStatus, ScheduledWakeupInfo, ScheduledWakeupDelivery, PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, AgentSessionSearchInfo, AgentSessionSearchOptions, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput } from "./types.js";
+import type { AgentInfo, ThreadInfo, BrokerMessage, InboxEntry, InboxReadOptions, InboxReadResult, InboxThreadUnreadSummary, DeliveredInboundMessageResult, BacklogEntry, BrokerDBInterface, InboundMessage, ChannelAssignment, TaskAssignmentInfo, TaskAssignmentKind, TaskAssignmentStatus, ScheduledWakeupInfo, ScheduledWakeupDelivery, PortLeaseAcquireInput, PortLeaseInfo, PortLeaseListOptions, PortLeaseReleaseInput, PortLeaseRenewInput, AgentSessionSearchInfo, AgentSessionSearchOptions, PinetLaneInfo, PinetLaneListOptions, PinetLaneParticipantInfo, PinetLaneParticipantUpsertInput, PinetLaneUpsertInput, AgentHibernatePolicy, AgentLifecycleLease, AgentLifecycleOperation, AgentLifecycleTransitionInput, AgentLifecycleRetentionInfo, AgentRuntimeSpec, AgentRuntimeSpecInput, AgentCheckpointReceipt, AgentCheckpointReceiptInput, AgentWakeReservation, AgentWakeAcceptanceReceipt, AcceptRuntimeGenerationInput, RuntimeGenerationAcceptance, AgentWakeQueueEntry, EnqueueWakeInput, AgentLifecycleEvent, AgentLifecycleEventInput } from "./types.js";
 export interface TaskAssignmentAwaitingReplyInfo {
     id: number;
     agentId: string;
@@ -12,7 +12,7 @@ export interface TaskAssignmentAwaitingReplyInfo {
 export declare function defaultDbPath(): string;
 export declare const DEFAULT_RESUMABLE_WINDOW_MS = 15000;
 export declare const DEFAULT_DISCONNECTED_PURGE_GRACE_MS: number;
-export declare const CURRENT_BROKER_SCHEMA_VERSION = 18;
+export declare const CURRENT_BROKER_SCHEMA_VERSION = 24;
 export declare class BrokerDB implements BrokerDBInterface {
     private db;
     private readonly dbPath;
@@ -28,6 +28,185 @@ export declare class BrokerDB implements BrokerDBInterface {
     close(): void;
     registerAgent(id: string, name: string, emoji: string, pid: number, metadata?: Record<string, unknown>, stableId?: string): AgentInfo;
     private resolveAgentHierarchy;
+    transitionAgentLifecycle(input: AgentLifecycleTransitionInput): AgentInfo;
+    /**
+     * Append an audit-only lifecycle event (a refusal, fenced stale attempt, or
+     * duplicate-launch prevention) without changing the agent's lifecycle state.
+     */
+    recordAgentLifecycleEvent(input: AgentLifecycleEventInput): void;
+    private insertLifecycleEventRow;
+    getRecentAgentLifecycleEvents(agentId?: string, limit?: number): AgentLifecycleEvent[];
+    getAgentLifecycleRetentionInfo(): AgentLifecycleRetentionInfo;
+    acquireAgentLifecycleLease(input: {
+        agentId: string;
+        operation: AgentLifecycleOperation;
+        ownerBrokerInstanceId: string;
+        leaseId: string;
+        ttlMs: number;
+        triggerMessageId?: number | null;
+        now?: number;
+    }): AgentLifecycleLease | null;
+    releaseAgentLifecycleLease(agentId: string, leaseId: string, fenceToken: number): boolean;
+    /**
+     * Extend an already-held, still-valid lease's expiry WITHOUT bumping the
+     * fence, so a legitimately long-running operation (e.g. a wake that waits on
+     * process launch + runtime registration across several attempts) keeps a valid
+     * lease across adapter waits and can still complete its fenced forward
+     * transition. The fence is preserved so revival fencing is unaffected.
+     *
+     * Renewal only succeeds while the lease is still unexpired and held by this
+     * exact owner (matching `leaseId` + `fenceToken`); this preserves the takeover
+     * guarantee (a stalled owner past expiry cannot reclaim a lease another broker
+     * may take over). Returns the refreshed lease, or null when ownership was lost
+     * (expired, released, or the fence moved) — a null result means the caller
+     * must fail closed rather than continue driving forward transitions.
+     */
+    renewAgentLifecycleLease(input: {
+        agentId: string;
+        leaseId: string;
+        fenceToken: number;
+        ttlMs: number;
+        now?: number;
+    }): AgentLifecycleLease | null;
+    /** Set the opt-in hibernation policy for an agent (auto | manual | never). */
+    setAgentHibernatePolicy(agentId: string, policy: AgentHibernatePolicy): void;
+    /** Record grace/idle eligibility timestamps used by the auto-hibernation scheduler. */
+    setAgentHibernationSchedule(agentId: string, schedule: {
+        graceUntil?: string | null;
+        idleEligibleAt?: string | null;
+    }): void;
+    getAgentLifecycleLease(agentId: string): AgentLifecycleLease | null;
+    upsertAgentRuntimeSpec(input: AgentRuntimeSpecInput): AgentRuntimeSpec;
+    getAgentRuntimeSpec(agentId: string): AgentRuntimeSpec | null;
+    deleteAgentRuntimeSpec(agentId: string): void;
+    recordAgentCheckpointReceipt(input: AgentCheckpointReceiptInput): AgentCheckpointReceipt;
+    getLatestAgentCheckpointReceipt(agentId: string): AgentCheckpointReceipt | null;
+    /**
+     * Reserve the exact runtime generation the broker will accept for a wake.
+     * Requires an unexpired wake lease held with the given fence token. Exactly
+     * one reservation may exist per agent (PK). The reserved generation is the
+     * agent's current runtime_generation + 1, so any older runtime is fenced out.
+     */
+    reserveWakeGeneration(input: {
+        agentId: string;
+        wakeLeaseId: string;
+        fenceToken: number;
+        correlationId: string;
+        /** Optional injected nonce (tests); production mints a fresh UUID. */
+        reservationNonce?: string;
+        now?: number;
+    }): AgentWakeReservation;
+    getAgentWakeReservation(agentId: string): AgentWakeReservation | null;
+    clearAgentWakeReservation(agentId: string): void;
+    /**
+     * Record the EXACT wake fence that just accepted a generation, so a runtime
+     * whose register RPC response was lost to a crash can replay its single-use
+     * fence and be re-bound idempotently. Called INSIDE the acceptance transaction
+     * (via {@link acceptRuntimeGeneration} / {@link registerAgentWithGenerationAcceptance})
+     * so the receipt is atomic with the generation advance. The stable id is read
+     * from the just-registered row so the receipt binds to the durable identity.
+     */
+    private writeWakeAcceptanceReceipt;
+    getAgentWakeAcceptanceReceipt(agentId: string): AgentWakeAcceptanceReceipt | null;
+    /**
+     * Accept exactly one runtime generation for a waking agent. The registration
+     * must present the same wake lease id, fence token, and reserved generation,
+     * AND the bound lease must still be an unexpired `wake` lease while the agent
+     * is still in the `waking` lifecycle state. A stale, expired, wrong-operation,
+     * wrong-state, or duplicate registration returns `{ accepted: false }` without
+     * mutating state. On success the agent's runtime_generation is advanced and
+     * the reservation is consumed. `now` (epoch ms) is injectable for tests.
+     */
+    /**
+     * Non-mutating validation shared by {@link acceptRuntimeGeneration} and
+     * {@link checkRuntimeGenerationAcceptable}. Returns a `{ accepted: false }`
+     * rejection when the fence does not bind, or `null` when acceptance is legal.
+     * Never advances the generation or consumes the reservation.
+     */
+    private validateRuntimeGenerationAcceptance;
+    acceptRuntimeGeneration(input: AcceptRuntimeGenerationInput): RuntimeGenerationAcceptance;
+    /**
+     * Atomically settle a wake attempt against the acceptance boundary BEFORE the
+     * orchestrator stops or quarantines a launched-but-unaccepted runtime. This
+     * closes the timeout-boundary race: the socket layer accepts a generation
+     * atomically, so an acceptance can land in the window between the
+     * orchestrator's last waiter read and its decision to stop the attempt. In one
+     * transaction:
+     *
+     *  - If the reserved generation was ALREADY accepted (the agent's
+     *    `runtime_generation` reached `reservedGeneration` — the socket won the
+     *    race), report `{ accepted: true }` and leave the accepted runtime and its
+     *    (already consumed) reservation untouched. The caller must then treat the
+     *    attempt as the live runtime and NEVER stop it.
+     *  - Otherwise, consume ONLY this attempt's exact-nonce reservation, so any
+     *    later registration by the launched runtime can no longer be accepted
+     *    (`no_reservation`). This makes the caller's subsequent prove-stop safe:
+     *    once this returns `{ accepted: false }` the launched runtime can never
+     *    become live. A reservation minted by a superseded/newer attempt (a
+     *    different nonce) is left intact.
+     *
+     * `runtime_generation === reservedGeneration` uniquely identifies acceptance of
+     * THIS attempt because reserved generations are `current_generation + 1` at
+     * reserve time and only advance on acceptance.
+     */
+    finalizeWakeAttempt(input: {
+        agentId: string;
+        reservedGeneration: number;
+        reservationNonce: string;
+    }): {
+        accepted: boolean;
+    };
+    /**
+     * Atomically revive a hibernated identity: perform the agent registration
+     * mutation AND accept the reserved runtime generation in ONE transaction, so a
+     * rejected acceptance rolls the registration mutation back. This closes the
+     * window where a revival whose wake lease expires between the socket-layer
+     * preflight and acceptance would otherwise leave the durable row with a
+     * mutated pid/metadata/connectivity even though the socket is refused and
+     * unbound. On rejection the transaction is rolled back and `agent` is null.
+     */
+    registerAgentWithGenerationAcceptance(input: {
+        registration: {
+            id: string;
+            name: string;
+            emoji: string;
+            pid: number;
+            metadata?: NonNullable<AgentInfo["metadata"]>;
+            stableId?: string;
+        };
+        accept: AcceptRuntimeGenerationInput;
+    }): {
+        agent: AgentInfo | null;
+        acceptance: RuntimeGenerationAcceptance;
+    };
+    /**
+     * Non-mutating preflight for {@link acceptRuntimeGeneration}: runs the exact
+     * same fence validation without advancing the generation or consuming the
+     * reservation. The socket layer uses this to validate a wake fence BEFORE
+     * committing the agent registration, and only accepts the generation once
+     * registration has succeeded. Because broker registration is synchronous, a
+     * passing preflight followed immediately by `acceptRuntimeGeneration` cannot
+     * be interleaved by another connection, so this closes the window where a
+     * generation was advanced for a runtime whose registration then failed.
+     */
+    checkRuntimeGenerationAcceptable(input: AcceptRuntimeGenerationInput): RuntimeGenerationAcceptance;
+    /**
+     * Idempotently enqueue a wake trigger. If an active (queued/dispatching)
+     * entry already exists for the agent it is returned unchanged except that the
+     * effective priority is lowered to the strongest (smallest) trigger and the
+     * trigger message id is preserved when still unset. Never fans out.
+     */
+    enqueueWake(input: EnqueueWakeInput): AgentWakeQueueEntry;
+    private getActiveWakeQueueEntry;
+    private getWakeQueueEntryById;
+    listWakeQueue(status?: AgentWakeQueueEntry["status"]): AgentWakeQueueEntry[];
+    countInflightWakes(repoRoot?: string | null): number;
+    markWakeDispatching(id: number): AgentWakeQueueEntry | null;
+    requeueWake(id: number): AgentWakeQueueEntry | null;
+    completeWakeQueueEntry(id: number, status?: "done" | "cancelled"): void;
+    cancelWake(agentId: string): void;
+    /** Mark any active wake-queue entry for an agent as completed (idempotent). */
+    completeWakeForAgent(agentId: string): void;
     unregisterAgent(id: string): void;
     disconnectAgent(id: string, resumableForMs?: number): void;
     private getDirectChildren;