@rallycry/conveyor-mcp 4.3.28 → 4.3.30

package/dist/tunnel.js

@@ -2,10 +2,9 @@ import {
   attachTunnel,
   runTunnel,
   waitForPtySession
-} from "./chunk-N2XC2PGJ.js";
+} from "./chunk-HIVOGGE3.js";
 export {
   attachTunnel,
   runTunnel,
   waitForPtySession
 };
-//# sourceMappingURL=tunnel.js.map

package/dist/wait-cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/wait-cli.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+import {
+  ConveyorConnection
+} from "./chunk-X3EHPZNH.js";
+import {
+  runWait
+} from "./chunk-OPZL4NDT.js";
+import {
+  DEFAULT_WAIT_SCOPES,
+  DEFAULT_WAIT_STATUSES,
+  DEFAULT_WAIT_TYPES,
+  parseWaitScopes,
+  parseWaitStatuses,
+  parseWaitTypes
+} from "./chunk-D3Q2QZJA.js";
+
+// src/wait-cli.ts
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import { sep } from "path";
+
+// src/wait-config.ts
+var TOKEN_KEYS = ["CONVEYOR_USER_TOKEN", "CONVEYOR_PROJECT_TOKEN"];
+var MAX_ANCESTORS = 24;
+function parseJson(raw) {
+  if (raw === null) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value;
+}
+function extractConveyorEnv(config) {
+  const root = asRecord(config);
+  const servers = asRecord(root?.mcpServers);
+  if (!servers) return null;
+  for (const [name, raw] of Object.entries(servers)) {
+    const server = asRecord(raw);
+    if (!server) continue;
+    const args2 = Array.isArray(server.args) ? server.args.filter((a) => typeof a === "string") : [];
+    const haystack = [name, String(server.command ?? ""), ...args2].join(" ");
+    if (!/conveyor/i.test(haystack)) continue;
+    const env = asRecord(server.env);
+    if (!env) continue;
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+      if (typeof value === "string") out[key] = value;
+    }
+    if (Object.keys(out).length > 0) return out;
+  }
+  return null;
+}
+function ancestorDirs(cwd, sep2) {
+  const out = [];
+  let current = cwd;
+  for (let i = 0; i < MAX_ANCESTORS; i++) {
+    out.push(current);
+    const cut = current.lastIndexOf(sep2);
+    if (cut < 0) break;
+    const parent = cut === 0 ? sep2 : current.slice(0, cut);
+    if (parent === current) break;
+    current = parent;
+  }
+  return out;
+}
+function fill(credentials2, env, source) {
+  const assign = (field, key) => {
+    if (credentials2[field] !== void 0) return;
+    const value = env[key];
+    if (value) {
+      credentials2[field] = value;
+      credentials2.sources[field] = source;
+    }
+  };
+  assign("apiUrl", "CONVEYOR_API_URL");
+  assign("projectId", "CONVEYOR_PROJECT_ID");
+  assign("subProjectId", "CONVEYOR_SUBPROJECT_ID");
+  if (credentials2.token === void 0) {
+    for (const key of TOKEN_KEYS) {
+      const value = env[key];
+      if (value) {
+        credentials2.token = value;
+        credentials2.sources.token = `${source} (${key})`;
+        break;
+      }
+    }
+  }
+}
+function resolveWaitCredentials(deps) {
+  const sep2 = deps.sep ?? "/";
+  const credentials2 = { sources: {} };
+  fill(credentials2, deps.env, "environment");
+  const dirs = ancestorDirs(deps.cwd, sep2);
+  for (const dir of dirs) {
+    const path = dir.endsWith(sep2) ? `${dir}.mcp.json` : `${dir}${sep2}.mcp.json`;
+    const env = extractConveyorEnv(parseJson(deps.readFile(path)));
+    if (env) fill(credentials2, env, path);
+  }
+  const claudeConfig = parseJson(
+    deps.readFile(
+      deps.homeDir.endsWith(sep2) ? `${deps.homeDir}.claude.json` : `${deps.homeDir}${sep2}.claude.json`
+    )
+  );
+  const projects = asRecord(claudeConfig?.projects);
+  if (projects) {
+    for (const dir of dirs) {
+      const env = extractConveyorEnv(projects[dir]);
+      if (env) fill(credentials2, env, `~/.claude.json (${dir})`);
+    }
+  }
+  return credentials2;
+}
+function describeMissingCredentials(credentials2) {
+  const missing = [];
+  if (!credentials2.apiUrl) missing.push("CONVEYOR_API_URL");
+  if (!credentials2.token) missing.push("CONVEYOR_USER_TOKEN (or legacy CONVEYOR_PROJECT_TOKEN)");
+  return `conveyor-wait found no Conveyor credentials. Missing: ${missing.join(", ")}.
+It looked at the environment, every .mcp.json from the working directory up, and ~/.claude.json.
+Fix it by exporting the values, or by adding a "conveyor" entry to .mcp.json. Mint a token in the web app under User Settings \u2192 Connect your coding agent.`;
+}
+
+// src/wait-cli.ts
+var HELP = `conveyor-wait \u2014 block until a card becomes actionable on your board.
+
+Exits as soon as a card ENTERS the filtered state, or at the timeout. Run it in
+the background and let its completion be your wake signal instead of polling.
+
+Usage:
+  conveyor-wait [options]
+
+Options:
+  --types <list>      Card kinds to watch: task, incident, suggestion, chat, all.
+                      Default: ${DEFAULT_WAIT_TYPES.join(",")}
+  --scope <list>      Assignment scopes: mine, unclaimed, all.
+                      Default: ${DEFAULT_WAIT_SCOPES.join(",")}
+  --statuses <list>   Statuses to watch. Default: ${DEFAULT_WAIT_STATUSES.join(",")}
+  --timeout <secs>    Give up and exit 0 after this long. Default: 1740 (29m).
+  --project <id>      Project to watch. Defaults to the configured project.
+  -h, --help          Show this help.
+
+Output:
+  One line of JSON on stdout, always. Human-facing progress goes to stderr.
+    {"reason":"event","card":{"id":\u2026,"slug":\u2026,"title":\u2026,"type":\u2026,"status":\u2026,"assignedUserId":\u2026}}
+    {"reason":"timeout"}
+    {"reason":"interrupted"}
+  Exit 0 in all three cases \u2014 only a configuration or auth failure exits 1.
+
+Credentials:
+  Read from CONVEYOR_API_URL, CONVEYOR_USER_TOKEN (or legacy
+  CONVEYOR_PROJECT_TOKEN), and CONVEYOR_PROJECT_ID. When those are unset, the
+  CLI falls back to any .mcp.json from the working directory up, then to
+  ~/.claude.json \u2014 so it works from an agent shell that never saw the MCP
+  server's environment.
+
+The card in the trigger is advisory. Re-read the board before acting on it: by
+the time you wake, someone else may already have claimed it.
+`;
+var DEFAULT_TIMEOUT_SECONDS = 1740;
+var MAX_TIMEOUT_MS = 2147483647;
+var VALUE_FLAGS = {
+  "--types": "types",
+  "--type": "types",
+  "--scope": "scope",
+  "--scopes": "scope",
+  "--statuses": "statuses",
+  "--status": "statuses",
+  "--timeout": "timeout",
+  "--project": "project",
+  "--project-id": "project"
+};
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      out.help = true;
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    if (arg.startsWith("--") && eq !== -1) {
+      const key = VALUE_FLAGS[arg.slice(0, eq)];
+      if (key) out[key] = arg.slice(eq + 1);
+      continue;
+    }
+    const valueKey = VALUE_FLAGS[arg];
+    if (valueKey) out[valueKey] = argv[++i];
+  }
+  return out;
+}
+var log = (message) => {
+  process.stderr.write(`${message}
+`);
+};
+function emitResult(result, done) {
+  process.stdout.write(`${JSON.stringify(result)}
+`, () => done());
+}
+var args = parseArgs(process.argv.slice(2));
+if (args.help) {
+  process.stderr.write(HELP);
+  process.exit(0);
+}
+var filter;
+var timeoutMs;
+try {
+  filter = {
+    types: parseWaitTypes(args.types),
+    scopes: parseWaitScopes(args.scope),
+    statuses: parseWaitStatuses(args.statuses)
+  };
+  const seconds = args.timeout === void 0 ? DEFAULT_TIMEOUT_SECONDS : Number(args.timeout);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    throw new Error(`--timeout must be a positive number of seconds, got "${args.timeout}".`);
+  }
+  timeoutMs = Math.min(Math.round(seconds * 1e3), MAX_TIMEOUT_MS);
+} catch (err) {
+  log(`Error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+}
+var credentials = resolveWaitCredentials({
+  env: process.env,
+  cwd: process.cwd(),
+  homeDir: homedir(),
+  sep,
+  readFile: (path) => {
+    try {
+      return readFileSync(path, "utf8");
+    } catch {
+      return null;
+    }
+  }
+});
+if (!credentials.apiUrl || !credentials.token) {
+  log(describeMissingCredentials(credentials));
+  process.exit(1);
+}
+var conn = new ConveyorConnection({
+  apiUrl: credentials.apiUrl,
+  projectToken: credentials.token,
+  projectId: args.project ?? credentials.projectId,
+  subProjectId: credentials.subProjectId
+});
+var exiting = false;
+function shutdown(code) {
+  exiting = true;
+  conn.disconnect();
+  process.exit(code);
+}
+function interrupt() {
+  if (exiting) return;
+  exiting = true;
+  emitResult({ reason: "interrupted" }, () => shutdown(0));
+}
+process.on("SIGINT", interrupt);
+process.on("SIGTERM", interrupt);
+try {
+  await conn.connect();
+} catch (err) {
+  log(`Failed to connect to Conveyor: ${err instanceof Error ? err.message : String(err)}`);
+  shutdown(1);
+}
+var projectId = args.project ?? credentials.projectId;
+if (!projectId) {
+  try {
+    const projects = await conn.listProjects();
+    const ids = projects.map((project) => project.id).filter((id) => typeof id === "string");
+    if (ids.length === 1) {
+      projectId = ids[0];
+      log(`Watching the only accessible project: ${projectId}`);
+    }
+  } catch {
+  }
+}
+if (!projectId) {
+  log(
+    "Error: no project to watch. Set CONVEYOR_PROJECT_ID or pass --project <id>. Your token can reach more than one project, so conveyor-wait cannot pick for you."
+  );
+  shutdown(1);
+}
+var userId = null;
+try {
+  const context = await conn.getConnectionContext(projectId);
+  userId = context.account.userId;
+} catch (err) {
+  if (filter.scopes.includes("mine")) {
+    log(
+      `Failed to resolve the connected account, which --scope mine needs: ${err instanceof Error ? err.message : String(err)}`
+    );
+    shutdown(1);
+  }
+}
+log(
+  `Waiting up to ${Math.round(timeoutMs / 1e3)}s for a ${filter.statuses.join("/")} ${filter.types.join("/")} card in scope ${filter.scopes.join("+")}.`
+);
+try {
+  const result = await runWait({
+    source: conn,
+    projectId,
+    filter: { ...filter, userId },
+    timeoutMs,
+    log
+  });
+  emitResult(result, () => shutdown(0));
+} catch (err) {
+  log(`Wait failed: ${err instanceof Error ? err.message : String(err)}`);
+  shutdown(1);
+}

package/dist/wait-runner.d.ts

@@ -0,0 +1,48 @@
+import { C as CardCollectionPage, a as CardCollectionDelta } from './connection-CRkBLz5w.js';
+import { WaitFilter, WaitResult } from './wait.js';
+
+/**
+ * `conveyor-wait` runner — the live half of the engine.
+ *
+ * `wait.ts` decides what "matching" means; this module owns the socket-shaped
+ * lifecycle around it: seed from a paged snapshot, apply deltas, re-snapshot
+ * after a `reset` or a reconnect, and settle on the first card that enters the
+ * filter (or on the deadline).
+ *
+ * It talks to a narrow `CardCollectionSource` rather than a socket, so the
+ * reconnect, reset, and paging paths are unit-testable without a server.
+ */
+
+/**
+ * The slice of `ConveyorConnection` the engine needs. `ConveyorConnection`
+ * satisfies it structurally; tests pass a fake.
+ */
+interface CardCollectionSource {
+    subscribeToCardCollection(projectId: string, opts?: {
+        cursor?: string | null;
+        limit?: number;
+    }): Promise<CardCollectionPage>;
+    onCardDelta(projectId: string, handler: (delta: CardCollectionDelta) => void): () => void;
+    onReconnect(handler: () => void): () => void;
+}
+interface RunWaitOptions {
+    source: CardCollectionSource;
+    projectId: string;
+    filter: WaitFilter;
+    timeoutMs: number;
+    pageLimit?: number;
+    maxPages?: number;
+    /** Backoff between re-snapshot attempts. Overridable so tests stay fast. */
+    resyncRetryDelayMs?: number;
+    /** Human-facing progress, written to stderr by the CLI. */
+    log?: (message: string) => void;
+}
+/**
+ * Resolve with the first card that enters matching state, or with
+ * `{ reason: "timeout" }` at the deadline. Rejects only when the snapshot
+ * itself fails (bad project id, revoked access) — a caller that gets a
+ * rejection should exit non-zero rather than keep waiting.
+ */
+declare function runWait(options: RunWaitOptions): Promise<WaitResult>;
+
+export { type CardCollectionSource, type RunWaitOptions, runWait };

package/dist/wait-runner.js

@@ -0,0 +1,7 @@
+import {
+  runWait
+} from "./chunk-OPZL4NDT.js";
+import "./chunk-D3Q2QZJA.js";
+export {
+  runWait
+};

package/dist/wait.d.ts

@@ -0,0 +1,108 @@
+import { b as CardCollectionItem } from './connection-CRkBLz5w.js';
+
+/**
+ * `conveyor-wait` engine — block until a card becomes actionable on a board.
+ *
+ * The API already fans every card write out as a quickdraw collection delta on
+ * `taskService`'s `cardsByProject` scope. This module subscribes to that scope,
+ * holds the set of card ids that ALREADY match the caller's filter, and reports
+ * the first card that *enters* matching state.
+ *
+ * Two wire facts drive the design and are easy to get wrong:
+ * - **Creates arrive as `updated` deltas.** Most card writes go through the
+ *   service's hand-rolled upsert choke point, which always emits `updated`.
+ *   "New work" is therefore a set diff, never a delta-type check.
+ * - **The snapshot ack is one PAGE, not the scope.** `cardsByProject` omits
+ *   `ids` (the scope is unbounded), so seeding walks `nextCursor` to the end.
+ *   When the walk is capped we merge instead of replacing, because dropping an
+ *   unseen id would make it look newly-matching on the next delta.
+ *
+ * The live half — snapshot paging, reconnect, and settling — lives in
+ * `wait-runner.ts`; this module is the pure filter and set-diff logic it uses.
+ */
+
+/** Card kinds `--types` accepts. Mirrors `CardType` in @project/shared. */
+declare const WAIT_CARD_TYPES: readonly ["task", "incident", "suggestion", "chat"];
+type WaitCardType = (typeof WAIT_CARD_TYPES)[number];
+/** Assignment scopes `--scope` accepts. `all` disables the assignee filter. */
+declare const WAIT_SCOPES: readonly ["mine", "unclaimed", "all"];
+type WaitScope = (typeof WAIT_SCOPES)[number];
+/**
+ * Canonical card statuses. Kept in lockstep with the unified status list in
+ * @project/shared — conveyor-mcp publishes standalone and does not depend on
+ * the shared package, so the vocabulary is duplicated here.
+ */
+declare const WAIT_STATUSES: readonly ["Planning", "Open", "InProgress", "ReviewPR", "ReviewDev", "ReviewLive", "Complete", "Cancelled"];
+/** Chat cards are excluded by default — they are conversations, not queue work. */
+declare const DEFAULT_WAIT_TYPES: WaitCardType[];
+declare const DEFAULT_WAIT_SCOPES: WaitScope[];
+/** `Open` is the claimable lane: identified, planned enough to start, unbuilt. */
+declare const DEFAULT_WAIT_STATUSES: string[];
+interface WaitFilter {
+    types: WaitCardType[];
+    scopes: WaitScope[];
+    statuses: string[];
+    /** The connected account, resolved at startup. `mine` never matches without it. */
+    userId: string | null;
+}
+/** The card fields conveyor-wait filters on and prints — a subset of `TaskCardDTO`. */
+interface WaitCard {
+    id: string;
+    slug: string | null;
+    title: string | null;
+    type: string | null;
+    status: string | null;
+    assignedUserId: string | null;
+}
+type WaitResult = {
+    reason: "event";
+    card: WaitCard;
+} | {
+    reason: "timeout";
+};
+/**
+ * Parse `--types`. Accepts singular or plural (`incident`/`incidents`) and
+ * `all`. Throws on an unknown kind rather than silently never matching.
+ */
+declare function parseWaitTypes(value: string | undefined): WaitCardType[];
+/** Parse `--scope`. `all` short-circuits: it subsumes every other scope. */
+declare function parseWaitScopes(value: string | undefined): WaitScope[];
+/** Parse `--statuses` into canonical casing. Unknown statuses are an error. */
+declare function parseWaitStatuses(value: string | undefined): string[];
+/**
+ * Project a collection item down to the fields we filter on. `assignedUserId`
+ * is derived from the nested `assignedUser` relation — `TaskCardDTO` has no
+ * flat assignee id.
+ */
+declare function toWaitCard(item: CardCollectionItem): WaitCard;
+declare function matchesFilter(card: WaitCard, filter: WaitFilter): boolean;
+/**
+ * The held set of already-matching card ids. Everything the CLI reports is a
+ * transition INTO this set — a card that was already matching and merely got
+ * edited is not new work, and a card that stops matching is not either.
+ */
+declare class MatchSet {
+    private readonly filter;
+    private readonly matched;
+    constructor(filter: WaitFilter);
+    get size(): number;
+    has(id: string): boolean;
+    /** Seed from the first snapshot. Pre-existing matches never trigger. */
+    seed(cards: WaitCard[]): void;
+    /**
+     * Re-seed after a `reset` delta or a reconnect gap, returning every card
+     * that entered matching state while we were not listening.
+     *
+     * `complete` says whether the snapshot walk reached the end of the scope.
+     * When it did not, ids we no longer see are merged forward rather than
+     * dropped — forgetting a still-matching card would re-report it as new on
+     * its next delta.
+     */
+    reseed(cards: WaitCard[], complete?: boolean): WaitCard[];
+    /** Apply an `added`/`updated` delta. Returns the card only on entry. */
+    upsert(card: WaitCard): WaitCard | null;
+    /** Apply a `removed` delta. A deleted card is never new work. */
+    remove(id: string): void;
+}
+
+export { DEFAULT_WAIT_SCOPES, DEFAULT_WAIT_STATUSES, DEFAULT_WAIT_TYPES, MatchSet, WAIT_CARD_TYPES, WAIT_SCOPES, WAIT_STATUSES, type WaitCard, type WaitCardType, type WaitFilter, type WaitResult, type WaitScope, matchesFilter, parseWaitScopes, parseWaitStatuses, parseWaitTypes, toWaitCard };

package/dist/wait.js

@@ -0,0 +1,28 @@
+import {
+  DEFAULT_WAIT_SCOPES,
+  DEFAULT_WAIT_STATUSES,
+  DEFAULT_WAIT_TYPES,
+  MatchSet,
+  WAIT_CARD_TYPES,
+  WAIT_SCOPES,
+  WAIT_STATUSES,
+  matchesFilter,
+  parseWaitScopes,
+  parseWaitStatuses,
+  parseWaitTypes,
+  toWaitCard
+} from "./chunk-D3Q2QZJA.js";
+export {
+  DEFAULT_WAIT_SCOPES,
+  DEFAULT_WAIT_STATUSES,
+  DEFAULT_WAIT_TYPES,
+  MatchSet,
+  WAIT_CARD_TYPES,
+  WAIT_SCOPES,
+  WAIT_STATUSES,
+  matchesFilter,
+  parseWaitScopes,
+  parseWaitStatuses,
+  parseWaitTypes,
+  toWaitCard
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycry/conveyor-mcp",
-  "version": "4.3.28",
+  "version": "4.3.30",
   "description": "Conveyor MCP server for Claude Code PM integration",
   "keywords": [
     "claude",
@@ -11,7 +11,8 @@
   "license": "MIT",
   "bin": {
     "conveyor-mcp": "dist/cli.js",
-    "conveyor-tunnel": "dist/tunnel-cli.js"
+    "conveyor-tunnel": "dist/tunnel-cli.js",
+    "conveyor-wait": "dist/wait-cli.js"
   },
   "files": [
     "dist"

package/dist/chunk-N2XC2PGJ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/tunnel.ts"],"sourcesContent":["import type { ActivePtySession, PtyAttachSnapshot, PtyDataChunk } from \"./connection.js\";\n\n/** ETX (Ctrl-C) byte. In raw mode this arrives as data rather than SIGINT. */\nconst ETX = 0x03;\n\n/**\n * The slice of {@link ConveyorConnection} the tunnel needs. Defined as a\n * structural interface so tests can inject a mock — and, deliberately, so the\n * relay has NO reference to `stopBuild`. Detaching the local terminal must\n * never stop the cloud session, and the cleanest way to guarantee that is to\n * make stopping unreachable from this layer.\n */\nexport interface TunnelConnection {\n  createTask(params: {\n    title: string;\n    description?: string;\n    plan?: string;\n    status?: string;\n  }): Promise<{ id: string; slug: string }>;\n  startBuild(taskId: string): Promise<{ taskId: string; status: string }>;\n  getActivePtySession(taskId: string): Promise<ActivePtySession>;\n  ptyAttach(sessionId: string): Promise<PtyAttachSnapshot>;\n  subscribeToSession(sessionId: string): void;\n  ptyInput(sessionId: string, data: string): void;\n  ptyResize(sessionId: string, cols: number, rows: number): void;\n  onPtyData(handler: (chunk: PtyDataChunk) => void): () => void;\n}\n\n/**\n * Local terminal abstraction. The CLI binds this to the real process TTY; tests\n * bind it to an in-memory fake. All output is raw utf8 (node-pty does not use\n * base64), matching the S2 relay encoding.\n */\nexport interface TunnelTty {\n  /** Write raw PTY output to the local terminal. */\n  write(data: string): void;\n  /** Register a stdin handler. Returns an unsubscribe function. */\n  onInput(handler: (data: Buffer) => void): () => void;\n  /** Register a resize handler. Returns an unsubscribe function. */\n  onResize(handler: (cols: number, rows: number) => void): () => void;\n  /** Current local terminal dimensions. */\n  size(): { cols: number; rows: number };\n}\n\n/** A live tunnel attachment. */\nexport interface TunnelHandle {\n  sessionId: string;\n  /**\n   * Tear down the local relay (stdin/resize/output listeners). Does NOT stop\n   * the cloud build — the session keeps running after detach. Idempotent.\n   */\n  detach(): void;\n}\n\n/** Resolved (non-null) active PTY session. */\nexport interface ResolvedPtySession {\n  sessionId: string;\n  cols?: number;\n  rows?: number;\n}\n\nconst defaultSleep = (ms: number): Promise<void> =>\n  new Promise((resolve) => {\n    setTimeout(resolve, ms);\n  });\n\nexport interface WaitForPtySessionOptions {\n  intervalMs?: number;\n  timeoutMs?: number;\n  log?: (msg: string) => void;\n  /** Injectable for tests; defaults to a real timer. */\n  sleep?: (ms: number) => Promise<void>;\n}\n\n/**\n * Poll {@link TunnelConnection.getActivePtySession} until the cloud agent has\n * booted its PTY and produced at least one ring frame. `sessionId` is resolved\n * server-side from `taskId`, so the local side never invents or supplies one.\n */\nexport async function waitForPtySession(\n  conn: TunnelConnection,\n  taskId: string,\n  options: WaitForPtySessionOptions = {},\n): Promise<ResolvedPtySession> {\n  const intervalMs = options.intervalMs ?? 2000;\n  const timeoutMs = options.timeoutMs ?? 5 * 60_000;\n  const sleep = options.sleep ?? defaultSleep;\n  const deadline = Date.now() + timeoutMs;\n\n  for (;;) {\n    const active = await conn.getActivePtySession(taskId);\n    if (active.sessionId) {\n      return { sessionId: active.sessionId, cols: active.cols, rows: active.rows };\n    }\n    if (Date.now() >= deadline) {\n      throw new Error(\n        `Timed out after ${timeoutMs}ms waiting for the cloud PTY session to become ready`,\n      );\n    }\n    await sleep(intervalMs);\n  }\n}\n\nexport interface AttachTunnelOptions {\n  /**\n   * Called when the local user requests a detach (Ctrl-C / ETX in the input\n   * stream). When provided, the ETX byte is intercepted and NOT forwarded to\n   * the cloud PTY; when omitted, all input passes through unmodified.\n   */\n  onDetachRequest?: () => void;\n}\n\n/**\n * Attach the local TTY to a cloud PTY session, reusing the S2 `pty:*` relay\n * envelope. Replays the ring snapshot then streams live frames, with the same\n * seq-based dedup the web `PtyTerminal` uses so no bytes are dropped or doubled\n * across the attach boundary.\n */\nexport async function attachTunnel(\n  conn: TunnelConnection,\n  session: ResolvedPtySession,\n  tty: TunnelTty,\n  options: AttachTunnelOptions = {},\n): Promise<TunnelHandle> {\n  const { sessionId } = session;\n  let attached = false;\n  let lastSeq = -1;\n  const liveBuffer: PtyDataChunk[] = [];\n\n  const writeChunk = (chunk: { seq: number; data: string }): void => {\n    tty.write(chunk.data);\n    if (chunk.seq > lastSeq) lastSeq = chunk.seq;\n  };\n\n  // 1. Register the output handler and join the room BEFORE fetching the\n  //    snapshot. Frames that arrive during the fetch are buffered, never lost.\n  const offData = conn.onPtyData((chunk) => {\n    if (chunk.sessionId !== sessionId) return;\n    if (!attached) {\n      liveBuffer.push(chunk);\n      return;\n    }\n    if (chunk.seq <= lastSeq) return;\n    writeChunk(chunk);\n  });\n  conn.subscribeToSession(sessionId);\n\n  // 2. Replay the ring snapshot (skip anything already seen).\n  const snapshot = await conn.ptyAttach(sessionId);\n  for (const chunk of snapshot.chunks) {\n    if (chunk.seq > lastSeq) writeChunk(chunk);\n  }\n\n  // 3. Flush frames buffered during the fetch, then go live.\n  attached = true;\n  for (const chunk of liveBuffer) {\n    if (chunk.seq > lastSeq) writeChunk(chunk);\n  }\n  liveBuffer.length = 0;\n\n  // 4. Wire local stdin → cloud PTY (raw utf8). Intercept ETX for detach.\n  const offInput = tty.onInput((data) => {\n    if (options.onDetachRequest) {\n      const idx = data.indexOf(ETX);\n      if (idx !== -1) {\n        if (idx > 0) conn.ptyInput(sessionId, data.subarray(0, idx).toString(\"utf8\"));\n        options.onDetachRequest();\n        return;\n      }\n    }\n    conn.ptyInput(sessionId, data.toString(\"utf8\"));\n  });\n\n  // 5. Wire resize → cloud PTY, and push the current size now so the cloud TUI\n  //    repaints to the local viewport dimensions.\n  const offResize = tty.onResize((cols, rows) => {\n    conn.ptyResize(sessionId, cols, rows);\n  });\n  const initial = tty.size();\n  conn.ptyResize(sessionId, initial.cols, initial.rows);\n\n  let detached = false;\n  return {\n    sessionId,\n    detach() {\n      if (detached) return;\n      detached = true;\n      offInput();\n      offResize();\n      offData();\n      // Intentionally NO stopBuild here: detach != stop. The cloud session\n      // continues running so the agent's work is never interrupted by the\n      // local terminal disconnecting.\n    },\n  };\n}\n\nexport interface RunTunnelOptions {\n  /** Reuse an existing task instead of creating a new card. */\n  taskId?: string;\n  /** Card fields (used only when `taskId` is not supplied). */\n  title?: string;\n  description?: string;\n  plan?: string;\n  pollIntervalMs?: number;\n  pollTimeoutMs?: number;\n  log?: (msg: string) => void;\n  sleep?: (ms: number) => Promise<void>;\n  onDetachRequest?: () => void;\n  /**\n   * Invoked once the PTY session is ready, immediately before attaching. The\n   * CLI uses this to enable raw TTY mode only at the last moment — before this\n   * point Ctrl-C should still raise SIGINT so the user can abort the wait.\n   */\n  onReady?: (session: ResolvedPtySession) => void;\n}\n\nexport interface TunnelSession {\n  taskId: string;\n  sessionId: string;\n  handle: TunnelHandle;\n}\n\n/**\n * End-to-end flow: (optionally) create a cloud card, start the build, wait for\n * the cloud PTY to come up, then attach the local terminal. Returns once the\n * relay is live; the caller keeps the process alive and calls `handle.detach()`.\n */\nexport async function runTunnel(\n  conn: TunnelConnection,\n  tty: TunnelTty,\n  options: RunTunnelOptions = {},\n): Promise<TunnelSession> {\n  const log = options.log ?? (() => {});\n\n  let taskId = options.taskId;\n  if (!taskId) {\n    const title = options.title;\n    if (!title) throw new Error(\"A task title is required to create a new cloud card\");\n    log(\"Creating cloud card…\");\n    const task = await conn.createTask({\n      title,\n      description: options.description,\n      plan: options.plan,\n    });\n    taskId = task.id;\n    log(`Created card ${task.slug} (${task.id})`);\n  }\n\n  log(\"Starting cloud build…\");\n  await conn.startBuild(taskId);\n\n  log(\"Waiting for the cloud PTY session to become ready…\");\n  const session = await waitForPtySession(conn, taskId, {\n    intervalMs: options.pollIntervalMs,\n    timeoutMs: options.pollTimeoutMs,\n    log,\n    sleep: options.sleep,\n  });\n  log(`Cloud PTY session ready: ${session.sessionId}`);\n\n  options.onReady?.(session);\n\n  const handle = await attachTunnel(conn, session, tty, {\n    onDetachRequest: options.onDetachRequest,\n  });\n  log(\"Attached. Press Ctrl-C to detach (the cloud session keeps running).\");\n\n  return { taskId, sessionId: session.sessionId, handle };\n}\n"],"mappings":"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","names":[]}