@huynle/hub 0.6.1 → 0.7.2

package/src/central/agent/launch-routes.ts

@@ -0,0 +1,252 @@
+// The launch API on /api/agent (design §6.1, §7, §8; decision znbg8xa5): thin HTTP over the launch engine
+// (launch-engine.ts, Central.launches).
+//
+//   POST   /api/agent/launches                     {launch spec}  → 201 {launch}; an idempotent repeat (same key and
+//                                                                   body) → 200 {launch}; same key, other body → 400
+//   GET    /api/agent/launches?state=a,b&label=k=v  → {launches} (oldest first; every label must match)
+//   GET    /api/agent/launches/:id                  → {launch}
+//   DELETE /api/agent/launches/:id                  → 200 {launch} (ended stopped); already ended → 410 gone
+//
+// Who: users always (their own launches; tenancy only). App tokens with scope sessions:launch and sessions through
+// their act token (never a shell token) under a grant of their user with verb `launch` covering the repo, in the
+// acting order: kill switch → grant usable → grant action consumed (hourly cap; an idempotent repeat spends none)
+// → kill switch again → the engine. Apps and sessions see and stop only the launches they started (by); any other
+// launch, like another user's, is 404 not_found. The engine applies the per-user launch caps (rate_limited).
+// Every outcome once the body is valid is in the agent audit (verb launch, or launch.stop for DELETE).
+import type { LaunchInfo, LaunchSpec as WireSpec } from "../../protocol"
+import { Feed } from "../cluster/feed"
+import type { ActingSwitch } from "./acting-switch"
+import { auditOf } from "./acting"
+import type { AgentActor } from "./actor"
+import type { AgentAudit, AuditDecision, AuditOutcome, AuditTarget } from "./audit"
+import type { Directory } from "./directory"
+import { partyFromActor, type Party } from "./envelope"
+import { AgentError } from "./errors"
+import type { Grant, Grants } from "./grants"
+import type { LaunchEngine, LaunchView } from "./launch-engine"
+import { type LaunchSpec, validateLaunchSpec } from "./launch-spec"
+import { LAUNCH_STATES, type Launch, type LaunchFilter, type LaunchState, type LaunchStep } from "./launch-store"
+import type { AgentRoute } from "./routes"
+
+// A literal: routes.ts imports this module (AGENT_PREFIX is not initialised yet when it loads).
+const PATH = "/api/agent/launches"
+const NO_STORE = { "cache-control": "no-store" }
+/** Users; sessions by their act token; apps with sessions:launch. */
+const LAUNCH = { act: true, scope: "sessions:launch" } as const
+
+export type RouteLaunches = Pick<LaunchEngine, "accept" | "view" | "list" | "stop">
+
+export interface LaunchRoutesDeps {
+  readonly launches: RouteLaunches
+  readonly grants: Pick<Grants, "usable" | "consume">
+  readonly acting: Pick<ActingSwitch, "ensureActing">
+  readonly audit: Pick<AgentAudit, "record">
+  /** Names a session caller in the audit. */
+  readonly directory?: Pick<Directory, "resolveOne">
+}
+
+/** A launch change for its user (the engine's onLaunchChanged). */
+export type LaunchListener = (userID: string, launch: Launch) => void
+
+/** Launch changes' Bus topic (cluster mode). */
+export const LAUNCHES_TOPIC = "feed.launches"
+
+/**
+ * Every launch change, per user: the hub's SSE 'launch' events, GET /api/agent/watch and webhooks (P4-T10)
+ * subscribe. A throwing listener is logged and never stops the others. Shared with the other pods once attached
+ * (see ../cluster/feed).
+ */
+export class LaunchFeed extends Feed<Launch> {
+  constructor() {
+    super(LAUNCHES_TOPIC, (cause) => console.error(`[hub] launch listener failed: ${cause instanceof Error ? cause.message : String(cause)}`))
+  }
+}
+
+/** A launch as the API shows it: LaunchInfo, plus who launched it and its steps. */
+export type LaunchApiView = LaunchInfo & { readonly by?: string; readonly history: readonly LaunchStep[] }
+
+const UNITS: readonly [string, number][] = [
+  ["d", 86_400_000],
+  ["h", 3_600_000],
+  ["m", 60_000],
+  ["s", 1000],
+]
+
+/** A duration as the launch API writes it (`4h`, `90m`, `45s`). */
+function duration(ms: number): string {
+  for (const [unit, size] of UNITS) if (ms % size === 0) return `${ms / size}${unit}`
+  return `${Math.ceil(ms / 1000)}s`
+}
+
+/** The validated spec as a request body (end.timeout as a duration). */
+function wireSpec(spec: LaunchSpec): WireSpec {
+  const { timeoutMs, ...end } = spec.end
+  return { ...spec, end: { ...end, ...(timeoutMs !== undefined ? { timeout: duration(timeoutMs) } : {}) } }
+}
+
+/** The API view of a launch: never its owner; `updated` is when it entered its state. */
+export function launchInfo(launch: LaunchView): LaunchApiView {
+  return {
+    id: launch.id,
+    state: launch.state,
+    reason: launch.reason,
+    spec: wireSpec(launch.spec),
+    created: launch.created,
+    updated: launch.at,
+    ...(launch.by !== undefined ? { by: launch.by } : {}),
+    ...(launch.machineID !== undefined ? { machineID: launch.machineID } : {}),
+    ...(launch.directory !== undefined ? { directory: launch.directory } : {}),
+    ...(launch.sessionID !== undefined ? { sessionID: launch.sessionID } : {}),
+    ...(launch.name !== undefined ? { name: launch.name } : {}),
+    ...(launch.outcome !== undefined ? { outcome: launch.outcome } : {}),
+    ...(launch.artifacts !== undefined ? { artifacts: launch.artifacts as LaunchInfo["artifacts"] } : {}),
+    history: launch.history,
+  }
+}
+
+/** Who launched, as the launch records it: `user`, `app:<token id>` or the session ID. */
+export function launchedBy(actor: AgentActor): string {
+  switch (actor.kind) {
+    case "user":
+      return "user"
+    case "app":
+      return `app:${actor.tokenID}`
+    case "session":
+      return actor.sessionID
+  }
+}
+
+const invalid = (message: string) => new AgentError("invalid", message)
+const notFound = (id: string) => new AgentError("not_found", `No launch ${id}`)
+
+async function bodyOf(request: Request): Promise<unknown> {
+  return JSON.parse(await request.text())
+}
+
+/** ?state=a,b and ?label=k=v (repeated). */
+function filterOf(params: URLSearchParams): LaunchFilter {
+  const raw = params.get("state")
+  const states = raw === null ? undefined : raw.split(",").filter(Boolean)
+  if (states?.some((s) => !(LAUNCH_STATES as readonly string[]).includes(s))) throw invalid(`state must be ${LAUNCH_STATES.join(", ")} (comma-separated)`)
+  const labels: Record<string, string> = {}
+  for (const label of params.getAll("label")) {
+    const at = label.indexOf("=")
+    if (at < 1) throw invalid("label must be key=value")
+    labels[label.slice(0, at)] = label.slice(at + 1)
+  }
+  return { ...(states?.length ? { states: states as LaunchState[] } : {}), ...(Object.keys(labels).length ? { labels } : {}) }
+}
+
+export function launchRoutes(deps: LaunchRoutesDeps): AgentRoute[] {
+  const { launches, grants, acting, audit } = deps
+
+  const party = (userID: string, actor: AgentActor): Party => {
+    if (actor.kind !== "session" || !deps.directory) return partyFromActor(actor)
+    let name: string | undefined
+    try {
+      name = deps.directory.resolveOne(userID, actor.sessionID).name
+    } catch {}
+    return partyFromActor(actor, name ? { name } : {})
+  }
+
+  /** The caller's launch: not_found when unknown, another user's, or (apps, sessions) started by someone else. */
+  const own = async (userID: string, actor: AgentActor, id: string): Promise<LaunchView> => {
+    const launch = await launches.view(userID, id)
+    if (!launch || (actor.kind !== "user" && launch.by !== launchedBy(actor))) throw notFound(id)
+    return launch
+  }
+
+  /**
+   * Runs `run` for the caller in the acting order (agents: kill switch, launch grant on the repo, its action
+   * spent unless `spend` is false, kill switch again) and audits the outcome.
+   */
+  async function act<T>(
+    userID: string,
+    actor: AgentActor,
+    verb: string,
+    repo: string,
+    plan: { readonly target: () => AuditTarget; readonly spend: () => Promise<boolean>; readonly run: () => Promise<T> },
+  ): Promise<T> {
+    let grant: Grant | undefined
+    const record = (decision: AuditDecision, outcome: AuditOutcome, reason?: string) =>
+      audit.record(userID, { actor: party(userID, actor), verb, target: plan.target(), ...(grant ? { grant: grant.id } : {}), decision, ...(reason ? { reason } : {}), outcome })
+    try {
+      if (actor.kind !== "user") {
+        acting.ensureActing(userID)
+        const usable = await grants.usable(actor, "launch", { directory: repo })
+        if (!usable.length) throw new AgentError("forbidden", `No grant lets this ${actor.kind} launch in ${repo}`)
+        grant = usable[0]!
+        if (await plan.spend()) await grants.consume(grant)
+        acting.ensureActing(userID)
+      }
+      const result = await plan.run()
+      await record("allow", "ok")
+      return result
+    } catch (cause) {
+      const [decision, outcome] = auditOf(cause)
+      await record(decision, outcome, cause instanceof Error ? cause.message : undefined)
+      throw cause
+    }
+  }
+
+  return [
+    {
+      method: "POST",
+      path: PATH,
+      allow: LAUNCH,
+      async handle({ request, actor, user }) {
+        const raw = await bodyOf(request)
+        const spec = validateLaunchSpec(raw)
+        const by = launchedBy(actor)
+        const held = spec.key === undefined ? undefined : (await launches.list(user.id)).find((l) => l.spec.key === spec.key)
+        let launchID: string | undefined
+        const result = await act(user.id, actor, "launch", spec.workspace.repo, {
+          target: () => (launchID !== undefined ? { launchID } : {}),
+          // An idempotent repeat spends no grant action.
+          spend: async () => held === undefined,
+          run: async () => {
+            // An agent never gets another launcher's launch through its key.
+            if (held && actor.kind !== "user" && held.by !== by) throw new AgentError("invalid", "This key was used by another launcher", { hint: "Use a key of your own" })
+            const accepted = await launches.accept(user.id, raw, { by })
+            launchID = accepted.launch.id
+            return accepted
+          },
+        })
+        return Response.json({ launch: launchInfo(result.launch) }, { status: result.created ? 201 : 200, headers: NO_STORE })
+      },
+    },
+    {
+      method: "GET",
+      path: PATH,
+      allow: LAUNCH,
+      async handle({ url, actor, user }) {
+        const filter = filterOf(url.searchParams)
+        const by = actor.kind === "user" ? undefined : launchedBy(actor)
+        const list = (await launches.list(user.id, filter)).filter((l) => by === undefined || l.by === by)
+        return Response.json({ launches: list.map(launchInfo) }, { headers: NO_STORE })
+      },
+    },
+    {
+      method: "GET",
+      path: `${PATH}/:id`,
+      allow: LAUNCH,
+      async handle({ params, actor, user }) {
+        return Response.json({ launch: launchInfo(await own(user.id, actor, params.id!)) }, { headers: NO_STORE })
+      },
+    },
+    {
+      method: "DELETE",
+      path: `${PATH}/:id`,
+      allow: LAUNCH,
+      async handle({ params, actor, user }) {
+        const launch = await own(user.id, actor, params.id!)
+        const stopped = await act(user.id, actor, "launch.stop", launch.spec.workspace.repo, {
+          target: () => ({ launchID: launch.id, ...(launch.sessionID !== undefined ? { sessionID: launch.sessionID } : {}) }),
+          spend: async () => true,
+          run: () => launches.stop(user.id, launch.id),
+        })
+        return Response.json({ launch: launchInfo(stopped) }, { headers: NO_STORE })
+      },
+    },
+  ]
+}

