feat(eve): add eve invoke command

.changeset/wise-dev-prompts.md

@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Invoke an agent without a TUI using `eve invoke`, which returns pretty JSON at terminal or blocking events. Durable session coordinates support follow-up turns, human input, authorization, interrupted waits, and machine discovery through `--json-schema`.

docs/reference/cli.md

@@ -183,14 +183,38 @@ Pass a bare URL and the UI connects to that server instead of booting a local on
 
 A fresh `eve init` passes `--input /model`. That bare local input starts onboarding: the TUI installs the Vercel CLI if needed, asks you to log in if needed, then opens `/model`. Other input stays editable in the prompt.
 
-For a URL target protected by HTTP Basic auth, put the credentials in the URL. Eve sends them as a Basic `Authorization` header and strips them from the server URL before connecting:
+For a URL target protected by HTTP Basic auth, put the credentials in the URL. eve sends them as a Basic `Authorization` header and strips them from the server URL before connecting:
 
 ```bash
 eve dev https://user:pass@your-app.example.com
 ```
 
 For bearer tokens or custom schemes, pass explicit headers with `-H`.
 
+### `eve invoke`
+
+| Option                  | Type   | Default | Description                                     |
+| ----------------------- | ------ | ------- | ----------------------------------------------- |
+| `[prompt]`              | string | none    | Prompt, follow-up, or answer to a pending input |
+| `-u, --url <url>`       | string | local   | Invoke an existing server                       |
+| `-H, --header <header>` | string | none    | Request header for a URL target; repeatable     |
+| `--resume`              | flag   | off     | Read a previous resumable result from stdin     |
+| `--scope <team>`        | string | current | Vercel team that owns the URL target            |
+| `--json-schema`         | flag   | off     | Print the result JSON Schema and exit           |
+
+Use `eve invoke` to submit a turn without opening the TUI. It emits JSON after the invocation completes or reaches a blocking input or authorization event.
+
+```bash
+eve invoke "Summarize station telemetry"
+result=$(eve invoke "Deploy the application")
+printf '%s' "$result" | eve invoke --resume "approve"
+eve invoke --json-schema
+```
+
+`--resume` reads a complete previous result from stdin. Supply text for a `ready` follow-up or pending input; the agent harness resolves input text against all pending requests. A `ready` result includes the previous turn's completed or failed `outcome`. An `authorization-required` result lists every unresolved challenge in `authorizations`; complete them, then resume without text. Pass explicit headers again for protected remote servers. If the URL belongs to another Vercel team, pass its slug with `--scope`; this does not relink the current directory. Pass the scope again when resuming. Paused invocations exit `3`; failures exit `1`.
+
+Local callback-based connection authorization requires a persistent server. Run `eve dev`, then use `eve invoke --url <dev-url>` instead. If a waiting invocation receives `SIGINT` or `SIGTERM` after acceptance, it emits a final resumable `running` result before exiting.
+
 Local dev records the last ready URL per resolved app root in `.eve/dev-server-state.v1.json`. A second interactive `eve dev` reconnects only when that URL is loopback and healthy; each terminal UI creates a fresh client session while sharing the server process. A stale or malformed record is replaced when eve starts a new server. Passing `--host`, `--port`, or a `PORT` environment value skips reconnection and reports a healthy recorded server instead.
 
 Local dev keeps immutable runtime source snapshots under `.eve/dev-runtime/snapshots/` so in-flight turns hold a consistent code revision while new turns pick up rebuilds. The terminal REPL keeps its logical session across successful rebuilds, so the next turn continues the conversation on the latest generation; `/new` terminally retires that session before clearing the transcript, and the next prompt starts a fresh session with a new session-scoped sandbox on first sandbox use. After a generation is superseded, `eve dev` retains it for at least 30 minutes and also retains the five most recently superseded generations, regardless of the configured Workflow World. The active generation is never pruned. Old runtime snapshots and local sandbox templates are pruned in the background. For manual cleanup, stop `eve dev` before deleting `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/`. A turn that remains unfinished beyond the automatic retention window can no longer resume after its generation is pruned.

packages/eve/src/cli/dev/tui/remote-connection-probe.ts

