@zgeoff/atc 2.16.0 → 2.19.0

package/src/client/ui.ts

@@ -387,6 +387,9 @@ export interface PickerView {
   input: string;
   placeholder?: string;
   hint: string;
+
+  // The indexes of items drawn dim: listed, but not a fit for the flow.
+  dimmed?: ReadonlySet<number>;
 }
 
 export function drawPicker(view: PickerView) {
@@ -397,7 +400,9 @@ export function drawPicker(view: PickerView) {
   for (const [i, item] of shown.entries()) {
     const sel = i === view.selected;
     const t = truncate(item, width - 4);
-    const styled = sel ? `${ESC}[7m${t.padEnd(width - 4)}${ESC}[0m` : t;
+    const dim = view.dimmed?.has(i) === true;
+    const inverse = sel ? `${ESC}[7m${t.padEnd(width - 4)}${ESC}[0m` : t;
+    const styled = dim ? `${ESC}[90m${inverse}${ESC}[0m` : inverse;
     const plainLen = sel ? width - 4 : t.length;
 
     rowsList.push(boxRow(width, styled, plainLen));

package/src/daemon/daemon-connection.ts

@@ -19,6 +19,7 @@ import type { AgentID } from '../shared/agent-id';
 import { isRecord } from '../shared/report';
 import type { SessionID } from '../shared/session-id';
 import { toSessionID } from '../shared/to-session-id';
+import type { SourceProvider, SourceRequest } from '../sources/types';
 import { buildPayloadHash } from './build-payload-hash';
 import { buildScopedContext } from './build-scoped-context';
 import { buildTargetForbiddenError } from './build-target-forbidden-error';
@@ -43,6 +44,18 @@ interface ViewUpdate {
   readonly withdrawn: readonly SessionID[];
 }
 
+// What a source request holds: the source's id and the target it is for.
+interface SourceParams {
+  readonly source: string;
+  readonly target?: string | undefined;
+}
+
+// The source a request asks for, and the request the source serves.
+interface ResolvedSourceRequest {
+  readonly source: SourceProvider;
+  readonly request: SourceRequest;
+}
+
 interface PeerSocket extends SocketWriter {
   readonly end: () => void;
 }
@@ -409,6 +422,21 @@ export class DaemonConnection {
 
         return;
       }
+      case 'sources.list': {
+        await this.applySourcesList(req, ctx);
+
+        return;
+      }
+      case 'sources.interpret': {
+        await this.applySourcesInterpret(req, ctx);
+
+        return;
+      }
+      case 'git.probe': {
+        await this.applyGitProbe(req, ctx);
+
+        return;
+      }
       case 'session.spawn': {
         await this.applySpawn(req, ctx);
 
@@ -794,6 +822,107 @@ export class DaemonConnection {
     this.sendOk(req.id, spawned);
   }
 
+  // Lists one source's candidates for a spawn to the request's target.
+  private async applySourcesList(req: RequestMsg, ctx: DaemonContext): Promise<void> {
+    const parsed = parseRequestParams('sources.list', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const resolved = this.resolveSourceRequest(parsed.data, ctx);
+    const source = resolved.source;
+
+    const listed = await source.list(
+      {
+        ...(parsed.data.scope === undefined ? {} : { scope: parsed.data.scope }),
+        ...(parsed.data.text === undefined ? {} : { text: parsed.data.text }),
+      },
+      resolved.request,
+    );
+
+    this.sendOk(req.id, { source: source.id, scope: listed.scope, candidates: listed.candidates });
+  }
+
+  // Reads typed input through one source for a spawn to the request's
+  // target.
+  private async applySourcesInterpret(req: RequestMsg, ctx: DaemonContext): Promise<void> {
+    const parsed = parseRequestParams('sources.interpret', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const resolved = this.resolveSourceRequest(parsed.data, ctx);
+
+    const interpretation = await resolved.source.interpret(parsed.data.input, resolved.request);
+
+    this.sendOk(req.id, { ...interpretation });
+  }
+
+  // The source a request asks for and the request it serves, so a principal
+  // reaches a source only for a target it may spawn on, and a git source
+  // only for a target it may spawn a workspace on.
+  private resolveSourceRequest(params: SourceParams, ctx: DaemonContext): ResolvedSourceRequest {
+    const source = ctx.findSource(params.source);
+
+    if (source === null) {
+      throw new DaemonError('unsupported', `this daemon offers no source '${params.source}'`);
+    }
+
+    const target = ctx.resolveSpawnTarget(params.target);
+
+    if (source.kind === 'git') {
+      this.ctx.requireWorkspaceTarget(target);
+    }
+
+    // The spawn history is read through the request's own view, so a
+    // principal lists only directories spawned on targets it may use.
+    return { source, request: { target, collectSpawnDirs: () => ctx.collectSpawnDirs(null) } };
+  }
+
+  // Probes a git workspace source for a spawn to the request's target, so
+  // a principal probes only for a target it may spawn a workspace on. A
+  // refusal holds the repository's other URLs that the offered sources know.
+  private async applyGitProbe(req: RequestMsg, ctx: DaemonContext): Promise<void> {
+    const parsed = parseRequestParams('git.probe', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const data = parsed.data;
+
+    this.ctx.requireWorkspaceTarget(ctx.resolveSpawnTarget(data.target));
+
+    const access = await ctx.checkRepositoryAccess({
+      url: data.url,
+      ref: data.ref,
+      sha: data.sha,
+      credential: data.credentialRef,
+    });
+
+    if (!access.ok) {
+      const alternates = ctx.collectAlternateGitURLs(data.url);
+      const detail = alternates.length === 0 ? undefined : { alternates };
+
+      throw new DaemonError(access.code, access.message, detail);
+    }
+
+    this.sendOk(req.id, {
+      url: access.url,
+      head: access.head,
+      refs: access.refs,
+      resolved: access.resolved,
+    });
+  }
+
   private applyAttach(req: RequestMsg, ctx: DaemonContext): void {
     const parsed = parseRequestParams('session.attach', req.p);
 

package/src/daemon/daemon-context.ts

@@ -6,9 +6,11 @@ import type { TargetConfigError } from '../shared/collect-targets';
 import type { DaemonID } from '../shared/daemon-id';
 import type { MessageID } from '../shared/message-id';
 import type { SessionID } from '../shared/session-id';
+import type { SourceKind, SourceProvider } from '../sources/types';
 import type { FleetEntry } from '../store/fleet-entry';
 import type { MessageRecord } from '../store/message-record';
 import type { TurnSibling } from '../store/state-store';
+import type { checkRepositoryAccess } from '../workspace/check-repository-access';
 import type { Dims } from './attach-registry';
 import type { AgentEntry } from './build-agent-list';
 import type { FleetEvent } from './build-fleet-events';
@@ -79,6 +81,13 @@ interface AgentList {
   readonly spawnDefaults: { readonly agent: AgentID; readonly target: string | null };
   readonly configRevision: string;
   readonly targetErrors: readonly TargetConfigError[];
+
+  // The sources the spawn picker offers, in order.
+  readonly sources: readonly {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: SourceKind;
+  }[];
 }
 
 // The slice of a connection the attach bookkeeping needs: identity plus the
@@ -163,6 +172,20 @@ export interface DaemonContext {
   // one whose provider cannot both transfer an archive and run a command.
   readonly requireWorkspaceTarget: (target: string) => void;
 
+  // The source the daemon offers the spawn picker under an id, or null when
+  // it offers none under it.
+  readonly findSource: (id: string) => SourceProvider | null;
+
+  // The other URLs the offered sources know for a git URL the daemon's host
+  // could not read, each once.
+  readonly collectAlternateGitURLs: (url: string) => readonly string[];
+
+  // Checks that the daemon's host can read a git workspace source, and
+  // resolves its ref, the way a workspace spawn from it would.
+  readonly checkRepositoryAccess: (
+    request: Omit<Parameters<typeof checkRepositoryAccess>[0], 'transports'>,
+  ) => ReturnType<typeof checkRepositoryAccess>;
+
   // Runs the plan, which throws the refusal for a spawn it refuses, then
   // spawns. Answers with the `session.spawn` ok payload, which a keyed
   // retry replays as the first spawn answered it while the access, when

package/src/daemon/daemon.ts

@@ -13,12 +13,15 @@ import type { SpawnWorkspaceSource } from '../protocol/request-param-schemas';
 import type { SessionState } from '../protocol/session-state';
 import type { HooksConfig } from '../shared/collect-hooks';
 import type { TargetConfigError } from '../shared/collect-targets';
+import type { InvalidGitTransports } from '../shared/collect-workspaces-config';
+import { DEFAULT_GIT_TRANSPORTS } from '../shared/default-git-transports';
 import { findDaemonRecord } from '../shared/find-daemon-record';
 import type { MessageID } from '../shared/message-id';
 import { isRecord } from '../shared/report';
 import type { SessionID } from '../shared/session-id';
 import { toMessageID } from '../shared/to-message-id';
 import { truncateToBytes } from '../shared/truncate-to-bytes';
+import type { SourceProvider } from '../sources/types';
 import type { IdempotencyRecord } from '../store/idempotency-record';
 import type { MessageOwner } from '../store/message-owner';
 import type { MessageRecord, MessageStatus } from '../store/message-record';
@@ -26,6 +29,7 @@ import { StateStore } from '../store/state-store';
 import type { EventScope } from '../store/state-store';
 import type { TrailEntry } from '../store/trail-entry';
 import type { SessionWorkspace } from '../store/workspace-materialization';
+import { checkRepositoryAccess } from '../workspace/check-repository-access';
 import { ANSWER_BYTE_CAP } from './answer-byte-cap';
 import { AttachRegistry } from './attach-registry';
 import { buildAgentList } from './build-agent-list';
@@ -68,6 +72,7 @@ import { mintMessageID } from './mint-message-id';
 import { mintSessionID } from './mint-session-id';
 import { parseReport } from './parse-report';
 import { PermissionRegistry } from './permission-registry';
+import { requireGitTransports } from './require-git-transports';
 import { restoreFleet } from './restore-fleet';
 import { runEjectHandoff } from './run-eject-handoff';
 import { ScreenModel } from './screen-model';
@@ -153,6 +158,15 @@ export interface DaemonOptions {
   // Where background failures are reported, one line at a time; stderr
   // when unset.
   readonly log?: (line: string) => void;
+
+  // The sources the spawn picker offers, in order, each built with the
+  // services it uses; none when unset.
+  readonly sources?: readonly SourceProvider[];
+
+  // The transports a git workspace source may use and git may fetch over,
+  // or the invalid list the config holds, which refuses every git
+  // operation; https and ssh when unset.
+  readonly gitTransports?: readonly string[] | InvalidGitTransports;
 }
 
 export interface DaemonHandle {
@@ -236,6 +250,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
   const targetErrors = opts.targetErrors ?? [];
   const principals = opts.principals ?? null;
+  const gitTransports = opts.gitTransports ?? DEFAULT_GIT_TRANSPORTS;
 
   const targetsByID = new Map(targets.map((target) => [target.id, target]));
 
@@ -911,6 +926,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
           mgr.log(line);
         },
         stagingRoot: tmpdir(),
+        gitTransports,
       },
     );
   };
@@ -1192,6 +1208,8 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     }
   };
 
+  const sources = opts.sources ?? [];
+
   const ctx: DaemonContext = {
     build: opts.build,
     daemonID: store.daemonID,
@@ -1215,6 +1233,11 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       spawnDefaults: { agent: 'claude', target: defaultTarget },
       configRevision,
       targetErrors,
+      sources: sources.map((source) => ({
+        id: source.id,
+        label: source.label,
+        kind: source.kind,
+      })),
     }),
     collectFleet: () => store.loadFleet(),
     loadLastUsedAgent: () => store.loadLastUsedAgent(),
@@ -1256,6 +1279,12 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       mgr.requireExecution({ target, targetIdentity: null }, 'transfer');
       mgr.requireExecution({ target, targetIdentity: null }, 'run');
     },
+    findSource: (id) => sources.find((source) => source.id === id) ?? null,
+    collectAlternateGitURLs: (url) => [
+      ...new Set(sources.flatMap((source) => source.findAlternateURLs?.(url) ?? [])),
+    ],
+    checkRepositoryAccess: (request) =>
+      checkRepositoryAccess({ ...request, transports: requireGitTransports(gitTransports) }),
     spawnSession: (plan, keyed, access) => {
       // Under an access, a spawn under a parent whose tree leaves the access
       // before the harness starts is refused as a spawn under an unknown

package/src/daemon/materialize-workspace.ts

@@ -3,18 +3,22 @@ import { dirname, join, resolve } from 'node:path';
 import { DaemonError } from '../protocol/daemon-error';
 import type { ErrorCode } from '../protocol/protocol';
 import type { SpawnWorkspaceSource } from '../protocol/request-param-schemas';
+import type { InvalidGitTransports } from '../shared/collect-workspaces-config';
 import type { SessionID } from '../shared/session-id';
 import type { StateStore } from '../store/state-store';
 import type { MaterializationPhase, SessionWorkspace } from '../store/workspace-materialization';
 import { checkURLCredentials } from '../workspace/check-url-credentials';
 import { createWorkspaceClone } from '../workspace/create-workspace-clone';
+import { expandGitShorthand } from '../workspace/expand-git-shorthand';
 import { normalizeGitURL } from '../workspace/normalize-git-url';
 import { readWorkspaceTar } from '../workspace/read-workspace-tar';
 import { REPOSITORY_ENV_VARS } from '../workspace/repository-env-vars';
+import { resolveGitURL } from '../workspace/resolve-git-url';
 import { resolvePathSource } from '../workspace/resolve-path-source';
 import { runGit } from '../workspace/run-git';
 import { sanitizeWorkspaceClone } from '../workspace/sanitize-workspace-clone';
 import type { ExecutionProvider } from './execution-provider';
+import { requireGitTransports } from './require-git-transports';
 
 interface MaterializeRequest {
   readonly sessionID: SessionID;
@@ -39,6 +43,10 @@ interface MaterializeDeps {
   // The directory on the daemon's host that holds each clone's staging
   // directory while the workspace is built.
   readonly stagingRoot: string;
+
+  // The transports a source may use and git may fetch over, or the invalid
+  // list the config holds, which refuses every source that needs git.
+  readonly gitTransports: readonly string[] | InvalidGitTransports;
 }
 
 type MaterializedWorkspace = { readonly kind: 'in_place' } | ReadyWorkspace;
@@ -203,7 +211,9 @@ async function runMaterialization(
   updateProgress: ProgressTracker,
   secret: string | null,
 ): Promise<Omit<ReadyWorkspace, 'withheldEnv'>> {
-  const pinned = await resolveSource(request.source, staging);
+  const transports = requireGitTransports(deps.gitTransports, { phase: 'resolving' });
+
+  const pinned = await resolveSource(request.source, staging, transports);
 
   // What is recorded and returned is scrubbed of the credential, even
   // where a caller's own ref happens to spell it.
@@ -213,7 +223,7 @@ async function runMaterialization(
   await claimTargetDir(request, deps, updateProgress);
   await recordPhase(request, deps, updateProgress, 'cloning', { repoURL, ref });
 
-  const clone = await createCleanClone(pinned, join(staging, 'clone'));
+  const clone = await createCleanClone(pinned, join(staging, 'clone'), transports);
 
   // The archive is in memory, so the clone leaves the daemon's host before
   // the target is touched.
@@ -251,8 +261,10 @@ interface PinnedSource {
   readonly cloneURL: string;
   readonly repoURL: string;
 
-  // The ref or commit the clone checks out, and the branch or tag recorded.
+  // The ref or commit the clone checks out, the commit it is pinned to when
+  // the ref only names its branch, and the branch or tag recorded.
   readonly checkout: string;
+  readonly sha?: string | undefined;
   readonly ref: string | null;
   readonly credential: { readonly kind: 'env'; readonly name: string } | undefined;
   readonly warnings: readonly string[];
@@ -263,7 +275,11 @@ interface PinnedSource {
  * not a pushed, complete, credential-free repository. A path source pins
  * its pushed HEAD; a git source keeps its ref, which the clone pins.
  */
-async function resolveSource(source: SpawnWorkspaceSource, staging: string): Promise<PinnedSource> {
+async function resolveSource(
+  source: SpawnWorkspaceSource,
+  staging: string,
+  transports: readonly string[],
+): Promise<PinnedSource> {
   if (source.kind === 'path') {
     // The origin is checked as configured, before resolving it applies any
     // rewrite: a rewrite the checkout's own config holds expands it too.
@@ -271,6 +287,7 @@ async function resolveSource(source: SpawnWorkspaceSource, staging: string): Pro
 
     const resolved = await resolvePathSource(source.path, {
       allowDirty: source.allowDirty ?? 'refuse',
+      transports,
     });
 
     if (!resolved.ok) {
@@ -289,22 +306,19 @@ async function resolveSource(source: SpawnWorkspaceSource, staging: string): Pro
     };
   }
 
-  await requireNoURLCredentials(source.url, staging);
+  // The clone fetches the URL it records, so the spawn API's `owner/repo`
+  // shorthand reaches the repository it expands to.
+  const resolved = await resolveGitURL(expandGitShorthand(source.url), staging, transports);
 
-  // The clone fetches the URL it records, so an `owner/repo` shorthand
-  // reaches the repository it expands to.
-  const normalized = normalizeGitURL(source.url);
-
-  if (!normalized.ok) {
-    throw new DaemonError(normalized.code, normalized.message, { phase: 'resolving' });
+  if (!resolved.ok) {
+    throw new DaemonError(resolved.code, resolved.message, { phase: 'resolving' });
   }
 
-  await requireNoURLCredentials(normalized.url, staging);
-
   return {
-    cloneURL: normalized.url,
-    repoURL: normalized.url,
-    checkout: source.sha ?? source.ref ?? '',
+    cloneURL: resolved.url,
+    repoURL: resolved.url,
+    checkout: source.ref ?? source.sha ?? '',
+    sha: source.ref === undefined ? undefined : source.sha,
     ref: source.ref ?? null,
     credential: source.credentialRef,
     warnings: [],
@@ -400,10 +414,20 @@ interface CleanClone {
  * Clones the pinned source into a staging directory on the daemon's host,
  * sanitizes it, and reads it back as a tar archive.
  */
-async function createCleanClone(pinned: PinnedSource, dir: string): Promise<CleanClone> {
+async function createCleanClone(
+  pinned: PinnedSource,
+  dir: string,
+  transports: readonly string[],
+): Promise<CleanClone> {
   const clone = await createWorkspaceClone({
-    source: { kind: 'git', url: pinned.cloneURL, ref: pinned.checkout },
+    source: {
+      kind: 'git',
+      url: pinned.cloneURL,
+      ref: pinned.checkout,
+      ...(pinned.sha === undefined ? {} : { sha: pinned.sha }),
+    },
     dir,
+    transports,
     ...(pinned.credential === undefined ? {} : { credential: pinned.credential }),
   });
 

package/src/daemon/require-git-transports.ts

@@ -0,0 +1,23 @@
+import { DaemonError } from '../protocol/daemon-error';
+import type { InvalidGitTransports } from '../shared/collect-workspaces-config';
+
+/**
+ * The transports git may fetch over, or the refusal of a git operation
+ * when the configured list is invalid: the daemon then runs no git at all,
+ * and the error quotes the config errors it printed at startup, with
+ * `data` as its detail.
+ */
+export function requireGitTransports(
+  policy: readonly string[] | InvalidGitTransports,
+  data?: Readonly<Record<string, unknown>>,
+): readonly string[] {
+  if ('invalid' in policy) {
+    throw new DaemonError(
+      'git_transports_invalid',
+      `workspaces.gitTransports in config.json is invalid, so the daemon runs no git: ${policy.invalid}`,
+      data,
+    );
+  }
+
+  return policy;
+}

package/src/mcp/require-daemon-features.ts

@@ -19,6 +19,8 @@ const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'report.get': 'atc_report_get',
   'request.principal': 'the target limits of a remote MCP client',
   'spawn.workspace': "atc_session_spawn's workspace",
+  sources: 'sources.list and sources.interpret',
+  'git.probe': 'git.probe',
 };
 
 /**

package/src/protocol/daemon-features.ts

@@ -56,6 +56,14 @@ export const DAEMON_FEATURES = [
 
   // `report.get` exists.
   'report.get',
+
+  // `sources.list` and `sources.interpret` exist, and `agents.list` returns
+  // `sources`.
+  'sources',
+
+  // `git.probe` exists, and `session.spawn` takes a git workspace with both
+  // `ref` and `sha`.
+  'git.probe',
 ] as const;
 
 export type DaemonFeature = (typeof DAEMON_FEATURES)[number];

package/src/protocol/protocol.ts

@@ -34,6 +34,7 @@ const ERROR_CODES = [
   'workspace_dirty',
   'no_origin',
   'invalid_git_url',
+  'git_transports_invalid',
   'unpushed_head',
   'credential_in_url',
   'credential_missing',
@@ -44,6 +45,7 @@ const ERROR_CODES = [
   'workspace_exists',
   'transfer_failed',
   'workspace_mismatch',
+  'github_unavailable',
   'host_unavailable',
   'auth_not_configured',
   'host_leased',

package/src/protocol/request-param-schemas.ts

@@ -32,15 +32,30 @@ const CREDENTIAL_REF = z.strictObject({
   name: z.string().regex(/^[A-Za-z_]\w*$/u, 'a credentialRef names an environment variable'),
 });
 
+// A git workspace's repository URL, which git must never read as an option.
+const GIT_URL = z
+  .string({ error: 'a git workspace requires a url' })
+  .min(1, 'a git workspace requires a url')
+  .refine((url) => !url.startsWith('-'), 'a git workspace url must not start with -');
+
+// A git workspace's branch or tag, which git must never read as an option.
+const GIT_REF = z
+  .string()
+  .min(1, 'a git workspace ref must not be empty')
+  .refine((ref) => !ref.startsWith('-'), 'a git workspace ref must not start with -');
+
+const GIT_SHA = z.string().regex(COMMIT_ID, 'a git workspace sha is a full commit id');
+
 /**
  * Where a spawn's working directory comes from, materialized as a clean
  * checkout into the spawn's `cwd` on its execution target. A `path` source
  * is a directory on the daemon's host, resolved to its origin URL and
  * pushed HEAD; `allowDirty: 'warn'` resolves a tree with uncommitted
  * changes to HEAD and leaves the changes behind with a warning. A `git`
- * source is a repository URL with exactly one of a branch or tag `ref` or
- * a full commit `sha`, and an optional `credentialRef` naming the daemon
- * environment variable that holds its token.
+ * source is a repository URL with a branch or tag `ref`, a full commit
+ * `sha`, or both, and an optional `credentialRef` naming the daemon
+ * environment variable that holds its token. With both, the sha is the
+ * commit checked out and the ref is recorded as what it was resolved from.
  */
 const WORKSPACE_SOURCE = z.discriminatedUnion('kind', [
   z.strictObject({
@@ -53,23 +68,33 @@ const WORKSPACE_SOURCE = z.discriminatedUnion('kind', [
   z
     .strictObject({
       kind: z.literal('git'),
-      url: z
-        .string({ error: 'a git workspace requires a url' })
-        .min(1, 'a git workspace requires a url')
-        .refine((url) => !url.startsWith('-'), 'a git workspace url must not start with -'),
-      ref: z
-        .string()
-        .min(1, 'a git workspace ref must not be empty')
-        .refine((ref) => !ref.startsWith('-'), 'a git workspace ref must not start with -')
-        .optional(),
-      sha: z.string().regex(COMMIT_ID, 'a git workspace sha is a full commit id').optional(),
+      url: GIT_URL,
+      ref: GIT_REF.optional(),
+      sha: GIT_SHA.optional(),
       credentialRef: CREDENTIAL_REF.optional(),
     })
-    .refine((source) => (source.ref === undefined) !== (source.sha === undefined), {
-      message: 'a git workspace takes exactly one of ref or sha',
+    .refine((source) => source.ref !== undefined || source.sha !== undefined, {
+      message: 'a git workspace takes a ref, a sha, or both',
     }),
 ]);
 
+// The execution target a request acts for; absent is the default target.
+const TARGET = z
+  .string({ error: 'target must be a non-empty target id' })
+  .min(1, 'target must be a non-empty target id')
+  .optional();
+
+// The id of a source the daemon offers the spawn picker.
+const SOURCE_ID = z
+  .string({ error: 'source must be a source id' })
+  .min(1, 'source must be a source id')
+  .max(64, 'source must be a source id');
+
+// Text a source reads, at most 4096 characters.
+const SOURCE_TEXT = z
+  .string({ error: 'source text must be a string' })
+  .max(4096, 'source text must be at most 4096 characters');
+
 export type SpawnWorkspaceSource = z.infer<typeof WORKSPACE_SOURCE>;
 
 // The refusal of a terminal size outside the range a terminal takes.
@@ -88,6 +113,33 @@ export const REQUEST_PARAM_SCHEMAS = {
   'session.list': z.object({}),
   'dirs.list': z.object({}),
   'agents.list': z.object({}),
+
+  // One source's candidates for a spawn to the target, under the scope the
+  // source defines and filtered by text when it filters.
+  'sources.list': z.object({
+    source: SOURCE_ID,
+    target: TARGET,
+    scope: SOURCE_TEXT.min(1, 'scope must be non-empty').optional(),
+    text: SOURCE_TEXT.optional(),
+  }),
+
+  // What one source reads typed input as, for a spawn to the target.
+  'sources.interpret': z.object({ source: SOURCE_ID, input: SOURCE_TEXT, target: TARGET }),
+
+  // Whether the daemon's host can read a git workspace source the way a
+  // spawn to the target would, with its refs and the commit a ref or sha
+  // selects; at most one of the two.
+  'git.probe': z
+    .object({
+      url: GIT_URL,
+      ref: GIT_REF.optional(),
+      sha: GIT_SHA.optional(),
+      credentialRef: CREDENTIAL_REF.optional(),
+      target: TARGET,
+    })
+    .refine((probe) => probe.ref === undefined || probe.sha === undefined, {
+      message: 'git.probe takes at most one of ref or sha',
+    }),
   'fleet.list': z.object({}),
   'fleet.restore': z.object({
     cols: buildTerminalSize(80),