@vertesia/studio-utils 1.6.0-dev.20260923.085325Z → 1.6.0-dev.20261004.085740Z

package/src/roles/agent-runs.ts

@@ -0,0 +1,41 @@
+import { type AbacScope, Permission, type RoleDomain } from '@vertesia/common';
+import { AbacRole, type Role, type RolePartition } from './classes.js';
+
+const AgentRunRoleDomain: RoleDomain = 'agent_runs';
+
+const APPLICABLE_SCOPES: readonly AbacScope[] = ['agent_run'];
+
+/** Names of roles that grant conditional access to agent and process runs. */
+export enum AgentRunRoleNames {
+    agent_run_reader = 'agent_runs:reader',
+    agent_run_operator = 'agent_runs:operator',
+}
+
+class AgentRunReaderRole extends AbacRole {
+    constructor() {
+        // Delegating run reads requires the RBAC the run read endpoints check (`workflow:read`), not
+        // `agent_run:read`, which is the auditor-only "see every private run" capability.
+        super(AgentRunRoleNames.agent_run_reader, ['read'], AgentRunRoleDomain, APPLICABLE_SCOPES, [
+            Permission.workflow_read,
+        ]);
+    }
+}
+
+class AgentRunOperatorRole extends AbacRole {
+    constructor() {
+        super(AgentRunRoleNames.agent_run_operator, ['read', 'control'], AgentRunRoleDomain, APPLICABLE_SCOPES, [
+            Permission.workflow_read,
+            Permission.workflow_run,
+        ]);
+    }
+}
+
+const agentRunRoles: Record<AgentRunRoleNames, Role> = {
+    [AgentRunRoleNames.agent_run_reader]: new AgentRunReaderRole(),
+    [AgentRunRoleNames.agent_run_operator]: new AgentRunOperatorRole(),
+};
+
+export const agentRunPartition: RolePartition = {
+    domain: AgentRunRoleDomain,
+    roles: new Map(Object.entries(agentRunRoles)),
+};

package/src/roles/classes.ts

@@ -62,6 +62,13 @@ export class AbacRole extends Role<string> {
         permissions: string[],
         domain: RoleDomain,
         public applicableScopes: readonly AbacScope[],
+        /**
+         * The central `Permission`s a caller must hold to delegate this role through an ACE.
+         * Declared explicitly because ABAC verbs (`read`, `control`, ...) are scope vocabulary,
+         * not `Permission` values — deriving them from `${domain}:${verb}` only happens to work
+         * for the `content` domain and yields unknown keys for every other one.
+         */
+        public delegationPermissions: readonly Permission[],
     ) {
         super(name, permissions, domain);
     }

package/src/roles/content.ts

@@ -1,9 +1,16 @@
-import type { AbacScope, RoleDomain } from '@vertesia/common';
+import { type AbacScope, Permission, type RoleDomain } from '@vertesia/common';
 import { AbacRole, type Role, type RolePartition } from './classes.js';
 
 const ContentRoleDomain: RoleDomain = 'content';
 
