@tyvm/knowhow-module-terminal 0.0.1

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@tyvm/knowhow-module-terminal",
+  "version": "0.0.1",
+  "description": "Terminal addon module for @tyvm/knowhow — portless PTY over the tunnel WebSocket",
+  "main": "ts_build/index.js",
+  "types": "ts_build/index.d.ts",
+  "scripts": {
+    "compile": "tsc",
+    "prepublishOnly": "npm run compile"
+  },
+  "keywords": [
+    "knowhow",
+    "terminal",
+    "pty",
+    "tunnel"
+  ],
+  "author": "Tyvm AI",
+  "license": "MIT",
+  "peerDependencies": {
+    "@tyvm/knowhow": "*"
+  },
+  "dependencies": {
+    "@tyvm/knowhow-tunnel": "*",
+    "node-pty": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.39",
+    "typescript": "^5.0.0"
+  }
+}

package/src/TunnelTerminalAddon.ts

@@ -0,0 +1,143 @@
+import {
+  TunnelAddon,
+  TunnelAddonContext,
+  AnyTunnelMessage,
+  TunnelMessageType,
+  TunnelPtyOpen,
+  TunnelPtyData,
+  TunnelPtyResize,
+  TunnelPtyClose,
+} from "@tyvm/knowhow-tunnel";
+import * as pty from "node-pty";
+
+interface PtySession {
+  pty: pty.IPty;
+  streamId: string;
+}
+
+/**
+ * TunnelTerminalAddon
+ *
+ * Handles TUNNEL_PTY_* messages over the existing tunnel WebSocket.
+ * No local port is opened — all communication flows through the tunnel.
+ *
+ * Message flow:
+ *   backend → worker  TUNNEL_PTY_OPEN    → spawn PTY
+ *   worker  → backend TUNNEL_PTY_DATA    → PTY stdout/stderr output
+ *   backend → worker  TUNNEL_PTY_DATA    → keyboard input
+ *   backend → worker  TUNNEL_PTY_RESIZE  → resize PTY window
+ *   backend → worker  TUNNEL_PTY_CLOSE   → kill PTY
+ *   worker  → backend TUNNEL_PTY_EXIT    → PTY process exited
+ */
+export class TunnelTerminalAddon implements TunnelAddon {
+  name = "terminal";
+
+  // Handle all TUNNEL_PTY_* messages via prefix matching
+  handles = ["TUNNEL_PTY_"];
+
+  private sessions = new Map<string, PtySession>();
+
+  onDisconnect(): void {
+    // Kill all active PTY sessions when the tunnel disconnects
+    for (const [streamId, session] of this.sessions) {
+      try {
+        session.pty.kill();
+      } catch {
+        // ignore
+      }
+      this.sessions.delete(streamId);
+    }
+  }
+
+  async onMessage(message: AnyTunnelMessage, ctx: TunnelAddonContext): Promise<void> {
+    switch (message.type) {
+      case TunnelMessageType.PTY_OPEN:
+        this.handleOpen(message as TunnelPtyOpen, ctx);
+        break;
+      case TunnelMessageType.PTY_DATA:
+        this.handleInput(message as TunnelPtyData);
+        break;
+      case TunnelMessageType.PTY_RESIZE:
+        this.handleResize(message as TunnelPtyResize);
+        break;
+      case TunnelMessageType.PTY_CLOSE:
+        this.handleClose(message as TunnelPtyClose, ctx);
+        break;
+    }
+  }
+
+  private handleOpen(msg: TunnelPtyOpen, ctx: TunnelAddonContext): void {
+    const { streamId, command, args = [], cols = 80, rows = 24, env = {} } = msg;
+
+    if (this.sessions.has(streamId)) {
+      console.warn(`[terminal] PTY session already exists for streamId=${streamId}`);
+      return;
+    }
+
+    console.log(`[terminal] Spawning PTY streamId=${streamId} cmd=${command} ${args.join(" ")}`);
+
+    const shell = pty.spawn(command, args, {
+      name: "xterm-256color",
+      cols,
+      rows,
+      cwd: process.env.HOME || process.cwd(),
+      env: {
+        ...process.env,
+        ...env,
+        TERM: "xterm-256color",
+        COLORTERM: "truecolor",
+      } as Record<string, string>,
+    });
+
+    const session: PtySession = { pty: shell, streamId };
+    this.sessions.set(streamId, session);
+
+    // Forward PTY output back through the tunnel
+    shell.onData((data: string) => {
+      ctx.send({
+        type: TunnelMessageType.PTY_DATA,
+        streamId,
+        data: Buffer.from(data).toString("base64"),
+      });
+    });
+
+    shell.onExit(({ exitCode }) => {
+      console.log(`[terminal] PTY exited streamId=${streamId} code=${exitCode}`);
+      this.sessions.delete(streamId);
+      ctx.send({
+        type: TunnelMessageType.PTY_EXIT,
+        streamId,
+        exitCode,
+      });
+    });
+  }
+
+  private handleInput(msg: TunnelPtyData): void {
+    const session = this.sessions.get(msg.streamId);
+    if (!session) return;
+    const text = Buffer.from(msg.data, "base64").toString("utf8");
+    session.pty.write(text);
+  }
+
+  private handleResize(msg: TunnelPtyResize): void {
+    const session = this.sessions.get(msg.streamId);
+    if (!session) return;
+    session.pty.resize(msg.cols, msg.rows);
+  }
+
+  private handleClose(msg: TunnelPtyClose, ctx: TunnelAddonContext): void {
+    const session = this.sessions.get(msg.streamId);
+    if (!session) return;
+    try {
+      session.pty.kill();
+    } catch {
+      // ignore
+    }
+    this.sessions.delete(msg.streamId);
+    ctx.send({
+      type: TunnelMessageType.PTY_EXIT,
+      streamId: msg.streamId,
+      exitCode: 0,
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import { KnowhowModule, InitParams } from "@tyvm/knowhow/ts_build/src/services/modules/types";
+import { TunnelTerminalAddon } from "./TunnelTerminalAddon";
+
+export { TunnelTerminalAddon } from "./TunnelTerminalAddon";
+
+const terminalModule: KnowhowModule = {
+  async init(params: InitParams) {
+    const tunnelHandler = params.context?.Tunnel;
+    if (tunnelHandler) {
+      tunnelHandler.use(new TunnelTerminalAddon());
+      console.log("✅ Terminal module: TunnelTerminalAddon registered on tunnel handler");
+    } else {
+      console.warn("⚠️  Terminal module: no TunnelHandler in context — terminal addon not registered");
+    }
+  },
+  tools: [],
+  agents: [],
+  plugins: [],
+  clients: [],
+  commands: [],
+};
+
+export default terminalModule;

package/ts_build/TunnelTerminalAddon.d.ts

@@ -0,0 +1,12 @@
+import { TunnelAddon, TunnelAddonContext, AnyTunnelMessage } from "@tyvm/knowhow-tunnel";
+export declare class TunnelTerminalAddon implements TunnelAddon {
+    name: string;
+    handles: string[];
+    private sessions;
+    onDisconnect(): void;
+    onMessage(message: AnyTunnelMessage, ctx: TunnelAddonContext): Promise<void>;
+    private handleOpen;
+    private handleInput;
+    private handleResize;
+    private handleClose;
+}

package/ts_build/TunnelTerminalAddon.js

@@ -0,0 +1,138 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TunnelTerminalAddon = void 0;
+const knowhow_tunnel_1 = require("@tyvm/knowhow-tunnel");
+const pty = __importStar(require("node-pty"));
+class TunnelTerminalAddon {
+    name = "terminal";
+    handles = ["TUNNEL_PTY_"];
+    sessions = new Map();
+    onDisconnect() {
+        for (const [streamId, session] of this.sessions) {
+            try {
+                session.pty.kill();
+            }
+            catch {
+            }
+            this.sessions.delete(streamId);
+        }
+    }
+    async onMessage(message, ctx) {
+        switch (message.type) {
+            case knowhow_tunnel_1.TunnelMessageType.PTY_OPEN:
+                this.handleOpen(message, ctx);
+                break;
+            case knowhow_tunnel_1.TunnelMessageType.PTY_DATA:
+                this.handleInput(message);
+                break;
+            case knowhow_tunnel_1.TunnelMessageType.PTY_RESIZE:
+                this.handleResize(message);
+                break;
+            case knowhow_tunnel_1.TunnelMessageType.PTY_CLOSE:
+                this.handleClose(message, ctx);
+                break;
+        }
+    }
+    handleOpen(msg, ctx) {
+        const { streamId, command, args = [], cols = 80, rows = 24, env = {} } = msg;
+        if (this.sessions.has(streamId)) {
+            console.warn(`[terminal] PTY session already exists for streamId=${streamId}`);
+            return;
+        }
+        console.log(`[terminal] Spawning PTY streamId=${streamId} cmd=${command} ${args.join(" ")}`);
+        const shell = pty.spawn(command, args, {
+            name: "xterm-256color",
+            cols,
+            rows,
+            cwd: process.env.HOME || process.cwd(),
+            env: {
+                ...process.env,
+                ...env,
+                TERM: "xterm-256color",
+                COLORTERM: "truecolor",
+            },
+        });
+        const session = { pty: shell, streamId };
+        this.sessions.set(streamId, session);
+        shell.onData((data) => {
+            ctx.send({
+                type: knowhow_tunnel_1.TunnelMessageType.PTY_DATA,
+                streamId,
+                data: Buffer.from(data).toString("base64"),
+            });
+        });
+        shell.onExit(({ exitCode }) => {
+            console.log(`[terminal] PTY exited streamId=${streamId} code=${exitCode}`);
+            this.sessions.delete(streamId);
+            ctx.send({
+                type: knowhow_tunnel_1.TunnelMessageType.PTY_EXIT,
+                streamId,
+                exitCode,
+            });
+        });
+    }
+    handleInput(msg) {
+        const session = this.sessions.get(msg.streamId);
+        if (!session)
+            return;
+        const text = Buffer.from(msg.data, "base64").toString("utf8");
+        session.pty.write(text);
+    }
+    handleResize(msg) {
+        const session = this.sessions.get(msg.streamId);
+        if (!session)
+            return;
+        session.pty.resize(msg.cols, msg.rows);
+    }
+    handleClose(msg, ctx) {
+        const session = this.sessions.get(msg.streamId);
+        if (!session)
+            return;
+        try {
+            session.pty.kill();
+        }
+        catch {
+        }
+        this.sessions.delete(msg.streamId);
+        ctx.send({
+            type: knowhow_tunnel_1.TunnelMessageType.PTY_EXIT,
+            streamId: msg.streamId,
+            exitCode: 0,
+        });
+    }
+}
+exports.TunnelTerminalAddon = TunnelTerminalAddon;
+//# sourceMappingURL=TunnelTerminalAddon.js.map

package/ts_build/TunnelTerminalAddon.js.map

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

package/ts_build/index.d.ts

@@ -0,0 +1,4 @@
+import { KnowhowModule } from "@tyvm/knowhow/ts_build/src/services/modules/types";
+export { TunnelTerminalAddon } from "./TunnelTerminalAddon";
+declare const terminalModule: KnowhowModule;
+export default terminalModule;

package/ts_build/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TunnelTerminalAddon = void 0;
+const TunnelTerminalAddon_1 = require("./TunnelTerminalAddon");
+var TunnelTerminalAddon_2 = require("./TunnelTerminalAddon");
+Object.defineProperty(exports, "TunnelTerminalAddon", { enumerable: true, get: function () { return TunnelTerminalAddon_2.TunnelTerminalAddon; } });
+const terminalModule = {
+    async init(params) {
+        const tunnelHandler = params.context?.Tunnel;
+        if (tunnelHandler) {
+            tunnelHandler.use(new TunnelTerminalAddon_1.TunnelTerminalAddon());
+            console.log("✅ Terminal module: TunnelTerminalAddon registered on tunnel handler");
+        }
+        else {
+            console.warn("⚠️  Terminal module: no TunnelHandler in context — terminal addon not registered");
+        }
+    },
+    tools: [],
+    agents: [],
+    plugins: [],
+    clients: [],
+    commands: [],
+};
+exports.default = terminalModule;
+//# sourceMappingURL=index.js.map

package/ts_build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AACA,+DAA4D;AAE5D,6DAA4D;AAAnD,0HAAA,mBAAmB,OAAA;AAE5B,MAAM,cAAc,GAAkB;IACpC,KAAK,CAAC,IAAI,CAAC,MAAkB;QAC3B,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC;QAC7C,IAAI,aAAa,EAAE,CAAC;YAClB,aAAa,CAAC,GAAG,CAAC,IAAI,yCAAmB,EAAE,CAAC,CAAC;YAC7C,OAAO,CAAC,GAAG,CAAC,qEAAqE,CAAC,CAAC;QACrF,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,kFAAkF,CAAC,CAAC;QACnG,CAAC;IACH,CAAC;IACD,KAAK,EAAE,EAAE;IACT,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,EAAE;IACX,QAAQ,EAAE,EAAE;CACb,CAAC;AAEF,kBAAe,cAAc,CAAC"}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "lib": ["es5", "es6", "es2021", "es2022"],
+    "skipLibCheck": true,
+    "noImplicitAny": false,
+    "removeComments": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "target": "esnext",
+    "outDir": "ts_build",
+    "sourceMap": true
+  },
+  "include": ["./src/**/*.ts", "./tests/**/*.ts"],
+  "exclude": ["node_modules", "tests/tree-sitter/test-files/**/*.ts", "tests/test-files/**/*.ts"]
+}