@skrr-ai/cli 0.1.93 → 0.1.95

package/bin/update-session.cjs

@@ -0,0 +1,194 @@
+'use strict';
+
+// This bootstrap uses only Node built-ins: npm may replace the package while
+// the updater runs, so admission and the worker must not depend on its modules.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+// Protocol 1: bakery admission lock, immutable PID/birth/token leases, and
+// process-group mutation ownership. Its wire/locking contract is immutable.
+// Future protocols must coexist with these sessions or require an external
+// package-manager update; selecting a separate lock must never bypass them.
+const COORDINATION_VERSION = 1;
+
+function runtimeDir(packageRoot) {
+  const key = crypto
+    .createHash('sha256')
+    .update(path.resolve(packageRoot))
+    .digest('hex')
+    .slice(0, 24);
+  // Installation leases deliberately ignore SKRR_CONFIG_DIR: two profiles or
+  // config roots still share the same npm installation.
+  return path.join(os.homedir(), '.skrr', 'cli-update-runtime', key);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+    fs.renameSync(temporary, file);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+function processIdentity(pid) {
+  if (process.platform === 'win32') return null;
+  try {
+    return (
+      execFileSync('ps', ['-p', String(pid), '-o', 'lstart='], {
+        timeout: 500,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim() || null
+    );
+  } catch {
+    return null;
+  }
+}
+
+function isAlive(owner) {
+  if (!owner || !Number.isSafeInteger(owner.pid) || owner.pid <= 0) return false;
+  try {
+    process.kill(owner.group && process.platform !== 'win32' ? -owner.pid : owner.pid, 0);
+  } catch (error) {
+    return error.code !== 'ESRCH';
+  }
+  // A recycled PID is not the process that created this lease. If the OS
+  // cannot disclose its identity, remain conservative rather than expiring a
+  // live session on a wall-clock timeout.
+  const identity = owner.identity && processIdentity(owner.pid);
+  return !identity || identity === owner.identity;
+}
+
+function wait(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+function acquireLock(directory, timeoutMs = 1000) {
+  // Lamport's bakery algorithm, with one immutable participant filename per
+  // acquisition. Reaping a crashed participant never removes a replacement
+  // owner's lock (the stale-directory removal race of mkdir mutexes).
+  const deadline = Date.now() + timeoutMs;
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const owner = {
+    pid: process.pid,
+    identity: processIdentity(process.pid),
+    token: crypto.randomUUID(),
+  };
+  const participant = path.join(directory, `${owner.pid}-${owner.token}.json`);
+  const participants = () => {
+    const active = [];
+    for (const file of fs.readdirSync(directory)) {
+      if (!file.endsWith('.json')) continue;
+      const target = path.join(directory, file);
+      const record = readJson(target);
+      if (record && isAlive(record)) active.push(record);
+      else if (record) fs.rmSync(target, { force: true });
+    }
+    return active;
+  };
+  try {
+    writeJson(participant, { ...owner, choosing: true, ticket: 0 });
+    const ticket = Math.max(0, ...participants().map((record) => record.ticket || 0)) + 1;
+    writeJson(participant, { ...owner, choosing: false, ticket });
+    while (true) {
+      const blocked = participants().some(
+        (other) =>
+          other.token !== owner.token &&
+          (other.choosing ||
+            (other.ticket > 0 &&
+              (other.ticket < ticket || (other.ticket === ticket && other.token < owner.token)))),
+      );
+      if (!blocked)
+        return () => {
+          fs.rmSync(participant, { force: true });
+        };
+      if (Date.now() >= deadline)
+        throw Object.assign(new Error('CLI update lock is busy'), { code: 'CLI_UPDATE_BUSY' });
+      wait(25);
+    }
+  } catch (error) {
+    fs.rmSync(participant, { force: true });
+    throw error;
+  }
+}
+
+function liveLeases(directory) {
+  const leaseDir = path.join(directory, 'sessions');
+  fs.mkdirSync(leaseDir, { recursive: true, mode: 0o700 });
+  const live = [];
+  for (const file of fs.readdirSync(leaseDir)) {
+    const target = path.join(leaseDir, file);
+    const lease = readJson(target);
+    if (lease && isAlive(lease)) live.push(lease);
+    else fs.rmSync(target, { force: true });
+  }
+  return live;
+}
+
+function registerSession(packageRoot, timeoutMs = 60000) {
+  const directory = runtimeDir(packageRoot);
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    const release = acquireLock(path.join(directory, 'admission.lock'), 1000);
+    try {
+      const mutationFile = path.join(directory, 'mutation.json');
+      const mutation = readJson(mutationFile);
+      if (!mutation || !isAlive(mutation)) {
+        if (mutation) fs.rmSync(mutationFile, { force: true });
+        const token = crypto.randomUUID();
+        const leaseFile = path.join(directory, 'sessions', `${process.pid}-${token}.json`);
+        writeJson(leaseFile, {
+          pid: process.pid,
+          identity: processIdentity(process.pid),
+          token,
+          coordinationVersion: COORDINATION_VERSION,
+        });
+        const cleanup = () => {
+          try {
+            fs.rmSync(leaseFile, { force: true });
+          } catch {
+            /* read-only home */
+          }
+        };
+        process.once('exit', cleanup);
+        return cleanup;
+      }
+    } finally {
+      release();
+    }
+    if (Date.now() >= deadline) {
+      throw Object.assign(
+        new Error(
+          'skrr is being updated by npm. Retry shortly; inspect `skrr update --check` after the update finishes.',
+        ),
+        { code: 'CLI_UPDATE_BUSY' },
+      );
+    }
+    wait(100);
+  }
+}
+
+module.exports = {
+  COORDINATION_VERSION,
+  runtimeDir,
+  readJson,
+  writeJson,
+  processIdentity,
+  isAlive,
+  acquireLock,
+  liveLeases,
+  registerSession,
+};

package/bin/update-worker.cjs

@@ -0,0 +1,208 @@
+'use strict';
+
+// Copied next to update-session.cjs outside the npm package before launch.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFile, spawn } = require('node:child_process');
+const { promisify } = require('node:util');
+const runtime = require('./update-session.cjs');
+const execFileAsync = promisify(execFile);
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const MAX_WAIT_MS = 5 * 60 * 1000;
+const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+const MAX_LOG_BYTES = 256 * 1024;
+
+async function run(directory, options = {}) {
+  let releaseWorker;
+  try {
+    releaseWorker = runtime.acquireLock(path.join(directory, 'worker.lock'), 1000);
+  } catch (error) {
+    if (error.code === 'CLI_UPDATE_BUSY') return;
+    throw error;
+  }
+  const stateFile = path.join(directory, 'result.json');
+  let mutation = false;
+  let mutationChild = null;
+  let attempt = runtime.readJson(stateFile);
+  const persist = (changes) => {
+    attempt = { ...attempt, ...changes, updatedAt: Date.now() };
+    runtime.writeJson(stateFile, attempt);
+  };
+  try {
+    if (!attempt || !['queued', 'running'].includes(attempt.status)) return;
+    if (
+      attempt.coordinationVersion != null &&
+      attempt.coordinationVersion !== runtime.COORDINATION_VERSION
+    )
+      throw new Error(
+        'Incompatible CLI update coordination protocol; use the owning package manager',
+      );
+    if (
+      !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(attempt.version) ||
+      !path.isAbsolute(attempt.packageRoot) ||
+      !path.isAbsolute(attempt.npmPath)
+    ) {
+      throw new Error('Invalid persisted CLI update request');
+    }
+    // Serialize admission and the empty-session check. Newly starting CLIs
+    // then wait before loading oclif/package modules until npm has finished.
+    const deadline = Date.now() + (options.maxWaitMs ?? MAX_WAIT_MS);
+    while (true) {
+      const releaseAdmission = runtime.acquireLock(path.join(directory, 'admission.lock'), 1000);
+      try {
+        const previousMutation = runtime.readJson(path.join(directory, 'mutation.json'));
+        if (
+          (!previousMutation || !runtime.isAlive(previousMutation)) &&
+          runtime.liveLeases(directory).length === 0
+        ) {
+          runtime.writeJson(path.join(directory, 'mutation.json'), {
+            pid: process.pid,
+            identity: runtime.processIdentity(process.pid),
+          });
+          mutation = true;
+          break;
+        }
+      } finally {
+        releaseAdmission();
+      }
+      if (Date.now() >= deadline) {
+        persist({
+          status: 'queued',
+          message: 'Waiting for active CLI sessions; the next invocation resumes this request.',
+        });
+        return;
+      }
+      await delay(250);
+    }
+    if (
+      runtime.readJson(path.join(attempt.packageRoot, 'package.json'))?.version === attempt.version
+    ) {
+      persist({
+        status: 'succeeded',
+        finishedAt: Date.now(),
+        installedVersion: attempt.version,
+        message: 'The requested CLI version is already installed.',
+      });
+      return;
+    }
+    const rootResult = await execFileAsync(attempt.npmPath, ['root', '-g'], {
+      timeout: 1500,
+      maxBuffer: 64 * 1024,
+      shell: process.platform === 'win32',
+    });
+    const npmRoot = fs.realpathSync(rootResult.stdout.trim());
+    const expectedPackage = path.join(npmRoot, '@skrr-ai', 'cli');
+    if (fs.realpathSync(expectedPackage) !== fs.realpathSync(attempt.packageRoot)) {
+      throw new Error(
+        'npm global prefix changed; run the update with the package manager that owns this CLI',
+      );
+    }
+    persist({
+      status: 'running',
+      startedAt: Date.now(),
+      workerPid: process.pid,
+      message: 'npm is installing the requested CLI version.',
+    });
+    const logFile = path.join(directory, 'update.log');
+    fs.writeFileSync(logFile, '', { mode: 0o600 });
+    let logBytes = 0;
+    const log = (chunk) => {
+      const bytes = Buffer.from(chunk);
+      if (logBytes >= MAX_LOG_BYTES) return;
+      const bounded = bytes.subarray(0, MAX_LOG_BYTES - logBytes);
+      fs.appendFileSync(logFile, bounded);
+      logBytes += bounded.length;
+    };
+    await new Promise((resolve, reject) => {
+      const requestFile = path.join(directory, `runner-${crypto.randomUUID()}.json`);
+      const token = crypto.randomUUID();
+      runtime.writeJson(requestFile, { token, npmPath: attempt.npmPath, version: attempt.version });
+      const child = spawn(
+        process.execPath,
+        [path.join(__dirname, 'update-npm-runner.cjs'), requestFile],
+        {
+          detached: process.platform !== 'win32',
+          stdio: ['ignore', 'pipe', 'pipe'],
+        },
+      );
+      if (child.pid) {
+        mutationChild = { pid: child.pid, group: process.platform !== 'win32' };
+        runtime.writeJson(path.join(directory, 'mutation.json'), mutationChild);
+        runtime.writeJson(`${requestFile}.go`, { pid: child.pid, token });
+      }
+      child.stdout.on('data', log);
+      child.stderr.on('data', log);
+      let timedOut = false;
+      let forceTimer;
+      const signal = (name) => {
+        try {
+          if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, name);
+          else child.kill(name);
+        } catch {
+          /* already exited */
+        }
+      };
+      const timer = setTimeout(() => {
+        timedOut = true;
+        signal('SIGTERM');
+        forceTimer = setTimeout(() => {
+          signal('SIGKILL');
+        }, 5000);
+      }, options.installTimeoutMs ?? INSTALL_TIMEOUT_MS);
+      child.once('error', (error) => {
+        clearTimeout(timer);
+        clearTimeout(forceTimer);
+        reject(error);
+      });
+      child.once('exit', async (code, exitSignal) => {
+        clearTimeout(timer);
+        if (timedOut) {
+          // npm can exit on TERM while a descendant keeps writing. Complete
+          // KILL escalation for the whole group before releasing admission.
+          signal('SIGKILL');
+          const stopDeadline = Date.now() + 5000;
+          while (mutationChild && runtime.isAlive(mutationChild) && Date.now() < stopDeadline)
+            await delay(50);
+        }
+        clearTimeout(forceTimer);
+        fs.rmSync(requestFile, { force: true });
+        fs.rmSync(`${requestFile}.go`, { force: true });
+        if (timedOut) reject(new Error('npm update exceeded the 10-minute time limit'));
+        else if (code === 0) resolve();
+        else reject(new Error(`npm update failed (${exitSignal || code}); see ${logFile}`));
+      });
+    });
+    const installedVersion = runtime.readJson(
+      path.join(attempt.packageRoot, 'package.json'),
+    )?.version;
+    if (installedVersion !== attempt.version)
+      throw new Error(
+        `npm completed but installed ${installedVersion || 'an unknown version'} instead of ${attempt.version}`,
+      );
+    persist({
+      status: 'succeeded',
+      finishedAt: Date.now(),
+      installedVersion,
+      message: 'The new CLI version is ready for the next invocation.',
+    });
+  } catch (error) {
+    persist({ status: 'failed', finishedAt: Date.now(), message: String(error.message || error) });
+  } finally {
+    // A crashed worker/terminated npm parent can leave a mutating process
+    // group alive. Keep the gate until the group is confirmed gone.
+    if (mutation && (!mutationChild || !runtime.isAlive(mutationChild)))
+      fs.rmSync(path.join(directory, 'mutation.json'), { force: true });
+    releaseWorker();
+  }
+}
+
+if (require.main === module) {
+  const directory = process.argv[2];
+  if (!directory || !path.isAbsolute(directory)) process.exitCode = 1;
+  else
+    run(directory).catch(() => {
+      process.exitCode = 1;
+    });
+}
+module.exports = { run };

package/dist/base-command.js

@@ -52,7 +52,6 @@ const daemonBroker_1 = require("./lib/daemonBroker");
 const daemonBrokerRefusal_1 = require("./lib/daemonBrokerRefusal");
 const refresh_1 = require("./lib/refresh");
 const auth_storage_1 = require("./lib/auth-storage");
-const update_check_1 = require("./lib/update-check");
 const web_url_1 = require("./lib/web-url");
 const edge_error_page_1 = require("./lib/edge-error-page");
 const step_up_1 = require("./lib/step-up");
@@ -541,20 +540,6 @@ class BaseCommand extends core_1.Command {
         }
         (0, node_adapter_1.setAdapterCredentialOverride)(this.resolvedCredential);
         (0, data_provider_1.setHttpAdapter)((0, node_adapter_1.createNodeAdapter)());
-        // Non-blocking "a newer skrr is available" advisory. Decides from a ~4h
-        // on-disk cache (zero added latency) and refreshes in the background.
-        // Writes at most one line to stderr, never stdout, so --json consumers
-        // are unaffected; self-suppresses in bundled/non-TTY/opted-out contexts.
-        // Wrapped so an advisory can never break the command it precedes.
-        try {
-            (0, update_check_1.maybeWarnOutdatedCli)({
-                currentVersion: this.config.version,
-                baseURL: this.cliConfig.baseURL,
-            });
-        }
-        catch {
-            /* advisory is strictly best-effort */
-        }
     }
     /**
      * Read only the two global base flags. A narrow parser — oclif's

package/dist/commands/agents/operating-plan.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../base-command';
+export default class AgentOperatingPlan extends BaseCommand {
+    static description: string;
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/agents/operating-plan.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const roles_1 = require("../../lib/roles");
+class AgentOperatingPlan extends base_command_1.BaseCommand {
+    static description = 'Read responsibilities, evidence, inquiries, work, delayed evaluation and existing planning loops without scheduling work';
+    static args = {
+        id: core_1.Args.string({ required: true, description: 'Agent ID', ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output full joined state and source coverage as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(AgentOperatingPlan);
+        try {
+            const plan = await roles_1.roleApi.plan(args.id);
+            if (flags.json) {
+                this.log(JSON.stringify(plan, null, 2));
+                return;
+            }
+            this.log(`Operating plan — ${args.id} (${plan.generatedAt})`);
+            for (const r of plan.responsibilities) {
+                this.log(`\n${r.title} · ${r.status} · ${r.kind} v${r.version}`);
+                this.log(`  Responsibility: ${r.purpose}`);
+                this.log(`  Evidence: ${r.evidence.status}${r.evidence.issues?.length ? ` (${r.evidence.issues.join(', ')})` : ''}`);
+                this.log("  Execution authority: tools, sandbox and approvals use the Agent's runtime permissions.");
+                for (const q of r.inquiries)
+                    this.log(`  Inquiry: ${q.question} [${q.status}] — ${q.decisionImpact}`);
+                for (const w of r.work)
+                    this.log(`  Work: ${w.title} [${w.status}]`);
+                for (const w of r.waiting)
+                    this.log(`  Evaluation: ${w.status} — ${w.reason}${w.nextAt ? `; next ${w.nextAt}` : ''}`);
+                this.log(`  Next intervention: ${r.lifecycle !== 'active' ? 'inactive; requires activation' : r.nextIntervention?.nextAt || r.nextIntervention?.status || 'not recorded'}`);
+                if (r.blocker)
+                    this.log(`  Blocker: ${r.blocker.code} — ${r.blocker.remediation || ''}`);
+            }
+            this.log(`\n${plan.planning.loops.length} existing planning/reflection loops; ${plan.planning.todos.length} scheduled work blocks.`);
+            if (plan.learning?.skillValidation)
+                this.log(`Skill validation: ${plan.learning.skillValidation.enabled ? 'enabled' : 'disabled'} (${plan.learning.skillValidation.scope}); external effects validated: ${plan.learning.skillValidation.externalEffectsValidated}.`);
+            if (!plan.coverage.complete) {
+                this.log(`Incomplete coverage${plan.coverage.truncated ? '; view limits reached' : ''}.`);
+                for (const s of plan.coverage.sources.filter((s) => s.status !== 'available'))
+                    this.log(`  ${s.name}: ${s.status} (${s.code || 'unknown'})`);
+            }
+            this.log('Task or Run completion does not establish a verified outcome.');
+        }
+        catch (error) {
+            this.handleApiError(error);
+        }
+    }
+}
+exports.default = AgentOperatingPlan;

package/dist/commands/agents/roles/example.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../../base-command';
+export default class RolesExample extends BaseCommand {
+    static description: string;
+    static args: {
+        role: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        output: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/agents/roles/example.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const node_fs_1 = require("node:fs");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+class RolesExample extends base_command_1.BaseCommand {
+    static description = 'Start a portable DevOps, Financial Tech or Research Operations role using one generic schema';
+    static args = {
+        role: core_1.Args.string({
+            required: true,
+            options: ['devops', 'financial', 'research'],
+            description: 'Example role',
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        output: core_1.Flags.string({ description: 'Save the example JSON to a file; otherwise print JSON' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(RolesExample);
+        const example = data_provider_1.ROLE_OPERATING_SPEC_EXAMPLES[args.role];
+        const json = `${JSON.stringify(example, null, 2)}\n`;
+        if (flags.output)
+            (0, node_fs_1.writeFileSync)(flags.output, json, { mode: 0o600 });
+        else
+            this.log(json.trimEnd());
+    }
+}
+exports.default = RolesExample;

package/dist/commands/{commitments/mode.d.ts → agents/roles/export.d.ts}

@@ -1,15 +1,15 @@
-import { BaseCommand } from '../../base-command';
-export default class CommitmentsMode extends BaseCommand {
+import { BaseCommand } from '../../../base-command';
+export default class RolesExport extends BaseCommand {
     static description: string;
     static examples: string[];
     static args: {
         id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
-        mode: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        key: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
+        summary: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        output: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
-        verbose: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
-        reason: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/agents/roles/export.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../../base-command");
+const roles_1 = require("../../../lib/roles");
+const artifact_export_1 = require("../../../lib/artifact-export");
+/** Shape version of the portable role spec this command writes. */
+const ROLE_EXPORT_VERSION = 1;
+class RolesExport extends base_command_1.BaseCommand {
+    static description = 'Export portable role authoring intent; credentials, installation IDs and runtime state are excluded';
+    static examples = [
+        '<%= config.bin %> agents roles export <agent> <key> --summary',
+        '<%= config.bin %> agents roles export <agent> <key> --output role.json',
+        '<%= config.bin %> agents roles export <agent> <key> --output - | jq .',
+    ];
+    static args = {
+        id: core_1.Args.string({ required: true, description: 'Agent ID', ignoreStdin: true }),
+        key: core_1.Args.string({ required: true, description: 'Role key', ignoreStdin: true }),
+    };
+    static flags = {
+        ...(0, artifact_export_1.standardExportFlags)(),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(RolesExport);
+        let selection;
+        try {
+            selection = (0, artifact_export_1.resolveExportSelection)(flags);
+        }
+        catch (err) {
+            if (err instanceof artifact_export_1.ExportContractError) {
+                this.failWithCliError({ message: err.message, code: err.code, exit: 2, retryable: false });
+            }
+            throw err;
+        }
+        let spec;
+        try {
+            spec = await roles_1.roleApi.export(args.id, args.key);
+        }
+        catch (error) {
+            this.handleApiError(error);
+        }
+        if (selection.summary) {
+            const summary = (0, artifact_export_1.contentFreeSummary)({
+                command: 'agents roles export',
+                artifactSchemaVersion: ROLE_EXPORT_VERSION,
+                itemCount: 1,
+                counts: {},
+            });
+            this.log(selection.json ? JSON.stringify(summary, null, 2) : (0, artifact_export_1.humanExportSummary)(summary));
+            return;
+        }
+        const serialized = (0, artifact_export_1.serializedArtifact)(spec);
+        if (selection.output === '-') {
+            this.log(serialized.trimEnd());
+            return;
+        }
+        let receipt;
+        try {
+            receipt = await (0, artifact_export_1.writeExportArtifact)({
+                command: 'agents roles export',
+                artifactSchemaVersion: ROLE_EXPORT_VERSION,
+                format: 'json',
+                output: selection.output,
+                content: serialized,
+                itemCount: 1,
+            });
+        }
+        catch (err) {
+            this.failWithCliError({
+                message: `Could not write ${selection.output}: ${err.message}`,
+                code: 'ROLE_EXPORT_WRITE_FAILED',
+                exit: 1,
+                retryable: false,
+                details: { path: selection.output },
+            });
+        }
+        this.log(selection.json ? JSON.stringify(receipt, null, 2) : (0, artifact_export_1.humanExportReceipt)(receipt));
+    }
+}
+exports.default = RolesExport;

package/dist/commands/agents/roles/install.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../../base-command';
+export default class RolesInstall extends BaseCommand {
+    static description: string;
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        preview: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}