-const APPLICABLE_SCOPES: readonly AbacScope[] = ['document', 'collection'];
+// Scopes where content can be written/managed. `shared_content` is deliberately absent — shared content
+// is read-only, so writer/manager never apply to it.
+const WRITABLE_CONTENT_SCOPES: readonly AbacScope[] = ['document', 'collection'];
+
+// content:reader additionally serves the read-only `shared_content` scope: cross-project sharing reuses
+// the content read permission — `shared_content` is a SCOPE over content (like `collection`), not its own
+// domain. Only the reader lists it, so the vocabulary can't grant write/manage on shared content.
+const READER_SCOPES: readonly AbacScope[] = [...WRITABLE_CONTENT_SCOPES, 'shared_content'];
 
 /**
  * Names of roles owned by the `content` domain. Apply to ResourceSet ACEs
@@ -18,19 +25,28 @@ export enum ContentRoleNames {
 
 class ContentReaderRole extends AbacRole {
     constructor() {
-        super(ContentRoleNames.content_reader, ['read'], ContentRoleDomain, APPLICABLE_SCOPES);
+        super(ContentRoleNames.content_reader, ['read'], ContentRoleDomain, READER_SCOPES, [Permission.content_read]);
     }
 }
 
 class ContentWriterRole extends AbacRole {
     constructor() {
-        super(ContentRoleNames.content_writer, ['read', 'write'], ContentRoleDomain, APPLICABLE_SCOPES);
+        super(ContentRoleNames.content_writer, ['read', 'write'], ContentRoleDomain, WRITABLE_CONTENT_SCOPES, [
+            Permission.content_read,
+            Permission.content_write,
+        ]);
     }
 }
 
 class ContentManagerRole extends AbacRole {
     constructor() {
-        super(ContentRoleNames.content_manager, ['read', 'write', 'delete'], ContentRoleDomain, APPLICABLE_SCOPES);
+        super(
+            ContentRoleNames.content_manager,
+            ['read', 'write', 'delete'],
+            ContentRoleDomain,
+            WRITABLE_CONTENT_SCOPES,
+            [Permission.content_read, Permission.content_write, Permission.content_delete],
+        );
     }
 }
 

package/src/roles/index.ts

@@ -1,8 +1,10 @@
 import type { AbacScope, RoleDomain } from '@vertesia/common';
+import { agentRunPartition } from './agent-runs.js';
 import { AbacRole, type Role, type RolePartition, SystemRole } from './classes.js';
 import { contentPartition } from './content.js';
 import { systemPartition } from './system.js';
 
+export { AgentRunRoleNames } from './agent-runs.js';
 export { AbacRole, Role, type RolePartition, SystemRole } from './classes.js';
 export { ContentRoleNames } from './content.js';
 
@@ -11,7 +13,7 @@ export { ContentRoleNames } from './content.js';
  * match wins. The `system` partition is registered first so domain-specific
  * partitions (added later) cannot shadow built-in system roles.
  */
