tinker-agent 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [2.10.0] - 2026-09-06
+
+### Added
+
+- Add remote access for paired clients. `tinker serve --config <path>` runs the
+  local daemon that paired remote clients connect to, and
+  `tinker connect --config <path>` attaches a terminal client to a running
+  service; exiting the client detaches without stopping the service. See
+  `docs/remote-access.md`. A native iOS client under `client/Tinker` is included
+  for acceptance.
+- Add `offset` and `head_limit` pagination to `Glob` results. Long result sets
+  now report whether more matches remain instead of being silently capped.
+- Add `cols` and `rows` options to `Bash` for custom initial PTY dimensions when
+  `tty=true`, so terminal applications that require a specific size can run in
+  an appropriately sized pseudo-terminal.
+
+### Changed
+
+- Run `Grep` directory searches with ripgrep's working directory set to the search
+  directory and `.` as the path argument. Directory globs such as `sub/**` now
+  match from that directory; globs that relied on absolute search paths may need
+  updating. Explicit file searches keep their existing invocation.
+- Increase the default `Bash` foreground wait before a command continues in the
+  background, and clarify how `TaskOutput` and `TaskInput` poll PTY sessions.
+- Omit internal file hashes from tool observations; the model sees the same
+  content without opaque bookkeeping tokens.
+
+### Fixed
+
+- Stop `TaskStop` from hanging when a shell's child processes survive after the
+  shell itself exits; stopping a task now reliably reports its final state.
+- Preserve `Grep` match context across paginated results, keep long-line matches
+  instead of dropping them, and report counts and paginated records
+  consistently, including a `count-matches` mode with explicit counting units.
+- Resolve symbolic-link search roots in `Glob` while preserving result paths,
+  and exclude directory and broken symbolic links from results.
+- Accept pagination arguments in `Read` when reading empty files instead of
+  rejecting the call.
+
 ## [2.9.0] - 2026-09-05
 
 ### Added
@@ -398,7 +437,8 @@ All notable user-facing changes to Tinker are documented here. The project follo
 - First formal npm release under the `tinker-agent` package name with the `tinker`
   executable.
 
-[Unreleased]: https://github.com/ishowshao/tinker/compare/v2.9.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v2.10.0...HEAD
+[2.10.0]: https://github.com/ishowshao/tinker/releases/tag/v2.10.0
 [2.9.0]: https://github.com/ishowshao/tinker/releases/tag/v2.9.0
 [2.8.0]: https://github.com/ishowshao/tinker/releases/tag/v2.8.0
 [2.7.0]: https://github.com/ishowshao/tinker/releases/tag/v2.7.0

package/README.md

@@ -34,6 +34,20 @@ This does not pretend that any model has infinite tokens or guarantee that it wi
   explicit model and context limits. Actual provider support must be established
   by a qualification matrix; transport compatibility alone is not a guarantee.
 
+### PTY screen size
+
+`Bash` accepts optional `cols` and `rows` for the initial PTY screen size:
+
+```json
+{"command":"python3 -q","tty":true,"cols":160,"rows":48}
+```
+
+Each omitted dimension keeps its default: 80 columns and 24 rows. Columns accept
+integers from 2 to 1000; rows accept integers from 1 to 1000. When `tty` is omitted
+or `false`, dimensions are ignored and execution continues through ordinary pipes.
+`TaskOutput` and `TaskInput` report the actual screen size. Dimensions are set at
+creation; running tasks cannot be resized through these tools.
+
 ### Reading another session's history
 
 Both Recall tools accept an optional `sessionId` (a canonical session UUID).
@@ -158,6 +172,8 @@ The installed package exposes this public CLI:
 | `tinker run [--profile <profile-name>] [--yolo] --stdin` | Read the prompt from standard input until EOF. |
 | `tinker run [--profile <profile-name>] [--yolo] --file <path>` | Read the prompt from a UTF-8 text file. |
 | `tinker update` | Update the global npm installation from the official npm registry. |
+| `tinker serve --config <path>` | Run the local daemon for paired remote clients. |
+| `tinker connect --config <path>` | Attach a terminal client to a service; exiting detaches only. |
 | `tinker --help` | Show top-level CLI help. |
 | `tinker help run` | Show one-shot command help. |
 | `tinker help update` | Show update command help. |
