@hua-labs/tap 0.5.1 → 0.6.0

package/dist/bridges/codex-app-server-bridge.d.mts

@@ -1,5 +1,7 @@
 type BusyMode = "wait" | "steer";
 type LogLevel = "debug" | "info" | "warn" | "error";
+type CandidateScope = "observe" | "suggest" | "drive";
+type DispatchMode = "start" | "steer" | "drive" | "blocked" | "rejected";
 interface Options {
     repoRoot: string;
     commsDir: string;
@@ -21,11 +23,26 @@ interface Options {
     logLevel: LogLevel;
     threadId: string | null;
     ephemeral: boolean;
+    /**
+     * M392: explicit routing slot derived from the base instance id by the
+     * bridge launcher and forwarded via `TAP_ROUTING_SLOT`. When set, takes
+     * precedence over `resolveBridgeRoutingSlot(agentId)` in
+     * `buildBridgeAddress` so suffixed agent ids (`codex-wt1-abc123`) still
+     * advertise the correct slot in heartbeats / presence.
+     */
+    routingSlot: BridgeRoutingSlot | null;
 }
 interface InboxRoute {
     sender: string;
     recipient: string;
     subject: string;
+    messageId?: string | null;
+    fromAddress?: HeartbeatAddressRecord | null;
+    toAddress?: HeartbeatAddressRecord | null;
+    scope?: CandidateScope | null;
+    action?: string | null;
+    consentRef?: string | null;
+    validationError?: string | null;
 }
 interface Candidate {
     markerId: string;
@@ -36,6 +53,12 @@ interface Candidate {
     subject: string;
     body: string;
     mtimeMs: number;
+    messageId?: string | null;
+    fromAddress?: HeartbeatAddressRecord | null;
+    toAddress?: HeartbeatAddressRecord | null;
+    scope?: CandidateScope | null;
+    action?: string | null;
+    consentRef?: string | null;
 }
 interface ThreadStateRecord {
     threadId: string;
@@ -70,6 +93,16 @@ interface HeartbeatRecord {
     consecutiveFailureCount: number;
     busyMode: BusyMode;
 }
+type BridgeRoutingSlot = "tower" | "reviewer" | `wt-${number}`;
+interface HeartbeatAddressRecord {
+    hostId?: string | null;
+    clientId?: string | null;
+    conversationId?: string | null;
+    ownerClientId?: string | null;
+    routingAddress?: string;
+    slot?: BridgeRoutingSlot | null;
+    aliases?: string[];
+}
 interface BridgeHealthState {
     consecutiveFailureCount: number;
 }
@@ -103,6 +136,8 @@ interface HeartbeatStoreRecord {
     instanceId?: string | null;
     bridgePid?: number | null;
     connectHash?: string;
+    address?: HeartbeatAddressRecord;
+    receiveTransports?: string[];
 }
 type HeartbeatStore = Record<string, HeartbeatStoreRecord>;
 interface JsonRpcResponse {
@@ -134,7 +169,9 @@ declare const STALE_TURN_MS: number;
  * M206: Re-export canonicalizeAgentId as canonicalize for backward compat.
  */
 declare function canonicalize(id: string): string;
+declare function stripWindowsNamespacePrefix(cwd: string): string;
 declare function normalizeThreadCwd(cwd: string): string;
+declare function normalizePersistedThreadCwd(cwd: string | null | undefined): string | null;
 declare function threadCwdMatches(expectedCwd: string, actualCwd: string | null | undefined): boolean;
 declare function chooseLoadedThreadForCwd(cwd: string, threads: LoadedThreadCandidate[]): LoadedThreadCandidate | null;
 declare function normalizeAgentToken(value?: string | null): string | null;
@@ -166,20 +203,18 @@ declare function isOwnMessageSender(sender: string, agentId: string, agentName:
  * Returns true if the turn should be treated as not active.
  */
 declare function isTurnStuckOnApproval(activeFlags: string[]): boolean;
+declare function isWaitingApprovalStatus(status: string | null | undefined): boolean;
 /**
  * M203: Check if a turn has been running longer than the stale threshold.
  */
 declare function isTurnStale(turnStartedAt: string | null, nowMs?: number): boolean;
 declare function shouldRetrySteerAsStart(error: unknown): boolean;
+declare const FORBIDDEN_RAW_PAIR_TOKEN_REASON = "envelope rejected: forbidden raw pairToken field present (M355 defensive drop)";
 /**
  * Parse YAML frontmatter from message content for routing.
  * Returns null if no valid frontmatter found.
  */
-declare function parseBridgeFrontmatter(content: string): {
-    sender: string;
-    recipient: string;
-    subject: string;
-} | null;
+declare function parseBridgeFrontmatter(content: string): InboxRoute | null;
 /**
  * Strip YAML frontmatter from message content, returning only the body.
  */
@@ -214,10 +249,35 @@ declare function sanitizeStateSegment(agentName: string): string;
 declare function buildDefaultStateDir(repoRoot: string, preferredAgentName?: string | null): string;
 declare function resolveStateDir(repoRoot: string, explicit?: string, preferredAgentName?: string | null): string;
 declare function readGatewayTokenFile(tokenFile: string): string;
+declare function normalizeRoutingSlotEnv(value: string | null | undefined): BridgeRoutingSlot | null;
 declare function buildOptions(argv: string[]): Options;
 
 declare function buildMarkerId(filePath: string, mtimeMs: number): string;
 declare function getProcessedMarkerPath(stateDir: string, markerId: string): string;
+interface SweepOrphanProcessedMarkersResult {
+    scanned: number;
+    removed: number;
+    kept: number;
+    errors: number;
+    removedMarkerIds: string[];
+}
+type SweepLogger = (message: string, context?: Record<string, unknown>) => void;
+/**
+ * M362 (M346 cache-contract drift #5): scan processed markers and retire
+ * those whose source inbox artefact no longer exists, plus those that have
+ * aged past the retention window.
+ *
+ * The sweep is idempotent and failure-tolerant — unreadable payloads and
+ * unlink failures are counted into `errors` and skipped, never thrown. The
+ * intent is to run once at bridge startup; callers may also invoke it
+ * periodically without guard.
+ */
+declare function sweepOrphanProcessedMarkers(stateDir: string, options?: {
+    nowMs?: number;
+    maxAgeMs?: number;
+    graceMs?: number;
+    logger?: SweepLogger;
+}): SweepOrphanProcessedMarkersResult;
 declare function loadHeartbeats(commsDir: string): HeartbeatStore;
 declare function shouldSkipInHeadlessMode(fileName: string, body: string): boolean;
 declare function collectCandidates(inboxDir: string, agentId: string, agentName: string, aliasName?: string): Candidate[];
@@ -227,8 +287,15 @@ declare function getPendingCandidates(options: Options, cutoff: Date): {
 };
 
 declare function buildUserInput(candidate: Candidate, agentName: string, heartbeats: HeartbeatStore): string;
-declare function writeProcessedMarker(stateDir: string, candidate: Candidate, dispatchMode: "start" | "steer", threadId: string | null, turnId: string | null): void;
-declare function writeLastDispatch(stateDir: string, candidate: Candidate, dispatchMode: "start" | "steer", threadId: string | null, turnId: string | null): void;
+declare function writeProcessedMarker(stateDir: string, candidate: Candidate, dispatchMode: DispatchMode, threadId: string | null, turnId: string | null, blockedReason?: string | null): void;
+declare function writeLastDispatch(stateDir: string, candidate: Candidate, dispatchMode: DispatchMode, threadId: string | null, turnId: string | null, blockedReason?: string | null): void;
+
+declare function isAutoElicitationRequestMethod(method: string): boolean;
+interface ElicitationResult {
+    action: "accept" | "cancel";
+    content?: Record<string, unknown>;
+}
+declare function buildAutoElicitationResult(rawParams: unknown): ElicitationResult | null;
 
 type LogContext = Record<string, unknown>;
 interface BridgeLogger {
@@ -240,6 +307,7 @@ interface BridgeLogger {
 
 declare function readSocketData(data: unknown): Promise<string>;
 declare function formatJsonRpcError(error: JsonRpcResponse["error"]): string;
+declare const DEFAULT_APP_SERVER_REQUEST_TIMEOUT_MS = 30000;
 declare class AppServerClient {
     private socket;
     private readonly url;
@@ -247,7 +315,9 @@ declare class AppServerClient {
     private readonly logger;
     private readonly clientId;
     private nextId;
-    private pending;
+    private readonly requestTimeoutMs;
+    private readonly pending;
+    private readonly socketListeners;
     connected: boolean;
     initialized: boolean;
     threadId: string | null;
@@ -260,7 +330,8 @@ declare class AppServerClient {
     lastError: string | null;
     lastSuccessfulAppServerAt: string | null;
     lastSuccessfulAppServerMethod: string | null;
-    constructor(url: string, logger: BridgeLogger, gatewayToken?: string | null);
+    constructor(url: string, logger: BridgeLogger, gatewayToken?: string | null, requestTimeoutMs?: number);
+    getPendingRequestCount(): number;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     ensureThread(explicitThreadId: string | null, savedThread: ThreadStateRecord | null, cwd: string, ephemeral: boolean): Promise<string>;
@@ -268,6 +339,7 @@ declare class AppServerClient {
     startTurn(inputText: string): Promise<string | null>;
     steerTurn(inputText: string): Promise<string>;
     isBusy(): boolean;
+    isWaitingOnApproval(): boolean;
     refreshCurrentThreadState(): Promise<void>;
     private requireThreadId;
     private requireActiveTurnId;
@@ -276,17 +348,38 @@ declare class AppServerClient {
     private handleMessage;
     private handleNotification;
     private request;
+    private sendJsonRpcResult;
     private rejectPending;
+    private clearPendingTimeout;
+    private detachSocketListeners;
+    private buildMetricsContext;
 }
 
+declare const DRIVE_NOT_YET_WIRED_REASON = "missing pairToken / drive not yet wired (M345 Phase 2 / M355 pending)";
+declare const DRIVE_ACTION_NOT_YET_SUPPORTED_REASON = "drive action is not yet wired through bridge dispatch";
+interface DriveDispatchTransport {
+    connect(): Promise<unknown>;
+    disconnect(): Promise<void>;
+    startTurn(options: {
+        conversationId: string;
+        text: string;
+        action?: string | null;
+        consentRef?: string | null;
+        hostId?: string | null;
+        ownerClientId?: string | null;
+    }): Promise<unknown>;
+}
+type DriveDispatchTransportFactory = (options: Options) => DriveDispatchTransport;
 declare function sanitizeErrorForPersistence(error: string | null): string | null;
 declare function readThreadState(stateDir: string): ThreadStateRecord | null;
 declare function persistThreadState(stateDir: string, threadId: string, appServerUrl: string, ephemeral: boolean, cwd: string | null): void;
 declare function acquireCommsLock(lockPath: string): boolean;
 declare function releaseCommsLock(lockPath: string): void;
-declare function updateCommsHeartbeat(options: Options, status: string): void;
+declare function updateCommsHeartbeat(options: Options, status: string, conversationId?: string | null): void;
+declare function markBridgeActivity(): void;
+declare function getLastBridgeActivityAt(): string | null;
 declare function writeHeartbeat(options: Options, client: AppServerClient | null, health: BridgeHealthState): void;
-declare function dispatchCandidate(client: AppServerClient, options: Options, candidate: Candidate, heartbeats: HeartbeatStore): Promise<boolean>;
+declare function dispatchCandidate(client: AppServerClient, options: Options, candidate: Candidate, heartbeats: HeartbeatStore, driveTransportFactory?: DriveDispatchTransportFactory): Promise<boolean>;
 declare function runScan(options: Options, cutoff: Date, client: AppServerClient | null): Promise<{
     dispatched: boolean;
     maxMtimeMs: number;
@@ -301,4 +394,4 @@ declare function getGeneralInboxCutoff(stateDir: string, lookbackMinutes: number
 declare function main(): Promise<void>;
 declare function isDirectExecution(): boolean;
 
-export { AUTH_SUBPROTOCOL_PREFIX, AppServerClient, type BridgeHealthState, type BusyMode, COMMS_HEARTBEAT_LOCK_TIMEOUT_MS, COMMS_LOCK_STALE_AGE_MS, type Candidate, DEFAULT_AGENT, DEFAULT_APP_SERVER_URL, HEADLESS_SKIP_PATTERNS, HEADLESS_WARMUP_PROMPT, HEADLESS_WARMUP_TIMEOUT_MS, type HeadlessWarmupClient, type HeartbeatRecord, type HeartbeatStore, type HeartbeatStoreRecord, type InboxRoute, type JsonRpcResponse, type LoadedThreadCandidate, type LogLevel, type Options, PLACEHOLDER_AGENT_VALUES, type RequestRecord, STALE_TURN_MS, TURN_COMPLETION_POLL_MS, TURN_COMPLETION_REFRESH_MS, type ThreadStateRecord, acquireCommsLock, buildDefaultStateDir, buildMarkerId, buildOptions, buildUserInput, canonicalize, chooseLoadedThreadForCwd, collectCandidates, dispatchCandidate, formatAgentLabel, formatJsonRpcError, getGeneralInboxCutoff, getInboxRoute, getInboxRouteFromFilename, getPendingCandidates, getProcessedMarkerPath, isDirectExecution, isOwnMessageSender, isTurnStale, isTurnStuckOnApproval, loadHeartbeats, loadResumableThreadState, main, maybeBootstrapHeadlessTurn, normalizeAgentToken, normalizeThreadCwd, parseArgs, parseBridgeFrontmatter, persistAgentName, persistThreadState, readGatewayTokenFile, readHeartbeatState, readSocketData, readThreadState, recipientMatchesAgent, refreshAgentIdentity, releaseCommsLock, resolveAddressLabel, resolveAgentId, resolveAgentName, resolveCommsDir, resolveCurrentAgentName, resolvePreferredAgentName, resolveRepoRoot, resolveStateDir, resolveTapConfigPath, runScan, sanitizeErrorForPersistence, sanitizeStateSegment, shouldRetrySteerAsStart, shouldSkipInHeadlessMode, stripBridgeFrontmatter, threadCwdMatches, updateCommsHeartbeat, waitForTurnCompletion, waitForTurnDrain, writeHeartbeat, writeLastDispatch, writeProcessedMarker };
+export { AUTH_SUBPROTOCOL_PREFIX, AppServerClient, type BridgeHealthState, type BridgeRoutingSlot, type BusyMode, COMMS_HEARTBEAT_LOCK_TIMEOUT_MS, COMMS_LOCK_STALE_AGE_MS, type Candidate, type CandidateScope, DEFAULT_AGENT, DEFAULT_APP_SERVER_REQUEST_TIMEOUT_MS, DEFAULT_APP_SERVER_URL, DRIVE_ACTION_NOT_YET_SUPPORTED_REASON, DRIVE_NOT_YET_WIRED_REASON, type DispatchMode, type ElicitationResult, FORBIDDEN_RAW_PAIR_TOKEN_REASON, HEADLESS_SKIP_PATTERNS, HEADLESS_WARMUP_PROMPT, HEADLESS_WARMUP_TIMEOUT_MS, type HeadlessWarmupClient, type HeartbeatAddressRecord, type HeartbeatRecord, type HeartbeatStore, type HeartbeatStoreRecord, type InboxRoute, type JsonRpcResponse, type LoadedThreadCandidate, type LogLevel, type Options, PLACEHOLDER_AGENT_VALUES, type RequestRecord, STALE_TURN_MS, type SweepOrphanProcessedMarkersResult, TURN_COMPLETION_POLL_MS, TURN_COMPLETION_REFRESH_MS, type ThreadStateRecord, acquireCommsLock, buildAutoElicitationResult, buildDefaultStateDir, buildMarkerId, buildOptions, buildUserInput, canonicalize, chooseLoadedThreadForCwd, collectCandidates, dispatchCandidate, formatAgentLabel, formatJsonRpcError, getGeneralInboxCutoff, getInboxRoute, getInboxRouteFromFilename, getLastBridgeActivityAt, getPendingCandidates, getProcessedMarkerPath, isAutoElicitationRequestMethod, isDirectExecution, isOwnMessageSender, isTurnStale, isTurnStuckOnApproval, isWaitingApprovalStatus, loadHeartbeats, loadResumableThreadState, main, markBridgeActivity, maybeBootstrapHeadlessTurn, normalizeAgentToken, normalizePersistedThreadCwd, normalizeRoutingSlotEnv, normalizeThreadCwd, parseArgs, parseBridgeFrontmatter, persistAgentName, persistThreadState, readGatewayTokenFile, readHeartbeatState, readSocketData, readThreadState, recipientMatchesAgent, refreshAgentIdentity, releaseCommsLock, resolveAddressLabel, resolveAgentId, resolveAgentName, resolveCommsDir, resolveCurrentAgentName, resolvePreferredAgentName, resolveRepoRoot, resolveStateDir, resolveTapConfigPath, runScan, sanitizeErrorForPersistence, sanitizeStateSegment, shouldRetrySteerAsStart, shouldSkipInHeadlessMode, stripBridgeFrontmatter, stripWindowsNamespacePrefix, sweepOrphanProcessedMarkers, threadCwdMatches, updateCommsHeartbeat, waitForTurnCompletion, waitForTurnDrain, writeHeartbeat, writeLastDispatch, writeProcessedMarker };