@relayflows/core 0.0.1 → 1.0.1

package/dist/provisioner.js

@@ -0,0 +1,269 @@
+/**
+ * Workflow agent provisioning.
+ *
+ * Composes identity primitives (token minting, scope compilation, JWKS,
+ * audit logging from @agent-relay/cloud) with relayfile-server primitives
+ * (workspace seeding, ACL seeding, mount lifecycle from @relayfile/sdk)
+ * into a single `provisionWorkflowAgents` orchestration suitable for
+ * workflow runners.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { compileAgentScopes, DEFAULT_ADMIN_AGENT_NAME, DEFAULT_ADMIN_SCOPES, getDefaultPermissionAuditPath, mintAgentToken, PermissionAuditLog, } from '@agent-relay/cloud';
+import { createWorkspaceIfNeeded, seedWorkflowAcls, seedWorkspace, } from '@relayfile/sdk/workspace-seeder';
+import { ensureRelayfileMount, } from '@relayfile/sdk/workspace-mount';
+const DEFAULT_AGENT_NAME = 'default-agent';
+function discoverAgentNames(projectDir) {
+    if (!existsSync(projectDir)) {
+        return [DEFAULT_AGENT_NAME];
+    }
+    const agentNames = new Set();
+    for (const entry of readdirSync(projectDir)) {
+        const match = entry.match(/^\.(.+)\.(agentignore|agentreadonly)$/u);
+        if (match?.[1]) {
+            agentNames.add(match[1]);
+        }
+    }
+    const discovered = [...agentNames].sort((left, right) => left.localeCompare(right));
+    return discovered.length > 0 ? discovered : [DEFAULT_AGENT_NAME];
+}
+function resolveAgents(config) {
+    const configuredAgents = Object.entries(config.agents ?? {});
+    if (configuredAgents.length > 0) {
+        return configuredAgents.map(([name, permissions]) => ({
+            name,
+            permissions: permissions ?? {},
+            resolutionSource: 'configured',
+        }));
+    }
+    return discoverAgentNames(config.projectDir).map((name) => ({
+        name,
+        permissions: {},
+        resolutionSource: 'auto-discovered',
+    }));
+}
+function buildSummary(compilations) {
+    return compilations.reduce((summary, compiled) => ({
+        readonly: summary.readonly + compiled.summary.readonly,
+        readwrite: summary.readwrite + compiled.summary.readwrite,
+        denied: summary.denied + compiled.summary.denied,
+        customScopes: summary.customScopes + compiled.summary.customScopes,
+    }), { readonly: 0, readwrite: 0, denied: 0, customScopes: 0 });
+}
+function buildAgentResult(projectDir, name, token, compiled, mountPoint) {
+    return {
+        name,
+        tokenPath: path.resolve(projectDir, '.relay', 'tokens', `${name}.jwt`),
+        token,
+        scopes: [...compiled.scopes],
+        compiled,
+        mountPoint,
+    };
+}
+function sanitizePathComponent(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, '-');
+}
+function countAclDirectories(compilations) {
+    const directories = new Set();
+    for (const compilation of compilations) {
+        for (const directory of Object.keys(compilation.acl)) {
+            directories.add(directory);
+        }
+    }
+    return directories.size;
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+export async function provisionWorkflowAgents(config) {
+    const audit = new PermissionAuditLog();
+    const auditPath = getDefaultPermissionAuditPath(config.projectDir);
+    try {
+        const agents = resolveAgents(config);
+        const tokens = new Map();
+        const scopes = new Map();
+        const mounts = new Map();
+        const agentResults = {};
+        const compilations = [];
+        const compiledByAgent = new Map();
+        for (const agent of agents) {
+            audit.log({
+                agentName: agent.name,
+                action: 'resolve',
+                details: {
+                    source: agent.resolutionSource,
+                    workspace: config.workspace,
+                    permissionKeys: Object.keys(agent.permissions).sort(),
+                },
+            });
+            const compiled = compileAgentScopes({
+                agentName: agent.name,
+                workspace: config.workspace,
+                projectDir: config.projectDir,
+                permissions: agent.permissions,
+            });
+            const token = mintAgentToken({
+                privateKey: config.tokenSigningKey.privateKey,
+                kid: config.tokenSigningKey.kid,
+                agentName: agent.name,
+                workspace: config.workspace,
+                scopes: compiled.scopes,
+                ttlSeconds: config.tokenTtlSeconds,
+            });
+            audit.log({
+                agentName: agent.name,
+                action: 'mint',
+                details: {
+                    workspace: config.workspace,
+                    jwtPath: path.resolve(config.projectDir, '.relay', 'tokens', `${agent.name}.jwt`),
+                    scopeCount: compiled.scopes.length,
+                    scopes: [...compiled.scopes],
+                    ttlSeconds: config.tokenTtlSeconds ?? null,
+                },
+            });
+            tokens.set(agent.name, token);
+            scopes.set(agent.name, [...compiled.scopes]);
+            compilations.push(compiled);
+            compiledByAgent.set(agent.name, compiled);
+        }
+        const adminScopes = [...(config.adminScopes ?? DEFAULT_ADMIN_SCOPES)];
+        const adminToken = mintAgentToken({
+            privateKey: config.tokenSigningKey.privateKey,
+            kid: config.tokenSigningKey.kid,
+            agentName: DEFAULT_ADMIN_AGENT_NAME,
+            workspace: config.workspace,
+            scopes: adminScopes,
+            ttlSeconds: config.tokenTtlSeconds,
+        });
+        audit.log({
+            agentName: DEFAULT_ADMIN_AGENT_NAME,
+            action: 'mint',
+            details: {
+                workspace: config.workspace,
+                role: 'admin',
+                scopeCount: adminScopes.length,
+                scopes: adminScopes,
+                ttlSeconds: config.tokenTtlSeconds ?? null,
+            },
+        });
+        let seededAclCount = 0;
+        let seededFileCount = 0;
+        if (!config.skipSeeding) {
+            await createWorkspaceIfNeeded(config.relayfileBaseUrl, adminToken, config.workspace);
+            audit.log({
+                agentName: DEFAULT_ADMIN_AGENT_NAME,
+                action: 'seed',
+                details: {
+                    workspace: config.workspace,
+                    step: 'workspace',
+                    relayfileBaseUrl: config.relayfileBaseUrl,
+                },
+            });
+            seededFileCount = await seedWorkspace(config.relayfileBaseUrl, adminToken, config.workspace, config.projectDir, config.excludeDirs ?? []);
+            audit.log({
+                agentName: DEFAULT_ADMIN_AGENT_NAME,
+                action: 'seed',
+                details: {
+                    workspace: config.workspace,
+                    step: 'files',
+                    projectDir: config.projectDir,
+                    excludeDirs: config.excludeDirs ?? [],
+                    fileCount: seededFileCount,
+                },
+            });
+            await seedWorkflowAcls({
+                relayfileUrl: config.relayfileBaseUrl,
+                adminToken,
+                workspace: config.workspace,
+                agents: compilations.map((compilation) => ({
+                    name: compilation.agentName,
+                    acl: compilation.acl,
+                })),
+            });
+            seededAclCount = countAclDirectories(compilations);
+            audit.log({
+                agentName: DEFAULT_ADMIN_AGENT_NAME,
+                action: 'seed',
+                details: {
+                    workspace: config.workspace,
+                    step: 'acl',
+                    directoryCount: seededAclCount,
+                    agentCount: compilations.length,
+                },
+            });
+        }
+        if (!config.skipMount) {
+            const mountRoot = path.resolve(config.mountBaseDir ?? path.join(config.projectDir, '.relay'));
+            try {
+                for (const agent of agents) {
+                    const token = tokens.get(agent.name);
+                    const compiled = compiledByAgent.get(agent.name);
+                    if (!token || !compiled) {
+                        continue;
+                    }
+                    const mountHandle = await ensureRelayfileMount({
+                        binaryPath: config.mountBinaryPath,
+                        relayfileUrl: config.relayfileBaseUrl,
+                        workspace: config.workspace,
+                        token,
+                        mountPoint: path.join(mountRoot, `workspace-${sanitizePathComponent(config.workspace)}-${sanitizePathComponent(agent.name)}`),
+                    });
+                    mounts.set(agent.name, mountHandle);
+                    agentResults[agent.name] = buildAgentResult(config.projectDir, agent.name, token, compiled, mountHandle.mountPoint);
+                }
+            }
+            catch (mountError) {
+                for (const [, mount] of mounts) {
+                    try {
+                        if (typeof mount.stop === 'function') {
+                            await mount.stop();
+                        }
+                    }
+                    catch {
+                        // Best-effort cleanup.
+                    }
+                }
+                mounts.clear();
+                throw mountError;
+            }
+        }
+        else {
+            for (const agent of agents) {
+                const token = tokens.get(agent.name);
+                const compiled = compiledByAgent.get(agent.name);
+                if (!token || !compiled) {
+                    continue;
+                }
+                agentResults[agent.name] = buildAgentResult(config.projectDir, agent.name, token, compiled);
+            }
+        }
+        return {
+            agents: agentResults,
+            agentNames: agents.map((agent) => agent.name),
+            adminToken,
+            seededFileCount,
+            seededAclCount,
+            summary: buildSummary(compilations),
+            mounts,
+            tokens,
+            scopes,
+        };
+    }
+    finally {
+        try {
+            await audit.writeTo(auditPath);
+        }
+        catch (error) {
+            if (config.verbose) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`Failed to write permission audit to ${auditPath}: ${message}`);
+            }
+        }
+        if (config.verbose) {
+            console.info(audit.summary());
+        }
+    }
+}
+// Backwards-compatible re-export so callers that previously did
+// `import { resolveAgentPermissions } from '@agent-relay/sdk/provisioner'`
+// can swap to `@relayflows/core`.
+export { resolveAgentPermissions } from '@agent-relay/cloud';
+//# sourceMappingURL=provisioner.js.map

package/dist/provisioner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioner.js","sourceRoot":"","sources":["../src/provisioner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAGL,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,6BAA6B,EAE7B,cAAc,EACd,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,GACd,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,oBAAoB,GAErB,MAAM,gCAAgC,CAAC;AA4ExC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAE3C,SAAS,kBAAkB,CAAC,UAAkB;IAC5C,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC9B,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IAErC,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACpE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACf,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;IACpF,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,aAAa,CAAC,MAA+B;IACpD,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAC7D,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC;YACpD,IAAI;YACJ,WAAW,EAAE,WAAW,IAAI,EAAE;YAC9B,gBAAgB,EAAE,YAAY;SAC/B,CAAC,CAAC,CAAC;IACN,CAAC;IAED,OAAO,kBAAkB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1D,IAAI;QACJ,WAAW,EAAE,EAAE;QACf,gBAAgB,EAAE,iBAAiB;KACpC,CAAC,CAAC,CAAC;AACN,CAAC;AAED,SAAS,YAAY,CAAC,YAAiD;IACrE,OAAO,YAAY,CAAC,MAAM,CACxB,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ;QACtD,SAAS,EAAE,OAAO,CAAC,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS;QACzD,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM;QAChD,YAAY,EAAE,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC,YAAY;KACnE,CAAC,EACF,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAC1D,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CACvB,UAAkB,EAClB,IAAY,EACZ,KAAa,EACb,QAAkC,EAClC,UAAmB;IAEnB,OAAO;QACL,IAAI;QACJ,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,MAAM,CAAC;QACtE,KAAK;QACL,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC5B,QAAQ;QACR,UAAU;KACX,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAa;IAC1C,OAAO,KAAK,CAAC,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,mBAAmB,CAAC,YAAiD;IAC5E,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IAEtC,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QACvC,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;YACrD,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC,IAAI,CAAC;AAC1B,CAAC;AAED,+EAA+E;AAE/E,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,MAA+B;IAC3E,MAAM,KAAK,GAAG,IAAI,kBAAkB,EAAE,CAAC;IACvC,MAAM,SAAS,GAAG,6BAA6B,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAEnE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QACrC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,EAA4D,CAAC;QACnF,MAAM,YAAY,GAAsB,EAAE,CAAC;QAC3C,MAAM,YAAY,GAA+B,EAAE,CAAC;QACpD,MAAM,eAAe,GAAG,IAAI,GAAG,EAAoC,CAAC;QAEpE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,KAAK,CAAC,GAAG,CAAC;gBACR,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,MAAM,EAAE,SAAS;gBACjB,OAAO,EAAE;oBACP,MAAM,EAAE,KAAK,CAAC,gBAAgB;oBAC9B,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,cAAc,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE;iBACtD;aACF,CAAC,CAAC;YAEH,MAAM,QAAQ,GAAG,kBAAkB,CAAC;gBAClC,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,WAAW,EAAE,KAAK,CAAC,WAAW;aAC/B,CAAC,CAAC;YACH,MAAM,KAAK,GAAG,cAAc,CAAC;gBAC3B,UAAU,EAAE,MAAM,CAAC,eAAe,CAAC,UAAU;gBAC7C,GAAG,EAAE,MAAM,CAAC,eAAe,CAAC,GAAG;gBAC/B,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,UAAU,EAAE,MAAM,CAAC,eAAe;aACnC,CAAC,CAAC;YAEH,KAAK,CAAC,GAAG,CAAC;gBACR,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC,IAAI,MAAM,CAAC;oBACjF,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM;oBAClC,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;oBAC5B,UAAU,EAAE,MAAM,CAAC,eAAe,IAAI,IAAI;iBAC3C;aACF,CAAC,CAAC;YAEH,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YAC7C,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC5B,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC5C,CAAC;QAED,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,oBAAoB,CAAC,CAAC,CAAC;QACtE,MAAM,UAAU,GAAG,cAAc,CAAC;YAChC,UAAU,EAAE,MAAM,CAAC,eAAe,CAAC,UAAU;YAC7C,GAAG,EAAE,MAAM,CAAC,eAAe,CAAC,GAAG;YAC/B,SAAS,EAAE,wBAAwB;YACnC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,MAAM,EAAE,WAAW;YACnB,UAAU,EAAE,MAAM,CAAC,eAAe;SACnC,CAAC,CAAC;QAEH,KAAK,CAAC,GAAG,CAAC;YACR,SAAS,EAAE,wBAAwB;YACnC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,IAAI,EAAE,OAAO;gBACb,UAAU,EAAE,WAAW,CAAC,MAAM;gBAC9B,MAAM,EAAE,WAAW;gBACnB,UAAU,EAAE,MAAM,CAAC,eAAe,IAAI,IAAI;aAC3C;SACF,CAAC,CAAC;QAEH,IAAI,cAAc,GAAG,CAAC,CAAC;QACvB,IAAI,eAAe,GAAG,CAAC,CAAC;QAExB,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YACxB,MAAM,uBAAuB,CAAC,MAAM,CAAC,gBAAgB,EAAE,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;YACrF,KAAK,CAAC,GAAG,CAAC;gBACR,SAAS,EAAE,wBAAwB;gBACnC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,IAAI,EAAE,WAAW;oBACjB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;iBAC1C;aACF,CAAC,CAAC;YAEH,eAAe,GAAG,MAAM,aAAa,CACnC,MAAM,CAAC,gBAAgB,EACvB,UAAU,EACV,MAAM,CAAC,SAAS,EAChB,MAAM,CAAC,UAAU,EACjB,MAAM,CAAC,WAAW,IAAI,EAAE,CACzB,CAAC;YACF,KAAK,CAAC,GAAG,CAAC;gBACR,SAAS,EAAE,wBAAwB;gBACnC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,IAAI,EAAE,OAAO;oBACb,UAAU,EAAE,MAAM,CAAC,UAAU;oBAC7B,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE;oBACrC,SAAS,EAAE,eAAe;iBAC3B;aACF,CAAC,CAAC;YAEH,MAAM,gBAAgB,CAAC;gBACrB,YAAY,EAAE,MAAM,CAAC,gBAAgB;gBACrC,UAAU;gBACV,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;oBACzC,IAAI,EAAE,WAAW,CAAC,SAAS;oBAC3B,GAAG,EAAE,WAAW,CAAC,GAAG;iBACrB,CAAC,CAAC;aACJ,CAAC,CAAC;YACH,cAAc,GAAG,mBAAmB,CAAC,YAAY,CAAC,CAAC;YACnD,KAAK,CAAC,GAAG,CAAC;gBACR,SAAS,EAAE,wBAAwB;gBACnC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,IAAI,EAAE,KAAK;oBACX,cAAc,EAAE,cAAc;oBAC9B,UAAU,EAAE,YAAY,CAAC,MAAM;iBAChC;aACF,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACtB,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;YAC9F,IAAI,CAAC;gBACH,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;oBAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBACrC,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBACjD,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;wBACxB,SAAS;oBACX,CAAC;oBAED,MAAM,WAAW,GAAG,MAAM,oBAAoB,CAAC;wBAC7C,UAAU,EAAE,MAAM,CAAC,eAAe;wBAClC,YAAY,EAAE,MAAM,CAAC,gBAAgB;wBACrC,SAAS,EAAE,MAAM,CAAC,SAAS;wBAC3B,KAAK;wBACL,UAAU,EAAE,IAAI,CAAC,IAAI,CACnB,SAAS,EACT,aAAa,qBAAqB,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAC5F;qBACF,CAAC,CAAC;oBAEH,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;oBACpC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CACzC,MAAM,CAAC,UAAU,EACjB,KAAK,CAAC,IAAI,EACV,KAAK,EACL,QAAQ,EACR,WAAW,CAAC,UAAU,CACvB,CAAC;gBACJ,CAAC;YACH,CAAC;YAAC,OAAO,UAAU,EAAE,CAAC;gBACpB,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;oBAC/B,IAAI,CAAC;wBACH,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;4BACrC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;wBACrB,CAAC;oBACH,CAAC;oBAAC,MAAM,CAAC;wBACP,uBAAuB;oBACzB,CAAC;gBACH,CAAC;gBACD,MAAM,CAAC,KAAK,EAAE,CAAC;gBACf,MAAM,UAAU,CAAC;YACnB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACrC,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACjD,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACxB,SAAS;gBACX,CAAC;gBAED,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;QAED,OAAO;YACL,MAAM,EAAE,YAAY;YACpB,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;YAC7C,UAAU;YACV,eAAe;YACf,cAAc;YACd,OAAO,EAAE,YAAY,CAAC,YAAY,CAAC;YACnC,MAAM;YACN,MAAM;YACN,MAAM;SACP,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACvE,OAAO,CAAC,IAAI,CAAC,uCAAuC,SAAS,KAAK,OAAO,EAAE,CAAC,CAAC;YAC/E,CAAC;QACH,CAAC;QAED,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;AACH,CAAC;AAED,gEAAgE;AAChE,2EAA2E;AAC3E,kCAAkC;AAClC,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/proxy-env.d.ts

@@ -0,0 +1,52 @@
+import type { AgentDefinition, SwarmConfig } from './types.js';
+export interface ProxyEnvBinding {
+    baseUrlVar: string;
+    apiKeyVar: string;
+}
+export type ProxyEnvRegistry = Record<string, readonly ProxyEnvBinding[]>;
+export declare const RELAY_PROXY_URL_ENV: "RELAY_LLM_PROXY";
+export declare const RELAY_PROXY_URL_ENV_ALIAS: "RELAY_LLM_PROXY_URL";
+export declare const RELAY_PROXY_TOKEN_ENV: "CREDENTIAL_PROXY_TOKEN";
+export declare const RELAY_PROXY_TOKEN_ENV_ALIAS: "RELAY_LLM_PROXY_TOKEN";
+export declare const DEFAULT_PROXY_ENV_REGISTRY: {
+    readonly claude: readonly [{
+        readonly baseUrlVar: "ANTHROPIC_BASE_URL";
+        readonly apiKeyVar: "ANTHROPIC_API_KEY";
+    }];
+    readonly codex: readonly [{
+        readonly baseUrlVar: "OPENAI_BASE_URL";
+        readonly apiKeyVar: "OPENAI_API_KEY";
+    }];
+    readonly opencode: readonly [{
+        readonly baseUrlVar: "OPENAI_BASE_URL";
+        readonly apiKeyVar: "OPENAI_API_KEY";
+    }];
+    readonly aider: readonly [{
+        readonly baseUrlVar: "OPENAI_API_BASE";
+        readonly apiKeyVar: "OPENAI_API_KEY";
+    }];
+    readonly gemini: readonly [{
+        readonly baseUrlVar: "GOOGLE_API_BASE";
+        readonly apiKeyVar: "GOOGLE_API_KEY";
+    }];
+    readonly goose: readonly [{
+        readonly baseUrlVar: "OPENAI_BASE_URL";
+        readonly apiKeyVar: "OPENAI_API_KEY";
+    }];
+    readonly droid: readonly [{
+        readonly baseUrlVar: "OPENAI_BASE_URL";
+        readonly apiKeyVar: "OPENAI_API_KEY";
+    }];
+    readonly cursor: readonly [{
+        readonly baseUrlVar: "OPENAI_BASE_URL";
+        readonly apiKeyVar: "OPENAI_API_KEY";
+    }];
+};
+export declare function createProxyEnvResolver(registry?: ProxyEnvRegistry): (cli: string, proxyUrl: string, proxyToken: string) => Record<string, string>;
+export declare const resolveProxyEnv: (cli: string, proxyUrl: string, proxyToken: string) => Record<string, string>;
+export declare function resolveProxyUrlFromEnv(env?: Record<string, string | undefined>): string | undefined;
+export declare function resolveProxyTokenFromEnv(env?: Record<string, string | undefined>): string | undefined;
+export declare function buildNormalizedProxyEnv(proxyUrl: string, proxyToken: string): Record<string, string>;
+export declare function getStrippedApiKeyVars(): string[];
+export declare function isProxyEnabled(agentDef?: Pick<AgentDefinition, 'credentials'> | null, swarmConfig?: Pick<SwarmConfig, 'credentialProxy'> | null): boolean;
+//# sourceMappingURL=proxy-env.d.ts.map

package/dist/proxy-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-env.d.ts","sourceRoot":"","sources":["../src/proxy-env.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE/D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC,CAAC;AAE1E,eAAO,MAAM,mBAAmB,EAAG,iBAA0B,CAAC;AAC9D,eAAO,MAAM,yBAAyB,EAAG,qBAA8B,CAAC;AACxE,eAAO,MAAM,qBAAqB,EAAG,wBAAiC,CAAC;AACvE,eAAO,MAAM,2BAA2B,EAAG,uBAAgC,CAAC;AAuC5E,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CASF,CAAC;AAmBtC,wBAAgB,sBAAsB,CAAC,QAAQ,GAAE,gBAA6C,IACpF,KAAK,MAAM,EAAE,UAAU,MAAM,EAAE,YAAY,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiBnF;AAED,eAAO,MAAM,eAAe,QAnBb,MAAM,YAAY,MAAM,cAAc,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAmB5B,CAAC;AAExD,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOpG;AAED,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,cAAc,CAC5B,QAAQ,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,GAAG,IAAI,EACtD,WAAW,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,iBAAiB,CAAC,GAAG,IAAI,GACxD,OAAO,CAET"}

package/dist/proxy-env.js

@@ -0,0 +1,92 @@
+import { getCliDefinition } from './cli-registry.js';
+export const RELAY_PROXY_URL_ENV = 'RELAY_LLM_PROXY';
+export const RELAY_PROXY_URL_ENV_ALIAS = 'RELAY_LLM_PROXY_URL';
+export const RELAY_PROXY_TOKEN_ENV = 'CREDENTIAL_PROXY_TOKEN';
+export const RELAY_PROXY_TOKEN_ENV_ALIAS = 'RELAY_LLM_PROXY_TOKEN';
+const OPENAI_COMPATIBLE_BINDINGS = [
+    { baseUrlVar: 'OPENAI_BASE_URL', apiKeyVar: 'OPENAI_API_KEY' },
+];
+const ANTHROPIC_BINDINGS = [
+    { baseUrlVar: 'ANTHROPIC_BASE_URL', apiKeyVar: 'ANTHROPIC_API_KEY' },
+];
+const AIDER_BINDINGS = [
+    { baseUrlVar: 'OPENAI_API_BASE', apiKeyVar: 'OPENAI_API_KEY' },
+];
+const GEMINI_BINDINGS = [
+    { baseUrlVar: 'GOOGLE_API_BASE', apiKeyVar: 'GOOGLE_API_KEY' },
+];
+const GENERIC_FALLBACK_BINDINGS = [
+    ...OPENAI_COMPATIBLE_BINDINGS,
+    ...ANTHROPIC_BINDINGS,
+];
+const STRIPPED_API_KEY_VARS = [
+    'OPENAI_API_KEY',
+    'ANTHROPIC_API_KEY',
+    'OPENROUTER_API_KEY',
+    'GOOGLE_API_KEY',
+    'OPENAI_BASE_URL',
+    'ANTHROPIC_BASE_URL',
+    'OPENAI_API_BASE',
+    'GOOGLE_API_BASE',
+];
+const CLI_ALIASES = {
+    agent: 'cursor',
+    'cursor-agent': 'cursor',
+};
+export const DEFAULT_PROXY_ENV_REGISTRY = {
+    claude: ANTHROPIC_BINDINGS,
+    codex: OPENAI_COMPATIBLE_BINDINGS,
+    opencode: OPENAI_COMPATIBLE_BINDINGS,
+    aider: AIDER_BINDINGS,
+    gemini: GEMINI_BINDINGS,
+    goose: OPENAI_COMPATIBLE_BINDINGS,
+    droid: OPENAI_COMPATIBLE_BINDINGS,
+    cursor: OPENAI_COMPATIBLE_BINDINGS,
+};
+function normalizeCli(cli) {
+    const baseCli = cli.includes(':') ? cli.split(':')[0] : cli;
+    return CLI_ALIASES[baseCli] ?? baseCli;
+}
+function buildProxyEnv(bindings, proxyUrl, proxyToken) {
+    return bindings.reduce((env, binding) => {
+        env[binding.baseUrlVar] = proxyUrl;
+        env[binding.apiKeyVar] = proxyToken;
+        return env;
+    }, {});
+}
+export function createProxyEnvResolver(registry = DEFAULT_PROXY_ENV_REGISTRY) {
+    return (cli, proxyUrl, proxyToken) => {
+        const normalizedCli = normalizeCli(cli);
+        const bindings = registry[normalizedCli];
+        if (bindings) {
+            return buildProxyEnv(bindings, proxyUrl, proxyToken);
+        }
+        const knownCli = getCliDefinition(normalizedCli);
+        const warningPrefix = knownCli ? 'No proxy env registry entry' : 'Unknown CLI';
+        console.warn(`[proxy-env] ${warningPrefix} for "${normalizedCli}". ` +
+            'Falling back to generic OpenAI/Anthropic proxy env overrides.');
+        return buildProxyEnv(GENERIC_FALLBACK_BINDINGS, proxyUrl, proxyToken);
+    };
+}
+export const resolveProxyEnv = createProxyEnvResolver();
+export function resolveProxyUrlFromEnv(env = process.env) {
+    return env[RELAY_PROXY_URL_ENV] ?? env[RELAY_PROXY_URL_ENV_ALIAS];
+}
+export function resolveProxyTokenFromEnv(env = process.env) {
+    return env[RELAY_PROXY_TOKEN_ENV] ?? env[RELAY_PROXY_TOKEN_ENV_ALIAS];
+}
+export function buildNormalizedProxyEnv(proxyUrl, proxyToken) {
+    return {
+        [RELAY_PROXY_URL_ENV]: proxyUrl,
+        [RELAY_PROXY_URL_ENV_ALIAS]: proxyUrl,
+        [RELAY_PROXY_TOKEN_ENV]: proxyToken,
+        [RELAY_PROXY_TOKEN_ENV_ALIAS]: proxyToken,
+    };
+}
+export function getStrippedApiKeyVars() {
+    return [...STRIPPED_API_KEY_VARS];
+}
+export function isProxyEnabled(agentDef, swarmConfig) {
+    return Boolean(agentDef?.credentials?.proxy && swarmConfig?.credentialProxy);
+}
+//# sourceMappingURL=proxy-env.js.map

package/dist/proxy-env.js.map

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

package/dist/run-script.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Programmatic local runner for `.ts` / `.tsx` / `.py` workflow scripts.
+ *
+ * This is the body of the `agent-relay run <script>` command extracted into
+ * the SDK so other tools (e.g. `ricky run`) can drive the same execution
+ * flow without shelling out to the `agent-relay` binary.
+ *
+ * Behavior is preserved exactly — the relay CLI's `run` command now
+ * delegates to `runScriptWorkflow()` with no semantic change.
+ */
+import { execFileSync } from 'node:child_process';
+export type ExecFileSyncLike = typeof execFileSync;
+export interface RunScriptWorkflowOptions {
+    /** Validate without running. Sets `DRY_RUN=true` in the child env. */
+    dryRun?: boolean;
+    /** Resume a previously failed workflow run by id. */
+    resume?: string;
+    /** Start from the given step name, skipping predecessors. */
+    startFrom?: string;
+    /** Use cached outputs from this previous run id. Pairs with `startFrom`. */
+    previousRunId?: string;
+}
+/**
+ * Parsed workflow parse error, normalized from whatever shape the tsx/esbuild
+ * subprocess produced on stderr. Decoupling this from any specific error class
+ * means the formatter is testable in isolation and works regardless of how
+ * the error surfaced (TransformError from tsx, Bun-bundled esbuild error, etc.).
+ */
+export interface ParsedWorkflowError {
+    file: string;
+    line?: number;
+    column?: number;
+    message: string;
+    lineText?: string;
+}
+export interface LocalSdkWorkspace {
+    rootDir: string;
+    sdkDir: string;
+}
+/**
+ * Walk upward from `startDir` looking for a workspace where the root
+ * `package.json` is `agent-relay` and `packages/sdk/package.json` is
+ * `@agent-relay/sdk`. Returns the matched paths or `null`.
+ */
+export declare function findLocalSdkWorkspace(startDir: string): LocalSdkWorkspace | null;
+/**
+ * When running inside the relay monorepo, ensure `packages/sdk/dist/workflows`
+ * is built so the script can resolve `@relayflows/core`. No-op
+ * outside the monorepo or when the build is already present.
+ */
+export declare function ensureLocalSdkWorkflowRuntime(startDir: string, execRunner?: ExecFileSyncLike): void;
+/**
+ * Parse tsx's stderr for the esbuild parse-error fingerprint and extract a
+ * normalized {@link ParsedWorkflowError}. Returns null if nothing looks like
+ * a parse error — runtime errors, module-not-found, etc. pass through.
+ *
+ * We match two common esbuild output formats:
+ *   1. `/path/file.ts:LINE:COL: ERROR: message` (most common, one-liner)
+ *   2. `✘ [ERROR] message\n\n    /path/file.ts:LINE:COL:\n      LINE │ text\n           ╵ pointer`
+ *      (pretty-printed, multi-line)
+ */
+export declare function parseTsxStderr(stderr: string): ParsedWorkflowError | null;
+export declare function shouldSkipNodeStripTypesPreflight(filePath: string, seen?: Set<string>, isEntry?: boolean): boolean;
+/**
+ * Format a {@link ParsedWorkflowError} as an actionable workflow-author error
+ * message with hints keyed off the most common mistakes in `command:` /
+ * `task:` template literals.
+ */
+export declare function formatWorkflowParseError(parsed: ParsedWorkflowError): Error;
+/**
+ * Run a `.ts`, `.tsx`, or `.py` workflow script locally.
+ *
+ * For TypeScript files, tries Node's `--experimental-strip-types` first
+ * (Node 22.6+), then falls back to `tsx`, `ts-node`, and finally `npx tsx`.
+ * For Python files, tries `python3` then `python`.
+ *
+ * Throws on non-zero exit. The error message includes the run id (when
+ * the script wrote one to `AGENT_RELAY_RUN_ID_FILE`) so callers can resume
+ * with `--start-from <step> --previous-run-id <id>`.
+ */
+export declare function runScriptWorkflow(filePath: string, options?: RunScriptWorkflowOptions): Promise<void>;
+//# sourceMappingURL=run-script.d.ts.map

package/dist/run-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-script.d.ts","sourceRoot":"","sources":["../src/run-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,YAAY,EAAoC,MAAM,oBAAoB,CAAC;AAIpF,MAAM,MAAM,gBAAgB,GAAG,OAAO,YAAY,CAAC;AAEnD,MAAM,WAAW,wBAAwB;IACvC,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAwBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAwBhF;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,gBAA+B,GAC1C,IAAI,CA6BN;AAID;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CA4CzE;AAsDD,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,EAChB,IAAI,cAAoB,EACxB,OAAO,UAAO,GACb,OAAO,CAuBT;AA2ED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,mBAAmB,GAAG,KAAK,CAoD3E;AAkDD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAiKf"}