Merge pull request 'feat(ai-roles): импортируемый мультиязычный каталог ролей агента' (#222) from feature/agent-roles-catalog into develop
Reviewed-on: #222
This commit was merged in pull request #222.
This commit is contained in:
@@ -39,6 +39,10 @@ describe('AiAgentRolesController admin gate', () => {
|
||||
create: jest.fn().mockResolvedValue({ id: 'r1' }),
|
||||
update: jest.fn().mockResolvedValue({ id: 'r1' }),
|
||||
remove: jest.fn().mockResolvedValue({ success: true }),
|
||||
getCatalog: jest.fn().mockResolvedValue({ languages: [], bundles: [] }),
|
||||
getCatalogBundle: jest.fn().mockResolvedValue({ roles: [] }),
|
||||
importFromCatalog: jest.fn().mockResolvedValue({ created: 0 }),
|
||||
updateFromCatalog: jest.fn().mockResolvedValue({ updated: false }),
|
||||
};
|
||||
const controller = new AiAgentRolesController(
|
||||
rolesService as never,
|
||||
@@ -109,6 +113,90 @@ describe('AiAgentRolesController admin gate', () => {
|
||||
});
|
||||
});
|
||||
|
||||
// Catalog routes (browse + import) are ALL admin-only: a non-admin caller must
|
||||
// get ForbiddenException with the service untouched; an admin delegates with
|
||||
// the right arguments (import/update-from-catalog carry workspace.id).
|
||||
describe('catalog routes admin gate', () => {
|
||||
const catalogDto = { language: 'en' } as never;
|
||||
const bundleDto = { bundleId: 'general', language: 'en' } as never;
|
||||
const importDto = {
|
||||
bundleId: 'general',
|
||||
language: 'en',
|
||||
conflict: 'skip',
|
||||
} as never;
|
||||
const updateDto = { id: 'r1' } as never;
|
||||
|
||||
describe('non-admin is rejected and the service is NOT called', () => {
|
||||
it('catalog', async () => {
|
||||
const { controller, rolesService } = makeController(false);
|
||||
await expect(
|
||||
controller.catalog(catalogDto, user, workspace),
|
||||
).rejects.toBeInstanceOf(ForbiddenException);
|
||||
expect(rolesService.getCatalog).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('catalog/bundle', async () => {
|
||||
const { controller, rolesService } = makeController(false);
|
||||
await expect(
|
||||
controller.catalogBundle(bundleDto, user, workspace),
|
||||
).rejects.toBeInstanceOf(ForbiddenException);
|
||||
expect(rolesService.getCatalogBundle).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('import', async () => {
|
||||
const { controller, rolesService } = makeController(false);
|
||||
await expect(
|
||||
controller.import(importDto, user, workspace),
|
||||
).rejects.toBeInstanceOf(ForbiddenException);
|
||||
expect(rolesService.importFromCatalog).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('update-from-catalog', async () => {
|
||||
const { controller, rolesService } = makeController(false);
|
||||
await expect(
|
||||
controller.updateFromCatalog(updateDto, user, workspace),
|
||||
).rejects.toBeInstanceOf(ForbiddenException);
|
||||
expect(rolesService.updateFromCatalog).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('admin delegates to the service', () => {
|
||||
it('catalog passes the requested language', async () => {
|
||||
const { controller, rolesService } = makeController(true);
|
||||
await controller.catalog(catalogDto, user, workspace);
|
||||
expect(rolesService.getCatalog).toHaveBeenCalledWith('en');
|
||||
});
|
||||
|
||||
it('catalog/bundle passes bundleId + language', async () => {
|
||||
const { controller, rolesService } = makeController(true);
|
||||
await controller.catalogBundle(bundleDto, user, workspace);
|
||||
expect(rolesService.getCatalogBundle).toHaveBeenCalledWith(
|
||||
'general',
|
||||
'en',
|
||||
);
|
||||
});
|
||||
|
||||
it('import passes workspace.id + user.id + dto', async () => {
|
||||
const { controller, rolesService } = makeController(true);
|
||||
await controller.import(importDto, user, workspace);
|
||||
expect(rolesService.importFromCatalog).toHaveBeenCalledWith(
|
||||
'ws-1',
|
||||
'u1',
|
||||
importDto,
|
||||
);
|
||||
});
|
||||
|
||||
it('update-from-catalog passes workspace.id + dto', async () => {
|
||||
const { controller, rolesService } = makeController(true);
|
||||
await controller.updateFromCatalog(updateDto, user, workspace);
|
||||
expect(rolesService.updateFromCatalog).toHaveBeenCalledWith(
|
||||
'ws-1',
|
||||
updateDto,
|
||||
);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('list (member-reachable)', () => {
|
||||
it('non-admin reaches list and the service is asked for the picker view (isAdmin=false)', async () => {
|
||||
const { controller, rolesService } = makeController(false);
|
||||
|
||||
@@ -22,6 +22,12 @@ import {
|
||||
CreateAgentRoleDto,
|
||||
UpdateAgentRoleDto,
|
||||
} from './dto/agent-role.dto';
|
||||
import {
|
||||
CatalogBundleDto,
|
||||
CatalogQueryDto,
|
||||
ImportFromCatalogDto,
|
||||
UpdateFromCatalogDto,
|
||||
} from './dto/agent-role-catalog.dto';
|
||||
|
||||
/** Path/body param for the per-role routes (update/delete). */
|
||||
class AgentRoleIdDto {
|
||||
@@ -113,4 +119,54 @@ export class AiAgentRolesController {
|
||||
this.assertAdmin(user, workspace);
|
||||
return this.rolesService.remove(workspace.id, idDto.id);
|
||||
}
|
||||
|
||||
// --- Catalog (admin-only): browse + import + update imported roles. ---
|
||||
|
||||
/** Browse the curated catalog (localized to dto.language). */
|
||||
@HttpCode(HttpStatus.OK)
|
||||
@Post('catalog')
|
||||
async catalog(
|
||||
@Body() dto: CatalogQueryDto,
|
||||
@AuthUser() user: User,
|
||||
@AuthWorkspace() workspace: Workspace,
|
||||
) {
|
||||
this.assertAdmin(user, workspace);
|
||||
return this.rolesService.getCatalog(dto.language);
|
||||
}
|
||||
|
||||
/** Open one catalog bundle in a language (role content + versions). */
|
||||
@HttpCode(HttpStatus.OK)
|
||||
@Post('catalog/bundle')
|
||||
async catalogBundle(
|
||||
@Body() dto: CatalogBundleDto,
|
||||
@AuthUser() user: User,
|
||||
@AuthWorkspace() workspace: Workspace,
|
||||
) {
|
||||
this.assertAdmin(user, workspace);
|
||||
return this.rolesService.getCatalogBundle(dto.bundleId, dto.language);
|
||||
}
|
||||
|
||||
/** Import roles from a catalog bundle into the workspace. */
|
||||
@HttpCode(HttpStatus.OK)
|
||||
@Post('import')
|
||||
async import(
|
||||
@Body() dto: ImportFromCatalogDto,
|
||||
@AuthUser() user: User,
|
||||
@AuthWorkspace() workspace: Workspace,
|
||||
) {
|
||||
this.assertAdmin(user, workspace);
|
||||
return this.rolesService.importFromCatalog(workspace.id, user.id, dto);
|
||||
}
|
||||
|
||||
/** Update an already-imported role from its catalog source. */
|
||||
@HttpCode(HttpStatus.OK)
|
||||
@Post('update-from-catalog')
|
||||
async updateFromCatalog(
|
||||
@Body() dto: UpdateFromCatalogDto,
|
||||
@AuthUser() user: User,
|
||||
@AuthWorkspace() workspace: Workspace,
|
||||
) {
|
||||
this.assertAdmin(user, workspace);
|
||||
return this.rolesService.updateFromCatalog(workspace.id, dto);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,16 +1,19 @@
|
||||
import { Module } from '@nestjs/common';
|
||||
import { AiAgentRolesController } from './ai-agent-roles.controller';
|
||||
import { AiAgentRolesService } from './ai-agent-roles.service';
|
||||
import { AiAgentRolesCatalogProvider } from './catalog/ai-agent-roles-catalog.provider';
|
||||
|
||||
/**
|
||||
* Agent roles unit (v1). Admin CRUD + member-visible listing for the chat
|
||||
* role picker. AiAgentRoleRepo (DatabaseModule, global) and
|
||||
* WorkspaceAbilityFactory (CaslModule, global) are resolved without explicit
|
||||
* imports. The stream-time role resolution + model override live in
|
||||
* AiChatService / AiService; this module only hosts the management API.
|
||||
* role picker, plus the admin catalog (browse/import/update). AiAgentRoleRepo
|
||||
* (DatabaseModule, global), WorkspaceAbilityFactory (CaslModule, global) and
|
||||
* EnvironmentService (EnvironmentModule, global — used by the catalog provider)
|
||||
* are resolved without explicit imports. The stream-time role resolution +
|
||||
* model override live in AiChatService / AiService; this module only hosts the
|
||||
* management API.
|
||||
*/
|
||||
@Module({
|
||||
controllers: [AiAgentRolesController],
|
||||
providers: [AiAgentRolesService],
|
||||
providers: [AiAgentRolesService, AiAgentRolesCatalogProvider],
|
||||
})
|
||||
export class AiAgentRolesModule {}
|
||||
|
||||
@@ -1,4 +1,9 @@
|
||||
import { BadRequestException, ConflictException } from '@nestjs/common';
|
||||
import {
|
||||
BadGatewayException,
|
||||
BadRequestException,
|
||||
ConflictException,
|
||||
Logger,
|
||||
} from '@nestjs/common';
|
||||
import { AiAgentRolesService } from './ai-agent-roles.service';
|
||||
import type { AiAgentRole } from '@docmost/db/types/entity.types';
|
||||
import type {
|
||||
@@ -27,12 +32,22 @@ describe('AiAgentRolesService guards', () => {
|
||||
enabled: true,
|
||||
autoStart: true,
|
||||
launchMessage: null,
|
||||
source: null,
|
||||
createdAt: new Date(),
|
||||
updatedAt: new Date(),
|
||||
...over,
|
||||
} as AiAgentRole;
|
||||
}
|
||||
|
||||
// A stubbed catalog provider; the CRUD tests never reach it (they exercise
|
||||
// create/update/remove/list only), so the methods just reject if hit.
|
||||
function makeCatalog() {
|
||||
return {
|
||||
fetchIndex: jest.fn(),
|
||||
fetchBundle: jest.fn(),
|
||||
};
|
||||
}
|
||||
|
||||
function makeService(opts: { existing?: AiAgentRole | undefined } = {}) {
|
||||
const repo = {
|
||||
findById: jest.fn().mockResolvedValue(opts.existing),
|
||||
@@ -41,8 +56,9 @@ describe('AiAgentRolesService guards', () => {
|
||||
softDelete: jest.fn().mockResolvedValue(undefined),
|
||||
listByWorkspace: jest.fn().mockResolvedValue([]),
|
||||
};
|
||||
const service = new AiAgentRolesService(repo as never);
|
||||
return { service, repo };
|
||||
const catalog = makeCatalog();
|
||||
const service = new AiAgentRolesService(repo as never, catalog as never);
|
||||
return { service, repo, catalog };
|
||||
}
|
||||
|
||||
describe('update', () => {
|
||||
@@ -163,6 +179,7 @@ describe('AiAgentRolesService guards', () => {
|
||||
enabled: false,
|
||||
autoStart: true,
|
||||
launchMessage: null,
|
||||
source: null,
|
||||
createdAt,
|
||||
updatedAt,
|
||||
});
|
||||
@@ -397,7 +414,7 @@ describe('AiAgentRolesService guards', () => {
|
||||
softDelete: jest.fn(),
|
||||
listByWorkspace: jest.fn().mockResolvedValue(rows),
|
||||
};
|
||||
const service = new AiAgentRolesService(repo as never);
|
||||
const service = new AiAgentRolesService(repo as never, makeCatalog() as never);
|
||||
return { service, repo };
|
||||
}
|
||||
|
||||
@@ -461,4 +478,630 @@ describe('AiAgentRolesService guards', () => {
|
||||
).rejects.toBeInstanceOf(ConflictException);
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Catalog: import (skip / rename / already-installed) and update reconciliation
|
||||
// against a MOCKED catalog provider + mocked repo (mirrors the CRUD style).
|
||||
// ---------------------------------------------------------------------------
|
||||
describe('importFromCatalog', () => {
|
||||
function catalogRole(over: Record<string, unknown> = {}) {
|
||||
return {
|
||||
slug: 'researcher',
|
||||
name: 'Researcher',
|
||||
instructions: 'be a researcher',
|
||||
...over,
|
||||
};
|
||||
}
|
||||
|
||||
function makeImportService(opts: {
|
||||
indexRoles?: { slug: string; version: number }[];
|
||||
bundleRoles?: Record<string, unknown>[];
|
||||
existing?: AiAgentRole[];
|
||||
}) {
|
||||
const index = {
|
||||
schemaVersion: 1,
|
||||
bundles: [
|
||||
{
|
||||
id: 'general',
|
||||
name: { en: 'General' },
|
||||
languages: ['en'],
|
||||
roles: opts.indexRoles ?? [{ slug: 'researcher', version: 3 }],
|
||||
},
|
||||
],
|
||||
};
|
||||
const bundle = {
|
||||
schemaVersion: 1,
|
||||
language: 'en',
|
||||
roles: opts.bundleRoles ?? [catalogRole()],
|
||||
};
|
||||
const repo = {
|
||||
findById: jest.fn(),
|
||||
insert: jest.fn().mockImplementation((v) => Promise.resolve(makeRow(v))),
|
||||
update: jest.fn().mockResolvedValue(undefined),
|
||||
softDelete: jest.fn(),
|
||||
listByWorkspace: jest.fn().mockResolvedValue(opts.existing ?? []),
|
||||
};
|
||||
const catalog = {
|
||||
fetchIndex: jest.fn().mockResolvedValue(index),
|
||||
fetchBundle: jest.fn().mockResolvedValue(bundle),
|
||||
};
|
||||
const service = new AiAgentRolesService(repo as never, catalog as never);
|
||||
return { service, repo, catalog };
|
||||
}
|
||||
|
||||
const dto = (over: Record<string, unknown> = {}) =>
|
||||
({
|
||||
bundleId: 'general',
|
||||
language: 'en',
|
||||
conflict: 'skip',
|
||||
...over,
|
||||
}) as never;
|
||||
|
||||
it('inserts a new role with source { slug, language, version } from the index', async () => {
|
||||
const { service, repo } = makeImportService({});
|
||||
const res = await service.importFromCatalog('ws-1', 'u1', dto());
|
||||
expect(res).toMatchObject({ created: 1, skipped: 0, renamed: 0 });
|
||||
expect(res.errors).toEqual([]);
|
||||
const values = repo.insert.mock.calls[0][0];
|
||||
expect(values.source).toEqual({
|
||||
slug: 'researcher',
|
||||
language: 'en',
|
||||
version: 3,
|
||||
});
|
||||
expect(values.enabled).toBe(true);
|
||||
});
|
||||
|
||||
it('already-installed catalog slug => skipped (no insert)', async () => {
|
||||
const existing = [
|
||||
makeRow({
|
||||
id: 'r-existing',
|
||||
name: 'Old researcher',
|
||||
source: { slug: 'researcher', language: 'en', version: 1 } as never,
|
||||
}),
|
||||
];
|
||||
const { service, repo } = makeImportService({ existing });
|
||||
const res = await service.importFromCatalog('ws-1', 'u1', dto());
|
||||
expect(res).toMatchObject({ created: 0, skipped: 1, renamed: 0 });
|
||||
expect(repo.insert).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('same slug installed in a DIFFERENT language => NOT skipped (separate install)', async () => {
|
||||
// Installed as `ru`; importing the `en` variant of the same slug must
|
||||
// still import (dedup key is slug+language, matching the client UI).
|
||||
const existing = [
|
||||
makeRow({
|
||||
id: 'r-ru',
|
||||
name: 'Исследователь',
|
||||
source: { slug: 'researcher', language: 'ru', version: 1 } as never,
|
||||
}),
|
||||
];
|
||||
const { service, repo } = makeImportService({ existing });
|
||||
const res = await service.importFromCatalog('ws-1', 'u1', dto());
|
||||
expect(res).toMatchObject({ created: 1, skipped: 0, renamed: 0 });
|
||||
expect(repo.insert).toHaveBeenCalledTimes(1);
|
||||
expect(repo.insert.mock.calls[0][0].source).toEqual({
|
||||
slug: 'researcher',
|
||||
language: 'en',
|
||||
version: 3,
|
||||
});
|
||||
});
|
||||
|
||||
it('name collision + conflict:skip => skipped (no insert)', async () => {
|
||||
const existing = [makeRow({ id: 'r-x', name: 'Researcher' })];
|
||||
const { service, repo } = makeImportService({ existing });
|
||||
const res = await service.importFromCatalog(
|
||||
'ws-1',
|
||||
'u1',
|
||||
dto({ conflict: 'skip' }),
|
||||
);
|
||||
expect(res).toMatchObject({ created: 0, skipped: 1, renamed: 0 });
|
||||
expect(repo.insert).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('name collision + conflict:rename => inserts under " (2)"', async () => {
|
||||
const existing = [makeRow({ id: 'r-x', name: 'Researcher' })];
|
||||
const { service, repo } = makeImportService({ existing });
|
||||
const res = await service.importFromCatalog(
|
||||
'ws-1',
|
||||
'u1',
|
||||
dto({ conflict: 'rename' }),
|
||||
);
|
||||
expect(res).toMatchObject({ created: 1, skipped: 0, renamed: 1 });
|
||||
expect(repo.insert.mock.calls[0][0].name).toBe('Researcher (2)');
|
||||
});
|
||||
|
||||
it('dto.slugs filters; an unknown slug becomes an error entry', async () => {
|
||||
const { service, repo } = makeImportService({
|
||||
bundleRoles: [catalogRole()],
|
||||
});
|
||||
const res = await service.importFromCatalog(
|
||||
'ws-1',
|
||||
'u1',
|
||||
dto({ slugs: ['researcher', 'ghost'] }),
|
||||
);
|
||||
expect(res.created).toBe(1);
|
||||
expect(res.errors).toEqual([
|
||||
{ slug: 'ghost', message: 'Role not found in catalog bundle' },
|
||||
]);
|
||||
expect(repo.insert).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it('insert unique-violation (23505) is recorded as an error, import continues', async () => {
|
||||
const { service, repo } = makeImportService({
|
||||
bundleRoles: [
|
||||
catalogRole({ slug: 'a', name: 'A' }),
|
||||
catalogRole({ slug: 'b', name: 'B' }),
|
||||
],
|
||||
indexRoles: [
|
||||
{ slug: 'a', version: 1 },
|
||||
{ slug: 'b', version: 1 },
|
||||
],
|
||||
});
|
||||
repo.insert
|
||||
.mockRejectedValueOnce({ code: '23505' })
|
||||
.mockImplementationOnce((v) => Promise.resolve(makeRow(v)));
|
||||
const res = await service.importFromCatalog('ws-1', 'u1', dto());
|
||||
expect(res.created).toBe(1);
|
||||
expect(res.errors).toEqual([
|
||||
{ slug: 'a', message: 'A role with this name already exists' },
|
||||
]);
|
||||
});
|
||||
|
||||
it('source-uniqueness 23505 (concurrent import of same slug+language) => skipped, NOT an error, batch continues', async () => {
|
||||
// Two parallel imports of the same bundle each build installedKeys from a
|
||||
// stale snapshot, so both reach the insert for slug 'a'. The DB partial
|
||||
// unique index on (workspace, source->>slug, source->>language) rejects the
|
||||
// loser with a 23505 carrying the source-index constraint name. That must
|
||||
// be treated as "already installed" (skip), not a per-role error, and the
|
||||
// rest of the batch (slug 'b') must still import.
|
||||
const { service, repo } = makeImportService({
|
||||
bundleRoles: [
|
||||
catalogRole({ slug: 'a', name: 'A' }),
|
||||
catalogRole({ slug: 'b', name: 'B' }),
|
||||
],
|
||||
indexRoles: [
|
||||
{ slug: 'a', version: 1 },
|
||||
{ slug: 'b', version: 1 },
|
||||
],
|
||||
});
|
||||
// The kysely-postgres-js driver surfaces the violated constraint on
|
||||
// `constraint_name` (not node-postgres' `.constraint`), matching prod.
|
||||
const sourceRace = Object.assign(new Error('duplicate key'), {
|
||||
code: '23505',
|
||||
constraint_name: 'ai_agent_roles_workspace_source_unique',
|
||||
});
|
||||
repo.insert
|
||||
.mockRejectedValueOnce(sourceRace)
|
||||
.mockImplementationOnce((v) => Promise.resolve(makeRow(v)));
|
||||
const res = await service.importFromCatalog('ws-1', 'u1', dto());
|
||||
// 'a' converged on the concurrent install (skip); 'b' imported; no errors.
|
||||
expect(res).toMatchObject({ created: 1, skipped: 1, renamed: 0 });
|
||||
expect(res.errors).toEqual([]);
|
||||
// Both inserts were attempted (the batch did not abort on the 23505).
|
||||
expect(repo.insert).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it('non-unique insert error => generic message, root cause logged, import continues', async () => {
|
||||
const logSpy = jest
|
||||
.spyOn(Logger.prototype, 'error')
|
||||
.mockImplementation(() => undefined);
|
||||
try {
|
||||
const { service, repo } = makeImportService({
|
||||
bundleRoles: [
|
||||
catalogRole({ slug: 'a', name: 'A' }),
|
||||
catalogRole({ slug: 'b', name: 'B' }),
|
||||
],
|
||||
indexRoles: [
|
||||
{ slug: 'a', version: 1 },
|
||||
{ slug: 'b', version: 1 },
|
||||
],
|
||||
});
|
||||
// A non-23505 failure (e.g. a not-null violation) on the first insert.
|
||||
const boom = Object.assign(new Error('null value in column'), {
|
||||
code: '23502',
|
||||
});
|
||||
repo.insert
|
||||
.mockRejectedValueOnce(boom)
|
||||
.mockImplementationOnce((v) => Promise.resolve(makeRow(v)));
|
||||
const res = await service.importFromCatalog('ws-1', 'u1', dto());
|
||||
// The generic (non-409) user-facing message; the second role still imports.
|
||||
expect(res.created).toBe(1);
|
||||
expect(res.errors).toEqual([
|
||||
{ slug: 'a', message: 'Failed to import role' },
|
||||
]);
|
||||
// The root cause was logged with the slug for diagnosis.
|
||||
expect(logSpy).toHaveBeenCalledTimes(1);
|
||||
expect(String(logSpy.mock.calls[0][0])).toContain('slug=a');
|
||||
} finally {
|
||||
logSpy.mockRestore();
|
||||
}
|
||||
});
|
||||
|
||||
it('bundleId absent from the index => BadGateway (no insert)', async () => {
|
||||
// The requested bundle is not listed in the fetched index (a stale client
|
||||
// or an index/bundle drift); the import must surface a 502 rather than
|
||||
// silently doing nothing or dereferencing a missing meta.
|
||||
const { service, repo } = makeImportService({});
|
||||
await expect(
|
||||
service.importFromCatalog('ws-1', 'u1', dto({ bundleId: 'missing' })),
|
||||
).rejects.toBeInstanceOf(BadGatewayException);
|
||||
expect(repo.insert).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('updateFromCatalog', () => {
|
||||
function makeUpdateService(opts: {
|
||||
role?: AiAgentRole;
|
||||
indexBundles?: unknown[];
|
||||
bundleRoles?: Record<string, unknown>[];
|
||||
others?: AiAgentRole[];
|
||||
}) {
|
||||
const index = {
|
||||
schemaVersion: 1,
|
||||
bundles: opts.indexBundles ?? [
|
||||
{
|
||||
id: 'general',
|
||||
name: { en: 'General' },
|
||||
languages: ['en'],
|
||||
roles: [{ slug: 'researcher', version: 5 }],
|
||||
},
|
||||
],
|
||||
};
|
||||
const bundle = {
|
||||
schemaVersion: 1,
|
||||
language: 'en',
|
||||
roles: opts.bundleRoles ?? [
|
||||
{ slug: 'researcher', name: 'Researcher v5', instructions: 'new' },
|
||||
],
|
||||
};
|
||||
const repo = {
|
||||
findById: jest.fn().mockResolvedValue(opts.role),
|
||||
insert: jest.fn(),
|
||||
update: jest.fn().mockResolvedValue(undefined),
|
||||
softDelete: jest.fn(),
|
||||
listByWorkspace: jest.fn().mockResolvedValue(opts.others ?? []),
|
||||
};
|
||||
const catalog = {
|
||||
fetchIndex: jest.fn().mockResolvedValue(index),
|
||||
fetchBundle: jest.fn().mockResolvedValue(bundle),
|
||||
};
|
||||
const service = new AiAgentRolesService(repo as never, catalog as never);
|
||||
return { service, repo, catalog };
|
||||
}
|
||||
|
||||
const imported = (version: number, over: Partial<AiAgentRole> = {}) =>
|
||||
makeRow({
|
||||
id: 'r1',
|
||||
name: 'Researcher',
|
||||
source: { slug: 'researcher', language: 'en', version } as never,
|
||||
...over,
|
||||
});
|
||||
|
||||
it('role not imported from catalog (source null) => BadRequest', async () => {
|
||||
const { service } = makeUpdateService({ role: makeRow({ source: null }) });
|
||||
await expect(
|
||||
service.updateFromCatalog('ws-1', { id: 'r1' } as never),
|
||||
).rejects.toBeInstanceOf(BadRequestException);
|
||||
});
|
||||
|
||||
it('role not found => BadRequest', async () => {
|
||||
const { service } = makeUpdateService({ role: undefined });
|
||||
await expect(
|
||||
service.updateFromCatalog('ws-1', { id: 'r1' } as never),
|
||||
).rejects.toBeInstanceOf(BadRequestException);
|
||||
});
|
||||
|
||||
it('catalog version <= source.version => up-to-date (no update)', async () => {
|
||||
const { service, repo } = makeUpdateService({ role: imported(5) });
|
||||
const res = await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
|
||||
expect(res).toEqual({ updated: false, reason: 'up-to-date' });
|
||||
expect(repo.update).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('slug no longer listed in any bundle => not-in-catalog', async () => {
|
||||
const { service, repo } = makeUpdateService({
|
||||
role: imported(1),
|
||||
indexBundles: [
|
||||
{
|
||||
id: 'general',
|
||||
name: { en: 'General' },
|
||||
languages: ['en'],
|
||||
roles: [{ slug: 'other', version: 9 }],
|
||||
},
|
||||
],
|
||||
});
|
||||
const res = await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
|
||||
expect(res).toEqual({ updated: false, reason: 'not-in-catalog' });
|
||||
expect(repo.update).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('source.language no longer offered by the bundle => language-unavailable', async () => {
|
||||
const { service, repo } = makeUpdateService({
|
||||
role: imported(1, {
|
||||
source: { slug: 'researcher', language: 'ru', version: 1 } as never,
|
||||
}),
|
||||
indexBundles: [
|
||||
{
|
||||
id: 'general',
|
||||
name: { en: 'General' },
|
||||
languages: ['en'],
|
||||
roles: [{ slug: 'researcher', version: 5 }],
|
||||
},
|
||||
],
|
||||
});
|
||||
const res = await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
|
||||
expect(res).toEqual({ updated: false, reason: 'language-unavailable' });
|
||||
expect(repo.update).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('newer version => updates content + bumps source.version, returns versions', async () => {
|
||||
const role = imported(1);
|
||||
const { service, repo } = makeUpdateService({ role });
|
||||
// The post-update re-fetch returns the bumped row.
|
||||
repo.findById
|
||||
.mockResolvedValueOnce(role)
|
||||
.mockResolvedValueOnce(
|
||||
imported(5, { name: 'Researcher v5', instructions: 'new' }),
|
||||
);
|
||||
const res = await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
|
||||
expect(res).toMatchObject({
|
||||
updated: true,
|
||||
fromVersion: 1,
|
||||
toVersion: 5,
|
||||
});
|
||||
const patch = repo.update.mock.calls[0][2];
|
||||
expect(patch.source).toEqual({
|
||||
slug: 'researcher',
|
||||
language: 'en',
|
||||
version: 5,
|
||||
});
|
||||
expect(patch.name).toBe('Researcher v5');
|
||||
// enabled is never touched by an update-from-catalog.
|
||||
expect('enabled' in patch).toBe(false);
|
||||
});
|
||||
|
||||
it('slug listed in the index but missing from the bundle file => not-in-catalog', async () => {
|
||||
// Index/bundle drift: the index still advertises a newer `researcher`
|
||||
// (v5 > installed v1) in an offered language, but the fetched bundle file
|
||||
// no longer contains that slug. The update must no-op as not-in-catalog,
|
||||
// not throw or write a half-resolved role.
|
||||
const { service, repo } = makeUpdateService({
|
||||
role: imported(1),
|
||||
bundleRoles: [
|
||||
{ slug: 'someone-else', name: 'Other', instructions: 'x' },
|
||||
],
|
||||
});
|
||||
const res = await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
|
||||
expect(res).toEqual({ updated: false, reason: 'not-in-catalog' });
|
||||
expect(repo.update).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('new catalog name collides with another live role => keeps current name', async () => {
|
||||
const role = imported(1);
|
||||
const other = makeRow({ id: 'r2', name: 'Researcher v5' });
|
||||
const { service, repo } = makeUpdateService({ role, others: [role, other] });
|
||||
repo.findById
|
||||
.mockResolvedValueOnce(role)
|
||||
.mockResolvedValueOnce(imported(5));
|
||||
await service.updateFromCatalog('ws-1', { id: 'r1' } as never);
|
||||
// The colliding catalog name is dropped; the current name is kept.
|
||||
expect(repo.update.mock.calls[0][2].name).toBe('Researcher');
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Catalog browse (getCatalog / getCatalogBundle) against a MOCKED provider.
|
||||
// Covers the localized() three-tier fallback (requested lang -> en -> first ->
|
||||
// null), the sorted union of bundle languages, the missing-bundle BadGateway,
|
||||
// and the role-version default.
|
||||
// ---------------------------------------------------------------------------
|
||||
describe('getCatalog', () => {
|
||||
function makeBrowseService(index: unknown) {
|
||||
const repo = {
|
||||
findById: jest.fn(),
|
||||
insert: jest.fn(),
|
||||
update: jest.fn(),
|
||||
softDelete: jest.fn(),
|
||||
listByWorkspace: jest.fn(),
|
||||
};
|
||||
const catalog = {
|
||||
fetchIndex: jest.fn().mockResolvedValue(index),
|
||||
fetchBundle: jest.fn(),
|
||||
};
|
||||
const service = new AiAgentRolesService(repo as never, catalog as never);
|
||||
return { service, catalog };
|
||||
}
|
||||
|
||||
it('returns the sorted union of every bundle language', async () => {
|
||||
const { service } = makeBrowseService({
|
||||
schemaVersion: 1,
|
||||
bundles: [
|
||||
{
|
||||
id: 'a',
|
||||
name: { en: 'A' },
|
||||
languages: ['ru', 'en'],
|
||||
roles: [],
|
||||
},
|
||||
{
|
||||
id: 'b',
|
||||
name: { en: 'B' },
|
||||
languages: ['en', 'de'],
|
||||
roles: [],
|
||||
},
|
||||
],
|
||||
});
|
||||
const res = await service.getCatalog('en');
|
||||
expect(res.languages).toEqual(['de', 'en', 'ru']);
|
||||
});
|
||||
|
||||
it('localized name uses the requested language when present', async () => {
|
||||
const { service } = makeBrowseService({
|
||||
schemaVersion: 1,
|
||||
bundles: [
|
||||
{
|
||||
id: 'a',
|
||||
name: { en: 'General', ru: 'Общие' },
|
||||
description: { en: 'desc-en', ru: 'desc-ru' },
|
||||
languages: ['en', 'ru'],
|
||||
roles: [{ slug: 'researcher', version: 2 }],
|
||||
},
|
||||
],
|
||||
});
|
||||
const res = await service.getCatalog('ru');
|
||||
expect(res.bundles[0]).toMatchObject({
|
||||
id: 'a',
|
||||
name: 'Общие',
|
||||
description: 'desc-ru',
|
||||
languages: ['en', 'ru'],
|
||||
roles: [{ slug: 'researcher', version: 2 }],
|
||||
});
|
||||
});
|
||||
|
||||
it('localized name falls back to en when the requested language is missing', async () => {
|
||||
const { service } = makeBrowseService({
|
||||
schemaVersion: 1,
|
||||
bundles: [
|
||||
{
|
||||
id: 'a',
|
||||
name: { en: 'General', ru: 'Общие' },
|
||||
languages: ['en', 'ru'],
|
||||
roles: [],
|
||||
},
|
||||
],
|
||||
});
|
||||
const res = await service.getCatalog('fr');
|
||||
expect(res.bundles[0].name).toBe('General');
|
||||
});
|
||||
|
||||
it('localized name falls back to the first available locale when en is absent', async () => {
|
||||
const { service } = makeBrowseService({
|
||||
schemaVersion: 1,
|
||||
bundles: [
|
||||
{
|
||||
id: 'a',
|
||||
name: { ru: 'Общие', de: 'Allgemein' },
|
||||
languages: ['ru', 'de'],
|
||||
roles: [],
|
||||
},
|
||||
],
|
||||
});
|
||||
const res = await service.getCatalog('fr');
|
||||
// Neither 'fr' nor 'en' is present -> first available value.
|
||||
expect(res.bundles[0].name).toBe('Общие');
|
||||
});
|
||||
|
||||
it('empty name map => falls back to the bundle id; absent description => null', async () => {
|
||||
const { service } = makeBrowseService({
|
||||
schemaVersion: 1,
|
||||
bundles: [
|
||||
{
|
||||
id: 'a',
|
||||
name: {},
|
||||
languages: ['en'],
|
||||
roles: [],
|
||||
},
|
||||
],
|
||||
});
|
||||
const res = await service.getCatalog('en');
|
||||
expect(res.bundles[0].name).toBe('a');
|
||||
expect(res.bundles[0].description).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('getCatalogBundle', () => {
|
||||
function makeBundleService(opts: {
|
||||
index: unknown;
|
||||
bundle: unknown;
|
||||
}) {
|
||||
const repo = {
|
||||
findById: jest.fn(),
|
||||
insert: jest.fn(),
|
||||
update: jest.fn(),
|
||||
softDelete: jest.fn(),
|
||||
listByWorkspace: jest.fn(),
|
||||
};
|
||||
const catalog = {
|
||||
fetchIndex: jest.fn().mockResolvedValue(opts.index),
|
||||
fetchBundle: jest.fn().mockResolvedValue(opts.bundle),
|
||||
};
|
||||
const service = new AiAgentRolesService(repo as never, catalog as never);
|
||||
return { service, catalog };
|
||||
}
|
||||
|
||||
const index = {
|
||||
schemaVersion: 1,
|
||||
bundles: [
|
||||
{
|
||||
id: 'general',
|
||||
name: { en: 'General' },
|
||||
languages: ['en'],
|
||||
roles: [{ slug: 'researcher', version: 4 }],
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
it('missing bundle in the index => BadGateway', async () => {
|
||||
const { service, catalog } = makeBundleService({
|
||||
index,
|
||||
bundle: { schemaVersion: 1, language: 'en', roles: [] },
|
||||
});
|
||||
await expect(
|
||||
service.getCatalogBundle('ghost', 'en'),
|
||||
).rejects.toBeInstanceOf(BadGatewayException);
|
||||
expect(catalog.fetchBundle).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('maps role content with the version taken from the index', async () => {
|
||||
const { service } = makeBundleService({
|
||||
index,
|
||||
bundle: {
|
||||
schemaVersion: 1,
|
||||
language: 'en',
|
||||
roles: [
|
||||
{
|
||||
slug: 'researcher',
|
||||
name: 'Researcher',
|
||||
instructions: 'be a researcher',
|
||||
emoji: '🔬',
|
||||
autoStart: false,
|
||||
launchMessage: 'go',
|
||||
},
|
||||
],
|
||||
},
|
||||
});
|
||||
const res = await service.getCatalogBundle('general', 'en');
|
||||
expect(res).toMatchObject({ bundleId: 'general', language: 'en' });
|
||||
expect(res.roles[0]).toEqual({
|
||||
slug: 'researcher',
|
||||
emoji: '🔬',
|
||||
name: 'Researcher',
|
||||
description: null,
|
||||
instructions: 'be a researcher',
|
||||
autoStart: false,
|
||||
launchMessage: 'go',
|
||||
version: 4,
|
||||
});
|
||||
});
|
||||
|
||||
it('role absent from the index meta => version defaults to 1; autoStart defaults to true', async () => {
|
||||
const { service } = makeBundleService({
|
||||
index,
|
||||
bundle: {
|
||||
schemaVersion: 1,
|
||||
language: 'en',
|
||||
roles: [
|
||||
{ slug: 'newcomer', name: 'Newcomer', instructions: 'hi' },
|
||||
],
|
||||
},
|
||||
});
|
||||
const res = await service.getCatalogBundle('general', 'en');
|
||||
expect(res.roles[0]).toMatchObject({
|
||||
slug: 'newcomer',
|
||||
version: 1,
|
||||
autoStart: true,
|
||||
emoji: null,
|
||||
launchMessage: null,
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,12 +1,24 @@
|
||||
import {
|
||||
BadGatewayException,
|
||||
BadRequestException,
|
||||
ConflictException,
|
||||
Injectable,
|
||||
Logger,
|
||||
} from '@nestjs/common';
|
||||
import { AiAgentRoleRepo } from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
|
||||
import { AiAgentRole } from '@docmost/db/types/entity.types';
|
||||
import {
|
||||
AiAgentRoleRepo,
|
||||
parseSource,
|
||||
} from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
|
||||
import { AiAgentRole, RoleSource } from '@docmost/db/types/entity.types';
|
||||
import { CreateAgentRoleDto, UpdateAgentRoleDto } from './dto/agent-role.dto';
|
||||
import { ImportFromCatalogDto, UpdateFromCatalogDto } from './dto/agent-role-catalog.dto';
|
||||
import { RoleModelConfig } from './role-model-config';
|
||||
import { AiAgentRolesCatalogProvider } from './catalog/ai-agent-roles-catalog.provider';
|
||||
import {
|
||||
CatalogBundleFile,
|
||||
CatalogBundleMeta,
|
||||
CatalogRole,
|
||||
} from './catalog/catalog-types';
|
||||
|
||||
/**
|
||||
* Full (admin) view of an agent role. There are no secret columns on this table
|
||||
@@ -24,6 +36,10 @@ export interface AgentRoleView {
|
||||
enabled: boolean;
|
||||
autoStart: boolean;
|
||||
launchMessage: string | null;
|
||||
// Catalog origin of an imported role, or null for a manually-created one. The
|
||||
// admin UI uses `version` to offer an UPDATE when the catalog ships a newer
|
||||
// revision. Admin-only (deliberately absent from AgentRolePickerView).
|
||||
source: RoleSource | null;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
}
|
||||
@@ -56,7 +72,12 @@ export interface AgentRolePickerView {
|
||||
*/
|
||||
@Injectable()
|
||||
export class AiAgentRolesService {
|
||||
constructor(private readonly repo: AiAgentRoleRepo) {}
|
||||
private readonly logger = new Logger(AiAgentRolesService.name);
|
||||
|
||||
constructor(
|
||||
private readonly repo: AiAgentRoleRepo,
|
||||
private readonly catalog: AiAgentRolesCatalogProvider,
|
||||
) {}
|
||||
|
||||
/**
|
||||
* List the workspace's roles. Admins get the full view (the settings page needs
|
||||
@@ -165,6 +186,316 @@ export class AiAgentRolesService {
|
||||
return { success: true };
|
||||
}
|
||||
|
||||
// -------------------------------------------------------------------------
|
||||
// Catalog (admin-only). The catalog is curated, untrusted JSON fetched +
|
||||
// validated by AiAgentRolesCatalogProvider; this layer resolves localized
|
||||
// text and reconciles a bundle against the workspace's existing roles.
|
||||
// -------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Browse the catalog. Returns the union of every bundle's languages (sorted)
|
||||
* plus per-bundle metadata with `name` / `description` resolved to the
|
||||
* requested `language` (fallback: 'en', then the first available locale).
|
||||
*/
|
||||
async getCatalog(language?: string): Promise<{
|
||||
languages: string[];
|
||||
bundles: {
|
||||
id: string;
|
||||
name: string;
|
||||
description: string | null;
|
||||
languages: string[];
|
||||
roles: { slug: string; version: number }[];
|
||||
}[];
|
||||
}> {
|
||||
const index = await this.catalog.fetchIndex();
|
||||
const languages = Array.from(
|
||||
new Set(index.bundles.flatMap((b) => b.languages)),
|
||||
).sort();
|
||||
const bundles = index.bundles.map((b) => ({
|
||||
id: b.id,
|
||||
name: localized(b.name, language) ?? b.id,
|
||||
description: b.description ? localized(b.description, language) : null,
|
||||
languages: b.languages,
|
||||
roles: b.roles.map((r) => ({ slug: r.slug, version: r.version })),
|
||||
}));
|
||||
return { languages, bundles };
|
||||
}
|
||||
|
||||
/**
|
||||
* Shared read prefix for the two bundle-by-id catalog paths (getCatalogBundle /
|
||||
* importFromCatalog): fetch the index, resolve the requested bundle's meta
|
||||
* (502 if the index does not list it), fetch its per-language file, and build
|
||||
* the slug->version map from the meta. The callers keep their own response /
|
||||
* write logic; only this duplicated read is factored out here.
|
||||
*/
|
||||
private async loadBundleById(
|
||||
bundleId: string,
|
||||
language: string,
|
||||
): Promise<{
|
||||
meta: CatalogBundleMeta;
|
||||
file: CatalogBundleFile;
|
||||
versions: Map<string, number>;
|
||||
}> {
|
||||
const index = await this.catalog.fetchIndex();
|
||||
const meta = index.bundles.find((b) => b.id === bundleId);
|
||||
if (!meta) {
|
||||
throw new BadGatewayException('Catalog bundle not found');
|
||||
}
|
||||
const file = await this.catalog.fetchBundle(bundleId, language);
|
||||
return { meta, file, versions: versionMap(meta) };
|
||||
}
|
||||
|
||||
/**
|
||||
* Open one bundle in a language: returns each role's content plus the version
|
||||
* taken from the index (so the client can compare against an imported role's
|
||||
* source.version). A missing bundle/language => BadGateway (catalog issue).
|
||||
*/
|
||||
async getCatalogBundle(
|
||||
bundleId: string,
|
||||
language: string,
|
||||
): Promise<{
|
||||
bundleId: string;
|
||||
language: string;
|
||||
roles: {
|
||||
slug: string;
|
||||
emoji: string | null;
|
||||
name: string;
|
||||
description: string | null;
|
||||
instructions: string;
|
||||
autoStart: boolean;
|
||||
launchMessage: string | null;
|
||||
version: number;
|
||||
}[];
|
||||
}> {
|
||||
const { file, versions } = await this.loadBundleById(bundleId, language);
|
||||
return {
|
||||
bundleId,
|
||||
language,
|
||||
roles: file.roles.map((r) => ({
|
||||
slug: r.slug,
|
||||
emoji: r.emoji ?? null,
|
||||
name: r.name,
|
||||
description: r.description ?? null,
|
||||
instructions: r.instructions,
|
||||
autoStart: r.autoStart ?? true,
|
||||
launchMessage: r.launchMessage ?? null,
|
||||
version: versions.get(r.slug) ?? 1,
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Import a bundle's roles into the workspace. A role is "already installed"
|
||||
* (and thus skipped — updates are a separate action) only when an existing
|
||||
* role matches BOTH its `source.slug` AND `source.language`: this is a
|
||||
* multilingual catalog, so a different language of the same slug (e.g. the
|
||||
* `ru` variant of a slug already installed as `en`) is a SEPARATE install and
|
||||
* still imports. A name collision with an existing role is either skipped or
|
||||
* imported under a free " (N)" name, per `dto.conflict`. Inserts run
|
||||
* sequentially (the repo exposes no batch insert and the volume is tiny); a
|
||||
* unique-name race still surfaces as an error entry rather than aborting the
|
||||
* whole import.
|
||||
*/
|
||||
async importFromCatalog(
|
||||
workspaceId: string,
|
||||
creatorId: string,
|
||||
dto: ImportFromCatalogDto,
|
||||
): Promise<{
|
||||
created: number;
|
||||
skipped: number;
|
||||
renamed: number;
|
||||
errors: { slug: string; message: string }[];
|
||||
}> {
|
||||
const { file, versions } = await this.loadBundleById(
|
||||
dto.bundleId,
|
||||
dto.language,
|
||||
);
|
||||
|
||||
const errors: { slug: string; message: string }[] = [];
|
||||
|
||||
// Resolve the selected catalog roles (honor dto.slugs; flag unknown ones).
|
||||
let selected = file.roles;
|
||||
if (dto.slugs && dto.slugs.length > 0) {
|
||||
const wanted = new Set(dto.slugs);
|
||||
const present = new Set(file.roles.map((r) => r.slug));
|
||||
for (const slug of dto.slugs) {
|
||||
if (!present.has(slug)) {
|
||||
errors.push({ slug, message: 'Role not found in catalog bundle' });
|
||||
}
|
||||
}
|
||||
selected = file.roles.filter((r) => wanted.has(r.slug));
|
||||
}
|
||||
|
||||
const existingRoles = await this.repo.listByWorkspace(workspaceId);
|
||||
// Catalog roles already installed in this workspace, keyed by slug+language
|
||||
// (skip; never duplicate). The key MUST match the client install-state and
|
||||
// updateFromCatalog (both match by source.slug AND source.language): the
|
||||
// `ru` variant of a slug already installed as `en` is a separate install.
|
||||
const installedKeys = new Set(
|
||||
existingRoles
|
||||
.map((r) => parseSource(r.source))
|
||||
.filter((s): s is RoleSource => s !== null)
|
||||
.map((s) => `${s.slug}:${s.language}`),
|
||||
);
|
||||
// Live role names (lowercased) for collision detection. Mutated as we
|
||||
// insert so two imported roles cannot both grab the same name.
|
||||
const takenNames = new Set(
|
||||
existingRoles.map((r) => r.name.trim().toLowerCase()),
|
||||
);
|
||||
|
||||
let created = 0;
|
||||
let skipped = 0;
|
||||
let renamed = 0;
|
||||
|
||||
for (const role of selected) {
|
||||
// Already installed from the catalog in THIS language => skip (use
|
||||
// update-from-catalog). A different language of the same slug still imports.
|
||||
const installKey = `${role.slug}:${dto.language}`;
|
||||
if (installedKeys.has(installKey)) {
|
||||
skipped++;
|
||||
continue;
|
||||
}
|
||||
|
||||
let name = role.name.trim();
|
||||
let didRename = false;
|
||||
if (takenNames.has(name.toLowerCase())) {
|
||||
if (dto.conflict === 'skip') {
|
||||
skipped++;
|
||||
continue;
|
||||
}
|
||||
// conflict === 'rename': find a free " (N)" suffix.
|
||||
name = freeName(name, takenNames);
|
||||
didRename = true;
|
||||
}
|
||||
|
||||
const version = versions.get(role.slug) ?? 1;
|
||||
try {
|
||||
await this.repo.insert({
|
||||
workspaceId,
|
||||
creatorId,
|
||||
name,
|
||||
...catalogRoleContentFields(role),
|
||||
enabled: true,
|
||||
source: { slug: role.slug, language: dto.language, version },
|
||||
});
|
||||
created++;
|
||||
if (didRename) renamed++;
|
||||
takenNames.add(name.toLowerCase());
|
||||
installedKeys.add(installKey);
|
||||
} catch (err) {
|
||||
// A 23505 from the source-uniqueness index means a CONCURRENT import
|
||||
// already installed this exact slug+language between our snapshot
|
||||
// (installedKeys) and this insert: the in-process snapshot cannot see a
|
||||
// sibling request's writes, so the partial unique index is the backstop.
|
||||
// Outcome is identical to the snapshot-based skip above — count it as
|
||||
// skipped (already installed) and continue; do NOT abort or error.
|
||||
if (isSourceUniqueViolation(err)) {
|
||||
skipped++;
|
||||
installedKeys.add(installKey);
|
||||
continue;
|
||||
}
|
||||
// Otherwise: a unique-NAME race (23505 on the name index) is expected and
|
||||
// self-explanatory (it becomes a friendly per-role error). Any OTHER
|
||||
// insert failure is unexpected, so log the root cause with enough context
|
||||
// to diagnose it — the user-facing message is deliberately generic.
|
||||
if (!isUniqueViolation(err)) {
|
||||
this.logger.error(
|
||||
`Failed to import catalog role (workspaceId=${workspaceId} bundleId=${dto.bundleId} slug=${role.slug}): ${err instanceof Error ? err.stack ?? err.message : String(err)}`,
|
||||
);
|
||||
}
|
||||
errors.push({ slug: role.slug, message: importErrorMessage(err) });
|
||||
}
|
||||
}
|
||||
|
||||
return { created, skipped, renamed, errors };
|
||||
}
|
||||
|
||||
/**
|
||||
* Update an already-imported role from its catalog source when the catalog
|
||||
* ships a newer version. Returns a discriminated result so the UI can explain
|
||||
* a no-op (up-to-date / removed from catalog / language no longer offered).
|
||||
* Never touches `enabled`; keeps the current name if the catalog's new name
|
||||
* would collide with another role (avoiding the unique-name 409).
|
||||
*/
|
||||
async updateFromCatalog(
|
||||
workspaceId: string,
|
||||
dto: UpdateFromCatalogDto,
|
||||
): Promise<
|
||||
| { updated: false; reason: 'not-in-catalog' | 'up-to-date' | 'language-unavailable' }
|
||||
| { updated: true; fromVersion: number; toVersion: number; role: AgentRoleView }
|
||||
> {
|
||||
const role = await this.repo.findById(dto.id, workspaceId);
|
||||
if (!role) throw new BadRequestException('Role not found');
|
||||
|
||||
const source = parseSource(role.source);
|
||||
if (!source || !source.slug) {
|
||||
throw new BadRequestException('Role was not imported from the catalog');
|
||||
}
|
||||
|
||||
const index = await this.catalog.fetchIndex();
|
||||
// Find the bundle whose meta lists this slug, and its catalog version.
|
||||
let meta: CatalogBundleMeta | undefined;
|
||||
let currentVersion: number | undefined;
|
||||
for (const b of index.bundles) {
|
||||
const m = b.roles.find((r) => r.slug === source.slug);
|
||||
if (m) {
|
||||
meta = b;
|
||||
currentVersion = m.version;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (!meta || currentVersion === undefined) {
|
||||
return { updated: false, reason: 'not-in-catalog' };
|
||||
}
|
||||
if (currentVersion <= source.version) {
|
||||
return { updated: false, reason: 'up-to-date' };
|
||||
}
|
||||
if (!meta.languages.includes(source.language)) {
|
||||
return { updated: false, reason: 'language-unavailable' };
|
||||
}
|
||||
|
||||
const file = await this.catalog.fetchBundle(meta.id, source.language);
|
||||
const fresh = file.roles.find((r) => r.slug === source.slug);
|
||||
if (!fresh) {
|
||||
return { updated: false, reason: 'not-in-catalog' };
|
||||
}
|
||||
|
||||
// Keep the current name when the catalog's new name would collide with
|
||||
// another live role (avoids the unique-name 409). Same-name (case-insensitive)
|
||||
// means "no rename needed".
|
||||
const newName = fresh.name.trim();
|
||||
let name = newName;
|
||||
if (newName.toLowerCase() !== role.name.trim().toLowerCase()) {
|
||||
const others = await this.repo.listByWorkspace(workspaceId);
|
||||
const collision = others.some(
|
||||
(r) =>
|
||||
r.id !== role.id &&
|
||||
r.name.trim().toLowerCase() === newName.toLowerCase(),
|
||||
);
|
||||
if (collision) name = role.name;
|
||||
}
|
||||
|
||||
await this.repo.update(dto.id, workspaceId, {
|
||||
name,
|
||||
...catalogRoleContentFields(fresh),
|
||||
// enabled is deliberately NOT changed.
|
||||
source: {
|
||||
slug: source.slug,
|
||||
language: source.language,
|
||||
version: currentVersion,
|
||||
},
|
||||
});
|
||||
|
||||
const updated = await this.repo.findById(dto.id, workspaceId);
|
||||
if (!updated) throw new BadRequestException('Role not found');
|
||||
return {
|
||||
updated: true,
|
||||
fromVersion: source.version,
|
||||
toVersion: currentVersion,
|
||||
role: this.toView(updated),
|
||||
};
|
||||
}
|
||||
|
||||
private toView(row: AiAgentRole): AgentRoleView {
|
||||
return {
|
||||
id: row.id,
|
||||
@@ -176,6 +507,9 @@ export class AiAgentRolesService {
|
||||
enabled: row.enabled,
|
||||
autoStart: row.autoStart,
|
||||
launchMessage: row.launchMessage ?? null,
|
||||
// parseSource yields a fully-valid RoleSource | null (the row is already
|
||||
// normalized; this also keeps the field type honest without a cast).
|
||||
source: parseSource(row.source),
|
||||
createdAt: row.createdAt,
|
||||
updatedAt: row.updatedAt,
|
||||
};
|
||||
@@ -205,11 +539,7 @@ export class AiAgentRolesService {
|
||||
* failures keep surfacing as 500s.
|
||||
*/
|
||||
function rethrowDuplicateName(err: unknown, name: string): never {
|
||||
if (
|
||||
err &&
|
||||
typeof err === 'object' &&
|
||||
(err as { code?: unknown }).code === '23505'
|
||||
) {
|
||||
if (isUniqueViolation(err)) {
|
||||
throw new ConflictException(
|
||||
`A role named "${name}" already exists in this workspace.`,
|
||||
);
|
||||
@@ -217,13 +547,120 @@ function rethrowDuplicateName(err: unknown, name: string): never {
|
||||
throw err;
|
||||
}
|
||||
|
||||
/** '' / whitespace-only / undefined => null; otherwise the trimmed value. */
|
||||
function emptyToNull(value: string | undefined): string | null {
|
||||
if (value === undefined) return null;
|
||||
/** Whether `err` is a Postgres unique-violation (SQLSTATE 23505). */
|
||||
function isUniqueViolation(err: unknown): boolean {
|
||||
return (
|
||||
!!err &&
|
||||
typeof err === 'object' &&
|
||||
(err as { code?: unknown }).code === '23505'
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* The partial unique index name from the
|
||||
* 20260626T160000-ai-agent-roles-catalog-source-unique migration: unique on
|
||||
* (workspace_id, source->>'slug', source->>'language') for catalog-imported,
|
||||
* non-deleted rows. A 23505 carrying this constraint name is a source-collision
|
||||
* (concurrent import of the same slug+language), distinct from a name-collision.
|
||||
*/
|
||||
const SOURCE_UNIQUE_CONSTRAINT = 'ai_agent_roles_workspace_source_unique';
|
||||
|
||||
/**
|
||||
* Whether `err` is the 23505 raised by the SOURCE-uniqueness index specifically
|
||||
* (vs the name-uniqueness index). The active driver (`kysely-postgres-js` over
|
||||
* `postgres@3.4.8`) exposes the violated constraint name on `constraint_name`,
|
||||
* so we key off that (accepting the node-postgres-style `.constraint` as a
|
||||
* fallback for other drivers) — that way a source race is skipped while a name
|
||||
* race still surfaces as a friendly per-role error. A 23505 with no constraint
|
||||
* name (e.g. a wrapped/test error) is NOT treated as a source collision,
|
||||
* preserving the existing name-race behavior.
|
||||
*/
|
||||
function isSourceUniqueViolation(err: unknown): boolean {
|
||||
if (!isUniqueViolation(err)) return false;
|
||||
const e = err as { constraint_name?: unknown; constraint?: unknown };
|
||||
return (
|
||||
e.constraint_name === SOURCE_UNIQUE_CONSTRAINT ||
|
||||
e.constraint === SOURCE_UNIQUE_CONSTRAINT
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* The role-content fields shared by import (insert) and update (patch) of a
|
||||
* catalog role: emoji/description/launchMessage normalized to null, model config
|
||||
* normalized, autoStart defaulted. The caller adds the write-specific fields
|
||||
* (`name`, `source`, and on insert `workspaceId`/`creatorId`/`enabled`).
|
||||
*/
|
||||
function catalogRoleContentFields(role: CatalogRole): {
|
||||
emoji: string | null;
|
||||
description: string | null;
|
||||
instructions: string;
|
||||
modelConfig: Record<string, unknown> | null;
|
||||
autoStart: boolean;
|
||||
launchMessage: string | null;
|
||||
} {
|
||||
return {
|
||||
emoji: emptyToNull(role.emoji),
|
||||
description: emptyToNull(role.description),
|
||||
instructions: role.instructions,
|
||||
modelConfig: normalizeModelConfig(role.modelConfig) as
|
||||
| Record<string, unknown>
|
||||
| null,
|
||||
autoStart: role.autoStart ?? true,
|
||||
launchMessage: emptyToNull(role.launchMessage ?? undefined),
|
||||
};
|
||||
}
|
||||
|
||||
/** '' / whitespace-only / undefined / null => null; otherwise the trimmed value. */
|
||||
function emptyToNull(value: string | null | undefined): string | null {
|
||||
if (value === undefined || value === null) return null;
|
||||
const trimmed = value.trim();
|
||||
return trimmed.length > 0 ? trimmed : null;
|
||||
}
|
||||
|
||||
/** slug -> version map from a bundle's index metadata. */
|
||||
function versionMap(meta: CatalogBundleMeta): Map<string, number> {
|
||||
return new Map(meta.roles.map((r) => [r.slug, r.version]));
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a localized value `{ en, ru, ... }` to `language`, falling back to
|
||||
* 'en', then the first available locale. Returns null only for an empty map.
|
||||
*/
|
||||
function localized(
|
||||
map: Record<string, string>,
|
||||
language?: string,
|
||||
): string | null {
|
||||
if (language && typeof map[language] === 'string') return map[language];
|
||||
if (typeof map.en === 'string') return map.en;
|
||||
const first = Object.values(map)[0];
|
||||
return typeof first === 'string' ? first : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Find a free display name by appending " (2)", " (3)", ... when `base` is
|
||||
* already taken (case-insensitive against `taken`). Caller adds the result to
|
||||
* `taken` after a successful insert.
|
||||
*/
|
||||
function freeName(base: string, taken: Set<string>): string {
|
||||
// `taken` is finite, so within `taken.size + 2` iterations a candidate index
|
||||
// is guaranteed free; the 1000 cap is a defensive upper bound far above any
|
||||
// realistic per-name collision count. The throw below is therefore
|
||||
// unreachable in practice and only satisfies the return-type checker.
|
||||
for (let n = 2; n < 1000; n++) {
|
||||
const candidate = `${base} (${n})`;
|
||||
if (!taken.has(candidate.toLowerCase())) return candidate;
|
||||
}
|
||||
throw new BadRequestException(`Too many roles named "${base}"`);
|
||||
}
|
||||
|
||||
/** A short, safe message for an import insert failure (409 vs other). */
|
||||
function importErrorMessage(err: unknown): string {
|
||||
if (isUniqueViolation(err)) {
|
||||
return 'A role with this name already exists';
|
||||
}
|
||||
return 'Failed to import role';
|
||||
}
|
||||
|
||||
/**
|
||||
* Normalize an incoming modelConfig DTO to the persisted shape, or null when
|
||||
* there is no usable override (no driver and no chatModel). The DTO's @IsIn
|
||||
|
||||
@@ -0,0 +1,357 @@
|
||||
import { promises as fs } from 'node:fs';
|
||||
import * as os from 'node:os';
|
||||
import * as path from 'node:path';
|
||||
import { BadGatewayException, BadRequestException } from '@nestjs/common';
|
||||
import { AiAgentRolesCatalogProvider } from './ai-agent-roles-catalog.provider';
|
||||
|
||||
/**
|
||||
* Provider tests against a LOCAL fixture directory (no network). They cover the
|
||||
* happy read path (fetchIndex / fetchBundle), the malformed-shape rejection, a
|
||||
* missing file => unavailable, and — most importantly — the `^[a-z0-9-]+$`
|
||||
* path-traversal guard that runs BEFORE any path is built.
|
||||
*/
|
||||
describe('AiAgentRolesCatalogProvider (local fixtures)', () => {
|
||||
let dir: string;
|
||||
|
||||
function makeProvider(source: string) {
|
||||
const env = {
|
||||
getAiAgentRolesCatalogSource: () => source,
|
||||
};
|
||||
return new AiAgentRolesCatalogProvider(env as never);
|
||||
}
|
||||
|
||||
beforeAll(async () => {
|
||||
dir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-roles-catalog-'));
|
||||
await fs.writeFile(
|
||||
path.join(dir, 'index.json'),
|
||||
JSON.stringify({
|
||||
schemaVersion: 1,
|
||||
bundles: [
|
||||
{
|
||||
id: 'general',
|
||||
name: { en: 'General', ru: 'Общие' },
|
||||
languages: ['en'],
|
||||
roles: [{ slug: 'researcher', version: 2 }],
|
||||
},
|
||||
],
|
||||
}),
|
||||
'utf8',
|
||||
);
|
||||
await fs.mkdir(path.join(dir, 'bundles', 'general'), { recursive: true });
|
||||
await fs.writeFile(
|
||||
path.join(dir, 'bundles', 'general', 'en.json'),
|
||||
JSON.stringify({
|
||||
schemaVersion: 1,
|
||||
language: 'en',
|
||||
roles: [
|
||||
{
|
||||
slug: 'researcher',
|
||||
name: 'Researcher',
|
||||
instructions: 'be a researcher',
|
||||
},
|
||||
],
|
||||
}),
|
||||
'utf8',
|
||||
);
|
||||
// A malformed bundle (a role missing `instructions`) to test rejection.
|
||||
await fs.writeFile(
|
||||
path.join(dir, 'bundles', 'general', 'fr.json'),
|
||||
JSON.stringify({
|
||||
schemaVersion: 1,
|
||||
language: 'fr',
|
||||
roles: [{ slug: 'researcher', name: 'Chercheur' }],
|
||||
}),
|
||||
'utf8',
|
||||
);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await fs.rm(dir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it('fetchIndex reads + validates index.json', async () => {
|
||||
const provider = makeProvider(dir);
|
||||
const index = await provider.fetchIndex();
|
||||
expect(index.schemaVersion).toBe(1);
|
||||
expect(index.bundles[0].id).toBe('general');
|
||||
expect(index.bundles[0].roles[0]).toEqual({
|
||||
slug: 'researcher',
|
||||
version: 2,
|
||||
});
|
||||
});
|
||||
|
||||
it('fetchBundle reads + validates a language file', async () => {
|
||||
const provider = makeProvider(dir);
|
||||
const bundle = await provider.fetchBundle('general', 'en');
|
||||
expect(bundle.language).toBe('en');
|
||||
expect(bundle.roles[0].slug).toBe('researcher');
|
||||
expect(bundle.roles[0].instructions).toBe('be a researcher');
|
||||
});
|
||||
|
||||
it('malformed bundle (missing instructions) => BadGateway', async () => {
|
||||
const provider = makeProvider(dir);
|
||||
await expect(provider.fetchBundle('general', 'fr')).rejects.toBeInstanceOf(
|
||||
BadGatewayException,
|
||||
);
|
||||
});
|
||||
|
||||
it('missing file => BadGateway (unavailable)', async () => {
|
||||
const provider = makeProvider(dir);
|
||||
await expect(
|
||||
provider.fetchBundle('general', 'de'),
|
||||
).rejects.toBeInstanceOf(BadGatewayException);
|
||||
});
|
||||
|
||||
it('empty source resolves to the in-repo folder (no throw building the path)', async () => {
|
||||
// With an empty source the provider targets ./agent-roles-catalog under the
|
||||
// cwd; that folder is created by a separate task, so a read here surfaces as
|
||||
// BadGateway (unavailable) rather than a path-build error.
|
||||
const provider = makeProvider('');
|
||||
await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
|
||||
BadGatewayException,
|
||||
);
|
||||
});
|
||||
|
||||
describe('remote fetch streaming size cap', () => {
|
||||
const realFetch = global.fetch;
|
||||
afterEach(() => {
|
||||
global.fetch = realFetch;
|
||||
});
|
||||
|
||||
/** A web ReadableStream that yields `chunks` (each a Uint8Array). */
|
||||
function streamOf(chunks: Uint8Array[]): ReadableStream<Uint8Array> {
|
||||
let i = 0;
|
||||
return new ReadableStream<Uint8Array>({
|
||||
pull(controller) {
|
||||
if (i < chunks.length) controller.enqueue(chunks[i++]);
|
||||
else controller.close();
|
||||
},
|
||||
// The provider cancels the reader on the too-large path; no-op here.
|
||||
cancel() {},
|
||||
});
|
||||
}
|
||||
|
||||
/** A ReadableStream whose first read rejects (e.g. a mid-body AbortError). */
|
||||
function errorStream(err: Error): ReadableStream<Uint8Array> {
|
||||
return new ReadableStream<Uint8Array>({
|
||||
pull() {
|
||||
throw err;
|
||||
},
|
||||
cancel() {},
|
||||
});
|
||||
}
|
||||
|
||||
function mockResponse(opts: {
|
||||
ok?: boolean;
|
||||
status?: number;
|
||||
headers?: Record<string, string>;
|
||||
body: ReadableStream<Uint8Array> | null;
|
||||
text?: string;
|
||||
}): Response {
|
||||
return {
|
||||
ok: opts.ok ?? true,
|
||||
status: opts.status ?? 200,
|
||||
headers: { get: (k: string) => opts.headers?.[k.toLowerCase()] ?? null },
|
||||
body: opts.body,
|
||||
text: async () => opts.text ?? 'unused',
|
||||
} as unknown as Response;
|
||||
}
|
||||
|
||||
it('declared Content-Length over the cap => BadGateway before reading the body', async () => {
|
||||
global.fetch = jest.fn().mockResolvedValue(
|
||||
mockResponse({
|
||||
headers: { 'content-length': String(2_000_000) },
|
||||
body: streamOf([new Uint8Array(10)]),
|
||||
}),
|
||||
) as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
|
||||
BadGatewayException,
|
||||
);
|
||||
});
|
||||
|
||||
it('streamed body exceeding the cap (no/under-reported Content-Length) => BadGateway', async () => {
|
||||
// 1.5 MB streamed in 256 KB chunks, with no Content-Length header.
|
||||
const chunks = Array.from(
|
||||
{ length: 6 },
|
||||
() => new Uint8Array(256 * 1024),
|
||||
);
|
||||
global.fetch = jest
|
||||
.fn()
|
||||
.mockResolvedValue(mockResponse({ body: streamOf(chunks) })) as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
|
||||
BadGatewayException,
|
||||
);
|
||||
});
|
||||
|
||||
it('fetch rejects (network failure) => BadGateway (unavailable)', async () => {
|
||||
global.fetch = jest
|
||||
.fn()
|
||||
.mockRejectedValue(new Error('ECONNREFUSED')) as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
|
||||
BadGatewayException,
|
||||
);
|
||||
});
|
||||
|
||||
it('passes redirect:"error" to fetch (redirect-SSRF hardening)', async () => {
|
||||
const fetchMock = jest
|
||||
.fn()
|
||||
.mockResolvedValue(
|
||||
mockResponse({ body: streamOf([new Uint8Array(0)]) }),
|
||||
);
|
||||
global.fetch = fetchMock as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
// Body shape is irrelevant; an empty stream parses to invalid JSON and
|
||||
// throws, but the fetch call (with its init) still happened.
|
||||
await expect(provider.fetchIndex()).rejects.toBeDefined();
|
||||
expect(fetchMock).toHaveBeenCalledWith(
|
||||
expect.any(String),
|
||||
expect.objectContaining({ redirect: 'error' }),
|
||||
);
|
||||
});
|
||||
|
||||
it('redirect response rejects (redirect:"error") => BadGateway', async () => {
|
||||
// With redirect:"error", the platform fetch rejects on a 3xx instead of
|
||||
// following it. Simulate that: the mock rejects when asked not to follow.
|
||||
global.fetch = jest.fn().mockImplementation((_url, init) => {
|
||||
if (init?.redirect === 'error') {
|
||||
return Promise.reject(
|
||||
new TypeError('fetch failed: unexpected redirect'),
|
||||
);
|
||||
}
|
||||
return Promise.resolve(
|
||||
mockResponse({ status: 302, body: null }),
|
||||
);
|
||||
}) as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
|
||||
BadGatewayException,
|
||||
);
|
||||
});
|
||||
|
||||
it('non-ok response (503) => BadGateway carrying the status', async () => {
|
||||
global.fetch = jest.fn().mockResolvedValue(
|
||||
mockResponse({ ok: false, status: 503, body: null }),
|
||||
) as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
await expect(provider.fetchIndex()).rejects.toThrow(/503/);
|
||||
});
|
||||
|
||||
it('small streamed body parses normally (cap not hit)', async () => {
|
||||
const json = JSON.stringify({
|
||||
schemaVersion: 1,
|
||||
bundles: [
|
||||
{
|
||||
id: 'general',
|
||||
name: { en: 'General' },
|
||||
languages: ['en'],
|
||||
roles: [{ slug: 'researcher', version: 2 }],
|
||||
},
|
||||
],
|
||||
});
|
||||
const body = streamOf([new TextEncoder().encode(json)]);
|
||||
global.fetch = jest
|
||||
.fn()
|
||||
.mockResolvedValue(mockResponse({ body })) as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
const index = await provider.fetchIndex();
|
||||
expect(index.bundles[0].id).toBe('general');
|
||||
});
|
||||
|
||||
it('body read aborts mid-stream (AbortError) => BadGateway (not a generic 500)', async () => {
|
||||
// The 10s timer aborts the whole request; on a slow/dripping source the
|
||||
// body read (reader.read()) rejects with an AbortError AFTER fetch()
|
||||
// resolved. The provider must map that to BadGateway, not let it escape.
|
||||
const abortErr = Object.assign(new Error('The operation was aborted'), {
|
||||
name: 'AbortError',
|
||||
});
|
||||
global.fetch = jest
|
||||
.fn()
|
||||
.mockResolvedValue(mockResponse({ body: errorStream(abortErr) })) as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
|
||||
BadGatewayException,
|
||||
);
|
||||
});
|
||||
|
||||
it('null body (no readable stream) => response.text() fallback parses', async () => {
|
||||
const json = JSON.stringify({
|
||||
schemaVersion: 1,
|
||||
bundles: [
|
||||
{
|
||||
id: 'general',
|
||||
name: { en: 'General' },
|
||||
languages: ['en'],
|
||||
roles: [{ slug: 'researcher', version: 2 }],
|
||||
},
|
||||
],
|
||||
});
|
||||
global.fetch = jest
|
||||
.fn()
|
||||
.mockResolvedValue(mockResponse({ body: null, text: json })) as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
const index = await provider.fetchIndex();
|
||||
expect(index.bundles[0].id).toBe('general');
|
||||
});
|
||||
|
||||
it('null body + text() over the cap => BadGateway (too large)', async () => {
|
||||
const oversized = 'a'.repeat(1_000_001);
|
||||
global.fetch = jest
|
||||
.fn()
|
||||
.mockResolvedValue(
|
||||
mockResponse({ body: null, text: oversized }),
|
||||
) as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
|
||||
BadGatewayException,
|
||||
);
|
||||
});
|
||||
|
||||
it('invalid JSON body => BadGateway (parse failure)', async () => {
|
||||
const body = streamOf([new TextEncoder().encode('{not valid json')]);
|
||||
global.fetch = jest
|
||||
.fn()
|
||||
.mockResolvedValue(mockResponse({ body })) as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
await expect(provider.fetchIndex()).rejects.toBeInstanceOf(
|
||||
BadGatewayException,
|
||||
);
|
||||
});
|
||||
|
||||
it('malformed index.json (valid JSON, wrong shape) => BadGateway', async () => {
|
||||
// Parses as JSON but fails isCatalogIndex (schemaVersion not a number).
|
||||
const body = streamOf([
|
||||
new TextEncoder().encode(
|
||||
JSON.stringify({ schemaVersion: 'x', bundles: [] }),
|
||||
),
|
||||
]);
|
||||
global.fetch = jest
|
||||
.fn()
|
||||
.mockResolvedValue(mockResponse({ body })) as never;
|
||||
const provider = makeProvider('https://catalog.example.com');
|
||||
await expect(provider.fetchIndex()).rejects.toThrow(/malformed/i);
|
||||
});
|
||||
});
|
||||
|
||||
describe('path-traversal / SSRF guard (^[a-z0-9-]+$)', () => {
|
||||
const bad = ['../etc', 'a/b', 'A', 'foo.bar', 'foo_bar', '', '..'];
|
||||
|
||||
for (const value of bad) {
|
||||
it(`rejects bundleId="${value}" with BadRequest`, async () => {
|
||||
const provider = makeProvider(dir);
|
||||
await expect(
|
||||
provider.fetchBundle(value, 'en'),
|
||||
).rejects.toBeInstanceOf(BadRequestException);
|
||||
});
|
||||
|
||||
it(`rejects language="${value}" with BadRequest`, async () => {
|
||||
const provider = makeProvider(dir);
|
||||
await expect(
|
||||
provider.fetchBundle('general', value),
|
||||
).rejects.toBeInstanceOf(BadRequestException);
|
||||
});
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,324 @@
|
||||
import { promises as fs } from 'node:fs';
|
||||
import * as path from 'node:path';
|
||||
import {
|
||||
BadGatewayException,
|
||||
BadRequestException,
|
||||
Injectable,
|
||||
Logger,
|
||||
} from '@nestjs/common';
|
||||
import { EnvironmentService } from '../../../../integrations/environment/environment.service';
|
||||
import {
|
||||
CatalogBundleFile,
|
||||
CatalogBundleMeta,
|
||||
CatalogIndex,
|
||||
CatalogRole,
|
||||
} from './catalog-types';
|
||||
|
||||
/** Identifier shape allowed in any path/URL segment (bundleId, language). The
|
||||
* ONLY characters that can appear in a fetched path — the path-traversal and
|
||||
* SSRF guard. Anything else is rejected before a path/URL is built. */
|
||||
const SEGMENT_RE = /^[a-z0-9-]+$/;
|
||||
|
||||
/** Remote fetch timeout and response-size cap. A curated catalog file is tiny;
|
||||
* the cap stops a hostile/misconfigured source from streaming unbounded data. */
|
||||
const FETCH_TIMEOUT_MS = 10_000;
|
||||
const MAX_BYTES = 1_000_000;
|
||||
|
||||
/**
|
||||
* Fetches + validates the agent-roles catalog from its configured source. The
|
||||
* source location (EnvironmentService.getAiAgentRolesCatalogSource()) is either
|
||||
* an http(s):// base URL (REMOTE) or a local filesystem directory (LOCAL; the
|
||||
* empty default resolves to the in-repo `agent-roles-catalog/` folder).
|
||||
*
|
||||
* The catalog is UNTRUSTED input: every file is JSON-parsed and run through a
|
||||
* hand-written type guard before any field is exposed, and every dynamic path
|
||||
* segment is validated against SEGMENT_RE up front (path-traversal + SSRF).
|
||||
*/
|
||||
@Injectable()
|
||||
export class AiAgentRolesCatalogProvider {
|
||||
private readonly logger = new Logger(AiAgentRolesCatalogProvider.name);
|
||||
|
||||
constructor(private readonly environmentService: EnvironmentService) {}
|
||||
|
||||
/** Read + validate the top-level index (`index.json`). */
|
||||
async fetchIndex(): Promise<CatalogIndex> {
|
||||
const raw = await this.readRelative('index.json');
|
||||
const parsed = this.parseJson(raw, 'index.json');
|
||||
if (!isCatalogIndex(parsed)) {
|
||||
throw new BadGatewayException(
|
||||
'Agent roles catalog index is malformed (index.json)',
|
||||
);
|
||||
}
|
||||
return parsed;
|
||||
}
|
||||
|
||||
/** Read + validate one language file (`bundles/<bundleId>/<language>.json`). */
|
||||
async fetchBundle(
|
||||
bundleId: string,
|
||||
language: string,
|
||||
): Promise<CatalogBundleFile> {
|
||||
// SECURITY: validate BEFORE building any path/URL (path-traversal + SSRF).
|
||||
this.assertSegment(bundleId, 'bundleId');
|
||||
this.assertSegment(language, 'language');
|
||||
const rel = `bundles/${bundleId}/${language}.json`;
|
||||
const raw = await this.readRelative(rel);
|
||||
const parsed = this.parseJson(raw, rel);
|
||||
if (!isCatalogBundleFile(parsed)) {
|
||||
throw new BadGatewayException(
|
||||
`Agent roles catalog bundle is malformed (${rel})`,
|
||||
);
|
||||
}
|
||||
return parsed;
|
||||
}
|
||||
|
||||
/** Reject a segment that is not a safe `[a-z0-9-]+` identifier. */
|
||||
private assertSegment(value: string, field: string): void {
|
||||
if (typeof value !== 'string' || !SEGMENT_RE.test(value)) {
|
||||
throw new BadRequestException(`Invalid ${field}`);
|
||||
}
|
||||
}
|
||||
|
||||
/** JSON.parse with a clear BadGateway on malformed content. */
|
||||
private parseJson(raw: string, rel: string): unknown {
|
||||
try {
|
||||
return JSON.parse(raw);
|
||||
} catch (err) {
|
||||
const reason = shortError(err);
|
||||
this.logger.error(`Agent roles catalog JSON parse failed (${rel}): ${reason}`);
|
||||
throw new BadGatewayException(
|
||||
`Agent roles catalog file is not valid JSON (${rel}): ${reason}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/** Read a relative catalog path as text from the configured source. */
|
||||
private async readRelative(rel: string): Promise<string> {
|
||||
const source = this.environmentService
|
||||
.getAiAgentRolesCatalogSource()
|
||||
.trim();
|
||||
if (/^https?:\/\//i.test(source)) {
|
||||
return this.fetchRemote(source, rel);
|
||||
}
|
||||
const dir = source || path.join(process.cwd(), 'agent-roles-catalog');
|
||||
return this.readLocal(dir, rel);
|
||||
}
|
||||
|
||||
/** Read a local catalog file. Missing => the catalog is unavailable. */
|
||||
private async readLocal(dir: string, rel: string): Promise<string> {
|
||||
try {
|
||||
return await fs.readFile(path.join(dir, rel), 'utf8');
|
||||
} catch (err) {
|
||||
const reason = shortError(err);
|
||||
this.logger.error(
|
||||
`Agent roles catalog local read failed (${path.join(dir, rel)}): ${reason}`,
|
||||
);
|
||||
throw new BadGatewayException(
|
||||
`Agent roles catalog is unavailable: ${reason}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetch a remote catalog file with a timeout + a STREAMING size cap. The body
|
||||
* is never buffered in full before the check: we reject on a too-large
|
||||
* Content-Length up front, then read the stream chunk-by-chunk and abort the
|
||||
* moment the running total exceeds MAX_BYTES, so a hostile/misconfigured
|
||||
* source cannot make us hold an unbounded body in memory.
|
||||
*/
|
||||
private async fetchRemote(base: string, rel: string): Promise<string> {
|
||||
const url = `${base.replace(/\/+$/, '')}/${rel}`;
|
||||
const controller = new AbortController();
|
||||
const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
|
||||
try {
|
||||
let response: Response;
|
||||
try {
|
||||
// `redirect: 'error'` hardens against redirect-SSRF: a
|
||||
// compromised-but-trusted upstream cannot 3xx the fetch into the
|
||||
// internal network (e.g. http://169.254.169.254/...). A redirect
|
||||
// response rejects here and is mapped to BadGateway below.
|
||||
response = await fetch(url, {
|
||||
signal: controller.signal,
|
||||
redirect: 'error',
|
||||
});
|
||||
} catch (err) {
|
||||
const reason = shortError(err);
|
||||
this.logger.error(
|
||||
`Agent roles catalog remote fetch failed (${rel}): ${reason}`,
|
||||
);
|
||||
throw new BadGatewayException(
|
||||
`Agent roles catalog is unavailable: ${reason}`,
|
||||
);
|
||||
}
|
||||
if (!response.ok) {
|
||||
this.logger.error(
|
||||
`Agent roles catalog remote returned ${response.status} (${rel})`,
|
||||
);
|
||||
throw new BadGatewayException(
|
||||
`Agent roles catalog returned ${response.status}`,
|
||||
);
|
||||
}
|
||||
// Reject a too-large declared size before reading any body bytes.
|
||||
const declared = Number(response.headers.get('content-length'));
|
||||
if (Number.isFinite(declared) && declared > MAX_BYTES) {
|
||||
throw new BadGatewayException('Agent roles catalog file is too large');
|
||||
}
|
||||
// Bound the actual read: a missing/lying Content-Length is caught here.
|
||||
// The 10s timer aborts the WHOLE request, so a slow/dripping hostile
|
||||
// source rejects reader.read() (or response.text()) with an AbortError
|
||||
// mid-body. Map that — and any other read failure — to a logged
|
||||
// BadGateway so the admin endpoint returns 502 (not a generic 500). The
|
||||
// cap's own BadGateway is rethrown as-is (no double-wrap).
|
||||
try {
|
||||
if (response.body) {
|
||||
return await readStreamCapped(response.body, MAX_BYTES);
|
||||
}
|
||||
// Edge: no readable stream — fall back to a buffered read + length check.
|
||||
const text = await response.text();
|
||||
if (text.length > MAX_BYTES) {
|
||||
throw new BadGatewayException('Agent roles catalog file is too large');
|
||||
}
|
||||
return text;
|
||||
} catch (err) {
|
||||
if (err instanceof BadGatewayException) throw err;
|
||||
const reason = shortError(err);
|
||||
this.logger.error(
|
||||
`Agent roles catalog body read failed (${rel}): ${reason}`,
|
||||
);
|
||||
throw new BadGatewayException(
|
||||
`Agent roles catalog is unavailable: ${reason}`,
|
||||
);
|
||||
}
|
||||
} finally {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Read a web ReadableStream into a UTF-8 string, throwing as soon as the
|
||||
* accumulated byte count exceeds `maxBytes` (the reader is cancelled so the
|
||||
* underlying connection is released). Never buffers more than the cap + the
|
||||
* final chunk before bailing out.
|
||||
*/
|
||||
async function readStreamCapped(
|
||||
body: ReadableStream<Uint8Array>,
|
||||
maxBytes: number,
|
||||
): Promise<string> {
|
||||
const reader = body.getReader();
|
||||
const chunks: Uint8Array[] = [];
|
||||
let total = 0;
|
||||
try {
|
||||
for (;;) {
|
||||
const { done, value } = await reader.read();
|
||||
if (done) break;
|
||||
if (!value) continue;
|
||||
total += value.length;
|
||||
if (total > maxBytes) {
|
||||
throw new BadGatewayException('Agent roles catalog file is too large');
|
||||
}
|
||||
chunks.push(value);
|
||||
}
|
||||
} finally {
|
||||
// Release the stream on both the normal and the too-large/abort paths.
|
||||
await reader.cancel().catch(() => undefined);
|
||||
}
|
||||
return Buffer.concat(chunks).toString('utf8');
|
||||
}
|
||||
|
||||
/**
|
||||
* A short, non-sensitive error string for logging/propagation: only the first
|
||||
* line of the message head is kept (upstream bodies / URLs are discarded).
|
||||
*/
|
||||
function shortError(err: unknown): string {
|
||||
let message = '';
|
||||
if (typeof err === 'string') {
|
||||
message = err;
|
||||
} else if (
|
||||
err &&
|
||||
typeof err === 'object' &&
|
||||
typeof (err as { message?: unknown }).message === 'string'
|
||||
) {
|
||||
// Read `.message` directly (works for Error instances and the realm-shifted
|
||||
// Error-likes jest can hand back, where `instanceof Error` is false).
|
||||
message = (err as { message: string }).message;
|
||||
}
|
||||
const head = (message || 'unknown error').split('\n')[0];
|
||||
return head.length > 200 ? `${head.slice(0, 200)}…` : head;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Hand-written type guards (no zod / new deps). Each validates the exact wire
|
||||
// shape declared in catalog-types.ts; anything else is rejected by the caller.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function isObject(v: unknown): v is Record<string, unknown> {
|
||||
return v !== null && typeof v === 'object' && !Array.isArray(v);
|
||||
}
|
||||
|
||||
function isStringMap(v: unknown): v is Record<string, string> {
|
||||
if (!isObject(v)) return false;
|
||||
return Object.values(v).every((x) => typeof x === 'string');
|
||||
}
|
||||
|
||||
function isStringArray(v: unknown): v is string[] {
|
||||
return Array.isArray(v) && v.every((x) => typeof x === 'string');
|
||||
}
|
||||
|
||||
export function isCatalogRole(v: unknown): v is CatalogRole {
|
||||
if (!isObject(v)) return false;
|
||||
if (typeof v.slug !== 'string') return false;
|
||||
if (typeof v.name !== 'string') return false;
|
||||
if (typeof v.instructions !== 'string') return false;
|
||||
if (v.emoji !== undefined && typeof v.emoji !== 'string') return false;
|
||||
if (v.description !== undefined && typeof v.description !== 'string') {
|
||||
return false;
|
||||
}
|
||||
if (v.autoStart !== undefined && typeof v.autoStart !== 'boolean') {
|
||||
return false;
|
||||
}
|
||||
if (
|
||||
v.launchMessage !== undefined &&
|
||||
v.launchMessage !== null &&
|
||||
typeof v.launchMessage !== 'string'
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
if (
|
||||
v.modelConfig !== undefined &&
|
||||
v.modelConfig !== null &&
|
||||
!isObject(v.modelConfig)
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
export function isCatalogBundleFile(v: unknown): v is CatalogBundleFile {
|
||||
if (!isObject(v)) return false;
|
||||
if (typeof v.schemaVersion !== 'number') return false;
|
||||
if (typeof v.language !== 'string') return false;
|
||||
if (!Array.isArray(v.roles)) return false;
|
||||
return v.roles.every(isCatalogRole);
|
||||
}
|
||||
|
||||
function isCatalogBundleMeta(v: unknown): v is CatalogBundleMeta {
|
||||
if (!isObject(v)) return false;
|
||||
if (typeof v.id !== 'string') return false;
|
||||
if (!isStringMap(v.name)) return false;
|
||||
if (v.description !== undefined && !isStringMap(v.description)) return false;
|
||||
if (!isStringArray(v.languages)) return false;
|
||||
if (!Array.isArray(v.roles)) return false;
|
||||
return v.roles.every(
|
||||
(r) =>
|
||||
isObject(r) &&
|
||||
typeof r.slug === 'string' &&
|
||||
typeof r.version === 'number',
|
||||
);
|
||||
}
|
||||
|
||||
export function isCatalogIndex(v: unknown): v is CatalogIndex {
|
||||
if (!isObject(v)) return false;
|
||||
if (typeof v.schemaVersion !== 'number') return false;
|
||||
if (!Array.isArray(v.bundles)) return false;
|
||||
return v.bundles.every(isCatalogBundleMeta);
|
||||
}
|
||||
47
apps/server/src/core/ai-chat/roles/catalog/catalog-types.ts
Normal file
47
apps/server/src/core/ai-chat/roles/catalog/catalog-types.ts
Normal file
@@ -0,0 +1,47 @@
|
||||
/**
|
||||
* Catalog wire shapes. The catalog is curated, untrusted JSON (a GitHub repo or
|
||||
* a local folder), so every shape is validated by a hand-written type guard in
|
||||
* the provider before any field is used — no zod / new deps on the server.
|
||||
*
|
||||
* Localized fields (`name` / `description` at the bundle level) are
|
||||
* `Record<language, string>` so one bundle serves many UI languages; per-role
|
||||
* `name` / `description` are already language-specific (the bundle file is keyed
|
||||
* by language).
|
||||
*/
|
||||
|
||||
/** One role's content as shipped in a per-language bundle file. */
|
||||
export interface CatalogRole {
|
||||
slug: string;
|
||||
emoji?: string;
|
||||
name: string;
|
||||
description?: string;
|
||||
instructions: string;
|
||||
autoStart?: boolean;
|
||||
launchMessage?: string | null;
|
||||
// Optional model override; same loose object shape as ai_agent_roles.model_config.
|
||||
modelConfig?: Record<string, unknown> | null;
|
||||
}
|
||||
|
||||
/** A single language file: `bundles/<id>/<language>.json`. */
|
||||
export interface CatalogBundleFile {
|
||||
schemaVersion: number;
|
||||
language: string;
|
||||
roles: CatalogRole[];
|
||||
}
|
||||
|
||||
/** Bundle metadata as listed in the top-level index. Versions live here (per
|
||||
* slug), so an UPDATE check needs only the index, not every language file. */
|
||||
export interface CatalogBundleMeta {
|
||||
id: string;
|
||||
// Localized display name/description: { en: '...', ru: '...' }.
|
||||
name: Record<string, string>;
|
||||
description?: Record<string, string>;
|
||||
languages: string[];
|
||||
roles: { slug: string; version: number }[];
|
||||
}
|
||||
|
||||
/** Top-level catalog index: `index.json`. */
|
||||
export interface CatalogIndex {
|
||||
schemaVersion: number;
|
||||
bundles: CatalogBundleMeta[];
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
import {
|
||||
IsArray,
|
||||
IsIn,
|
||||
IsOptional,
|
||||
IsString,
|
||||
IsUUID,
|
||||
Matches,
|
||||
MaxLength,
|
||||
} from 'class-validator';
|
||||
|
||||
/** Safe identifier shape for any catalog path segment (bundleId / language).
|
||||
* Mirrors SEGMENT_RE in the catalog provider — the path-traversal/SSRF guard
|
||||
* is enforced both at the API boundary (here) and in the provider. */
|
||||
const SEGMENT_RE = /^[a-z0-9-]+$/;
|
||||
|
||||
/** Browse the catalog, optionally localized to `language` (defaults applied in
|
||||
* the service: fall back to 'en', then the first available language). */
|
||||
export class CatalogQueryDto {
|
||||
@IsOptional()
|
||||
@IsString()
|
||||
@MaxLength(16)
|
||||
language?: string;
|
||||
}
|
||||
|
||||
/** Open one catalog bundle in a specific language. */
|
||||
export class CatalogBundleDto {
|
||||
@IsString()
|
||||
@Matches(SEGMENT_RE)
|
||||
bundleId: string;
|
||||
|
||||
@IsString()
|
||||
@Matches(SEGMENT_RE)
|
||||
language: string;
|
||||
}
|
||||
|
||||
/** Import roles from a catalog bundle into the workspace. */
|
||||
export class ImportFromCatalogDto {
|
||||
@IsString()
|
||||
@Matches(SEGMENT_RE)
|
||||
bundleId: string;
|
||||
|
||||
@IsString()
|
||||
@Matches(SEGMENT_RE)
|
||||
language: string;
|
||||
|
||||
// Omitted => import the whole bundle; otherwise only these slugs.
|
||||
@IsOptional()
|
||||
@IsArray()
|
||||
@IsString({ each: true })
|
||||
slugs?: string[];
|
||||
|
||||
// How to handle a name collision with an existing (non-catalog) role:
|
||||
// 'skip' leaves it; 'rename' imports under a free " (N)" name.
|
||||
@IsIn(['skip', 'rename'])
|
||||
conflict: 'skip' | 'rename';
|
||||
}
|
||||
|
||||
/** Update an already-imported role from its catalog source. */
|
||||
export class UpdateFromCatalogDto {
|
||||
@IsUUID()
|
||||
id: string;
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
import { type Kysely } from 'kysely';
|
||||
|
||||
export async function up(db: Kysely<any>): Promise<void> {
|
||||
// `source` links an imported role back to its catalog origin
|
||||
// `{ slug, language, version }`. Nullable: null => a manually-created role
|
||||
// (no catalog provenance). The version lets the admin UI offer an UPDATE when
|
||||
// the catalog ships a newer revision of the same slug.
|
||||
await db.schema
|
||||
.alterTable('ai_agent_roles')
|
||||
.addColumn('source', 'jsonb', (col) => col)
|
||||
.execute();
|
||||
}
|
||||
|
||||
export async function down(db: Kysely<any>): Promise<void> {
|
||||
await db.schema
|
||||
.alterTable('ai_agent_roles')
|
||||
.dropColumn('source')
|
||||
.execute();
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
import { type Kysely, sql } from 'kysely';
|
||||
|
||||
export async function up(db: Kysely<any>): Promise<void> {
|
||||
// A catalog-imported role is uniquely identified within a workspace by its
|
||||
// `source.slug` + `source.language` (a multilingual catalog: the `ru` variant
|
||||
// of a slug installed as `en` is a SEPARATE install — hence both keys). The
|
||||
// import path skips a slug+language already installed using an in-memory
|
||||
// snapshot (installedKeys), but two CONCURRENT imports of the same bundle each
|
||||
// read a stale snapshot and would both insert the same slug+language,
|
||||
// duplicating the role. This partial unique index is the database-level
|
||||
// backstop: the second insert gets a 23505 the service treats as
|
||||
// "already installed" (skip), so the two imports converge on ONE role.
|
||||
//
|
||||
// Partial on `source IS NOT NULL` so MANUALLY-created roles (source NULL) are
|
||||
// unconstrained — there can be many of those. Also partial on
|
||||
// `deleted_at IS NULL` (like the existing name-unique index) so a soft-deleted
|
||||
// role does not block re-importing the same slug+language later, matching the
|
||||
// app's snapshot (listByWorkspace filters out soft-deleted rows).
|
||||
await sql`
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS ai_agent_roles_workspace_source_unique
|
||||
ON ai_agent_roles (workspace_id, (source ->> 'slug'), (source ->> 'language'))
|
||||
WHERE source IS NOT NULL AND deleted_at IS NULL
|
||||
`.execute(db);
|
||||
}
|
||||
|
||||
export async function down(db: Kysely<any>): Promise<void> {
|
||||
await db.schema
|
||||
.dropIndex('ai_agent_roles_workspace_source_unique')
|
||||
.ifExists()
|
||||
.execute();
|
||||
}
|
||||
@@ -1,4 +1,4 @@
|
||||
import { AiAgentRoleRepo } from './ai-agent-roles.repo';
|
||||
import { AiAgentRoleRepo, parseSource } from './ai-agent-roles.repo';
|
||||
import type { KyselyDB } from '../../types/kysely.types';
|
||||
|
||||
/**
|
||||
@@ -132,4 +132,77 @@ describe('AiAgentRoleRepo insert/update auto-start columns', () => {
|
||||
expect(set2.mock.calls[0][0].launchMessage).toBeNull();
|
||||
expect('autoStart' in set2.mock.calls[0][0]).toBe(false);
|
||||
});
|
||||
|
||||
it('insert binds `source` (jsonb); update sets it only when present', async () => {
|
||||
const { repo, values } = makeInsertRepo();
|
||||
await repo.insert({
|
||||
workspaceId: 'ws-1',
|
||||
name: 'R',
|
||||
instructions: 'do',
|
||||
source: { slug: 'researcher', language: 'en', version: 1 },
|
||||
});
|
||||
// jsonbBind returns a RawBuilder for a non-empty object (not null).
|
||||
expect(values.mock.calls[0][0].source).not.toBeNull();
|
||||
|
||||
const { repo: repo2, set } = makeUpdateRepo();
|
||||
await repo2.update('r-1', 'ws-1', { name: 'X' });
|
||||
expect('source' in set.mock.calls[0][0]).toBe(false);
|
||||
|
||||
const { repo: repo3, set: set3 } = makeUpdateRepo();
|
||||
await repo3.update('r-1', 'ws-1', {
|
||||
source: { slug: 's', language: 'en', version: 2 },
|
||||
});
|
||||
expect('source' in set3.mock.calls[0][0]).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* parseSource is THE single form validator for the `source` jsonb column: a
|
||||
* JSON-string (legacy double-encoded) is parsed; a FULLY-VALID object
|
||||
* ({ slug, language, version }) passes through as a typed RoleSource; anything
|
||||
* partial or wrong-shaped degrades to null (= manual role). This is the
|
||||
* stricter-than-before guard that closes the drift where a weak `{}`/`{slug:123}`
|
||||
* value used to be stamped as a valid source by the read path.
|
||||
*/
|
||||
describe('parseSource', () => {
|
||||
it('parses a legacy double-encoded JSON string into the typed source', () => {
|
||||
expect(
|
||||
parseSource('{"slug":"researcher","language":"en","version":1}'),
|
||||
).toEqual({ slug: 'researcher', language: 'en', version: 1 });
|
||||
});
|
||||
|
||||
it('passes a fully-valid already-parsed object through', () => {
|
||||
const obj = { slug: 's', language: 'en', version: 2 };
|
||||
expect(parseSource(obj)).toEqual(obj);
|
||||
});
|
||||
|
||||
it('returns the typed RoleSource (extra keys tolerated) for a valid shape', () => {
|
||||
const src = parseSource({ slug: 's', language: 'ru', version: 3 });
|
||||
expect(src).not.toBeNull();
|
||||
// Narrowed to RoleSource: the fields are present and correctly typed.
|
||||
expect(src?.slug).toBe('s');
|
||||
expect(src?.language).toBe('ru');
|
||||
expect(src?.version).toBe(3);
|
||||
});
|
||||
|
||||
it('null / array / non-object / unparseable string => null', () => {
|
||||
expect(parseSource(null)).toBeNull();
|
||||
expect(parseSource([1, 2])).toBeNull();
|
||||
expect(parseSource(42)).toBeNull();
|
||||
expect(parseSource('not json')).toBeNull();
|
||||
});
|
||||
|
||||
it('partial / wrong-typed shapes => null (no weak-but-typed-as-valid drift)', () => {
|
||||
// Empty object: no slug/language/version.
|
||||
expect(parseSource({})).toBeNull();
|
||||
// slug present but not a string.
|
||||
expect(parseSource({ slug: 123, language: 'en', version: 1 })).toBeNull();
|
||||
// slug only, missing language + version.
|
||||
expect(parseSource({ slug: 'a' })).toBeNull();
|
||||
// empty-string slug / language are not valid catalog keys.
|
||||
expect(parseSource({ slug: '', language: 'en', version: 1 })).toBeNull();
|
||||
expect(parseSource({ slug: 'a', language: '', version: 1 })).toBeNull();
|
||||
// version must be a number, not a numeric string.
|
||||
expect(parseSource({ slug: 'a', language: 'en', version: '1' })).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
@@ -2,7 +2,7 @@ import { Injectable } from '@nestjs/common';
|
||||
import { InjectKysely } from 'nestjs-kysely';
|
||||
import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
|
||||
import { dbOrTx, jsonbBind, parseJsonbValue } from '../../utils';
|
||||
import { AiAgentRole } from '@docmost/db/types/entity.types';
|
||||
import { AiAgentRole, RoleSource } from '@docmost/db/types/entity.types';
|
||||
|
||||
/** The jsonb shape persisted in `model_config` (loosely typed for the column). */
|
||||
type ModelConfigValue = Record<string, unknown> | null;
|
||||
@@ -81,6 +81,8 @@ export class AiAgentRoleRepo {
|
||||
autoStart?: boolean;
|
||||
// null/'' => stored as null (client default launch message).
|
||||
launchMessage?: string | null;
|
||||
// Catalog origin { slug, language, version } | null. null => manual role.
|
||||
source?: Record<string, unknown> | null;
|
||||
},
|
||||
trx?: KyselyTransaction,
|
||||
): Promise<AiAgentRole> {
|
||||
@@ -103,6 +105,9 @@ export class AiAgentRoleRepo {
|
||||
autoStart: values.autoStart ?? true,
|
||||
// Empty string is treated as "no custom text" => null.
|
||||
launchMessage: values.launchMessage || null,
|
||||
// Same cast reason as modelConfig (see above).
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
source: jsonbBind(values.source) as any,
|
||||
})
|
||||
.returningAll()
|
||||
.executeTakeFirst();
|
||||
@@ -124,6 +129,8 @@ export class AiAgentRoleRepo {
|
||||
autoStart?: boolean;
|
||||
// undefined => unchanged; null/'' => clear to null; string => set.
|
||||
launchMessage?: string | null;
|
||||
// undefined => unchanged; null => clear; object => set.
|
||||
source?: Record<string, unknown> | null;
|
||||
},
|
||||
trx?: KyselyTransaction,
|
||||
): Promise<void> {
|
||||
@@ -142,6 +149,9 @@ export class AiAgentRoleRepo {
|
||||
// Empty string clears to null (client default launch message).
|
||||
set.launchMessage = patch.launchMessage || null;
|
||||
}
|
||||
if (patch.source !== undefined) {
|
||||
set.source = jsonbBind(patch.source);
|
||||
}
|
||||
await db
|
||||
.updateTable('aiAgentRoles')
|
||||
.set(set)
|
||||
@@ -192,14 +202,46 @@ export function parseModelConfig(
|
||||
);
|
||||
}
|
||||
|
||||
/** Normalize a DB row so `modelConfig` is always an object or null. The cast
|
||||
* bridges parseModelConfig's concrete `Record | null` to the column's broad
|
||||
* generated `JsonValue` type (an object is a valid JsonValue at runtime). */
|
||||
/**
|
||||
* THE single form validator for the `source` jsonb column: parse the value read
|
||||
* from the DB into a fully-valid {@link RoleSource} or null. Same legacy
|
||||
* double-encoding self-heal as {@link parseModelConfig} (a JSON string is parsed
|
||||
* once), then validates the FULL shape — `slug` and `language` non-empty
|
||||
* strings, `version` a number. A null / corrupt / partially-shaped value (e.g.
|
||||
* `{}`, `{ slug: 123 }`, `{ slug: 'a' }` missing language/version) degrades to
|
||||
* null (= manually created, no catalog provenance), so a bad row never breaks
|
||||
* the read path AND never stamps a half-built object as a valid `RoleSource`.
|
||||
* Both the repo read-path and the service share this so the contract cannot
|
||||
* drift between layers.
|
||||
*/
|
||||
export function parseSource(value: unknown): RoleSource | null {
|
||||
return parseJsonbValue(value, isRoleSource);
|
||||
}
|
||||
|
||||
/** Full-shape guard for a persisted `source` jsonb value (see parseSource). */
|
||||
function isRoleSource(v: unknown): v is RoleSource {
|
||||
if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
|
||||
const obj = v as Record<string, unknown>;
|
||||
return (
|
||||
typeof obj.slug === 'string' &&
|
||||
obj.slug.length > 0 &&
|
||||
typeof obj.language === 'string' &&
|
||||
obj.language.length > 0 &&
|
||||
typeof obj.version === 'number'
|
||||
);
|
||||
}
|
||||
|
||||
/** Normalize a DB row so `modelConfig` and `source` are always a valid object or
|
||||
* null. The casts bridge the concrete parsed types (`Record | null`,
|
||||
* `RoleSource | null`) to the column's broad generated `JsonValue` type — both
|
||||
* are valid JsonValues at runtime; RoleSource lacks the JsonObject index
|
||||
* signature so it routes through `unknown`. */
|
||||
function normalizeRow(row: AiAgentRole): AiAgentRole {
|
||||
return {
|
||||
...row,
|
||||
modelConfig: parseModelConfig(
|
||||
row.modelConfig,
|
||||
) as AiAgentRole['modelConfig'],
|
||||
source: parseSource(row.source) as unknown as AiAgentRole['source'],
|
||||
};
|
||||
}
|
||||
|
||||
2
apps/server/src/database/types/db.d.ts
vendored
2
apps/server/src/database/types/db.d.ts
vendored
@@ -618,6 +618,8 @@ export interface AiAgentRoles {
|
||||
autoStart: Generated<boolean>;
|
||||
// Optional custom auto-start text. null/empty => client default launch message.
|
||||
launchMessage: string | null;
|
||||
// Catalog origin of an imported role: { slug, language, version } | null. null => manually created.
|
||||
source: Json | null;
|
||||
createdAt: Generated<Timestamp>;
|
||||
updatedAt: Generated<Timestamp>;
|
||||
deletedAt: Timestamp | null;
|
||||
|
||||
@@ -81,6 +81,24 @@ export type UpdatableAiMcpServer = Updateable<Omit<AiMcpServersTable, 'id'>>;
|
||||
// A role replaces the persona layer of the system prompt (instructions) and may
|
||||
// optionally override the chat model (`modelConfig`). Soft-deletable.
|
||||
export type AiAgentRole = Selectable<AiAgentRoles>;
|
||||
|
||||
/**
|
||||
* The validated shape of the `source` jsonb column on ai_agent_roles: the
|
||||
* catalog origin of an imported role. `version` lets the admin UI offer an
|
||||
* UPDATE when the catalog ships a newer revision of the same slug; null `source`
|
||||
* (not this type) means a manually-created role with no catalog provenance.
|
||||
*
|
||||
* THE single contract for that column, shared by the repo read-path
|
||||
* (`parseSource`, the only form validator) and the service, so the persisted
|
||||
* shape can never be validated weakly in one layer and strongly in another.
|
||||
* Defined here (a leaf db-types module both already import `AiAgentRole` from) to
|
||||
* avoid an import cycle between the repo and the service.
|
||||
*/
|
||||
export interface RoleSource {
|
||||
slug: string;
|
||||
language: string;
|
||||
version: number;
|
||||
}
|
||||
export type InsertableAiAgentRole = Insertable<AiAgentRoles>;
|
||||
export type UpdatableAiAgentRole = Updateable<Omit<AiAgentRoles, 'id'>>;
|
||||
|
||||
|
||||
@@ -289,6 +289,15 @@ export class EnvironmentService {
|
||||
// provider/model/key config now lives solely in workspace settings +
|
||||
// ai_provider_credentials, with no env fallback. APP_SECRET stays (getAppSecret).
|
||||
|
||||
getAiAgentRolesCatalogSource(): string {
|
||||
// Catalog location. http(s):// URL => fetched remotely; anything else => a
|
||||
// local filesystem directory. Defaults to the in-repo folder (dev). In prod
|
||||
// set this to the raw GitHub base URL of the catalog repo. Unlike the AI_*
|
||||
// getters above this is INFRA config (where the catalog lives), not
|
||||
// provider/model config — so an env var here is appropriate.
|
||||
return this.configService.get<string>('AI_AGENT_ROLES_CATALOG_URL', '');
|
||||
}
|
||||
|
||||
getEventStoreDriver(): string {
|
||||
return this.configService
|
||||
.get<string>('EVENT_STORE_DRIVER', 'postgres')
|
||||
|
||||
Reference in New Issue
Block a user