/** * Localhost probe server - the piece the TeamShare website detects. * GET /ping answers { ok: true, version, agents } with permissive CORS so the * browser can reach it from the web app (contract section 5). * * Also hosts the workspace-arbitration endpoints (IMP-950): acquire/release * for PATH-shim callers and external tooling, an SSE event hub fed by * /arbitrate/publish, and a combined status view. All state is the shared * FS-backed lock tree in lib/workspace/repo-lock. */ import { type Server } from 'node:http'; export interface ProbeAgentStatus { agentId: string; lastWake?: string; /** True while a session lock is held for this agent (busy). */ busy?: boolean; since?: string; kind?: 'task' | 'chat' | 'doc' | 'board' | 'build' | 'orchestrator' | 'tool' /** Blog authoring session (IMP-9xx). */ | 'blog' /** Insights harness session (2026-10). */ | 'insight' /** Custom workflow session (2026-10). */ | 'workflow' /** Workflow authoring session (2026-10). */ | 'workflow-author'; taskId?: string; projectId?: string; documentId?: string; /** BlogGeneration id (kind === 'blog'). */ blogGenerationId?: string; /** InsightNarrativeRun id (kind === 'insight'). */ insightRunId?: string; /** WorkflowRun id (kind === 'workflow'). */ workflowRunId?: string; /** Wakes waiting for the agent to free up. */ queued?: number; /** * Wakes this daemon has ACKED and not yet reported a terminal outcome for * (2026-10). Non-zero while a run is in flight; PERMANENTLY non-zero on a * broken install, because a crash-looping daemon keeps taking receipts and * never finishes. `doctor` treats a rising count as the signal that wakes are * being stranded rather than worked. */ unsettledWakes?: number; /** True when the daemon paused this agent after repeated 401 heartbeats. */ authInvalid?: boolean; } export interface ProbeStatus { configPath: string; agents: ProbeAgentStatus[]; registeredSchemes: boolean; /** Project guard: projectId -> linked folder (never keys). */ projects: Record; } /** Session relay callbacks — wired to SessionRelay by the daemon. */ export interface SessionCallbacks { sessionStart(body: Record): boolean; sessionOutput(body: Record): boolean; sessionEnd(body: Record): boolean; } /** The token this process's probe server expects (minted on `startProbeServer`). */ export declare function getProbeToken(): string | null; export declare function startProbeServer(preferredPort: number | undefined, getStatus: () => ProbeStatus, onReload?: () => void, onPushState?: () => void, sessionCallbacks?: SessionCallbacks, onRelease?: (agentId: string) => void, onStopAllSessions?: () => Promise<{ ok: boolean; stopped: Array<{ agentId: string; hadLock: boolean; }>; }>): Promise<{ server: Server; port: number; }>; export interface PersistedToken { token: string; label?: string; sessionId?: string; createdAt: number; } /** * Load the tokens a previous daemon instance minted, re-resolving each agent's * key from the secret store (never from this file). Called when the probe * server starts, so tests that import this module never touch disk. */ export declare function enableTokenStatePersistence(resolveKey?: (label: string) => string | null): void; /** * The persisted rows a restart would restore, for tests and diagnostics. * Deliberately contains NO apiKey field - that is the invariant this file * exists to keep. */ export declare function tokenStateSnapshot(): PersistedToken[]; /** * Liveness of one run, as the harness's idle timer sees it (2026-10-27). * * `known: false` means the daemon does not hold a token for that run key - an * OLD daemon, a run that fell back to the direct API, or a finished run whose * token was revoked. The harness treats it as "no signal", never as "dead": * an absent probe must not change the run's behaviour. */ export interface SessionActivity { ok: true; session: string; known: boolean; /** Newest relayed request (ms epoch), or null when unknown. */ lastActivityAt: number | null; /** `tools/call` tool name / JSON-RPC method of that request. */ lastTool: string | null; requests: number; /** > 0 while a forwarded call has not answered yet. */ inFlight: number; } export declare function sessionActivity(sessionId: string): SessionActivity; /** * What a relayed MCP request is, for the activity stamp and the deadline. * Pure: a malformed body answers `{}` and is forwarded untouched. */ export declare function parseMcpRelayBody(body: Buffer): { method?: string; tool?: string; }; /** * Register a relay token for an agent key. * * With a `sessionId`, an existing token for that session is REUSED (and its * idle clock refreshed). That is the load-bearing part: the OpenCode service * keeps the first MCP connection for the run's project directory, so handing a * resumed/continued run a NEW token would leave the live connection * authenticating with the OLD one - and 401ing forever. */ export declare function registerSessionToken(apiKey: string, label?: string, sessionId?: string): string; /** Revoke a session token (explicit run end / stop). */ export declare function revokeSessionToken(token: string): void; /** * Revoke every relay token minted for an agent's API key (2026-10). * * THE FORCED-STOP HOLE: a forced stop kills the CLI, so its own cleanup never * runs. The token would otherwise stay valid and a surviving OpenCode V2 * service session would keep calling MCP tools as the agent. The daemon knows * the agent's key, so it revokes every token for that key at stop time. * Returns how many were revoked. */ export declare function revokeSessionTokensForApiKey(apiKey: string): number; /** Revoke every relay token whose debug label is `label` (the agent id). */ export declare function revokeSessionTokensForLabel(label: string): number; /** * Revoke the token(s) of ONE bridge session. Used when the session is truly * finished (never on a harness exit - a resume keeps using the same token, * because the OpenCode service still holds the connection it opened with it). */ export declare function revokeSessionTokensForSession(sessionId: string): number; /** * The daemon reports session liveness so the token-less relay path can answer * "which agent is this run?" when the harness's own config was bypassed. * Entries expire (a session that died without its end callback must not make * every later request ambiguous). */ export declare function noteSessionLive(agentId: string, live: boolean): void; /** The agent id a token-less relay request should act as, or null when ambiguous. */ export declare function resolveRelayFallbackAgentId(): string | null; /** * MCP Streamable HTTP: every POST must accept BOTH response shapes, or the * SDK server answers 406 `{"code":-32000,"message":"Not Acceptable: Client * must accept both application/json and text/event-stream"}`. */ export declare const MCP_REQUIRED_ACCEPT = "application/json, text/event-stream"; /** * Build the upstream request headers for a relayed MCP call (2026-10-15). * * The relay used to forward only Content-Type + the X-TeamShare-* headers and * INJECT X-Api-Key - dropping `Accept` (406 for every harness through the * relay) and the protocol/session headers. Pure - pinned in * `tests/mcp-relay-headers.test.mjs`. */ export declare function relayRequestHeaders(incoming: Record, apiKey: string, runKey?: string): Record; /** * Response headers the relay passes back server -> client. `mcp-session-id` * is the session handle every later request must echo; the response body is * streamed as-is (SSE included) by the caller. */ export declare function relayResponseHeaders(upstream: { get: (name: string) => string | null; }): Record; /** Does this upstream body mean "that MCP session no longer exists"? */ export declare function isUnknownMcpSession(body: string): boolean; /** * Is this request safe to REPLAY after a hub session expired? * * Only metadata requests. A `tools/call` may have reached the tool even when * the response looks like a session error (a proxy, or a hub restart mid-call), * and replaying `create_document` / `submit_qa_report` would duplicate it. The * cost of not replaying a tool call is one clear error the agent can retry; the * cost of replaying a mutation is a duplicate write. */ export declare function isReplayableMcpRequest(body: Buffer | string): boolean; export declare function probeErrorMessage(err: unknown): string;