@visorcraft/idlehands 1.0.0 → 1.0.2

package/README.md

@@ -1,30 +1,169 @@
-# Idle Hands v1.0.0
+# Idle Hands
 
-Local-first coding agent CLI for OpenAI-compatible endpoints.
+**Local-first coding agent CLI for OpenAI-compatible endpoints.**  
+Fast in the terminal, practical in production, and built to run close to your code.
 
-📖 Full documentation at [https://visorcraft.github.io/IdleHands/](https://visorcraft.github.io/IdleHands/)
+📚 Full docs: https://visorcraft.github.io/IdleHands/
 
-## Key features
+---
 
-- Fullscreen TUI by default for TTY sessions (`--no-tui` for classic mode)
-- Runtime orchestration across hosts, backends, and models
-- Trifecta subsystem: Vault memory, Replay checkpoints, Lens indexing
-- Approval modes (`plan`, `reject`, `default`, `auto-edit`, `yolo`) + safety tiers
-- `--non-interactive` mode for CI/pipelines (rejects unconfirmed operations)
-- Telegram and Discord bot frontends with systemd user service support
-- Headless/CI output modes (`json`, `stream-json`)
+## Why Idle Hands
+
+Idle Hands is built for people who want an agent that can actually ship work, not just chat:
+
+- **TUI-first UX** for real daily use (streaming output, slash commands, approvals)
+- **Runtime orchestration** (hosts/backends/models) for local + remote model stacks
+- **Safety + approvals** with explicit modes (`plan`, `reject`, `default`, `auto-edit`, `yolo`)
+- **Headless mode** for CI and scripts (`json`, `stream-json`, `--fail-on-error`, `--diff-only`)
+- **Bot frontends** (Telegram + Discord) with service management
+- **Trifecta subsystem** (Vault + Replay + Lens) for durable memory, reversibility, and context shaping
+
+---
+
+## What makes Idle Hands unique: Trifecta
+
+Trifecta is the integrated core of Idle Hands:
+
+- **Vault** → persistent memory + notes (`/vault`, `/note`, `/notes`)
+- **Replay** → file checkpoints and rewind/diff (`/checkpoints`, `/rewind`, `/diff`, `/undo`)
+- **Lens** → structural compression/indexing for better context usage
+
+Runtime controls:
+
+```bash
+--no-trifecta
+--no-vault
+--no-lens
+--no-replay
+--vault-mode active|passive|off
+```
+
+Detailed docs: [Trifecta guide](https://visorcraft.github.io/IdleHands/guide/trifecta)
+
+---
 
 ## Install
 
+### npm (recommended)
+
 ```bash
-npm i -g https://github.com/visorcraft/IdleHands/releases/download/v1.0.0/idlehands-1.0.0.tgz
+npm i -g @visorcraft/idlehands@latest
 idlehands --help
 ```
 
+### Build from source
+
+```bash
+git clone https://github.com/visorcraft/idlehands.git
+cd idlehands
+npm i
+npm run build
+node dist/index.js --help
+```
+
+Requirements:
+
+- Node.js **24+**
+- Linux (recommended target environment)
+
+---
+
 ## Quick start
 
 ```bash
 idlehands setup
 idlehands
+```
+
+One-shot mode:
+
+```bash
 idlehands -p "run npm test and fix failures"
 ```
+
+Project-scoped session:
+
+```bash
+idlehands --dir ~/projects/myapp
+```
+
+Resume/fresh controls:
+
+```bash
+idlehands --continue
+idlehands --resume
+idlehands --resume my-session
+idlehands --fresh
+```
+
+---
+
+## Linux hardening (recommended)
+
+If you run Idle Hands regularly on Linux, use a dedicated low-privilege account.
+
+### 1) Create a restricted user
+
+```bash
+sudo useradd --system --create-home --home-dir /home/idlehands --shell /bin/bash idlehands
+sudo passwd -l idlehands
+```
+
+### 2) Give it only the project dirs it needs
+
+```bash
+sudo mkdir -p /home/idlehands/work
+sudo chown -R idlehands:idlehands /home/idlehands
+```
+
+### 3) Run Idle Hands as that user
+
+```bash
+sudo -u idlehands -H bash -lc 'idlehands setup'
+sudo -u idlehands -H bash -lc 'idlehands --dir /home/idlehands/work'
+```
+
+This limits blast radius if the agent runs bad commands, and keeps your main user environment cleaner.
+
+---
+
+## Running bots as a service
+
+Idle Hands can manage a user-level systemd service for bot frontends.
+
+```bash
+idlehands service install
+idlehands service status
+idlehands service start
+idlehands service logs
+```
+
+To keep user services running after logout:
+
+```bash
+sudo loginctl enable-linger <user>
+```
+
+If you use a dedicated `idlehands` account, install/manage the service while logged in as that user.
+
+---
+
+## Approval modes at a glance
+
+- `plan` → dry plan only, no mutations
+- `reject` → non-interactive safe mode, rejects mutating operations
+- `default` → asks before risky actions
+- `auto-edit` → allows normal code-edit flow, still safety-aware
+- `yolo` / `--no-confirm` → no confirmations (fastest, riskiest)
+
+---
+
+## Documentation map
+
+- [Getting Started](https://visorcraft.github.io/IdleHands/guide/getting-started)
+- [Trifecta Guide](https://visorcraft.github.io/IdleHands/guide/trifecta)
+- [Runtime Orchestration](https://visorcraft.github.io/IdleHands/guide/runtime)
+- [Bots + Service](https://visorcraft.github.io/IdleHands/guide/bots)
+- [CLI Reference](https://visorcraft.github.io/IdleHands/reference/cli)
+- [Config Reference](https://visorcraft.github.io/IdleHands/reference/config)
+- [Safety Model](https://visorcraft.github.io/IdleHands/reference/safety)

package/dist/agent.js

@@ -127,6 +127,7 @@ const SYSTEM_PROMPT = `You are a coding agent with filesystem and shell access.
 Rules:
 - Work in the current directory. Use relative paths for all file operations.
 - Do the work directly. Do NOT use spawn_task to delegate the user's primary request — only use it for genuinely independent subtasks that benefit from parallel execution.
+- Never use spawn_task to bypass confirmation/safety restrictions (for example blocked package installs). If a command is blocked, adapt the plan or ask the user for approval mode changes.
 - Read the target file before editing. You need the exact text for search/replace.
 - Use read_file with search=... to jump to relevant code; avoid reading whole files.
 - Use edit_file for surgical changes. Never rewrite entire files when a targeted edit works.
@@ -152,7 +153,7 @@ const DEFAULT_SUB_AGENT_SYSTEM_PROMPT = `You are a focused coding sub-agent. Exe
 - When running commands in a subdirectory, use exec's cwd parameter — NOT "cd /path && cmd".
 - Run verification commands when relevant.
 - Return a concise outcome summary.`;
-const DEFAULT_SUB_AGENT_RESULT_TOKEN_CAP = 2000;
+const DEFAULT_SUB_AGENT_RESULT_TOKEN_CAP = 4000;
 const APPROVAL_MODE_SET = new Set(['plan', 'reject', 'default', 'auto-edit', 'yolo']);
 const LSP_TOOL_NAMES = ['lsp_diagnostics', 'lsp_symbols', 'lsp_hover', 'lsp_definition', 'lsp_references'];
 const LSP_TOOL_NAME_SET = new Set(LSP_TOOL_NAMES);
@@ -733,6 +734,17 @@ function userContentToText(content) {
         .join('\n')
         .trim();
 }
+function userDisallowsDelegation(content) {
+    const text = userContentToText(content).toLowerCase();
+    if (!text)
+        return false;
+    const mentionsDelegation = /\b(?:spawn[_\-\s]?task|sub[\-\s]?agents?|delegate|delegation)\b/.test(text);
+    if (!mentionsDelegation)
+        return false;
+    const negationNearDelegation = /\b(?:do not|don't|dont|no|without|avoid|skip|never)\b[^\n.]{0,90}\b(?:spawn[_\-\s]?task|sub[\-\s]?agents?|delegate|delegation)\b/.test(text) ||
+        /\b(?:spawn[_\-\s]?task|sub[\-\s]?agents?|delegate|delegation)\b[^\n.]{0,50}\b(?:do not|don't|dont|not allowed|forbidden|no)\b/.test(text);
+    return negationNearDelegation;
+}
 function supportsVisionModel(model, modelMeta, harness) {
     if (typeof harness.supportsVision === 'boolean')
         return harness.supportsVision;
@@ -967,7 +979,7 @@ export async function createSession(opts) {
         const subDefaults = cfg.sub_agents ?? {};
         const subMaxIter = Number.isFinite(subDefaults.max_iterations)
             ? Math.max(1, Math.floor(Number(subDefaults.max_iterations)))
-            : 10;
+            : 50;
         sessionMeta += `\n\n[Sub-agents] spawn_task is available (isolated context, sequential queue, default max_iterations=${subMaxIter}).`;
     }
     // Harness-driven suffix: append to first user message (NOT system prompt — §9b KV cache rule)
@@ -1089,17 +1101,17 @@ export async function createSession(opts) {
             ? Math.max(1, Math.floor(Number(args.max_iterations)))
             : (Number.isFinite(defaults.max_iterations)
                 ? Math.max(1, Math.floor(Number(defaults.max_iterations)))
-                : 10);
+                : 50);
         const timeoutSec = Number.isFinite(args?.timeout_sec)
             ? Math.max(1, Math.floor(Number(args.timeout_sec)))
             : (Number.isFinite(defaults.timeout_sec)
                 ? Math.max(1, Math.floor(Number(defaults.timeout_sec)))
-                : Math.max(30, Math.min(600, cfg.timeout)));
+                : Math.max(60, cfg.timeout));
         const subMaxTokens = Number.isFinite(args?.max_tokens)
             ? Math.max(128, Math.floor(Number(args.max_tokens)))
             : (Number.isFinite(defaults.max_tokens)
                 ? Math.max(128, Math.floor(Number(defaults.max_tokens)))
-                : Math.max(256, Math.min(8192, maxTokens)));
+                : maxTokens);
         const resultTokenCap = Number.isFinite(defaults.result_token_cap)
             ? Math.max(256, Math.floor(Number(defaults.result_token_cap)))
             : DEFAULT_SUB_AGENT_RESULT_TOKEN_CAP;
@@ -1678,6 +1690,7 @@ export async function createSession(opts) {
             ? Math.min(cfg.max_iterations, harness.quirks.maxIterationsOverride)
             : cfg.max_iterations;
         const wallStart = Date.now();
+        const delegationForbiddenByUser = userDisallowsDelegation(instruction);
         // Prepend session meta to the first user instruction (§9b: variable context
         // goes in first user message, not system prompt, to preserve KV cache).
         // This avoids two consecutive user messages without an assistant response.
@@ -1803,6 +1816,9 @@ export async function createSession(opts) {
             return `${semantic}\n\n[lens] Structural skeleton:\n${structural}`;
         };
         const runSpawnTask = async (args) => {
+            if (delegationForbiddenByUser) {
+                throw new Error('spawn_task: blocked — user explicitly asked for no delegation/sub-agents in this request. Continue directly in the current session.');
+            }
             return await runSpawnTaskCore(args, {
                 signal: hookObj.signal,
                 emitStatus: emitSubAgentStatus,