@x12i/agent-roles

Which model does role R use for agent A, org O, process P, and step S? This package stores that answer, edits it, and returns a concrete call target.

It does not call models, hold credentials, or choose a role from severity. Pricing is read from @x12i/ai-catalogs. Profile keys are resolved with @x12i/ai-profiles.

npm install @x12i/agent-roles

Node.js 20 or newer.

Resolve

import { createAgentRoles } from "@x12i/agent-roles";

const roles = createAgentRoles();
const resolved = await roles.resolve({
  dir: "/path/to/agent",
  role: "thinker",
  orgId: "tgi",
  processFile: "processes/alerts/process.json",
  stepId: "nx-p4",
});

resolved.layer;       // step | process | org | agent | default | pack | code
resolved.call?.model;    // OpenRouter slug when prefer-openrouter is on
resolved.call?.provider; // dispatcher target: "openrouter" for that slug
resolved.call?.digest;

First non-blank choice wins: step → process → org → agent → general default → pack models.json → openai/gpt-6-luna. A process file does not inherit another process file. Pack placeholders such as configured-analysis-model are skipped. A stale profile warns and the next layer is used. strict: true (or AGENT_ROLES_STRICT=true) throws instead.

AGENT_ROLES_PROFILES=off loads no @x12i/ai-profiles code and rejects profile choices with PROFILES_DISABLED.

Where files live

Agent document: <agentDir>/metadata/agent-roles.json

General default: <workspaceRoot>/metadata/agent-roles.json

metadata/ is managed. It is not part of a package digest, and materializePackage does not copy it. carry(from, to) copies it onto a pin that does not have one yet, and only for process files that still exist.

Legacy memorix.role-models/v1 files are still read, including both nested spellings (processes/<id>/process.role-models.json and processes/<id>/role-models.json). Writes use the new file only.

npx agent-roles migrate --from <workspace>          # dry run
npx agent-roles migrate --from <workspace> --apply --remove-legacy
npx agent-roles doctor
npx agent-roles resolve --agent neo --role thinker --explain

Browser

@x12i/agent-roles/browser is the pure entry: registry, document parse, and resolveFromDocument. It does not import fs, mongodb, or @x12i/env. createBrowserGateway() lazily loads @x12i/ai-profiles/browser.

import { ROLES, ROLE_DEFAULTS, resolveFromDocument } from "@x12i/agent-roles/browser";

Environment

Init options override env. Env is read through @x12i/env. No .env file is required. See .env.example and erc-manifest.json.

| Variable | Default | |---|---| | AGENT_ROLES_STORE | auto (mongo only when AGENT_ROLES_MONGO_URI is set) | | AGENT_ROLES_AGENTS_ROOT | AGENTS_DIR, then PACKS_ROOT, then <cwd>/.memorix-agents | | AGENT_ROLES_WORKSPACE_ROOT | <parent of agents root>/.tmp/memorix-runtime/workspaces | | AGENT_ROLES_METADATA_DIR | metadata | | AGENT_ROLES_FILE | agent-roles.json | | AGENT_ROLES_MONGO_URI | unset. After mongo is chosen: MONGO_METADATA_URI, then MONGO_URI | | AGENT_ROLES_MONGO_DB | MONGO_METADATA_DB, then agent-roles | | AGENT_ROLES_MONGO_COLLECTION | agent-roles | | AGENT_ROLES_PROFILES | auto (off = concrete models only) | | AGENT_ROLES_PROFILE_SOURCE | bundled | | AGENT_ROLES_PREFER_OPENROUTER | PREFER_OPENROUTER, then true | | AGENT_ROLES_CATALOG_LANE | text | | AGENT_ROLES_DEFAULT_MODEL | openai/gpt-6-luna | | AGENT_ROLES_STRICT | false | | AGENT_ROLES_READONLY | false | | AGENT_ROLES_CACHE_TTL_MS | 15000 | | AGENT_ROLES_LOG_LEVEL | warn |

Mongo URIs are masked in doctor output and are rejected if a caller tries to store one in a role document. mongodb is an optional peer dependency.

Host intents ship the studio defaults (overview → sum/default, analysis → cyber/default, and the rest). Pass hostIntents to override keys, or replaceHostIntents: true to replace the map. They are registered with @x12i/ai-profiles unless profiles are off.

Errors

AgentRolesError codes: UNKNOWN_ROLE, INVALID_CHOICE, UNKNOWN_PROFILE, UNKNOWN_MODEL, PROFILES_DISABLED, NOT_CALLABLE, STORE_UNAVAILABLE, STORE_READONLY, CONFLICT, AGENT_NOT_FOUND, PROCESS_NOT_FOUND, CONFIG_INVALID.