palmier 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# Palmier Agent
+
+A Node.js CLI that runs on your machine as a persistent agent. It manages tasks, communicates with the Palmier platform via NATS, and executes Claude Code autonomously.
+
+## Prerequisites
+
+- **Node.js 20+**
+- **Claude Code CLI** installed and authenticated
+- **Linux with systemd** (the agent installs as a systemd user service)
+
+## Installation
+
+```bash
+npm install -g palmier-agent
+```
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `palmier init --token <token>` | Provision the agent with a token from the dashboard |
+| `palmier serve` | Run the persistent NATS RPC handler (default command) |
+| `palmier run <task-id>` | Execute a specific task |
+| `palmier hook` | Handle Claude Code hook events (invoked by Claude Code, not manually) |
+
+## Setup
+
+1. Install the agent: `npm install -g palmier-agent`
+2. Register on the Palmier PWA and click **Add Agent**.
+3. Copy the provisioning token.
+4. Run `palmier init --token <token>` in your project directory.
+
+The `init` command:
+- Saves agent configuration to `~/.config/palmier/agent.json`
+- Installs a systemd user service for the agent
+- Configures Claude Code hooks for remote interaction
+
+## How It Works
+
+- The agent runs as a **systemd user service**, staying alive in the background.
+- Incoming tasks from the platform are stored as `TASK.md` files in a local `tasks/` directory.
+- Task execution spawns **Claude Code in a PTY**, giving the AI full CLI access within the project.
+- **Hooks** intercept Claude Code permission, confirmation, and input prompts, resolving them remotely via NATS KV so tasks can run unattended.
+
+## Project Structure
+
+```
+src/
+  index.ts            # CLI entrypoint (commander setup)
+  config.ts           # Agent configuration (read/write ~/.config/palmier)
+  nats-client.ts      # NATS connection and messaging
+  systemd.ts          # systemd service installation
+  task.ts             # Task file management
+  types.ts            # Shared type definitions
+  commands/
+    init.ts           # Provisioning logic
+    serve.ts          # Persistent NATS RPC handler
+    run.ts            # Single task execution
+    hook.ts           # Claude Code hook handler
+```
+
+## Related
+
+See the [palmier](../palmier) repo for the server, API, and PWA.

package/dist/commands/hook.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Handle a Claude Code hook invocation.
+ * Called by Claude Code as a subprocess. Reads hook event from stdin,
+ * dispatches by hook_name, and outputs response to stdout.
+ */
+export declare function hookCommand(): Promise<void>;
+//# sourceMappingURL=hook.d.ts.map

package/dist/commands/hook.js

