@fonz/tgcc 0.6.19 → 0.7.0

package/README.md

@@ -2,6 +2,21 @@
 
 **Telegram ↔ Claude Code bridge** — run Claude Code sessions from Telegram with full streaming, session management, and multi-agent support.
 
+## Why TGCC?
+
+Claude Code is powerful but lives in a terminal. TGCC gives it a **shared, visible interface** through Telegram.
+
+**The problem**: When an AI agent spawns a Claude Code session, it's ephemeral and invisible. No one can watch it work. No one can jump in. When it finishes, the context is gone.
+
+**What TGCC does**: Each CC session gets a Telegram bot that streams output in real-time — thinking, tool use, code edits — all in a single updating message. Multiple sources can share the same CC process:
+
+- Your **OpenClaw agent** delegates a coding task via the supervisor protocol
+- **You** watch it work in Telegram from your phone
+- You can **jump in** mid-session to steer, approve permissions, or add context
+- The agent gets the **result back** automatically when CC finishes
+
+This turns Claude Code from a black-box subprocess into a **collaborative workspace** between humans and AI agents.
+
 ## Quick Start
 
 ```bash
@@ -96,6 +111,68 @@ CC processes can communicate back to the orchestrator via built-in MCP tools:
 See [`docs/SPEC-SUPERVISOR-PROTOCOL.md`](docs/SPEC-SUPERVISOR-PROTOCOL.md) for the full protocol spec.
 See [`docs/SPEC-SUBAGENT-OBSERVABILITY.md`](docs/SPEC-SUBAGENT-OBSERVABILITY.md) for the observability spec.
 
+
+## OpenClaw Plugin
+
+TGCC ships an **OpenClaw community plugin** that gives your OpenClaw agents direct access to TGCC-managed Claude Code sessions.
+
+### Install
+
+```bash
+openclaw plugins install @fonz/tgcc
+```
+
+### Configure
+
+Add to your OpenClaw config (`~/.openclaw/openclaw.json`):
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "tgcc": {
+        "enabled": true,
+        "config": {
+          "socketDir": "/tmp/tgcc/ctl",
+          "defaultAgent": "tgcc",
+          "telegramChatId": "your-chat-id"
+        }
+      }
+    }
+  }
+}
+```
+
+### Tools
+
+The plugin registers four agent tools:
+
+| Tool | Description |
+|------|-------------|
+| `tgcc_status` | List agents, check state, view pending results and events |
+| `tgcc_spawn` | Start a CC session (existing or ephemeral agent) |
+| `tgcc_send` | Send a message to an active agent |
+| `tgcc_kill` | Kill a CC process or destroy an ephemeral agent |
+
+### Example
+
+```
+# From your OpenClaw agent:
+tgcc_spawn agentId="tgcc" task="Fix the render pipeline"
+tgcc_status                    # check progress
+tgcc_send agentId="tgcc" text="Also run the tests"
+tgcc_kill agentId="tgcc"      # done
+```
+
+Ephemeral agents for isolated work:
+
+```
+tgcc_spawn agentId="pr-42" repo="/tmp/pr-42" task="Review this PR" model="opus"
+tgcc_kill agentId="pr-42" destroy=true
+```
+
+The plugin also ships a **skill** (`tgcc-agents`) that teaches OpenClaw agents how to use these tools effectively.
+
 ## Service Management
 
 ```bash

package/dist/plugin/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * OpenClaw plugin entry point for the TGCC Bridge.
+ *
+ * Connects to TGCC's control socket as a supervisor, registers agent tools
+ * (tgcc_spawn, tgcc_send, tgcc_status, tgcc_kill), and relays events.
+ */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+interface TgccPluginConfig {
+    enabled: boolean;
+    socketDir: string;
+    defaultAgent?: string;
+    agents?: string[];
+    telegramChatId?: string;
+}
+declare const tgccPlugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: {
+        parse(value: unknown): TgccPluginConfig;
+        uiHints: {
+            socketDir: {
+                label: string;
+                help: string;
+            };
+            defaultAgent: {
+                label: string;
+                help: string;
+            };
+            agents: {
+                label: string;
+            };
+            telegramChatId: {
+                label: string;
+                help: string;
+            };
+        };
+    };
+    register(api: OpenClawPluginApi): void;
+};
+export default tgccPlugin;

package/dist/plugin/index.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * OpenClaw plugin entry point for the TGCC Bridge.
+ *
+ * Connects to TGCC's control socket as a supervisor, registers agent tools
+ * (tgcc_spawn, tgcc_send, tgcc_status, tgcc_kill), and relays events.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const client_js_1 = require("./src/client.js");
+const events_js_1 = require("./src/events.js");
+const tgcc_spawn_js_1 = require("./src/tools/tgcc-spawn.js");
+const tgcc_send_js_1 = require("./src/tools/tgcc-send.js");
+const tgcc_status_js_1 = require("./src/tools/tgcc-status.js");
+const tgcc_kill_js_1 = require("./src/tools/tgcc-kill.js");
+const permissions_js_1 = require("./src/permissions.js");
+function parseConfig(raw) {
+    const obj = raw ?? {};
+    return {
+        enabled: typeof obj.enabled === "boolean" ? obj.enabled : true,
+        socketDir: typeof obj.socketDir === "string" ? obj.socketDir : "/tmp/tgcc/ctl",
+        defaultAgent: typeof obj.defaultAgent === "string" ? obj.defaultAgent : undefined,
+        agents: Array.isArray(obj.agents) ? obj.agents : undefined,
+        telegramChatId: typeof obj.telegramChatId === "string" ? obj.telegramChatId : undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Socket discovery — find .sock files in the socket directory
+// ---------------------------------------------------------------------------
+function discoverSocket(socketDir) {
+    try {
+        const files = node_fs_1.default.readdirSync(socketDir);
+        const sock = files.find((f) => f.endsWith(".sock"));
+        return sock ? node_path_1.default.join(socketDir, sock) : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin export
+// ---------------------------------------------------------------------------
+const tgccPlugin = {
+    id: "tgcc",
+    name: "TGCC Bridge",
+    description: "Bridge OpenClaw agents to Claude Code sessions via TGCC",
+    configSchema: {
+        parse(value) {
+            const raw = value && typeof value === "object" && !Array.isArray(value)
+                ? value
+                : {};
+            return parseConfig(raw);
+        },
+        uiHints: {
+            socketDir: {
+                label: "Socket Directory",
+                help: "Directory containing TGCC control sockets (default: /tmp/tgcc/ctl)",
+            },
+            defaultAgent: {
+                label: "Default Agent",
+                help: "Default TGCC agent ID for spawns",
+            },
+            agents: { label: "Agent IDs" },
+            telegramChatId: {
+                label: "Telegram Chat ID",
+                help: "Chat ID for permission request buttons",
+            },
+        },
+    },
+    register(api) {
+        const config = parseConfig(api.pluginConfig);
+        if (!config.enabled) {
+            api.logger.info("[tgcc] plugin disabled");
+            return;
+        }
+        const log = api.logger;
+        let client = null;
+        const getClient = () => client;
+        // ── Register tools ──────────────────────────────────────────────
+        api.registerTool((0, tgcc_spawn_js_1.createTgccSpawnTool)(getClient, config.defaultAgent));
+        api.registerTool((0, tgcc_send_js_1.createTgccSendTool)(getClient));
+        api.registerTool((0, tgcc_status_js_1.createTgccStatusTool)(getClient));
+        api.registerTool((0, tgcc_kill_js_1.createTgccKillTool)(getClient));
+        // ── Register gateway methods ────────────────────────────────────
+        // Permission response gateway method
+        api.registerGatewayMethod("tgcc.permission_response", (0, permissions_js_1.createPermissionResponseHandler)(getClient, log));
+        // Status gateway method (for programmatic access)
+        api.registerGatewayMethod("tgcc.status", async ({ params, respond }) => {
+            const c = getClient();
+            if (!c?.isConnected()) {
+                respond(false, { error: "Not connected to TGCC" });
+                return;
+            }
+            try {
+                const agentId = typeof params.agentId === "string" ? params.agentId : undefined;
+                const status = await c.getStatus(agentId);
+                respond(true, status);
+            }
+            catch (err) {
+                respond(false, { error: err instanceof Error ? err.message : String(err) });
+            }
+        });
+        // Send message gateway method
+        api.registerGatewayMethod("tgcc.send", async ({ params, respond }) => {
+            const c = getClient();
+            if (!c?.isConnected()) {
+                respond(false, { error: "Not connected to TGCC" });
+                return;
+            }
+            const agentId = typeof params.agentId === "string" ? params.agentId : "";
+            const text = typeof params.text === "string" ? params.text : "";
+            if (!agentId || !text) {
+                respond(false, { error: "agentId and text are required" });
+                return;
+            }
+            try {
+                const result = await c.sendMessage(agentId, text, { subscribe: true });
+                respond(true, result);
+            }
+            catch (err) {
+                respond(false, { error: err instanceof Error ? err.message : String(err) });
+            }
+        });
+        // ── Register background service ─────────────────────────────────
+        api.registerService({
+            id: "tgcc-supervisor",
+            async start() {
+                const socketPath = discoverSocket(config.socketDir);
+                if (!socketPath) {
+                    log.info(`[tgcc] no socket found in ${config.socketDir}, will retry on reconnect`);
+                }
+                const effectiveSocket = socketPath ?? node_path_1.default.join(config.socketDir, "tgcc.sock");
+                client = new client_js_1.TgccSupervisorClient({
+                    socket: effectiveSocket,
+                    logger: log,
+                });
+                // Wire up event handlers
+                (0, events_js_1.attachEventHandlers)(client, log);
+                // Wire up permission request handler
+                (0, events_js_1.setPermissionRequestHandler)((event) => {
+                    (0, permissions_js_1.handlePermissionRequest)(event, api.runtime, config.telegramChatId, log);
+                });
+                client.start();
+                log.info(`[tgcc] supervisor service started (socket: ${effectiveSocket})`);
+            },
+            async stop() {
+                if (client) {
+                    client.stop();
+                    client = null;
+                    log.info("[tgcc] supervisor service stopped");
+                }
+            },
+        });
+    },
+};
+exports.default = tgccPlugin;
+//# sourceMappingURL=index.js.map

package/dist/plugin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../plugin/index.ts"],"names":[],"mappings":"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"}

package/dist/plugin/openclaw.plugin.json

@@ -0,0 +1,55 @@
+{
+  "id": "tgcc",
+  "name": "TGCC Bridge",
+  "description": "Bridge OpenClaw agents to Claude Code sessions via TGCC (Telegram \u2194 Claude Code)",
+  "version": "0.6.19",
+  "uiHints": {
+    "socketDir": {
+      "label": "Socket Directory",
+      "help": "Directory containing TGCC control sockets (default: /tmp/tgcc/ctl)"
+    },
+    "defaultAgent": {
+      "label": "Default Agent",
+      "help": "Default TGCC agent ID for spawns"
+    },
+    "agents": {
+      "label": "Agent IDs",
+      "help": "TGCC agent IDs to subscribe to (default: all)"
+    },
+    "telegramChatId": {
+      "label": "Telegram Chat ID",
+      "help": "Chat ID for permission request buttons"
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean"
+      },
+      "socketDir": {
+        "type": "string",
+        "description": "Directory containing TGCC control sockets (default: /tmp/tgcc/ctl)"
+      },
+      "defaultAgent": {
+        "type": "string",
+        "description": "Default TGCC agent to use for spawns (e.g. 'tgcc')"
+      },
+      "agents": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "TGCC agent IDs to subscribe to (default: all)"
+      },
+      "telegramChatId": {
+        "type": "string",
+        "description": "Telegram chat ID for permission request buttons"
+      }
+    }
+  },
+  "skills": [
+    "skills/tgcc-agents"
+  ]
+}

package/dist/plugin/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "tgcc",
+  "openclaw": {
+    "extensions": ["./index.js"]
+  }
+}

package/dist/plugin/skills/tgcc-agents/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: tgcc-agents
+description: 'Manage TGCC agents (Claude Code via Telegram) using tgcc_spawn, tgcc_send, tgcc_status, tgcc_kill tools. Use when: spawning CC sessions through TGCC, sending tasks to persistent TGCC bots, checking agent status, killing sessions, or creating ephemeral agents for one-off work.'
+homepage: https://github.com/botverse/tgcc
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🔌",
+        "requires": { "sockets": ["/tmp/tgcc/ctl/tgcc.sock"] },
+        "install":
+          [
+            {
+              "id": "npm",
+              "kind": "npm",
+              "package": "@fonz/tgcc",
+              "label": "Install TGCC plugin",
+            },
+          ],
+        "setup": "Install with `openclaw plugins install @fonz/tgcc`, then configure plugin with socketDir and defaultAgent.",
+      },
+  }
+---
+
+# TGCC Agents — OpenClaw Plugin
+
+Manage **Claude Code sessions via TGCC** (Telegram ↔ Claude Code bridge) using four dedicated tools. TGCC manages CC processes with Telegram rendering — you get visibility in both OpenClaw and Telegram.
+
+## Tools
+
+### `tgcc_status` — Check what's running
+
+```
+tgcc_status                          # all agents
+tgcc_status agentId="tgcc"           # specific agent
+```
+
+Returns:
+- **agents**: list with repo, type (persistent/ephemeral), state (idle/active/spawning)
+- **pendingResults**: completed CC results not yet consumed (use `drain=true` to consume)
+- **pendingPermissions**: permission requests waiting for approval
+- **recentEvents**: last events (cc_spawned, result, error, etc.)
+
+### `tgcc_spawn` — Start a CC session
+
+**Existing agent** (persistent, has Telegram bot):
+```
+tgcc_spawn agentId="tgcc" task="Fix the render pipeline bug"
+tgcc_spawn agentId="sentinella" task="Check tile coverage for Ibiza"
+```
+
+**Ephemeral agent** (one-off, no Telegram bot — requires `repo`):
+```
+tgcc_spawn agentId="my-task" repo="/home/user/project" task="Add error handling"
+tgcc_spawn agentId="review-pr" repo="/tmp/pr-42" task="Review this PR" model="opus"
+```
+
+Optional params:
+- `model`: override CC model (e.g. `opus`, `sonnet`)
+- `permissionMode`: CC permission mode (`plan`, `default`, `bypassPermissions`)
+
+### `tgcc_send` — Message an active agent
+
+Send a follow-up message or new task to an agent that already has a CC session:
+```
+tgcc_send agentId="tgcc" text="Also run the tests"
+tgcc_send agentId="sentinella" text="Now compare with last month"
+```
+
+If the agent is idle (no CC process), this spawns a new session. If active, the message is queued and sent to CC when it's ready for input.
+
+### `tgcc_kill` — Stop a CC session
+
+```
+tgcc_kill agentId="tgcc"                          # kill CC process, keep agent
+tgcc_kill agentId="my-task" destroy=true           # kill CC + destroy ephemeral agent
+```
+
+## Typical Workflows
+
+### Delegate a coding task
+```
+tgcc_spawn agentId="tgcc" task="Implement the OpenClaw plugin per specs/openclaw-plugin.md"
+# ... wait ...
+tgcc_status                    # check pendingResults for completion
+```
+
+### Multi-agent coordination
+```
+tgcc_send agentId="sentinella" text="Generate the fire risk report"
+tgcc_send agentId="kyobot" text="Update the booking dashboard"
+tgcc_status                    # see both working in parallel
+```
+
+### Ephemeral agent for isolated work
+```
+tgcc_spawn agentId="pr-review" repo="/tmp/pr-42" task="Review changes" model="opus"
+# ... result comes back ...
+tgcc_kill agentId="pr-review" destroy=true   # clean up
+```
+
+### Follow up on running work
+```
+tgcc_send agentId="tgcc" text="Also fix the edge case in splitMessage"
+```
+
+## How It Works
+
+```
+OpenClaw Plugin              TGCC Bridge                CC Process
+  │                            │                          │
+  │── send_message ───────────►│                          │
+  │   {agentId, text}          │── spawn/resume CC ──────►│
+  │◄── ack ───────────────────│   {sessionId, state}      │
+  │                            │                          │
+  │   (CC works, visible       │                          │
+  │    in Telegram chat)       │                          │
+  │                            │◄── result ───────────────│
+  │◄── event: result ─────────│   {text, cost}            │
+  │                            │                          │
+```
+
+- **Protocol**: NDJSON over Unix socket (default: `/tmp/tgcc/ctl/*.sock`)
+- **Connection**: Plugin registers as supervisor, auto-reconnects with backoff
+- **Discovery**: Agents auto-discovered on connect (persistent bots + ephemeral)
+- **Events**: cc_spawned, result, process_exit, permission_request, api_error
+- **Shared sessions**: Persistent agents share CC sessions with Telegram users — both see the same work
+
+## Plugin Configuration
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "tgcc": {
+        "enabled": true,
+        "config": {
+          "socketDir": "/tmp/tgcc/ctl",
+          "defaultAgent": "tgcc",
+          "telegramChatId": "7016073156"
+        }
+      }
+    }
+  }
+}
+```
+
+- **socketDir**: where TGCC control sockets live (default: `/tmp/tgcc/ctl`)
+- **defaultAgent**: fallback agentId when none specified
+- **telegramChatId**: chat ID for permission request buttons
+- **agents**: optional array of agent IDs to subscribe to (default: all)
+
+## Permission Requests
+
+When CC needs permission (file write, bash command, etc.), TGCC forwards it through the plugin. If `telegramChatId` is configured, approval buttons appear in Telegram (✅ Allow / ❌ Deny). Otherwise, permissions follow CC's configured `permissionMode`.
+
+## When NOT to Use This
+
+- **Quick file edits**: use the `edit` tool directly
+- **Reading/exploring code**: use `read` / `exec` tools
+- **Tasks needing full isolation from Telegram**: spawn CC directly via coding-agent skill