Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(agent): discover model-specific session capabilities (#7157)

Eric Hayes8090561a2cf3
diff --git a/apps/web/src/lib/queries/agents/capabilities.test.tsx b/apps/web/src/lib/queries/agents/capabilities.test.tsx
new file mode 100644
index 0000000000..a68f38b735
--- /dev/null
+++ b/apps/web/src/lib/queries/agents/capabilities.test.tsx
@@ -0,0 +1,82 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { agentHarnessServiceClient } from '@service-agent-harness/client';
+import { QueryClient, QueryClientProvider } from '@tanstack/solid-query';
+import { createSignal, type JSX } from 'solid-js';
+import { render } from 'solid-js/web';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useAgentCapabilitiesQuery } from './capabilities';
+
+vi.mock('@service-agent-harness/client', () => ({
+ agentHarnessServiceClient: {
+ discoverAgentCapabilities: vi.fn(),
+ },
+}));
+
+let queryClient: QueryClient;
+let dispose: (() => void) | undefined;
+
+function renderHook(factory: () => unknown) {
+ dispose = render(
+ () => (
+ <QueryClientProvider client={queryClient}>
+ {(() => {
+ factory();
+ return null as unknown as JSX.Element;
+ })()}
+ </QueryClientProvider>
+ ),
+ document.body
+ );
+}
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+});
+
+afterEach(() => {
+ dispose?.();
+ dispose = undefined;
+ queryClient.clear();
+});
+
+describe('agent capability discovery', () => {
+ it('keys fresh discovery by the selected model and disables unsupported targets', async () => {
+ vi.mocked(
+ agentHarnessServiceClient.discoverAgentCapabilities
+ ).mockReturnValue(new Promise<never>(() => {}));
+ const [target, setTarget] = createSignal<{
+ harness: 'cursor';
+ model: string;
+ }>();
+ renderHook(() => useAgentCapabilitiesQuery(target));
+ expect(
+ agentHarnessServiceClient.discoverAgentCapabilities
+ ).not.toHaveBeenCalled();
+ setTarget({ harness: 'cursor', model: 'first' });
+ await vi.waitFor(() =>
+ expect(
+ agentHarnessServiceClient.discoverAgentCapabilities
+ ).toHaveBeenCalledTimes(1)
+ );
+ setTarget({ harness: 'cursor', model: 'second' });
+ await vi.waitFor(() =>
+ expect(
+ agentHarnessServiceClient.discoverAgentCapabilities
+ ).toHaveBeenCalledTimes(2)
+ );
+ expect(
+ vi
+ .mocked(agentHarnessServiceClient.discoverAgentCapabilities)
+ .mock.calls.map(([request]) => request)
+ ).toEqual([
+ { harness: 'cursor', model: 'first' },
+ { harness: 'cursor', model: 'second' },
+ ]);
+ });
+});
diff --git a/apps/web/src/lib/queries/agents/capabilities.ts b/apps/web/src/lib/queries/agents/capabilities.ts
new file mode 100644
index 0000000000..a46928a9f3
--- /dev/null
+++ b/apps/web/src/lib/queries/agents/capabilities.ts
@@ -0,0 +1,50 @@
+import { throwOnErr } from '@core/util/result';
+import { agentHarnessServiceClient } from '@service-agent-harness/client';
+import type { DiscoverAgentCapabilitiesRequest } from '@service-agent-harness/generated/schemas';
+import { useQuery } from '@tanstack/solid-query';
+
+/** Capabilities belong to a harness and selected model, never a provider alone. */
+export function useAgentCapabilitiesQuery(
+ target: () => DiscoverAgentCapabilitiesRequest | undefined
+) {
+ return useQuery(() => ({
+ queryKey: ['agent-capabilities', target() ?? null] as const,
+ queryFn: async ({ signal }: { signal: AbortSignal }) => {
+ const request = target();
+ if (!request) throw new Error('No capability target');
+ const response = await throwOnErr(() =>
+ agentHarnessServiceClient.discoverAgentCapabilities(request, signal)
+ );
+ return {
+ configOptions: response.configOptions.map((option) => {
+ const common = {
+ id: option.id,
+ name: option.name,
+ description: option.description ?? null,
+ category: option.category ?? null,
+ };
+ if (option.type === 'select')
+ return {
+ ...common,
+ type: option.type,
+ currentValue: option.currentValue,
+ options: option.options.map((value) => ({
+ ...value,
+ description: value.description ?? null,
+ group: value.group ?? null,
+ })),
+ };
+ return {
+ ...common,
+ type: option.type,
+ currentValue: option.currentValue,
+ };
+ }),
+ };
+ },
+ enabled: target() !== undefined,
+ staleTime: 0,
+ gcTime: 0,
+ retry: false,
+ }));
+}
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/client.ts b/apps/web/src/lib/service-clients/service-agent-harness/client.ts
index 827eb6b28b..fdf1e4ccec 100644
--- a/apps/web/src/lib/service-clients/service-agent-harness/client.ts
+++ b/apps/web/src/lib/service-clients/service-agent-harness/client.ts
@@ -13,6 +13,8 @@ import type {
ControlResponse,
CreateAgentSessionRequest,
CreateAgentSessionResponse,
+ DiscoverAgentCapabilitiesRequest,
+ DiscoverAgentCapabilitiesResponse,
LoadAgentModelsRequest,
LoadAgentModelsResponse,
PreviewAgentSessionsResponse,
@@ -65,6 +67,21 @@ export const agentHarnessServiceClient = {
);
},
+ discoverAgentCapabilities(
+ request: DiscoverAgentCapabilitiesRequest,
+ signal?: AbortSignal
+ ) {
+ return fetchWithToken<DiscoverAgentCapabilitiesResponse>(
+ `${agentHarnessHost}/agent-capabilities/discover`,
+ {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(request),
+ signal,
+ }
+ );
+ },
+
create(request: CreateAgentSessionRequest) {
return fetchWithToken<CreateAgentSessionResponse>(
`${agentHarnessHost}/agent-sessions`,
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/client.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/client.ts
index b3fc11958e..7627a3a4ae 100644
--- a/apps/web/src/lib/service-clients/service-agent-harness/generated/client.ts
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/client.ts
@@ -17,6 +17,8 @@ import type {
ControlResponse,
CreateAgentSessionRequest,
CreateAgentSessionResponse,
+ DiscoverAgentCapabilitiesRequest,
+ DiscoverAgentCapabilitiesResponse,
EditQueuedActionRequest,
EmptyRequest,
ListAgentRepositoryBranchesParams,
@@ -33,6 +35,90 @@ import type {
UpdateSharePermissionRequestV2,
} from './schemas';
+/**
+ * @summary Probe one provider's ACP session configuration without persisting a session.
+ */
+export type discoverAgentCapabilitiesHandlerResponse200 = {
+ data: DiscoverAgentCapabilitiesResponse;
+ status: 200;
+};
+
+export type discoverAgentCapabilitiesHandlerResponse400 = {
+ data: void;
+ status: 400;
+};
+
+export type discoverAgentCapabilitiesHandlerResponse401 = {
+ data: void;
+ status: 401;
+};
+
+export type discoverAgentCapabilitiesHandlerResponse403 = {
+ data: void;
+ status: 403;
+};
+
+export type discoverAgentCapabilitiesHandlerResponse409 = {
+ data: void;
+ status: 409;
+};
+
+export type discoverAgentCapabilitiesHandlerResponse502 = {
+ data: void;
+ status: 502;
+};
+
+export type discoverAgentCapabilitiesHandlerResponse504 = {
+ data: void;
+ status: 504;
+};
+
+export type discoverAgentCapabilitiesHandlerResponseSuccess =
+ discoverAgentCapabilitiesHandlerResponse200 & {
+ headers: Headers;
+ };
+export type discoverAgentCapabilitiesHandlerResponseError = (
+ | discoverAgentCapabilitiesHandlerResponse400
+ | discoverAgentCapabilitiesHandlerResponse401
+ | discoverAgentCapabilitiesHandlerResponse403
+ | discoverAgentCapabilitiesHandlerResponse409
+ | discoverAgentCapabilitiesHandlerResponse502
+ | discoverAgentCapabilitiesHandlerResponse504
+) & {
+ headers: Headers;
+};
+
+export type discoverAgentCapabilitiesHandlerResponse =
+ | discoverAgentCapabilitiesHandlerResponseSuccess
+ | discoverAgentCapabilitiesHandlerResponseError;
+
+export const getDiscoverAgentCapabilitiesHandlerUrl = () => {
+ return `/agent-capabilities/discover`;
+};
+
+export const discoverAgentCapabilitiesHandler = async (
+ discoverAgentCapabilitiesRequest: DiscoverAgentCapabilitiesRequest,
+ options?: RequestInit
+): Promise<discoverAgentCapabilitiesHandlerResponse> => {
+ const res = await fetch(getDiscoverAgentCapabilitiesHandlerUrl(), {
+ ...options,
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', ...options?.headers },
+ body: JSON.stringify(discoverAgentCapabilitiesRequest),
+ });
+
+ const body = [204, 205, 304].includes(res.status) ? null : await res.text();
+
+ const data: discoverAgentCapabilitiesHandlerResponse['data'] = body
+ ? JSON.parse(body)
+ : {};
+ return {
+ data,
+ status: res.status,
+ headers: res.headers,
+ } as discoverAgentCapabilitiesHandlerResponse;
+};
+
/**
* @summary Probe one provider's model catalog without creating an agent session.
*/
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDto.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDto.ts
new file mode 100644
index 0000000000..2d1006948d
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDto.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { AgentConfigKindDtoOneOf } from './agentConfigKindDtoOneOf';
+import type { AgentConfigKindDtoOneOfThree } from './agentConfigKindDtoOneOfThree';
+
+/**
+ * Type-specific state for one agent session setting.
+ */
+export type AgentConfigKindDto =
+ | AgentConfigKindDtoOneOf
+ | AgentConfigKindDtoOneOfThree;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOf.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOf.ts
new file mode 100644
index 0000000000..5570c4faa7
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOf.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+import type { AgentConfigKindDtoOneOfType } from './agentConfigKindDtoOneOfType';
+import type { AgentConfigSelectOptionDto } from './agentConfigSelectOptionDto';
+
+/**
+ * A single-value selector.
+ */
+export type AgentConfigKindDtoOneOf = {
+ /** Current opaque value. */
+ currentValue: string;
+ /** Ordered values supplied by the agent. */
+ options: AgentConfigSelectOptionDto[];
+ type: AgentConfigKindDtoOneOfType;
+};
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOfThree.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOfThree.ts
new file mode 100644
index 0000000000..7662c44c08
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOfThree.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { AgentConfigKindDtoOneOfThreeType } from './agentConfigKindDtoOneOfThreeType';
+
+/**
+ * An on/off setting.
+ */
+export type AgentConfigKindDtoOneOfThree = {
+ /** Current value. */
+ currentValue: boolean;
+ type: AgentConfigKindDtoOneOfThreeType;
+};
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOfThreeType.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOfThreeType.ts
new file mode 100644
index 0000000000..2ecfc50a5c
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOfThreeType.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+export type AgentConfigKindDtoOneOfThreeType =
+ (typeof AgentConfigKindDtoOneOfThreeType)[keyof typeof AgentConfigKindDtoOneOfThreeType];
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const AgentConfigKindDtoOneOfThreeType = {
+ boolean: 'boolean',
+} as const;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOfType.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOfType.ts
new file mode 100644
index 0000000000..16e940d06e
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigKindDtoOneOfType.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+export type AgentConfigKindDtoOneOfType =
+ (typeof AgentConfigKindDtoOneOfType)[keyof typeof AgentConfigKindDtoOneOfType];
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const AgentConfigKindDtoOneOfType = {
+ select: 'select',
+} as const;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDto.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDto.ts
new file mode 100644
index 0000000000..f89150011f
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDto.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { AgentConfigKindDto } from './agentConfigKindDto';
+import type { AgentConfigOptionDtoAllOf } from './agentConfigOptionDtoAllOf';
+
+/**
+ * One agent-advertised ACP session setting.
+ */
+export type AgentConfigOptionDto = AgentConfigKindDto &
+ AgentConfigOptionDtoAllOf;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDtoAllOf.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDtoAllOf.ts
new file mode 100644
index 0000000000..3809e83ab2
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDtoAllOf.ts
@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { AgentConfigOptionDtoAllOfCategory } from './agentConfigOptionDtoAllOfCategory';
+import type { AgentConfigOptionDtoAllOfDescription } from './agentConfigOptionDtoAllOfDescription';
+
+export type AgentConfigOptionDtoAllOf = {
+ /** ACP semantic category, such as `model` or `thought_level`. */
+ category?: AgentConfigOptionDtoAllOfCategory;
+ /** Optional explanatory copy. */
+ description?: AgentConfigOptionDtoAllOfDescription;
+ /** Opaque id used to change this setting. */
+ id: string;
+ /** Display label supplied by the agent. */
+ name: string;
+};
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDtoAllOfCategory.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDtoAllOfCategory.ts
new file mode 100644
index 0000000000..b82c556295
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDtoAllOfCategory.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * ACP semantic category, such as `model` or `thought_level`.
+ */
+export type AgentConfigOptionDtoAllOfCategory = string | null;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDtoAllOfDescription.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDtoAllOfDescription.ts
new file mode 100644
index 0000000000..1ffd7150a4
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigOptionDtoAllOfDescription.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Optional explanatory copy.
+ */
+export type AgentConfigOptionDtoAllOfDescription = string | null;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigSelectOptionDto.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigSelectOptionDto.ts
new file mode 100644
index 0000000000..20410068e6
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigSelectOptionDto.ts
@@ -0,0 +1,22 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { AgentConfigSelectOptionDtoDescription } from './agentConfigSelectOptionDtoDescription';
+import type { AgentConfigSelectOptionDtoGroup } from './agentConfigSelectOptionDtoGroup';
+
+/**
+ * One value in an agent-advertised select.
+ */
+export interface AgentConfigSelectOptionDto {
+ /** Optional provider description of this value. */
+ description?: AgentConfigSelectOptionDtoDescription;
+ /** Optional group heading supplied by the provider. */
+ group?: AgentConfigSelectOptionDtoGroup;
+ /** Display label. */
+ name: string;
+ /** Opaque value returned to the agent when selected. */
+ value: string;
+}
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigSelectOptionDtoDescription.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigSelectOptionDtoDescription.ts
new file mode 100644
index 0000000000..b9f48f5b95
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigSelectOptionDtoDescription.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Optional provider description of this value.
+ */
+export type AgentConfigSelectOptionDtoDescription = string | null;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigSelectOptionDtoGroup.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigSelectOptionDtoGroup.ts
new file mode 100644
index 0000000000..f26f35ec82
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/agentConfigSelectOptionDtoGroup.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Optional group heading supplied by the provider.
+ */
+export type AgentConfigSelectOptionDtoGroup = string | null;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/capabilityHarnessDto.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/capabilityHarnessDto.ts
new file mode 100644
index 0000000000..fdbcbe1aed
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/capabilityHarnessDto.ts
@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Harness names accepted by the capability-discovery endpoint.
+ */
+export type CapabilityHarnessDto =
+ (typeof CapabilityHarnessDto)[keyof typeof CapabilityHarnessDto];
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const CapabilityHarnessDto = {
+ 'in-memory': 'in-memory',
+ cursor: 'cursor',
+ macrod: 'macrod',
+} as const;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesRequest.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesRequest.ts
new file mode 100644
index 0000000000..1362c79898
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesRequest.ts
@@ -0,0 +1,21 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { CapabilityHarnessDto } from './capabilityHarnessDto';
+import type { DiscoverAgentCapabilitiesRequestHarnessId } from './discoverAgentCapabilitiesRequestHarnessId';
+import type { DiscoverAgentCapabilitiesRequestModel } from './discoverAgentCapabilitiesRequestModel';
+
+/**
+ * HTTP request selecting one provider to probe.
+ */
+export interface DiscoverAgentCapabilitiesRequest {
+ /** Provider to probe. */
+ harness: CapabilityHarnessDto;
+ /** Required for macrod and forbidden for other targets. */
+ harnessId?: DiscoverAgentCapabilitiesRequestHarnessId;
+ /** Model whose session settings should be inspected. */
+ model?: DiscoverAgentCapabilitiesRequestModel;
+}
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesRequestHarnessId.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesRequestHarnessId.ts
new file mode 100644
index 0000000000..0116b34029
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesRequestHarnessId.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Required for macrod and forbidden for other targets.
+ */
+export type DiscoverAgentCapabilitiesRequestHarnessId = string | null;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesRequestModel.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesRequestModel.ts
new file mode 100644
index 0000000000..99b84f4a40
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesRequestModel.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * Model whose session settings should be inspected.
+ */
+export type DiscoverAgentCapabilitiesRequestModel = string | null;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesResponse.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesResponse.ts
new file mode 100644
index 0000000000..b3b42f4668
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/discoverAgentCapabilitiesResponse.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { AgentConfigOptionDto } from './agentConfigOptionDto';
+
+/**
+ * Successful capability-discovery response.
+ */
+export interface DiscoverAgentCapabilitiesResponse {
+ /** Complete ordered ACP session configuration advertised by the agent. */
+ configOptions: AgentConfigOptionDto[];
+}
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/index.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/index.ts
index 2bbfc05dfd..c4cec09642 100644
--- a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/index.ts
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/index.ts
@@ -27,6 +27,18 @@ export * from './agentActionOneOfOnezeroType';
export * from './agentActionOneOfSeven';
export * from './agentActionOneOfSevenAllOf';
export * from './agentActionOneOfSevenAllOfType';
+export * from './agentConfigKindDto';
+export * from './agentConfigKindDtoOneOf';
+export * from './agentConfigKindDtoOneOfThree';
+export * from './agentConfigKindDtoOneOfThreeType';
+export * from './agentConfigKindDtoOneOfType';
+export * from './agentConfigOptionDto';
+export * from './agentConfigOptionDtoAllOf';
+export * from './agentConfigOptionDtoAllOfCategory';
+export * from './agentConfigOptionDtoAllOfDescription';
+export * from './agentConfigSelectOptionDto';
+export * from './agentConfigSelectOptionDtoDescription';
+export * from './agentConfigSelectOptionDtoGroup';
export * from './agentModelDto';
export * from './agentModelDtoDescription';
export * from './agentModelDtoGroup';
@@ -73,6 +85,7 @@ export * from './agentSessionResponseThreadParent';
export * from './agentSetConfigOptionAction';
export * from './agentSetModelAction';
export * from './botId';
+export * from './capabilityHarnessDto';
export * from './captureAttemptDto';
export * from './captureAttemptDtoError';
export * from './captureAttemptDtoFinishedAt';
@@ -106,6 +119,10 @@ export * from './createSessionThread';
export * from './createSessionThreadChannelId';
export * from './createSessionThreadParent';
export * from './createSessionThreadThreadId';
+export * from './discoverAgentCapabilitiesRequest';
+export * from './discoverAgentCapabilitiesRequestHarnessId';
+export * from './discoverAgentCapabilitiesRequestModel';
+export * from './discoverAgentCapabilitiesResponse';
export * from './documentId';
export * from './editQueuedActionRequest';
export * from './elicitationAnswer';
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/openapi.json b/apps/web/src/lib/service-clients/service-agent-harness/openapi.json
index 49e1c243c4..a45a321ced 100644
--- a/apps/web/src/lib/service-clients/service-agent-harness/openapi.json
+++ b/apps/web/src/lib/service-clients/service-agent-harness/openapi.json
@@ -10,6 +10,58 @@
"version": "0.1.0"
},
"paths": {
+ "/agent-capabilities/discover": {
+ "post": {
+ "tags": ["agent-capabilities"],
+ "summary": "Probe one provider's ACP session configuration without persisting a session.",
+ "operationId": "discover_agent_capabilities_handler",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DiscoverAgentCapabilitiesRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Fresh provider session capabilities",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DiscoverAgentCapabilitiesResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid target"
+ },
+ "401": {
+ "description": "Unauthenticated"
+ },
+ "403": {
+ "description": "Harness is not visible to caller"
+ },
+ "409": {
+ "description": "Macrod runtime is disconnected"
+ },
+ "502": {
+ "description": "Provider probe failed"
+ },
+ "504": {
+ "description": "Macrod probe timed out"
+ }
+ },
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ]
+ }
+ },
"/agent-models/load": {
"post": {
"tags": ["agent-models"],
@@ -1657,6 +1709,102 @@
"format": "uuid",
"description": "Identifies one accepted [`AgentAction`] end to end: returned by the\ncontrol endpoint, written as the JSON-RPC request id on the action's wire\nframe, and read back off that frame as `request_id` on the folded message\nit derives.\n\nA v7 uuid, so ids sort by mint time. Minted by the server at accept time,\nor by a client that speculated the action and named it in the control\nrequest - either way the server is the only writer of runtime-bound\nframes, so a uuid-shaped request id remains the whole ownership test. The\nmachine's own handshake request ids (`agent_session:{session}:{n}`) are\nnot uuids and stay `None`."
},
+ "AgentConfigKindDto": {
+ "oneOf": [
+ {
+ "type": "object",
+ "description": "A single-value selector.",
+ "required": ["currentValue", "options", "type"],
+ "properties": {
+ "currentValue": {
+ "type": "string",
+ "description": "Current opaque value."
+ },
+ "options": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/AgentConfigSelectOptionDto"
+ },
+ "description": "Ordered values supplied by the agent."
+ },
+ "type": {
+ "type": "string",
+ "enum": ["select"]
+ }
+ }
+ },
+ {
+ "type": "object",
+ "description": "An on/off setting.",
+ "required": ["currentValue", "type"],
+ "properties": {
+ "currentValue": {
+ "type": "boolean",
+ "description": "Current value."
+ },
+ "type": {
+ "type": "string",
+ "enum": ["boolean"]
+ }
+ }
+ }
+ ],
+ "description": "Type-specific state for one agent session setting."
+ },
+ "AgentConfigOptionDto": {
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/AgentConfigKindDto",
+ "description": "Type-specific current value and choices."
+ },
+ {
+ "type": "object",
+ "required": ["id", "name"],
+ "properties": {
+ "category": {
+ "type": ["string", "null"],
+ "description": "ACP semantic category, such as `model` or `thought_level`."
+ },
+ "description": {
+ "type": ["string", "null"],
+ "description": "Optional explanatory copy."
+ },
+ "id": {
+ "type": "string",
+ "description": "Opaque id used to change this setting."
+ },
+ "name": {
+ "type": "string",
+ "description": "Display label supplied by the agent."
+ }
+ }
+ }
+ ],
+ "description": "One agent-advertised ACP session setting."
+ },
+ "AgentConfigSelectOptionDto": {
+ "type": "object",
+ "description": "One value in an agent-advertised select.",
+ "required": ["value", "name"],
+ "properties": {
+ "description": {
+ "type": ["string", "null"],
+ "description": "Optional provider description of this value."
+ },
+ "group": {
+ "type": ["string", "null"],
+ "description": "Optional group heading supplied by the provider."
+ },
+ "name": {
+ "type": "string",
+ "description": "Display label."
+ },
+ "value": {
+ "type": "string",
+ "description": "Opaque value returned to the agent when selected."
+ }
+ }
+ },
"AgentModelDto": {
"type": "object",
"description": "One model picker option.",
@@ -2163,6 +2311,11 @@
"BotId": {
"type": "string"
},
+ "CapabilityHarnessDto": {
+ "type": "string",
+ "description": "Harness names accepted by the capability-discovery endpoint.",
+ "enum": ["in-memory", "cursor", "macrod"]
+ },
"CaptureAttemptDto": {
"type": "object",
"description": "The latest capture attempt.\n\nClients deserialize this, so both derives are used.",
@@ -2503,6 +2656,40 @@
}
}
},
+ "DiscoverAgentCapabilitiesRequest": {
+ "type": "object",
+ "description": "HTTP request selecting one provider to probe.",
+ "required": ["harness"],
+ "properties": {
+ "harness": {
+ "$ref": "#/components/schemas/CapabilityHarnessDto",
+ "description": "Provider to probe."
+ },
+ "harnessId": {
+ "type": ["string", "null"],
+ "format": "uuid",
+ "description": "Required for macrod and forbidden for other targets."
+ },
+ "model": {
+ "type": ["string", "null"],
+ "description": "Model whose session settings should be inspected."
+ }
+ }
+ },
+ "DiscoverAgentCapabilitiesResponse": {
+ "type": "object",
+ "description": "Successful capability-discovery response.",
+ "required": ["configOptions"],
+ "properties": {
+ "configOptions": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/AgentConfigOptionDto"
+ },
+ "description": "Complete ordered ACP session configuration advertised by the agent."
+ }
+ }
+ },
"DocumentId": {
"type": "string",
"description": "A validated document identifier. Historical document ids need not be UUIDs."
diff --git a/crates/agent_harness/src/domain/capability_discovery.rs b/crates/agent_harness/src/domain/capability_discovery.rs
new file mode 100644
index 0000000000..d87b37e026
--- /dev/null
+++ b/crates/agent_harness/src/domain/capability_discovery.rs
@@ -0,0 +1,242 @@
+//! Domain vocabulary for fresh ACP capability discovery.
+
+use std::future::Future;
+use std::time::Duration;
+
+use agent_client_protocol::schema::v1::SessionConfigOption as AcpSessionConfigOption;
+use agent_fold::domain::session_config::{SessionConfigOption, session_config_options};
+use harness_id::HarnessId;
+use macro_user_id::user_id::MacroUserIdStr;
+
+#[cfg(test)]
+mod test;
+
+/// Provider selected by a capability-discovery request.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CapabilityHarness {
+ /// Macro's in-process agent.
+ InMemory,
+ /// The caller's Cursor account.
+ Cursor,
+ /// A paired macrod runtime.
+ Macrod,
+}
+
+/// One fresh capability-discovery request.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DiscoverAgentCapabilities {
+ /// Provider to inspect.
+ pub harness: CapabilityHarness,
+ /// Paired harness identity, required only for [`CapabilityHarness::Macrod`].
+ pub harness_id: Option<HarnessId>,
+ /// Selected model, when inspecting a preflight override.
+ pub model: Option<String>,
+}
+
+/// Agent-advertised settings returned by the use case.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentCapabilities {
+ /// Complete ordered ACP session configuration advertised by the agent.
+ pub config_options: Vec<SessionConfigOption>,
+}
+
+impl AgentCapabilities {
+ fn from_options(options: &[AcpSessionConfigOption]) -> Self {
+ Self {
+ config_options: session_config_options(options),
+ }
+ }
+
+ /// A provider with no discoverable session configuration.
+ #[must_use]
+ pub fn unsupported() -> Self {
+ Self {
+ config_options: Vec::new(),
+ }
+ }
+}
+
+/// Raw outcome from a provider probe.
+#[derive(Debug)]
+pub enum RawCapabilityProbe {
+ /// ACP session configuration advertised by the provider.
+ Options(Vec<AcpSessionConfigOption>),
+ /// This provider cannot advertise session configuration.
+ Unsupported,
+}
+
+/// A provider probe failure.
+#[derive(Debug, thiserror::Error)]
+pub enum CapabilityProbeError {
+ /// A required live runtime is not connected.
+ #[error("the requested harness is disconnected")]
+ Disconnected,
+ /// Provider-specific probing failed.
+ #[error("capability probe failed: {0}")]
+ Failed(String),
+}
+
+/// Use-case failure.
+#[derive(Debug, thiserror::Error)]
+pub enum DiscoverAgentCapabilitiesError {
+ /// The target shape is invalid.
+ #[error("{0}")]
+ BadRequest(String),
+ /// The caller cannot use or see the target harness.
+ #[error("forbidden")]
+ Forbidden,
+ /// A required runtime is disconnected.
+ #[error("the requested harness is disconnected")]
+ Disconnected,
+ /// The bounded request expired.
+ #[error("capability probe timed out")]
+ Timeout,
+ /// A provider failed.
+ #[error("capability probe failed: {0}")]
+ Probe(String),
+}
+
+/// Authorizes visibility and use of paired harnesses.
+pub trait HarnessCapabilityAccess: Send + Sync + 'static {
+ /// Whether `caller` may use and see `harness`.
+ fn can_use(
+ &self,
+ caller: &MacroUserIdStr<'static>,
+ harness: HarnessId,
+ ) -> impl Future<Output = Result<bool, String>> + Send;
+}
+
+/// Discovers a harness's advertised configuration without persisting a session.
+pub trait CapabilityProbe: Send + Sync + 'static {
+ /// Identity needed by the adapter: a caller, a paired harness, or `()`.
+ type Target: Sync;
+
+ /// Probe fresh capabilities for a target authorized by the domain service.
+ fn probe(
+ &self,
+ target: &Self::Target,
+ model: Option<&str>,
+ ) -> impl Future<Output = Result<RawCapabilityProbe, CapabilityProbeError>> + Send;
+}
+
+/// Authenticated agent-capability discovery use case.
+pub trait AgentCapabilitiesService: Send + Sync + 'static {
+ /// Discover one target's session settings without creating a persisted session.
+ fn load(
+ &self,
+ caller: MacroUserIdStr<'static>,
+ request: DiscoverAgentCapabilities,
+ ) -> impl Future<Output = Result<AgentCapabilities, DiscoverAgentCapabilitiesError>> + Send;
+}
+
+/// Domain service coordinating authorization, dispatch, timeout, and projection.
+pub struct AgentCapabilitiesServiceImpl<Access, InMemory, Cursor, Macrod> {
+ access: Access,
+ in_memory: InMemory,
+ cursor: Cursor,
+ macrod: Macrod,
+ timeout: Duration,
+}
+
+impl<Access, InMemory, Cursor, Macrod>
+ AgentCapabilitiesServiceImpl<Access, InMemory, Cursor, Macrod>
+{
+ /// Build the service from its outbound ports.
+ pub fn new(
+ access: Access,
+ in_memory: InMemory,
+ cursor: Cursor,
+ macrod: Macrod,
+ timeout: Duration,
+ ) -> Self {
+ Self {
+ access,
+ in_memory,
+ cursor,
+ macrod,
+ timeout,
+ }
+ }
+}
+
+impl<Access, InMemory, Cursor, Macrod> AgentCapabilitiesService
+ for AgentCapabilitiesServiceImpl<Access, InMemory, Cursor, Macrod>
+where
+ Access: HarnessCapabilityAccess,
+ InMemory: CapabilityProbe<Target = ()>,
+ Cursor: CapabilityProbe<Target = MacroUserIdStr<'static>>,
+ Macrod: CapabilityProbe<Target = HarnessId>,
+{
+ async fn load(
+ &self,
+ caller: MacroUserIdStr<'static>,
+ request: DiscoverAgentCapabilities,
+ ) -> Result<AgentCapabilities, DiscoverAgentCapabilitiesError> {
+ match (request.harness, request.harness_id) {
+ (CapabilityHarness::InMemory, None) => {
+ self.discover(&self.in_memory, &(), request.model.as_deref())
+ .await
+ }
+ (CapabilityHarness::Cursor, None) => {
+ self.discover(&self.cursor, &caller, request.model.as_deref())
+ .await
+ }
+ (CapabilityHarness::Macrod, Some(harness)) => {
+ let allowed = self
+ .access
+ .can_use(&caller, harness)
+ .await
+ .map_err(DiscoverAgentCapabilitiesError::Probe)?;
+ if !allowed {
+ return Err(DiscoverAgentCapabilitiesError::Forbidden);
+ }
+ self.discover(&self.macrod, &harness, request.model.as_deref())
+ .await
+ }
+ (CapabilityHarness::Macrod, None) => Err(DiscoverAgentCapabilitiesError::BadRequest(
+ "harnessId is required for macrod".to_owned(),
+ )),
+ (_, Some(_)) => Err(DiscoverAgentCapabilitiesError::BadRequest(
+ "harnessId is only valid for macrod".to_owned(),
+ )),
+ }
+ }
+}
+
+impl<Access, InMemory, Cursor, Macrod>
+ AgentCapabilitiesServiceImpl<Access, InMemory, Cursor, Macrod>
+{
+ async fn discover<Probe: CapabilityProbe>(
+ &self,
+ adapter: &Probe,
+ target: &Probe::Target,
+ model: Option<&str>,
+ ) -> Result<AgentCapabilities, DiscoverAgentCapabilitiesError> {
+ let probe = tokio::time::timeout(self.timeout, adapter.probe(target, model))
+ .await
+ .map_err(|_| DiscoverAgentCapabilitiesError::Timeout)?;
+ match probe {
+ Ok(RawCapabilityProbe::Options(options)) => {
+ Ok(AgentCapabilities::from_options(&options))
+ }
+ Ok(RawCapabilityProbe::Unsupported) => Ok(AgentCapabilities::unsupported()),
+ Err(CapabilityProbeError::Disconnected) => {
+ Err(DiscoverAgentCapabilitiesError::Disconnected)
+ }
+ Err(CapabilityProbeError::Failed(message)) => {
+ Err(DiscoverAgentCapabilitiesError::Probe(message))
+ }
+ }
+ }
+}
+
+impl<T: super::model_load::HarnessModelAccess> HarnessCapabilityAccess for T {
+ async fn can_use(
+ &self,
+ caller: &MacroUserIdStr<'static>,
+ harness: HarnessId,
+ ) -> Result<bool, String> {
+ super::model_load::HarnessModelAccess::can_use(self, caller, harness).await
+ }
+}
diff --git a/crates/agent_harness/src/domain/capability_discovery/test.rs b/crates/agent_harness/src/domain/capability_discovery/test.rs
new file mode 100644
index 0000000000..df5a3630b4
--- /dev/null
+++ b/crates/agent_harness/src/domain/capability_discovery/test.rs
@@ -0,0 +1,267 @@
+use std::sync::Mutex;
+use std::time::Duration;
+
+use agent_client_protocol::schema::v1::{
+ SessionConfigOption, SessionConfigSelectOption, SessionConfigValueId,
+};
+
+use super::*;
+
+fn caller() -> MacroUserIdStr<'static> {
+ MacroUserIdStr::try_from_email("[email protected]").unwrap()
+}
+
+fn options() -> Vec<SessionConfigOption> {
+ vec![SessionConfigOption::select(
+ "model",
+ "Model",
+ SessionConfigValueId::new("fast"),
+ vec![SessionConfigSelectOption::new("fast", "Fast")],
+ )]
+}
+
+struct Access(bool);
+
+impl HarnessCapabilityAccess for Access {
+ async fn can_use(
+ &self,
+ _caller: &MacroUserIdStr<'static>,
+ _harness: HarnessId,
+ ) -> Result<bool, String> {
+ Ok(self.0)
+ }
+}
+
+struct Probe<Target> {
+ targets: Mutex<Vec<Target>>,
+ result: fn() -> Result<RawCapabilityProbe, CapabilityProbeError>,
+}
+
+impl<Target> Probe<Target> {
+ fn new(result: fn() -> Result<RawCapabilityProbe, CapabilityProbeError>) -> Self {
+ Self {
+ targets: Mutex::new(Vec::new()),
+ result,
+ }
+ }
+
+ fn calls(&self) -> usize {
+ self.targets.lock().unwrap().len()
+ }
+}
+
+impl<Target: Clone + Send + Sync + 'static> CapabilityProbe for Probe<Target> {
+ type Target = Target;
+
+ async fn probe(
+ &self,
+ target: &Target,
+ _model: Option<&str>,
+ ) -> Result<RawCapabilityProbe, CapabilityProbeError> {
+ self.targets.lock().unwrap().push(target.clone());
+ (self.result)()
+ }
+}
+
+fn available() -> Result<RawCapabilityProbe, CapabilityProbeError> {
+ Ok(RawCapabilityProbe::Options(options()))
+}
+
+fn unsupported() -> Result<RawCapabilityProbe, CapabilityProbeError> {
+ Ok(RawCapabilityProbe::Unsupported)
+}
+
+struct HangingCursor;
+
+impl CapabilityProbe for HangingCursor {
+ type Target = MacroUserIdStr<'static>;
+
+ async fn probe(
+ &self,
+ _caller: &MacroUserIdStr<'static>,
+ _model: Option<&str>,
+ ) -> Result<RawCapabilityProbe, CapabilityProbeError> {
+ std::future::pending().await
+ }
+}
+
+#[tokio::test]
+async fn macrod_authorizes_before_dispatch_and_projects_the_catalog() {
+ let in_memory = Probe::new(unsupported);
+ let cursor = Probe::new(unsupported);
+ let macrod = Probe::new(available);
+ let service = AgentCapabilitiesServiceImpl::new(
+ Access(true),
+ in_memory,
+ cursor,
+ macrod,
+ Duration::from_secs(1),
+ );
+
+ let result = service
+ .load(
+ caller(),
+ DiscoverAgentCapabilities {
+ harness: CapabilityHarness::Macrod,
+ harness_id: Some(HarnessId::TEST_A),
+ model: None,
+ },
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(result.config_options[0].id, "model");
+ assert_eq!(service.in_memory.calls(), 0);
+ assert_eq!(service.cursor.calls(), 0);
+ assert_eq!(service.macrod.calls(), 1);
+ assert_eq!(
+ *service.macrod.targets.lock().unwrap(),
+ vec![HarnessId::TEST_A]
+ );
+}
+
+#[tokio::test]
+async fn invisible_macrod_is_forbidden_without_probing() {
+ let service = AgentCapabilitiesServiceImpl::new(
+ Access(false),
+ Probe::new(unsupported),
+ Probe::new(unsupported),
+ Probe::new(available),
+ Duration::from_secs(1),
+ );
+
+ let result = service
+ .load(
+ caller(),
+ DiscoverAgentCapabilities {
+ harness: CapabilityHarness::Macrod,
+ harness_id: Some(HarnessId::TEST_A),
+ model: None,
+ },
+ )
+ .await;
+
+ assert!(matches!(
+ result,
+ Err(DiscoverAgentCapabilitiesError::Forbidden)
+ ));
+ assert_eq!(service.macrod.calls(), 0);
+}
+
+#[tokio::test]
+async fn unsupported_provider_returns_the_supported_response_shape() {
+ let service = AgentCapabilitiesServiceImpl::new(
+ Access(true),
+ Probe::new(unsupported),
+ Probe::new(available),
+ Probe::new(available),
+ Duration::from_secs(1),
+ );
+
+ let result = service
+ .load(
+ caller(),
+ DiscoverAgentCapabilities {
+ harness: CapabilityHarness::InMemory,
+ harness_id: None,
+ model: None,
+ },
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(result, AgentCapabilities::unsupported());
+ assert_eq!(service.in_memory.calls(), 1);
+ assert_eq!(service.cursor.calls(), 0);
+}
+
+#[tokio::test]
+async fn cursor_receives_the_authenticated_caller() {
+ let service = AgentCapabilitiesServiceImpl::new(
+ Access(false),
+ Probe::new(unsupported),
+ Probe::new(available),
+ Probe::new(unsupported),
+ Duration::from_secs(1),
+ );
+
+ let result = service
+ .load(
+ caller(),
+ DiscoverAgentCapabilities {
+ harness: CapabilityHarness::Cursor,
+ harness_id: None,
+ model: None,
+ },
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(result.config_options[0].id, "model");
+ assert_eq!(*service.cursor.targets.lock().unwrap(), vec![caller()]);
+ assert_eq!(service.in_memory.calls(), 0);
+ assert_eq!(service.macrod.calls(), 0);
+}
+
+#[tokio::test]
+async fn invalid_targets_are_rejected_without_probing() {
+ let service = AgentCapabilitiesServiceImpl::new(
+ Access(true),
+ Probe::new(available),
+ Probe::new(available),
+ Probe::new(available),
+ Duration::from_secs(1),
+ );
+
+ for (harness, harness_id) in [
+ (CapabilityHarness::Macrod, None),
+ (CapabilityHarness::InMemory, Some(HarnessId::TEST_A)),
+ (CapabilityHarness::Cursor, Some(HarnessId::TEST_A)),
+ ] {
+ let result = service
+ .load(
+ caller(),
+ DiscoverAgentCapabilities {
+ harness,
+ harness_id,
+ model: None,
+ },
+ )
+ .await;
+ assert!(matches!(
+ result,
+ Err(DiscoverAgentCapabilitiesError::BadRequest(_))
+ ));
+ }
+
+ assert_eq!(service.in_memory.calls(), 0);
+ assert_eq!(service.cursor.calls(), 0);
+ assert_eq!(service.macrod.calls(), 0);
+}
+
+#[tokio::test]
+async fn cursor_probe_obeys_the_service_timeout() {
+ let service = AgentCapabilitiesServiceImpl::new(
+ Access(true),
+ Probe::new(unsupported),
+ HangingCursor,
+ Probe::new(unsupported),
+ Duration::from_millis(1),
+ );
+
+ let result = service
+ .load(
+ caller(),
+ DiscoverAgentCapabilities {
+ harness: CapabilityHarness::Cursor,
+ harness_id: None,
+ model: None,
+ },
+ )
+ .await;
+
+ assert!(matches!(
+ result,
+ Err(DiscoverAgentCapabilitiesError::Timeout)
+ ));
+}
diff --git a/crates/agent_harness/src/domain/mod.rs b/crates/agent_harness/src/domain/mod.rs
index 2ed1ce435b..d72a205112 100644
--- a/crates/agent_harness/src/domain/mod.rs
+++ b/crates/agent_harness/src/domain/mod.rs
@@ -1,7 +1,7 @@
+/// Fresh ACP capability discovery without creating an agent session.
+pub mod capability_discovery;
pub mod error;
pub mod model;
-/// Fresh model discovery without creating an agent session.
-pub mod model_load;
/// Which lifecycle facts become notifications for people, and for whom.
pub mod notifications;
/// A shared record of sessions with a command admitted but not yet resolved,
@@ -23,5 +23,7 @@ pub mod codex;
/// Owner-bound Claude conversation lifecycle.
pub mod claude;
+/// Compatible agent model discovery.
+pub mod model_load;
/// Repository selection and fallback policy for hosted coding sessions.
pub(crate) mod repository_selection;
diff --git a/crates/agent_harness/src/inbound/capability_discovery.rs b/crates/agent_harness/src/inbound/capability_discovery.rs
new file mode 100644
index 0000000000..6def87b3c3
--- /dev/null
+++ b/crates/agent_harness/src/inbound/capability_discovery.rs
@@ -0,0 +1,272 @@
+//! Authenticated HTTP adapter for fresh ACP capability discovery.
+
+use std::sync::Arc;
+
+use axum::Router;
+use axum::extract::{FromRef, Json, State};
+use axum::http::StatusCode;
+use axum::response::{IntoResponse, Response};
+use axum::routing::post;
+use harness_id::HarnessId;
+use macro_authorization::{
+ MacroAuthorizationExtractor, MacroAuthorizationService, MacroAuthorizationState, UserOnly,
+};
+use macro_uuid::Uuid;
+use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use crate::domain::capability_discovery::{
+ AgentCapabilities, AgentCapabilitiesService, CapabilityHarness, DiscoverAgentCapabilities,
+ DiscoverAgentCapabilitiesError,
+};
+
+#[cfg(test)]
+mod test;
+
+/// HTTP request selecting one provider to probe.
+#[derive(Debug, Deserialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct DiscoverAgentCapabilitiesRequest {
+ /// Provider to probe.
+ pub harness: CapabilityHarnessDto,
+ /// Required for macrod and forbidden for other targets.
+ pub harness_id: Option<Uuid>,
+ /// Model whose session settings should be inspected.
+ pub model: Option<String>,
+}
+
+/// Harness names accepted by the capability-discovery endpoint.
+#[derive(Debug, Deserialize, ToSchema)]
+#[serde(rename_all = "kebab-case")]
+pub enum CapabilityHarnessDto {
+ /// Macro's in-process agent.
+ InMemory,
+ /// The caller's Cursor account.
+ Cursor,
+ /// A paired macrod runtime.
+ Macrod,
+}
+
+impl TryFrom<DiscoverAgentCapabilitiesRequest> for DiscoverAgentCapabilities {
+ type Error = DiscoverAgentCapabilitiesError;
+
+ fn try_from(value: DiscoverAgentCapabilitiesRequest) -> Result<Self, Self::Error> {
+ let harness = match value.harness {
+ CapabilityHarnessDto::InMemory => CapabilityHarness::InMemory,
+ CapabilityHarnessDto::Cursor => CapabilityHarness::Cursor,
+ CapabilityHarnessDto::Macrod => CapabilityHarness::Macrod,
+ };
+ Ok(Self {
+ harness,
+ harness_id: value.harness_id.map(HarnessId::new_from_uuid),
+ model: value.model,
+ })
+ }
+}
+
+/// One value in an agent-advertised select.
+#[derive(Debug, Serialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentConfigSelectOptionDto {
+ /// Opaque value returned to the agent when selected.
+ pub value: String,
+ /// Display label.
+ pub name: String,
+ /// Optional provider description of this value.
+ pub description: Option<String>,
+ /// Optional group heading supplied by the provider.
+ pub group: Option<String>,
+}
+
+/// Type-specific state for one agent session setting.
+#[derive(Debug, Serialize, ToSchema)]
+#[serde(
+ tag = "type",
+ rename_all = "snake_case",
+ rename_all_fields = "camelCase"
+)]
+pub enum AgentConfigKindDto {
+ /// A single-value selector.
+ Select {
+ /// Current opaque value.
+ #[serde(rename = "currentValue")]
+ #[schema(rename = "currentValue")]
+ current_value: String,
+ /// Ordered values supplied by the agent.
+ options: Vec<AgentConfigSelectOptionDto>,
+ },
+ /// An on/off setting.
+ Boolean {
+ /// Current value.
+ #[serde(rename = "currentValue")]
+ #[schema(rename = "currentValue")]
+ current_value: bool,
+ },
+}
+
+/// One agent-advertised ACP session setting.
+#[derive(Debug, Serialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct AgentConfigOptionDto {
+ /// Opaque id used to change this setting.
+ pub id: String,
+ /// Display label supplied by the agent.
+ pub name: String,
+ /// Optional explanatory copy.
+ pub description: Option<String>,
+ /// ACP semantic category, such as `model` or `thought_level`.
+ pub category: Option<String>,
+ /// Type-specific current value and choices.
+ #[serde(flatten)]
+ pub kind: AgentConfigKindDto,
+}
+
+/// Successful capability-discovery response.
+#[derive(Debug, Serialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct DiscoverAgentCapabilitiesResponse {
+ /// Complete ordered ACP session configuration advertised by the agent.
+ pub config_options: Vec<AgentConfigOptionDto>,
+}
+
+impl From<AgentCapabilities> for DiscoverAgentCapabilitiesResponse {
+ fn from(value: AgentCapabilities) -> Self {
+ Self {
+ config_options: value
+ .config_options
+ .into_iter()
+ .map(|option| AgentConfigOptionDto {
+ id: option.id,
+ name: option.name,
+ description: option.description,
+ category: option.category,
+ kind: match option.kind {
+ agent_fold::domain::session_config::SessionConfigKind::Select {
+ current_value,
+ options,
+ } => AgentConfigKindDto::Select {
+ current_value,
+ options: options
+ .into_iter()
+ .map(|option| AgentConfigSelectOptionDto {
+ value: option.value,
+ name: option.name,
+ description: option.description,
+ group: option.group,
+ })
+ .collect(),
+ },
+ agent_fold::domain::session_config::SessionConfigKind::Boolean {
+ current_value,
+ } => AgentConfigKindDto::Boolean { current_value },
+ },
+ })
+ .collect(),
+ }
+ }
+}
+
+/// Router state for capability discovery.
+pub struct AgentCapabilitiesRouterState<Service, Auth> {
+ service: Arc<Service>,
+ authorization: MacroAuthorizationState<Auth>,
+}
+
+impl<Service, Auth> AgentCapabilitiesRouterState<Service, Auth> {
+ /// Build capability-discovery route state.
+ pub fn new(service: Arc<Service>, authorization: MacroAuthorizationState<Auth>) -> Self {
+ Self {
+ service,
+ authorization,
+ }
+ }
+}
+
+impl<Service, Auth> Clone for AgentCapabilitiesRouterState<Service, Auth> {
+ fn clone(&self) -> Self {
+ Self {
+ service: Arc::clone(&self.service),
+ authorization: self.authorization.clone(),
+ }
+ }
+}
+
+impl<Service, Auth> FromRef<AgentCapabilitiesRouterState<Service, Auth>>
+ for MacroAuthorizationState<Auth>
+{
+ fn from_ref(state: &AgentCapabilitiesRouterState<Service, Auth>) -> Self {
+ state.authorization.clone()
+ }
+}
+
+/// Build `POST /agent-capabilities/discover`.
+pub fn agent_capabilities_router<Service, Auth, S>(
+ state: AgentCapabilitiesRouterState<Service, Auth>,
+) -> Router<S>
+where
+ Service: AgentCapabilitiesService,
+ Auth: MacroAuthorizationService,
+ S: Clone + Send + Sync + 'static,
+{
+ Router::new()
+ .route(
+ "/agent-capabilities/discover",
+ post(discover_agent_capabilities_handler::<Service, Auth>),
+ )
+ .with_state(state)
+}
+
+/// Probe one provider's ACP session configuration without persisting a session.
+#[utoipa::path(
+ post,
+ path = "/agent-capabilities/discover",
+ tag = "agent-capabilities",
+ security(("bearerAuth" = [])),
+ request_body = DiscoverAgentCapabilitiesRequest,
+ responses(
+ (status = 200, description = "Fresh provider session capabilities", body = DiscoverAgentCapabilitiesResponse),
+ (status = 400, description = "Invalid target"),
+ (status = 401, description = "Unauthenticated"),
+ (status = 403, description = "Harness is not visible to caller"),
+ (status = 409, description = "Macrod runtime is disconnected"),
+ (status = 504, description = "Macrod probe timed out"),
+ (status = 502, description = "Provider probe failed"),
+ )
+)]
+pub async fn discover_agent_capabilities_handler<Service, Auth>(
+ State(state): State<AgentCapabilitiesRouterState<Service, Auth>>,
+ authorization: MacroAuthorizationExtractor<Auth, UserOnly>,
+ Json(request): Json<DiscoverAgentCapabilitiesRequest>,
+) -> Response
+where
+ Service: AgentCapabilitiesService,
+ Auth: MacroAuthorizationService,
+{
+ let request = match request.try_into() {
+ Ok(request) => request,
+ Err(error) => return capability_error_response(error),
+ };
+ match state
+ .service
+ .load(authorization.authorization.macro_user_id.clone(), request)
+ .await
+ {
+ Ok(capabilities) => (
+ StatusCode::OK,
+ Json(DiscoverAgentCapabilitiesResponse::from(capabilities)),
+ )
+ .into_response(),
+ Err(error) => capability_error_response(error),
+ }
+}
+
+fn capability_error_response(error: DiscoverAgentCapabilitiesError) -> Response {
+ let status = match error {
+ DiscoverAgentCapabilitiesError::BadRequest(_) => StatusCode::BAD_REQUEST,
+ DiscoverAgentCapabilitiesError::Forbidden => StatusCode::FORBIDDEN,
+ DiscoverAgentCapabilitiesError::Disconnected => StatusCode::CONFLICT,
+ DiscoverAgentCapabilitiesError::Timeout => StatusCode::GATEWAY_TIMEOUT,
+ DiscoverAgentCapabilitiesError::Probe(_) => StatusCode::BAD_GATEWAY,
+ };
+ (status, error.to_string()).into_response()
+}
diff --git a/crates/agent_harness/src/inbound/capability_discovery/test.rs b/crates/agent_harness/src/inbound/capability_discovery/test.rs
new file mode 100644
index 0000000000..885af523a3
--- /dev/null
+++ b/crates/agent_harness/src/inbound/capability_discovery/test.rs
@@ -0,0 +1,101 @@
+use axum::body::to_bytes;
+
+use super::*;
+
+#[test]
+fn target_request_maps_all_supported_harnesses() {
+ let in_memory = DiscoverAgentCapabilities::try_from(DiscoverAgentCapabilitiesRequest {
+ harness: CapabilityHarnessDto::InMemory,
+ harness_id: None,
+ model: None,
+ })
+ .unwrap();
+ assert_eq!(in_memory.harness, CapabilityHarness::InMemory);
+
+ let macrod_id = Uuid::new_v4();
+ let macrod = DiscoverAgentCapabilities::try_from(DiscoverAgentCapabilitiesRequest {
+ harness: CapabilityHarnessDto::Macrod,
+ harness_id: Some(macrod_id),
+ model: None,
+ })
+ .unwrap();
+ assert_eq!(macrod.harness, CapabilityHarness::Macrod);
+ assert_eq!(macrod.harness_id.unwrap().as_uuid(), macrod_id);
+}
+
+#[test]
+fn handler_errors_map_to_transport_statuses() {
+ for (error, status) in [
+ (
+ DiscoverAgentCapabilitiesError::BadRequest("bad".to_owned()),
+ StatusCode::BAD_REQUEST,
+ ),
+ (
+ DiscoverAgentCapabilitiesError::Forbidden,
+ StatusCode::FORBIDDEN,
+ ),
+ (
+ DiscoverAgentCapabilitiesError::Disconnected,
+ StatusCode::CONFLICT,
+ ),
+ (
+ DiscoverAgentCapabilitiesError::Timeout,
+ StatusCode::GATEWAY_TIMEOUT,
+ ),
+ (
+ DiscoverAgentCapabilitiesError::Probe("failed".to_owned()),
+ StatusCode::BAD_GATEWAY,
+ ),
+ ] {
+ assert_eq!(capability_error_response(error).status(), status);
+ }
+}
+
+#[tokio::test]
+async fn successful_response_serializes_config_options() {
+ let response = (
+ StatusCode::OK,
+ Json(DiscoverAgentCapabilitiesResponse::from(AgentCapabilities {
+ config_options: vec![agent_fold::domain::session_config::SessionConfigOption {
+ id: "reasoning_effort".to_owned(),
+ name: "Fast".to_owned(),
+ description: None,
+ category: Some("thought_level".to_owned()),
+ kind: agent_fold::domain::session_config::SessionConfigKind::Select {
+ current_value: "high".to_owned(),
+ options: vec![
+ agent_fold::domain::session_config::SessionConfigSelectOption {
+ value: "high".to_owned(),
+ name: "High".to_owned(),
+ description: None,
+ group: None,
+ },
+ ],
+ },
+ }],
+ })),
+ )
+ .into_response();
+
+ assert_eq!(response.status(), StatusCode::OK);
+ let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
+ assert_eq!(
+ serde_json::from_slice::<serde_json::Value>(&body).unwrap(),
+ serde_json::json!({
+ "configOptions": [{
+ "id": "reasoning_effort",
+ "name": "Fast",
+ "description": null,
+ "category": "thought_level",
+ "type": "select",
+ "currentValue": "high",
+ "options": [{
+ "value": "high",
+ "name": "High",
+ "description": null,
+ "group": null
+ }]
+ }]
+ })
+ );
+}
diff --git a/crates/agent_harness/src/inbound/mod.rs b/crates/agent_harness/src/inbound/mod.rs
index 9e8e749650..2af4433602 100644
--- a/crates/agent_harness/src/inbound/mod.rs
+++ b/crates/agent_harness/src/inbound/mod.rs
@@ -3,6 +3,8 @@
//! Thin by construction - decode the broker message, ask the domain whether it
//! is addressed to us, hand one value inward. No policy lives here.
+/// Authenticated ACP capability discovery.
+pub mod capability_discovery;
pub mod kafka;
/// Authenticated model discovery.
pub mod model_load;
diff --git a/docs/AGENT_EFFORT.md b/docs/AGENT_EFFORT.md
index c31ce170f8..24d86fed40 100644
--- a/docs/AGENT_EFFORT.md
+++ b/docs/AGENT_EFFORT.md
@@ -6,16 +6,6 @@ ACP `configOptions`, selecting category `thought_level` (legacy id fallback:
`reasoning_effort`). External ids and values are opaque; `ultra`, for example,
is not a native Macro effort level.
-## Configuration contract
-
-Session metadata preserves the agent's complete advertised ACP configuration.
-An omitted configOptions field leaves the prior snapshot intact; an explicit
-empty list removes it. Select values and configuration ids remain opaque.
-
-The generic setConfigOption action records a correlated control outcome. HTTP
-queue acceptance does not mean the runtime accepted the setting. Clients must
-wait for the runtime outcome before presenting a change as confirmed.
-
## Cursor
The authenticated Cursor catalog supplies concrete model variants. Discovery
@@ -51,3 +41,40 @@ Sources checked September 21, 2026:
[Anthropic effort](https://platform.claude.com/docs/en/build-with-claude/effort),
[GPT-5.5](https://developers.openai.com/api/docs/models/gpt-5.5), and
[OpenAI reasoning](https://developers.openai.com/api/docs/guides/reasoning).
+
+## Session lifecycle
+
+- POST /agent-capabilities/discover accepts a selected model for Cursor and
+ in-memory. The existing /agent-models/load API remains available.
+- External ACP runtimes do not advertise model-specific preflight capabilities.
+- New/resumed sessions and setting changes return the complete configuration.
+ Clients replace their previous options, including removing unsupported controls.
+- In-memory rejects unsupported models and effort values. A model change resets
+ an incompatible effort to Default. Replay restores confirmed snapshots only;
+ failed or unanswered requests do not become session settings.
+
+## Probe evidence and limits
+
+Prompt-free local ACP probes initialized a session, switched advertised models,
+set advertised effort values, and tried an invalid value. No inference request
+was sent. Observed capabilities are version- and account-specific:
+
+| Harness tested | Observations |
+| --- | --- |
+| Claude Code 2.1.278, claude-agent-acp 0.73.0 | Sonnet/Opus: default, low, medium, high, xhigh, max; switching to Haiku removes effort. Invalid value rejected. |
+| Codex CLI 0.154, codex-acp 1.8.0 | GPT-5.5: low/medium/high/xhigh; GPT-5.6 Sol adds max/ultra. Initial Astra session omitted effort. Invalid value rejected. |
+| OpenCode 1.18.23 | Tested Haiku 4.5 and Sonnet 4.5 advertised high/max; Opus 4.5 advertised low/medium/high. Initial model omitted effort. Subsequent probe startups failed. |
+| Hermes 0.20.4 | Legacy model/mode metadata, no configOptions observed. |
+
+Sixteen advertised effort changes were accepted with complete configuration
+responses. These observations verify ACP advertisement and acceptance, not the
+provider request made during inference. OpenClaw was unavailable. Cursor and
+in-memory are covered by repository ACP adapter tests and provider serialization
+tests; these are deterministic tests, not claims of live provider execution.
+
+To reproduce the protocol check with an authenticated harness, launch its ACP
+stdio command in an empty temporary directory; send `initialize`, `session/new`,
+and `session/set_config_option` using the returned session id and advertised
+config ids/values. Re-read the full `configOptions` after every model change.
+Record harness and adapter versions. Never infer a native provider profile from
+an external harness result.
diff --git a/packages/sdk/generated/agent-harness/index.ts b/packages/sdk/generated/agent-harness/index.ts
index 16f98b3ec3..3f383faae0 100644
--- a/packages/sdk/generated/agent-harness/index.ts
+++ b/packages/sdk/generated/agent-harness/index.ts
@@ -1,4 +1,4 @@
// This file is auto-generated by @hey-api/openapi-ts
export { type Options, Sdk } from './sdk.gen';
-export type { AccessLevel, AgentAction, AgentActionId, AgentModelDto, AgentModelsStatusDto, AgentPermissionAction, AgentPromptAction, AgentRepositoriesResponse, AgentRepositoryBranchesResponse, AgentRepositoryDto, AgentRespondElicitationAction, AgentSessionChangesPatchResponse, AgentSessionChangesResponse, AgentSessionLogEntryDto, AgentSessionLogResponse, AgentSessionPreviewData, AgentSessionPreviewDto, AgentSessionQueueResponse, AgentSessionResponse, AgentSetConfigOptionAction, AgentSetModelAction, BotId, CaptureAttemptDto, CaptureOutcomeDto, ChangedFileDto, ChangesetDto, ChangesetSourceDto, ChannelSharePermission, ClientOptions, CompleteData, CompleteErrors, CompleteRequest, CompleteResponse, CompleteResponses, ControlAgentSessionData, ControlAgentSessionError, ControlAgentSessionErrors, ControlAgentSessionResponse, ControlAgentSessionResponses, ControlRequest, ControlResponse, ControlStatusDto, CreateAgentSessionData, CreateAgentSessionError, CreateAgentSessionErrors, CreateAgentSessionRequest, CreateAgentSessionResponse, CreateAgentSessionResponse2, CreateAgentSessionResponses, CreateSessionThread, DeleteAgentSessionData, DeleteAgentSessionError, DeleteAgentSessionErrors, DeleteAgentSessionResponses, DisconnectData, DisconnectErrors, DisconnectResponse, DisconnectResponses, DocumentId, EditQueuedActionData, EditQueuedActionError, EditQueuedActionErrors, EditQueuedActionRequest, EditQueuedActionResponse, EditQueuedActionResponses, ElicitationAnswer, ElicitationContentValue, ElicitationRequestId, EmptyRequest, ExternalSessionResponse, FileChangeKindDto, GetAgentSandboxSizeData, GetAgentSandboxSizeError, GetAgentSandboxSizeErrors, GetAgentSandboxSizeResponse, GetAgentSandboxSizeResponses, GetAgentSessionChangesData, GetAgentSessionChangesError, GetAgentSessionChangesErrors, GetAgentSessionChangesPatchData, GetAgentSessionChangesPatchError, GetAgentSessionChangesPatchErrors, GetAgentSessionChangesPatchResponse, GetAgentSessionChangesPatchResponses, GetAgentSessionChangesResponse, GetAgentSessionChangesResponses, GetAgentSessionData, GetAgentSessionError, GetAgentSessionErrors, GetAgentSessionLogData, GetAgentSessionLogError, GetAgentSessionLogErrors, GetAgentSessionLogResponse, GetAgentSessionLogResponses, GetAgentSessionPermissionsData, GetAgentSessionPermissionsError, GetAgentSessionPermissionsErrors, GetAgentSessionPermissionsResponse, GetAgentSessionPermissionsResponses, GetAgentSessionQueueData, GetAgentSessionQueueError, GetAgentSessionQueueErrors, GetAgentSessionQueueResponse, GetAgentSessionQueueResponses, GetAgentSessionResponse, GetAgentSessionResponses, GitRefDto, LinkShare, ListAgentRepositoriesData, ListAgentRepositoriesErrors, ListAgentRepositoriesResponse, ListAgentRepositoriesResponses, ListAgentRepositoryBranchesData, ListAgentRepositoryBranchesErrors, ListAgentRepositoryBranchesResponse, ListAgentRepositoryBranchesResponses, LoadAgentModelsHandlerData, LoadAgentModelsHandlerErrors, LoadAgentModelsHandlerResponse, LoadAgentModelsHandlerResponses, LoadAgentModelsRequest, LoadAgentModelsResponse, LogDirectionDto, LogFrameDto, MessageParent, ModelHarnessDto, PermissionAnswer, PreviewAgentSessionsData, PreviewAgentSessionsError, PreviewAgentSessionsErrors, PreviewAgentSessionsRequest, PreviewAgentSessionsResponse, PreviewAgentSessionsResponse2, PreviewAgentSessionsResponses, PromptAttachment, PutAgentSandboxSizeData, PutAgentSandboxSizeError, PutAgentSandboxSizeErrors, PutAgentSandboxSizeResponse, PutAgentSandboxSizeResponses, PutAgentSessionSandboxSizeData, PutAgentSessionSandboxSizeError, PutAgentSessionSandboxSizeErrors, PutAgentSessionSandboxSizeResponse, PutAgentSessionSandboxSizeResponses, QueuedActionDto, RefreshAgentSessionChangesData, RefreshAgentSessionChangesError, RefreshAgentSessionChangesErrors, RefreshAgentSessionChangesResponse, RefreshAgentSessionChangesResponses, RemoveQueuedActionData, RemoveQueuedActionError, RemoveQueuedActionErrors, RemoveQueuedActionResponse, RemoveQueuedActionResponses, RenameAgentSessionData, RenameAgentSessionError, RenameAgentSessionErrors, RenameAgentSessionRequest, RenameAgentSessionResponse, RenameAgentSessionResponses, SandboxSize, SandboxSizeBody, SessionBot, SessionStatusDto, SetAgentSessionArchivedData, SetAgentSessionArchivedError, SetAgentSessionArchivedErrors, SetAgentSessionArchivedRequest, SetAgentSessionArchivedResponse, SetAgentSessionArchivedResponses, SharePermissionV2, StartData, StartErrors, StartResponse, StartResponse2, StartResponses, StatusData, StatusErrors, StatusResponse, StatusResponse2, StatusResponses, UpdateAgentSessionPermissionsData, UpdateAgentSessionPermissionsError, UpdateAgentSessionPermissionsErrors, UpdateAgentSessionPermissionsResponse, UpdateAgentSessionPermissionsResponses, UpdateChannelSharePermission, UpdateOperation, UpdateSharePermissionRequestV2, WithAgentSessionId } from './types.gen';
+export type { AccessLevel, AgentAction, AgentActionId, AgentConfigKindDto, AgentConfigOptionDto, AgentConfigSelectOptionDto, AgentModelDto, AgentModelsStatusDto, AgentPermissionAction, AgentPromptAction, AgentRepositoriesResponse, AgentRepositoryBranchesResponse, AgentRepositoryDto, AgentRespondElicitationAction, AgentSessionChangesPatchResponse, AgentSessionChangesResponse, AgentSessionLogEntryDto, AgentSessionLogResponse, AgentSessionPreviewData, AgentSessionPreviewDto, AgentSessionQueueResponse, AgentSessionResponse, AgentSetConfigOptionAction, AgentSetModelAction, BotId, CapabilityHarnessDto, CaptureAttemptDto, CaptureOutcomeDto, ChangedFileDto, ChangesetDto, ChangesetSourceDto, ChannelSharePermission, ClientOptions, CompleteData, CompleteErrors, CompleteRequest, CompleteResponse, CompleteResponses, ControlAgentSessionData, ControlAgentSessionError, ControlAgentSessionErrors, ControlAgentSessionResponse, ControlAgentSessionResponses, ControlRequest, ControlResponse, ControlStatusDto, CreateAgentSessionData, CreateAgentSessionError, CreateAgentSessionErrors, CreateAgentSessionRequest, CreateAgentSessionResponse, CreateAgentSessionResponse2, CreateAgentSessionResponses, CreateSessionThread, DeleteAgentSessionData, DeleteAgentSessionError, DeleteAgentSessionErrors, DeleteAgentSessionResponses, DisconnectData, DisconnectErrors, DisconnectResponse, DisconnectResponses, DiscoverAgentCapabilitiesHandlerData, DiscoverAgentCapabilitiesHandlerErrors, DiscoverAgentCapabilitiesHandlerResponse, DiscoverAgentCapabilitiesHandlerResponses, DiscoverAgentCapabilitiesRequest, DiscoverAgentCapabilitiesResponse, DocumentId, EditQueuedActionData, EditQueuedActionError, EditQueuedActionErrors, EditQueuedActionRequest, EditQueuedActionResponse, EditQueuedActionResponses, ElicitationAnswer, ElicitationContentValue, ElicitationRequestId, EmptyRequest, ExternalSessionResponse, FileChangeKindDto, GetAgentSandboxSizeData, GetAgentSandboxSizeError, GetAgentSandboxSizeErrors, GetAgentSandboxSizeResponse, GetAgentSandboxSizeResponses, GetAgentSessionChangesData, GetAgentSessionChangesError, GetAgentSessionChangesErrors, GetAgentSessionChangesPatchData, GetAgentSessionChangesPatchError, GetAgentSessionChangesPatchErrors, GetAgentSessionChangesPatchResponse, GetAgentSessionChangesPatchResponses, GetAgentSessionChangesResponse, GetAgentSessionChangesResponses, GetAgentSessionData, GetAgentSessionError, GetAgentSessionErrors, GetAgentSessionLogData, GetAgentSessionLogError, GetAgentSessionLogErrors, GetAgentSessionLogResponse, GetAgentSessionLogResponses, GetAgentSessionPermissionsData, GetAgentSessionPermissionsError, GetAgentSessionPermissionsErrors, GetAgentSessionPermissionsResponse, GetAgentSessionPermissionsResponses, GetAgentSessionQueueData, GetAgentSessionQueueError, GetAgentSessionQueueErrors, GetAgentSessionQueueResponse, GetAgentSessionQueueResponses, GetAgentSessionResponse, GetAgentSessionResponses, GitRefDto, LinkShare, ListAgentRepositoriesData, ListAgentRepositoriesErrors, ListAgentRepositoriesResponse, ListAgentRepositoriesResponses, ListAgentRepositoryBranchesData, ListAgentRepositoryBranchesErrors, ListAgentRepositoryBranchesResponse, ListAgentRepositoryBranchesResponses, LoadAgentModelsHandlerData, LoadAgentModelsHandlerErrors, LoadAgentModelsHandlerResponse, LoadAgentModelsHandlerResponses, LoadAgentModelsRequest, LoadAgentModelsResponse, LogDirectionDto, LogFrameDto, MessageParent, ModelHarnessDto, PermissionAnswer, PreviewAgentSessionsData, PreviewAgentSessionsError, PreviewAgentSessionsErrors, PreviewAgentSessionsRequest, PreviewAgentSessionsResponse, PreviewAgentSessionsResponse2, PreviewAgentSessionsResponses, PromptAttachment, PutAgentSandboxSizeData, PutAgentSandboxSizeError, PutAgentSandboxSizeErrors, PutAgentSandboxSizeResponse, PutAgentSandboxSizeResponses, PutAgentSessionSandboxSizeData, PutAgentSessionSandboxSizeError, PutAgentSessionSandboxSizeErrors, PutAgentSessionSandboxSizeResponse, PutAgentSessionSandboxSizeResponses, QueuedActionDto, RefreshAgentSessionChangesData, RefreshAgentSessionChangesError, RefreshAgentSessionChangesErrors, RefreshAgentSessionChangesResponse, RefreshAgentSessionChangesResponses, RemoveQueuedActionData, RemoveQueuedActionError, RemoveQueuedActionErrors, RemoveQueuedActionResponse, RemoveQueuedActionResponses, RenameAgentSessionData, RenameAgentSessionError, RenameAgentSessionErrors, RenameAgentSessionRequest, RenameAgentSessionResponse, RenameAgentSessionResponses, SandboxSize, SandboxSizeBody, SessionBot, SessionStatusDto, SetAgentSessionArchivedData, SetAgentSessionArchivedError, SetAgentSessionArchivedErrors, SetAgentSessionArchivedRequest, SetAgentSessionArchivedResponse, SetAgentSessionArchivedResponses, SharePermissionV2, StartData, StartErrors, StartResponse, StartResponse2, StartResponses, StatusData, StatusErrors, StatusResponse, StatusResponse2, StatusResponses, UpdateAgentSessionPermissionsData, UpdateAgentSessionPermissionsError, UpdateAgentSessionPermissionsErrors, UpdateAgentSessionPermissionsResponse, UpdateAgentSessionPermissionsResponses, UpdateChannelSharePermission, UpdateOperation, UpdateSharePermissionRequestV2, WithAgentSessionId } from './types.gen';
diff --git a/packages/sdk/generated/agent-harness/sdk.gen.ts b/packages/sdk/generated/agent-harness/sdk.gen.ts
index dbdd7c2a81..ab5860cca3 100644
--- a/packages/sdk/generated/agent-harness/sdk.gen.ts
+++ b/packages/sdk/generated/agent-harness/sdk.gen.ts
@@ -2,7 +2,7 @@
import type { Client, ClientMeta, Options as Options2, RequestResult, TDataShape } from './client';
import { client } from './client.gen';
-import type { CompleteData, CompleteErrors, CompleteResponses, ControlAgentSessionData, ControlAgentSessionErrors, ControlAgentSessionResponses, CreateAgentSessionData, CreateAgentSessionErrors, CreateAgentSessionResponses, DeleteAgentSessionData, DeleteAgentSessionErrors, DeleteAgentSessionResponses, DisconnectData, DisconnectErrors, DisconnectResponses, EditQueuedActionData, EditQueuedActionErrors, EditQueuedActionResponses, GetAgentSandboxSizeData, GetAgentSandboxSizeErrors, GetAgentSandboxSizeResponses, GetAgentSessionChangesData, GetAgentSessionChangesErrors, GetAgentSessionChangesPatchData, GetAgentSessionChangesPatchErrors, GetAgentSessionChangesPatchResponses, GetAgentSessionChangesResponses, GetAgentSessionData, GetAgentSessionErrors, GetAgentSessionLogData, GetAgentSessionLogErrors, GetAgentSessionLogResponses, GetAgentSessionPermissionsData, GetAgentSessionPermissionsErrors, GetAgentSessionPermissionsResponses, GetAgentSessionQueueData, GetAgentSessionQueueErrors, GetAgentSessionQueueResponses, GetAgentSessionResponses, ListAgentRepositoriesData, ListAgentRepositoriesErrors, ListAgentRepositoriesResponses, ListAgentRepositoryBranchesData, ListAgentRepositoryBranchesErrors, ListAgentRepositoryBranchesResponses, LoadAgentModelsHandlerData, LoadAgentModelsHandlerErrors, LoadAgentModelsHandlerResponses, PreviewAgentSessionsData, PreviewAgentSessionsErrors, PreviewAgentSessionsResponses, PutAgentSandboxSizeData, PutAgentSandboxSizeErrors, PutAgentSandboxSizeResponses, PutAgentSessionSandboxSizeData, PutAgentSessionSandboxSizeErrors, PutAgentSessionSandboxSizeResponses, RefreshAgentSessionChangesData, RefreshAgentSessionChangesErrors, RefreshAgentSessionChangesResponses, RemoveQueuedActionData, RemoveQueuedActionErrors, RemoveQueuedActionResponses, RenameAgentSessionData, RenameAgentSessionErrors, RenameAgentSessionResponses, SetAgentSessionArchivedData, SetAgentSessionArchivedErrors, SetAgentSessionArchivedResponses, StartData, StartErrors, StartResponses, StatusData, StatusErrors, StatusResponses, UpdateAgentSessionPermissionsData, UpdateAgentSessionPermissionsErrors, UpdateAgentSessionPermissionsResponses } from './types.gen';
+import type { CompleteData, CompleteErrors, CompleteResponses, ControlAgentSessionData, ControlAgentSessionErrors, ControlAgentSessionResponses, CreateAgentSessionData, CreateAgentSessionErrors, CreateAgentSessionResponses, DeleteAgentSessionData, DeleteAgentSessionErrors, DeleteAgentSessionResponses, DisconnectData, DisconnectErrors, DisconnectResponses, DiscoverAgentCapabilitiesHandlerData, DiscoverAgentCapabilitiesHandlerErrors, DiscoverAgentCapabilitiesHandlerResponses, EditQueuedActionData, EditQueuedActionErrors, EditQueuedActionResponses, GetAgentSandboxSizeData, GetAgentSandboxSizeErrors, GetAgentSandboxSizeResponses, GetAgentSessionChangesData, GetAgentSessionChangesErrors, GetAgentSessionChangesPatchData, GetAgentSessionChangesPatchErrors, GetAgentSessionChangesPatchResponses, GetAgentSessionChangesResponses, GetAgentSessionData, GetAgentSessionErrors, GetAgentSessionLogData, GetAgentSessionLogErrors, GetAgentSessionLogResponses, GetAgentSessionPermissionsData, GetAgentSessionPermissionsErrors, GetAgentSessionPermissionsResponses, GetAgentSessionQueueData, GetAgentSessionQueueErrors, GetAgentSessionQueueResponses, GetAgentSessionResponses, ListAgentRepositoriesData, ListAgentRepositoriesErrors, ListAgentRepositoriesResponses, ListAgentRepositoryBranchesData, ListAgentRepositoryBranchesErrors, ListAgentRepositoryBranchesResponses, LoadAgentModelsHandlerData, LoadAgentModelsHandlerErrors, LoadAgentModelsHandlerResponses, PreviewAgentSessionsData, PreviewAgentSessionsErrors, PreviewAgentSessionsResponses, PutAgentSandboxSizeData, PutAgentSandboxSizeErrors, PutAgentSandboxSizeResponses, PutAgentSessionSandboxSizeData, PutAgentSessionSandboxSizeErrors, PutAgentSessionSandboxSizeResponses, RefreshAgentSessionChangesData, RefreshAgentSessionChangesErrors, RefreshAgentSessionChangesResponses, RemoveQueuedActionData, RemoveQueuedActionErrors, RemoveQueuedActionResponses, RenameAgentSessionData, RenameAgentSessionErrors, RenameAgentSessionResponses, SetAgentSessionArchivedData, SetAgentSessionArchivedErrors, SetAgentSessionArchivedResponses, StartData, StartErrors, StartResponses, StatusData, StatusErrors, StatusResponses, UpdateAgentSessionPermissionsData, UpdateAgentSessionPermissionsErrors, UpdateAgentSessionPermissionsResponses } from './types.gen';
export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = Options2<TData, ThrowOnError, TResponse> & {
/**
@@ -57,6 +57,21 @@ export class Sdk extends HeyApiClient {
Sdk.__registry.set(this, args?.key);
}
+ /**
+ * Probe one provider's ACP session configuration without persisting a session.
+ */
+ public discoverAgentCapabilitiesHandler<ThrowOnError extends boolean = false>(options: Options<DiscoverAgentCapabilitiesHandlerData, ThrowOnError>): RequestResult<DiscoverAgentCapabilitiesHandlerResponses, DiscoverAgentCapabilitiesHandlerErrors, ThrowOnError> {
+ return (options.client ?? this.client).post<DiscoverAgentCapabilitiesHandlerResponses, DiscoverAgentCapabilitiesHandlerErrors, ThrowOnError>({
+ security: [{ scheme: 'bearer', type: 'http' }],
+ url: '/agent-capabilities/discover',
+ ...options,
+ headers: {
+ 'Content-Type': 'application/json',
+ ...options.headers
+ }
+ });
+ }
+
/**
* Probe one provider's model catalog without creating an agent session.
*/
diff --git a/packages/sdk/generated/agent-harness/types.gen.ts b/packages/sdk/generated/agent-harness/types.gen.ts
index 40f3316575..1b021a32c3 100644
--- a/packages/sdk/generated/agent-harness/types.gen.ts
+++ b/packages/sdk/generated/agent-harness/types.gen.ts
@@ -43,6 +43,71 @@ export type AgentAction = (AgentPromptAction & {
*/
export type AgentActionId = string;
+/**
+ * Type-specific state for one agent session setting.
+ */
+export type AgentConfigKindDto = {
+ /**
+ * Current opaque value.
+ */
+ currentValue: string;
+ /**
+ * Ordered values supplied by the agent.
+ */
+ options: Array<AgentConfigSelectOptionDto>;
+ type: 'select';
+} | {
+ /**
+ * Current value.
+ */
+ currentValue: boolean;
+ type: 'boolean';
+};
+
+/**
+ * One agent-advertised ACP session setting.
+ */
+export type AgentConfigOptionDto = AgentConfigKindDto & {
+ /**
+ * ACP semantic category, such as `model` or `thought_level`.
+ */
+ category?: string | null;
+ /**
+ * Optional explanatory copy.
+ */
+ description?: string | null;
+ /**
+ * Opaque id used to change this setting.
+ */
+ id: string;
+ /**
+ * Display label supplied by the agent.
+ */
+ name: string;
+};
+
+/**
+ * One value in an agent-advertised select.
+ */
+export type AgentConfigSelectOptionDto = {
+ /**
+ * Optional provider description of this value.
+ */
+ description?: string | null;
+ /**
+ * Optional group heading supplied by the provider.
+ */
+ group?: string | null;
+ /**
+ * Display label.
+ */
+ name: string;
+ /**
+ * Opaque value returned to the agent when selected.
+ */
+ value: string;
+};
+
/**
* One model picker option.
*/
@@ -433,6 +498,11 @@ export type AgentSetModelAction = {
export type BotId = string;
+/**
+ * Harness names accepted by the capability-discovery endpoint.
+ */
+export type CapabilityHarnessDto = 'in-memory' | 'cursor' | 'macrod';
+
/**
* The latest capture attempt.
*
@@ -747,6 +817,34 @@ export type CreateSessionThread = {
threadId?: string | null;
};
+/**
+ * HTTP request selecting one provider to probe.
+ */
+export type DiscoverAgentCapabilitiesRequest = {
+ /**
+ * Provider to probe.
+ */
+ harness: CapabilityHarnessDto;
+ /**
+ * Required for macrod and forbidden for other targets.
+ */
+ harnessId?: string | null;
+ /**
+ * Model whose session settings should be inspected.
+ */
+ model?: string | null;
+};
+
+/**
+ * Successful capability-discovery response.
+ */
+export type DiscoverAgentCapabilitiesResponse = {
+ /**
+ * Complete ordered ACP session configuration advertised by the agent.
+ */
+ configOptions: Array<AgentConfigOptionDto>;
+};
+
/**
* A validated document identifier. Historical document ids need not be UUIDs.
*/
@@ -1224,6 +1322,49 @@ export type WithAgentSessionId = {
id: string;
};
+export type DiscoverAgentCapabilitiesHandlerData = {
+ body: DiscoverAgentCapabilitiesRequest;
+ path?: never;
+ query?: never;
+ url: '/agent-capabilities/discover';
+};
+
+export type DiscoverAgentCapabilitiesHandlerErrors = {
+ /**
+ * Invalid target
+ */
+ 400: unknown;
+ /**
+ * Unauthenticated
+ */
+ 401: unknown;
+ /**
+ * Harness is not visible to caller
+ */
+ 403: unknown;
+ /**
+ * Macrod runtime is disconnected
+ */
+ 409: unknown;
+ /**
+ * Provider probe failed
+ */
+ 502: unknown;
+ /**
+ * Macrod probe timed out
+ */
+ 504: unknown;
+};
+
+export type DiscoverAgentCapabilitiesHandlerResponses = {
+ /**
+ * Fresh provider session capabilities
+ */
+ 200: DiscoverAgentCapabilitiesResponse;
+};
+
+export type DiscoverAgentCapabilitiesHandlerResponse = DiscoverAgentCapabilitiesHandlerResponses[keyof DiscoverAgentCapabilitiesHandlerResponses];
+
export type LoadAgentModelsHandlerData = {
body: LoadAgentModelsRequest;
path?: never;
diff --git a/packages/sdk/specs/agent-harness.json b/packages/sdk/specs/agent-harness.json
index 49e1c243c4..a45a321ced 100644
--- a/packages/sdk/specs/agent-harness.json
+++ b/packages/sdk/specs/agent-harness.json
@@ -10,6 +10,58 @@
"version": "0.1.0"
},
"paths": {
+ "/agent-capabilities/discover": {
+ "post": {
+ "tags": ["agent-capabilities"],
+ "summary": "Probe one provider's ACP session configuration without persisting a session.",
+ "operationId": "discover_agent_capabilities_handler",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DiscoverAgentCapabilitiesRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Fresh provider session capabilities",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DiscoverAgentCapabilitiesResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid target"
+ },
+ "401": {
+ "description": "Unauthenticated"
+ },
+ "403": {
+ "description": "Harness is not visible to caller"
+ },
+ "409": {
+ "description": "Macrod runtime is disconnected"
+ },
+ "502": {
+ "description": "Provider probe failed"
+ },
+ "504": {
+ "description": "Macrod probe timed out"
+ }
+ },
+ "security": [
+ {
+ "bearerAuth": []
+ }
+ ]
+ }
+ },
"/agent-models/load": {
"post": {
"tags": ["agent-models"],
@@ -1657,6 +1709,102 @@
"format": "uuid",
"description": "Identifies one accepted [`AgentAction`] end to end: returned by the\ncontrol endpoint, written as the JSON-RPC request id on the action's wire\nframe, and read back off that frame as `request_id` on the folded message\nit derives.\n\nA v7 uuid, so ids sort by mint time. Minted by the server at accept time,\nor by a client that speculated the action and named it in the control\nrequest - either way the server is the only writer of runtime-bound\nframes, so a uuid-shaped request id remains the whole ownership test. The\nmachine's own handshake request ids (`agent_session:{session}:{n}`) are\nnot uuids and stay `None`."
},
+ "AgentConfigKindDto": {
+ "oneOf": [
+ {
+ "type": "object",
+ "description": "A single-value selector.",
+ "required": ["currentValue", "options", "type"],
+ "properties": {
+ "currentValue": {
+ "type": "string",
+ "description": "Current opaque value."
+ },
+ "options": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/AgentConfigSelectOptionDto"
+ },
+ "description": "Ordered values supplied by the agent."
+ },
+ "type": {
+ "type": "string",
+ "enum": ["select"]
+ }
+ }
+ },
+ {
+ "type": "object",
+ "description": "An on/off setting.",
+ "required": ["currentValue", "type"],
+ "properties": {
+ "currentValue": {
+ "type": "boolean",
+ "description": "Current value."
+ },
+ "type": {
+ "type": "string",
+ "enum": ["boolean"]
+ }
+ }
+ }
+ ],
+ "description": "Type-specific state for one agent session setting."
+ },
+ "AgentConfigOptionDto": {
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/AgentConfigKindDto",
+ "description": "Type-specific current value and choices."
+ },
+ {
+ "type": "object",
+ "required": ["id", "name"],
+ "properties": {
+ "category": {
+ "type": ["string", "null"],
+ "description": "ACP semantic category, such as `model` or `thought_level`."
+ },
+ "description": {
+ "type": ["string", "null"],
+ "description": "Optional explanatory copy."
+ },
+ "id": {
+ "type": "string",
+ "description": "Opaque id used to change this setting."
+ },
+ "name": {
+ "type": "string",
+ "description": "Display label supplied by the agent."
+ }
+ }
+ }
+ ],
+ "description": "One agent-advertised ACP session setting."
+ },
+ "AgentConfigSelectOptionDto": {
+ "type": "object",
+ "description": "One value in an agent-advertised select.",
+ "required": ["value", "name"],
+ "properties": {
+ "description": {
+ "type": ["string", "null"],
+ "description": "Optional provider description of this value."
+ },
+ "group": {
+ "type": ["string", "null"],
+ "description": "Optional group heading supplied by the provider."
+ },
+ "name": {
+ "type": "string",
+ "description": "Display label."
+ },
+ "value": {
+ "type": "string",
+ "description": "Opaque value returned to the agent when selected."
+ }
+ }
+ },
"AgentModelDto": {
"type": "object",
"description": "One model picker option.",
@@ -2163,6 +2311,11 @@
"BotId": {
"type": "string"
},
+ "CapabilityHarnessDto": {
+ "type": "string",
+ "description": "Harness names accepted by the capability-discovery endpoint.",
+ "enum": ["in-memory", "cursor", "macrod"]
+ },
"CaptureAttemptDto": {
"type": "object",
"description": "The latest capture attempt.\n\nClients deserialize this, so both derives are used.",
@@ -2503,6 +2656,40 @@
}
}
},
+ "DiscoverAgentCapabilitiesRequest": {
+ "type": "object",
+ "description": "HTTP request selecting one provider to probe.",
+ "required": ["harness"],
+ "properties": {
+ "harness": {
+ "$ref": "#/components/schemas/CapabilityHarnessDto",
+ "description": "Provider to probe."
+ },
+ "harnessId": {
+ "type": ["string", "null"],
+ "format": "uuid",
+ "description": "Required for macrod and forbidden for other targets."
+ },
+ "model": {
+ "type": ["string", "null"],
+ "description": "Model whose session settings should be inspected."
+ }
+ }
+ },
+ "DiscoverAgentCapabilitiesResponse": {
+ "type": "object",
+ "description": "Successful capability-discovery response.",
+ "required": ["configOptions"],
+ "properties": {
+ "configOptions": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/AgentConfigOptionDto"
+ },
+ "description": "Complete ordered ACP session configuration advertised by the agent."
+ }
+ }
+ },
"DocumentId": {
"type": "string",
"description": "A validated document identifier. Historical document ids need not be UUIDs."
diff --git a/packages/sdk/src/coverage/skipped.ts b/packages/sdk/src/coverage/skipped.ts
index e65e0a38a7..3db74d973c 100644
--- a/packages/sdk/src/coverage/skipped.ts
+++ b/packages/sdk/src/coverage/skipped.ts
@@ -31,6 +31,7 @@ export const agentHarnessExcluded = [
'start',
'status',
'loadAgentModelsHandler',
+ 'discoverAgentCapabilitiesHandler',
'previewAgentSessions',
] as const satisfies readonly (keyof AgentHarnessSdk)[];
diff --git a/services/agent_harness_service/src/api.rs b/services/agent_harness_service/src/api.rs
index 91c3848c2c..6f9d3212a3 100644
--- a/services/agent_harness_service/src/api.rs
+++ b/services/agent_harness_service/src/api.rs
@@ -71,6 +71,7 @@ pub struct ApiStates<T, R, Opener, Bots, Requests, Access, Auth, Models, Changes
claude_auth: Router,
sharing: Router,
routine_sessions: Router,
+ capabilities: Router,
changes: AgentChangesRouterState<Changes, Access, Auth>,
}
@@ -97,10 +98,17 @@ impl<T, R, Opener, Bots, Requests, Access, Auth, Models, Changes>
claude_auth: Router::new(),
sharing: Router::new(),
routine_sessions: Router::new(),
+ capabilities: Router::new(),
changes,
}
}
+ /// Attach model-specific harness capability discovery routes.
+ pub fn with_capabilities(mut self, router: Router) -> Self {
+ self.capabilities = router;
+ self
+ }
+
/// Attach the optional owner-authenticated Claude demo connection routes.
pub fn with_claude_auth(mut self, router: Router) -> Self {
self.claude_auth = router;
@@ -217,6 +225,7 @@ where
.merge(agent_repositories_router(states.repositories))
.merge(states.claude_auth)
.merge(states.routine_sessions)
+ .merge(states.capabilities)
.nest("/runtime", runtime_gateway_router(states.gateway))
}
diff --git a/services/agent_harness_service/src/api/swagger.rs b/services/agent_harness_service/src/api/swagger.rs
index 956e860727..542d1cdaf9 100644
--- a/services/agent_harness_service/src/api/swagger.rs
+++ b/services/agent_harness_service/src/api/swagger.rs
@@ -5,6 +5,7 @@ use agent_changes::inbound::axum_router::{
CaptureAttemptDto, CaptureOutcomeDto, ChangedFileDto, ChangesetDto, ChangesetSourceDto,
FileChangeKindDto, GitRefDto,
};
+use agent_harness::inbound::capability_discovery;
use agent_harness::inbound::model_load::{
self, AgentModelDto, AgentModelsStatusDto, LoadAgentModelsRequest, LoadAgentModelsResponse,
ModelHarnessDto,
@@ -68,6 +69,7 @@ impl Modify for SecurityAddon {
axum_router::get_agent_sandbox_size_handler,
axum_router::put_agent_sandbox_size_handler,
model_load::load_agent_models_handler,
+ capability_discovery::discover_agent_capabilities_handler,
repositories::list_agent_repositories_handler,
repositories::list_agent_repository_branches_handler,
changes_router::get_agent_session_changes_handler,
diff --git a/services/agent_harness_service/src/main.rs b/services/agent_harness_service/src/main.rs
index e7790710d7..a251da0e6f 100644
--- a/services/agent_harness_service/src/main.rs
+++ b/services/agent_harness_service/src/main.rs
@@ -988,6 +988,23 @@ async fn run() -> anyhow::Result<()> {
.with_harness_authorizer(PgHarnessAuthorizer::new(PgHarnessAuthorizationRepo::new(
pool.clone(),
)));
+ let capabilities = agent_harness::inbound::capability_discovery::agent_capabilities_router(
+ agent_harness::inbound::capability_discovery::AgentCapabilitiesRouterState::new(
+ Arc::new(
+ agent_harness::domain::capability_discovery::AgentCapabilitiesServiceImpl::new(
+ VisibleHarnessAccess::new(PgHarnessRepo::new(pool.clone())),
+ InMemoryModels::new(
+ Some(Arc::clone(&inmem_model_engine)),
+ config.inmem_model.clone(),
+ ),
+ CursorModels::new(cursor_keys.clone(), cursor_api_base_url()),
+ macrod_models.clone(),
+ model_probe_timeout,
+ ),
+ ),
+ MacroAuthorizationState::new(Arc::new(authorization_service.clone())),
+ ),
+ );
let model_service = Arc::new(
AgentModelsServiceImpl::new(
VisibleHarnessAccess::new(PgHarnessRepo::new(pool.clone())),
@@ -1092,7 +1109,8 @@ async fn run() -> anyhow::Result<()> {
)
.with_claude_auth(claude_auth)
.with_sharing(sharing)
- .with_routine_sessions(routine_sessions),
+ .with_routine_sessions(routine_sessions)
+ .with_capabilities(capabilities),
http_runtime_commands_readiness,
http_port,
shutdown_signal(),
diff --git a/services/agent_harness_service/src/model_providers/cursor.rs b/services/agent_harness_service/src/model_providers/cursor.rs
index 12fb5de152..be05137ec8 100644
--- a/services/agent_harness_service/src/model_providers/cursor.rs
+++ b/services/agent_harness_service/src/model_providers/cursor.rs
@@ -1,5 +1,6 @@
//! Cursor model discovery adapter.
+use agent_harness::domain::capability_discovery::{CapabilityProbeError, RawCapabilityProbe};
use agent_harness::domain::model_load::{CursorModelProbe, ModelProbeError, RawModelProbe};
use agent_harness::outbound::cursor::CursorApiKeys;
use cursor_cloud_agents::api::{ApiKey, CursorClient, CursorConfig};
@@ -56,3 +57,52 @@ where
)))
}
}
+
+impl<Keys: CursorApiKeys> agent_harness::domain::capability_discovery::CapabilityProbe
+ for CursorModels<Keys>
+{
+ type Target = MacroUserIdStr<'static>;
+ async fn probe(
+ &self,
+ caller: &Self::Target,
+ model: Option<&str>,
+ ) -> Result<RawCapabilityProbe, CapabilityProbeError> {
+ let config = self
+ .keys
+ .resolve(caller)
+ .await
+ .map_err(|error| CapabilityProbeError::Failed(error.to_string()))?;
+ let client = CursorClient::new(CursorConfig {
+ api_key: ApiKey::new(config.key.expose()),
+ base_url: self.base_url.clone(),
+ model: None,
+ starting_ref: "main".to_owned(),
+ record_dir: None,
+ })
+ .map_err(|error| CapabilityProbeError::Failed(error.to_string()))?;
+ let models = client
+ .list_models()
+ .await
+ .map_err(|error| CapabilityProbeError::Failed(error.to_string()))?;
+ let selected = model.or(config.default_model_id.as_deref());
+ let current = match selected {
+ Some(id) => Some(
+ models
+ .iter()
+ .find(|model| model.id == id)
+ .ok_or_else(|| CapabilityProbeError::Failed("unsupported model".to_owned()))?
+ .default_choice(),
+ ),
+ None => models
+ .iter()
+ .find(|model| model.id == "default")
+ .map(|model| model.default_choice()),
+ };
+ Ok(RawCapabilityProbe::Options(
+ cursor_cloud_agents::domain::model_options::cursor_session_config_options(
+ &models,
+ current.as_ref(),
+ ),
+ ))
+ }
+}
diff --git a/services/agent_harness_service/src/model_providers/cursor/test.rs b/services/agent_harness_service/src/model_providers/cursor/test.rs
index ef1a567623..afa7ea36e3 100644
--- a/services/agent_harness_service/src/model_providers/cursor/test.rs
+++ b/services/agent_harness_service/src/model_providers/cursor/test.rs
@@ -37,7 +37,11 @@ async fn cursor_api(
Json(serde_json::json!({
"items": [
{"id": "default", "displayName": "Auto", "variants": []},
- {"id": "fast", "displayName": "Fast", "variants": []}
+ {"id": "fast", "displayName": "Fast", "variants": []},
+ {"id": "thoughtful", "displayName": "Thoughtful", "variants": [
+ {"params": [{"id": "effort", "value": "low"}], "isDefault": true},
+ {"params": [{"id": "effort", "value": "ultra"}], "isDefault": false}
+ ]}
]
}))
}
@@ -68,3 +72,33 @@ async fn probe_lists_models_without_creating_an_agent() {
);
server.abort();
}
+
+#[tokio::test]
+async fn capabilities_use_the_selected_model_instead_of_the_account_default() {
+ use agent_harness::domain::capability_discovery::{CapabilityProbe, RawCapabilityProbe};
+ let calls = Arc::new(Mutex::new(Vec::new()));
+ let app = Router::new()
+ .fallback(any(cursor_api))
+ .with_state(Arc::clone(&calls));
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let address = listener.local_addr().unwrap();
+ let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
+ let provider = CursorModels::new(TestCursorKeys, format!("http://{address}"));
+ let caller = MacroUserIdStr::try_from_email("[email protected]").unwrap();
+ let RawCapabilityProbe::Options(options) =
+ CapabilityProbe::probe(&provider, &caller, Some("thoughtful"))
+ .await
+ .unwrap()
+ else {
+ panic!("options");
+ };
+ let options = serde_json::to_value(options).unwrap();
+ assert_eq!(options[0]["currentValue"], "thoughtful");
+ assert_eq!(options[1]["currentValue"], "low");
+ assert_eq!(options[1]["options"][1]["value"], "ultra");
+ assert_eq!(
+ calls.lock().unwrap().as_slice(),
+ &[("GET".to_owned(), "/v1/models".to_owned())]
+ );
+ server.abort();
+}
diff --git a/services/agent_harness_service/src/model_providers/in_memory.rs b/services/agent_harness_service/src/model_providers/in_memory.rs
index 6c306f9e99..aedd031818 100644
--- a/services/agent_harness_service/src/model_providers/in_memory.rs
+++ b/services/agent_harness_service/src/model_providers/in_memory.rs
@@ -1,5 +1,6 @@
//! In-memory model discovery adapter.
+use agent_harness::domain::capability_discovery::{CapabilityProbeError, RawCapabilityProbe};
use std::sync::Arc;
use agent_harness::domain::model_load::{InMemoryModelProbe, ModelProbeError, RawModelProbe};
@@ -31,3 +32,26 @@ impl InMemoryModelProbe for InMemoryModels {
))
}
}
+
+impl agent_harness::domain::capability_discovery::CapabilityProbe for InMemoryModels {
+ type Target = ();
+ async fn probe(
+ &self,
+ _: &(),
+ model: Option<&str>,
+ ) -> Result<RawCapabilityProbe, CapabilityProbeError> {
+ let Some(engine) = &self.engine else {
+ return Ok(RawCapabilityProbe::Unsupported);
+ };
+ let current = model.unwrap_or(&self.current);
+ if !engine.supported_models().contains(&current) {
+ return Err(CapabilityProbeError::Failed("unsupported model".to_owned()));
+ }
+ Ok(RawCapabilityProbe::Options(
+ agent_inmem::domain::model_options::model_config_options(
+ current,
+ engine.supported_models(),
+ ),
+ ))
+ }
+}
diff --git a/services/agent_harness_service/src/model_providers/macrod.rs b/services/agent_harness_service/src/model_providers/macrod.rs
index 60dca1d1a5..ccc0322349 100644
--- a/services/agent_harness_service/src/model_providers/macrod.rs
+++ b/services/agent_harness_service/src/model_providers/macrod.rs
@@ -1,6 +1,8 @@
//! Model discovery over the existing Redis runtime bus.
+use agent_harness::domain::capability_discovery::{CapabilityProbeError, RawCapabilityProbe};
use std::sync::Arc;
+
use std::time::Duration;
use agent_harness::domain::model_load::{MacrodModelProbe, ModelProbeError, RawModelProbe};
@@ -122,3 +124,23 @@ impl MacrodModelProbe for MacrodModels {
}
}
}
+
+impl agent_harness::domain::capability_discovery::CapabilityProbe for MacrodModels {
+ type Target = HarnessId;
+ async fn probe(
+ &self,
+ harness: &HarnessId,
+ model: Option<&str>,
+ ) -> Result<RawCapabilityProbe, CapabilityProbeError> {
+ // Model-specific discovery requires a live session for external ACP runtimes.
+ if model.is_some() {
+ return Ok(RawCapabilityProbe::Unsupported);
+ }
+ match MacrodModelProbe::probe(self, *harness).await {
+ Ok(RawModelProbe::Options(options)) => Ok(RawCapabilityProbe::Options(options)),
+ Ok(RawModelProbe::Unsupported) => Ok(RawCapabilityProbe::Unsupported),
+ Err(ModelProbeError::Disconnected) => Err(CapabilityProbeError::Disconnected),
+ Err(error) => Err(CapabilityProbeError::Failed(error.to_string())),
+ }
+ }
+}