@ericsanchezok/meta-synergy 1.1.6 → 1.1.8

package/package.json

@@ -1,9 +1,12 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@ericsanchezok/meta-synergy",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "type": "module",
   "license": "MIT",
+  "bin": {
+    "meta-synergy": "./src/cli.ts"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",

package/src/cli.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env bun
+import { spawn } from "node:child_process"
+import { MetaSynergyRuntime } from "./runtime"
+
+async function main() {
+  const command = process.argv[2] ?? "start"
+  const runtime = await MetaSynergyRuntime.create()
+
+  switch (command) {
+    case "start":
+      await runtime.start()
+      return
+    case "login": {
+      const result = await runtime.login()
+      console.log(`Logged in as ${result.agentID}`)
+      return
+    }
+    case "status": {
+      const status = await runtime.status()
+      console.log(JSON.stringify(status, null, 2))
+      return
+    }
+    case "logout":
+      await runtime.logout()
+      console.log("Logged out from Holos.")
+      return
+    case "enable":
+      await runtime.setCollaborationEnabled(true)
+      console.log("Collaboration enabled.")
+      return
+    case "disable":
+      await runtime.setCollaborationEnabled(false)
+      console.log("Collaboration disabled.")
+      return
+    case "kick": {
+      await runtime.requestKick(false)
+      console.log("Requested current collaboration session to close.")
+      return
+    }
+    case "block": {
+      await runtime.requestKick(true)
+      console.log("Requested current collaboration session to close and block the collaborator.")
+      return
+    }
+    case "reconnect":
+      await runtime.requestReconnect()
+      console.log("Requested Holos reconnect.")
+      return
+    case "menu":
+      await new Promise<void>((resolve, reject) => {
+        const child = spawn("swift", ["src/menu.swift"], { stdio: "inherit" })
+        child.once("exit", (code) => {
+          if ((code ?? 0) === 0) resolve()
+          else reject(new Error(`Menu exited with code ${code ?? 0}`))
+        })
+        child.once("error", reject)
+      })
+      return
+    default:
+      console.error(`Unknown command: ${command}`)
+      console.error("Usage: bun meta-synergy [start|login|status|logout|enable|disable|kick|block|reconnect|menu]")
+      process.exit(1)
+  }
+}
+
+await main()

package/src/holos/client.ts

@@ -0,0 +1,146 @@
+import { MetaProtocolBridge } from "@ericsanchezok/meta-protocol"
+import type { RPCResult } from "../rpc/schema"
+import { MetaSynergyHolosEnvelope } from "./envelope"
+import { MetaSynergyHolosProtocol } from "./protocol"
+import type { MetaSynergyInboundHandler } from "../inbound/handler"
+import { MetaSynergyLog } from "../log"
+
+const HOLOS_HOST = "www.holosai.io"
+const HOLOS_URL = `https://${HOLOS_HOST}`
+const HOLOS_WS_URL = `wss://${HOLOS_HOST}`
+
+export class MetaSynergyHolosClient {
+  #ws: WebSocket | null = null
+  #heartbeat: ReturnType<typeof setInterval> | null = null
+
+  constructor(
+    readonly auth: { agentID: string; agentSecret: string },
+    readonly inbound: MetaSynergyInboundHandler,
+  ) {}
+
+  async connect() {
+    const token = await fetchWsToken(this.auth.agentSecret)
+    const endpoint = `${HOLOS_WS_URL}/api/v1/holos/agent_tunnel/ws?token=${token}`
+    MetaSynergyLog.info("holos.connect.begin", {
+      agentID: this.auth.agentID,
+      endpoint,
+    })
+    const ws = new WebSocket(endpoint)
+    this.#ws = ws
+
+    await new Promise<void>((resolve, reject) => {
+      let opened = false
+      ws.addEventListener("open", () => {
+        opened = true
+        MetaSynergyLog.info("holos.connect.open", {
+          agentID: this.auth.agentID,
+        })
+        resolve()
+      })
+      ws.addEventListener("error", (error) => {
+        MetaSynergyLog.error("holos.connect.error", {
+          agentID: this.auth.agentID,
+          error: String(error),
+        })
+        if (!opened) reject(new Error("Failed to connect to Holos websocket."))
+      })
+      ws.addEventListener("close", () => {
+        MetaSynergyLog.warn("holos.connect.closed_before_open", {
+          agentID: this.auth.agentID,
+        })
+        if (!opened) reject(new Error("Holos websocket closed before opening."))
+      })
+    })
+
+    ws.addEventListener("message", (event) => {
+      void this.#handleMessage(String(event.data))
+    })
+    ws.addEventListener("close", () => {
+      MetaSynergyLog.warn("holos.socket.closed", {
+        agentID: this.auth.agentID,
+      })
+      if (this.#heartbeat) clearInterval(this.#heartbeat)
+      this.#heartbeat = null
+      this.#ws = null
+    })
+
+    this.#heartbeat = setInterval(() => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(MetaSynergyHolosEnvelope.ping())
+      }
+    }, 60_000)
+    this.#heartbeat.unref?.()
+  }
+
+  async disconnect() {
+    MetaSynergyLog.info("holos.disconnect", {
+      agentID: this.auth.agentID,
+    })
+    if (this.#heartbeat) clearInterval(this.#heartbeat)
+    this.#heartbeat = null
+    this.#ws?.close()
+    this.#ws = null
+  }
+
+  connected() {
+    return this.#ws?.readyState === WebSocket.OPEN
+  }
+
+  async #handleMessage(raw: string) {
+    MetaSynergyLog.info("holos.message.received.raw", {
+      raw,
+    })
+    const parsed = MetaSynergyHolosEnvelope.parse(raw)
+    if (!parsed) {
+      MetaSynergyLog.warn("holos.message.ignored.unparsed")
+      return
+    }
+
+    MetaSynergyLog.info("holos.message.received.parsed", {
+      event: parsed.event,
+      callerAgentID: parsed.caller.agentID,
+      callerOwnerUserID: parsed.caller.ownerUserID,
+      payload: parsed.payload,
+    })
+
+    if (parsed.event !== MetaProtocolBridge.RequestEvent) {
+      MetaSynergyLog.info("holos.message.ignored.non_request_event", {
+        event: parsed.event,
+        callerAgentID: parsed.caller.agentID,
+      })
+      return
+    }
+
+    const result = await this.inbound.handle({ caller: parsed.caller, body: parsed.payload })
+    this.#sendResult(parsed.caller.agentID, result)
+  }
+
+  #sendResult(targetAgentID: string, result: RPCResult) {
+    if (this.#ws?.readyState !== WebSocket.OPEN) {
+      MetaSynergyLog.warn("holos.response.dropped.socket_not_open", {
+        targetAgentID,
+        result,
+      })
+      return
+    }
+    MetaSynergyLog.info("holos.response.sending", {
+      targetAgentID,
+      result,
+    })
+    this.#ws.send(MetaSynergyHolosEnvelope.response(targetAgentID, result))
+  }
+}
+
+async function fetchWsToken(agentSecret: string): Promise<string> {
+  const response = await fetch(`${HOLOS_URL}/api/v1/holos/agent_tunnel/ws_token`, {
+    headers: { Authorization: `Bearer ${agentSecret}` },
+  })
+  if (!response.ok) {
+    throw new Error(`Failed to get Holos ws token: ${response.status} ${response.statusText}`)
+  }
+  const body = MetaSynergyHolosProtocol.WsTokenResponse.parse(await response.json())
+  if (body.code !== 0) {
+    throw new Error(body.message ?? "Failed to get Holos ws token.")
+  }
+  return body.data.ws_token
+}

