@ganglion/xacpx-channel-relay 0.1.0

package/README.md

@@ -0,0 +1,8 @@
+# @ganglion/xacpx-channel-relay
+
+Connector channel plugin: dials out from a local xacpx instance to a
+self-hosted @ganglion/xacpx-relay hub over WebSocket.
+
+Pairing: `xacpx channel add relay --url ws://<relay-host>:8788 --token <pairing-token>`.
+On first connect the pairing token is exchanged for a long-lived instance
+credential stored at `<xacpx-home>/relay/credential.json` (never in config.json).

package/dist/channel.d.ts

@@ -0,0 +1,40 @@
+import type { ChannelStartInput, CoordinatorMessageInput, MessageChannelRuntime, ScheduledChannelMessageInput } from "xacpx/plugin-api";
+import { type RelayCredential } from "./credential-store.js";
+import { type RelayClientOptions } from "./relay-client.js";
+type OrchestrationTaskRecord = Parameters<MessageChannelRuntime["notifyTaskCompletion"]>[0];
+interface CredentialStoreLike {
+    load(): RelayCredential | null;
+    save(credential: RelayCredential): void;
+    clear(): void;
+}
+interface RelayClientLike {
+    start(abortSignal: AbortSignal): void;
+    stop(): void;
+    sendEvent(type: string, payload: unknown): void;
+}
+export interface RelayChannelDeps {
+    credentialStore?: CredentialStoreLike;
+    createClient?: (options: RelayClientOptions) => RelayClientLike;
+}
+export declare class RelayChannel implements MessageChannelRuntime {
+    private readonly deps;
+    readonly id = "relay";
+    readonly nativeSessionListFormat: "table";
+    private readonly config;
+    private readonly credentials;
+    private client;
+    private unsubscribe;
+    private control;
+    constructor(options: Record<string, unknown> | undefined, deps?: RelayChannelDeps);
+    isLoggedIn(): boolean;
+    login(): Promise<string>;
+    logout(): void;
+    start(input: ChannelStartInput): Promise<void>;
+    stop(): void;
+    notifyTaskCompletion(task: OrchestrationTaskRecord): Promise<void>;
+    notifyTaskProgress(task: OrchestrationTaskRecord, text: string): Promise<void>;
+    sendCoordinatorMessage(input: CoordinatorMessageInput): Promise<void>;
+    sendScheduledMessage(input: ScheduledChannelMessageInput): Promise<void>;
+    private sendNotice;
+}
+export {};

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+export interface RelayChannelConfig {
+    url: string;
+    pairingToken?: string;
+    name?: string;
+}
+/**
+ * Normalize a relay URL input into a full ws(s):// URL.
+ *
+ * Rules:
+ * - Trim. Empty → "".
+ * - Already ws:// or wss:// (case-insensitive) → return as-is.
+ * - http:// → ws://, https:// → wss:// (map scheme, keep the rest).
+ * - No scheme → parse host[:port]:
+ *   - Explicit numeric port → ws://<host>:<port>.
+ *   - IPv4 literal, "localhost", or bracketed IPv6 → ws://<host>:8788.
+ *   - Domain name → wss://<host> (production TLS, no port appended).
+ *
+ * Note: bare unbracketed IPv6 (e.g. "::1") is not supported; use "[::1]" instead.
+ */
+export declare function normalizeRelayUrl(input: string): string;
+export declare function parseRelayChannelConfig(options: Record<string, unknown> | undefined): RelayChannelConfig;

package/dist/control-bridge.d.ts

@@ -0,0 +1,7 @@
+import { type OrchestrationTaskDto, type RelayEnvelope, type ScheduledTaskDto } from "@ganglion/xacpx-relay-protocol";
+import type { ControlService } from "xacpx/plugin-api";
+export declare function scheduledTaskToDto(record: ReturnType<ControlService["listScheduledTasks"]>[number]): ScheduledTaskDto;
+export declare function orchestrationTaskToDto(record: Awaited<ReturnType<ControlService["listOrchestrationTasks"]>>[number]): OrchestrationTaskDto;
+export type ControlBridge = (envelope: RelayEnvelope, respond: (payload: unknown) => void) => void;
+export declare function createControlBridge(control: ControlService): ControlBridge;
+export declare function subscribeControlEvents(control: ControlService, sendEvent: (type: string, payload: unknown) => void): () => void;

package/dist/credential-store.d.ts