@@ -229,7 +245,7 @@ are required. Boolean environment values accept case-insensitive `true/false`,
 | `EXA_API_KEY` | Tooling | All modes | No | Non-empty string | — | Yes | Enables WebSearch and the Exa WebFetch backend when set. |
 | `TINKER_MCP_TIMEOUT_MS` | Tooling | All modes | No | Positive integer | `60000` | No | MCP tool-call timeout in milliseconds. |
 | `TINKER_MCP_MAX_OBSERVATION_CHARS` | Tooling | All modes | No | Positive integer | `40000` | No | Maximum model-visible characters in one MCP result. |
-| `TINKER_BASH_DEFAULT_TIMEOUT_MS` | Tooling | All modes | No | Positive integer | `5000` | No | Default Bash foreground timeout in milliseconds. |
+| `TINKER_BASH_DEFAULT_TIMEOUT_MS` | Tooling | All modes | No | Positive integer | `60000` | No | Default Bash foreground timeout in milliseconds. |
 | `TINKER_BASH_MAX_TIMEOUT_MS` | Tooling | All modes | No | Positive integer | `600000` | No | Maximum Bash foreground timeout in milliseconds. |
 | `TINKER_YOLO` | Tooling | All modes | No | Boolean | `false` | No | Allow high-confidence destructive Bash commands without confirmation. |
 | `TINKER_GREP_TIMEOUT_MS` | Tooling | All modes | No | Positive integer | `20000` | No | Bundled ripgrep invocation timeout in milliseconds. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "A personal coding agent with an interactive TUI and one-shot CLI.",
   "license": "Apache-2.0",
   "type": "module",
@@ -23,6 +23,7 @@
     "src/memory",
     "src/model",
     "src/observation",
+    "src/remote",
     "src/session",
     "src/skills",
     "src/tools",

package/src/agent/runtime-hosted-session.ts

