@revoengine/cli 1.0.20 → 1.0.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -301,7 +301,7 @@ revo plan --json
301
301
  revo deploy --yes --json
302
302
  ```
303
303
 
304
- Repository `plan` and `deploy` reports separate resource operations from lock bookkeeping across all ten resource families. An existing resource whose managed definition matches the repository is `operation: "noop"`, including when its baseline is absent or stale. Per-item `baselineAction` is `"adopt"` for a missing baseline, `"refresh"` for a stale baseline, or `"none"`. It describes separate bookkeeping for converged resources; create/update operations still save their verified baselines through the existing deployment flow. Use `revo plan --hints` to see this diagnostic in terminal output.
304
+ Repository `plan` and `deploy` reports separate resource operations from lock bookkeeping across all twelve resource families. An existing resource whose managed definition matches the repository is `operation: "noop"`, including when its baseline is absent or stale. Per-item `baselineAction` is `"adopt"` for a missing baseline, `"refresh"` for a stale baseline, or `"none"`. It describes separate bookkeeping for converged resources; create/update operations still save their verified baselines through the existing deployment flow. Use `revo plan --hints` to see this diagnostic in terminal output.
305
305
 
306
306
  The JSON extension retains schema version 2, raw family `status`/`counts`, and `operations.adopt`. Repository summaries count converged resources as `operations.noop`; CI consumers should use item `operation` or aggregate `operations` rather than raw family status to identify resource changes. Validation failures, owner/role changes, and activation exclusions still take precedence over content equality. Dedicated resource commands and named `migrate` keep their existing contract.
307
307
 
@@ -394,16 +394,18 @@ Full pull, deployment, and migration use this fixed dependency order:
394
394
  | 2 | `database-view` | `database-views` | `DatabaseViews/` | STRUCTURED and RAW_SQL views, including materialized views; target schemas must be ready first. |
395
395
  | 3 | `component` | `component` | `Components/` | Portable code, libraries, and elements. Libraries are deployed before executable components. |
396
396
  | 4 | `service-account` | `service-accounts` | `ServiceAccounts/` | Owner identities are resolved before dependent Groups and Job Templates; secrets are target-local. |
397
- | 5 | `job-template` | `job-templates` | `JobTemplates/` | Resolves Component and Service Account dependencies by Stable Key. Pull skips WIP templates without a Stable Key or with an unkeyed Component and reports each skip. |
398
- | 6 | `endpoint` | `endpoints` | `Endpoints/` | Resolves Component dependencies and route ordering. |
399
- | 7 | `schedule` | `schedules` | `Schedules/` | Targets Job Templates or Materialized Views. New schedules are inactive by default. |
400
- | 8 | `event` | `events` | `Events/` | Supports Job Template event targets. Manifests retain `custom: true/false` alongside `type`; new events are inactive by default. |
401
- | 9 | `group` | `groups` | `Groups/` | Group owners use Stable Keys; Service Account owners resolve early; human users and memberships remain target-local. |
402
- | 10 | `role-group` | `role-groups` | `RoleGroups/` | Role assignments run last; members and user identifiers remain target-local. |
397
+ | 5 | `agent-plugin` | `agent-plugins` | `AgentPlugins/` | Tools, MCP servers, skills and packages; dependencies precede consumers and authentication remains target-local. |
398
+ | 6 | `agent` | `agents` | `Agents/` | Portable config/policy and execution identity; memory and runtime state remain target-local. |
399
+ | 7 | `job-template` | `job-templates` | `JobTemplates/` | Resolves Component and Service Account dependencies by Stable Key. Pull skips WIP templates without a Stable Key or with an unkeyed Component and reports each skip. |
400
+ | 8 | `endpoint` | `endpoints` | `Endpoints/` | Resolves Component dependencies and route ordering. |
401
+ | 9 | `schedule` | `schedules` | `Schedules/` | Targets Job Templates or Materialized Views. New schedules are inactive by default. |
402
+ | 10 | `event` | `events` | `Events/` | Supports Job Template event targets. Manifests retain `custom: true/false` alongside `type`; new events are inactive by default. |
403
+ | 11 | `group` | `groups` | `Groups/` | Group owners use Stable Keys; Service Account owners resolve early; human users and memberships remain target-local. |
404
+ | 12 | `role-group` | `role-groups` | `RoleGroups/` | Role assignments run last; members and user identifiers remain target-local. |
403
405
 
404
406
  Active Materialized View refresh Schedules are reported in Database View plans but do not block push, repository deployment, or named migration. Updating a view preserves Schedule activation; API write failures and readback verification failures are still reported.
405
407
 
406
- `--resources all` selects all ten families. Singular, plural, and common compact aliases are accepted where the command parser documents them, but the selectors above are the canonical values.
408
+ `--resources all` selects all twelve families. Singular, plural, and common compact aliases are accepted where the command parser documents them, but the selectors above are the canonical values.
407
409
 
408
410
  Existing `database-schema` selectors and `revo database-schemas` commands remain accepted as compatibility aliases. New table manifests use `DatabaseTables/**/database-table.json`; older `DatabaseSchemas/**/database-schema.json` files remain readable and are relocated by the next successful table pull. A locally edited manifest still needs `--force` before pull replaces it. The manifest `kind` and `databaseSchemas` lock and plan keys retain their existing schema names for format compatibility.
409
411
 
@@ -597,3 +599,26 @@ Both Endpoints and Job Templates accept `mode: "INHERIT"`, `"CALLER"` or `"SERVI
597
599
  Job Template manifests retain the legacy `executionPrincipal` reference for existing definitions, including `{ "kind": "system" }`. Use either this field or `executionPolicy`, never both. Writing an explicit policy clears the legacy `triggerUser` alias. Definitions without either field retain target-local execution configuration. An explicit policy pointing to a human or an unkeyed ordinary account cannot be exported as a portable definition.
