@moondeck/station 0.0.1 → 1.0.1

package/src/engine-usage.ts

@@ -0,0 +1,104 @@
+/**
+ * Build the secret-free account usage report sent to Uai Cloud.
+ *
+ * A leased env account carries both a variable name and its secret value in
+ * runner memory. Billing is deliberately inferred from the NAME alone. Some
+ * file-backed accounts use the same `auth.json` name for a subscription and
+ * an API key, so they carry no hint.
+ *
+ * The hint names the revision it was read from, and is given only when that is
+ * the revision the reporting session runs on: after a re-paste, a lease
+ * refresh can hand the runner newer material than an agent is still using.
+ */
+
+import type { EngineUsageFrame, EngineUsageWindow } from "./protocol";
+
+type EngineUsageBilling = NonNullable<EngineUsageFrame["billing"]>;
+
+export interface LeasedBillingAccount {
+  credentialId: string;
+  revision: string;
+  engineKind: string;
+  authKind: "env" | "config-dir";
+  env: Readonly<Record<string, string>> | null;
+}
+
+export interface EngineUsageObservation {
+  status: EngineUsageFrame["status"];
+  resetsAt?: number;
+  usingOverage?: boolean;
+  windows: EngineUsageWindow[];
+  source: EngineUsageFrame["source"];
+  observedAt: number;
+}
+
+const BILLING_BY_VARIABLE: Readonly<
+  Record<string, Readonly<Record<string, EngineUsageBilling>>>
+> = Object.freeze({
+  claude: Object.freeze({
+    // Capture files every pasted Claude secret that is NOT `sk-ant-api…` under
+    // this name (engine-accounts.ts `pastedSecretMaterial`), so the name alone
+    // also covers a token whose prefix told capture nothing, which the cloud
+    // left unknown. Subscription is still right for a report: usage is read
+    // from a session that worked, and Claude Code authenticates this variable
+    // only as an OAuth (subscription) token, so a session that ran on it was
+    // one. Do not "correct" it to unknown.
+    CLAUDE_CODE_OAUTH_TOKEN: "subscription",
+    ANTHROPIC_API_KEY: "api-key",
+  }),
+  cursor: Object.freeze({ CURSOR_API_KEY: "api-key" }),
+  grok: Object.freeze({ XAI_API_KEY: "api-key" }),
+});
+
+/** The billing lane when one leased variable name tells it unambiguously. */
+export function billingFromLeasedVariableName(
+  account: LeasedBillingAccount | null | undefined,
+): EngineUsageBilling | undefined {
+  if (!account || account.authKind !== "env" || account.env === null) {
+    return undefined;
+  }
+  const names = Object.keys(account.env);
+  if (names.length !== 1) return undefined;
+  return BILLING_BY_VARIABLE[account.engineKind]?.[names[0]!];
+}
+
+/** Construct the exact wire frame for one adapter usage observation.
+ *  `revision` is the one the reporting session runs on; a leased account at
+ *  any other revision gives no hint. */
+export function buildEngineUsageFrame(input: {
+  reportId: string;
+  taskId: string;
+  agentId: string;
+  engine: EngineUsageFrame["engine"];
+  credentialId: string;
+  revision?: string;
+  usage: EngineUsageObservation;
+  leasedAccount?: LeasedBillingAccount | null;
+}): EngineUsageFrame {
+  const { usage } = input;
+  const account =
+    input.revision !== undefined &&
+    input.leasedAccount?.credentialId === input.credentialId &&
+    input.leasedAccount.revision === input.revision &&
+    input.leasedAccount.engineKind === input.engine
+      ? input.leasedAccount
+      : null;
+  const billing = billingFromLeasedVariableName(account);
+  return {
+    kind: "engine.usage",
+    reportId: input.reportId,
+    taskId: input.taskId,
+    agentId: input.agentId,
+    engine: input.engine,
+    credentialId: input.credentialId,
+    ...(billing === undefined ? {} : { billing, revision: account!.revision }),
+    status: usage.status,
+    ...(usage.resetsAt === undefined ? {} : { resetsAt: usage.resetsAt }),
+    ...(usage.usingOverage === undefined
+      ? {}
+      : { usingOverage: usage.usingOverage }),
+    windows: usage.windows,
+    source: usage.source,
+    observedAt: usage.observedAt,
+  };
+}

