@prismer/runtime 2.0.8 → 2.2.55

package/built-in-skills/role-builder/scripts/author-role.mjs

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+export class RoleAuthoringError extends Error {
+  constructor(stage, code, message, exitCode = 1, details = undefined) {
+    super(message);
+    this.name = 'RoleAuthoringError';
+    this.stage = stage;
+    this.code = code;
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+
+const SECRET_OPTIONS = new Set(['--api-key', '--token', '--jwt', '--secret', '--password']);
+const BOOLEAN_OPTIONS = new Set(['--json', '--preflight-only', '--help']);
+
+function optionName(arg) {
+  const equalsAt = typeof arg === 'string' ? arg.indexOf('=') : -1;
+  return equalsAt === -1 ? arg : arg.slice(0, equalsAt);
+}
+
+function enabled(value) {
+  return ['1', 'true', 'yes'].includes(String(value ?? '').toLowerCase());
+}
+
+function localTarget(hostname) {
+  return ['localhost', '127.0.0.1', '::1', 'host.docker.internal'].includes(hostname);
+}
+
+function roleRevision(rolePath) {
+  const stat = statSync(rolePath);
+  const hash = createHash('sha256');
+  if (stat.isDirectory()) {
+    for (const name of ['role.json', 'SOUL.md']) {
+      const file = resolve(rolePath, name);
+      if (!existsSync(file)) continue;
+      hash.update(name);
+      hash.update('\0');
+      hash.update(readFileSync(file));
+      hash.update('\0');
+    }
+  } else {
+    hash.update(readFileSync(rolePath));
+  }
+  return hash.digest('hex');
+}
+
+export function loadRoleAuthoringConfig(argv, env = process.env) {
+  const flags = new Set();
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const name = optionName(arg);
+    if (SECRET_OPTIONS.has(name)) {
+      throw new RoleAuthoringError(
+        'local_validation',
+        'SECRET_ARGUMENT_FORBIDDEN',
+        `${name} is forbidden; credentials must come from the injected environment`,
+        2,
+      );
+    }
+    if (!BOOLEAN_OPTIONS.has(arg)) {
+      throw new RoleAuthoringError(
+        'local_validation',
+        'UNKNOWN_ARGUMENT',
+        `unknown argument at position ${index + 1}`,
+        2,
+      );
+    }
+    flags.add(arg);
+  }
+  if (flags.has('--help')) return { help: true };
+
+  const rawRolePath = env.PRISMER_ROLE_BUNDLE?.trim();
+  if (!rawRolePath) {
+    throw new RoleAuthoringError('local_validation', 'CONFIG_MISSING', 'PRISMER_ROLE_BUNDLE is required', 2);
+  }
+  const rolePath = resolve(rawRolePath);
+  if (!existsSync(rolePath)) {
+    throw new RoleAuthoringError('local_validation', 'ROLE_BUNDLE_NOT_FOUND', 'PRISMER_ROLE_BUNDLE does not exist', 2);
+  }
+
+  let baseUrl;
+  try {
+    baseUrl = new URL((env.PRISMER_CLOUD_BASE || 'http://127.0.0.1:3000').replace(/\/$/, ''));
+  } catch {
+    throw new RoleAuthoringError('local_validation', 'INVALID_BASE_URL', 'PRISMER_CLOUD_BASE must be a valid URL', 2);
+  }
+  if (
+    !['http:', 'https:'].includes(baseUrl.protocol) ||
+    baseUrl.username ||
+    baseUrl.password ||
+    baseUrl.search ||
+    baseUrl.hash
+  ) {
+    throw new RoleAuthoringError(
+      'local_validation',
+      'UNSAFE_BASE_URL',
+      'PRISMER_CLOUD_BASE must be a plain http(s) origin without credentials, query, or hash',
+      2,
+    );
+  }
+  const preflightOnly = flags.has('--preflight-only');
+  if (!preflightOnly && !localTarget(baseUrl.hostname) && !enabled(env.PRISMER_ALLOW_REMOTE_WRITE)) {
+    throw new RoleAuthoringError(
+      'local_validation',
+      'REMOTE_WRITE_NOT_CONFIRMED',
+      'remote mutation is blocked; set PRISMER_ALLOW_REMOTE_WRITE=1 after confirming the target environment',
+      2,
+    );
+  }
+
+  const revision = roleRevision(rolePath);
+  return {
+    rolePath,
+    revision,
+    cloudBin: env.PRISMER_CLOUD_BIN?.trim() || 'cloud',
+    baseUrl: baseUrl.toString().replace(/\/$/, ''),
+    ledgerPath: resolve(
+      env.PRISMER_ROLE_AUTHORING_LEDGER?.trim() ||
+        `.prismer/operations/role-author-${createHash('sha256').update(rolePath).digest('hex').slice(0, 16)}.json`,
+    ),
+    publish: enabled(env.PRISMER_ROLE_PUBLISH),
+    preflightOnly,
+    json: flags.has('--json'),
+  };
+}
+
+function defaultRunCloud(config, args) {
+  const result = spawnSync(config.cloudBin, args, {
+    encoding: 'utf8',
+    env: { ...process.env, PRISMER_CLOUD_BASE: config.baseUrl },
+    shell: false,
+  });
+  if (result.error) {
+    throw new RoleAuthoringError(
+      'local_validation',
+      'CLOUD_CLI_UNAVAILABLE',
+      `could not execute the configured Cloud CLI: ${result.error.message}`,
+      2,
+    );
+  }
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+  };
+}
+
+function parseJson(result, stage) {
+  const raw = String(result.stdout || '').trim();
+  try {
+    return JSON.parse(raw);
+  } catch {
+    const start = raw.indexOf('{');
+    const end = raw.lastIndexOf('}');
+    if (start >= 0 && end > start) {
+      try {
+        return JSON.parse(raw.slice(start, end + 1));
+      } catch {
+        // Fall through.
+      }
+    }
+    throw new RoleAuthoringError(stage, 'INVALID_CLI_JSON', 'cloud CLI did not return valid JSON', 5);
+  }
+}
+
+function cliError(result) {
+  return (
+    String(result.stderr || '')
+      .trim()
+      .slice(0, 2_000) || `cloud CLI exited ${String(result.status)}`
+  );
+}
+
+function writeLedger(path, ledger) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(ledger, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+function readLedger(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    throw new RoleAuthoringError(
+      'local_validation',
+      'INVALID_AUTHORING_LEDGER',
+      'the role authoring ledger exists but is not valid JSON',
+      2,
+    );
+  }
+}
+
+export async function runRoleAuthoring(config, runCloud = defaultRunCloud) {
+  const previous = readLedger(config.ledgerPath);
+  if (
+    previous &&
+    (previous.rolePath !== config.rolePath ||
+      previous.revision !== config.revision ||
+      Boolean(previous.publish) !== config.publish)
+  ) {
+    throw new RoleAuthoringError(
+      'local_validation',
+      'AUTHORING_LEDGER_CONFLICT',
+      'the role authoring ledger belongs to different bundle content or destination',
+      2,
+    );
+  }
+  if (previous?.stage === 'completed') return previous;
+  if (previous?.stage === 'created' && previous.slug) {
+    // The server push completed and its canonical slug was durably recorded;
+    // resume from readback instead of pushing again (which intentionally bumps
+    // a role version even when its content is identical).
+    const shown = await runCloud(config, ['role', 'show', previous.slug, '--json']);
+    if (!shown.ok) {
+      throw new RoleAuthoringError(
+        'readback',
+        'ROLE_READBACK_FAILED',
+        'a previously-created role could not be read back; refusing an automatic second push',
+        5,
+      );
+    }
+    previous.readback = parseJson(shown, 'readback');
+    previous.stage = 'completed';
+    previous.completedAt = new Date().toISOString();
+    previous.updatedAt = previous.completedAt;
+    writeLedger(config.ledgerPath, previous);
+    return previous;
+  }
+
+  const validated = await runCloud(config, ['role', 'validate', config.rolePath, '--json']);
+  if (!validated.ok) {
+    throw new RoleAuthoringError('validation', 'ROLE_VALIDATION_FAILED', cliError(validated), 2);
+  }
+  const validation = parseJson(validated, 'validation');
+  if (validation.ok === false) {
+    throw new RoleAuthoringError('validation', 'ROLE_VALIDATION_FAILED', 'role bundle failed local validation', 2);
+  }
+
+  const tested = await runCloud(config, ['role', 'test', config.rolePath, '--json']);
+  if (!tested.ok) {
+    throw new RoleAuthoringError('preflight', 'ROLE_PREFLIGHT_FAILED', cliError(tested), 5);
+  }
+  const test = parseJson(tested, 'preflight');
+  if (test.ok === false) {
+    throw new RoleAuthoringError('preflight', 'ROLE_PREFLIGHT_FAILED', 'required Skill resolution failed', 5);
+  }
+
+  const ledger = {
+    schemaVersion: 1,
+    rolePath: config.rolePath,
+    revision: config.revision,
+    publish: config.publish,
+    slug: validation.slug ?? test.slug ?? null,
+    stage: 'preflight_complete',
+    validation,
+    test,
+    updatedAt: new Date().toISOString(),
+  };
+  writeLedger(config.ledgerPath, ledger);
+  if (config.preflightOnly) return ledger;
+
+  const createArgs = ['role', 'create', config.rolePath, '--mine', '--json'];
+  if (config.publish) createArgs.push('--publish');
+  const created = await runCloud(config, createArgs);
+  if (!created.ok) {
+    throw new RoleAuthoringError('create', 'ROLE_CREATE_FAILED', cliError(created), 5);
+  }
+  const creation = parseJson(created, 'create');
+  if (!creation.slug) {
+    throw new RoleAuthoringError('create', 'CANONICAL_SLUG_MISSING', 'create response omitted the role slug', 5);
+  }
+  ledger.creation = creation;
+  ledger.slug = creation.slug;
+  ledger.stage = 'created';
+  ledger.updatedAt = new Date().toISOString();
+  writeLedger(config.ledgerPath, ledger);
+
+  const shown = await runCloud(config, ['role', 'show', creation.slug, '--json']);
+  if (!shown.ok) {
+    throw new RoleAuthoringError('readback', 'ROLE_READBACK_FAILED', cliError(shown), 5);
+  }
+  ledger.readback = parseJson(shown, 'readback');
+  ledger.stage = 'completed';
+  ledger.completedAt = new Date().toISOString();
+  ledger.updatedAt = ledger.completedAt;
+  writeLedger(config.ledgerPath, ledger);
+  return ledger;
+}
+
+const HELP = `Usage:
+  # PRISMER_ROLE_BUNDLE and cloud authentication are injected in env
+  node scripts/author-role.mjs [--preflight-only] [--json]
+
+Optional env: PRISMER_ROLE_PUBLISH=1, PRISMER_ROLE_AUTHORING_LEDGER,
+PRISMER_CLOUD_BIN, PRISMER_CLOUD_BASE, PRISMER_ALLOW_REMOTE_WRITE=1.`;
+
+async function main() {
+  let config;
+  try {
+    config = loadRoleAuthoringConfig(process.argv.slice(2));
+    if (config.help) {
+      process.stdout.write(`${HELP}\n`);
+      return;
+    }
+    const result = await runRoleAuthoring(config);
+    if (config.json) process.stdout.write(`${JSON.stringify(result)}\n`);
+    else {
+      process.stdout.write(
+        `[role-builder] ${result.stage}: role=${result.slug || 'unresolved'} ledger=${config.ledgerPath}\n`,
+      );
+    }
+  } catch (error) {
+    const failure =
+      error instanceof RoleAuthoringError
+        ? error
+        : new RoleAuthoringError('internal', 'UNEXPECTED_ERROR', error?.message || String(error), 1);
+    process.stderr.write(
+      `${JSON.stringify({ ok: false, stage: failure.stage, error: { code: failure.code, message: failure.message, details: failure.details }, ...(config?.ledgerPath ? { ledger: config.ledgerPath } : {}) })}\n`,
+    );
+    process.exitCode = failure.exitCode;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) await main();

package/built-in-skills/role-builder/scripts/ingest-role.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// role-builder ingest — material→role template→live, optionally applied, via API key.
+//
+// Zero runtime dependencies (Node ≥18 built-ins). Reads a SS-02 role.json,
+// POSTs it to the real role-template endpoint with an `sk-prismer-*` admin API
+// key, and optionally applies it to a live agent.
+//
+// Accepts EITHER a single role.json OR a role bundle directory (role.json +
+// optional SOUL.md). When a dir + SOUL.md is given, SOUL.md's markdown becomes
+// operatingPrinciples (Hermes-compatible persona, doc 16 §5.4). Mirrors the
+// `cloud role create` CLI logic so the offline path matches.
+//
+// Usage:
+//   PRISMER_API_KEY=sk-prismer-... [PRISMER_CLOUD_BASE=http://127.0.0.1:3000] \
+//     node scripts/ingest-role.mjs <role.json|role-dir> [--publish|--admin-catalog] [--apply --agent <imUserId> --workspace-id <wsId>] [--json]
+//
+// Notes (product204/16 §2.3 — CLI 三入口默认私域):
+//   • DEFAULT (no flag) is the caller's PRIVATE Studio `/mine` (ownerAgentId=
+//     caller, visibility=private) via POST /api/im/role-templates/mine —
+//     editable, then publishable. Any authenticated key works (no admin
+//     needed). `--mine` is accepted as an explicit no-op for back-compat.
+//   • `--publish` (alias `--admin-catalog`) creates on the admin-only public
+//     catalog path (POST /api/im/role-templates, SS-02 §4.1) — the key must
+//     map to an admin email, else the server returns 403. Publication is an
+//     EXPLICIT act, never the default (16 §2.3).
+//   • APPLY is admin OR the target agent's workspace owner.
+
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+function die(msg, code = 1) {
+  console.error(`[role-builder] ✗ ${msg}`);
+  process.exit(code);
+}
+
+const args = process.argv.slice(2);
+const secretOptions = new Set(['--api-key', '--token', '--jwt', '--secret', '--password']);
+let rolePath;
+let wantApply = false;
+let wantPublish = false;
+let asJson = false;
+let agentId;
+let workspaceId;
+for (let index = 0; index < args.length; index += 1) {
+  const arg = args[index];
+  const equalsAt = arg.indexOf('=');
+  const option = equalsAt === -1 ? arg : arg.slice(0, equalsAt);
+  if (secretOptions.has(option)) {
+    die(`${option} is forbidden; credentials must come from environment variables`, 2);
+  }
+  if (arg === '--apply') {
+    wantApply = true;
+    continue;
+  }
+  if (arg === '--publish' || arg === '--admin-catalog') {
+    wantPublish = true;
+    continue;
+  }
+  if (arg === '--mine') continue;
+  if (arg === '--json') {
+    asJson = true;
+    continue;
+  }
+  if (arg === '--agent' || arg === '--workspace-id') {
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) die(`${arg} requires a value`, 2);
+    if (arg === '--agent') agentId = value;
+    else workspaceId = value;
+    index += 1;
+    continue;
+  }
+  if (arg.startsWith('--')) die(`unknown argument at position ${index + 1}`, 2);
+  if (rolePath) die('only one role path may be supplied', 2);
+  rolePath = arg;
+}
+// product204/16 §2.3 — private `/mine` is the DEFAULT; the public catalog is an
+// explicit `--publish` (alias `--admin-catalog`). `--mine` stays accepted as a
+// no-op for back-compat with pre-204 invocations.
+const wantMine = !wantPublish;
+
+const API_KEY = process.env.PRISMER_API_KEY;
+const BASE = (process.env.PRISMER_CLOUD_BASE || 'http://127.0.0.1:3000').replace(/\/$/, '');
+
+if (!rolePath) die('usage: node ingest-role.mjs <role.json|role-dir> [--publish|--admin-catalog] [--apply --agent <id> --workspace-id <id>] [--json]');
+if (!API_KEY) die('PRISMER_API_KEY env is required (sk-prismer-*; --mine needs any key, the admin catalog path needs an admin email)');
+if (wantApply && !agentId) die('--apply requires --agent <imUserId>');
+let target;
+try {
+  target = new URL(BASE);
+} catch {
+  die('PRISMER_CLOUD_BASE must be a valid URL', 2);
+}
+if (
+  !['http:', 'https:'].includes(target.protocol) ||
+  target.username ||
+  target.password ||
+  target.search ||
+  target.hash
+) {
+  die('PRISMER_CLOUD_BASE must be a plain http(s) origin without credentials, query, or hash', 2);
+}
+const isLocalTarget = ['localhost', '127.0.0.1', '::1', 'host.docker.internal'].includes(target.hostname);
+const allowRemote = ['1', 'true', 'yes'].includes(String(process.env.PRISMER_ALLOW_REMOTE_WRITE).toLowerCase());
+if (!isLocalTarget && !allowRemote) {
+  die('remote mutation is blocked; set PRISMER_ALLOW_REMOTE_WRITE=1 after confirming the target environment', 2);
+}
+
+// Read a role authoring unit — file OR directory (mirrors `cloud role create` /
+// runtime bundle.readRoleBundle). A dir folds SOUL.md → operatingPrinciples.
+function readRoleBundle(p) {
+  let st;
+  try {
+    st = statSync(p);
+  } catch {
+    die(`role path not found: ${p}`);
+  }
+  if (!st.isDirectory()) {
+    try {
+      return JSON.parse(readFileSync(p, 'utf8'));
+    } catch (err) {
+      die(`could not read/parse ${p}: ${err?.message || err}`);
+    }
+  }
+  // Directory bundle: role.json (required) + SOUL.md (optional persona).
+  let r;
+  try {
+    r = JSON.parse(readFileSync(join(p, 'role.json'), 'utf8'));
+  } catch (err) {
+    if (err?.code === 'ENOENT') die(`role bundle dir is missing role.json: ${join(p, 'role.json')}`);
+    die(`could not read/parse ${join(p, 'role.json')}: ${err?.message || err}`);
+  }
+  try {
+    const soul = readFileSync(join(p, 'SOUL.md'), 'utf8');
+    // SOUL.md is the persona source-of-truth → operatingPrinciples (markdown).
+    if (soul.trim() !== '') r.operatingPrinciples = soul;
+  } catch (err) {
+    if (err?.code !== 'ENOENT') die(`could not read SOUL.md: ${err?.message || err}`);
+    // SOUL.md absent is allowed.
+  }
+  return r;
+}
+
+const role = readRoleBundle(rolePath);
+
+const slug = role.slug || role.templateName;
+if (!slug && !role.name && !role.displayName) die('role.json must have slug or name/displayName');
+
+if (role.requiredSkills && !Array.isArray(role.requiredSkills)) {
+  die('requiredSkills must be an array of { skillSlug, required }');
+}
+for (const rs of role.requiredSkills || []) {
+  if (!rs || typeof rs.skillSlug !== 'string') {
+    die(`each requiredSkills entry needs a string skillSlug — got ${JSON.stringify(rs)}`);
+  }
+}
+
+async function api(method, path, body) {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${API_KEY}` },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+  let json = null;
+  try {
+    json = await res.json();
+  } catch {
+    /* non-JSON */
+  }
+  return { status: res.status, json };
+}
+
+(async () => {
+  // product204/16 §2.3 — DEFAULT is the owner-scoped create path (private role
+  // owned by the caller, lands in Studio `/mine`); `--publish`/`--admin-catalog`
+  // is the EXPLICIT admin catalog path (publishes straight to the Marketplace).
+  const createPath = wantMine ? '/api/im/role-templates/mine' : '/api/im/role-templates';
+  const created = await api('POST', createPath, role);
+  if (created.status === 403) {
+    die(
+      wantMine
+        ? 'create returned 403 — the API key does not resolve to a workspace user (auth failed).'
+        : 'create returned 403 — the API key does not map to an admin email (role create is admin-only). Use --mine for an owner-scoped private role.',
+      3,
+    );
+  }
+  if (created.status === 409) die(`role slug already exists (409). Use update or a new slug.`, 2);
+  if (created.status !== 201 || !created.json?.ok) {
+    die(`create failed (HTTP ${created.status}): ${created.json?.error || 'unknown error'}`);
+  }
+  const tpl = created.json.data;
+  const result = {
+    slug: tpl.slug,
+    agentType: tpl.agentType,
+    taskAuthority: tpl.taskAuthority,
+    requiredSkills: Array.isArray(role.requiredSkills) ? role.requiredSkills.length : 0,
+    applied: false,
+  };
+
+  if (wantApply) {
+    const apply = await api('POST', `/api/im/role-templates/${encodeURIComponent(tpl.slug)}/apply`, {
+      agentId,
+      ...(workspaceId ? { workspaceId } : {}),
+    });
+    if (apply.status >= 200 && apply.status < 300 && apply.json?.ok !== false) {
+      result.applied = agentId;
+    } else if (apply.status === 403) {
+      result.applyError = '403 — need admin or the target agent workspace owner';
+    } else {
+      result.applyError = `HTTP ${apply.status}: ${apply.json?.error || 'apply failed'}`;
+    }
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`[role-builder] ✓ ingested role ${result.slug}`);
+    console.log(`  type:     ${result.agentType} / authority=${result.taskAuthority}`);
+    console.log(`  skills:   ${result.requiredSkills}`);
+    console.log(`  applied:  ${result.applied}${result.applyError ? ` (${result.applyError})` : ''}`);
+    console.log(`  verify:   GET /api/im/role-templates/${result.slug}`);
+  }
+  if (result.applyError) process.exitCode = 5;
+})().catch((err) => die(err?.message || String(err)));