@runuai/host 0.1.0

package/src/paths.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared filesystem paths for the host service + local UI (ADR-028).
+ * Used by main.ts (server boot), cli.ts (status/open/logs), and the per-OS
+ * install modules so the log/port/asset locations have a single definition.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { env } from "../lib/env";
+
+const srcDir = dirname(fileURLToPath(import.meta.url)); // host-agent/src
+
+/** Base dir for host state — the repo root in a checkout, ~/.uai when
+ *  installed via npm. Used as the service working directory. */
+export function uaiHome(): string {
+  return env.uaiHome;
+}
+
+/** `.env.local` under UAI_HOME — where `setup`/`pair` persist the credential. */
+export function envLocalPath(): string {
+  return join(env.uaiHome, ".env.local");
+}
+
+/** Static UI asset dir (`host-agent/ui`). */
+export function uiAssetsDir(): string {
+  return resolve(srcDir, "..", "ui");
+}
+
+/** Where the chosen UI port is persisted (`$UAI_DATA_DIR/host.port`). */
+export function uiPortFilePath(): string {
+  return join(env.dataDir, "host.port");
+}
+
+/** Per-OS service log path — informational in `/api/status`, the file
+ *  `uai-host logs` tails. Linux logs to journald, so returns a hint there. */
+export function serviceLogPath(): string {
+  if (process.platform === "darwin") {
+    return resolve(homedir(), "Library", "Logs", "Uai", "host.log");
+  }
+  if (process.platform === "win32") {
+    return join(
+      process.env.LOCALAPPDATA ?? homedir(),
+      "Uai",
+      "service",
+      "logs",
+      "host.log",
+    );
+  }
+  return "journald (journalctl --user -u uai-host)";
+}
+
+/** `@runuai/host` package version (read at runtime; no JSON-import dance). */
+export function packageVersion(): string {
+  try {
+    const raw = readFileSync(resolve(srcDir, "..", "package.json"), "utf8");
+    const pkg = JSON.parse(raw) as { version?: string };
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,413 @@
+export enum HostErrorCode {
+  TaskNotFound = "task_not_found",
+  ProjectNotFound = "project_not_found",
+  TemplateNotFound = "template_not_found",
+  TaskAlreadyRunning = "task_already_running",
+  TaskNotRunning = "task_not_running",
+  ContainerInitFailed = "container_init_failed",
+  ComposeUpFailed = "compose_up_failed",
+  ComposeDownFailed = "compose_down_failed",
+  WorktreeFailed = "worktree_failed",
+  CloneFailed = "clone_failed",
+  FetchFailed = "fetch_failed",
+  RenderFailed = "render_failed",
+  DbFailed = "db_failed",
+  NoSuchAgent = "no_such_agent",
+  NoSuchPermission = "no_such_permission",
+  HostUnavailable = "host_unavailable",
+  Internal = "internal",
+}
+
+export type HostCommandResult<T> =
+  | { ok: true; value: T }
+  | {
+      ok: false;
+      code: HostErrorCode;
+      message: string;
+      retryable?: boolean;
+    };
+
+export interface CommandContext {
+  commandId: string;
+}
+
+export type PermissionDecision = { kind: "accept" } | { kind: "decline" };
+
+/**
+ * An agent materialised onto a task (ADR-021/ADR-022). `kind` is the
+ * host-advertised agent kind ("claude" | "codex" | "gemini" | …); there is no
+ * `role` field. `model` is passed through to the CLI by the adapter. Each
+ * agent carries its own first-turn `initialPrompt` and persona `defaultPrompt`.
+ * `effort` (when set) is the CLI reasoning level, passed through like `model`.
+ */
+export interface TaskAgent {
+  id: string;
+  label: string;
+  kind: string;
+  model?: string;
+  effort?: string;
+  defaultPrompt?: string;
+  initialPrompt?: string;
+}
+
+/**
+ * Host capability advertisement (ADR-021). Sent as a `host.capabilities`
+ * frame after auth-success and re-sent when the host's adapter registry
+ * changes. The cloud caches it per hostId to drive the task-creation pickers.
+ */
+export interface HostCapabilities {
+  agentKinds: Array<{
+    kind: string;
+    label: string;
+    supportedModels: string[];
+    defaultModel?: string;
+    supportedEfforts: string[];
+    defaultEffort?: string;
+  }>;
+  runtimes: Array<{
+    kind: string;
+    availableVersions: string[];
+  }>;
+}
+
+export interface TaskUpResult {
+  composeProject: string;
+  worktreePath: string;
+  codeServerPort?: number;
+  previewPorts?: Array<{ name: string; hostPort: number }>;
+}
+
+export interface TaskDownResult {
+  status?: string;
+  alreadyGone?: boolean;
+  [key: string]: unknown;
+}
+
+export interface TaskStatusResult {
+  composeRunning: boolean;
+  containers: string[];
+  worktreePresent: boolean;
+}
+
+export interface CloneRepoInput {
+  url: string;
+  projectId: string;
+}
+
+export interface CloneRepoResult {
+  status: "ready" | "error";
+  error?: string;
+  absolutePath: string;
+}
+
+export interface TaskCommandTask {
+  id: string;
+  ownerUserId: string;
+  hostId: string;
+  name: string;
+  slug: string;
+  branch: string;
+  status: string;
+  globalContext?: string;
+  reviewerOrder?: string[];
+  agents: TaskAgent[];
+}
+
+/**
+ * A project snapshot carried in a task command. A project is a single repo
+ * plus config (ADR-022). `previewPorts` and `env` are JSON strings (the
+ * host parses them). `position` orders the clone layout and prompt concat.
+ */
+export interface TaskCommandProject {
+  id: string;
+  ownerUserId: string;
+  name: string;
+  slug: string;
+  repoUrl: string;
+  defaultPrompt: string;
+  previewPorts: string;
+  env: string;
+  toolVersions?: string;
+  extra?: string;
+  position: number;
+}
+
+export interface TaskLaunchInput {
+  task: TaskCommandTask;
+  projects: TaskCommandProject[];
+  ownerEmail?: string;
+  ownerName?: string;
+}
+
+export interface TaskDownInput {
+  taskId: string;
+  task: TaskCommandTask;
+  projects: TaskCommandProject[];
+}
+
+export interface TaskDiffInput {
+  taskId: string;
+  projects: Array<{ id: string; slug: string }>;
+}
+
+export interface ChannelEnsureInput {
+  taskId: string;
+  agents: TaskAgent[];
+  globalContext?: string;
+  projects: Array<{ slug: string; defaultPrompt: string }>;
+  branch: string;
+  workspacePath: string;
+  status: string;
+}
+
+export type DiffStatus =
+  | "added"
+  | "deleted"
+  | "modified"
+  | "renamed"
+  | "copied"
+  | "binary";
+
+export interface DiffLine {
+  kind: "ctx" | "add" | "del";
+  content: string;
+  oldNo?: number;
+  newNo?: number;
+}
+
+export interface DiffHunk {
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  header: string;
+  lines: DiffLine[];
+}
+
+export interface DiffFile {
+  path: string;
+  oldPath?: string;
+  status: DiffStatus;
+  language?: string;
+  binary: boolean;
+  hunks: DiffHunk[];
+}
+
+export interface TaskDiffRepo {
+  id: string;
+  name: string;
+  mountPath: string;
+  defaultBranch: string;
+  files: DiffFile[];
+  error?: string;
+}
+
+export interface TaskDiffResult {
+  repos: TaskDiffRepo[];
+}
+
+export interface HostCommands {
+  taskUp(
+    ctx: CommandContext,
+    input: TaskLaunchInput,
+  ): Promise<HostCommandResult<TaskUpResult>>;
+  taskDown(
+    ctx: CommandContext,
+    input: TaskDownInput,
+  ): Promise<HostCommandResult<TaskDownResult>>;
+  taskStatus(
+    ctx: CommandContext,
+    taskId: string,
+  ): Promise<HostCommandResult<TaskStatusResult>>;
+  channelEnsure(
+    ctx: CommandContext,
+    input: ChannelEnsureInput,
+  ): Promise<HostCommandResult<void>>;
+  channelTeardown(
+    ctx: CommandContext,
+    taskId: string,
+  ): Promise<HostCommandResult<void>>;
+  channelDeliver(
+    ctx: CommandContext,
+    taskId: string,
+    agentId: string,
+    text: string,
+  ): Promise<HostCommandResult<void>>;
+  channelResolvePermission(
+    ctx: CommandContext,
+    taskId: string,
+    agentId: string,
+    requestId: string,
+    decision: PermissionDecision,
+  ): Promise<HostCommandResult<void>>;
+  cloneRepo(
+    ctx: CommandContext,
+    input: CloneRepoInput,
+  ): Promise<HostCommandResult<CloneRepoResult>>;
+  taskDiff(
+    ctx: CommandContext,
+    input: TaskDiffInput,
+  ): Promise<HostCommandResult<TaskDiffResult>>;
+  // Chat attachments live in the task workspace on the host (ADR-015); the
+  // cloud relays bytes (base64) in and out, never persisting them.
+  attachmentWrite(
+    ctx: CommandContext,
+    input: { taskId: string; filename: string; dataBase64: string },
+  ): Promise<HostCommandResult<void>>;
+  attachmentRead(
+    ctx: CommandContext,
+    input: { taskId: string; filename: string },
+  ): Promise<HostCommandResult<{ dataBase64: string }>>;
+  channelInterrupt(
+    ctx: CommandContext,
+    taskId: string,
+    agentId: string,
+  ): Promise<HostCommandResult<void>>;
+  // Append a chat message to the task's shared transcript (<workspace>/.uai/
+  // chat.md) so agents can read cross-agent context on demand.
+  appendTranscript(
+    ctx: CommandContext,
+    taskId: string,
+    author: string,
+    text: string,
+  ): Promise<HostCommandResult<void>>;
+}
+
+export interface TunnelReqLine {
+  method: string;
+  url: string;
+  headers: [string, string][];
+}
+
+export type TunnelTarget = "editor" | "preview";
+
+export type CloudToHost =
+  | {
+      kind: "command";
+      commandId: string;
+      command: keyof HostCommands;
+      args: unknown[];
+    }
+  | { kind: "pong"; ts: number }
+  | {
+      kind: "tunnel.open";
+      tunnelId: string;
+      target: TunnelTarget;
+      taskId: string;
+      name?: string;
+      reqLine: TunnelReqLine;
+      upgrade: boolean;
+    }
+  | { kind: "tunnel.data"; tunnelId: string }
+  // Signals the request body is complete so the host can end the upstream
+  // request (only then does an upstream that reads the body reply). Without
+  // this, a body request deadlocks: the host never ends the upstream, so it
+  // never responds, so the cloud never sends an ack. (HTTP tunnels only.)
+  | { kind: "tunnel.requestEnd"; tunnelId: string }
+  | { kind: "tunnel.close"; tunnelId: string; reason?: string }
+  // GitHub App connect lifecycle (ADR-027). The cloud forwards the user's
+  // refresh token to the host, which encrypts + persists it; the per-task
+  // access-token exchange is a host→cloud HTTP POST, not a frame.
+  | {
+      kind: "gh.connect.set";
+      userId: string;
+      installationId: number;
+      githubLogin: string;
+      targetType: "User" | "Organization";
+      refreshToken: string;
+      refreshTokenExpiresAt?: number;
+    }
+  | { kind: "gh.connect.clear"; userId: string }
+  // Per-user SSH key lifecycle (ADR-029). Keys are generated + stored on the
+  // host; only the public key crosses the bridge (ssh.key.ack). `get` fetches
+  // without creating, `ensure` creates-if-absent, `delete` removes.
+  | { kind: "ssh.key.get"; userId: string }
+  | { kind: "ssh.key.ensure"; userId: string }
+  | { kind: "ssh.key.delete"; userId: string };
+
+export type HostToCloud =
+  | { kind: "auth"; token: string; hostId: string }
+  | { kind: "host.capabilities"; capabilities: HostCapabilities }
+  | {
+      kind: "result";
+      commandId: string;
+      result: HostCommandResult<unknown>;
+    }
+  | { kind: "event"; event: HostEvent }
+  | { kind: "ping"; ts: number }
+  | {
+      kind: "tunnel.ack";
+      tunnelId: string;
+      ok: boolean;
+      status?: number;
+      statusText?: string;
+      headers?: [string, string][];
+      message?: string;
+    }
+  | { kind: "tunnel.data"; tunnelId: string }
+  | { kind: "tunnel.close"; tunnelId: string; reason?: string }
+  // Ack for gh.connect.set / gh.connect.clear (ADR-027).
+  | { kind: "gh.connect.ack"; userId: string; ok: true }
+  | { kind: "gh.connect.ack"; userId: string; ok: false; error: string }
+  // Ack for ssh.key.get / ssh.key.ensure / ssh.key.delete (ADR-029). publicKey
+  // is null when the user has no key (after delete, or a get-miss).
+  | { kind: "ssh.key.ack"; userId: string; ok: true; publicKey: string | null }
+  | { kind: "ssh.key.ack"; userId: string; ok: false; error: string };
+
+export type HostEvent =
+  | {
+      kind: "task.status_changed";
+      taskId: string;
+      from: string;
+      to: string;
+    }
+  | {
+      kind: "task.log";
+      taskId: string;
+      stream: "stdout" | "stderr";
+      chunk: string;
+    }
+  | {
+      kind: "agent.message_delta";
+      taskId: string;
+      agentId: string;
+      chunk: string;
+    }
+  | {
+      kind: "agent.message_complete";
+      taskId: string;
+      agentId: string;
+      fullText: string;
+      mentions: string[];
+    }
+  | {
+      kind: "agent.tool_call";
+      taskId: string;
+      agentId: string;
+      tool: string;
+      meta: unknown;
+    }
+  | {
+      kind: "agent.permission_request";
+      taskId: string;
+      agentId: string;
+      requestId: string;
+      meta: unknown;
+    }
+  | {
+      kind: "agent.exit";
+      taskId: string;
+      agentId: string;
+      reason: string;
+    }
+  // A host-originated system note for the task channel (ADR-027) — e.g. gh
+  // auth expired. The cloud renders it as an author:"system" message.
+  | {
+      kind: "system.note";
+      taskId: string;
+      text: string;
+    };
+
+export interface HostEventStream {
+  subscribe(handler: (e: HostEvent) => void): () => void;
+}