@questionbase/deskfree 0.3.0-alpha.8 → 0.4.0-alpha.1

package/dist/cli/install.d.ts

@@ -0,0 +1,3 @@
+declare function install(token: string): void;
+
+export { install };

package/dist/cli/install.js

@@ -0,0 +1,53 @@
+import { createRequire } from 'node:module';
+import { execSync } from 'child_process';
+import { writeFileSync, chmodSync } from 'fs';
+
+createRequire(import.meta.url);
+var SERVICE_NAME = "deskfree-agent";
+var SERVICE_FILE = `/etc/systemd/system/${SERVICE_NAME}.service`;
+var ENV_FILE = `/etc/${SERVICE_NAME}.env`;
+var PACKAGE = "@questionbase/deskfree-agents-sdk@latest";
+function install(token) {
+  if (process.getuid?.() !== 0) {
+    console.error("Error: install must be run as root (use sudo)");
+    process.exit(1);
+  }
+  let npxPath;
+  try {
+    npxPath = execSync("which npx", { encoding: "utf8" }).trim();
+  } catch {
+    console.error("Error: npx not found in PATH");
+    process.exit(1);
+  }
+  writeFileSync(ENV_FILE, `DESKFREE_LAUNCH=${token}
+`, { mode: 384 });
+  chmodSync(ENV_FILE, 384);
+  console.log(`Wrote ${ENV_FILE}`);
+  const unit = `[Unit]
+Description=DeskFree Agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${npxPath} ${PACKAGE} start
+EnvironmentFile=${ENV_FILE}
+Environment=NODE_ENV=production
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+`;
+  writeFileSync(SERVICE_FILE, unit);
+  console.log(`Wrote ${SERVICE_FILE}`);
+  execSync("systemctl daemon-reload");
+  execSync(`systemctl enable ${SERVICE_NAME}`);
+  execSync(`systemctl start ${SERVICE_NAME}`);
+  console.log(`Service ${SERVICE_NAME} installed and started.`);
+  console.log(`Check status: systemctl status ${SERVICE_NAME}`);
+}
+
+export { install };
+//# sourceMappingURL=install.js.map
+//# sourceMappingURL=install.js.map

