granclaw 0.0.1-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AITrace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# granclaw
+
+> A personal AI assistant you run on your own machine. Built on the Claude Code CLI.
+
+## Install
+
+```bash
+npx granclaw
+```
+
+or globally:
+
+```bash
+npm i -g granclaw
+granclaw
+```
+
+Requires **Node 20+** and the [Claude Code CLI](https://claude.ai/download) on `PATH`.
+
+## Usage
+
+```
+granclaw [start] [options]
+
+Options:
+  --port <n>      Listen on port n (default: 8787; env: PORT)
+  --home <path>   GranClaw home directory (default: ~/.granclaw; env: GRANCLAW_HOME)
+  --version       Print the version
+  --help          Print this message
+```
+
+On first run, GranClaw creates `~/.granclaw/` containing:
+
+```
+agents.config.json    ← your agents (empty by default)
+data/                 ← SQLite databases
+workspaces/           ← per-agent working directories
+logs/                 ← CLI process logs
+```
+
+Open the dashboard at <http://localhost:8787> and create your first agent.
+
+## What's inside
+
+- **Streaming chat** with Claude Code, tokens live over WebSocket
+- **Mission Control** kanban board every agent knows how to drive
+- **Persistent browser sessions** — saved logins, DOM replay, screenshots
+- **Obsidian-compatible vault** — each agent keeps its own plain-markdown brain
+- **Secrets vault** — API keys injected as env vars only inside the agent process
+- **Schedules** — cron-based scheduled tasks with per-agent isolation
+- **Usage tracking** — token cost breakdown per agent and per model
+
+## Links
+
+- 🌐 [granclaw.com](https://granclaw.com)
+- 💻 [github.com/aitrace-dev/granclaw](https://github.com/aitrace-dev/granclaw)
+- 🐛 [Issues](https://github.com/aitrace-dev/granclaw/issues)
+
+## License
+
+MIT

package/bin/granclaw.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/index.js').main(process.argv.slice(2));

package/dist/backend/agent/process.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * agent/process.ts
+ *
+ * Standalone agent process — spawned by the orchestrator, one per agent.
+ *
+ * Architecture:
+ *   WS server  →  receives messages  →  [BB evaluate]  →  enqueue()
+ *   Queue worker (poll loop)          →  dequeueNext() → runAgent() → broadcastToChannel chunks
+ *
+ * WebSocket protocol:
+ *   Client → Agent:  { type: 'message', text: string, channelId?: string }
+ *   Agent  → Client: { type: 'queued' }
+ *                    { type: 'chunk', chunk: StreamChunk }
+ *                    { type: 'error', message: string }
+ *                    { type: 'blocked', reason: string }
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
+const ws_1 = require("ws");
+const crypto_1 = require("crypto");
+const path_1 = __importDefault(require("path"));
+const config_js_1 = require("../config.js");
+const agent_db_js_1 = require("../agent-db.js");
+const runner_pi_js_1 = require("./runner-pi.js");
+const messages_db_js_1 = require("../messages-db.js");
+const telegram_adapter_js_1 = require("./telegram-adapter.js");
+const browser_sessions_js_1 = require("../browser-sessions.js");
+const takeover_state_js_1 = require("../takeover-state.js");
+const takeover_timeout_js_1 = require("../takeover-timeout.js");
+const agentId = process.env.AGENT_ID;
+const port = Number(process.env.AGENT_PORT);
+if (!agentId || !port) {
+    console.error('[agent/process] AGENT_ID and AGENT_PORT env vars are required');
+    process.exit(1);
+}
+// ── Main ───────────────────────────────────────────────────────────────────────
+function main() {
+    const agent = (0, config_js_1.getAgent)(agentId);
+    if (!agent) {
+        console.error(`[agent/process] Agent "${agentId}" not found in agents.config.json`);
+        process.exit(1);
+    }
+    const workspaceDir = path_1.default.resolve(config_js_1.REPO_ROOT, agent.workspaceDir);
+    // Clean up stale 'processing' jobs from previous crashes/restarts
+    const cleaned = (0, agent_db_js_1.cleanupStaleJobs)(workspaceDir);
+    if (cleaned > 0)
+        console.log(`[agent:${agentId}] cleaned up ${cleaned} stale processing jobs`);
+    // ── WebSocket server ───────────────────────────────────────────────────────
+    const wss = new ws_1.WebSocketServer({ port });
+    // Map from channelId → set of WS clients subscribed to that channel
+    const channelClients = new Map();
+    function getChannelClients(channelId) {
+        if (!channelClients.has(channelId))
+            channelClients.set(channelId, new Set());
+        return channelClients.get(channelId);
+    }
+    wss.on('connection', (ws) => {
+        let clientChannelId = 'ui'; // default until client sends a message with channelId
+        console.log(`[agent:${agentId}] client connected`);
+        ws.on('message', (raw) => {
+            let msg;
+            try {
+                msg = JSON.parse(raw.toString());
+            }
+            catch {
+                ws.send(JSON.stringify({ type: 'error', message: 'invalid JSON' }));
+                return;
+            }
+            if (msg.type === 'stop') {
+                const stopped = (0, runner_pi_js_1.stopAgent)(agentId);
+                console.log(`[agent:${agentId}] stop requested — ${stopped ? 'killed' : 'no active process'}`);
+                ws.send(JSON.stringify({ type: 'stopped', killed: stopped }));
+            }
+            else if (msg.type === 'subscribe' && msg.channelId) {
+                // Subscribe this WS client to a channel without sending a message.
+                // Used by the frontend to receive live chunks from scheduled runs.
+                clientChannelId = msg.channelId;
+                getChannelClients(clientChannelId).add(ws);
+            }
+            else if (msg.type === 'message' && msg.text) {
+                clientChannelId = msg.channelId ?? 'ui';
+                getChannelClients(clientChannelId).add(ws);
+                (0, agent_db_js_1.enqueue)(workspaceDir, agentId, msg.text, clientChannelId);
+                ws.send(JSON.stringify({ type: 'queued' }));
+            }
+        });
+        ws.on('close', () => {
+            // Remove from whichever channel set it was in
+            for (const [id, set] of channelClients.entries()) {
+                set.delete(ws);
+                if (set.size === 0)
+                    channelClients.delete(id);
+            }
+            console.log(`[agent:${agentId}] client disconnected`);
+        });
+    });
+    console.log(`[agent:${agentId}] WS listening on ws://localhost:${port}`);
+    // ── Telegram adapter ───────────────────────────────────────────────────────
+    // Started automatically if TELEGRAM_BOT_TOKEN is set (via Secrets in the UI).
+    // The user adds TELEGRAM_BOT_TOKEN as a secret → orchestrator injects it as
+    // an env var when spawning this process → adapter picks it up here.
+    let telegramAdapter = null;
+    const telegramBotToken = process.env.TELEGRAM_BOT_TOKEN;
+    if (telegramBotToken) {
+        telegramAdapter = new telegram_adapter_js_1.TelegramAdapter(agentId, telegramBotToken, workspaceDir);
+    }
+    // ── Queue worker ───────────────────────────────────────────────────────────
+    function broadcastToChannel(channelId, data) {
+        const json = JSON.stringify(data);
+        const targets = channelClients.get(channelId);
+        if (!targets)
+            return;
+        for (const ws of targets) {
+            if (ws.readyState === ws_1.WebSocket.OPEN)
+                ws.send(json);
+        }
+    }
+    // Track busy state per channel type so UI chat can run while workflows/schedules execute
+    const busyChannels = new Set();
+    function channelType(channelId) {
+        if (channelId.startsWith('wf-'))
+            return 'workflow';
+        if (channelId === 'schedule')
+            return 'schedule';
+        return channelId; // 'ui', 'telegram:xxx' — each is its own lane
+    }
+    async function processNext() {
+        const job = (0, agent_db_js_1.dequeueNext)(workspaceDir, agentId, busyChannels);
+        if (!job)
+            return;
+        const lane = channelType(job.channelId);
+        busyChannels.add(lane);
+        try {
+            const isTelegramJob = telegramAdapter !== null && job.channelId.startsWith('telegram:');
+            // Save the prompt so it's visible in run history immediately
+            try {
+                (0, messages_db_js_1.saveMessage)({ id: (0, crypto_1.randomUUID)(), agentId: agentId, channelId: job.channelId, role: 'user', content: job.message });
+            }
+            catch { /* non-fatal */ }
+            // Stream chunks directly to channel clients.
+            //
+            // tool_call rows are persisted to the DB the moment they arrive
+            // (not batched at turn end). Reason: if a user leaves the chat view
+            // mid-turn and navigates to /dashboard, ChatPage unmounts and loses
+            // its in-memory streaming state. On return, it refetches history
+            // from the DB — if tool_calls were still buffered in memory, the
+            // user would see an empty chat while the agent was clearly still
+            // working. Persisting as-they-happen makes the live state
+            // refetchable. See regression A (view-switch-state.spec.ts).
+            let fullResponse = '';
+            let toolCallCount = 0;
+            // Inject context message if a human takeover was pending
+            let messageText = job.message;
+            if ((0, takeover_state_js_1.hasTakeover)(agentId)) {
+                (0, takeover_state_js_1.cancelTakeoverTimer)(agentId); // stop 10min timeout — entry stays for runner-pi to restore handle
+                messageText =
+                    `[User completed browser interaction]\n` +
+                        `User said: "${job.message}"`;
+            }
+            await (0, runner_pi_js_1.runAgent)(agent, messageText, (chunk) => {
+                broadcastToChannel(job.channelId, { type: 'chunk', chunk });
+                if (chunk.type === 'text') {
+                    fullResponse += chunk.text;
+                    if (isTelegramJob) {
+                        telegramAdapter.appendChunk(job.channelId, chunk.text);
+                    }
+                }
+                if (chunk.type === 'tool_call') {
+                    const tcString = `${chunk.tool}(${JSON.stringify(chunk.input)})`;
+                    toolCallCount++;
+                    try {
+                        (0, messages_db_js_1.saveMessage)({
+                            id: (0, crypto_1.randomUUID)(),
+                            agentId: agentId,
+                            channelId: job.channelId,
+                            role: 'tool_call',
+                            content: tcString,
+                        });
+                    }
+                    catch { /* non-fatal — WAL/locking can fail under parallel writes */ }
+                    if (isTelegramJob) {
+                        // Live status update — appears in the user's chat as the
+                        // acknowledgment message gets edited to show progress.
+                        void telegramAdapter.appendToolStep(job.channelId, chunk.tool);
+                    }
+                }
+            }, { channelId: job.channelId });
+            // Persist the final assistant message. tool_call rows were already
+            // saved one-by-one above, so no batch here.
+            try {
+                if (fullResponse) {
+                    (0, messages_db_js_1.saveMessage)({
+                        id: (0, crypto_1.randomUUID)(),
+                        agentId: agentId,
+                        channelId: job.channelId,
+                        role: 'assistant',
+                        content: fullResponse,
+                        createdAt: Date.now() + toolCallCount, // ordered after the last tool_call
+                    });
+                }
+            }
+            catch { /* non-fatal */ }
+            (0, agent_db_js_1.markDone)(workspaceDir, job.id);
+            // Arm 10-minute timeout if the agent registered a takeover during this run
+            if ((0, takeover_state_js_1.hasTakeover)(agentId)) {
+                const timer = setTimeout(() => {
+                    (0, takeover_timeout_js_1.handleTakeoverTimeout)(agentId, workspaceDir).catch((err) => {
+                        console.error(`[agent:${agentId}] takeover timeout callback failed`, err);
+                    });
+                }, takeover_state_js_1.TAKEOVER_TIMEOUT_MS);
+                (0, takeover_state_js_1.updateTakeoverTimer)(agentId, timer);
+            }
+            // Belt-and-suspenders: if the agent left a browser session open (e.g.
+            // forgot to call close), finalize it so recordings don't stay "active"
+            // forever and stream subscribers detach cleanly.
+            // Skip if a human takeover is pending — browser session must stay alive
+            if (!(0, takeover_state_js_1.hasTakeover)(agentId)) {
+                (0, browser_sessions_js_1.forceCloseActiveSession)(agentId);
+            }
+            // Send the full reply back to Telegram once the turn is complete
+            if (isTelegramJob) {
+                await telegramAdapter.flushReply(job.channelId);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            (0, agent_db_js_1.markFailed)(workspaceDir, job.id);
+            broadcastToChannel(job.channelId, { type: 'error', message });
+            if (telegramAdapter && job.channelId.startsWith('telegram:')) {
+                const chatId = parseInt(job.channelId.split(':')[1], 10);
+                if (!isNaN(chatId)) {
+                    await telegramAdapter.sendErrorMessage(chatId, 'Sorry, something went wrong. Please try again.').catch(() => { });
+                }
+            }
+        }
+        finally {
+            busyChannels.delete(lane);
+        }
+    }
+    setInterval(() => { processNext().catch(console.error); }, 300);
+}
+main();