@@ -0,0 +1,181 @@
+import { v4 as uuidv4 } from "uuid";
+import { StringCodec } from "nats";
+import { loadConfig } from "../config.js";
+import { connectNats } from "../nats-client.js";
+/**
+ * Handle a Claude Code hook invocation.
+ * Called by Claude Code as a subprocess. Reads hook event from stdin,
+ * dispatches by hook_name, and outputs response to stdout.
+ */
+export async function hookCommand() {
+    const rawInput = await readStdin();
+    let event;
+    try {
+        event = JSON.parse(rawInput);
+    }
+    catch {
+        console.error("Failed to parse hook event from stdin");
+        process.exit(1);
+    }
+    const taskId = process.env.PALMIER_TASK_ID;
+    if (!taskId) {
+        // Not running in a palmier task context, exit silently
+        return;
+    }
+    const config = loadConfig();
+    const nc = await connectNats(config);
+    const sc = StringCodec();
+    try {
+        const js = nc.jetstream();
+        const kv = await js.views.kv("pending-hooks");
+        switch (event.hook_name) {
+            case "PermissionRequest":
+                await handlePermissionRequest(config, nc, kv, sc, event, taskId);
+                break;
+            case "Notification":
+                await handleNotification(config, nc, kv, sc, event, taskId);
+                break;
+            case "Stop":
+                await handleStop(config, nc, sc, taskId);
+                break;
+            default:
+                // Unknown hook, exit silently
+                break;
+        }
+    }
+    finally {
+        await nc.drain();
+    }
+}
+async function handlePermissionRequest(config, nc, kv, sc, event, taskId) {
+    const hookId = uuidv4();
+    const kvKey = `${config.agentId}.${taskId}.${hookId}`;
+    // Start watching BEFORE writing
+    const watch = await kv.watch({ key: kvKey });
+    // Write hook payload to KV
+    const payload = {
+        type: "permission",
+        task_id: taskId,
+        hook_id: hookId,
+        agent_id: config.agentId,
+        user_id: config.userId,
+        details: {
+            tool: event.tool_name,
+            input: event.tool_input,
+        },
+        status: "pending",
+    };
+    await kv.put(kvKey, sc.encode(JSON.stringify(payload)));
+    // Publish push notification
+    nc.publish(`user.${config.userId}.push.request.permission`, sc.encode(JSON.stringify({
+        type: "permission",
+        task_id: taskId,
+        hook_id: hookId,
+        agent_id: config.agentId,
+        tool: event.tool_name,
+        input: event.tool_input,
+    })));
+    // Wait for status change
+    for await (const entry of watch) {
+        if (entry.operation === "DEL" || entry.operation === "PURGE") {
+            // Key deleted, deny by default
+            process.stdout.write(JSON.stringify({ behavior: "deny" }));
+            return;
+        }
+        try {
+            const updated = JSON.parse(sc.decode(entry.value));
+            if (updated.status === "confirmed" || updated.status === "allowed") {
+                process.stdout.write(JSON.stringify({ behavior: "allow" }));
+                await kv.delete(kvKey);
+                return;
+            }
+            else if (updated.status === "denied" || updated.status === "aborted") {
+                process.stdout.write(JSON.stringify({ behavior: "deny" }));
+                await kv.delete(kvKey);
+                return;
+            }
+            // Still pending, keep watching
+        }
+        catch {
+            // Couldn't parse, keep watching
+        }
+    }
+}
+async function handleNotification(config, nc, kv, sc, event, taskId) {
+    const message = event.message || "";
+    // Check if notification requires user input
+    // Look for patterns suggesting input is needed
+    const inputPatterns = [
+        /\bwait(ing)?\s+(for|on)\s+(user\s+)?input\b/i,
+        /\bplease\s+(provide|enter|type|input)\b/i,
+        /\buser\s+input\s+(required|needed)\b/i,
+        /\bask(ing)?\s+(the\s+)?user\b/i,
+        /\brequires?\s+(user\s+)?input\b/i,
+        /\bprompt(ing)?\s+(the\s+)?user\b/i,
+    ];
+    const needsInput = inputPatterns.some((pattern) => pattern.test(message));
+    if (!needsInput) {
+        // No input needed, exit silently
+        return;
+    }
+    const hookId = uuidv4();
+    const kvKey = `${config.agentId}.${taskId}.${hookId}`;
+    // Start watching BEFORE writing
+    const watch = await kv.watch({ key: kvKey });
+    // Write hook payload to KV
+    const payload = {
+        type: "input",
+        task_id: taskId,
+        hook_id: hookId,
+        agent_id: config.agentId,
+        user_id: config.userId,
+        details: {
+            message: event.message,
+        },
+        status: "pending",
+    };
+    await kv.put(kvKey, sc.encode(JSON.stringify(payload)));
+    // Publish push notification
+    nc.publish(`user.${config.userId}.push.notify.input_needed`, sc.encode(JSON.stringify({
+        type: "input",
+        task_id: taskId,
+        hook_id: hookId,
+        agent_id: config.agentId,
+        message: event.message,
+    })));
+    // Wait for status change - the status field will contain the user's input text
+    for await (const entry of watch) {
+        if (entry.operation === "DEL" || entry.operation === "PURGE") {
+            return;
+        }
+        try {
+            const updated = JSON.parse(sc.decode(entry.value));
+            if (updated.status !== "pending") {
+                // The status field contains the user's input text
+                process.stdout.write(updated.status);
+                await kv.delete(kvKey);
+                return;
+            }
+            // Still pending, keep watching
+        }
+        catch {
+            // Couldn't parse, keep watching
+        }
+    }
+}
+async function handleStop(config, nc, sc, taskId) {
+    // Publish completion notification
+    nc.publish(`user.${config.userId}.push.notify.complete`, sc.encode(JSON.stringify({
+        type: "complete",
+        task_id: taskId,
+        agent_id: config.agentId,
+    })));
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+//# sourceMappingURL=hook.js.map

package/dist/commands/init.d.ts

@@ -0,0 +1,8 @@
+export interface InitOptions {
+    token: string;
+}
+/**
+ * Provision this agent by exchanging a base64 provisioning token for permanent credentials.
+ */
+export declare function initCommand(options: InitOptions): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.js

@@ -0,0 +1,111 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+import { homedir } from "os";
+import { saveConfig } from "../config.js";
+/**
+ * Provision this agent by exchanging a base64 provisioning token for permanent credentials.
+ */
+export async function initCommand(options) {
+    // 1. Decode base64 provisioning token
+    let decoded;
+    try {
+        const jsonStr = Buffer.from(options.token, "base64").toString("utf-8");
+        decoded = JSON.parse(jsonStr);
+    }
+    catch {
+        console.error("Failed to decode provisioning token. Ensure it is a valid base64-encoded JSON string.");
+        process.exit(1);
+    }
+    if (!decoded.server || !decoded.token) {
+        console.error("Invalid provisioning token: missing 'server' or 'token' field.");
+        process.exit(1);
+    }
+    console.log(`Claiming agent at ${decoded.server}...`);
+    // 2. POST to server to claim agent
+    let claimResponse;
+    try {
+        const res = await fetch(`${decoded.server}/api/agents/claim`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ provisioning_token: decoded.token }),
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            console.error(`Failed to claim agent: ${res.status} ${res.statusText}\n${body}`);
+            process.exit(1);
+        }
+        claimResponse = (await res.json());
+    }
+    catch (err) {
+        console.error(`Failed to reach server: ${err}`);
+        process.exit(1);
+    }
+    // 3. Save config
+    const config = {
+        agentId: claimResponse.agent_id,
+        userId: claimResponse.user_id,
+        natsUrl: claimResponse.nats_url,
+        natsWsUrl: claimResponse.nats_ws_url,
+        natsToken: claimResponse.nats_token,
+        projectRoot: process.cwd(),
+    };
+    saveConfig(config);
+    console.log(`Agent provisioned. ID: ${config.agentId}`);
+    console.log("Config saved to ~/.config/palmier/agent.json");
+    // 4. Write Claude Code hooks config
+    const claudeSettingsDir = path.join(process.cwd(), ".claude");
+    fs.mkdirSync(claudeSettingsDir, { recursive: true });
+    const hooksConfig = {
+        hooks: {
+            PermissionRequest: [{ type: "command", command: "palmier hook" }],
+            Notification: [{ type: "command", command: "palmier hook" }],
+            Stop: [{ type: "command", command: "palmier hook" }],
+        },
+    };
+    fs.writeFileSync(path.join(claudeSettingsDir, "settings.json"), JSON.stringify(hooksConfig, null, 2), "utf-8");
+    console.log("Claude Code hooks config written to .claude/settings.json");
+    // 5. Install systemd user service for palmier serve
+    const unitDir = path.join(homedir(), ".config", "systemd", "user");
+    fs.mkdirSync(unitDir, { recursive: true });
+    const palmierBin = process.argv[1] || "palmier";
+    const serviceContent = `[Unit]
+Description=Palmier Agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${palmierBin} serve
+WorkingDirectory=${config.projectRoot}
+Restart=on-failure
+RestartSec=5
+Environment=PATH=${process.env.PATH || "/usr/local/bin:/usr/bin:/bin"}
+
+[Install]
+WantedBy=default.target
+`;
+    const servicePath = path.join(unitDir, "palmier-agent.service");
+    fs.writeFileSync(servicePath, serviceContent, "utf-8");
+    console.log("Systemd service installed at:", servicePath);
+    // 6. Enable and start the service
+    try {
+        execSync("systemctl --user daemon-reload", { stdio: "inherit" });
+        execSync("systemctl --user enable --now palmier-agent.service", { stdio: "inherit" });
+        console.log("Palmier agent service enabled and started.");
+    }
+    catch (err) {
+        console.error(`Warning: failed to enable systemd service: ${err}`);
+        console.error("You may need to start it manually: systemctl --user enable --now palmier-agent.service");
+    }
+    // 7. Enable lingering so service runs without active login session
+    try {
+        execSync(`loginctl enable-linger ${process.env.USER || ""}`, { stdio: "inherit" });
+        console.log("Login lingering enabled.");
+    }
+    catch (err) {
+        console.error(`Warning: failed to enable linger: ${err}`);
+    }
+    console.log("\nAgent initialization complete!");
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/run.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Execute a task by ID.
+ */
+export declare function runCommand(taskId: string): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/commands/run.js