package/src/holos/envelope.ts

@@ -0,0 +1,68 @@
+import { MetaProtocolBridge } from "@ericsanchezok/meta-protocol"
+import type { HolosCaller } from "../types"
+import { MetaSynergyHolosProtocol } from "./protocol"
+
+export namespace MetaSynergyHolosEnvelope {
+  export function parse(raw: string): { event: string; payload: unknown; caller: HolosCaller } | null {
+    let data: unknown
+    try {
+      data = JSON.parse(raw)
+    } catch {
+      return null
+    }
+
+    const parsed = MetaSynergyHolosProtocol.Envelope.safeParse(data)
+    if (!parsed.success || parsed.data.type !== "ws_send" || !parsed.data.caller) {
+      return null
+    }
+
+    return {
+      event: String(parsed.data.meta.event ?? ""),
+      payload: parsed.data.payload,
+      caller: {
+        type: parsed.data.caller.type,
+        agentID: parsed.data.caller.agent_id,
+        ownerUserID: parsed.data.caller.owner_user_id,
+        profile: parsed.data.caller.profile,
+      },
+    }
+  }
+
+  export function request(targetAgentID: string, payload: unknown, requestID = crypto.randomUUID()): string {
+    return JSON.stringify({
+      type: "ws_send",
+      request_id: requestID,
+      meta: {
+        target_agent_id: targetAgentID,
+        event: MetaProtocolBridge.RequestEvent,
+        content_type: "application/json",
+      },
+      payload,
+      caller: null,
+    })
+  }
+
+  export function response(targetAgentID: string, payload: unknown, requestID = crypto.randomUUID()): string {
+    return JSON.stringify({
+      type: "ws_send",
+      request_id: requestID,
+      meta: {
+        target_agent_id: targetAgentID,
+        event: MetaProtocolBridge.ResponseEvent,
+        content_type: "application/json",
+      },
+      payload,
+      caller: null,
+    })
+  }
+
+  export function ping(): string {
+    return JSON.stringify({
+      type: "ping",
+      request_id: null,
+      meta: { timestamp: Date.now() },
+      payload: null,
+      caller: null,
+    })
+  }
+}