-const partitions: RolePartition[] = [systemPartition, contentPartition];
+const partitions: RolePartition[] = [systemPartition, contentPartition, agentRunPartition];
 
 /** Look up a role by its name across all registered partitions. */
 export function getRoleByName(name: string): Role {
@@ -75,16 +77,16 @@ export function getPermissionsForRoles(roleNames: Iterable<string>): string[] {
 }
 
 /**
- * Return the platform permission keys a caller must hold to delegate a role.
+ * Return the platform `Permission` keys a caller must hold to delegate a role.
  *
  * System roles already contain complete `domain:verb` Permission values. ABAC roles store bare
- * verbs for content-security token generation, so map them back to their domain-qualified keys at
- * an authorization boundary.
+ * scope verbs (`read`, `control`, ...) for token generation, which are not Permission values, so
+ * they declare the Permissions that gate their delegation separately (`AbacRole.delegationPermissions`).
  */
 export function getDelegablePermissionsForRole(roleName: string): string[] {
     const role = getRoleByName(roleName);
     if (role instanceof AbacRole) {
-        return [...role.permissions].map((permission) => `${role.domain}:${permission}`);
+        return [...role.delegationPermissions];
     }
     return [...role.permissions];
 }

package/src/apps/index.test.ts

@@ -1,166 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { installStudioUtilsLogger, type StudioUtilsLogger } from '../logger.js';
-import {
-    parseGatewayAppEndpoint,
-    type ResolveAppEndpointOptions,
-    resolveAppApiBase,
-    resolveAppEndpoint,
-    resolveAppResource,
-} from './index.js';
-
-const APPS_MOUNT = 'https://gw.example.com/tenants/1589ba_149d0b/apps/my-app';
-const LEGACY_PACKAGE_MOUNT = 'https://gw.example.com/tenants/1589ba_149d0b/package/my-app';
-const PACKAGE_MOUNT = 'https://gw.example.com/tenants/1589ba_149d0b/apps/my-app/api/package';
-const VERSION_PACKAGE_MOUNT =
-    'https://gw.example.com/tenants/1589ba_149d0b/apps/my-app/versions/20260101T000000Z/api/package';
-
-function resolve(
-    endpoint: string,
-    options: ResolveAppEndpointOptions = {},
-    endpoint_overrides?: Record<string, string>,
-): string | undefined {
-    return resolveAppEndpoint({ endpoint, endpoint_overrides }, options);
-}
-
-describe('app endpoint resolution', () => {
-    it('parses gateway app endpoint shapes', () => {
-        expect(parseGatewayAppEndpoint(APPS_MOUNT)).toEqual({
-            origin: 'https://gw.example.com',
-            tenant: '1589ba_149d0b',
-            appId: 'my-app',
-        });
-        expect(parseGatewayAppEndpoint(LEGACY_PACKAGE_MOUNT)).toEqual({
-            origin: 'https://gw.example.com',
-            tenant: '1589ba_149d0b',
-            appId: 'my-app',
-        });
-        expect(parseGatewayAppEndpoint(VERSION_PACKAGE_MOUNT)).toEqual({
-            origin: 'https://gw.example.com',
-            tenant: '1589ba_149d0b',
-            appId: 'my-app',
-            version: '20260101T000000Z',
-        });
-        expect(parseGatewayAppEndpoint('https://third-party.example.com/api/package')).toBeUndefined();
-    });
-
-    it('normalizes gateway app endpoints to canonical package URLs', () => {
-        expect(resolve(APPS_MOUNT)).toBe(PACKAGE_MOUNT);
-        expect(resolve(LEGACY_PACKAGE_MOUNT)).toBe(PACKAGE_MOUNT);
-        expect(resolve(PACKAGE_MOUNT)).toBe(PACKAGE_MOUNT);
-    });
-
-    it('normalizes gateway app endpoints to version-pinned package URLs', () => {
-        expect(resolve(APPS_MOUNT, { version: '20260101T000000Z' })).toBe(VERSION_PACKAGE_MOUNT);
-        expect(resolve(LEGACY_PACKAGE_MOUNT, { version: '20260101T000000Z' })).toBe(VERSION_PACKAGE_MOUNT);
-        expect(resolve(PACKAGE_MOUNT, { version: '20260101T000000Z' })).toBe(VERSION_PACKAGE_MOUNT);
-    });
-
-    it('ignores endpoint overrides for gateway apps', () => {
-        const endpoint_overrides = {
-            '20260101T000000Z': 'https://plugin.example.com/releases/20260101T000000Z/package',
-            dev: 'https://plugin.example.com/dev/package',
-        };
-
-        expect(resolve(APPS_MOUNT, { version: '20260101T000000Z', envName: 'dev' }, endpoint_overrides)).toBe(
-            VERSION_PACKAGE_MOUNT,
-        );
-        expect(resolve(APPS_MOUNT, { envName: 'dev' }, endpoint_overrides)).toBe(PACKAGE_MOUNT);
-    });
-
-    it('uses endpoint overrides in version, requested override, environment, endpoint order', () => {
-        const endpoint_overrides = {
-            '1.2.3': 'https://plugin.example.com/releases/1.2.3/package',
-            dev: 'https://plugin.example.com/dev/package',
-            desktop: 'https://plugin.example.com/desktop/package',
-        };
-
-        expect(
-            resolve('https://plugin.example.com/api/package', { version: '1.2.3', envName: 'dev' }, endpoint_overrides),
-        ).toBe('https://plugin.example.com/releases/1.2.3/package');
-        expect(
-            resolve(
-                'https://plugin.example.com/api/package',
-                { requestedOverride: 'desktop', envName: 'dev' },
-                endpoint_overrides,
-            ),
-        ).toBe('https://plugin.example.com/desktop/package');
-        expect(resolve('https://plugin.example.com/api/package', { envName: 'dev' }, endpoint_overrides)).toBe(
-            'https://plugin.example.com/dev/package',
-        );
-        expect(resolve('https://plugin.example.com/api/package', {}, endpoint_overrides)).toBe(
-            'https://plugin.example.com/api/package',
-        );
-    });
-
-    it('does not use endpoint overrides without a base endpoint', () => {
-        expect(
-            resolveAppEndpoint(
-                {
-                    endpoint: undefined,
-                    endpoint_overrides: {
-                        dev: 'https://plugin.example.com/dev/package',
-                    },
-                },
-                { envName: 'dev' },
-            ),
-        ).toBeUndefined();
-    });
-
-    it('substitutes endpoint variables before gateway normalization', () => {
-        expect(
-            resolve('{{gateway}}/tenants/1589ba_149d0b/package/my-app', {
-                vars: { gateway: 'https://gw.example.com/' },
-            }),
-        ).toBe(PACKAGE_MOUNT);
-    });
-
-    it('leaves regular package endpoints unchanged', () => {
-        expect(resolve('https://third-party.example.com/api/package')).toBe(
-            'https://third-party.example.com/api/package',
-        );
-    });
-
-    it('leaves non-standard package endpoints unchanged and warns', () => {
-        const logger: StudioUtilsLogger = {
-            warn: vi.fn(),
-        };
-        const previousLogger = installStudioUtilsLogger(logger);
-
-        expect(resolve('https://third-party.example.com/exotic/pkg')).toBe(
-            'https://third-party.example.com/exotic/pkg',
-        );
-        expect(logger.warn).toHaveBeenCalledWith(
-            { endpoint: 'https://third-party.example.com/exotic/pkg' },
-            'Non-standard app package endpoint; returning it unchanged during app endpoint resolution',
-        );
-
-        installStudioUtilsLogger(previousLogger);
-    });
-});
-
-describe('app API base resolution', () => {
-    it('derives the API base by removing the final package URL segment', () => {
-        expect(resolveAppApiBase('https://third-party.example.com/api/package')).toBe(
-            'https://third-party.example.com/api',
-        );
-        expect(resolveAppApiBase('https://third-party.example.com/exotic/pkg')).toBe(
-            'https://third-party.example.com/exotic',
-        );
-        expect(resolveAppApiBase(PACKAGE_MOUNT)).toBe('https://gw.example.com/tenants/1589ba_149d0b/apps/my-app/api');
-        expect(resolveAppApiBase(VERSION_PACKAGE_MOUNT)).toBe(
-            'https://gw.example.com/tenants/1589ba_149d0b/apps/my-app/versions/20260101T000000Z/api',
-        );
-    });
-
-    it('resolves API-relative resource paths from package endpoints', () => {
-        expect(resolveAppResource('https://third-party.example.com/api/package', 'tools/main')).toBe(
-            'https://third-party.example.com/api/tools/main',
-        );
-        expect(resolveAppResource(PACKAGE_MOUNT, '/interactions/main/hello')).toBe(
-            'https://gw.example.com/tenants/1589ba_149d0b/apps/my-app/api/interactions/main/hello',
-        );
-        expect(resolveAppResource(VERSION_PACKAGE_MOUNT, 'templates/invoice')).toBe(
-            'https://gw.example.com/tenants/1589ba_149d0b/apps/my-app/versions/20260101T000000Z/api/templates/invoice',
-        );
-    });
-});

package/src/conditions/match.test.ts

@@ -1,134 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { installStudioUtilsLogger, type StudioUtilsLogger } from '../logger.js';
-import { matchConditions, matchLike, resolveConditions, resolvePath } from './index.js';
-
-describe('resolvePath', () => {
-    it('resolves top-level fields and one-level properties fields', () => {
-        const value = {
-            clearance: 3,
-            properties: {
-                department: 'engineering',
-            },
-        };
-
-        expect(resolvePath(value, 'clearance')).toBe(3);
-        expect(resolvePath(value, 'properties.department')).toBe('engineering');
-        expect(resolvePath(value, 'properties.missing')).toBeUndefined();
-        expect(resolvePath({ clearance: 3 }, 'properties.department')).toBeUndefined();
-    });
-});
-
-describe('matchLike', () => {
-    it('matches wildcard string patterns case-insensitively', () => {
-        expect(matchLike('bogdan+test@vertesiahq.com', '*+test*@VERTESIAHQ.COM')).toBe(true);
-        expect(matchLike('bogdan@gmail.com', '*@vertesiahq.com')).toBe(false);
-        expect(matchLike(42, '*')).toBe(false);
-    });
-});
-
-describe('matchConditions', () => {
-    it('matches direct values and operator objects', () => {
-        const properties = {
-            active: true,
-            clearance: 5,
-            compartments: ['engineering'],
-            email: 'bogdan@vertesiahq.com',
-            properties: {
-                department: 'engineering',
-            },
-        };
-
-        expect(
-            matchConditions(
-                {
-                    active: true,
-                    clearance: { $gte: 3, $lte: 5 },
-                    compartments: { $empty: false },
-                    email: { $like: '*@vertesiahq.com' },
-                    'properties.department': { $in: ['engineering', 'product'] },
-                },
-                properties,
-            ),
-        ).toBe(true);
-    });
-
-    it('requires ordered comparisons to use matching primitive types', () => {
-        expect(matchConditions({ clearance: { $gt: 3 } }, { clearance: 5 })).toBe(true);
-        expect(matchConditions({ clearance: { $gt: 3 } }, { clearance: '5' })).toBe(false);
-        expect(matchConditions({ code: { $gt: 'a' } }, { code: 'b' })).toBe(true);
-    });
-
-    it('matches set operators against scalar and array-valued object fields', () => {
-        expect(
-            matchConditions({ compartments: { $in: ['finance', 'legal'] } }, { compartments: ['hr', 'finance'] }),
-        ).toBe(true);
-        expect(matchConditions({ compartments: { $in: ['finance'] } }, { compartments: ['hr'] })).toBe(false);
-        expect(matchConditions({ compartments: { $nin: ['finance'] } }, { compartments: ['hr'] })).toBe(true);
-        expect(matchConditions({ compartments: { $nin: ['finance'] } }, { compartments: ['hr', 'finance'] })).toBe(
-            false,
-        );
-    });
-
-    it('uses Mongo-compatible equality for scalar conditions on array-valued fields', () => {
-        expect(matchConditions({ tags: 'finance' }, { tags: ['audit', 'finance'] })).toBe(true);
-        expect(matchConditions({ tags: { $eq: 'finance' } }, { tags: ['audit', 'finance'] })).toBe(true);
-        expect(matchConditions({ tags: { $ne: 'finance' } }, { tags: ['audit', 'finance'] })).toBe(false);
-    });
-
-    it('treats unknown operators as non-matches', () => {
-        const logger: StudioUtilsLogger = {
-            warn: vi.fn(),
-        };
-        const previousLogger = installStudioUtilsLogger(logger);
-
-        expect(matchConditions({ clearance: { $unknown: 3 } }, { clearance: 5 })).toBe(false);
-        expect(logger.warn).toHaveBeenCalledWith(
-            { op: '$unknown', key: 'clearance' },
-            'Unknown operator in PropertyConditions',
-        );
-
-        installStudioUtilsLogger(previousLogger);
-    });
-});
-
-describe('resolveConditions', () => {
-    it('resolves scalar and array principal references', () => {
-        expect(
-            resolveConditions(
-                {
-                    sensitivity: { $lte: '$principal.clearance' },
-                    compartments: { $in: '$principal.compartments' },
-                    'properties.department': '$principal.properties.department',
-                },
-                {
-                    clearance: 3,
-                    compartments: ['finance'],
-                    properties: { department: 'finance' },
-                },
-            ),
-        ).toEqual({
-            sensitivity: { $lte: 3 },
-            compartments: { $in: ['finance'] },
-            'properties.department': 'finance',
-        });
-    });
-
-    it('uses deterministic defaults for missing principal fields', () => {
-        expect(
-            resolveConditions(
-                {
-                    sensitivity: { $lte: '$principal.clearance' },
-                    compartments: { $in: '$principal.compartments' },
-                    active: { $exists: '$principal.active' },
-                    department: '$principal.properties.department',
-                },
-                {},
-            ),
-        ).toEqual({
-            sensitivity: { $lte: 0 },
-            compartments: { $in: [] },
-            active: { $exists: false },
-            department: '',
-        });
-    });
-});

package/src/prompts/render.test.ts

@@ -1,110 +0,0 @@
-import { PromptRole } from '@llumiverse/common';
-import {
-    type PromptSegmentDef,
-    PromptSegmentDefType,
-    PromptStatus,
-    type PromptTemplate,
-    TemplateType,
-} from '@vertesia/common';
-import { describe, expect, it } from 'vitest';
-
-import { renderSegments, renderTemplate } from './render.js';
-
-describe('renderTemplate', () => {
-    it('returns text content verbatim instead of evaluating it as JST', () => {
-        const content = 'You are a test assistant for skill validation. Be concise.';
-        expect(renderTemplate(content, TemplateType.text, {}, {})).toEqual(content);
-    });
-
-    it('renders handlebars templates', () => {
-        expect(renderTemplate('Hello {{name}}', TemplateType.handlebars, {}, { name: 'Ada' })).toEqual('Hello Ada');
-    });
-
-    it('renders JST templates', () => {
-        expect(
-            renderTemplate('return `Hello ${name}`', TemplateType.jst, { properties: { name: {} } }, { name: 'Ada' }),
-        ).toEqual('Hello Ada');
-    });
-});
-
-describe('renderSegments', () => {
-    it('renders a text system segment followed by a handlebars user segment', () => {
-        const segments: PromptSegmentDef<PromptTemplate>[] = [
-            {
-                type: PromptSegmentDefType.template,
-                template: createPromptTemplate({
-                    id: 'sys-1',
-                    role: PromptRole.system,
-                    content: 'You are a test assistant for skill validation. Be concise.',
-                    content_type: TemplateType.text,
-                }),
-            },
-            {
-                type: PromptSegmentDefType.template,
-                template: createPromptTemplate({
-                    id: 'user-1',
-                    role: PromptRole.user,
-                    content: 'Answer this question: {{question}}',
-                    content_type: TemplateType.handlebars,
-                }),
-            },
-        ];
-
-        expect(renderSegments(segments, { question: 'What is 2+2?' })).toEqual([
-            {
-                title: '@system',
-                content: 'You are a test assistant for skill validation. Be concise.',
-                segmentId: 'sys-1',
-            },
-            {
-                title: '@user',
-                content: 'Answer this question: What is 2+2?',
-                segmentId: 'user-1',
-            },
-        ]);
-    });
-
-    it('isolates a failing segment so the remaining segments still render', () => {
-        const segments: PromptSegmentDef<PromptTemplate>[] = [
-            {
-                type: PromptSegmentDefType.template,
-                template: createPromptTemplate({
-                    id: 'bad-1',
-                    content: 'return missingGlobal',
-                    content_type: TemplateType.jst,
-                }),
-            },
-            {
-                type: PromptSegmentDefType.template,
-                template: createPromptTemplate({
-                    id: 'good-1',
-                    content: 'Hello {{name}}',
-                    content_type: TemplateType.handlebars,
-                }),
-            },
-        ];
-
-        const result = renderSegments(segments, { name: 'Ada' });
-        expect(result[0].error).toBeInstanceOf(Error);
-        expect(result[1]).toEqual({ title: '@user', content: 'Hello Ada', segmentId: 'good-1' });
-    });
-});
-
-function createPromptTemplate(overrides: Partial<PromptTemplate>): PromptTemplate {
-    return {
-        id: 'prompt-1',
-        name: 'Greeting',
-        role: PromptRole.user,
-        status: PromptStatus.draft,
-        version: 1,
-        edit_revision: 1,
-        content: '',
-        content_type: TemplateType.jst,
-        project: 'project-1',
-        created_by: 'user-1',
-        updated_by: 'user-1',
-        created_at: '2026-01-01T00:00:00.000Z',
-        updated_at: '2026-01-01T00:00:00.000Z',
-        ...overrides,
-    };
-}