@ericsanchezok/meta-synergy 0.0.0-dev-202603260728

package/src/host.ts

@@ -0,0 +1,39 @@
+import { MetaProtocolEnv, MetaProtocolHost } from "@ericsanchezok/meta-protocol"
+import { Platform } from "./platform"
+
+export interface MetaSynergyHostOptions {
+  envID?: MetaProtocolEnv.EnvID
+  hostSessionID?: MetaProtocolEnv.HostSessionID
+  capabilities?: MetaProtocolHost.Capabilities
+}
+
+export class MetaSynergyHost {
+  readonly envID?: MetaProtocolEnv.EnvID
+  readonly hostSessionID: MetaProtocolEnv.HostSessionID
+  readonly capabilities: MetaProtocolHost.Capabilities
+
+  constructor(options: MetaSynergyHostOptions = {}) {
+    this.envID = options.envID
+    this.hostSessionID = options.hostSessionID || crypto.randomUUID()
+    this.capabilities = options.capabilities || Platform.detectCapabilities()
+  }
+
+  hello() {
+    if (!this.envID) {
+      throw new Error("MetaSynergyHost requires envID to emit host.hello")
+    }
+
+    return {
+      type: "host.hello" as const,
+      envID: this.envID,
+      hostSessionID: this.hostSessionID,
+      capabilities: this.capabilities,
+    }
+  }
+
+  assertEnv(envID: string) {
+    if (this.envID && envID !== this.envID) {
+      throw new Error(`env mismatch: host bound to ${this.envID}, received ${envID}`)
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./types"
+export * from "./host"
+export * from "./platform"
+export * from "./client/holos-client"
+export * from "./rpc/schema"
+export * from "./rpc/handler"
+export * from "./exec/bash-runner"
+export * from "./exec/process-registry"

package/src/platform.ts

@@ -0,0 +1,227 @@
+import os from "node:os"
+import path from "node:path"
+import process from "node:process"
+import { spawn } from "node:child_process"
+import { MetaProtocolHost } from "@ericsanchezok/meta-protocol"
+
+const SIGKILL_TIMEOUT_MS = 200
+const ESC = "\u001b"
+
+export type ProcessEnv = Record<string, string | undefined>
+export type ChildLike = { pid?: number; kill(signal?: number | NodeJS.Signals): boolean }
+
+export namespace Platform {
+  export function runtime(): MetaProtocolHost.Runtime {
+    if (typeof process.versions?.bun === "string") return "bun"
+    if (typeof process.versions?.node === "string") return "node"
+    return "unknown"
+  }
+
+  export function defaultShell(): MetaProtocolHost.Shell {
+    if (process.platform === "win32") {
+      const comspec = (process.env.ComSpec || process.env.COMSPEC || "").toLowerCase()
+      if (comspec.includes("pwsh")) return "pwsh"
+      if (comspec.includes("powershell")) return "powershell"
+      return "cmd"
+    }
+    return "sh"
+  }
+
+  export function supportedShells(): MetaProtocolHost.Shell[] {
+    return process.platform === "win32" ? ["cmd", "powershell", "pwsh"] : ["sh"]
+  }
+
+  export function detectCapabilities(): MetaProtocolHost.Capabilities {
+    return {
+      platform: process.platform,
+      arch: process.arch,
+      hostname: safeHostname(),
+      runtime: runtime(),
+      defaultShell: defaultShell(),
+      supportedShells: supportedShells(),
+      supportsPty: false,
+      supportsSendKeys: true,
+      supportsSoftKill: process.platform !== "win32",
+      supportsProcessGroups: process.platform !== "win32",
+      envCaseInsensitive: process.platform === "win32",
+      lineEndings: process.platform === "win32" ? "crlf" : "lf",
+    }
+  }
+
+  export function normalizeEnv(env: ProcessEnv): ProcessEnv {
+    if (process.platform !== "win32") {
+      return { ...env }
+    }
+
+    const result: ProcessEnv = {}
+    const entries = Object.entries(env).sort(([left], [right]) => left.localeCompare(right))
+    const seen = new Set<string>()
+    for (const [key, value] of entries) {
+      const upper = key.toUpperCase()
+      if (seen.has(upper) && key !== "Path") continue
+      seen.add(upper)
+      result[key === "PATH" ? "Path" : key] = value
+    }
+    return result
+  }
+
+  export function resolveShellLaunch(command: string): { shell: MetaProtocolHost.Shell; file: string; args: string[] } {
+    if (process.platform === "win32") {
+      return {
+        shell: "cmd",
+        file: process.env.ComSpec || process.env.COMSPEC || "cmd.exe",
+        args: ["/d", "/s", "/c", command],
+      }
+    }
+
+    return {
+      shell: "sh",
+      file: "/bin/sh",
+      args: ["-c", command],
+    }
+  }
+
+  export async function killTree(child: ChildLike, exited?: () => boolean): Promise<void> {
+    const pid = child.pid
+    if (!pid || exited?.()) return
+
+    if (process.platform === "win32") {
+      await new Promise<void>((resolve) => {
+        const killer = spawn("taskkill", ["/pid", String(pid), "/f", "/t"], {
+          stdio: "ignore",
+          windowsHide: true,
+        })
+        killer.once("exit", () => resolve())
+        killer.once("error", () => resolve())
+      })
+      return
+    }
+
+    try {
+      process.kill(-pid, "SIGTERM")
+      await sleep(SIGKILL_TIMEOUT_MS)
+      if (!exited?.()) process.kill(-pid, "SIGKILL")
+      return
+    } catch {}
+
+    child.kill("SIGTERM")
+    await sleep(SIGKILL_TIMEOUT_MS)
+    if (!exited?.()) child.kill("SIGKILL")
+  }
+
+  export function encodeKeySequence(keys: string[]): { data: string; warnings: string[] } {
+    const warnings: string[] = []
+    let data = ""
+    for (const token of keys) {
+      data += encodeKeyToken(token, warnings)
+    }
+    return { data, warnings }
+  }
+
+  export function resolveWorkdir(workdir?: string): string {
+    if (!workdir) return process.cwd()
+    if (path.isAbsolute(workdir)) return workdir
+    return path.resolve(process.cwd(), workdir)
+  }
+
+  export function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}
+
+function encodeKeyToken(raw: string, warnings: string[]): string {
+  const token = raw.trim()
+  if (!token) return ""
+  if (token.length === 2 && token.startsWith("^")) {
+    const ctrl = toCtrlChar(token[1])
+    if (ctrl) return ctrl
+  }
+
+  const parsed = parseModifiers(token)
+  const named = namedKey(parsed.base.toLowerCase())
+  if (named) {
+    return parsed.alt ? `${ESC}${named}` : named
+  }
+
+  if (parsed.base.length === 1) {
+    let value = parsed.shift && /[a-z]/.test(parsed.base) ? parsed.base.toUpperCase() : parsed.base
+    if (parsed.ctrl) value = toCtrlChar(value) || value
+    if (parsed.alt) value = `${ESC}${value}`
+    return value
+  }
+
+  if (parsed.hasModifiers) {
+    warnings.push(`Unknown key \"${parsed.base}\" for modifiers; sending literal.`)
+  }
+  return parsed.base
+}
+
+function parseModifiers(token: string) {
+  let rest = token
+  let ctrl = false
+  let alt = false
+  let shift = false
+  let hasModifiers = false
+
+  while (rest.length > 2 && rest[1] === "-") {
+    const mod = rest[0].toLowerCase()
+    if (mod === "c") ctrl = true
+    else if (mod === "m") alt = true
+    else if (mod === "s") shift = true
+    else break
+    hasModifiers = true
+    rest = rest.slice(2)
+  }
+
+  return { base: rest, ctrl, alt, shift, hasModifiers }
+}
+
+function namedKey(input: string): string | undefined {
+  const map = new Map<string, string>([
+    ["enter", "\r"],
+    ["return", "\r"],
+    ["tab", "\t"],
+    ["escape", ESC],
+    ["esc", ESC],
+    ["space", " "],
+    ["backspace", process.platform === "win32" ? "\b" : "\u007f"],
+    ["up", `${ESC}[A`],
+    ["down", `${ESC}[B`],
+    ["right", `${ESC}[C`],
+    ["left", `${ESC}[D`],
+    ["home", `${ESC}[1~`],
+    ["end", `${ESC}[4~`],
+    ["pageup", `${ESC}[5~`],
+    ["pagedown", `${ESC}[6~`],
+    ["insert", `${ESC}[2~`],
+    ["delete", `${ESC}[3~`],
+    ["f1", `${ESC}OP`],
+    ["f2", `${ESC}OQ`],
+    ["f3", `${ESC}OR`],
+    ["f4", `${ESC}OS`],
+    ["f5", `${ESC}[15~`],
+    ["f6", `${ESC}[17~`],
+    ["f7", `${ESC}[18~`],
+    ["f8", `${ESC}[19~`],
+    ["f9", `${ESC}[20~`],
+    ["f10", `${ESC}[21~`],
+    ["f11", `${ESC}[23~`],
+    ["f12", `${ESC}[24~`],
+  ])
+  return map.get(input)
+}
+
+function toCtrlChar(char: string): string | null {
+  if (char.length !== 1) return null
+  if (char === "?") return "\u007f"
+  const code = char.toUpperCase().charCodeAt(0)
+  return code >= 64 && code <= 95 ? String.fromCharCode(code & 0x1f) : null
+}
+
+function safeHostname(): string | undefined {
+  try {
+    return os.hostname()
+  } catch {
+    return undefined
+  }
+}

package/src/rpc/handler.ts

@@ -0,0 +1,76 @@
+import { MetaProtocolEnvelope, MetaProtocolError } from "@ericsanchezok/meta-protocol"
+import { ProcessRegistry } from "../exec/process-registry"
+import { MetaSynergyHost, type MetaSynergyHostOptions } from "../host"
+import { BashRunner } from "../exec/bash-runner"
+import { RPCRequestSchema } from "./schema"
+
+export class RPCHandler {
+  readonly host: MetaSynergyHost
+  readonly processRegistry: ProcessRegistry
+  readonly bashRunner: BashRunner
+
+  constructor(options: MetaSynergyHostOptions = {}) {
+    this.host = new MetaSynergyHost(options)
+    this.processRegistry = new ProcessRegistry(this.host)
+    this.bashRunner = new BashRunner(this.processRegistry)
+  }
+
+  async handle(input: unknown) {
+    try {
+      const request = RPCRequestSchema.parse(input)
+      this.host.assertEnv(request.envID)
+
+      if (request.tool === "bash") {
+        const result = await this.bashRunner.run(request.payload, request.envID)
+        return {
+          version: 1,
+          requestID: request.requestID,
+          ok: true,
+          result,
+        } as const
+      }
+
+      if (request.tool === "process") {
+        const result = await this.processRegistry.execute(request.payload, request.envID)
+        return {
+          version: 1,
+          requestID: request.requestID,
+          ok: true,
+          result,
+        } as const
+      }
+
+      return errorResult(undefined, "unsupported_tool", "Unsupported tool")
+    } catch (error) {
+      if (isEnvelopeError(error)) {
+        return errorResult(error.requestID, error.code, error.message, error.details)
+      }
+
+      return errorResult(undefined, "host_internal_error", error instanceof Error ? error.message : String(error))
+    }
+  }
+}
+
+function errorResult(
+  requestID: string | undefined,
+  code: MetaProtocolError.Code,
+  message: string,
+  details?: unknown,
+): MetaProtocolEnvelope.ErrorResult {
+  return {
+    version: 1,
+    requestID: requestID || crypto.randomUUID(),
+    ok: false,
+    error: {
+      code,
+      message,
+      details,
+    },
+  }
+}
+
+function isEnvelopeError(
+  error: unknown,
+): error is { requestID?: string; code: MetaProtocolError.Code; message: string; details?: unknown } {
+  return typeof error === "object" && error !== null && "code" in error && "message" in error
+}

package/src/rpc/schema.ts

@@ -0,0 +1,16 @@
+import z from "zod"
+import { MetaProtocolBash, MetaProtocolEnvelope, MetaProtocolProcess } from "@ericsanchezok/meta-protocol"
+
+export const RPCRequestSchema = z.discriminatedUnion("tool", [
+  MetaProtocolBash.ExecuteRequest,
+  MetaProtocolProcess.ExecuteRequest,
+])
+
+export const RPCResultSchema = z.discriminatedUnion("ok", [
+  MetaProtocolBash.ExecuteResult,
+  MetaProtocolProcess.ExecuteResult,
+  MetaProtocolEnvelope.ErrorResult,
+])
+
+export type RPCRequest = z.infer<typeof RPCRequestSchema>
+export type RPCResult = z.infer<typeof RPCResultSchema>

package/src/types.ts

@@ -0,0 +1,17 @@
+import type { MetaProtocolEnv, MetaProtocolHost } from "@ericsanchezok/meta-protocol"
+
+export type EnvID = MetaProtocolEnv.EnvID
+export type RequestID = string
+
+export interface RemoteHostIdentity {
+  envID: EnvID
+  hostSessionID: MetaProtocolEnv.HostSessionID
+  capabilities: MetaProtocolHost.Capabilities
+  label?: string
+}
+
+export interface HostTransport {
+  connect(): Promise<void>
+  disconnect(): Promise<void>
+  send(message: unknown): Promise<void>
+}

package/test/rpc-handler.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test"
+import { RPCHandler } from "../src/rpc/handler"
+
+describe("meta-synergy rpc handler", () => {
+  test("bash background execution returns process id", async () => {
+    const handler = new RPCHandler({ envID: "env_test" })
+    const result = await handler.handle({
+      version: 1,
+      requestID: "req_1",
+      envID: "env_test",
+      tool: "bash",
+      action: "execute",
+      payload: {
+        command: "echo hello && sleep 1",
+        description: "background test",
+        background: true,
+      },
+    })
+
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const metadata = result.result.metadata as { processId?: string; background?: boolean }
+    expect(metadata.processId).toBeTruthy()
+    expect(metadata.background).toBe(true)
+  })
+
+  test("process list includes backgrounded process", async () => {
+    const handler = new RPCHandler({ envID: "env_test" })
+    const started = await handler.handle({
+      version: 1,
+      requestID: "req_2",
+      envID: "env_test",
+      tool: "bash",
+      action: "execute",
+      payload: {
+        command: "echo hello && sleep 1",
+        description: "background test",
+        background: true,
+      },
+    })
+
+    expect(started.ok).toBe(true)
+    if (!started.ok) return
+
+    const listed = await handler.handle({
+      version: 1,
+      requestID: "req_3",
+      envID: "env_test",
+      tool: "process",
+      action: "list",
+      payload: { action: "list" },
+    })
+
+    expect(listed.ok).toBe(true)
+    if (!listed.ok) return
+    const startedMetadata = started.result.metadata as { processId?: string }
+    const listedMetadata = listed.result.metadata as { processes?: Array<{ processId: string }> }
+    expect(listedMetadata.processes?.some((item) => item.processId === startedMetadata.processId)).toBe(true)
+  })
+
+  test("env mismatch returns error envelope", async () => {
+    const handler = new RPCHandler({ envID: "env_bound" })
+    const result = await handler.handle({
+      version: 1,
+      requestID: "req_4",
+      envID: "env_other",
+      tool: "process",
+      action: "list",
+      payload: { action: "list" },
+    })
+
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.error.code).toBe("host_internal_error")
+  })
+})

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig.json",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext", "DOM"],
+    "types": ["node"],
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "outDir": "dist",
+    "declaration": true,
+    "noEmit": false,
+    "strict": true,
+    "isolatedModules": true,
+    "baseUrl": ".",
+    "paths": {
+      "@ericsanchezok/meta-protocol": ["../meta-protocol/src/index.ts"]
+    }
+  },
+  "include": ["src"]
+}