@nocobase/app-plugin-agents 0.1.0-beta.9 → 1.0.0-beta.16

package/dist/server/routes/admin.js

@@ -1,3 +1,4 @@
+import { involvesRun as involves, mayAccessRun } from '../core/runs/access.js';
 /**
  * The people-facing API, mounted at `/api/agents`: agents and their brief preview, variables, the skill library, runs,
  * usage and prices; runners and registration tokens are in `runners/admin.ts`. Every route is behind the guard the
@@ -29,20 +30,18 @@
 import { apiErrorResponse, apiErrorResponses, apiValidator, cliRoute, dataResponse, describeRoute, emptyResponse, listResponse, } from '@nocobase/app-server/router';
 import { bodyLimit } from 'hono/body-limit';
 import { z } from 'zod';
-import { policyAllowsAgent } from '@nocobase/agent-protocol';
 import { reaches, } from '../../shared/access.js';
-import { offersEntry } from '../../shared/models.js';
 import { SKILL_UPLOAD_MAX_BYTES } from '../../shared/skills.js';
 import { CONVERSATION_SUBJECT } from '../../shared/conversations.js';
-import { AgentInputSchema, AgentPatchSchema } from '../core/agents/index.js';
+import { AgentPatchSchema, agentViews } from '../core/agents/index.js';
 import { ModelPricesSchema } from '../core/reports/index.js';
-import { countActive, hasTool, onlineEntryOf, runForViewer, } from '../core/runs/index.js';
+import { runMachineViewerFor, runForViewer, } from '../core/runs/index.js';
 import { SkillIdsSchema, SkillImportSchema, SkillInputSchema, SkillSaveSchema, } from '../core/skills/index.js';
 import { forbidden, invalid, notFound } from '../kernel/errors.js';
 import { decodePageToken, domainRouter, encodePageToken, } from '../kernel/http.js';
 import { WORKDIR_TITLE } from '../kernel/scopes.js';
 import { tags } from './openapi.js';
-import { AgentActionOptionSchema, AgentChangeSchema, AgentHistoryQuery, AgentListQuery, AgentParams, AgentSchema, AgentSummarySchema, BriefPreviewSchema, ModelUsageReportSchema, PageTokenMetaSchema, PricesSchema, RunBriefSchema, RunDetailSchema, RunEventItemSchema, RunSchema, SeqPageMetaSchema, SkillArchiveQuery, SkillAttachmentsSchema, SkillDetailSchema, SkillFileQuery, SkillUploadSchema, SkillSchema, SkillVersionDetailSchema, SkillVersionSchema, SkillViewSchema, UsageReportSchema, UserRefSchema, VariableAuditSchema, VariableSchema, VariableValueSchema, VocabularySchema, AuditListQuery, ModelUsageQuery, PreviewBriefQuery, RunEventsQuery, RunListQuery, RunParams, ScopeParams, SkillParams, SkillRestoreInput, SkillVersionParams, UsageQuerySchema, VariableParams, VariableValueInput, WorkspaceParams, } from './schemas.js';
+import { AgentActionOptionSchema, AgentChangeSchema, AgentHistoryQuery, AgentParams, AgentNameSchema, AgentSchema, AgentViewSchema, BriefPreviewSchema, ModelUsageReportSchema, PageTokenMetaSchema, PricesSchema, RunBriefSchema, RunDetailSchema, RunEventItemSchema, RunSchema, SeqPageMetaSchema, SkillArchiveQuery, SkillAttachmentsSchema, SkillDetailSchema, SkillFileQuery, SkillUploadSchema, SkillSchema, SkillVersionDetailSchema, SkillVersionSchema, SkillViewSchema, UsageReportSchema, UserRefSchema, VariableAuditSchema, VariableSchema, VariableValueSchema, VocabularySchema, AuditListQuery, ModelUsageQuery, PreviewBriefQuery, RunEventsQuery, RunListQuery, RunParams, ScopeParams, SkillParams, SkillRestoreInput, SkillVersionParams, UsageQuerySchema, VariableParams, VariableValueInput, WorkspaceParams, } from './schemas.js';
 /** A multipart body of one file, as `file`. */
 const skillUploadBody = {
     required: true,
@@ -90,9 +89,6 @@ async function mayEdit(who, relatedTo) {
         return true;
     return reaches(await who.scope('agents.agents/edit'), relatedTo);
 }
-function involves(run, userId) {
-    return run.actorUserId === userId || run.ownerUserId === userId;
-}
 const RunPosition = z.object({ createdAt: z.string(), id: z.string() });
 const AuditPosition = z.object({ at: z.string(), id: z.string() });
 const ChangePosition = z.object({
@@ -115,13 +111,11 @@ export function createAdminRoutes(services, guard, scoped = guard) {
     const visibleRun = async (context, action) => {
         const who = caller(context);
         const run = await services.runs.get(context.req.param('runId') ?? '');
-        if (involves(run, who.userId))
+        if (await mayAccessRun(run, who.userId, isPrivate(run), () => who.can('agents.agents', action)))
             return run;
         // A private subject's runs (a conversation) belong to the people they involve, whatever the caller manages.
         if (isPrivate(run))
             throw notFound('Run');
-        if (await who.can('agents.agents', action))
-            return run;
         if (action === 'manage' && (await who.can('agents.agents', 'read')))
             throw forbidden('This needs agents.agents manage permission.');
         throw notFound('Run');
@@ -129,42 +123,6 @@ export function createAdminRoutes(services, guard, scoped = guard) {
     const isPrivate = (run) => services.subjects.get(run.subject.kind)?.private === true;
     const nameOf = async (userId) => (await services.people.names(services.tx.read(), [userId])).get(userId) ??
         userId;
-    /** The agents with what the list shows about their runs and runners, and whether the caller may change each. */
-    const summarize = async (who, agents) => {
-        const conn = services.tx.read();
-        const online = await services.runners.online(conn);
-        const owners = await services.people.names(conn, agents.map((agent) => agent.ownerUserId));
-        const catalog = await services.online.gateway.catalog();
-        const result = [];
-        for (const agent of agents)
-            result.push({
-                ...agent,
-                ownerName: owners.get(agent.ownerUserId) ?? null,
-                activeRuns: await countActive(conn, 'agentId', agent.id),
-                // An online agent runs here: "online" while the service of its first entry offers its model.
-                onlineRunners: agent.type === 'online'
-                    ? Number(offersEntry(catalog, onlineEntryOf(agent, undefined, catalog.defaultModel ?? null)))
-                    : online.filter((runner) => hasTool(runner, agent) &&
-                        policyAllowsAgent(runner.policy, agent) &&
-                        (agent.runnerIds.length === 0 ||
-                            agent.runnerIds.includes(runner.id))).length,
-                canEdit: await mayEdit(who, agent.ownerUserId),
-                owned: agent.ownerUserId === who.userId,
-                canCopy: services.agents.mayInvoke(agent, who.userId),
-            });
-        return result;
-    };
-    /** Only a caller who may change the agent of the path goes on: 404 when they may not read it, 403 when not change it. */
-    const editableAgent = async (context, next) => {
-        const who = caller(context);
-        const agent = await services.agents.get(context.req.param('agentId') ?? '');
-        if (!(await mayEdit(who, agent.ownerUserId))) {
-            if (!(await who.can('agents.agents', 'read')))
-                throw notFound('Agent');
-            throw forbidden('Only its owner (with the related level of agents.agents edit) or a manager of agents may change this agent.');
-        }
-        await next();
-    };
     /** Only a caller who may edit the skill of the path goes on: 404 when they may not read it, 403 when not edit it. */
     const editableSkill = async (context, next) => {
         const who = caller(context);
@@ -186,12 +144,20 @@ export function createAdminRoutes(services, guard, scoped = guard) {
         const allowed = services.scopes
             .keys()
             .filter((key) => withAgent || key !== 'agent');
+        const who = caller(context);
+        if (!withAgent && scope === 'global') {
+            if (scopeId !== 'default')
+                throw notFound('Scope');
+            const manage = await who.can('agents.agents', 'manage');
+            if (!manage && !(await who.can('agents.agents', 'read')))
+                throw notFound('Scope');
+            return { scope, scopeId, manage };
+        }
         if (!allowed.includes(scope) || !scopeId)
             throw notFound('Scope');
-        const who = caller(context);
         if (scope === 'agent') {
-            const agent = await services.agents.get(scopeId);
-            const manage = await mayEdit(who, agent.ownerUserId);
+            await services.agents.get(scopeId);
+            const manage = await who.can('agents.agents', 'manage');
             if (!manage && !(await who.can('agents.agents', 'read')))
                 throw notFound('Agent');
             return { scope: 'agent', scopeId, manage };
@@ -280,6 +246,64 @@ export function createAdminRoutes(services, guard, scoped = guard) {
         const data = await services.people.list(services.tx.read());
         return context.json({ data, meta: { total: data.length } });
     });
+    router.put('/discoveryPreferences', scoped, can('agents.agents', 'manage'), describeRoute({
+        tags,
+        summary: 'Ignore or restore discovery groups',
+        operationId: 'agentsSetDiscoveryPreferences',
+        ...cliRoute({ command: 'agent discovery set', bodyFile: 'input' }),
+        description: 'Shared administrator preferences. Only pending groups can be changed. Batches are atomic and checked against each group revision. Reports do not reset preferences.',
+        responses: {
+            200: listResponse(z.object({
+                key: z.string(),
+                ignored: z.boolean(),
+                revision: z.number().int(),
+            })),
+            400: apiErrorResponse(400, 'The group contains a non-pending agent.'),
+            409: apiErrorResponse(409, 'The discovery group changed.'),
+            ...apiErrorResponses,
+        },
+    }), apiValidator('json', z.strictObject({
+        groups: z
+            .array(z.strictObject({
+            key: z
+                .string()
+                .min(1)
+                .max(256)
+                .meta({ description: 'The discoveryKey from the agent list.' }),
+            expectedRevision: z.number().int().min(0).meta({
+                description: 'The discoveryRevision from the agent list.',
+            }),
+        }))
+            .min(1)
+            .max(256)
+            .refine((groups) => new Set(groups.map((group) => group.key)).size === groups.length, 'Groups must be unique.')
+            .meta({
+            description: 'Unique pending discovery groups to update atomically.',
+        }),
+        ignored: z.boolean().meta({
+            description: 'True to ignore pending discoveries; false to restore them without enabling.',
+        }),
+    })), async (context) => {
+        const { groups, ignored } = context.req.valid('json');
+        const data = await services.agents.setIgnored(groups, ignored);
+        return context.json({ data, meta: { total: data.length } });
+    });
+    // Every agent's name, removed ones and the application's own included, for the runs that name them.
+    router.get('/agentNames', guard, describeRoute({
+        tags,
+        summary: 'List the names of agents',
+        operationId: 'agentsListAgentNames',
+        // UI-only: the names runs show.
+        ...cliRoute(false),
+        description: 'Every agent there has been, removed ones and the application’s own included, by id and name: what the runs that name them show.',
+        responses: {
+            200: listResponse(AgentNameSchema),
+            ...apiErrorResponses,
+        },
+    }), async (context) => {
+        const data = await services.agents.directory(services.tx.read());
+        return context.json({ data, meta: { total: data.length } });
+    });
     // Variables of an agent, a working directory, or a scope the application registers.
     const scopedRouter = router;
     const variableParam = apiValidator('param', VariableParams);
@@ -469,8 +493,20 @@ export function createAdminRoutes(services, guard, scoped = guard) {
     /** The skill with whether the caller may edit it. */
     const viewOf = async (context, id) => {
         const skill = await services.skills.get(id);
+        const names = new Map();
+        for (const scope of new Set(skill.attachments.map((item) => item.scope))) {
+            const kind = services.scopes.get(scope);
+            if (kind?.describe)
+                names.set(scope, await kind.describe(skill.attachments
+                    .filter((item) => item.scope === scope)
+                    .map((item) => item.scopeId), caller(context).userId, caller(context).keyScope));
+        }
         return {
             ...skill,
+            attachments: skill.attachments.map((item) => ({
+                ...item,
+                ...names.get(item.scope)?.get(item.scopeId),
+            })),
             canEdit: await mayEdit(caller(context), skill.createdById),
         };
     };
@@ -483,7 +519,7 @@ export function createAdminRoutes(services, guard, scoped = guard) {
         operationId: 'agentsListSkills',
         ...cliRoute({
             command: 'skill list',
-            columns: ['id', 'name', 'version', 'agentCount', 'updatedAt'],
+            columns: ['id', 'name', 'version', 'updatedAt'],
         }),
         description: 'The skill library. Needs `agents.agents` read.',
         responses: { 200: listResponse(SkillSchema), ...apiErrorResponses },
@@ -815,15 +851,15 @@ export function createAdminRoutes(services, guard, scoped = guard) {
             flags: {
                 scopeKind: {
                     name: 'kind',
-                    description: 'The scope kind: `agent`, `workdir`, or one the application registers.',
+                    description: 'The scope kind: `global`, `workdir`, or one the application registers.',
                 },
                 scopeId: {
                     name: 'scope',
-                    description: 'The scope: an agent id, a working directory id, or the id the application gives.',
+                    description: 'The scope: `default` for global, a working directory id, or the id the application gives.',
                 },
             },
         }),
-        description: "The skills every run working in the scope gets (a working directory, or a scope the application registers; an agent's own skills are its `skillIds`).",
+        description: 'The skills every run gets: global default, then application scopes, then working directories; later scopes override the same slug. Global reads require agents.agents read or manage.',
         responses: {
             200: dataResponse(SkillAttachmentsSchema),
             404: noScope,
@@ -843,19 +879,21 @@ export function createAdminRoutes(services, guard, scoped = guard) {
             flags: {
                 scopeKind: {
                     name: 'kind',
-                    description: 'The scope kind: `agent`, `workdir`, or one the application registers.',
+                    description: 'The scope kind: `global`, `workdir`, or one the application registers.',
                 },
                 scopeId: {
                     name: 'scope',
-                    description: 'The scope: an agent id, a working directory id, or the id the application gives.',
+                    description: 'The scope: `default` for global, a working directory id, or the id the application gives.',
                 },
                 skillIds: { name: 'skills' },
             },
             examples: [
+                'skill attachment set global default --skills <skill>,<skill>',
+                'skill attachment set global default --file empty-skills.json',
                 'skill attachment set workdir <workdir> --skills <skill>,<skill>',
             ],
         }),
-        description: 'Makes `skillIds` the skills attached to the scope. Needs the right to change the scope.',
+        description: 'Makes `skillIds` the skills attached to the scope. Global accepts only default and requires agents.agents manage; other scopes need the right to change that scope. An empty skillIds array clears attachments. Agent attachments are refused.',
         responses: {
             200: dataResponse(SkillAttachmentsSchema),
             400: apiErrorResponse(400, 'A skill id is unknown (`INVALID_ARGUMENT`).'),
@@ -877,10 +915,11 @@ export function createAdminRoutes(services, guard, scoped = guard) {
         const see = manage ||
             (await who.can('agents.runners', 'read')) ||
             (await who.can('agents.agents', 'read'));
-        const uses = see &&
-            !manage &&
-            (await services.agents.list()).some((agent) => services.agents.mayInvoke(agent, who.userId));
-        return { userId: who.userId, seesMachines: manage || uses };
+        return runMachineViewerFor(services.agents, {
+            userId: who.userId,
+            manage,
+            read: see,
+        });
     };
     /** Only a caller who may see the run of the path (or, with `manage`, act on it) goes on. */
     const runAccess = (action) => async (context, next) => {
@@ -1181,65 +1220,28 @@ export function createAdminRoutes(services, guard, scoped = guard) {
     // Agents, last: `/:agentId` would otherwise shadow the fixed segments above.
     const agentParam = apiValidator('param', AgentParams);
     const noAgent = notFoundAs('The agent');
-    const editAccess = 'Its owner (at the related level of `agents.agents` edit) or a manager of agents may.';
-    router.get('/', scoped, can('agents.agents', 'read'), describeRoute({
+    router.get('/', guard, describeRoute({
         tags,
         summary: 'List agents',
         operationId: 'agentsListAgents',
         ...cliRoute({
             command: 'agent list-all',
-            flags: { includeArchived: { name: 'archived' } },
-            columns: [
-                'id',
-                'name',
-                'type',
-                'ownerName',
-                'activeRuns',
-                'archivedAt',
-            ],
-            examples: ['agent list-all --archived'],
+            columns: ['id', 'name', 'status', 'unusable', 'busy', 'description'],
+            examples: ['agent list-all', 'agent list-all --json'],
         }),
-        description: 'With what the list shows about their runs and runners, and whether the caller may change each. Needs `agents.agents` read.',
+        description: 'Every agent discovered from runners: one for each coding tool and model they report, with whether it is enabled, what it is good at, where it can run now (team and personal runners, the caller’s own among them), why it cannot take the caller’s work, and whether the caller may change it. Anyone signed in may read them; only a manager of agents (`agents.agents` manage) changes them.',
         responses: {
-            200: listResponse(AgentSummarySchema),
+            200: listResponse(AgentViewSchema),
             ...apiErrorResponses,
         },
-    }), apiValidator('query', AgentListQuery), async (context) => {
-        const data = await summarize(caller(context), await services.agents.list({
-            includeArchived: context.req.valid('query').includeArchived === true,
-        }));
+    }), async (context) => {
+        const who = caller(context);
+        const data = await services.views(services.tx.read(), who.userId, {
+            canEdit: await who.can('agents.agents', 'manage'),
+        });
         return context.json({ data, meta: { total: data.length } });
     });
-    router.post('/', scoped, can('agents.agents', 'manage'), describeRoute({
-        tags,
-        summary: 'Create an agent',
-        operationId: 'agentsCreateAgent',
-        ...cliRoute({
-            command: 'agent create',
-            bodyFile: 'file',
-            flags: {
-                instructions: { contentFile: true },
-                modelEntries: { name: 'models' },
-                ownerUserId: { name: 'owner' },
-                runnerIds: { name: 'runtimes' },
-                skillIds: { name: 'skills' },
-                userIds: { name: 'users' },
-            },
-            examples: [
-                'agent create --name Coder --models \'[{"tool":"claude"},{"tool":"codex","model":"gpt-5"}]\'',
-                'agent create --name PM --type online --models \'[{"modelService":"openai","model":"gpt-5"}]\'',
-                'agent create --file agent.json',
-            ],
-        }),
-        description: '`modelEntries` lists the tools and models it works with, in order (the first is its default): `{ tool, model? }` for a runner agent, `{ modelService, model }` for an online one. Needs `agents.agents` manage.',
-        responses: {
-            201: dataResponse(AgentSchema, 'Created.'),
-            ...apiErrorResponses,
-        },
-    }), apiValidator('json', AgentInputSchema), async (context) => context.json({
-        data: await services.agents.create(caller(context).userId, context.req.valid('json')),
-    }, 201));
-    router.get('/:agentId', scoped, can('agents.agents', 'read'), describeRoute({
+    router.get('/:agentId', guard, describeRoute({
         tags,
         summary: 'Get an agent',
         operationId: 'agentsGetAgent',
@@ -1248,17 +1250,22 @@ export function createAdminRoutes(services, guard, scoped = guard) {
             args: ['agentId'],
             flags: { agentId: { name: 'agent' } },
         }),
-        description: 'Needs `agents.agents` read.',
+        description: 'An agent as the Agent page shows it. An application’s own agent, such as a project manager, is answered too.',
         responses: {
-            200: dataResponse(AgentSummarySchema),
+            200: dataResponse(AgentViewSchema),
             404: noAgent,
             ...apiErrorResponses,
         },
     }), agentParam, async (context) => {
-        const [agent] = await summarize(caller(context), [
-            await services.agents.get(context.req.valid('param').agentId),
-        ]);
-        return context.json({ data: agent });
+        const who = caller(context);
+        const agent = await services.agents.get(context.req.valid('param').agentId);
+        const [data] = await agentViews(services.tx.read(), [agent], {
+            availability: services.availability,
+            userId: who.userId,
+            canEdit: await who.can('agents.agents', 'manage'),
+            now: services.clock.now(),
+        });
+        return context.json({ data });
     });
     router.get('/:agentId/history', guard, can('agents.agents', 'read'), describeRoute({
         tags,
@@ -1304,117 +1311,32 @@ export function createAdminRoutes(services, guard, scoped = guard) {
                 : {},
         });
     });
-    router.patch('/:agentId', scoped, editableAgent, describeRoute({
+    router.patch('/:agentId', scoped, can('agents.agents', 'manage'), describeRoute({
         tags,
         summary: 'Update an agent',
         operationId: 'agentsUpdateAgent',
         ...cliRoute({
             command: 'agent update',
             args: ['agentId'],
-            bodyFile: 'file',
             flags: {
                 agentId: { name: 'agent' },
-                instructions: { contentFile: true },
-                modelEntries: { name: 'models' },
-                ownerUserId: { name: 'owner' },
-                runnerIds: { name: 'runtimes' },
-                skillIds: { name: 'skills' },
-                userIds: { name: 'users' },
-                expectedRevision: { name: 'revision' },
+                description: { name: 'good-at', contentFile: true },
             },
             examples: [
-                'agent update <agent> --instructions-file notes.md --revision 4',
-                'agent update <agent> --models \'[{"tool":"codex"},{"tool":"claude","model":"opus"}]\' --revision 4',
+                'agent update <agent> --good-at "Code review" --enabled --expected-revision 2',
+                'agent update <agent> --no-enabled --expected-revision 3',
             ],
         }),
-        description: `Changes the fields given, against \`expectedRevision\`. ${editAccess} Only a manager of agents may give it to another owner, and an owner adds only business actions they hold themselves.`,
-        responses: {
-            200: dataResponse(AgentSchema),
-            404: noAgent,
-            409: revisionConflict('agent'),
-            ...apiErrorResponses,
-        },
-    }), agentParam, apiValidator('json', AgentPatchSchema), async (context) => {
-        const who = caller(context);
-        const agent = await services.agents.get(context.req.valid('param').agentId);
-        const patch = context.req.valid('json');
-        if (!(await who.can('agents.agents', 'manage'))) {
-            // Someone editing as the owner gives the agent only what they may grant themselves.
-            if (patch.ownerUserId !== undefined &&
-                patch.ownerUserId !== agent.ownerUserId)
-                throw forbidden('Only a manager of agents may give an agent to another owner.');
-            if (patch.actions !== undefined) {
-                const held = await services.gate.allowed({
-                    kind: 'user',
-                    userId: who.userId,
-                    displayName: who.userId,
-                });
-                const beyond = patch.actions.filter((action) => !agent.actions.includes(action) && !held.has(action));
-                if (beyond.length > 0)
-                    throw forbidden(`You may not give the agent business actions you do not hold yourself: ${beyond.join(', ')}.`);
-            }
-        }
-        return context.json({
-            data: await services.agents.update(agent.id, who.userId, patch),
-        });
-    });
-    router.delete('/:agentId', scoped, editableAgent, describeRoute({
-        tags,
-        summary: 'Delete an agent',
-        operationId: 'agentsDeleteAgent',
-        ...cliRoute({
-            command: 'agent delete',
-            args: ['agentId'],
-            flags: { agentId: { name: 'agent' } },
-            confirm: 'Delete this archived agent with its variables and history?',
-        }),
-        description: `Deletes an archived agent with no open runs, with its variables, skill attachments and history; its past runs stay. ${editAccess}`,
-        responses: {
-            204: emptyResponse(),
-            400: apiErrorResponse(400, 'The agent is not archived, or has open runs (`AGENT_NOT_ARCHIVED`, `AGENT_HAS_ACTIVE_RUNS`).'),
-            404: noAgent,
-            ...apiErrorResponses,
-        },
-    }), agentParam, async (context) => {
-        await services.agents.remove(context.req.valid('param').agentId, caller(context).userId);
-        return context.body(null, 204);
-    });
-    router.post('/:agentId/archive', scoped, editableAgent, describeRoute({
-        tags,
-        summary: 'Archive an agent',
-        operationId: 'agentsArchiveAgent',
-        ...cliRoute({
-            command: 'agent archive',
-            args: ['agentId'],
-            flags: { agentId: { name: 'agent' } },
-            confirm: 'Archive this agent? Its queued runs are withdrawn.',
-        }),
-        description: `An archived agent is not run: its queued runs are withdrawn. ${editAccess}`,
-        responses: {
-            200: dataResponse(AgentSchema),
-            404: noAgent,
-            ...apiErrorResponses,
-        },
-    }), agentParam, async (context) => context.json({
-        data: await services.agents.archive(context.req.valid('param').agentId, caller(context).userId),
-    }));
-    router.post('/:agentId/restore', scoped, editableAgent, describeRoute({
-        tags,
-        summary: 'Restore an archived agent',
-        operationId: 'agentsRestoreAgent',
-        ...cliRoute({
-            command: 'agent restore',
-            args: ['agentId'],
-            flags: { agentId: { name: 'agent' } },
-        }),
-        description: editAccess,
+        description: "Writes what an agent discovered from runners is good at, its default reasoning effort, and enables or disables it, against the revision the edit was made from. An agent is enabled only with a description. Disabling withdraws its queued runs. An application's own agent is changed through the application. Needs `agents.agents` manage.",
         responses: {
             200: dataResponse(AgentSchema),
+            400: apiErrorResponse(400, 'Enabling without a description (`GOOD_AT_REQUIRED`), an effort its tool does not take (`EFFORT_UNSUPPORTED`), or an application’s own agent (`AGENT_MANAGED`).'),
             404: noAgent,
+            409: apiErrorResponse(409, 'Someone changed the agent since the revision named (`REVISION_CONFLICT`, `metadata.revision`).'),
             ...apiErrorResponses,
         },
-    }), agentParam, async (context) => context.json({
-        data: await services.agents.restore(context.req.valid('param').agentId, caller(context).userId),
+    }), agentParam, apiValidator('json', AgentPatchSchema), async (context) => context.json({
+        data: await services.agents.update(context.req.valid('param').agentId, caller(context).userId, context.req.valid('json')),
     }));
     router.get('/:agentId/previewBrief', guard, can('agents.agents', 'read'), describeRoute({
         tags,