assurgent 0.0.1 → 0.2.0

package/README.md

@@ -1 +1,175 @@
-# assurgent
+# assurgent Chat Wrapper
+
+A lightweight wrapper that connects chat (e.g. **Telegram**) to Agent (e.g. **Claude Code CLI**), so you can talk to Claude from your phone — with your entire assurgent workspace as context.
+
+> Experimental project, early alpha. Expect bugs and breaking changes, use at your own risk.
+
+```
+You (Telegram) --> Wrapper --> Claude Code CLI --> Response --> You (Telegram)
+```
+
+It is not an agent itself. It's a bridge between Telegram and the Claude Code CLI, with automatic session management.
+
+## Quick Start
+
+### Prerequisites
+
+- [Bun](https://bun.sh) runtime
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
+
+### Install
+
+```bash
+cd app
+bun install
+```
+
+### Configure
+
+```bash
+cp config.example.json config.json
+```
+
+Edit `config.json`:
+
+```json
+{
+  "chat": {
+    "adapter": "telegram",
+    "telegram": {
+      "botToken": "YOUR_BOT_TOKEN_HERE",
+      "allowedUserIds": ["YOUR_TELEGRAM_USER_ID"],
+      "placeholder": {
+        "enabled": true,
+        "text": "thinking..."
+      }
+    }
+  },
+  "agent": {
+    "adapter": "claude-code",
+    "claude-code": {
+      "model": "sonnet",
+      "maxTurns": 10,
+      "flags": ["--dangerously-skip-permissions"],
+      "claudePath": "claude"
+    }
+  },
+  "session": {
+    "turnLimit": 20
+  },
+  "workspacePath": "/path/to/assurgent"
+}
+```
+
+To find your Telegram user ID, message [@userinfobot](https://t.me/userinfobot).
+
+> **Note:** If `claude` is not in your shell's PATH (common on servers where PATH is set in `.bashrc`), set `claudePath` to the full path, e.g. `/home/user/.local/bin/claude`.
+
+### Run
+
+```bash
+bun run dev
+```
+
+Then message your bot on Telegram.
+
+## Bot Commands
+
+| Command                                 | Description                                    |
+| --------------------------------------- | ---------------------------------------------- |
+| `/new`                                  | Archive current session, start fresh           |
+| `/extend [N]`                           | Extend session by N turns (default: turnLimit) |
+| `/model [opus\|sonnet\|haiku\|default]` | Show or change model for current session       |
+| `/session list`                         | List all sessions with turn usage              |
+| `/session info`                         | Show current session details                   |
+| `/session resume <name>`                | Resume a session by name                       |
+| `/session rename <name>`                | Rename current session                         |
+| `/help`                                 | Show all commands                              |
+
+Any other text message is forwarded to Claude Code in the current session.
+
+## Sessions
+
+Sessions always resume the active session until you explicitly start a new one with `/new`.
+
+When the turn count reaches the configured `turnLimit` (default: 20), the bot pauses and asks you to decide:
+- `/extend 20` to add more turns and keep the same session
+- `/new` to archive and start fresh
+
+Session names are auto-generated from the date and first message (e.g. `2026-03-27-fix-bug`).
+
+You can override the model per-session with `/model sonnet` — this persists until you reset with `/model default` or start a new session.
+
+Sessions persist across restarts via `state/sessions.json` (relative to `workspacePath`).
+
+## Config Reference
+
+| Field                               | Description                                                 |
+| ----------------------------------- | ----------------------------------------------------------- |
+| `chat.adapter`                      | Chat platform (`"telegram"`)                                |
+| `chat.telegram.botToken`            | Telegram bot token                                          |
+| `chat.telegram.allowedUserIds`      | Array of allowed Telegram user IDs                          |
+| `chat.telegram.placeholder.enabled` | Show a placeholder message while agent thinks               |
+| `chat.telegram.placeholder.text`    | Placeholder text                                            |
+| `agent.adapter`                     | Agent CLI (`"claude-code"`)                                 |
+| `agent.claude-code.model`           | Default model (e.g. `"opus"`, `"sonnet"`)                   |
+| `agent.claude-code.maxTurns`        | Max agent turns per invocation                              |
+| `agent.claude-code.flags`           | Extra CLI flags (e.g. `["--dangerously-skip-permissions"]`) |
+| `agent.claude-code.claudePath`      | Path to `claude` binary (default: `"claude"`)               |
+| `session.turnLimit`                 | Pause session after N turns, ask user to /extend or /new    |
+| `workspacePath`                     | Absolute path to the assurgent repo root                     |
+
+## Environment Variables Passed to Agent
+
+The wrapper sets these env vars on every Claude Code invocation:
+
+| Variable           | Description                                          |
+| ------------------ | ---------------------------------------------------- |
+| `AGENT_SESSION_ID` | The Claude Code session UUID for the current session |
+
+## Development
+
+```bash
+bun install            # Install dependencies
+bun run dev            # Run the wrapper
+bun run typecheck      # Type check (tsc --noEmit)
+bun test               # Run tests
+bun run lint           # Lint (biome)
+bun run lint:fix       # Auto-fix lint issues
+```
+
+## Architecture
+
+```
+ChatAdapter (Telegram) --> Wrapper Core --> AgentAdapter (Claude Code CLI)
+                              |
+                        Session Manager
+                       (name <-> UUID)
+```
+
+Both the chat side and agent side are pluggable interfaces. The design supports adding other chat platforms or agent backends later without touching the core.
+
+### Directory Structure
+
+```
+app/
+├── src/
+│   ├── index.ts             # Entry point
+│   ├── config.ts            # Config loader + validation
+│   ├── core/
+│   │   ├── wrapper.ts       # Core orchestrator
+│   │   └── session-manager.ts
+│   ├── interfaces/
+│   │   ├── chat-adapter.ts
+│   │   └── agent-adapter.ts
+│   ├── chat/
+│   │   └── telegram.ts      # Telegram adapter (grammy)
+│   └── agent/
+│       └── claude-code.ts   # Claude Code adapter (execa)
+├── config.json              # Runtime config (gitignored)
+├── config.example.json      # Committed template
+├── package.json
+├── tsconfig.json
+└── biome.json
+```

package/cli.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env bun
+// Entry point for `bunx assurgent`
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`
+assurgent - Telegram bot bridge to Claude Code CLI
+
+Usage:
+  assurgent          Start the bot
+  assurgent init     Scaffold config.json into ASSURGENT_HOME
+  assurgent --help   Show this help message
+  assurgent --version  Print the version number
+
+Configuration:
+  Config is loaded from $ASSURGENT_HOME/config.json.
+  ASSURGENT_HOME defaults to ~/.assurgent/ if not set.
+
+  Run "assurgent init" to create the config file, then edit it with your settings.
+`);
+  process.exit(0);
+}
+
+if (args.includes("--version") || args.includes("-v")) {
+  const pkgPath = join(import.meta.dirname, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version: string };
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (args[0] === "init") {
+  const { getAssurgentHome } = await import("./src/config.ts");
+  const target = join(getAssurgentHome(), "config.json");
+
+  if (existsSync(target)) {
+    console.error(
+      `Config already exists at ${target}. Edit it directly or delete it to re-initialize.`,
+    );
+    process.exit(1);
+  }
+
+  mkdirSync(dirname(target), { recursive: true });
+  const source = join(import.meta.dirname, "config.example.json");
+  copyFileSync(source, target);
+  console.log(`Created config at ${target}. Edit it with your settings, then run "assurgent".`);
+  process.exit(0);
+}
+
+await import("./src/index.ts");

package/config.example.json

@@ -0,0 +1,26 @@
+{
+  "chat": {
+    "adapter": "telegram",
+    "telegram": {
+      "botToken": "123456:ABC-DEF...",
+      "allowedUserIds": ["YOUR_TELEGRAM_USER_ID"],
+      "placeholder": {
+        "enabled": true,
+        "text": "thinking..."
+      }
+    }
+  },
+  "agent": {
+    "adapter": "claude-code",
+    "claude-code": {
+      "model": "sonnet",
+      "maxTurns": 10,
+      "flags": ["--dangerously-skip-permissions"],
+      "claudePath": "claude"
+    }
+  },
+  "session": {
+    "turnLimit": 20
+  },
+  "workspacePath": "/path/to/your/workspace"
+}

package/package.json

@@ -1,14 +1,28 @@
 {
   "name": "assurgent",
-  "version": "0.0.1",
-  "description": "",
-  "main": "index.js",
-  "types": "index.d.ts",
-  "files": [
-    "index.js",
-    "index.d.ts"
-  ],
-  "keywords": [],
-  "author": "",
-  "license": "MIT"
+  "version": "0.2.0",
+  "type": "module",
+  "bin": {
+    "assurgent": "./cli.ts"
+  },
+  "files": ["cli.ts", "src", "config.example.json", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --fix"
+  },
+  "dependencies": {
+    "execa": "^9.5.2",
+    "grammy": "^1.35.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/bun": "latest",
+    "typescript": "^5.8.2"
+  }
 }

package/src/agent/claude-code.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import type { ClaudeCodeConfig } from "./claude-code";
+import { SUPPORTED_MODELS, buildArgs } from "./claude-code";
+
+const baseConfig: ClaudeCodeConfig = {
+  model: "opus",
+  maxTurns: 10,
+  flags: [],
+};
+
+describe("SUPPORTED_MODELS", () => {
+  test("contains opus, sonnet, haiku", () => {
+    expect(SUPPORTED_MODELS).toContain("opus");
+    expect(SUPPORTED_MODELS).toContain("sonnet");
+    expect(SUPPORTED_MODELS).toContain("haiku");
+  });
+
+  test("has exactly 3 entries", () => {
+    expect(SUPPORTED_MODELS.length).toBe(3);
+  });
+});
+
+describe("buildArgs", () => {
+  test("always includes -p and --output-format json", () => {
+    const args = buildArgs(baseConfig, { message: "hello" });
+    expect(args).toContain("-p");
+    expect(args).toContain("--output-format");
+    expect(args).toContain("json");
+  });
+
+  test("includes --max-turns from config when not overridden", () => {
+    const args = buildArgs(baseConfig, { message: "hello" });
+    const idx = args.indexOf("--max-turns");
+    expect(idx).not.toBe(-1);
+    expect(args[idx + 1]).toBe("10");
+  });
+
+  test("includes --resume when sessionId is provided", () => {
+    const args = buildArgs(baseConfig, {
+      message: "hello",
+      sessionId: "9b55c171-cee9-4883-a365-abf385761889",
+    });
+    const idx = args.indexOf("--resume");
+    expect(idx).not.toBe(-1);
+    expect(args[idx + 1]).toBe("9b55c171-cee9-4883-a365-abf385761889");
+  });
+
+  test("does not include --resume when sessionId is absent", () => {
+    const args = buildArgs(baseConfig, { message: "hello" });
+    expect(args).not.toContain("--resume");
+  });
+
+  test("options.model overrides config.model", () => {
+    const args = buildArgs(baseConfig, { message: "hello", model: "sonnet" });
+    const idx = args.indexOf("--model");
+    expect(idx).not.toBe(-1);
+    expect(args[idx + 1]).toBe("sonnet");
+    expect(args.filter((a) => a === "--model").length).toBe(1);
+  });
+
+  test("includes --append-system-prompt when appendPrompt is set", () => {
+    const args = buildArgs(baseConfig, {
+      message: "hello",
+      appendPrompt: "Be concise.",
+    });
+    const idx = args.indexOf("--append-system-prompt");
+    expect(idx).not.toBe(-1);
+    expect(args[idx + 1]).toBe("Be concise.");
+  });
+
+  test("includes config flags", () => {
+    const config: ClaudeCodeConfig = {
+      ...baseConfig,
+      flags: ["--dangerously-skip-permissions"],
+    };
+    const args = buildArgs(config, { message: "hello" });
+    expect(args).toContain("--dangerously-skip-permissions");
+  });
+
+  test("message is always the last argument", () => {
+    const args = buildArgs(baseConfig, {
+      message: "do the thing",
+      sessionId: "abc-123",
+      appendPrompt: "extra",
+    });
+    expect(args[args.length - 1]).toBe("do the thing");
+  });
+});

package/src/agent/claude-code.ts

@@ -0,0 +1,79 @@
+import { execa } from "execa";
+import type { AgentAdapter, AgentInvokeOptions, AgentResponse } from "../interfaces/agent-adapter";
+
+export const SUPPORTED_MODELS = ["opus", "sonnet", "haiku"] as const;
+
+export interface ClaudeCodeConfig {
+  model: string;
+  maxTurns: number;
+  flags: string[];
+  claudePath?: string;
+}
+
+/**
+ * Builds the CLI argument array for `claude -p` invocations.
+ * Pure function -- no side effects.
+ */
+export function buildArgs(config: ClaudeCodeConfig, options: AgentInvokeOptions): string[] {
+  const args: string[] = [
+    "-p",
+    "--output-format",
+    "json",
+    "--max-turns",
+    String(options.maxTurns ?? config.maxTurns),
+  ];
+
+  // Spread configured flags (e.g. --dangerously-skip-permissions)
+  args.push(...config.flags);
+
+  if (options.sessionId) {
+    args.push("--resume", options.sessionId);
+  }
+
+  const model = options.model ?? config.model;
+  if (model) {
+    args.push("--model", model);
+  }
+
+  if (options.appendPrompt) {
+    args.push("--append-system-prompt", options.appendPrompt);
+  }
+
+  // Message must always be the last argument
+  args.push(options.message);
+
+  return args;
+}
+
+/** AgentAdapter implementation backed by the Claude Code CLI. */
+export class ClaudeCodeAdapter implements AgentAdapter {
+  readonly name = "claude-code";
+
+  constructor(
+    private config: ClaudeCodeConfig,
+    private workspacePath: string,
+  ) {}
+
+  async invoke(options: AgentInvokeOptions): Promise<AgentResponse> {
+    const args = buildArgs(this.config, options);
+
+    const proc = await execa(this.config.claudePath ?? "claude", args, {
+      cwd: this.workspacePath,
+      timeout: 180_000,
+      stdin: "ignore",
+      env: {
+        ...process.env,
+        AGENT_SESSION_ID: options.sessionId ?? "",
+      },
+    });
+
+    const raw = JSON.parse(proc.stdout) as Record<string, unknown>;
+
+    return {
+      result: (raw.result as string) ?? "",
+      sessionId: (raw.session_id as string) ?? "",
+      durationMs: (raw.duration_ms as number) ?? 0,
+      raw,
+    };
+  }
+}

package/src/chat/telegram.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import { splitMessage } from "./telegram";
+
+describe("splitMessage", () => {
+  test("returns single chunk when text is under limit", () => {
+    const result = splitMessage("hello world", 100);
+    expect(result).toEqual(["hello world"]);
+  });
+
+  test("splits at last newline before maxLength", () => {
+    const text = "line one\nline two\nline three";
+    const result = splitMessage(text, 18);
+    // "line one\nline two" is 17 chars, fits
+    expect(result[0]).toBe("line one\nline two");
+    expect(result[1]).toBe("line three");
+  });
+
+  test("hard splits at maxLength when no newlines present", () => {
+    const text = "abcdefghij"; // 10 chars
+    const result = splitMessage(text, 5);
+    expect(result[0]).toBe("abcde");
+    expect(result[1]).toBe("fghij");
+  });
+
+  test("handles multiple chunks", () => {
+    const text = "aaa\nbbb\nccc\nddd\neee";
+    const result = splitMessage(text, 8);
+    // "aaa\nbbb" is 7 chars
+    expect(result.length).toBeGreaterThanOrEqual(2);
+    for (const chunk of result) {
+      expect(chunk.length).toBeLessThanOrEqual(8);
+    }
+  });
+
+  test("returns empty array element for empty string", () => {
+    const result = splitMessage("", 100);
+    expect(result).toEqual([""]);
+  });
+});

package/src/chat/telegram.ts

@@ -0,0 +1,135 @@
+import { Bot } from "grammy";
+import type { Context } from "grammy";
+import type { ChatAdapter, IncomingMessage } from "../interfaces/chat-adapter";
+
+/**
+ * Splits a text string into chunks of at most maxLength characters.
+ * Prefers splitting at the last newline before maxLength.
+ * If no newline is found, splits at maxLength.
+ * Trims leading whitespace from subsequent chunks.
+ */
+export function splitMessage(text: string, maxLength: number): string[] {
+  if (text.length <= maxLength) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining);
+      break;
+    }
+
+    let splitAt = remaining.lastIndexOf("\n", maxLength);
+    if (splitAt <= 0) splitAt = maxLength;
+
+    chunks.push(remaining.slice(0, splitAt));
+    remaining = remaining.slice(splitAt).trimStart();
+  }
+
+  return chunks;
+}
+
+export class TelegramAdapter implements ChatAdapter {
+  private bot: Bot;
+  private messageHandler?: (msg: IncomingMessage) => Promise<void>;
+  private commandHandlers = new Map<
+    string,
+    (msg: IncomingMessage, args: string) => Promise<void>
+  >();
+
+  constructor(
+    private config: {
+      botToken: string;
+      allowedUserIds: string[];
+      placeholder?: { enabled: boolean; text: string };
+    },
+  ) {
+    this.bot = new Bot(config.botToken);
+  }
+
+  async start(): Promise<void> {
+    for (const [cmd, handler] of this.commandHandlers) {
+      this.bot.command(cmd, async (ctx) => {
+        if (!this.isAllowed(ctx.from?.id)) return;
+        const msg = this.toIncoming(ctx);
+        await handler(msg, ctx.match ?? "");
+      });
+    }
+
+    this.bot.on("message:text", async (ctx) => {
+      if (!this.isAllowed(ctx.from?.id)) return;
+      if (ctx.message?.text?.startsWith("/")) return;
+      if (this.messageHandler) {
+        await this.messageHandler(this.toIncoming(ctx));
+      }
+    });
+
+    this.bot.start();
+  }
+
+  async stop(): Promise<void> {
+    await this.bot.stop();
+  }
+
+  onMessage(handler: (msg: IncomingMessage) => Promise<void>): void {
+    this.messageHandler = handler;
+  }
+
+  onCommand(command: string, handler: (msg: IncomingMessage, args: string) => Promise<void>): void {
+    this.commandHandlers.set(command, handler);
+  }
+
+  async sendText(chatId: string, text: string): Promise<void> {
+    const chunks = splitMessage(text, 4000);
+    for (const chunk of chunks) {
+      try {
+        await this.bot.api.sendMessage(Number(chatId), chunk, { parse_mode: "Markdown" });
+      } catch {
+        await this.bot.api.sendMessage(Number(chatId), chunk);
+      }
+    }
+  }
+
+  async sendTyping(chatId: string): Promise<void> {
+    await this.bot.api.sendChatAction(Number(chatId), "typing");
+  }
+
+  async sendPlaceholder(chatId: string): Promise<number | undefined> {
+    if (!this.config.placeholder?.enabled) return undefined;
+    const msg = await this.bot.api.sendMessage(Number(chatId), this.config.placeholder.text);
+    return msg.message_id;
+  }
+
+  async editMessage(chatId: string, messageId: number, text: string): Promise<void> {
+    const chunks = splitMessage(text, 4000);
+    try {
+      await this.bot.api.editMessageText(Number(chatId), messageId, chunks[0], {
+        parse_mode: "Markdown",
+      });
+    } catch {
+      await this.bot.api.editMessageText(Number(chatId), messageId, chunks[0]);
+    }
+    for (let i = 1; i < chunks.length; i++) {
+      try {
+        await this.bot.api.sendMessage(Number(chatId), chunks[i], { parse_mode: "Markdown" });
+      } catch {
+        await this.bot.api.sendMessage(Number(chatId), chunks[i]);
+      }
+    }
+  }
+
+  private isAllowed(userId?: number): boolean {
+    if (!userId) return false;
+    return this.config.allowedUserIds.includes(String(userId));
+  }
+
+  private toIncoming(ctx: Context): IncomingMessage {
+    return {
+      chatId: String(ctx.chat?.id ?? ""),
+      text: ctx.message?.text ?? "",
+      from: String(ctx.from?.id ?? ""),
+      timestamp: ctx.message?.date ?? Date.now(),
+    };
+  }
+}