@the-open-engine/zeroshot 6.32.0 → 6.33.0

package/src/agent-cli-provider/provider-registry.ts

@@ -276,9 +276,9 @@ export const providerRegistry = [
     authInstructions: 'codex login',
     credentialPaths: ['~/.config/codex', '~/.codex'],
     credentialEnvKeys: codexAdapter.credentialEnvKeys,
-    settingsFields: ['webSearch'],
-    settingsDefaults: { webSearch: false },
-    settingsValidator: (settings): string | null => validateWebSearchSettings('codex', settings),
+    settingsFields: ['webSearch', 'trustIsolatedRecoveryProfile'],
+    settingsDefaults: { webSearch: false, trustIsolatedRecoveryProfile: false },
+    settingsValidator: validateCodexSettings,
     capabilities: {
       ...STANDARD_CAPABILITIES,
       jsonSchema: true,
@@ -662,6 +662,18 @@ export const providerRegistry = [
   },
 ] as const satisfies readonly ProviderRegistryEntry[];
 
+function validateCodexSettings(settings: Record<string, unknown>): string | null {
+  const webSearchError = validateWebSearchSettings('codex', settings);
+  if (webSearchError) return webSearchError;
+  if (
+    settings.trustIsolatedRecoveryProfile === undefined ||
+    typeof settings.trustIsolatedRecoveryProfile === 'boolean'
+  ) {
+    return null;
+  }
+  return 'providerSettings.codex.trustIsolatedRecoveryProfile must be a boolean';
+}
+
 function validateWebSearchSettings(
   provider: 'codex' | 'opencode',
   settings: Record<string, unknown>

package/src/agent-cli-provider/single-agent-runtime.ts

@@ -54,16 +54,12 @@ import type {
 
 type UnknownFunction = (...args: readonly unknown[]) => unknown;
 
-interface CommandParts {
-  readonly command: string;
-  readonly args: readonly string[];
-}
-
 interface RuntimeProviderSettings {
   readonly defaultLevel?: ModelLevel;
   readonly levelOverrides: LevelOverrides;
   readonly gateway?: GatewayBuildOptions;
   readonly webSearch?: boolean;
+  readonly trustIsolatedRecoveryProfile?: boolean;
 }
 
 interface RuntimeCommandContext {
@@ -428,7 +424,6 @@ function ompExecutionContext(
   throw new Error('options.executionContext must be "host", "detached", "docker", or "benchmark".');
 }
 
-
 function ompSdkOutputContract(
   options: BuildProviderCommandOptions
 ):
@@ -664,7 +659,7 @@ export function probeRuntimeProviderCli(
   const requested = registryEntry.settingsFields.includes('webSearch')
     ? runtimeProviderSettings(settings, adapter.id, process.cwd()).webSearch === true
     : false;
-  const helpCommand = runtimeHelpCommand(adapter.id);
+  const helpCommand = resolveProviderCommand(adapter.id);
   const commandAvailable =
     evidence === undefined
       ? booleanResult(commandExistsFn(helpCommand.command))
@@ -735,6 +730,10 @@ function buildRuntimeOptions(
     cliFeatures: runtime.cliFeatures,
   };
   const resolved = { ...baseResolved };
+  delete resolved.trustIsolatedCodexProfile;
+  if (baseOptions.structuredOutputRecovery && adapter.id === 'codex') {
+    resolved.trustIsolatedCodexProfile = providerSettings.trustIsolatedRecoveryProfile === true;
+  }
   if (baseOptions.structuredOutputRecovery) {
     delete resolved.resumeSessionId;
     delete resolved.continueSession;
@@ -870,6 +869,10 @@ function runtimeProviderSettings(
     providerSettings.webSearch,
     `settings.providerSettings.${provider}.webSearch`
   );
+  const trustIsolatedRecoveryProfile = optionalBoolean(
+    providerSettings.trustIsolatedRecoveryProfile,
+    `settings.providerSettings.${provider}.trustIsolatedRecoveryProfile`
+  );
   const gateway =
     provider === 'gateway'
       ? normalizeGatewayBuildOptions(providerSettings, 'settings.providerSettings.gateway', cwd)
@@ -878,14 +881,11 @@ function runtimeProviderSettings(
     levelOverrides,
     ...(gateway === undefined ? {} : { gateway }),
     ...(webSearch === undefined ? {} : { webSearch }),
+    ...(trustIsolatedRecoveryProfile === undefined ? {} : { trustIsolatedRecoveryProfile }),
   };
   return defaultLevel === undefined ? base : { ...base, defaultLevel };
 }
 
-function runtimeHelpCommand(provider: ProviderId): CommandParts {
-  return resolveProviderCommand(provider);
-}
-
 function probeGatewayProvider(
   adapter: ProviderAdapter,
   runtimeSettings?: Record<string, unknown>

package/src/agent-cli-provider/types.ts

@@ -468,6 +468,8 @@ export interface BuildProviderCommandOptions {
   readonly mcpConfig?: readonly string[];
   /** Internal profile for provider-neutral structured-output correction turns. */
   readonly structuredOutputRecovery?: boolean;
+  /** Preserve a caller-isolated CODEX_HOME profile during Codex recovery. */
+  readonly trustIsolatedCodexProfile?: boolean;
 }
 
 export interface TextEvent {

package/src/hosted-target/adapter-request.ts

@@ -19,9 +19,14 @@ export type ExecuteArguments<T> = [
 ];
 
 export function requestUrl(path: string, descriptor: TargetDiscoveryDescriptor): URL {
-  const url = new globalThis.URL(path, descriptor.capsule.baseUrl);
-  if (url.origin !== descriptor.origin || url.hash ||
-      `${url.pathname}${url.search}` !== path) {
+  const baseUrl = new globalThis.URL(descriptor.capsule.baseUrl);
+  const requestPath = `${baseUrl.pathname.replace(/\/$/, '')}${path}`;
+  const url = new globalThis.URL(requestPath, baseUrl.origin);
+  if (
+    url.origin !== descriptor.origin ||
+    url.hash ||
+    `${url.pathname}${url.search}` !== requestPath
+  ) {
     throw new TargetProtocolError('Capsule route changed during URL canonicalization');
   }
   return url;

package/src/isolation-manager.js

@@ -36,6 +36,40 @@ const { provisionClaudeCredentials } = require('./claude-credentials');
 
 const DEFAULT_WORKTREE_SETUP_TIMEOUT_MS = 15 * 60 * 1000;
 const FRESH_BASE_REF_PREFIX = 'refs/zeroshot/base-fetch';
+const DETACHED_SETUP_CLUSTER_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+const DETACHED_SETUP_RESOURCE_KEYS = ['configDir', 'containerName', 'isolatedDir', 'kind'];
+
+function getDetachedSetupResources(clusterId) {
+  if (typeof clusterId !== 'string' || !DETACHED_SETUP_CLUSTER_ID_PATTERN.test(clusterId)) {
+    throw new Error(`Invalid detached setup cluster ID: ${clusterId}`);
+  }
+
+  return Object.freeze({
+    kind: 'docker',
+    containerName: `zeroshot-cluster-${clusterId}`,
+    isolatedDir: path.join(os.tmpdir(), 'zeroshot-isolated', clusterId),
+    configDir: path.join(os.tmpdir(), 'zeroshot-cluster-configs', clusterId),
+  });
+}
+
+function setupResourcesMatch(recorded, expected) {
+  if (!recorded || typeof recorded !== 'object' || Array.isArray(recorded)) return false;
+  const keys = Object.keys(recorded).sort();
+  return (
+    keys.length === DETACHED_SETUP_RESOURCE_KEYS.length &&
+    keys.every((key, index) => key === DETACHED_SETUP_RESOURCE_KEYS[index]) &&
+    keys.every((key) => recorded[key] === expected[key])
+  );
+}
+
+function removeBoundedSetupDirectory(root, target) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedTarget = path.resolve(target);
+  if (path.dirname(resolvedTarget) !== resolvedRoot) {
+    throw new Error(`Refusing to remove setup directory outside ${resolvedRoot}`);
+  }
+  fs.rmSync(resolvedTarget, { recursive: true, force: true });
+}
 
 function runSync(command, args, options = {}) {
   const timeout = options.timeout ?? 30000;
@@ -364,6 +398,24 @@ class IsolationManager {
     return this._isContainerRunning(existingId) ? existingId : null;
   }
 
+  static getDetachedSetupResources(clusterId) {
+    return getDetachedSetupResources(clusterId);
+  }
+
+  cleanupDetachedSetupResources(clusterId, recordedResources) {
+    const expected = getDetachedSetupResources(clusterId);
+    if (!setupResourcesMatch(recordedResources, expected)) {
+      throw new Error(`Detached setup resources do not match cluster ${clusterId}`);
+    }
+
+    this._removeContainerByName(expected.containerName);
+    removeBoundedSetupDirectory(path.join(os.tmpdir(), 'zeroshot-isolated'), expected.isolatedDir);
+    removeBoundedSetupDirectory(
+      path.join(os.tmpdir(), 'zeroshot-cluster-configs'),
+      expected.configDir
+    );
+  }
+
   async _prepareIsolatedWorkspace(clusterId, workDir, reuseExisting) {
     if (!this._isGitRepo(workDir)) {
       return workDir;

package/src/orchestrator.js

@@ -2221,6 +2221,12 @@ class Orchestrator {
   async _killSetupCluster(clusterId, cluster) {
     await this._signalSetupProcess(clusterId, cluster);
 
+    if (cluster.setupResources) {
+      this._log(`[Orchestrator] Cleaning provisional setup resources for ${clusterId}...`);
+      const manager = new IsolationManager();
+      manager.cleanupDetachedSetupResources(clusterId, cluster.setupResources);
+    }
+
     if (cluster.worktree?.path) {
       this._teardownWorktreeCompose(cluster.worktree.path);
       try {

package/src/target/discovery-sections.ts

@@ -9,6 +9,7 @@ import {
   stringField,
   type CredentialInstallDescriptor,
 } from './discovery-validation.js';
+import { parseRunIntent, type RunIntentDescriptor } from './run-intent-discovery.js';
 import { routeTemplate } from './route-template.js';
 
 export function parseAdapter(discovery: Record<string, unknown>): {
@@ -29,8 +30,11 @@ export function parseAdapter(discovery: Record<string, unknown>): {
 export function validateCachePolicy(discovery: Record<string, unknown>): void {
   const cache = closedRecord(discovery.cache_policy, 'cache_policy', ['control', 'discovery']);
   exact(cache.control, 'no-store', 'cache_policy.control');
-  if (cache.discovery !== undefined && cache.discovery !== null &&
-      typeof cache.discovery !== 'string') {
+  if (
+    cache.discovery !== undefined &&
+    cache.discovery !== null &&
+    typeof cache.discovery !== 'string'
+  ) {
     throw new TargetDiscoveryError('cache_policy.discovery must be a string or null');
   }
 }
@@ -40,9 +44,12 @@ export function parseSizes(discovery: Record<string, unknown>): {
   readonly default: 'tiny' | 'small' | 'standard' | 'large';
 } {
   const sizes = closedRecord(discovery.sizes, 'sizes', ['catalog', 'default']);
-  if (!Array.isArray(sizes.catalog) || sizes.catalog.length === 0 ||
-      new Set(sizes.catalog).size !== sizes.catalog.length ||
-      sizes.catalog.some((size) => !['tiny', 'small', 'standard', 'large'].includes(String(size)))) {
+  if (
+    !Array.isArray(sizes.catalog) ||
+    sizes.catalog.length === 0 ||
+    new Set(sizes.catalog).size !== sizes.catalog.length ||
+    sizes.catalog.some((size) => !['tiny', 'small', 'standard', 'large'].includes(String(size)))
+  ) {
     throw new TargetDiscoveryError('sizes.catalog contains an unsupported size');
   }
   if (!sizes.catalog.includes(sizes.default)) {
@@ -56,44 +63,58 @@ export function parseSizes(discovery: Record<string, unknown>): {
 
 export function parseExtensions(
   discovery: Record<string, unknown>,
-  origin: string,
-): CredentialInstallDescriptor | null {
-  if (discovery.extensions === undefined || discovery.extensions === null) return null;
+  origin: string
+): {
+  readonly credentialInstall: CredentialInstallDescriptor | null;
+  readonly runIntent: RunIntentDescriptor | null;
+} {
+  if (discovery.extensions === undefined || discovery.extensions === null) {
+    return Object.freeze({ credentialInstall: null, runIntent: null });
+  }
   const extensions = closedRecord(discovery.extensions, 'extensions', [
-    'connections', 'credential_install',
+    'connections',
+    'credential_install',
+    'run_intent',
   ]);
   if (extensions.connections === undefined) {
     throw new TargetDiscoveryError('extensions.connections is required');
   }
   const connections = closedRecord(extensions.connections, 'extensions.connections', [
-    'kind', 'base_url', 'route_templates',
+    'kind',
+    'base_url',
+    'route_templates',
   ]);
   exact(connections.kind, 'zerocloud.connections/v1', 'extensions.connections.kind');
   sameOriginUrl(connections.base_url, 'extensions.connections.base_url', origin);
-  const routes = closedRecord(connections.route_templates, 'extensions.connections.route_templates', [
-    'list', 'create', 'update',
-  ]);
+  const routes = closedRecord(
+    connections.route_templates,
+    'extensions.connections.route_templates',
+    ['list', 'create', 'update']
+  );
   routeTemplate(routes.list, 'extensions.connections.route_templates.list', []);
   routeTemplate(routes.create, 'extensions.connections.route_templates.create', []);
   routeTemplate(routes.update, 'extensions.connections.route_templates.update', ['connection_id']);
-  return parseCredentialInstall(extensions.credential_install);
+  return Object.freeze({
+    credentialInstall: parseCredentialInstall(extensions.credential_install),
+    runIntent: parseRunIntent(extensions.run_intent, origin),
+  });
 }
 
 export function validateOAuthMetadata(
   metadata: Record<string, unknown>,
   origin: string,
-  expected: readonly [string, string, string],
+  expected: readonly [string, string, string]
 ): void {
   const device = sameOriginUrl(
     metadata.device_authorization_endpoint,
     'OAuth metadata device_authorization_endpoint',
-    origin,
+    origin
   );
   const token = sameOriginUrl(metadata.token_endpoint, 'OAuth metadata token_endpoint', origin);
   const revoke = sameOriginUrl(
     metadata.revocation_endpoint,
     'OAuth metadata revocation_endpoint',
-    origin,
+    origin
   );
   if (device !== expected[0] || token !== expected[1] || revoke !== expected[2]) {
     throw new TargetDiscoveryError('OAuth metadata does not match hosted-target discovery');
@@ -108,20 +129,15 @@ export function parseEndpoint(discovery: Record<string, unknown>, origin: string
   exact(binding.scope, 'organization', 'binding.scope');
   exact(binding.auth_location, 'authorization_header', 'binding.auth_location');
   const endpoint = closedRecord(discovery.endpoint, 'endpoint', ['url', 'capabilities']);
-  const capabilities = exactStringSet(
-    endpoint.capabilities,
-    'endpoint.capabilities',
-    ['exec', 'log_stream'],
-  ) as readonly ['exec', 'log_stream'];
+  const capabilities = exactStringSet(endpoint.capabilities, 'endpoint.capabilities', [
+    'exec',
+    'log_stream',
+  ]) as readonly ['exec', 'log_stream'];
   const pagination = closedRecord(discovery.pagination, 'pagination', [
     'default_page_size',
     'max_page_size',
   ]);
-  const defaultPageSize = integer(
-    pagination.default_page_size,
-    'pagination.default_page_size',
-    1,
-  );
+  const defaultPageSize = integer(pagination.default_page_size, 'pagination.default_page_size', 1);
   const maxPageSize = integer(pagination.max_page_size, 'pagination.max_page_size', 1);
   if (defaultPageSize > maxPageSize) {
     throw new TargetDiscoveryError('pagination.default_page_size exceeds maximum');
@@ -151,11 +167,14 @@ export function parseCapsule(discovery: Record<string, unknown>, origin: string)
   ]);
   exact(capsule.name, 'openengine.capsules/v1', 'capsule_protocol.name');
   exact(capsule.major_version, 1, 'capsule_protocol.major_version');
-  const routes = closedRecord(
-    capsule.route_templates,
-    'capsule_protocol.route_templates',
-    ['allocate', 'list', 'inspect', 'terminate', 'limits', 'access'],
-  );
+  const routes = closedRecord(capsule.route_templates, 'capsule_protocol.route_templates', [
+    'allocate',
+    'list',
+    'inspect',
+    'terminate',
+    'limits',
+    'access',
+  ]);
   const route = (name: string, variables: readonly string[]) =>
     routeTemplate(routes[name], `capsule_protocol.route_templates.${name}`, variables);
   return Object.freeze({
@@ -185,26 +204,25 @@ export function parseOAuth(discovery: Record<string, unknown>, origin: string) {
   exact(
     oauth.device_grant_type,
     'urn:ietf:params:oauth:grant-type:device_code',
-    'oauth.device_grant_type',
-  );
-  exactStringSet(
-    oauth.device_exchange_fields,
-    'oauth.device_exchange_fields',
-    ['device_token', 'device_label'],
+    'oauth.device_grant_type'
   );
+  exactStringSet(oauth.device_exchange_fields, 'oauth.device_exchange_fields', [
+    'device_token',
+    'device_label',
+  ]);
   exact(oauth.audience, 'capsule', 'oauth.audience');
   return Object.freeze({
     metadataUrl: sameOriginUrl(oauth.metadata_url, 'oauth.metadata_url', origin),
     deviceAuthorizationEndpoint: sameOriginUrl(
       oauth.device_authorization_endpoint,
       'oauth.device_authorization_endpoint',
-      origin,
+      origin
     ),
     tokenEndpoint: sameOriginUrl(oauth.token_endpoint, 'oauth.token_endpoint', origin),
     revocationEndpoint: sameOriginUrl(
       oauth.revocation_endpoint,
       'oauth.revocation_endpoint',
-      origin,
+      origin
     ),
     clientId: stringField(oauth, 'client_id', 'oauth.'),
     deviceGrantType: 'urn:ietf:params:oauth:grant-type:device_code' as const,
@@ -243,7 +261,7 @@ export function parseTransport(discovery: Record<string, unknown>) {
     websocketRouteTemplate: routeTemplate(
       transport.websocket_route_template,
       'transport.websocket_route_template',
-      ['capsule_id'],
+      ['capsule_id']
     ),
     unauthorizedStatus: 401 as const,
     closeCodes: Object.freeze({ expired: 4401 as const, revoked: 4403 as const }),

package/src/target/discovery.ts

@@ -8,6 +8,7 @@ import {
   record,
   type CredentialInstallDescriptor,
 } from './discovery-validation.js';
+import type { RunIntentDescriptor } from './run-intent-discovery.js';
 import {
   parseAdapter,
   parseCapsule,
@@ -20,6 +21,7 @@ import {
   validateOAuthMetadata,
 } from './discovery-sections.js';
 export type { CredentialInstallDescriptor } from './discovery-validation.js';
+export type { RunIntentDescriptor } from './run-intent-discovery.js';
 export { TargetDiscoveryError } from './discovery-errors.js';
 export { expandRoute, type RouteTemplate } from './route-template.js';
 
@@ -84,6 +86,7 @@ export interface TargetDiscoveryDescriptor {
   };
   readonly capabilityFlags: readonly string[];
   readonly credentialInstall: CredentialInstallDescriptor | null;
+  readonly runIntent: RunIntentDescriptor | null;
   readonly additional: Readonly<Record<string, unknown>>;
 }
 
@@ -100,69 +103,37 @@ export interface TargetSessionEndpoints {
   readonly descriptor: TargetDiscoveryDescriptor;
 }
 
+const FLAGS = [
+  'capsule_allocate',
+  'capsule_read',
+  'capsule_terminate',
+  'capsule_access',
+  'connections_onboarding',
+] as const;
+const SIZE_ERROR = 'response exceeds the size limit';
+const JSON_ERROR = 'response is not valid UTF-8 JSON';
 
-
-async function readBoundedJson(response: Response): Promise<unknown> {
-  return readBoundedResponseJson(response, MAX_DISCOVERY_BYTES, (kind) =>
-    new TargetDiscoveryError(
-      kind === 'size' ? 'response exceeds the size limit' : 'response is not valid UTF-8 JSON',
-    ),
-  );
-}
-
-
-async function fetchDocument(http: HttpTransport, url: string): Promise<Record<string, unknown>> {
-  const response = await http.fetch(url, {
-    method: 'GET',
-    headers: { Accept: 'application/json' },
-    redirect: 'error',
-  });
-  if (response.url && new URL(response.url).href !== url) {
-    await response.body?.cancel().catch(() => undefined);
-    throw new TargetDiscoveryError('request changed target route or authority');
-  }
-  if (!response.ok) {
-    await response.body?.cancel().catch(() => undefined);
-    throw new TargetDiscoveryError(`request failed with status ${response.status}`);
-  }
-  return record(await readBoundedJson(response), 'response');
-}
-
-
-export async function discoverTarget(targetUrl: string, http: HttpTransport): Promise<TargetDiscoveryDescriptor> {
-  const target = new URL(targetUrl);
-  const origin = target.origin;
-  const discovery = await fetchDocument(http, new URL(DISCOVERY_PATH, target).href);
+function parseDiscoveryDocument(
+  discovery: Record<string, unknown>,
+  origin: string
+): TargetDiscoveryDescriptor {
   exact(discovery.kind, 'openengine.hosted-target/v1', 'kind');
-
   const adapter = parseAdapter(discovery);
   const endpoint = parseEndpoint(discovery, origin);
   const capsule = parseCapsule(discovery, origin);
   const oauth = parseOAuth(discovery, origin);
   exact(discovery.organization_binding, 'device_approval', 'organization_binding');
-  const capabilityFlags = exactStringSet(discovery.capability_flags, 'capability_flags', [
-    'capsule_allocate',
-    'capsule_read',
-    'capsule_terminate',
-    'capsule_access',
-    'connections_onboarding',
-  ]);
+  const capabilityFlags = exactStringSet(discovery.capability_flags, 'capability_flags', FLAGS);
   const sizes = parseSizes(discovery);
   const session = parseSession(discovery);
   const transport = parseTransport(discovery);
-  const credentialInstall = parseExtensions(discovery, origin);
-
-  const metadata = await fetchDocument(http, oauth.metadataUrl);
-  validateOAuthMetadata(metadata, origin, [
-    oauth.deviceAuthorizationEndpoint,
-    oauth.tokenEndpoint,
-    oauth.revocationEndpoint,
-  ]);
-
+  const extensions = parseExtensions(discovery, origin);
   const additional = Object.freeze(
-    Object.fromEntries(Object.entries(discovery).filter(([key]) =>
-      !ROOT_FIELDS.includes(key as (typeof ROOT_FIELDS)[number]),
-    )),
+    Object.fromEntries(
+      Object.entries(discovery).filter(
+        ([key]) => !ROOT_FIELDS.includes(key as (typeof ROOT_FIELDS)[number])
+      )
+    )
   );
   return Object.freeze({
     origin,
@@ -176,12 +147,33 @@ export async function discoverTarget(targetUrl: string, http: HttpTransport): Pr
     capsule,
     transport,
     capabilityFlags,
-    credentialInstall,
+    credentialInstall: extensions.credentialInstall,
+    runIntent: extensions.runIntent,
     additional,
   });
 }
 
-export async function discoverTargetSessionEndpoints(targetUrl: string, http: HttpTransport): Promise<TargetSessionEndpoints> {
+export async function discoverTarget(
+  targetUrl: string,
+  http: HttpTransport
+): Promise<TargetDiscoveryDescriptor> {
+  const target = new URL(targetUrl);
+  const origin = target.origin;
+  const discovery = await fetchDocument(http, new URL(DISCOVERY_PATH, target).href);
+  const descriptor = parseDiscoveryDocument(discovery, origin);
+  const metadata = await fetchDocument(http, descriptor.oauth.metadataUrl);
+  validateOAuthMetadata(metadata, origin, [
+    descriptor.oauth.deviceAuthorizationEndpoint,
+    descriptor.oauth.tokenEndpoint,
+    descriptor.oauth.revocationEndpoint,
+  ]);
+  return descriptor;
+}
+
+export async function discoverTargetSessionEndpoints(
+  targetUrl: string,
+  http: HttpTransport
+): Promise<TargetSessionEndpoints> {
   const descriptor = await discoverTarget(targetUrl, http);
   return Object.freeze({
     deviceAuthorizationEndpoint: descriptor.oauth.deviceAuthorizationEndpoint,
@@ -195,3 +187,28 @@ export async function discoverTargetSessionEndpoints(targetUrl: string, http: Ht
     descriptor,
   });
 }
+
+function boundedResponseError(kind: 'size' | 'json'): Error {
+  return new TargetDiscoveryError(kind === 'size' ? SIZE_ERROR : JSON_ERROR);
+}
+
+async function readBoundedJson(response: Response): Promise<unknown> {
+  return readBoundedResponseJson(response, MAX_DISCOVERY_BYTES, boundedResponseError);
+}
+
+async function fetchDocument(http: HttpTransport, url: string): Promise<Record<string, unknown>> {
+  const response = await http.fetch(url, {
+    method: 'GET',
+    headers: { Accept: 'application/json' },
+    redirect: 'error',
+  });
+  if (response.url && new URL(response.url).href !== url) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new TargetDiscoveryError('request changed target route or authority');
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new TargetDiscoveryError(`request failed with status ${response.status}`);
+  }
+  return record(await readBoundedJson(response), 'response');
+}

package/src/target/index.ts

@@ -53,6 +53,7 @@ export {
   expandRoute,
   TargetDiscoveryError,
   type CredentialInstallDescriptor,
+  type RunIntentDescriptor,
   type RouteTemplate,
   type TargetDiscoveryDescriptor,
   type TargetSessionEndpoints,

package/src/target/run-intent-discovery.ts

@@ -0,0 +1,39 @@
+import type { RouteTemplate } from './route-template.js';
+import { routeTemplate } from './route-template.js';
+import { closedRecord, exact, sameOriginUrl } from './discovery-validation.js';
+
+export interface RunIntentDescriptor {
+  readonly kind: 'zeroshot.run-intent/v2';
+  readonly baseUrl: string;
+  readonly routes: {
+    readonly submit: RouteTemplate;
+    readonly status: RouteTemplate;
+    readonly cancel: RouteTemplate;
+  };
+}
+
+export function parseRunIntent(value: unknown, origin: string): RunIntentDescriptor | null {
+  if (value === undefined || value === null) return null;
+  const extension = closedRecord(value, 'extensions.run_intent', [
+    'kind',
+    'base_url',
+    'route_templates',
+  ]);
+  exact(extension.kind, 'zeroshot.run-intent/v2', 'extensions.run_intent.kind');
+  const routes = closedRecord(extension.route_templates, 'extensions.run_intent.route_templates', [
+    'submit',
+    'status',
+    'cancel',
+  ]);
+  const route = (name: string, variables: readonly string[]) =>
+    routeTemplate(routes[name], `extensions.run_intent.route_templates.${name}`, variables);
+  return Object.freeze({
+    kind: 'zeroshot.run-intent/v2' as const,
+    baseUrl: sameOriginUrl(extension.base_url, 'extensions.run_intent.base_url', origin),
+    routes: Object.freeze({
+      submit: route('submit', ['org_id']),
+      status: route('status', ['org_id', 'intent_id']),
+      cancel: route('cancel', ['org_id', 'intent_id']),
+    }),
+  });
+}