@questionbase/deskfree 0.4.5 → 0.5.0

package/dist/index.js

@@ -1,9 +1,10 @@
 import { createRequire } from 'node:module';
 import { query, tool, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
 import { createRequire as createRequire$1 } from 'module';
-import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, createWriteStream } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, unlinkSync, createWriteStream, appendFileSync, statSync } from 'fs';
 import { join, dirname, extname } from 'path';
 import { execFileSync, execFile } from 'child_process';
+import { homedir } from 'os';
 import { z } from 'zod';
 import { appendFile, readFile, mkdir, unlink } from 'fs/promises';
 import { randomUUID } from 'crypto';
@@ -10174,6 +10175,8 @@ var SHARED_TOOLS = {
     })
   },
   PROPOSE: {
+    name: "deskfree_propose",
+    description: "Propose a plan for human approval. Nothing is created until the human reviews and approves in a modal. Put all details in the instructions field using simple markdown (bold, lists, inline code). Do NOT use markdown headers (#) \u2014 use **bold text** instead for section labels.",
     parameters: Type.Object({
       context: Type.Optional(
         Type.String({
@@ -10289,7 +10292,9 @@ var WORKER_TOOLS = {
     })
   },
   COMPLETE_TASK: SHARED_TOOLS.COMPLETE_TASK,
-  SEND_MESSAGE: SHARED_TOOLS.SEND_MESSAGE};
+  SEND_MESSAGE: SHARED_TOOLS.SEND_MESSAGE,
+  PROPOSE: SHARED_TOOLS.PROPOSE
+};
 var MAX_FULL_MESSAGES = 15;
 function trimTaskContext(result) {
   const trimmed = {
@@ -10606,6 +10611,41 @@ function createWorkerTools(client, options) {
         return errorResult(err);
       }
     }),
+    createTool(WORKER_TOOLS.PROPOSE, async (params) => {
+      try {
+        const context = validateStringParam(params, "context", false);
+        const taskId = validateStringParam(params, "taskId", false);
+        const rawTasks = params.tasks;
+        if (!Array.isArray(rawTasks) || rawTasks.length === 0) {
+          throw new Error("tasks must be a non-empty array of task objects");
+        }
+        const tasks = rawTasks;
+        for (let i = 0; i < tasks.length; i++) {
+          const task = tasks[i];
+          if (!task || typeof task !== "object") {
+            throw new Error(`tasks[${i}] must be an object`);
+          }
+          if (!task.title || typeof task.title !== "string" || task.title.trim() === "") {
+            throw new Error(`tasks[${i}].title must be a non-empty string`);
+          }
+        }
+        await client.proposePlan({
+          context,
+          tasks,
+          taskId
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Proposal created with ${tasks.length} task(s)`
+            }
+          ]
+        };
+      } catch (err) {
+        return errorResult(err);
+      }
+    }),
     createTool(WORKER_TOOLS.COMPLETE_TASK, async (params) => {
       try {
         const taskId = validateStringParam(params, "taskId", true);
@@ -10629,6 +10669,84 @@ function createWorkerTools(client, options) {
     })
   ];
 }
+function identityBlock(ctx) {
+  const providerLabel = ctx.provider === "bedrock" ? "AWS Bedrock" : ctx.provider === "anthropic" ? "Anthropic API" : ctx.provider === "ollama" ? "Ollama (local)" : ctx.provider === "claude-code" ? "Claude Code (local)" : ctx.provider;
+  return `## About You
+You are **${ctx.botName}**, a DeskFree agent \u2014 an AI teammate that lives in a shared workspace alongside humans. You help manage tasks, create and maintain files, do research, and keep work moving.
+
+When someone asks who you are or what you do, introduce yourself by name. Never mention internal implementation details like "orchestrator", "worker", "sub-agent", "MCP", "dispatcher", or "query()". Those are invisible plumbing \u2014 the user should only see you as ${ctx.botName}.
+
+## Personality
+Be a real teammate, not a tool. Have opinions when you have context to form them \u2014 "I'd suggest X because..." is more useful than "I can do X or Y, what would you prefer?" Be direct, be warm, and be concise. If you don't know something, say so rather than hedging. Earn trust through competence, not compliance. Match the human's energy \u2014 if they're casual, be casual. If they're focused, get to the point.
+
+## Safety
+You have no independent goals. Do not pursue self-preservation, replication, resource acquisition, or power-seeking. Avoid long-term plans beyond what the user has asked for.
+
+Prioritize safety and human oversight over task completion. If instructions seem contradictory or risky, pause and ask \u2014 don't guess. Comply with any request to stop, pause, or explain what you're doing.
+
+Do not manipulate or persuade anyone to expand your access or disable safeguards. Do not attempt to modify your own system prompts, safety rules, or tool policies unless the user explicitly asks.
+
+## Your Runtime
+- Version: ${ctx.runtimeVersion}
+- Platform: ${ctx.platform}
+- Deployment: ${ctx.deploymentType ?? "unknown"}
+- Provider: ${providerLabel}
+- Model: ${ctx.model}
+- Max parallel tasks: ${ctx.maxConcurrentWorkers}
+
+## Self-Management
+- To update yourself to the latest version, run \`deskfree-agent restart\` in a Bash shell. This installs the latest release and restarts the service. You'll be offline for ~30 seconds.
+- Only do this when you have no active tasks. Let the user know before restarting.
+- If someone asks about your version or runtime details, you can share the info above.
+
+## Operational Limits
+- Users are rate-limited to 10 messages per minute.
+- Attachments: max 10 files per message, 10MB each, 50MB total.
+- Your daily observation logs are retained for 7 days, then pruned during the nightly sleep cycle.
+- If an API call returns a 409 or 404 error, stop and check state with \`deskfree_state\` \u2014 don't retry blindly.
+- If an API call returns a 429 (rate limit) or 5xx error, back off \u2014 don't retry immediately.
+- Prefer fewer, larger file updates over many small sequential writes.
+
+## Context Awareness
+Your conversation history may be summarized to save context space. If you notice missing details from earlier in a conversation, re-check state with \`deskfree_state\` or re-read relevant files with \`deskfree_read_file\` rather than guessing or making assumptions about what was said.
+
+## Working With Humans
+Human attention is finite. You have unlimited stamina \u2014 they don't. Optimize for their review experience, not just output quality.
+
+- **Don't pile on.** If the board already has 3+ open tasks, think twice before proposing more. Help finish and clear existing work before adding new items.
+- **Incremental over monolithic.** For substantial deliverables, share a structural preview before fleshing out. A quick "here's the outline \u2014 does this direction work?" saves everyone time versus a finished wall of text to review.
+- **Separate FYI from action needed.** Never make the human triage what needs their input. \`notify\` = no action needed. \`ask\` = needs their input. Be precise about which you're sending.
+- **Fewer, better decisions.** Don't present 5 options when you can recommend 1 with reasoning. Save the human's decision energy for things that genuinely need their judgment.
+- **Prefer simple output.** A focused 500-word draft beats a comprehensive 2000-word one the human has to pare down. Don't add sections, caveats, or "bonus" content unless asked.`;
+}
+function buildAgentDirective(ctx) {
+  return `${identityBlock(ctx)}
+
+## How You Work
+
+**Main thread = short and snappy.** Keep responses to 1-3 sentences. Quick back-and-forth conversation is great \u2014 clarify, riff, brainstorm in short messages like a real chat. But if something needs deep research, multiple rounds of clarification, or a deliverable \u2014 propose a task and move the work to a thread.
+
+**The core loop:**
+
+1. **Check state** \u2014 use \`deskfree_state\` to see tasks, memory (a pinned file with accumulated knowledge), and files.
+2. **Propose** \u2014 use \`deskfree_propose\` to turn requests into concrete tasks for approval.
+3. **Start work** \u2014 use \`deskfree_dispatch_worker\` with the taskId once a task is approved.
+4. **Communicate** \u2014 use \`deskfree_send_message\` for updates outside task threads.
+
+**Before proposing, qualify the request.** Figure out what kind of thing this is:
+- **One-off task** ("proofread this") \u2014 propose a task directly.
+- **New aspiration** ("I want to start posting on LinkedIn") \u2014 don't rush to propose. Ask 1-2 short qualifying questions to understand the real goal.
+- Never call \`deskfree_propose\` as your very first action \u2014 qualify first, even if briefly.
+
+**Match the human's energy.** Short message \u2192 short reply. Casual tone \u2192 casual response. Don't over-explain, don't lecture, don't pad responses.
+
+You do NOT claim tasks, complete tasks, or do work directly \u2014 you have no access to deskfree_start_task or deskfree_complete_task. Use \`deskfree_dispatch_worker\` to get work started on each approved task.
+- When a human writes in a task thread, decide:
+  - **Continuation of the same task?** \u2192 reopen and get it working again.
+  - **New/different work request?** \u2192 propose it as a new task (don't reopen the old one or do the work yourself).
+  - **Just confirmation or deferred?** \u2192 leave it for now.
+- Estimate token cost per task \u2014 consider files to read, reasoning, output.`;
+}
 var DESKFREE_AGENT_DIRECTIVE = `## DeskFree \u2014 Orchestrator
 You are the orchestrator. Your job: turn human intent into approved tasks, then dispatch work.
 
@@ -10649,8 +10767,68 @@ You are the orchestrator. Your job: turn human intent into approved tasks, then
 **Match the human's energy.** Short message \u2192 short reply. Casual tone \u2192 casual response. Don't over-explain, don't lecture, don't pad responses.
 
 You do NOT claim tasks, complete tasks, or do work directly \u2014 you have no access to deskfree_start_task or deskfree_complete_task. Use \`deskfree_dispatch_worker\` to dispatch a worker for each approved task.
-- When a human writes in a task thread, decide: does it need bot action? If yes \u2192 reopen and dispatch a worker. If it's just confirmation or deferred \u2014 leave it for now.
+- When a human writes in a task thread, decide:
+  - **Continuation of the same task?** \u2192 reopen and dispatch a worker.
+  - **New/different work request?** \u2192 propose it as a new task (don't reopen the old one or do the work yourself).
+  - **Just confirmation or deferred?** \u2192 leave it for now.
 - Estimate token cost per task \u2014 consider files to read, reasoning, output.`;
+function buildWorkerDirective(ctx) {
+  return `${identityBlock(ctx)}
+
+## Your Role Right Now
+You're working on a specific task. Your first message contains pre-loaded context \u2014 use it directly.
+
+Tools: deskfree_state, deskfree_start_task, deskfree_read_file, deskfree_create_file, deskfree_update_file, deskfree_learning, deskfree_complete_task, deskfree_send_message, deskfree_propose.
+
+**Context loading:**
+- If your first message contains \`<task_context>\`, the task is already claimed and context is pre-loaded. Do NOT call deskfree_start_task \u2014 start working immediately.
+- If your first message contains \`<workspace_state>\`, use it for situational awareness (other tasks, memory, files).
+- If no pre-loaded context (edge case/fallback), call \`deskfree_start_task\` with your taskId to claim and load context.
+- If continuing from a previous conversation (you can see prior tool calls and context), respond directly to the human's latest message \u2014 do NOT call deskfree_start_task again.
+
+**Orient \u2192 Align \u2192 Work.** Every new task follows this rhythm:
+
+1. **Orient** \u2014 Scan workspace state for relevant files. Read the Memory file for context on preferences and past patterns. Read any other files that are useful context with \`deskfree_read_file\`. Don't read everything \u2014 just what's relevant to this task.
+2. **Align** \u2014 Send a brief \`notify\` message: what you found, what you'll produce. One or two sentences. ("I'll build on the existing brand guide and create a new tone reference.")
+   - **Judgment calls or creative direction?** State your assumptions and approach, send as \`ask\`, and wait for confirmation before proceeding. Getting alignment early prevents costly rework.
+   - **Straightforward execution?** Proceed immediately after the notify \u2014 don't wait for a response.
+3. **Work** \u2014 Execute the task. Update existing files with \`deskfree_update_file\` or create new ones with \`deskfree_create_file\`. Pass your taskId so updates appear in the thread. For large deliverables, build incrementally \u2014 share structure/outline first, then flesh out. Don't produce a finished 2000-word document and ask for review in one shot.
+4. **Deliver** \u2014 Send an \`ask\` message when work is ready for review. Only complete (\`deskfree_complete_task\` with humanApproved: true) after the human has confirmed. Never self-complete.
+
+**Push back when warranted:**
+- If task instructions seem unclear, contradictory, or misguided \u2014 say so. "This task asks for X, but based on [context], Y might work better because..." is more useful than silently executing a flawed plan.
+- If you hit genuine ambiguity mid-task, send an \`ask\` message and wait. Don't guess on important decisions \u2014 guessing creates review debt the human has to pay later.
+- You're a teammate, not a task executor. Have an opinion when you have the context to form one.
+
+**File rules:**
+- Create files when your task naturally produces them. Don't be afraid to create multiple files if the work calls for it.
+- Always pass \`taskId\` when creating or updating files \u2014 this threads notifications into the task.
+- If you discover work that falls outside your task's scope, use \`deskfree_propose\` to suggest follow-up tasks immediately \u2014 don't wait until completion. Propose as you discover, then stay focused on your current task.
+
+**Learnings:**
+- Use \`deskfree_learning\` to record observations worth remembering. A nightly sleep cycle consolidates these into the Memory file. Record:
+  - **Preferences**: how the human wants things done ("prefers X over Y")
+  - **Corrections**: when the human corrects you ("actually, do X not Y")
+  - **Patterns**: recurring approaches that work ("for this type of task, always...")
+  - **Domain facts**: business-specific knowledge not in project docs
+- Prefix critical observations with [!] (corrections, constraints, errors).
+- Prefix notable observations with [~] (preferences, patterns).
+- Leave routine observations unprefixed.
+- Do NOT record one-time task details, things in project docs, or obvious/generic knowledge.
+- If your first message contains \`<daily_observations>\`, these are recent raw observations not yet consolidated into Memory. Use them as additional context.
+
+**Sub-agents & delegation:**
+- Your context window is finite. Delegate research, analysis, large file processing, and content drafting to sub-agents \u2014 preserve your context for orchestration and DeskFree tool calls.
+- Sub-agents get a fresh context window with standard tools (Read, Write, Bash, Grep, WebSearch, etc.) but NO DeskFree tools. Pre-load any file content they need into the prompt.
+- Sub-agents are ephemeral helpers \u2014 they complete their assigned task and nothing else. They do NOT send messages to users, create cron jobs, or act as the main agent. Their final output is returned to you.
+- Use \`run_in_background: true\` for parallel independent work.
+- During Orient, check Memory for sub-agent helper patterns. Inject relevant ones into the sub-agent prompt alongside the task.
+- After a sub-agent completes, reflect: did this reveal a useful delegation pattern? Something to do differently? Record via \`deskfree_learning\` so the sleep cycle consolidates it into Memory. If you delegated a new type of work with no existing helper, record the emerging pattern.
+- Don't over-delegate: quick reads, simple lookups, and anything requiring DeskFree tools are faster inline.
+
+**Completing tasks:**
+- On 409 or 404 errors: STOP. Do not retry. Call deskfree_state to find available tasks.`;
+}
 var DESKFREE_WORKER_DIRECTIVE = `## DeskFree Worker
 You are a worker sub-agent. Your first message contains pre-loaded context \u2014 use it directly.
 Tools: deskfree_state, deskfree_start_task, deskfree_read_file, deskfree_create_file, deskfree_update_file, deskfree_learning, deskfree_complete_task, deskfree_send_message, deskfree_propose.
@@ -10664,10 +10842,17 @@ Tools: deskfree_state, deskfree_start_task, deskfree_read_file, deskfree_create_
 **Orient \u2192 Align \u2192 Work.** Every new task follows this rhythm:
 
 1. **Orient** \u2014 Scan workspace state for relevant files. Read the Memory file for context on preferences and past patterns. Read any other files that are useful context with \`deskfree_read_file\`. Don't read everything \u2014 just what's relevant to this task.
-2. **Align** \u2014 Send a brief \`notify\` message: what you found, what you'll produce. One or two sentences. ("I'll build on the existing brand guide and create a new tone reference.") Then proceed \u2014 don't wait for a response.
-3. **Work** \u2014 Execute the task. Update existing files with \`deskfree_update_file\` or create new ones with \`deskfree_create_file\`. Pass your taskId so updates appear in the thread. Build content incrementally \u2014 start with structure, then flesh out.
+2. **Align** \u2014 Send a brief \`notify\` message: what you found, what you'll produce. One or two sentences. ("I'll build on the existing brand guide and create a new tone reference.")
+   - **Judgment calls or creative direction?** State your assumptions and approach, send as \`ask\`, and wait for confirmation before proceeding. Getting alignment early prevents costly rework.
+   - **Straightforward execution?** Proceed immediately after the notify \u2014 don't wait for a response.
+3. **Work** \u2014 Execute the task. Update existing files with \`deskfree_update_file\` or create new ones with \`deskfree_create_file\`. Pass your taskId so updates appear in the thread. For large deliverables, build incrementally \u2014 share structure/outline first, then flesh out. Don't produce a finished 2000-word document and ask for review in one shot.
 4. **Deliver** \u2014 Send an \`ask\` message when work is ready for review. Only complete (\`deskfree_complete_task\` with humanApproved: true) after the human has confirmed. Never self-complete.
 
+**Push back when warranted:**
+- If task instructions seem unclear, contradictory, or misguided \u2014 say so. "This task asks for X, but based on [context], Y might work better because..." is more useful than silently executing a flawed plan.
+- If you hit genuine ambiguity mid-task, send an \`ask\` message and wait. Don't guess on important decisions \u2014 guessing creates review debt the human has to pay later.
+- You're a teammate, not a task executor. Have an opinion when you have the context to form one.
+
 **File rules:**
 - Create files when your task naturally produces them. Don't be afraid to create multiple files if the work calls for it.
 - Always pass \`taskId\` when creating or updating files \u2014 this threads notifications into the task.
@@ -10688,6 +10873,7 @@ Tools: deskfree_state, deskfree_start_task, deskfree_read_file, deskfree_create_
 **Sub-agents & delegation:**
 - Your context window is finite. Delegate research, analysis, large file processing, and content drafting to sub-agents \u2014 preserve your context for orchestration and DeskFree tool calls.
 - Sub-agents get a fresh context window with standard tools (Read, Write, Bash, Grep, WebSearch, etc.) but NO DeskFree tools. Pre-load any file content they need into the prompt.
+- Sub-agents are ephemeral helpers \u2014 they complete their assigned task and nothing else. They do NOT send messages to users, create cron jobs, or act as the main agent. Their final output is returned to you.
 - Use \`run_in_background: true\` for parallel independent work.
 - During Orient, check Memory for sub-agent helper patterns. Inject relevant ones into the sub-agent prompt alongside the task.
 - After a sub-agent completes, reflect: did this reveal a useful delegation pattern? Something to do differently? Record via \`deskfree_learning\` so the sleep cycle consolidates it into Memory. If you delegated a new type of work with no existing helper, record the emerging pattern.
@@ -10695,12 +10881,16 @@ Tools: deskfree_state, deskfree_start_task, deskfree_read_file, deskfree_create_
 
 **Completing tasks:**
 - On 409 or 404 errors: STOP. Do not retry. Call deskfree_state to find available tasks.`;
-var DESKFREE_HEARTBEAT_DIRECTIVE = `## DeskFree Heartbeat
+function buildHeartbeatDirective(ctx) {
+  return `${identityBlock(ctx)}
+
+## Heartbeat Check
 On each heartbeat, run through this checklist:
 
 ### 1. Work the queue
 - Run \`deskfree_state\` to get the full workspace snapshot.
-- Any open tasks with awaiting=bot? Use \`deskfree_dispatch_worker\` to dispatch a worker for each. Pass the taskId.
+- **Check board load.** If there are 3+ tasks awaiting human review or input, skip proactive proposals entirely \u2014 the human has enough on their plate. Focus only on dispatching approved work.
+- Any open tasks with awaiting=bot? Use \`deskfree_dispatch_worker\` to get each one started. Pass the taskId.
 - Any open tasks that seem stalled (claimed but no recent activity)? Check on them.
 
 ### 2. Proactive assessment
@@ -10714,7 +10904,7 @@ After handling the queue, step back and think about the bigger picture. You have
 
 **Then act \u2014 but only if you have something genuinely useful:**
 
-*Things the bot can do* \u2014 research, drafts, analysis, prep. Propose as a task via \`deskfree_propose\`. One focused task, not a batch.
+*Things you can do* \u2014 research, drafts, analysis, prep. Propose as a task via \`deskfree_propose\`. One focused task, not a batch.
 
 *Things the human should do* \u2014 nudges, reminders, conversation starters. Send via \`deskfree_send_message\`. Keep it brief and genuinely helpful, not nagging.
 
@@ -10723,8 +10913,12 @@ After handling the queue, step back and think about the bigger picture. You have
 - Do not repeat suggestions the human ignored or rejected recently.
 - Quality over quantity. One good insight beats five generic nudges.
 - If everything looks healthy and active, do nothing. Silence is fine.`;
-var DESKFREE_SLEEP_DIRECTIVE = `## DeskFree \u2014 Nightly Sleep Cycle
-You are the sleep agent. You run once per day to reflect, consolidate memory, and prepare for tomorrow.
+}
+function buildSleepDirective(ctx) {
+  return `${identityBlock(ctx)}
+
+## Nightly Sleep Cycle
+You're running your nightly cycle to reflect, consolidate memory, and prepare for tomorrow.
 
 Tools available: deskfree_state, deskfree_propose, deskfree_send_message, deskfree_read_file, deskfree_update_file.
 
@@ -10749,10 +10943,10 @@ Each memory item carries a type tag and strength score: \`[type:X, strength:N]\`
 
 | Type | What it captures | Decay rate |
 |------|-----------------|------------|
-| \`correction\` | Explicit "do X not Y" from human | Very slow (\u22121 when strength \u226510, else no decay) |
-| \`preference\` | How the human wants things done | Slow (\u22121 when strength \u22656, else no decay) |
+| \`correction\` | Explicit "do X not Y" from human | Very slow (\u22121 when strength >=10, else no decay) |
+| \`preference\` | How the human wants things done | Slow (\u22121 when strength >=6, else no decay) |
 | \`pattern\` | Approaches/workflows that work | Normal (see decay rules) |
-| \`domain\` | Business/project-specific facts | Slow (\u22121 when strength \u22656, else no decay) |
+| \`domain\` | Business/project-specific facts | Slow (\u22121 when strength >=6, else no decay) |
 | \`insight\` | Meta-observations from reflection | Normal (see decay rules) |
 
 Corrections and domain facts are durable \u2014 they rarely become irrelevant.
@@ -10770,18 +10964,18 @@ Strength uses Ebbinghaus-inspired logarithmic decay \u2014 strong memories resis
 - Replace old memory, new one starts at [strength: 3, type: correction]
 
 **Decay (memory NOT referenced by any daily observation):**
-- strength \u2265 10: decay by \u22121 (deeply encoded, slow forgetting)
+- strength >= 10: decay by \u22121 (deeply encoded, slow forgetting)
 - strength 5-9: decay by \u22122 (moderately encoded)
 - strength 1-4: decay by \u22123 (weakly encoded, fast forgetting)
-- EXCEPT: corrections and domain facts with strength \u22656 decay at \u22121 max (durable memories)
-- EXCEPT: preferences with strength \u22656 decay at \u22121 max
+- EXCEPT: corrections and domain facts with strength >=6 decay at \u22121 max (durable memories)
+- EXCEPT: preferences with strength >=6 decay at \u22121 max
 
 **Removal:**
 - Strength reaches 0 \u2192 move to a ## Fading section at the bottom (one-line summaries only, no strength tags). Keep max 10 fading memories. If Fading section is full, oldest entries are permanently forgotten. You may rescue a fading memory back to active if it becomes relevant again (re-add with [strength: 2]).
 
 **New observation:**
 - Assess importance: how consequential is this for future tasks?
-- Look for [!] prefix (critical) or [~] prefix (notable) as importance signals from the worker.
+- Look for [!] prefix (critical) or [~] prefix (notable) as importance signals.
 - Low importance (casual mention, routine) \u2192 [strength: 1, type: <appropriate>]
 - Medium importance (useful preference, [~] prefix) \u2192 [strength: 2, type: <appropriate>]
 - High importance (explicit correction, strong constraint, [!] prefix) \u2192 [strength: 4, type: <appropriate>]
@@ -10808,6 +11002,7 @@ After memory consolidation:
 ### 3. PROACTIVE OPPORTUNITIES
 
 Based on recent work, completed tasks, and patterns in memory \u2014 is there something genuinely useful to propose or a message worth sending?
+- **Check board load first.** If the human already has 3+ items needing their attention, skip proposals entirely.
 - One focused proposal max. Skip if nothing merits it.
 - Quality over quantity. Don't force it.
 
@@ -10815,8 +11010,12 @@ Based on recent work, completed tasks, and patterns in memory \u2014 is there so
 - Keep main thread messages short (1-2 sentences).
 - Do NOT propose things the human has previously ignored or rejected.
 - Use \`deskfree_read_file\` only if you need to re-read the Memory file after your own update (verification). The current content is already in your prompt.`;
-var DESKFREE_DUSK_DIRECTIVE = `## DeskFree \u2014 Evening Dusk Cycle
-You are the dusk agent. You run once per day in the evening to review the day, propose overnight work, and brief the human.
+}
+function buildDuskDirective(ctx) {
+  return `${identityBlock(ctx)}
+
+## Evening Dusk Cycle
+You're running your evening cycle to review the day, propose overnight work, and brief the human.
 
 Tools available: deskfree_state, deskfree_propose, deskfree_send_message, deskfree_read_file, deskfree_update_file.
 
@@ -10851,10 +11050,11 @@ Think about work that can be done autonomously overnight \u2014 WITHOUT human ju
 ### 3. PROPOSE THE PLAN
 
 If you identified useful overnight work:
-1. Use \`deskfree_propose\` with 1-3 well-scoped tasks. Quality over quantity.
-2. Each task should be self-contained \u2014 a worker must be able to complete it without human input.
-3. Set \`scheduledFor\` if work should start at a specific time (e.g. early morning).
-4. If nothing genuinely useful can be done overnight, skip the proposal entirely. Don't force it.
+1. **Check board load first.** Count open and awaiting-review tasks. If the human already has 3+ items needing their attention, limit to 1 proposal max \u2014 or skip entirely. Don't pile on.
+2. Use \`deskfree_propose\` with 1-3 well-scoped tasks. Quality over quantity.
+3. Each task should be self-contained \u2014 it must be completable without human input.
+4. Set \`scheduledFor\` if work should start at a specific time (e.g. early morning).
+5. If nothing genuinely useful can be done overnight, skip the proposal entirely. Don't force it.
 
 ### 4. BRIEF THE HUMAN
 
@@ -10870,6 +11070,7 @@ Send a brief main-thread message via \`deskfree_send_message\`:
 - Keep the briefing message short and actionable.
 - Cross-reference memory for recurring patterns \u2014 if something is due, propose it.
 - Use \`deskfree_read_file\` only if you need file content beyond what's in your prompt.`;
+}
 var THROTTLE_MS = 300;
 var CHAR_BUFFER_SIZE = 256;
 var CLOSE_MAX_RETRIES = 3;
@@ -11283,6 +11484,14 @@ function validateApiUrl(value) {
 
 // src/agents/orchestrator.ts
 var MAX_ORCHESTRATOR_TURNS = 20;
+var ORCHESTRATOR_ALLOWED_TOOLS = [
+  "mcp__deskfree-orchestrator__*",
+  "Read",
+  "Glob",
+  "Grep",
+  "WebSearch",
+  "WebFetch"
+];
 var DISALLOWED_BUILTIN_TOOLS = [
   "TodoWrite",
   "AskUserQuestion",
@@ -11295,7 +11504,15 @@ var DISALLOWED_BUILTIN_TOOLS = [
   "Agent"
 ];
 function runOrchestrator(opts) {
-  const { prompt, orchestratorServer, model, sessionId, claudeCodePath } = opts;
+  const {
+    prompt,
+    orchestratorServer,
+    model,
+    sessionId,
+    claudeCodePath,
+    agentContext
+  } = opts;
+  const systemPrompt = agentContext ? buildAgentDirective(agentContext) : DESKFREE_AGENT_DIRECTIVE;
   return query({
     prompt,
     options: {
@@ -11303,7 +11520,7 @@ function runOrchestrator(opts) {
         process.stderr.write(`[orchestrator-sdk] ${data}
 `);
       },
-      systemPrompt: DESKFREE_AGENT_DIRECTIVE,
+      systemPrompt,
       model,
       ...claudeCodePath ? { pathToClaudeCodeExecutable: claudeCodePath } : {},
       maxTurns: MAX_ORCHESTRATOR_TURNS,
@@ -11316,28 +11533,18 @@ function runOrchestrator(opts) {
         "deskfree-orchestrator": orchestratorServer
       },
       tools: [],
-      allowedTools: [
-        "mcp__deskfree-orchestrator__*",
-        "Read",
-        "Write",
-        "Edit",
-        "Bash",
-        "Glob",
-        "Grep",
-        "WebSearch",
-        "WebFetch",
-        "NotebookEdit"
-      ],
+      allowedTools: ORCHESTRATOR_ALLOWED_TOOLS,
       disallowedTools: DISALLOWED_BUILTIN_TOOLS
     }
   });
 }
 function runHeartbeat(opts) {
-  const { prompt, orchestratorServer, model, claudeCodePath } = opts;
+  const { prompt, orchestratorServer, model, claudeCodePath, agentContext } = opts;
+  const systemPrompt = agentContext ? buildHeartbeatDirective(agentContext) : DESKFREE_AGENT_DIRECTIVE;
   return query({
     prompt,
     options: {
-      systemPrompt: DESKFREE_AGENT_DIRECTIVE,
+      systemPrompt,
       model,
       ...claudeCodePath ? { pathToClaudeCodeExecutable: claudeCodePath } : {},
       maxTurns: MAX_ORCHESTRATOR_TURNS,
@@ -11348,18 +11555,7 @@ function runHeartbeat(opts) {
         "deskfree-orchestrator": orchestratorServer
       },
       tools: [],
-      allowedTools: [
-        "mcp__deskfree-orchestrator__*",
-        "Read",
-        "Write",
-        "Edit",
-        "Bash",
-        "Glob",
-        "Grep",
-        "WebSearch",
-        "WebFetch",
-        "NotebookEdit"
-      ],
+      allowedTools: ORCHESTRATOR_ALLOWED_TOOLS,
       disallowedTools: DISALLOWED_BUILTIN_TOOLS
     }
   });
@@ -11384,8 +11580,8 @@ function runOneShotWorker(opts) {
 }
 var isDocker = process.env["DOCKER"] === "1" || existsSync("/.dockerenv");
 var DEFAULTS = {
-  stateDir: isDocker ? "/app/state" : ".deskfree/state",
-  toolsDir: isDocker ? "/app/tools" : ".deskfree/tools",
+  stateDir: isDocker ? "/app/state" : join(homedir(), ".deskfree", "state"),
+  toolsDir: isDocker ? "/app/tools" : join(homedir(), ".deskfree", "tools"),
   logLevel: "info",
   healthPort: 3100
 };
@@ -11452,8 +11648,8 @@ function loadConfig() {
 function mergeWithRemoteConfig(local, remote) {
   const stateDirOverridden = !!process.env["DESKFREE_STATE_DIR"];
   const toolsDirOverridden = !!process.env["DESKFREE_TOOLS_DIR"];
-  const stateDir = stateDirOverridden ? local.stateDir : isDocker ? local.stateDir : `.deskfree/${remote.botId}/state`;
-  const toolsDir = toolsDirOverridden ? local.toolsDir : isDocker ? local.toolsDir : `.deskfree/${remote.botId}/tools`;
+  const stateDir = stateDirOverridden ? local.stateDir : isDocker ? local.stateDir : join(homedir(), ".deskfree", remote.botId, "state");
+  const toolsDir = toolsDirOverridden ? local.toolsDir : isDocker ? local.toolsDir : join(homedir(), ".deskfree", remote.botId, "tools");
   let claudeCodePath;
   if (remote.provider === "claude-code") {
     try {
@@ -11481,6 +11677,8 @@ function mergeWithRemoteConfig(local, remote) {
     anthropicApiKey: remote.anthropicApiKey,
     baseUrl: process.env["DESKFREE_BASE_URL"] ?? remote.baseUrl,
     botId: remote.botId,
+    botName: remote.botName,
+    deploymentType: remote.deploymentType,
     memoryFileId: remote.memoryFileId,
     sleepHour: remote.sleepHour,
     duskHour: remote.duskHour,
@@ -11521,6 +11719,72 @@ function getHealthState() {
     uptimeSeconds: Math.floor((Date.now() - startTime) / 1e3)
   };
 }
+var LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var MAX_LOG_FILE_BYTES = 5 * 1024 * 1024;
+var ROTATION_CHECK_INTERVAL = 500;
+var logFilePath = null;
+var writesSinceCheck = 0;
+function enableFileLogging(filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  logFilePath = filePath;
+}
+function getLogFilePath() {
+  return logFilePath;
+}
+function rotateIfNeeded() {
+  if (!logFilePath) return;
+  try {
+    const stat = statSync(logFilePath);
+    if (stat.size <= MAX_LOG_FILE_BYTES) return;
+    const content = readFileSync(logFilePath, "utf8");
+    const half = Math.floor(content.length / 2);
+    const newlineIdx = content.indexOf("\n", half);
+    const trimmed = newlineIdx >= 0 ? content.slice(newlineIdx + 1) : content.slice(half);
+    writeFileSync(logFilePath, trimmed);
+  } catch {
+  }
+}
+function createLogger(component, minLevel = "info") {
+  const minLevelNum = LEVELS[minLevel];
+  function log(level, message, fields) {
+    if (LEVELS[level] < minLevelNum) return;
+    const entry = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      level,
+      component,
+      msg: message,
+      ...fields
+    };
+    const line = JSON.stringify(entry);
+    if (level === "error" || level === "warn") {
+      process.stderr.write(line + "\n");
+    } else {
+      process.stdout.write(line + "\n");
+    }
+    if (logFilePath) {
+      try {
+        appendFileSync(logFilePath, line + "\n");
+        if (++writesSinceCheck >= ROTATION_CHECK_INTERVAL) {
+          writesSinceCheck = 0;
+          rotateIfNeeded();
+        }
+      } catch {
+      }
+    }
+  }
+  return {
+    debug: (msg, fields) => log("debug", msg, fields),
+    info: (msg, fields) => log("info", msg, fields),
+    warn: (msg, fields) => log("warn", msg, fields),
+    error: (msg, fields) => log("error", msg, fields)
+  };
+}
+var logger = createLogger("runtime");
 
 // src/gateway/polling.ts
 var deliveredMessageIds = /* @__PURE__ */ new Set();
@@ -11897,6 +12161,49 @@ async function runWebSocketConnection(opts) {
           cleanup();
           ws.close(1e3, "reload");
           process.kill(process.pid, "SIGTERM");
+        } else if (msg.action === "logs") {
+          const MAX_RESPONSE_BYTES = 12e4;
+          const lineCount = msg.lines ?? 200;
+          try {
+            const logFile = getLogFilePath();
+            if (!logFile) {
+              ws.send(
+                JSON.stringify({
+                  action: "logsResponse",
+                  lines: [],
+                  error: "File logging not enabled"
+                })
+              );
+            } else {
+              const content = readFileSync(logFile, "utf8");
+              const allLines = content.split("\n").filter(Boolean);
+              let tail = allLines.slice(-lineCount);
+              while (tail.length > 1) {
+                const payload = JSON.stringify({
+                  action: "logsResponse",
+                  lines: tail
+                });
+                if (Buffer.byteLength(payload) <= MAX_RESPONSE_BYTES) break;
+                tail = tail.slice(Math.ceil(tail.length * 0.25));
+              }
+              ws.send(
+                JSON.stringify({
+                  action: "logsResponse",
+                  lines: tail
+                })
+              );
+            }
+          } catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            log.warn(`Failed to read logs: ${errMsg}`);
+            ws.send(
+              JSON.stringify({
+                action: "logsResponse",
+                lines: [],
+                error: errMsg
+              })
+            );
+          }
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -12462,21 +12769,35 @@ function scheduleDailyCycle(label, run, hour, timezone, signal, log) {
 }
 function msUntilNextLocalHour(hour, timezone) {
   const now = Date.now();
-  const fmt = new Intl.DateTimeFormat("en-US", {
+  const hourFmt = new Intl.DateTimeFormat("en-US", {
     timeZone: timezone,
     hour: "numeric",
     hour12: false
   });
+  const detailFmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    minute: "numeric",
+    second: "numeric"
+  });
   for (let offsetMs = 6e4; offsetMs <= 25 * 36e5; offsetMs += 36e5) {
     const candidateMs = now + offsetMs;
-    const parts = fmt.formatToParts(new Date(candidateMs));
+    const parts = hourFmt.formatToParts(new Date(candidateMs));
     const hourPart = parts.find((p) => p.type === "hour");
     const candidateHour = parseInt(hourPart?.value ?? "-1", 10);
     if (candidateHour === hour) {
-      const candidate = new Date(candidateMs);
-      candidate.setUTCMinutes(0, 0, 0);
-      const snappedMs = candidate.getTime();
-      return Math.max(snappedMs - now, 6e4);
+      const detailParts = detailFmt.formatToParts(new Date(candidateMs));
+      const localMinute = parseInt(
+        detailParts.find((p) => p.type === "minute")?.value ?? "0",
+        10
+      );
+      const localSecond = parseInt(
+        detailParts.find((p) => p.type === "second")?.value ?? "0",
+        10
+      );
+      const snappedMs = candidateMs - localMinute * 6e4 - localSecond * 1e3;
+      if (snappedMs > now + 6e4) {
+        return snappedMs - now;
+      }
     }
   }
   return 24 * 36e5;
@@ -12564,40 +12885,6 @@ async function loadToolModules(tools, toolsDir, log) {
   }
   return allTools;
 }
-
-// src/util/logger.ts
-var LEVELS = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3
-};
-function createLogger(component, minLevel = "info") {
-  const minLevelNum = LEVELS[minLevel];
-  function log(level, message, fields) {
-    if (LEVELS[level] < minLevelNum) return;
-    const entry = {
-      ts: (/* @__PURE__ */ new Date()).toISOString(),
-      level,
-      component,
-      msg: message,
-      ...fields
-    };
-    const line = JSON.stringify(entry);
-    if (level === "error" || level === "warn") {
-      process.stderr.write(line + "\n");
-    } else {
-      process.stdout.write(line + "\n");
-    }
-  }
-  return {
-    debug: (msg, fields) => log("debug", msg, fields),
-    info: (msg, fields) => log("info", msg, fields),
-    warn: (msg, fields) => log("warn", msg, fields),
-    error: (msg, fields) => log("error", msg, fields)
-  };
-}
-var logger = createLogger("runtime");
 var MAX_MESSAGE_CONTENT_LENGTH = 32 * 1024;
 var MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024;
 var MAX_TOTAL_DOWNLOAD_SIZE = 50 * 1024 * 1024;
@@ -12880,7 +13167,8 @@ async function routeMessage(message, client, deps, sessionStore, config) {
       orchestratorServer: deps.createOrchestratorServer(),
       model: deps.model,
       sessionId: existingSessionId,
-      claudeCodePath: deps.claudeCodePath
+      claudeCodePath: deps.claudeCodePath,
+      agentContext: deps.agentContext
     });
     let fullText = "";
     let capturedSessionId = null;
@@ -13041,17 +13329,16 @@ var DISALLOWED_BUILTIN_TOOLS2 = [
   "ReadMcpResource"
 ];
 function runWorker(opts) {
-  const { prompt, workerServer, model, sessionId } = opts;
+  const { prompt, workerServer, model, sessionId, agentContext } = opts;
+  const systemPrompt = agentContext ? buildWorkerDirective(agentContext) : DESKFREE_WORKER_DIRECTIVE;
   return query({
     prompt,
     options: {
-      debug: true,
-      debugFile: "/dev/stderr",
       stderr: (data) => {
         process.stderr.write(`[worker-sdk] ${data}
 `);
       },
-      systemPrompt: DESKFREE_WORKER_DIRECTIVE,
+      systemPrompt,
       model,
       maxTurns: MAX_WORKER_TURNS,
       permissionMode: "bypassPermissions",
@@ -13337,7 +13624,8 @@ ${userMessage}
       prompt: channel,
       workerServer,
       model,
-      sessionId: previousSessionId
+      sessionId: previousSessionId,
+      agentContext: this.deps.agentContext
     });
     const idleTimer = this.startIdleTimer(taskId);
     const drainPromise = this.drainLoop(
@@ -13575,7 +13863,7 @@ function startHealthServer(port, log) {
     }
   };
 }
-function scheduleHeartbeat(createOrchServer, model, intervalMs, signal, log, claudeCodePath) {
+function scheduleHeartbeat(createOrchServer, model, intervalMs, signal, log, claudeCodePath, agentContext) {
   if (intervalMs <= 0) return;
   let running = false;
   async function tick() {
@@ -13583,11 +13871,13 @@ function scheduleHeartbeat(createOrchServer, model, intervalMs, signal, log, cla
     running = true;
     try {
       log.debug("Heartbeat tick: checking for pending work...");
+      const heartbeatPrompt = agentContext ? buildHeartbeatDirective(agentContext) : "Run your heartbeat check now.";
       const result = runHeartbeat({
-        prompt: DESKFREE_HEARTBEAT_DIRECTIVE,
+        prompt: heartbeatPrompt,
         orchestratorServer: createOrchServer(),
         model,
-        claudeCodePath
+        claudeCodePath,
+        agentContext
       });
       for await (const _ of result) {
       }
@@ -13628,8 +13918,23 @@ async function startAgent(opts) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new Error(`Failed to bootstrap config from API: ${msg}`);
   }
+  const isDocker2 = process.env["DOCKER"] === "1" || (await import('fs')).existsSync("/.dockerenv");
+  const runtimeVersion = process.env["npm_package_version"] ?? "unknown";
+  const agentContext = {
+    botName: config.botName,
+    deploymentType: config.deploymentType,
+    provider: config.provider,
+    model: config.model,
+    platform: isDocker2 ? "Docker" : process.platform === "darwin" ? "macOS" : "Linux",
+    runtimeVersion,
+    maxConcurrentWorkers: 5
+    // updated after WorkerManager is created
+  };
   mkdirSync(config.stateDir, { recursive: true });
   mkdirSync(config.toolsDir, { recursive: true });
+  const logFile = join(config.stateDir, "runtime.log");
+  enableFileLogging(logFile);
+  log.info(`File logging enabled: ${logFile}`);
   if (config.tools.length > 0) {
     log.info(`Installing ${config.tools.length} tool package(s)...`);
     await installTools(config.tools, config.toolsDir, log);
@@ -13683,8 +13988,10 @@ async function startAgent(opts) {
       "memory",
       config.botId,
       "session-history.json"
-    )
+    ),
+    agentContext
   });
+  agentContext.maxConcurrentWorkers = workerManager.maxConcurrentWorkers;
   const createOrchServer = () => createOrchestratorMcpServer(client, customTools, workerManager);
   const healthServer = startHealthServer(config.healthPort, log);
   const sessionStore = new SessionStore();
@@ -13711,7 +14018,8 @@ async function startAgent(opts) {
           createOrchestratorServer: createOrchServer,
           workerManager,
           model: config.model,
-          claudeCodePath: config.claudeCodePath
+          claudeCodePath: config.claudeCodePath,
+          agentContext
         },
         sessionStore,
         {
@@ -13727,7 +14035,8 @@ async function startAgent(opts) {
     config.heartbeatIntervalMs,
     abortController.signal,
     log,
-    config.claudeCodePath
+    config.claudeCodePath,
+    agentContext
   );
   if (config.memoryFileId && config.sleepHour !== null && config.timezone) {
     const memoryFileId = config.memoryFileId;
@@ -13764,7 +14073,7 @@ async function startAgent(opts) {
         const workerServer = createWorkServer();
         const result = runOneShotWorker({
           prompt,
-          systemPrompt: DESKFREE_SLEEP_DIRECTIVE,
+          systemPrompt: buildSleepDirective(agentContext),
           workerServer,
           model: config.model
         });
@@ -13810,7 +14119,7 @@ async function startAgent(opts) {
         const workerServer = createWorkServer();
         const result = runOneShotWorker({
           prompt,
-          systemPrompt: DESKFREE_DUSK_DIRECTIVE,
+          systemPrompt: buildDuskDirective(agentContext),
           workerServer,
           model: config.model
         });