598
600
 
599
601
  Selecting System or another instance administrator execution account approves the current instance Component and library code. Later source changes require administrator approval; ordinary editors cannot replace approved code silently. Authority selection preserves the caller in the audit trail.
602
+
603
+ ### Agents and Agent Plugins
604
+
605
+ Agents and registry plugins participate in the same repository pull/plan/deploy and named migration flow as Service Accounts. Enable the families explicitly, or use `all`:
606
+
607
+ ```bash
608
+ revo project update --resources component,service-account,group,agent-plugin,agent
609
+ revo metadata plan --project source --resources agent-plugin,agent
610
+ revo metadata apply --project source --resources agent-plugin,agent --yes
611
+ revo pull --project source --resources component,service-account,group,agent-plugin,agent --yes
612
+ revo plan --project target --json
613
+ revo deploy --project target --yes
614
+ ```
615
+
616
+ Manifests live under `Agents/<name>-<key-suffix>/agent.json` and `AgentPlugins/<name>-<key-suffix>/agent-plugin.json` in the configured workspace. The shared lock stores portable hashes and per-instance baselines. Dedicated `revo agents` and `revo agent-plugins` commands support `pull`, `plan`, and `push` with `--all`, `--project`, `--json`, and `--force`; push requires `--yes` or interactive confirmation. Dedicated plan also supports `--strict`.
617
+
618
+ Plugin definitions cover `tools`, `mcp_server`, `skill`, and `package`, including routing, governance, schemas, toolsets, Markdown content and content token budgets. Read-only marketplace package metadata is excluded from portable manifests. Component references use `componentStableKey`; skill/package dependencies use `pluginStableKeys`. Agent config/policy attachments use `pluginStableKeys`, eager attachments use `eagerPluginStableKeys`, and `executionPrincipal` resolves a Service Account or the built-in System account. Portable Group and Service Account owners are resolved on the target; human ownership remains target-local. Plugins are deployed in dependency order before Agents. Missing/duplicate keys, unmanaged name/slug collisions, cycles and invalid references block writes even with force.
619
+
620
+ Agent `config.memory`, workspace files, conversations, runs, terminal selection, automation recipients, rollout state, avatars and MCP secrets/Vault UUIDs are instance-local. Export omits them; updates preserve target settings, including memory checkpoints, while replacing managed configuration. New Agents use the API's ordinary creation defaults and are not run by deployment. Configure their target execution permissions and automation separately. Tenant default plugin attachments are not synchronized; inherited eager attachments become explicit portable Agent attachments.
621
+
622
+ MCP URLs must use public HTTPS without embedded credentials, query or fragment. New authenticated MCP plugins (including inline plugins) require manual target-local authentication setup and the matching Stable Key before deployment. CLI preserves existing target MCP authentication; it neither provisions secrets nor invokes MCP test/sync or an external provider. Unauthenticated MCP definitions can be created normally. Legacy numeric Component revision pins require a portable `componentDigest` before export; Vault-bound tool inputs and instance-specific rollout snapshots are rejected rather than copied.
623
+
624
+ Agent and Agent Plugin synchronization is upsert-only. Repository prune blocks deletion of either family; retained Agents and inline/registry plugin references also protect Components, Groups and Service Accounts from unsafe pruning. Existing Service Account synchronization remains unchanged, including target-local credentials and membership policy.
package/dist/src/cli.js CHANGED
@@ -3,7 +3,7 @@ import { pathToFileURL } from 'node:url';
3
3
  import { RevoClient } from "./client.js";
4
4
  import { readComponentLock } from "./component-lock.js";
5
5
  import { getActiveEnvironmentName } from "./config.js";
