@revoengine/cli 1.0.19 → 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.
Files changed (37) hide show
  1. package/README.md +60 -9
  2. package/dist/src/cli.js +5 -1
  3. package/dist/src/client.d.ts +20 -3
  4. package/dist/src/client.js +45 -1
  5. package/dist/src/commands/agents.d.ts +2 -0
  6. package/dist/src/commands/agents.js +56 -0
  7. package/dist/src/commands/component.js +2 -0
  8. package/dist/src/commands/index.d.ts +1 -0
  9. package/dist/src/commands/index.js +1 -0
  10. package/dist/src/commands/migrate.js +14 -2
  11. package/dist/src/component-lock.d.ts +5 -0
  12. package/dist/src/component-lock.js +45 -5
  13. package/dist/src/metadata-backfill.js +48 -1
  14. package/dist/src/migration.d.ts +9 -2
  15. package/dist/src/migration.js +60 -0
  16. package/dist/src/resource-inventory.d.ts +4 -2
  17. package/dist/src/resource-inventory.js +11 -1
  18. package/dist/src/resource-syncs/account-principal.d.ts +19 -1
  19. package/dist/src/resource-syncs/account-principal.js +94 -4
  20. package/dist/src/resource-syncs/agent-sync.d.ts +98 -0
  21. package/dist/src/resource-syncs/agent-sync.js +586 -0
  22. package/dist/src/resource-syncs/endpoint-sync.d.ts +3 -0
  23. package/dist/src/resource-syncs/endpoint-sync.js +27 -1
  24. package/dist/src/resource-syncs/group-sync.d.ts +4 -1
  25. package/dist/src/resource-syncs/group-sync.js +32 -17
  26. package/dist/src/resource-syncs/identity-migration.d.ts +1 -1
  27. package/dist/src/resource-syncs/identity-migration.js +20 -1
  28. package/dist/src/resource-syncs/job-template-sync.d.ts +2 -1
  29. package/dist/src/resource-syncs/job-template-sync.js +38 -32
  30. package/dist/src/resource-syncs/service-account-sync.js +16 -9
  31. package/dist/src/tracked-resources.d.ts +1 -1
  32. package/dist/src/tracked-resources.js +4 -2
  33. package/dist/src/types.d.ts +22 -0
  34. package/dist/src/ui.js +5 -1
  35. package/dist/src/workspace-diff.js +2 -0
  36. package/dist/src/workspace-prune.js +44 -3
  37. package/package.json +2 -2
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # @revoengine/cli
2
2
 
3
+ Development and GitLab CI use Node.js 24.21.0. Run `nvm use` in this repository to select the checked-in `.nvmrc`.
4
+
3
5
  Official command-line interface for moving RevoEngine configuration between an instance, a Git repository, and another instance.
4
6
 
5
7
  The CLI has three main capabilities:
@@ -299,7 +301,7 @@ revo plan --json
299
301
  revo deploy --yes --json
300
302
  ```
301
303
 
302
- 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.
303
305
 
304
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.
305
307
 
@@ -392,16 +394,18 @@ Full pull, deployment, and migration use this fixed dependency order:
392
394
  | 2 | `database-view` | `database-views` | `DatabaseViews/` | STRUCTURED and RAW_SQL views, including materialized views; target schemas must be ready first. |
393
395
  | 3 | `component` | `component` | `Components/` | Portable code, libraries, and elements. Libraries are deployed before executable components. |
394
396
  | 4 | `service-account` | `service-accounts` | `ServiceAccounts/` | Owner identities are resolved before dependent Groups and Job Templates; secrets are target-local. |
395
- | 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. |
396
- | 6 | `endpoint` | `endpoints` | `Endpoints/` | Resolves Component dependencies and route ordering. |
397
- | 7 | `schedule` | `schedules` | `Schedules/` | Targets Job Templates or Materialized Views. New schedules are inactive by default. |
398
- | 8 | `event` | `events` | `Events/` | Supports Job Template event targets. Manifests retain `custom: true/false` alongside `type`; new events are inactive by default. |
399
- | 9 | `group` | `groups` | `Groups/` | Group owners use Stable Keys; Service Account owners resolve early; human users and memberships remain target-local. |
400
- | 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. |
401
405
 
402
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.
403
407
 
404
- `--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.
405
409
 
406
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.
407
411
 