package/src/holos/login.ts

@@ -0,0 +1,128 @@
+import process from "node:process"
+import { createServer, type IncomingMessage } from "node:http"
+import { spawn } from "node:child_process"
+import { MetaSynergyStore } from "../state/store"
+import { MetaSynergyHolosProtocol } from "./protocol"
+
+const HOLOS_HOST = "www.holosai.io"
+const HOLOS_URL = `https://${HOLOS_HOST}`
+
+export namespace MetaSynergyHolosLogin {
+  export function createBindURL(input: { callbackURL: string; state: string }) {
+    return (
+      `${HOLOS_URL}/api/v1/holos/agent_tunnel/bind/start` +
+      `?local_callback=${encodeURIComponent(input.callbackURL)}` +
+      `&state=${encodeURIComponent(input.state)}`
+    )
+  }
+
+  export async function verifySecret(agentSecret: string): Promise<{ valid: true } | { valid: false; reason: string }> {
+    const response = await fetch(`${HOLOS_URL}/api/v1/holos/agent_tunnel/ws_token`, {
+      headers: { Authorization: `Bearer ${agentSecret}` },
+    })
+    const body = MetaSynergyHolosProtocol.WsTokenResponse.safeParse(await response.json())
+    if (!body.success || !response.ok || body.data.code !== 0) {
+      return { valid: false, reason: body.success ? (body.data.message ?? "Invalid response") : "Invalid response" }
+    }
+    return { valid: true }
+  }
+
+  export async function login(): Promise<{ agentID: string }> {
+    await MetaSynergyStore.ensureRoot()
+    const state = crypto.randomUUID()
+    const port = 19836 + Math.floor(Math.random() * 1000)
+    const callbackURL = `http://127.0.0.1:${port}/holos/login`
+    const bindURL = createBindURL({ callbackURL, state })
+
+    const callback = new Promise<{ code: string; state: string }>((resolve, reject) => {
+      const server = createServer((request, response) => {
+        const params = parseRequest(request)
+        if (!params || params.pathname !== "/holos/login") {
+          response.statusCode = 404
+          response.end("Not found")
+          return
+        }
+
+        server.close()
+        if (!params.code || !params.state) {
+          reject(new Error("Missing login callback parameters."))
+          response.statusCode = 400
+          response.end("Login failed.")
+          return
+        }
+
+        resolve({ code: params.code, state: params.state })
+        response.end("Login successful. You can close this window.")
+      })
+      server.listen(port, "127.0.0.1")
+
+      const timer = setTimeout(() => {
+        server.close()
+        reject(new Error("Login timed out."))
+      }, 5 * 60_000)
+      timer.unref?.()
+    })
+
+    try {
+      await launchBrowser(bindURL)
+    } catch {
+      console.log(`Open this URL to continue login:\n${bindURL}`)
+    }
+
+    const params = await callback
+    if (params.state !== state) {
+      throw new Error("State mismatch during Holos login.")
+    }
+
+    const exchangeResponse = await fetch(`${HOLOS_URL}/api/v1/holos/agent_tunnel/bind/exchange`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        code: params.code,
+        state: params.state,
+        profile: { name: "Meta Synergy Host" },
+      }),
+    })
+    if (!exchangeResponse.ok) {
+      throw new Error(`Exchange failed: ${exchangeResponse.status} ${exchangeResponse.statusText}`)
+    }
+
+    const exchangeBody = MetaSynergyHolosProtocol.BindExchangeResponse.parse(await exchangeResponse.json())
+    if (exchangeBody.code !== 0) {
+      throw new Error(exchangeBody.message ?? exchangeBody.msg ?? "Holos exchange failed.")
+    }
+
+    const agentSecret = exchangeBody.data.agent_secret ?? exchangeBody.data.secret
+    if (!agentSecret) {
+      throw new Error("Holos exchange did not return an agent secret.")
+    }
+
+    await MetaSynergyStore.saveAuth({
+      agentID: exchangeBody.data.agent_id,
+      agentSecret,
+    })
+
+    return { agentID: exchangeBody.data.agent_id }
+  }
+}
+
+function parseRequest(request: IncomingMessage) {
+  if (!request.url) return
+  const url = new URL(request.url, "http://127.0.0.1")
+  return {
+    pathname: url.pathname,
+    code: url.searchParams.get("code") ?? undefined,
+    state: url.searchParams.get("state") ?? undefined,
+  }
+}
+
+async function launchBrowser(url: string): Promise<void> {
+  const command =
+    process.platform === "darwin"
+      ? ["open", url]
+      : process.platform === "win32"
+        ? ["cmd", "/c", "start", "", url]
+        : ["xdg-open", url]
+  const child = spawn(command[0], command.slice(1), { stdio: "ignore", detached: true })
+  child.unref()
+}