package/src/central/agent/launch-spec.ts

@@ -0,0 +1,289 @@
+// The launch spec (design §6.1, §6.4; decision znbg8xa5): validates a POST /api/agent/launches body into a
+// LaunchSpec with the defaults filled in. Pure: no state, no I/O; tenancy, grants, caps and placement are the
+// launch engine's. Malformed input is AgentError invalid.
+// - Git-facing fields are strict because the node hands them to git (argv only, never a shell): branch and base
+//   follow `git check-ref-format --branch` with no option-like (`-`) component; remotes are https or ssh only
+//   (no credentials in the URL, no `ext::`, `file://`, local paths or option-like hosts); repo is an absolute path.
+// - `grant` is not supported in phase 4 (a launched session gets no powers beyond its launcher's).
+// - labels are free-form and never interpreted by the hub, but bounded (LABELS_MAX entries, short keys and values).
+// - Defaults: harness opencode, workspace mode worktree, runtime host, placement mode require, end when idle,
+//   cleanup keep, no timeout.
+// LaunchSpec is defined here until packages/protocol carries it (P4-T1); keep the two in step.
+
+import { AgentError } from "./errors"
+import { isReservedName, parseAddress, validName } from "./names"
+import { canonicalProject, parseDuration } from "./policy"
+
+export type WorkspaceMode = "worktree" | "checkout" | "clone"
+export type RuntimeKind = "host" | "openshell"
+export type PlacementMode = "require" | "prefer"
+export type EndWhen = "idle" | "asked" | "never"
+export type CleanupPolicy = "keep" | "remove"
+
+export interface LaunchWorkspace {
+  /** Canonical absolute path of the repository on the node. */
+  readonly repo: string
+  readonly mode: WorkspaceMode
+  /** The branch to create or check out (required for worktree). */
+  readonly branch?: string
+  /** What a new branch starts from. */
+  readonly base?: string
+  /** https or ssh remote (required for clone). */
+  readonly remote?: string
+}
+
+export interface LaunchRuntime {
+  readonly kind: RuntimeKind
+  /** An openshell sandbox profile of the user's. */
+  readonly profile?: string
+}
+
+export interface LaunchPlacement {
+  /** Node labels to match. */
+  readonly labels: Readonly<Record<string, string>>
+  /** A machine ID or name. */
+  readonly machine?: string
+  readonly mode: PlacementMode
+}
+
+export interface LaunchEnd {
+  readonly when: EndWhen
+  readonly timeoutMs?: number
+  readonly cleanup: CleanupPolicy
+}
+
+export interface LaunchSpec {
+  /** App-chosen idempotency key: the same key (and body) returns the same launch. */
+  readonly key?: string
+  /** The session's @name (without the @). */
+  readonly name?: string
+  readonly roles: readonly string[]
+  readonly harness: string
+  readonly agent?: string
+  /** `provider/model`. */
+  readonly model?: string
+  readonly workspace: LaunchWorkspace
+  readonly runtime: LaunchRuntime
+  readonly placement: LaunchPlacement
+  readonly prompt?: string
+  /** Free-form app labels (never interpreted by the hub). */
+  readonly labels: Readonly<Record<string, string>>
+  readonly end: LaunchEnd
+}
+
+export const KEY_MAX = 200
+export const ROLES_MAX = 10
+export const PROMPT_MAX = 10_000
+export const LABELS_MAX = 32
+export const LABEL_KEY_MAX = 63
+export const LABEL_VALUE_MAX = 256
+export const BRANCH_MAX = 200
+export const REMOTE_MAX = 500
+export const MODEL_MAX = 200
+export const LAUNCH_TIMEOUT_MIN_MS = 60_000
+export const LAUNCH_TIMEOUT_MAX_MS = 30 * 86_400_000
+
+const FIELDS = ["key", "name", "roles", "harness", "agent", "model", "workspace", "runtime", "placement", "prompt", "labels", "end"]
+const WORKSPACE_FIELDS = ["repo", "mode", "branch", "base", "remote"]
+const RUNTIME_FIELDS = ["kind", "profile"]
+const PLACEMENT_FIELDS = ["labels", "machine", "mode"]
+const END_FIELDS = ["when", "timeout", "cleanup"]
+
+const KEY = /^[!-~]{1,200}$/
+const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/
+const AGENT = /^[A-Za-z0-9_.-]{1,80}$/
+const MODEL = /^[A-Za-z0-9._-]{1,80}\/[!-~]+$/
+const MACHINE = /^[A-Za-z0-9._-]{1,80}$/
+const LABEL_KEY = /^[A-Za-z0-9](?:[A-Za-z0-9._/-]*[A-Za-z0-9])?$/
+/** Control characters (C0, DEL, C1). */
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/
+/** Control characters other than tab, newline and carriage return. */
+const PROMPT_CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/
+
+const invalid = (message: string, hint?: string) => new AgentError("invalid", message, hint ? { hint } : {})
+const isObject = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value)
+
+function onlyFields(value: Record<string, unknown>, allowed: readonly string[], what: string): void {
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw invalid(`Unknown ${what} field ${key}`)
+}
+
+function oneOf<T extends string>(value: unknown, options: readonly T[], fallback: T, what: string): T {
+  if (value === undefined) return fallback
+  if (!options.includes(value as T)) throw invalid(`${what} is ${options.join(", ")}`)
+  return value as T
+}
+
+function matching(value: unknown, pattern: RegExp, what: string, max = Infinity): string | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== "string" || value.length > max || !pattern.test(value)) throw invalid(`${what} is malformed`)
+  return value
+}
+
+// ---------- git ----------
+
+/** A branch name `git check-ref-format --branch` accepts, printable ASCII, with no component starting with `-`. */
+export function validBranch(name: unknown): boolean {
+  if (typeof name !== "string" || name.length === 0 || name.length > BRANCH_MAX) return false
+  if (!/^[!-~]+$/.test(name) || /[~^:?*[\\]/.test(name)) return false
+  if (name === "@" || name === "HEAD" || name.includes("@{") || name.includes("..")) return false
+  if (name.startsWith("/") || name.endsWith("/") || name.endsWith(".") || name.includes("//")) return false
+  return name.split("/").every((part) => !part.startsWith(".") && !part.startsWith("-") && !part.endsWith(".lock"))
+}
+
+const HOST = "[A-Za-z0-9][A-Za-z0-9.-]*"
+const USER = "[A-Za-z0-9_][A-Za-z0-9._-]*"
+const PORT = "(?::\\d{1,5})?"
+const REMOTES = [
+  new RegExp(`^https://${HOST}${PORT}/[!-~]+$`),
+  new RegExp(`^ssh://(?:${USER}@)?${HOST}${PORT}/[!-~]+$`),
+  new RegExp(`^${USER}@${HOST}:(?![-/])[!-~]+$`),
+]
+
+/** An https or ssh git remote (URL or scp-like `user@host:path`), without credentials or option-like parts. */
+export function validRemote(remote: unknown): boolean {
+  if (typeof remote !== "string" || remote.length === 0 || remote.length > REMOTE_MAX) return false
+  return REMOTES.some((pattern) => pattern.test(remote))
+}
+
+// ---------- parts ----------
+
+function validLabels(value: unknown, what: string): Record<string, string> {
+  if (value === undefined) return {}
+  if (!isObject(value)) throw invalid(`${what} is an object of string values`)
+  const entries = Object.entries(value)
+  if (entries.length > LABELS_MAX) throw invalid(`${what} has at most ${LABELS_MAX} entries`)
+  const out: Record<string, string> = {}
+  for (const [key, text] of entries) {
+    if (key.length > LABEL_KEY_MAX || !LABEL_KEY.test(key)) throw invalid(`${what}: ${key.slice(0, LABEL_KEY_MAX)} is not a label key (letters, digits, . _ / -; up to ${LABEL_KEY_MAX})`)
+    if (typeof text !== "string" || text.length > LABEL_VALUE_MAX || CONTROL.test(text)) throw invalid(`${what}.${key} is a string of up to ${LABEL_VALUE_MAX} characters`)
+    out[key] = text
+  }
+  return out
+}
+
+function validRoles(value: unknown): string[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || value.length > ROLES_MAX) throw invalid(`roles lists up to ${ROLES_MAX} role names`)
+  const roles: string[] = []
+  for (const role of value) {
+    if (typeof role !== "string" || parseAddress(`@@${role}`)?.kind !== "role") throw invalid(`roles: ${String(role)} is not a role name (such as reviewer or reviewer.hub)`)
+    if (!roles.includes(role)) roles.push(role)
+  }
+  return roles
+}
+
+function validWorkspace(value: unknown): LaunchWorkspace {
+  if (!isObject(value)) throw invalid("workspace is {repo, mode?, branch?, base?, remote?}")
+  onlyFields(value, WORKSPACE_FIELDS, "workspace")
+  // canonicalProject rejects relative, `~` and root paths.
+  const repo = typeof value.repo === "string" ? canonicalProject(value.repo) : undefined
+  if (repo === undefined) throw invalid("workspace.repo is an absolute repository path")
+  const mode = oneOf<WorkspaceMode>(value.mode, ["worktree", "checkout", "clone"], "worktree", "workspace.mode")
+  for (const field of ["branch", "base"] as const) {
+    if (value[field] !== undefined && !validBranch(value[field])) throw invalid(`workspace.${field} is not a safe git branch name`, "Branch names follow git check-ref-format and never start with -")
+  }
+  if (value.remote !== undefined && !validRemote(value.remote)) throw invalid("workspace.remote is an https or ssh git remote", "Use https://host/path or git@host:path, without credentials")
+  if (mode === "worktree" && value.branch === undefined) throw invalid("A worktree workspace needs workspace.branch")
+  if (mode === "clone" && value.remote === undefined) throw invalid("A clone workspace needs workspace.remote")
+  return {
+    repo,
+    mode,
+    ...(value.branch !== undefined ? { branch: value.branch as string } : {}),
+    ...(value.base !== undefined ? { base: value.base as string } : {}),
+    ...(value.remote !== undefined ? { remote: value.remote as string } : {}),
+  }
+}
+
+function validRuntime(value: unknown, workspace: LaunchWorkspace): LaunchRuntime {
+  if (value === undefined) return { kind: "host" }
+  if (!isObject(value)) throw invalid("runtime is {kind, profile?}")
+  onlyFields(value, RUNTIME_FIELDS, "runtime")
+  const kind = oneOf<RuntimeKind>(value.kind, ["host", "openshell"], "host", "runtime.kind")
+  const profile = matching(value.profile, SLUG, "runtime.profile")
+  if (kind === "host" && profile !== undefined) throw invalid("runtime.profile applies to the openshell runtime only")
+  if (kind === "openshell" && workspace.mode !== "clone") throw invalid("The openshell runtime runs clone workspaces only")
+  return { kind, ...(profile !== undefined ? { profile } : {}) }
+}
+
+function validPlacement(value: unknown): LaunchPlacement {
+  if (value === undefined) return { labels: {}, mode: "require" }
+  if (!isObject(value)) throw invalid("placement is {labels?, machine?, mode?}")
+  onlyFields(value, PLACEMENT_FIELDS, "placement")
+  const labels = validLabels(value.labels, "placement.labels")
+  const machine = matching(value.machine, MACHINE, "placement.machine")
+  const mode = oneOf<PlacementMode>(value.mode, ["require", "prefer"], "require", "placement.mode")
+  return { labels, ...(machine !== undefined ? { machine } : {}), mode }
+}
+
+function validEnd(value: unknown): LaunchEnd {
+  if (value === undefined) return { when: "idle", cleanup: "keep" }
+  if (!isObject(value)) throw invalid("end is {when?, timeout?, cleanup?}")
+  onlyFields(value, END_FIELDS, "end")
+  const when = oneOf<EndWhen>(value.when, ["idle", "asked", "never"], "idle", "end.when")
+  let timeoutMs: number | undefined
+  if (value.timeout !== undefined) {
+    timeoutMs = parseDuration(value.timeout)
+    if (timeoutMs === undefined || timeoutMs < LAUNCH_TIMEOUT_MIN_MS || timeoutMs > LAUNCH_TIMEOUT_MAX_MS) throw invalid("end.timeout is 1 minute to 30 days (seconds, or 30m, 4h, 2d)")
+  }
+  const cleanup = oneOf<CleanupPolicy>(value.cleanup, ["keep", "remove"], "keep", "end.cleanup")
+  return { when, ...(timeoutMs !== undefined ? { timeoutMs } : {}), cleanup }
+}
+
+// ---------- spec ----------
+
+/** Validates a launch body into a LaunchSpec (a fresh copy, defaults filled in); throws AgentError invalid. */
+export function validateLaunchSpec(input: unknown): LaunchSpec {
+  if (!isObject(input)) throw invalid("A launch is an object")
+  if ("grant" in input) throw invalid("grant is not supported yet: a launched session has its launcher's powers only")
+  onlyFields(input, FIELDS, "launch")
+  const key = matching(input.key, KEY, `key (1–${KEY_MAX} visible characters)`)
+  let name: string | undefined
+  if (input.name !== undefined) {
+    if (typeof input.name !== "string" || !validName(input.name) || isReservedName(input.name)) throw invalid("name is a session name (lowercase letters, digits, dashes; 2–40), without the @")
+    name = input.name
+  }
+  const roles = validRoles(input.roles)
+  const harness = matching(input.harness, SLUG, "harness") ?? "opencode"
+  const agent = matching(input.agent, AGENT, "agent")
+  const model = matching(input.model, MODEL, "model (provider/model)", MODEL_MAX)
+  const workspace = validWorkspace(input.workspace)
+  const runtime = validRuntime(input.runtime, workspace)
+  const placement = validPlacement(input.placement)
+  let prompt: string | undefined
+  if (input.prompt !== undefined) {
+    if (typeof input.prompt !== "string" || input.prompt.length > PROMPT_MAX || PROMPT_CONTROL.test(input.prompt)) throw invalid(`prompt is text of up to ${PROMPT_MAX} characters`)
+    prompt = input.prompt
+  }
+  const labels = validLabels(input.labels, "labels")
+  const end = validEnd(input.end)
+  return {
+    ...(key !== undefined ? { key } : {}),
+    ...(name !== undefined ? { name } : {}),
+    roles,
+    harness,
+    ...(agent !== undefined ? { agent } : {}),
+    ...(model !== undefined ? { model } : {}),
+    workspace,
+    runtime,
+    placement,
+    ...(prompt !== undefined ? { prompt } : {}),
+    labels,
+    end,
+  }
+}
+
+/** JSON with object keys sorted (stable for equal values). */
+function stable(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`
+  if (isObject(value)) {
+    const keys = Object.keys(value).filter((key) => value[key] !== undefined).sort()
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(",")}}`
+  }
+  return JSON.stringify(value)
+}
+
+/** What idempotency compares: the validated spec without its key, as stable JSON (equal for equivalent bodies). */
+export function launchBodyKey(spec: LaunchSpec): string {
+  const { key: _key, ...body } = spec
+  return stable(body)
+}