@@ -0,0 +1,443 @@
+import { randomUUID } from "node:crypto";
+import type { RuntimeSession } from "./runtime-session";
+import type {
+  AssistantTextDeltaSink,
+  AssistantTextDeltaUpdate,
+} from "./assistant-text-delta";
+import type { AgentEvent } from "../events/types";
+import type { EventSink } from "../events/event-sink";
+import {
+  RemoteHistoryReader,
+  type RemoteHistoryPage,
+} from "../session/remote-history-reader";
+import { parseSessionId } from "../ids/runtime-id";
+import {
+  RemoteError,
+  type RemoteActivity,
+  type RemoteOperationInput,
+  type OperationReceipt,
+  type RemoteView,
+} from "../remote/protocol";
+import { type ManagedSessionRecord, RemoteServiceStore } from "../remote/service-store";
+import { RemoteSyncHub } from "../remote/sync-hub";
+
+export type HostedRuntimeFactory = (input: {
+  record: ManagedSessionRecord;
+  sink: EventSink & AssistantTextDeltaSink;
+}) => Promise<{
+  runtime: RuntimeSession;
+  databasePath: string;
+  modelName: string;
+}>;
+
+export class HostedSession implements EventSink, AssistantTextDeltaSink {
+  readonly name = "remote-view";
+  readonly hub: RemoteSyncHub;
+  private runtime?: RuntimeSession;
+  private reader?: RemoteHistoryReader;
+  private opening?: Promise<void>;
+  private readonly queue: OperationReceipt[] = [];
+  private active?: {
+    receipt: OperationReceipt;
+    controller: AbortController;
+    completion?: Promise<void>;
+  };
+  private activity: Omit<RemoteActivity, "session" | "operations"> = {
+    status: "idle",
+    tools: [],
+  };
+  private lastOrdinal = 0;
+  private streamTimer?: ReturnType<typeof setTimeout>;
+  private stopping = false;
+  private unsubscribers: (() => void)[] = [];
+  private controlTail: Promise<void> = Promise.resolve();
+
+  constructor(
+    private record: ManagedSessionRecord,
+    private readonly store: RemoteServiceStore,
+    epoch: string,
+    private readonly factory: HostedRuntimeFactory,
+  ) {
+    this.hub = new RemoteSyncHub(epoch, () => this.view());
+  }
+
+  open(): Promise<void> {
+    return (this.opening ??= this.initialize());
+  }
+  private async initialize(): Promise<void> {
+    try {
+      const opened = await this.factory({ record: this.record, sink: this });
+      this.runtime = opened.runtime;
+      this.reader = new RemoteHistoryReader(
+        opened.databasePath,
+        parseSessionId(this.record.id),
+        this.record.workspacePath,
+      );
+      this.record = {
+        ...this.record,
+        initialized: true,
+        modelName: opened.modelName,
+        status: "idle",
+      };
+      this.store.saveSession(this.record);
+      const latest = this.reader.latestTurn();
+      if (latest && latest.status !== "open") {
+        this.activity.status = latest.status as RemoteActivity["status"];
+        this.activity.error = latest.error;
+      }
+      // Canonical terminal status wins over a crash between turn commit and receipt update.
+      for (const receipt of this.store.operations(this.record.id)) {
+        const status = receipt.turnId
+          ? this.reader.turnStatus(receipt.turnId)
+          : undefined;
+        if (receipt.kind === "prompt" && status && status !== "open") {
+          this.store.update({
+            ...receipt,
+            status: status as OperationReceipt["status"],
+            error: status === "interrupted" ? receipt.error : undefined,
+          });
+        }
+      }
+      const last = this.store
+        .operations(this.record.id)
+        .filter((op) => op.kind === "prompt")
+        .at(-1);
+      if (last?.status === "interrupted") {
+        this.activity.status = "interrupted";
+        this.activity.error = last.error;
+      }
+      this.unsubscribers = [
+        this.runtime.subscribeAskUser(() => this.updateInteraction()),
+        this.runtime.subscribeBashGuard(() => this.updateInteraction()),
+      ];
+      this.publish();
+    } catch (error) {
+      this.activity.status = "failed";
+      this.activity.error = errorMessage(error);
+      if (this.runtime)
+        await this.runtime
+          .dispose({ type: "runner_failed", error: errorMessage(error) })
+          .catch(() => undefined);
+      this.publish();
+      throw error;
+    }
+  }
+
+  view(): RemoteView {
+    return { ...this.readActivity(), history: this.history() };
+  }
+  history(before?: number, limit?: number): RemoteHistoryPage {
+    return this.reader?.page(before, limit) ?? { messages: [], hasMore: false };
+  }
+  private readActivity(): RemoteActivity {
+    const { id, workspaceId, title, modelName, owner, updatedAt } = this.record;
+    const session = { id, workspaceId, title, modelName, owner, updatedAt };
+    return structuredClone({
+      ...this.activity,
+      session: { ...session, status: this.activity.status },
+      operations: this.store.operations(this.record.id),
+    });
+  }
+
+  validate(input: RemoteOperationInput): void {
+    if (this.stopping)
+      throw new RemoteError(503, "SERVICE_STOPPING", "The local service is stopping.");
+    if (input.kind === "prompt" && this.queue.length >= 8)
+      throw new RemoteError(
+        409,
+        "QUEUE_FULL",
+        "This session already has eight queued requests.",
+      );
+    if (input.kind === "answer" || input.kind === "confirm") {
+      const pending = this.activity.interaction;
+      if (
+        !pending ||
+        pending.id !== input.interactionId ||
+        pending.kind !== (input.kind === "answer" ? "question" : "confirmation")
+      )
+        throw new RemoteError(
+          409,
+          "STALE_INTERACTION",
+          "This question or confirmation is no longer pending.",
+        );
+      if (
+        input.kind === "answer" &&
+        input.selectedIndex !== null &&
+        pending.kind === "question" &&
+        !pending.options[input.selectedIndex]
+      )
+        throw new RemoteError(400, "INVALID_ANSWER", "Answer index is out of range.");
+    }
+    if (input.kind === "stop") {
+      const target = this.store.get(input.targetRequestId);
+      if (target.sessionId !== this.record.id || target.kind !== "prompt")
+        throw new RemoteError(
+          409,
+          "INVALID_STOP_TARGET",
+          "Stop must target a prompt in this session.",
+        );
+    }
+  }
+
+  enqueue(receipt: OperationReceipt): void {
+    this.queue.push(receipt);
+    if (!this.active) this.activity.status = "accepted";
+    if (this.record.title === "New session" && receipt.prompt) {
+      this.record = {
+        ...this.record,
+        title: receipt.prompt.replace(/\s+/g, " ").slice(0, 100),
+      };
+      this.store.saveSession(this.record);
+    }
+    this.publish();
+    this.pump();
+  }
+  private pump(): void {
+    if (this.active || this.stopping) return;
+    const receipt = this.queue.shift();
+    if (!receipt) return;
+    const active = {
+      receipt,
+      controller: new AbortController(),
+      completion: undefined as Promise<void> | undefined,
+    };
+    this.active = active;
+    active.completion = this.execute(active);
+  }
+  private async execute(active: NonNullable<HostedSession["active"]>): Promise<void> {
+    try {
+      await this.open();
+      if (active.controller.signal.aborted) {
+        this.updateReceipt(active.receipt, { status: "cancelled" });
+        return;
+      }
+      this.activity = {
+        status: "running",
+        activeRequestId: active.receipt.requestId,
+        tools: [],
+      };
+      this.updateReceipt(active.receipt, { status: "running" });
+      this.publish();
+      const accepted = await this.runtime!.admitTurn({
+        userMessage: { role: "user", content: active.receipt.prompt! },
+        signal: active.controller.signal,
+      });
+      active.receipt = this.updateReceipt(active.receipt, {
+        status: "running",
+        turnId: accepted.turnId,
+      });
+      this.activity.activeTurnId = accepted.turnId;
+      this.publish();
+      const result = await accepted.completion;
+      this.updateReceipt(active.receipt, {
+        status: result.status,
+        ...(result.status === "failed" ? { error: result.error } : {}),
+      });
+      this.activity.status = result.status;
+      if (result.status === "failed") this.activity.error = result.error;
+    } catch (error) {
+      const status = active.controller.signal.aborted ? "cancelled" : "failed";
+      this.updateReceipt(active.receipt, {
+        status,
+        error: errorMessage(error),
+      });
+      this.activity.status = status;
+      this.activity.error = errorMessage(error);
+    } finally {
+      this.activity.streaming = undefined;
+      this.activity.interaction = undefined;
+      this.activity.activeRequestId = undefined;
+      this.activity.activeTurnId = undefined;
+      for (const tool of this.activity.tools) {
+        if (tool.status === "running")
+          tool.status = this.activity.status === "cancelled" ? "cancelled" : "failed";
+      }
+      this.active = undefined;
+      this.publish(true);
+      this.pump();
+    }
+  }
+
+  control(input: RemoteOperationInput, receipt: OperationReceipt): void {
+    // Separate from prompt execution: answering a wait cannot wait for that turn.
+    this.controlTail = this.controlTail.then(async () => {
+      try {
+        await this.open();
+        this.validate(input);
+        if (input.kind === "stop") {
+          if (this.active?.receipt.requestId === input.targetRequestId)
+            this.active.controller.abort();
+          const index = this.queue.findIndex(
+            (op) => op.requestId === input.targetRequestId,
+          );
+          if (index !== -1)
+            this.updateReceipt(this.queue.splice(index, 1)[0], {
+              status: "cancelled",
+            });
+        } else if (input.kind === "answer") {
+          await this.runtime!.resolveAskUser(
+            input.selectedIndex === null
+              ? { outcome: "dismissed" }
+              : { outcome: "selected", selectedIndex: input.selectedIndex },
+          );
+        } else if (input.kind === "confirm") {
+          await this.runtime!.resolveBashConfirmation(input.decision);
+        }
+        this.updateReceipt(receipt, { status: "completed" });
+      } catch (error) {
+        this.updateReceipt(receipt, {
+          status: "failed",
+          error: errorMessage(error),
+        });
+      }
+      this.publish();
+    });
+  }
+
+  private updateReceipt(
+    receipt: OperationReceipt,
+    patch: Partial<OperationReceipt>,
+  ): OperationReceipt {
+    const next = this.store.update({
+      ...this.store.get(receipt.requestId),
+      ...patch,
+    });
+    this.record = { ...this.record, updatedAt: next.updatedAt };
+    this.store.saveSession(this.record);
+    if (this.active?.receipt.requestId === receipt.requestId)
+      this.active.receipt = next;
+    return next;
+  }
+
+  private updateInteraction(): void {
+    const question = this.runtime?.askUser().pending;
+    const confirmation = this.runtime?.bashGuard().pending;
+    if (question || confirmation) {
+      if (!this.activity.interaction) {
+        this.activity.interaction = question
+          ? { id: randomUUID(), kind: "question", ...question }
+          : { id: randomUUID(), kind: "confirmation", ...confirmation! };
+      }
+      this.activity.status = "waiting_input";
+    } else {
+      this.activity.interaction = undefined;
+      if (this.active) this.activity.status = "running";
+    }
+    if (this.active)
+      this.updateReceipt(this.active.receipt, {
+        status: this.activity.status as OperationReceipt["status"],
+      });
+    this.publish();
+  }
+
+  async append(event: AgentEvent): Promise<void> {
+    if (!this.reader) return;
+    switch (event.type) {
+      case "turn.started":
+        this.activity.activeTurnId = event.turnId;
+        if (this.active)
+          this.updateReceipt(this.active.receipt, { turnId: event.turnId });
+        break;
+      case "model.request.started":
+        this.activity.streaming = undefined;
+        break;
+      case "model.request.finished":
+        this.activity.streaming = undefined;
+        break;
+      case "tool.started":
+        this.activity.tools.push({
+          id: event.data.call.toolCallId,
+          name: event.data.call.name,
+          arguments: JSON.stringify(event.data.call.args),
+          status: "running",
+        });
+        this.activity.tools = this.activity.tools.slice(-100);
+        break;
+      case "tool.finished": {
+        const tool = this.activity.tools.find((tool) => tool.id === event.toolCallId);
+        if (tool) tool.status = event.data.ok ? "completed" : "failed";
+        break;
+      }
+      case "tool.observation": {
+        const tool = this.activity.tools.find((tool) => tool.id === event.toolCallId);
+        if (tool) tool.detail = event.data.observation.displayText;
+        break;
+      }
+      case "turn.finished":
+      case "turn.failed":
+      case "turn.cancelled":
+      case "agent.iteration.finished":
+      case "turn.steering.applied":
+        break;
+      default:
+        return;
+    }
+    this.publish();
+  }
+  updateAssistantTextDelta(update: AssistantTextDeltaUpdate): void {
+    const previous = this.activity.streaming;
+    this.activity.streaming = {
+      iterationId: update.iterationId,
+      attempt: update.attemptNumber,
+      text:
+        previous?.iterationId === update.iterationId &&
+        previous.attempt === update.attemptNumber
+          ? previous.text + update.content
+          : update.content,
+    };
+    if (!this.streamTimer)
+      this.streamTimer = setTimeout(() => {
+        this.streamTimer = undefined;
+        this.publish();
+      }, 50);
+  }
+  private publish(refreshTurn = false): void {
+    if (this.streamTimer) {
+      clearTimeout(this.streamTimer);
+      this.streamTimer = undefined;
+    }
+    const messages = this.reader?.after(this.lastOrdinal) ?? [];
+    if (messages.length) this.lastOrdinal = messages.at(-1)!.ordinal;
+    if (refreshTurn) {
+      const latest = this.reader?.latestTurn();
+      messages.push(
+        ...(this.reader?.page().messages.filter((m) => m.turnId === latest?.id) ?? []),
+      );
+    }
+    this.hub.publish({ activity: this.readActivity(), messages });
+  }
+
+  async close(): Promise<void> {
+    this.stopping = true;
+    for (const receipt of this.queue.splice(0))
+      this.updateReceipt(receipt, {
+        status: "interrupted",
+        error: "The service was stopped before this queued request began.",
+      });
+    if (this.opening) await this.opening.catch(() => undefined);
+    if (this.runtime)
+      await this.runtime.dispose({
+        type: "runner_failed",
+        error: "Remote service shutdown.",
+      });
+    await this.active?.completion;
+    await this.controlTail;
+    for (const unsubscribe of this.unsubscribers) unsubscribe();
+    if (this.streamTimer) clearTimeout(this.streamTimer);
+    this.hub.close();
+    this.reader?.close();
+  }
+  get pendingCount(): number {
+    return this.queue.length + (this.active ? 1 : 0);
+  }
+  receiptChanged(): void {
+    this.publish();
+  }
+  get initialized(): boolean {
+    return this.runtime !== undefined;
+  }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/cli/command-line.ts

@@ -6,6 +6,8 @@ import { CliUsageError, type CliCommandScope } from "./output";
 export type CliCommand =
   | { readonly type: "tui"; readonly profileName?: string }
   | { readonly type: "update" }
+  | { readonly type: "serve"; readonly configPath: string }
+  | { readonly type: "connect"; readonly configPath: string }
   | {
       readonly type: "run";
       readonly profileName?: string;
@@ -130,6 +132,21 @@ export async function parseCommandLine(
       },
     );
 
+  for (const type of ["serve", "connect"] as const) {
+    const command = contract[type];
+    program
+      .command(command.command)
+      .description(command.description)
+      .requiredOption(command.configOption.flags, command.configOption.description)
+      .allowExcessArguments(false)
+      .exitOverride()
+      .action((options: { config: string }) => {
+        if (!options.config.trim())
+          throw new CliUsageError("--config requires a non-empty path.", type);
+        selectedCommand = Object.freeze({ type, configPath: options.config });
+      });
+  }
+
   program
     .command(contract.update.command)
     .description(contract.update.description)
@@ -166,10 +183,13 @@ export async function parseCommandLine(
       "run",
     );
   }
