@questionbase/deskfree 0.3.0-alpha.9 → 0.4.0

package/dist/index.d.ts

@@ -1,727 +1,419 @@
-import { IncomingMessage, ServerResponse } from 'node:http';
+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;
 /**
- * Minimal type definitions for the OpenClaw plugin API.
- * These mirror the actual OpenClaw types but are defined inline
- * to avoid a hard dependency on the openclaw package at build time.
- * At runtime, the real types are provided by OpenClaw.
+ * 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 AnyAgentTool {
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-    execute: (id: string, params: Record<string, unknown>) => Promise<{
-        content: Array<{
-            type: string;
-            text?: string;
-        }>;
-    }>;
-    optional?: boolean;
-}
-interface OpenClawPluginToolContext {
-    config?: unknown;
-    messageChannel?: unknown;
-    agentAccountId?: string;
-    sandboxed?: boolean;
-}
-type OpenClawPluginToolFactory = (ctx: OpenClawPluginToolContext) => AnyAgentTool | AnyAgentTool[] | null | undefined;
-interface OpenClawPluginToolOptions {
-    optional?: boolean;
-}
-interface OpenClawConfig {
-    channels?: {
-        deskfree?: DeskFreeChannelConfig;
-        [key: string]: unknown;
-    };
-    plugins?: {
-        entries?: {
-            [pluginId: string]: {
-                enabled?: boolean;
-                [key: string]: unknown;
-            };
-        };
-        [key: string]: unknown;
-    };
-    [key: string]: unknown;
-}
-interface OpenClawPluginApi {
-    runtime: PluginRuntime;
-    config: OpenClawConfig;
-    pluginConfig: Record<string, unknown>;
-    logger: PluginLogger;
-    registerChannel(registration: {
-        plugin: ChannelPlugin;
-    }): void;
-    registerHttpRoute(params: {
-        path: string;
-        handler: (req: IncomingMessage, res: ServerResponse) => Promise<void> | void;
-    }): void;
-    registerTool(tool: AnyAgentTool | OpenClawPluginToolFactory, opts?: OpenClawPluginToolOptions): void;
-    registerHook(events: string | string[], handler: (event: Record<string, unknown>) => Promise<unknown> | unknown, opts?: {
-        priority?: number;
-    }): void;
-    on<K extends PluginHookName>(hookName: K, handler: PluginHookHandlerMap[K], opts?: {
-        priority?: number;
-    }): void;
-}
-type PluginHookName = 'before_agent_start' | 'llm_input' | 'llm_output' | 'agent_end' | 'before_compaction' | 'after_compaction' | 'before_reset' | 'message_received' | 'message_sending' | 'message_sent' | 'before_tool_call' | 'after_tool_call' | 'tool_result_persist' | 'session_start' | 'session_end' | 'gateway_start' | 'gateway_stop';
-interface PluginHookAgentContext {
-    agentId?: string;
-    sessionKey?: string;
+interface OrchestratorQueryOptions {
+    prompt: string;
+    orchestratorServer: McpSdkServerConfigWithInstance;
+    model: string;
+    /** Agent SDK session ID to resume (for multi-turn conversations). */
     sessionId?: string;
-    workspaceDir?: string;
-    messageProvider?: string;
 }
