@moondeck/station 0.0.0-stage → 1.0.0

package/lib/token-lanes/xai-oauth.ts

@@ -0,0 +1,165 @@
+/**
+ * Lane `xai-oauth` — Grok subscription sign-ins (`grok login --device-auth`).
+ *
+ * `auth.json` is keyed by `<issuer>::<client-id>`; each entry carries
+ * `key` (the bearer the CLI sends), `refresh_token`, `expires_at` (ISO),
+ * `oidc_issuer` and `oidc_client_id`. Refresh is a standard OIDC
+ * `grant_type=refresh_token` against `https://auth.x.ai/oauth2/token`
+ * (confirmed from the issuer's discovery document, 2026-09-09; refresh_token
+ * is among its supported grants).
+ *
+ * ASSUMPTION, recorded until observed on a live refresh: `key` is the OIDC
+ * access token, so a refresh replaces it with `access_token`. The lane never
+ * writes on an answer that lacks `access_token`, so a wrong assumption costs
+ * a failed refresh (retried, then the reactive path), never a corrupted
+ * sign-in.
+ */
+
+import {
+  BROKER_REFRESH_PLACEHOLDER,
+  isTerminalOAuthError,
+  parseObjectFile,
+  type CredentialFiles,
+  type CredentialHeader,
+  type LaneHttp,
+  type RefreshOutcome,
+  type TokenLane,
+} from "./types";
+import { brokerErrorKind, CREDENTIAL_LANE_SCHEDULES } from "../../src/cloud-credentials";
+
+export const XAI_ISSUER = "https://auth.x.ai";
+export const XAI_TOKEN_ENDPOINT = `${XAI_ISSUER}/oauth2/token`;
+const HOUR_MS = 60 * 60 * 1000;
+
+interface Entry {
+  key: string;
+  doc: Record<string, unknown>;
+}
+
+function entriesOf(files: CredentialFiles): { doc: Record<string, unknown>; entries: Entry[] } | null {
+  const doc = parseObjectFile(files["auth.json"]);
+  if (!doc) return null;
+  const entries: Entry[] = [];
+  for (const [key, value] of Object.entries(doc)) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      entries.push({ key, doc: value as Record<string, unknown> });
+    }
+  }
+  return { doc, entries };
+}
+
+function expiryOf(entry: Record<string, unknown>): number | null {
+  const raw = entry.expires_at;
+  if (typeof raw !== "string") return null;
+  const ms = Date.parse(raw);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+export const xaiOAuthLane: TokenLane = {
+  id: "xai-oauth",
+  endpoints: [XAI_TOKEN_ENDPOINT],
+  // Observed 2026-09-09: the token lives SIX hours (create_time → expires_at).
+  // Refresh with three hours left — the hourly cycle then renews it at about
+  // four hours of age — and every four hours when expiry cannot be read.
+  // ADR-154 §7: the cloud names a revision on the same schedule.
+  schedule: CREDENTIAL_LANE_SCHEDULES["xai-oauth"]!,
+  reactiveSignals: [/invalid_grant/i, /token (?:has )?expired/i, /log ?in again/i, /unauthorized/i],
+
+  matches(header: CredentialHeader, files: CredentialFiles): boolean {
+    if (header.kind !== "grok" || header.authKind !== "config-dir") return false;
+    const parsed = entriesOf(files);
+    return (
+      parsed !== null && parsed.entries.some((e) => typeof e.doc.refresh_token === "string")
+    );
+  },
+
+  expiresAt(files: CredentialFiles): number | null {
+    const parsed = entriesOf(files);
+    if (!parsed) return null;
+    const known = parsed.entries.map((e) => expiryOf(e.doc)).filter((v): v is number => v !== null);
+    return known.length ? Math.min(...known) : null;
+  },
+
+  brokeredCopy(files: CredentialFiles): CredentialFiles {
+    const parsed = entriesOf(files);
+    if (!parsed) return files;
+    let changed = false;
+    for (const entry of parsed.entries) {
+      if (
+        typeof entry.doc.refresh_token === "string" &&
+        entry.doc.refresh_token !== BROKER_REFRESH_PLACEHOLDER
+      ) {
+        entry.doc.refresh_token = BROKER_REFRESH_PLACEHOLDER;
+        changed = true;
+      }
+    }
+    return changed ? { ...files, "auth.json": `${JSON.stringify(parsed.doc, null, 2)}\n` } : files;
+  },
+
+  async refresh(files: CredentialFiles, http: LaneHttp, now: number): Promise<RefreshOutcome> {
+    const parsed = entriesOf(files);
+    if (!parsed) return { ok: false, terminal: true, reason: "auth.json is not readable" };
+    let refreshed = 0;
+    let expiresAt: number | null = null;
+    for (const entry of parsed.entries) {
+      const current = entry.doc.refresh_token;
+      if (typeof current !== "string" || current === BROKER_REFRESH_PLACEHOLDER) continue;
+      const issuer = typeof entry.doc.oidc_issuer === "string" ? entry.doc.oidc_issuer : XAI_ISSUER;
+      if (issuer.replace(/\/$/, "") !== XAI_ISSUER) {
+        return { ok: false, terminal: true, reason: "unexpected issuer" };
+      }
+      const clientId = entry.doc.oidc_client_id;
+      if (typeof clientId !== "string" || !clientId) {
+        return { ok: false, terminal: true, reason: "entry has no client id" };
+      }
+      let res;
+      try {
+        res = await http.postForm(XAI_TOKEN_ENDPOINT, {
+          grant_type: "refresh_token",
+          refresh_token: current,
+          client_id: clientId,
+        });
+      } catch (error) {
+        return {
+          ok: false,
+          terminal: false,
+          // A transport error can quote the request (and therefore the refresh
+          // token) in its message. Only its bounded kind may cross the lane.
+          reason: brokerErrorKind(error),
+        };
+      }
+      if (res.status < 200 || res.status >= 300) {
+        return {
+          ok: false,
+          terminal: isTerminalOAuthError(res.status, res.json),
+          reason: `HTTP ${res.status}`,
+        };
+      }
+      const body =
+        res.json && typeof res.json === "object" && !Array.isArray(res.json)
+          ? (res.json as Record<string, unknown>)
+          : null;
+      const access = body?.access_token;
+      if (typeof access !== "string" || !access) {
+        return { ok: false, terminal: false, reason: "response missing access_token" };
+      }
+      entry.doc.key = access;
+      if (typeof body?.refresh_token === "string" && body.refresh_token) {
+        entry.doc.refresh_token = body.refresh_token;
+      }
+      const expiresIn = body?.expires_in;
+      if (typeof expiresIn === "number" && Number.isFinite(expiresIn)) {
+        const at = now + expiresIn * 1000;
+        entry.doc.expires_at = new Date(at).toISOString();
+        expiresAt = expiresAt === null ? at : Math.min(expiresAt, at);
+      }
+      refreshed += 1;
+    }
+    if (refreshed === 0) return { ok: false, terminal: true, reason: "no refresh token to use" };
+    return {
+      ok: true,
+      files: { ...files, "auth.json": `${JSON.stringify(parsed.doc, null, 2)}\n` },
+      expiresAt,
+    };
+  },
+};

package/lib/transcript.ts

@@ -0,0 +1,128 @@
+/**
+ * The shared channel transcript (ADR-027-adjacent). Agents have private,
+ * isolated conversations — each only hears what it's addressed. So they can opt
+ * into cross-agent awareness, the host maintains a plain-text log of every chat
+ * message at `<workspace>/.moondeck/chat.md` (mounted at /workspace), which any agent
+ * can read on demand. Secretary mode adds a frontstage projection at
+ * `chat-front.md`; the cloud decides which projection(s) a row belongs to and
+ * sends an explicit target list. Conversational rows (including dispatch
+ * instructions) only — no tool-call execution traces.
+ */
+
+import { mkdirSync } from "node:fs";
+
+import { taskWorkspaceDir } from "./env";
+import { rewriteAttachmentRefs } from "./orchestrator";
+import type { TaskEnvironmentHandle } from "./task-environment/types";
+import { appendContainedFileSync, makeContainedDirectoriesSync } from "./task-environment/workspace-files";
+import type { TranscriptTarget } from "../src/protocol";
+
+/** Container path agents are pointed at. */
+export const CONTAINER_TRANSCRIPT_PATH = "/workspace/.moondeck/chat.md";
+export const CONTAINER_FRONT_TRANSCRIPT_PATH =
+  "/workspace/.moondeck/chat-front.md";
+
+const TARGET_FILENAME: Record<TranscriptTarget, string> = {
+  chat: "chat.md",
+  "chat-front": "chat-front.md",
+};
+
+function transcriptEntry(author: string, text: string): string | null {
+  // Rewrite cloud attachment URLs to the in-container path so an agent reading
+  // the transcript can open referenced files directly.
+  const body = rewriteAttachmentRefs(text).trim();
+  if (!body) return null;
+  return `## ${author}\n\n${body}\n\n`;
+}
+
+export function appendTranscript(
+  taskId: string,
+  author: string,
+  text: string,
+  targets: TranscriptTarget[],
+): void {
+  const entry = transcriptEntry(author, text);
+  if (entry === null) return;
+  // Into the task's own .moondeck, never through a link the task put there
+  // (#cb3j0z). The workspace root is the runner's own path; .moondeck, directly
+  // below it, is made if gone without following a link.
+  const workspace = taskWorkspaceDir(taskId);
+  mkdirSync(workspace, { recursive: true });
+  makeContainedDirectoriesSync(workspace, [".moondeck"]);
+  for (const target of new Set(targets)) {
+    appendContainedFileSync(workspace, [".moondeck", TARGET_FILENAME[target]], Buffer.from(entry));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ADR-121: environment-side transcript for machine-backed tasks. The
+// workspace lives in the machine's world, so the append travels over the
+// environment transport (entry via stdin). A per-task promise chain
+// preserves message order the way the sync host-FS path did implicitly.
+// ---------------------------------------------------------------------------
+
+const environmentAppendChains = new Map<string, Promise<void>>();
+
+async function appendOneViaEnvironment(
+  environment: TaskEnvironmentHandle<unknown>,
+  target: TranscriptTarget,
+  entry: string,
+): Promise<void> {
+  const path = `${environment.descriptor.workspacePath}/.moondeck/${TARGET_FILENAME[target]}`;
+  const proc = await environment.spawn({
+    projectEnvProfile: "maintenance",
+    argv: [
+      "/bin/sh",
+      "-c",
+      'mkdir -p "$(dirname "$1")" && cat >> "$1"',
+      "append",
+      path,
+    ],
+    inheritEnv: [],
+    env: {},
+    timeoutMs: 30_000,
+    maxOutputBytes: 8 * 1024,
+  });
+  const drains = [
+    (async () => {
+      for await (const chunk of proc.stdout) void chunk;
+    })(),
+    (async () => {
+      for await (const chunk of proc.stderr) void chunk;
+    })(),
+  ];
+  await proc.write(Buffer.from(entry));
+  await proc.closeInput();
+  const exit = await proc.completion;
+  await Promise.allSettled(drains);
+  if (exit.exitCode !== 0) {
+    throw new Error(`environment transcript append exited ${exit.exitCode}`);
+  }
+}
+
+export function appendTranscriptViaEnvironment(
+  taskId: string,
+  environment: TaskEnvironmentHandle<unknown>,
+  author: string,
+  text: string,
+  targets: TranscriptTarget[],
+): Promise<void> {
+  const entry = transcriptEntry(author, text);
+  if (entry === null) return Promise.resolve();
+  const previous = environmentAppendChains.get(taskId) ?? Promise.resolve();
+  const next = previous
+    .catch(() => {})
+    .then(async () => {
+      for (const target of new Set(targets)) {
+        await appendOneViaEnvironment(environment, target, entry);
+      }
+    });
+  environmentAppendChains.set(taskId, next);
+  // Bound the map: forget the chain once it settles as the latest entry.
+  void next.finally(() => {
+    if (environmentAppendChains.get(taskId) === next) {
+      environmentAppendChains.delete(taskId);
+    }
+  });
+  return next;
+}

package/lib/tunnel-registry.ts

@@ -0,0 +1,220 @@
+/**
+ * Tunnel upstreams, plus the frames that arrive before an upstream exists.
+ *
+ * `tunnel.open` is handled ASYNCHRONOUSLY on the host: resolving a target can
+ * await the task lifecycle lock and, for an ad-hoc preview, `docker run` of a
+ * sidecar (ADR-043). The frames that follow it — `tunnel.data`,
+ * `tunnel.requestEnd`, `tunnel.close` — are handled synchronously off the same
+ * WebSocket, and the cloud emits `requestEnd` for a bodyless GET on the tick
+ * after `open`. So they routinely land while the open is still resolving.
+ *
+ * Looking the tunnel up with `tunnels.get(id)?.` silently dropped them, and a
+ * dropped `requestEnd` is unrecoverable rather than merely late. The HTTP open
+ * deliberately leaves its `ClientRequest` unended so request bodies can stream,
+ * and node writes no header until `write`/`end` — so the upstream socket
+ * CONNECTS and then receives nothing at all. On the wire that reads as an
+ * established TCP connection carrying zero bytes, an upstream that never saw a
+ * request, and a flat 30s `504 host did not respond in time` from the cloud's
+ * ack deadline: four symptoms that each point somewhere different, none of them
+ * at the open that never finished.
+ *
+ * So ops for an opening tunnel are QUEUED and replayed on `register`. The
+ * queue is bounded by the request itself — the cloud stops sending once its
+ * ack deadline fires — and is dropped by `abandon` when an open fails, so a
+ * tunnel that never opens leaves nothing behind.
+ */
+
+export interface TunnelUpstream {
+  write(chunk: Buffer): boolean;
+  end(): void;
+  destroy(): void;
+}
+
+type TunnelOp = (upstream: TunnelUpstream) => void;
+type TunnelRelease = () => Promise<void>;
+
+interface OpenTunnel {
+  readonly upstream: TunnelUpstream;
+  readonly release: TunnelRelease;
+}
+
+interface OpeningTunnel {
+  readonly ops: TunnelOp[];
+  readonly settled: Promise<void>;
+  finish(): void;
+  aborted: boolean;
+}
+
+export class TunnelRegistry {
+  private readonly open = new Map<string, OpenTunnel>();
+  /** tunnelId -> ops that arrived while its `tunnel.open` was still resolving. */
+  private readonly opening = new Map<string, OpeningTunnel>();
+  /** Async provider teardown is joined by connection replacement/shutdown. */
+  private readonly pendingReleases = new Set<Promise<void>>();
+
+  /**
+   * Mark a tunnel as opening. MUST be called synchronously when `tunnel.open`
+   * is received — before the first `await` of target resolution — or the frames
+   * that follow have nothing to queue against and are dropped, which is the
+   * whole bug this class exists for.
+   */
+  markOpening(tunnelId: string): void {
+    const previous = this.opening.get(tunnelId);
+    if (previous) {
+      previous.aborted = true;
+      previous.finish();
+    }
+    let finish!: () => void;
+    const settled = new Promise<void>((resolve) => {
+      finish = resolve;
+    });
+    this.opening.set(tunnelId, {
+      ops: [],
+      settled,
+      finish,
+      aborted: false,
+    });
+  }
+
+  /** Target resolved: publish the upstream and replay what arrived meanwhile.
+   * Returns whether this upstream now owns the tunnel — false means the open
+   * was canceled during resolution and the upstream was destroyed, so the
+   * caller must not write to it (a stale generation must never emit bytes). */
+  register(
+    tunnelId: string,
+    upstream: TunnelUpstream,
+    release: TunnelRelease = async () => {},
+  ): boolean {
+    const pending = this.opening.get(tunnelId);
+    this.opening.delete(tunnelId);
+    pending?.finish();
+    const releaseOnce = onceAsync(release);
+    if (pending?.aborted) {
+      upstream.destroy();
+      this.trackRelease(releaseOnce());
+      return false;
+    }
+    this.open.set(tunnelId, { upstream, release: releaseOnce });
+    if (!pending) return true;
+    for (const op of pending.ops) op(upstream);
+    return true;
+  }
+
+  /** Open failed (no target, or it errored) — nothing will ever service these. */
+  abandon(tunnelId: string): void {
+    this.opening.get(tunnelId)?.finish();
+    this.opening.delete(tunnelId);
+  }
+
+  get(tunnelId: string): TunnelUpstream | undefined {
+    return this.open.get(tunnelId)?.upstream;
+  }
+
+  delete(tunnelId: string): void {
+    const current = this.open.get(tunnelId);
+    this.open.delete(tunnelId);
+    if (current) this.trackRelease(current.release());
+  }
+
+  /**
+   * Run `op` against the upstream now, or queue it if the tunnel is still
+   * opening. A tunnel this registry has never heard of is dropped, exactly as
+   * the old `?.` did — that is a frame for a tunnel already torn down, not a
+   * race.
+   */
+  apply(tunnelId: string, op: TunnelOp): void {
+    const current = this.open.get(tunnelId);
+    if (current) {
+      op(current.upstream);
+      return;
+    }
+    const pending = this.opening.get(tunnelId);
+    if (pending && !pending.aborted) pending.ops.push(op);
+  }
+
+  /**
+   * Tear the tunnel down now, or as soon as it opens. Queued ops are discarded
+   * rather than replayed first: they exist to be written to an upstream that is
+   * about to be destroyed, and a `write` after `destroy` is at best wasted and
+   * at worst an unhandled error on a socket nobody is listening to any more.
+   */
+  abort(tunnelId: string): void {
+    const current = this.open.get(tunnelId);
+    this.open.delete(tunnelId);
+    if (current) {
+      current.upstream.destroy();
+      this.trackRelease(current.release());
+      return;
+    }
+    const pending = this.opening.get(tunnelId);
+    if (pending) {
+      pending.ops.length = 0;
+      pending.aborted = true;
+    }
+  }
+
+  /** Destroy every upstream from one bridge generation and wait until opening
+   * targets have either failed or registered and their provider resources are
+   * released. No SSH forward may outlive the WebSocket generation that owns
+   * it — but reconnect must not be hostage to one wedged open, so the join is
+   * bounded: entries are already marked aborted, their eventual register()
+   * destroys the upstream and releases provider resources, and the releases
+   * stay tracked for the next generation's join. */
+  async abortAll(timeoutMs = 15_000): Promise<void> {
+    for (const pending of this.opening.values()) {
+      pending.ops.length = 0;
+      pending.aborted = true;
+    }
+    for (const [tunnelId, current] of this.open) {
+      this.open.delete(tunnelId);
+      current.upstream.destroy();
+      this.trackRelease(current.release());
+    }
+    let timer: NodeJS.Timeout | undefined;
+    const expired = new Promise<"timeout">((resolve) => {
+      timer = setTimeout(() => resolve("timeout"), timeoutMs);
+      timer.unref?.();
+    });
+    try {
+      while (this.opening.size > 0 || this.pendingReleases.size > 0) {
+        const opening = [...this.opening.values()].map((entry) => entry.settled);
+        const outcome = await Promise.race([
+          Promise.all([...opening, ...this.pendingReleases]).then(
+            () => "settled" as const,
+          ),
+          expired,
+        ]);
+        if (outcome === "timeout") {
+          console.warn(
+            `[tunnel] abortAll: ${this.opening.size} opening and ` +
+              `${this.pendingReleases.size} releasing tunnels did not settle ` +
+              `within ${timeoutMs}ms; continuing while they drain`,
+          );
+          return;
+        }
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private trackRelease(release: Promise<void>): void {
+    // A rejected provider release must neither crash the process (a bare
+    // `.finally()` chain rethrows with no handler attached) nor poison the
+    // abortAll() join above — cleanup failure is logged, never fatal.
+    const settled = release.catch((error: unknown) => {
+      console.warn(
+        `[tunnel] upstream release failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    });
+    this.pendingReleases.add(settled);
+    void settled.finally(() => this.pendingReleases.delete(settled));
+  }
+}
+
+function onceAsync(operation: TunnelRelease): TunnelRelease {
+  let result: Promise<void> | null = null;
+  return () => (result ??= operation());
+}