@@ -562,8 +566,9 @@ The same family is included in `revo pull --all`, repository `diff`/`plan`/`depl
562
566
  Select it alone with `--resources service-account`. Named profiles (`--project`/`--env`), URL/token environment variables,
563
567
  and the ordinary authenticated runtime work through the existing config resolution. `--force` retains the existing drift policy.
564
568
 
565
- The portable manifest contains the Stable Key, name, and a single Group or Service Account management principal. The manifest field `owner` remains the portable dependency policy; Platform 1.6.4 writes it as a restricted management `access` ACL, with target UUIDs and no legacy `ownerId`/`ownerType` fields.
569
+ The portable manifest contains the Stable Key, name, and a single Group, Service Account or built-in System management principal. The manifest field `owner` remains the portable dependency policy; Platform 1.6.4 writes it as a restricted management `access` ACL, with target UUIDs and no legacy `ownerId`/`ownerType` fields.
566
570
  Group USER owners and Job Template `triggerUser` references to Service Accounts are resolved to target `userId` at write time.
571
+ Use `owner: { "type": "system" }` for a Group or Service Account managed by the physical built-in System account. The CLI reads the target account with UUID `00000000-0000-0000-0000-000000000000` and verifies `serviceAccount: true` and active state before any dependent write; an unmigrated instance is blocked. System itself is never exported as a managed account, assigned a Stable Key, updated or pruned. An ordinary account named System remains managed through its own Stable Key.
567
572
  Human principals are reported for manual configuration; an account with a human owner needs a target account with the exact Stable Key before it can be adopted.
568
573
  A missing or circular owner dependency blocks writes. Groups and accounts are created in dependency order before their consumers.
569
574
 
@@ -571,3 +576,49 @@ API keys and secrets cannot be exported. Every newly created Service Account is
571
576
  The push result contains `credentials: { stableKey, environment, policy: "target-local", status: "configure-manually" }`.
572
577
  Existing target secrets remain local and are never compared, copied, rotated, or exposed in manifests, plans, lock files, or HTTP trace.
573
578
  Execution memberships, unrestricted or multiple-principal management ACLs, other account metadata, and `metadataAdvanced` remain target-local. Existing self access is preserved when a portable management principal changes; name/metadata updates omit the ACL. Complex target ACLs cannot be replaced through the single-principal manifest, including with `--force`.
579
+
580
+
581
+ ## Runtime execution policies
582
+
583
+ Endpoint `execution` still identifies its Component. The separate optional `executionPolicy` selects runtime authority and, for Endpoints, the account exposed through `api.currentUser`:
584
+
585
+ ```json
586
+ {
587
+ "executionPolicy": {
588
+ "mode": "SERVICE_ACCOUNT",
589
+ "serviceAccount": { "kind": "system" },
590
+ "currentUser": "CALLER"
591
+ }
592
+ }
593
+ ```
594
+
595
+ A normal Service Account uses `serviceAccount: { "kind": "service-account", "stableKey": "Ops/Robot#abc12345" }`. The target account must be active and have platform access. Plans include accounts created earlier in a multi-resource migration; writes resolve fresh target IDs and account state. The manifest and lock contain portable references, never source account UUIDs.
596
+
597
+ Both Endpoints and Job Templates accept `mode: "INHERIT"`, `"CALLER"` or `"SERVICE_ACCOUNT"`. Non-Service Account modes omit `serviceAccount`. Endpoint `currentUser` independently accepts `"INHERIT"`, `"CALLER"` or `"EXECUTION_ACCOUNT"`. Job Templates expose the executor through `api.currentUser` and record the initiator separately; unattended jobs require a Service Account. Set instance defaults in **Settings > Endpoints**. Instance settings are target-local and are not copied by resource migration.
598
+
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.
600
+
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,5 +1,6 @@
1
+ import type { RuntimeExecutionPolicy } from './types.ts';
1
2
  import { RequestQueue } from './request-queue.ts';
2
- 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';
3
4
  import type { TrackableResourceType } from './tracked-resources.ts';
4
5
  export type RequestOptions = {
5
6
  query?: Record<string, unknown>;
@@ -123,6 +124,7 @@ export type DatabaseViewUpdatePayload = {
123
124
  });
124
125
  export type EndpointListRequest = ComponentListRequest;
125
126
  export type EndpointWritePayload = {
127
+ executionPolicy?: RuntimeExecutionPolicy;
126
128
  version: number;
127
129
  metadata: Record<string, unknown>;
128
130
  name?: string;
@@ -241,7 +243,8 @@ export type ScheduleCreatePayload = {
241
243
  targetConfig?: Record<string, unknown> | null;
242
244
  };
243
245
  export type JobTemplateUpdatePayload = {
244
- triggerUser?: string;
246
+ executionPolicy?: RuntimeExecutionPolicy;
247
+ triggerUser?: string | null;
245
248
  version: number;
246
249
  name?: string;
247
250
  category?: string | null;
@@ -253,7 +256,8 @@ export type JobTemplateUpdatePayload = {
253
256
  inputs?: unknown;
254
257
  };
255
258
  export type JobTemplateCreatePayload = {
256
- triggerUser?: string;
259
+ executionPolicy?: RuntimeExecutionPolicy;
260
+ triggerUser?: string | null;
257
261
  name: string;
258
262
  category?: string | null;
259
263
  desc?: string;
@@ -447,6 +451,19 @@ export declare class RevoClient {
447
451
  discoveredTotal: number | null;
448
452
  }>;
449
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>;
450
467
  listGroups(options?: GroupListRequest): Promise<unknown>;
451
468
  listAllGroups(): Promise<{
452
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',
@@ -1208,7 +1210,7 @@ export class RevoClient {
1208
1210
  throw new Error('Invalid account response.');
1209
1211
  }
1210
1212
  const record = {};
1211
- for (const field of ['userId', 'name', 'serviceAccount', 'ownerId', 'ownerType', 'access', 'memberships', 'version', 'deletedAt']) {
1213
+ for (const field of ['userId', 'name', 'serviceAccount', 'ownerId', 'ownerType', 'access', 'memberships', 'version', 'deletedAt', 'deletedBy', 'status', 'platformAccess']) {
1212
1214
  if (wrapper[field] !== undefined) {
1213
1215
  Object.assign(record, { [field]: wrapper[field] });
1214
1216
  }
@@ -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']);
@@ -47,6 +47,9 @@ export type GroupOwnerPolicy = {
47
47
  } | {
48
48
  type: 'service-account';
49
49
  stableKey: string;
50
+ } | {
51
+ type: 'system';
52
+ stableKey?: never;
50
53
  } | {
51
54
  type: 'manual-user';
52
55
  } | {
@@ -116,6 +119,8 @@ export type RevoLockFile = {
116
119
  groups: Record<string, GroupLockEntry>;
117
120
  roleGroups: Record<string, RoleGroupLockEntry>;
118
121
  serviceAccounts: Record<string, RoleGroupLockEntry>;
122
+ agents: Record<string, RoleGroupLockEntry>;
123
+ agentPlugins: Record<string, RoleGroupLockEntry>;
119
124
  jobTemplates: Record<string, JobTemplateLockEntry>;
120
125
  schedules: Record<string, ScheduleLockEntry>;
121
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: {},
@@ -215,11 +217,47 @@ export function readComponentLock(projectRoot) {
215
217
  sourceHash: String(entry.sourceHash),
216
218
  ...((isRecord(entry.owner) && (entry.owner.type === 'group' || entry.owner.type === 'service-account') && typeof entry.owner.stableKey === 'string')
217
219
  ? { owner: { type: entry.owner.type, stableKey: entry.owner.stableKey } }
218
- : (isRecord(entry.owner) && entry.owner.type === 'manual-user')
219
- ? { owner: { type: 'manual-user' } }
220
- : (isRecord(entry.owner) && entry.owner.type === 'unresolved' && typeof entry.owner.reason === 'string')
221
- ? { owner: { type: 'unresolved', reason: entry.owner.reason } }
222
- : {}),
220
+ : (isRecord(entry.owner) && entry.owner.type === 'system')
221
+ ? { owner: { type: 'system' } }
222
+ : (isRecord(entry.owner) && entry.owner.type === 'manual-user')
223
+ ? { owner: { type: 'manual-user' } }
224
+ : (isRecord(entry.owner) && entry.owner.type === 'unresolved' && typeof entry.owner.reason === 'string')
225
+ ? { owner: { type: 'unresolved', reason: entry.owner.reason } }
226
+ : {}),
227
+ environments: Object.fromEntries(Object.entries(entry.environments)
228
+ .filter(([, baseline]) => typeof baseline.remoteHash === 'string' && typeof baseline.syncedAt === 'string')
229
+ .map(([envName, baseline]) => [envName, {
230
+ remoteHash: String(baseline.remoteHash),
231
+ syncedAt: String(baseline.syncedAt),
232
+ }])),
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),
223
261
  environments: Object.fromEntries(Object.entries(entry.environments)
224
262
  .filter(([, baseline]) => typeof baseline.remoteHash === 'string' && typeof baseline.syncedAt === 'string')
225
263
  .map(([envName, baseline]) => [envName, {
@@ -397,6 +435,8 @@ export function writeComponentLock(projectRoot, lock) {
397
435
  components: sortedComponents,
398
436
  ...(Object.keys(sortedGroups).length > 0 ? { groups: sortedGroups } : {}),
399
437
  roleGroups: sortedRoleGroups,
438
+ ...(Object.keys(lock.agents || {}).length ? { agents: lock.agents } : {}),
439
+ ...(Object.keys(lock.agentPlugins || {}).length ? { agentPlugins: lock.agentPlugins } : {}),
400
440
  ...(Object.keys(lock.serviceAccounts || {}).length ? { serviceAccounts: lock.serviceAccounts } : {}),
401
441
  jobTemplates: sortedJobTemplates,
402
442
  ...(Object.keys(sortedSchedules).length > 0 ? { schedules: sortedSchedules } : {}),
@@ -1,6 +1,7 @@
1
1
  import { randomBytes } from 'node:crypto';
2
2
  import { readResourceInventory, resourceIdOf, unwrapResource, } from "./resource-inventory.js";
3
3
  import { isDatabaseBackupArtifact } from "./database-table-artifacts.js";
4
+ import { isBuiltinSystemAccount } from "./resource-syncs/account-principal.js";
4
5
  import { buildStableKey, buildResourceIdentityStableKeyValue, normalizeStableKeyValue, readConfiguredResourceMetadataStableKey, sanitizeUserMetadata, } from "./resource-metadata.js";
5
6
  import { shouldTrackResource } from "./tracked-resources.js";
6
7
  function isRecord(value) {
@@ -160,6 +161,8 @@ function endpointExclusionReason(endpoint) {
160
161
  return endpoint.deletedAt || endpoint.deletedBy ? 'deleted endpoint is excluded' : null;
161
162
  }
162
163
  function buildMetadataUpdatePayload(resource, stableKeyName, stableKey, resourceType) {
164
+ if (isBuiltinSystemAccount(resource))
165
+ throw new Error('The built-in System account cannot be managed by metadata backfill.');
163
166
  if (!Number.isInteger(resource.version)) {
164
167
  throw new Error(`${resourceType} version is required to update metadata`);
165
168
  }
@@ -487,6 +490,10 @@ export async function buildMetadataBackfillPlan(input) {
487
490
  }
488
491
  if (shouldTrackResource(trackedResources, 'service-account') && typeof client.listAllServiceAccounts === 'function') {
489
492
  for await (const { listedId, resource: account } of readResourceInventory(client, 'service-account')) {
493
+ if (isBuiltinSystemAccount(account)) {
494
+ items.push({ resourceType: 'service-account', resourceId: resourceIdOf(account) || listedId, name: String(account.name || 'System'), category: null, action: 'skip', metadataField: 'metadata', stableKeyName, reason: 'built-in System account is managed by the platform' });
495
+ continue;
496
+ }
490
497
  if (!listedId) {
491
498
  continue;
492
499
  }
@@ -575,6 +582,21 @@ export async function buildMetadataBackfillPlan(input) {
575
582
  });
576
583
  }
577
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
+ }
578
600
  if (shouldTrackResource(trackedResources, 'job-template') && typeof client.listAllJobTemplates === 'function') {
579
601
  for await (const { listedId, resource: jobTemplate } of readResourceInventory(client, 'job-template')) {
580
602
  if (!listedId) {
@@ -740,7 +762,7 @@ export async function applyMetadataBackfillPlan(input) {
740
762
  const resourceTypes = new Set(plan.items.map((item) => item.resourceType));
741
763
  const readOrder = [
742
764
  'component', 'database-table', 'database-view', 'endpoint',
743
- 'role-group', 'service-account', 'group', 'job-template', 'schedule', 'event',
765
+ 'role-group', 'service-account', 'group', 'job-template', 'schedule', 'event', 'agent-plugin', 'agent',
744
766
  ];
745
767
  for (const resourceType of readOrder) {
746
768
  if (!resourceTypes.has(resourceType)) {
@@ -826,6 +848,29 @@ export async function applyMetadataBackfillPlan(input) {
826
848
  throw new Error(`Unsupported metadata plan action: ${item.action}.`);
827
849
  }
828
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
+ }
829
874
  if (item.resourceType === 'component') {
830
875
  const component = currentResources.get(`component:${item.resourceId}`);
831
876
  if (!component)
@@ -982,6 +1027,8 @@ export async function applyMetadataBackfillPlan(input) {
982
1027
  }
983
1028
  if (item.resourceType === 'service-account') {
984
1029
  const account = await client.getServiceAccount(item.resourceId);
1030
+ if (isBuiltinSystemAccount(account))
1031
+ throw new Error('The built-in System account cannot be managed by metadata backfill.');
985
1032
  const current = readConfiguredResourceMetadataStableKey(account, plan.stableKeyName);
986
1033
  if (current && !plan.force) {
987
1034
  results.push({ resourceType: item.resourceType, resourceId: item.resourceId, stableKey: current, action: 'skip' });