@fonz/tgcc 0.6.15 → 0.6.18

package/README.md

@@ -20,11 +20,81 @@ TGCC bridges the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-cod
 
 - **Streaming** — responses stream into a single message that updates in place
 - **Sessions** — resume, switch, and list sessions. Roam between Telegram and the CC CLI on the same session
-- **Multi-project** — switch repos on the fly with `/repo`, or run dedicated bots per project
+- **Multi-agent** — run dedicated bots per project, each with its own repo and model
 - **Permission relay** — CC permission prompts appear as inline buttons
 - **MCP tools** — CC can send files, images, and voice back via built-in MCP server
 - **Markdown → Telegram HTML** — code blocks, bold, italic, links, tables, all rendered properly
 - **Usage stats** — per-turn token counts and cost
+- **Supervisor protocol** — external orchestrators (e.g. OpenClaw) can send messages, subscribe to events, and share the same CC process via Unix socket
+
+## Architecture
+
+```
+Telegram ──► TGCC Bridge ──► Claude Code CLI (stream-json)
+                 │
+CLI (ctl) ───────┤
+                 │
+Supervisor ──────┘ (Unix socket, NDJSON)
+```
+
+### Agent Model
+
+Each agent has:
+- **One repo** — the project directory CC runs in
+- **One CC process** (at most) — shared by all message sources (Telegram, supervisor, CLI)
+- **One model** — the Claude model to use
+
+Agents don't know about users. `allowedUsers` is a system-level ACL that gates which Telegram users can interact with the bot. All allowed users share the same agent state.
+
+`sessionId` lives on the CC process, not the agent. When a process spawns, it either continues the last session (`--continue`) or resumes a specific one (`--resume <id>`).
+
+### Supervisor Protocol
+
+External systems connect to TGCC's control socket (`/tmp/tgcc/ctl/tgcc.sock`) and register as a supervisor. They can then:
+
+- **`send_message`** — send a message to any agent's CC process (spawns if needed)
+- **`send_to_cc`** — write directly to an active CC process's stdin
+- **`subscribe`** / **`unsubscribe`** — observe an agent's events
+- **`status`** — list all agents, their state, and active processes
+- **`kill_cc`** — terminate an agent's CC process
+
+Events forwarded to subscribers: `result`, `session_takeover`, `process_exit`, `cc_spawned`, `state_changed`, `bridge_started`, plus all observability events.
+
+When a supervisor sends a message to a persistent agent, a system notification (`🦞 OpenClaw: ...`) appears in the Telegram chat.
+
+### Ephemeral Agents
+
+Supervisors can create temporary agents for one-off tasks — no Telegram bot needed:
+
+- **`create_agent`** — create an in-memory agent with a repo and model
+- **`destroy_agent`** — tear down when the task is done
+
+Ephemeral agents auto-destroy on timeout. Only the supervisor can interact with them.
+
+### Observability
+
+TGCC detects high-signal events from CC processes and forwards them to subscribers:
+
+- **Build/test results** — pass/fail with error counts
+- **Git commits** — commit messages as natural progress summaries
+- **Context pressure** — alerts at 50%, 75%, 90% of context window
+- **Failure loops** — 3+ consecutive tool failures
+- **Stuck detection** — no CC output for 5+ minutes
+- **Task milestones** — TodoWrite progress tracking
+- **Sub-agent spawns** — CC using Task tool for parallel work
+
+Each agent's events are stored in a ring buffer, queryable via `get_log` with offset/limit/grep/since/type filters.
+
+### MCP Tools for CC → Supervisor
+
+CC processes can communicate back to the orchestrator via built-in MCP tools:
+
+- **`notify_parent`** — send a message to the parent (questions, blockers, progress)
+- **`supervisor_exec`** — request command execution on the host
+- **`supervisor_notify`** — send a notification to any agent
+
+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.
 
 ## Service Management
 
@@ -61,7 +131,7 @@ tgcc repo list
 
 # Messaging (while service is running)
 tgcc message "fix the login bug"
-tgcc message "deploy" --agent=mybot --session=abc123
+tgcc message "deploy" --agent=mybot
 tgcc status
 tgcc status --agent=mybot
 
@@ -82,40 +152,6 @@ tgcc permissions set mybot dangerously-skip
 | `/permissions` | Set permission mode |
 | `/status` | Process state, model, repo, cost |
 | `/cancel` | Abort current CC turn |