package/dist/cli/install.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cli/install.ts"],"names":[],"mappings":";;;;;AAGA,IAAM,YAAA,GAAe,gBAAA;AACrB,IAAM,YAAA,GAAe,uBAAuB,YAAY,CAAA,QAAA,CAAA;AACxD,IAAM,QAAA,GAAW,QAAQ,YAAY,CAAA,IAAA,CAAA;AACrC,IAAM,OAAA,GAAU,0CAAA;AAET,SAAS,QAAQ,KAAA,EAAqB;AAC3C,EAAA,IAAI,OAAA,CAAQ,MAAA,IAAS,KAAM,CAAA,EAAG;AAC5B,IAAA,OAAA,CAAQ,MAAM,+CAA+C,CAAA;AAC7D,IAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AAAA,EAChB;AAGA,EAAA,IAAI,OAAA;AACJ,EAAA,IAAI;AACF,IAAA,OAAA,GAAU,SAAS,WAAA,EAAa,EAAE,UAAU,MAAA,EAAQ,EAAE,IAAA,EAAK;AAAA,EAC7D,CAAA,CAAA,MAAQ;AACN,IAAA,OAAA,CAAQ,MAAM,8BAA8B,CAAA;AAC5C,IAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AAAA,EAChB;AAGA,EAAA,aAAA,CAAc,QAAA,EAAU,mBAAmB,KAAK;AAAA,CAAA,EAAM,EAAE,IAAA,EAAM,GAAA,EAAO,CAAA;AACrE,EAAA,SAAA,CAAU,UAAU,GAAK,CAAA;AACzB,EAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,MAAA,EAAS,QAAQ,CAAA,CAAE,CAAA;AAG/B,EAAA,MAAM,IAAA,GAAO,CAAA;AAAA;AAAA;AAAA;;AAAA;AAAA;AAAA,UAAA,EAOH,OAAO,IAAI,OAAO,CAAA;AAAA,gBAAA,EACZ,QAAQ;AAAA;AAAA;AAAA;;AAAA;AAAA;AAAA,CAAA;AASxB,EAAA,aAAA,CAAc,cAAc,IAAI,CAAA;AAChC,EAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,MAAA,EAAS,YAAY,CAAA,CAAE,CAAA;AAGnC,EAAA,QAAA,CAAS,yBAAyB,CAAA;AAClC,EAAA,QAAA,CAAS,CAAA,iBAAA,EAAoB,YAAY,CAAA,CAAE,CAAA;AAC3C,EAAA,QAAA,CAAS,CAAA,gBAAA,EAAmB,YAAY,CAAA,CAAE,CAAA;AAE1C,EAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,QAAA,EAAW,YAAY,CAAA,uBAAA,CAAyB,CAAA;AAC5D,EAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,+BAAA,EAAkC,YAAY,CAAA,CAAE,CAAA;AAC9D","file":"install.js","sourcesContent":["import { execSync } from 'node:child_process';\nimport { chmodSync, writeFileSync } from 'node:fs';\n\nconst SERVICE_NAME = 'deskfree-agent';\nconst SERVICE_FILE = `/etc/systemd/system/${SERVICE_NAME}.service`;\nconst ENV_FILE = `/etc/${SERVICE_NAME}.env`;\nconst PACKAGE = '@questionbase/deskfree-agents-sdk@latest';\n\nexport function install(token: string): void {\n  if (process.getuid?.() !== 0) {\n    console.error('Error: install must be run as root (use sudo)');\n    process.exit(1);\n  }\n\n  // Resolve full npx path so systemd doesn't depend on PATH\n  let npxPath: string;\n  try {\n    npxPath = execSync('which npx', { encoding: 'utf8' }).trim();\n  } catch {\n    console.error('Error: npx not found in PATH');\n    process.exit(1);\n  }\n\n  // Write env file with token (chmod 600 — only root can read)\n  writeFileSync(ENV_FILE, `DESKFREE_LAUNCH=${token}\\n`, { mode: 0o600 });\n  chmodSync(ENV_FILE, 0o600);\n  console.log(`Wrote ${ENV_FILE}`);\n\n  // Write systemd unit file\n  const unit = `[Unit]\nDescription=DeskFree Agent\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nExecStart=${npxPath} ${PACKAGE} start\nEnvironmentFile=${ENV_FILE}\nEnvironment=NODE_ENV=production\nRestart=always\nRestartSec=10\n\n[Install]\nWantedBy=multi-user.target\n`;\n\n  writeFileSync(SERVICE_FILE, unit);\n  console.log(`Wrote ${SERVICE_FILE}`);\n\n  // Enable and start\n  execSync('systemctl daemon-reload');\n  execSync(`systemctl enable ${SERVICE_NAME}`);\n  execSync(`systemctl start ${SERVICE_NAME}`);\n\n  console.log(`Service ${SERVICE_NAME} installed and started.`);\n  console.log(`Check status: systemctl status ${SERVICE_NAME}`);\n}\n"]}

package/dist/cli/uninstall.d.ts

@@ -0,0 +1,3 @@
+declare function uninstall(): void;
+
+export { uninstall };

package/dist/cli/uninstall.js

@@ -0,0 +1,36 @@
+import { createRequire } from 'node:module';
+import { execSync } from 'child_process';
+import { existsSync, unlinkSync } from 'fs';
+
+createRequire(import.meta.url);
+var SERVICE_NAME = "deskfree-agent";
+var SERVICE_FILE = `/etc/systemd/system/${SERVICE_NAME}.service`;
+var ENV_FILE = `/etc/${SERVICE_NAME}.env`;
+function uninstall() {
+  if (process.getuid?.() !== 0) {
+    console.error("Error: uninstall must be run as root (use sudo)");
+    process.exit(1);
+  }
+  try {
+    execSync(`systemctl stop ${SERVICE_NAME}`, { stdio: "ignore" });
+  } catch {
+  }
+  try {
+    execSync(`systemctl disable ${SERVICE_NAME}`, { stdio: "ignore" });
+  } catch {
+  }
+  if (existsSync(SERVICE_FILE)) {
+    unlinkSync(SERVICE_FILE);
+    console.log(`Removed ${SERVICE_FILE}`);
+  }
+  if (existsSync(ENV_FILE)) {
+    unlinkSync(ENV_FILE);
+    console.log(`Removed ${ENV_FILE}`);
+  }
+  execSync("systemctl daemon-reload");
+  console.log(`Service ${SERVICE_NAME} uninstalled.`);
+}
+
+export { uninstall };
+//# sourceMappingURL=uninstall.js.map
+//# sourceMappingURL=uninstall.js.map

package/dist/cli/uninstall.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cli/uninstall.ts"],"names":[],"mappings":";;;;;AAGA,IAAM,YAAA,GAAe,gBAAA;AACrB,IAAM,YAAA,GAAe,uBAAuB,YAAY,CAAA,QAAA,CAAA;AACxD,IAAM,QAAA,GAAW,QAAQ,YAAY,CAAA,IAAA,CAAA;AAE9B,SAAS,SAAA,GAAkB;AAChC,EAAA,IAAI,OAAA,CAAQ,MAAA,IAAS,KAAM,CAAA,EAAG;AAC5B,IAAA,OAAA,CAAQ,MAAM,iDAAiD,CAAA;AAC/D,IAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AAAA,EAChB;AAGA,EAAA,IAAI;AACF,IAAA,QAAA,CAAS,kBAAkB,YAAY,CAAA,CAAA,EAAI,EAAE,KAAA,EAAO,UAAU,CAAA;AAAA,EAChE,CAAA,CAAA,MAAQ;AAAA,EAER;AACA,EAAA,IAAI;AACF,IAAA,QAAA,CAAS,qBAAqB,YAAY,CAAA,CAAA,EAAI,EAAE,KAAA,EAAO,UAAU,CAAA;AAAA,EACnE,CAAA,CAAA,MAAQ;AAAA,EAER;AAGA,EAAA,IAAI,UAAA,CAAW,YAAY,CAAA,EAAG;AAC5B,IAAA,UAAA,CAAW,YAAY,CAAA;AACvB,IAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,QAAA,EAAW,YAAY,CAAA,CAAE,CAAA;AAAA,EACvC;AACA,EAAA,IAAI,UAAA,CAAW,QAAQ,CAAA,EAAG;AACxB,IAAA,UAAA,CAAW,QAAQ,CAAA;AACnB,IAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,QAAA,EAAW,QAAQ,CAAA,CAAE,CAAA;AAAA,EACnC;AAEA,EAAA,QAAA,CAAS,yBAAyB,CAAA;AAClC,EAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,QAAA,EAAW,YAAY,CAAA,aAAA,CAAe,CAAA;AACpD","file":"uninstall.js","sourcesContent":["import { execSync } from 'node:child_process';\nimport { existsSync, unlinkSync } from 'node:fs';\n\nconst SERVICE_NAME = 'deskfree-agent';\nconst SERVICE_FILE = `/etc/systemd/system/${SERVICE_NAME}.service`;\nconst ENV_FILE = `/etc/${SERVICE_NAME}.env`;\n\nexport function uninstall(): void {\n  if (process.getuid?.() !== 0) {\n    console.error('Error: uninstall must be run as root (use sudo)');\n    process.exit(1);\n  }\n\n  // Stop and disable (ignore errors if not running/enabled)\n  try {\n    execSync(`systemctl stop ${SERVICE_NAME}`, { stdio: 'ignore' });\n  } catch {\n    // not running — fine\n  }\n  try {\n    execSync(`systemctl disable ${SERVICE_NAME}`, { stdio: 'ignore' });\n  } catch {\n    // not enabled — fine\n  }\n\n  // Remove files\n  if (existsSync(SERVICE_FILE)) {\n    unlinkSync(SERVICE_FILE);\n    console.log(`Removed ${SERVICE_FILE}`);\n  }\n  if (existsSync(ENV_FILE)) {\n    unlinkSync(ENV_FILE);\n    console.log(`Removed ${ENV_FILE}`);\n  }\n\n  execSync('systemctl daemon-reload');\n  console.log(`Service ${SERVICE_NAME} uninstalled.`);\n}\n"]}

package/dist/index.d.ts

@@ -1,12 +1,419 @@
-import type { OpenClawPluginApi } from './types';
-export { DeskFreeClient, DeskFreeError } from './client';
-export { reportError } from './error-reporter';
-export { OfflineQueue } from './offline-queue';
-export type * from './types';
-declare const plugin: {
-    id: string;
-    name: string;
-    register(api: OpenClawPluginApi): void;
-};
-export default plugin;
-//# sourceMappingURL=index.d.ts.map
+import { PluginLogger, DeskFreeClient, DeskFreeTool, ChatMessage, RuntimeBootstrapConfig } from '@deskfree/core';
+import * as _anthropic_ai_claude_agent_sdk from '@anthropic-ai/claude-agent-sdk';
+import { McpSdkServerConfigWithInstance, SDKMessage, SDKUserMessage, Query, tool } from '@anthropic-ai/claude-agent-sdk';
+
+interface StartAgentOptions {
+    log?: PluginLogger;
+}
+/** Dispose function returned by startAgent — call to shut down cleanly. */
+type DisposeAgent = () => void;
+/**
+ * Full agent startup sequence:
+ *
+ * 1. Load local config (token + apiUrl from env)
+ * 2. Create DeskFree client
+ * 3. Bootstrap: fetch config from API (wsUrl, model, region, tools)
+ * 4. Install enabled tool packages
+ * 5. Configure Agent SDK env vars (Bedrock, region, model)
+ * 6. Create MCP servers
+ * 7. Start health server + WS gateway + heartbeat
+ */
+declare function startAgent(opts?: StartAgentOptions): Promise<DisposeAgent>;
+
+interface OrchestratorQueryOptions {
+    prompt: string;
+    orchestratorServer: McpSdkServerConfigWithInstance;
+    model: string;
+    /** Agent SDK session ID to resume (for multi-turn conversations). */
+    sessionId?: string;
+}
+/**
+ * Run the orchestrator agent. Returns an async iterable of SDKMessage events.
+ *
+ * The orchestrator:
+ * - Uses DeskFree orchestrator tools via MCP
+ * - Dispatches workers via the deskfree_dispatch_worker MCP tool
+ * - Persists sessions for multi-turn conversations
+ */
+declare function runOrchestrator(opts: OrchestratorQueryOptions): AsyncGenerator<SDKMessage, void>;
+interface HeartbeatOptions {
+    prompt: string;
+    orchestratorServer: McpSdkServerConfigWithInstance;
+    model: string;
+}
+/**
+ * Run a one-shot heartbeat query (no session persistence).
+ */
+declare function runHeartbeat(opts: HeartbeatOptions): AsyncGenerator<SDKMessage, void>;
+
+interface WorkerQueryOptions {
+    prompt: string | AsyncIterable<SDKUserMessage>;
+    workerServer: McpSdkServerConfigWithInstance;
+    model: string;
+    /** Agent SDK session ID to resume (for multi-turn task conversations). */
+    sessionId?: string;
+}
+/**
+ * Run the worker agent directly. Returns a Query (async iterable of
+ * SDKMessage events with a .close() method for teardown).
+ *
+ * Used for task thread messages where the router routes to 'runner'.
+ * The worker:
+ * - Claims a task and loads its context
+ * - Executes work (update files, steps, send messages)
+ * - Completes the task
+ */
+declare function runWorker(opts: WorkerQueryOptions): Query;
+
+/**
+ * Manages daily log files for memory observations.
+ *
+ * Logs are stored at `{stateDir}/memory/{botId}/daily/YYYY-MM-DD.md`.
+ * Each entry is a single line: `- [ISO timestamp] (task: {taskId}) {content}`
+ *
+ * Appends are atomic via O_APPEND flag (safe for writes <4KB on Linux).
+ */
+declare class DailyLogManager {
+    private readonly dailyDir;
+    constructor(stateDir: string, botId: string);
+    /** Ensure the daily log directory exists. */
+    init(): void;
+    /** Append a learning entry to today's log file. */
+    appendLearning(content: string, taskId?: string): Promise<void>;
+    /** Read today's daily log, or null if it doesn't exist. */
+    readToday(): Promise<string | null>;
+    /** Read all daily logs, concatenated with date headers. */
+    readAllLogs(): Promise<string | null>;
+    /**
+     * Read recent daily logs up to a character budget (newest first).
+     * Returns as many days as fit. Quiet week → 14 days. Busy day → just today.
+     */
+    readRecentWithBudget(maxChars: number): Promise<string | null>;
+    /** Delete daily log files older than the given number of days. */
+    pruneOlderThan(days: number): void;
+    private todayPath;
+}
+
+interface WorkerManagerDeps {
+    client: DeskFreeClient;
+    createWorkerServer: () => McpSdkServerConfigWithInstance;
+    model: string;
+    log: PluginLogger;
+    /** Max concurrent workers. Defaults to 5. */
+    maxConcurrentWorkers?: number;
+    /** DailyLogManager for injecting recent observations into worker context. */
+    dailyLog?: DailyLogManager;
+    /** Character budget for daily log injection (~4 chars/token). Defaults to 16000. */
+    dailyLogCharBudget?: number;
+    /** Path to persist session history JSON (taskId → sessionId). */
+    sessionHistoryPath?: string;
+}
+declare class WorkerManager {
+    private workers;
+    /** Persists taskId → sessionId across worker restarts for session resume. */
+    private sessionHistory;
+    private pendingQueue;
+    private deps;
+    private maxConcurrent;
+    constructor(deps: WorkerManagerDeps);
+    /** Check if a worker is currently active for a task. */
+    has(taskId: string): boolean;
+    /**
+     * Dispatch a new long-lived worker for a task.
+     * Claims the task and loads workspace state server-side, then builds
+     * an enriched first message so the worker can start immediately.
+     *
+     * If at capacity, queues the dispatch and notifies the user.
+     * If a worker already exists for this taskId, returns 'already_running'.
+     */
+    dispatch(taskId: string, userMessage?: string): Promise<'started' | 'already_running' | 'queued'>;
+    /** Number of active workers. */
+    get activeCount(): number;
+    /** Number of queued dispatches waiting for a slot. */
+    get queuedCount(): number;
+    /** Maximum number of concurrent workers allowed. */
+    get maxConcurrentWorkers(): number;
+    /**
+     * Push a message into an active worker's channel.
+     * Resets the idle timer.
+     */
+    pushMessage(taskId: string, content: string): void;
+    /** Tear down a specific worker. */
+    teardown(taskId: string): void;
+    /** Tear down all active workers and clear the queue (shutdown hook). */
+    teardownAll(): void;
+    /** Core worker startup logic (no capacity check — callers must check first). */
+    private startWorker;
+    /** Drain the pending queue — called when a worker finishes. */
+    private drainQueue;
+    private startIdleTimer;
+    /**
+     * Background drain loop — processes query output and streams it back
+     * to DeskFree via DeskFreeStreamingSession.
+     */
+    private drainLoop;
+    /** Load session history from disk (best-effort). */
+    private loadSessionHistory;
+    /** Persist session history to disk (best-effort). */
+    private saveSessionHistory;
+    /** Build an SDKUserMessage from plain text content. */
+    private buildUserMessage;
+}
+
+/**
+ * Create an in-process MCP server with orchestrator tools.
+ *
+ * When a WorkerManager is provided, adds the deskfree_dispatch_worker
+ * tool that lets the orchestrator dispatch long-lived workers for tasks.
+ */
+declare function createOrchestratorMcpServer(client: DeskFreeClient, customTools?: DeskFreeTool[], workerManager?: WorkerManager): _anthropic_ai_claude_agent_sdk.McpSdkServerConfigWithInstance;
+
+interface ContentScanner {
+    scan(content: string): Promise<ScanResult>;
+}
+interface ScanResult {
+    safe: boolean;
+    reason?: string;
+}
+/**
+ * Default content scanner — applies heuristic injection pattern detection.
+ * In production the backend may provide a more sophisticated scanner.
+ */
+declare class DefaultContentScanner implements ContentScanner {
+    private readonly log?;
+    constructor(log?: PluginLogger | undefined);
+    scan(content: string): Promise<ScanResult>;
+}
+/**
+ * Wrap a tool's execute function with content scan verification.
+ * Used to gate file write operations.
+ *
+ * @param execute - The original tool execute function
+ * @param extractContent - Function to extract the text content to scan from args
+ * @param scanner - ContentScanner implementation
+ */
+declare function withContentScan<TArgs extends Record<string, unknown>>(execute: (args: TArgs) => Promise<unknown>, extractContent: (args: TArgs) => string | null | undefined, scanner: ContentScanner): (args: TArgs) => Promise<unknown>;
+/**
+ * Validate a URL is safe to fetch (HTTPS only, no private IPs).
+ * Throws an error with a descriptive message if validation fails.
+ */
+declare function validateDownloadUrl(url: string): void;
+/**
+ * Check whether a content type is allowed for attachment downloads.
+ */
+declare function isContentTypeAllowed(contentType: string): boolean;
+/**
+ * Sanitize a filename to prevent directory traversal and injection.
+ */
+declare function sanitizeFileName(fileName: string): string;
+
+/**
+ * Create an in-process MCP server with worker tools.
+ *
+ * If a ContentScanner is provided, the deskfree_update_file tool's execute
+ * function is wrapped to scan file content for prompt injection before
+ * allowing the write.
+ */
+declare function createWorkerMcpServer(client: DeskFreeClient, customTools?: DeskFreeTool[], contentScanner?: ContentScanner, dailyLog?: DailyLogManager): _anthropic_ai_claude_agent_sdk.McpSdkServerConfigWithInstance;
+
+/**
+ * MCP Tool Adapter
+ *
+ * Converts DeskFreeTool[] into Agent SDK tool() definitions.
+ * JSON Schema parameters are converted to Zod schemas for the SDK's
+ * type-safe tool() function.
+ */
+
+type AgentSdkTool = ReturnType<typeof tool>;
+/**
+ * Adapt a single DeskFreeTool into an Agent SDK tool() definition.
+ *
+ * The handler delegates to `tool.execute()` which returns a `ToolResult`
+ * — this is already compatible with the MCP `CallToolResult` shape:
+ *   `{ content: Array<{ type: 'text', text: string }>, isError?: boolean }`
+ */
+declare function adaptTool(deskfreeTool: DeskFreeTool): AgentSdkTool;
+/**
+ * Adapt an array of DeskFree tools into Agent SDK tool() definitions.
+ */
+declare function adaptTools(tools: DeskFreeTool[]): AgentSdkTool[];
+
+/**
+ * Session Store — maps DeskFree session keys to Agent SDK session IDs.
+ *
+ * Session keys:
+ *   dm:<peerId>       — DM messages routed to orchestrator
+ *   task:<taskId>     — Task thread messages routed to worker
+ *
+ * The Agent SDK handles conversation history internally via session
+ * persistence. We only need to track the mapping from our session keys
+ * to the Agent SDK session IDs.
+ *
+ * Why in-memory is fine:
+ * - Container restarts are clean — agents re-claim context from backend
+ * - Session ID mapping is a performance optimization, not state of record
+ * - Backend stores all messages persistently
+ */
+interface SessionEntry {
+    /** Agent SDK session ID for resuming conversations. */
+    agentSessionId: string;
+    /** Timestamp of last activity (for TTL eviction). */
+    lastActivityAt: number;
+}
+declare class SessionStore {
+    private readonly staleTtlMs;
+    private readonly maxSessions;
+    private readonly sessions;
+    private cleanupTimer;
+    constructor(staleTtlMs?: number, // 30 min TTL
+    maxSessions?: number);
+    /**
+     * Get the Agent SDK session ID for a given key.
+     * Returns undefined if no session exists or it has expired.
+     */
+    getSessionId(key: string): string | undefined;
+    /**
+     * Store an Agent SDK session ID for a given key.
+     */
+    setSessionId(key: string, agentSessionId: string): void;
+    /** Delete a specific session. */
+    delete(key: string): void;
+    /** Number of active sessions. */
+    get size(): number;
+    /** Remove sessions that haven't been active within the TTL. */
+    private cleanup;
+    /** Evict the session with the oldest lastActivityAt. */
+    private evictOldest;
+    /** Dispose — clear the cleanup timer. */
+    dispose(): void;
+}
+
+interface WorkerStatus {
+    activeWorkers: number;
+    queuedTasks: number;
+    maxConcurrency: number;
+}
+interface GatewayConfig {
+    client: DeskFreeClient;
+    wsUrl: string;
+    accountId: string;
+    stateDir: string;
+    log: PluginLogger;
+    abortSignal: AbortSignal;
+    onMessage: (message: ChatMessage) => Promise<void>;
+    getWorkerStatus?: () => WorkerStatus;
+}
+/**
+ * Start the WS gateway — reconnection loop with backoff.
+ *
+ * Loop: getWsTicket() → connect → listen for notify → poll messages → deliver
+ * On disconnect: backoff → reconnect
+ * Fallback: interval-based polling when WS is unavailable
+ */
+declare function startGateway(config: GatewayConfig): Promise<void>;
+
+interface ToolPackageConfig {
+    package: string;
+    version: string;
+}
+/**
+ * Install tool packages into an isolated directory.
+ * Creates a minimal package.json and runs `bun install`.
+ *
+ * Tool packages are pre-bundled single files with zero deps —
+ * install is fast (~2-5s for a handful of tools).
+ *
+ * Security: only @deskfree/tool-* packages are allowed.
+ */
+declare function installTools(tools: ToolPackageConfig[], toolsDir: string, log?: PluginLogger): Promise<void>;
+/**
+ * Load installed tool packages and extract DeskFreeTool definitions.
+ *
+ * Each @deskfree/tool-* package must export one of:
+ *   export const tools: DeskFreeTool[]
+ *   export function createTools(): DeskFreeTool[]
+ */
+declare function loadToolModules(tools: ToolPackageConfig[], toolsDir: string, log?: PluginLogger): Promise<DeskFreeTool[]>;
+
+/**
+ * Local config: values known before connecting to the API.
+ * Only botToken + apiUrl are required. Everything else has sensible defaults.
+ */
+interface LocalConfig {
+    /** Bot authentication token (required) */
+    botToken: string;
+    /** DeskFree backend API URL (required) */
+    apiUrl: string;
+    /** Directory for cursor + media storage */
+    stateDir: string;
+    /** Directory for dynamic tool installs */
+    toolsDir: string;
+    /** Log level */
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    /** HTTP port for health check endpoint */
+    healthPort: number;
+}
+/**
+ * Full runtime config: local config + API-bootstrapped values.
+ * Built by merging LocalConfig with the config.get response.
+ * Env var overrides take precedence over API values.
+ */
+interface RuntimeConfig extends LocalConfig {
+    /** DeskFree WebSocket URL */
+    wsUrl: string;
+    /** Model ID (Bedrock or Anthropic format) */
+    model: string;
+    /** AWS region for Bedrock */
+    awsRegion: string;
+    /** Heartbeat interval in ms (0 = disabled) */
+    heartbeatIntervalMs: number;
+    /** Tool packages to install */
+    tools: Array<{
+        package: string;
+        version: string;
+    }>;
+    /** Account ID (set after first API call) */
+    accountId: string;
+    /** LLM provider: bedrock (default), anthropic, or ollama */
+    provider: 'bedrock' | 'anthropic' | 'ollama';
+    /** Anthropic API key (only set when provider is 'anthropic') */
+    anthropicApiKey?: string;
+    /** Base URL for Ollama-compatible API (only set when provider is 'ollama') */
+    baseUrl?: string;
+    /** Bot ID for this runtime instance */
+    botId: string;
+    /** File ID for the bot's Memory file (null if not created yet) */
+    memoryFileId: string | null;
+    /** Hour of day (0-23) in local time for the nightly sleep cycle (null = disabled) */
+    sleepHour: number | null;
+    /** Hour of day (0-23) in local time for the evening dusk planning cycle (null = disabled) */
+    duskHour: number | null;
+    /** IANA timezone string (e.g. 'America/New_York') for sleep scheduling */
+    timezone: string | null;
+}
+/**
+ * Load local config from environment variables.
+ *
+ * Checks DESKFREE_LAUNCH first — a base64-encoded JSON with { botToken, apiUrl }.
+ * Falls back to individual env vars DESKFREE_BOT_TOKEN and DESKFREE_API_URL.
+ */
+declare function loadConfig(): LocalConfig;
+/**
+ * Merge local config with API-bootstrapped config.
+ * Env var overrides take precedence over API values for debugging/testing.
+ */
+declare function mergeWithRemoteConfig(local: LocalConfig, remote: RuntimeBootstrapConfig): RuntimeConfig;
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Structured JSON logger that satisfies the PluginLogger interface.
+ * Writes newline-delimited JSON to stdout/stderr.
+ *
+ * Supports optional structured fields that are merged into the JSON entry:
+ *   log.info('message routed', { sessionKey: 'dm:abc', target: 'orchestrator' })
+ */
+declare function createLogger(component: string, minLevel?: LogLevel): PluginLogger;
+/** Default logger for the root process. */
+declare const logger: PluginLogger;
+
+export { type ContentScanner, DefaultContentScanner, type DisposeAgent, type GatewayConfig, type HeartbeatOptions, type LocalConfig, type LogLevel, type OrchestratorQueryOptions, type RuntimeConfig, type ScanResult, type SessionEntry, SessionStore, type StartAgentOptions, type ToolPackageConfig, type WorkerQueryOptions, adaptTool, adaptTools, createLogger, createOrchestratorMcpServer, createWorkerMcpServer, installTools, isContentTypeAllowed, loadConfig, loadToolModules, logger, mergeWithRemoteConfig, runHeartbeat, runOrchestrator, runWorker, sanitizeFileName, startAgent, startGateway, validateDownloadUrl, withContentScan };