6
- import { handleAuthCommand, handleComponentCommand, handleDatabaseTablesCommand, handleDatabaseViewsCommand, handleDeployCommand, handleDiffCommand, handleEndpointsCommand, handleEnvCommand, handleEventsCommand, handleGroupsCommand, handleInfoCommand, handleJobTemplatesCommand, handleMetadataCommand, handleMigrateCommand, handlePlanCommand, handlePullCommand, handleProjectCommand, handleRequestCommand, handleRoleGroupsCommand, handleServiceAccountsCommand, handleSearchCommand, handleSchedulesCommand, handleTerminalCommand, } from "./commands/index.js";
6
+ import { handleAgentsCommand, handleAuthCommand, handleComponentCommand, handleDatabaseTablesCommand, handleDatabaseViewsCommand, handleDeployCommand, handleDiffCommand, handleEndpointsCommand, handleEnvCommand, handleEventsCommand, handleGroupsCommand, handleInfoCommand, handleJobTemplatesCommand, handleMetadataCommand, handleMigrateCommand, handlePlanCommand, handlePullCommand, handleProjectCommand, handleRequestCommand, handleRoleGroupsCommand, handleServiceAccountsCommand, handleSearchCommand, handleSchedulesCommand, handleTerminalCommand, } from "./commands/index.js";
7
7
  import { createHttpTraceSession, finalizeHttpTraceSession, withHttpTraceSession, } from "./http-trace.js";
8
8
  import { resolveProjectRoot } from "./project.js";
9
9
  import { withRequestQueue } from "./request-queue.js";
@@ -293,6 +293,10 @@ async function runMain(args, argv) {
293
293
  await handleRequestCommand(context);
294
294
  return;
295
295
  }