@@ -0,0 +1,163 @@
+import { v4 as uuidv4 } from "uuid";
+import { loadConfig } from "../config.js";
+import { connectNats } from "../nats-client.js";
+import { parseTaskFile, getTaskDir } from "../task.js";
+import { StringCodec } from "nats";
+/**
+ * Execute a task by ID.
+ */
+export async function runCommand(taskId) {
+    const config = loadConfig();
+    const taskDir = getTaskDir(config.projectRoot, taskId);
+    const task = parseTaskFile(taskDir);
+    console.log(`Running task: ${task.frontmatter.name || taskId}`);
+    let nc;
+    let kv;
+    // Track KV keys we create so we can clean them up
+    const kvKeysToClean = [];
+    const cleanup = async () => {
+        if (kv) {
+            for (const key of kvKeysToClean) {
+                try {
+                    await kv.delete(key);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+        }
+        if (nc && !nc.isClosed()) {
+            await nc.drain();
+        }
+    };
+    // Handle signals
+    const onSignal = async () => {
+        console.log("Received signal, cleaning up...");
+        await cleanup();
+        process.exit(1);
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    try {
+        // If requires_confirmation, ask user via NATS KV
+        if (task.frontmatter.requires_confirmation) {
+            nc = await connectNats(config);
+            const js = nc.jetstream();
+            kv = await js.views.kv("pending-hooks");
+            const confirmed = await requestConfirmation(config, task, kv, nc, kvKeysToClean);
+            if (!confirmed) {
+                console.log("Task aborted by user.");
+                await cleanup();
+                return;
+            }
+            console.log("Task confirmed by user.");
+        }
+        // Spawn Claude CLI via node-pty
+        await spawnClaude(config, task, taskId);
+        console.log(`Task ${taskId} completed.`);
+    }
+    catch (err) {
+        console.error(`Task ${taskId} failed:`, err);
+        process.exitCode = 1;
+    }
+    finally {
+        await cleanup();
+    }
+}
+async function requestConfirmation(config, task, kv, nc, kvKeysToClean) {
+    const sc = StringCodec();
+    const hookId = uuidv4();
+    const kvKey = `${config.agentId}.${task.frontmatter.id}.${hookId}`;
+    kvKeysToClean.push(kvKey);
+    // Start watching BEFORE writing, to avoid race condition
+    const watch = await kv.watch({ key: kvKey });
+    // Write hook payload to KV
+    const payload = {
+        type: "confirm",
+        task_id: task.frontmatter.id,
+        hook_id: hookId,
+        agent_id: config.agentId,
+        user_id: config.userId,
+        details: {
+            task_name: task.frontmatter.name,
+            prompt: task.frontmatter.user_prompt,
+        },
+        status: "pending",
+    };
+    await kv.put(kvKey, sc.encode(JSON.stringify(payload)));
+    // Publish push notification
+    nc.publish(`user.${config.userId}.push.request.confirm`, sc.encode(JSON.stringify({
+        type: "confirm",
+        task_id: task.frontmatter.id,
+        hook_id: hookId,
+        agent_id: config.agentId,
+        task_name: task.frontmatter.name,
+    })));
+    // Wait for status change
+    for await (const entry of watch) {
+        if (entry.operation === "DEL" || entry.operation === "PURGE") {
+            // Key was deleted, treat as aborted
+            return false;
+        }
+        try {
+            const updated = JSON.parse(sc.decode(entry.value));
+            if (updated.status === "confirmed") {
+                await kv.delete(kvKey);
+                kvKeysToClean.pop();
+                return true;
+            }
+            else if (updated.status === "aborted") {
+                await kv.delete(kvKey);
+                kvKeysToClean.pop();
+                return false;
+            }
+            // Still pending, keep watching
+        }
+        catch {
+            // Couldn't parse, keep watching
+        }
+    }
+    return false;
+}
+async function spawnClaude(config, task, taskId) {
+    // Dynamic import of node-pty (native module)
+    const { spawn } = await import("node-pty");
+    return new Promise((resolve, reject) => {
+        const args = ["-p", task.frontmatter.user_prompt];
+        if (task.frontmatter.suppress_permissions) {
+            args.push("--dangerously-skip-permissions");
+        }
+        // If the task has a body (system prompt / additional instructions), pass via --system-prompt
+        if (task.body) {
+            args.push("--system-prompt", task.body);
+        }
+        const ptyProcess = spawn("claude", args, {
+            name: "xterm-256color",
+            cols: 120,
+            rows: 40,
+            cwd: config.projectRoot,
+            env: {
+                ...process.env,
+                PALMIER_TASK_ID: taskId,
+            },
+        });
+        ptyProcess.onData((data) => {
+            process.stdout.write(data);
+        });
+        ptyProcess.onExit(({ exitCode }) => {
+            if (exitCode === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`Claude exited with code ${exitCode}`));
+            }
+        });
+        // Forward signals to pty child
+        const killChild = () => {
+            ptyProcess.kill();
+        };
+        process.on("SIGINT", killChild);
+        process.on("SIGTERM", killChild);
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/serve.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Start the persistent NATS RPC handler.
+ */
+export declare function serveCommand(): Promise<void>;
+//# sourceMappingURL=serve.d.ts.map