package/src/enrollment-next-steps.ts

@@ -0,0 +1,24 @@
+/**
+ * What `moondeck-station enroll` / `setup` tells the person to do once the
+ * machine is enrolled. Run by hand, the next step is theirs: install and
+ * start the service, or restart it. Run by the installer (which exports
+ * UAI_FROM_INSTALLER=1 for its enrollment call), the installer registers and
+ * starts the service itself right after, so telling the person to do it was
+ * a stale instruction (the owner's public-install test, 2026-11-03).
+ *
+ * An environment variable rather than a flag: the installer the cloud serves
+ * may run a station runtime older than this one, which ignores an unknown
+ * variable but would refuse an unknown flag.
+ */
+import { STATION } from "./station-identity";
+
+export const FROM_INSTALLER_ENV = "UAI_FROM_INSTALLER";
+
+export function enrollmentNextSteps(env: NodeJS.ProcessEnv = process.env): Array<{ text: string; command?: string; note?: string }> {
+  if (env[FROM_INSTALLER_ENV] === "1") return [];
+  return [
+    { text: "Start the station:" },
+    { text: "", command: `  ${STATION.command} install && ${STATION.command} start`, note: "   (first time)" },
+    { text: "", command: `  ${STATION.command} restart`, note: "                     (already installed)" },
+  ];
+}

package/src/event-outbox.ts