-interface PluginHookBeforeAgentStartEvent {
+/**
+ * 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;
-    messages?: unknown[];
-}
-interface PluginHookBeforeAgentStartResult {
-    systemPrompt?: string;
-    prependContext?: string;
-}
-type PluginHookHandlerMap = {
-    before_agent_start: (event: PluginHookBeforeAgentStartEvent, ctx: PluginHookAgentContext) => Promise<PluginHookBeforeAgentStartResult | void> | PluginHookBeforeAgentStartResult | void;
-    llm_input: (event: Record<string, unknown>, ctx: PluginHookAgentContext) => Promise<void> | void;
-    llm_output: (event: Record<string, unknown>, ctx: PluginHookAgentContext) => Promise<void> | void;
-    agent_end: (event: Record<string, unknown>, ctx: PluginHookAgentContext) => Promise<void> | void;
-    before_compaction: (event: Record<string, unknown>, ctx: PluginHookAgentContext) => Promise<void> | void;
-    after_compaction: (event: Record<string, unknown>, ctx: PluginHookAgentContext) => Promise<void> | void;
-    before_reset: (event: Record<string, unknown>, ctx: PluginHookAgentContext) => Promise<void> | void;
-    message_received: (event: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<void> | void;
-    message_sending: (event: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
-    message_sent: (event: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<void> | void;
-    before_tool_call: (event: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
-    after_tool_call: (event: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<void> | void;
-    tool_result_persist: (event: Record<string, unknown>, ctx: Record<string, unknown>) => Record<string, unknown> | void;
-    session_start: (event: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<void> | void;
-    session_end: (event: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<void> | void;
-    gateway_start: (event: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<void> | void;
-    gateway_stop: (event: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<void> | void;
-};
-interface PluginRuntime {
-    version: string;
-    config: {
-        loadConfig(): OpenClawConfig;
-        writeConfigFile(cfg: OpenClawConfig): Promise<void>;
-    };
-    channel: {
-        reply: {
-            finalizeInboundContext<T extends Record<string, unknown>>(ctx: T): T & FinalizedMsgContext;
-            dispatchReplyFromConfig(params: {
-                ctx: FinalizedMsgContext;
-                cfg: OpenClawConfig;
-                dispatcher: ReplyDispatcher;
-                replyOptions?: Record<string, unknown>;
-            }): Promise<{
-                queuedFinal: boolean;
-            }>;
-            createReplyDispatcherWithTyping(params: {
-                channel: string;
-                accountId: string;
-                deliver: (payload: {
-                    text?: string;
-                    body?: string;
-                }) => Promise<void>;
-                [key: string]: unknown;
-            }): {
-                dispatcher: ReplyDispatcher;
-                replyOptions: Record<string, unknown>;
-                markDispatchIdle: () => void;
-            };
-        };
-        text: {
-            chunkMarkdownText(text: string, limit: number): string[];
-        };
-    };
-    logging: {
-        createLogger(name: string): PluginLogger;
-    };
-    state: {
-        resolveStateDir(): string;
-    };
-}
-interface FinalizedMsgContext {
-    Body: string;
-    RawBody?: string;
-    ChatType: string;
-    Provider: string;
-    Surface: string;
-    From: string;
-    To: string;
-    MessageSid: string;
-    Timestamp?: string;
-    BodyForAgent?: string;
-    [key: string]: unknown;
-}
-interface ReplyDispatcher {
-    send(reply: unknown): Promise<void>;
-    getQueuedCounts(): unknown;
-}
-interface PluginLogger {
-    info(msg: string): void;
-    warn(msg: string): void;
-    error(msg: string): void;
-    debug(msg: string): void;
-}
-interface ChannelMessagingTargetResolver {
-    hint?: string;
-    looksLikeId?(raw: string, normalized?: string): boolean;
-}
-interface ChannelMessagingAdapter {
-    normalizeTarget?(raw: string): string | undefined;
-    targetResolver?: ChannelMessagingTargetResolver;
-}
-interface ChannelPlugin {
-    id: string;
-    meta: ChannelMeta;
-    capabilities: ChannelCapabilities;
-    config: ChannelConfigAdapter;
-    outbound?: ChannelOutboundAdapter;
-    gateway?: ChannelGatewayAdapter;
-    setup?: ChannelSetupAdapter;
-    security?: ChannelSecurityAdapter;
-    messaging?: ChannelMessagingAdapter;
-    onboarding?: ChannelOnboardingAdapter;
-    status?: ChannelStatusAdapter;
-}
-interface ChannelMeta {
-    name: string;
-    icon?: string;
-    description?: string;
-}
-interface ChannelCapabilities {
-    text: boolean;
-    media: boolean;
-    reactions: boolean;
-    threads: boolean;
-    editing: boolean;
-}
-interface ChannelConfigAdapter {
-    listAccountIds(cfg: OpenClawConfig): string[];
-    resolveAccount(cfg: OpenClawConfig, accountId?: string | null): ResolvedDeskFreeAccount;
-    isConfigured?(account: ResolvedDeskFreeAccount, cfg?: OpenClawConfig): boolean;
-    isEnabled?(account: ResolvedDeskFreeAccount, cfg?: OpenClawConfig): boolean;
-    describeAccount?(account: ResolvedDeskFreeAccount, cfg?: OpenClawConfig): ChannelAccountSnapshot;
-}
-interface ChannelOutboundAdapter {
-    deliveryMode: 'direct' | 'gateway' | 'hybrid';
-    resolveTarget?(target: string, ctx: {
-        cfg: OpenClawConfig;
-        accountId?: string | null;
-    }): {
-        to: string;
-    } | null;
-    sendText?(ctx: ChannelOutboundContext): Promise<OutboundDeliveryResult>;
-    textChunkLimit?: number;
-    chunkerMode?: 'text' | 'markdown';
-}
-interface ChannelGatewayAdapter {
-    startAccount?(ctx: ChannelGatewayContext): Promise<unknown>;
-    stopAccount?(ctx: ChannelGatewayContext): Promise<void>;
-    logoutAccount?(ctx: ChannelLogoutContext): Promise<ChannelLogoutResult>;
-}
-interface ChannelGatewayContext {
-    cfg: OpenClawConfig;
-    accountId: string;
-    account: ResolvedDeskFreeAccount;
-    runtime: PluginRuntime;
-    abortSignal: AbortSignal;
-    log?: PluginLogger;
-    getStatus(): ChannelAccountSnapshot;
-    setStatus(next: Partial<ChannelAccountSnapshot>): void;
-}
-interface ChannelSetupAdapter {
-    applyAccountConfig(params: {
-        cfg: OpenClawConfig;
-        accountId: string;
-        input: Record<string, string>;
-    }): OpenClawConfig;
-    validateInput?(params: {
-        cfg: OpenClawConfig;
-        accountId: string;
-        input: Record<string, string>;
-    }): string | null;
-}
-interface ChannelSecurityDmPolicy {
-    policy: string;
-    allowFrom?: Array<string | number> | null;
-    policyPath?: string;
-    allowFromPath: string;
-    approveHint: string;
-    normalizeEntry?: (raw: string) => string;
-}
-interface ChannelSecurityAdapter {
-    resolveDmPolicy?(ctx: {
-        cfg: OpenClawConfig;
-        accountId?: string | null;
-        account: ResolvedDeskFreeAccount;
-    }): ChannelSecurityDmPolicy | null;
-    collectWarnings?(ctx: {
-        cfg: OpenClawConfig;
-        accountId?: string | null;
-        account: ResolvedDeskFreeAccount;
-    }): Promise<string[]> | string[];
-}
-interface ChannelOutboundContext {
-    cfg: OpenClawConfig;
-    to: string;
-    text: string;
-    threadId?: string | number | null;
-    replyToId?: string | null;
-    accountId?: string | null;
-}
-interface OutboundDeliveryResult {
-    channel: string;
-    success: boolean;
-    threadId?: string;
-}
-interface ChannelAccountSnapshot {
-    accountId?: string;
-    enabled?: boolean;
-    configured?: boolean;
-    running?: boolean;
-    lastStartAt?: number;
-    lastStopAt?: number;
-    lastError?: string;
-    probe?: ChannelProbeResult;
-}
-interface ResolvedDeskFreeAccount {
-    accountId: string;
-    botToken: string;
-    apiUrl: string;
-    wsUrl: string;
-    userId: string;
-    enabled: boolean;
-    botName?: string;
-    humanName?: string;
-}
-interface DeskFreeChannelConfig {
-    enabled?: boolean;
-    botToken: string;
-    apiUrl: string;
-    wsUrl: string;
-    userId: string;
-    botName?: string;
-    humanName?: string;
-    accounts?: Record<string, Omit<DeskFreeChannelConfig, 'accounts'>>;
-}
-interface ChatMessageAttachment {
-    name: string;
-    contentType: string;
-    size: number;
-    url: string;
-}
-interface ChatMessage {
-    messageId: string;
-    botId: string;
-    humanId: string;
-    authorType: 'bot' | 'user';
-    content: string;
-    attachments?: ChatMessageAttachment[];
-    taskId?: string | null;
-    createdAt: string;
-    userName?: string | null;
-    botName?: string | null;
-}
-interface MessagesResponse {
-    items: ChatMessage[];
-    cursor: string | null;
-    hasMore: boolean;
-}
-interface WsTicketResponse {
-    ticket: string;
-    wsUrl: string;
-    expiresAt: string;
-}
-interface WizardPrompter {
-    text(params: {
-        message: string;
-        initialValue?: string;
-        placeholder?: string;
-        validate?: (value: string) => string | undefined;
-    }): Promise<string>;
-    confirm(params: {
-        message: string;
-        initialValue?: boolean;
-    }): Promise<boolean>;
-    note(message: string, title?: string): Promise<void>;
-}
-interface ChannelOnboardingStatus {
-    channel: string;
-    configured: boolean;
-    statusLines: string[];
-    selectionHint?: string;
-    quickstartScore?: number;
-}
-interface ChannelOnboardingResult {
-    cfg: OpenClawConfig;
-    accountId?: string;
-}
-interface ChannelOnboardingAdapter {
-    channel: string;
-    getStatus(ctx: {
-        cfg: OpenClawConfig;
-    }): Promise<ChannelOnboardingStatus>;
-    configure(ctx: {
-        cfg: OpenClawConfig;
-        runtime: PluginRuntime;
-        prompter: WizardPrompter;
-        accountOverrides: Record<string, string>;
-        shouldPromptAccountIds: boolean;
-        forceAllowFrom: boolean;
-    }): Promise<ChannelOnboardingResult>;
-    disable?(cfg: OpenClawConfig): OpenClawConfig;
-}
-interface ChannelProbeResult {
-    ok: boolean;
-    error?: string;
-}
-interface ChannelStatusIssue {
-    channel: string;
-    accountId: string;
-    kind: 'config' | 'auth' | 'runtime';
-    message: string;
-    fix?: string;
-}
-interface ChannelStatusAdapter {
-    probeAccount?(params: {
-        account: ResolvedDeskFreeAccount;
-        timeoutMs: number;
-        cfg: OpenClawConfig;
-    }): Promise<ChannelProbeResult>;
-    buildAccountSnapshot?(params: {
-        account: ResolvedDeskFreeAccount;
-        cfg: OpenClawConfig;
-        runtime?: ChannelAccountSnapshot;
-        probe?: ChannelProbeResult;
-    }): ChannelAccountSnapshot;
-    collectStatusIssues?(accounts: ChannelAccountSnapshot[]): ChannelStatusIssue[];
-}
-interface ChannelLogoutContext {
-    cfg: OpenClawConfig;
-    accountId: string;
-    account: ResolvedDeskFreeAccount;
-    runtime: PluginRuntime;
-    log?: PluginLogger;
-}
-interface ChannelLogoutResult {
-    cleared: boolean;
-    loggedOut?: boolean;
-    [key: string]: unknown;
-}
-interface WsNotification {
-    action: 'notify';
-    hint: string;
+    orchestratorServer: McpSdkServerConfigWithInstance;
+    model: string;
 }
-interface Goal {
-    goalId: string;
-    botId: string;
-    createdById: string;
-    title: string;
-    description?: string | null;
-    status: 'active' | 'paused' | 'completed' | 'archived';
-    createdAt: string;
-    updatedAt: string;
-}
-interface Task {
-    taskId: string;
-    title: string;
-    status: 'ready_for_bot' | 'working_on_it' | 'waiting_for_human' | 'done';
-    instructions?: string;
-    createdAt: string;
-    updatedAt: string;
-    botId?: string | null;
-    createdById: string;
-    reason?: string | null;
-    deliverable?: string | null;
-}
-interface TaskMessage {
-    messageId: string;
-    authorType: 'bot' | 'user';
-    content: string;
-    attachments: ChatMessageAttachment[];
-    createdAt: string;
-    userName?: string | null;
-}
-interface TaskWithContext extends Task {
-    instructions: string;
-    deliverable: string;
-    messages: TaskMessage[];
+/**
+ * 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;
 }
 /**
- * Response from the tasks.create bot endpoint.
+ * Run the worker agent directly. Returns a Query (async iterable of
+ * SDKMessage events with a .close() method for teardown).
  *
- * The backend mutation (`trpc.bot.tasks.create`) returns the Task object
- * directly (not wrapped in `{ task: ... }`), unlike `goals.create` which
- * returns `{ goal: Goal }`.
+ * 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
  */
-type CreateTaskResponse = Task;
-interface CompleteTaskInput {
-    taskId: string;
-    outcome: 'done' | 'blocked';
-}
-interface WorkspaceStateTask {
-    taskId: string;
-    title: string;
-    status: 'ready_for_bot' | 'working_on_it' | 'waiting_for_human' | 'done';
-    instructions?: string | null;
-    deliverable?: string | null;
-    createdAt: string;
-    updatedAt: string;
-}
-interface WorkspaceStateGoal {
-    goalId: string;
-    title: string;
-    description?: string | null;
-    status: 'active' | 'paused' | 'completed' | 'archived';
-    tasks: WorkspaceStateTask[];
-}
-interface WorkspaceState {
-    goals: WorkspaceStateGoal[];
-    unlinkedTasks: WorkspaceStateTask[];
-    recentlyDone: WorkspaceStateTask[];
-}
+declare function runWorker(opts: WorkerQueryOptions): Query;
 
-/** Enhanced error class for DeskFree API errors with user-friendly messages */
-declare class DeskFreeError extends Error {
-    readonly type: 'network' | 'auth' | 'server' | 'client' | 'timeout' | 'invalid_response';
-    readonly statusCode?: number;
-    readonly userMessage: string;
-    readonly procedure: string;
-    constructor(type: DeskFreeError['type'], procedure: string, message: string, userMessage: string, statusCode?: number);
-    static fromResponse(response: Response, procedure: string, responseText: string): DeskFreeError;
-    static timeout(procedure: string, timeoutMs: number): DeskFreeError;
-    static invalidResponse(procedure: string): DeskFreeError;
-    static network(procedure: string, originalError: Error): DeskFreeError;
-}
-declare class DeskFreeClient {
-    private botToken;
-    private apiUrl;
-    private requestTimeoutMs;
-    constructor(botToken: string, apiUrl: string, options?: {
-        requestTimeoutMs?: number;
-    });
-    private request;
-    /**
-     * Validates that a string parameter is non-empty.
-     * Catches invalid inputs before they hit the network.
-     */
-    private requireNonEmpty;
+/**
+ * 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>;
     /**
-     * Send a typing indicator to the DeskFree conversation.
-     *
-     * @param input - Optional parameters including taskId to scope the indicator
+     * 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.
      */
-    typing(input?: {
-        taskId?: string;
-        clear?: boolean;
-    }): Promise<void>;
+    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;
     /**
-     * Update an existing bot message content (for streaming).
+     * 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.
      *
-     * @param input - messageId, new content, and streaming flag
+     * If at capacity, queues the dispatch and notifies the user.
+     * If a worker already exists for this taskId, returns 'already_running'.
      */
-    updateMessage(input: {
-        messageId: string;
-        content: string;
-        streaming?: boolean;
-    }): Promise<{
-        messageId: string;
-        content: string;
-    }>;
+    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;
     /**
-     * Send a text message (with optional attachments) to a DeskFree conversation.
-     *
-     * @param input - Message content, optional userId, taskId, and attachments
+     * Push a message into an active worker's channel.
+     * Resets the idle timer.
      */
-    sendMessage(input: {
-        userId?: string;
-        content: string;
-        taskId?: string;
-        attachments?: Array<{
-            s3Key: string;
-            name: string;
-            contentType: string;
-            size: number;
-        }>;
-    }): Promise<{
-        messageId: string;
-        content: string;
-    }>;
-    /** Fetch paginated message history for a conversation. */
-    listMessages(input: {
-        userId?: string;
-        cursor?: string | null;
-        limit?: number;
-    }): Promise<MessagesResponse>;
-    /** Obtain a one-time WebSocket authentication ticket for real-time notifications. */
-    getWsTicket(): Promise<WsTicketResponse>;
-    /** Create a new goal. */
-    createGoal(input: {
-        title: string;
-        description?: string;
-    }): Promise<{
-        goal: Goal;
-    }>;
-    /** Update a goal's status, title, or description. */
-    updateGoal(input: {
-        goalId: string;
-        title?: string;
-        description?: string;
-        status?: string;
-    }): Promise<Goal>;
-    /** Create a new task, optionally with a recurring schedule. */
-    createTask(input: {
-        title: string;
-        instructions?: string;
-        goalId?: string;
-        isRecurring?: boolean;
-        recurringSchedule?: {
-            frequency: 'daily' | 'weekly' | 'biweekly' | 'monthly';
-            dayOfWeek?: number;
-            dayOfMonth?: number;
-            time: string;
-            timezone?: string;
-        };
-    }): Promise<CreateTaskResponse>;
-    /** Claim a task so the bot can begin working on it. Returns enriched context. */
-    claimTask(input: {
-        taskId: string;
-    }): Promise<TaskWithContext>;
-    /** Update the deliverable (markdown content) for a task. */
-    updateDeliverable(input: {
-        taskId: string;
-        deliverable: string;
-    }): Promise<void>;
-    /** Send an agent status update to DeskFree. */
-    statusUpdate(input: {
-        status: 'idle' | 'working' | 'responding';
-        activeSubAgents: Array<{
-            label: string;
-            status: 'running' | 'completed' | 'failed';
-            startedAt: string;
-            completedAt?: string;
-            tokenUsage?: number;
-            task?: string;
-        }>;
-        model?: string;
-        lastActivity?: string;
-        pluginVersion?: string;
-        openclawVersion?: string;
-    }): Promise<{
-        success: boolean;
-    }>;
-    /** Report error log entries to the backend for CloudWatch/Slack visibility. */
-    reportError(input: {
-        errors: Array<{
-            message: string;
-            level: 'warn' | 'error' | 'fatal';
-            timestamp: string;
-            metadata?: Record<string, unknown>;
-        }>;
-    }): Promise<{
-        accepted: number;
-    }>;
-    /** Get short-lived AWS credentials for S3 workspace access. */
-    workspaceCredentials(): Promise<{
-        accessKeyId: string;
-        secretAccessKey: string;
-        sessionToken: string;
-        expiration: Date;
-        s3Uri: string;
-        region: string;
-    }>;
-    /** Notify DeskFree that workspace files have changed locally. */
-    workspaceRead(input: {
-        path: string;
-    }): Promise<{
-        path: string;
-        content: string;
-        lastModified: string;
-    }>;
-    /** Get full workspace snapshot — goals with tasks, unlinked tasks, recently done. */
-    getState(): Promise<WorkspaceState>;
-    /** Report token usage for a task. Atomically increments rollup columns. */
-    reportUsage(input: {
-        taskId: string;
-        inputTokens: number;
-        outputTokens: number;
-        thinkingTokens: number;
-        model: string;
-        estimatedCost: number;
-    }): Promise<{
-        success: boolean;
-    }>;
-    /** Complete a task with an outcome. Moves task to waiting_for_human. */
-    completeTask(input: CompleteTaskInput): Promise<Task & {
-        outcome: 'done' | 'blocked';
-    }>;
+    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;
     /**
-     * Lightweight health check that verifies connectivity and authentication.
-     *
-     * @param timeoutMs - Maximum time to wait for the probe response
-     * @returns Probe result indicating success or a descriptive error
+     * Background drain loop — processes query output and streams it back
+     * to DeskFree via DeskFreeStreamingSession.
      */
-    probe(timeoutMs: number): Promise<ChannelProbeResult>;
+    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;
 }
 
 /**
- * Convenience: report an error if the reporter is initialized.
- * No-op if called before initErrorReporter(). Never throws.
+ * 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 reportError(level: 'warn' | 'error' | 'fatal', message: string, metadata?: Record<string, unknown>): void;
+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;
+}
 /**
- * Offline queue for failed API requests.
+ * 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.
  *
- * When the DeskFree API is unreachable (network errors, timeouts),
- * outbound requests are queued in memory and retried with exponential
- * backoff when connectivity is restored.
+ * @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;
 
-/** A queued request that can be retried. */
-interface QueuedRequest {
-    id: string;
-    /** Human-readable description for logging. */
-    label: string;
-    /** The function to execute. Must be idempotent for safe retries. */
-    execute: () => Promise<void>;
-    /** Number of retry attempts so far. */
-    attempts: number;
-    /** Timestamp when the request was first queued. */
-    queuedAt: number;
-}
-declare class OfflineQueue {
-    private queue;
-    private processing;
-    private retryTimer;
-    private log;
-    constructor(log: PluginLogger);
-    /** Number of requests currently queued. */
-    get size(): number;
+/**
+ * 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);
     /**
-     * Enqueue a failed request for later retry.
-     * Returns false if the queue is full.
+     * Get the Agent SDK session ID for a given key.
+     * Returns undefined if no session exists or it has expired.
      */
-    enqueue(request: Omit<QueuedRequest, 'attempts' | 'queuedAt'>): boolean;
+    getSessionId(key: string): string | undefined;
     /**
-     * Attempt to flush all queued requests.
-     * Called when connectivity is restored (e.g., WebSocket reconnect).
+     * Store an Agent SDK session ID for a given key.
      */
-    flush(): Promise<void>;
-    /** Clear all queued requests. */
-    clear(): void;
-    /** Stop the retry timer (for cleanup). */
-    destroy(): void;
-    private scheduleRetry;
+    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[]>;
 
-declare const plugin: {
-    id: string;
-    name: string;
-    register(api: OpenClawPluginApi): void;
-};
+/**
+ * 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, ollama, or claude-code */
+    provider: 'bedrock' | 'anthropic' | 'ollama' | 'claude-code';
+    /** 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 AnyAgentTool, type ChannelAccountSnapshot, type ChannelCapabilities, type ChannelConfigAdapter, type ChannelGatewayAdapter, type ChannelGatewayContext, type ChannelLogoutContext, type ChannelLogoutResult, type ChannelMessagingAdapter, type ChannelMessagingTargetResolver, type ChannelMeta, type ChannelOnboardingAdapter, type ChannelOnboardingResult, type ChannelOnboardingStatus, type ChannelOutboundAdapter, type ChannelOutboundContext, type ChannelPlugin, type ChannelProbeResult, type ChannelSecurityAdapter, type ChannelSecurityDmPolicy, type ChannelSetupAdapter, type ChannelStatusAdapter, type ChannelStatusIssue, type ChatMessage, type ChatMessageAttachment, type CompleteTaskInput, type CreateTaskResponse, type DeskFreeChannelConfig, DeskFreeClient, DeskFreeError, type FinalizedMsgContext, type Goal, type MessagesResponse, OfflineQueue, type OpenClawConfig, type OpenClawPluginApi, type OpenClawPluginToolContext, type OpenClawPluginToolFactory, type OpenClawPluginToolOptions, type OutboundDeliveryResult, type PluginHookAgentContext, type PluginHookBeforeAgentStartEvent, type PluginHookBeforeAgentStartResult, type PluginHookHandlerMap, type PluginHookName, type PluginLogger, type PluginRuntime, type ReplyDispatcher, type ResolvedDeskFreeAccount, type Task, type TaskMessage, type TaskWithContext, type WizardPrompter, type WorkspaceState, type WorkspaceStateGoal, type WorkspaceStateTask, type WsNotification, type WsTicketResponse, plugin as default, reportError };
+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 };