refactor: migrate runtime managers to typescript

Author: MackDing

README.md

@@ -104,7 +104,7 @@ npm run healthcheck
 Telegram Message
   -> src/bot/handlers.js
   -> src/orchestrator/router.ts
-     -> src/runner/ptyManager.js        (coding tasks -> Codex CLI)
+     -> src/runner/ptyManager.ts        (coding tasks -> Codex CLI)
      -> src/orchestrator/skills/*.js    (general tasks -> MCP/GitHub subagents)
   -> src/bot/formatter.js
   -> Telegram sendMessage/editMessageText
@@ -116,7 +116,7 @@ Core modules:
 - `src/config.ts`: env parsing and validation
 - `src/bot/`: auth middleware, formatting, command handlers
 - `src/orchestrator/`: routing + MCP client + skills
-- `src/runner/ptyManager.js`: Codex PTY process + streaming
+- `src/runner/ptyManager.ts`: Codex PTY process + streaming
 - `src/cron/scheduler.js`: proactive scheduled push
 
 Enterprise target architecture: [docs/enterprise-architecture.md](/Users/ding/Documents/Code/Github/codex-telegram-claws/docs/enterprise-architecture.md)

docs/enterprise-architecture.md

@@ -110,9 +110,9 @@ For enterprise rollout, migrate the following first:
 - `src/config.ts`
 - `src/orchestrator/router.ts`
 - `src/orchestrator/skillRegistry.ts`
-- `src/orchestrator/mcpClient.js`
-- `src/runner/ptyManager.js`
-- `src/runner/shellManager.js`
+- `src/orchestrator/mcpClient.ts`
+- `src/runner/ptyManager.ts`
+- `src/runner/shellManager.ts`
 
 TypeScript matters here because config shape, skill contracts, worker RPC payloads, and audit event schemas must remain stable across teams and releases.
 

docs/phase-1-roadmap.md

@@ -20,9 +20,9 @@ Scope:
 - Migrate `src/config.ts`
 - Migrate `src/orchestrator/router.ts`
 - Migrate `src/orchestrator/skillRegistry.ts`
-- Migrate `src/orchestrator/mcpClient.js`
-- Migrate `src/runner/ptyManager.js`
-- Migrate `src/runner/shellManager.js`
+- Migrate `src/orchestrator/mcpClient.ts`
+- Migrate `src/runner/ptyManager.ts`
+- Migrate `src/runner/shellManager.ts`
 
 Deliverables:
 

package-lock.json

@@ -44,6 +44,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
+    "@types/lodash.throttle": "^4.1.9",
     "@types/node": "^25.5.0",
     "@typescript-eslint/eslint-plugin": "^8.57.0",
     "@typescript-eslint/parser": "^8.57.0",

package.json

@@ -1,13 +1,57 @@
+import process from "node:process";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { AppConfig, McpServerConfig } from "../config.js";
 
-function normalizeToolContent(result) {
+interface ToolTextItem {
+  text?: string;
+  json?: unknown;
+}
+
+interface ToolResultLike {
+  content?: string | ToolTextItem[];
+}
+
+interface McpConnection {
+  client: {
+    connect: (transport: unknown) => Promise<void>;
+    listTools: () => Promise<{ tools?: Array<{ name?: string }> }>;
+    callTool: (input: {
+      name: string;
+      arguments: Record<string, unknown>;
+    }) => Promise<unknown>;
+  };
+  transport: {
+    close?: () => Promise<void>;
+  };
+}
+
+export interface McpServerStatus {
+  name: string;
+  command: string;
+  args: string[];
+  cwd: string;
+  enabled: boolean;
+  connected: boolean;
+}
+
+export interface McpClientSnapshot {
+  disabledServers: string[];
+}
+
+interface McpClientOptions {
+  onChange?: (snapshot: McpClientSnapshot) => void;
+}
+
+function normalizeToolContent(result: unknown): string {
   if (!result) return "";
 
   if (typeof result === "string") return result;
 
-  if (Array.isArray(result.content)) {
-    return result.content
+  const content = (result as ToolResultLike & { content?: unknown }).content;
+
+  if (Array.isArray(content)) {
+    return content
       .map((item) => {
         if (typeof item === "string") return item;
         if (item?.text) return item.text;
@@ -18,44 +62,60 @@ function normalizeToolContent(result) {
       .join("\n");
   }
 
-  if (result?.content?.text) return String(result.content.text);
-  if (result?.content?.json) return JSON.stringify(result.content.json);
+  if (content && typeof content === "object") {
+    const record = content as ToolTextItem;
+    if (record.text) {
+      return String(record.text);
+    }
+
+    if (record.json !== undefined) {
+      return JSON.stringify(record.json);
+    }
+  }
 
   return JSON.stringify(result);
 }
 
 export class McpClient {
-  constructor(config, { onChange } = {}) {
+  readonly config: Pick<AppConfig, "mcp">;
+  readonly connections: Map<string, McpConnection>;
+  disabledServers: Set<string>;
+  private readonly onChange?: (snapshot: McpClientSnapshot) => void;
+
+  constructor(
+    config: Pick<AppConfig, "mcp">,
+    { onChange }: McpClientOptions = {}
+  ) {
     this.config = config;
     this.connections = new Map();
     this.disabledServers = new Set();
     this.onChange = onChange;
   }
 
-  hasServers() {
+  hasServers(): boolean {
     return this.config.mcp.servers.length > 0;
   }
 
-  getServerConfig(serverName) {
+  getServerConfig(serverName: string): McpServerConfig | null {
     return (
       this.config.mcp.servers.find((server) => server.name === serverName) ||
       null
     );
   }
 
-  hasServer(serverName) {
+  hasServer(serverName: string): boolean {
     return Boolean(this.getServerConfig(serverName));
   }
 
-  isServerEnabled(serverName) {
+  isServerEnabled(serverName: string): boolean {
     return this.hasServer(serverName) && !this.disabledServers.has(serverName);
   }
 
-  isServerConnected(serverName) {
+  isServerConnected(serverName: string): boolean {
     return this.connections.has(serverName);
   }
 
-  listServers() {
+  listServers(): McpServerStatus[] {
     return this.config.mcp.servers.map((server) => ({
       name: server.name,
       command: server.command,
@@ -66,27 +126,31 @@ export class McpClient {
     }));
   }
 
-  async connectAll() {
+  async connectAll(): Promise<void> {
     for (const server of this.config.mcp.servers) {
       await this.connectServer(server);
     }
   }
 
-  async connectServer(server) {
+  async connectServer(server: McpServerConfig): Promise<void> {
     if (this.disabledServers.has(server.name)) {
       return;
     }
 
     if (this.connections.has(server.name)) return;
 
+    const env = Object.fromEntries(
+      Object.entries({
+        ...process.env,
+        ...server.env
+      }).filter(([, value]) => value !== undefined)
+    ) as Record<string, string>;
+
     const transport = new StdioClientTransport({
       command: server.command,
       args: server.args,
       cwd: server.cwd,
-      env: {
-        ...process.env,
-        ...server.env
-      }
+      env
     });
 
     const client = new Client(
@@ -97,13 +161,13 @@ export class McpClient {
       {
         capabilities: {}
       }
-    );
+    ) as McpConnection["client"];
 
     await client.connect(transport);
     this.connections.set(server.name, { client, transport });
   }
 
-  async connectServerByName(serverName) {
+  async connectServerByName(serverName: string): Promise<void> {
     const server = this.getServerConfig(serverName);
     if (!server) {
       throw new Error(`Unknown MCP server: ${serverName}`);
@@ -116,7 +180,7 @@ export class McpClient {
     await this.connectServer(server);
   }
 
-  async disconnectServer(serverName) {
+  async disconnectServer(serverName: string): Promise<boolean> {
     const conn = this.connections.get(serverName);
     if (!conn) return false;
 
@@ -130,7 +194,7 @@ export class McpClient {
     return true;
   }
 
-  async reconnectServer(serverName) {
+  async reconnectServer(serverName: string): Promise<McpServerStatus | null> {
     if (!this.hasServer(serverName)) {
       throw new Error(`Unknown MCP server: ${serverName}`);
     }
@@ -146,7 +210,9 @@ export class McpClient {
     );
   }
 
-  async disableServer(serverName) {
+  async disableServer(
+    serverName: string
+  ): Promise<(McpServerStatus & { changed: boolean }) | null> {
     if (!this.hasServer(serverName)) {
       throw new Error(`Unknown MCP server: ${serverName}`);
     }
@@ -165,7 +231,9 @@ export class McpClient {
     return current ? { ...current, changed: true } : null;
   }
 
-  async enableServer(serverName) {
+  async enableServer(
+    serverName: string
+  ): Promise<(McpServerStatus & { changed: boolean }) | null> {
     if (!this.hasServer(serverName)) {
       throw new Error(`Unknown MCP server: ${serverName}`);
     }
@@ -188,13 +256,13 @@ export class McpClient {
     return current ? { ...current, changed } : null;
   }
 
-  exportState() {
+  exportState(): McpClientSnapshot {
     return {
       disabledServers: [...this.disabledServers].sort()
     };
   }
 
-  restoreState(snapshot = {}) {
+  restoreState(snapshot: Partial<McpClientSnapshot> = {}): void {
     const disabledServers = Array.isArray(snapshot?.disabledServers)
       ? snapshot.disabledServers.filter((serverName) =>
           this.hasServer(serverName)
@@ -204,14 +272,22 @@ export class McpClient {
     this.disabledServers = new Set(disabledServers);
   }
 
-  async listTools(serverName) {
+  async listTools(serverName: string): Promise<Array<{ name?: string }>> {
     const conn = this.connections.get(serverName);
     if (!conn) throw new Error(`MCP server not connected: ${serverName}`);
     const res = await conn.client.listTools();
     return res.tools || [];
   }
 
-  async callTool({ serverName, toolName, args = {} }) {
+  async callTool({
+    serverName,
+    toolName,
+    args = {}
+  }: {
+    serverName: string;
+    toolName: string;
+    args?: Record<string, unknown>;
+  }): Promise<string> {
     const conn = this.connections.get(serverName);
     if (!conn) throw new Error(`MCP server not connected: ${serverName}`);
 
@@ -223,12 +299,12 @@ export class McpClient {
     return normalizeToolContent(result);
   }
 
-  async gatherContextForTask(taskText) {
+  async gatherContextForTask(taskText: string): Promise<string> {
     if (!this.connections.size || !taskText.trim()) {
       return "";
     }
 
-    const contextBlocks = [];
+    const contextBlocks: string[] = [];
     const toolNameHints = [
       "search",
       "query",
@@ -249,7 +325,7 @@ export class McpClient {
           return toolNameHints.some((hint) => name.includes(hint));
         });
 
-        if (!preferredTool) continue;
+        if (!preferredTool?.name) continue;
 
         const result = await conn.client.callTool({
           name: preferredTool.name,
@@ -265,19 +341,18 @@ export class McpClient {
 
         contextBlocks.push(`[${serverName}/${preferredTool.name}]\n${text}`);
       } catch (error) {
-        contextBlocks.push(
-          `[${serverName}] MCP query failed: ${error.message}`
-        );
+        const message = error instanceof Error ? error.message : String(error);
+        contextBlocks.push(`[${serverName}] MCP query failed: ${message}`);
       }
     }
 
     return contextBlocks.join("\n\n");
   }
 
-  async closeAll() {
+  async closeAll(): Promise<void> {
     for (const { transport } of this.connections.values()) {
       try {
-        await transport.close();
+        await transport.close?.();
       } catch {
         // Ignore close errors on shutdown.
       }