feat: external Agent Profile foundations (#203, phase 1)

apps/server/src/app.ts

@@ -30,6 +30,8 @@ import {
 } from './modules/agent/acp/index.js';
 import { buildLegacyCommandProfiles } from './modules/agent/acp/legacy-profile-migration.js';
 import { listProfiles as listLegacyAcpProfiles } from './modules/agent/acp/profile-store.js';
+import { initializeAgentDefaults } from './modules/agent/agent-defaults.js';
+import agentDefaultsRoutes from './modules/agent/agent-defaults.route.js';
 import agentRoutes from './modules/agent/agent.route.js';
 import agentChangeReviewConfigRoutes from './modules/agent/change-review-config.route.js';
 import llmRoutes from './modules/agent/llm.route.js';
@@ -321,10 +323,13 @@ const agentletGateway = mountAgenetes(app, {
 });
 let unregisterHarnessDiscovery: (() => void) | undefined;
 app.addHook('onReady', async () => {
+  const registry = getAgentProfileRegistry();
+  if (registry) initializeAgentDefaults(registry.listProfiles());
   unregisterHarnessDiscovery = registerHarnessProfileDiscovery({
     gateway: agentletGateway,
     getRegistry: getAgentProfileRegistry,
     log: app.log,
+    onProfilesDiscovered: initializeAgentDefaults,
   });
 });
 app.addHook('preClose', async () => unregisterHarnessDiscovery?.());
@@ -353,6 +358,7 @@ app.addHook('onListen', async () => {
 // (M3). See modules/agent/acp/profile-cache-port.ts.
 installAcpProfileCachePort();
 app.register(acpProfilesRoutes, { prefix: '/api/acp' });
+app.register(agentDefaultsRoutes, { prefix: '/api/agent/defaults' });
 app.register(acpAgentletRoutes, { prefix: '/api/acp' });
 app.register(acpAgentCliRoutes, { prefix: '/api/acp' });
 app.register(acpThreadsRoutes, { prefix: '/api/acp' });

apps/server/src/modules/agent/acp/agent-cli.route.test.ts

@@ -9,6 +9,13 @@ import { markBasicAuthenticated } from '../../security/owner.js';
 
 import type { FastifyInstance } from 'fastify';
 
+const mocks = vi.hoisted(() => ({ getProfile: vi.fn(), discover: vi.fn() }));
+vi.mock('@agenetes/agentlet-host', () => ({
+  getAgentProfileRegistry: () => ({ getProfile: mocks.getProfile }),
+  getSupervisedAgentletId: () => 'supervised',
+  getAgentletGateway: () => ({ discoverHarnesses: mocks.discover }),
+}));
+
 let app: FastifyInstance | undefined;
 
 afterEach(async () => {
@@ -106,4 +113,46 @@ describe('ACP agent CLI route', () => {
     expect(response.json().code).toBe('harness_discovery_unavailable');
     expect(response.json()).not.toHaveProperty('agents');
   });
+
+  it('queries the edited Profile machine and projects Custom for older catalogues', async () => {
+    mocks.getProfile.mockReturnValue({ agentletId: 'remote-machine' });
+    mocks.discover.mockResolvedValue({ harnesses: [] });
+    app = Fastify({ logger: false });
+    await app.register(createAcpAgentCliRoutes(), { prefix: '/api/acp' });
+    const response = await app.inject(
+      '/api/acp/agent-cli?profileId=remote-profile',
+    );
+    expect(response.statusCode).toBe(200);
+    expect(mocks.discover).toHaveBeenCalledWith('remote-machine', {
+      prepareWorkspaces: false,
+    });
+    expect(response.json().agents).toEqual([
+      expect.objectContaining({
+        id: 'custom',
+        capabilities: {
+          customLaunchCommand: 'supported',
+          autoApprove: 'unsupported',
+          modelOverride: 'unsupported',
+          sessionPersistence: 'unsupported',
+        },
+      }),
+    ]);
+  });
+
+  it('rejects invalid query fields and missing Profiles without detection', async () => {
+    const detect = vi.fn(async () => []);
+    mocks.getProfile.mockReturnValue(undefined);
+    app = Fastify({ logger: false });
+    await app.register(createAcpAgentCliRoutes(detect), { prefix: '/api/acp' });
+    expect((await app.inject('/api/acp/agent-cli?profileId=')).statusCode).toBe(
+      400,
+    );
+    expect(
+      (await app.inject('/api/acp/agent-cli?unexpected=value')).statusCode,
+    ).toBe(400);
+    expect(
+      (await app.inject('/api/acp/agent-cli?profileId=missing')).statusCode,
+    ).toBe(404);
+    expect(detect).not.toHaveBeenCalled();
+  });
 });

apps/server/src/modules/agent/acp/agent-cli.route.ts

@@ -18,7 +18,14 @@
 import {
   getAgentletGateway,
   getSupervisedAgentletId,
+  getAgentProfileRegistry,
 } from '@agenetes/agentlet-host';
+import {
+  CUSTOM_COMMAND_CAPABILITIES,
+  CUSTOM_COMMAND_WRAPPER_ID,
+} from '@agentlet/protocol';
+
+import { acpAgentCliQuerySchema } from '@huabu/shared';
 
 import { isOwnerRequest } from '../../security/owner.js';
 
@@ -29,13 +36,34 @@ import type {
 } from '@huabu/shared';
 import type { FastifyPluginAsync } from 'fastify';
 
-async function detectAgentClis(): Promise<AcpAgentCliInfo[]> {
+async function detectAgentClis(profileId?: string): Promise<AcpAgentCliInfo[]> {
   const gateway = getAgentletGateway();
   if (!gateway) throw new Error('Agentlet Gateway is not ready');
-  const result = await gateway.discoverHarnesses(getSupervisedAgentletId(), {
-    prepareWorkspaces: false,
-  });
-  return result.harnesses;
+  const profile = profileId
+    ? getAgentProfileRegistry()?.getProfile(profileId)
+    : undefined;
+  if (profileId && !profile) throw new Error('Agent Profile is unavailable');
+  const result = await gateway.discoverHarnesses(
+    profile?.agentletId ?? getSupervisedAgentletId(),
+    {
+      prepareWorkspaces: false,
+    },
+  );
+  if (result.harnesses.some((entry) => entry.id === CUSTOM_COMMAND_WRAPPER_ID))
+    return result.harnesses;
+  return [
+    ...result.harnesses,
+    {
+      id: CUSTOM_COMMAND_WRAPPER_ID,
+      displayName: 'Custom command',
+      binary: CUSTOM_COMMAND_WRAPPER_ID,
+      acpArgs: [],
+      autoApprove: null,
+      installed: false,
+      installHint: '',
+      capabilities: CUSTOM_COMMAND_CAPABILITIES,
+    },
+  ];
 }
 
 export function createAcpAgentCliRoutes(
@@ -51,8 +79,24 @@ export function createAcpAgentCliRoutes(
               'Forbidden: agent CLI detection requires owner authorization',
           });
         }
+        const parsed = acpAgentCliQuerySchema.safeParse(request.query);
+        if (!parsed.success) {
+          return reply.status(400).send({
+            code: 'validation_failed',
+            message: 'Invalid harness catalogue query',
+          });
+        }
         try {
-          return { agents: await detect() };
+          if (
+            parsed.data.profileId &&
+            !getAgentProfileRegistry()?.getProfile(parsed.data.profileId)
+          ) {
+            return reply.status(404).send({
+              code: 'profile_not_found',
+              message: 'Agent Profile is unavailable',
+            });
+          }
+          return { agents: await detect(parsed.data.profileId) };
         } catch (error) {
           request.log.warn(
             { err: error },

apps/server/src/modules/agent/acp/external-agent-realization.test.ts

@@ -154,6 +154,7 @@ function createHarness(options?: {
         truncated: false,
       },
     });
+  const subscribeProfileCache = vi.fn();
   const service = new ExternalAgentRealizationService({
     resolveAgentNode: vi
       .fn()
@@ -167,7 +168,7 @@ function createHarness(options?: {
     readRecord: vi.fn(() => durableRecord),
     createHandle,
     buildSpec,
-    subscribeProfileCache: vi.fn(),
+    subscribeProfileCache,
     subscribeTitles,
     ensureSession,
     ...(options?.bindingCoordinator
@@ -184,6 +185,7 @@ function createHarness(options?: {
     createHandle,
     subscribeTitles,
     buildSpec,
+    subscribeProfileCache,
     collectSpacePrompt,
     ensureSession,
     promote,
@@ -464,6 +466,7 @@ describe('ExternalAgentRealizationService', () => {
       workloadType: 'Deployment',
       spec: {
         binding: { alias: 'Fixed Agent', profileId: 'profile-fixed' },
+        profileExecutionRevision: 3,
         agentletId: 'agentlet-1',
         cwd: '/fixed/work',
         recipe: null,
@@ -491,6 +494,11 @@ describe('ExternalAgentRealizationService', () => {
     });
 
     expect(realized.spec).toBe(persisted);
+    expect(harness.subscribeProfileCache).toHaveBeenCalledWith(
+      'thread-1',
+      'profile-fixed',
+      3,
+    );
     expect(harness.buildSpec).not.toHaveBeenCalled();
     expect(harness.collectSpacePrompt).not.toHaveBeenCalled();
     expect(harness.subscribeTitles).toHaveBeenCalledWith(

apps/server/src/modules/agent/acp/external-agent-realization.ts

@@ -128,6 +128,7 @@ async function ensureSessionFromCanonicalSpec(
     threadId: spec.threadId,
     binding: spec.spec.binding,
     namespace: spec.namespace,
+    profileExecutionRevision: spec.spec.profileExecutionRevision ?? 0,
     ...(spec.spec.cwd !== undefined && { cwd: spec.spec.cwd }),
     ...(spec.spec.recipe !== undefined && { recipe: spec.spec.recipe }),
     ...(env !== undefined && { env }),
@@ -298,6 +299,7 @@ export class ExternalAgentRealizationService {
       this.dependencies.subscribeProfileCache(
         options.threadId,
         binding.profileId,
+        spec.spec.profileExecutionRevision ?? 0,
       );
       this.dependencies.subscribeTitles?.(
         options.canvasId ?? '',
@@ -390,6 +392,7 @@ export class ExternalAgentRealizationService {
     this.dependencies.subscribeProfileCache(
       options.threadId,
       binding.profileId,
+      spec.spec.profileExecutionRevision ?? 0,
     );
     this.dependencies.subscribeTitles?.(
       options.canvasId ?? '',