-| `/catchup` | Summarize external CC activity |
-
-## Project Setup
-
-TGCC supports two approaches — use one or both:
-
-### Single bot, multiple repos (recommended)
-
-One bot switches between projects on the fly:
-
-```bash
-tgcc repo add ~/code/frontend --name=frontend
-tgcc repo add ~/code/backend --name=backend
-tgcc repo assign --agent=mybot --name=frontend   # set default
-```
-
-In Telegram, use `/repo` to switch. If no repo is selected, TGCC warns that CC will run in `~`.
-
-### Dedicated bot per project
-
-Create a separate Telegram bot (via [@BotFather](https://t.me/BotFather)) for each project:
-
-```bash
-tgcc agent add frontend-bot --bot-token <token1>
-tgcc agent add backend-bot --bot-token <token2>
-
-tgcc repo add ~/code/frontend --name=frontend
-tgcc repo add ~/code/backend --name=backend
-
-tgcc repo assign --agent=frontend-bot --name=frontend
-tgcc repo assign --agent=backend-bot --name=backend
-```
-
-Each bot starts CC in its assigned repo by default. Users can still `/repo` switch if needed.
 
 ## Configuration
 
@@ -133,9 +169,10 @@ Config lives at `~/.tgcc/config.json` (created by `tgcc init`).
   "agents": {
     "mybot": {
       "botToken": "123456:ABC-DEF...",
-      "allowedUsers": [],
+      "allowedUsers": ["your-telegram-id"],
       "defaults": {
         "repo": "myproject",
+        "model": "claude-sonnet-4-20250514",
         "permissionMode": "bypassPermissions"
       }
     }
@@ -152,19 +189,6 @@ Config lives at `~/.tgcc/config.json` (created by `tgcc init`).
 | `default` | Full permission flow via inline buttons |
 | `plan` | Plan-only, no tool execution |
 
-## Architecture
-
-```
-User ──► Telegram ──► TGCC ──► Claude Code CLI (stream-json)
-                        │
-                  config.json ─── agents, repos, permissions
-                  state.json ─── sessions, per-user overrides
-```
-
-TGCC runs as a persistent service. When a user sends a message, it spawns (or resumes) a Claude Code process using the `stream-json` protocol, streams the response back with edit-in-place updates.
-
-Sessions are fully interoperable with the VS Code Claude Code extension — same `~/.claude/projects/` JSONL files.
-
 ## License
 
 MIT

package/dist/bridge.d.ts

@@ -6,11 +6,16 @@ export declare class Bridge extends EventEmitter implements CtlHandler {
     private config;
     private agents;
     private processRegistry;
-    private sessionModelOverrides;
     private mcpServer;
     private ctlServer;
     private sessionStore;
     private logger;
+    private highSignalDetector;
+    private supervisorWrite;
+    private supervisorAgentId;
+    private supervisorSubscriptions;
+    private suppressExitForProcess;
+    private supervisorPendingRequests;
     constructor(config: TgccConfig, logger?: pino.Logger);
     start(): Promise<void>;
     private startAgent;
@@ -18,14 +23,12 @@ export declare class Bridge extends EventEmitter implements CtlHandler {
     private stopAgent;
     private handleTelegramMessage;
     private sendToCC;
-    /** Check if the session JSONL was modified externally since we last tracked it. */
-    private checkSessionStaleness;
     /**
-     * Disconnect a client from its CC process.
-     * If other subscribers remain, the process stays alive.
-     * If this was the last subscriber, the process is destroyed.
+     * Kill the agent's CC process and clean up.
      */
-    private disconnectClient;
+    private killAgentProcess;
+    /** Get the primary TG chat ID for an agent (first allowed user). */
+    private getAgentChatId;
     private startTypingIndicator;
     private stopTypingIndicator;
     private spawnCCProcess;
@@ -36,5 +39,14 @@ export declare class Bridge extends EventEmitter implements CtlHandler {
     handleCtlMessage(agentId: string, text: string, sessionId?: string): CtlAckResponse;
     handleCtlStatus(agentId?: string): CtlStatusResponse;
     private handleMcpToolRequest;
+    private isSupervisorSubscribed;
+    registerSupervisor(agentId: string, capabilities: string[], writeFn: (line: string) => void): void;
+    handleSupervisorDetach(): void;
+    handleSupervisorLine(line: string): void;
+    private handleSupervisorCommand;
+    private emitStateChanged;
+    private sendToSupervisor;
+    private sendSupervisorRequest;
+    private destroyEphemeralAgent;
     stop(): Promise<void>;
 }