@@ -7,7 +7,7 @@ import {
 import { toErrorMessage } from "#shared/errors.js";
 import { isObject } from "#shared/guards.js";
 
-import { probeAgentInfo } from "./agent-info-probe.js";
+import { probeAgentInfo } from "#services/dev-client/agent-info-probe.js";
 import type { RemoteConnectionState } from "./remote-connection-types.js";
 
 export type RemoteProbeResult = Extract<

packages/eve/src/cli/dev/tui/runner.ts

@@ -46,7 +46,7 @@ import {
 } from "./errors.js";
 
 import { pickAgentHeaderTip } from "./agent-header.js";
-import { probeAgentInfo } from "./agent-info-probe.js";
+import { probeAgentInfo } from "#services/dev-client/agent-info-probe.js";
 import { parseLogDisplayMode } from "./log-display-mode.js";
 import {
   formatPromptCommandHelp,

packages/eve/src/cli/dev/tui/target.ts

@@ -1,23 +1,15 @@
 import { basename } from "node:path";
 
-interface DevelopmentTargetBase {
-  readonly serverUrl: string;
-  /** Local workspace root for app files and the fallback Vercel project link. */
-  readonly workspaceRoot: string;
-}
-
-/** A development TUI session backed by the local `eve dev` server. */
-export interface LocalDevelopmentTarget extends DevelopmentTargetBase {
-  readonly kind: "local";
-}
+import type {
+  DevelopmentTarget,
+  LocalDevelopmentTarget,
+  RemoteDevelopmentTarget,
+} from "#services/dev-client/target.js";
 
-/** A development TUI session connected to an existing remote server. */
-export interface RemoteDevelopmentTarget extends DevelopmentTargetBase {
-  readonly kind: "remote";
-}
+export type { LocalDevelopmentTarget, RemoteDevelopmentTarget };
 
 /** Local or remote server backing one development TUI session. */
-export type DevelopmentTuiTarget = LocalDevelopmentTarget | RemoteDevelopmentTarget;
+export type DevelopmentTuiTarget = DevelopmentTarget;
 
 /** Resolves the explicit name, remote host, or humanized local folder shown by the TUI. */
 export function resolveTuiTitle(input: {

packages/eve/src/cli/invoke/command.ts

@@ -0,0 +1,234 @@
+import { type Command, InvalidArgumentError } from "#compiled/commander/index.js";
+import {
+  parseDevelopmentHeaderOption,
+  resolveDevelopmentUrlTarget,
+  type DevelopmentRequestHeaders,
+} from "#cli/dev/url-target.js";
+import { parseDevelopmentServerUrl } from "#cli/dev/url.js";
+import type { DevelopmentServer, DevelopmentServerOptions } from "#internal/nitro/host/types.js";
+import type { DevelopmentTarget } from "#services/dev-client/target.js";
+
+import { resolveInvokeOperation, type RunInvokeInput } from "./invoke.js";
+import { invokeResultJsonSchema, parseInvokeResumeInput, type InvokeResult } from "./result.js";
+
+interface InvokeCliOptions {
+  header?: DevelopmentRequestHeaders;
+  jsonSchema?: boolean;
+  resume?: boolean;
+  scope?: string;
+  url?: string;
+}
+
+export interface InvokeCommandDependencies {
+  readonly loadEnvironment: (appRoot: string) => void | Promise<void>;
+  readonly runInvoke: (input: RunInvokeInput) => Promise<InvokeResult>;
+  readonly startHost: (appRoot: string) => DevelopmentServer | Promise<DevelopmentServer>;
+}
+
+/** Runtime overrides used when wiring `eve invoke` into the root CLI. */
+export interface InvokeCliRuntimeDependencies {
+  readonly runInvoke: (input: RunInvokeInput) => Promise<InvokeResult>;
+  readonly startHost: (appRoot: string, options?: DevelopmentServerOptions) => DevelopmentServer;
+}
+
+interface InvokeCommandLogger {
+  log(message: string): void;
+}
+
+/** Registers the invoke command with lazily loaded production dependencies. */
+export function registerRuntimeInvokeCommand(input: {
+  readonly appRoot: string;
+  readonly logger: InvokeCommandLogger;
+  readonly program: Command;
+  readonly runtime: Partial<InvokeCliRuntimeDependencies>;
+}): void {
+  registerInvokeCommand({
+    ...input,
+    deps: {
+      loadEnvironment: async (root) =>
+        (await import("#cli/dev/environment.js")).loadDevelopmentEnvironmentFiles(root),
+      runInvoke: async (invokeInput) =>
+        await (input.runtime.runInvoke ?? (await import("./invoke.js")).runInvoke)(invokeInput),
+      startHost: async (root) =>
+        (
+          input.runtime.startHost ??
+          (await import("#internal/nitro/host.js")).createDevelopmentServer
+        )(root, { existing: "reject" }),
+    },
+  });
+}
+
+/** Registers the non-interactive invoke command. */
+export function registerInvokeCommand(input: {
+  readonly appRoot: string;
+  readonly deps: InvokeCommandDependencies;
+  readonly logger: InvokeCommandLogger;
+  readonly program: Command;
+}): void {
+  input.program
+    .command("invoke")
+    .description("Invoke an eve agent without a terminal UI.")
+    .argument("[prompt]", "Prompt, follow-up message, or answer to a pending input")
+    .option("-u, --url <url>", "Invoke an existing server URL", parseDevelopmentServerUrl)
+    .option(
+      "-H, --header <header>",
+      'Request header for a URL target, in "Name: value" form (repeatable)',
+      parseDevelopmentHeaderOption,
+    )
+    .option("--resume", "Read a previous resumable result from stdin")
+    .option("--scope <team>", "Vercel team that owns the URL target")
+    .option("--json-schema", "Print the invoke result JSON Schema and exit")
+    .action((prompt: string | undefined, options: InvokeCliOptions) =>
+      runInvokeCommand({ ...input, options, prompt }),
+    );
+}
+
+async function runInvokeCommand(input: {
+  readonly appRoot: string;
+  readonly deps: InvokeCommandDependencies;
+  readonly logger: InvokeCommandLogger;
+  readonly options: InvokeCliOptions;
+  readonly prompt?: string;
+}): Promise<void> {
+  const { options } = input;
+  if (options.jsonSchema === true) {
+    assertSchemaOnly(input.prompt, options);
+    input.logger.log(JSON.stringify(invokeResultJsonSchema, null, 2));
+    return;
+  }
+  const previous =
+    options.resume === true ? parseInvokeResumeInput(await readJsonFromStdin()) : undefined;
+  const resumedTarget = previous?.resume.target;
+  if (resumedTarget?.kind === "local" && options.url !== undefined) {
+    throw new InvalidArgumentError("A local invocation cannot be resumed against --url.");
+  }
+
+  const effectiveUrl =
+    options.url ?? (resumedTarget?.kind === "remote" ? resumedTarget.serverUrl : undefined);
+  const remoteTarget = resolveDevelopmentUrlTarget(
+    { header: options.header, url: effectiveUrl },
+    undefined,
+  );
+  if (options.scope !== undefined && remoteTarget === undefined) {
+    throw new InvalidArgumentError("The --scope option requires a URL target.");
+  }
+  if (
+    resumedTarget?.kind === "remote" &&
+    options.url !== undefined &&
+    remoteTarget !== undefined &&
+    remoteTarget.serverUrl !== resumedTarget.serverUrl
+  ) {
+    throw new InvalidArgumentError(
+      `Session target ${resumedTarget.serverUrl} does not match ${remoteTarget.serverUrl}.`,
+    );
+  }
+  const operation = resolveInvokeOperation({ previous, prompt: input.prompt });
+
+  await input.deps.loadEnvironment(input.appRoot);
+  if (remoteTarget !== undefined) {
+    await executeWithSignals(
+      input,
+      {
+        kind: "remote",
+        serverUrl: remoteTarget.serverUrl,
+        workspaceRoot: input.appRoot,
+      },
+      remoteTarget.headers,
+      operation,
+      options.scope,
+    );
+    return;
+  }
+
+  const server = await input.deps.startHost(input.appRoot);
+  try {
+    const handle = await server.start();
+    await executeWithSignals(
+      input,
+      { kind: "local", serverUrl: handle.url, workspaceRoot: handle.appRoot },
+      undefined,
+      operation,
+    );
+  } finally {
+    await server.close();
+  }
+}
+
+async function executeWithSignals(
+  input: {
+    readonly deps: InvokeCommandDependencies;
+    readonly logger: InvokeCommandLogger;
+    readonly options: InvokeCliOptions;
+  },
+  target: DevelopmentTarget,
+  headers: DevelopmentRequestHeaders | undefined,
+  operation: RunInvokeInput["operation"],
+  vercelScope?: string,
+): Promise<void> {
+  const controller = new AbortController();
+  let signalExitCode: number | undefined;
+  const handleSigint = () => {
+    signalExitCode = 130;
+    controller.abort();
+  };
+  const handleSigterm = () => {
+    signalExitCode = 143;
+    controller.abort();
+  };
+  process.once("SIGINT", handleSigint);
+  process.once("SIGTERM", handleSigterm);
+  try {
+    const invokeInput =
+      headers === undefined
+        ? { operation, signal: controller.signal, target }
+        : { headers, operation, signal: controller.signal, target };
+    const scopedInvokeInput =
+      vercelScope === undefined ? invokeInput : { ...invokeInput, vercelScope };
+    const result = await input.deps.runInvoke(scopedInvokeInput);
+    input.logger.log(JSON.stringify(result, null, 2));
+    process.exitCode = signalExitCode ?? invokeExitCode(result);
+  } finally {
+    process.off("SIGINT", handleSigint);
+    process.off("SIGTERM", handleSigterm);
+  }
+}
+
+function assertSchemaOnly(prompt: string | undefined, options: InvokeCliOptions): void {
+  if (
+    prompt !== undefined ||
+    options.resume === true ||
+    options.scope !== undefined ||
+    options.url !== undefined ||
+    options.header !== undefined
+  ) {
+    throw new InvalidArgumentError(
+      "--json-schema cannot be combined with invoke options or a prompt.",
+    );
+  }
+}
+
+async function readJsonFromStdin(): Promise<unknown> {
+  let text = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) text += chunk;
+  if (text.trim().length === 0) {
+    throw new InvalidArgumentError("--resume expected a resumable eve invoke result on stdin.");
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new InvalidArgumentError("--resume received invalid JSON on stdin.");
+  }
+}
+
+function invokeExitCode(result: InvokeResult): number {
+  if (
+    result.status === "failed" ||
+    result.status === "authentication-required" ||
+    (result.status === "ready" && result.outcome.status === "failed")
+  ) {
+    return 1;
+  }
+  if (result.status === "input-required" || result.status === "authorization-required") return 3;
+  return 0;
+}