@@ -0,0 +1,13 @@
+export interface RelayCredential {
+    instanceId: string;
+    credential: string;
+    relayUrl: string;
+}
+export declare function defaultCredentialPath(): string;
+export declare class CredentialStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    load(): RelayCredential | null;
+    save(credential: RelayCredential): void;
+    clear(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { XacpxPlugin } from "xacpx/plugin-api";
+export { RelayChannel } from "./channel.js";
+export { relayCliProvider } from "./relay-provider.js";
+declare const plugin: XacpxPlugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,799 @@
+// packages/channel-relay/src/channel.ts
+import {
+  MSG as MSG3
+} from "@ganglion/xacpx-relay-protocol";
+
+// packages/channel-relay/src/config.ts
+function normalizeRelayUrl(input) {
+  const trimmed = input.trim();
+  if (!trimmed)
+    return "";
+  if (/^wss?:\/\//i.test(trimmed))
+    return trimmed;
+  if (/^http:\/\//i.test(trimmed))
+    return "ws://" + trimmed.slice("http://".length);
+  if (/^https:\/\//i.test(trimmed))
+    return "wss://" + trimmed.slice("https://".length);
+  const s = trimmed;
+  const bracketMatch = s.match(/^\[([^\]]+)\](?::(\d+))?$/);
+  if (bracketMatch) {
+    const ipv6 = bracketMatch[1];
+    const port2 = bracketMatch[2];
+    if (port2)
+      return `ws://[${ipv6}]:${port2}`;
+    return `ws://[${ipv6}]:8788`;
+  }
+  let host = s;
+  let port;
+  const idx = s.lastIndexOf(":");
+  if (idx > 0 && /^\d+$/.test(s.slice(idx + 1))) {
+    host = s.slice(0, idx);
+    port = s.slice(idx + 1);
+  }
+  if (port) {
+    return `ws://${host}:${port}`;
+  }
+  const isIPv4 = /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
+  if (isIPv4 || host === "localhost") {
+    return `ws://${host}:8788`;
+  }
+  return `wss://${host}`;
+}
+function parseRelayChannelConfig(options) {
+  const raw = typeof options?.url === "string" ? options.url : "";
+  const url = normalizeRelayUrl(raw);
+  if (!url) {
+    throw new Error("relay channel requires options.url (a domain, IP, or IP:port / ws(s):// address)");
+  }
+  if (!url.startsWith("ws://") && !url.startsWith("wss://")) {
+    throw new Error(`relay channel options.url must resolve to ws:// or wss://, got: ${raw}`);
+  }
+  const config = { url };
+  if (typeof options?.pairingToken === "string" && options.pairingToken.trim()) {
+    config.pairingToken = options.pairingToken.trim();
+  }
+  if (typeof options?.name === "string" && options.name.trim()) {
+    config.name = options.name.trim();
+  }
+  return config;
+}
+
+// packages/channel-relay/src/credential-store.ts
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { coreHomeDir } from "xacpx/plugin-api";
+function defaultCredentialPath() {
+  return join(coreHomeDir(process.env.HOME ?? homedir()), "relay", "credential.json");
+}
+
+class CredentialStore {
+  filePath;
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  load() {
+    try {
+      const parsed = JSON.parse(readFileSync(this.filePath, "utf8"));
+      if (typeof parsed.instanceId === "string" && typeof parsed.credential === "string" && typeof parsed.relayUrl === "string") {
+        return { instanceId: parsed.instanceId, credential: parsed.credential, relayUrl: parsed.relayUrl };
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  save(credential) {
+    mkdirSync(dirname(this.filePath), { recursive: true });
+    const tmp = `${this.filePath}.tmp`;
+    writeFileSync(tmp, JSON.stringify(credential, null, 2), { encoding: "utf8", mode: 384 });
+    chmodSync(tmp, 384);
+    renameSync(tmp, this.filePath);
+  }
+  clear() {
+    rmSync(this.filePath, { force: true });
+  }
+}
+
+// packages/channel-relay/src/control-bridge.ts
+import {
+  MSG,
+  errorPayload
+} from "@ganglion/xacpx-relay-protocol";
+
+// packages/channel-relay/src/tool-presentation.ts
+var TEXT_CAP = 8000;
+var DIFF_CAP = 4000;
+function cap(s, n = TEXT_CAP) {
+  return s.length > n ? s.slice(0, n) + `
+…(truncated)` : s;
+}
+function asString(v) {
+  if (typeof v === "string")
+    return v;
+  if (typeof v === "number" || typeof v === "boolean")
+    return String(v);
+  return;
+}
+function rec(v) {
+  return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+function blocksOf(content) {
+  if (Array.isArray(content))
+    return content.filter((b) => b && typeof b === "object");
+  if (content && typeof content === "object")
+    return [content];
+  return [];
+}
+function textFromContentBlock(cb) {
+  switch (cb.type) {
+    case "text":
+      return asString(cb.text);
+    case "resource_link":
+      return asString(cb.title) ?? asString(cb.name) ?? asString(cb.uri);
+    case "resource": {
+      const r = rec(cb.resource);
+      const text = asString(r.text);
+      if (text)
+        return text;
+      const uri = asString(r.uri);
+      return uri ? `[resource] ${uri}` : undefined;
+    }
+    default:
+      return;
+  }
+}
+function textFromBlocks(blocks) {
+  const parts = [];
+  for (const b of blocks) {
+    const t = b.type === "content" ? textFromContentBlock(rec(b.content)) : textFromContentBlock(b);
+    if (t)
+      parts.push(t);
+  }
+  return parts.length ? parts.join(`
+`) : undefined;
+}
+function diffBlock(blocks) {
+  return blocks.find((b) => b.type === "diff");
+}
+function parsedCmd0(input) {
+  const pc = input.parsed_cmd;
+  if (Array.isArray(pc) && pc[0] && typeof pc[0] === "object")
+    return pc[0];
+  return;
+}
+function locationPath(event) {
+  const locs = event.locations;
+  if (Array.isArray(locs) && locs[0] && typeof locs[0] === "object") {
+    const l = locs[0];
+    return asString(l.path) ?? asString(l.file);
+  }
+  return;
+}
+function readLines(input) {
+  const { offset, limit } = input;
+  if (typeof offset === "number" && typeof limit === "number")
+    return `${offset}–${offset + limit}`;
+  if (typeof limit === "number")
+    return `first ${limit}`;
+  return;
+}
+function primitiveFields(input) {
+  const out = [];
+  for (const [label, v] of Object.entries(input)) {
+    const value = asString(v);
+    if (value !== undefined)
+      out.push({ label, value: cap(value) });
+  }
+  return out;
+}
+function toolUseEventToStepDto(event) {
+  const input = rec(event.rawInput);
+  const blocks = blocksOf(event.content);
+  const output = rec(event.rawOutput);
+  const rawOutputText = asString(event.rawOutput);
+  const pc = parsedCmd0(input);
+  const fallbackTitle = event.summary ?? event.toolName;
+  const errMsg = event.status === "error" ? asString(output.error) ?? asString(output.message) ?? textFromBlocks(blocks) ?? asString(output.output) ?? asString(output.text) ?? rawOutputText : undefined;
+  const base = {
+    toolCallId: event.toolCallId,
+    toolName: event.toolName,
+    kind: event.kind,
+    status: event.status,
+    ...event.durationMs !== undefined ? { durationMs: event.durationMs } : {},
+    ...errMsg ? { error: cap(errMsg, 2000) } : {}
+  };
+  if (event.kind === "edit") {
+    const diff = diffBlock(blocks);
+    if (diff) {
+      const path2 = asString(diff.path) ?? locationPath(event) ?? asString(input.file_path) ?? asString(input.path) ?? fallbackTitle;
+      const detail = { type: "diff", path: path2, oldText: cap(asString(diff.oldText) ?? "", DIFF_CAP), newText: cap(asString(diff.newText) ?? "", DIFF_CAP) };
+      return { ...base, title: path2, detail };
+    }
+    const path = locationPath(event) ?? asString(input.file_path) ?? asString(input.path) ?? fallbackTitle;
+    return { ...base, title: path, detail: { type: "fields", fields: primitiveFields(input) } };
+  }
+  if (event.kind === "read") {
+    const path = asString(input.file_path) ?? asString(input.path) ?? asString(pc?.name) ?? locationPath(event) ?? fallbackTitle;
+    const lines = readLines(input);
+    const preview = textFromBlocks(blocks) ?? asString(output.text) ?? rawOutputText;
+    const detail = { type: "read", path, ...lines ? { lines } : {}, ...preview ? { preview: cap(preview) } : {} };
+    return { ...base, title: path, detail };
+  }
+  if (event.kind === "execute") {
+    const command = asString(input.command) ?? asString(input.cmd) ?? asString(pc?.cmd) ?? fallbackTitle;
+    const out2 = asString(output.stdout) ?? textFromBlocks(blocks) ?? asString(output.text) ?? rawOutputText;
+    const exitCode = typeof output.exitCode === "number" ? output.exitCode : undefined;
+    const detail = { type: "command", command, ...out2 ? { output: cap(out2) } : {}, ...exitCode !== undefined ? { exitCode } : {} };
+    return { ...base, title: command, detail };
+  }
+  if (event.kind === "search") {
+    const query = asString(input.query) ?? asString(input.pattern) ?? asString(input.search) ?? asString(input.command) ?? asString(pc?.cmd) ?? fallbackTitle;
+    const out2 = textFromBlocks(blocks) ?? asString(output.stdout) ?? asString(output.text) ?? rawOutputText;
+    const detail = { type: "search", query, ...out2 ? { output: cap(out2) } : {} };
+    return { ...base, title: query, detail };
+  }
+  if (event.kind === "think") {
+    const text = asString(input.description) ?? asString(input.prompt) ?? textFromBlocks(blocks) ?? "";
+    return { ...base, title: fallbackTitle, detail: { type: "text", text: cap(text) } };
+  }
+  const out = textFromBlocks(blocks) ?? asString(output.stdout) ?? asString(output.text) ?? rawOutputText;
+  return { ...base, title: fallbackTitle, detail: { type: "fields", fields: primitiveFields(input), ...out ? { output: cap(out) } : {} } };
+}
+
+// packages/channel-relay/src/control-bridge.ts
+function scheduledTaskToDto(record) {
+  return {
+    id: record.id,
+    sessionAlias: record.session_alias,
+    executeAt: record.execute_at,
+    message: record.message,
+    status: record.status,
+    createdAt: record.created_at,
+    ...record.executed_at ? { executedAt: record.executed_at } : {},
+    ...record.failed_at ? { failedAt: record.failed_at } : {},
+    ...record.last_error ? { lastError: record.last_error } : {}
+  };
+}
+function orchestrationTaskToDto(record) {
+  return {
+    taskId: record.taskId,
+    status: record.status,
+    targetAgent: record.targetAgent,
+    workspace: record.workspace,
+    task: record.task,
+    summary: record.summary,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt
+  };
+}
+function createControlBridge(control) {
+  return (envelope, respond) => {
+    dispatchControlRequest(control, envelope).then(respond).catch((error) => {
+      respond(errorPayload("internal", error instanceof Error ? error.message : String(error)));
+    });
+  };
+}
+async function dispatchControlRequest(control, envelope) {
+  const payload = envelope.payload;
+  switch (envelope.type) {
+    case MSG.sessionsList: {
+      const input = payload;
+      return { sessions: control.listSessions(input.chatKey) };
+    }
+    case MSG.sessionsCreate: {
+      const input = payload;
+      return await control.createSession(input.chatKey, input.alias, input.agent, input.workspace, input.agentSessionId, input.model);
+    }
+    case MSG.sessionsNativeList: {
+      const input = payload;
+      return { sessions: await control.listNativeSessions(input.chatKey, input.agent, input.workspace) };
+    }
+    case MSG.sessionsRemove: {
+      const input = payload;
+      return await control.removeSession(input.chatKey, input.alias);
+    }
+    case MSG.agentsList:
+      return { agents: control.listAgents() };
+    case MSG.workspacesList:
+      return { workspaces: control.listWorkspaces() };
+    case MSG.workspacesCreate: {
+      const input = payload;
+      const name = typeof input.name === "string" ? input.name.trim() : "";
+      const cwd = typeof input.cwd === "string" ? input.cwd.trim() : "";
+      if (!name || !cwd)
+        return errorPayload("bad-request", "workspace name and cwd are required");
+      return { workspace: await control.createWorkspace(name, cwd, input.description) };
+    }
+    case MSG.agentsCatalog:
+      return { agents: control.listAgentCatalog() };
+    case MSG.agentsCreate: {
+      const input = payload;
+      const name = typeof input.name === "string" ? input.name.trim() : "";
+      const driver = typeof input.driver === "string" ? input.driver.trim() : "";
+      if (!name || !driver)
+        return errorPayload("bad-request", "agent name and driver are required");
+      return { agent: await control.createAgent(name, driver) };
+    }
+    case MSG.agentsRemove: {
+      const input = payload;
+      const name = typeof input.name === "string" ? input.name.trim() : "";
+      if (!name)
+        return errorPayload("bad-request", "agent name is required");
+      await control.removeAgent(name);
+      return { ok: true };
+    }
+    case MSG.workspacesRemove: {
+      const input = payload;
+      const name = typeof input.name === "string" ? input.name.trim() : "";
+      if (!name)
+        return errorPayload("bad-request", "workspace name is required");
+      await control.removeWorkspace(name);
+      return { ok: true };
+    }
+    case MSG.prompt:
+      return await control.prompt(payload);
+    case MSG.promptCancel: {
+      const input = payload;
+      return { cancelled: control.cancelTurn(input.chatKey, input.sessionAlias) };
+    }
+    case MSG.commandExecute: {
+      const input = payload;
+      return { output: await control.executeCommand(input) };
+    }
+    case MSG.scheduledList: {
+      const input = payload;
+      return { tasks: control.listScheduledTasks(input.chatKey).map(scheduledTaskToDto) };
+    }
+    case MSG.scheduledCreate: {
+      const input = payload;
+      const ms = Date.parse(input.executeAt);
+      if (Number.isNaN(ms))
+        return errorPayload("bad-request", "executeAt is not a valid ISO timestamp");
+      const task = await control.createScheduledTask({
+        chatKey: input.chatKey,
+        sessionAlias: input.sessionAlias,
+        executeAt: new Date(ms),
+        message: input.message
+      });
+      return scheduledTaskToDto(task);
+    }
+    case MSG.scheduledCancel: {
+      const input = payload;
+      return { cancelled: await control.cancelScheduledTask(input.id, input.chatKey) };
+    }
+    case MSG.orchestrationList:
+      return { tasks: (await control.listOrchestrationTasks()).map(orchestrationTaskToDto) };
+    case MSG.orchestrationGet: {
+      const input = payload;
+      const task = await control.getOrchestrationTask(input.taskId);
+      return { task: task ? orchestrationTaskToDto(task) : null };
+    }
+    case MSG.orchestrationCancel: {
+      const input = payload;
+      return orchestrationTaskToDto(await control.cancelOrchestrationTask({ taskId: input.taskId }));
+    }
+    case MSG.fsList: {
+      const input = payload;
+      if (!input.workspace)
+        return errorPayload("bad-request", "workspace is required");
+      return await control.listDirectory(input.workspace, input.path);
+    }
+    case MSG.fsRead: {
+      const input = payload;
+      if (!input.workspace || !input.path)
+        return errorPayload("bad-request", "workspace and path are required");
+      return await control.readWorkspaceFile(input.workspace, input.path);
+    }
+    case MSG.fsDiff: {
+      const input = payload;
+      if (!input.workspace)
+        return errorPayload("bad-request", "workspace is required");
+      return await control.workspaceGitDiff(input.workspace, input.path);
+    }
+    case MSG.fsSearch: {
+      const input = payload;
+      if (!input.workspace)
+        return errorPayload("bad-request", "workspace is required");
+      return await control.searchWorkspace(input.workspace, input.query ?? "");
+    }
+    case MSG.sessionModelGet: {
+      const input = payload;
+      if (!input.sessionAlias)
+        return errorPayload("bad-request", "sessionAlias is required");
+      return await control.getSessionModel(input.chatKey, input.sessionAlias);
+    }
+    case MSG.sessionModelSet: {
+      const input = payload;
+      if (!input.sessionAlias || !input.modelId)
+        return errorPayload("bad-request", "sessionAlias and modelId are required");
+      await control.setSessionModel(input.chatKey, input.sessionAlias, input.modelId);
+      return { ok: true };
+    }
+    default:
+      return errorPayload("unknown-type", `unsupported rpc type: ${envelope.type}`);
+  }
+}
+function historyMessagesToRows(messages) {
+  return messages.map((m) => {
+    if (m.role === "user")
+      return { direction: "in", text: m.text };
+    const parts = [];
+    const toolSteps = [];
+    const reasoningChunks = [];
+    for (const p of m.parts ?? []) {
+      if (p.kind === "text")
+        parts.push({ type: "text", text: p.text });
+      else if (p.kind === "reasoning") {
+        parts.push({ type: "reasoning", text: p.text });
+        reasoningChunks.push(p.text);
+      } else if (p.kind === "tool") {
+        const step = toolUseEventToStepDto(p.tool);
+        parts.push({ type: "tool", step });
+        toolSteps.push(step);
+      }
+    }
+    const hasStructured = toolSteps.length > 0 || reasoningChunks.length > 0 || parts.length > 0;
+    const structured = hasStructured ? {
+      ...toolSteps.length ? { toolSteps } : {},
+      ...reasoningChunks.length ? { reasoning: reasoningChunks.join(`
+`) } : {},
+      ...parts.length ? { parts } : {}
+    } : undefined;
+    return { direction: "out", text: m.text, ...structured ? { structured } : {} };
+  });
+}
+function subscribeControlEvents(control, sendEvent) {
+  return control.events.subscribe((event) => {
+    if (event.type === "tool-event") {
+      sendEvent(MSG.instanceEvent, {
+        event: { type: "tool-event", chatKey: event.chatKey, sessionAlias: event.sessionAlias, step: toolUseEventToStepDto(event.event) }
+      });
+      return;
+    }
+    if (event.type === "session-history") {
+      sendEvent(MSG.instanceEvent, {
+        event: { type: "session-history", chatKey: event.chatKey, sessionAlias: event.sessionAlias, messages: historyMessagesToRows(event.messages) }
+      });
+      return;
+    }
+    sendEvent(MSG.instanceEvent, { event });
+  });
+}
+
+// packages/channel-relay/src/relay-client.ts
+import WebSocket from "ws";
+import {
+  MSG as MSG2,
+  RELAY_PROTOCOL_VERSION,
+  decodeEnvelope,
+  encodeEnvelope,
+  isErrorPayload
+} from "@ganglion/xacpx-relay-protocol";
+var DEFAULT_DELAYS = [1000, 2000, 5000, 1e4, 30000];
+var HANDSHAKE_ID = "handshake-1";
+
+class RelayClient {
+  options;
+  socket = null;
+  attempts = 0;
+  stopped = false;
+  ready = false;
+  constructor(options) {
+    this.options = options;
+  }
+  start(abortSignal) {
+    abortSignal.addEventListener("abort", () => this.stop(), { once: true });
+    if (!abortSignal.aborted)
+      this.connect();
+  }
+  stop() {
+    this.stopped = true;
+    this.socket?.close();
+    this.socket = null;
+  }
+  sendEvent(type, payload) {
+    if (!this.ready || !this.socket || this.socket.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    this.socket.send(encodeEnvelope({ protocolVersion: RELAY_PROTOCOL_VERSION, kind: "event", type, payload }));
+  }
+  connect() {
+    if (this.stopped)
+      return;
+    const socket = (this.options.createSocket ?? ((url) => new WebSocket(url)))(this.options.url);
+    this.socket = socket;
+    this.ready = false;
+    socket.on("open", () => this.sendHandshake(socket));
+    socket.on("message", (data) => this.handleMessage(socket, String(data)));
+    socket.on("error", () => {});
+    socket.on("close", () => {
+      this.ready = false;
+      if (this.stopped)
+        return;
+      const delays = this.options.reconnectDelaysMs ?? DEFAULT_DELAYS;
+      const delay = delays[Math.min(this.attempts, delays.length - 1)] ?? 30000;
+      this.attempts += 1;
+      setTimeout(() => this.connect(), delay);
+    });
+  }
+  sendHandshake(socket) {
+    const credential = this.options.credentialStore.load();
+    if (credential) {
+      socket.send(encodeEnvelope({
+        protocolVersion: RELAY_PROTOCOL_VERSION,
+        kind: "req",
+        id: HANDSHAKE_ID,
+        type: MSG2.instanceAuth,
+        payload: {
+          instanceId: credential.instanceId,
+          credential: credential.credential,
+          coreVersion: this.options.coreVersion
+        }
+      }));
+      return;
+    }
+    if (this.options.pairingToken) {
+      socket.send(encodeEnvelope({
+        protocolVersion: RELAY_PROTOCOL_VERSION,
+        kind: "req",
+        id: HANDSHAKE_ID,
+        type: MSG2.instanceRegister,
+        payload: {
+          pairingToken: this.options.pairingToken,
+          name: this.options.instanceName,
+          coreVersion: this.options.coreVersion
+        }
+      }));
+      return;
+    }
+    this.options.logger?.error("relay.no_credentials", "relay channel has neither credential nor pairing token", {});
+    this.stopped = true;
+    socket.close();
+  }
+  handleMessage(socket, raw) {
+    const decoded = decodeEnvelope(raw);
+    if (!decoded.ok) {
+      this.options.logger?.error("relay.decode_failed", `relay sent an undecodable message: ${decoded.error}`, { error: decoded.error, detail: decoded.detail ?? "" });
+      if (decoded.error === "version-mismatch") {
+        this.stopped = true;
+        socket.close();
+      }
+      return;
+    }
+    const envelope = decoded.envelope;
+    if (envelope.kind === "event" && envelope.type === "relay.protocol-error") {
+      const p = envelope.payload;
+      const detail = isErrorPayload(p) ? `${p.error.code}: ${p.error.message}` : "protocol error";
+      this.options.logger?.error("relay.protocol_error", `relay reported a protocol error: ${detail}`, {});
+      this.stopped = true;
+      socket.close();
+      return;
+    }
+    if (envelope.kind === "res" && envelope.id === HANDSHAKE_ID) {
+      if (isErrorPayload(envelope.payload)) {
+        this.options.logger?.error("relay.handshake_rejected", "relay rejected the handshake; not retrying", {
+          code: envelope.payload.error.code,
+          message: envelope.payload.error.message
+        });
+        this.stopped = true;
+        socket.close();
+        return;
+      }
+      if (envelope.type === MSG2.instanceRegister) {
+        const result = envelope.payload;
+        const credential = {
+          instanceId: result.instanceId,
+          credential: result.credential,
+          relayUrl: this.options.url
+        };
+        this.options.credentialStore.save(credential);
+      }
+      this.ready = true;
+      this.attempts = 0;
+      this.options.onReady?.();
+      return;
+    }
+    if (envelope.kind === "req") {
+      const respond = (payload) => {
+        socket.send(encodeEnvelope({
+          protocolVersion: RELAY_PROTOCOL_VERSION,
+          kind: "res",
+          id: envelope.id,
+          type: envelope.type,
+          payload
+        }));
+      };
+      this.options.onRequest(envelope, respond);
+    }
+  }
+}
+
+// packages/channel-relay/src/channel.ts
+class RelayChannel {
+  deps;
+  id = "relay";
+  nativeSessionListFormat = "table";
+  config;
+  credentials;
+  client = null;
+  unsubscribe = null;
+  control = null;
+  constructor(options, deps = {}) {
+    this.deps = deps;
+    this.config = parseRelayChannelConfig(options);
+    this.credentials = deps.credentialStore ?? new CredentialStore(defaultCredentialPath());
+  }
+  isLoggedIn() {
+    return this.credentials.load() !== null || this.config.pairingToken !== undefined;
+  }
+  async login() {
+    return "relay channel pairs automatically on start; configure it via: xacpx channel add relay --url <ws-url> --token <pairing-token>";
+  }
+  logout() {
+    this.credentials.clear();
+  }
+  async start(input) {
+    if (!input.control) {
+      throw new Error("relay channel requires ChannelStartInput.control (xacpx >= 0.11)");
+    }
+    this.control = input.control;
+    const bridge = createControlBridge(input.control);
+    const client = (this.deps.createClient ?? ((options) => new RelayClient(options)))({
+      url: this.config.url,
+      credentialStore: this.credentials,
+      pairingToken: this.config.pairingToken,
+      instanceName: this.config.name,
+      coreVersion: input.coreVersion,
+      onRequest: bridge,
+      logger: input.logger
+    });
+    this.client = client;
+    this.unsubscribe = subscribeControlEvents(input.control, (type, payload) => client.sendEvent(type, payload));
+    client.start(input.abortSignal);
+    await new Promise((resolve) => {
+      if (input.abortSignal.aborted) {
+        resolve();
+        return;
+      }
+      input.abortSignal.addEventListener("abort", () => resolve(), { once: true });
+    });
+    this.stop();
+  }
+  stop() {
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    this.client?.stop();
+    this.client = null;
+    this.control = null;
+  }
+  async notifyTaskCompletion(task) {
+    this.sendNotice({ kind: "task-completion", taskId: task.taskId, text: task.summary || task.resultText || task.taskId });
+  }
+  async notifyTaskProgress(task, text) {
+    this.sendNotice({ kind: "task-progress", taskId: task.taskId, text });
+  }
+  async sendCoordinatorMessage(input) {
+    this.sendNotice({ kind: "coordinator-message", chatKey: input.chatKey, text: input.text });
+  }
+  async sendScheduledMessage(input) {
+    if (!this.control) {
+      throw new Error("relay channel cannot dispatch scheduled task before start()");
+    }
+    const result = await this.control.runScheduledTurn({
+      chatKey: input.chatKey,
+      sessionAlias: input.sessionAlias,
+      promptText: input.promptText,
+      taskId: input.taskId ?? "",
+      executeAt: input.executeAt ?? new Date(0).toISOString(),
+      ...input.abortSignal ? { abortSignal: input.abortSignal } : {}
+    });
+    if (!result.ok) {
+      throw new Error(result.errorMessage ?? "scheduled turn failed");
+    }
+  }
+  sendNotice(payload) {
+    this.client?.sendEvent(MSG3.instanceNotice, payload);
+  }
+}
+
+// packages/channel-relay/src/relay-provider.ts
+function stringField(input, key) {
+  const value = input[key];
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+var relayCliProvider = {
+  type: "relay",
+  displayName: "Relay Hub",
+  supportsLogin: false,
+  parseAddArgs(args) {
+    const input = {};
+    for (let i = 0;i < args.length; i++) {
+      const arg = args[i];
+      const next = args[i + 1];
+      if (arg === "--url" || arg === "--token" || arg === "--name") {
+        if (!next || next.startsWith("--")) {
+          return { ok: false, message: `${arg} requires a value` };
+        }
+        input[arg.slice(2)] = next;
+        i += 1;
+      } else {
+        return { ok: false, message: `unknown flag: ${arg}` };
+      }
+    }
+    return { ok: true, input };
+  },
+  buildDefaultConfig(input) {
+    const url = stringField(input, "url");
+    const pairingToken = stringField(input, "token");
+    const name = stringField(input, "name");
+    const options = {};
+    if (url !== undefined)
+      options.url = normalizeRelayUrl(url);
+    if (pairingToken !== undefined)
+      options.pairingToken = pairingToken;
+    if (name !== undefined)
+      options.name = name;
+    return {
+      id: "relay",
+      type: "relay",
+      enabled: true,
+      options
+    };
+  },
+  validateConfig(config) {
+    const issues = [];
+    const options = config.options ?? {};
+    const url = normalizeRelayUrl(typeof options.url === "string" ? options.url : "");
+    if (!url) {
+      issues.push({ kind: "missing-required-field", flag: "--url", message: "relay url — a domain (wss), or IP[:port] (ws, default :8788) is required" });
+    } else if (!url.startsWith("ws://") && !url.startsWith("wss://")) {
+      issues.push({ kind: "invalid-config", message: `url must be a domain, IP[:port], or ws(s):// address, got: ${String(options.url ?? "")}` });
+    }
+    if (typeof options.pairingToken !== "string" || !options.pairingToken) {
+      issues.push({ kind: "missing-required-field", flag: "--token", message: "access token is required (generate one with: xacpx-relay add token)" });
+    }
+    return issues;
+  },
+  renderSummary(config) {
+    const options = config.options ?? {};
+    const lines = [`relay url: ${String(options.url ?? "")}`, "pairing token: ***"];
+    if (typeof options.name === "string")
+      lines.push(`instance name: ${options.name}`);
+    return lines;
+  },
+  async promptForMissingFields(input, io) {
+    const completed = { ...input };
+    if (!stringField(completed, "url")) {
+      const value = (await io.promptText("Relay url (domain, or IP[:port]; e.g. relay.example.com or 1.2.3.4): ")).trim();
+      if (value)
+        completed.url = value;
+    }
+    if (!stringField(completed, "token")) {
+      const value = (await io.promptSecret("Pairing token: ")).trim();
+      if (value)
+        completed.token = value;
+    }
+    return completed;
+  }
+};
+
+// packages/channel-relay/src/index.ts
+var plugin = {
+  apiVersion: 1,
+  name: "@ganglion/xacpx-channel-relay",
+  minXacpxVersion: "0.11.0",
+  channels: [
+    {
+      type: "relay",
+      factory: (options, deps) => new RelayChannel(options, deps),
+      cliProvider: relayCliProvider
+    }
+  ]
+};
+var src_default = plugin;
+export {
+  relayCliProvider,
+  src_default as default,
+  RelayChannel
+};

package/dist/relay-client.d.ts

@@ -0,0 +1,30 @@
+import WebSocket from "ws";
+import { type RelayEnvelope } from "@ganglion/xacpx-relay-protocol";
+import type { AppLogger } from "xacpx/plugin-api";
+import type { CredentialStore } from "./credential-store.js";
+export interface RelayClientOptions {
+    url: string;
+    credentialStore: Pick<CredentialStore, "load" | "save" | "clear">;
+    pairingToken?: string;
+    instanceName?: string;
+    coreVersion?: string;
+    onRequest: (envelope: RelayEnvelope, respond: (payload: unknown) => void) => void;
+    onReady?: () => void;
+    reconnectDelaysMs?: number[];
+    createSocket?: (url: string) => WebSocket;
+    logger?: AppLogger;
+}
+export declare class RelayClient {
+    private readonly options;
+    private socket;
+    private attempts;
+    private stopped;
+    private ready;
+    constructor(options: RelayClientOptions);
+    start(abortSignal: AbortSignal): void;
+    stop(): void;
+    sendEvent(type: string, payload: unknown): void;
+    private connect;
+    private sendHandshake;
+    private handleMessage;
+}

package/dist/relay-provider.d.ts

@@ -0,0 +1,2 @@
+import type { ChannelCliProvider } from "xacpx/plugin-api";
+export declare const relayCliProvider: ChannelCliProvider;

package/dist/tool-presentation.d.ts

@@ -0,0 +1,4 @@
+import type { ToolUseEvent } from "xacpx/plugin-api";
+import type { ToolStepDto } from "@ganglion/xacpx-relay-protocol";
+/** Normalize a raw core ToolUseEvent into a friendly, capped, presentation-ready step. */
+export declare function toolUseEventToStepDto(event: ToolUseEvent): ToolStepDto;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ganglion/xacpx-channel-relay",
+  "version": "0.1.0",
+  "description": "Relay hub connector channel plugin for xacpx.",
+  "license": "MIT",
+  "keywords": ["xacpx", "relay", "channel", "plugin"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gadzan/xacpx.git",
+    "directory": "packages/channel-relay"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "peerDependencies": {
+    "xacpx": ">=0.11.0-0"
+  },
+  "peerDependenciesMeta": {
+    "xacpx": { "optional": true }
+  },
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "@ganglion/xacpx-relay-protocol": "^0.1.0",
+    "ws": "^8.20.0"
+  }
+}