patchwork-os 0.2.0-beta.1 → 0.2.0-beta.10.canary.95

package/dist/server.d.ts

@@ -4,6 +4,7 @@ import { WebSocket } from "ws";
 import type { ActivityListener } from "./activityTypes.js";
 import type { Logger } from "./logger.js";
 import type { OAuthServer } from "./oauth.js";
+import type { LintIssue } from "./recipes/validation.js";
 import type { RecipeDraft } from "./recipesHttp.js";
 interface ServerEvents {
     connection: [ws: WebSocket];
@@ -24,6 +25,7 @@ export declare class Server extends EventEmitter<ServerEvents> {
     private logger;
     private extraCorsOrigins;
     private pingIntervalMs;
+    private trustedProxies;
     private httpServer;
     private wss;
     private pingInterval;
@@ -34,9 +36,23 @@ export declare class Server extends EventEmitter<ServerEvents> {
     private oauthServer;
     private oauthIssuerUrl;
     private sseSubscriberCount;
+    /**
+     * Registered SSE subscribers on `/stream`, oldest-first by insertion
+     * order. Used as a defense-in-depth backstop: if a subscriber's peer is
+     * a dead-but-not-erroring socket (e.g. an orphaned proxy connection),
+     * the ping-write cleanup can fail to fire and the subscriber leaks. To
+     * guarantee a leak can never *permanently* brick `/stream`, a new
+     * request arriving at the cap evicts the oldest subscriber instead of
+     * returning 503 — mirroring the HTTP-session eviction in ADR-0005.
+     * The real cure for the known leak is the dashboard proxy aborting its
+     * upstream fetch on client disconnect; this is the backstop.
+     */
+    private sseSubscribers;
     /** Cache for CC permission rules (30s TTL) to avoid filesystem walks on each dashboard poll */
     private _explainRulesCache;
     private static readonly MAX_SSE_SUBSCRIBERS;
+    /** Number of currently-registered `/stream` SSE subscribers. Read-only. */
+    get sseSubscribers_count(): number;
     /** Set by bridge to provide health data */
     healthDataFn: (() => Record<string, unknown>) | null;
     /** Set by bridge to provide Prometheus metrics */
@@ -70,6 +86,24 @@ export declare class Server extends EventEmitter<ServerEvents> {
         error?: string;
         unavailable?: boolean;
     }>) | null;
+    /**
+     * Patchwork Phase 2A: repair a broken recipe YAML given the current
+     * content + structured LintIssue[] context. Driven by the same
+     * Claude-orchestrator infrastructure as `generateRecipeFn` (system
+     * prompt + sanitized user-tag wrapper + post-lint), but the user
+     * input is the user's CURRENT recipe rather than free-text — gated
+     * behind the `recipe.repair-ai` feature flag.
+     */
+    repairRecipeFn: ((args: {
+        currentYaml: string;
+        lintIssues: LintIssue[];
+    }) => Promise<{
+        ok: boolean;
+        yaml?: string;
+        warnings?: string[];
+        error?: string;
+        unavailable?: boolean;
+    }>) | null;
     /** Patchwork: set by bridge to list installed recipes for the dashboard. */
     recipesFn: (() => Record<string, unknown>) | null;
     /** Patchwork: set by bridge to load raw recipe source content by name. */
@@ -115,8 +149,8 @@ export declare class Server extends EventEmitter<ServerEvents> {
     /** Patchwork: set by bridge to lint raw recipe content without saving. */
     lintRecipeContentFn: ((content: string) => {
         ok: boolean;
-        errors: string[];
-        warnings: string[];
+        errors: LintIssue[];
+        warnings: LintIssue[];
     }) | null;
     /** Patchwork: set by bridge to save a new recipe draft to disk. */
     saveRecipeFn: ((draft: RecipeDraft) => {
@@ -131,9 +165,22 @@ export declare class Server extends EventEmitter<ServerEvents> {
         status?: string;
         recipe?: string;
         after?: number;
+        manualRunId?: string;
     }) => Record<string, unknown>[]) | null;
     /** Patchwork: set by bridge to fetch a single run by seq for the detail page. */
     runDetailFn: ((seq: number) => Record<string, unknown> | null) | null;
+    /** Patchwork (PR1c): aggregate halt-reason categories across recent runs. */
+    haltSummaryFn: ((opts?: {
+        sinceMs?: number;
+        limit?: number;
+        recipe?: string;
+    }) => import("./recipes/haltCategory.js").HaltSummary) | null;
+    /** Patchwork (PR3b): aggregate judge-step verdicts across recent runs. */
+    judgeSummaryFn: ((opts?: {
+        sinceMs?: number;
+        limit?: number;
+        recipe?: string;
+    }) => import("./recipes/judgeSummary.js").JudgeSummary) | null;
     /** Patchwork: set by bridge to generate a dry-run plan for a recipe by name. */
     runPlanFn: ((recipeName: string) => Promise<Record<string, unknown>>) | null;
     /** Patchwork (VD-4): mocked replay of an existing run. Returns the new
@@ -150,10 +197,25 @@ export declare class Server extends EventEmitter<ServerEvents> {
         taskId?: string;
         error?: string;
     }>) | null;
+    /**
+     * Patchwork: set by bridge to re-prime the recipe scheduler when the
+     * on-disk recipe set changes (install / save / delete). Lets cron-
+     * triggered recipes start firing without a bridge restart. Optional —
+     * tests + headless tooling leave it null; the install handler treats
+     * the callback as best-effort fire-and-forget.
+     */
+    onRecipesChangedFn: (() => void) | null;
     /** Patchwork: admin-controlled managed settings path (highest rule precedence). */
     managedSettingsPath: string | undefined;
     /** Effective bridge config path to update when dashboard saves driver changes. */
     bridgeConfigPath: string | undefined;
+    /**
+     * Shared secret for HMAC-SHA256 verification of POST /hooks/* requests
+     * carrying `X-Hub-Signature-256`. When null (default), HMAC auth is
+     * disabled and /hooks/* requires the bridge bearer token like every
+     * other route. Set by Bridge constructor from `config.webhookSecret`.
+     */
+    webhookSecret: string | null;
     /** Patchwork: live approval gate level — mutated by POST /settings, read by bridge per-session setup. */
     approvalGate: "off" | "high" | "all";
     /** Patchwork: outbound webhook URL for approval notifications (from dashboard.webhookUrl in config). */
@@ -164,6 +226,10 @@ export declare class Server extends EventEmitter<ServerEvents> {
     pushServiceToken: string | undefined;
     /** Patchwork: public base URL of this bridge, embedded in push payloads as callback base. */
     pushServiceBaseUrl: string | undefined;
+    /** Patchwork: ntfy.sh topic for direct phone-path approvals via action buttons. */
+    ntfyTopic: string | undefined;
+    /** Patchwork: ntfy server (default https://ntfy.sh; override for self-hosted). */
+    ntfyServer: string | undefined;
     /** Patchwork: approval decision audit callback wired to activityLog.recordEvent. */
     onApprovalDecision: ((event: string, meta: Record<string, unknown>) => void) | undefined;
     /**
@@ -186,6 +252,37 @@ export declare class Server extends EventEmitter<ServerEvents> {
      * the user's preference.
      */
     enableTimeOfDayAnomaly: boolean;
+    /**
+     * Patchwork: set by bridge to record a kill-switch audit trace.
+     * `/kill-switch` POST emits one entry on every state transition (no-op
+     * toggles do not emit). When unset, the handler logs via this.logger
+     * instead — see step 5 of issue #422.
+     *
+     * Trace encoding (v2-I6 from #422): we encode kill-switch events via
+     * the existing `DecisionTrace` schema rather than extending its
+     * `traceType` union, to keep schema migration off the kill-switch
+     * critical path. Fields used:
+     *   ref       = "kill-switch.writes"
+     *   problem   = "<short reason>" or "engage" / "release" if no reason
+     *   solution  = "ENGAGED at <ts>" or "RELEASED at <ts>"
+     *   tags      = ["kill-switch", "engage" | "release", "actor:http"]
+     *
+     * `ctxQueryTraces({tag: "kill-switch"})` returns the full audit
+     * history; pair with `tag: "engage"` / `tag: "release"` to filter
+     * direction.
+     */
+    recordKillSwitchTraceFn: ((event: {
+        engaged: boolean;
+        reason: string | undefined;
+        ts: number;
+    }) => void) | null;
+    /**
+     * Set by bridge to broadcast a `kind: "kill-switch"` SSE event from
+     * `/stream` when the kill-switch state changes (issue #422 v2, pitfall I8).
+     * Bridge wires this to `activityLog.broadcastKillSwitch()` or an equivalent
+     * that notifies all active SSE listeners so the dashboard updates in <1s.
+     */
+    broadcastKillSwitchEventFn: ((engaged: boolean, reason?: string) => void) | null;
     /** Patchwork: set by bridge to match + fire webhook-triggered recipes. */
     webhookFn: ((path: string, payload: unknown) => Promise<{
         ok: boolean;
@@ -210,6 +307,36 @@ export declare class Server extends EventEmitter<ServerEvents> {
         recipeName?: string;
     }[]>;
     static readonly MAX_WEBHOOK_PAYLOADS = 5;
+    /**
+     * Per-list FIFO bounds the per-recipe payload count, but the Map itself
+     * needs a key cap so a recipe-rename loop or a scanner hitting many
+     * distinct legitimate hookPaths can't grow `webhookPayloads.size`
+     * without bound. 1000 is generous for any realistic operator deployment
+     * (5 payloads × 1000 recipes = ~5000 entries × ~10 KB each = 50 MB).
+     * On overflow, evict the oldest *recipe* (Map iteration order is
+     * insertion order in JS), not the largest list.
+     */
+    static readonly MAX_WEBHOOK_RECIPES = 1000;
+    /**
+     * Per-IP rate limit on the unauthenticated phone-path approval endpoints
+     * (`POST /approve/:callId` and `POST /reject/:callId` when
+     * `x-approval-token` is present). The auth gate intentionally bypasses
+     * bearer auth for those paths so a phone can dispatch without a bridge
+     * token; without rate limiting, an attacker who learns a callId (via
+     * webhook target leak, bearer-authed `/approvals` reader, etc.) can
+     * spray garbage tokens to DoS the legitimate approver. PR #380 bumped
+     * the per-callId failure cap to 1000 (memory bound, not security
+     * bound); this is the HTTP-layer spray defense flagged as the proper
+     * fix in that commit.
+     *
+     * 60 attempts per IP per minute is generous for legitimate retries
+     * (phone re-tap, network flake) and tight enough to bound brute-force
+     * attempts during the 5-minute approval TTL to 300 — well within the
+     * per-callId cap, so no legit retry budget is consumed by sprayers.
+     */
+    private readonly approvalIpCounts;
+    static readonly APPROVAL_IP_MAX = 60;
+    static readonly APPROVAL_IP_WINDOW_MS = 60000;
     /** Set by bridge to handle MCP Streamable HTTP sessions (POST/GET/DELETE /mcp) */
     httpMcpHandler: ((req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>) | null;
     /** Set by bridge to subscribe a caller to real-time activity events. Returns unsubscribe fn. */
@@ -261,6 +388,26 @@ export declare class Server extends EventEmitter<ServerEvents> {
         ok: boolean;
         error?: string;
     }) | null;
+    /** Set by bridge to check if restart is safe (no in-flight tool calls). */
+    restartCheckFn: (() => {
+        totalSessions: number;
+        inFlightCalls: number;
+        busySessions: string[];
+    }) | null;
+    /**
+     * Called when /restart decides it is safe to shut down. Defaults to
+     * `process.kill(process.pid, 'SIGTERM')`. Override in tests to a no-op so
+     * the Vitest runner process is not actually killed.
+     */
+    restartKillFn: () => void;
+    /**
+     * Called when /shutdown decides it is safe to exit. Defaults to
+     * `process.kill(process.pid, 'SIGTERM')`. Bridge overrides this to run its
+     * internal shutdown sequence directly — necessary on Windows where
+     * `process.kill(pid, 'SIGTERM')` is TerminateProcess and cleanup handlers
+     * never fire.
+     */
+    shutdownFn: () => void;
     /**
      * Attach an OAuth 2.0 Authorization Server.
      * When set, the bridge exposes:
@@ -274,7 +421,17 @@ export declare class Server extends EventEmitter<ServerEvents> {
     setOAuthServer(oauth: OAuthServer, issuerUrl: string): void;
     /** Hosts accepted in the WebSocket upgrade Host header (DNS-rebinding guard). */
     private readonly allowedHosts;
-    constructor(authToken: string, logger: Logger, extraCorsOrigins?: string[], pingIntervalMs?: number);
+    constructor(authToken: string, logger: Logger, extraCorsOrigins?: string[], pingIntervalMs?: number, trustedProxies?: string[]);
+    /**
+     * Resolve the client IP for rate-limit bucketing on the phone-path
+     * approval bypass. Default: the direct socket peer. When trustedProxies
+     * is set AND the socket peer is one of them, the rightmost X-Forwarded-For
+     * entry not in the trusted list is the real client. XFF from an untrusted
+     * peer is ignored — that header is spoofable by anyone who can reach the
+     * server directly. Returns null when no IP can be determined; the caller
+     * should fail closed.
+     */
+    private getClientIp;
     listen(port: number, bindAddress?: string): Promise<number>;
     findAndListen(preferredPort: number | null, bindAddress?: string): Promise<number>;
     close(): Promise<void>;