package/src/holos/protocol.ts

@@ -0,0 +1,38 @@
+import z from "zod"
+
+export namespace MetaSynergyHolosProtocol {
+  export const Caller = z.object({
+    type: z.string(),
+    agent_id: z.string(),
+    owner_user_id: z.number(),
+    profile: z.record(z.string(), z.unknown()).optional(),
+  })
+
+  export const Envelope = z.object({
+    type: z.string(),
+    request_id: z.string().nullable(),
+    meta: z.record(z.string(), z.unknown()),
+    payload: z.unknown().nullable(),
+    caller: Caller.nullable().optional(),
+  })
+
+  export const WsTokenResponse = z.object({
+    code: z.number(),
+    message: z.string().optional(),
+    data: z.object({
+      ws_token: z.string(),
+      expires_in: z.number(),
+    }),
+  })
+
+  export const BindExchangeResponse = z.object({
+    code: z.number(),
+    msg: z.string().optional(),
+    message: z.string().optional(),
+    data: z.object({
+      agent_id: z.string(),
+      agent_secret: z.string().optional(),
+      secret: z.string().optional(),
+    }),
+  })
+}

package/src/inbound/handler.ts

@@ -0,0 +1,200 @@
+import {
+  MetaProtocolBash,
+  MetaProtocolEnvelope,
+  MetaProtocolError,
+  MetaProtocolProcess,
+  MetaProtocolSession,
+} from "@ericsanchezok/meta-protocol"
+import type { HolosCaller } from "../types"
+import { RPCHandler } from "../rpc/handler"
+import { RPCRequestSchema, type RPCResult } from "../rpc/schema"
+import { SessionManager } from "../session/manager"
+import { MetaSynergyLog } from "../log"
+
+export class MetaSynergyInboundHandler {
+  constructor(
+    readonly rpc: RPCHandler,
+    readonly sessions: SessionManager,
+    readonly collaborationEnabled: () => boolean,
+    readonly confirmOpen?: (input: { caller: HolosCaller; label?: string }) => Promise<boolean>,
+  ) {}
+
+  async handle(input: { caller: HolosCaller; body: unknown }): Promise<RPCResult> {
+    try {
+      const request = RPCRequestSchema.parse(input.body)
+      MetaSynergyLog.info("inbound.request.accepted", {
+        callerAgentID: input.caller.agentID,
+        callerOwnerUserID: input.caller.ownerUserID,
+        tool: request.tool,
+        action: request.action,
+        requestID: request.requestID,
+        envID: request.envID,
+        sessionID: "sessionID" in request ? request.sessionID : undefined,
+        payload: request.payload,
+      })
+
+      if (request.tool === "session") {
+        return this.#handleSession(input.caller, request)
+      }
+
+      if (!this.collaborationEnabled()) {
+        MetaSynergyLog.warn("inbound.request.refused.collaboration_disabled", {
+          callerAgentID: input.caller.agentID,
+          tool: request.tool,
+          action: request.action,
+          requestID: request.requestID,
+        })
+        return errorResult(
+          { requestID: request.requestID, tool: request.tool, action: request.action },
+          "session_refused",
+          "Collaboration is currently disabled.",
+        )
+      }
+
+      this.sessions.validateCaller(input.caller, request.sessionID)
+      const result = await this.rpc.handle(request)
+      MetaSynergyLog.info("inbound.request.completed", {
+        callerAgentID: input.caller.agentID,
+        tool: request.tool,
+        action: request.action,
+        requestID: request.requestID,
+        result,
+      })
+      return result
+    } catch (error) {
+      if (isEnvelopeError(error)) {
+        MetaSynergyLog.warn("inbound.request.failed.envelope", {
+          callerAgentID: input.caller.agentID,
+          code: error.code,
+          message: error.message,
+          details: error.details,
+        })
+        return errorResult(
+          {
+            requestID: error.requestID,
+            tool: error.tool,
+            action: error.action,
+          },
+          error.code,
+          error.message,
+          error.details,
+        )
+      }
+
+      MetaSynergyLog.error("inbound.request.failed.unexpected", {
+        callerAgentID: input.caller.agentID,
+        error: error instanceof Error ? error.message : String(error),
+      })
+      return errorResult(undefined, "host_internal_error", error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  async #handleSession(
+    caller: HolosCaller,
+    request: MetaProtocolSession.ExecuteRequest,
+  ): Promise<MetaProtocolSession.ExecuteResult | MetaProtocolEnvelope.ErrorResult> {
+    MetaSynergyLog.info("session.request.received", {
+      callerAgentID: caller.agentID,
+      callerOwnerUserID: caller.ownerUserID,
+      action: request.payload.action,
+      requestID: request.requestID,
+      payload: request.payload,
+    })
+
+    if (!this.collaborationEnabled() && request.payload.action === "open") {
+      MetaSynergyLog.warn("session.request.refused.collaboration_disabled", {
+        callerAgentID: caller.agentID,
+        requestID: request.requestID,
+      })
+      return errorResult(
+        { requestID: request.requestID, tool: request.tool, action: request.action },
+        "session_refused",
+        "Collaboration is currently disabled.",
+      )
+    }
+
+    if (request.payload.action === "open" && !this.sessions.current()) {
+      const approved = await (this.confirmOpen?.({
+        caller,
+        label: request.payload.label,
+      }) ?? Promise.resolve(true))
+      if (!approved) {
+        MetaSynergyLog.warn("session.request.refused.user_denied", {
+          callerAgentID: caller.agentID,
+          requestID: request.requestID,
+        })
+        return errorResult(
+          { requestID: request.requestID, tool: request.tool, action: request.action },
+          "session_refused",
+          "User denied this collaboration request.",
+        )
+      }
+    }
+
+    let result: MetaProtocolSession.Result
+    switch (request.payload.action) {
+      case "open":
+        result = await this.sessions.open(caller, request.payload.label)
+        break
+      case "close":
+        result = await this.sessions.close(caller, request.payload.sessionID)
+        break
+      case "heartbeat":
+        result = await this.sessions.heartbeat(caller, request.payload.sessionID)
+        break
+    }
+
+    const response = {
+      version: 1,
+      requestID: request.requestID,
+      ok: true,
+      tool: request.tool,
+      action: request.action,
+      result,
+    } as const
+
+    MetaSynergyLog.info("session.request.completed", {
+      callerAgentID: caller.agentID,
+      requestID: request.requestID,
+      action: request.payload.action,
+      status: result.metadata.status,
+      sessionID: result.metadata.sessionID,
+      result,
+    })
+
+    return response
+  }
+}
+
+function errorResult(
+  request:
+    | {
+        requestID?: string
+        tool?: MetaProtocolEnvelope.Tool
+        action?: string
+      }
+    | undefined,
+  code: MetaProtocolError.Code,
+  message: string,
+  details?: unknown,
+): MetaProtocolEnvelope.ErrorResult {
+  return {
+    version: 1,
+    requestID: request?.requestID || crypto.randomUUID(),
+    ok: false,
+    tool: request?.tool,
+    action: request?.action,
+    error: { code, message, details },
+  }
+}
+
+function isEnvelopeError(error: unknown): error is {
+  requestID?: string
+  tool?: MetaProtocolEnvelope.Tool
+  action?: string
+  code: MetaProtocolError.Code
+  message: string
+  details?: unknown
+} {
+  return typeof error === "object" && error !== null && "code" in error && "message" in error
+}

package/src/index.ts

@@ -1,7 +1,14 @@
 export * from "./types"
+export * from "./log"
 export * from "./host"
 export * from "./platform"
+export * from "./runtime"
 export * from "./client/holos-client"
+export * from "./session/manager"
+export * from "./inbound/handler"
+export * from "./holos/client"
+export * from "./holos/login"
+export * from "./state/store"
 export * from "./rpc/schema"
 export * from "./rpc/handler"
 export * from "./exec/bash-runner"