296
+ if (command === 'agents' || command === 'agent-plugins') {
297
+ await handleAgentsCommand(context);
298
+ return;
299
+ }
296
300
  if (command === 'service-accounts') {
297
301
  await handleServiceAccountsCommand(context);
298
302
  return;
@@ -1,6 +1,6 @@
1
1
  import type { RuntimeExecutionPolicy } from './types.ts';
2
2
  import { RequestQueue } from './request-queue.ts';
3
- import type { ComponentRecord, DatabaseSchemaRecord, DatabaseViewRecord, EndpointRecord, EventRecord, GroupRecord, JobTemplateRecord, RoleGroupRecord, ServiceAccountRecord, ScheduleRecord } from './types.ts';
3
+ import type { AgentRecord, AgentPluginRecord, ComponentRecord, DatabaseSchemaRecord, DatabaseViewRecord, EndpointRecord, EventRecord, GroupRecord, JobTemplateRecord, RoleGroupRecord, ServiceAccountRecord, ScheduleRecord } from './types.ts';
4
4
  import type { TrackableResourceType } from './tracked-resources.ts';
5
5
  export type RequestOptions = {
6
6
  query?: Record<string, unknown>;
@@ -451,6 +451,19 @@ export declare class RevoClient {
451
451
  discoveredTotal: number | null;
452
452
  }>;
453
453
  getRoleGroup(roleGroupId: string, options?: Pick<RequestOptions, 'timeoutMs' | 'maxRetries'>): Promise<RoleGroupResponse>;
454
+ private listAgentDefinitions;
455
+ listAllAgents(): Promise<{
456
+ agents: AgentRecord[];
457
+ }>;
458
+ listAllAgentPlugins(): Promise<{
459
+ agentPlugins: AgentPluginRecord[];
460
+ }>;
461
+ getAgent(id: string): Promise<AgentRecord>;
462
+ getAgentPlugin(id: string): Promise<AgentPluginRecord>;
463
+ createAgent(body: Record<string, unknown>): Promise<AgentRecord>;
464
+ updateAgent(id: string, body: Record<string, unknown>): Promise<AgentRecord>;
465
+ createAgentPlugin(body: Record<string, unknown>): Promise<AgentPluginRecord>;
466
+ updateAgentPlugin(id: string, body: Record<string, unknown>): Promise<AgentPluginRecord>;
454
467
  listGroups(options?: GroupListRequest): Promise<unknown>;
455
468
  listAllGroups(): Promise<{
456
469
  groups: GroupRecord[];
@@ -1180,6 +1180,7 @@ export class RevoClient {
1180
1180
  async deleteWorkspaceResource(resource, id) {
1181
1181
  const encoded = encodeURIComponent(id);
1182
1182
  const single = {
1183
+ agent: `/api/v1/agents/${encoded}`,
1183
1184
  component: `/api/v1/component/${encoded}`,
1184
1185
  'database-table': `/api/v1/databases/${encoded}`,
1185
1186
  group: `/api/v1/groups/${encoded}`,
@@ -1187,6 +1188,7 @@ export class RevoClient {
1187
1188
  'service-account': `/api/v1/accounts/${encoded}`,
1188
1189
  };
1189
1190
  const bulk = {
1191
+ 'agent-plugin': '/api/v1/agent/plugins/delete',
1190
1192
  'job-template': '/api/v1/automation/template/delete',
1191
1193
  schedule: '/api/v1/automation/schedule/delete',
1192
1194
  event: '/api/v1/automation/event/delete',
@@ -1310,6 +1312,48 @@ export class RevoClient {
1310
1312
  async getRoleGroup(roleGroupId, options = {}) {
1311
1313
  return this.requestData('GET', `/api/v1/role-groups/${roleGroupId}`, options);
1312
1314
  }
1315
+ async listAgentDefinitions(resourcePath) {
1316
+ const records = [];
1317
+ const seenIds = new Set();
1318
+ for (let skip = 0;;) {
1319
+ const raw = await this.requestData('GET', resourcePath, {
1320
+ query: { take: COMPONENT_LIST_PAGE_SIZE, skip, count: true, sort: resourcePath === '/api/v1/agents' ? 'agentId' : 'agentPluginId', ...ACTIVE_COMPONENT_LIST_FILTER },
1321
+ });
1322
+ if (!Array.isArray(raw) && !(isRecord(raw) && ['data', 'items', 'results'].some(key => Array.isArray(raw[key]))))
1323
+ throw new Error('Invalid agent definition inventory.');
1324
+ const page = unwrapListPage(raw);
1325
+ if (page.total !== null && (!Number.isInteger(page.total) || page.total < 0))
1326
+ throw new Error('Invalid agent inventory count.');
1327
+ for (const item of page.items) {
1328
+ if (!isRecord(item))
1329
+ throw new Error('Invalid agent definition record.');
1330
+ const id = String(item.agentId || item.agentPluginId || '');
1331
+ if (!id || seenIds.has(id))
1332
+ throw new Error('Agent definition pagination returned a missing or duplicate identity.');
1333
+ seenIds.add(id);
1334
+ records.push(item);
1335
+ }
1336
+ skip += page.items.length;
1337
+ if (page.total !== null && skip >= page.total)
1338
+ break;
1339
+ if (!page.items.length) {
1340
+ if (page.total !== null && skip < page.total)
1341
+ throw new Error('Incomplete agent definition inventory.');
1342
+ break;
1343
+ }
1344
+ if (page.total === null && page.items.length < COMPONENT_LIST_PAGE_SIZE)
1345
+ break;
1346
+ }
1347
+ return records;
1348
+ }
1349
+ async listAllAgents() { return { agents: await this.listAgentDefinitions('/api/v1/agents') }; }
1350
+ async listAllAgentPlugins() { return { agentPlugins: await this.listAgentDefinitions('/api/v1/agent/plugins') }; }
1351
+ async getAgent(id) { return this.requestData('GET', `/api/v1/agents/${encodeURIComponent(id)}`); }
1352
+ async getAgentPlugin(id) { return this.requestData('GET', `/api/v1/agent/plugins/${encodeURIComponent(id)}`, { query: { includeDeleted: false } }); }
1353
+ async createAgent(body) { return this.requestData('POST', '/api/v1/agents', { body, maxRetries: 0 }); }
1354
+ async updateAgent(id, body) { return this.requestData('PATCH', `/api/v1/agents/${encodeURIComponent(id)}`, { body, maxRetries: 0 }); }
1355
+ async createAgentPlugin(body) { return this.requestData('POST', '/api/v1/agent/plugins', { body, maxRetries: 0 }); }
1356
+ async updateAgentPlugin(id, body) { return this.requestData('PATCH', `/api/v1/agent/plugins/${encodeURIComponent(id)}`, { body, maxRetries: 0 }); }
1313
1357
  async listGroups(options = {}) {
1314
1358
  return this.requestData('GET', options.path || '/api/v1/groups', {
1315
1359
  query: options.query,
@@ -0,0 +1,2 @@
1
+ import type { CommandContext } from '../types.ts';
2
+ export declare function handleAgentsCommand(context: CommandContext): Promise<void>;
@@ -0,0 +1,56 @@
1
+ import { resolveResourceTarget } from "../resource-target.js";
2
+ import { readProjectStableKeyName } from "../project.js";
3
+ import { buildAgentsPlan, pullAgentsToWorkspace, pushAgents } from "../resource-syncs/agent-sync.js";
4
+ import { isInteractiveTerminal, promptConfirm } from "../prompt.js";
5
+ import { printSyncPlan, printSyncStatus, printSyncSummary } from "../sync-output.js";
6
+ import { readBoolFlag } from "../utils.js";
7
+ export async function handleAgentsCommand(context) {
8
+ const family = context.args._[0] === 'agent-plugins' ? 'agent-plugin' : 'agent';
9
+ const command = context.args._[1];
10
+ if (!['pull', 'plan', 'push'].includes(command))
11
+ throw new Error(`Usage: revo ${context.args._[0]} <pull|plan|push> --all [--project <name>] [--json]`);
12
+ if (!readBoolFlag(context.args, ['all', 'a']))
13
+ throw new Error(`${family} ${command} requires --all.`);
14
+ if (readBoolFlag(context.args, ['prune']))
15
+ throw new Error('Agent and Agent Plugin sync is upsert-only; review deletion explicitly.');
16
+ const target = await resolveResourceTarget(context, { resource: family, allowDefaultProfile: true });
17
+ const input = { client: target.client, envName: target.envName, cwd: context.cwd, stableKeyName: readProjectStableKeyName(context.cwd), family };
18
+ const json = readBoolFlag(context.args, ['json']);
19
+ const force = readBoolFlag(context.args, ['force', 'f']);
20
+ const started = Date.now();
21
+ if (command === 'plan') {
22
+ const plan = await buildAgentsPlan(input);
23
+ if (json)
24
+ context.print(plan);
25
+ else
26
+ printSyncPlan(context.println, { title: family, environment: target.displayName, counts: plan.counts, items: plan.items, warnings: plan.exclusions, blockers: plan.blockers });
27
+ if (readBoolFlag(context.args, ['strict']) && (plan.blockers.length || plan.items.some(item => !['clean', 'orphan', 'skipped'].includes(item.status))))
28
+ throw new Error(`${family} plan is not clean.`);
29
+ return;
30
+ }
31
+ if (command === 'pull') {
32
+ const result = await pullAgentsToWorkspace({ ...input, force });
33
+ if (json)
34
+ context.print(result);
35
+ else {
36
+ for (const item of result.pulled)
37
+ printSyncStatus(context.println, { status: 'Pulled', direction: 'pull', targetPath: item.targetPath });
38
+ for (const item of result.skipped)
39
+ printSyncStatus(context.println, { status: 'Skipped', direction: 'pull', targetPath: item.name, reason: item.reason });
40
+ printSyncSummary(context.println, 'Pulled', [...result.pulled.map(item => ({ ...item, status: 'pulled' })), ...result.skipped.map(item => ({ ...item, status: 'skipped' }))], Date.now() - started);
41
+ }
42
+ return;
43
+ }
44
+ if (!readBoolFlag(context.args, ['yes', 'y']) && (!isInteractiveTerminal() || !await promptConfirm(`Push ${family} to "${target.displayName}"?`, false)))
45
+ throw new Error('Push requires confirmation. Use --yes or an interactive terminal.');
46
+ const result = await pushAgents({ ...input, force });
47
+ if (json)
48
+ context.print(result);
49
+ else {
50
+ for (const item of result.results)
51
+ printSyncStatus(context.println, { status: item.status === 'deployed' ? 'Deployed' : 'Failed', direction: 'push', targetPath: item.targetPath, reason: item.error });
52
+ printSyncSummary(context.println, 'Deployed', result.results, Date.now() - started);
53
+ }
54
+ if (result.results.some(item => item.status === 'failed'))
55
+ throw new Error(`${family} push failed; inspect results.`);
56
+ }
@@ -618,6 +618,8 @@ function migrateComponentLockIdentity(cwd, identity, localCatalog, remoteCatalog
618
618
  groups: lock.groups,
619
619
  roleGroups: lock.roleGroups,
620
620
  serviceAccounts: lock.serviceAccounts,
621
+ agents: lock.agents,
622
+ agentPlugins: lock.agentPlugins,
621
623
  jobTemplates: lock.jobTemplates,
622
624
  schedules: lock.schedules,
623
625
  events: lock.events,
@@ -17,3 +17,4 @@ export * from './role-groups.ts';
17
17
  export * from './search.ts';
18
18
  export * from './terminal.ts';
19
19
  export * from './schedules.ts';
20
+ export * from './agents.ts';
@@ -17,3 +17,4 @@ export * from "./role-groups.js";
17
17
  export * from "./search.js";
18
18
  export * from "./terminal.js";
19
19
  export * from "./schedules.js";
20
+ export * from "./agents.js";
@@ -35,6 +35,8 @@ const RESOURCE_ALIASES = {
35
35
  events: 'event',
36
36
  group: 'group',
37
37
  groups: 'group',
38
+ agent: 'agent', agents: 'agent',
39
+ 'agent-plugin': 'agent-plugin', 'agent-plugins': 'agent-plugin',
38
40
  'service-account': 'service-account',
39
41
  'service-accounts': 'service-account',
40
42
  'role-group': 'role-group',
@@ -47,6 +49,8 @@ const MIGRATION_RESOURCE_ORDER = [
47
49
  'database-view',
48
50
  'component',
49
51
  'service-account',
52
+ 'agent-plugin',
53
+ 'agent',
50
54
  'job-template',
51
55
  'endpoint',
52
56
  'schedule',
@@ -68,7 +72,7 @@ function readMigrationResources(context, commandLabel = 'Migration') {
68
72
  for (const value of values) {
69
73
  const resource = RESOURCE_ALIASES[value];
70
74
  if (!resource) {
71
- throw new Error(`${commandLabel} currently supports: database-table, database-view, component, job-template, endpoint, schedule, event, group, role-group, service-account, or all.`);
75
+ throw new Error(`${commandLabel} currently supports: database-table, database-view, component, job-template, endpoint, schedule, event, group, role-group, service-account, agent-plugin, agent, or all.`);
72
76
  }
73
77
  if (!resources.includes(resource)) {
74
78
  resources.push(resource);
@@ -202,6 +206,14 @@ function printMigrationPlan(context, plan) {
202
206
  blockers: phase.blockers,
203
207
  });
204
208
  }
209
+ if (phase.resource === 'agent' || phase.resource === 'agent-plugin') {
210
+ const familyPlan = phase.resource === 'agent' ? plan.agents : plan.agentPlugins;
211
+ if (familyPlan)
212
+ printSyncPlan(context.println, { title: `${phaseLabel} phase ${phase.order} / ${phase.resource}`, environment: plan.to,
213
+ counts: phase.operations, showHints: readBoolFlag(context.args, ['hints']),
214
+ items: familyPlan.items.map(item => ({ ...item, status: item.operation ?? item.status, hints: baselineHints(item) })),
215
+ warnings: phase.warnings, blockers: phase.blockers });
216
+ }
205
217
  if (phase.resource === 'service-account' && plan.serviceAccounts) {
206
218
  printSyncPlan(context.println, { title: `${phaseLabel} phase ${phase.order} / Service Account`, environment: plan.to,
207
219
  counts: phase.operations, showHints: readBoolFlag(context.args, ['hints']),
@@ -581,7 +593,7 @@ export async function handleMigrateCommand(context) {
581
593
  const dryRun = readBoolFlag(context.args, ['dry-run']);
582
594
  const subcommand = dryRun ? 'plan' : requestedSubcommand;
583
595
  if (requestedSubcommand !== 'plan' && requestedSubcommand !== 'run' && requestedSubcommand !== 'verify') {
584
- throw new Error('Unknown migrate command. Usage: revo migrate <plan|run|verify> --from <env> --to <env> [--resources database-table,database-view,component,job-template,endpoint,schedule,event,group,role-group,service-account] [--skip-groups] [--dry-run]');
596
+ throw new Error('Unknown migrate command. Usage: revo migrate <plan|run|verify> --from <env> --to <env> [--resources database-table,database-view,component,job-template,endpoint,schedule,event,group,role-group,service-account,agent-plugin,agent] [--skip-groups] [--dry-run]');
585
597
  }
586
598
  const input = readMigrationInput(context);
587
599
  const json = readBoolFlag(context.args, ['json']);
@@ -119,6 +119,8 @@ export type RevoLockFile = {
119
119
  groups: Record<string, GroupLockEntry>;
120
120
  roleGroups: Record<string, RoleGroupLockEntry>;
121
121
  serviceAccounts: Record<string, RoleGroupLockEntry>;
122
+ agents: Record<string, RoleGroupLockEntry>;
123
+ agentPlugins: Record<string, RoleGroupLockEntry>;
122
124
  jobTemplates: Record<string, JobTemplateLockEntry>;
123
125
  schedules: Record<string, ScheduleLockEntry>;
124
126
  events: Record<string, EventLockEntry>;
@@ -156,6 +156,8 @@ export function readComponentLock(projectRoot) {
156
156
  groups: {},
157
157
  roleGroups: {},
158
158
  serviceAccounts: {},
159
+ agents: {},
160
+ agentPlugins: {},
159
161
  jobTemplates: {},
160
162
  schedules: {},
161
163
  events: {},
@@ -229,6 +231,40 @@ export function readComponentLock(projectRoot) {
229
231
  syncedAt: String(baseline.syncedAt),
230
232
  }])),
231
233
  }])),
234
+ agents: Object.fromEntries(Object.entries(raw.agents && typeof raw.agents === 'object' ? raw.agents : {})
235
+ .filter(([, entry]) => (typeof entry.stableKey === 'string'
236
+ && typeof entry.path === 'string'
237
+ && typeof entry.sourceHash === 'string'
238
+ && entry.environments
239
+ && typeof entry.environments === 'object'))
240
+ .map(([key, entry]) => [key, {
241
+ stableKey: String(entry.stableKey),
242
+ path: String(entry.path),
243
+ sourceHash: String(entry.sourceHash),
244
+ environments: Object.fromEntries(Object.entries(entry.environments)
245
+ .filter(([, baseline]) => typeof baseline.remoteHash === 'string' && typeof baseline.syncedAt === 'string')
246
+ .map(([envName, baseline]) => [envName, {
247
+ remoteHash: String(baseline.remoteHash),
248
+ syncedAt: String(baseline.syncedAt),
249
+ }])),
250
+ }])),
251
+ agentPlugins: Object.fromEntries(Object.entries(raw.agentPlugins && typeof raw.agentPlugins === 'object' ? raw.agentPlugins : {})
252
+ .filter(([, entry]) => (typeof entry.stableKey === 'string'
253
+ && typeof entry.path === 'string'
254
+ && typeof entry.sourceHash === 'string'
255
+ && entry.environments
256
+ && typeof entry.environments === 'object'))
257
+ .map(([key, entry]) => [key, {
258
+ stableKey: String(entry.stableKey),
259
+ path: String(entry.path),
260
+ sourceHash: String(entry.sourceHash),
261
+ environments: Object.fromEntries(Object.entries(entry.environments)
262
+ .filter(([, baseline]) => typeof baseline.remoteHash === 'string' && typeof baseline.syncedAt === 'string')
263
+ .map(([envName, baseline]) => [envName, {
264
+ remoteHash: String(baseline.remoteHash),
265
+ syncedAt: String(baseline.syncedAt),
266
+ }])),
267
+ }])),
232
268
  serviceAccounts: Object.fromEntries(Object.entries(raw.serviceAccounts && typeof raw.serviceAccounts === 'object' ? raw.serviceAccounts : {})
233
269
  .filter(([, entry]) => (typeof entry.stableKey === 'string'
234
270
  && typeof entry.path === 'string'
@@ -399,6 +435,8 @@ export function writeComponentLock(projectRoot, lock) {
399
435
  components: sortedComponents,
400
436
  ...(Object.keys(sortedGroups).length > 0 ? { groups: sortedGroups } : {}),
401
437
  roleGroups: sortedRoleGroups,
438
+ ...(Object.keys(lock.agents || {}).length ? { agents: lock.agents } : {}),
439
+ ...(Object.keys(lock.agentPlugins || {}).length ? { agentPlugins: lock.agentPlugins } : {}),
402
440
  ...(Object.keys(lock.serviceAccounts || {}).length ? { serviceAccounts: lock.serviceAccounts } : {}),
403
441
  jobTemplates: sortedJobTemplates,
404
442
  ...(Object.keys(sortedSchedules).length > 0 ? { schedules: sortedSchedules } : {}),
@@ -582,6 +582,21 @@ export async function buildMetadataBackfillPlan(input) {
582
582
  });
583
583
  }
584
584
  }
585
+ for (const [family, method] of [['agent', 'listAllAgents'], ['agent-plugin', 'listAllAgentPlugins']]) {
586
+ if (!shouldTrackResource(trackedResources, family) || typeof client[method] !== 'function')
587
+ continue;
588
+ for await (const { resource } of readResourceInventory(client, family)) {
589
+ if (resource.deletedAt || resource.deletedBy)
590
+ continue;
591
+ const raw = rawConfiguredStableKey(resource, stableKeyName);
592
+ const invalid = raw.present && (typeof raw.value !== 'string' || !raw.value.trim());
593
+ const existing = readConfiguredResourceMetadataStableKey(resource, stableKeyName);
594
+ items.push({ resourceType: family, resourceId: resourceIdOf(resource), name: String(resource.name || ''), category: resource.category || null,
595
+ action: invalid ? 'blocked' : existing && !force ? 'skip' : 'update', metadataField: 'metadata', stableKeyName,
596
+ stableKey: existing && !force ? existing : buildNamedResourceGeneratedStableKey(resource),
597
+ reason: invalid ? 'Invalid Stable Key; refusing to overwrite.' : existing && !force ? 'stable key already exists' : 'assign-stable-key' });
598
+ }
599
+ }
585
600
  if (shouldTrackResource(trackedResources, 'job-template') && typeof client.listAllJobTemplates === 'function') {
586
601
  for await (const { listedId, resource: jobTemplate } of readResourceInventory(client, 'job-template')) {
587
602
  if (!listedId) {
@@ -747,7 +762,7 @@ export async function applyMetadataBackfillPlan(input) {
747
762
  const resourceTypes = new Set(plan.items.map((item) => item.resourceType));
748
763
  const readOrder = [
749
764
  'component', 'database-table', 'database-view', 'endpoint',
750
- 'role-group', 'service-account', 'group', 'job-template', 'schedule', 'event',
765
+ 'role-group', 'service-account', 'group', 'job-template', 'schedule', 'event', 'agent-plugin', 'agent',
751
766
  ];
752
767
  for (const resourceType of readOrder) {
753
768
  if (!resourceTypes.has(resourceType)) {
@@ -833,6 +848,29 @@ export async function applyMetadataBackfillPlan(input) {
833
848
  throw new Error(`Unsupported metadata plan action: ${item.action}.`);
834
849
  }
835
850
  try {
851
+ if (item.resourceType === 'agent' || item.resourceType === 'agent-plugin') {
852
+ const live = unwrapResource(item.resourceType === 'agent' ? await client.getAgent(item.resourceId) : await client.getAgentPlugin(item.resourceId));
853
+ if (live.deletedAt || live.deletedBy || !Number.isInteger(live.version))
854
+ throw new Error('Active target and current version are required.');
855
+ const raw = rawConfiguredStableKey(live, plan.stableKeyName);
856
+ if (raw.present && (typeof raw.value !== 'string' || !raw.value.trim()))
857
+ throw new Error('Invalid current Stable Key.');
858
+ const existing = readConfiguredResourceMetadataStableKey(live, plan.stableKeyName);
859
+ if (existing && !plan.force) {
860
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: existing, action: 'skip' });
861
+ continue;
862
+ }
863
+ const metadata = { ...sanitizeUserMetadata(live.metadata), [plan.stableKeyName]: item.stableKey };
864
+ if (item.resourceType === 'agent')
865
+ await client.updateAgent(item.resourceId, { metadata, version: live.version });
866
+ else
867
+ await client.updateAgentPlugin(item.resourceId, { metadata, version: live.version });
868
+ const verified = unwrapResource(item.resourceType === 'agent' ? await client.getAgent(item.resourceId) : await client.getAgentPlugin(item.resourceId));
869
+ if (readConfiguredResourceMetadataStableKey(verified, plan.stableKeyName) !== item.stableKey)
870
+ throw new Error('Agent metadata readback differs; write unverified.');
871
+ results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: item.stableKey, action: 'update' });
872
+ continue;
873
+ }
836
874
  if (item.resourceType === 'component') {
837
875
  const component = currentResources.get(`component:${item.resourceId}`);
838
876
  if (!component)
@@ -1,3 +1,4 @@
1
+ import { type AgentSyncPlan, type AgentSyncPull, type AgentSyncResult } from './resource-syncs/agent-sync.ts';
1
2
  import { type MigrationResourcePlan } from './migration-actions.ts';
2
3
  import { type WorkspacePrunePlan } from './workspace-prune.ts';
3
4
  import { type ServiceAccountsPlan, type ServiceAccountPullResult, type ServiceAccountPushResult } from './resource-syncs/service-account-sync.ts';
@@ -11,12 +12,12 @@ import { type GroupPullResult, type GroupPushResult, type GroupsPlan } from './r
11
12
  import { type JobTemplatePullResult, type JobTemplatePushResult, type JobTemplatesPlan } from './resource-syncs/job-template-sync.ts';
12
13
  import { type SchedulePullResult, type SchedulePushResult, type SchedulesPlan } from './resource-syncs/schedule-sync.ts';
13
14
  import { type RoleGroupPullResult, type RoleGroupPushResult, type RoleGroupsPlan } from './resource-syncs/role-group-sync.ts';
14
- export type MigrationResource = 'database-table' | 'database-view' | 'component' | 'job-template' | 'endpoint' | 'schedule' | 'event' | 'group' | 'role-group' | 'service-account';
15
+ export type MigrationResource = 'database-table' | 'database-view' | 'component' | 'job-template' | 'endpoint' | 'schedule' | 'event' | 'group' | 'role-group' | 'service-account' | 'agent-plugin' | 'agent';
15
16
  export type MigrationVerdict = 'ready' | 'ready-with-warnings' | 'blocked';
16
17
  export type MigrationOperations = Record<'noop' | 'create' | 'update' | 'adopt' | 'excluded' | 'blocked', number> & {
17
18
  delete?: number;
18
19
  };
19
- type MigrationPushResult = DatabaseSchemaPushResult | DatabaseViewPushResult | ComponentSyncResult | JobTemplatePushResult | EndpointPushResult | SchedulePushResult | EventPushResult | GroupPushResult | RoleGroupPushResult | ServiceAccountPushResult;
20
+ type MigrationPushResult = DatabaseSchemaPushResult | DatabaseViewPushResult | ComponentSyncResult | JobTemplatePushResult | EndpointPushResult | SchedulePushResult | EventPushResult | GroupPushResult | RoleGroupPushResult | ServiceAccountPushResult | AgentSyncResult;
20
21
  export type MigrationPhasePlan = {
21
22
  order: number;
22
23
  resource: MigrationResource;
@@ -69,6 +70,8 @@ export type MigrationPlan = {
69
70
  groups?: MigrationResourcePlan<GroupsPlan>;
70
71
  roleGroups?: MigrationResourcePlan<RoleGroupsPlan>;
71
72
  serviceAccounts?: MigrationResourcePlan<ServiceAccountsPlan>;
73
+ agentPlugins?: MigrationResourcePlan<AgentSyncPlan>;
74
+ agents?: MigrationResourcePlan<AgentSyncPlan>;
72
75
  warnings: string[];
73
76
  blockers: string[];
74
77
  };
@@ -93,6 +96,8 @@ export type MigrationRun = {
93
96
  groups?: GroupPullResult;
94
97
  roleGroups?: RoleGroupPullResult;
95
98
  serviceAccounts?: ServiceAccountPullResult;
99
+ agentPlugins?: AgentSyncPull;
100
+ agents?: AgentSyncPull;
96
101
  };
97
102
  plan: MigrationPlan;
98
103
  results: MigrationPushResult[];
@@ -132,6 +137,8 @@ export type ResourcePullResults = {
132
137
  groups?: GroupPullResult;
133
138
  roleGroups?: RoleGroupPullResult;
134
139
  serviceAccounts?: ServiceAccountPullResult;
140
+ agentPlugins?: AgentSyncPull;
141
+ agents?: AgentSyncPull;
135
142
  };
136
143
  export type ResourcePullInput = {
137
144
  cwd: string;