palmier 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "palmier",
+  "version": "0.1.0",
+  "description": "Palmier agent CLI - provisions, executes tasks, and serves NATS RPC",
+  "license": "ISC",
+  "author": "Hongxu Cai",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "palmier": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7",
+    "nats": "^2.29.1",
+    "node-pty": "^1.0.0",
+    "uuid": "^11.1.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "@types/uuid": "^10.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/commands/hook.ts

@@ -0,0 +1,240 @@
+import { v4 as uuidv4 } from "uuid";
+import { StringCodec } from "nats";
+import { loadConfig } from "../config.js";
+import { connectNats } from "../nats-client.js";
+import type { ClaudeHookEvent, HookPayload } from "../types.js";
+import type { NatsConnection, KV } from "nats";
+
+/**
+ * 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(): Promise<void> {
+  const rawInput = await readStdin();
+
+  let event: ClaudeHookEvent;
+  try {
+    event = JSON.parse(rawInput) as ClaudeHookEvent;
+  } 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: ReturnType<typeof loadConfig>,
+  nc: NatsConnection,
+  kv: KV,
+  sc: ReturnType<typeof StringCodec>,
+  event: ClaudeHookEvent,
+  taskId: string
+): Promise<void> {
+  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: HookPayload = {
+    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)) as HookPayload;
+      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: ReturnType<typeof loadConfig>,
+  nc: NatsConnection,
+  kv: KV,
+  sc: ReturnType<typeof StringCodec>,
+  event: ClaudeHookEvent,
+  taskId: string
+): Promise<void> {
+  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: HookPayload = {
+    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)) as HookPayload;
+      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: ReturnType<typeof loadConfig>,
+  nc: NatsConnection,
+  sc: ReturnType<typeof StringCodec>,
+  taskId: string
+): Promise<void> {
+  // 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(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}

package/src/commands/init.ts

@@ -0,0 +1,140 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+import { homedir } from "os";
+import { saveConfig } from "../config.js";
+import type { AgentConfig } from "../types.js";
+
+export interface InitOptions {
+  token: string;
+}
+
+/**
+ * Provision this agent by exchanging a base64 provisioning token for permanent credentials.
+ */
+export async function initCommand(options: InitOptions): Promise<void> {
+  // 1. Decode base64 provisioning token
+  let decoded: { server: string; token: string };
+  try {
+    const jsonStr = Buffer.from(options.token, "base64").toString("utf-8");
+    decoded = JSON.parse(jsonStr) as { server: string; token: string };
+  } 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: {
+    agent_id: string;
+    user_id: string;
+    nats_url: string;
+    nats_ws_url: string;
+    nats_token: string;
+  };
+
+  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()) as typeof claimResponse;
+  } catch (err) {
+    console.error(`Failed to reach server: ${err}`);
+    process.exit(1);
+  }
+
+  // 3. Save config
+  const config: AgentConfig = {
+    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!");
+}

package/src/commands/run.ts

@@ -0,0 +1,197 @@
+import { v4 as uuidv4 } from "uuid";
+import { loadConfig } from "../config.js";
+import { connectNats } from "../nats-client.js";
+import { parseTaskFile, getTaskDir } from "../task.js";
+import type { AgentConfig, ParsedTask, HookPayload } from "../types.js";
+import type { NatsConnection, KV } from "nats";
+import { StringCodec } from "nats";
+
+/**
+ * Execute a task by ID.
+ */
+export async function runCommand(taskId: string): Promise<void> {
+  const config = loadConfig();
+  const taskDir = getTaskDir(config.projectRoot, taskId);
+  const task = parseTaskFile(taskDir);
+
+  console.log(`Running task: ${task.frontmatter.name || taskId}`);
+
+  let nc: NatsConnection | undefined;
+  let kv: KV | undefined;
+
+  // Track KV keys we create so we can clean them up
+  const kvKeysToClean: string[] = [];
+
+  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: AgentConfig,
+  task: ParsedTask,
+  kv: KV,
+  nc: NatsConnection,
+  kvKeysToClean: string[]
+): Promise<boolean> {
+  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: HookPayload = {
+    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)) as HookPayload;
+      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: AgentConfig,
+  task: ParsedTask,
+  taskId: string
+): Promise<void> {
+  // Dynamic import of node-pty (native module)
+  const { spawn } = await import("node-pty");
+
+  return new Promise<void>((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,
+      } as Record<string, string>,
+    });
+
+    ptyProcess.onData((data: string) => {
+      process.stdout.write(data);
+    });
+
+    ptyProcess.onExit(({ exitCode }: { exitCode: number }) => {
+      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);
+  });
+}