@phuetz/code-buddy 1.0.0 → 1.2.0

package/dist/scheduler/cron-scheduler.d.ts

@@ -140,6 +140,10 @@ export interface JobRun {
     result?: unknown;
     error?: string;
     duration?: number;
+    /** Structured output from this job run, passed as inputData to chained jobs. */
+    outputData?: string;
+    /** Input data received from a parent job in a chain. */
+    inputData?: string;
 }
 export interface CronSchedulerConfig {
     /** Jobs persist path */
@@ -174,7 +178,7 @@ export declare class CronScheduler extends EventEmitter {
     /**
      * Set the task executor (for CronAgentBridge integration)
      */
-    setTaskExecutor(executor: (job: CronJob) => Promise<unknown>): void;
+    setTaskExecutor(executor: (job: CronJob, inputData?: string) => Promise<unknown>): void;
     /**
      * Load persisted jobs into memory without starting the tick loop. Useful for
      * one-shot CLI commands (`buddy cron list/add/remove`) that must see the
@@ -182,7 +186,7 @@ export declare class CronScheduler extends EventEmitter {
      * overwrite the file with only the in-memory jobs.
      */
     loadFromDisk(): Promise<void>;
-    start(taskExecutor?: (job: CronJob) => Promise<unknown>): Promise<void>;
+    start(taskExecutor?: (job: CronJob, inputData?: string) => Promise<unknown>): Promise<void>;
     stop(): Promise<void>;
     /**
      * Add a new job
@@ -232,11 +236,19 @@ export declare class CronScheduler extends EventEmitter {
     /**
      * Run a job immediately
      */
-    runJobNow(jobId: string): Promise<JobRun | null>;
+    runJobNow(jobId: string, inputData?: string): Promise<JobRun | null>;
     private scheduleJob;
     private cancelJobTimer;
     private calculateNextRun;
     private executeJob;
+    /** Max bytes for outputData passed between chained jobs. */
+    private static readonly MAX_OUTPUT_DATA_BYTES;
+    /**
+     * Extract a string `outputData` from the executor result. Looks for an
+     * explicit `outputData` field first, then falls back to `output`, then
+     * stringifies the whole result. Always capped at 64KB.
+     */
+    static extractOutputData(result: unknown): string | undefined;
     /**
      * Resolve and execute a chained (`then`) job after its parent succeeds.
      *

package/dist/scheduler/cron-scheduler.js

@@ -304,11 +304,11 @@ export class CronScheduler extends EventEmitter {
     /**
      * Run a job immediately
      */
-    async runJobNow(jobId) {
+    async runJobNow(jobId, inputData) {
         const job = this.jobs.get(jobId);
         if (!job)
             return null;
-        return await this.executeJob(job);
+        return await this.executeJob(job, 0, inputData);
     }
     // ==========================================================================
     // Scheduling
@@ -379,19 +379,20 @@ export class CronScheduler extends EventEmitter {
     // ==========================================================================
     // Execution
     // ==========================================================================
-    async executeJob(job, chainDepth = 0) {
+    async executeJob(job, chainDepth = 0, inputData) {
         const run = {
             id: crypto.randomUUID(),
             jobId: job.id,
             startedAt: new Date(),
             status: 'running',
+            ...(inputData !== undefined ? { inputData } : {}),
         };
         this.emit('job:run:start', run);
         try {
             // Execute task
             let result;
             if (this.taskExecutor) {
-                result = await this.taskExecutor(job);
+                result = await this.taskExecutor(job, inputData);
             }
             else {
                 // Default execution (just log)
@@ -401,6 +402,10 @@ export class CronScheduler extends EventEmitter {
             run.status = 'success';
             run.result = result;
             run.duration = run.completedAt.getTime() - run.startedAt.getTime();
+            // Extract outputData from the executor result for cross-job data passing.
+            // The executor may return an object with an `output` or `outputData`
+            // field; we cap at 64KB to keep run history manageable.
+            run.outputData = CronScheduler.extractOutputData(result);
             job.lastRunAt = run.startedAt;
             job.runCount++;
             // Reset backoff on success
@@ -444,10 +449,50 @@ export class CronScheduler extends EventEmitter {
         // successful run, so the chain runs inside a guarded helper that swallows
         // (and logs) any error from the chained job.
         if (run.status === 'success' && job.then) {
-            await this.runChainedJob(job, chainDepth);
+            await this.runChainedJob(job, chainDepth, run.outputData);
         }
         return run;
     }
+    /** Max bytes for outputData passed between chained jobs. */
+    static MAX_OUTPUT_DATA_BYTES = 65_536; // 64 KiB
+    /**
+     * Extract a string `outputData` from the executor result. Looks for an
+     * explicit `outputData` field first, then falls back to `output`, then
+     * stringifies the whole result. Always capped at 64KB.
+     */
+    static extractOutputData(result) {
+        if (result == null)
+            return undefined;
+        let raw;
+        if (typeof result === 'string') {
+            raw = result;
+        }
+        else if (typeof result === 'object') {
+            const obj = result;
+            if (typeof obj.outputData === 'string') {
+                raw = obj.outputData;
+            }
+            else if (typeof obj.output === 'string') {
+                raw = obj.output;
+            }
+            else {
+                try {
+                    raw = JSON.stringify(result);
+                }
+                catch {
+                    return undefined;
+                }
+            }
+        }
+        else {
+            raw = String(result);
+        }
+        if (!raw || raw.length === 0)
+            return undefined;
+        return raw.length > CronScheduler.MAX_OUTPUT_DATA_BYTES
+            ? raw.slice(0, CronScheduler.MAX_OUTPUT_DATA_BYTES)
+            : raw;
+    }
     /**
      * Resolve and execute a chained (`then`) job after its parent succeeds.
      *
@@ -455,7 +500,7 @@ export class CronScheduler extends EventEmitter {
      * authored out of order. A missing/disabled target, a self-reference, or a
      * depth-cap breach is logged and stops the chain — it never throws.
      */
-    async runChainedJob(parent, chainDepth) {
+    async runChainedJob(parent, chainDepth, outputData) {
         const target = parent.then;
         if (!target)
             return;
@@ -493,7 +538,8 @@ export class CronScheduler extends EventEmitter {
             return;
         }
         try {
-            await this.executeJob(next, chainDepth + 1);
+            // Pass the parent job's outputData as the chained job's inputData.
+            await this.executeJob(next, chainDepth + 1, outputData);
         }
         catch (err) {
             // A chained failure is captured in the chained job's own run record; it

package/dist/scheduler/script-runner.d.ts

@@ -26,6 +26,8 @@ export interface CronScriptResult {
     exitCode: number | null;
     /** Combined stdout + stderr, capped. */
     output: string;
+    /** Stdout only, capped at 64KB. Used for cross-job data passing. */
+    stdout: string;
     /** True when the timeout fired and the process was killed. */
     timedOut: boolean;
 }

package/dist/scheduler/script-runner.js

@@ -16,6 +16,7 @@ import { spawn } from 'child_process';
 import path from 'path';
 const DEFAULT_SCRIPT_TIMEOUT_MS = 600_000;
 const MAX_OUTPUT_BYTES = 1_048_576; // 1 MiB cap on captured output
+const MAX_STDOUT_BYTES = 65_536; // 64 KiB cap on stdout for data passing
 const DEFAULT_ALLOWED_EXECUTABLES = new Set([
     'bash',
     'cargo',
@@ -68,27 +69,41 @@ function spawnScript(command, timeoutMs) {
             windowsHide: true,
         });
         let output = '';
+        let stdoutOnly = '';
         let timedOut = false;
-        const append = (chunk) => {
+        const appendOutput = (chunk) => {
             if (output.length < MAX_OUTPUT_BYTES) {
                 output += chunk;
             }
         };
+        const appendStdout = (chunk) => {
+            if (stdoutOnly.length < MAX_STDOUT_BYTES) {
+                stdoutOnly += chunk;
+            }
+        };
         const timer = setTimeout(() => {
             timedOut = true;
             child.kill('SIGTERM');
         }, timeoutMs);
         child.stdout.setEncoding('utf8');
-        child.stdout.on('data', append);
+        child.stdout.on('data', (chunk) => {
+            appendOutput(chunk);
+            appendStdout(chunk);
+        });
         child.stderr.setEncoding('utf8');
-        child.stderr.on('data', append);
+        child.stderr.on('data', appendOutput);
         child.on('error', (error) => {
             clearTimeout(timer);
             reject(error);
         });
         child.on('close', (exitCode) => {
             clearTimeout(timer);
-            resolve({ exitCode, output: output.trimEnd(), timedOut });
+            resolve({
+                exitCode,
+                output: output.trimEnd(),
+                stdout: stdoutOnly.trimEnd(),
+                timedOut,
+            });
         });
     });
 }

package/dist/scheduler/watchdog-handlers.js

@@ -16,8 +16,8 @@
  * The aggregate `ok` is true only when there are no alerts and no errors.
  */
 import { spawn } from 'child_process';
-import fs from 'fs';
 import path from 'path';
+import { getFreeSpaceInfo } from '../utils/disk-guard.js';
 const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
 const DEFAULT_BUILD_ALLOWED_EXECUTABLES = new Set([
     'bash',
@@ -115,32 +115,19 @@ async function runSingleCheck(check, allowedExecutables) {
 }
 function checkDisk(check, name) {
     const target = check.path || process.cwd();
-    const statfs = fs.statfsSync;
-    if (typeof statfs !== 'function') {
+    // Single source of truth for free space (uses bavail); null when statfs is
+    // unavailable or the path can't be stat'd.
+    const info = getFreeSpaceInfo(target);
+    if (info === null) {
         return {
             type: 'disk',
             name,
             status: 'error',
-            summary: 'fs.statfsSync is not available in this Node runtime',
+            summary: `cannot determine free space at ${target} (fs.statfsSync unavailable or path unreadable)`,
             details: { path: target },
         };
     }
-    let stats;
-    try {
-        stats = statfs(target);
-    }
-    catch (err) {
-        return {
-            type: 'disk',
-            name,
-            status: 'error',
-            summary: `cannot stat filesystem at ${target}: ${errMsg(err)}`,
-            details: { path: target },
-        };
-    }
-    const totalBytes = stats.blocks * stats.bsize;
-    const freeBytes = stats.bavail * stats.bsize;
-    const freePercent = totalBytes > 0 ? (freeBytes / totalBytes) * 100 : 0;
+    const { freeBytes, totalBytes, freePercent } = info;
     const breaches = [];
     if (typeof check.minFreeBytes === 'number' && freeBytes < check.minFreeBytes) {
         breaches.push(`free ${formatBytes(freeBytes)} < min ${formatBytes(check.minFreeBytes)}`);

package/dist/search/usearch-index.js

@@ -89,8 +89,13 @@ export class USearchVectorIndex extends EventEmitter {
      */
     async loadUSearch() {
         try {
-            // Dynamic import for optional dependency
-            const usearch = (await import('usearch'));
+            // Dynamic import for an OPTIONAL native dependency (see optionalDependencies).
+            // Use a non-literal specifier so `tsc` doesn't require 'usearch' to be
+            // resolvable on every platform — it isn't installed on some CI runners
+            // (e.g. windows-latest), which otherwise fails type-check with TS2307.
+            // Types come from the local USearchModule interface, not the package.
+            const usearchSpecifier = 'usearch';
+            const usearch = (await import(usearchSpecifier));
             return usearch;
         }
         catch (_err) {

package/dist/security/tool-policy/tool-groups.js

@@ -42,6 +42,8 @@ export const TOOL_GROUPS = {
     // Runtime - Process
     spawn_process: ['group:runtime', 'group:runtime:process'],
     kill_process: ['group:runtime', 'group:runtime:process', 'group:dangerous'],
+    // Runtime - Office macros (arbitrary VBA/PowerShell via COM, Windows only)
+    office_macro_execute: ['group:runtime', 'group:runtime:shell', 'group:dangerous'],
     // Web - Fetch
     web_fetch: ['group:web', 'group:web:fetch'],
     http_request: ['group:web', 'group:web:fetch'],

package/dist/server/index.js

@@ -14,6 +14,8 @@ import { createRequire } from 'module';
 import express from 'express';
 import cors from 'cors';
 import { createServer } from 'http';
+import { createServer as createHttpsServer, Server as HttpsServer } from 'https';
+import { resolveServerTlsOptions } from './tls-config.js';
 const _require = createRequire(import.meta.url);
 let SERVER_VERSION = '0.0.0';
 try {
@@ -77,7 +79,10 @@ export function getServerBaseUrl(server, config) {
     const port = typeof address === 'object' && address ? address.port : config.port;
     const publicHost = config.host === '0.0.0.0' || config.host === '::' ? '127.0.0.1' : config.host;
     const host = publicHost.includes(':') && !publicHost.startsWith('[') ? `[${publicHost}]` : publicHost;
-    return `http://${host}:${port}`;
+    // Report https:// when the server was constructed with TLS so the logged URL
+    // isn't a lie. Default (plain http.Server) stays http://.
+    const scheme = server instanceof HttpsServer ? 'https' : 'http';
+    return `${scheme}://${host}:${port}`;
 }
 // Default configuration
 const DEFAULT_CONFIG = {
@@ -878,7 +883,17 @@ export async function startServer(userConfig = {}) {
         /* prometheus exporter optional */
     }
     const app = createApp(config);
-    const server = createServer(app);
+    // Optional TLS: serve the API (including /api/mobile) over HTTPS when
+    // CODEBUDDY_HTTPS / CODEBUDDY_MOBILE_TLS is set so the mobile-supervision
+    // endpoint can be exposed off-device securely. Default (no env) is plain HTTP,
+    // byte-for-byte unchanged. resolveServerTlsOptions() throws (never silently
+    // downgrades) if TLS is requested but cannot be satisfied. The https.Server
+    // surface (listen/address/on('upgrade')/close) matches http.Server at runtime,
+    // so we keep the `HttpServer` type to avoid widening downstream signatures.
+    const tlsOptions = resolveServerTlsOptions();
+    const server = tlsOptions
+        ? createHttpsServer(tlsOptions, app)
+        : createServer(app);
     const startChannelBridge = async (baseUrl) => {
         try {
             const { getChannelManager } = await import('../channels/index.js');

package/dist/server/routes/mobile.d.ts

@@ -1,4 +1,5 @@
 import { Request, Response, NextFunction } from 'express';
+import { EventEmitter } from 'events';
 export declare const mobileRouter: import("express-serve-static-core").Router;
 export declare let activePairingCode: string;
 export declare let activePairingCodeExpiresAt: number;
@@ -10,11 +11,11 @@ export declare const activeTokens: Map<string, {
  * A follow-up prompt review draft. The mobile device (or a draft-only call) can
  * *propose* a prompt, but it never executes: it lands here as
  * `needs_local_operator` and only a local operator (loopback) can `approve` or
- * `cancel` it. Approval is a review-gate marker — it records who/when but never
- * dispatches work, matching the gateway contract's `autoDispatch:false` /
- * `remoteExecutionDisabled:true` invariants.
+ * `cancel` it. When `CODEBUDDY_MOBILE_ALLOW_DISPATCH=true`, an approved draft
+ * can optionally be dispatched to the agent for execution. When the env var is
+ * OFF (default), approval remains a review-gate marker only.
  */
-export type FollowupDraftStatus = 'needs_local_operator' | 'approved' | 'cancelled';
+export type FollowupDraftStatus = 'needs_local_operator' | 'approved' | 'cancelled' | 'dispatched' | 'completed' | 'failed';
 export interface FollowupDraft {
     id: string;
     prompt: string;
@@ -24,9 +25,16 @@ export interface FollowupDraft {
     approvedBy?: string;
     approvedAt?: number;
     cancelledAt?: number;
+    dispatchedAt?: number;
+    completedAt?: number;
+    failedAt?: number;
+    failureReason?: string;
     [key: string]: unknown;
 }
 export declare const followupDrafts: FollowupDraft[];
+export declare const mobileEventBus: EventEmitter<[never]>;
+/** Check whether dispatch is enabled via environment variable. */
+export declare function isDispatchEnabled(): boolean;
 /**
  * Decide whether a request originates from the loopback interface. We read the
  * raw socket address (`req.socket.remoteAddress`) on purpose: `req.ip` and the

package/dist/server/routes/mobile.js

@@ -1,5 +1,6 @@
 import { Router } from 'express';
 import crypto from 'crypto';
+import { EventEmitter } from 'events';
 import path from 'path';
 import fs from 'fs';
 import { logger } from '../../utils/logger.js';
@@ -36,6 +37,11 @@ function rotatePairingCode() {
     }
     activePairingCode = nextCode;
     activePairingCodeExpiresAt = Date.now() + getPairingCodeTtlMs();
+    mobileEventBus.emit('event', {
+        type: 'pairing_rotated',
+        pairingCodeExpiresAt: activePairingCodeExpiresAt,
+        timestamp: Date.now(),
+    });
     return activePairingCode;
 }
 function ensureActivePairingCodeFresh() {
@@ -44,6 +50,15 @@ function ensureActivePairingCodeFresh() {
     }
 }
 export const followupDrafts = [];
+// ──────────────────────────────────────────────────────────────────────────
+// Mobile event bus — emits SSE-pushed events for mobile clients.
+// ──────────────────────────────────────────────────────────────────────────
+export const mobileEventBus = new EventEmitter();
+mobileEventBus.setMaxListeners(50);
+/** Check whether dispatch is enabled via environment variable. */
+export function isDispatchEnabled() {
+    return process.env.CODEBUDDY_MOBILE_ALLOW_DISPATCH === 'true';
+}
 function pruneExpiredTokens(now = Date.now()) {
     for (const [token, tokenData] of activeTokens) {
         if (now > tokenData.expiresAt) {
@@ -158,7 +173,8 @@ mobileRouter.get('/followup-drafts', loopbackOnlyMiddleware, (req, res) => {
     res.json({ ok: true, drafts: followupDrafts });
 });
 // POST /api/mobile/followup-draft/:id/approve: local operator approves a draft.
-// Approval is a review-gate marker only — it NEVER dispatches or executes work.
+// When CODEBUDDY_MOBILE_ALLOW_DISPATCH is OFF (default), approval is a
+// review-gate marker only — it never dispatches or executes work.
 mobileRouter.post('/followup-draft/:id/approve', loopbackOnlyMiddleware, (req, res) => {
     const draft = followupDrafts.find((d) => d.id === req.params.id);
     if (!draft) {
@@ -175,6 +191,12 @@ mobileRouter.post('/followup-draft/:id/approve', loopbackOnlyMiddleware, (req, r
     draft.status = 'approved';
     draft.approvedBy = reviewer;
     draft.approvedAt = Date.now();
+    mobileEventBus.emit('event', {
+        type: 'draft_status_changed',
+        draftId: draft.id,
+        status: draft.status,
+        timestamp: Date.now(),
+    });
     res.json({
         ok: true,
         message: 'Draft approved by local operator. No work is dispatched automatically — execution stays local and explicit.',
@@ -194,8 +216,52 @@ mobileRouter.post('/followup-draft/:id/cancel', loopbackOnlyMiddleware, (req, re
     }
     draft.status = 'cancelled';
     draft.cancelledAt = Date.now();
+    mobileEventBus.emit('event', {
+        type: 'draft_status_changed',
+        draftId: draft.id,
+        status: draft.status,
+        timestamp: Date.now(),
+    });
     res.json({ ok: true, message: 'Draft cancelled by local operator.', draft });
 });
+// POST /api/mobile/followup-draft/:id/dispatch: local operator dispatches an
+// approved draft to the agent. Gated behind CODEBUDDY_MOBILE_ALLOW_DISPATCH.
+mobileRouter.post('/followup-draft/:id/dispatch', loopbackOnlyMiddleware, (req, res) => {
+    if (!isDispatchEnabled()) {
+        res.status(403).json({
+            ok: false,
+            error: 'Dispatch is disabled. Set CODEBUDDY_MOBILE_ALLOW_DISPATCH=true to enable.',
+        });
+        return;
+    }
+    const draft = followupDrafts.find((d) => d.id === req.params.id);
+    if (!draft) {
+        res.status(404).json({ ok: false, error: 'Draft not found' });
+        return;
+    }
+    if (draft.status !== 'approved') {
+        res.status(409).json({
+            ok: false,
+            error: `Draft must be approved before dispatch (status: ${draft.status})`,
+        });
+        return;
+    }
+    draft.status = 'dispatched';
+    draft.dispatchedAt = Date.now();
+    mobileEventBus.emit('event', {
+        type: 'draft_status_changed',
+        draftId: draft.id,
+        status: draft.status,
+        timestamp: Date.now(),
+    });
+    // Emit a dispatch queue entry for the agent to pick up.
+    mobileEventBus.emit('dispatch', { draftId: draft.id, prompt: draft.prompt });
+    res.json({
+        ok: true,
+        message: 'Draft dispatched to agent for execution.',
+        draft,
+    });
+});
 // 1. POST /api/mobile/pair: Validate pairing request and issue short-lived token
 mobileRouter.post('/pair', (req, res) => {
     const code = typeof req.body?.code === 'string' ? req.body.code.trim() : '';
@@ -221,6 +287,49 @@ mobileRouter.post('/pair', (req, res) => {
         expiresAt,
     });
 });
+// ──────────────────────────────────────────────────────────────────────────
+// SSE push endpoint — authenticated via mobile bearer token (query param
+// fallback for EventSource API which doesn't support Authorization header).
+// Pushes: draft_status_changed, snapshot_available, pairing_rotated.
+// ──────────────────────────────────────────────────────────────────────────
+const HEARTBEAT_INTERVAL_MS = 30_000;
+mobileRouter.get('/events', (req, res) => {
+    // Auth: prefer Authorization header, fall back to ?token= query param.
+    const authHeader = req.headers.authorization;
+    let token;
+    if (authHeader && authHeader.startsWith('Bearer ')) {
+        token = authHeader.substring(7).trim();
+    }
+    else if (typeof req.query.token === 'string') {
+        token = req.query.token.trim();
+    }
+    if (!token || !isValidToken(token)) {
+        res.status(401).json({ ok: false, error: 'Unauthorized: Invalid or expired pairing token' });
+        return;
+    }
+    // SSE headers.
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+    res.flushHeaders();
+    const sendSSE = (payload) => {
+        res.write(`data: ${JSON.stringify(payload)}\n\n`);
+    };
+    // Heartbeat to keep the connection alive.
+    const heartbeat = setInterval(() => {
+        sendSSE({ type: 'heartbeat', timestamp: Date.now() });
+    }, HEARTBEAT_INTERVAL_MS);
+    // Forward bus events to this SSE client.
+    const onEvent = (payload) => {
+        sendSSE(payload);
+    };
+    mobileEventBus.on('event', onEvent);
+    // Cleanup on disconnect.
+    req.on('close', () => {
+        clearInterval(heartbeat);
+        mobileEventBus.off('event', onEvent);
+    });
+});
 // Apply mobile auth middleware to all remaining routes
 mobileRouter.use(mobileAuthMiddleware);
 // 2. GET /api/mobile/snapshot: Return active run snapshot summary
@@ -331,6 +440,12 @@ async function enqueuePendingFollowupDraft(prompt, query, source) {
         createdAt: Date.now(),
     };
     followupDrafts.push(savedDraft);
+    mobileEventBus.emit('event', {
+        type: 'draft_status_changed',
+        draftId: savedDraft.id,
+        status: savedDraft.status,
+        timestamp: Date.now(),
+    });
     return savedDraft;
 }
 // 5. POST /api/mobile/followup-draft: Save a local operator followup review draft

package/dist/server/tls-config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Optional TLS for the API server.
+ *
+ * The mobile-supervision endpoint (`/api/mobile`) rides the main HTTP server.
+ * To expose it off-device securely it can be served over HTTPS. This is purely
+ * transport security — it does not change any product gate (the dispatch gate
+ * `CODEBUDDY_MOBILE_ALLOW_DISPATCH` is untouched).
+ *
+ * Behaviour, gated by env (HTTP stays the default — no env, no TLS):
+ *  - `CODEBUDDY_HTTPS=1` (or `CODEBUDDY_MOBILE_TLS=1`) enables HTTPS.
+ *  - `CODEBUDDY_TLS_CERT` / `CODEBUDDY_TLS_KEY` = paths to a PEM cert/key. This
+ *    is the standard production approach (Let's Encrypt / reverse proxy / the
+ *    operator provisions the cert).
+ *  - If TLS is enabled but no cert is provided, a dev self-signed cert is
+ *    generated via `openssl` (if on PATH) into `~/.codebuddy/tls/` and reused.
+ *  - If TLS is enabled but it cannot be satisfied (cert unreadable, or openssl
+ *    absent), this **throws** with a clear message. It never silently falls back
+ *    to plain HTTP — an operator who asked for TLS must not be downgraded.
+ *
+ * Uses only Node built-ins (`https`, `fs`, `child_process`) — no new dependency.
+ */
+export interface ServerTlsOptions {
+    cert: string | Buffer;
+    key: string | Buffer;
+}
+/** Whether HTTPS is requested for the API server. */
+export declare function isTlsEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolve TLS options for the server, or `null` when TLS is not requested.
+ *
+ * Returns `null` (HTTP, unchanged default) when neither `CODEBUDDY_HTTPS` nor
+ * `CODEBUDDY_MOBILE_TLS` is set. Throws a clear error if TLS is requested but
+ * cannot be satisfied — it never downgrades to HTTP behind the operator's back.
+ */
+export declare function resolveServerTlsOptions(env?: NodeJS.ProcessEnv): ServerTlsOptions | null;