@fonz/tgcc 0.6.18 → 0.7.0

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

package/dist/plugin/src/client.d.ts

@@ -0,0 +1,167 @@
+/**
+ * TgccSupervisorClient — Unix socket client for the TGCC Supervisor Protocol.
+ *
+ * Connects to TGCC's ctl socket, registers as a supervisor, and provides
+ * async methods for interacting with TGCC-managed agents and CC processes.
+ *
+ * Adapted from the OpenClaw fork (src/agents/tgcc-supervisor/client.ts)
+ * to use only the plugin API — no OpenClaw internal imports.
+ */
+import { EventEmitter } from "node:events";
+import type { PluginLogger } from "openclaw/plugin-sdk";
+export interface SupervisorCommand {
+    type: "command";
+    requestId: string;
+    action: string;
+    params?: Record<string, unknown>;
+}
+export interface SupervisorResponse {
+    type: "response";
+    requestId: string;
+    result?: unknown;
+    error?: string;
+}
+export interface SupervisorEvent {
+    type: "event";
+    event: string;
+    [key: string]: unknown;
+}
+export interface TgccAgentStatus {
+    id: string;
+    type: "persistent" | "ephemeral";
+    state: "idle" | "active";
+    sessionId: string | null;
+    repo: string;
+    supervisorSubscribed: boolean;
+}
+export interface TgccStatusResult {
+    agents: TgccAgentStatus[];
+    sessions?: Array<{
+        id: string;
+        agentId: string;
+        messageCount?: number;
+        totalCostUsd?: number;
+    }>;
+}
+export interface TgccResultEvent {
+    agentId: string;
+    sessionId: string;
+    text: string;
+    cost_usd?: number;
+    duration_ms?: number;
+    is_error?: boolean;
+}
+export interface TgccProcessExitEvent {
+    agentId: string;
+    sessionId: string;
+    exitCode: number | null;
+}
+export interface TgccSessionTakeoverEvent {
+    agentId: string;
+    sessionId: string;
+    exitCode: number | null;
+}
+export interface TgccApiErrorEvent {
+    agentId: string;
+    sessionId: string;
+    message: string;
+}
+export interface TgccPermissionRequestEvent {
+    agentId: string;
+    toolName: string;
+    requestId: string;
+    description: string;
+}
+export interface TgccSupervisorClientConfig {
+    socket: string;
+    logger: PluginLogger;
+    reconnectInitialMs?: number;
+    reconnectMaxMs?: number;
+    heartbeatMs?: number;
+}
+export declare class TgccSupervisorClient extends EventEmitter {
+    private log;
+    private socketPath;
+    private socket;
+    private connected;
+    private destroyed;
+    private reconnectDelay;
+    private reconnectInitialMs;
+    private reconnectMaxMs;
+    private heartbeatMs;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private pongTimer;
+    private pendingRequests;
+    private lineBuffer;
+    constructor(config: TgccSupervisorClientConfig);
+    start(): void;
+    stop(): void;
+    isConnected(): boolean;
+    sendMessage(agentId: string, text: string, opts?: {
+        sessionId?: string;
+        subscribe?: boolean;
+    }): Promise<{
+        sessionId: string;
+        state: string;
+        subscribed?: boolean;
+    }>;
+    sendToCC(agentId: string, text: string): Promise<{
+        sent: boolean;
+    }>;
+    getStatus(agentId?: string): Promise<TgccStatusResult>;
+    killCC(agentId: string): Promise<unknown>;
+    subscribe(agentId: string, sessionId?: string): Promise<unknown>;
+    unsubscribe(agentId: string): Promise<unknown>;
+    respondToPermission(agentId: string, permissionRequestId: string, decision: "allow" | "deny"): Promise<unknown>;
+    createAgent(params: {
+        agentId?: string;
+        repo: string;
+        model?: string;
+        permissionMode?: string;
+        timeoutMs?: number;
+    }): Promise<{
+        agentId: string;
+        state: string;
+    }>;
+    destroyAgent(agentId: string): Promise<{
+        destroyed: boolean;
+    }>;
+    getLog(agentId: string, opts?: {
+        offset?: number;
+        limit?: number;
+        grep?: string;
+        since?: number;
+        type?: string;
+    }): Promise<{
+        totalLines: number;
+        returnedLines: number;
+        offset: number;
+        lines: Array<{
+            ts: number;
+            type: string;
+            text: string;
+        }>;
+    }>;
+    private connect;
+    private scheduleReconnect;
+    private register;
+    private startHeartbeat;
+    private sendPing;
+    private forceReconnect;
+    private handleData;
+    private handleMessage;
+    private handleResponse;
+    private handleEvent;
+    private syncStateAfterConnect;
+    private handleReverseCommand;
+    private handleExecCommand;
+    private handleRestartServiceCommand;
+    private handleNotifyCommand;
+    private sendResponse;
+    private sendCommand;
+    private sendRaw;
+    private clearTimers;
+    private clearHeartbeat;
+    private rejectAllPending;
+}