@rolealpha/n8n-nodes-rolealpha 0.0.0-stage → 0.5.0

package/dist/lib/agentRun.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * Acting as an agent (roleALPHA `agent:run`, RFC 8693). The runner holds one function
+ * account; for every run it swaps the account token for a run token that carries exactly
+ * the view of one agent, valid for 15 minutes. Without a run token nothing runs: there is
+ * no fallback to the view of the account.
+ *
+ * Tokens stay in memory only and are never written to node output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRunTokens = exports.PROCESS_STORE = exports.TOKEN_TYPE_ACCESS = exports.GRANT_TOKEN_EXCHANGE = exports.AgentRunError = void 0;
+exports.reactionFor = reactionFor;
+exports.isValidRunId = isValidRunId;
+exports.mcpRefusalCode = mcpRefusalCode;
+const REACTIONS = {
+    agent_uuid_fehlt: 'fixConfig',
+    run_id_ungueltig: 'fixConfig',
+    invalid_request: 'fixConfig',
+    unsupported_grant_type: 'fixConfig',
+    kein_agent_run_recht: 'informAdmin',
+    agent_nicht_gebunden: 'informAdmin',
+    funktionskonto_deaktiviert: 'informAdmin',
+    funktion_nicht_freigeschaltet: 'informAdmin',
+    mandant_stimmt_nicht: 'informAdmin',
+    anker_fehlt: 'informAdmin',
+    invalid_client: 'informAdmin',
+    agent_unbekannt: 'removeAgent',
+    agent_nicht_aktiv: 'pause',
+    agent_budget_erschoepft: 'pauseUntilNextPeriod',
+    agent_status_nicht_pruefbar: 'retryLater',
+    token_ungueltig: 'renewAccountToken',
+    falscher_token_typ: 'renewAccountToken',
+    falsche_resource: 'renewAccountToken',
+    funktionskonto_unbekannt: 'renewAccountToken',
+    secret_widerrufen: 'renewAccountToken',
+};
+function reactionFor(code, status = 0) {
+    return REACTIONS[code] ?? (status === 401 ? 'renewAccountToken' : status >= 500 || status === 429 ? 'retryLater' : 'endRun');
+}
+class AgentRunError extends Error {
+    code;
+    status;
+    description;
+    reaction;
+    constructor(code, status, description) {
+        super(`${code}${description ? `: ${description}` : ''}`);
+        this.code = code;
+        this.status = status;
+        this.description = description;
+        this.name = 'AgentRunError';
+        this.reaction = reactionFor(code, status);
+    }
+}
+exports.AgentRunError = AgentRunError;
+const RUN_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Renew a token this long before it expires, so no call starts with a token about to lapse. */
+const MARGIN_MS = 60_000;
+exports.GRANT_TOKEN_EXCHANGE = 'urn:ietf:params:oauth:grant-type:token-exchange';
+exports.TOKEN_TYPE_ACCESS = 'urn:ietf:params:oauth:token-type:access_token';
+function isValidRunId(runId) {
+    return RUN_ID.test(runId);
+}
+function parse(body) {
+    try {
+        const v = JSON.parse(body);
+        return v && typeof v === 'object' ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+function refusal(reply) {
+    const b = parse(reply.body);
+    const code = typeof b.error === 'string' && b.error ? b.error : `http_${reply.status}`;
+    const description = typeof b.error_description === 'string' ? b.error_description : reply.body.slice(0, 300);
+    return new AgentRunError(code, reply.status, description);
+}
+function basic(id, secret) {
+    return `Basic ${Buffer.from(`${encodeURIComponent(id)}:${encodeURIComponent(secret)}`).toString('base64')}`;
+}
+/** One store per process: the nodes and sub-workflows of one run swap once and share the token. */
+exports.PROCESS_STORE = { accounts: new Map(), runs: new Map() };
+/** Holds the account token and the run tokens, kept per account, agent and run. */
+class AgentRunTokens {
+    post;
+    now;
+    accounts;
+    runs;
+    constructor(post, now = Date.now, store = exports.PROCESS_STORE) {
+        this.post = post;
+        this.now = now;
+        this.accounts = store.accounts;
+        this.runs = store.runs;
+    }
+    accountKey(a) {
+        return `${a.tokenUrl}|${a.clientId}`;
+    }
+    async accountToken(a, fresh) {
+        const key = this.accountKey(a);
+        const hit = this.accounts.get(key);
+        if (!fresh && hit && hit.expiresAt - MARGIN_MS > this.now())
+            return hit.token;
+        const reply = a.authentication === 'body'
+            ? await this.post(a.tokenUrl, { grant_type: 'client_credentials', client_id: a.clientId, client_secret: a.clientSecret }, {})
+            : await this.post(a.tokenUrl, { grant_type: 'client_credentials' }, { Authorization: basic(a.clientId, a.clientSecret) });
+        if (reply.status !== 200)
+            throw refusal(reply);
+        const b = parse(reply.body);
+        if (typeof b.access_token !== 'string' || !b.access_token)
+            throw new AgentRunError('no_access_token', reply.status, 'The token endpoint returned no access_token');
+        const token = { token: b.access_token, expiresAt: this.now() + (Number(b.expires_in) || 3600) * 1000 };
+        this.accounts.set(key, token);
+        return token.token;
+    }
+    /** The run token for one agent and run: cached, swapped again shortly before it expires. */
+    async runToken(a, agentUuid, runId, opts = {}) {
+        const agent = agentUuid.trim().toLowerCase();
+        if (!UUID.test(agent))
+            throw new AgentRunError('agent_uuid_fehlt', 400, `Not an agent UUID: "${agentUuid}"`);
+        if (!isValidRunId(runId))
+            throw new AgentRunError('run_id_ungueltig', 400, 'Run ID: 1-128 characters of A-Z a-z 0-9 . _ : -');
+        const key = `${this.accountKey(a)}|${agent}|${runId}`;
+        const hit = this.runs.get(key);
+        if (!opts.fresh && hit && hit.expiresAt - MARGIN_MS > this.now())
+            return hit;
+        this.prune();
+        const swap = async (fresh) => this.post(a.tokenUrl, { grant_type: exports.GRANT_TOKEN_EXCHANGE, subject_token: await this.accountToken(a, fresh), subject_token_type: exports.TOKEN_TYPE_ACCESS, agent_uuid: agent, run_id: runId }, {});
+        let reply = await swap(false);
+        // A stale account token is renewed once; every other refusal is final for this call.
+        if (reply.status !== 200 && reactionFor(refusal(reply).code, reply.status) === 'renewAccountToken')
+            reply = await swap(true);
+        if (reply.status !== 200)
+            throw refusal(reply);
+        const b = parse(reply.body);
+        if (typeof b.access_token !== 'string' || !b.access_token)
+            throw new AgentRunError('no_access_token', reply.status, 'The token exchange returned no access_token');
+        const named = (b.agent ?? {});
+        const token = {
+            token: b.access_token,
+            expiresAt: this.now() + (Number(b.expires_in) || 900) * 1000,
+            agent: { uuid: agent, name: typeof named.name === 'string' ? named.name : null },
+            runId,
+        };
+        this.runs.set(key, token);
+        return token;
+    }
+    /** Forgets a run token, e.g. after the MCP endpoint refused it. */
+    forget(a, agentUuid, runId) {
+        this.runs.delete(`${this.accountKey(a)}|${agentUuid.trim().toLowerCase()}|${runId}`);
+    }
+    prune() {
+        const now = this.now();
+        for (const [k, v] of this.runs)
+            if (v.expiresAt <= now)
+                this.runs.delete(k);
+    }
+}
+exports.AgentRunTokens = AgentRunTokens;
+/** Reads the refusal code of an MCP reply under a run token: JSON-RPC error.message or an OAuth error. */
+function mcpRefusalCode(body) {
+    const b = parse(body);
+    const err = b.error;
+    if (typeof err === 'string')
+        return err;
+    if (err && typeof err === 'object' && typeof err.message === 'string')
+        return String(err.message).trim().split(/\s/)[0];
+    return '';
+}
+//# sourceMappingURL=agentRun.js.map

package/dist/lib/agentRun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentRun.js","sourceRoot":"","sources":["../../lib/agentRun.ts"],"names":[],"mappings":"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"}

package/dist/lib/agents.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Agents over the roleALPHA MCP endpoint. With one OAuth2 connection every agent
+ * of the organisation is found and run, so a new agent needs no per-agent key.
+ */
+import type { McpClient } from './mcp';
+import type { ContextBundle } from './prompt';
+export type ContextView = 'agent' | 'caller';
+export interface AgentEntry {
+    agentUuid: string;
+    agentName: string;
+    customId: string | null;
+    status: string | null;
+}
+/** Status comes from `status`, else from the last part of the summary ("Name | active"). */
+export declare function agentStatus(raw: Record<string, unknown>): string | null;
+/** All agents of the organisation, paged through search_agents. */
+export declare function listAgents(client: McpClient, organisation: string): Promise<AgentEntry[]>;
+/** The context bundle of one agent; view "agent" is exactly what the agent receives over its own key. */
+export declare function getAgentContext(client: McpClient, organisation: string, agentUuid: string, view?: ContextView): Promise<ContextBundle>;

package/dist/lib/agents.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Agents over the roleALPHA MCP endpoint. With one OAuth2 connection every agent
+ * of the organisation is found and run, so a new agent needs no per-agent key.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentStatus = agentStatus;
+exports.listAgents = listAgents;
+exports.getAgentContext = getAgentContext;
+const PAGE_SIZE = 200;
+const MAX_PAGES = 50;
+function str(value) {
+    if (typeof value === 'string')
+        return value.trim() === '' ? null : value.trim();
+    if (typeof value === 'number')
+        return String(value);
+    return null;
+}
+/** Status comes from `status`, else from the last part of the summary ("Name | active"). */
+function agentStatus(raw) {
+    const direct = str(raw.status);
+    if (direct)
+        return direct.toLowerCase();
+    const summary = str(raw.summary);
+    if (!summary || !summary.includes('|'))
+        return null;
+    return str(summary.split('|').pop())?.toLowerCase() ?? null;
+}
+function toEntry(raw) {
+    const uuid = str(raw.uuid ?? raw.entityUuid ?? raw.id);
+    if (!uuid)
+        return null;
+    return {
+        agentUuid: uuid.toLowerCase(),
+        agentName: str(raw.name) ?? '',
+        customId: str(raw.customerId ?? raw.customer_id ?? raw.customId),
+        status: agentStatus(raw),
+    };
+}
+/** All agents of the organisation, paged through search_agents. */
+async function listAgents(client, organisation) {
+    const out = [];
+    const seen = new Set();
+    let offset = 0;
+    for (let page = 0; page < MAX_PAGES; page++) {
+        const res = (await client.callTool('search_agents', { query: '', organisation, limit: PAGE_SIZE, offset }));
+        const list = Array.isArray(res) ? res : (res?.agents ?? res?.results ?? res?.entities ?? []);
+        for (const raw of list) {
+            const entry = raw && typeof raw === 'object' ? toEntry(raw) : null;
+            if (entry && !seen.has(entry.agentUuid)) {
+                seen.add(entry.agentUuid);
+                out.push(entry);
+            }
+        }
+        if (Array.isArray(res) || !res?.hasMore)
+            return out;
+        const next = Number(res.nextOffset);
+        offset = Number.isFinite(next) && next > offset ? next : offset + list.length;
+        if (list.length === 0)
+            break;
+    }
+    throw new Error(`search_agents did not finish after ${MAX_PAGES} pages`);
+}
+/** The bundle may come bare, wrapped in {bundle} or as one of several content parts. */
+function findBundle(value) {
+    if (Array.isArray(value)) {
+        for (const v of value) {
+            const b = findBundle(v);
+            if (b)
+                return b;
+        }
+        return null;
+    }
+    if (!value || typeof value !== 'object')
+        return null;
+    const obj = value;
+    if (obj.agent && typeof obj.agent === 'object')
+        return obj;
+    return obj.bundle ? findBundle(obj.bundle) : null;
+}
+/** The context bundle of one agent; view "agent" is exactly what the agent receives over its own key. */
+async function getAgentContext(client, organisation, agentUuid, view = 'agent') {
+    const res = await client.callTool('get_agent_context', { agent_uuid: agentUuid, organisation, view });
+    const bundle = findBundle(res);
+    if (!bundle) {
+        const raw = typeof res === 'string' ? res : JSON.stringify(res);
+        throw new Error(`get_agent_context returned no agent for ${agentUuid}: ${String(raw).slice(0, 400)}`);
+    }
+    return { ...bundle, guardrails: bundle.guardrails ?? [], context: bundle.context ?? [] };
+}
+//# sourceMappingURL=agents.js.map

package/dist/lib/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../lib/agents.ts"],"names":[],"mappings":"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"}

package/dist/lib/graph.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Traversal of the roleALPHA graph. Nothing here knows a concrete role, person
+ * or step: everything is read at run time, starting from an agent or a step.
+ *
+ * Edge directions (roleALPHA conventions):
+ *   Role --RESPONSIBLE_FOR--> Step        Role --DECIDES_ON--> Step
+ *   Role --ACCOUNTABLE_FOR--> Step        Policy --APPLIES_TO--> Step
+ *   Successor --DEPENDS_ON--> Predecessor Parent --HAS_SUBPROCESS--> Child
+ *   Person --EXECUTES--> Role             Agent --AGENT_FULFILLS_ROLE--> Role
+ *   Circle --IS_IMPLEMENTED_BY--> Role
+ */
+import type { McpClient } from './mcp';
+export interface EntityDetails {
+    uuid: string;
+    name: string;
+    customId: string | null;
+    entityType: string;
+    data: Record<string, unknown>;
+}
+export interface Relationship {
+    id?: string | number;
+    type: string;
+    direction: 'incoming' | 'outgoing';
+    uuid: string;
+    name: string;
+    entityType: string;
+}
+export interface SearchHit {
+    uuid: string;
+    name: string;
+    customId: string | null;
+    entityType: string;
+}
+export interface GraphSource {
+    details(uuid: string): Promise<EntityDetails>;
+    relationships(uuid: string): Promise<Relationship[]>;
+    search(query: string, entityType?: string): Promise<SearchHit[]>;
+}
+export interface EntityRef {
+    uuid: string;
+    name: string;
+    entityType?: string;
+}
+export interface PersonRef extends EntityRef {
+    email: string | null;
+}
+export interface AgentRef extends EntityRef {
+    status: string | null;
+}
+export interface RoleHolders {
+    persons: PersonRef[];
+    agents: AgentRef[];
+}
+export interface RoleRef extends EntityRef {
+    holders?: RoleHolders;
+    purpose?: string | null;
+    accountabilities?: string[];
+    domains?: string[];
+}
+export interface StepSummary extends EntityRef {
+    customId: string | null;
+    subtype: string | null;
+    status: string | null;
+    frequency: string | null;
+    dueDate: string | null;
+    description: string | null;
+    criteria: string | null;
+    result: string | null;
+}
+export interface Step extends StepSummary {
+    predecessors: EntityRef[];
+    successors: EntityRef[];
+    parents: EntityRef[];
+    children: EntityRef[];
+    responsibleRoles: RoleRef[];
+    decidingRoles: RoleRef[];
+    accountableRoles: RoleRef[];
+    policies: Array<EntityRef & {
+        description: string | null;
+        version: string | null;
+        status: string | null;
+    }>;
+}
+export interface Duty {
+    role: EntityRef;
+    circle: EntityRef | null;
+    step: StepSummary;
+}
+export interface Decider {
+    basis: 'DECIDES_ON' | 'ACCOUNTABLE_FOR' | null;
+    roles: RoleRef[];
+}
+export interface ApproverCheck {
+    allowed: boolean;
+    reason: string;
+    basis: Decider['basis'];
+    role: EntityRef | null;
+    person: PersonRef | null;
+    candidates: Array<{
+        role: EntityRef;
+        persons: string[];
+    }>;
+}
+export declare function normalizeEmail(value: unknown): string;
+export declare function toDetails(raw: unknown, uuid: string): EntityDetails;
+export declare function toRelationships(raw: unknown): Relationship[];
+export declare function toSearchHits(raw: unknown): SearchHit[];
+export declare function toStepSummary(d: EntityDetails): StepSummary;
+/** Graph source on top of the roleALPHA MCP. Caches per instance (one per node execution). */
+export declare class McpGraphSource implements GraphSource {
+    private readonly client;
+    private readonly organisation;
+    private readonly detailCache;
+    private readonly relCache;
+    constructor(client: McpClient, organisation: string);
+    details(uuid: string): Promise<EntityDetails>;
+    relationships(uuid: string): Promise<Relationship[]>;
+    search(query: string, entityType?: string): Promise<SearchHit[]>;
+}
+export declare function findStepByCustomId(src: GraphSource, customId: string): Promise<StepSummary | null>;
+export declare function getRoleHolders(src: GraphSource, roleUuid: string): Promise<RoleHolders>;
+export declare function getCircle(src: GraphSource, roleUuid: string): Promise<EntityRef | null>;
+export interface CircleLead {
+    circle: EntityRef;
+    /** The role that leads the circle, with its holders; null when the circle names none. */
+    lead: RoleRef | null;
+    /** How the lead was recognised. */
+    basis: 'flag' | 'lead-link' | 'custom-id' | 'decides-on-circle' | null;
+    /** The agent's roles in this circle. */
+    roles: EntityRef[];
+}
+/**
+ * The role that leads the circle of each given role, read from roleALPHA at run time:
+ * a role inside the circle flagged as lead (leadLink / lead / subtype), else one whose purpose
+ * names it the Lead Link, else one whose custom ID ends in ":lead", else a role that decides on
+ * or is accountable for the circle itself. Persons first, agents after, as holders.
+ */
+export declare function getCircleLeads(src: GraphSource, roleUuids: string[]): Promise<CircleLead[]>;
+export declare function getStep(src: GraphSource, stepUuid: string, opts?: {
+    resolveHolders?: boolean;
+    roleDetails?: boolean;
+}): Promise<Step>;
+/** The roles an agent fulfils, read from the graph (used when no context bundle is at hand). */
+export declare function getAgentRoles(src: GraphSource, agentUuid: string): Promise<EntityRef[]>;
+/** Every step the given roles are responsible for, one entry per role and step. */
+export declare function getDuties(src: GraphSource, roleUuids: string[]): Promise<Duty[]>;
+/** Which of the given roles is responsible for the step. Empty means: not responsible. */
+export declare function responsibleRolesFor(src: GraphSource, stepUuid: string, roleUuids: string[]): Promise<EntityRef[]>;
+/** Role first, then person: DECIDES_ON wins; without it the ACCOUNTABLE_FOR role decides. */
+export declare function getDecider(src: GraphSource, stepUuid: string): Promise<Decider>;
+/**
+ * Fail-closed check whether the acting person may decide on the step right now.
+ * Only persons decide; agents filling the deciding role never count.
+ */
+export declare function checkApprover(src: GraphSource, stepUuid: string, actor: string): Promise<ApproverCheck>;