@@ -0,0 +1,185 @@
+/**
+ * ADR-103: the host-side event outbox.
+ *
+ * Every HostEvent gets a monotonic seq and its serialized wire frame is held
+ * here until the cloud acks it. The bridge connection drains the outbox in
+ * order — live traffic and reconnect replay are the same code path, so a
+ * WSS blip (a cloud deploy) can no longer drop events on the floor.
+ *
+ * Bounded, in-memory. A host PROCESS restart still loses unsent events —
+ * that path is ADR-061's (the restarted host reattaches to the container
+ * and resumes streaming); this outbox closes the disconnect gap only.
+ */
+
+import { MAX_OUTBOUND_FRAME_BYTES } from "./outbound-frame";
+import type { HostEvent } from "./protocol";
+
+export interface OutboxEntry {
+  seq: number;
+  /** The full serialized `{kind:"event", seq, event}` frame, ready to send. */
+  raw: string;
+  /** Exact UTF-8 wire bytes retained by this frame. */
+  bytes: number;
+}
+
+export interface EventOutboxSink {
+  readonly bufferedAmount: number;
+  send(raw: string): void;
+}
+
+export type EventOutboxTransmitResult =
+  | "empty"
+  | "backpressured"
+  | "send_failed";
+
+/** Overflow bounds. Generous: a disconnect longer than this many events is a
+ *  real outage, not a deploy blip, and dropping OLDEST keeps the tail — the
+ *  most recent turn — intact for replay. */
+const MAX_ENTRIES = 10_000;
+const MAX_BYTES = 32 * 1024 * 1024;
+// The one ceiling on anything the runner sends (src/outbound-frame.ts), under
+// the authenticated cloud receiver's. Task diffs and message_complete events
+// are not yet field-bounded, so rolling hosts must retain one legitimate
+// frame above the ordinary outbox/transport budgets. Anything larger is
+// refused here, counted as dropped: it would never reach the cloud, and could
+// otherwise put the host into a permanent reconnect loop.
+export const MAX_EVENT_FRAME_BYTES = MAX_OUTBOUND_FRAME_BYTES;
+
+export class EventOutbox {
+  private entries: OutboxEntry[] = [];
+  private totalBytes = 0;
+  private nextSeq = 1;
+  /** Highest seq ever transmitted on any connection. */
+  private sentUpTo = 0;
+  /** Entries dropped by overflow since the last drain — for one loud log. */
+  private droppedSinceDrain = 0;
+
+  /** Serialize + append. Returns the entry's seq. */
+  enqueue(event: HostEvent): number {
+    const seq = this.nextSeq++;
+    const raw = JSON.stringify({ kind: "event", seq, event });
+    const bytes = Buffer.byteLength(raw, "utf8");
+    if (bytes > MAX_EVENT_FRAME_BYTES) {
+      this.droppedSinceDrain += 1;
+      return seq;
+    }
+    this.entries.push({ seq, raw, bytes });
+    this.totalBytes += bytes;
+    while (
+      this.entries.length > MAX_ENTRIES ||
+      (this.totalBytes > MAX_BYTES && this.entries.length > 1)
+    ) {
+      const dropped = this.entries.shift();
+      if (!dropped) break;
+      this.totalBytes -= dropped.bytes;
+      // Only a NEVER-SENT entry is a real loss; an unacked-but-sent one most
+      // likely landed and just lost its ack.
+      if (dropped.seq > this.sentUpTo) this.droppedSinceDrain += 1;
+    }
+    return seq;
+  }
+
+  /** Cumulative ack: forget everything up to and including `seq`. */
+  ack(seq: number): void {
+    let i = 0;
+    for (const entry of this.entries) {
+      if (entry.seq > seq) break;
+      this.totalBytes -= entry.bytes;
+      i += 1;
+    }
+    if (i > 0) this.entries.splice(0, i);
+    if (seq > this.sentUpTo) this.sentUpTo = seq;
+  }
+
+  /**
+   * Rewind the transmit cursor for a reconnect (ADR-103 resume handshake).
+   * `afterSeq` is the cloud's watermark: everything newer re-sends on the
+   * next drain. `null` = the cloud has no state for this boot — replay
+   * nothing; only never-transmitted entries go out.
+   */
+  resume(afterSeq: number | null): void {
+    if (afterSeq !== null && afterSeq < this.sentUpTo) this.sentUpTo = afterSeq;
+  }
+
+  /**
+   * Entries due for transmission, in order. The caller sends them and the
+   * cursor advances — drain is idempotent per entry until `resume` rewinds.
+   */
+  drain(): OutboxEntry[] {
+    const due = this.entries.filter((e) => e.seq > this.sentUpTo);
+    const last = due[due.length - 1];
+    if (last) this.sentUpTo = last.seq;
+    return due;
+  }
+
+  /** Oldest due entry without advancing the transmit cursor. */
+  nextDue(): OutboxEntry | null {
+    return this.entries.find((entry) => entry.seq > this.sentUpTo) ?? null;
+  }
+
+  /** Advance only the exact next due entry after the caller queues it. */
+  markSent(seq: number): boolean {
+    const due = this.nextDue();
+    if (!due || due.seq !== seq) return false;
+    this.sentUpTo = seq;
+    return true;
+  }
+
+  /** Never-sent entries lost to overflow since the last call; resets. */
+  takeDroppedCount(): number {
+    const n = this.droppedSinceDrain;
+    this.droppedSinceDrain = 0;
+    return n;
+  }
+
+  get size(): number {
+    return this.entries.length;
+  }
+
+  get bytes(): number {
+    return this.totalBytes;
+  }
+}
+
+/**
+ * Queue due frames only until the transport reaches its high-water mark.
+ * Entries advance one at a time after `send` accepts them, so a slow socket
+ * leaves the remainder replayable in the bounded outbox instead of moving the
+ * whole backlog into the WebSocket implementation's own buffer.
+ */
+export function transmitEventOutbox(
+  outbox: EventOutbox,
+  sink: EventOutboxSink,
+  maxBufferedBytes: number,
+): EventOutboxTransmitResult {
+  let projectedBufferedBytes = sink.bufferedAmount;
+  while (true) {
+    const entry = outbox.nextDue();
+    if (!entry) return "empty";
+    if (
+      maxBufferedBytes <= 0 ||
+      (projectedBufferedBytes > 0 &&
+        (projectedBufferedBytes >= maxBufferedBytes ||
+          entry.bytes > maxBufferedBytes - projectedBufferedBytes))
+    ) {
+      return "backpressured";
+    }
+    try {
+      sink.send(entry.raw);
+    } catch {
+      return "send_failed";
+    }
+    if (!outbox.markSent(entry.seq)) return "send_failed";
+    projectedBufferedBytes = Math.max(
+      sink.bufferedAmount,
+      projectedBufferedBytes + entry.bytes,
+    );
+
+    // A rolling-compatible frame above the normal high-water budget gets one
+    // empty transport to itself. Do not depend on a sink updating
+    // `bufferedAmount` synchronously before protecting the following frame.
+    if (entry.bytes > maxBufferedBytes) {
+      return outbox.nextDue() ? "backpressured" : "empty";
+    }
+  }
+}