-  if (selectedCommand.type === "update" && topLevelProfile !== undefined) {
+  if (
+    ["update", "serve", "connect"].includes(selectedCommand.type) &&
+    topLevelProfile !== undefined
+  ) {
     throw new CliUsageError(
       "The top-level --profile option only applies to the TUI.",
-      "update",
+      selectedCommand.type as CliCommandScope,
     );
   }
   return Object.freeze({ type: "command", command: selectedCommand });
@@ -224,6 +244,10 @@ function preflightArgv(args: readonly string[]): CliCommandScope {
         scope = "update";
         continue;
       }
+      if (token === "serve" || token === "connect") {
+        scope = token;
+        continue;
+      }
       if (token === "help") {
         return "root";
       }

package/src/cli/connect-runner.tsx

@@ -0,0 +1,26 @@
+import { render } from "ink";
+import { RemoteClient, loadRemoteClientConfig } from "../remote/client";
+import { RemoteApp } from "../tui/remote-app";
+import type { CliOutputWriter } from "./output";
+
+export async function runConnect(input: {
+  configPath: string;
+  env: NodeJS.ProcessEnv;
+  stdout: CliOutputWriter;
+}): Promise<number> {
+  if (!process.stdin.isTTY)
+    throw new Error("tinker connect requires an interactive terminal.");
+  const client = new RemoteClient(await loadRemoteClientConfig(input.configPath));
+  let instance: ReturnType<typeof render> | undefined;
+  try {
+    await client.initialize();
+    instance = render(<RemoteApp client={client} />, { incrementalRendering: true });
+    await instance.waitUntilExit();
+    return 0;
+  } finally {
+    instance?.unmount();
+    await client.close();
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    process.stdin.pause();
+  }
+}

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 import type { SessionId } from "../ids/runtime-id";
+import path from "node:path";
 import { createUuidV7 } from "../ids/uuid-v7";
 import { parseCommandLine, type CommandLineResult } from "./command-line";
 import type {
@@ -91,6 +92,8 @@ export type MainDependencies = {
   readonly loadTuiRunner: () => Promise<TuiRunner>;
   readonly loadOneShotRunner: () => Promise<OneShotRunner>;
   readonly loadUpdateRunner: () => Promise<UpdateRunner>;
+  readonly loadServeRunner: () => Promise<typeof import("./serve-runner")>;
+  readonly loadConnectRunner: () => Promise<typeof import("./connect-runner")>;
 };
 
 const DEFAULT_DEPENDENCIES: MainDependencies = {
@@ -102,6 +105,8 @@ const DEFAULT_DEPENDENCIES: MainDependencies = {
   loadTuiRunner: () => import("./tui-runner"),
   loadOneShotRunner: () => import("./run-runner"),
   loadUpdateRunner: () => import("./update-runner"),
+  loadServeRunner: () => import("./serve-runner"),
+  loadConnectRunner: () => import("./connect-runner"),
 };
 
 export async function main(
@@ -160,6 +165,27 @@ export async function main(
       }
     }
 
+    if (parsed.command.type === "serve" || parsed.command.type === "connect") {
+      const options = {
+        configPath: path.resolve(cwd, parsed.command.configPath),
+        env,
+        stdout: input.stdout,
+      };
+      try {
+        const exitCode =
+          parsed.command.type === "serve"
+            ? await (await dependencies.loadServeRunner()).runServe(options)
+            : await (await dependencies.loadConnectRunner()).runConnect(options);
+        return finish(exitCode);
+      } catch (error) {
+        await writeCliOutput(
+          input.stderr,
+          renderCliFailure("Remote operation failed", error),
+        );
+        return finish(1);
+      }
+    }
+
     let configBoundary: ConfigBoundary;
     let publicConfig: ResolvedPublicConfig;
     let runnerConfig: RunnerConfig;