@tonyclaw/agent-inspector 3.0.44 → 3.0.45

package/src/cli.ts

@@ -6,11 +6,18 @@ import { fileURLToPath } from "node:url";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { existsSync } from "node:fs";
 import type { Readable, Writable } from "node:stream";
+import packageJson from "../package.json";
 import {
   AGENT_INSPECTOR_INTERNAL_STRIPPED_BASE_PATH_ENV,
   appendBasePathToOrigin,
   getConfiguredBasePath,
 } from "./lib/basePath.js";
+import {
+  AGENT_INSPECTOR_CLI_ENTRY_ENV,
+  managedInstanceShutdownMessage,
+  readManagedInstanceLaunch,
+  type ManagedInstanceLaunch,
+} from "./lib/managedInstance.js";
 import {
   formatAccessHintLines,
   isLoopbackHost,
@@ -29,6 +36,7 @@ import {
   forceCloseIdentityProxy,
   startIdentityProxy,
   stopIdentityProxyAdmission,
+  type ManagedInstanceControlOptions,
 } from "./proxy/identityProxy.js";
 import { findPidsByPort, killPid, openUrlCommand } from "./proxy/platformCommands.js";
 
@@ -61,19 +69,71 @@ process.title = "Agent Inspector";
  */
 const subcommand = process.argv[2];
 
-if (subcommand === "onboard") {
-  const { runOnboard } = await import("./cli/onboard.js");
-  const code = await runOnboard(process.argv.slice(3));
-  process.exit(code);
-}
+function printGlobalHelp(): void {
+  console.log(`agent-inspector ${packageJson.version} - Agent observability and knowledge capture
+
+Usage:
+  agent-inspector [start] [options]
+  agent-inspector instance <start|list|status|connect|stop|restart> ...
+  agent-inspector alias <list|add|remove> ...
+  agent-inspector onboard [options]
+  agent-inspector doctor [options]
+
+Global options:
+  -h, --help      Show this help without starting a runtime
+  -v, --version   Print the package version
 
-if (subcommand === "doctor") {
-  const { runDoctor } = await import("./cli/doctor.js");
-  const code = await runDoctor(process.argv.slice(3));
-  process.exit(code);
+Run \`agent-inspector instance --help\`, \`agent-inspector onboard --help\`, or
+\`agent-inspector doctor --help\` for command-specific options.`);
 }
 
-await runStart(process.argv.slice(2));
+switch (subcommand) {
+  case "--help":
+  case "-h":
+    printGlobalHelp();
+    process.exitCode = 0;
+    break;
+  case "--version":
+  case "-v":
+    console.log(packageJson.version);
+    process.exitCode = 0;
+    break;
+  case "onboard": {
+    const { runOnboard } = await import("./cli/onboard.js");
+    const code = await runOnboard(process.argv.slice(3));
+    process.exit(code);
+  }
+  case "doctor": {
+    const { runDoctor } = await import("./cli/doctor.js");
+    const code = await runDoctor(process.argv.slice(3));
+    process.exit(code);
+  }
+  case "alias": {
+    const { runAlias } = await import("./cli/alias.js");
+    const code = await runAlias(process.argv.slice(3));
+    process.exit(code);
+  }
+  case "instance": {
+    const { runInstance } = await import("./cli/instance.js");
+    const code = await runInstance(process.argv.slice(3));
+    process.exitCode = code;
+    break;
+  }
+  case undefined:
+    await runStart(process.argv.slice(2));
+    break;
+  case "start":
+    await runStart(process.argv.slice(3));
+    break;
+  default:
+    if (subcommand.startsWith("-")) {
+      await runStart(process.argv.slice(2));
+    } else {
+      console.error(`agent-inspector: unknown command ${subcommand}`);
+      console.error("Run `agent-inspector --help` for supported commands.");
+      process.exitCode = 2;
+    }
+}
 
 // -----------------------------------------------------------------------------
 // Legacy `start` behavior — start the proxy on the configured port. Extracted
@@ -345,6 +405,7 @@ async function tryStartIdentityProxy(
   upstreamPort: number,
   listenHost: string,
   upstreamHost: string,
+  managedInstance: ManagedInstanceControlOptions | undefined,
 ): Promise<import("node:http").Server | null> {
   try {
     const server = await startIdentityProxy({
@@ -364,6 +425,7 @@ async function tryStartIdentityProxy(
         .filter((host) => host.length > 0),
       maxRequestBytes: readPositiveIntegerEnv("AGENT_INSPECTOR_MAX_REQUEST_BYTES"),
       requestTimeoutMs: readPositiveIntegerEnv("AGENT_INSPECTOR_REQUEST_TIMEOUT_MS"),
+      managedInstance,
     });
     return server;
   } catch (err) {
@@ -378,6 +440,14 @@ async function tryStartIdentityProxy(
 }
 
 async function runStart(args: string[]): Promise<void> {
+  const managedLaunchResult = readManagedInstanceLaunch(process.env);
+  if (managedLaunchResult.kind === "invalid") {
+    console.error(managedLaunchResult.message);
+    process.exitCode = 1;
+    return;
+  }
+  const managedLaunch: ManagedInstanceLaunch | null =
+    managedLaunchResult.kind === "managed" ? managedLaunchResult.launch : null;
   const envPort = process.env["AGENT_INSPECTOR_PORT"] ?? process.env["PORT"];
   const portDefault = envPort !== undefined ? Number(envPort) : DEFAULT_PORT;
   const envHost = process.env["NITRO_HOST"] ?? process.env["HOST"];
@@ -417,6 +487,10 @@ async function runStart(args: string[]): Promise<void> {
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i] ?? "";
+    if (arg.startsWith("--port=")) {
+      port = Number(arg.slice(arg.indexOf("=") + 1));
+      continue;
+    }
     if (arg.startsWith("--host=")) {
       const value = arg.slice(arg.indexOf("=") + 1).trim();
       if (!isValidBindHost(value)) {
@@ -515,8 +589,19 @@ async function runStart(args: string[]): Promise<void> {
       case "--legacy-port":
         legacyAliasEnabled = true;
         break;
+      case "--help":
+      case "-h":
+        printGlobalHelp();
+        return;
+      case "--version":
+      case "-v":
+        console.log(packageJson.version);
+        return;
       default:
-        break;
+        console.error(`agent-inspector start: unknown option ${arg}`);
+        console.error("Run `agent-inspector --help` for supported options.");
+        process.exitCode = 2;
+        return;
     }
   }
 
@@ -551,7 +636,22 @@ async function runStart(args: string[]): Promise<void> {
   // TanStack Start listens on the private upstream port; identity proxies own
   // the public-facing port(s). When the identity proxy is disabled we fall
   // back to TanStack listening on the public port directly.
-  const upstreamPort = enableIdentityProxy ? pickUpstreamPort(port, legacyAliasPort) : port;
+  const upstreamPort =
+    managedLaunch === null
+      ? enableIdentityProxy
+        ? pickUpstreamPort(port, legacyAliasPort)
+        : port
+      : managedLaunch.upstreamPort;
+  if (
+    upstreamPort < 1 ||
+    upstreamPort > 65_535 ||
+    (enableIdentityProxy && upstreamPort === port) ||
+    upstreamPort === legacyAliasPort
+  ) {
+    console.error(`Invalid managed upstream port: ${String(upstreamPort)}.`);
+    process.exitCode = 1;
+    return;
+  }
   const upstreamHost = enableIdentityProxy ? DEFAULT_BIND_HOST : host;
   process.env["PORT"] = String(upstreamPort);
 
@@ -629,7 +729,7 @@ async function runStart(args: string[]): Promise<void> {
     const supervisorProcess = spawn(process.execPath, [cliEntry, ...supervisorArgs], {
       stdio: "ignore",
       detached: true,
-      env: process.env,
+      env: { ...process.env, [AGENT_INSPECTOR_CLI_ENTRY_ENV]: cliEntry },
       windowsHide: true,
     });
     supervisorProcess.once("error", (err) => {
@@ -697,6 +797,10 @@ async function runStart(args: string[]): Promise<void> {
 
   // Start the server with the branded Windows runtime when postinstall created it.
   const serverEnv = { ...process.env };
+  const currentCliEntry = process.env[AGENT_INSPECTOR_CLI_ENTRY_ENV] ?? process.argv[1];
+  if (currentCliEntry !== undefined && currentCliEntry.length > 0) {
+    serverEnv[AGENT_INSPECTOR_CLI_ENTRY_ENV] = currentCliEntry;
+  }
   if (configDir !== undefined) {
     // Normalize MSYS / Git Bash paths to Windows native form.
     // On Windows, `path.join('/c/Users/foo')` becomes `\c\Users\foo`
@@ -732,7 +836,14 @@ async function runStart(args: string[]): Promise<void> {
     serverEnv["AGENT_INSPECTOR_WORKER_DIR"] = workerDir;
   }
   const serverProcess = spawn(serverCommand.command, serverCommand.args, {
-    stdio: background ? ["ignore", "ignore", "ignore"] : ["ignore", "pipe", "pipe"],
+    stdio:
+      managedLaunch === null
+        ? background
+          ? ["ignore", "ignore", "ignore"]
+          : ["ignore", "pipe", "pipe"]
+        : background
+          ? ["ignore", "ignore", "ignore", "ipc"]
+          : ["ignore", "pipe", "pipe", "ipc"],
     detached: background,
     env: serverEnv,
     windowsHide: background,
@@ -764,7 +875,13 @@ async function runStart(args: string[]): Promise<void> {
   const requestSupervisorShutdown = (signal: "SIGINT" | "SIGTERM"): void => {
     if (supervisorShutdownPromise !== null) return;
     for (const proxy of identityProxies) stopIdentityProxyAdmission(proxy.server);
-    serverProcess.kill(signal);
+    if (managedLaunch !== null && serverProcess.connected) {
+      serverProcess.send(managedInstanceShutdownMessage(managedLaunch.controlToken), (error) => {
+        if (error !== null && serverProcess.exitCode === null) serverProcess.kill(signal);
+      });
+    } else {
+      serverProcess.kill(signal);
+    }
 
     const childDeadline =
       readPositiveIntegerEnv("AGENT_INSPECTOR_SHUTDOWN_TIMEOUT_MS") ?? DEFAULT_SHUTDOWN_DEADLINE_MS;
@@ -795,8 +912,28 @@ async function runStart(args: string[]): Promise<void> {
   const currentSupervisorShutdown = (): Promise<void> | null => supervisorShutdownPromise;
   process.on("SIGINT", handleSigint);
   process.on("SIGTERM", handleSigterm);
+  const managedInstanceControl: ManagedInstanceControlOptions | undefined =
+    managedLaunch === null
+      ? undefined
+      : {
+          name: managedLaunch.name,
+          instanceId: managedLaunch.instanceId,
+          launchId: managedLaunch.launchId,
+          controlToken: managedLaunch.controlToken,
+          supervisorPid: process.pid,
+          startedAt: managedLaunch.startedAt,
+          publicPort: port,
+          upstreamPort,
+          requestShutdown: () => requestSupervisorShutdown("SIGTERM"),
+        };
   if (enableIdentityProxy) {
-    const primaryProxy = await tryStartIdentityProxy(port, upstreamPort, host, upstreamHost);
+    const primaryProxy = await tryStartIdentityProxy(
+      port,
+      upstreamPort,
+      host,
+      upstreamHost,
+      managedInstanceControl,
+    );
     if (primaryProxy !== null) {
       identityProxies.push({ label: "primary", port, server: primaryProxy });
     }
@@ -806,6 +943,7 @@ async function runStart(args: string[]): Promise<void> {
         upstreamPort,
         host,
         upstreamHost,
+        managedInstanceControl,
       );
       if (legacyProxy !== null) {
         identityProxies.push({ label: "legacy", port: legacyAliasPort, server: legacyProxy });

package/src/components/ProxyViewer.tsx

@@ -43,7 +43,8 @@ import {
 
 import type { CapturedLog } from "../contracts";
 import { exportLogsAsZip, type ExportMode } from "../lib/export-logs";
-import { withBasePath } from "../lib/basePath";
+import { getConfiguredBasePath, withBasePath } from "../lib/basePath";
+import { deriveCodingAgentEndpoints } from "../lib/codingAgentEndpoints";
 import type { ImportLogsResponse } from "../lib/logImportContract";
 import { copyTextToClipboard } from "../lib/clipboard";
 import type { InspectorGroupEvidence, InspectorGroupMember } from "../lib/groupContract";
@@ -1384,9 +1385,9 @@ export function ProxyViewer({
   const exportRequestIdRef = useRef(0);
   const detailsPanelResizeRef = useRef<DetailsPanelResizeState | null>(null);
   useKeyboardNavigation(logListRef, logListWrapperRef, { pageWide: true });
-  const proxyEndpoint = useMemo(() => {
+  const connectionEndpoints = useMemo(() => {
     const origin = typeof window === "undefined" ? "http://localhost:9527" : window.location.origin;
-    return `${origin}${withBasePath("/proxy")}`;
+    return deriveCodingAgentEndpoints(origin, getConfiguredBasePath());
   }, []);
 
   const cancelTransientTasks = useCallback(() => {
@@ -2146,11 +2147,18 @@ export function ProxyViewer({
                       <>
                         <div className="flex flex-col items-center gap-2">
                           <CopyableCommand
-                            command={`ANTHROPIC_BASE_URL=${proxyEndpoint} <your-tool>`}
+                            command={`ANTHROPIC_BASE_URL=${connectionEndpoints.proxy} <your-tool>`}
                           />
                           <CopyableCommand
-                            command={`OPENAI_BASE_URL=${proxyEndpoint} <your-tool>`}
+                            command={`LLM_BASE_URL=${connectionEndpoints.proxy} opencode`}
                           />
+                          <CopyableCommand
+                            command={`OPENAI_BASE_URL=${connectionEndpoints.openAiV1} <your-tool>`}
+                          />
+                          <CopyableCommand
+                            command={`base_url = "${connectionEndpoints.openAiV1}"`}
+                          />
+                          <CopyableCommand command={`MCP_URL=${connectionEndpoints.mcp}`} />
                         </div>
                         <p className="mx-auto max-w-xl text-xs leading-relaxed text-muted-foreground">
                           Container note: if your AI tool runs in a different container or host than

package/src/components/providers/SettingsDialog.tsx

@@ -10,7 +10,8 @@ import { useProviders } from "../../lib/useProviders";
 import { useStripConfig } from "../../lib/useStripConfig";
 import { copyTextToClipboard } from "../../lib/clipboard";
 import { fetchJsonWithTimeout } from "../../lib/apiClient";
-import { withBasePath } from "../../lib/basePath";
+import { getConfiguredBasePath, withBasePath } from "../../lib/basePath";
+import { deriveCodingAgentEndpoints } from "../../lib/codingAgentEndpoints";
 import {
   MAX_PROVIDER_TEST_TIMEOUT_SECONDS,
   MAX_SLOW_RESPONSE_THRESHOLD_SECONDS,
@@ -333,6 +334,10 @@ function OnboardingSettingsTab(): JSX.Element {
     if (typeof window === "undefined") return "http://localhost:9527";
     return window.location.origin;
   }, []);
+  const endpoints = useMemo(
+    () => deriveCodingAgentEndpoints(origin, getConfiguredBasePath()),
+    [origin],
+  );
   const values = useMemo(
     () => [
       { id: "status", label: "Check onboarding", value: "agent-inspector onboard --status" },
@@ -367,7 +372,7 @@ function OnboardingSettingsTab(): JSX.Element {
       {
         id: "opencode-proxy",
         label: "OpenCode proxy",
-        value: `LLM_BASE_URL=${origin}${withBasePath("/proxy")}`,
+        value: `LLM_BASE_URL=${endpoints.proxy}`,
       },
       {
         id: "mimo-config",
@@ -383,22 +388,22 @@ function OnboardingSettingsTab(): JSX.Element {
       {
         id: "mimo-proxy",
         label: "MiMo Code proxy",
-        value: `OPENAI_BASE_URL=${origin}${withBasePath("/proxy")}`,
+        value: `OPENAI_BASE_URL=${endpoints.proxy}`,
       },
-      { id: "mcp", label: "MCP URL", value: `${origin}${withBasePath("/api/mcp")}` },
-      { id: "proxy", label: "Proxy URL", value: `${origin}${withBasePath("/proxy")}` },
+      { id: "mcp", label: "MCP URL", value: endpoints.mcp },
+      { id: "proxy", label: "Proxy URL", value: endpoints.proxy },
       {
         id: "anthropic",
         label: "Anthropic base",
-        value: `ANTHROPIC_BASE_URL=${origin}${withBasePath("/proxy")}`,
+        value: `ANTHROPIC_BASE_URL=${endpoints.proxy}`,
       },
       {
         id: "openai",
         label: "OpenAI base",
-        value: `OPENAI_BASE_URL=${origin}${withBasePath("/proxy")}`,
+        value: `OPENAI_BASE_URL=${endpoints.openAiV1}`,
       },
     ],
-    [origin],
+    [endpoints],
   );
 
   const handleCopy = useCallback((id: string, value: string) => {

package/src/lib/basePath.ts

@@ -4,6 +4,8 @@ export const AGENT_INSPECTOR_BASE_PATH_ENV = "AGENT_INSPECTOR_BASE_PATH";
 export const AGENT_INSPECTOR_INTERNAL_STRIPPED_BASE_PATH_ENV =
   "AGENT_INSPECTOR_INTERNAL_STRIPPED_BASE_PATH";
 export const AGENT_INSPECTOR_BASE_PATH_META_NAME = "agent-inspector-base-path";
+export const AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER = "x-agent-inspector-public-base-path";
+export const AGENT_INSPECTOR_PUBLIC_PORT_HEADER = "x-agent-inspector-public-port";
 export const DEFAULT_AGENT_INSPECTOR_BASE_PATH = "/inspector";
 
 type BasePathEnv = Readonly<Record<string, string | undefined>>;
@@ -35,9 +37,13 @@ function readProcessBasePath(): string | undefined {
 }
 
 export function getConfiguredBasePath(env?: BasePathEnv): string {
+  if (env !== undefined) {
+    return normalizeBasePath(
+      env[AGENT_INSPECTOR_BASE_PATH_ENV] ?? DEFAULT_AGENT_INSPECTOR_BASE_PATH,
+    );
+  }
   return normalizeBasePath(
-    env?.[AGENT_INSPECTOR_BASE_PATH_ENV] ??
-      readProcessBasePath() ??
+    readProcessBasePath() ??
       readDocumentBasePath() ??
       import.meta.env?.BASE_URL ??
       DEFAULT_AGENT_INSPECTOR_BASE_PATH,

package/src/lib/codingAgentEndpoints.ts

@@ -0,0 +1,16 @@
+import { appendBasePathToOrigin } from "./basePath";
+
+export type CodingAgentEndpoints = {
+  proxy: string;
+  openAiV1: string;
+  mcp: string;
+};
+
+/** Derive the public protocol endpoints shown to coding agents from one Inspector origin. */
+export function deriveCodingAgentEndpoints(origin: string, basePath: string): CodingAgentEndpoints {
+  return {
+    proxy: appendBasePathToOrigin(origin, "/proxy", basePath),
+    openAiV1: appendBasePathToOrigin(origin, "/proxy/v1", basePath),
+    mcp: appendBasePathToOrigin(origin, "/api/mcp", basePath),
+  };
+}

package/src/lib/instanceContract.ts

@@ -0,0 +1,220 @@
+import { z } from "zod";
+
+export const INSTANCE_API_SCHEMA_VERSION = 1;
+
+export const InstanceStateSchema = z.enum(["running", "stopped", "conflict"]);
+export const InstanceStateReasonSchema = z.enum(["identity_mismatch", "port_conflict"]);
+
+export const InstanceUrlsSchema = z
+  .object({
+    ui: z.url(),
+    api: z.url(),
+    health: z.url(),
+    proxy: z.url(),
+    openai: z.url(),
+    mcp: z.url(),
+  })
+  .strict();
+
+export const InstanceStatusOutputSchema = z
+  .object({
+    schemaVersion: z.literal(INSTANCE_API_SCHEMA_VERSION),
+    name: z.string().min(1),
+    instanceId: z.string().min(1),
+    state: InstanceStateSchema,
+    stateReason: InstanceStateReasonSchema.nullable(),
+    checkedAt: z.iso.datetime(),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime(),
+    launch: z
+      .object({
+        launchId: z.string().min(1),
+        startedAt: z.iso.datetime(),
+      })
+      .strict(),
+    host: z.string().min(1),
+    publicPort: z.number().int().min(1).max(65_535),
+    upstreamPort: z.number().int().min(1).max(65_535),
+    basePath: z.string().startsWith("/"),
+    captureMode: z.enum(["simple", "full"]),
+    dataDir: z.string().min(1),
+    supervisorPid: z.number().int().positive().nullable(),
+    urls: InstanceUrlsSchema,
+  })
+  .strict();
+
+export const InstanceConnectionOutputSchema = z
+  .object({
+    schemaVersion: z.literal(INSTANCE_API_SCHEMA_VERSION),
+    instance: InstanceStatusOutputSchema,
+    baseUrl: z.url(),
+    endpoints: InstanceUrlsSchema,
+    environment: z
+      .object({
+        ANTHROPIC_BASE_URL: z.url(),
+        LLM_BASE_URL: z.url(),
+        OPENAI_BASE_URL: z.url(),
+        AGENT_INSPECTOR_MCP_URL: z.url(),
+      })
+      .strict(),
+    mcp: z
+      .object({
+        serverName: z.string().min(1),
+        transport: z.literal("streamable-http"),
+        url: z.url(),
+      })
+      .strict(),
+    codex: z
+      .object({
+        providerName: z.string().min(1),
+        baseUrl: z.url(),
+        wireApi: z.literal("responses"),
+      })
+      .strict(),
+  })
+  .strict();
+
+export const InstanceStartRequestSchema = z
+  .object({
+    port: z.number().int().min(1).max(65_535).optional(),
+    basePath: z
+      .string()
+      .min(1)
+      .max(2_048)
+      .refine(
+        (value) =>
+          value.startsWith("/") &&
+          !value.includes("?") &&
+          !value.includes("#") &&
+          !value.includes("\\"),
+        "Base Path must be an absolute URL path without query, hash, or backslash",
+      )
+      .optional(),
+    host: z
+      .string()
+      .min(1)
+      .max(253)
+      .refine(
+        (value) =>
+          value.trim() === value &&
+          !value.includes("://") &&
+          !value.includes("/") &&
+          !value.includes("\\") &&
+          !/\s/u.test(value),
+        "Host must be a hostname or IP address without protocol, path, or whitespace",
+      )
+      .optional(),
+    captureMode: z.enum(["simple", "full"]).optional(),
+    dataDir: z.string().trim().min(1).max(32_767).optional(),
+  })
+  .strict();
+
+export const InstanceEmptyRequestSchema = z.object({}).strict();
+
+export const InstanceOperationSchema = z.enum(["start", "stop", "restart"]);
+export const InstanceOperationOutcomeSchema = z.enum([
+  "created",
+  "started",
+  "already_running",
+  "stopped",
+  "already_stopped",
+  "restarted",
+]);
+
+export const InstanceOperationOutputSchema = z
+  .object({
+    schemaVersion: z.literal(INSTANCE_API_SCHEMA_VERSION),
+    operation: InstanceOperationSchema,
+    outcome: InstanceOperationOutcomeSchema,
+    instance: InstanceStatusOutputSchema,
+  })
+  .strict();
+
+export const InstanceListOutputSchema = z
+  .object({
+    schemaVersion: z.literal(INSTANCE_API_SCHEMA_VERSION),
+    instances: z.array(InstanceStatusOutputSchema),
+  })
+  .strict();
+
+export const InstancePublicErrorCodeSchema = z.enum([
+  "argument_invalid",
+  "config_mismatch",
+  "data_dir_conflict",
+  "data_dir_invalid",
+  "identity_mismatch",
+  "instance_not_found",
+  "launch_failed",
+  "launch_unavailable",
+  "lock_not_owned",
+  "lock_timeout",
+  "name_invalid",
+  "port_conflict",
+  "port_exhausted",
+  "port_invalid",
+  "record_invalid",
+  "registry_io",
+  "restart_failed_degraded",
+  "restart_failed_rolled_back",
+  "self_lifecycle_unsupported",
+  "shutdown_failed",
+]);
+
+export const InstancePublicErrorSchema = z
+  .object({
+    code: InstancePublicErrorCodeSchema,
+    message: z.string().min(1),
+    retryable: z.boolean(),
+  })
+  .strict();
+
+export const InstanceErrorOutputSchema = z
+  .object({
+    schemaVersion: z.literal(INSTANCE_API_SCHEMA_VERSION),
+    error: InstancePublicErrorSchema,
+  })
+  .strict();
+
+export type InstanceState = z.infer<typeof InstanceStateSchema>;
+export type InstanceStateReason = z.infer<typeof InstanceStateReasonSchema>;
+export type InstanceStatusOutput = z.infer<typeof InstanceStatusOutputSchema>;
+export type InstanceConnectionOutput = z.infer<typeof InstanceConnectionOutputSchema>;
+export type InstanceStartRequest = z.infer<typeof InstanceStartRequestSchema>;
+export type InstanceOperation = z.infer<typeof InstanceOperationSchema>;
+export type InstanceOperationOutcome = z.infer<typeof InstanceOperationOutcomeSchema>;
+export type InstanceOperationOutput = z.infer<typeof InstanceOperationOutputSchema>;
+export type InstanceListOutput = z.infer<typeof InstanceListOutputSchema>;
+export type InstancePublicErrorCode = z.infer<typeof InstancePublicErrorCodeSchema>;
+export type InstancePublicError = z.infer<typeof InstancePublicErrorSchema>;
+export type InstanceErrorOutput = z.infer<typeof InstanceErrorOutputSchema>;
+
+export function isRetryableInstanceError(code: InstancePublicErrorCode): boolean {
+  switch (code) {
+    case "launch_failed":
+    case "launch_unavailable":
+    case "lock_timeout":
+    case "port_exhausted":
+    case "registry_io":
+    case "restart_failed_degraded":
+    case "restart_failed_rolled_back":
+    case "shutdown_failed":
+      return true;
+    case "argument_invalid":
+    case "config_mismatch":
+    case "data_dir_conflict":
+    case "data_dir_invalid":
+    case "identity_mismatch":
+    case "instance_not_found":
+    case "lock_not_owned":
+    case "name_invalid":
+    case "port_conflict":
+    case "port_invalid":
+    case "record_invalid":
+    case "self_lifecycle_unsupported":
+      return false;
+  }
+}
+
+export function instanceErrorOutput(error: InstancePublicError): InstanceErrorOutput {
+  return { schemaVersion: INSTANCE_API_SCHEMA_VERSION, error };
+}