Compare commits
1 Commits
726f7ab772
...
release/mo
| Author | SHA1 | Date | |
|---|---|---|---|
|
5096b31233 |
@@ -5,5 +5,3 @@ pnpm-lock.yaml
|
||||
**/drizzle
|
||||
**/.next
|
||||
.claude/
|
||||
docs/tess/TASKS.md
|
||||
docs/scratchpads/
|
||||
|
||||
@@ -7,14 +7,7 @@ variables:
|
||||
- &enable_pnpm 'corepack enable'
|
||||
|
||||
when:
|
||||
# PR + manual CI run on any branch — the pull_request pipeline is the merge gate.
|
||||
# push CI is restricted to protected branches (main) so a feature-branch push no
|
||||
# longer fires a redundant SECOND pipeline alongside its PR pipeline. This ~halves
|
||||
# CI load on the storage-constrained runner with zero loss of gating (branch
|
||||
# protection requires no push/ci status context; main still gets full push CI).
|
||||
- event: [pull_request, manual]
|
||||
- event: push
|
||||
branch: main
|
||||
- event: [push, pull_request, manual]
|
||||
|
||||
# Turbo remote cache (turbo.mosaicstack.dev) is configured via Woodpecker
|
||||
# repository-level environment variables (TURBO_API, TURBO_TEAM, TURBO_TOKEN).
|
||||
|
||||
@@ -31,7 +31,6 @@
|
||||
"@mariozechner/pi-ai": "^0.65.0",
|
||||
"@mariozechner/pi-coding-agent": "^0.65.0",
|
||||
"@modelcontextprotocol/sdk": "^1.27.1",
|
||||
"@mosaicstack/agent": "workspace:^",
|
||||
"@mosaicstack/auth": "workspace:^",
|
||||
"@mosaicstack/brain": "workspace:^",
|
||||
"@mosaicstack/config": "workspace:^",
|
||||
|
||||
@@ -20,7 +20,7 @@ export class AdminHealthController {
|
||||
async check(): Promise<HealthStatusDto> {
|
||||
const [database, cache] = await Promise.all([this.checkDatabase(), this.checkCache()]);
|
||||
|
||||
const sessions = this.agentService.listAllSessionsForSystem();
|
||||
const sessions = this.agentService.listSessions();
|
||||
const providers = this.providerService.listProviders();
|
||||
|
||||
const allOk = database.status === 'ok' && cache.status === 'ok';
|
||||
|
||||
@@ -1,142 +0,0 @@
|
||||
import { ForbiddenException } from '@nestjs/common';
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import { AgentService, type AgentSession } from '../agent.service.js';
|
||||
import type { ActorTenantScope } from '../../auth/session-scope.js';
|
||||
|
||||
const CONVERSATION_ID = '22222222-2222-4222-8222-222222222222';
|
||||
const OWNER_SCOPE: ActorTenantScope = { userId: 'owner-user', tenantId: 'owner-tenant' };
|
||||
const FOREIGN_SCOPE: ActorTenantScope = { userId: 'foreign-user', tenantId: 'foreign-tenant' };
|
||||
|
||||
type AgentServiceInternals = {
|
||||
sessions: Map<string, AgentSession>;
|
||||
creating: Map<string, Promise<AgentSession>>;
|
||||
};
|
||||
|
||||
function makeService(): AgentService {
|
||||
return new AgentService(
|
||||
{} as never,
|
||||
{} as never,
|
||||
{} as never,
|
||||
{ available: false } as never,
|
||||
{} as never,
|
||||
{} as never,
|
||||
{} as never,
|
||||
null,
|
||||
null,
|
||||
{ collect: vi.fn().mockResolvedValue(undefined) } as never,
|
||||
);
|
||||
}
|
||||
|
||||
function internals(service: AgentService): AgentServiceInternals {
|
||||
return service as unknown as AgentServiceInternals;
|
||||
}
|
||||
|
||||
function makeSession(scope: ActorTenantScope = OWNER_SCOPE): AgentSession {
|
||||
return {
|
||||
id: CONVERSATION_ID,
|
||||
provider: 'test-provider',
|
||||
modelId: 'test-model',
|
||||
piSession: {
|
||||
thinkingLevel: 'off',
|
||||
getAvailableThinkingLevels: vi.fn().mockReturnValue(['off', 'low', 'high']),
|
||||
setThinkingLevel: vi.fn(),
|
||||
abort: vi.fn().mockResolvedValue(undefined),
|
||||
prompt: vi.fn().mockResolvedValue(undefined),
|
||||
dispose: vi.fn(),
|
||||
getSessionStats: vi.fn(),
|
||||
getContextUsage: vi.fn(),
|
||||
} as unknown as AgentSession['piSession'],
|
||||
listeners: new Set(),
|
||||
unsubscribe: vi.fn(),
|
||||
createdAt: Date.now(),
|
||||
promptCount: 0,
|
||||
channels: new Set(),
|
||||
skillPromptAdditions: [],
|
||||
sandboxDir: '/tmp/tess-session-ownership-test',
|
||||
allowedTools: null,
|
||||
userId: scope.userId,
|
||||
tenantId: scope.tenantId,
|
||||
metrics: {
|
||||
tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
|
||||
modelSwitches: 0,
|
||||
messageCount: 0,
|
||||
lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe('AgentService owner/tenant scope enforcement', () => {
|
||||
it('allows owner-scoped operations and rejects foreign scopes for seeded sessions', async () => {
|
||||
const service = makeService();
|
||||
const session = makeSession();
|
||||
internals(service).sessions.set(CONVERSATION_ID, session);
|
||||
|
||||
expect(service.getSession(CONVERSATION_ID, OWNER_SCOPE)).toBe(session);
|
||||
expect(service.getSession(CONVERSATION_ID, FOREIGN_SCOPE)).toBeUndefined();
|
||||
expect(service.getSessionInfo(CONVERSATION_ID, FOREIGN_SCOPE)).toBeUndefined();
|
||||
expect(service.listSessions(OWNER_SCOPE)).toHaveLength(1);
|
||||
expect(service.listSessions(FOREIGN_SCOPE)).toEqual([]);
|
||||
|
||||
service.addChannel(CONVERSATION_ID, 'websocket:owner', OWNER_SCOPE);
|
||||
expect(session.channels.has('websocket:owner')).toBe(true);
|
||||
expect(() => service.addChannel(CONVERSATION_ID, 'websocket:foreign', FOREIGN_SCOPE)).toThrow(
|
||||
ForbiddenException,
|
||||
);
|
||||
expect(() => service.removeChannel(CONVERSATION_ID, 'websocket:owner', FOREIGN_SCOPE)).toThrow(
|
||||
ForbiddenException,
|
||||
);
|
||||
|
||||
expect(() =>
|
||||
service.updateSessionModel(CONVERSATION_ID, 'foreign-model', FOREIGN_SCOPE),
|
||||
).toThrow(ForbiddenException);
|
||||
service.updateSessionModel(CONVERSATION_ID, 'owner-model', OWNER_SCOPE);
|
||||
expect(session.modelId).toBe('owner-model');
|
||||
|
||||
expect(() =>
|
||||
service.applyAgentConfig(CONVERSATION_ID, 'agent-foreign', 'Foreign Agent', FOREIGN_SCOPE),
|
||||
).toThrow(ForbiddenException);
|
||||
service.applyAgentConfig(CONVERSATION_ID, 'agent-owner', 'Owner Agent', OWNER_SCOPE);
|
||||
expect(session.agentConfigId).toBe('agent-owner');
|
||||
|
||||
expect(() => service.onEvent(CONVERSATION_ID, vi.fn(), FOREIGN_SCOPE)).toThrow(
|
||||
ForbiddenException,
|
||||
);
|
||||
const cleanup = service.onEvent(CONVERSATION_ID, vi.fn(), OWNER_SCOPE);
|
||||
cleanup();
|
||||
|
||||
await expect(
|
||||
service.prompt(CONVERSATION_ID, 'foreign prompt', FOREIGN_SCOPE),
|
||||
).rejects.toBeInstanceOf(ForbiddenException);
|
||||
await service.prompt(CONVERSATION_ID, 'owner prompt', OWNER_SCOPE);
|
||||
expect(session.piSession.prompt).toHaveBeenCalledWith('owner prompt');
|
||||
|
||||
await expect(service.destroySession(CONVERSATION_ID, FOREIGN_SCOPE)).rejects.toBeInstanceOf(
|
||||
ForbiddenException,
|
||||
);
|
||||
expect(internals(service).sessions.has(CONVERSATION_ID)).toBe(true);
|
||||
|
||||
await service.destroySession(CONVERSATION_ID, OWNER_SCOPE);
|
||||
expect(session.piSession.dispose).toHaveBeenCalled();
|
||||
expect(internals(service).sessions.has(CONVERSATION_ID)).toBe(false);
|
||||
});
|
||||
|
||||
it('checks owner/tenant scope before returning an in-flight session creation', async () => {
|
||||
const service = makeService();
|
||||
const session = makeSession();
|
||||
internals(service).creating.set(CONVERSATION_ID, Promise.resolve(session));
|
||||
|
||||
await expect(
|
||||
service.createSession(CONVERSATION_ID, {
|
||||
userId: FOREIGN_SCOPE.userId,
|
||||
tenantId: FOREIGN_SCOPE.tenantId,
|
||||
}),
|
||||
).rejects.toBeInstanceOf(ForbiddenException);
|
||||
|
||||
await expect(
|
||||
service.createSession(CONVERSATION_ID, {
|
||||
userId: OWNER_SCOPE.userId,
|
||||
tenantId: OWNER_SCOPE.tenantId,
|
||||
}),
|
||||
).resolves.toBe(session);
|
||||
});
|
||||
});
|
||||
@@ -1,285 +0,0 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import type {
|
||||
AgentRuntimeProvider,
|
||||
RuntimeAttachHandle,
|
||||
RuntimeAttachMode,
|
||||
RuntimeCapability,
|
||||
RuntimeCapabilitySet,
|
||||
RuntimeHealth,
|
||||
RuntimeMessage,
|
||||
RuntimeScope,
|
||||
RuntimeSession,
|
||||
RuntimeSessionTree,
|
||||
RuntimeStreamEvent,
|
||||
} from '@mosaicstack/types';
|
||||
import { AgentRuntimeProviderRegistry } from '@mosaicstack/agent';
|
||||
import type { ActorTenantScope } from '../../auth/session-scope.js';
|
||||
import {
|
||||
RuntimeProviderService,
|
||||
type RuntimeAuditEvent,
|
||||
type RuntimeAuditSink,
|
||||
type RuntimeApprovalVerifier,
|
||||
} from '../runtime-provider-registry.service.js';
|
||||
|
||||
const OWNER_SCOPE: ActorTenantScope = { userId: 'owner-1', tenantId: 'tenant-1' };
|
||||
const CONTEXT = {
|
||||
actorScope: OWNER_SCOPE,
|
||||
channelId: 'cli',
|
||||
correlationId: 'correlation-1',
|
||||
};
|
||||
|
||||
class RecordingRuntimeProvider implements AgentRuntimeProvider {
|
||||
readonly id = 'fleet';
|
||||
readonly receivedScopes: RuntimeScope[] = [];
|
||||
readonly sentMessages: RuntimeMessage[] = [];
|
||||
terminateCalls = 0;
|
||||
throwAfterSend = false;
|
||||
|
||||
constructor(private readonly supported: RuntimeCapability[]) {}
|
||||
|
||||
async capabilities(scope: RuntimeScope): Promise<RuntimeCapabilitySet> {
|
||||
this.receivedScopes.push(scope);
|
||||
return { supported: this.supported };
|
||||
}
|
||||
|
||||
async health(scope: RuntimeScope): Promise<RuntimeHealth> {
|
||||
this.receivedScopes.push(scope);
|
||||
return { status: 'healthy', checkedAt: '2026-07-12T00:00:00.000Z' };
|
||||
}
|
||||
|
||||
async listSessions(scope: RuntimeScope): Promise<RuntimeSession[]> {
|
||||
this.receivedScopes.push(scope);
|
||||
return [];
|
||||
}
|
||||
|
||||
async getSessionTree(scope: RuntimeScope): Promise<RuntimeSessionTree[]> {
|
||||
this.receivedScopes.push(scope);
|
||||
return [];
|
||||
}
|
||||
|
||||
async *streamSession(
|
||||
_sessionId: string,
|
||||
_cursor: string | undefined,
|
||||
scope: RuntimeScope,
|
||||
): AsyncIterable<RuntimeStreamEvent> {
|
||||
this.receivedScopes.push(scope);
|
||||
return;
|
||||
}
|
||||
|
||||
async sendMessage(
|
||||
_sessionId: string,
|
||||
message: RuntimeMessage,
|
||||
scope: RuntimeScope,
|
||||
): Promise<void> {
|
||||
this.receivedScopes.push(scope);
|
||||
this.sentMessages.push(message);
|
||||
if (this.throwAfterSend) {
|
||||
throw new Error('provider acknowledgement failed');
|
||||
}
|
||||
}
|
||||
|
||||
async attach(
|
||||
sessionId: string,
|
||||
mode: RuntimeAttachMode,
|
||||
scope: RuntimeScope,
|
||||
): Promise<RuntimeAttachHandle> {
|
||||
this.receivedScopes.push(scope);
|
||||
return {
|
||||
attachmentId: 'attachment-1',
|
||||
sessionId,
|
||||
mode,
|
||||
expiresAt: '2026-07-12T00:00:00.000Z',
|
||||
};
|
||||
}
|
||||
|
||||
async detach(_attachmentId: string, scope: RuntimeScope): Promise<void> {
|
||||
this.receivedScopes.push(scope);
|
||||
}
|
||||
|
||||
async terminate(_sessionId: string, _approvalRef: string, scope: RuntimeScope): Promise<void> {
|
||||
this.receivedScopes.push(scope);
|
||||
this.terminateCalls += 1;
|
||||
}
|
||||
}
|
||||
|
||||
class RecordingAuditSink implements RuntimeAuditSink {
|
||||
readonly events: RuntimeAuditEvent[] = [];
|
||||
|
||||
async record(event: RuntimeAuditEvent): Promise<void> {
|
||||
this.events.push(event);
|
||||
}
|
||||
}
|
||||
|
||||
class DenyingApprovalVerifier implements RuntimeApprovalVerifier {
|
||||
async consume(): Promise<boolean> {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
class AcceptingApprovalVerifier implements RuntimeApprovalVerifier {
|
||||
consumedAction: Parameters<RuntimeApprovalVerifier['consume']>[1] | undefined;
|
||||
|
||||
async consume(
|
||||
_approvalRef: string,
|
||||
action: Parameters<RuntimeApprovalVerifier['consume']>[1],
|
||||
): Promise<boolean> {
|
||||
this.consumedAction = action;
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
function makeService(
|
||||
provider: RecordingRuntimeProvider,
|
||||
audit: RuntimeAuditSink = new RecordingAuditSink(),
|
||||
approval: RuntimeApprovalVerifier = new DenyingApprovalVerifier(),
|
||||
): RuntimeProviderService {
|
||||
const registry = new AgentRuntimeProviderRegistry();
|
||||
registry.register(provider);
|
||||
return new RuntimeProviderService(registry, audit, approval);
|
||||
}
|
||||
|
||||
describe('RuntimeProviderService security boundary', (): void => {
|
||||
it('derives and freezes only the authenticated actor scope while preserving correlation metadata', async (): Promise<void> => {
|
||||
const provider = new RecordingRuntimeProvider(['session.send']);
|
||||
const audit = new RecordingAuditSink();
|
||||
const service = makeService(provider, audit);
|
||||
|
||||
await service.sendMessage(
|
||||
'fleet',
|
||||
'session-1',
|
||||
{ content: 'hello', idempotencyKey: 'key-1' },
|
||||
CONTEXT,
|
||||
);
|
||||
|
||||
const providerScope = provider.receivedScopes[0];
|
||||
expect(providerScope).toEqual({
|
||||
actorId: OWNER_SCOPE.userId,
|
||||
tenantId: OWNER_SCOPE.tenantId,
|
||||
channelId: CONTEXT.channelId,
|
||||
correlationId: CONTEXT.correlationId,
|
||||
});
|
||||
expect(Object.isFrozen(providerScope)).toBe(true);
|
||||
expect(audit.events).toContainEqual({
|
||||
providerId: 'fleet',
|
||||
operation: 'session.send',
|
||||
outcome: 'succeeded',
|
||||
actorId: OWNER_SCOPE.userId,
|
||||
tenantId: OWNER_SCOPE.tenantId,
|
||||
channelId: CONTEXT.channelId,
|
||||
correlationId: CONTEXT.correlationId,
|
||||
resourceId: 'session-1',
|
||||
});
|
||||
expect(JSON.stringify(audit.events)).not.toContain('hello');
|
||||
expect(JSON.stringify(audit.events)).not.toContain('key-1');
|
||||
});
|
||||
|
||||
it('fails closed before a provider side effect when a capability is missing', async (): Promise<void> => {
|
||||
const provider = new RecordingRuntimeProvider([]);
|
||||
const service = makeService(provider);
|
||||
|
||||
await expect(
|
||||
service.sendMessage(
|
||||
'fleet',
|
||||
'session-1',
|
||||
{ content: 'hello', idempotencyKey: 'key-1' },
|
||||
CONTEXT,
|
||||
),
|
||||
).rejects.toThrow(/capability denied/);
|
||||
expect(provider.sentMessages).toEqual([]);
|
||||
});
|
||||
|
||||
it('requires a consumed exact-action approval before termination', async (): Promise<void> => {
|
||||
const provider = new RecordingRuntimeProvider(['session.terminate']);
|
||||
const approval = new DenyingApprovalVerifier();
|
||||
const service = makeService(provider, new RecordingAuditSink(), approval);
|
||||
|
||||
await expect(
|
||||
service.terminate('fleet', 'session-1', 'forged-approval', CONTEXT),
|
||||
).rejects.toThrow(/approval denied/);
|
||||
expect(provider.terminateCalls).toBe(0);
|
||||
});
|
||||
|
||||
it('binds an accepted termination approval to provider, session, immutable scope, and correlation', async (): Promise<void> => {
|
||||
const provider = new RecordingRuntimeProvider(['session.terminate']);
|
||||
const approval = new AcceptingApprovalVerifier();
|
||||
const service = makeService(provider, new RecordingAuditSink(), approval);
|
||||
|
||||
await service.terminate('fleet', 'session-1', 'approval-1', CONTEXT);
|
||||
|
||||
expect(approval.consumedAction).toEqual({
|
||||
providerId: 'fleet',
|
||||
sessionId: 'session-1',
|
||||
actorId: OWNER_SCOPE.userId,
|
||||
tenantId: OWNER_SCOPE.tenantId,
|
||||
channelId: CONTEXT.channelId,
|
||||
correlationId: CONTEXT.correlationId,
|
||||
});
|
||||
expect(provider.terminateCalls).toBe(1);
|
||||
});
|
||||
|
||||
it('fails closed before invoking a provider when audit persistence rejects the request', async (): Promise<void> => {
|
||||
const provider = new RecordingRuntimeProvider(['session.send']);
|
||||
const unavailableAudit: RuntimeAuditSink = {
|
||||
async record(): Promise<void> {
|
||||
throw new Error('audit unavailable');
|
||||
},
|
||||
};
|
||||
const service = makeService(provider, unavailableAudit);
|
||||
|
||||
await expect(
|
||||
service.sendMessage(
|
||||
'fleet',
|
||||
'session-1',
|
||||
{ content: 'hello', idempotencyKey: 'key-1' },
|
||||
CONTEXT,
|
||||
),
|
||||
).rejects.toThrow(/audit unavailable/);
|
||||
expect(provider.sentMessages).toEqual([]);
|
||||
});
|
||||
|
||||
it('records a provider error after invocation as failed rather than denied', async (): Promise<void> => {
|
||||
const provider = new RecordingRuntimeProvider(['session.send']);
|
||||
provider.throwAfterSend = true;
|
||||
const audit = new RecordingAuditSink();
|
||||
const service = makeService(provider, audit);
|
||||
|
||||
await expect(
|
||||
service.sendMessage(
|
||||
'fleet',
|
||||
'session-1',
|
||||
{ content: 'hello', idempotencyKey: 'key-1' },
|
||||
CONTEXT,
|
||||
),
|
||||
).rejects.toThrow(/provider acknowledgement failed/);
|
||||
expect(provider.sentMessages).toHaveLength(1);
|
||||
expect(audit.events.map((event: RuntimeAuditEvent): string => event.outcome)).toEqual([
|
||||
'requested',
|
||||
'failed',
|
||||
]);
|
||||
});
|
||||
|
||||
it('does not misreport a completed provider side effect when completion auditing fails', async (): Promise<void> => {
|
||||
const provider = new RecordingRuntimeProvider(['session.send']);
|
||||
let auditCalls = 0;
|
||||
const audit: RuntimeAuditSink = {
|
||||
async record(): Promise<void> {
|
||||
auditCalls += 1;
|
||||
if (auditCalls === 2) {
|
||||
throw new Error('completion audit unavailable');
|
||||
}
|
||||
},
|
||||
};
|
||||
const service = makeService(provider, audit);
|
||||
|
||||
await expect(
|
||||
service.sendMessage(
|
||||
'fleet',
|
||||
'session-1',
|
||||
{ content: 'hello', idempotencyKey: 'key-1' },
|
||||
CONTEXT,
|
||||
),
|
||||
).resolves.toBeUndefined();
|
||||
expect(provider.sentMessages).toHaveLength(1);
|
||||
expect(auditCalls).toBe(2);
|
||||
});
|
||||
});
|
||||
@@ -1,262 +0,0 @@
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { resolve } from 'node:path';
|
||||
import { ForbiddenException, NotFoundException } from '@nestjs/common';
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
|
||||
vi.mock('../agent.service.js', () => ({ AgentService: class AgentService {} }));
|
||||
vi.mock('../../commands/command-executor.service.js', () => ({
|
||||
CommandExecutorService: class CommandExecutorService {},
|
||||
}));
|
||||
vi.mock('../routing/routing-engine.service.js', () => ({
|
||||
RoutingEngineService: class RoutingEngineService {},
|
||||
}));
|
||||
|
||||
import { SessionsController } from '../sessions.controller.js';
|
||||
import { ChatController } from '../../chat/chat.controller.js';
|
||||
import { ChatGateway } from '../../chat/chat.gateway.js';
|
||||
import type { AgentSession } from '../agent.service.js';
|
||||
import type { SessionInfoDto } from '../session.dto.js';
|
||||
|
||||
const USER_A = { id: 'user-a', tenantId: 'tenant-a' };
|
||||
const USER_B = { id: 'user-b', tenantId: 'tenant-b' };
|
||||
const CONVERSATION_ID = '11111111-1111-4111-8111-111111111111';
|
||||
|
||||
function makeSessionInfo(overrides?: Partial<SessionInfoDto>): SessionInfoDto {
|
||||
return {
|
||||
id: CONVERSATION_ID,
|
||||
provider: 'test-provider',
|
||||
modelId: 'test-model',
|
||||
createdAt: new Date('2026-07-12T00:00:00Z').toISOString(),
|
||||
promptCount: 0,
|
||||
channels: [],
|
||||
durationMs: 0,
|
||||
metrics: {
|
||||
tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
|
||||
modelSwitches: 0,
|
||||
messageCount: 0,
|
||||
lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
|
||||
},
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function makeAgentSession(owner = USER_A): AgentSession {
|
||||
return {
|
||||
id: CONVERSATION_ID,
|
||||
provider: 'test-provider',
|
||||
modelId: 'test-model',
|
||||
piSession: {
|
||||
thinkingLevel: 'off',
|
||||
getAvailableThinkingLevels: vi.fn().mockReturnValue(['off', 'low', 'high']),
|
||||
setThinkingLevel: vi.fn(),
|
||||
abort: vi.fn().mockResolvedValue(undefined),
|
||||
prompt: vi.fn().mockResolvedValue(undefined),
|
||||
dispose: vi.fn(),
|
||||
getSessionStats: vi.fn(),
|
||||
getContextUsage: vi.fn(),
|
||||
} as unknown as AgentSession['piSession'],
|
||||
listeners: new Set(),
|
||||
unsubscribe: vi.fn(),
|
||||
createdAt: Date.now(),
|
||||
promptCount: 0,
|
||||
channels: new Set(),
|
||||
skillPromptAdditions: [],
|
||||
sandboxDir: '/tmp',
|
||||
allowedTools: null,
|
||||
userId: owner.id,
|
||||
tenantId: owner.tenantId,
|
||||
metrics: {
|
||||
tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
|
||||
modelSwitches: 0,
|
||||
messageCount: 0,
|
||||
lastActivityAt: new Date('2026-07-12T00:00:00Z').toISOString(),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function makeScopedAgentService() {
|
||||
const foreign = makeAgentSession(USER_A);
|
||||
return {
|
||||
listSessions: vi.fn((scope?: { userId: string; tenantId?: string }) =>
|
||||
scope?.userId === USER_B.id ? [] : [makeSessionInfo({ id: foreign.id })],
|
||||
),
|
||||
getSessionInfo: vi.fn((_id: string, scope?: { userId: string; tenantId?: string }) =>
|
||||
scope?.userId === USER_B.id ? undefined : makeSessionInfo({ id: foreign.id }),
|
||||
),
|
||||
destroySession: vi.fn(),
|
||||
getSession: vi.fn((_id: string, scope?: { userId: string; tenantId?: string }) =>
|
||||
scope?.userId === USER_B.id ? undefined : foreign,
|
||||
),
|
||||
createSession: vi.fn().mockRejectedValue(new ForbiddenException('Session scope mismatch')),
|
||||
onEvent: vi.fn(() => vi.fn()),
|
||||
addChannel: vi.fn(),
|
||||
removeChannel: vi.fn(),
|
||||
recordMessage: vi.fn(),
|
||||
prompt: vi.fn().mockResolvedValue(undefined),
|
||||
};
|
||||
}
|
||||
|
||||
describe('TESS-M1-SEC-002 AgentService ownership boundary', () => {
|
||||
it('requires explicit owner+tenant scope on protected session operations', () => {
|
||||
const source = readFileSync(resolve('src/agent/agent.service.ts'), 'utf8');
|
||||
|
||||
expect(source).toContain('getSession(sessionId: string, scope: ActorTenantScope)');
|
||||
expect(source).toContain('listSessions(scope: ActorTenantScope)');
|
||||
expect(source).toContain('getSessionInfo(sessionId: string, scope: ActorTenantScope)');
|
||||
expect(source).toContain(
|
||||
'addChannel(sessionId: string, channel: string, scope: ActorTenantScope)',
|
||||
);
|
||||
expect(source).toContain(
|
||||
'removeChannel(sessionId: string, channel: string, scope: ActorTenantScope)',
|
||||
);
|
||||
expect(source).toContain(
|
||||
'async prompt(sessionId: string, message: string, scope: ActorTenantScope)',
|
||||
);
|
||||
expect(source).toContain('scope: ActorTenantScope,');
|
||||
expect(source).toContain('async destroySession(sessionId: string, scope: ActorTenantScope)');
|
||||
expect(source).not.toContain('scope?: ActorTenantScope');
|
||||
});
|
||||
});
|
||||
|
||||
describe('TESS-M1-SEC-002 REST session ownership and tenant binding', () => {
|
||||
it('lists only sessions owned by the authenticated owner+tenant scope', () => {
|
||||
const agentService = makeScopedAgentService();
|
||||
const controller = new SessionsController(agentService as never);
|
||||
|
||||
expect(controller.list(USER_B)).toEqual({ sessions: [], total: 0 });
|
||||
expect(agentService.listSessions).toHaveBeenCalledWith({
|
||||
userId: USER_B.id,
|
||||
tenantId: USER_B.tenantId,
|
||||
});
|
||||
});
|
||||
|
||||
it('does not reveal another owner/tenant session by guessed id', () => {
|
||||
const agentService = makeScopedAgentService();
|
||||
const controller = new SessionsController(agentService as never);
|
||||
|
||||
expect(() => controller.findOne(CONVERSATION_ID, USER_B)).toThrow(NotFoundException);
|
||||
expect(agentService.getSessionInfo).toHaveBeenCalledWith(CONVERSATION_ID, {
|
||||
userId: USER_B.id,
|
||||
tenantId: USER_B.tenantId,
|
||||
});
|
||||
});
|
||||
|
||||
it('does not terminate another owner/tenant session by guessed id', async () => {
|
||||
const agentService = makeScopedAgentService();
|
||||
const controller = new SessionsController(agentService as never);
|
||||
|
||||
await expect(controller.destroy(CONVERSATION_ID, USER_B)).rejects.toBeInstanceOf(
|
||||
NotFoundException,
|
||||
);
|
||||
expect(agentService.destroySession).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('TESS-M1-SEC-002 REST chat send ownership and tenant binding', () => {
|
||||
it('does not send a prompt into another owner/tenant session by guessed conversationId', async () => {
|
||||
const agentService = makeScopedAgentService();
|
||||
const controller = new ChatController(agentService as never);
|
||||
|
||||
await expect(
|
||||
controller.chat({ conversationId: CONVERSATION_ID, content: 'take over' }, USER_B),
|
||||
).rejects.toMatchObject({ status: 404 });
|
||||
|
||||
expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
|
||||
userId: USER_B.id,
|
||||
tenantId: USER_B.tenantId,
|
||||
});
|
||||
expect(agentService.prompt).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe('TESS-M1-SEC-002 WebSocket session ownership and tenant binding', () => {
|
||||
function makeGateway(agentService = makeScopedAgentService()) {
|
||||
const brain = {
|
||||
conversations: {
|
||||
findById: vi.fn().mockResolvedValue(undefined),
|
||||
create: vi.fn().mockResolvedValue(undefined),
|
||||
update: vi.fn().mockResolvedValue(undefined),
|
||||
findMessages: vi.fn().mockResolvedValue([]),
|
||||
addMessage: vi.fn().mockResolvedValue(undefined),
|
||||
},
|
||||
};
|
||||
const commandRegistry = { getManifest: vi.fn().mockReturnValue([]) };
|
||||
const commandExecutor = { execute: vi.fn() };
|
||||
const routingEngine = {
|
||||
resolve: vi.fn().mockResolvedValue({ provider: 'test', model: 'test-model' }),
|
||||
};
|
||||
const gateway = new ChatGateway(
|
||||
agentService as never,
|
||||
{} as never,
|
||||
brain as never,
|
||||
commandRegistry as never,
|
||||
commandExecutor as never,
|
||||
routingEngine as never,
|
||||
);
|
||||
return { gateway, agentService };
|
||||
}
|
||||
|
||||
function makeSocket() {
|
||||
return {
|
||||
id: 'socket-b',
|
||||
connected: true,
|
||||
data: { user: USER_B, session: { id: 'auth-session-b', userId: USER_B.id } },
|
||||
emit: vi.fn(),
|
||||
disconnect: vi.fn(),
|
||||
};
|
||||
}
|
||||
|
||||
it('does not attach or send to another owner/tenant session by guessed conversationId', async () => {
|
||||
const { gateway, agentService } = makeGateway();
|
||||
const socket = makeSocket();
|
||||
|
||||
await gateway.handleMessage(socket as never, {
|
||||
conversationId: CONVERSATION_ID,
|
||||
content: 'attach to foreign session',
|
||||
});
|
||||
|
||||
expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
|
||||
userId: USER_B.id,
|
||||
tenantId: USER_B.tenantId,
|
||||
});
|
||||
expect(agentService.onEvent).not.toHaveBeenCalled();
|
||||
expect(agentService.addChannel).not.toHaveBeenCalled();
|
||||
expect(agentService.prompt).not.toHaveBeenCalled();
|
||||
expect(socket.emit).toHaveBeenCalledWith(
|
||||
'error',
|
||||
expect.objectContaining({ conversationId: CONVERSATION_ID }),
|
||||
);
|
||||
});
|
||||
|
||||
it('does not mutate thinking level on another owner/tenant session', () => {
|
||||
const { gateway, agentService } = makeGateway();
|
||||
const socket = makeSocket();
|
||||
|
||||
gateway.handleSetThinking(socket as never, { conversationId: CONVERSATION_ID, level: 'high' });
|
||||
|
||||
expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
|
||||
userId: USER_B.id,
|
||||
tenantId: USER_B.tenantId,
|
||||
});
|
||||
expect(socket.emit).toHaveBeenCalledWith(
|
||||
'error',
|
||||
expect.objectContaining({ conversationId: CONVERSATION_ID }),
|
||||
);
|
||||
});
|
||||
|
||||
it('does not terminate another owner/tenant session over WebSocket abort', async () => {
|
||||
const { gateway, agentService } = makeGateway();
|
||||
const socket = makeSocket();
|
||||
|
||||
await gateway.handleAbort(socket as never, { conversationId: CONVERSATION_ID });
|
||||
|
||||
expect(agentService.getSession).toHaveBeenCalledWith(CONVERSATION_ID, {
|
||||
userId: USER_B.id,
|
||||
tenantId: USER_B.tenantId,
|
||||
});
|
||||
expect(socket.emit).toHaveBeenCalledWith(
|
||||
'error',
|
||||
expect.objectContaining({ conversationId: CONVERSATION_ID }),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -1,5 +1,4 @@
|
||||
import { Global, Module } from '@nestjs/common';
|
||||
import { AgentRuntimeProviderRegistry } from '@mosaicstack/agent';
|
||||
import { AgentService } from './agent.service.js';
|
||||
import { ProviderService } from './provider.service.js';
|
||||
import { ProviderCredentialsService } from './provider-credentials.service.js';
|
||||
@@ -14,14 +13,6 @@ import { CoordModule } from '../coord/coord.module.js';
|
||||
import { McpClientModule } from '../mcp-client/mcp-client.module.js';
|
||||
import { SkillsModule } from '../skills/skills.module.js';
|
||||
import { GCModule } from '../gc/gc.module.js';
|
||||
import {
|
||||
AGENT_RUNTIME_PROVIDER_REGISTRY,
|
||||
DenyRuntimeApprovalVerifier,
|
||||
RUNTIME_APPROVAL_VERIFIER,
|
||||
RUNTIME_PROVIDER_AUDIT_SINK,
|
||||
RuntimeProviderAuditService,
|
||||
RuntimeProviderService,
|
||||
} from './runtime-provider-registry.service.js';
|
||||
|
||||
@Global()
|
||||
@Module({
|
||||
@@ -32,21 +23,6 @@ import {
|
||||
RoutingService,
|
||||
RoutingEngineService,
|
||||
SkillLoaderService,
|
||||
{
|
||||
provide: AGENT_RUNTIME_PROVIDER_REGISTRY,
|
||||
useFactory: (): AgentRuntimeProviderRegistry => new AgentRuntimeProviderRegistry(),
|
||||
},
|
||||
RuntimeProviderAuditService,
|
||||
{
|
||||
provide: RUNTIME_PROVIDER_AUDIT_SINK,
|
||||
useExisting: RuntimeProviderAuditService,
|
||||
},
|
||||
DenyRuntimeApprovalVerifier,
|
||||
{
|
||||
provide: RUNTIME_APPROVAL_VERIFIER,
|
||||
useExisting: DenyRuntimeApprovalVerifier,
|
||||
},
|
||||
RuntimeProviderService,
|
||||
AgentService,
|
||||
],
|
||||
controllers: [ProvidersController, SessionsController, AgentConfigsController, RoutingController],
|
||||
@@ -57,8 +33,6 @@ import {
|
||||
RoutingService,
|
||||
RoutingEngineService,
|
||||
SkillLoaderService,
|
||||
RuntimeProviderService,
|
||||
AGENT_RUNTIME_PROVIDER_REGISTRY,
|
||||
],
|
||||
})
|
||||
export class AgentModule {}
|
||||
|
||||
@@ -1,11 +1,4 @@
|
||||
import {
|
||||
ForbiddenException,
|
||||
Inject,
|
||||
Injectable,
|
||||
Logger,
|
||||
Optional,
|
||||
type OnModuleDestroy,
|
||||
} from '@nestjs/common';
|
||||
import { Inject, Injectable, Logger, Optional, type OnModuleDestroy } from '@nestjs/common';
|
||||
import {
|
||||
createAgentSession,
|
||||
DefaultResourceLoader,
|
||||
@@ -35,7 +28,6 @@ import type { SessionInfoDto, SessionMetrics } from './session.dto.js';
|
||||
import { SystemOverrideService } from '../preferences/system-override.service.js';
|
||||
import { PreferencesService } from '../preferences/preferences.service.js';
|
||||
import { SessionGCService } from '../gc/session-gc.service.js';
|
||||
import type { ActorTenantScope } from '../auth/session-scope.js';
|
||||
|
||||
/** A single message from DB conversation history, used for context injection. */
|
||||
export interface ConversationHistoryMessage {
|
||||
@@ -76,8 +68,6 @@ export interface AgentSessionOptions {
|
||||
agentConfigId?: string;
|
||||
/** ID of the user who owns this session. Used for preferences and system override lookups. */
|
||||
userId?: string;
|
||||
/** Server-derived tenant scope that owns this session. Falls back to userId for solo users. */
|
||||
tenantId?: string;
|
||||
/**
|
||||
* Prior conversation messages to inject as context when resuming a session.
|
||||
* These messages are formatted and prepended to the system prompt so the
|
||||
@@ -104,8 +94,6 @@ export interface AgentSession {
|
||||
allowedTools: string[] | null;
|
||||
/** User ID that owns this session, used for preference lookups. */
|
||||
userId?: string;
|
||||
/** Server-derived tenant scope that owns this session. Falls back to userId for solo users. */
|
||||
tenantId?: string;
|
||||
/** Agent config ID applied to this session, if any (M5-001). */
|
||||
agentConfigId?: string;
|
||||
/** Human-readable agent name applied to this session, if any (M5-001). */
|
||||
@@ -186,20 +174,12 @@ export class AgentService implements OnModuleDestroy {
|
||||
.filter((t) => t.length > 0);
|
||||
}
|
||||
|
||||
async createSession(sessionId: string, options: AgentSessionOptions): Promise<AgentSession> {
|
||||
const scope = this.scopeFromOptions(options);
|
||||
async createSession(sessionId: string, options?: AgentSessionOptions): Promise<AgentSession> {
|
||||
const existing = this.sessions.get(sessionId);
|
||||
if (existing) {
|
||||
this.assertSessionScope(existing, scope);
|
||||
return existing;
|
||||
}
|
||||
if (existing) return existing;
|
||||
|
||||
const inflight = this.creating.get(sessionId);
|
||||
if (inflight) {
|
||||
const session = await inflight;
|
||||
this.assertSessionScope(session, scope);
|
||||
return session;
|
||||
}
|
||||
if (inflight) return inflight;
|
||||
|
||||
const promise = this.doCreateSession(sessionId, options).finally(() => {
|
||||
this.creating.delete(sessionId);
|
||||
@@ -362,7 +342,6 @@ export class AgentService implements OnModuleDestroy {
|
||||
sandboxDir,
|
||||
allowedTools,
|
||||
userId: mergedOptions?.userId,
|
||||
tenantId: this.tenantIdFor(mergedOptions?.userId, mergedOptions?.tenantId),
|
||||
agentConfigId: mergedOptions?.agentConfigId,
|
||||
agentName: resolvedAgentName,
|
||||
metrics: {
|
||||
@@ -494,70 +473,38 @@ export class AgentService implements OnModuleDestroy {
|
||||
return this.providerService.getDefaultModel() ?? null;
|
||||
}
|
||||
|
||||
getSession(sessionId: string, scope: ActorTenantScope): AgentSession | undefined {
|
||||
const session = this.sessions.get(sessionId);
|
||||
if (!session || !this.sessionMatchesScope(session, scope)) return undefined;
|
||||
return session;
|
||||
getSession(sessionId: string): AgentSession | undefined {
|
||||
return this.sessions.get(sessionId);
|
||||
}
|
||||
|
||||
listSessions(scope: ActorTenantScope): SessionInfoDto[] {
|
||||
listSessions(): SessionInfoDto[] {
|
||||
const now = Date.now();
|
||||
return Array.from(this.sessions.values())
|
||||
.filter((s) => this.sessionMatchesScope(s, scope))
|
||||
.map((s) => this.toSessionInfo(s, now));
|
||||
return Array.from(this.sessions.values()).map((s) => ({
|
||||
id: s.id,
|
||||
provider: s.provider,
|
||||
modelId: s.modelId,
|
||||
...(s.agentName ? { agentName: s.agentName } : {}),
|
||||
createdAt: new Date(s.createdAt).toISOString(),
|
||||
promptCount: s.promptCount,
|
||||
channels: Array.from(s.channels),
|
||||
durationMs: now - s.createdAt,
|
||||
metrics: { ...s.metrics },
|
||||
}));
|
||||
}
|
||||
|
||||
listAllSessionsForSystem(): SessionInfoDto[] {
|
||||
const now = Date.now();
|
||||
return Array.from(this.sessions.values()).map((s) => this.toSessionInfo(s, now));
|
||||
}
|
||||
|
||||
getSessionInfo(sessionId: string, scope: ActorTenantScope): SessionInfoDto | undefined {
|
||||
getSessionInfo(sessionId: string): SessionInfoDto | undefined {
|
||||
const s = this.sessions.get(sessionId);
|
||||
if (!s || !this.sessionMatchesScope(s, scope)) return undefined;
|
||||
return this.toSessionInfo(s);
|
||||
}
|
||||
|
||||
private scopeFromOptions(options: AgentSessionOptions): ActorTenantScope {
|
||||
if (!options.userId) {
|
||||
throw new ForbiddenException('Session owner scope is required');
|
||||
}
|
||||
if (!s) return undefined;
|
||||
return {
|
||||
userId: options.userId,
|
||||
tenantId: this.tenantIdFor(options.userId, options.tenantId) ?? options.userId,
|
||||
};
|
||||
}
|
||||
|
||||
private tenantIdFor(
|
||||
userId: string | undefined,
|
||||
tenantId: string | undefined,
|
||||
): string | undefined {
|
||||
return tenantId ?? userId;
|
||||
}
|
||||
|
||||
private sessionMatchesScope(session: AgentSession, scope: ActorTenantScope): boolean {
|
||||
return (
|
||||
session.userId === scope.userId && (session.tenantId ?? session.userId) === scope.tenantId
|
||||
);
|
||||
}
|
||||
|
||||
private assertSessionScope(session: AgentSession, scope: ActorTenantScope): void {
|
||||
if (!this.sessionMatchesScope(session, scope)) {
|
||||
throw new ForbiddenException('Session does not belong to the current owner/tenant scope');
|
||||
}
|
||||
}
|
||||
|
||||
private toSessionInfo(session: AgentSession, now = Date.now()): SessionInfoDto {
|
||||
return {
|
||||
id: session.id,
|
||||
provider: session.provider,
|
||||
modelId: session.modelId,
|
||||
...(session.agentName ? { agentName: session.agentName } : {}),
|
||||
createdAt: new Date(session.createdAt).toISOString(),
|
||||
promptCount: session.promptCount,
|
||||
channels: Array.from(session.channels),
|
||||
durationMs: now - session.createdAt,
|
||||
metrics: { ...session.metrics },
|
||||
id: s.id,
|
||||
provider: s.provider,
|
||||
modelId: s.modelId,
|
||||
...(s.agentName ? { agentName: s.agentName } : {}),
|
||||
createdAt: new Date(s.createdAt).toISOString(),
|
||||
promptCount: s.promptCount,
|
||||
channels: Array.from(s.channels),
|
||||
durationMs: Date.now() - s.createdAt,
|
||||
metrics: { ...s.metrics },
|
||||
};
|
||||
}
|
||||
|
||||
@@ -606,10 +553,9 @@ export class AgentService implements OnModuleDestroy {
|
||||
* not reconstructed — the model is used on the next createSession call for
|
||||
* the same conversationId when the session is torn down or a new one is created.
|
||||
*/
|
||||
updateSessionModel(sessionId: string, modelId: string, scope: ActorTenantScope): void {
|
||||
updateSessionModel(sessionId: string, modelId: string): void {
|
||||
const session = this.sessions.get(sessionId);
|
||||
if (!session) return;
|
||||
this.assertSessionScope(session, scope);
|
||||
const prev = session.modelId;
|
||||
session.modelId = modelId;
|
||||
this.recordModelSwitch(sessionId);
|
||||
@@ -626,51 +572,48 @@ export class AgentService implements OnModuleDestroy {
|
||||
sessionId: string,
|
||||
agentConfigId: string,
|
||||
agentName: string,
|
||||
scope: ActorTenantScope,
|
||||
modelId?: string,
|
||||
): void {
|
||||
const session = this.sessions.get(sessionId);
|
||||
if (!session) return;
|
||||
this.assertSessionScope(session, scope);
|
||||
session.agentConfigId = agentConfigId;
|
||||
session.agentName = agentName;
|
||||
if (modelId) {
|
||||
this.updateSessionModel(sessionId, modelId, scope);
|
||||
this.updateSessionModel(sessionId, modelId);
|
||||
}
|
||||
this.logger.log(
|
||||
`Session ${sessionId}: agent switched to "${agentName}" (${agentConfigId}) (M5-003)`,
|
||||
);
|
||||
}
|
||||
|
||||
addChannel(sessionId: string, channel: string, scope: ActorTenantScope): void {
|
||||
addChannel(sessionId: string, channel: string): void {
|
||||
const session = this.sessions.get(sessionId);
|
||||
if (!session) return;
|
||||
this.assertSessionScope(session, scope);
|
||||
session.channels.add(channel);
|
||||
if (session) {
|
||||
session.channels.add(channel);
|
||||
}
|
||||
}
|
||||
|
||||
removeChannel(sessionId: string, channel: string, scope: ActorTenantScope): void {
|
||||
removeChannel(sessionId: string, channel: string): void {
|
||||
const session = this.sessions.get(sessionId);
|
||||
if (!session) return;
|
||||
this.assertSessionScope(session, scope);
|
||||
session.channels.delete(channel);
|
||||
if (session) {
|
||||
session.channels.delete(channel);
|
||||
}
|
||||
}
|
||||
|
||||
async prompt(sessionId: string, message: string, scope: ActorTenantScope): Promise<void> {
|
||||
async prompt(sessionId: string, message: string): Promise<void> {
|
||||
const session = this.sessions.get(sessionId);
|
||||
if (!session) {
|
||||
throw new Error(`No agent session found: ${sessionId}`);
|
||||
}
|
||||
this.assertSessionScope(session, scope);
|
||||
session.promptCount += 1;
|
||||
|
||||
// Prepend session-scoped system override if present (renew TTL on each turn)
|
||||
let effectiveMessage = message;
|
||||
if (this.systemOverride) {
|
||||
const override = await this.systemOverride.get(sessionId, scope);
|
||||
const override = await this.systemOverride.get(sessionId);
|
||||
if (override) {
|
||||
effectiveMessage = `[System Override]\n${override}\n\n${message}`;
|
||||
await this.systemOverride.renew(sessionId, scope);
|
||||
await this.systemOverride.renew(sessionId);
|
||||
this.logger.debug(`Applied system override for session ${sessionId}`);
|
||||
}
|
||||
}
|
||||
@@ -686,28 +629,16 @@ export class AgentService implements OnModuleDestroy {
|
||||
}
|
||||
}
|
||||
|
||||
onEvent(
|
||||
sessionId: string,
|
||||
listener: (event: AgentSessionEvent) => void,
|
||||
scope: ActorTenantScope,
|
||||
): () => void {
|
||||
onEvent(sessionId: string, listener: (event: AgentSessionEvent) => void): () => void {
|
||||
const session = this.sessions.get(sessionId);
|
||||
if (!session) {
|
||||
throw new Error(`No agent session found: ${sessionId}`);
|
||||
}
|
||||
this.assertSessionScope(session, scope);
|
||||
session.listeners.add(listener);
|
||||
return () => session.listeners.delete(listener);
|
||||
}
|
||||
|
||||
async destroySession(sessionId: string, scope: ActorTenantScope): Promise<void> {
|
||||
const session = this.sessions.get(sessionId);
|
||||
if (!session) return;
|
||||
this.assertSessionScope(session, scope);
|
||||
await this.destroySessionForSystem(sessionId);
|
||||
}
|
||||
|
||||
private async destroySessionForSystem(sessionId: string): Promise<void> {
|
||||
async destroySession(sessionId: string): Promise<void> {
|
||||
const session = this.sessions.get(sessionId);
|
||||
if (!session) return;
|
||||
this.logger.log(`Destroying agent session ${sessionId}`);
|
||||
@@ -736,7 +667,7 @@ export class AgentService implements OnModuleDestroy {
|
||||
|
||||
async onModuleDestroy(): Promise<void> {
|
||||
this.logger.log('Shutting down all agent sessions');
|
||||
const stops = Array.from(this.sessions.keys()).map((id) => this.destroySessionForSystem(id));
|
||||
const stops = Array.from(this.sessions.keys()).map((id) => this.destroySession(id));
|
||||
const results = await Promise.allSettled(stops);
|
||||
for (const result of results) {
|
||||
if (result.status === 'rejected') {
|
||||
|
||||
@@ -1,404 +0,0 @@
|
||||
import { ForbiddenException, Inject, Injectable, Logger, NotFoundException } from '@nestjs/common';
|
||||
import { AgentRuntimeProviderRegistry } from '@mosaicstack/agent';
|
||||
import type {
|
||||
AgentRuntimeProvider,
|
||||
RuntimeAttachHandle,
|
||||
RuntimeAttachMode,
|
||||
RuntimeCapability,
|
||||
RuntimeCapabilitySet,
|
||||
RuntimeHealth,
|
||||
RuntimeMessage,
|
||||
RuntimeScope,
|
||||
RuntimeSession,
|
||||
RuntimeSessionTree,
|
||||
RuntimeStreamEvent,
|
||||
} from '@mosaicstack/types';
|
||||
import type { ActorTenantScope } from '../auth/session-scope.js';
|
||||
|
||||
export const AGENT_RUNTIME_PROVIDER_REGISTRY = Symbol('AGENT_RUNTIME_PROVIDER_REGISTRY');
|
||||
export const RUNTIME_PROVIDER_AUDIT_SINK = Symbol('RUNTIME_PROVIDER_AUDIT_SINK');
|
||||
export const RUNTIME_APPROVAL_VERIFIER = Symbol('RUNTIME_APPROVAL_VERIFIER');
|
||||
|
||||
export type RuntimeProviderOperation =
|
||||
| RuntimeCapability
|
||||
| 'runtime.capabilities'
|
||||
| 'runtime.health';
|
||||
export type RuntimeProviderAuditOutcome = 'requested' | 'succeeded' | 'denied' | 'failed';
|
||||
|
||||
/** Trusted server-side context only; it intentionally excludes client-provided identity fields. */
|
||||
export interface RuntimeProviderRequestContext {
|
||||
actorScope: ActorTenantScope;
|
||||
channelId: string;
|
||||
correlationId: string;
|
||||
}
|
||||
|
||||
/** Metadata-only audit record. Message bodies, idempotency keys, and approval refs are excluded. */
|
||||
export interface RuntimeAuditEvent {
|
||||
providerId: string;
|
||||
operation: RuntimeProviderOperation;
|
||||
outcome: RuntimeProviderAuditOutcome;
|
||||
actorId: string;
|
||||
tenantId: string;
|
||||
channelId: string;
|
||||
correlationId: string;
|
||||
resourceId?: string;
|
||||
}
|
||||
|
||||
export interface RuntimeAuditSink {
|
||||
record(event: RuntimeAuditEvent): Promise<void>;
|
||||
}
|
||||
|
||||
/** Exact action shape that a durable approval implementation must consume once. */
|
||||
export interface RuntimeTerminationAction {
|
||||
providerId: string;
|
||||
sessionId: string;
|
||||
actorId: string;
|
||||
tenantId: string;
|
||||
channelId: string;
|
||||
correlationId: string;
|
||||
}
|
||||
|
||||
export interface RuntimeApprovalVerifier {
|
||||
consume(approvalRef: string, action: RuntimeTerminationAction): Promise<boolean>;
|
||||
}
|
||||
|
||||
class RuntimeApprovalDeniedError extends Error {
|
||||
constructor() {
|
||||
super('Runtime termination approval denied');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The default denies all runtime termination until a durable, exact-action
|
||||
* approval implementation is configured. This is safer than a permissive stub.
|
||||
*/
|
||||
@Injectable()
|
||||
export class DenyRuntimeApprovalVerifier implements RuntimeApprovalVerifier {
|
||||
async consume(_approvalRef: string, _action: RuntimeTerminationAction): Promise<boolean> {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Temporary metadata-only audit sink. M1 observability can replace this token
|
||||
* with a durable audit writer without changing provider call sites.
|
||||
*/
|
||||
@Injectable()
|
||||
export class RuntimeProviderAuditService implements RuntimeAuditSink {
|
||||
private readonly logger = new Logger(RuntimeProviderAuditService.name);
|
||||
|
||||
async record(event: RuntimeAuditEvent): Promise<void> {
|
||||
this.logger.log(JSON.stringify(event));
|
||||
}
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class RuntimeProviderService {
|
||||
private readonly logger = new Logger(RuntimeProviderService.name);
|
||||
|
||||
constructor(
|
||||
@Inject(AGENT_RUNTIME_PROVIDER_REGISTRY)
|
||||
private readonly registry: AgentRuntimeProviderRegistry,
|
||||
@Inject(RUNTIME_PROVIDER_AUDIT_SINK)
|
||||
private readonly audit: RuntimeAuditSink,
|
||||
@Inject(RUNTIME_APPROVAL_VERIFIER)
|
||||
private readonly approvals: RuntimeApprovalVerifier,
|
||||
) {}
|
||||
|
||||
async capabilities(
|
||||
providerId: string,
|
||||
context: RuntimeProviderRequestContext,
|
||||
): Promise<RuntimeCapabilitySet> {
|
||||
return this.execute(
|
||||
providerId,
|
||||
'runtime.capabilities',
|
||||
undefined,
|
||||
undefined,
|
||||
context,
|
||||
(provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<RuntimeCapabilitySet> =>
|
||||
provider.capabilities(scope),
|
||||
);
|
||||
}
|
||||
|
||||
async health(providerId: string, context: RuntimeProviderRequestContext): Promise<RuntimeHealth> {
|
||||
return this.execute(
|
||||
providerId,
|
||||
'runtime.health',
|
||||
undefined,
|
||||
undefined,
|
||||
context,
|
||||
(provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<RuntimeHealth> =>
|
||||
provider.health(scope),
|
||||
);
|
||||
}
|
||||
|
||||
async listSessions(
|
||||
providerId: string,
|
||||
context: RuntimeProviderRequestContext,
|
||||
): Promise<RuntimeSession[]> {
|
||||
return this.execute(
|
||||
providerId,
|
||||
'session.list',
|
||||
'session.list',
|
||||
undefined,
|
||||
context,
|
||||
(provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<RuntimeSession[]> =>
|
||||
provider.listSessions(scope),
|
||||
);
|
||||
}
|
||||
|
||||
async getSessionTree(
|
||||
providerId: string,
|
||||
context: RuntimeProviderRequestContext,
|
||||
): Promise<RuntimeSessionTree[]> {
|
||||
return this.execute(
|
||||
providerId,
|
||||
'session.tree',
|
||||
'session.tree',
|
||||
undefined,
|
||||
context,
|
||||
(provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<RuntimeSessionTree[]> =>
|
||||
provider.getSessionTree(scope),
|
||||
);
|
||||
}
|
||||
|
||||
streamSession(
|
||||
providerId: string,
|
||||
sessionId: string,
|
||||
cursor: string | undefined,
|
||||
context: RuntimeProviderRequestContext,
|
||||
): AsyncIterable<RuntimeStreamEvent> {
|
||||
return this.stream(
|
||||
providerId,
|
||||
'session.stream',
|
||||
'session.stream',
|
||||
sessionId,
|
||||
context,
|
||||
(provider: AgentRuntimeProvider, scope: RuntimeScope): AsyncIterable<RuntimeStreamEvent> =>
|
||||
provider.streamSession(sessionId, cursor, scope),
|
||||
);
|
||||
}
|
||||
|
||||
async sendMessage(
|
||||
providerId: string,
|
||||
sessionId: string,
|
||||
message: RuntimeMessage,
|
||||
context: RuntimeProviderRequestContext,
|
||||
): Promise<void> {
|
||||
await this.execute(
|
||||
providerId,
|
||||
'session.send',
|
||||
'session.send',
|
||||
sessionId,
|
||||
context,
|
||||
(provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<void> =>
|
||||
provider.sendMessage(sessionId, message, scope),
|
||||
);
|
||||
}
|
||||
|
||||
async attach(
|
||||
providerId: string,
|
||||
sessionId: string,
|
||||
mode: RuntimeAttachMode,
|
||||
context: RuntimeProviderRequestContext,
|
||||
): Promise<RuntimeAttachHandle> {
|
||||
return this.execute(
|
||||
providerId,
|
||||
'session.attach',
|
||||
'session.attach',
|
||||
sessionId,
|
||||
context,
|
||||
(provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<RuntimeAttachHandle> =>
|
||||
provider.attach(sessionId, mode, scope),
|
||||
);
|
||||
}
|
||||
|
||||
async detach(
|
||||
providerId: string,
|
||||
attachmentId: string,
|
||||
context: RuntimeProviderRequestContext,
|
||||
): Promise<void> {
|
||||
await this.execute(
|
||||
providerId,
|
||||
'session.attach',
|
||||
'session.attach',
|
||||
attachmentId,
|
||||
context,
|
||||
(provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<void> =>
|
||||
provider.detach(attachmentId, scope),
|
||||
);
|
||||
}
|
||||
|
||||
async terminate(
|
||||
providerId: string,
|
||||
sessionId: string,
|
||||
approvalRef: string,
|
||||
context: RuntimeProviderRequestContext,
|
||||
): Promise<void> {
|
||||
await this.execute(
|
||||
providerId,
|
||||
'session.terminate',
|
||||
'session.terminate',
|
||||
sessionId,
|
||||
context,
|
||||
async (provider: AgentRuntimeProvider, scope: RuntimeScope): Promise<void> => {
|
||||
const approved = await this.approvals.consume(approvalRef, {
|
||||
providerId,
|
||||
sessionId,
|
||||
actorId: scope.actorId,
|
||||
tenantId: scope.tenantId,
|
||||
channelId: scope.channelId,
|
||||
correlationId: scope.correlationId,
|
||||
});
|
||||
if (!approved) {
|
||||
throw new RuntimeApprovalDeniedError();
|
||||
}
|
||||
await provider.terminate(sessionId, approvalRef, scope);
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
private async execute<T>(
|
||||
providerId: string,
|
||||
operation: RuntimeProviderOperation,
|
||||
requiredCapability: RuntimeCapability | undefined,
|
||||
resourceId: string | undefined,
|
||||
context: RuntimeProviderRequestContext,
|
||||
invoke: (provider: AgentRuntimeProvider, scope: RuntimeScope) => Promise<T>,
|
||||
): Promise<T> {
|
||||
const scope = this.deriveScope(context);
|
||||
await this.record(providerId, operation, 'requested', scope, resourceId);
|
||||
let invocationStarted = false;
|
||||
try {
|
||||
const provider = this.provider(providerId);
|
||||
if (requiredCapability) {
|
||||
await this.assertCapability(provider, requiredCapability, scope);
|
||||
}
|
||||
invocationStarted = true;
|
||||
const result = await invoke(provider, scope);
|
||||
await this.recordCompletion(providerId, operation, scope, resourceId);
|
||||
return result;
|
||||
} catch (error: unknown) {
|
||||
if (invocationStarted && !(error instanceof RuntimeApprovalDeniedError)) {
|
||||
await this.recordFailure(providerId, operation, scope, resourceId);
|
||||
} else {
|
||||
await this.record(providerId, operation, 'denied', scope, resourceId);
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
private async *stream(
|
||||
providerId: string,
|
||||
operation: RuntimeProviderOperation,
|
||||
requiredCapability: RuntimeCapability,
|
||||
resourceId: string,
|
||||
context: RuntimeProviderRequestContext,
|
||||
invoke: (
|
||||
provider: AgentRuntimeProvider,
|
||||
scope: RuntimeScope,
|
||||
) => AsyncIterable<RuntimeStreamEvent>,
|
||||
): AsyncIterable<RuntimeStreamEvent> {
|
||||
const scope = this.deriveScope(context);
|
||||
await this.record(providerId, operation, 'requested', scope, resourceId);
|
||||
let invocationStarted = false;
|
||||
try {
|
||||
const provider = this.provider(providerId);
|
||||
await this.assertCapability(provider, requiredCapability, scope);
|
||||
invocationStarted = true;
|
||||
for await (const event of invoke(provider, scope)) {
|
||||
yield event;
|
||||
}
|
||||
await this.recordCompletion(providerId, operation, scope, resourceId);
|
||||
} catch (error: unknown) {
|
||||
if (invocationStarted) {
|
||||
await this.recordFailure(providerId, operation, scope, resourceId);
|
||||
} else {
|
||||
await this.record(providerId, operation, 'denied', scope, resourceId);
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
private provider(providerId: string): AgentRuntimeProvider {
|
||||
try {
|
||||
return this.registry.require(providerId);
|
||||
} catch (error: unknown) {
|
||||
const message = error instanceof Error ? error.message : 'Runtime provider is not registered';
|
||||
throw new NotFoundException(message);
|
||||
}
|
||||
}
|
||||
|
||||
private async assertCapability(
|
||||
provider: AgentRuntimeProvider,
|
||||
requiredCapability: RuntimeCapability,
|
||||
scope: RuntimeScope,
|
||||
): Promise<void> {
|
||||
const capabilities = await provider.capabilities(scope);
|
||||
if (!capabilities.supported.includes(requiredCapability)) {
|
||||
throw new ForbiddenException(`Runtime provider capability denied: ${requiredCapability}`);
|
||||
}
|
||||
}
|
||||
|
||||
private deriveScope(context: RuntimeProviderRequestContext): RuntimeScope {
|
||||
const actorId = context.actorScope.userId.trim();
|
||||
const tenantId = context.actorScope.tenantId.trim();
|
||||
const channelId = context.channelId.trim();
|
||||
const correlationId = context.correlationId.trim();
|
||||
if (!actorId || !tenantId || !channelId || !correlationId) {
|
||||
throw new ForbiddenException(
|
||||
'Authenticated runtime actor scope and correlation are required',
|
||||
);
|
||||
}
|
||||
return Object.freeze({ actorId, tenantId, channelId, correlationId });
|
||||
}
|
||||
|
||||
private async recordFailure(
|
||||
providerId: string,
|
||||
operation: RuntimeProviderOperation,
|
||||
scope: RuntimeScope,
|
||||
resourceId: string | undefined,
|
||||
): Promise<void> {
|
||||
try {
|
||||
await this.record(providerId, operation, 'failed', scope, resourceId);
|
||||
} catch {
|
||||
this.logger.error(
|
||||
`Runtime provider failure audit failed provider=${providerId} operation=${operation} correlation=${scope.correlationId}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
private async recordCompletion(
|
||||
providerId: string,
|
||||
operation: RuntimeProviderOperation,
|
||||
scope: RuntimeScope,
|
||||
resourceId: string | undefined,
|
||||
): Promise<void> {
|
||||
try {
|
||||
await this.record(providerId, operation, 'succeeded', scope, resourceId);
|
||||
} catch {
|
||||
this.logger.error(
|
||||
`Runtime provider completion audit failed provider=${providerId} operation=${operation} correlation=${scope.correlationId}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
private async record(
|
||||
providerId: string,
|
||||
operation: RuntimeProviderOperation,
|
||||
outcome: RuntimeProviderAuditOutcome,
|
||||
scope: RuntimeScope,
|
||||
resourceId: string | undefined,
|
||||
): Promise<void> {
|
||||
await this.audit.record({
|
||||
providerId,
|
||||
operation,
|
||||
outcome,
|
||||
actorId: scope.actorId,
|
||||
tenantId: scope.tenantId,
|
||||
channelId: scope.channelId,
|
||||
correlationId: scope.correlationId,
|
||||
...(resourceId ? { resourceId } : {}),
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -10,8 +10,6 @@ import {
|
||||
UseGuards,
|
||||
} from '@nestjs/common';
|
||||
import { AuthGuard } from '../auth/auth.guard.js';
|
||||
import { CurrentUser } from '../auth/current-user.decorator.js';
|
||||
import { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.js';
|
||||
import { AgentService } from './agent.service.js';
|
||||
|
||||
@Controller('api/sessions')
|
||||
@@ -20,24 +18,23 @@ export class SessionsController {
|
||||
constructor(@Inject(AgentService) private readonly agentService: AgentService) {}
|
||||
|
||||
@Get()
|
||||
list(@CurrentUser() user: AuthenticatedUserLike) {
|
||||
const sessions = this.agentService.listSessions(scopeFromUser(user));
|
||||
list() {
|
||||
const sessions = this.agentService.listSessions();
|
||||
return { sessions, total: sessions.length };
|
||||
}
|
||||
|
||||
@Get(':id')
|
||||
findOne(@Param('id') id: string, @CurrentUser() user: AuthenticatedUserLike) {
|
||||
const info = this.agentService.getSessionInfo(id, scopeFromUser(user));
|
||||
findOne(@Param('id') id: string) {
|
||||
const info = this.agentService.getSessionInfo(id);
|
||||
if (!info) throw new NotFoundException('Session not found');
|
||||
return info;
|
||||
}
|
||||
|
||||
@Delete(':id')
|
||||
@HttpCode(HttpStatus.NO_CONTENT)
|
||||
async destroy(@Param('id') id: string, @CurrentUser() user: AuthenticatedUserLike) {
|
||||
const scope = scopeFromUser(user);
|
||||
const info = this.agentService.getSessionInfo(id, scope);
|
||||
async destroy(@Param('id') id: string) {
|
||||
const info = this.agentService.getSessionInfo(id);
|
||||
if (!info) throw new NotFoundException('Session not found');
|
||||
await this.agentService.destroySession(id, scope);
|
||||
await this.agentService.destroySession(id);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
export interface AuthenticatedUserLike {
|
||||
id: string;
|
||||
tenantId?: string | null;
|
||||
teamId?: string | null;
|
||||
organizationId?: string | null;
|
||||
orgId?: string | null;
|
||||
}
|
||||
|
||||
export interface ActorTenantScope {
|
||||
userId: string;
|
||||
tenantId: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the immutable server-derived scope used for Tess session operations.
|
||||
* Current Mosaic auth is user-scoped; future org/team claims can populate one
|
||||
* of the tenant fields without allowing clients to choose another tenant.
|
||||
*/
|
||||
export function scopeFromUser(user: AuthenticatedUserLike): ActorTenantScope {
|
||||
return {
|
||||
userId: user.id,
|
||||
tenantId: user.tenantId ?? user.teamId ?? user.organizationId ?? user.orgId ?? user.id,
|
||||
};
|
||||
}
|
||||
@@ -12,8 +12,7 @@ describe('Chat controller source hardening', () => {
|
||||
const source = readFileSync(resolve('src/chat/chat.controller.ts'), 'utf8');
|
||||
|
||||
expect(source).toContain('@UseGuards(AuthGuard)');
|
||||
expect(source).toContain('@CurrentUser() user: AuthenticatedUserLike');
|
||||
expect(source).toContain('const scope = scopeFromUser(user);');
|
||||
expect(source).toContain('@CurrentUser() user: { id: string }');
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
@@ -3,10 +3,8 @@ import {
|
||||
Post,
|
||||
Body,
|
||||
Logger,
|
||||
ForbiddenException,
|
||||
HttpException,
|
||||
HttpStatus,
|
||||
NotFoundException,
|
||||
Inject,
|
||||
UseGuards,
|
||||
} from '@nestjs/common';
|
||||
@@ -15,7 +13,6 @@ import { Throttle } from '@nestjs/throttler';
|
||||
import { AgentService } from '../agent/agent.service.js';
|
||||
import { AuthGuard } from '../auth/auth.guard.js';
|
||||
import { CurrentUser } from '../auth/current-user.decorator.js';
|
||||
import { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.js';
|
||||
import { v4 as uuid } from 'uuid';
|
||||
import { ChatRequestDto } from './chat.dto.js';
|
||||
|
||||
@@ -35,23 +32,16 @@ export class ChatController {
|
||||
@Throttle({ default: { limit: 10, ttl: 60_000 } })
|
||||
async chat(
|
||||
@Body() body: ChatRequestDto,
|
||||
@CurrentUser() user: AuthenticatedUserLike,
|
||||
@CurrentUser() user: { id: string },
|
||||
): Promise<ChatResponse> {
|
||||
const conversationId = body.conversationId ?? uuid();
|
||||
const scope = scopeFromUser(user);
|
||||
|
||||
try {
|
||||
let agentSession = this.agentService.getSession(conversationId, scope);
|
||||
let agentSession = this.agentService.getSession(conversationId);
|
||||
if (!agentSession) {
|
||||
agentSession = await this.agentService.createSession(conversationId, {
|
||||
userId: scope.userId,
|
||||
tenantId: scope.tenantId,
|
||||
});
|
||||
agentSession = await this.agentService.createSession(conversationId);
|
||||
}
|
||||
} catch (err) {
|
||||
if (err instanceof ForbiddenException) {
|
||||
throw new NotFoundException('Session not found');
|
||||
}
|
||||
this.logger.error(
|
||||
`Session creation failed for conversation=${conversationId}`,
|
||||
err instanceof Error ? err.stack : String(err),
|
||||
@@ -70,27 +60,20 @@ export class ChatController {
|
||||
reject(new Error('Agent response timed out'));
|
||||
}, 120_000);
|
||||
|
||||
const cleanup = this.agentService.onEvent(
|
||||
conversationId,
|
||||
(event: AgentSessionEvent) => {
|
||||
if (
|
||||
event.type === 'message_update' &&
|
||||
event.assistantMessageEvent.type === 'text_delta'
|
||||
) {
|
||||
responseText += event.assistantMessageEvent.delta;
|
||||
}
|
||||
if (event.type === 'agent_end') {
|
||||
clearTimeout(timer);
|
||||
cleanup();
|
||||
resolve();
|
||||
}
|
||||
},
|
||||
scope,
|
||||
);
|
||||
const cleanup = this.agentService.onEvent(conversationId, (event: AgentSessionEvent) => {
|
||||
if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
|
||||
responseText += event.assistantMessageEvent.delta;
|
||||
}
|
||||
if (event.type === 'agent_end') {
|
||||
clearTimeout(timer);
|
||||
cleanup();
|
||||
resolve();
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
try {
|
||||
await this.agentService.prompt(conversationId, body.content, scope);
|
||||
await this.agentService.prompt(conversationId, body.content);
|
||||
await done;
|
||||
} catch (err) {
|
||||
if (err instanceof HttpException) throw err;
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
import { timingSafeEqual } from 'node:crypto';
|
||||
import type { IncomingHttpHeaders } from 'node:http';
|
||||
import { fromNodeHeaders } from 'better-auth/node';
|
||||
|
||||
@@ -13,19 +12,6 @@ export interface SessionAuth {
|
||||
};
|
||||
}
|
||||
|
||||
export function validateDiscordServiceToken(
|
||||
candidate: unknown,
|
||||
expected: string | undefined,
|
||||
): boolean {
|
||||
if (typeof candidate !== 'string' || !expected) return false;
|
||||
const candidateBuffer = Buffer.from(candidate);
|
||||
const expectedBuffer = Buffer.from(expected);
|
||||
return (
|
||||
candidateBuffer.length === expectedBuffer.length &&
|
||||
timingSafeEqual(candidateBuffer, expectedBuffer)
|
||||
);
|
||||
}
|
||||
|
||||
export async function validateSocketSession(
|
||||
headers: IncomingHttpHeaders,
|
||||
auth: SessionAuth,
|
||||
|
||||
@@ -1,74 +0,0 @@
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import type { SlashCommandPayload } from '@mosaicstack/types';
|
||||
import { ChatGateway } from './chat.gateway.js';
|
||||
|
||||
const payload: SlashCommandPayload = {
|
||||
command: 'gc',
|
||||
conversationId: 'conversation-1',
|
||||
approvalId: 'approval-1',
|
||||
};
|
||||
|
||||
function buildGateway(commandExecutor: {
|
||||
execute: ReturnType<typeof vi.fn>;
|
||||
createApproval: ReturnType<typeof vi.fn>;
|
||||
}): ChatGateway {
|
||||
return new ChatGateway(
|
||||
{} as never,
|
||||
{} as never,
|
||||
{} as never,
|
||||
{} as never,
|
||||
commandExecutor as never,
|
||||
{} as never,
|
||||
);
|
||||
}
|
||||
|
||||
describe('ChatGateway command approval ingress', () => {
|
||||
it('passes the client approval ID through to command execution while deriving the actor server-side', async (): Promise<void> => {
|
||||
const commandExecutor = {
|
||||
execute: vi.fn().mockResolvedValue({ ...payload, success: true }),
|
||||
createApproval: vi.fn(),
|
||||
};
|
||||
const gateway = buildGateway(commandExecutor);
|
||||
const client = { data: { user: { id: 'admin-1' } }, emit: vi.fn() };
|
||||
|
||||
await gateway.handleCommandExecute(client as never, payload);
|
||||
|
||||
expect(commandExecutor.execute).toHaveBeenCalledWith(payload, {
|
||||
userId: 'admin-1',
|
||||
tenantId: 'admin-1',
|
||||
});
|
||||
expect(client.emit).toHaveBeenCalledWith(
|
||||
'command:result',
|
||||
expect.objectContaining({ success: true }),
|
||||
);
|
||||
});
|
||||
|
||||
it('issues a durable approval only for the authenticated actor', async (): Promise<void> => {
|
||||
const commandExecutor = {
|
||||
execute: vi.fn(),
|
||||
createApproval: vi.fn().mockResolvedValue({
|
||||
approvalId: 'approval-1',
|
||||
expiresAt: '2026-07-12T00:05:00.000Z',
|
||||
}),
|
||||
};
|
||||
const gateway = buildGateway(commandExecutor);
|
||||
const client = { data: { user: { id: 'admin-1' } }, emit: vi.fn() };
|
||||
|
||||
await gateway.handleCommandApproval(client as never, {
|
||||
command: 'gc',
|
||||
conversationId: 'conversation-1',
|
||||
});
|
||||
|
||||
expect(commandExecutor.createApproval).toHaveBeenCalledWith(
|
||||
{ command: 'gc', conversationId: 'conversation-1' },
|
||||
{ userId: 'admin-1', tenantId: 'admin-1' },
|
||||
);
|
||||
expect(client.emit).toHaveBeenCalledWith('command:approval', {
|
||||
command: 'gc',
|
||||
conversationId: 'conversation-1',
|
||||
success: true,
|
||||
approvalId: 'approval-1',
|
||||
expiresAt: '2026-07-12T00:05:00.000Z',
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -1,170 +0,0 @@
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import { ChatGateway } from './chat.gateway.js';
|
||||
|
||||
const CONVERSATION_ID = 'conversation-1';
|
||||
const CANARY = 'sk_canary12345678';
|
||||
|
||||
type GatewayInternals = {
|
||||
clientSessions: Map<string, unknown>;
|
||||
relayEvent(client: unknown, conversationId: string, event: unknown): void;
|
||||
};
|
||||
|
||||
function buildGateway() {
|
||||
const brain = {
|
||||
conversations: {
|
||||
addMessage: vi.fn().mockResolvedValue(undefined),
|
||||
},
|
||||
};
|
||||
const agentService = {
|
||||
getSession: vi.fn().mockReturnValue(undefined),
|
||||
};
|
||||
const gateway = new ChatGateway(
|
||||
agentService as never,
|
||||
{} as never,
|
||||
brain as never,
|
||||
{} as never,
|
||||
{} as never,
|
||||
{} as never,
|
||||
);
|
||||
|
||||
return { gateway: gateway as unknown as GatewayInternals, brain };
|
||||
}
|
||||
|
||||
describe('ChatGateway redaction boundary', (): void => {
|
||||
it('redacts a secret split across assistant deltas before egress and persistence', (): void => {
|
||||
const { gateway } = buildGateway();
|
||||
const client = {
|
||||
connected: true,
|
||||
id: 'client-1',
|
||||
data: { user: { id: 'user-1' } },
|
||||
emit: vi.fn(),
|
||||
};
|
||||
const session = {
|
||||
conversationId: CONVERSATION_ID,
|
||||
cleanup: vi.fn(),
|
||||
assistantText: '',
|
||||
toolCalls: [],
|
||||
pendingToolCalls: new Map(),
|
||||
scope: { userId: 'user-1', tenantId: 'tenant-1' },
|
||||
};
|
||||
gateway.clientSessions.set(client.id, session);
|
||||
|
||||
gateway.relayEvent(client, CONVERSATION_ID, {
|
||||
type: 'message_update',
|
||||
assistantMessageEvent: { type: 'text_delta', delta: 'sk_canary' },
|
||||
});
|
||||
|
||||
expect(JSON.stringify(client.emit.mock.calls)).not.toContain('sk_canary');
|
||||
|
||||
gateway.relayEvent(client, CONVERSATION_ID, {
|
||||
type: 'message_update',
|
||||
assistantMessageEvent: { type: 'text_delta', delta: '12345678 ' },
|
||||
});
|
||||
|
||||
expect(client.emit).toHaveBeenCalledWith('agent:text', {
|
||||
conversationId: CONVERSATION_ID,
|
||||
text: '[REDACTED_SECRET] ',
|
||||
});
|
||||
expect(session.assistantText).toBe(`${CANARY} `);
|
||||
expect(JSON.stringify(client.emit.mock.calls)).not.toContain(CANARY);
|
||||
});
|
||||
|
||||
it('retains a split secret label until its value can be redacted', (): void => {
|
||||
const { gateway } = buildGateway();
|
||||
const client = {
|
||||
connected: true,
|
||||
id: 'client-1',
|
||||
data: { user: { id: 'user-1' } },
|
||||
emit: vi.fn(),
|
||||
};
|
||||
|
||||
gateway.relayEvent(client, CONVERSATION_ID, {
|
||||
type: 'message_update',
|
||||
assistantMessageEvent: { type: 'text_delta', delta: 'token ' },
|
||||
});
|
||||
gateway.relayEvent(client, CONVERSATION_ID, {
|
||||
type: 'message_update',
|
||||
assistantMessageEvent: { type: 'text_delta', delta: '=canaryvalue123 ' },
|
||||
});
|
||||
|
||||
expect(client.emit).toHaveBeenCalledWith('agent:text', {
|
||||
conversationId: CONVERSATION_ID,
|
||||
text: '[REDACTED_SECRET] ',
|
||||
});
|
||||
expect(JSON.stringify(client.emit.mock.calls)).not.toContain('canaryvalue123');
|
||||
});
|
||||
|
||||
it('holds a streamed private key until it can be redacted', (): void => {
|
||||
const { gateway } = buildGateway();
|
||||
const client = {
|
||||
connected: true,
|
||||
id: 'client-1',
|
||||
data: { user: { id: 'user-1' } },
|
||||
emit: vi.fn(),
|
||||
};
|
||||
|
||||
gateway.relayEvent(client, CONVERSATION_ID, {
|
||||
type: 'message_update',
|
||||
assistantMessageEvent: { type: 'text_delta', delta: '-----BEGIN PRIVATE KEY-----\ncanary' },
|
||||
});
|
||||
gateway.relayEvent(client, CONVERSATION_ID, {
|
||||
type: 'message_update',
|
||||
assistantMessageEvent: { type: 'text_delta', delta: '\n-----END PRIVATE KEY-----' },
|
||||
});
|
||||
|
||||
expect(client.emit).toHaveBeenCalledWith('agent:text', {
|
||||
conversationId: CONVERSATION_ID,
|
||||
text: '[REDACTED_SECRET]',
|
||||
});
|
||||
expect(JSON.stringify(client.emit.mock.calls)).not.toContain('canary');
|
||||
});
|
||||
|
||||
it('drops an oversized unterminated stream fragment rather than retaining it', (): void => {
|
||||
const { gateway } = buildGateway();
|
||||
const client = {
|
||||
connected: true,
|
||||
id: 'client-1',
|
||||
data: { user: { id: 'user-1' } },
|
||||
emit: vi.fn(),
|
||||
};
|
||||
|
||||
gateway.relayEvent(client, CONVERSATION_ID, {
|
||||
type: 'message_update',
|
||||
assistantMessageEvent: { type: 'text_delta', delta: 'x'.repeat(8_193) },
|
||||
});
|
||||
|
||||
expect(client.emit).toHaveBeenCalledWith('agent:text', {
|
||||
conversationId: CONVERSATION_ID,
|
||||
text: '[REDACTED_STREAM_OVERFLOW]',
|
||||
});
|
||||
});
|
||||
|
||||
it('persists only redacted assistant content with classifications', (): void => {
|
||||
const { gateway, brain } = buildGateway();
|
||||
const client = {
|
||||
connected: true,
|
||||
id: 'client-1',
|
||||
data: { user: { id: 'user-1' } },
|
||||
emit: vi.fn(),
|
||||
};
|
||||
gateway.clientSessions.set(client.id, {
|
||||
conversationId: CONVERSATION_ID,
|
||||
cleanup: vi.fn(),
|
||||
assistantText: CANARY,
|
||||
toolCalls: [],
|
||||
pendingToolCalls: new Map(),
|
||||
scope: { userId: 'user-1', tenantId: 'tenant-1' },
|
||||
});
|
||||
|
||||
gateway.relayEvent(client, CONVERSATION_ID, { type: 'agent_end' });
|
||||
|
||||
expect(brain.conversations.addMessage).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
content: '[REDACTED_SECRET]',
|
||||
metadata: expect.objectContaining({ classifications: ['secret'] }),
|
||||
}),
|
||||
'user-1',
|
||||
);
|
||||
expect(JSON.stringify(brain.conversations.addMessage.mock.calls)).not.toContain(CANARY);
|
||||
});
|
||||
});
|
||||
@@ -11,17 +11,10 @@ import {
|
||||
} from '@nestjs/websockets';
|
||||
import { Server, Socket } from 'socket.io';
|
||||
import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
|
||||
import {
|
||||
verifyDiscordIngressEnvelope,
|
||||
type DiscordIngressEnvelope,
|
||||
type DiscordIngressPayload,
|
||||
} from '@mosaicstack/discord-plugin';
|
||||
import type { Auth } from '@mosaicstack/auth';
|
||||
import type { Brain } from '@mosaicstack/brain';
|
||||
import { redactSensitiveContent } from '@mosaicstack/log';
|
||||
import type {
|
||||
SetThinkingPayload,
|
||||
SlashCommandApprovalResultPayload,
|
||||
SlashCommandPayload,
|
||||
SystemReloadPayload,
|
||||
RoutingDecisionInfo,
|
||||
@@ -29,19 +22,13 @@ import type {
|
||||
} from '@mosaicstack/types';
|
||||
import { AgentService, type ConversationHistoryMessage } from '../agent/agent.service.js';
|
||||
import { AUTH } from '../auth/auth.tokens.js';
|
||||
import {
|
||||
scopeFromUser,
|
||||
type ActorTenantScope,
|
||||
type AuthenticatedUserLike,
|
||||
} from '../auth/session-scope.js';
|
||||
import { BRAIN } from '../brain/brain.tokens.js';
|
||||
import { CommandRegistryService } from '../commands/command-registry.service.js';
|
||||
import { CommandExecutorService } from '../commands/command-executor.service.js';
|
||||
import { RoutingEngineService } from '../agent/routing/routing-engine.service.js';
|
||||
import { v4 as uuid } from 'uuid';
|
||||
import { ChatSocketMessageDto } from './chat.dto.js';
|
||||
import { validateDiscordServiceToken, validateSocketSession } from './chat.gateway-auth.js';
|
||||
import { DiscordReplayProtector } from '../plugin/discord-replay-protector.js';
|
||||
import { validateSocketSession } from './chat.gateway-auth.js';
|
||||
|
||||
/** Per-client state tracking streaming accumulation for persistence. */
|
||||
interface ClientSession {
|
||||
@@ -53,8 +40,6 @@ interface ClientSession {
|
||||
toolCalls: Array<{ toolCallId: string; toolName: string; args: unknown; isError: boolean }>;
|
||||
/** Tool calls in-flight (started but not ended yet). */
|
||||
pendingToolCalls: Map<string, { toolName: string; args: unknown }>;
|
||||
/** Server-derived owner/tenant scope for this socket's conversation attachment. */
|
||||
scope: ActorTenantScope;
|
||||
/** Last routing decision made for this session (M4-008) */
|
||||
lastRoutingDecision?: RoutingDecisionInfo;
|
||||
}
|
||||
@@ -64,38 +49,6 @@ interface ClientSession {
|
||||
* Keyed by conversationId, value is the model name to use.
|
||||
*/
|
||||
const modelOverrides = new Map<string, string>();
|
||||
const MAX_REDACTION_BUFFER_LENGTH = 8_192;
|
||||
|
||||
function isDiscordIngressEnvelope(value: unknown): value is DiscordIngressEnvelope {
|
||||
if (typeof value !== 'object' || value === null) return false;
|
||||
const envelope = value as { payload?: unknown; signature?: unknown };
|
||||
if (
|
||||
typeof envelope.signature !== 'string' ||
|
||||
typeof envelope.payload !== 'object' ||
|
||||
envelope.payload === null
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
const payload = envelope.payload as Record<string, unknown>;
|
||||
return [
|
||||
payload['correlationId'],
|
||||
payload['messageId'],
|
||||
payload['guildId'],
|
||||
payload['channelId'],
|
||||
payload['userId'],
|
||||
payload['conversationId'],
|
||||
payload['content'],
|
||||
].every((field: unknown): boolean => typeof field === 'string');
|
||||
}
|
||||
|
||||
function isChatSocketMessage(value: unknown): value is ChatSocketMessageDto {
|
||||
if (typeof value !== 'object' || value === null) return false;
|
||||
const payload = value as { content?: unknown; conversationId?: unknown };
|
||||
return (
|
||||
typeof payload.content === 'string' &&
|
||||
(payload.conversationId === undefined || typeof payload.conversationId === 'string')
|
||||
);
|
||||
}
|
||||
|
||||
@WebSocketGateway({
|
||||
cors: {
|
||||
@@ -109,11 +62,6 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
|
||||
private readonly logger = new Logger(ChatGateway.name);
|
||||
private readonly clientSessions = new Map<string, ClientSession>();
|
||||
/** Raw stream fragments are kept in memory only until they are safe to redact and emit. */
|
||||
private readonly textEgressBuffers = new Map<string, string>();
|
||||
private readonly thinkingEgressBuffers = new Map<string, string>();
|
||||
private readonly overflowedEgress = new Set<string>();
|
||||
private readonly discordReplayProtector = new DiscordReplayProtector();
|
||||
|
||||
constructor(
|
||||
@Inject(AgentService) private readonly agentService: AgentService,
|
||||
@@ -129,13 +77,6 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
}
|
||||
|
||||
async handleConnection(client: Socket): Promise<void> {
|
||||
const serviceToken = client.handshake.auth['discordServiceToken'];
|
||||
if (validateDiscordServiceToken(serviceToken, process.env['DISCORD_SERVICE_TOKEN'])) {
|
||||
client.data.discordService = true;
|
||||
this.logger.log(`Authenticated Discord service connected: ${client.id}`);
|
||||
return;
|
||||
}
|
||||
|
||||
const session = await validateSocketSession(client.handshake.headers, this.auth);
|
||||
if (!session) {
|
||||
this.logger.warn(`Rejected unauthenticated WebSocket client: ${client.id}`);
|
||||
@@ -146,6 +87,8 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
client.data.user = session.user;
|
||||
client.data.session = session.session;
|
||||
this.logger.log(`Client connected: ${client.id}`);
|
||||
|
||||
// Broadcast command manifest to the newly connected client
|
||||
client.emit('commands:manifest', { manifest: this.commandRegistry.getManifest() });
|
||||
}
|
||||
|
||||
@@ -154,84 +97,25 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
const session = this.clientSessions.get(client.id);
|
||||
if (session) {
|
||||
session.cleanup();
|
||||
this.agentService.removeChannel(
|
||||
session.conversationId,
|
||||
`websocket:${client.id}`,
|
||||
session.scope,
|
||||
);
|
||||
this.agentService.removeChannel(session.conversationId, `websocket:${client.id}`);
|
||||
this.clientSessions.delete(client.id);
|
||||
}
|
||||
this.textEgressBuffers.delete(client.id);
|
||||
this.thinkingEgressBuffers.delete(client.id);
|
||||
this.overflowedEgress.delete(this.egressKey(client, 'agent:text'));
|
||||
this.overflowedEgress.delete(this.egressKey(client, 'agent:thinking'));
|
||||
}
|
||||
|
||||
private getClientScope(client: Socket): ActorTenantScope | null {
|
||||
const user = client.data.user as AuthenticatedUserLike | undefined;
|
||||
if (!user?.id) return null;
|
||||
return scopeFromUser(user);
|
||||
}
|
||||
|
||||
private modelOverrideKey(conversationId: string, scope: ActorTenantScope): string {
|
||||
return `${scope.tenantId}:${scope.userId}:${conversationId}`;
|
||||
}
|
||||
|
||||
private scopesEqual(a: ActorTenantScope, b: ActorTenantScope): boolean {
|
||||
return a.userId === b.userId && a.tenantId === b.tenantId;
|
||||
}
|
||||
|
||||
@SubscribeMessage('message')
|
||||
async handleMessage(
|
||||
@ConnectedSocket() client: Socket,
|
||||
@MessageBody() rawData: unknown,
|
||||
@MessageBody() data: ChatSocketMessageDto,
|
||||
): Promise<void> {
|
||||
let discordIngress: DiscordIngressPayload | null = null;
|
||||
let data: ChatSocketMessageDto;
|
||||
if (client.data.discordService) {
|
||||
if (!isDiscordIngressEnvelope(rawData)) {
|
||||
this.logger.warn(`Rejected malformed Discord ingress from ${client.id}`);
|
||||
return;
|
||||
}
|
||||
discordIngress = this.resolveDiscordIngress(client, rawData);
|
||||
if (!discordIngress) return;
|
||||
data = { conversationId: discordIngress.conversationId, content: discordIngress.content };
|
||||
} else {
|
||||
if (!isChatSocketMessage(rawData)) {
|
||||
this.logger.warn(`Rejected malformed chat message from ${client.id}`);
|
||||
return;
|
||||
}
|
||||
data = rawData;
|
||||
}
|
||||
const conversationId = data.conversationId ?? uuid();
|
||||
const discordServiceUserId = process.env['DISCORD_SERVICE_USER_ID'];
|
||||
if (discordIngress && !discordServiceUserId) {
|
||||
this.logger.warn(
|
||||
`Rejected Discord ingress without configured service owner from ${client.id}`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
const scope = discordIngress
|
||||
? {
|
||||
userId: discordServiceUserId!,
|
||||
tenantId: process.env['DISCORD_SERVICE_TENANT_ID'] ?? discordServiceUserId!,
|
||||
}
|
||||
: this.getClientScope(client);
|
||||
if (!scope) {
|
||||
client.emit('error', { conversationId, error: 'Authenticated user scope is required.' });
|
||||
return;
|
||||
}
|
||||
const userId = scope.userId;
|
||||
const correlationId = discordIngress?.correlationId;
|
||||
const userId = (client.data.user as { id: string } | undefined)?.id;
|
||||
|
||||
this.logger.log(
|
||||
`Message from ${client.id} in conversation ${conversationId}${correlationId ? ` correlation=${correlationId}` : ''}`,
|
||||
);
|
||||
this.logger.log(`Message from ${client.id} in conversation ${conversationId}`);
|
||||
|
||||
// Ensure agent session exists for this conversation
|
||||
let sessionRoutingDecision: RoutingDecisionInfo | undefined;
|
||||
try {
|
||||
let agentSession = this.agentService.getSession(conversationId, scope);
|
||||
let agentSession = this.agentService.getSession(conversationId);
|
||||
if (!agentSession) {
|
||||
// When resuming an existing conversation, load prior messages to inject as context (M1-004)
|
||||
const conversationHistory = await this.loadConversationHistory(conversationId, userId);
|
||||
@@ -251,7 +135,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
let resolvedProvider = data.provider;
|
||||
let resolvedModelId = data.modelId;
|
||||
|
||||
const modelOverride = modelOverrides.get(this.modelOverrideKey(conversationId, scope));
|
||||
const modelOverride = modelOverrides.get(conversationId);
|
||||
if (modelOverride) {
|
||||
// /model override bypasses routing engine (M4-007)
|
||||
resolvedModelId = modelOverride;
|
||||
@@ -288,7 +172,6 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
modelId: resolvedModelId,
|
||||
agentConfigId: data.agentId,
|
||||
userId,
|
||||
tenantId: scope.tenantId,
|
||||
conversationHistory: conversationHistory.length > 0 ? conversationHistory : undefined,
|
||||
});
|
||||
|
||||
@@ -327,17 +210,9 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
{
|
||||
conversationId,
|
||||
role: 'user',
|
||||
content: redactSensitiveContent(data.content).content,
|
||||
content: data.content,
|
||||
metadata: {
|
||||
timestamp: new Date().toISOString(),
|
||||
...(correlationId
|
||||
? {
|
||||
correlationId,
|
||||
discordMessageId: discordIngress?.messageId,
|
||||
discordUserId: discordIngress?.userId,
|
||||
}
|
||||
: {}),
|
||||
classifications: redactSensitiveContent(data.content).classifications,
|
||||
},
|
||||
},
|
||||
userId,
|
||||
@@ -357,13 +232,9 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
}
|
||||
|
||||
// Subscribe to agent events and relay to client
|
||||
const cleanup = this.agentService.onEvent(
|
||||
conversationId,
|
||||
(event: AgentSessionEvent) => {
|
||||
this.relayEvent(client, conversationId, event);
|
||||
},
|
||||
scope,
|
||||
);
|
||||
const cleanup = this.agentService.onEvent(conversationId, (event: AgentSessionEvent) => {
|
||||
this.relayEvent(client, conversationId, event);
|
||||
});
|
||||
|
||||
// Preserve routing decision from the existing client session if we didn't get a new one
|
||||
const prevClientSession = this.clientSessions.get(client.id);
|
||||
@@ -375,17 +246,16 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
assistantText: '',
|
||||
toolCalls: [],
|
||||
pendingToolCalls: new Map(),
|
||||
scope,
|
||||
lastRoutingDecision: routingDecisionToStore,
|
||||
});
|
||||
|
||||
// Track channel connection
|
||||
this.agentService.addChannel(conversationId, `websocket:${client.id}`, scope);
|
||||
this.agentService.addChannel(conversationId, `websocket:${client.id}`);
|
||||
|
||||
// Send session info so the client knows the model/provider (M4-008: include routing decision)
|
||||
// Include agentName when a named agent config is active (M5-001)
|
||||
{
|
||||
const agentSession = this.agentService.getSession(conversationId, scope);
|
||||
const agentSession = this.agentService.getSession(conversationId);
|
||||
if (agentSession) {
|
||||
const piSession = agentSession.piSession;
|
||||
client.emit('session:info', {
|
||||
@@ -401,21 +271,11 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
}
|
||||
|
||||
// Send acknowledgment
|
||||
client.emit('message:ack', {
|
||||
conversationId,
|
||||
messageId: uuid(),
|
||||
...(correlationId
|
||||
? {
|
||||
correlationId,
|
||||
discordMessageId: discordIngress?.messageId,
|
||||
discordUserId: discordIngress?.userId,
|
||||
}
|
||||
: {}),
|
||||
});
|
||||
client.emit('message:ack', { conversationId, messageId: uuid() });
|
||||
|
||||
// Dispatch to agent
|
||||
try {
|
||||
await this.agentService.prompt(conversationId, data.content, scope);
|
||||
await this.agentService.prompt(conversationId, data.content);
|
||||
} catch (err) {
|
||||
this.logger.error(
|
||||
`Agent prompt failed for client=${client.id}, conversation=${conversationId}`,
|
||||
@@ -433,16 +293,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
@ConnectedSocket() client: Socket,
|
||||
@MessageBody() data: SetThinkingPayload,
|
||||
): void {
|
||||
const scope = this.getClientScope(client);
|
||||
if (!scope) {
|
||||
client.emit('error', {
|
||||
conversationId: data.conversationId,
|
||||
error: 'Authenticated user scope is required.',
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
const session = this.agentService.getSession(data.conversationId, scope);
|
||||
const session = this.agentService.getSession(data.conversationId);
|
||||
if (!session) {
|
||||
client.emit('error', {
|
||||
conversationId: data.conversationId,
|
||||
@@ -483,13 +334,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
const conversationId = data.conversationId;
|
||||
this.logger.log(`Abort requested by ${client.id} for conversation ${conversationId}`);
|
||||
|
||||
const scope = this.getClientScope(client);
|
||||
if (!scope) {
|
||||
client.emit('error', { conversationId, error: 'Authenticated user scope is required.' });
|
||||
return;
|
||||
}
|
||||
|
||||
const session = this.agentService.getSession(conversationId, scope);
|
||||
const session = this.agentService.getSession(conversationId);
|
||||
if (!session) {
|
||||
client.emit('error', {
|
||||
conversationId,
|
||||
@@ -518,45 +363,11 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
@ConnectedSocket() client: Socket,
|
||||
@MessageBody() payload: SlashCommandPayload,
|
||||
): Promise<void> {
|
||||
const scope = this.getClientScope(client);
|
||||
if (!scope) {
|
||||
client.emit('command:result', {
|
||||
command: payload.command,
|
||||
conversationId: payload.conversationId,
|
||||
success: false,
|
||||
message: 'Authenticated user scope is required.',
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
const result = await this.commandExecutor.execute(payload, scope);
|
||||
const userId = (client.data.user as { id: string } | undefined)?.id ?? 'unknown';
|
||||
const result = await this.commandExecutor.execute(payload, userId);
|
||||
client.emit('command:result', result);
|
||||
}
|
||||
|
||||
@SubscribeMessage('command:approve')
|
||||
async handleCommandApproval(
|
||||
@ConnectedSocket() client: Socket,
|
||||
@MessageBody() payload: SlashCommandPayload,
|
||||
): Promise<void> {
|
||||
const scope = this.getClientScope(client);
|
||||
const approval = scope ? await this.commandExecutor.createApproval(payload, scope) : null;
|
||||
const result: SlashCommandApprovalResultPayload = approval
|
||||
? {
|
||||
command: payload.command,
|
||||
conversationId: payload.conversationId,
|
||||
success: true,
|
||||
approvalId: approval.approvalId,
|
||||
expiresAt: approval.expiresAt,
|
||||
}
|
||||
: {
|
||||
command: payload.command,
|
||||
conversationId: payload.conversationId,
|
||||
success: false,
|
||||
message: 'Not authorized to approve this command.',
|
||||
};
|
||||
client.emit('command:approval', result);
|
||||
}
|
||||
|
||||
broadcastReload(payload: SystemReloadPayload): void {
|
||||
this.server.emit('system:reload', payload);
|
||||
this.logger.log('Broadcasted system:reload to all connected clients');
|
||||
@@ -569,23 +380,18 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
* M5-005: Emits session:info to clients subscribed to this conversation when a model is set.
|
||||
* M5-007: Records a model switch in session metrics.
|
||||
*/
|
||||
setModelOverride(
|
||||
conversationId: string,
|
||||
modelName: string | null,
|
||||
scope: ActorTenantScope,
|
||||
): void {
|
||||
const key = this.modelOverrideKey(conversationId, scope);
|
||||
setModelOverride(conversationId: string, modelName: string | null): void {
|
||||
if (modelName) {
|
||||
modelOverrides.set(key, modelName);
|
||||
modelOverrides.set(conversationId, modelName);
|
||||
this.logger.log(`Model override set: conversation=${conversationId} model="${modelName}"`);
|
||||
|
||||
// M5-002: Update the live session's modelId so session:info reflects the new model immediately
|
||||
this.agentService.updateSessionModel(conversationId, modelName, scope);
|
||||
this.agentService.updateSessionModel(conversationId, modelName);
|
||||
|
||||
// M5-005: Broadcast session:info to all clients subscribed to this conversation
|
||||
this.broadcastSessionInfo(conversationId, scope);
|
||||
this.broadcastSessionInfo(conversationId);
|
||||
} else {
|
||||
modelOverrides.delete(key);
|
||||
modelOverrides.delete(conversationId);
|
||||
this.logger.log(`Model override cleared: conversation=${conversationId}`);
|
||||
}
|
||||
}
|
||||
@@ -593,8 +399,8 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
/**
|
||||
* Return the active model override for a conversation, or undefined if none.
|
||||
*/
|
||||
getModelOverride(conversationId: string, scope: ActorTenantScope): string | undefined {
|
||||
return modelOverrides.get(this.modelOverrideKey(conversationId, scope));
|
||||
getModelOverride(conversationId: string): string | undefined {
|
||||
return modelOverrides.get(conversationId);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -603,10 +409,9 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
*/
|
||||
broadcastSessionInfo(
|
||||
conversationId: string,
|
||||
scope: ActorTenantScope,
|
||||
extra?: { agentName?: string; routingDecision?: RoutingDecisionInfo },
|
||||
): void {
|
||||
const agentSession = this.agentService.getSession(conversationId, scope);
|
||||
const agentSession = this.agentService.getSession(conversationId);
|
||||
if (!agentSession) return;
|
||||
|
||||
const piSession = agentSession.piSession;
|
||||
@@ -623,7 +428,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
|
||||
// Emit to all clients currently subscribed to this conversation
|
||||
for (const [clientId, session] of this.clientSessions) {
|
||||
if (session.conversationId === conversationId && this.scopesEqual(session.scope, scope)) {
|
||||
if (session.conversationId === conversationId) {
|
||||
const socket = this.server.sockets.sockets.get(clientId);
|
||||
if (socket?.connected) {
|
||||
socket.emit('session:info', payload);
|
||||
@@ -637,39 +442,6 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
* Creates it if absent — safe to call concurrently since a duplicate insert
|
||||
* would fail on the PK constraint and be caught here.
|
||||
*/
|
||||
private resolveDiscordIngress(
|
||||
client: Socket,
|
||||
envelope: DiscordIngressEnvelope,
|
||||
): DiscordIngressPayload | null {
|
||||
const payload = verifyDiscordIngressEnvelope(
|
||||
envelope,
|
||||
process.env['DISCORD_SERVICE_TOKEN'] ?? '',
|
||||
{
|
||||
guildIds: this.readDiscordAllowlist('DISCORD_ALLOWED_GUILD_IDS'),
|
||||
channelIds: this.readDiscordAllowlist('DISCORD_ALLOWED_CHANNEL_IDS'),
|
||||
userIds: this.readDiscordAllowlist('DISCORD_ALLOWED_USER_IDS'),
|
||||
},
|
||||
);
|
||||
if (!payload) {
|
||||
this.logger.warn(`Rejected invalid Discord ingress envelope from ${client.id}`);
|
||||
return null;
|
||||
}
|
||||
if (!this.discordReplayProtector.claim(payload.messageId)) {
|
||||
this.logger.warn(
|
||||
`Rejected replayed Discord message=${payload.messageId} correlation=${payload.correlationId}`,
|
||||
);
|
||||
return null;
|
||||
}
|
||||
return payload;
|
||||
}
|
||||
|
||||
private readDiscordAllowlist(name: string): string[] {
|
||||
return (process.env[name] ?? '')
|
||||
.split(',')
|
||||
.map((id: string): string => id.trim())
|
||||
.filter((id: string): boolean => id.length > 0);
|
||||
}
|
||||
|
||||
private async ensureConversation(conversationId: string, userId: string): Promise<void> {
|
||||
try {
|
||||
const existing = await this.brain.conversations.findById(conversationId, userId);
|
||||
@@ -755,127 +527,6 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
}
|
||||
}
|
||||
|
||||
private appendAndFlushRedactedEgress(
|
||||
client: Socket,
|
||||
conversationId: string,
|
||||
eventName: 'agent:text' | 'agent:thinking',
|
||||
buffers: Map<string, string>,
|
||||
delta: string,
|
||||
): void {
|
||||
const key = this.egressKey(client, eventName);
|
||||
if (this.overflowedEgress.has(key)) return;
|
||||
|
||||
const buffered = `${buffers.get(client.id) ?? ''}${delta}`;
|
||||
if (buffered.length > MAX_REDACTION_BUFFER_LENGTH) {
|
||||
buffers.delete(client.id);
|
||||
this.overflowedEgress.add(key);
|
||||
client.emit(eventName, { conversationId, text: '[REDACTED_STREAM_OVERFLOW]' });
|
||||
return;
|
||||
}
|
||||
|
||||
buffers.set(client.id, buffered);
|
||||
this.flushRedactedEgress(client, conversationId, eventName, buffers, false);
|
||||
}
|
||||
|
||||
/**
|
||||
* Holds any suffix that could become a secret, email, or phone number after a
|
||||
* later stream chunk. This avoids relying on downstream redaction after data
|
||||
* has already reached the socket.
|
||||
*/
|
||||
private flushRedactedEgress(
|
||||
client: Socket,
|
||||
conversationId: string,
|
||||
eventName: 'agent:text' | 'agent:thinking',
|
||||
buffers: Map<string, string>,
|
||||
final: boolean,
|
||||
): void {
|
||||
const key = this.egressKey(client, eventName);
|
||||
if (this.overflowedEgress.has(key)) {
|
||||
if (final) this.overflowedEgress.delete(key);
|
||||
return;
|
||||
}
|
||||
|
||||
const buffered = buffers.get(client.id) ?? '';
|
||||
const releaseLength = final ? buffered.length : this.safeRedactionPrefixLength(buffered);
|
||||
const released = buffered.slice(0, releaseLength);
|
||||
const pending = buffered.slice(releaseLength);
|
||||
|
||||
if (pending) {
|
||||
buffers.set(client.id, pending);
|
||||
} else {
|
||||
buffers.delete(client.id);
|
||||
}
|
||||
|
||||
if (released) {
|
||||
client.emit(eventName, {
|
||||
conversationId,
|
||||
text: redactSensitiveContent(released).content,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
private safeRedactionPrefixLength(content: string): number {
|
||||
let retainedFrom = content.length;
|
||||
|
||||
// Retain the current token because it may become a split secret or email.
|
||||
const token = /(?:^|\s)(\S*)$/.exec(content);
|
||||
if (token) {
|
||||
const matched = token[0] ?? '';
|
||||
const trailingToken = token[1] ?? '';
|
||||
retainedFrom = token.index + matched.length - trailingToken.length;
|
||||
}
|
||||
|
||||
// The secret classifier accepts whitespace around ':' and '=', so preserve
|
||||
// a pending label until its value and delimiter are both complete.
|
||||
const pendingSecretLabel =
|
||||
/(?:^|[^A-Za-z0-9_])((?:api[_-]?key|token|password|secret|bearer|authorization)\s*)$/i.exec(
|
||||
content,
|
||||
);
|
||||
if (pendingSecretLabel) {
|
||||
const label = pendingSecretLabel[1] ?? '';
|
||||
retainedFrom = Math.min(
|
||||
retainedFrom,
|
||||
pendingSecretLabel.index + pendingSecretLabel[0].length - label.length,
|
||||
);
|
||||
}
|
||||
|
||||
const secretLabel = /(?:api[_-]?key|token|password|secret|authorization)\s*[:=]\s*$/i.exec(
|
||||
content,
|
||||
);
|
||||
if (secretLabel) {
|
||||
retainedFrom = Math.min(retainedFrom, secretLabel.index);
|
||||
}
|
||||
|
||||
// Phone numbers can contain whitespace and punctuation; preserve the full
|
||||
// trailing numeric candidate until a non-phone character establishes a boundary.
|
||||
const phone = /(?:^|[^A-Za-z0-9_])(\+?\d[\d(). -]*)$/.exec(content);
|
||||
if (phone) {
|
||||
const matched = phone[0] ?? '';
|
||||
const trailingPhoneCandidate = phone[1] ?? '';
|
||||
retainedFrom = Math.min(
|
||||
retainedFrom,
|
||||
phone.index + matched.length - trailingPhoneCandidate.length,
|
||||
);
|
||||
}
|
||||
|
||||
const privateKeyStart = content.lastIndexOf('-----BEGIN');
|
||||
if (privateKeyStart >= 0) {
|
||||
const privateKey = content.slice(privateKeyStart);
|
||||
if (/-----END(?: [A-Z]+)* KEY-----/.test(privateKey)) {
|
||||
// Release the complete block in one pass so the full-block classifier can redact it.
|
||||
retainedFrom = content.length;
|
||||
} else {
|
||||
retainedFrom = Math.min(retainedFrom, privateKeyStart);
|
||||
}
|
||||
}
|
||||
|
||||
return retainedFrom;
|
||||
}
|
||||
|
||||
private egressKey(client: Socket, eventName: 'agent:text' | 'agent:thinking'): string {
|
||||
return `${client.id}:${eventName}`;
|
||||
}
|
||||
|
||||
private relayEvent(client: Socket, conversationId: string, event: AgentSessionEvent): void {
|
||||
if (!client.connected) {
|
||||
this.logger.warn(
|
||||
@@ -893,20 +544,13 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
cs.toolCalls = [];
|
||||
cs.pendingToolCalls.clear();
|
||||
}
|
||||
this.textEgressBuffers.set(client.id, '');
|
||||
this.thinkingEgressBuffers.set(client.id, '');
|
||||
this.overflowedEgress.delete(this.egressKey(client, 'agent:text'));
|
||||
this.overflowedEgress.delete(this.egressKey(client, 'agent:thinking'));
|
||||
client.emit('agent:start', { conversationId });
|
||||
break;
|
||||
}
|
||||
|
||||
case 'agent_end': {
|
||||
// Gather usage stats from the Pi session
|
||||
const activeClientSession = this.clientSessions.get(client.id);
|
||||
const agentSession = activeClientSession
|
||||
? this.agentService.getSession(conversationId, activeClientSession.scope)
|
||||
: undefined;
|
||||
const agentSession = this.agentService.getSession(conversationId);
|
||||
const piSession = agentSession?.piSession;
|
||||
const stats = piSession?.getSessionStats();
|
||||
const contextUsage = piSession?.getContextUsage();
|
||||
@@ -925,20 +569,6 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
}
|
||||
: undefined;
|
||||
|
||||
this.flushRedactedEgress(
|
||||
client,
|
||||
conversationId,
|
||||
'agent:text',
|
||||
this.textEgressBuffers,
|
||||
true,
|
||||
);
|
||||
this.flushRedactedEgress(
|
||||
client,
|
||||
conversationId,
|
||||
'agent:thinking',
|
||||
this.thinkingEgressBuffers,
|
||||
true,
|
||||
);
|
||||
client.emit('agent:end', {
|
||||
conversationId,
|
||||
usage: usagePayload,
|
||||
@@ -981,11 +611,8 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
{
|
||||
conversationId,
|
||||
role: 'assistant',
|
||||
content: redactSensitiveContent(cs.assistantText).content,
|
||||
metadata: {
|
||||
...metadata,
|
||||
classifications: redactSensitiveContent(cs.assistantText).classifications,
|
||||
},
|
||||
content: cs.assistantText,
|
||||
metadata,
|
||||
},
|
||||
userId,
|
||||
)
|
||||
@@ -1007,26 +634,20 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
|
||||
case 'message_update': {
|
||||
const assistantEvent = event.assistantMessageEvent;
|
||||
if (assistantEvent.type === 'text_delta') {
|
||||
// Keep raw stream material in memory only; persist and emit only redacted text.
|
||||
// Accumulate assistant text for persistence
|
||||
const cs = this.clientSessions.get(client.id);
|
||||
if (cs) {
|
||||
cs.assistantText += assistantEvent.delta;
|
||||
}
|
||||
this.appendAndFlushRedactedEgress(
|
||||
client,
|
||||
client.emit('agent:text', {
|
||||
conversationId,
|
||||
'agent:text',
|
||||
this.textEgressBuffers,
|
||||
assistantEvent.delta,
|
||||
);
|
||||
text: assistantEvent.delta,
|
||||
});
|
||||
} else if (assistantEvent.type === 'thinking_delta') {
|
||||
this.appendAndFlushRedactedEgress(
|
||||
client,
|
||||
client.emit('agent:thinking', {
|
||||
conversationId,
|
||||
'agent:thinking',
|
||||
this.thinkingEgressBuffers,
|
||||
assistantEvent.delta,
|
||||
);
|
||||
text: assistantEvent.delta,
|
||||
});
|
||||
}
|
||||
break;
|
||||
}
|
||||
|
||||
@@ -1,61 +0,0 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import type { CommandDef, SlashCommandPayload } from '@mosaicstack/types';
|
||||
import { CommandAuthorizationService } from './command-authorization.service.js';
|
||||
|
||||
const adminCommand: CommandDef = {
|
||||
name: 'gc',
|
||||
description: 'GC',
|
||||
aliases: [],
|
||||
scope: 'admin',
|
||||
execution: 'socket',
|
||||
available: true,
|
||||
};
|
||||
const payload: SlashCommandPayload = { command: 'gc', conversationId: 'conversation-1' };
|
||||
|
||||
function createService(role: string): CommandAuthorizationService {
|
||||
const entries = new Map<string, string>();
|
||||
const db = {
|
||||
select: () => ({ from: () => ({ where: () => ({ limit: async () => [{ role }] }) }) }),
|
||||
};
|
||||
const redis = {
|
||||
get: async (key: string) => entries.get(key) ?? null,
|
||||
set: async (key: string, value: string) => {
|
||||
entries.set(key, value);
|
||||
},
|
||||
del: async (key: string) => Number(entries.delete(key)),
|
||||
};
|
||||
return new CommandAuthorizationService(db as never, redis);
|
||||
}
|
||||
|
||||
describe('CommandAuthorizationService', () => {
|
||||
it('consumes one exact actor-bound approval once', async (): Promise<void> => {
|
||||
const service = createService('admin');
|
||||
const approval = await service.createApproval(adminCommand, payload, 'admin-1');
|
||||
expect(approval).not.toBeNull();
|
||||
expect(
|
||||
(await service.authorize(adminCommand, payload, 'admin-1', approval!.approvalId)).allowed,
|
||||
).toBe(true);
|
||||
expect(
|
||||
(await service.authorize(adminCommand, payload, 'admin-1', approval!.approvalId)).allowed,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it('rejects an approval when the structured action is mutated', async (): Promise<void> => {
|
||||
const service = createService('admin');
|
||||
const approval = await service.createApproval(adminCommand, payload, 'admin-1');
|
||||
const mutated = { ...payload, conversationId: 'other-conversation' };
|
||||
expect(approval).not.toBeNull();
|
||||
expect(
|
||||
(await service.authorize(adminCommand, mutated, 'admin-1', approval!.approvalId)).allowed,
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it('denies an admin command to a member before approval is considered', async (): Promise<void> => {
|
||||
const service = createService('member');
|
||||
const approval = await service.createApproval(adminCommand, payload, 'member-1');
|
||||
expect(approval).toBeNull();
|
||||
expect(
|
||||
(await service.authorize(adminCommand, payload, 'member-1', 'forged-approval-id')).allowed,
|
||||
).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -1,138 +0,0 @@
|
||||
import { createHash, randomUUID } from 'node:crypto';
|
||||
import { Inject, Injectable } from '@nestjs/common';
|
||||
import { eq, users as usersTable, type Db } from '@mosaicstack/db';
|
||||
import type { CommandDef, SlashCommandPayload } from '@mosaicstack/types';
|
||||
import { DB } from '../database/database.module.js';
|
||||
import { COMMANDS_REDIS } from './commands.tokens.js';
|
||||
|
||||
export type CommandRole = 'admin' | 'member' | 'viewer';
|
||||
|
||||
export interface CommandApproval {
|
||||
approvalId: string;
|
||||
actionDigest: string;
|
||||
actorId: string;
|
||||
command: string;
|
||||
expiresAt: string;
|
||||
}
|
||||
|
||||
export interface CommandAuthorizationResult {
|
||||
allowed: boolean;
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class CommandAuthorizationService {
|
||||
constructor(
|
||||
@Inject(DB) private readonly db: Db,
|
||||
@Inject(COMMANDS_REDIS)
|
||||
private readonly redis: {
|
||||
get(key: string): Promise<string | null>;
|
||||
set(key: string, value: string, ...args: string[]): Promise<unknown>;
|
||||
del(key: string): Promise<number>;
|
||||
},
|
||||
) {}
|
||||
|
||||
async authorize(
|
||||
command: CommandDef,
|
||||
payload: SlashCommandPayload,
|
||||
actorId: string,
|
||||
approvalId?: string,
|
||||
): Promise<CommandAuthorizationResult> {
|
||||
const role = await this.resolveRole(actorId);
|
||||
if (!role || !this.hasScope(role, command.scope)) {
|
||||
return { allowed: false, reason: 'not authorized for this command scope' };
|
||||
}
|
||||
if (command.scope !== 'admin') return { allowed: true };
|
||||
if (!approvalId) return { allowed: false, reason: 'durable approval is required' };
|
||||
const actionDigest = this.actionDigest(command.name, payload);
|
||||
const approved = await this.consumeApproval(approvalId, actorId, actionDigest);
|
||||
return approved
|
||||
? { allowed: true }
|
||||
: {
|
||||
allowed: false,
|
||||
reason: 'approval is invalid, expired, replayed, or does not match this action',
|
||||
};
|
||||
}
|
||||
|
||||
async createApproval(
|
||||
command: CommandDef,
|
||||
payload: SlashCommandPayload,
|
||||
actorId: string,
|
||||
): Promise<CommandApproval | null> {
|
||||
const role = await this.resolveRole(actorId);
|
||||
if (!role || command.scope !== 'admin' || !this.hasScope(role, command.scope)) return null;
|
||||
|
||||
const approvalId = randomUUID();
|
||||
const expiresAt = new Date(Date.now() + 5 * 60_000).toISOString();
|
||||
const approval: CommandApproval = {
|
||||
approvalId,
|
||||
actionDigest: this.actionDigest(command.name, payload),
|
||||
actorId,
|
||||
command: command.name,
|
||||
expiresAt,
|
||||
};
|
||||
await this.redis.set(this.key(approvalId), JSON.stringify(approval), 'EX', '300');
|
||||
return approval;
|
||||
}
|
||||
|
||||
private async resolveRole(actorId: string): Promise<CommandRole | null> {
|
||||
const [user] = await this.db
|
||||
.select({ role: usersTable.role })
|
||||
.from(usersTable)
|
||||
.where(eq(usersTable.id, actorId))
|
||||
.limit(1);
|
||||
const role = user?.role;
|
||||
return role === 'admin' || role === 'member' || role === 'viewer' ? role : null;
|
||||
}
|
||||
|
||||
private hasScope(role: CommandRole, scope: CommandDef['scope']): boolean {
|
||||
if (role === 'admin') return true;
|
||||
return role === 'member' && (scope === 'core' || scope === 'agent');
|
||||
}
|
||||
|
||||
private async consumeApproval(
|
||||
approvalId: string,
|
||||
actorId: string,
|
||||
actionDigest: string,
|
||||
): Promise<boolean> {
|
||||
const key = this.key(approvalId);
|
||||
const encoded = await this.redis.get(key);
|
||||
if (!encoded) return false;
|
||||
const parsed: unknown = JSON.parse(encoded);
|
||||
if (
|
||||
!this.isApproval(parsed) ||
|
||||
parsed.actorId !== actorId ||
|
||||
parsed.actionDigest !== actionDigest ||
|
||||
Date.parse(parsed.expiresAt) <= Date.now()
|
||||
)
|
||||
return false;
|
||||
return (await this.redis.del(key)) === 1;
|
||||
}
|
||||
|
||||
private actionDigest(command: string, payload: SlashCommandPayload): string {
|
||||
return createHash('sha256')
|
||||
.update(
|
||||
JSON.stringify({
|
||||
command,
|
||||
args: payload.args?.trim() ?? '',
|
||||
conversationId: payload.conversationId,
|
||||
}),
|
||||
)
|
||||
.digest('hex');
|
||||
}
|
||||
|
||||
private isApproval(value: unknown): value is CommandApproval {
|
||||
return (
|
||||
typeof value === 'object' &&
|
||||
value !== null &&
|
||||
'approvalId' in value &&
|
||||
'actionDigest' in value &&
|
||||
'actorId' in value &&
|
||||
'expiresAt' in value
|
||||
);
|
||||
}
|
||||
|
||||
private key(approvalId: string): string {
|
||||
return `tess:command-approval:${approvalId}`;
|
||||
}
|
||||
}
|
||||
@@ -89,7 +89,6 @@ function buildService(): CommandExecutorService {
|
||||
describe('CommandExecutorService — P8-012 commands', () => {
|
||||
let service: CommandExecutorService;
|
||||
const userId = 'user-123';
|
||||
const userScope = { userId, tenantId: userId };
|
||||
const conversationId = 'conv-456';
|
||||
|
||||
beforeEach(() => {
|
||||
@@ -100,26 +99,31 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
// /provider login — missing provider name
|
||||
it('/provider login with no provider name returns usage error', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'provider', args: 'login', conversationId };
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.message).toContain('Usage: /provider login');
|
||||
expect(result.command).toBe('provider');
|
||||
});
|
||||
|
||||
// /provider login anthropic — no bearer token or auth URL reaches chat output
|
||||
it('/provider login <name> keeps its one-time token out of chat output', async () => {
|
||||
// /provider login anthropic — success with URL containing poll token
|
||||
it('/provider login <name> returns success with URL and poll token', async () => {
|
||||
const payload: SlashCommandPayload = {
|
||||
command: 'provider',
|
||||
args: 'login anthropic',
|
||||
conversationId,
|
||||
};
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.command).toBe('provider');
|
||||
expect(result.message).toContain('anthropic');
|
||||
expect(result.message).not.toContain('http');
|
||||
expect(result.message).not.toContain('token=');
|
||||
expect(result.data).toEqual({ provider: 'anthropic' });
|
||||
expect(result.message).toContain('http');
|
||||
// data should contain loginUrl and pollToken
|
||||
expect(result.data).toBeDefined();
|
||||
const data = result.data as Record<string, unknown>;
|
||||
expect(typeof data['loginUrl']).toBe('string');
|
||||
expect(typeof data['pollToken']).toBe('string');
|
||||
expect(data['loginUrl'] as string).toContain('anthropic');
|
||||
expect(data['loginUrl'] as string).toContain(data['pollToken'] as string);
|
||||
// Verify Valkey was called
|
||||
expect(mockRedis.set).toHaveBeenCalledOnce();
|
||||
const [key, value, , ttl] = mockRedis.set.mock.calls[0] as [string, string, string, number];
|
||||
@@ -134,7 +138,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
// /provider with no args — returns usage
|
||||
it('/provider with no args returns usage message', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'provider', conversationId };
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.message).toContain('Usage: /provider');
|
||||
});
|
||||
@@ -142,7 +146,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
// /provider list
|
||||
it('/provider list returns success', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'provider', args: 'list', conversationId };
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.command).toBe('provider');
|
||||
});
|
||||
@@ -150,7 +154,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
// /provider logout with no name — usage error
|
||||
it('/provider logout with no name returns error', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'provider', args: 'logout', conversationId };
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.message).toContain('Usage: /provider logout');
|
||||
});
|
||||
@@ -162,7 +166,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
args: 'unknown',
|
||||
conversationId,
|
||||
};
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.message).toContain('Unknown subcommand');
|
||||
});
|
||||
@@ -170,7 +174,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
// /mission status
|
||||
it('/mission status returns stub message', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'mission', args: 'status', conversationId };
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.command).toBe('mission');
|
||||
expect(result.message).toContain('Mission status');
|
||||
@@ -179,7 +183,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
// /mission with no args
|
||||
it('/mission with no args returns status stub', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'mission', conversationId };
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.message).toContain('Mission status');
|
||||
});
|
||||
@@ -191,7 +195,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
args: 'set my-mission-123',
|
||||
conversationId,
|
||||
};
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.message).toContain('my-mission-123');
|
||||
});
|
||||
@@ -199,7 +203,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
// /agent list
|
||||
it('/agent list returns stub message', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'agent', args: 'list', conversationId };
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.command).toBe('agent');
|
||||
expect(result.message).toContain('agent');
|
||||
@@ -208,7 +212,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
// /agent with no args
|
||||
it('/agent with no args returns usage', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'agent', conversationId };
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.message).toContain('Usage: /agent');
|
||||
});
|
||||
@@ -220,7 +224,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
args: 'my-agent-id',
|
||||
conversationId,
|
||||
};
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.message).toContain('my-agent-id');
|
||||
});
|
||||
@@ -228,7 +232,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
// /prdy
|
||||
it('/prdy returns PRD wizard message', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'prdy', conversationId };
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.command).toBe('prdy');
|
||||
expect(result.message).toContain('mosaic prdy');
|
||||
@@ -237,7 +241,7 @@ describe('CommandExecutorService — P8-012 commands', () => {
|
||||
// /tools
|
||||
it('/tools returns tools stub message', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'tools', conversationId };
|
||||
const result = await service.execute(payload, userScope);
|
||||
const result = await service.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.command).toBe('tools');
|
||||
expect(result.message).toContain('tools');
|
||||
|
||||
@@ -1,109 +0,0 @@
|
||||
import { beforeEach, describe, expect, it, vi } from 'vitest';
|
||||
import type { SlashCommandPayload } from '@mosaicstack/types';
|
||||
import { CommandAuthorizationService } from './command-authorization.service.js';
|
||||
import { CommandExecutorService } from './command-executor.service.js';
|
||||
|
||||
const registry = {
|
||||
getManifest: vi.fn(() => ({
|
||||
version: 1,
|
||||
commands: [
|
||||
{
|
||||
name: 'gc',
|
||||
description: 'System-wide garbage collection',
|
||||
aliases: [],
|
||||
scope: 'admin' as const,
|
||||
execution: 'socket' as const,
|
||||
available: true,
|
||||
},
|
||||
],
|
||||
skills: [],
|
||||
})),
|
||||
};
|
||||
|
||||
const sessionGc = {
|
||||
sweepOrphans: vi.fn().mockResolvedValue({ orphanedSessions: 1, totalCleaned: [], duration: 1 }),
|
||||
};
|
||||
|
||||
const scope = (userId: string) => ({ userId, tenantId: 'tenant-1' });
|
||||
|
||||
const authorization = {
|
||||
authorize: vi.fn((_command: unknown, _payload: unknown, actorId: string) =>
|
||||
Promise.resolve(
|
||||
actorId === 'member-1'
|
||||
? { allowed: false, reason: 'durable approval is required' }
|
||||
: { allowed: false, reason: 'not authorized for this command scope' },
|
||||
),
|
||||
),
|
||||
};
|
||||
|
||||
function buildExecutor(authorizationService: unknown = authorization): CommandExecutorService {
|
||||
return new CommandExecutorService(
|
||||
registry as never,
|
||||
{ getSession: vi.fn() } as never,
|
||||
{ clear: vi.fn(), set: vi.fn() } as never,
|
||||
sessionGc as never,
|
||||
{ set: vi.fn() } as never,
|
||||
{ agents: {} } as never,
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
authorizationService as never,
|
||||
);
|
||||
}
|
||||
|
||||
function createDurableAuthorization(): CommandAuthorizationService {
|
||||
const entries = new Map<string, string>();
|
||||
const db = {
|
||||
select: () => ({ from: () => ({ where: () => ({ limit: async () => [{ role: 'admin' }] }) }) }),
|
||||
};
|
||||
const redis = {
|
||||
get: async (key: string) => entries.get(key) ?? null,
|
||||
set: async (key: string, value: string) => {
|
||||
entries.set(key, value);
|
||||
},
|
||||
del: async (key: string) => Number(entries.delete(key)),
|
||||
};
|
||||
return new CommandAuthorizationService(db as never, redis);
|
||||
}
|
||||
|
||||
describe('TESS-M1-SEC-001 command authorization abuse cases', () => {
|
||||
const payload: SlashCommandPayload = { command: 'gc', conversationId: 'conversation-1' };
|
||||
|
||||
beforeEach((): void => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it('denies a forged admin identity and does not execute a system-wide command', async (): Promise<void> => {
|
||||
const result = await buildExecutor().execute(payload, scope('admin-forged-by-client'));
|
||||
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.message).toContain('not authorized');
|
||||
expect(sessionGc.sweepOrphans).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('denies a privileged command without a server-bound durable approval', async (): Promise<void> => {
|
||||
const result = await buildExecutor().execute(payload, scope('member-1'));
|
||||
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.message).toContain('approval');
|
||||
expect(sessionGc.sweepOrphans).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('executes an admin command only after a valid durable approval is issued and supplied', async (): Promise<void> => {
|
||||
const executor = buildExecutor(createDurableAuthorization());
|
||||
|
||||
const adminScope = scope('admin-1');
|
||||
const denied = await executor.execute(payload, adminScope);
|
||||
const approval = await executor.createApproval(payload, adminScope);
|
||||
const approved = await executor.execute(
|
||||
{ ...payload, approvalId: approval?.approvalId },
|
||||
adminScope,
|
||||
);
|
||||
|
||||
expect(denied.success).toBe(false);
|
||||
expect(denied.message).toContain('approval');
|
||||
expect(approval).not.toBeNull();
|
||||
expect(approved.success).toBe(true);
|
||||
expect(sessionGc.sweepOrphans).toHaveBeenCalledOnce();
|
||||
});
|
||||
});
|
||||
@@ -3,7 +3,6 @@ import type { QueueHandle } from '@mosaicstack/queue';
|
||||
import type { Brain } from '@mosaicstack/brain';
|
||||
import type { SlashCommandPayload, SlashCommandResultPayload } from '@mosaicstack/types';
|
||||
import { AgentService } from '../agent/agent.service.js';
|
||||
import type { ActorTenantScope } from '../auth/session-scope.js';
|
||||
import { ChatGateway } from '../chat/chat.gateway.js';
|
||||
import { SessionGCService } from '../gc/session-gc.service.js';
|
||||
import { SystemOverrideService } from '../preferences/system-override.service.js';
|
||||
@@ -11,7 +10,6 @@ import { ReloadService } from '../reload/reload.service.js';
|
||||
import { McpClientService } from '../mcp-client/mcp-client.service.js';
|
||||
import { BRAIN } from '../brain/brain.tokens.js';
|
||||
import { COMMANDS_REDIS } from './commands.tokens.js';
|
||||
import { CommandAuthorizationService } from './command-authorization.service.js';
|
||||
import { CommandRegistryService } from './command-registry.service.js';
|
||||
|
||||
@Injectable()
|
||||
@@ -34,17 +32,10 @@ export class CommandExecutorService {
|
||||
@Optional()
|
||||
@Inject(McpClientService)
|
||||
private readonly mcpClient: McpClientService | null,
|
||||
@Optional()
|
||||
@Inject(CommandAuthorizationService)
|
||||
private readonly authorization: CommandAuthorizationService | null = null,
|
||||
) {}
|
||||
|
||||
async execute(
|
||||
payload: SlashCommandPayload,
|
||||
scope: ActorTenantScope,
|
||||
): Promise<SlashCommandResultPayload> {
|
||||
async execute(payload: SlashCommandPayload, userId: string): Promise<SlashCommandResultPayload> {
|
||||
const { command, args, conversationId } = payload;
|
||||
const userId = scope.userId;
|
||||
|
||||
const def = this.registry.getManifest().commands.find((c) => c.name === command);
|
||||
if (!def) {
|
||||
@@ -56,24 +47,14 @@ export class CommandExecutorService {
|
||||
};
|
||||
}
|
||||
|
||||
const authorization = await this.authorization?.authorize(
|
||||
def,
|
||||
payload,
|
||||
userId,
|
||||
payload.approvalId,
|
||||
);
|
||||
if (authorization && !authorization.allowed) {
|
||||
return { command, conversationId, success: false, message: authorization.reason };
|
||||
}
|
||||
|
||||
try {
|
||||
switch (command) {
|
||||
case 'model':
|
||||
return await this.handleModel(args ?? null, conversationId, scope);
|
||||
return await this.handleModel(args ?? null, conversationId);
|
||||
case 'thinking':
|
||||
return await this.handleThinking(args ?? null, conversationId);
|
||||
case 'system':
|
||||
return await this.handleSystem(args ?? null, conversationId, scope);
|
||||
return await this.handleSystem(args ?? null, conversationId);
|
||||
case 'new':
|
||||
return {
|
||||
command,
|
||||
@@ -113,7 +94,7 @@ export class CommandExecutorService {
|
||||
};
|
||||
}
|
||||
case 'agent':
|
||||
return await this.handleAgent(args ?? null, conversationId, scope);
|
||||
return await this.handleAgent(args ?? null, conversationId, userId);
|
||||
case 'provider':
|
||||
return await this.handleProvider(args ?? null, userId, conversationId);
|
||||
case 'mission':
|
||||
@@ -162,22 +143,13 @@ export class CommandExecutorService {
|
||||
}
|
||||
}
|
||||
|
||||
async createApproval(payload: SlashCommandPayload, scope: ActorTenantScope) {
|
||||
const def = this.registry
|
||||
.getManifest()
|
||||
.commands.find((command) => command.name === payload.command);
|
||||
if (!def || !this.authorization) return null;
|
||||
return this.authorization.createApproval(def, payload, scope.userId);
|
||||
}
|
||||
|
||||
private async handleModel(
|
||||
args: string | null,
|
||||
conversationId: string,
|
||||
scope: ActorTenantScope,
|
||||
): Promise<SlashCommandResultPayload> {
|
||||
if (!args || args.trim().length === 0) {
|
||||
// Show current override or usage hint
|
||||
const currentOverride = this.chatGateway?.getModelOverride(conversationId, scope);
|
||||
const currentOverride = this.chatGateway?.getModelOverride(conversationId);
|
||||
if (currentOverride) {
|
||||
return {
|
||||
command: 'model',
|
||||
@@ -199,7 +171,7 @@ export class CommandExecutorService {
|
||||
|
||||
// /model clear removes the override and re-enables automatic routing
|
||||
if (modelName === 'clear') {
|
||||
this.chatGateway?.setModelOverride(conversationId, null, scope);
|
||||
this.chatGateway?.setModelOverride(conversationId, null);
|
||||
return {
|
||||
command: 'model',
|
||||
conversationId,
|
||||
@@ -209,9 +181,9 @@ export class CommandExecutorService {
|
||||
}
|
||||
|
||||
// Set the sticky per-session override (M4-007)
|
||||
this.chatGateway?.setModelOverride(conversationId, modelName, scope);
|
||||
this.chatGateway?.setModelOverride(conversationId, modelName);
|
||||
|
||||
const session = this.agentService.getSession(conversationId, scope);
|
||||
const session = this.agentService.getSession(conversationId);
|
||||
if (!session) {
|
||||
return {
|
||||
command: 'model',
|
||||
@@ -252,11 +224,10 @@ export class CommandExecutorService {
|
||||
private async handleSystem(
|
||||
args: string | null,
|
||||
conversationId: string,
|
||||
scope: ActorTenantScope,
|
||||
): Promise<SlashCommandResultPayload> {
|
||||
if (!args || args.trim().length === 0) {
|
||||
// Clear the override when called with no args
|
||||
await this.systemOverride.clear(conversationId, scope);
|
||||
await this.systemOverride.clear(conversationId);
|
||||
return {
|
||||
command: 'system',
|
||||
conversationId,
|
||||
@@ -265,7 +236,7 @@ export class CommandExecutorService {
|
||||
};
|
||||
}
|
||||
|
||||
await this.systemOverride.set(conversationId, args.trim(), scope);
|
||||
await this.systemOverride.set(conversationId, args.trim());
|
||||
return {
|
||||
command: 'system',
|
||||
conversationId,
|
||||
@@ -277,9 +248,8 @@ export class CommandExecutorService {
|
||||
private async handleAgent(
|
||||
args: string | null,
|
||||
conversationId: string,
|
||||
scope: ActorTenantScope,
|
||||
userId: string,
|
||||
): Promise<SlashCommandResultPayload> {
|
||||
const userId = scope.userId;
|
||||
if (!args) {
|
||||
return {
|
||||
command: 'agent',
|
||||
@@ -368,14 +338,11 @@ export class CommandExecutorService {
|
||||
conversationId,
|
||||
agentConfig.id,
|
||||
agentConfig.name,
|
||||
scope,
|
||||
agentConfig.model ?? undefined,
|
||||
);
|
||||
|
||||
// Broadcast updated session:info so TUI TopBar reflects new agent/model
|
||||
this.chatGateway?.broadcastSessionInfo(conversationId, scope, {
|
||||
agentName: agentConfig.name,
|
||||
});
|
||||
this.chatGateway?.broadcastSessionInfo(conversationId, { agentName: agentConfig.name });
|
||||
|
||||
this.logger.log(
|
||||
`Agent switched to "${agentConfig.name}" (${agentConfig.id}) for conversation ${conversationId} (M5-003)`,
|
||||
@@ -436,28 +403,22 @@ export class CommandExecutorService {
|
||||
};
|
||||
}
|
||||
const pollToken = crypto.randomUUID();
|
||||
const tokenDigest = await crypto.subtle.digest(
|
||||
'SHA-256',
|
||||
new TextEncoder().encode(pollToken),
|
||||
);
|
||||
const tokenHash = Array.from(new Uint8Array(tokenDigest), (byte: number): string =>
|
||||
byte.toString(16).padStart(2, '0'),
|
||||
).join('');
|
||||
const key = `mosaic:auth:poll:${tokenHash}`;
|
||||
// Persist only a short-lived token digest. The raw token is delivered only by
|
||||
// the authenticated dashboard flow, never in chat output or command metadata.
|
||||
const key = `mosaic:auth:poll:${pollToken}`;
|
||||
// Store pending state in Valkey (TTL 5 minutes)
|
||||
await this.redis.set(
|
||||
key,
|
||||
JSON.stringify({ status: 'pending', provider: providerName, userId }),
|
||||
'EX',
|
||||
300,
|
||||
);
|
||||
// In production this would construct an OAuth URL
|
||||
const loginUrl = `${process.env['MOSAIC_BASE_URL'] ?? 'http://localhost:3000'}/auth/provider/${providerName}?token=${pollToken}`;
|
||||
return {
|
||||
command: 'provider',
|
||||
success: true,
|
||||
message: `Provider login for ${providerName} is ready. Continue in the authenticated dashboard.`,
|
||||
message: `Open this URL to authenticate with ${providerName}:\n${loginUrl}`,
|
||||
conversationId,
|
||||
data: { provider: providerName },
|
||||
data: { loginUrl, pollToken, provider: providerName },
|
||||
};
|
||||
}
|
||||
|
||||
|
||||
@@ -159,7 +159,6 @@ describe('CommandExecutorService — integration', () => {
|
||||
let registry: CommandRegistryService;
|
||||
let executor: CommandExecutorService;
|
||||
const userId = 'user-integ-001';
|
||||
const userScope = { userId, tenantId: userId };
|
||||
const conversationId = 'conv-integ-001';
|
||||
|
||||
beforeEach(() => {
|
||||
@@ -171,7 +170,7 @@ describe('CommandExecutorService — integration', () => {
|
||||
// Unknown command returns error
|
||||
it('unknown command returns success:false with descriptive message', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'nonexistent', conversationId };
|
||||
const result = await executor.execute(payload, userScope);
|
||||
const result = await executor.execute(payload, userId);
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.message).toContain('nonexistent');
|
||||
expect(result.command).toBe('nonexistent');
|
||||
@@ -180,7 +179,7 @@ describe('CommandExecutorService — integration', () => {
|
||||
// /gc handler calls SessionGCService.sweepOrphans (admin-only, no userId arg)
|
||||
it('/gc calls SessionGCService.sweepOrphans without arguments', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'gc', conversationId };
|
||||
const result = await executor.execute(payload, userScope);
|
||||
const result = await executor.execute(payload, userId);
|
||||
expect(mockSessionGC.sweepOrphans).toHaveBeenCalledWith();
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.message).toContain('GC sweep complete');
|
||||
@@ -191,8 +190,8 @@ describe('CommandExecutorService — integration', () => {
|
||||
it('/system with text calls SystemOverrideService.set', async () => {
|
||||
const override = 'You are a helpful assistant.';
|
||||
const payload: SlashCommandPayload = { command: 'system', args: override, conversationId };
|
||||
const result = await executor.execute(payload, userScope);
|
||||
expect(mockSystemOverride.set).toHaveBeenCalledWith(conversationId, override, userScope);
|
||||
const result = await executor.execute(payload, userId);
|
||||
expect(mockSystemOverride.set).toHaveBeenCalledWith(conversationId, override);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.message).toContain('override set');
|
||||
});
|
||||
@@ -200,8 +199,8 @@ describe('CommandExecutorService — integration', () => {
|
||||
// /system with no args clears the override
|
||||
it('/system with no args calls SystemOverrideService.clear', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'system', conversationId };
|
||||
const result = await executor.execute(payload, userScope);
|
||||
expect(mockSystemOverride.clear).toHaveBeenCalledWith(conversationId, userScope);
|
||||
const result = await executor.execute(payload, userId);
|
||||
expect(mockSystemOverride.clear).toHaveBeenCalledWith(conversationId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.message).toContain('cleared');
|
||||
});
|
||||
@@ -213,7 +212,7 @@ describe('CommandExecutorService — integration', () => {
|
||||
args: 'claude-3-opus',
|
||||
conversationId,
|
||||
};
|
||||
const result = await executor.execute(payload, userScope);
|
||||
const result = await executor.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.command).toBe('model');
|
||||
expect(result.message).toContain('claude-3-opus');
|
||||
@@ -222,7 +221,7 @@ describe('CommandExecutorService — integration', () => {
|
||||
// /thinking with valid level returns success
|
||||
it('/thinking with valid level returns success', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'thinking', args: 'high', conversationId };
|
||||
const result = await executor.execute(payload, userScope);
|
||||
const result = await executor.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.message).toContain('high');
|
||||
});
|
||||
@@ -230,7 +229,7 @@ describe('CommandExecutorService — integration', () => {
|
||||
// /thinking with invalid level returns usage message
|
||||
it('/thinking with invalid level returns usage message', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'thinking', args: 'invalid', conversationId };
|
||||
const result = await executor.execute(payload, userScope);
|
||||
const result = await executor.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.message).toContain('Usage:');
|
||||
});
|
||||
@@ -238,7 +237,7 @@ describe('CommandExecutorService — integration', () => {
|
||||
// /new command returns success
|
||||
it('/new returns success', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'new', conversationId };
|
||||
const result = await executor.execute(payload, userScope);
|
||||
const result = await executor.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.command).toBe('new');
|
||||
});
|
||||
@@ -246,7 +245,7 @@ describe('CommandExecutorService — integration', () => {
|
||||
// /reload without reloadService returns failure
|
||||
it('/reload without ReloadService returns failure', async () => {
|
||||
const payload: SlashCommandPayload = { command: 'reload', conversationId };
|
||||
const result = await executor.execute(payload, userScope);
|
||||
const result = await executor.execute(payload, userId);
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.message).toContain('ReloadService');
|
||||
});
|
||||
@@ -256,7 +255,7 @@ describe('CommandExecutorService — integration', () => {
|
||||
for (const cmd of stubCommands) {
|
||||
it(`/${cmd} returns success (stub)`, async () => {
|
||||
const payload: SlashCommandPayload = { command: cmd, conversationId };
|
||||
const result = await executor.execute(payload, userScope);
|
||||
const result = await executor.execute(payload, userId);
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.command).toBe(cmd);
|
||||
});
|
||||
|
||||
@@ -3,7 +3,6 @@ import { createQueue, type QueueHandle } from '@mosaicstack/queue';
|
||||
import { ChatModule } from '../chat/chat.module.js';
|
||||
import { GCModule } from '../gc/gc.module.js';
|
||||
import { ReloadModule } from '../reload/reload.module.js';
|
||||
import { CommandAuthorizationService } from './command-authorization.service.js';
|
||||
import { CommandExecutorService } from './command-executor.service.js';
|
||||
import { CommandRegistryService } from './command-registry.service.js';
|
||||
import { COMMANDS_REDIS } from './commands.tokens.js';
|
||||
@@ -25,7 +24,6 @@ const COMMANDS_QUEUE_HANDLE = 'COMMANDS_QUEUE_HANDLE';
|
||||
inject: [COMMANDS_QUEUE_HANDLE],
|
||||
},
|
||||
CommandRegistryService,
|
||||
CommandAuthorizationService,
|
||||
CommandExecutorService,
|
||||
],
|
||||
exports: [CommandRegistryService, CommandExecutorService],
|
||||
|
||||
@@ -1,255 +0,0 @@
|
||||
import 'reflect-metadata';
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import type { Db } from '@mosaicstack/db';
|
||||
import type { FederationListResponse } from '@mosaicstack/types';
|
||||
import {
|
||||
FederationClientError,
|
||||
type FederationClientService,
|
||||
} from '../federation-client.service.js';
|
||||
import { type QuerySourceError, QuerySourceService } from '../query-source.service.js';
|
||||
|
||||
interface TestRow {
|
||||
id: string;
|
||||
title: string;
|
||||
}
|
||||
|
||||
interface PeerRow {
|
||||
id: string;
|
||||
commonName: string;
|
||||
endpointUrl: string | null;
|
||||
clientKeyPem: string | null;
|
||||
state: 'active' | 'pending' | 'suspended' | 'revoked';
|
||||
}
|
||||
|
||||
const LOCAL_ROWS: TestRow[] = [
|
||||
{ id: 'local-1', title: 'Local One' },
|
||||
{ id: 'local-2', title: 'Local Two' },
|
||||
];
|
||||
|
||||
const PEER_A: PeerRow = {
|
||||
id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
|
||||
commonName: 'peer-a',
|
||||
endpointUrl: 'https://peer-a.example.com',
|
||||
clientKeyPem: 'sealed-key-a',
|
||||
state: 'active',
|
||||
};
|
||||
|
||||
const PEER_B: PeerRow = {
|
||||
id: 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
|
||||
commonName: 'peer-b',
|
||||
endpointUrl: 'https://peer-b.example.com',
|
||||
clientKeyPem: 'sealed-key-b',
|
||||
state: 'active',
|
||||
};
|
||||
|
||||
const PEER_LOCALHOST: PeerRow = {
|
||||
id: 'cccccccc-cccc-cccc-cccc-cccccccccccc',
|
||||
commonName: 'peer-localhost',
|
||||
endpointUrl: 'https://localhost:3001',
|
||||
clientKeyPem: 'sealed-key-c',
|
||||
state: 'active',
|
||||
};
|
||||
|
||||
function makeDb(activePeers: PeerRow[]): Db {
|
||||
const orderBy = vi.fn().mockResolvedValue(activePeers);
|
||||
const where = vi.fn().mockReturnValue({ orderBy });
|
||||
const from = vi.fn().mockReturnValue({ where });
|
||||
const select = vi.fn().mockReturnValue({ from });
|
||||
|
||||
return {
|
||||
select,
|
||||
insert: vi.fn(),
|
||||
update: vi.fn(),
|
||||
delete: vi.fn(),
|
||||
transaction: vi.fn(),
|
||||
} as unknown as Db;
|
||||
}
|
||||
|
||||
function makeFederationClient(
|
||||
list: (
|
||||
peerId: string,
|
||||
resource: string,
|
||||
request: Record<string, unknown>,
|
||||
) => Promise<FederationListResponse<TestRow>>,
|
||||
): FederationClientService {
|
||||
return {
|
||||
list: list as unknown as FederationClientService['list'],
|
||||
} as FederationClientService;
|
||||
}
|
||||
|
||||
function makeLocalResponse(rows: TestRow[] = LOCAL_ROWS): Promise<FederationListResponse<TestRow>> {
|
||||
return Promise.resolve({ items: rows });
|
||||
}
|
||||
|
||||
describe('QuerySourceService', () => {
|
||||
it('routes source="local" to the local executor and tags rows as local', async () => {
|
||||
const list = vi.fn(async (): Promise<FederationListResponse<TestRow>> => ({ items: [] }));
|
||||
const service = new QuerySourceService(makeDb([PEER_A]), makeFederationClient(list));
|
||||
|
||||
const result = await service.list<TestRow>({
|
||||
source: 'local',
|
||||
resource: 'tasks',
|
||||
request: { cursor: 'ignored-for-local-test' },
|
||||
local: () => makeLocalResponse(),
|
||||
});
|
||||
|
||||
expect(result).toEqual({
|
||||
items: [
|
||||
{ id: 'local-1', title: 'Local One', _source: 'local' },
|
||||
{ id: 'local-2', title: 'Local Two', _source: 'local' },
|
||||
],
|
||||
});
|
||||
expect(list).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('routes source="federated:<host>" to the matching active peer and tags rows with peer commonName', async () => {
|
||||
const list = vi.fn(
|
||||
async (): Promise<FederationListResponse<TestRow>> => ({
|
||||
items: [{ id: 'remote-1', title: 'Remote One' }],
|
||||
}),
|
||||
);
|
||||
const service = new QuerySourceService(makeDb([PEER_A, PEER_B]), makeFederationClient(list));
|
||||
|
||||
const result = await service.list<TestRow>({
|
||||
source: 'federated:peer-b.example.com',
|
||||
resource: 'tasks',
|
||||
request: { status: 'open' },
|
||||
local: () => makeLocalResponse(),
|
||||
});
|
||||
|
||||
expect(result).toEqual({
|
||||
items: [{ id: 'remote-1', title: 'Remote One', _source: 'peer-b' }],
|
||||
});
|
||||
expect(list).toHaveBeenCalledWith(PEER_B.id, 'tasks', { status: 'open' });
|
||||
});
|
||||
|
||||
it('matches federated hosts by endpoint host including non-default port', async () => {
|
||||
const list = vi.fn(
|
||||
async (): Promise<FederationListResponse<TestRow>> => ({
|
||||
items: [{ id: 'remote-port', title: 'Remote Port' }],
|
||||
}),
|
||||
);
|
||||
const service = new QuerySourceService(makeDb([PEER_LOCALHOST]), makeFederationClient(list));
|
||||
|
||||
const result = await service.list<TestRow>({
|
||||
source: 'federated:localhost:3001',
|
||||
resource: 'tasks',
|
||||
request: {},
|
||||
local: () => makeLocalResponse(),
|
||||
});
|
||||
|
||||
expect(result).toEqual({
|
||||
items: [{ id: 'remote-port', title: 'Remote Port', _source: 'peer-localhost' }],
|
||||
});
|
||||
expect(list).toHaveBeenCalledWith(PEER_LOCALHOST.id, 'tasks', {});
|
||||
});
|
||||
|
||||
it('fans out source="all" to local plus every active outbound peer in parallel and merges tagged rows', async () => {
|
||||
const callOrder: string[] = [];
|
||||
const list = vi.fn(async (peerId: string): Promise<FederationListResponse<TestRow>> => {
|
||||
callOrder.push(`remote-start:${peerId}`);
|
||||
await Promise.resolve();
|
||||
return {
|
||||
items: [{ id: `remote-${peerId.slice(0, 1)}`, title: `Remote ${peerId.slice(0, 1)}` }],
|
||||
};
|
||||
});
|
||||
const service = new QuerySourceService(makeDb([PEER_A, PEER_B]), makeFederationClient(list));
|
||||
|
||||
const result = await service.list<TestRow>({
|
||||
source: 'all',
|
||||
resource: 'tasks',
|
||||
request: { limit: 25 },
|
||||
local: async () => {
|
||||
callOrder.push('local-start');
|
||||
await Promise.resolve();
|
||||
return { items: [{ id: 'local-1', title: 'Local One' }] };
|
||||
},
|
||||
});
|
||||
|
||||
expect(result).toEqual({
|
||||
items: [
|
||||
{ id: 'local-1', title: 'Local One', _source: 'local' },
|
||||
{ id: 'remote-a', title: 'Remote a', _source: 'peer-a' },
|
||||
{ id: 'remote-b', title: 'Remote b', _source: 'peer-b' },
|
||||
],
|
||||
});
|
||||
expect(list).toHaveBeenCalledTimes(2);
|
||||
expect(callOrder).toEqual([
|
||||
'local-start',
|
||||
`remote-start:${PEER_A.id}`,
|
||||
`remote-start:${PEER_B.id}`,
|
||||
]);
|
||||
});
|
||||
|
||||
it('marks source="all" as partial and truncated when any subquery returns a cursor', async () => {
|
||||
const list = vi.fn(
|
||||
async (): Promise<FederationListResponse<TestRow>> => ({
|
||||
items: [{ id: 'remote-a', title: 'Remote A' }],
|
||||
nextCursor: 'remote-next',
|
||||
}),
|
||||
);
|
||||
const service = new QuerySourceService(makeDb([PEER_A]), makeFederationClient(list));
|
||||
|
||||
const result = await service.list<TestRow>({
|
||||
source: 'all',
|
||||
resource: 'tasks',
|
||||
request: {},
|
||||
local: () => makeLocalResponse([{ id: 'local-1', title: 'Local One' }]),
|
||||
});
|
||||
|
||||
expect(result).toEqual({
|
||||
items: [
|
||||
{ id: 'local-1', title: 'Local One', _source: 'local' },
|
||||
{ id: 'remote-a', title: 'Remote A', _source: 'peer-a' },
|
||||
],
|
||||
_partial: true,
|
||||
_truncated: true,
|
||||
});
|
||||
});
|
||||
|
||||
it('returns _partial=true for source="all" when one peer fails without dropping successful sources', async () => {
|
||||
const list = vi.fn(async (peerId: string): Promise<FederationListResponse<TestRow>> => {
|
||||
if (peerId === PEER_B.id) {
|
||||
throw new FederationClientError({
|
||||
code: 'NETWORK',
|
||||
message: 'peer unavailable',
|
||||
peerId,
|
||||
});
|
||||
}
|
||||
return { items: [{ id: 'remote-a', title: 'Remote A' }] };
|
||||
});
|
||||
const service = new QuerySourceService(makeDb([PEER_A, PEER_B]), makeFederationClient(list));
|
||||
|
||||
const result = await service.list<TestRow>({
|
||||
source: 'all',
|
||||
resource: 'tasks',
|
||||
request: {},
|
||||
local: () => makeLocalResponse([{ id: 'local-1', title: 'Local One' }]),
|
||||
});
|
||||
|
||||
expect(result).toEqual({
|
||||
items: [
|
||||
{ id: 'local-1', title: 'Local One', _source: 'local' },
|
||||
{ id: 'remote-a', title: 'Remote A', _source: 'peer-a' },
|
||||
],
|
||||
_partial: true,
|
||||
});
|
||||
});
|
||||
|
||||
it('throws QuerySourceError when a federated host does not match an active outbound peer', async () => {
|
||||
const list = vi.fn(async (): Promise<FederationListResponse<TestRow>> => ({ items: [] }));
|
||||
const service = new QuerySourceService(makeDb([PEER_A]), makeFederationClient(list));
|
||||
|
||||
await expect(
|
||||
service.list<TestRow>({
|
||||
source: 'federated:missing.example.com',
|
||||
resource: 'tasks',
|
||||
request: {},
|
||||
local: () => makeLocalResponse(),
|
||||
}),
|
||||
).rejects.toMatchObject({
|
||||
name: 'QuerySourceError',
|
||||
code: 'PEER_NOT_FOUND',
|
||||
} satisfies Partial<QuerySourceError>);
|
||||
});
|
||||
});
|
||||
@@ -11,13 +11,3 @@ export {
|
||||
type FederationClientErrorCode,
|
||||
type FederationClientErrorOptions,
|
||||
} from './federation-client.service.js';
|
||||
export {
|
||||
QuerySourceService,
|
||||
QuerySourceError,
|
||||
type QuerySource,
|
||||
type QuerySourceErrorCode,
|
||||
type QuerySourceErrorOptions,
|
||||
type QuerySourceListOptions,
|
||||
type QuerySourceListResponse,
|
||||
type LocalListExecutor,
|
||||
} from './query-source.service.js';
|
||||
|
||||
@@ -1,261 +0,0 @@
|
||||
/**
|
||||
* QuerySourceService — gateway query source router (FED-M3-09).
|
||||
*
|
||||
* Accepts the federation query-layer `source` selector and routes list-style
|
||||
* reads to local storage, one federated peer, or all active outbound peers.
|
||||
*
|
||||
* `source: "all"` is intentionally tolerant of per-peer failures: local data
|
||||
* and successful peer responses are returned, and the envelope is marked
|
||||
* `_partial: true`. Local failures still reject because there is no safe local
|
||||
* fallback and the gateway's own storage is expected to be authoritative.
|
||||
*/
|
||||
|
||||
import { Inject, Injectable, Logger } from '@nestjs/common';
|
||||
import { and, eq, federationPeers, isNotNull, type Db } from '@mosaicstack/db';
|
||||
import {
|
||||
SOURCE_LOCAL,
|
||||
tagWithSource,
|
||||
type FederationListResponse,
|
||||
type SourceTag,
|
||||
} from '@mosaicstack/types';
|
||||
import { DB } from '../../database/database.module.js';
|
||||
import { FederationClientService } from './federation-client.service.js';
|
||||
|
||||
export type QuerySource = 'local' | 'all' | `federated:${string}`;
|
||||
|
||||
export type QuerySourceErrorCode = 'INVALID_SOURCE' | 'PEER_NOT_FOUND';
|
||||
|
||||
export interface QuerySourceErrorOptions {
|
||||
code: QuerySourceErrorCode;
|
||||
message: string;
|
||||
source: string;
|
||||
}
|
||||
|
||||
export class QuerySourceError extends Error {
|
||||
readonly code: QuerySourceErrorCode;
|
||||
readonly source: string;
|
||||
|
||||
constructor(opts: QuerySourceErrorOptions) {
|
||||
super(opts.message);
|
||||
this.name = 'QuerySourceError';
|
||||
this.code = opts.code;
|
||||
this.source = opts.source;
|
||||
}
|
||||
}
|
||||
|
||||
export type LocalListExecutor<T extends object> = () => Promise<FederationListResponse<T> | T[]>;
|
||||
|
||||
export interface QuerySourceListOptions<T extends object> {
|
||||
source: QuerySource;
|
||||
resource: string;
|
||||
request?: Record<string, unknown>;
|
||||
local: LocalListExecutor<T>;
|
||||
}
|
||||
|
||||
export type QuerySourceListResponse<T extends object> = FederationListResponse<T & SourceTag>;
|
||||
|
||||
interface OutboundPeer {
|
||||
id: string;
|
||||
commonName: string;
|
||||
endpointUrl: string;
|
||||
}
|
||||
|
||||
interface TaggedList<T extends object> {
|
||||
items: Array<T & SourceTag>;
|
||||
partial: boolean;
|
||||
truncated: boolean;
|
||||
nextCursor?: string;
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class QuerySourceService {
|
||||
private readonly logger = new Logger(QuerySourceService.name);
|
||||
|
||||
constructor(
|
||||
@Inject(DB) private readonly db: Db,
|
||||
@Inject(FederationClientService) private readonly federationClient: FederationClientService,
|
||||
) {}
|
||||
|
||||
async list<T extends object>(
|
||||
options: QuerySourceListOptions<T>,
|
||||
): Promise<QuerySourceListResponse<T>> {
|
||||
const request = options.request ?? {};
|
||||
|
||||
if (options.source === 'local') {
|
||||
const local = await this.runLocal(options.local);
|
||||
return this.toResponse(this.tagList(local, SOURCE_LOCAL));
|
||||
}
|
||||
|
||||
if (options.source === 'all') {
|
||||
return this.listAll(options.resource, request, options.local);
|
||||
}
|
||||
|
||||
if (options.source.startsWith('federated:')) {
|
||||
const host = options.source.slice('federated:'.length).trim();
|
||||
if (!host) {
|
||||
throw new QuerySourceError({
|
||||
code: 'INVALID_SOURCE',
|
||||
message: 'Federated source must include a host after federated:',
|
||||
source: options.source,
|
||||
});
|
||||
}
|
||||
|
||||
const peer = await this.findPeerByHost(host, options.source);
|
||||
const remote = await this.federationClient.list<T>(peer.id, options.resource, request);
|
||||
return this.toResponse(this.tagList(remote, peer.commonName));
|
||||
}
|
||||
|
||||
throw new QuerySourceError({
|
||||
code: 'INVALID_SOURCE',
|
||||
message: `Unsupported query source: ${options.source}`,
|
||||
source: options.source,
|
||||
});
|
||||
}
|
||||
|
||||
private async listAll<T extends object>(
|
||||
resource: string,
|
||||
request: Record<string, unknown>,
|
||||
local: LocalListExecutor<T>,
|
||||
): Promise<QuerySourceListResponse<T>> {
|
||||
const peers = await this.listActiveOutboundPeers();
|
||||
|
||||
const localPromise = this.runLocal(local).then((response) =>
|
||||
this.tagList(response, SOURCE_LOCAL),
|
||||
);
|
||||
const remotePromises = peers.map(async (peer: OutboundPeer): Promise<TaggedList<T> | null> => {
|
||||
try {
|
||||
const response = await this.federationClient.list<T>(peer.id, resource, request);
|
||||
return this.tagList(response, peer.commonName);
|
||||
} catch (error: unknown) {
|
||||
this.logger.warn(
|
||||
`Federated query to peer ${peer.commonName} (${peer.id}) failed; returning partial all-source response: ${
|
||||
error instanceof Error ? error.message : String(error)
|
||||
}`,
|
||||
);
|
||||
return null;
|
||||
}
|
||||
});
|
||||
|
||||
const [localResult, ...remoteResults] = await Promise.all([localPromise, ...remotePromises]);
|
||||
const successfulRemoteResults = remoteResults.filter(
|
||||
(result: TaggedList<T> | null): result is TaggedList<T> => result !== null,
|
||||
);
|
||||
const allResults = [localResult, ...successfulRemoteResults];
|
||||
const peerFailure = successfulRemoteResults.length !== peers.length;
|
||||
|
||||
return this.mergeTaggedLists(allResults, peerFailure);
|
||||
}
|
||||
|
||||
private async runLocal<T extends object>(
|
||||
local: LocalListExecutor<T>,
|
||||
): Promise<FederationListResponse<T>> {
|
||||
const response = await local();
|
||||
if (Array.isArray(response)) {
|
||||
return { items: response };
|
||||
}
|
||||
return response;
|
||||
}
|
||||
|
||||
private tagList<T extends object>(
|
||||
response: FederationListResponse<T>,
|
||||
source: string,
|
||||
): TaggedList<T> {
|
||||
return {
|
||||
items: tagWithSource(response.items, source),
|
||||
partial: response._partial === true,
|
||||
truncated: response._truncated === true || response.nextCursor !== undefined,
|
||||
nextCursor: response.nextCursor,
|
||||
};
|
||||
}
|
||||
|
||||
private mergeTaggedLists<T extends object>(
|
||||
lists: Array<TaggedList<T>>,
|
||||
peerFailure: boolean,
|
||||
): QuerySourceListResponse<T> {
|
||||
const items = lists.flatMap((list: TaggedList<T>) => list.items);
|
||||
const partial =
|
||||
peerFailure ||
|
||||
lists.some((list: TaggedList<T>) => list.partial || list.nextCursor !== undefined);
|
||||
const truncated = lists.some((list: TaggedList<T>) => list.truncated);
|
||||
|
||||
const response: QuerySourceListResponse<T> = { items };
|
||||
if (partial) {
|
||||
response._partial = true;
|
||||
}
|
||||
if (truncated) {
|
||||
response._truncated = true;
|
||||
}
|
||||
return response;
|
||||
}
|
||||
|
||||
private toResponse<T extends object>(tagged: TaggedList<T>): QuerySourceListResponse<T> {
|
||||
const response: QuerySourceListResponse<T> = {
|
||||
items: tagged.items,
|
||||
};
|
||||
if (tagged.nextCursor !== undefined) {
|
||||
response.nextCursor = tagged.nextCursor;
|
||||
}
|
||||
if (tagged.partial) {
|
||||
response._partial = true;
|
||||
}
|
||||
if (tagged.truncated) {
|
||||
response._truncated = true;
|
||||
}
|
||||
return response;
|
||||
}
|
||||
|
||||
private async findPeerByHost(sourceHost: string, source: string): Promise<OutboundPeer> {
|
||||
const host = normalizeHost(sourceHost);
|
||||
const peers = await this.listActiveOutboundPeers();
|
||||
const peer = peers.find((candidate: OutboundPeer) => {
|
||||
const commonName = normalizeHost(candidate.commonName);
|
||||
const endpointHosts = endpointHostKeys(candidate.endpointUrl).map((endpointHost: string) =>
|
||||
normalizeHost(endpointHost),
|
||||
);
|
||||
return commonName === host || endpointHosts.includes(host);
|
||||
});
|
||||
|
||||
if (!peer) {
|
||||
throw new QuerySourceError({
|
||||
code: 'PEER_NOT_FOUND',
|
||||
message: `No active outbound federation peer matches source ${source}`,
|
||||
source,
|
||||
});
|
||||
}
|
||||
|
||||
return peer;
|
||||
}
|
||||
|
||||
private async listActiveOutboundPeers(): Promise<OutboundPeer[]> {
|
||||
const rows = await this.db
|
||||
.select({
|
||||
id: federationPeers.id,
|
||||
commonName: federationPeers.commonName,
|
||||
endpointUrl: federationPeers.endpointUrl,
|
||||
})
|
||||
.from(federationPeers)
|
||||
.where(
|
||||
and(
|
||||
eq(federationPeers.state, 'active'),
|
||||
isNotNull(federationPeers.endpointUrl),
|
||||
isNotNull(federationPeers.clientKeyPem),
|
||||
),
|
||||
)
|
||||
.orderBy(federationPeers.commonName);
|
||||
|
||||
return rows.filter((row): row is OutboundPeer => typeof row.endpointUrl === 'string');
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeHost(host: string): string {
|
||||
return host.trim().toLowerCase();
|
||||
}
|
||||
|
||||
function endpointHostKeys(endpointUrl: string): string[] {
|
||||
try {
|
||||
const url = new URL(endpointUrl);
|
||||
return Array.from(new Set([url.host, url.hostname].filter((host: string) => host.length > 0)));
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
@@ -4,35 +4,26 @@ import { CaService } from './ca.service.js';
|
||||
import { EnrollmentController } from './enrollment.controller.js';
|
||||
import { EnrollmentService } from './enrollment.service.js';
|
||||
import { FederationController } from './federation.controller.js';
|
||||
import { CapabilitiesController } from './server/verbs/capabilities.controller.js';
|
||||
import { GrantsService } from './grants.service.js';
|
||||
import { FederationClientService, QuerySourceService } from './client/index.js';
|
||||
import { FederationAuthGuard, FederationScopeService } from './server/index.js';
|
||||
import { ListController } from './server/verbs/list.controller.js';
|
||||
import { FederationListQueryService } from './server/verbs/list-query.service.js';
|
||||
import { FederationClientService } from './client/index.js';
|
||||
import { FederationAuthGuard } from './server/index.js';
|
||||
|
||||
@Module({
|
||||
controllers: [EnrollmentController, FederationController, CapabilitiesController, ListController],
|
||||
controllers: [EnrollmentController, FederationController],
|
||||
providers: [
|
||||
AdminGuard,
|
||||
CaService,
|
||||
EnrollmentService,
|
||||
GrantsService,
|
||||
FederationClientService,
|
||||
QuerySourceService,
|
||||
FederationAuthGuard,
|
||||
FederationScopeService,
|
||||
FederationListQueryService,
|
||||
],
|
||||
exports: [
|
||||
CaService,
|
||||
EnrollmentService,
|
||||
GrantsService,
|
||||
FederationClientService,
|
||||
QuerySourceService,
|
||||
FederationAuthGuard,
|
||||
FederationScopeService,
|
||||
FederationListQueryService,
|
||||
],
|
||||
})
|
||||
export class FederationModule {}
|
||||
|
||||
@@ -1,324 +0,0 @@
|
||||
/**
|
||||
* Unit tests for FederationScopeService (FED-M3-04).
|
||||
*
|
||||
* Coverage:
|
||||
* - resource allowlist deny
|
||||
* - excluded resource deny
|
||||
* - invalid scope deny
|
||||
* - invalid requested limit deny
|
||||
* - native RBAC deny as subjectUserId
|
||||
* - scope/native filter intersection for personal and team rows
|
||||
* - native RBAC personal deny wins over scope include_personal allow/default
|
||||
* - max_rows_per_query cap
|
||||
*/
|
||||
|
||||
import { beforeEach, describe, expect, it, vi } from 'vitest';
|
||||
import { FederationScopeService, type FederationNativeRbacEvaluator } from '../scope.service.js';
|
||||
import type { FederationContext } from '../federation-context.js';
|
||||
|
||||
const GRANT_ID = 'grant-1';
|
||||
const PEER_ID = 'peer-1';
|
||||
const SUBJECT_USER_ID = 'user-1';
|
||||
|
||||
function makeContext(scope: Record<string, unknown>): FederationContext {
|
||||
return {
|
||||
grantId: GRANT_ID,
|
||||
peerId: PEER_ID,
|
||||
subjectUserId: SUBJECT_USER_ID,
|
||||
scope,
|
||||
};
|
||||
}
|
||||
|
||||
function makeNativeRbac(
|
||||
result: Awaited<ReturnType<FederationNativeRbacEvaluator['evaluateReadAccess']>>,
|
||||
): FederationNativeRbacEvaluator {
|
||||
return {
|
||||
evaluateReadAccess: vi.fn().mockResolvedValue(result),
|
||||
};
|
||||
}
|
||||
|
||||
describe('FederationScopeService', () => {
|
||||
let service: FederationScopeService;
|
||||
|
||||
beforeEach(() => {
|
||||
service = new FederationScopeService();
|
||||
});
|
||||
|
||||
it('allows a granted resource and returns a capped query filter', async () => {
|
||||
const nativeRbac = makeNativeRbac({
|
||||
allowed: true,
|
||||
access: { includePersonal: true, teamIds: ['team-1', 'team-2'] },
|
||||
});
|
||||
|
||||
const result = await service.evaluateAccess({
|
||||
context: makeContext({
|
||||
resources: ['tasks'],
|
||||
filters: { tasks: { include_teams: ['team-1', 'team-3'], include_personal: true } },
|
||||
max_rows_per_query: 50,
|
||||
}),
|
||||
resource: 'tasks',
|
||||
requestedLimit: 500,
|
||||
nativeRbac,
|
||||
});
|
||||
|
||||
expect(result).toEqual({
|
||||
allowed: true,
|
||||
filter: {
|
||||
resource: 'tasks',
|
||||
subjectUserId: SUBJECT_USER_ID,
|
||||
includePersonal: true,
|
||||
teamIds: ['team-1'],
|
||||
limit: 50,
|
||||
maxRowsPerQuery: 50,
|
||||
},
|
||||
});
|
||||
expect(nativeRbac.evaluateReadAccess).toHaveBeenCalledWith({
|
||||
grantId: GRANT_ID,
|
||||
peerId: PEER_ID,
|
||||
subjectUserId: SUBJECT_USER_ID,
|
||||
resource: 'tasks',
|
||||
});
|
||||
});
|
||||
|
||||
it('defaults absent resource filters to native RBAC personal and team visibility', async () => {
|
||||
const result = await service.evaluateAccess({
|
||||
context: makeContext({ resources: ['notes'], max_rows_per_query: 100 }),
|
||||
resource: 'notes',
|
||||
nativeRbac: makeNativeRbac({
|
||||
allowed: true,
|
||||
access: { includePersonal: true, teamIds: ['team-1', 'team-2'] },
|
||||
}),
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
allowed: true,
|
||||
filter: {
|
||||
includePersonal: true,
|
||||
teamIds: ['team-1', 'team-2'],
|
||||
limit: 100,
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('honors include_personal false even when native RBAC allows personal rows', async () => {
|
||||
const result = await service.evaluateAccess({
|
||||
context: makeContext({
|
||||
resources: ['memory'],
|
||||
filters: { memory: { include_personal: false } },
|
||||
max_rows_per_query: 25,
|
||||
}),
|
||||
resource: 'memory',
|
||||
nativeRbac: makeNativeRbac({
|
||||
allowed: true,
|
||||
access: { includePersonal: true, teamIds: [] },
|
||||
}),
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
allowed: true,
|
||||
filter: {
|
||||
includePersonal: false,
|
||||
teamIds: [],
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('does not leak personal rows when scope allows personal but native RBAC denies personal', async () => {
|
||||
const result = await service.evaluateAccess({
|
||||
context: makeContext({
|
||||
resources: ['tasks'],
|
||||
filters: { tasks: { include_personal: true } },
|
||||
max_rows_per_query: 25,
|
||||
}),
|
||||
resource: 'tasks',
|
||||
nativeRbac: makeNativeRbac({
|
||||
allowed: true,
|
||||
access: { includePersonal: false, teamIds: ['team-1'] },
|
||||
}),
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
allowed: true,
|
||||
filter: {
|
||||
includePersonal: false,
|
||||
teamIds: ['team-1'],
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('does not widen native RBAC when scope includes teams the user cannot access', async () => {
|
||||
const result = await service.evaluateAccess({
|
||||
context: makeContext({
|
||||
resources: ['tasks'],
|
||||
filters: { tasks: { include_teams: ['team-2'], include_personal: false } },
|
||||
max_rows_per_query: 25,
|
||||
}),
|
||||
resource: 'tasks',
|
||||
nativeRbac: makeNativeRbac({
|
||||
allowed: true,
|
||||
access: { includePersonal: true, teamIds: ['team-1'] },
|
||||
}),
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
allowed: true,
|
||||
filter: {
|
||||
includePersonal: false,
|
||||
teamIds: [],
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('denies invalid grant scope before RBAC evaluation', async () => {
|
||||
const nativeRbac = makeNativeRbac({
|
||||
allowed: true,
|
||||
access: { includePersonal: true, teamIds: [] },
|
||||
});
|
||||
|
||||
const result = await service.evaluateAccess({
|
||||
context: makeContext({ resources: [], max_rows_per_query: 100 }),
|
||||
resource: 'tasks',
|
||||
nativeRbac,
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
allowed: false,
|
||||
deny: {
|
||||
code: 'invalid_scope',
|
||||
stage: 'scope_parse',
|
||||
statusCode: 400,
|
||||
grantId: GRANT_ID,
|
||||
subjectUserId: SUBJECT_USER_ID,
|
||||
resource: 'tasks',
|
||||
},
|
||||
});
|
||||
expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('denies unsupported resource names before RBAC evaluation', async () => {
|
||||
const nativeRbac = makeNativeRbac({
|
||||
allowed: true,
|
||||
access: { includePersonal: true, teamIds: [] },
|
||||
});
|
||||
|
||||
const result = await service.evaluateAccess({
|
||||
context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
|
||||
resource: 'unknown_resource',
|
||||
nativeRbac,
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
allowed: false,
|
||||
deny: {
|
||||
code: 'invalid_resource',
|
||||
stage: 'resource_allowlist',
|
||||
statusCode: 403,
|
||||
},
|
||||
});
|
||||
expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('denies resources explicitly present in excluded_resources before allowlist miss', async () => {
|
||||
const nativeRbac = makeNativeRbac({
|
||||
allowed: true,
|
||||
access: { includePersonal: true, teamIds: [] },
|
||||
});
|
||||
|
||||
const result = await service.evaluateAccess({
|
||||
context: makeContext({
|
||||
resources: ['tasks'],
|
||||
excluded_resources: ['credentials'],
|
||||
max_rows_per_query: 100,
|
||||
}),
|
||||
resource: 'credentials',
|
||||
nativeRbac,
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
allowed: false,
|
||||
deny: {
|
||||
code: 'resource_excluded',
|
||||
stage: 'resource_exclusion',
|
||||
statusCode: 403,
|
||||
resource: 'credentials',
|
||||
},
|
||||
});
|
||||
expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('denies supported resources that are not granted by scope', async () => {
|
||||
const nativeRbac = makeNativeRbac({
|
||||
allowed: true,
|
||||
access: { includePersonal: true, teamIds: [] },
|
||||
});
|
||||
|
||||
const result = await service.evaluateAccess({
|
||||
context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
|
||||
resource: 'notes',
|
||||
nativeRbac,
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
allowed: false,
|
||||
deny: {
|
||||
code: 'resource_not_granted',
|
||||
stage: 'resource_allowlist',
|
||||
statusCode: 403,
|
||||
resource: 'notes',
|
||||
},
|
||||
});
|
||||
expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('denies invalid requested row limits before RBAC evaluation', async () => {
|
||||
const nativeRbac = makeNativeRbac({
|
||||
allowed: true,
|
||||
access: { includePersonal: true, teamIds: [] },
|
||||
});
|
||||
|
||||
const result = await service.evaluateAccess({
|
||||
context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
|
||||
resource: 'tasks',
|
||||
requestedLimit: 0,
|
||||
nativeRbac,
|
||||
});
|
||||
|
||||
expect(result).toMatchObject({
|
||||
allowed: false,
|
||||
deny: {
|
||||
code: 'invalid_limit',
|
||||
stage: 'row_cap',
|
||||
statusCode: 400,
|
||||
details: { requestedLimit: 0 },
|
||||
},
|
||||
});
|
||||
expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('denies when native RBAC rejects subjectUserId access to the resource', async () => {
|
||||
const result = await service.evaluateAccess({
|
||||
context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
|
||||
resource: 'tasks',
|
||||
nativeRbac: makeNativeRbac({
|
||||
allowed: false,
|
||||
reason: 'read:tasks denied',
|
||||
details: { permission: 'tasks:read' },
|
||||
}),
|
||||
});
|
||||
|
||||
expect(result).toEqual({
|
||||
allowed: false,
|
||||
deny: {
|
||||
code: 'native_rbac_denied',
|
||||
stage: 'native_rbac',
|
||||
statusCode: 403,
|
||||
message: 'read:tasks denied',
|
||||
grantId: GRANT_ID,
|
||||
peerId: PEER_ID,
|
||||
subjectUserId: SUBJECT_USER_ID,
|
||||
resource: 'tasks',
|
||||
details: { permission: 'tasks:read' },
|
||||
},
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -10,22 +10,4 @@
|
||||
*/
|
||||
|
||||
export { FederationAuthGuard } from './federation-auth.guard.js';
|
||||
export { FederationScopeService } from './scope.service.js';
|
||||
export type { FederationContext } from './federation-context.js';
|
||||
export type {
|
||||
FederationNativeRbacAccess,
|
||||
FederationNativeRbacAllowedResult,
|
||||
FederationNativeRbacDeniedResult,
|
||||
FederationNativeRbacEvaluator,
|
||||
FederationNativeRbacRequest,
|
||||
FederationNativeRbacResult,
|
||||
FederationScopeAllowedResult,
|
||||
FederationScopeDeniedResult,
|
||||
FederationScopeDenyCode,
|
||||
FederationScopeDenyDetails,
|
||||
FederationScopeDenyReason,
|
||||
FederationScopeDenyStage,
|
||||
FederationScopeEvaluationInput,
|
||||
FederationScopeEvaluationResult,
|
||||
FederationScopeQueryFilter,
|
||||
} from './scope.service.js';
|
||||
|
||||
@@ -1,272 +0,0 @@
|
||||
/**
|
||||
* FederationScopeService — M3 server-side scope enforcement pipeline.
|
||||
*
|
||||
* Pure trust-boundary service: it validates the grant scope, asks an injected
|
||||
* native RBAC evaluator what the subject user can read locally, intersects that
|
||||
* answer with the federation scope filters, and returns a query filter for the
|
||||
* verb controllers. The service performs no DB calls directly.
|
||||
*/
|
||||
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import {
|
||||
FEDERATION_RESOURCE_VALUES,
|
||||
type FederationResource,
|
||||
FederationScopeError,
|
||||
parseFederationScope,
|
||||
} from '../scope-schema.js';
|
||||
import type { FederationContext } from './federation-context.js';
|
||||
|
||||
const federationResourceSet: ReadonlySet<string> = new Set<string>(FEDERATION_RESOURCE_VALUES);
|
||||
|
||||
export type FederationScopeDenyStage =
|
||||
| 'scope_parse'
|
||||
| 'resource_allowlist'
|
||||
| 'resource_exclusion'
|
||||
| 'native_rbac'
|
||||
| 'row_cap';
|
||||
|
||||
export type FederationScopeDenyCode =
|
||||
| 'invalid_scope'
|
||||
| 'invalid_resource'
|
||||
| 'resource_not_granted'
|
||||
| 'resource_excluded'
|
||||
| 'native_rbac_denied'
|
||||
| 'invalid_limit';
|
||||
|
||||
export type FederationScopeDenyStatus = 400 | 403;
|
||||
|
||||
export interface FederationScopeDenyDetails {
|
||||
readonly [key: string]: string | number | boolean | readonly string[];
|
||||
}
|
||||
|
||||
export interface FederationScopeDenyReason {
|
||||
readonly code: FederationScopeDenyCode;
|
||||
readonly stage: FederationScopeDenyStage;
|
||||
readonly statusCode: FederationScopeDenyStatus;
|
||||
readonly message: string;
|
||||
readonly grantId: string;
|
||||
readonly peerId: string;
|
||||
readonly subjectUserId: string;
|
||||
readonly resource: string;
|
||||
readonly details?: FederationScopeDenyDetails;
|
||||
}
|
||||
|
||||
export interface FederationNativeRbacRequest {
|
||||
readonly grantId: string;
|
||||
readonly peerId: string;
|
||||
readonly subjectUserId: string;
|
||||
readonly resource: FederationResource;
|
||||
}
|
||||
|
||||
export interface FederationNativeRbacAccess {
|
||||
/** Whether this user may read personal rows for this resource. */
|
||||
readonly includePersonal: boolean;
|
||||
|
||||
/** Team IDs this user may read for this resource under native RBAC. */
|
||||
readonly teamIds: readonly string[];
|
||||
}
|
||||
|
||||
export interface FederationNativeRbacAllowedResult {
|
||||
readonly allowed: true;
|
||||
readonly access: FederationNativeRbacAccess;
|
||||
}
|
||||
|
||||
export interface FederationNativeRbacDeniedResult {
|
||||
readonly allowed: false;
|
||||
readonly reason?: string;
|
||||
readonly details?: FederationScopeDenyDetails;
|
||||
}
|
||||
|
||||
export type FederationNativeRbacResult =
|
||||
| FederationNativeRbacAllowedResult
|
||||
| FederationNativeRbacDeniedResult;
|
||||
|
||||
export interface FederationNativeRbacEvaluator {
|
||||
evaluateReadAccess(request: FederationNativeRbacRequest): Promise<FederationNativeRbacResult>;
|
||||
}
|
||||
|
||||
export interface FederationScopeEvaluationInput {
|
||||
readonly context: FederationContext;
|
||||
readonly resource: string;
|
||||
readonly requestedLimit?: number;
|
||||
readonly nativeRbac: FederationNativeRbacEvaluator;
|
||||
}
|
||||
|
||||
export interface FederationScopeQueryFilter {
|
||||
readonly resource: FederationResource;
|
||||
readonly subjectUserId: string;
|
||||
readonly includePersonal: boolean;
|
||||
readonly teamIds: readonly string[];
|
||||
readonly limit: number;
|
||||
readonly maxRowsPerQuery: number;
|
||||
}
|
||||
|
||||
export interface FederationScopeAllowedResult {
|
||||
readonly allowed: true;
|
||||
readonly filter: FederationScopeQueryFilter;
|
||||
}
|
||||
|
||||
export interface FederationScopeDeniedResult {
|
||||
readonly allowed: false;
|
||||
readonly deny: FederationScopeDenyReason;
|
||||
}
|
||||
|
||||
export type FederationScopeEvaluationResult =
|
||||
| FederationScopeAllowedResult
|
||||
| FederationScopeDeniedResult;
|
||||
|
||||
function isFederationResource(resource: string): resource is FederationResource {
|
||||
return federationResourceSet.has(resource);
|
||||
}
|
||||
|
||||
function uniqueStrings(values: readonly string[]): readonly string[] {
|
||||
return Array.from(new Set<string>(values));
|
||||
}
|
||||
|
||||
function intersectTeamIds(
|
||||
nativeTeamIds: readonly string[],
|
||||
scopedTeamIds: readonly string[] | undefined,
|
||||
): readonly string[] {
|
||||
const uniqueNativeTeamIds = uniqueStrings(nativeTeamIds);
|
||||
|
||||
if (scopedTeamIds === undefined) {
|
||||
return uniqueNativeTeamIds;
|
||||
}
|
||||
|
||||
const nativeSet = new Set<string>(uniqueNativeTeamIds);
|
||||
return uniqueStrings(scopedTeamIds).filter((teamId: string): boolean => nativeSet.has(teamId));
|
||||
}
|
||||
|
||||
function makeDenyReason(params: {
|
||||
readonly code: FederationScopeDenyCode;
|
||||
readonly stage: FederationScopeDenyStage;
|
||||
readonly statusCode?: FederationScopeDenyStatus;
|
||||
readonly message: string;
|
||||
readonly context: FederationContext;
|
||||
readonly resource: string;
|
||||
readonly details?: FederationScopeDenyDetails;
|
||||
}): FederationScopeDeniedResult {
|
||||
return {
|
||||
allowed: false,
|
||||
deny: {
|
||||
code: params.code,
|
||||
stage: params.stage,
|
||||
statusCode: params.statusCode ?? 403,
|
||||
message: params.message,
|
||||
grantId: params.context.grantId,
|
||||
peerId: params.context.peerId,
|
||||
subjectUserId: params.context.subjectUserId,
|
||||
resource: params.resource,
|
||||
...(params.details !== undefined ? { details: params.details } : {}),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class FederationScopeService {
|
||||
async evaluateAccess(
|
||||
input: FederationScopeEvaluationInput,
|
||||
): Promise<FederationScopeEvaluationResult> {
|
||||
const { context, resource, requestedLimit, nativeRbac } = input;
|
||||
|
||||
let scope: ReturnType<typeof parseFederationScope>;
|
||||
try {
|
||||
scope = parseFederationScope(context.scope);
|
||||
} catch (error: unknown) {
|
||||
const message =
|
||||
error instanceof FederationScopeError
|
||||
? 'Federation grant scope is invalid'
|
||||
: 'Federation grant scope could not be parsed';
|
||||
const details = error instanceof Error ? { reason: error.message } : undefined;
|
||||
return makeDenyReason({
|
||||
code: 'invalid_scope',
|
||||
stage: 'scope_parse',
|
||||
statusCode: 400,
|
||||
message,
|
||||
context,
|
||||
resource,
|
||||
...(details !== undefined ? { details } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
if (!isFederationResource(resource)) {
|
||||
return makeDenyReason({
|
||||
code: 'invalid_resource',
|
||||
stage: 'resource_allowlist',
|
||||
message: 'Requested federation resource is not supported',
|
||||
context,
|
||||
resource,
|
||||
details: { supportedResources: FEDERATION_RESOURCE_VALUES },
|
||||
});
|
||||
}
|
||||
|
||||
if (scope.excluded_resources.includes(resource)) {
|
||||
return makeDenyReason({
|
||||
code: 'resource_excluded',
|
||||
stage: 'resource_exclusion',
|
||||
message: 'Requested federation resource is explicitly excluded by grant scope',
|
||||
context,
|
||||
resource,
|
||||
});
|
||||
}
|
||||
|
||||
if (!scope.resources.includes(resource)) {
|
||||
return makeDenyReason({
|
||||
code: 'resource_not_granted',
|
||||
stage: 'resource_allowlist',
|
||||
message: 'Requested federation resource is not granted by scope',
|
||||
context,
|
||||
resource,
|
||||
details: { grantedResources: scope.resources },
|
||||
});
|
||||
}
|
||||
|
||||
if (requestedLimit !== undefined && (!Number.isInteger(requestedLimit) || requestedLimit < 1)) {
|
||||
return makeDenyReason({
|
||||
code: 'invalid_limit',
|
||||
stage: 'row_cap',
|
||||
statusCode: 400,
|
||||
message: 'Requested row limit must be a positive integer',
|
||||
context,
|
||||
resource,
|
||||
details: { requestedLimit },
|
||||
});
|
||||
}
|
||||
|
||||
const nativeResult = await nativeRbac.evaluateReadAccess({
|
||||
grantId: context.grantId,
|
||||
peerId: context.peerId,
|
||||
subjectUserId: context.subjectUserId,
|
||||
resource,
|
||||
});
|
||||
|
||||
if (!nativeResult.allowed) {
|
||||
return makeDenyReason({
|
||||
code: 'native_rbac_denied',
|
||||
stage: 'native_rbac',
|
||||
message: nativeResult.reason ?? 'Subject user is not allowed to read this resource',
|
||||
context,
|
||||
resource,
|
||||
...(nativeResult.details !== undefined ? { details: nativeResult.details } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
const scopeFilter = scope.filters?.[resource];
|
||||
const includePersonal =
|
||||
Boolean(scopeFilter?.include_personal ?? true) && nativeResult.access.includePersonal;
|
||||
const teamIds = intersectTeamIds(nativeResult.access.teamIds, scopeFilter?.include_teams);
|
||||
const limit = Math.min(requestedLimit ?? scope.max_rows_per_query, scope.max_rows_per_query);
|
||||
|
||||
return {
|
||||
allowed: true,
|
||||
filter: {
|
||||
resource,
|
||||
subjectUserId: context.subjectUserId,
|
||||
includePersonal,
|
||||
teamIds,
|
||||
limit,
|
||||
maxRowsPerQuery: scope.max_rows_per_query,
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -1,88 +0,0 @@
|
||||
import 'reflect-metadata';
|
||||
import { RequestMethod } from '@nestjs/common';
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import type { FastifyRequest } from 'fastify';
|
||||
import { FederationCapabilitiesResponseSchema, FEDERATION_VERBS } from '@mosaicstack/types';
|
||||
import { FederationScopeError } from '../../../scope-schema.js';
|
||||
import { FederationAuthGuard } from '../../federation-auth.guard.js';
|
||||
import { CapabilitiesController } from '../capabilities.controller.js';
|
||||
|
||||
const VALID_SCOPE = {
|
||||
resources: ['tasks', 'notes'],
|
||||
excluded_resources: ['credentials'],
|
||||
max_rows_per_query: 250,
|
||||
} as const;
|
||||
|
||||
const DEFAULTED_SCOPE = {
|
||||
resources: ['memory'],
|
||||
max_rows_per_query: 10,
|
||||
} as const;
|
||||
|
||||
function makeRequest(scope: Record<string, unknown>): FastifyRequest {
|
||||
return {
|
||||
federationContext: {
|
||||
grantId: 'grant-1',
|
||||
peerId: 'peer-1',
|
||||
subjectUserId: 'user-1',
|
||||
scope,
|
||||
},
|
||||
} as FastifyRequest;
|
||||
}
|
||||
|
||||
describe('CapabilitiesController', () => {
|
||||
it('declares GET /api/federation/v1/capabilities', () => {
|
||||
expect(Reflect.getMetadata('path', CapabilitiesController)).toBe(
|
||||
'api/federation/v1/capabilities',
|
||||
);
|
||||
expect(Reflect.getMetadata('path', CapabilitiesController.prototype.getCapabilities)).toBe('/');
|
||||
expect(Reflect.getMetadata('method', CapabilitiesController.prototype.getCapabilities)).toBe(
|
||||
RequestMethod.GET,
|
||||
);
|
||||
});
|
||||
|
||||
it('is protected only by FederationAuthGuard', () => {
|
||||
const guards = Reflect.getMetadata('__guards__', CapabilitiesController) as unknown[];
|
||||
|
||||
expect(guards).toEqual([FederationAuthGuard]);
|
||||
});
|
||||
|
||||
it('returns resources, excluded resources, max rows, and M3 supported verbs from the active grant scope', () => {
|
||||
const controller = new CapabilitiesController();
|
||||
|
||||
const response = controller.getCapabilities(makeRequest(VALID_SCOPE));
|
||||
|
||||
expect(response).toEqual({
|
||||
resources: ['tasks', 'notes'],
|
||||
excluded_resources: ['credentials'],
|
||||
max_rows_per_query: 250,
|
||||
supported_verbs: [...FEDERATION_VERBS],
|
||||
});
|
||||
expect(FederationCapabilitiesResponseSchema.safeParse(response).success).toBe(true);
|
||||
});
|
||||
|
||||
it('applies scope defaults without RBAC or resource filtering', () => {
|
||||
const controller = new CapabilitiesController();
|
||||
|
||||
const response = controller.getCapabilities(makeRequest(DEFAULTED_SCOPE));
|
||||
|
||||
expect(response).toEqual({
|
||||
resources: ['memory'],
|
||||
excluded_resources: [],
|
||||
max_rows_per_query: 10,
|
||||
supported_verbs: ['list', 'get', 'capabilities'],
|
||||
});
|
||||
});
|
||||
|
||||
it('rejects invalid scope state instead of returning an invalid capabilities contract', () => {
|
||||
const controller = new CapabilitiesController();
|
||||
|
||||
expect(() =>
|
||||
controller.getCapabilities(
|
||||
makeRequest({
|
||||
resources: [],
|
||||
max_rows_per_query: 0,
|
||||
}),
|
||||
),
|
||||
).toThrow(FederationScopeError);
|
||||
});
|
||||
});
|
||||
@@ -1,428 +0,0 @@
|
||||
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
|
||||
import {
|
||||
createPgliteDb,
|
||||
insights,
|
||||
missionTasks,
|
||||
missions,
|
||||
preferences,
|
||||
projects,
|
||||
runPgliteMigrations,
|
||||
teams,
|
||||
users,
|
||||
type Db,
|
||||
type DbHandle,
|
||||
} from '@mosaicstack/db';
|
||||
import type { FederationScopeQueryFilter } from '../../scope.service.js';
|
||||
import { FederationListQueryService } from '../list-query.service.js';
|
||||
|
||||
const TASK_FILTER: FederationScopeQueryFilter = {
|
||||
resource: 'tasks',
|
||||
subjectUserId: 'user-1',
|
||||
includePersonal: true,
|
||||
teamIds: [],
|
||||
limit: 2,
|
||||
maxRowsPerQuery: 2,
|
||||
};
|
||||
|
||||
const SUBJECT_USER_ID = 'fed-m3-05-subject';
|
||||
const OTHER_USER_ID = 'fed-m3-05-other';
|
||||
const TEAM_ID = '05000000-0000-4000-8000-000000000001';
|
||||
const UNAUTHORIZED_TEAM_ID = '05000000-0000-4000-8000-000000000002';
|
||||
const PERSONAL_PROJECT_ID = '05000000-0000-4000-8000-000000000101';
|
||||
const TEAM_PROJECT_ID = '05000000-0000-4000-8000-000000000102';
|
||||
const UNAUTHORIZED_PROJECT_ID = '05000000-0000-4000-8000-000000000103';
|
||||
const PERSONAL_MISSION_ID = '05000000-0000-4000-8000-000000000201';
|
||||
const TEAM_MISSION_ID = '05000000-0000-4000-8000-000000000202';
|
||||
const UNAUTHORIZED_MISSION_ID = '05000000-0000-4000-8000-000000000203';
|
||||
const SUBJECT_TEAM_NOTE_ID = '05000000-0000-4000-8000-000000000301';
|
||||
const OTHER_TEAM_NOTE_ID = '05000000-0000-4000-8000-000000000302';
|
||||
const SUBJECT_PERSONAL_NOTE_ID = '05000000-0000-4000-8000-000000000303';
|
||||
const SUBJECT_UNAUTHORIZED_NOTE_ID = '05000000-0000-4000-8000-000000000304';
|
||||
const INSIGHT_ONE_ID = '05000000-0000-4000-8000-000000000401';
|
||||
const INSIGHT_TWO_ID = '05000000-0000-4000-8000-000000000402';
|
||||
const PREFERENCE_ONE_ID = '05000000-0000-4000-8000-000000000501';
|
||||
const PREFERENCE_TWO_ID = '05000000-0000-4000-8000-000000000502';
|
||||
|
||||
let dbHandle: DbHandle | undefined;
|
||||
|
||||
function makeService() {
|
||||
return new FederationListQueryService({} as Db);
|
||||
}
|
||||
|
||||
function makeDbService() {
|
||||
if (!dbHandle) {
|
||||
throw new Error('test DB not initialized');
|
||||
}
|
||||
return new FederationListQueryService(dbHandle.db);
|
||||
}
|
||||
|
||||
async function seedNotesFixture() {
|
||||
if (!dbHandle) {
|
||||
throw new Error('test DB not initialized');
|
||||
}
|
||||
|
||||
await dbHandle.db.insert(users).values([
|
||||
{
|
||||
id: SUBJECT_USER_ID,
|
||||
name: 'Federation Subject',
|
||||
email: `${SUBJECT_USER_ID}@example.test`,
|
||||
emailVerified: false,
|
||||
},
|
||||
{
|
||||
id: OTHER_USER_ID,
|
||||
name: 'Federation Other',
|
||||
email: `${OTHER_USER_ID}@example.test`,
|
||||
emailVerified: false,
|
||||
},
|
||||
]);
|
||||
|
||||
await dbHandle.db.insert(teams).values([
|
||||
{
|
||||
id: TEAM_ID,
|
||||
name: 'FED-M3-05 Team',
|
||||
slug: 'fed-m3-05-team',
|
||||
ownerId: SUBJECT_USER_ID,
|
||||
managerId: SUBJECT_USER_ID,
|
||||
},
|
||||
{
|
||||
id: UNAUTHORIZED_TEAM_ID,
|
||||
name: 'FED-M3-05 Unauthorized Team',
|
||||
slug: 'fed-m3-05-unauthorized-team',
|
||||
ownerId: OTHER_USER_ID,
|
||||
managerId: OTHER_USER_ID,
|
||||
},
|
||||
]);
|
||||
|
||||
await dbHandle.db.insert(projects).values([
|
||||
{
|
||||
id: PERSONAL_PROJECT_ID,
|
||||
name: 'FED-M3-05 Personal Project',
|
||||
ownerId: SUBJECT_USER_ID,
|
||||
ownerType: 'user',
|
||||
},
|
||||
{
|
||||
id: TEAM_PROJECT_ID,
|
||||
name: 'FED-M3-05 Team Project',
|
||||
teamId: TEAM_ID,
|
||||
ownerType: 'team',
|
||||
},
|
||||
{
|
||||
id: UNAUTHORIZED_PROJECT_ID,
|
||||
name: 'FED-M3-05 Unauthorized Project',
|
||||
teamId: UNAUTHORIZED_TEAM_ID,
|
||||
ownerType: 'team',
|
||||
},
|
||||
]);
|
||||
|
||||
await dbHandle.db.insert(missions).values([
|
||||
{
|
||||
id: PERSONAL_MISSION_ID,
|
||||
name: 'FED-M3-05 Personal Mission',
|
||||
projectId: PERSONAL_PROJECT_ID,
|
||||
userId: SUBJECT_USER_ID,
|
||||
},
|
||||
{
|
||||
id: TEAM_MISSION_ID,
|
||||
name: 'FED-M3-05 Team Mission',
|
||||
projectId: TEAM_PROJECT_ID,
|
||||
userId: SUBJECT_USER_ID,
|
||||
},
|
||||
{
|
||||
id: UNAUTHORIZED_MISSION_ID,
|
||||
name: 'FED-M3-05 Unauthorized Mission',
|
||||
projectId: UNAUTHORIZED_PROJECT_ID,
|
||||
userId: SUBJECT_USER_ID,
|
||||
},
|
||||
]);
|
||||
|
||||
await dbHandle.db.insert(missionTasks).values([
|
||||
{
|
||||
id: SUBJECT_TEAM_NOTE_ID,
|
||||
missionId: TEAM_MISSION_ID,
|
||||
userId: SUBJECT_USER_ID,
|
||||
notes: 'subject note on team mission',
|
||||
createdAt: new Date('2026-06-24T03:00:00.000Z'),
|
||||
updatedAt: new Date('2026-06-24T03:00:00.000Z'),
|
||||
},
|
||||
{
|
||||
id: OTHER_TEAM_NOTE_ID,
|
||||
missionId: TEAM_MISSION_ID,
|
||||
userId: OTHER_USER_ID,
|
||||
notes: 'other user note on team mission',
|
||||
createdAt: new Date('2026-06-24T02:00:00.000Z'),
|
||||
updatedAt: new Date('2026-06-24T02:00:00.000Z'),
|
||||
},
|
||||
{
|
||||
id: SUBJECT_PERSONAL_NOTE_ID,
|
||||
missionId: PERSONAL_MISSION_ID,
|
||||
userId: SUBJECT_USER_ID,
|
||||
notes: 'subject note on personal mission',
|
||||
createdAt: new Date('2026-06-24T01:00:00.000Z'),
|
||||
updatedAt: new Date('2026-06-24T01:00:00.000Z'),
|
||||
},
|
||||
{
|
||||
id: SUBJECT_UNAUTHORIZED_NOTE_ID,
|
||||
missionId: UNAUTHORIZED_MISSION_ID,
|
||||
userId: SUBJECT_USER_ID,
|
||||
notes: 'subject note outside grant-visible missions',
|
||||
createdAt: new Date('2026-06-24T04:00:00.000Z'),
|
||||
updatedAt: new Date('2026-06-24T04:00:00.000Z'),
|
||||
},
|
||||
]);
|
||||
|
||||
const memoryCreatedAt = new Date('2026-06-24T05:00:00.000Z');
|
||||
await dbHandle.db.insert(insights).values([
|
||||
{
|
||||
id: INSIGHT_ONE_ID,
|
||||
userId: SUBJECT_USER_ID,
|
||||
content: 'first insight',
|
||||
source: 'agent',
|
||||
createdAt: memoryCreatedAt,
|
||||
updatedAt: memoryCreatedAt,
|
||||
},
|
||||
{
|
||||
id: INSIGHT_TWO_ID,
|
||||
userId: SUBJECT_USER_ID,
|
||||
content: 'second insight',
|
||||
source: 'agent',
|
||||
createdAt: memoryCreatedAt,
|
||||
updatedAt: memoryCreatedAt,
|
||||
},
|
||||
]);
|
||||
|
||||
await dbHandle.db.insert(preferences).values([
|
||||
{
|
||||
id: PREFERENCE_ONE_ID,
|
||||
userId: SUBJECT_USER_ID,
|
||||
key: 'fed-m3-05-pref-1',
|
||||
value: { enabled: true },
|
||||
createdAt: memoryCreatedAt,
|
||||
updatedAt: memoryCreatedAt,
|
||||
},
|
||||
{
|
||||
id: PREFERENCE_TWO_ID,
|
||||
userId: SUBJECT_USER_ID,
|
||||
key: 'fed-m3-05-pref-2',
|
||||
value: { enabled: false },
|
||||
createdAt: memoryCreatedAt,
|
||||
updatedAt: memoryCreatedAt,
|
||||
},
|
||||
]);
|
||||
}
|
||||
|
||||
function stubRows(
|
||||
service: FederationListQueryService,
|
||||
...pages: Array<Array<Record<string, unknown>>>
|
||||
) {
|
||||
const mock = vi.fn();
|
||||
for (const page of pages) {
|
||||
mock.mockResolvedValueOnce(page);
|
||||
}
|
||||
(
|
||||
service as unknown as {
|
||||
listAllRows: (
|
||||
_filter: FederationScopeQueryFilter,
|
||||
_rowLimit: number,
|
||||
_cursor: unknown,
|
||||
) => Promise<Array<Record<string, unknown>>>;
|
||||
}
|
||||
).listAllRows = mock;
|
||||
return mock;
|
||||
}
|
||||
|
||||
describe('FederationListQueryService', () => {
|
||||
beforeAll(async () => {
|
||||
dbHandle = createPgliteDb(`memory://fed-m3-05-list-${Date.now()}`);
|
||||
await runPgliteMigrations(dbHandle);
|
||||
await seedNotesFixture();
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await dbHandle?.close();
|
||||
dbHandle = undefined;
|
||||
});
|
||||
|
||||
it('denies sensitive resources in native RBAC for M3 list reads', async () => {
|
||||
const service = makeService();
|
||||
|
||||
await expect(
|
||||
service.evaluateReadAccess({
|
||||
grantId: 'grant-1',
|
||||
peerId: 'peer-1',
|
||||
subjectUserId: 'user-1',
|
||||
resource: 'credentials',
|
||||
}),
|
||||
).resolves.toMatchObject({
|
||||
allowed: false,
|
||||
reason: 'credentials federation list access is not implemented in M3',
|
||||
});
|
||||
});
|
||||
|
||||
it('allows personal memory reads without requiring team lookup', async () => {
|
||||
const service = makeService();
|
||||
|
||||
await expect(
|
||||
service.evaluateReadAccess({
|
||||
grantId: 'grant-1',
|
||||
peerId: 'peer-1',
|
||||
subjectUserId: 'user-1',
|
||||
resource: 'memory',
|
||||
}),
|
||||
).resolves.toEqual({
|
||||
allowed: true,
|
||||
access: { includePersonal: true, teamIds: [] },
|
||||
});
|
||||
});
|
||||
|
||||
it('applies the scope row cap and returns an opaque next cursor when truncated', async () => {
|
||||
const service = makeService();
|
||||
const listAllRows = stubRows(
|
||||
service,
|
||||
[
|
||||
{ id: '3', createdAt: new Date('2026-06-24T03:00:00.000Z') },
|
||||
{ id: '2', createdAt: new Date('2026-06-24T02:00:00.000Z') },
|
||||
{ id: '1', createdAt: new Date('2026-06-24T01:00:00.000Z') },
|
||||
],
|
||||
[{ id: '1', createdAt: new Date('2026-06-24T01:00:00.000Z') }],
|
||||
);
|
||||
|
||||
const firstPage = await service.list({ filter: TASK_FILTER });
|
||||
|
||||
expect(firstPage).toEqual({
|
||||
items: [
|
||||
{ id: '3', createdAt: new Date('2026-06-24T03:00:00.000Z') },
|
||||
{ id: '2', createdAt: new Date('2026-06-24T02:00:00.000Z') },
|
||||
],
|
||||
truncated: true,
|
||||
nextCursor: expect.any(String),
|
||||
});
|
||||
|
||||
expect(listAllRows).toHaveBeenNthCalledWith(1, TASK_FILTER, 3, undefined);
|
||||
|
||||
const secondPage = await service.list({ filter: TASK_FILTER, cursor: firstPage.nextCursor });
|
||||
expect(secondPage).toEqual({
|
||||
items: [{ id: '1', createdAt: new Date('2026-06-24T01:00:00.000Z') }],
|
||||
truncated: false,
|
||||
});
|
||||
expect(listAllRows).toHaveBeenNthCalledWith(
|
||||
2,
|
||||
TASK_FILTER,
|
||||
3,
|
||||
expect.objectContaining({ id: '2' }),
|
||||
);
|
||||
});
|
||||
|
||||
it('rejects invalid cursors instead of falling back to the first page', async () => {
|
||||
const service = makeService();
|
||||
stubRows(service, [{ id: '1' }]);
|
||||
|
||||
await expect(service.list({ filter: TASK_FILTER, cursor: 'not-base64-json' })).rejects.toThrow(
|
||||
'Invalid federation list cursor',
|
||||
);
|
||||
});
|
||||
|
||||
it('throws when a truncated page cannot encode a resumable cursor', async () => {
|
||||
const service = makeService();
|
||||
stubRows(service, [
|
||||
{ id: '2', createdAt: 'not-a-date' },
|
||||
{ id: '1', createdAt: 'not-a-date' },
|
||||
]);
|
||||
|
||||
await expect(service.list({ filter: { ...TASK_FILTER, limit: 1 } })).rejects.toThrow(
|
||||
'Federation list cursor cannot be encoded',
|
||||
);
|
||||
});
|
||||
|
||||
it('throws on unsupported resources instead of crashing pagination', async () => {
|
||||
const service = makeService();
|
||||
|
||||
await expect(
|
||||
service.list({
|
||||
filter: {
|
||||
...TASK_FILTER,
|
||||
resource: 'unknown-resource' as FederationScopeQueryFilter['resource'],
|
||||
},
|
||||
}),
|
||||
).rejects.toThrow('Unsupported federation list resource');
|
||||
});
|
||||
|
||||
it('does not leak another user mission task notes through team-scoped note reads', async () => {
|
||||
const service = makeDbService();
|
||||
|
||||
const result = await service.list({
|
||||
filter: {
|
||||
resource: 'notes',
|
||||
subjectUserId: SUBJECT_USER_ID,
|
||||
includePersonal: false,
|
||||
teamIds: [TEAM_ID],
|
||||
limit: 10,
|
||||
maxRowsPerQuery: 10,
|
||||
},
|
||||
});
|
||||
|
||||
const ids = result.items.map((item) => item['id']);
|
||||
expect(ids).toEqual([SUBJECT_TEAM_NOTE_ID]);
|
||||
expect(ids).not.toContain(OTHER_TEAM_NOTE_ID);
|
||||
});
|
||||
|
||||
it('does not return subject personal mission task notes when includePersonal is false', async () => {
|
||||
const service = makeDbService();
|
||||
|
||||
const result = await service.list({
|
||||
filter: {
|
||||
resource: 'notes',
|
||||
subjectUserId: SUBJECT_USER_ID,
|
||||
includePersonal: false,
|
||||
teamIds: [TEAM_ID],
|
||||
limit: 10,
|
||||
maxRowsPerQuery: 10,
|
||||
},
|
||||
});
|
||||
|
||||
expect(result.items.map((item) => item['id'])).not.toContain(SUBJECT_PERSONAL_NOTE_ID);
|
||||
});
|
||||
|
||||
it('does not return subject notes from missions outside the grant-visible project set', async () => {
|
||||
const service = makeDbService();
|
||||
|
||||
const result = await service.list({
|
||||
filter: {
|
||||
resource: 'notes',
|
||||
subjectUserId: SUBJECT_USER_ID,
|
||||
includePersonal: true,
|
||||
teamIds: [TEAM_ID],
|
||||
limit: 10,
|
||||
maxRowsPerQuery: 10,
|
||||
},
|
||||
});
|
||||
|
||||
const ids = result.items.map((item) => item['id']);
|
||||
expect(ids).toContain(SUBJECT_PERSONAL_NOTE_ID);
|
||||
expect(ids).toContain(SUBJECT_TEAM_NOTE_ID);
|
||||
expect(ids).not.toContain(SUBJECT_UNAUTHORIZED_NOTE_ID);
|
||||
expect(ids).not.toContain(OTHER_TEAM_NOTE_ID);
|
||||
});
|
||||
|
||||
it('paginates memory deterministically across insights and preferences', async () => {
|
||||
const service = makeDbService();
|
||||
const filter: FederationScopeQueryFilter = {
|
||||
resource: 'memory',
|
||||
subjectUserId: SUBJECT_USER_ID,
|
||||
includePersonal: true,
|
||||
teamIds: [],
|
||||
limit: 2,
|
||||
maxRowsPerQuery: 2,
|
||||
};
|
||||
|
||||
const firstPage = await service.list({ filter });
|
||||
const secondPage = await service.list({ filter, cursor: firstPage.nextCursor });
|
||||
const firstPageIds = firstPage.items.map((item) => item['id']);
|
||||
const secondPageIds = secondPage.items.map((item) => item['id']);
|
||||
const allIds = [...firstPageIds, ...secondPageIds];
|
||||
|
||||
expect(firstPage).toMatchObject({ truncated: true, nextCursor: expect.any(String) });
|
||||
expect(firstPageIds).toEqual([INSIGHT_TWO_ID, INSIGHT_ONE_ID]);
|
||||
expect(secondPageIds).toEqual([PREFERENCE_TWO_ID, PREFERENCE_ONE_ID]);
|
||||
expect(new Set(allIds).size).toBe(allIds.length);
|
||||
});
|
||||
});
|
||||
@@ -1,188 +0,0 @@
|
||||
import 'reflect-metadata';
|
||||
import { RequestMethod } from '@nestjs/common';
|
||||
import type { FastifyRequest } from 'fastify';
|
||||
import { beforeEach, describe, expect, it, vi } from 'vitest';
|
||||
import { FederationAuthGuard } from '../../federation-auth.guard.js';
|
||||
import type {
|
||||
FederationScopeEvaluationResult,
|
||||
FederationScopeQueryFilter,
|
||||
} from '../../scope.service.js';
|
||||
import { ListController } from '../list.controller.js';
|
||||
import type { FederationListQueryResult } from '../list-query.service.js';
|
||||
|
||||
const FEDERATION_CONTEXT = {
|
||||
grantId: 'grant-1',
|
||||
peerId: 'peer-1',
|
||||
subjectUserId: 'user-1',
|
||||
scope: { resources: ['tasks'], max_rows_per_query: 25 },
|
||||
};
|
||||
|
||||
const TASK_FILTER: FederationScopeQueryFilter = {
|
||||
resource: 'tasks',
|
||||
subjectUserId: 'user-1',
|
||||
includePersonal: true,
|
||||
teamIds: ['team-1'],
|
||||
limit: 10,
|
||||
maxRowsPerQuery: 25,
|
||||
};
|
||||
|
||||
function makeRequest(): FastifyRequest {
|
||||
return { federationContext: FEDERATION_CONTEXT } as unknown as FastifyRequest;
|
||||
}
|
||||
|
||||
function allowedScope(
|
||||
filter: FederationScopeQueryFilter = TASK_FILTER,
|
||||
): FederationScopeEvaluationResult {
|
||||
return { allowed: true, filter };
|
||||
}
|
||||
|
||||
function makeController(opts?: {
|
||||
scopeResult?: FederationScopeEvaluationResult;
|
||||
queryResult?: FederationListQueryResult;
|
||||
}) {
|
||||
const scope = {
|
||||
evaluateAccess: vi.fn().mockResolvedValue(opts?.scopeResult ?? allowedScope()),
|
||||
};
|
||||
const query = {
|
||||
evaluateReadAccess: vi.fn(),
|
||||
list: vi.fn().mockResolvedValue(
|
||||
opts?.queryResult ?? {
|
||||
items: [
|
||||
{
|
||||
id: 'task-1',
|
||||
title: 'Federated task',
|
||||
createdAt: new Date('2026-06-24T00:00:00.000Z'),
|
||||
},
|
||||
],
|
||||
truncated: false,
|
||||
},
|
||||
),
|
||||
};
|
||||
|
||||
return {
|
||||
controller: new ListController(scope as never, query as never),
|
||||
scope,
|
||||
query,
|
||||
};
|
||||
}
|
||||
|
||||
describe('ListController', () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it('declares POST /api/federation/v1/list/:resource protected only by FederationAuthGuard', () => {
|
||||
expect(Reflect.getMetadata('path', ListController)).toBe('api/federation/v1/list');
|
||||
expect(Reflect.getMetadata('path', ListController.prototype.list)).toBe(':resource');
|
||||
expect(Reflect.getMetadata('method', ListController.prototype.list)).toBe(RequestMethod.POST);
|
||||
expect(Reflect.getMetadata('__guards__', ListController)).toEqual([FederationAuthGuard]);
|
||||
});
|
||||
|
||||
it('runs AuthGuard context through ScopeService and returns local-source tagged rows', async () => {
|
||||
const { controller, scope, query } = makeController();
|
||||
|
||||
const response = await controller.list('tasks', makeRequest(), { limit: 10 });
|
||||
|
||||
expect(scope.evaluateAccess).toHaveBeenCalledWith({
|
||||
context: FEDERATION_CONTEXT,
|
||||
resource: 'tasks',
|
||||
requestedLimit: 10,
|
||||
nativeRbac: query,
|
||||
});
|
||||
expect(query.list).toHaveBeenCalledWith({ filter: TASK_FILTER, cursor: undefined });
|
||||
expect(response).toEqual({
|
||||
items: [
|
||||
{
|
||||
id: 'task-1',
|
||||
title: 'Federated task',
|
||||
createdAt: new Date('2026-06-24T00:00:00.000Z'),
|
||||
_source: 'local',
|
||||
},
|
||||
],
|
||||
});
|
||||
});
|
||||
|
||||
it('preserves pagination metadata when row cap truncates the query layer result', async () => {
|
||||
const { controller } = makeController({
|
||||
queryResult: {
|
||||
items: [{ id: 'task-1' }],
|
||||
nextCursor: 'cursor-2',
|
||||
truncated: true,
|
||||
},
|
||||
});
|
||||
|
||||
const response = await controller.list('tasks', makeRequest(), { cursor: 'cursor-1' });
|
||||
|
||||
expect(response).toEqual({
|
||||
items: [{ id: 'task-1', _source: 'local' }],
|
||||
nextCursor: 'cursor-2',
|
||||
_truncated: true,
|
||||
});
|
||||
});
|
||||
|
||||
it('returns a federation error envelope when auth guard context is missing', async () => {
|
||||
const { controller, scope, query } = makeController();
|
||||
|
||||
await expect(
|
||||
controller.list('tasks', {} as unknown as FastifyRequest, {}),
|
||||
).rejects.toMatchObject({
|
||||
response: {
|
||||
error: {
|
||||
code: 'unauthorized',
|
||||
message: 'Federation context missing',
|
||||
},
|
||||
},
|
||||
status: 401,
|
||||
});
|
||||
expect(scope.evaluateAccess).not.toHaveBeenCalled();
|
||||
expect(query.list).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('returns a federation error envelope when scope evaluation denies access', async () => {
|
||||
const { controller, query } = makeController({
|
||||
scopeResult: {
|
||||
allowed: false,
|
||||
deny: {
|
||||
code: 'resource_excluded',
|
||||
stage: 'resource_exclusion',
|
||||
statusCode: 403,
|
||||
message: 'Requested federation resource is explicitly excluded by grant scope',
|
||||
grantId: 'grant-1',
|
||||
peerId: 'peer-1',
|
||||
subjectUserId: 'user-1',
|
||||
resource: 'credentials',
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
await expect(controller.list('credentials', makeRequest(), {})).rejects.toMatchObject({
|
||||
response: {
|
||||
error: {
|
||||
code: 'scope_violation',
|
||||
message: 'Requested federation resource is explicitly excluded by grant scope',
|
||||
},
|
||||
},
|
||||
status: 403,
|
||||
});
|
||||
expect(query.list).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('rejects malformed request body fields before querying storage', async () => {
|
||||
const { controller, scope, query } = makeController();
|
||||
|
||||
await expect(controller.list('tasks', makeRequest(), { cursor: 123 })).rejects.toMatchObject({
|
||||
response: { error: { code: 'invalid_request' } },
|
||||
status: 400,
|
||||
});
|
||||
await expect(controller.list('tasks', makeRequest(), { limit: false })).rejects.toMatchObject({
|
||||
response: { error: { code: 'invalid_request' } },
|
||||
status: 400,
|
||||
});
|
||||
await expect(controller.list('tasks', makeRequest(), { limit: 'abc' })).rejects.toMatchObject({
|
||||
response: { error: { code: 'invalid_request' } },
|
||||
status: 400,
|
||||
});
|
||||
expect(scope.evaluateAccess).not.toHaveBeenCalled();
|
||||
expect(query.list).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
@@ -1,38 +0,0 @@
|
||||
/**
|
||||
* Federation capabilities verb (FED-M3-07).
|
||||
*
|
||||
* Returns the read-only capability envelope for the active grant attached by
|
||||
* FederationAuthGuard. This endpoint intentionally does not invoke native RBAC
|
||||
* or ScopeService: an active grant is enough to ask what the grant allows.
|
||||
*/
|
||||
|
||||
import { Controller, Get, Req, UseGuards } from '@nestjs/common';
|
||||
import type { FastifyRequest } from 'fastify';
|
||||
import {
|
||||
FEDERATION_VERBS,
|
||||
type FederationCapabilitiesResponse,
|
||||
type FederationVerb,
|
||||
} from '@mosaicstack/types';
|
||||
import { parseFederationScope } from '../../scope-schema.js';
|
||||
import { FederationAuthGuard } from '../federation-auth.guard.js';
|
||||
import '../federation-context.js';
|
||||
|
||||
@Controller('api/federation/v1/capabilities')
|
||||
@UseGuards(FederationAuthGuard)
|
||||
export class CapabilitiesController {
|
||||
@Get()
|
||||
getCapabilities(@Req() request: FastifyRequest): FederationCapabilitiesResponse {
|
||||
if (!request.federationContext) {
|
||||
throw new Error('Federation context missing after auth guard');
|
||||
}
|
||||
|
||||
const scope = parseFederationScope(request.federationContext.scope);
|
||||
|
||||
return {
|
||||
resources: [...scope.resources],
|
||||
excluded_resources: [...scope.excluded_resources],
|
||||
max_rows_per_query: scope.max_rows_per_query,
|
||||
supported_verbs: [...FEDERATION_VERBS] satisfies FederationVerb[],
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -1,408 +0,0 @@
|
||||
/**
|
||||
* Federation list query layer (FED-M3-05).
|
||||
*
|
||||
* Read-only DB adapter used by ListController after FederationAuthGuard and
|
||||
* FederationScopeService have established the subject user, allowed resource,
|
||||
* native-RBAC intersection, and row cap. Audit writes are intentionally
|
||||
* deferred to M4.
|
||||
*/
|
||||
|
||||
import { Inject, Injectable } from '@nestjs/common';
|
||||
import {
|
||||
and,
|
||||
desc,
|
||||
eq,
|
||||
inArray,
|
||||
insights,
|
||||
isNotNull,
|
||||
lt,
|
||||
missionTasks,
|
||||
missions,
|
||||
or,
|
||||
preferences,
|
||||
projects,
|
||||
tasks,
|
||||
teamMembers,
|
||||
type Db,
|
||||
} from '@mosaicstack/db';
|
||||
import type {
|
||||
FederationNativeRbacEvaluator,
|
||||
FederationNativeRbacRequest,
|
||||
FederationNativeRbacResult,
|
||||
FederationScopeQueryFilter,
|
||||
} from '../scope.service.js';
|
||||
import { DB } from '../../../database/database.module.js';
|
||||
|
||||
export interface FederationListQueryRequest {
|
||||
readonly filter: FederationScopeQueryFilter;
|
||||
readonly cursor?: string;
|
||||
}
|
||||
|
||||
export interface FederationListQueryResult<T extends object = Record<string, unknown>> {
|
||||
readonly items: T[];
|
||||
readonly nextCursor?: string;
|
||||
readonly truncated: boolean;
|
||||
}
|
||||
|
||||
type CursorSource = 'insights' | 'preferences';
|
||||
const CURSOR_SOURCE = Symbol('federationCursorSource');
|
||||
|
||||
type RowObject = Record<string, unknown> & { readonly [CURSOR_SOURCE]?: CursorSource };
|
||||
|
||||
interface KeysetCursor {
|
||||
readonly createdAt: Date;
|
||||
readonly id: string;
|
||||
readonly source?: CursorSource;
|
||||
}
|
||||
|
||||
function encodeCursor(row: RowObject): string {
|
||||
const createdAt = row['createdAt'];
|
||||
const id = row['id'];
|
||||
if (!(createdAt instanceof Date) || typeof id !== 'string') {
|
||||
throw new Error('Federation list cursor cannot be encoded');
|
||||
}
|
||||
|
||||
const source = row[CURSOR_SOURCE];
|
||||
return Buffer.from(
|
||||
JSON.stringify({ createdAt: createdAt.toISOString(), id, ...(source ? { source } : {}) }),
|
||||
'utf8',
|
||||
).toString('base64url');
|
||||
}
|
||||
|
||||
function decodeCursor(cursor: string | undefined): KeysetCursor | undefined {
|
||||
if (cursor === undefined) {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
try {
|
||||
const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as unknown;
|
||||
if (typeof parsed !== 'object' || parsed === null) {
|
||||
throw new Error('cursor must be an object');
|
||||
}
|
||||
|
||||
const { createdAt, id, source } = parsed as {
|
||||
createdAt?: unknown;
|
||||
id?: unknown;
|
||||
source?: unknown;
|
||||
};
|
||||
if (typeof createdAt !== 'string' || typeof id !== 'string' || id.length === 0) {
|
||||
throw new Error('cursor is missing createdAt or id');
|
||||
}
|
||||
if (source !== undefined && source !== 'insights' && source !== 'preferences') {
|
||||
throw new Error('cursor source is invalid');
|
||||
}
|
||||
|
||||
const date = new Date(createdAt);
|
||||
if (Number.isNaN(date.getTime())) {
|
||||
throw new Error('cursor createdAt is invalid');
|
||||
}
|
||||
|
||||
return { createdAt: date, id, ...(source ? { source } : {}) };
|
||||
} catch {
|
||||
throw new Error('Invalid federation list cursor');
|
||||
}
|
||||
}
|
||||
|
||||
function paginate<T extends RowObject>(rows: T[], limit: number): FederationListQueryResult<T> {
|
||||
const page = rows.slice(0, limit);
|
||||
const hasMore = rows.length > limit;
|
||||
const nextCursor = hasMore ? encodeCursor(page[page.length - 1] ?? {}) : undefined;
|
||||
|
||||
return {
|
||||
items: page,
|
||||
truncated: hasMore,
|
||||
...(nextCursor !== undefined ? { nextCursor } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
function markCursorSource<T extends RowObject>(row: T, source: CursorSource): T {
|
||||
Object.defineProperty(row, CURSOR_SOURCE, {
|
||||
value: source,
|
||||
enumerable: false,
|
||||
configurable: false,
|
||||
});
|
||||
return row;
|
||||
}
|
||||
|
||||
function sortRows(rows: RowObject[]): RowObject[] {
|
||||
return [...rows].sort((a, b) => {
|
||||
const aTime = a['createdAt'] instanceof Date ? a['createdAt'].getTime() : 0;
|
||||
const bTime = b['createdAt'] instanceof Date ? b['createdAt'].getTime() : 0;
|
||||
if (aTime !== bTime) {
|
||||
return bTime - aTime;
|
||||
}
|
||||
return String(b['id'] ?? '').localeCompare(String(a['id'] ?? ''));
|
||||
});
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class FederationListQueryService implements FederationNativeRbacEvaluator {
|
||||
constructor(@Inject(DB) private readonly db: Db) {}
|
||||
|
||||
async evaluateReadAccess(
|
||||
request: FederationNativeRbacRequest,
|
||||
): Promise<FederationNativeRbacResult> {
|
||||
if (request.resource === 'credentials' || request.resource === 'api_keys') {
|
||||
return {
|
||||
allowed: false,
|
||||
reason: `${request.resource} federation list access is not implemented in M3`,
|
||||
details: { resource: request.resource },
|
||||
};
|
||||
}
|
||||
|
||||
if (request.resource === 'memory') {
|
||||
return { allowed: true, access: { includePersonal: true, teamIds: [] } };
|
||||
}
|
||||
|
||||
const teamIds = await this.listSubjectTeamIds(request.subjectUserId);
|
||||
return { allowed: true, access: { includePersonal: true, teamIds } };
|
||||
}
|
||||
|
||||
async list<T extends RowObject = RowObject>(
|
||||
request: FederationListQueryRequest,
|
||||
): Promise<FederationListQueryResult<T>> {
|
||||
const cursor = decodeCursor(request.cursor);
|
||||
const rows = await this.listAllRows(request.filter, request.filter.limit + 1, cursor);
|
||||
return paginate(rows as T[], request.filter.limit);
|
||||
}
|
||||
|
||||
private async listAllRows(
|
||||
filter: FederationScopeQueryFilter,
|
||||
rowLimit: number,
|
||||
cursor: KeysetCursor | undefined,
|
||||
): Promise<RowObject[]> {
|
||||
switch (filter.resource) {
|
||||
case 'tasks':
|
||||
return this.listTasks(filter, rowLimit, cursor);
|
||||
case 'notes':
|
||||
return this.listNotes(filter, rowLimit, cursor);
|
||||
case 'memory':
|
||||
return this.listMemory(filter, rowLimit, cursor);
|
||||
case 'credentials':
|
||||
case 'api_keys':
|
||||
return [];
|
||||
default:
|
||||
throw new Error(`Unsupported federation list resource: ${String(filter.resource)}`);
|
||||
}
|
||||
}
|
||||
|
||||
private async listSubjectTeamIds(subjectUserId: string): Promise<string[]> {
|
||||
const rows = await this.db
|
||||
.select({ teamId: teamMembers.teamId })
|
||||
.from(teamMembers)
|
||||
.where(eq(teamMembers.userId, subjectUserId));
|
||||
|
||||
return rows.map((row) => row.teamId);
|
||||
}
|
||||
|
||||
private async listAccessibleProjectIds(filter: FederationScopeQueryFilter): Promise<string[]> {
|
||||
const clauses = [];
|
||||
if (filter.includePersonal) {
|
||||
clauses.push(and(eq(projects.ownerType, 'user'), eq(projects.ownerId, filter.subjectUserId)));
|
||||
}
|
||||
if (filter.teamIds.length > 0) {
|
||||
clauses.push(
|
||||
and(eq(projects.ownerType, 'team'), inArray(projects.teamId, [...filter.teamIds])),
|
||||
);
|
||||
}
|
||||
|
||||
if (clauses.length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const rows = await this.db
|
||||
.select({ id: projects.id })
|
||||
.from(projects)
|
||||
.where(clauses.length === 1 ? clauses[0] : or(...clauses));
|
||||
|
||||
return rows.map((row) => row.id);
|
||||
}
|
||||
|
||||
private async listMissionIds(projectIds: readonly string[]): Promise<string[]> {
|
||||
if (projectIds.length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const rows = await this.db
|
||||
.select({ id: missions.id })
|
||||
.from(missions)
|
||||
.where(inArray(missions.projectId, [...projectIds]));
|
||||
|
||||
return rows.map((row) => row.id);
|
||||
}
|
||||
|
||||
private async listTasks(
|
||||
filter: FederationScopeQueryFilter,
|
||||
rowLimit: number,
|
||||
cursor: KeysetCursor | undefined,
|
||||
): Promise<RowObject[]> {
|
||||
const projectIds = await this.listAccessibleProjectIds(filter);
|
||||
const missionIds = await this.listMissionIds(projectIds);
|
||||
const clauses = [];
|
||||
|
||||
if (projectIds.length > 0) {
|
||||
clauses.push(inArray(tasks.projectId, projectIds));
|
||||
}
|
||||
if (missionIds.length > 0) {
|
||||
clauses.push(inArray(tasks.missionId, missionIds));
|
||||
}
|
||||
|
||||
if (clauses.length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const scopeClause = clauses.length === 1 ? clauses[0] : or(...clauses);
|
||||
const cursorClause = cursor
|
||||
? or(
|
||||
lt(tasks.createdAt, cursor.createdAt),
|
||||
and(eq(tasks.createdAt, cursor.createdAt), lt(tasks.id, cursor.id)),
|
||||
)
|
||||
: undefined;
|
||||
|
||||
const rows = await this.db
|
||||
.select({
|
||||
id: tasks.id,
|
||||
title: tasks.title,
|
||||
description: tasks.description,
|
||||
status: tasks.status,
|
||||
priority: tasks.priority,
|
||||
projectId: tasks.projectId,
|
||||
missionId: tasks.missionId,
|
||||
assignee: tasks.assignee,
|
||||
tags: tasks.tags,
|
||||
dueDate: tasks.dueDate,
|
||||
metadata: tasks.metadata,
|
||||
createdAt: tasks.createdAt,
|
||||
updatedAt: tasks.updatedAt,
|
||||
})
|
||||
.from(tasks)
|
||||
.where(and(scopeClause, cursorClause))
|
||||
.orderBy(desc(tasks.createdAt), desc(tasks.id))
|
||||
.limit(rowLimit);
|
||||
|
||||
return sortRows(rows as RowObject[]);
|
||||
}
|
||||
|
||||
private async listNotes(
|
||||
filter: FederationScopeQueryFilter,
|
||||
rowLimit: number,
|
||||
cursor: KeysetCursor | undefined,
|
||||
): Promise<RowObject[]> {
|
||||
const projectIds = await this.listAccessibleProjectIds(filter);
|
||||
const missionIds = await this.listMissionIds(projectIds);
|
||||
|
||||
if (missionIds.length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
// mission_tasks rows are user-scoped even when the mission belongs to a team.
|
||||
// Team visibility can narrow the mission set, but it must never widen the
|
||||
// query to other users' mission task notes.
|
||||
const scopeClause = and(
|
||||
eq(missionTasks.userId, filter.subjectUserId),
|
||||
inArray(missionTasks.missionId, missionIds),
|
||||
);
|
||||
const cursorClause = cursor
|
||||
? or(
|
||||
lt(missionTasks.createdAt, cursor.createdAt),
|
||||
and(eq(missionTasks.createdAt, cursor.createdAt), lt(missionTasks.id, cursor.id)),
|
||||
)
|
||||
: undefined;
|
||||
|
||||
const rows = await this.db
|
||||
.select({
|
||||
id: missionTasks.id,
|
||||
missionId: missionTasks.missionId,
|
||||
taskId: missionTasks.taskId,
|
||||
status: missionTasks.status,
|
||||
content: missionTasks.notes,
|
||||
createdAt: missionTasks.createdAt,
|
||||
updatedAt: missionTasks.updatedAt,
|
||||
})
|
||||
.from(missionTasks)
|
||||
.where(and(scopeClause, cursorClause, isNotNull(missionTasks.notes)))
|
||||
.orderBy(desc(missionTasks.createdAt), desc(missionTasks.id))
|
||||
.limit(rowLimit);
|
||||
|
||||
return sortRows(rows.filter((row) => row.content !== '') as RowObject[]);
|
||||
}
|
||||
|
||||
private async listMemory(
|
||||
filter: FederationScopeQueryFilter,
|
||||
rowLimit: number,
|
||||
cursor: KeysetCursor | undefined,
|
||||
): Promise<RowObject[]> {
|
||||
if (!filter.includePersonal) {
|
||||
return [];
|
||||
}
|
||||
if (cursor && cursor.source === undefined) {
|
||||
throw new Error('Invalid federation list cursor');
|
||||
}
|
||||
|
||||
const rows: RowObject[] = [];
|
||||
|
||||
// Memory spans two physical tables. To keep pagination deterministic and
|
||||
// resumable without a SQL UNION, M3 emits a fixed block order: all insights
|
||||
// first, then preferences. The opaque cursor records which table produced
|
||||
// the boundary row, so the next page never re-applies one table's keyset to
|
||||
// the other table (which could duplicate/skip rows at equal timestamps).
|
||||
if (cursor?.source !== 'preferences') {
|
||||
const insightCursorClause = cursor
|
||||
? or(
|
||||
lt(insights.createdAt, cursor.createdAt),
|
||||
and(eq(insights.createdAt, cursor.createdAt), lt(insights.id, cursor.id)),
|
||||
)
|
||||
: undefined;
|
||||
const insightRows = await this.db
|
||||
.select({
|
||||
id: insights.id,
|
||||
kind: insights.source,
|
||||
content: insights.content,
|
||||
category: insights.category,
|
||||
relevanceScore: insights.relevanceScore,
|
||||
metadata: insights.metadata,
|
||||
createdAt: insights.createdAt,
|
||||
updatedAt: insights.updatedAt,
|
||||
})
|
||||
.from(insights)
|
||||
.where(and(eq(insights.userId, filter.subjectUserId), insightCursorClause))
|
||||
.orderBy(desc(insights.createdAt), desc(insights.id))
|
||||
.limit(rowLimit);
|
||||
|
||||
rows.push(...(insightRows as RowObject[]).map((row) => markCursorSource(row, 'insights')));
|
||||
}
|
||||
|
||||
const remaining = rowLimit - rows.length;
|
||||
if (remaining <= 0) {
|
||||
return rows;
|
||||
}
|
||||
|
||||
const preferenceCursorClause =
|
||||
cursor?.source === 'preferences'
|
||||
? or(
|
||||
lt(preferences.createdAt, cursor.createdAt),
|
||||
and(eq(preferences.createdAt, cursor.createdAt), lt(preferences.id, cursor.id)),
|
||||
)
|
||||
: undefined;
|
||||
const preferenceRows = await this.db
|
||||
.select({
|
||||
id: preferences.id,
|
||||
kind: preferences.category,
|
||||
key: preferences.key,
|
||||
value: preferences.value,
|
||||
source: preferences.source,
|
||||
mutable: preferences.mutable,
|
||||
createdAt: preferences.createdAt,
|
||||
updatedAt: preferences.updatedAt,
|
||||
})
|
||||
.from(preferences)
|
||||
.where(and(eq(preferences.userId, filter.subjectUserId), preferenceCursorClause))
|
||||
.orderBy(desc(preferences.createdAt), desc(preferences.id))
|
||||
.limit(remaining);
|
||||
|
||||
rows.push(
|
||||
...(preferenceRows as RowObject[]).map((row) => markCursorSource(row, 'preferences')),
|
||||
);
|
||||
return rows;
|
||||
}
|
||||
}
|
||||
@@ -1,147 +0,0 @@
|
||||
/**
|
||||
* Federation list verb (FED-M3-05).
|
||||
*
|
||||
* POST /api/federation/v1/list/:resource
|
||||
*
|
||||
* Pipeline: FederationAuthGuard attaches the active grant context, then
|
||||
* FederationScopeService enforces grant scope + native RBAC intersection, then
|
||||
* the read-only query layer returns capped rows tagged with `_source`. Read
|
||||
* audit-log writes are deferred to M4; this controller does not persist request
|
||||
* or response bodies.
|
||||
*/
|
||||
|
||||
import {
|
||||
Body,
|
||||
Controller,
|
||||
HttpException,
|
||||
Inject,
|
||||
Param,
|
||||
Post,
|
||||
Req,
|
||||
UseGuards,
|
||||
} from '@nestjs/common';
|
||||
import type { FastifyRequest } from 'fastify';
|
||||
import {
|
||||
FederationInvalidRequestError,
|
||||
FederationScopeViolationError,
|
||||
FederationUnauthorizedError,
|
||||
SOURCE_LOCAL,
|
||||
tagWithSource,
|
||||
type FederationListResponse,
|
||||
type SourceTag,
|
||||
} from '@mosaicstack/types';
|
||||
import { FederationAuthGuard } from '../federation-auth.guard.js';
|
||||
import '../federation-context.js';
|
||||
import { FederationScopeService } from '../scope.service.js';
|
||||
import { FederationListQueryService } from './list-query.service.js';
|
||||
|
||||
interface FederationListRequestBody {
|
||||
readonly limit?: unknown;
|
||||
readonly cursor?: unknown;
|
||||
}
|
||||
|
||||
type FederatedRow = Record<string, unknown> & SourceTag;
|
||||
|
||||
function parseLimit(body: FederationListRequestBody | undefined): number | undefined {
|
||||
if (body?.limit === undefined) {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
const parsed =
|
||||
typeof body.limit === 'number'
|
||||
? body.limit
|
||||
: typeof body.limit === 'string' && body.limit.trim().length > 0
|
||||
? Number(body.limit)
|
||||
: Number.NaN;
|
||||
|
||||
if (!Number.isSafeInteger(parsed) || parsed < 1) {
|
||||
throw new HttpException(
|
||||
new FederationInvalidRequestError(
|
||||
'Federation list limit must be a positive integer',
|
||||
).toEnvelope(),
|
||||
400,
|
||||
);
|
||||
}
|
||||
|
||||
return parsed;
|
||||
}
|
||||
|
||||
function parseCursor(body: FederationListRequestBody | undefined): string | undefined {
|
||||
if (body?.cursor === undefined) {
|
||||
return undefined;
|
||||
}
|
||||
if (typeof body.cursor === 'string') {
|
||||
return body.cursor;
|
||||
}
|
||||
throw new HttpException(
|
||||
new FederationInvalidRequestError('Federation list cursor must be a string').toEnvelope(),
|
||||
400,
|
||||
);
|
||||
}
|
||||
|
||||
@Controller('api/federation/v1/list')
|
||||
@UseGuards(FederationAuthGuard)
|
||||
export class ListController {
|
||||
constructor(
|
||||
@Inject(FederationScopeService) private readonly scope: FederationScopeService,
|
||||
@Inject(FederationListQueryService) private readonly query: FederationListQueryService,
|
||||
) {}
|
||||
|
||||
@Post(':resource')
|
||||
async list(
|
||||
@Param('resource') resource: string,
|
||||
@Req() request: FastifyRequest,
|
||||
@Body() body?: FederationListRequestBody,
|
||||
): Promise<FederationListResponse<FederatedRow>> {
|
||||
if (!request.federationContext) {
|
||||
throw new HttpException(
|
||||
new FederationUnauthorizedError('Federation context missing').toEnvelope(),
|
||||
401,
|
||||
);
|
||||
}
|
||||
|
||||
const requestedLimit = parseLimit(body);
|
||||
const cursor = parseCursor(body);
|
||||
const scopeResult = await this.scope.evaluateAccess({
|
||||
context: request.federationContext,
|
||||
resource,
|
||||
requestedLimit,
|
||||
nativeRbac: this.query,
|
||||
});
|
||||
|
||||
if (!scopeResult.allowed) {
|
||||
const ErrorClass =
|
||||
scopeResult.deny.statusCode === 400
|
||||
? FederationInvalidRequestError
|
||||
: FederationScopeViolationError;
|
||||
throw new HttpException(
|
||||
new ErrorClass(scopeResult.deny.message, scopeResult.deny).toEnvelope(),
|
||||
scopeResult.deny.statusCode,
|
||||
);
|
||||
}
|
||||
|
||||
let result: Awaited<ReturnType<FederationListQueryService['list']>>;
|
||||
try {
|
||||
result = await this.query.list({ filter: scopeResult.filter, cursor });
|
||||
} catch (error: unknown) {
|
||||
if (error instanceof Error && error.message === 'Invalid federation list cursor') {
|
||||
throw new HttpException(
|
||||
new FederationInvalidRequestError('Federation list cursor is invalid').toEnvelope(),
|
||||
400,
|
||||
);
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
|
||||
const response: FederationListResponse<FederatedRow> = {
|
||||
items: tagWithSource(result.items, SOURCE_LOCAL),
|
||||
};
|
||||
if (result.nextCursor !== undefined) {
|
||||
response.nextCursor = result.nextCursor;
|
||||
}
|
||||
if (result.truncated) {
|
||||
response._truncated = true;
|
||||
}
|
||||
return response;
|
||||
}
|
||||
}
|
||||
@@ -3,11 +3,7 @@ import { Logger } from '@nestjs/common';
|
||||
import { fromNodeHeaders } from 'better-auth/node';
|
||||
import type { Auth } from '@mosaicstack/auth';
|
||||
import type { NestFastifyApplication } from '@nestjs/platform-fastify';
|
||||
import {
|
||||
createMcpActorContext,
|
||||
deriveMcpToolScopesForUser,
|
||||
type McpService,
|
||||
} from './mcp.service.js';
|
||||
import type { McpService } from './mcp.service.js';
|
||||
import { AUTH } from '../auth/auth.tokens.js';
|
||||
|
||||
/**
|
||||
@@ -71,25 +67,14 @@ async function handleMcpRequest(
|
||||
return;
|
||||
}
|
||||
|
||||
const authUser = result.user as {
|
||||
id: string;
|
||||
role?: string | null;
|
||||
tenantId?: string | null;
|
||||
organizationId?: string | null;
|
||||
};
|
||||
const actor = createMcpActorContext({
|
||||
userId: authUser.id,
|
||||
role: authUser.role,
|
||||
tenantId: authUser.tenantId ?? authUser.organizationId ?? undefined,
|
||||
scopes: deriveMcpToolScopesForUser({ role: authUser.role }),
|
||||
});
|
||||
const userId = result.user.id;
|
||||
|
||||
// ─── Session routing ─────────────────────────────────────────────────────
|
||||
const sessionId = req.raw.headers['mcp-session-id'];
|
||||
|
||||
if (typeof sessionId === 'string' && sessionId.length > 0) {
|
||||
// Existing session request
|
||||
const transport = mcpService.getSession(sessionId, actor);
|
||||
const transport = mcpService.getSession(sessionId);
|
||||
if (!transport) {
|
||||
logger.warn(`MCP session not found: ${sessionId}`);
|
||||
reply.raw.writeHead(404, { 'Content-Type': 'application/json' });
|
||||
@@ -127,10 +112,8 @@ async function handleMcpRequest(
|
||||
}
|
||||
|
||||
// Create new session and handle this initializing request
|
||||
const { transport } = mcpService.createSession(actor);
|
||||
logger.log(
|
||||
`New MCP session created for actor=${actor.userId} tenant=${actor.tenantId} correlation=${actor.correlationId}`,
|
||||
);
|
||||
const { transport } = mcpService.createSession(userId);
|
||||
logger.log(`New MCP session created for user ${userId}`);
|
||||
|
||||
await transport.handleRequest(req.raw, reply.raw, body);
|
||||
}
|
||||
|
||||
@@ -1,461 +0,0 @@
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import type { z } from 'zod';
|
||||
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
||||
import type { Brain } from '@mosaicstack/brain';
|
||||
import type { Memory } from '@mosaicstack/memory';
|
||||
import type { EmbeddingService } from '../memory/embedding.service.js';
|
||||
import type { CoordService } from '../coord/coord.service.js';
|
||||
import {
|
||||
assertMcpToolAuthorized,
|
||||
createMcpActorContext,
|
||||
deriveMcpToolScopesForUser,
|
||||
MCP_TOOL_SCOPES,
|
||||
McpService,
|
||||
type McpToolName,
|
||||
} from './mcp.service.js';
|
||||
|
||||
type ToolResult = { content: Array<{ type: 'text'; text: string }> };
|
||||
type ToolHandler = (params: Record<string, unknown>) => Promise<ToolResult>;
|
||||
|
||||
interface CapturedTool {
|
||||
inputSchema: z.ZodType;
|
||||
handler: ToolHandler;
|
||||
}
|
||||
|
||||
function makeCapturingServer(): { server: McpServer; tools: Map<string, CapturedTool> } {
|
||||
const tools = new Map<string, CapturedTool>();
|
||||
const server = {
|
||||
registerTool(name: string, config: { inputSchema: z.ZodType }, handler: ToolHandler): void {
|
||||
tools.set(name, { inputSchema: config.inputSchema, handler });
|
||||
},
|
||||
};
|
||||
return { server: server as unknown as McpServer, tools };
|
||||
}
|
||||
|
||||
function makeService(opts?: {
|
||||
projects?: Array<Record<string, unknown> & { id: string; ownerId?: string | null }>;
|
||||
missions?: Array<
|
||||
Record<string, unknown> & { id: string; projectId?: string | null; userId?: string | null }
|
||||
>;
|
||||
tasks?: Array<
|
||||
Record<string, unknown> & {
|
||||
id: string;
|
||||
projectId?: string | null;
|
||||
missionId?: string | null;
|
||||
status?: string;
|
||||
}
|
||||
>;
|
||||
}) {
|
||||
const projects = opts?.projects ?? [];
|
||||
const missions = opts?.missions ?? [];
|
||||
const tasks = opts?.tasks ?? [];
|
||||
const brain = {
|
||||
projects: {
|
||||
findAll: vi.fn(async () => projects),
|
||||
findById: vi.fn(async (id: string) => projects.find((project) => project.id === id) ?? null),
|
||||
},
|
||||
tasks: {
|
||||
findAll: vi.fn(async () => tasks),
|
||||
findById: vi.fn(async (id: string) => tasks.find((task) => task.id === id) ?? null),
|
||||
findByProject: vi.fn(async (projectId: string) =>
|
||||
tasks.filter((task) => task.projectId === projectId),
|
||||
),
|
||||
findByMission: vi.fn(async (missionId: string) =>
|
||||
tasks.filter((task) => task.missionId === missionId),
|
||||
),
|
||||
findByStatus: vi.fn(async (status: string) => tasks.filter((task) => task.status === status)),
|
||||
create: vi.fn(async (task: Record<string, unknown>) => ({ id: 'task-1', ...task })),
|
||||
update: vi.fn(async (id: string, updates: Record<string, unknown>) => ({ id, ...updates })),
|
||||
},
|
||||
missions: {
|
||||
findAll: vi.fn(async () => missions),
|
||||
findById: vi.fn(async (id: string) => missions.find((mission) => mission.id === id) ?? null),
|
||||
findByProject: vi.fn(async (projectId: string) =>
|
||||
missions.filter((mission) => mission.projectId === projectId),
|
||||
),
|
||||
},
|
||||
conversations: {
|
||||
findAll: vi.fn(async (userId: string) => [{ id: 'conversation-1', userId }]),
|
||||
},
|
||||
} as unknown as Brain;
|
||||
|
||||
const memory = {
|
||||
insights: {
|
||||
searchByEmbedding: vi.fn(async (userId: string) => [{ id: 'insight-1', userId }]),
|
||||
create: vi.fn(async (insight: Record<string, unknown>) => ({ id: 'insight-2', ...insight })),
|
||||
},
|
||||
preferences: {
|
||||
findByUser: vi.fn(async (userId: string) => [{ key: 'theme', userId }]),
|
||||
findByUserAndCategory: vi.fn(async (userId: string, category: string) => [
|
||||
{ key: 'theme', userId, category },
|
||||
]),
|
||||
upsert: vi.fn(async (preference: Record<string, unknown>) => ({
|
||||
id: 'pref-1',
|
||||
...preference,
|
||||
})),
|
||||
},
|
||||
} as unknown as Memory;
|
||||
|
||||
const embeddings = {
|
||||
available: true,
|
||||
embed: vi.fn(async () => [0.1, 0.2, 0.3]),
|
||||
} as unknown as EmbeddingService;
|
||||
|
||||
const coord = {
|
||||
getMissionStatus: vi.fn(async () => null),
|
||||
listTasks: vi.fn(async () => []),
|
||||
getTaskStatus: vi.fn(async () => null),
|
||||
} as unknown as CoordService;
|
||||
|
||||
return {
|
||||
service: new McpService(brain, memory, embeddings, coord),
|
||||
brain: brain as unknown as {
|
||||
conversations: { findAll: ReturnType<typeof vi.fn> };
|
||||
tasks: {
|
||||
create: ReturnType<typeof vi.fn>;
|
||||
update: ReturnType<typeof vi.fn>;
|
||||
};
|
||||
},
|
||||
memory: memory as unknown as {
|
||||
insights: { searchByEmbedding: ReturnType<typeof vi.fn> };
|
||||
},
|
||||
coord: coord as unknown as {
|
||||
listTasks: ReturnType<typeof vi.fn>;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function getTool(tools: Map<string, CapturedTool>, name: McpToolName): CapturedTool {
|
||||
const tool = tools.get(name);
|
||||
if (!tool) throw new Error(`Missing captured tool ${name}`);
|
||||
return tool;
|
||||
}
|
||||
|
||||
function makeMemberActor(userId = 'authenticated-user') {
|
||||
return createMcpActorContext({
|
||||
userId,
|
||||
role: 'member',
|
||||
scopes: deriveMcpToolScopesForUser({ role: 'member' }),
|
||||
});
|
||||
}
|
||||
|
||||
function makeAdminActor(userId = 'admin-user', tenantId?: string) {
|
||||
return createMcpActorContext({
|
||||
userId,
|
||||
tenantId,
|
||||
role: 'admin',
|
||||
scopes: deriveMcpToolScopesForUser({ role: 'admin' }),
|
||||
});
|
||||
}
|
||||
|
||||
function makePlatformAdminActor(userId = 'platform-admin-user') {
|
||||
return createMcpActorContext({
|
||||
userId,
|
||||
role: 'platform-admin',
|
||||
scopes: deriveMcpToolScopesForUser({ role: 'platform-admin' }),
|
||||
});
|
||||
}
|
||||
|
||||
describe('MCP actor identity and tool scope enforcement', () => {
|
||||
it('derives immutable actor, tenant, channel, correlation, and explicit tool scopes server-side', () => {
|
||||
const actor = createMcpActorContext({
|
||||
userId: ' user-authenticated ',
|
||||
role: 'member',
|
||||
scopes: deriveMcpToolScopesForUser({ role: 'member' }),
|
||||
});
|
||||
|
||||
expect(actor.userId).toBe('user-authenticated');
|
||||
expect(actor.tenantId).toBe('user:user-authenticated');
|
||||
expect(actor.role).toBe('member');
|
||||
expect(actor.channel).toBe('mcp');
|
||||
expect(actor.correlationId).toMatch(/[0-9a-f-]{36}/i);
|
||||
expect(actor.scopes.has(MCP_TOOL_SCOPES.memory_search)).toBe(true);
|
||||
expect(actor.scopes.has(MCP_TOOL_SCOPES.coord_list_tasks)).toBe(false);
|
||||
expect(
|
||||
deriveMcpToolScopesForUser({ role: 'admin' }).has(MCP_TOOL_SCOPES.coord_list_tasks),
|
||||
).toBe(false);
|
||||
expect(
|
||||
deriveMcpToolScopesForUser({ role: 'platform-admin' }).has(MCP_TOOL_SCOPES.coord_list_tasks),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
it('fails closed when scopes are not supplied by the authenticated context policy', () => {
|
||||
const actor = createMcpActorContext({ userId: 'user-authenticated' });
|
||||
|
||||
expect(actor.scopes.size).toBe(0);
|
||||
expect(() => assertMcpToolAuthorized(actor, 'memory_search', { query: 'notes' })).toThrow(
|
||||
'MCP tool scope denied: memory:insight:read',
|
||||
);
|
||||
});
|
||||
|
||||
it('fails closed when a tool caller supplies actor or tenant identity fields', () => {
|
||||
const actor = createMcpActorContext({ userId: 'user-authenticated' });
|
||||
|
||||
expect(() =>
|
||||
assertMcpToolAuthorized(actor, 'memory_search', {
|
||||
userId: 'victim-user',
|
||||
query: 'private data',
|
||||
}),
|
||||
).toThrow('MCP caller-controlled identity field is forbidden: userId');
|
||||
|
||||
expect(() =>
|
||||
assertMcpToolAuthorized(actor, 'coord_list_tasks', {
|
||||
tenantId: 'victim-tenant',
|
||||
projectPath: '/tmp/project',
|
||||
}),
|
||||
).toThrow('MCP caller-controlled identity field is forbidden: tenantId');
|
||||
|
||||
expect(() =>
|
||||
assertMcpToolAuthorized(actor, 'brain_create_task', {
|
||||
title: 'forged org',
|
||||
organizationId: 'victim-org',
|
||||
}),
|
||||
).toThrow('MCP caller-controlled identity field is forbidden: organizationId');
|
||||
|
||||
expect(() =>
|
||||
assertMcpToolAuthorized(actor, 'brain_update_task', {
|
||||
title: 'forged team',
|
||||
teamId: 'victim-team',
|
||||
}),
|
||||
).toThrow('MCP caller-controlled identity field is forbidden: teamId');
|
||||
});
|
||||
|
||||
it('fails closed when the server-derived actor lacks the required per-tool scope', () => {
|
||||
const actor = createMcpActorContext({ userId: 'user-authenticated', scopes: [] });
|
||||
|
||||
expect(() => assertMcpToolAuthorized(actor, 'memory_search', { query: 'notes' })).toThrow(
|
||||
'MCP tool scope denied: memory:insight:read',
|
||||
);
|
||||
});
|
||||
|
||||
it('removes caller-controlled userId from memory schemas and never queries victim memory', async () => {
|
||||
const { service, memory } = makeService();
|
||||
const { server, tools } = makeCapturingServer();
|
||||
const actor = makeMemberActor('authenticated-user');
|
||||
|
||||
service.registerTools(server, actor);
|
||||
const tool = getTool(tools, 'memory_search');
|
||||
|
||||
expect(tool.inputSchema.safeParse({ userId: 'victim-user', query: 'anything' }).success).toBe(
|
||||
false,
|
||||
);
|
||||
await expect(tool.handler({ userId: 'victim-user', query: 'anything' })).rejects.toThrow(
|
||||
'MCP caller-controlled identity field is forbidden: userId',
|
||||
);
|
||||
expect(memory.insights.searchByEmbedding).not.toHaveBeenCalled();
|
||||
|
||||
await tool.handler({ query: 'only my notes' });
|
||||
expect(memory.insights.searchByEmbedding).toHaveBeenCalledWith(
|
||||
'authenticated-user',
|
||||
[0.1, 0.2, 0.3],
|
||||
5,
|
||||
);
|
||||
});
|
||||
|
||||
it('binds conversation listing to the authenticated actor instead of a caller-supplied userId', async () => {
|
||||
const { service, brain } = makeService();
|
||||
const { server, tools } = makeCapturingServer();
|
||||
const actor = makeMemberActor('authenticated-user');
|
||||
|
||||
service.registerTools(server, actor);
|
||||
const tool = getTool(tools, 'brain_list_conversations');
|
||||
|
||||
expect(tool.inputSchema.safeParse({ userId: 'victim-user' }).success).toBe(false);
|
||||
await expect(tool.handler({ userId: 'victim-user' })).rejects.toThrow(
|
||||
'MCP caller-controlled identity field is forbidden: userId',
|
||||
);
|
||||
expect(brain.conversations.findAll).not.toHaveBeenCalled();
|
||||
|
||||
await tool.handler({});
|
||||
expect(brain.conversations.findAll).toHaveBeenCalledWith('authenticated-user');
|
||||
});
|
||||
|
||||
it('scopes brain project, mission, and task reads to the authenticated actor', async () => {
|
||||
const { service } = makeService({
|
||||
projects: [
|
||||
{ id: 'project-owned', ownerId: 'authenticated-user', name: 'owned' },
|
||||
{ id: 'project-victim', ownerId: 'victim-user', name: 'victim' },
|
||||
],
|
||||
missions: [
|
||||
{ id: 'mission-owned', projectId: 'project-owned' },
|
||||
{ id: 'mission-victim', userId: 'victim-user', projectId: 'project-victim' },
|
||||
],
|
||||
tasks: [
|
||||
{ id: 'task-owned-project', projectId: 'project-owned', status: 'not-started' },
|
||||
{ id: 'task-owned-mission', missionId: 'mission-owned', status: 'not-started' },
|
||||
{ id: 'task-victim-project', projectId: 'project-victim', status: 'not-started' },
|
||||
{ id: 'task-unowned', status: 'not-started' },
|
||||
],
|
||||
});
|
||||
const { server, tools } = makeCapturingServer();
|
||||
const actor = makeMemberActor('authenticated-user');
|
||||
|
||||
service.registerTools(server, actor);
|
||||
|
||||
const projects = JSON.parse(
|
||||
(await getTool(tools, 'brain_list_projects').handler({})).content[0]!.text,
|
||||
);
|
||||
expect(projects.map((project: { id: string }) => project.id)).toEqual(['project-owned']);
|
||||
|
||||
const missions = JSON.parse(
|
||||
(await getTool(tools, 'brain_list_missions').handler({})).content[0]!.text,
|
||||
);
|
||||
expect(missions.map((mission: { id: string }) => mission.id)).toEqual(['mission-owned']);
|
||||
|
||||
const tasks = JSON.parse(
|
||||
(await getTool(tools, 'brain_list_tasks').handler({})).content[0]!.text,
|
||||
);
|
||||
expect(tasks.map((task: { id: string }) => task.id)).toEqual([
|
||||
'task-owned-project',
|
||||
'task-owned-mission',
|
||||
]);
|
||||
});
|
||||
|
||||
it('enforces tenant boundaries for tenant-admin brain project, mission, and task reads', async () => {
|
||||
const { service } = makeService({
|
||||
projects: [
|
||||
{
|
||||
id: 'project-tenant-a',
|
||||
ownerId: 'other-user-a',
|
||||
teamId: 'tenant-a',
|
||||
name: 'same tenant',
|
||||
},
|
||||
{
|
||||
id: 'project-tenant-b',
|
||||
ownerId: 'other-user-b',
|
||||
teamId: 'tenant-b',
|
||||
name: 'other tenant',
|
||||
},
|
||||
],
|
||||
missions: [
|
||||
{ id: 'mission-tenant-a', tenantId: 'tenant-a', projectId: 'project-tenant-a' },
|
||||
{ id: 'mission-tenant-b', tenantId: 'tenant-b', projectId: 'project-tenant-b' },
|
||||
],
|
||||
tasks: [
|
||||
{ id: 'task-tenant-a', projectId: 'project-tenant-a', status: 'not-started' },
|
||||
{ id: 'task-tenant-b', projectId: 'project-tenant-b', status: 'not-started' },
|
||||
],
|
||||
});
|
||||
const { server, tools } = makeCapturingServer();
|
||||
const actor = makeAdminActor('tenant-admin-user', 'tenant-a');
|
||||
|
||||
service.registerTools(server, actor);
|
||||
|
||||
const projects = JSON.parse(
|
||||
(await getTool(tools, 'brain_list_projects').handler({})).content[0]!.text,
|
||||
);
|
||||
expect(projects.map((project: { id: string }) => project.id)).toEqual(['project-tenant-a']);
|
||||
|
||||
const missions = JSON.parse(
|
||||
(await getTool(tools, 'brain_list_missions').handler({})).content[0]!.text,
|
||||
);
|
||||
expect(missions.map((mission: { id: string }) => mission.id)).toEqual(['mission-tenant-a']);
|
||||
|
||||
const tasks = JSON.parse(
|
||||
(await getTool(tools, 'brain_list_tasks').handler({})).content[0]!.text,
|
||||
);
|
||||
expect(tasks.map((task: { id: string }) => task.id)).toEqual(['task-tenant-a']);
|
||||
});
|
||||
|
||||
it('denies tenant-admin task writes outside the authenticated tenant', async () => {
|
||||
const { service, brain } = makeService({
|
||||
projects: [
|
||||
{ id: 'project-tenant-a', ownerId: 'other-user-a', teamId: 'tenant-a' },
|
||||
{ id: 'project-tenant-b', ownerId: 'other-user-b', teamId: 'tenant-b' },
|
||||
],
|
||||
missions: [
|
||||
{ id: 'mission-tenant-a', tenantId: 'tenant-a', projectId: 'project-tenant-a' },
|
||||
{ id: 'mission-tenant-b', tenantId: 'tenant-b', projectId: 'project-tenant-b' },
|
||||
],
|
||||
tasks: [
|
||||
{ id: 'task-tenant-a', projectId: 'project-tenant-a', status: 'not-started' },
|
||||
{ id: 'task-tenant-b', projectId: 'project-tenant-b', status: 'not-started' },
|
||||
],
|
||||
});
|
||||
const { server, tools } = makeCapturingServer();
|
||||
const actor = makeAdminActor('tenant-admin-user', 'tenant-a');
|
||||
|
||||
service.registerTools(server, actor);
|
||||
|
||||
await expect(
|
||||
getTool(tools, 'brain_create_task').handler({
|
||||
title: 'unscoped tenant write',
|
||||
}),
|
||||
).rejects.toThrow('MCP task scope denied');
|
||||
expect(brain.tasks.create).not.toHaveBeenCalled();
|
||||
|
||||
await expect(
|
||||
getTool(tools, 'brain_create_task').handler({
|
||||
title: 'cross-tenant write',
|
||||
projectId: 'project-tenant-b',
|
||||
}),
|
||||
).rejects.toThrow('MCP task project scope denied');
|
||||
expect(brain.tasks.create).not.toHaveBeenCalled();
|
||||
|
||||
await expect(
|
||||
getTool(tools, 'brain_update_task').handler({
|
||||
id: 'task-tenant-a',
|
||||
projectId: 'project-tenant-b',
|
||||
}),
|
||||
).rejects.toThrow('MCP task project scope denied');
|
||||
expect(brain.tasks.update).not.toHaveBeenCalled();
|
||||
|
||||
const updateResult = await getTool(tools, 'brain_update_task').handler({
|
||||
id: 'task-tenant-b',
|
||||
title: 'cross-tenant update',
|
||||
});
|
||||
expect(updateResult.content[0]!.text).toBe('Task not found: task-tenant-b');
|
||||
expect(brain.tasks.update).not.toHaveBeenCalled();
|
||||
|
||||
await getTool(tools, 'brain_create_task').handler({
|
||||
title: 'same-tenant write',
|
||||
projectId: 'project-tenant-a',
|
||||
});
|
||||
expect(brain.tasks.create).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ projectId: 'project-tenant-a', title: 'same-tenant write' }),
|
||||
);
|
||||
});
|
||||
|
||||
it('keeps admin-only coordination tools on server-derived paths', async () => {
|
||||
const { service, coord } = makeService();
|
||||
const { server, tools } = makeCapturingServer();
|
||||
const member = makeMemberActor('authenticated-user');
|
||||
const tenantAdmin = makeAdminActor('admin-user');
|
||||
const platformAdmin = makePlatformAdminActor('platform-admin-user');
|
||||
|
||||
service.registerTools(server, member);
|
||||
const memberTool = getTool(tools, 'coord_list_tasks');
|
||||
expect(memberTool.inputSchema.safeParse({ projectPath: '/tmp/victim' }).success).toBe(false);
|
||||
await expect(memberTool.handler({})).rejects.toThrow('MCP tool scope denied: coord:read');
|
||||
|
||||
tools.clear();
|
||||
service.registerTools(server, tenantAdmin);
|
||||
const tenantAdminTool = getTool(tools, 'coord_list_tasks');
|
||||
await expect(tenantAdminTool.handler({})).rejects.toThrow('MCP tool scope denied: coord:read');
|
||||
|
||||
tools.clear();
|
||||
service.registerTools(server, platformAdmin);
|
||||
const platformAdminTool = getTool(tools, 'coord_list_tasks');
|
||||
await platformAdminTool.handler({ projectPath: '/tmp/victim' });
|
||||
expect(coord.listTasks).toHaveBeenCalledWith(process.cwd());
|
||||
});
|
||||
|
||||
it('does not attach a guessed or stale-scope MCP session to another authenticated context', async () => {
|
||||
const { service } = makeService();
|
||||
const owner = makeMemberActor('owner-user');
|
||||
const attacker = makeMemberActor('attacker-user');
|
||||
const admin = makeAdminActor('admin-user');
|
||||
const downgradedAdmin = makeMemberActor('admin-user');
|
||||
|
||||
const { sessionId, transport } = service.createSession(owner);
|
||||
const staleSession = service.createSession(admin);
|
||||
|
||||
expect(service.getSession(sessionId, owner)).toBe(transport);
|
||||
expect(service.getSession(sessionId, attacker)).toBeNull();
|
||||
expect(service.getSession(sessionId, owner)).toBe(transport);
|
||||
expect(service.getSession(staleSession.sessionId, downgradedAdmin)).toBeNull();
|
||||
expect(service.getSession(staleSession.sessionId, admin)).toBe(staleSession.transport);
|
||||
|
||||
await service.onModuleDestroy();
|
||||
});
|
||||
});
|
||||
@@ -10,216 +10,11 @@ import { MEMORY } from '../memory/memory.tokens.js';
|
||||
import { EmbeddingService } from '../memory/embedding.service.js';
|
||||
import { CoordService } from '../coord/coord.service.js';
|
||||
|
||||
export const MCP_CALLER_IDENTITY_FIELDS = [
|
||||
'actorId',
|
||||
'actor',
|
||||
'authenticatedUserId',
|
||||
'channel',
|
||||
'organizationId',
|
||||
'ownerId',
|
||||
'sessionUserId',
|
||||
'teamId',
|
||||
'tenant',
|
||||
'tenantId',
|
||||
'user',
|
||||
'userId',
|
||||
] as const;
|
||||
|
||||
type McpCallerIdentityField = (typeof MCP_CALLER_IDENTITY_FIELDS)[number];
|
||||
|
||||
export const MCP_TOOL_SCOPES = {
|
||||
brain_list_projects: 'brain:project:read',
|
||||
brain_get_project: 'brain:project:read',
|
||||
brain_list_tasks: 'brain:task:read',
|
||||
brain_create_task: 'brain:task:write',
|
||||
brain_update_task: 'brain:task:write',
|
||||
brain_list_missions: 'brain:mission:read',
|
||||
brain_list_conversations: 'brain:conversation:read',
|
||||
memory_search: 'memory:insight:read',
|
||||
memory_get_preferences: 'memory:preference:read',
|
||||
memory_save_preference: 'memory:preference:write',
|
||||
memory_save_insight: 'memory:insight:write',
|
||||
coord_mission_status: 'coord:read',
|
||||
coord_list_tasks: 'coord:read',
|
||||
coord_task_detail: 'coord:read',
|
||||
} as const;
|
||||
|
||||
export type McpToolName = keyof typeof MCP_TOOL_SCOPES;
|
||||
export type McpToolScope = (typeof MCP_TOOL_SCOPES)[McpToolName];
|
||||
|
||||
export interface McpActorContext {
|
||||
userId: string;
|
||||
tenantId: string;
|
||||
role: string;
|
||||
channel: 'mcp';
|
||||
correlationId: string;
|
||||
scopes: ReadonlySet<McpToolScope>;
|
||||
}
|
||||
|
||||
interface SessionEntry {
|
||||
server: McpServer;
|
||||
transport: StreamableHTTPServerTransport;
|
||||
createdAt: Date;
|
||||
actor: McpActorContext;
|
||||
}
|
||||
|
||||
const GLOBAL_ADMIN_MCP_SCOPES = new Set<McpToolScope>(Object.values(MCP_TOOL_SCOPES));
|
||||
const TENANT_ADMIN_MCP_SCOPES = new Set<McpToolScope>([
|
||||
MCP_TOOL_SCOPES.brain_list_projects,
|
||||
MCP_TOOL_SCOPES.brain_get_project,
|
||||
MCP_TOOL_SCOPES.brain_list_tasks,
|
||||
MCP_TOOL_SCOPES.brain_create_task,
|
||||
MCP_TOOL_SCOPES.brain_update_task,
|
||||
MCP_TOOL_SCOPES.brain_list_missions,
|
||||
MCP_TOOL_SCOPES.brain_list_conversations,
|
||||
MCP_TOOL_SCOPES.memory_search,
|
||||
MCP_TOOL_SCOPES.memory_get_preferences,
|
||||
MCP_TOOL_SCOPES.memory_save_preference,
|
||||
MCP_TOOL_SCOPES.memory_save_insight,
|
||||
]);
|
||||
const MEMBER_MCP_SCOPES = new Set<McpToolScope>([
|
||||
MCP_TOOL_SCOPES.brain_list_projects,
|
||||
MCP_TOOL_SCOPES.brain_get_project,
|
||||
MCP_TOOL_SCOPES.brain_list_tasks,
|
||||
MCP_TOOL_SCOPES.brain_list_missions,
|
||||
MCP_TOOL_SCOPES.brain_list_conversations,
|
||||
MCP_TOOL_SCOPES.memory_search,
|
||||
MCP_TOOL_SCOPES.memory_get_preferences,
|
||||
MCP_TOOL_SCOPES.memory_save_preference,
|
||||
MCP_TOOL_SCOPES.memory_save_insight,
|
||||
]);
|
||||
|
||||
export function deriveMcpToolScopesForUser(input: {
|
||||
role?: string | null;
|
||||
}): ReadonlySet<McpToolScope> {
|
||||
if (input.role === 'platform-admin' || input.role === 'super-admin') {
|
||||
return new Set(GLOBAL_ADMIN_MCP_SCOPES);
|
||||
}
|
||||
if (input.role === 'admin') {
|
||||
return new Set(TENANT_ADMIN_MCP_SCOPES);
|
||||
}
|
||||
return new Set(MEMBER_MCP_SCOPES);
|
||||
}
|
||||
|
||||
export function createMcpActorContext(input: {
|
||||
userId: string;
|
||||
tenantId?: string;
|
||||
role?: string | null;
|
||||
scopes?: Iterable<McpToolScope>;
|
||||
correlationId?: string;
|
||||
}): McpActorContext {
|
||||
const userId = input.userId.trim();
|
||||
if (userId.length === 0) {
|
||||
throw new Error('MCP authenticated user is required');
|
||||
}
|
||||
|
||||
return {
|
||||
userId,
|
||||
tenantId: input.tenantId?.trim() || `user:${userId}`,
|
||||
role: input.role ?? 'member',
|
||||
channel: 'mcp',
|
||||
correlationId: input.correlationId ?? randomUUID(),
|
||||
scopes: new Set(input.scopes ?? []),
|
||||
};
|
||||
}
|
||||
|
||||
export function assertNoCallerControlledIdentity(params: unknown): void {
|
||||
if (params === null || typeof params !== 'object') return;
|
||||
|
||||
const keys = new Set(Object.keys(params));
|
||||
const forbidden = MCP_CALLER_IDENTITY_FIELDS.find((field: McpCallerIdentityField) =>
|
||||
keys.has(field),
|
||||
);
|
||||
if (forbidden) {
|
||||
throw new Error(`MCP caller-controlled identity field is forbidden: ${forbidden}`);
|
||||
}
|
||||
}
|
||||
|
||||
export function assertMcpToolAuthorized(
|
||||
actor: McpActorContext,
|
||||
toolName: McpToolName,
|
||||
params: unknown,
|
||||
): void {
|
||||
assertNoCallerControlledIdentity(params);
|
||||
const requiredScope = MCP_TOOL_SCOPES[toolName];
|
||||
if (!actor.scopes.has(requiredScope)) {
|
||||
throw new Error(`MCP tool scope denied: ${requiredScope}`);
|
||||
}
|
||||
}
|
||||
|
||||
function strictObject<T extends z.ZodRawShape>(shape: T): z.ZodObject<T> {
|
||||
return z.object(shape).strict();
|
||||
}
|
||||
|
||||
type TenantScopedLike = {
|
||||
tenantId?: string | null;
|
||||
organizationId?: string | null;
|
||||
teamId?: string | null;
|
||||
};
|
||||
type ProjectLike = TenantScopedLike & { id: string; ownerId?: string | null };
|
||||
type MissionLike = TenantScopedLike & {
|
||||
id: string;
|
||||
projectId?: string | null;
|
||||
userId?: string | null;
|
||||
};
|
||||
type TaskLike = TenantScopedLike & {
|
||||
projectId?: string | null;
|
||||
missionId?: string | null;
|
||||
userId?: string | null;
|
||||
};
|
||||
|
||||
function isGlobalAdminActor(actor: McpActorContext): boolean {
|
||||
return actor.role === 'platform-admin' || actor.role === 'super-admin';
|
||||
}
|
||||
|
||||
function isTenantAdminActor(actor: McpActorContext): boolean {
|
||||
return actor.role === 'admin';
|
||||
}
|
||||
|
||||
function matchesTenant(actor: McpActorContext, record: TenantScopedLike): boolean {
|
||||
return (
|
||||
record.tenantId === actor.tenantId ||
|
||||
record.organizationId === actor.tenantId ||
|
||||
record.teamId === actor.tenantId
|
||||
);
|
||||
}
|
||||
|
||||
function filterProjectsForActor<T extends ProjectLike>(actor: McpActorContext, projects: T[]): T[] {
|
||||
if (isGlobalAdminActor(actor)) return projects;
|
||||
return projects.filter(
|
||||
(project) =>
|
||||
project.ownerId === actor.userId ||
|
||||
(isTenantAdminActor(actor) && matchesTenant(actor, project)),
|
||||
);
|
||||
}
|
||||
|
||||
function filterMissionsByDirectActorScope<T extends MissionLike>(
|
||||
actor: McpActorContext,
|
||||
missions: T[],
|
||||
): T[] {
|
||||
if (isGlobalAdminActor(actor)) return missions;
|
||||
return missions.filter(
|
||||
(mission) =>
|
||||
mission.userId === actor.userId ||
|
||||
(isTenantAdminActor(actor) && matchesTenant(actor, mission)),
|
||||
);
|
||||
}
|
||||
|
||||
function scopesEqual(left: ReadonlySet<McpToolScope>, right: ReadonlySet<McpToolScope>): boolean {
|
||||
if (left.size !== right.size) return false;
|
||||
for (const scope of left) {
|
||||
if (!right.has(scope)) return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
function sameActorAuthorization(stored: McpActorContext, current: McpActorContext): boolean {
|
||||
return (
|
||||
stored.userId === current.userId &&
|
||||
stored.tenantId === current.tenantId &&
|
||||
stored.role === current.role &&
|
||||
scopesEqual(stored.scopes, current.scopes)
|
||||
);
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
@@ -238,18 +33,13 @@ export class McpService implements OnModuleDestroy {
|
||||
* Creates a new MCP session with its own server + transport pair.
|
||||
* Returns the transport for use by the controller.
|
||||
*/
|
||||
createSession(actor: McpActorContext): {
|
||||
sessionId: string;
|
||||
transport: StreamableHTTPServerTransport;
|
||||
} {
|
||||
createSession(userId: string): { sessionId: string; transport: StreamableHTTPServerTransport } {
|
||||
const sessionId = randomUUID();
|
||||
|
||||
const transport = new StreamableHTTPServerTransport({
|
||||
sessionIdGenerator: () => sessionId,
|
||||
onsessioninitialized: (id) => {
|
||||
this.logger.log(
|
||||
`MCP session initialized: ${id} for actor=${actor.userId} tenant=${actor.tenantId} correlation=${actor.correlationId}`,
|
||||
);
|
||||
this.logger.log(`MCP session initialized: ${id} for user ${userId}`);
|
||||
},
|
||||
});
|
||||
|
||||
@@ -258,7 +48,7 @@ export class McpService implements OnModuleDestroy {
|
||||
{ capabilities: { tools: {} } },
|
||||
);
|
||||
|
||||
this.registerTools(server, actor);
|
||||
this.registerTools(server, userId);
|
||||
|
||||
transport.onclose = () => {
|
||||
this.logger.log(`MCP session closed: ${sessionId}`);
|
||||
@@ -271,126 +61,31 @@ export class McpService implements OnModuleDestroy {
|
||||
);
|
||||
});
|
||||
|
||||
this.sessions.set(sessionId, { server, transport, createdAt: new Date(), actor });
|
||||
this.sessions.set(sessionId, { server, transport, createdAt: new Date(), userId });
|
||||
return { sessionId, transport };
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the transport for an existing session only when it belongs to the
|
||||
* currently authenticated MCP actor. Guessed or cross-tenant session IDs grant
|
||||
* no authority.
|
||||
* Returns the transport for an existing session, or null if not found.
|
||||
*/
|
||||
getSession(sessionId: string, actor: McpActorContext): StreamableHTTPServerTransport | null {
|
||||
const entry = this.sessions.get(sessionId);
|
||||
if (!entry) return null;
|
||||
if (!sameActorAuthorization(entry.actor, actor)) {
|
||||
this.logger.warn(
|
||||
`MCP session actor or scope mismatch: session=${sessionId} actor=${actor.userId} tenant=${actor.tenantId} role=${actor.role}`,
|
||||
);
|
||||
return null;
|
||||
}
|
||||
return entry.transport;
|
||||
}
|
||||
|
||||
private async isProjectAuthorized(actor: McpActorContext, projectId: string): Promise<boolean> {
|
||||
if (isGlobalAdminActor(actor)) return true;
|
||||
const project = (await this.brain.projects.findById(projectId)) as ProjectLike | undefined;
|
||||
return project ? filterProjectsForActor(actor, [project]).length === 1 : false;
|
||||
}
|
||||
|
||||
private async filterMissionsForActor<T extends MissionLike>(
|
||||
actor: McpActorContext,
|
||||
missions: T[],
|
||||
): Promise<T[]> {
|
||||
if (isGlobalAdminActor(actor)) return missions;
|
||||
|
||||
const projects = (await this.brain.projects.findAll()) as ProjectLike[];
|
||||
const projectIds = new Set(
|
||||
filterProjectsForActor(actor, projects).map((project) => project.id),
|
||||
);
|
||||
|
||||
return missions.filter(
|
||||
(mission) =>
|
||||
filterMissionsByDirectActorScope(actor, [mission]).length === 1 ||
|
||||
(typeof mission.projectId === 'string' && projectIds.has(mission.projectId)),
|
||||
);
|
||||
}
|
||||
|
||||
private async isMissionAuthorized(actor: McpActorContext, missionId: string): Promise<boolean> {
|
||||
if (isGlobalAdminActor(actor)) return true;
|
||||
const mission = (await this.brain.missions.findById(missionId)) as MissionLike | undefined;
|
||||
if (!mission) return false;
|
||||
return (await this.filterMissionsForActor(actor, [mission])).length === 1;
|
||||
}
|
||||
|
||||
private async assertTaskReferencesAuthorized(
|
||||
actor: McpActorContext,
|
||||
refs: { projectId?: string | null; missionId?: string | null },
|
||||
): Promise<void> {
|
||||
if (refs.projectId && !(await this.isProjectAuthorized(actor, refs.projectId))) {
|
||||
throw new Error('MCP task project scope denied');
|
||||
}
|
||||
if (refs.missionId && !(await this.isMissionAuthorized(actor, refs.missionId))) {
|
||||
throw new Error('MCP task mission scope denied');
|
||||
}
|
||||
}
|
||||
|
||||
private async assertTaskCreateScopeAuthorized(
|
||||
actor: McpActorContext,
|
||||
refs: { projectId?: string | null; missionId?: string | null },
|
||||
): Promise<void> {
|
||||
if (!isGlobalAdminActor(actor) && !refs.projectId && !refs.missionId) {
|
||||
throw new Error('MCP task scope denied');
|
||||
}
|
||||
await this.assertTaskReferencesAuthorized(actor, refs);
|
||||
}
|
||||
|
||||
private async filterTasksForActor<T extends TaskLike>(
|
||||
actor: McpActorContext,
|
||||
tasks: T[],
|
||||
): Promise<T[]> {
|
||||
if (isGlobalAdminActor(actor)) return tasks;
|
||||
|
||||
const [projects, missions] = await Promise.all([
|
||||
this.brain.projects.findAll(),
|
||||
this.brain.missions.findAll(),
|
||||
]);
|
||||
const projectIds = new Set(
|
||||
filterProjectsForActor(actor, projects as ProjectLike[]).map((project) => project.id),
|
||||
);
|
||||
const missionIds = new Set(
|
||||
(await this.filterMissionsForActor(actor, missions as MissionLike[])).map(
|
||||
(mission) => mission.id,
|
||||
),
|
||||
);
|
||||
|
||||
return tasks.filter(
|
||||
(task) =>
|
||||
task.userId === actor.userId ||
|
||||
(isTenantAdminActor(actor) && matchesTenant(actor, task)) ||
|
||||
(typeof task.projectId === 'string' && projectIds.has(task.projectId)) ||
|
||||
(typeof task.missionId === 'string' && missionIds.has(task.missionId)),
|
||||
);
|
||||
getSession(sessionId: string): StreamableHTTPServerTransport | null {
|
||||
return this.sessions.get(sessionId)?.transport ?? null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Registers all platform tools on the given McpServer instance.
|
||||
*/
|
||||
registerTools(server: McpServer, actor: McpActorContext): void {
|
||||
private registerTools(server: McpServer, _userId: string): void {
|
||||
// ─── Brain: Project tools ────────────────────────────────────────────
|
||||
|
||||
server.registerTool(
|
||||
'brain_list_projects',
|
||||
{
|
||||
description: 'List all projects in the brain.',
|
||||
inputSchema: strictObject({}),
|
||||
inputSchema: z.object({}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'brain_list_projects', params);
|
||||
const projects = filterProjectsForActor(
|
||||
actor,
|
||||
(await this.brain.projects.findAll()) as ProjectLike[],
|
||||
);
|
||||
async () => {
|
||||
const projects = await this.brain.projects.findAll();
|
||||
return {
|
||||
content: [{ type: 'text' as const, text: JSON.stringify(projects, null, 2) }],
|
||||
};
|
||||
@@ -401,21 +96,17 @@ export class McpService implements OnModuleDestroy {
|
||||
'brain_get_project',
|
||||
{
|
||||
description: 'Get a project by ID.',
|
||||
inputSchema: strictObject({
|
||||
inputSchema: z.object({
|
||||
id: z.string().describe('Project ID (UUID)'),
|
||||
}),
|
||||
},
|
||||
async ({ id, ...params }) => {
|
||||
assertMcpToolAuthorized(actor, 'brain_get_project', params);
|
||||
const project = (await this.brain.projects.findById(id)) as ProjectLike | undefined;
|
||||
const authorizedProject = project ? filterProjectsForActor(actor, [project])[0] : undefined;
|
||||
async ({ id }) => {
|
||||
const project = await this.brain.projects.findById(id);
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: 'text' as const,
|
||||
text: authorizedProject
|
||||
? JSON.stringify(authorizedProject, null, 2)
|
||||
: `Project not found: ${id}`,
|
||||
text: project ? JSON.stringify(project, null, 2) : `Project not found: ${id}`,
|
||||
},
|
||||
],
|
||||
};
|
||||
@@ -428,23 +119,20 @@ export class McpService implements OnModuleDestroy {
|
||||
'brain_list_tasks',
|
||||
{
|
||||
description: 'List tasks, optionally filtered by project, mission, or status.',
|
||||
inputSchema: strictObject({
|
||||
inputSchema: z.object({
|
||||
projectId: z.string().optional().describe('Filter by project ID'),
|
||||
missionId: z.string().optional().describe('Filter by mission ID'),
|
||||
status: z.string().optional().describe('Filter by status'),
|
||||
}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'brain_list_tasks', params);
|
||||
const { projectId, missionId, status } = params;
|
||||
async ({ projectId, missionId, status }) => {
|
||||
type TaskStatus = 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
|
||||
let tasks;
|
||||
if (projectId) tasks = await this.brain.tasks.findByProject(projectId);
|
||||
else if (missionId) tasks = await this.brain.tasks.findByMission(missionId);
|
||||
else if (status) tasks = await this.brain.tasks.findByStatus(status as TaskStatus);
|
||||
else tasks = await this.brain.tasks.findAll();
|
||||
const scopedTasks = await this.filterTasksForActor(actor, tasks as TaskLike[]);
|
||||
return { content: [{ type: 'text' as const, text: JSON.stringify(scopedTasks, null, 2) }] };
|
||||
return { content: [{ type: 'text' as const, text: JSON.stringify(tasks, null, 2) }] };
|
||||
},
|
||||
);
|
||||
|
||||
@@ -452,7 +140,7 @@ export class McpService implements OnModuleDestroy {
|
||||
'brain_create_task',
|
||||
{
|
||||
description: 'Create a new task in the brain.',
|
||||
inputSchema: strictObject({
|
||||
inputSchema: z.object({
|
||||
title: z.string().describe('Task title'),
|
||||
description: z.string().optional().describe('Task description'),
|
||||
projectId: z.string().optional().describe('Project ID'),
|
||||
@@ -461,8 +149,6 @@ export class McpService implements OnModuleDestroy {
|
||||
}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'brain_create_task', params);
|
||||
await this.assertTaskCreateScopeAuthorized(actor, params);
|
||||
type Priority = 'low' | 'medium' | 'high' | 'critical';
|
||||
const task = await this.brain.tasks.create({
|
||||
...params,
|
||||
@@ -476,7 +162,7 @@ export class McpService implements OnModuleDestroy {
|
||||
'brain_update_task',
|
||||
{
|
||||
description: 'Update an existing task.',
|
||||
inputSchema: strictObject({
|
||||
inputSchema: z.object({
|
||||
id: z.string().describe('Task ID'),
|
||||
title: z.string().optional(),
|
||||
description: z.string().optional(),
|
||||
@@ -485,17 +171,9 @@ export class McpService implements OnModuleDestroy {
|
||||
.optional()
|
||||
.describe('not-started, in-progress, blocked, done, cancelled'),
|
||||
priority: z.string().optional(),
|
||||
projectId: z.string().optional().describe('Project ID'),
|
||||
missionId: z.string().optional().describe('Mission ID'),
|
||||
}),
|
||||
},
|
||||
async ({ id, ...updates }) => {
|
||||
assertMcpToolAuthorized(actor, 'brain_update_task', updates);
|
||||
const existing = (await this.brain.tasks.findById(id)) as TaskLike | undefined;
|
||||
if (!existing || (await this.filterTasksForActor(actor, [existing])).length === 0) {
|
||||
return { content: [{ type: 'text' as const, text: `Task not found: ${id}` }] };
|
||||
}
|
||||
await this.assertTaskReferencesAuthorized(actor, updates);
|
||||
type TaskStatus = 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
|
||||
type Priority = 'low' | 'medium' | 'high' | 'critical';
|
||||
const task = await this.brain.tasks.update(id, {
|
||||
@@ -520,19 +198,14 @@ export class McpService implements OnModuleDestroy {
|
||||
'brain_list_missions',
|
||||
{
|
||||
description: 'List all missions, optionally filtered by project.',
|
||||
inputSchema: strictObject({
|
||||
inputSchema: z.object({
|
||||
projectId: z.string().optional().describe('Filter by project ID'),
|
||||
}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'brain_list_missions', params);
|
||||
const { projectId } = params;
|
||||
const missions = await this.filterMissionsForActor(
|
||||
actor,
|
||||
(projectId
|
||||
? await this.brain.missions.findByProject(projectId)
|
||||
: await this.brain.missions.findAll()) as MissionLike[],
|
||||
);
|
||||
async ({ projectId }) => {
|
||||
const missions = projectId
|
||||
? await this.brain.missions.findByProject(projectId)
|
||||
: await this.brain.missions.findAll();
|
||||
return { content: [{ type: 'text' as const, text: JSON.stringify(missions, null, 2) }] };
|
||||
},
|
||||
);
|
||||
@@ -540,12 +213,13 @@ export class McpService implements OnModuleDestroy {
|
||||
server.registerTool(
|
||||
'brain_list_conversations',
|
||||
{
|
||||
description: 'List conversations for the authenticated MCP actor.',
|
||||
inputSchema: strictObject({}),
|
||||
description: 'List conversations for a user.',
|
||||
inputSchema: z.object({
|
||||
userId: z.string().describe('User ID'),
|
||||
}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'brain_list_conversations', params);
|
||||
const conversations = await this.brain.conversations.findAll(actor.userId);
|
||||
async ({ userId }) => {
|
||||
const conversations = await this.brain.conversations.findAll(userId);
|
||||
return {
|
||||
content: [{ type: 'text' as const, text: JSON.stringify(conversations, null, 2) }],
|
||||
};
|
||||
@@ -558,15 +232,14 @@ export class McpService implements OnModuleDestroy {
|
||||
'memory_search',
|
||||
{
|
||||
description:
|
||||
'Search stored insights and knowledge for the authenticated MCP actor using natural language.',
|
||||
inputSchema: strictObject({
|
||||
'Search across stored insights and knowledge using natural language. Returns semantically similar results.',
|
||||
inputSchema: z.object({
|
||||
userId: z.string().describe('User ID to search memory for'),
|
||||
query: z.string().describe('Natural language search query'),
|
||||
limit: z.number().optional().describe('Max results (default 5)'),
|
||||
}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'memory_search', params);
|
||||
const { query, limit } = params;
|
||||
async ({ userId, query, limit }) => {
|
||||
if (!this.embeddings.available) {
|
||||
return {
|
||||
content: [
|
||||
@@ -578,11 +251,7 @@ export class McpService implements OnModuleDestroy {
|
||||
};
|
||||
}
|
||||
const embedding = await this.embeddings.embed(query);
|
||||
const results = await this.memory.insights.searchByEmbedding(
|
||||
actor.userId,
|
||||
embedding,
|
||||
limit ?? 5,
|
||||
);
|
||||
const results = await this.memory.insights.searchByEmbedding(userId, embedding, limit ?? 5);
|
||||
return { content: [{ type: 'text' as const, text: JSON.stringify(results, null, 2) }] };
|
||||
},
|
||||
);
|
||||
@@ -590,21 +259,20 @@ export class McpService implements OnModuleDestroy {
|
||||
server.registerTool(
|
||||
'memory_get_preferences',
|
||||
{
|
||||
description: 'Retrieve stored preferences for the authenticated MCP actor.',
|
||||
inputSchema: strictObject({
|
||||
description: 'Retrieve stored preferences for a user.',
|
||||
inputSchema: z.object({
|
||||
userId: z.string().describe('User ID'),
|
||||
category: z
|
||||
.string()
|
||||
.optional()
|
||||
.describe('Filter by category: communication, coding, workflow, appearance, general'),
|
||||
}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'memory_get_preferences', params);
|
||||
const { category } = params;
|
||||
async ({ userId, category }) => {
|
||||
type Cat = 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
|
||||
const prefs = category
|
||||
? await this.memory.preferences.findByUserAndCategory(actor.userId, category as Cat)
|
||||
: await this.memory.preferences.findByUser(actor.userId);
|
||||
? await this.memory.preferences.findByUserAndCategory(userId, category as Cat)
|
||||
: await this.memory.preferences.findByUser(userId);
|
||||
return { content: [{ type: 'text' as const, text: JSON.stringify(prefs, null, 2) }] };
|
||||
},
|
||||
);
|
||||
@@ -613,8 +281,9 @@ export class McpService implements OnModuleDestroy {
|
||||
'memory_save_preference',
|
||||
{
|
||||
description:
|
||||
'Store a learned preference for the authenticated MCP actor (e.g., "prefers tables over paragraphs").',
|
||||
inputSchema: strictObject({
|
||||
'Store a learned user preference (e.g., "prefers tables over paragraphs", "timezone: America/Chicago").',
|
||||
inputSchema: z.object({
|
||||
userId: z.string().describe('User ID'),
|
||||
key: z.string().describe('Preference key'),
|
||||
value: z.string().describe('Preference value (JSON string)'),
|
||||
category: z
|
||||
@@ -623,9 +292,7 @@ export class McpService implements OnModuleDestroy {
|
||||
.describe('Category: communication, coding, workflow, appearance, general'),
|
||||
}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'memory_save_preference', params);
|
||||
const { key, value, category } = params;
|
||||
async ({ userId, key, value, category }) => {
|
||||
type Cat = 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
|
||||
let parsedValue: unknown;
|
||||
try {
|
||||
@@ -634,7 +301,7 @@ export class McpService implements OnModuleDestroy {
|
||||
parsedValue = value;
|
||||
}
|
||||
const pref = await this.memory.preferences.upsert({
|
||||
userId: actor.userId,
|
||||
userId,
|
||||
key,
|
||||
value: parsedValue,
|
||||
category: (category as Cat) ?? 'general',
|
||||
@@ -648,8 +315,9 @@ export class McpService implements OnModuleDestroy {
|
||||
'memory_save_insight',
|
||||
{
|
||||
description:
|
||||
'Store a learned insight, decision, or knowledge for the authenticated MCP actor.',
|
||||
inputSchema: strictObject({
|
||||
'Store a learned insight, decision, or knowledge extracted from the current interaction.',
|
||||
inputSchema: z.object({
|
||||
userId: z.string().describe('User ID'),
|
||||
content: z.string().describe('The insight or knowledge to store'),
|
||||
category: z
|
||||
.string()
|
||||
@@ -657,13 +325,11 @@ export class McpService implements OnModuleDestroy {
|
||||
.describe('Category: decision, learning, preference, fact, pattern, general'),
|
||||
}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'memory_save_insight', params);
|
||||
const { content, category } = params;
|
||||
async ({ userId, content, category }) => {
|
||||
type Cat = 'decision' | 'learning' | 'preference' | 'fact' | 'pattern' | 'general';
|
||||
const embedding = this.embeddings.available ? await this.embeddings.embed(content) : null;
|
||||
const insight = await this.memory.insights.create({
|
||||
userId: actor.userId,
|
||||
userId,
|
||||
content,
|
||||
embedding,
|
||||
source: 'agent',
|
||||
@@ -680,11 +346,16 @@ export class McpService implements OnModuleDestroy {
|
||||
{
|
||||
description:
|
||||
'Get the current orchestration mission status including milestones, tasks, and active session.',
|
||||
inputSchema: strictObject({}),
|
||||
inputSchema: z.object({
|
||||
projectPath: z
|
||||
.string()
|
||||
.optional()
|
||||
.describe('Project path. Defaults to gateway working directory.'),
|
||||
}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'coord_mission_status', params);
|
||||
const status = await this.coordService.getMissionStatus(process.cwd());
|
||||
async ({ projectPath }) => {
|
||||
const resolvedPath = projectPath ?? process.cwd();
|
||||
const status = await this.coordService.getMissionStatus(resolvedPath);
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
@@ -700,11 +371,16 @@ export class McpService implements OnModuleDestroy {
|
||||
'coord_list_tasks',
|
||||
{
|
||||
description: 'List all tasks from the orchestration TASKS.md file.',
|
||||
inputSchema: strictObject({}),
|
||||
inputSchema: z.object({
|
||||
projectPath: z
|
||||
.string()
|
||||
.optional()
|
||||
.describe('Project path. Defaults to gateway working directory.'),
|
||||
}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'coord_list_tasks', params);
|
||||
const tasks = await this.coordService.listTasks(process.cwd());
|
||||
async ({ projectPath }) => {
|
||||
const resolvedPath = projectPath ?? process.cwd();
|
||||
const tasks = await this.coordService.listTasks(resolvedPath);
|
||||
return { content: [{ type: 'text' as const, text: JSON.stringify(tasks, null, 2) }] };
|
||||
},
|
||||
);
|
||||
@@ -713,14 +389,17 @@ export class McpService implements OnModuleDestroy {
|
||||
'coord_task_detail',
|
||||
{
|
||||
description: 'Get detailed status for a specific orchestration task.',
|
||||
inputSchema: strictObject({
|
||||
inputSchema: z.object({
|
||||
taskId: z.string().describe('Task ID (e.g. P2-005)'),
|
||||
projectPath: z
|
||||
.string()
|
||||
.optional()
|
||||
.describe('Project path. Defaults to gateway working directory.'),
|
||||
}),
|
||||
},
|
||||
async (params) => {
|
||||
assertMcpToolAuthorized(actor, 'coord_task_detail', params);
|
||||
const { taskId } = params;
|
||||
const detail = await this.coordService.getTaskStatus(process.cwd(), taskId);
|
||||
async ({ taskId, projectPath }) => {
|
||||
const resolvedPath = projectPath ?? process.cwd();
|
||||
const detail = await this.coordService.getTaskStatus(resolvedPath, taskId);
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
|
||||
@@ -1,89 +0,0 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
createDiscordIngressEnvelope,
|
||||
verifyDiscordIngressEnvelope,
|
||||
type DiscordIngressPayload,
|
||||
} from '@mosaicstack/discord-plugin';
|
||||
import { validateDiscordServiceToken } from '../chat/chat.gateway-auth.js';
|
||||
import { DiscordReplayProtector } from './discord-replay-protector.js';
|
||||
|
||||
const SERVICE_TOKEN = 'test-service-token';
|
||||
|
||||
function createPayload(overrides: Partial<DiscordIngressPayload> = {}): DiscordIngressPayload {
|
||||
return {
|
||||
correlationId: 'correlation-001',
|
||||
messageId: 'discord-message-001',
|
||||
guildId: 'guild-001',
|
||||
channelId: 'channel-001',
|
||||
userId: 'user-001',
|
||||
conversationId: 'discord-channel-001',
|
||||
content: 'hello Tess',
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe('Discord ingress security', () => {
|
||||
it('accepts only the configured Discord service identity', () => {
|
||||
expect(validateDiscordServiceToken(SERVICE_TOKEN, SERVICE_TOKEN)).toBe(true);
|
||||
expect(validateDiscordServiceToken('wrong-service-token', SERVICE_TOKEN)).toBe(false);
|
||||
expect(validateDiscordServiceToken(undefined, SERVICE_TOKEN)).toBe(false);
|
||||
});
|
||||
|
||||
it('rejects unauthenticated or tampered service envelopes', () => {
|
||||
const envelope = createDiscordIngressEnvelope(createPayload(), SERVICE_TOKEN);
|
||||
|
||||
expect(verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN)).toEqual(createPayload());
|
||||
expect(verifyDiscordIngressEnvelope(envelope, 'wrong-service-token')).toBeNull();
|
||||
expect(
|
||||
verifyDiscordIngressEnvelope(
|
||||
{ ...envelope, payload: { ...envelope.payload, content: 'forged command' } },
|
||||
SERVICE_TOKEN,
|
||||
),
|
||||
).toBeNull();
|
||||
});
|
||||
|
||||
it.each([
|
||||
['guild', { guildId: 'unlisted-guild' }],
|
||||
['channel', { channelId: 'unlisted-channel' }],
|
||||
['user', { userId: 'unlisted-user' }],
|
||||
])(
|
||||
'rejects an unallowlisted Discord %s',
|
||||
(_kind: string, overrides: Partial<DiscordIngressPayload>) => {
|
||||
const envelope = createDiscordIngressEnvelope(createPayload(overrides), SERVICE_TOKEN);
|
||||
|
||||
expect(
|
||||
verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN, {
|
||||
guildIds: ['guild-001'],
|
||||
channelIds: ['channel-001'],
|
||||
userIds: ['user-001'],
|
||||
}),
|
||||
).toBeNull();
|
||||
},
|
||||
);
|
||||
|
||||
it('retains Discord message and correlation IDs after authenticated allowlisted validation', () => {
|
||||
const payload = createPayload({
|
||||
correlationId: 'correlation-trace-123',
|
||||
messageId: 'discord-snowflake-987',
|
||||
});
|
||||
const envelope = createDiscordIngressEnvelope(payload, SERVICE_TOKEN);
|
||||
|
||||
expect(
|
||||
verifyDiscordIngressEnvelope(envelope, SERVICE_TOKEN, {
|
||||
guildIds: ['guild-001'],
|
||||
channelIds: ['channel-001'],
|
||||
userIds: ['user-001'],
|
||||
}),
|
||||
).toEqual(payload);
|
||||
});
|
||||
|
||||
it('rejects a replayed Discord message ID while retaining bounded replay state', () => {
|
||||
const replayProtector = new DiscordReplayProtector(60_000, 2);
|
||||
|
||||
expect(replayProtector.claim('discord-message-001')).toBe(true);
|
||||
expect(replayProtector.claim('discord-message-001')).toBe(false);
|
||||
expect(replayProtector.claim('discord-message-002')).toBe(true);
|
||||
expect(replayProtector.claim('discord-message-003')).toBe(true);
|
||||
expect(replayProtector.size).toBe(2);
|
||||
});
|
||||
});
|
||||
@@ -1,40 +0,0 @@
|
||||
/**
|
||||
* Bounded replay cache for Discord's globally unique native message IDs.
|
||||
* Durable ingress idempotency is added with Tess's canonical inbox/outbox work.
|
||||
*/
|
||||
export class DiscordReplayProtector {
|
||||
private readonly claimedAt = new Map<string, number>();
|
||||
|
||||
constructor(
|
||||
private readonly ttlMs = 15 * 60 * 1000,
|
||||
private readonly maxEntries = 10_000,
|
||||
) {}
|
||||
|
||||
get size(): number {
|
||||
return this.claimedAt.size;
|
||||
}
|
||||
|
||||
/** Claims an ID exactly once within its bounded retention window. */
|
||||
claim(messageId: string, now = Date.now()): boolean {
|
||||
this.prune(now);
|
||||
if (this.claimedAt.has(messageId)) return false;
|
||||
|
||||
this.claimedAt.set(messageId, now);
|
||||
this.evictOverflow();
|
||||
return true;
|
||||
}
|
||||
|
||||
private prune(now: number): void {
|
||||
for (const [messageId, claimedAt] of this.claimedAt) {
|
||||
if (now - claimedAt >= this.ttlMs) this.claimedAt.delete(messageId);
|
||||
}
|
||||
}
|
||||
|
||||
private evictOverflow(): void {
|
||||
while (this.claimedAt.size > this.maxEntries) {
|
||||
const oldestMessageId = this.claimedAt.keys().next().value;
|
||||
if (oldestMessageId === undefined) return;
|
||||
this.claimedAt.delete(oldestMessageId);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -50,41 +50,19 @@ class TelegramChannelPluginAdapter implements IChannelPlugin {
|
||||
|
||||
const DEFAULT_GATEWAY_URL = 'http://localhost:14242';
|
||||
|
||||
function requiredDiscordAllowlist(name: string): string[] {
|
||||
const value = process.env[name]
|
||||
?.split(',')
|
||||
.map((id: string): string => id.trim())
|
||||
.filter((id: string): boolean => id.length > 0);
|
||||
if (!value || value.length === 0) {
|
||||
throw new Error(`${name} is required when DISCORD_BOT_TOKEN is configured`);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function createPluginRegistry(): IChannelPlugin[] {
|
||||
const plugins: IChannelPlugin[] = [];
|
||||
const discordToken = process.env['DISCORD_BOT_TOKEN'];
|
||||
const discordGuildId = process.env['DISCORD_GUILD_ID'];
|
||||
const discordGatewayUrl = process.env['DISCORD_GATEWAY_URL'] ?? DEFAULT_GATEWAY_URL;
|
||||
const discordServiceToken = process.env['DISCORD_SERVICE_TOKEN'];
|
||||
const discordServiceUserId = process.env['DISCORD_SERVICE_USER_ID'];
|
||||
|
||||
if (discordToken) {
|
||||
if (!discordServiceToken || !discordServiceUserId) {
|
||||
throw new Error(
|
||||
'DISCORD_SERVICE_TOKEN and DISCORD_SERVICE_USER_ID are required when DISCORD_BOT_TOKEN is configured',
|
||||
);
|
||||
}
|
||||
plugins.push(
|
||||
new DiscordChannelPluginAdapter(
|
||||
new DiscordPlugin({
|
||||
token: discordToken,
|
||||
guildId: discordGuildId,
|
||||
gatewayUrl: discordGatewayUrl,
|
||||
serviceToken: discordServiceToken,
|
||||
allowedGuildIds: requiredDiscordAllowlist('DISCORD_ALLOWED_GUILD_IDS'),
|
||||
allowedChannelIds: requiredDiscordAllowlist('DISCORD_ALLOWED_CHANNEL_IDS'),
|
||||
allowedUserIds: requiredDiscordAllowlist('DISCORD_ALLOWED_USER_IDS'),
|
||||
}),
|
||||
),
|
||||
);
|
||||
|
||||
@@ -1,13 +1,9 @@
|
||||
import { Injectable, Logger } from '@nestjs/common';
|
||||
import { createQueue, type QueueHandle } from '@mosaicstack/queue';
|
||||
import type { ActorTenantScope } from '../auth/session-scope.js';
|
||||
|
||||
const scopedSessionId = (sessionId: string, scope: ActorTenantScope) =>
|
||||
`${scope.tenantId}:${scope.userId}:${sessionId}`;
|
||||
const SESSION_SYSTEM_KEY = (sessionId: string, scope: ActorTenantScope) =>
|
||||
`mosaic:session:${scopedSessionId(sessionId, scope)}:system`;
|
||||
const SESSION_SYSTEM_FRAGMENTS_KEY = (sessionId: string, scope: ActorTenantScope) =>
|
||||
`mosaic:session:${scopedSessionId(sessionId, scope)}:system:fragments`;
|
||||
const SESSION_SYSTEM_KEY = (sessionId: string) => `mosaic:session:${sessionId}:system`;
|
||||
const SESSION_SYSTEM_FRAGMENTS_KEY = (sessionId: string) =>
|
||||
`mosaic:session:${sessionId}:system:fragments`;
|
||||
const SYSTEM_OVERRIDE_TTL_SECONDS = 604800; // 7 days
|
||||
|
||||
interface OverrideFragment {
|
||||
@@ -24,9 +20,9 @@ export class SystemOverrideService {
|
||||
this.handle = createQueue();
|
||||
}
|
||||
|
||||
async set(sessionId: string, override: string, scope: ActorTenantScope): Promise<void> {
|
||||
async set(sessionId: string, override: string): Promise<void> {
|
||||
// Load existing fragments
|
||||
const existing = await this.handle.redis.get(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope));
|
||||
const existing = await this.handle.redis.get(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId));
|
||||
const fragments: OverrideFragment[] = existing
|
||||
? (JSON.parse(existing) as OverrideFragment[])
|
||||
: [];
|
||||
@@ -41,11 +37,11 @@ export class SystemOverrideService {
|
||||
// Store both: fragments array and condensed result
|
||||
const pipeline = this.handle.redis.pipeline();
|
||||
pipeline.setex(
|
||||
SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope),
|
||||
SESSION_SYSTEM_FRAGMENTS_KEY(sessionId),
|
||||
SYSTEM_OVERRIDE_TTL_SECONDS,
|
||||
JSON.stringify(fragments),
|
||||
);
|
||||
pipeline.setex(SESSION_SYSTEM_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS, condensed);
|
||||
pipeline.setex(SESSION_SYSTEM_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS, condensed);
|
||||
await pipeline.exec();
|
||||
|
||||
this.logger.debug(
|
||||
@@ -53,21 +49,21 @@ export class SystemOverrideService {
|
||||
);
|
||||
}
|
||||
|
||||
async get(sessionId: string, scope: ActorTenantScope): Promise<string | null> {
|
||||
return this.handle.redis.get(SESSION_SYSTEM_KEY(sessionId, scope));
|
||||
async get(sessionId: string): Promise<string | null> {
|
||||
return this.handle.redis.get(SESSION_SYSTEM_KEY(sessionId));
|
||||
}
|
||||
|
||||
async renew(sessionId: string, scope: ActorTenantScope): Promise<void> {
|
||||
async renew(sessionId: string): Promise<void> {
|
||||
const pipeline = this.handle.redis.pipeline();
|
||||
pipeline.expire(SESSION_SYSTEM_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
|
||||
pipeline.expire(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope), SYSTEM_OVERRIDE_TTL_SECONDS);
|
||||
pipeline.expire(SESSION_SYSTEM_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS);
|
||||
pipeline.expire(SESSION_SYSTEM_FRAGMENTS_KEY(sessionId), SYSTEM_OVERRIDE_TTL_SECONDS);
|
||||
await pipeline.exec();
|
||||
}
|
||||
|
||||
async clear(sessionId: string, scope: ActorTenantScope): Promise<void> {
|
||||
async clear(sessionId: string): Promise<void> {
|
||||
await this.handle.redis.del(
|
||||
SESSION_SYSTEM_KEY(sessionId, scope),
|
||||
SESSION_SYSTEM_FRAGMENTS_KEY(sessionId, scope),
|
||||
SESSION_SYSTEM_KEY(sessionId),
|
||||
SESSION_SYSTEM_FRAGMENTS_KEY(sessionId),
|
||||
);
|
||||
this.logger.debug(`Cleared system override for session ${sessionId}`);
|
||||
}
|
||||
|
||||
@@ -67,11 +67,10 @@ The MVP is complete when ALL declared workstreams are complete AND every cross-c
|
||||
|
||||
## Workstreams
|
||||
|
||||
| # | ID | Name | Status | Manifest | Notes |
|
||||
| --- | ---- | ------------------------------------------- | ----------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| W1 | FED | Federation v1 | planning-complete | [docs/federation/MISSION-MANIFEST.md](./federation/MISSION-MANIFEST.md) | 7 milestones, ~175K tokens, issues #460–#466 filed |
|
||||
| W2 | TESS | Tess interaction agent | planning-complete | [docs/tess/MISSION-MANIFEST.md](./tess/MISSION-MANIFEST.md) | 5 milestones; issue #706; M1 issue #707 ready |
|
||||
| W3+ | TBD | (additional workstreams declared as scoped) | — | — | Scope creep is expected and explicitly accommodated |
|
||||
| # | ID | Name | Status | Manifest | Notes |
|
||||
| --- | --- | ------------------------------------------- | ----------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| W1 | FED | Federation v1 | planning-complete | [docs/federation/MISSION-MANIFEST.md](./federation/MISSION-MANIFEST.md) | 7 milestones, ~175K tokens, issues #460–#466 filed |
|
||||
| W2+ | TBD | (additional workstreams declared as scoped) | — | — | Scope creep is expected and explicitly accommodated |
|
||||
|
||||
### Likely Additional Workstreams (Not Yet Declared)
|
||||
|
||||
|
||||
96
docs/PRD.md
96
docs/PRD.md
@@ -79,102 +79,6 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
|
||||
|
||||
---
|
||||
|
||||
## Tess Interaction Agent Workstream (TESS)
|
||||
|
||||
### Problem and Objective
|
||||
|
||||
Jason needs one durable, operator-facing Mosaic agent outside Hermes that is reachable through a dedicated Discord channel and CLI, can attach to and operate the Mosaic fleet and transitional Hermes agents, and preserves context across restarts and compaction. Mos remains the coding/general fleet orchestrator; Tess is the complementary human interaction, visibility, control, and migration agent.
|
||||
|
||||
The objective is to ship **Tess** (from _tessera_, a piece of a mosaic) as a Pi-native, GPT-5.6 Sol agent with high reasoning. Tess must use Mosaic-owned contracts and plugins so Hermes can be replaced incrementally rather than becoming a permanent architectural dependency.
|
||||
|
||||
### Scope
|
||||
|
||||
#### In Scope
|
||||
|
||||
1. `TESS-ARP-001`: A runtime-neutral `AgentRuntimeProvider` contract supporting `listSessions`, `streamSession`, `sendMessage`, `terminate`, `getSessionTree`, `attach`, health, capability discovery, and normalized events/errors.
|
||||
2. `TESS-PI-001`: A long-running Pi-native Tess agent profile/service pinned to GPT-5.6 Sol with high reasoning, explicit tool policy, lifecycle hooks, durable checkpoints, and restart recovery.
|
||||
3. `TESS-DSC-001`: Dedicated Discord channel binding to Tess through the Mosaic gateway, with allowlists/RBAC, thread/reply policy, streaming, attachments, approvals, and correlation IDs.
|
||||
4. `TESS-CLI-001`: `mosaic tess` CLI commands for chat, status, session listing, attach/detach, send/steer/stop, provider health, and recovery.
|
||||
5. `TESS-FLT-001`: Fleet plugin capabilities for roster/status/heartbeat inspection, message delivery, session hierarchy, safe attach, and controlled restart/recovery.
|
||||
6. `TESS-MOS-001`: Explicit Mos coordination boundary and tools: hand off orchestration requests, observe mission/task state, receive results, and never silently compete for orchestration authority.
|
||||
7. `TESS-HRM-001`: Transitional Hermes adapter for profiles/agents, sessions, streaming/messages, Kanban, skills, memory, tools, cron, and health, using capability negotiation and fail-closed unsupported operations.
|
||||
8. `TESS-MEM-001`: Unified memory/retrieval plugin with scoped search/recent/capture/stats, startup context injection, provenance, redaction, namespace isolation, and flat-file/project truth precedence.
|
||||
9. `TESS-STA-001`: Durable agent state, inbox, handoff, compaction-recovery, and resume reconstruction.
|
||||
10. `TESS-PLG-001`: Plugin/tool catalog covering runtime bootstrap, repository/PR workflow, fleet diagnostics, incident-safe read operations, Discord interaction, and extensible MCP/skill discovery.
|
||||
11. `TESS-TRN-001`: Replaceable transport providers: tmux/fleet now, Matrix/native Mosaic transport later, with no Discord/CLI business logic coupled to transport details.
|
||||
12. `TESS-SEC-001`: RBAC, per-operation authorization, explicit approval for destructive/privileged/customer-visible actions, audit events, secret/PII redaction, tenant isolation, and bounded command execution.
|
||||
13. `TESS-SEC-002`: Command execution SHALL enforce declared scope/role server-side; admin/system and destructive operations SHALL require policy-bound durable approval.
|
||||
14. `TESS-SEC-003`: Every session list/read/attach/send/terminate operation SHALL enforce server-derived owner and tenant scope; guessed or client-supplied IDs SHALL grant no authority.
|
||||
15. `TESS-SEC-004`: MCP tools SHALL derive actor/tenant from authenticated context and SHALL NOT accept caller-controlled identity fields.
|
||||
16. `TESS-SEC-005`: Discord plugin ingress SHALL authenticate service identity, enforce guild/channel/user allowlists, propagate correlation/message IDs, and reject replay.
|
||||
17. `TESS-SEC-006`: Secret/PII classification and redaction SHALL occur before persistence and before channel egress, including tool metadata and authentication flows.
|
||||
18. `TESS-SEC-007`: Approvals SHALL be one-time, expiring, actor/tenant-bound, and cryptographically bound to the exact structured action digest.
|
||||
19. `TESS-SEC-008`: Ingress, provider sends, tool side effects, and responses SHALL use durable inbox/outbox/checkpoints and idempotency records for restart-safe replay.
|
||||
20. `TESS-SEC-009`: Garbage collection and retention SHALL be session/tenant scoped unless executed as a separately authorized and audited system-wide job.
|
||||
21. `TESS-OBS-001`: Structured logs, traces, health/readiness, provider latency/errors, session lifecycle, tool audit, and actionable recovery diagnostics.
|
||||
22. `TESS-MIG-001`: Capability inventory and staged Hermes-to-Mosaic migration matrix with coexistence, cutover, rollback, and deprecation gates.
|
||||
|
||||
#### Out of Scope
|
||||
|
||||
1. Replacing Mos as coding/general fleet orchestrator.
|
||||
2. Making Hermes the Mosaic core or coupling Mosaic domain logic to Hermes schemas.
|
||||
3. Migrating every historical chat verbatim; only policy-compliant indexed summaries and user-selected sessions are migrated.
|
||||
4. Unrestricted shell execution from Discord.
|
||||
5. Full web UI parity in the first Tess operational milestone; gateway contracts must remain web-consumable.
|
||||
6. Replacing tmux before Matrix/native transport reaches operational parity.
|
||||
|
||||
### Stakeholder and User Requirements
|
||||
|
||||
- Jason must be able to converse with the same Tess session from Discord and CLI.
|
||||
- Jason must be able to see what is running, stale, blocked, or unhealthy without attaching manually to every session.
|
||||
- Jason must be able to attach to Tess and authorized fleet sessions through supported CLI controls.
|
||||
- Tess must collaborate with Mos and the fleet while preserving a single clear orchestration authority.
|
||||
- The system must migrate useful Hermes/OpenClaw capabilities intentionally, with evidence, instead of copying implementations wholesale.
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
1. **Security:** default-deny provider/tool capabilities, least privilege, no secrets in logs/prompts/commits, Discord user/channel authorization, and auditable approvals.
|
||||
2. **Reliability:** durable inbox/checkpoints; idempotent message handling; reconnect with bounded backoff; no message loss or duplicate execution across gateway restart.
|
||||
3. **Performance:** first acknowledgement within 2 seconds when connected; streamed agent output begins within 5 seconds excluding model/provider delay; status reads return within 2 seconds under nominal local conditions.
|
||||
4. **Observability:** every ingress message and resulting provider/tool operation carries a correlation ID across Discord, gateway, Tess, provider, and audit events.
|
||||
5. **Maintainability:** channel, runtime, transport, memory, and external-agent integrations remain adapter-based with contract tests.
|
||||
6. **Privacy:** only scoped context enters external runtimes; persisted messages/memories follow retention and redaction policy.
|
||||
7. **Portability:** Tess runs through Pi/Mosaic contracts and does not require Hermes to start or serve native Mosaic operations.
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
1. `AC-TESS-01`: A dedicated Discord channel and `mosaic tess chat` connect to one durable Tess session and stream responses bidirectionally.
|
||||
2. `AC-TESS-02`: `mosaic tess status|sessions|tree|attach|send|stop` operate against authorized provider capabilities with stable typed outputs and actionable errors.
|
||||
3. `AC-TESS-03`: Tess runs GPT-5.6 Sol at high reasoning and its effective runtime/model/tool policy is visible through status without exposing credentials.
|
||||
4. `AC-TESS-04`: Tess can inspect and message the Mosaic fleet, hand orchestration work to Mos, and demonstrate that Tess does not independently claim Mos-owned orchestration work.
|
||||
5. `AC-TESS-05`: Hermes adapter demonstrates session listing, streaming/message delivery, hierarchy mapping, and at least one approved capability in each of Kanban, skills, memory, tools, and cron—or reports unsupported capabilities fail-closed.
|
||||
6. `AC-TESS-06`: Restart/compaction test preserves session identity, pending inbox, last durable checkpoint, and a resumable handoff without duplicate side effects.
|
||||
7. `AC-TESS-07`: Unauthorized Discord users/channels, cross-tenant access, unsafe tool calls, forged approvals, and sensitive-output cases are denied and audited.
|
||||
8. `AC-TESS-08`: tmux/fleet and Matrix/native transport implementations pass the same provider contract suite; Matrix may remain non-default until readiness gates pass.
|
||||
9. `AC-TESS-09`: Baseline quality gates, unit/integration/contract tests, Discord+CLI E2E, restart/recovery tests, independent code review, and security review are green.
|
||||
10. `AC-TESS-10`: Migration matrix documents every audited Hermes/OpenClaw capability as native, adapted, deferred, or rejected, with cutover and rollback evidence.
|
||||
11. `AC-TESS-11`: User, admin, developer, API/OpenAPI, operations/recovery, and plugin-authoring documentation is current and linked from the sitemap.
|
||||
|
||||
### Constraints, Dependencies, Risks, and Assumptions
|
||||
|
||||
- Dependency: Mosaic gateway remains the single API surface; Pi is the native runtime; Valkey/PostgreSQL provide canonical durable state where required.
|
||||
- Dependency: Discord bot credentials and dedicated channel ID are deployment secrets provisioned outside source control.
|
||||
- Risk: Tess could drift into a second orchestrator. Mitigation: explicit role policy, Mos handoff contract, authority checks, and E2E boundary tests.
|
||||
- Risk: broad Hermes compatibility can freeze legacy semantics into Mosaic. Mitigation: Mosaic-owned normalized contracts and capability negotiation.
|
||||
- Risk: Discord creates a privileged remote-control surface. Mitigation: pairing/allowlists, RBAC, approvals, rate limits, audit, and safe tool classes.
|
||||
- Risk: transcript ingestion can violate privacy or overload memory. Mitigation: scoped opt-in import, redacted summaries, provenance, retention, and deduplication.
|
||||
- Risk: current root filesystem has limited headroom. Mitigation: isolated worktrees, no duplicated dependency installation unless required, and cleanup only after active-lane verification.
|
||||
- `ASSUMPTION:` The public name is **Tess**, because the user requested a name and the tessera/Mosaic relationship is distinctive; config must permit later display-name changes without renaming APIs or storage keys.
|
||||
- `ASSUMPTION:` The dedicated Discord channel ID and final guild policy will be supplied/provisioned during deployment, so implementation uses explicit configuration and fail-fast startup validation.
|
||||
- `ASSUMPTION:` tmux/fleet is the production transport for the first operational milestone; Matrix/native transport is implemented behind the same contract and promoted only after parity/reliability verification.
|
||||
- `ASSUMPTION:` Project/task truth remains in canonical Mosaic/project stores; semantic memory systems are retrieval/mirror layers, not hidden authorities.
|
||||
|
||||
### Testing and Delivery Intent
|
||||
|
||||
Delivery uses five gated milestones: runtime contracts/security; Pi service/state; Discord/CLI; fleet/Hermes/plugin suite; migration/Matrix/recovery/qualification. Every source-code task requires tests, independent review, a PR to `main`, terminal-green CI, and issue/task closure. Production activation additionally requires a clean-host Pi launch, dedicated Discord channel smoke test, CLI attach test, restart/recovery drill, and rollback procedure.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### High-Level System Diagram
|
||||
|
||||
@@ -14,10 +14,9 @@
|
||||
|
||||
## Workstream Rollup
|
||||
|
||||
| id | status | workstream | progress | tasks file | notes |
|
||||
| --- | ----------------- | ---------------------- | ---------------- | ------------------------------------------------- | --------------------------------------------------------------- |
|
||||
| W1 | planning-complete | Federation v1 (FED) | 0 / 7 milestones | [docs/federation/TASKS.md](./federation/TASKS.md) | M1 task breakdown populated; M2–M7 deferred to mission planning |
|
||||
| W2 | planning-complete | Tess interaction agent | 0 / 5 milestones | [docs/tess/TASKS.md](./tess/TASKS.md) | Issue #706; independent planning gate PASS; M1 issue #707 ready |
|
||||
| id | status | workstream | progress | tasks file | notes |
|
||||
| --- | ----------------- | ------------------- | ---------------- | ------------------------------------------------- | --------------------------------------------------------------- |
|
||||
| W1 | planning-complete | Federation v1 (FED) | 0 / 7 milestones | [docs/federation/TASKS.md](./federation/TASKS.md) | M1 task breakdown populated; M2–M7 deferred to mission planning |
|
||||
|
||||
## Cross-Cutting Tracking
|
||||
|
||||
|
||||
@@ -232,10 +232,6 @@ The following sections document how each supported channel maps its native messa
|
||||
|
||||
**Outbound:** Adapter calls Discord REST `POST /channels/{id}/messages`. Markdown content is sent as-is (Discord renders it). For `contentType = "code"` the adapter wraps in triple-backtick fences with the `metadata.language` tag.
|
||||
|
||||
### Discord service ingress security
|
||||
|
||||
The Discord adapter is an authenticated gateway service, not an anonymous Socket.IO client. It presents `DISCORD_SERVICE_TOKEN` during its `/chat` connection and signs each inbound envelope using HMAC-SHA-256. The envelope contains the Discord native message ID and a generated correlation ID. Gateway verifies the service credential, signature, and configured guild/channel/user allowlists before agent dispatch, then rejects duplicate native message IDs inside its bounded replay window. All three allowlists are default-deny and required when the Discord plugin is enabled. The service credential is injected at runtime and is never logged or included in protocol payloads.
|
||||
|
||||
---
|
||||
|
||||
### Telegram
|
||||
|
||||
@@ -91,22 +91,22 @@ Goal: Two federated gateways exchange real data over mTLS. Inbound requests pass
|
||||
>
|
||||
> **Tracking issue:** #462.
|
||||
|
||||
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
|
||||
| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ------------------------------------ | --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| FED-M3-01 | done | `packages/types/src/federation/` — request/response DTOs for `list`, `get`, `capabilities` verbs. Wire-format zod schemas + inferred TS types. Includes `FederationRequest`, `FederationListResponse<T>`, `FederationGetResponse<T>`, `FederationCapabilitiesResponse`, error envelope, `_source` tag. | #462 | sonnet | feat/federation-m3-types | — | 4K | Reusable from gateway server + client + harness. Pure types — no I/O, no NestJS. |
|
||||
| FED-M3-02 | done | `tools/federation-harness/` scaffold: `docker-compose.two-gateways.yml` (Server A + Server B + step-CA), `seed.ts` (provisions grants, peers, sample tasks/notes/credentials per scope variant), `harness.ts` helper (boots stack, returns typed clients). README documents harness use. | #462 | sonnet | feat/federation-m3-harness | DEPLOY-04 (soft) | 8K | Falls back to local docker-compose if `mos-test-1/-2` not yet redeployed (DEPLOY chain blocked on IMG-FIX). Permanent test infra used by M3+. |
|
||||
| FED-M3-03 | done | `apps/gateway/src/federation/server/federation-auth.guard.ts` (NestJS guard). Validates inbound client cert from Fastify TLS context, extracts `grantId` + `subjectUserId` from custom OIDs, loads grant from DB, asserts `status='active'`, attaches `FederationContext` to request. | #462 | sonnet | feat/federation-m3-auth-guard | M3-01 | 8K | Reuses OID parsing logic mirrored from `ca.service.ts` post-issuance verification. 401 on malformed/missing OIDs; 403 on revoked/expired/missing grant. |
|
||||
| FED-M3-04 | in-progress | `apps/gateway/src/federation/server/scope.service.ts`. Pipeline: (1) resource allowlist + excluded check, (2) native RBAC eval as `subjectUserId`, (3) scope filter intersection (`include_teams`, `include_personal`), (4) `max_rows_per_query` cap. Pure service — DB calls injected. | #462 | sonnet | feat/federation-m3-scope-service | M3-01 | 10K | Hardest correctness target in M3. Reuses `parseFederationScope` (M2-03). Returns either `{ allowed: true, filter }` or structured deny reason for audit. |
|
||||
| FED-M3-05 | in-progress | `apps/gateway/src/federation/server/verbs/list.controller.ts`. Wires AuthGuard → ScopeService → tasks/notes/memory query layer; applies row cap; tags rows with `_source`. Resource selector via path param. | #462 | sonnet | feat/federation-m3-verb-list | M3-03, M3-04 | 6K | Routes: `POST /api/federation/v1/list/:resource`. No body persistence. Audit write deferred to M4. |
|
||||
| FED-M3-06 | not-started | `apps/gateway/src/federation/server/verbs/get.controller.ts`. Single-resource fetch by id; same pipeline as list. 404 on not-found, 403 on RBAC/scope deny — both audited the same way. | #462 | sonnet | feat/federation-m3-verb-get | M3-03, M3-04 | 6K | `POST /api/federation/v1/get/:resource/:id`. Mirrors list controller patterns. |
|
||||
| FED-M3-07 | done | `apps/gateway/src/federation/server/verbs/capabilities.controller.ts`. Read-only enumeration: returns `{ resources, excluded_resources, max_rows_per_query, supported_verbs }` derived from grant scope. Always allowed for an active grant — no RBAC eval. | #462 | sonnet | feat/federation-m3-verb-capabilities | M3-03 | 4K | `GET /api/federation/v1/capabilities`. Smallest verb; useful sanity check that mTLS + auth guard work end-to-end. |
|
||||
| FED-M3-08 | done | `apps/gateway/src/federation/client/federation-client.service.ts`. Outbound mTLS dialer: picks `(certPem, sealed clientKey)` from `federation_peers`, unwraps key, builds undici Agent with mTLS, calls peer verb, parses typed response, wraps non-2xx into `FederationClientError`. | #462 | sonnet | feat/federation-m3-client | M3-01 | 8K | Independent of server stream — can land in parallel with M3-03/04. Cert/key cached per-peer; flushed by future M5/M6 logic. |
|
||||
| FED-M3-09 | done | `apps/gateway/src/federation/client/query-source.service.ts`. Accepts `source: "local" \| "federated:<host>" \| "all"` from gateway query layer; for `"all"` fans out to local + each peer in parallel; merges results; tags every row with `_source`. | #462 | sonnet | feat/federation-m3-query-source | M3-08 | 8K | Per-peer failure surfaces as `_partial: true` in response, not hard failure (sets up M5 offline UX). M5 adds caching + circuit breaker on top. |
|
||||
| FED-M3-10 | not-started | Integration tests for MILESTONES.md M3 acceptance #6 (malformed OIDs → 401; valid cert + revoked grant → 403) and #7 (`max_rows_per_query` cap). Real PG, mocked TLS context (Fastify req shim). | #462 | sonnet | feat/federation-m3-integration | M3-05, M3-06 | 8K | Vitest profile gated by `FEDERATED_INTEGRATION=1`. Single-gateway suite; no harness required. |
|
||||
| FED-M3-11 | not-started | E2E tests for MILESTONES.md M3 acceptance #1, #2, #3, #4, #5, #8, #9, #10 (8 cases). Uses harness from M3-02; two real gateways, real Step-CA, real mTLS. Each test asserts both happy-path response and audit/no-persist invariants. | #462 | sonnet | feat/federation-m3-e2e | M3-02, M3-04, M3-05, M3-06, M3-09 | 12K | Largest single task. Each acceptance gets its own `it(...)` for clear failure attribution. |
|
||||
| FED-M3-12 | not-started | Independent security review (sonnet, not author of M3-03/04/05/06/07/08/09): focus on cert-SAN spoofing, OID extraction edge cases, scope-bypass via filter manipulation, RBAC-bypass via subjectUser swap, response leakage when scope deny. | #462 | sonnet | feat/federation-m3-security-review | M3-11 | 10K | Two review rounds budgeted. PRD requires explicit test for every 401/403 path — review verifies coverage. |
|
||||
| FED-M3-13 | not-started | Docs update: `docs/federation/SETUP.md` mTLS handshake section, new `docs/federation/HARNESS.md` for federation-harness usage, OID reference table in SETUP.md, scope enforcement pipeline diagram. Runbook still M7-deferred. | #462 | haiku | feat/federation-m3-docs | M3-12 | 5K | One ASCII diagram for the auth-guard → scope → RBAC pipeline; helps future reviewers reason about denial paths. |
|
||||
| FED-M3-14 | not-started | PR aggregate close, CI green, merge to main, close #462. Release tag `fed-v0.3.0-m3`. Update mission manifest M3 row → done; M4 row → in-progress when work begins. | #462 | sonnet | chore/federation-m3-close | M3-13 | 3K | Same close pattern as M1-12 / M2-13. |
|
||||
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
|
||||
| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ------------------------------------ | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| FED-M3-01 | not-started | `packages/types/src/federation/` — request/response DTOs for `list`, `get`, `capabilities` verbs. Wire-format zod schemas + inferred TS types. Includes `FederationRequest`, `FederationListResponse<T>`, `FederationGetResponse<T>`, `FederationCapabilitiesResponse`, error envelope, `_source` tag. | #462 | sonnet | feat/federation-m3-types | — | 4K | Reusable from gateway server + client + harness. Pure types — no I/O, no NestJS. |
|
||||
| FED-M3-02 | not-started | `tools/federation-harness/` scaffold: `docker-compose.two-gateways.yml` (Server A + Server B + step-CA), `seed.ts` (provisions grants, peers, sample tasks/notes/credentials per scope variant), `harness.ts` helper (boots stack, returns typed clients). README documents harness use. | #462 | sonnet | feat/federation-m3-harness | DEPLOY-04 (soft) | 8K | Falls back to local docker-compose if `mos-test-1/-2` not yet redeployed (DEPLOY chain blocked on IMG-FIX). Permanent test infra used by M3+. |
|
||||
| FED-M3-03 | not-started | `apps/gateway/src/federation/server/federation-auth.guard.ts` (NestJS guard). Validates inbound client cert from Fastify TLS context, extracts `grantId` + `subjectUserId` from custom OIDs, loads grant from DB, asserts `status='active'`, attaches `FederationContext` to request. | #462 | sonnet | feat/federation-m3-auth-guard | M3-01 | 8K | Reuses OID parsing logic mirrored from `ca.service.ts` post-issuance verification. 401 on malformed/missing OIDs; 403 on revoked/expired/missing grant. |
|
||||
| FED-M3-04 | not-started | `apps/gateway/src/federation/server/scope.service.ts`. Pipeline: (1) resource allowlist + excluded check, (2) native RBAC eval as `subjectUserId`, (3) scope filter intersection (`include_teams`, `include_personal`), (4) `max_rows_per_query` cap. Pure service — DB calls injected. | #462 | sonnet | feat/federation-m3-scope-service | M3-01 | 10K | Hardest correctness target in M3. Reuses `parseFederationScope` (M2-03). Returns either `{ allowed: true, filter }` or structured deny reason for audit. |
|
||||
| FED-M3-05 | not-started | `apps/gateway/src/federation/server/verbs/list.controller.ts`. Wires AuthGuard → ScopeService → tasks/notes/memory query layer; applies row cap; tags rows with `_source`. Resource selector via path param. | #462 | sonnet | feat/federation-m3-verb-list | M3-03, M3-04 | 6K | Routes: `POST /api/federation/v1/list/:resource`. No body persistence. Audit write deferred to M4. |
|
||||
| FED-M3-06 | not-started | `apps/gateway/src/federation/server/verbs/get.controller.ts`. Single-resource fetch by id; same pipeline as list. 404 on not-found, 403 on RBAC/scope deny — both audited the same way. | #462 | sonnet | feat/federation-m3-verb-get | M3-03, M3-04 | 6K | `POST /api/federation/v1/get/:resource/:id`. Mirrors list controller patterns. |
|
||||
| FED-M3-07 | not-started | `apps/gateway/src/federation/server/verbs/capabilities.controller.ts`. Read-only enumeration: returns `{ resources, excluded_resources, max_rows_per_query, supported_verbs }` derived from grant scope. Always allowed for an active grant — no RBAC eval. | #462 | sonnet | feat/federation-m3-verb-capabilities | M3-03 | 4K | `GET /api/federation/v1/capabilities`. Smallest verb; useful sanity check that mTLS + auth guard work end-to-end. |
|
||||
| FED-M3-08 | not-started | `apps/gateway/src/federation/client/federation-client.service.ts`. Outbound mTLS dialer: picks `(certPem, sealed clientKey)` from `federation_peers`, unwraps key, builds undici Agent with mTLS, calls peer verb, parses typed response, wraps non-2xx into `FederationClientError`. | #462 | sonnet | feat/federation-m3-client | M3-01 | 8K | Independent of server stream — can land in parallel with M3-03/04. Cert/key cached per-peer; flushed by future M5/M6 logic. |
|
||||
| FED-M3-09 | not-started | `apps/gateway/src/federation/client/query-source.service.ts`. Accepts `source: "local" \| "federated:<host>" \| "all"` from gateway query layer; for `"all"` fans out to local + each peer in parallel; merges results; tags every row with `_source`. | #462 | sonnet | feat/federation-m3-query-source | M3-08 | 8K | Per-peer failure surfaces as `_partial: true` in response, not hard failure (sets up M5 offline UX). M5 adds caching + circuit breaker on top. |
|
||||
| FED-M3-10 | not-started | Integration tests for MILESTONES.md M3 acceptance #6 (malformed OIDs → 401; valid cert + revoked grant → 403) and #7 (`max_rows_per_query` cap). Real PG, mocked TLS context (Fastify req shim). | #462 | sonnet | feat/federation-m3-integration | M3-05, M3-06 | 8K | Vitest profile gated by `FEDERATED_INTEGRATION=1`. Single-gateway suite; no harness required. |
|
||||
| FED-M3-11 | not-started | E2E tests for MILESTONES.md M3 acceptance #1, #2, #3, #4, #5, #8, #9, #10 (8 cases). Uses harness from M3-02; two real gateways, real Step-CA, real mTLS. Each test asserts both happy-path response and audit/no-persist invariants. | #462 | sonnet | feat/federation-m3-e2e | M3-02, M3-09 | 12K | Largest single task. Each acceptance gets its own `it(...)` for clear failure attribution. |
|
||||
| FED-M3-12 | not-started | Independent security review (sonnet, not author of M3-03/04/05/06/07/08/09): focus on cert-SAN spoofing, OID extraction edge cases, scope-bypass via filter manipulation, RBAC-bypass via subjectUser swap, response leakage when scope deny. | #462 | sonnet | feat/federation-m3-security-review | M3-11 | 10K | Two review rounds budgeted. PRD requires explicit test for every 401/403 path — review verifies coverage. |
|
||||
| FED-M3-13 | not-started | Docs update: `docs/federation/SETUP.md` mTLS handshake section, new `docs/federation/HARNESS.md` for federation-harness usage, OID reference table in SETUP.md, scope enforcement pipeline diagram. Runbook still M7-deferred. | #462 | haiku | feat/federation-m3-docs | M3-12 | 5K | One ASCII diagram for the auth-guard → scope → RBAC pipeline; helps future reviewers reason about denial paths. |
|
||||
| FED-M3-14 | not-started | PR aggregate close, CI green, merge to main, close #462. Release tag `fed-v0.3.0-m3`. Update mission manifest M3 row → done; M4 row → in-progress when work begins. | #462 | sonnet | chore/federation-m3-close | M3-13 | 3K | Same close pattern as M1-12 / M2-13. |
|
||||
|
||||
**M3 estimate:** ~100K tokens (vs MILESTONES.md 40K — same per-task breakdown pattern as M1/M2: tests, review, and docs split out from implementation cost). Largest milestone in the federation mission.
|
||||
|
||||
@@ -118,10 +118,6 @@ Goal: Two federated gateways exchange real data over mTLS. Inbound requests pass
|
||||
|
||||
**Test bed fallback:** If `mos-test-1.woltje.com` / `mos-test-2.woltje.com` are still blocked on `FED-M2-DEPLOY-IMG-FIX` when M3-11 is ready to run, the harness's local `docker-compose.two-gateways.yml` is a sufficient stand-in. Production-host validation moves to M7 acceptance suite (PRD AC-12).
|
||||
|
||||
**Backlog sync — 2026-06-24 (orchestrator):** Status reconciled against `origin/main` (release 0.0.48). Landed on main: **FED-M3-01** (DTOs, PR #506), **FED-M3-02** (harness scaffold, PR #505), **FED-M3-03** (mTLS auth-guard, PR #509 — CRIT-1/2 + HIGH-1..4 remediated in-PR), **FED-M3-08** (outbound mTLS client, PR #508). With M3-01/03/08 merged, three cards became dependency-clear and were dispatched to the idle coder lane: **FED-M3-04** scope.service → coder0 (`feat/federation-m3-scope-service`); **FED-M3-09** query-source + **FED-M3-07** capabilities verb → coder1 (`feat/federation-m3-query-source` first). Reviewer warmed for the M3 trust-boundary PRs. Remaining blocked-by-DAG: M3-05/06 (await M3-04), M3-10 (await M3-05/06), M3-11 (await M3-09), M3-12→14 (tail). Deploy chain (DEPLOY-IMG-FIX → 03/04) still independent of M3 code — harness local docker-compose fallback covers M3-11.
|
||||
|
||||
**Backlog sync #2 — 2026-06-24 (orchestrator):** **FED-M3-09** (query-source) merged via PR #673 and **FED-M3-07** (capabilities) merged via PR #674 — both squash-merged on independent agent review-of-record + green CI (formal Gitea approve unavailable under the shared service account; merge is not gated by the self-approve guard). **FED-M3-05** (list verb) dispatched to coder1 (based on the M3-04 branch, rebase onto main once #672 lands). **FED-M3-04** (scope.service, PR #672) is in review-changes (one include_personal no-leak test outstanding). **DAG fix:** corrected `FED-M3-11` depends_on from `M3-02, M3-09` → `M3-02, M3-04, M3-05, M3-06, M3-09` — the E2E acceptance cases (#1–#5, #8–#10) exercise list/get over mTLS, so the server verbs + scope service are hard prerequisites; the original edge set omitted them and caused a premature M3-11 dispatch. Note: M3 read-path invariant for M3-11 is **no-persist + existing enrollment audit only** — read-verb audit-log writes are deferred to M4 (see M3-05/06 notes), so M3-11 must not assert read-audit-log entries.
|
||||
|
||||
## Milestone 4 — search + audit + rate limit (FED-M4)
|
||||
|
||||
_Deferred. Issue #463._
|
||||
|
||||
@@ -1,79 +0,0 @@
|
||||
# Mosaic Fleet — NORTH STAR
|
||||
|
||||
> **Generated file — do not edit by hand.**
|
||||
> Projected deterministically from [`NORTH_STAR.yaml`](./NORTH_STAR.yaml) by the pure
|
||||
> generator in `packages/mosaic/src/commands/fleet.ts` (`renderNorthStarMarkdown`).
|
||||
> Edit the YAML, then regenerate. Self-contained Mosaic — no Hermes dependency.
|
||||
|
||||
## Mission
|
||||
|
||||
A self-driving Mosaic system that 24/7 unattended converts a machine-readable goal set into merged, CI-green, budget-bounded change — looping plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN native backlog/dispatch engine. Mosaic is general-purpose: the user declares the system type they want (software delivery, personal assistant, research, business/operations, …) and the orchestrator provisions the matching persona roster and structure; the delivery fleet is one profile among many.
|
||||
|
||||
## Substrate
|
||||
|
||||
The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's native Postgres storage service (@mosaicstack/db drizzle; PGlite-embedded by default, full Postgres by config). NOT Hermes.
|
||||
|
||||
## Standing objectives
|
||||
|
||||
- **NS-1** — Single machine-readable source (this file) drives planning; prose docs are projections.
|
||||
- **NS-2** — Every backlog item is an independently-shippable unit with stable id, priority, depends_on DAG, represented as a Mosaic Backlog card; spend tracked as advisory projection.
|
||||
- **NS-3** — The supervisor guarantees movement: no idle agent while ready dependency-satisfied work exists; no empty backlog without a replan request; assignment via Mosaic native dispatch/claim.
|
||||
- **NS-4** — Exactly one merge-gate approver; nothing reaches main except via pr-merge.sh after pr-ci-wait.sh success; Gitea branch protection is the backstop.
|
||||
- **NS-5** — Every unit bounded by wall-clock TTL on its claim; token caps enforced only where a real meter exists, else advisory.
|
||||
- **NS-6** — Context cleared between tasks for ephemeral runners (reset_between_tasks); persona+mission re-injected per task.
|
||||
- **NS-7** — Meta-loop (session-review + enhancer) continuously proposes small fleet-improvement PRs.
|
||||
- **NS-8** — Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored before every dispatch and every merge.
|
||||
- **NS-9** — Mosaic is a general-purpose multi-agent system: the user declares the SYSTEM TYPE to run (e.g. software delivery, personal assistant, research, business/operations) and the orchestrator provisions the matching persona roster and org structure from a cross-domain baseline persona library; the delivery/coding fleet is one profile among many.
|
||||
|
||||
## Success criteria
|
||||
|
||||
- **AC-NS-1** — The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer) healthy across reboot.
|
||||
- **AC-NS-2** — A goal added to this YAML is decomposed to cards and either merged or escalated, with no human in the loop.
|
||||
- **AC-NS-3** — No PR merges with failure/error/no-status/timeout CI, and none bypass pr-merge.sh.
|
||||
- **AC-NS-4** — TTL is enforced on claims; token caps remain advisory until a real meter exists.
|
||||
- **AC-NS-5** — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
|
||||
- **AC-NS-6** — A user can declare a system type and the fleet provisions the matching persona roster + topology from the baseline library, with no code change.
|
||||
- **AC-NS-7** — A user-customized persona (edited or added via the orchestrator) survives `mosaic update`: baseline reseed never clobbers user overrides.
|
||||
|
||||
## Workstreams
|
||||
|
||||
| id | title |
|
||||
| --- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| A | Substrate — Mosaic Backlog on native Postgres storage service |
|
||||
| B | Supervisor — movement guarantee, two-agent floor, dispatch/claim |
|
||||
| C | Planner — goal decomposition into independently-shippable cards |
|
||||
| D | Merge-gate — single approver, pr-merge.sh after CI wait |
|
||||
| E | Meta-loop — session-review + enhancer improvement PRs |
|
||||
| F | Safety-rails — TTL claims, advisory spend, PAUSE kill-switch |
|
||||
| H | Personas & system profiles — cross-domain library, system-type provisioning, update-surviving customization |
|
||||
|
||||
## Goals (backlog projection)
|
||||
|
||||
| id | title | phase | priority | depends_on |
|
||||
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ----------- | ---------- |
|
||||
| A1 | Machine-readable NORTH_STAR.yaml + Markdown projection | 1 | must-have | — |
|
||||
| A2 | Mosaic Backlog schema + storage-service card store (drizzle/PGlite) | 1 | must-have | A1 |
|
||||
| A3a | Card lifecycle — create/claim/release with stable ids + depends_on DAG | 1 | must-have | A2 |
|
||||
| A3b | TTL-bounded claim enforcement (wall-clock) on cards | 1 | must-have | A3a |
|
||||
| A4 | Advisory spend projection per card (degrades to TTL, no real meter) | 1 | should-have | A3a |
|
||||
| B1 | Supervisor tick — readiness scan, two-agent-floor health check | 2 | must-have | A3a |
|
||||
| B2 | Native dispatch/claim — assign ready dependency-satisfied work | 2 | must-have | A3b, B1 |
|
||||
| B3a | Planner decompose — goal added to YAML → cards | 2 | must-have | A2, B1 |
|
||||
| B3b | Replan request on empty backlog; escalate on no-decompose | 2 | should-have | B3a |
|
||||
| G1 | PAUSE kill-switch + merge-gate honored before dispatch and merge | 2 | must-have | B2 |
|
||||
| H1 | Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles) | 1 | must-have | A1 |
|
||||
| H2 | System-type profiles — declarative mapping of system type to persona roster + topology | 2 | must-have | H1 |
|
||||
| H3 | System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure | 2 | must-have | H2 |
|
||||
| H4 | Update-surviving persona customization — ad-hoc edits/additions persisted in a PRESERVE-protected override layer (baseline merged with overrides) | 2 | must-have | H1 |
|
||||
|
||||
## Assumptions (vetoable)
|
||||
|
||||
- **ASM-1** (vetoable) — The Mosaic Backlog on the native Postgres storage service is the backlog of record.
|
||||
- **ASM-2** (vetoable) — Claude gate roles have no native busy status, so readiness = pane-idle + heartbeat.
|
||||
- **ASM-3** (vetoable) — Two-agent floor = 1 orchestrator + >=1 enhancer.
|
||||
- **ASM-4** (vetoable) — Baseline personas ship in framework/fleet/roles/ (reseeded on update); user overrides live in a separate PRESERVE_PATHS-protected layer and win on merge.
|
||||
|
||||
## Spend
|
||||
|
||||
- **advisory:** true
|
||||
- No per-task token meter yet; budgets degrade to TTL. Spend is tracked only as an advisory projection alongside each card.
|
||||
@@ -1,215 +0,0 @@
|
||||
# Mosaic Fleet — NORTH_STAR (machine-readable source of truth)
|
||||
#
|
||||
# This file is the single machine-readable source of truth for fleet planning.
|
||||
# Prose docs (including NORTH_STAR.md) are deterministic PROJECTIONS of this file.
|
||||
# Regenerate the Markdown projection with the pure generator in
|
||||
# packages/mosaic/src/commands/fleet.ts (renderNorthStarMarkdown). Edit the YAML,
|
||||
# never the .md.
|
||||
#
|
||||
# Self-contained Mosaic. NO Hermes runtime dependency. The backlog of record is
|
||||
# the Mosaic Backlog on Mosaic's OWN native Postgres storage service.
|
||||
|
||||
version: 1
|
||||
|
||||
mission: >-
|
||||
A self-driving Mosaic system that 24/7 unattended converts a machine-readable
|
||||
goal set into merged, CI-green, budget-bounded change — looping
|
||||
plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN native
|
||||
backlog/dispatch engine. Mosaic is general-purpose: the user declares the
|
||||
system type they want (software delivery, personal assistant, research,
|
||||
business/operations, …) and the orchestrator provisions the matching persona
|
||||
roster and structure; the delivery fleet is one profile among many.
|
||||
|
||||
substrate:
|
||||
note: >-
|
||||
The Mosaic Backlog is the backlog of record + dispatch engine, built on
|
||||
Mosaic's native Postgres storage service (@mosaicstack/db drizzle;
|
||||
PGlite-embedded by default, full Postgres by config). NOT Hermes.
|
||||
|
||||
standing_objectives:
|
||||
- id: NS-1
|
||||
text: >-
|
||||
Single machine-readable source (this file) drives planning; prose docs are
|
||||
projections.
|
||||
- id: NS-2
|
||||
text: >-
|
||||
Every backlog item is an independently-shippable unit with stable id,
|
||||
priority, depends_on DAG, represented as a Mosaic Backlog card; spend
|
||||
tracked as advisory projection.
|
||||
- id: NS-3
|
||||
text: >-
|
||||
The supervisor guarantees movement: no idle agent while ready
|
||||
dependency-satisfied work exists; no empty backlog without a replan
|
||||
request; assignment via Mosaic native dispatch/claim.
|
||||
- id: NS-4
|
||||
text: >-
|
||||
Exactly one merge-gate approver; nothing reaches main except via
|
||||
pr-merge.sh after pr-ci-wait.sh success; Gitea branch protection is the
|
||||
backstop.
|
||||
- id: NS-5
|
||||
text: >-
|
||||
Every unit bounded by wall-clock TTL on its claim; token caps enforced
|
||||
only where a real meter exists, else advisory.
|
||||
- id: NS-6
|
||||
text: >-
|
||||
Context cleared between tasks for ephemeral runners
|
||||
(reset_between_tasks); persona+mission re-injected per task.
|
||||
- id: NS-7
|
||||
text: >-
|
||||
Meta-loop (session-review + enhancer) continuously proposes small
|
||||
fleet-improvement PRs.
|
||||
- id: NS-8
|
||||
text: >-
|
||||
Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored
|
||||
before every dispatch and every merge.
|
||||
- id: NS-9
|
||||
text: >-
|
||||
Mosaic is a general-purpose multi-agent system: the user declares the
|
||||
SYSTEM TYPE to run (e.g. software delivery, personal assistant, research,
|
||||
business/operations) and the orchestrator provisions the matching persona
|
||||
roster and org structure from a cross-domain baseline persona library; the
|
||||
delivery/coding fleet is one profile among many.
|
||||
|
||||
success_criteria:
|
||||
- id: AC-NS-1
|
||||
text: >-
|
||||
The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer)
|
||||
healthy across reboot.
|
||||
- id: AC-NS-2
|
||||
text: >-
|
||||
A goal added to this YAML is decomposed to cards and either merged or
|
||||
escalated, with no human in the loop.
|
||||
- id: AC-NS-3
|
||||
text: >-
|
||||
No PR merges with failure/error/no-status/timeout CI, and none bypass
|
||||
pr-merge.sh.
|
||||
- id: AC-NS-4
|
||||
text: >-
|
||||
TTL is enforced on claims; token caps remain advisory until a real meter
|
||||
exists.
|
||||
- id: AC-NS-5
|
||||
text: >-
|
||||
Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
|
||||
- id: AC-NS-6
|
||||
text: >-
|
||||
A user can declare a system type and the fleet provisions the matching
|
||||
persona roster + topology from the baseline library, with no code change.
|
||||
- id: AC-NS-7
|
||||
text: >-
|
||||
A user-customized persona (edited or added via the orchestrator) survives
|
||||
`mosaic update`: baseline reseed never clobbers user overrides.
|
||||
|
||||
workstreams:
|
||||
- id: A
|
||||
title: Substrate — Mosaic Backlog on native Postgres storage service
|
||||
- id: B
|
||||
title: Supervisor — movement guarantee, two-agent floor, dispatch/claim
|
||||
- id: C
|
||||
title: Planner — goal decomposition into independently-shippable cards
|
||||
- id: D
|
||||
title: Merge-gate — single approver, pr-merge.sh after CI wait
|
||||
- id: E
|
||||
title: Meta-loop — session-review + enhancer improvement PRs
|
||||
- id: F
|
||||
title: Safety-rails — TTL claims, advisory spend, PAUSE kill-switch
|
||||
- id: H
|
||||
title: Personas & system profiles — cross-domain library, system-type provisioning, update-surviving customization
|
||||
|
||||
goals:
|
||||
- id: A1
|
||||
title: Machine-readable NORTH_STAR.yaml + Markdown projection
|
||||
phase: 1
|
||||
priority: must-have
|
||||
depends_on: []
|
||||
- id: A2
|
||||
title: Mosaic Backlog schema + storage-service card store (drizzle/PGlite)
|
||||
phase: 1
|
||||
priority: must-have
|
||||
depends_on: [A1]
|
||||
- id: A3a
|
||||
title: Card lifecycle — create/claim/release with stable ids + depends_on DAG
|
||||
phase: 1
|
||||
priority: must-have
|
||||
depends_on: [A2]
|
||||
- id: A3b
|
||||
title: TTL-bounded claim enforcement (wall-clock) on cards
|
||||
phase: 1
|
||||
priority: must-have
|
||||
depends_on: [A3a]
|
||||
- id: A4
|
||||
title: Advisory spend projection per card (degrades to TTL, no real meter)
|
||||
phase: 1
|
||||
priority: should-have
|
||||
depends_on: [A3a]
|
||||
- id: B1
|
||||
title: Supervisor tick — readiness scan, two-agent-floor health check
|
||||
phase: 2
|
||||
priority: must-have
|
||||
depends_on: [A3a]
|
||||
- id: B2
|
||||
title: Native dispatch/claim — assign ready dependency-satisfied work
|
||||
phase: 2
|
||||
priority: must-have
|
||||
depends_on: [A3b, B1]
|
||||
- id: B3a
|
||||
title: Planner decompose — goal added to YAML → cards
|
||||
phase: 2
|
||||
priority: must-have
|
||||
depends_on: [A2, B1]
|
||||
- id: B3b
|
||||
title: Replan request on empty backlog; escalate on no-decompose
|
||||
phase: 2
|
||||
priority: should-have
|
||||
depends_on: [B3a]
|
||||
- id: G1
|
||||
title: PAUSE kill-switch + merge-gate honored before dispatch and merge
|
||||
phase: 2
|
||||
priority: must-have
|
||||
depends_on: [B2]
|
||||
- id: H1
|
||||
title: Cross-domain baseline persona library (exec, marketing, ops, research, assistant + engineering roles)
|
||||
phase: 1
|
||||
priority: must-have
|
||||
depends_on: [A1]
|
||||
- id: H2
|
||||
title: System-type profiles — declarative mapping of system type to persona roster + topology
|
||||
phase: 2
|
||||
priority: must-have
|
||||
depends_on: [H1]
|
||||
- id: H3
|
||||
title: System-type provisioning — user declares type; orchestrator instantiates the matching roster + structure
|
||||
phase: 2
|
||||
priority: must-have
|
||||
depends_on: [H2]
|
||||
- id: H4
|
||||
title: Update-surviving persona customization — ad-hoc edits/additions persisted in a PRESERVE-protected override layer (baseline merged with overrides)
|
||||
phase: 2
|
||||
priority: must-have
|
||||
depends_on: [H1]
|
||||
|
||||
assumptions:
|
||||
- id: ASM-1
|
||||
vetoable: true
|
||||
text: >-
|
||||
The Mosaic Backlog on the native Postgres storage service is the backlog
|
||||
of record.
|
||||
- id: ASM-2
|
||||
vetoable: true
|
||||
text: >-
|
||||
Claude gate roles have no native busy status, so readiness = pane-idle +
|
||||
heartbeat.
|
||||
- id: ASM-3
|
||||
vetoable: true
|
||||
text: 'Two-agent floor = 1 orchestrator + >=1 enhancer.'
|
||||
- id: ASM-4
|
||||
vetoable: true
|
||||
text: >-
|
||||
Baseline personas ship in framework/fleet/roles/ (reseeded on update);
|
||||
user overrides live in a separate PRESERVE_PATHS-protected layer and win
|
||||
on merge.
|
||||
|
||||
spend:
|
||||
advisory: true
|
||||
note: >-
|
||||
No per-task token meter yet; budgets degrade to TTL. Spend is tracked only
|
||||
as an advisory projection alongside each card.
|
||||
@@ -1,138 +0,0 @@
|
||||
# Fleet Backlog Conventions
|
||||
|
||||
The **backlog** is Mosaic's native backlog-of-record for fleet work. It is built
|
||||
end-to-end on Mosaic's own storage layer (`@mosaicstack/db`, drizzle/Postgres)
|
||||
and surfaced as `mosaic fleet backlog <sub> --json`.
|
||||
|
||||
> **Mosaic-native, no Hermes.** This backlog REPLACES the former Hermes adapter.
|
||||
> There is **no** runtime dependency on Hermes, `hermes kanban`, or `~/.hermes`
|
||||
> anywhere in this feature. Anything previously delegated to Hermes is recreated
|
||||
> here on Mosaic's own Postgres storage layer.
|
||||
|
||||
## Storage tier — PGlite by default, Postgres by config
|
||||
|
||||
The backlog uses the existing Mosaic storage layer; there is **no** new database
|
||||
engine (no sqlite, no raw client).
|
||||
|
||||
| Condition | Tier | Data location |
|
||||
| ------------------------------ | -------------------- | -------------------------------- |
|
||||
| `DATABASE_URL` set | Full server Postgres | the configured database |
|
||||
| `PGLITE_DATA_DIR` set (no URL) | Embedded PGlite | that directory |
|
||||
| neither (default) | Embedded PGlite | `~/.config/mosaic/fleet/backlog` |
|
||||
|
||||
PGlite is real Postgres semantics in-process — including the row locks the atomic
|
||||
claim relies on — so the **same code** runs on a laptop (embedded, single-host
|
||||
default) and on a full Postgres deployment. Switching tiers is config-only.
|
||||
|
||||
The schema (`backlog` table) is created automatically on first CLI use:
|
||||
`runMigrations()` for Postgres, `runPgliteMigrations()` for embedded PGlite.
|
||||
|
||||
### Update safety
|
||||
|
||||
The embedded PGlite store lives under `~/.config/mosaic/fleet/backlog`, which is
|
||||
listed in `PRESERVE_PATHS` in `packages/mosaic/framework/install.sh`. This means
|
||||
`mosaic update` (which runs the framework sync with `rsync --delete`) will **not**
|
||||
wipe the operator's backlog — same protection as the roster, per-agent env, and
|
||||
heartbeat run dir.
|
||||
|
||||
## Card schema
|
||||
|
||||
A card is one row in the `backlog` table:
|
||||
|
||||
| Column | Type | Notes |
|
||||
| ------------------- | ------------------- | ------------------------------------------------------------- |
|
||||
| `id` | text (PK) | Stable, caller-supplied id (e.g. `A4`, `fleet-001`). |
|
||||
| `title` | text | Required. |
|
||||
| `body` | text (nullable) | Free-form description. |
|
||||
| `phase` | text (nullable) | Board/phase grouping (see below). |
|
||||
| `priority` | int (default 0) | **Higher = sooner.** Claim picks the max-priority ready card. |
|
||||
| `status` | enum | `ready` \| `claimed` \| `blocked` \| `done`. |
|
||||
| `depends_on` | jsonb `string[]` | DAG edges — ids of cards this one depends on. |
|
||||
| `claim_owner` | text (nullable) | Owner token of the active claim. |
|
||||
| `claim_ttl_seconds` | int (nullable) | TTL of the active claim. |
|
||||
| `claimed_at` | timestamptz (null) | When the claim was taken. `claimed_at + ttl` = expiry. |
|
||||
| `attempts` | int (default 0) | Incremented each time the card is claimed. |
|
||||
| `idempotency_key` | text (unique, null) | Dedups `create`; NULLs are distinct in Postgres. |
|
||||
| `acceptance` | jsonb (nullable) | Acceptance criteria (array of strings or object). |
|
||||
| `created_at` | timestamptz | |
|
||||
| `updated_at` | timestamptz | |
|
||||
|
||||
`depends_on` is modeled as a `jsonb` array column rather than a separate edge
|
||||
table. Justification: it matches the repo's existing style (e.g. `tasks.tags`,
|
||||
`agents.skills`, `routing_rules.conditions` are all jsonb arrays), keeps a card
|
||||
self-contained, and the DAG is small (per-card dependency lists), so a join table
|
||||
would add ceremony without benefit.
|
||||
|
||||
### Board / phase convention
|
||||
|
||||
`phase` is a free-form grouping string used as the board column / milestone label
|
||||
(e.g. `M1`, `fleet`, `infra`). `list --phase <phase>` filters to one board lane.
|
||||
`priority` orders cards **within** the ready pool regardless of phase.
|
||||
|
||||
## Status lifecycle
|
||||
|
||||
```
|
||||
create
|
||||
│
|
||||
▼
|
||||
┌──────► ready ───── claim ─────► claimed ───── complete ─────► done
|
||||
│ │ │
|
||||
│ block reclaim (TTL expiry or --id)
|
||||
│ ▼ │
|
||||
│ blocked └──────────────────────────┘ (back to ready)
|
||||
└──────────┘ (reclaim / re-create can return a card to ready)
|
||||
```
|
||||
|
||||
- **ready** — eligible to be claimed once every `depends_on` card is `done`.
|
||||
- **claimed** — a worker holds it; `claim_owner` + `claimed_at` set.
|
||||
- **blocked** — explicitly parked; never auto-claimed.
|
||||
- **done** — completed; satisfies dependents.
|
||||
|
||||
## Atomic claim (`FOR UPDATE SKIP LOCKED`) + TTL
|
||||
|
||||
`claim` is atomic. Inside a single transaction it locks candidate `ready` rows
|
||||
with `SELECT ... FOR UPDATE SKIP LOCKED` (via the drizzle `sql` operator), picks
|
||||
the highest-priority deps-satisfied card, and flips it to `claimed`. Because a row
|
||||
already locked by a concurrent claimer is **skipped**, two claimers can **never**
|
||||
both win the same card — the loser falls through to the next candidate or gets
|
||||
`null`. (Proven by the concurrency tests in `packages/db/src/backlog.spec.ts`.)
|
||||
|
||||
- **Deps gate:** a card is only claimable when every id in `depends_on` is `done`.
|
||||
- **TTL:** `claim --ttl <sec>` (default **900s**) records `claim_ttl_seconds`.
|
||||
- **reclaim:** releases claims whose `claimed_at + ttl` is in the past (expired)
|
||||
back to `ready`, clearing the claim fields. `reclaim --id <id>` force-releases a
|
||||
specific card regardless of expiry. This is how a crashed worker's card returns
|
||||
to the pool.
|
||||
|
||||
## CLI — `mosaic fleet backlog <sub> --json`
|
||||
|
||||
All subcommands support `--json`.
|
||||
|
||||
| Subcommand | Purpose |
|
||||
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `create --id --title [--body --phase --priority --depends-on --acceptance --idempotency-key]` | Create a card; `idempotency_key` dedups (repeat returns the existing card). |
|
||||
| `list [--status --phase --ready-only]` | List cards. `--ready-only` = status `ready` AND all deps `done`. |
|
||||
| `claim --owner [--ttl <sec> --id <id>]` | Atomically claim the highest-priority ready card (or `--id`). Returns the card or `null`. |
|
||||
| `reclaim [--id <id>]` | Release expired claims (or a specific card) back to `ready`. |
|
||||
| `link --from --to` | Add a `depends_on` edge (`--from` depends on `--to`). |
|
||||
| `stats` | Counts by status, oldest-ready age, expired-claim count. |
|
||||
| `block --id` | Set a card to `blocked`. |
|
||||
| `complete --id` | Set a card to `done` (releases any claim). |
|
||||
|
||||
### Example
|
||||
|
||||
```sh
|
||||
# Seed two cards, the second depends on the first.
|
||||
mosaic fleet backlog create --id A1 --title "schema" --priority 5
|
||||
mosaic fleet backlog create --id A2 --title "service" --depends-on A1 --priority 9
|
||||
|
||||
# A2 is gated on A1, so claim returns A1 first.
|
||||
mosaic fleet backlog claim --owner worker-1 --ttl 600 --json
|
||||
|
||||
# Finish A1; now A2 is ready.
|
||||
mosaic fleet backlog complete --id A1
|
||||
mosaic fleet backlog list --ready-only --json
|
||||
|
||||
# Recover stalled work.
|
||||
mosaic fleet backlog reclaim --json
|
||||
```
|
||||
@@ -353,25 +353,6 @@ re-evaluate if isolation or write-volume demands it.
|
||||
- **Docs as projections:** `docs/TASKS.md` and `MISSION-MANIFEST.md` become generated exports of the DB, not hand-maintained.
|
||||
- **Sub-decision pending:** dedicated schema in existing PG instance (recommended) vs. dedicated PG instance. Revisit if isolation or write-volume demands it.
|
||||
|
||||
## Decisions of record (2026-06-24, with Jason)
|
||||
|
||||
- **Per-agent model switch (operator-configurable, NOT a global lock):** model selection is
|
||||
**per-agent**, never a host-global pin. Claude sessions MUST NOT be locked to a single model in
|
||||
`~/.claude/settings.json`; each agent chooses its model independently. The plumbing already exists —
|
||||
roster `model_hint` → `MOSAIC_AGENT_MODEL` → `start-agent-session.sh` appends `--model <hint>` to that
|
||||
agent's harness (claude or pi); settable today via `mosaic fleet add|edit <agent> --model <hint>`.
|
||||
**North-star target:** surface this as a **per-agent model switch in the webUI** (with CLI/TUI parity
|
||||
per MVP-X1) — read the roster, expose a per-agent model dropdown, write `model_hint` back, and restart
|
||||
that one agent to apply. Unset = inherit the harness default. This **composes with** the budget
|
||||
downgrade ladder (opus → sonnet → haiku, then Claude → Codex): the operator sets the per-agent model
|
||||
_intent/ceiling_; budget pacing may downgrade within policy. Tracked as a Fleet `TASKS.md` entry under
|
||||
the Phase-5 webUI surface.
|
||||
- **Orchestrator runtime (confirmed live):** the **orchestrator and enhancer run Claude Opus 4.8 in the
|
||||
Claude Code harness**; only workers (coder/reviewer) run pi/gpt-5.5. Consistent with the 2026-06-20
|
||||
"Claude reserved for Claude Code only" decision (the orchestrator runs _in_ Claude Code, not an
|
||||
alternate Claude harness). Pi/gpt-5.5 as the orchestrator is permitted **only if proven** at least as
|
||||
satisfactory; absent that proof, the orchestrator stays on Claude Opus 4.8.
|
||||
|
||||
## Future enhancements (north-star, post-MVP — not on the MVP track)
|
||||
|
||||
- **Mosaic Claude Discord Plugin** — a first-party Mosaic Discord connector that properly
|
||||
|
||||
@@ -293,24 +293,13 @@ Each OIDC provider requires its client ID, client secret, and issuer URL togethe
|
||||
|
||||
### Plugins
|
||||
|
||||
| Variable | Description |
|
||||
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `DISCORD_BOT_TOKEN` | Discord bot token (enables Discord plugin) |
|
||||
| `DISCORD_SERVICE_TOKEN` | Required high-entropy service credential used to authenticate and sign Discord ingress; inject through the approved secret mechanism only |
|
||||
| `DISCORD_SERVICE_USER_ID` | Required Mosaic service-principal user ID that owns persisted Discord conversations; the original Discord user ID remains audit metadata |
|
||||
| `DISCORD_GUILD_ID` | Discord guild/server ID |
|
||||
| `DISCORD_GATEWAY_URL` | Gateway URL for Discord plugin to call (default: `http://localhost:14242`) |
|
||||
| `DISCORD_ALLOWED_GUILD_IDS` | Required comma-separated Discord guild snowflake allowlist; default-deny |
|
||||
| `DISCORD_ALLOWED_CHANNEL_IDS` | Required comma-separated Discord channel snowflake allowlist; default-deny |
|
||||
| `DISCORD_ALLOWED_USER_IDS` | Required comma-separated Discord user snowflake allowlist; default-deny |
|
||||
| `TELEGRAM_BOT_TOKEN` | Telegram bot token (enables Telegram plugin) |
|
||||
| `TELEGRAM_GATEWAY_URL` | Gateway URL for Telegram plugin to call |
|
||||
|
||||
### Discord ingress security
|
||||
|
||||
When `DISCORD_BOT_TOKEN` is configured, `DISCORD_SERVICE_TOKEN`, `DISCORD_SERVICE_USER_ID`, and all three Discord allowlists are required. Gateway startup fails rather than enabling a broad or unauthenticated remote-control surface. The service user ID identifies a provisioned Mosaic service principal for persistence; the original Discord user ID is retained in ingress audit metadata. The service token is a secret supplied by the approved runtime secret mechanism and is never committed or logged.
|
||||
|
||||
Inbound Discord messages must originate from an allowed guild, channel, and user, mention the bot, and carry a signed envelope containing the native Discord message ID and a generated correlation ID. The gateway validates the service identity, envelope signature, and allowlists again before dispatching. Replayed Discord message IDs are rejected during the bounded ingress replay window. Durable inbox/idempotency retention is introduced with Tess durable state.
|
||||
| Variable | Description |
|
||||
| ---------------------- | -------------------------------------------------------------------------- |
|
||||
| `DISCORD_BOT_TOKEN` | Discord bot token (enables Discord plugin) |
|
||||
| `DISCORD_GUILD_ID` | Discord guild/server ID |
|
||||
| `DISCORD_GATEWAY_URL` | Gateway URL for Discord plugin to call (default: `http://localhost:14242`) |
|
||||
| `TELEGRAM_BOT_TOKEN` | Telegram bot token (enables Telegram plugin) |
|
||||
| `TELEGRAM_GATEWAY_URL` | Gateway URL for Telegram plugin to call |
|
||||
|
||||
### Observability
|
||||
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
# Scratchpad — FED-M3-04 Scope Service
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `apps/gateway/src/federation/server/scope.service.ts` for the M3 inbound federation scope-enforcement pipeline.
|
||||
|
||||
## Scope / Constraints
|
||||
|
||||
- Task: FED-M3-04, issue #462.
|
||||
- Branch: `feat/federation-m3-scope-service` from `origin/main` @ 0.0.48.
|
||||
- Pure service: no direct DB access; native RBAC/data access is injected per evaluation call.
|
||||
- Reuse `parseFederationScope` from M2-03.
|
||||
- Workers do not edit `docs/federation/TASKS.md` per repo AGENTS.md.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. Resource allowlist and `excluded_resources` enforced.
|
||||
2. Native RBAC evaluated as `subjectUserId` through an injected evaluator.
|
||||
3. Scope filter intersection supports `include_teams` and `include_personal` without widening native RBAC.
|
||||
4. `max_rows_per_query` caps requested limits.
|
||||
5. Service returns `{ allowed: true, filter }` or a structured deny reason usable by M4 audit.
|
||||
6. Unit tests cover every deny path.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Inspect existing federation scope/schema/auth guard contracts.
|
||||
2. Add pure `FederationScopeService` plus typed result/filter/deny interfaces.
|
||||
3. Add focused unit tests for happy paths, filter intersection, row cap, and deny paths.
|
||||
4. Export/register service for future verb controllers.
|
||||
5. Run situational tests, baseline gates, code review, then PR.
|
||||
|
||||
## Budget
|
||||
|
||||
- Provided model tier: sonnet.
|
||||
- Estimate from task row: 10K tokens.
|
||||
- Working cap assumption: keep implementation focused to FED-M3-04 surfaces only.
|
||||
|
||||
## Progress
|
||||
|
||||
- Intake complete; dirty base worktree avoided by creating isolated worktree at `/home/jarvis/src/mosaic-mono-v1-fed-m3-04`.
|
||||
- Project PRD and federation task spec reviewed.
|
||||
- Added `FederationScopeService` with structured allow/deny result types and injected native RBAC evaluator contract.
|
||||
- Added unit coverage for happy path, row cap, filter intersection, and every deny path.
|
||||
- Exported/registered the service for upcoming M3 verb controllers.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm --filter @mosaicstack/gateway test -- src/federation/server/__tests__/scope.service.spec.ts` — pass (10 tests before review update; 11 tests after adding include_personal no-leak coverage).
|
||||
- `pnpm build` — pass (23 successful tasks).
|
||||
- `pnpm typecheck` — pass (41 successful tasks; re-run after review update).
|
||||
- `pnpm lint` — pass (23 successful tasks; re-run after review update).
|
||||
- `pnpm format:check` — pass (re-run after review update).
|
||||
- `pnpm test` — pass after starting local `postgres`/`valkey` and running `pnpm --filter @mosaicstack/db db:push` for the DB-backed cross-user isolation suite (41 successful tasks; gateway 477 passed / 11 skipped).
|
||||
- Code review: `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings.
|
||||
- Security review: `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — risk none, 0 findings.
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- Issue #462 is already closed in provider output; likely milestone tracking mismatch. Will still reference #462 in PR body unless orchestrator redirects.
|
||||
- Local full-test setup required `docker compose up -d postgres valkey` + `db:push`; containers were stopped with `docker compose down` after verification.
|
||||
@@ -1,33 +0,0 @@
|
||||
# Issue #561 — Bare python on agent hosts
|
||||
|
||||
## Objective
|
||||
|
||||
Make the durable bootstrap/provisioning guidance ensure agent hosts provide a bare `python` command that resolves to Python 3.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add Debian/Ubuntu `python-is-python3` to agent-host prerequisites in bootstrap docs.
|
||||
- Check for actual OS package provisioning scripts and update only if an existing agent-host package install path exists.
|
||||
- Do not touch live host state.
|
||||
- Do not update `docs/TASKS.md`; repo guidance says workers read it but never modify it.
|
||||
|
||||
## Recon
|
||||
|
||||
- Issue #561 confirms repeated `python: command not found` failures from fleet agents that emit `python foo.py`.
|
||||
- `guides/BOOTSTRAP.md` and `packages/mosaic/framework/guides/BOOTSTRAP.md` are the source and packaged framework copies of the bootstrap guide.
|
||||
- Targeted repo sweep found no agent-host Debian package provisioning script. Existing `apt-get install` hits are CI/test helper paths or unrelated deployment docs.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add a host prerequisite section to both bootstrap guide copies.
|
||||
2. Include `python-is-python3` in the Debian/Ubuntu package list with an issue comment.
|
||||
3. Note the non-Debian equivalent as a `/usr/bin/python -> python3` symlink.
|
||||
4. Validate markdown/diff, run shell syntax checks where applicable, run required review, commit, queue guard, and push.
|
||||
|
||||
## Validation Log
|
||||
|
||||
- `rg` recon: no existing agent-host Debian package provisioning script; only CI/test helper `apt-get install` paths and unrelated deployment docs.
|
||||
- `git diff --check`: passed.
|
||||
- `bash -n packages/mosaic/framework/install.sh tools/install.sh packages/mosaic/framework/tools/bootstrap/init-project.sh packages/mosaic/framework/tools/_scripts/mosaic-bootstrap-repo`: passed. No touched shell scripts.
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`: approved, 0 findings.
|
||||
- `pnpm format:check`: initially blocked because `node_modules` was absent and `prettier` was unavailable; `pnpm install --frozen-lockfile` initially hit an invalid `/root` pnpm store path. Reran install with `--store-dir /home/hermes/agent-work/.pnpm-store`, then `pnpm format:check` passed.
|
||||
@@ -1,25 +0,0 @@
|
||||
# Scratchpad — fleet-personas spec timeout
|
||||
|
||||
## Objective
|
||||
|
||||
Raise the `@mosaicstack/mosaic` Vitest timeout to 30s at config level so filesystem-backed fleet drift-guard specs (`fleet-personas`, `fleet-profiles`, and siblings) stop false-reding under contended CI.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Move timeout policy into `packages/mosaic/vitest.config.ts` with `testTimeout: 30_000`.
|
||||
2. Remove the narrower `fleet-personas.spec.ts` local override so PR #677 fixes the suite class, not one file.
|
||||
3. Run targeted fleet specs plus typecheck/lint/format gates.
|
||||
4. Commit, queue guard, push, PR update.
|
||||
|
||||
## Evidence
|
||||
|
||||
- `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet-personas.spec.ts` — pass (8 tests; initial narrow fix).
|
||||
- `pnpm typecheck` — pass (41 tasks; initial narrow fix).
|
||||
- `pnpm lint` — pass (23 tasks; initial narrow fix).
|
||||
- `pnpm format:check` — pass after formatting this scratchpad (initial narrow fix).
|
||||
- Package-wide timeout follow-up:
|
||||
- `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet-personas.spec.ts src/commands/fleet-profiles.spec.ts` — pass (24 tests).
|
||||
- `pnpm --filter @mosaicstack/mosaic test` — pass (44 files / 618 tests).
|
||||
- `pnpm typecheck` — pass (41 tasks).
|
||||
- `pnpm lint` — pass (23 tasks).
|
||||
- `pnpm format:check` — pass.
|
||||
@@ -1,49 +0,0 @@
|
||||
# #703 Git Wrapper Interactive and Auth Resilience
|
||||
|
||||
## Objective
|
||||
|
||||
Restore the deployed Git wrapper contract: issue-create supports interactive invocation and Gitea mutation behavior tolerates a stale Tea authenticated user by validating current identity and using the existing host-scoped API fallback.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/mosaic/framework/tools/git/issue-create.sh`
|
||||
- `packages/mosaic/framework/tools/git/detect-platform.sh`
|
||||
- Git wrapper regression harnesses
|
||||
- This scratchpad
|
||||
|
||||
## Requirements / acceptance evidence
|
||||
|
||||
1. `issue-create -i` and `--interactive` prompt for missing issue fields without exposing credentials.
|
||||
2. Explicit command-line fields retain precedence and do not trigger prompt input.
|
||||
3. Gitea wrapper resolves the current user dynamically from the target host and does not rely on the saved Tea user identity.
|
||||
4. A Tea `GetUserByName` failure falls back to authenticated API creation.
|
||||
5. Existing body-safety, login-resolution, issue-create, and pr-create paths remain green.
|
||||
6. Source framework is re-seeded to deployed `~/.config/mosaic`, then deployed wrappers are verified end to end.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add failing shell regression harness for interactive input and stale Tea user fallback.
|
||||
2. Implement minimal helper and parser changes.
|
||||
3. Run wrapper harnesses, syntax checks, and repository baseline checks.
|
||||
4. Re-seed deployed framework and run live wrapper verification.
|
||||
5. Commit, queue guard, push, open PR, and stop for independent review.
|
||||
|
||||
## Progress
|
||||
|
||||
- Issue #703 filed before code; issue comment records #536 root cause and stale-login trigger.
|
||||
- Deployed wrapper `issue-create.sh -i` reproduced: `Unknown option: -i` (exit 1).
|
||||
- Live Tea mutation did not reproduce `GetUserByName` on this host because the current mosaicstack Tea login is valid. The test harness models the reported stale authenticated-user condition.
|
||||
- Implemented `-i` / `--interactive` prompt collection and a dynamic Tea `/user` validation. A stale Tea identity now selects the existing host-scoped Gitea API fallback before mutation for both issue and PR creation.
|
||||
- Re-seeded the framework with `MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 bash packages/mosaic/framework/install.sh`. Installed and source wrapper SHA-256 values matched.
|
||||
- Live deployed verification: interactive issue-create opened then closed #704; installed dynamic identity resolved `jason.woltje`.
|
||||
|
||||
## Verification
|
||||
|
||||
- PASS: `packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh`
|
||||
- PASS: `packages/mosaic/framework/tools/git/test-issue-create-body-safety.sh`
|
||||
- PASS: `packages/mosaic/framework/tools/git/test-gitea-login-resolution.sh`
|
||||
- PASS: `packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh`
|
||||
- PASS: `packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh`
|
||||
- PASS: `bash packages/mosaic/framework/tools/git/test-lane-brief-pr-linkage.sh`
|
||||
- PASS: `bash -n packages/mosaic/framework/tools/git/*.sh`
|
||||
- PASS: Prettier check for this scratchpad
|
||||
@@ -1,52 +0,0 @@
|
||||
# FED-M3-05 — Federation List Verb Scratchpad
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `POST /api/federation/v1/list/:resource`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Wire `FederationAuthGuard` → `FederationScopeService` → read-only list query layer.
|
||||
- Apply `max_rows_per_query` row cap and return pagination metadata when truncated.
|
||||
- Tag returned rows with `_source: "local"`.
|
||||
- Keep audit writes deferred to M4.
|
||||
- No request/response body persistence.
|
||||
|
||||
## Base / branch
|
||||
|
||||
- Branch: `feat/federation-m3-verb-list`
|
||||
- Base: `main` after M3-04 scope service merged via PR #672 (`c739256a`).
|
||||
|
||||
## Implementation notes
|
||||
|
||||
- Added `ListController` under `apps/gateway/src/federation/server/verbs/`.
|
||||
- Added `FederationListQueryService` as the read-only query layer and native RBAC evaluator.
|
||||
- Query resources supported in M3 list path:
|
||||
- `tasks`: project/mission scoped tasks visible through personal/team project access.
|
||||
- `notes`: non-empty `mission_tasks.notes` rows visible through personal/team mission access.
|
||||
- `memory`: user-owned `insights` and `preferences` rows.
|
||||
- `credentials` / `api_keys`: denied by native RBAC in M3 even if present in scope; sensitive-resource implementation is not part of FED-M3-05.
|
||||
- Cursor pagination uses an opaque base64url keyset cursor over `(createdAt, id)`; DB reads fetch at most `limit + 1` rows per resource query.
|
||||
- Reviewer isolation fix: `mission_tasks.notes` rows are always constrained by `missionTasks.userId = subjectUserId` and accessible mission IDs; team scope narrows missions but never widens to other users' mission task notes.
|
||||
- Follow-up review fix: memory listing now uses deterministic table-block pagination (`insights` first, then `preferences`) with cursor source metadata, so one table's cursor is never applied to the other.
|
||||
- Follow-up hardening: missing auth-guard context returns a structured federation `unauthorized` envelope; unsupported resources and non-encodable truncated cursors throw instead of silently crashing/truncating.
|
||||
|
||||
## Tests
|
||||
|
||||
- `pnpm --filter @mosaicstack/gateway test -- list.controller.spec.ts list-query.service.spec.ts` — PASS (16 tests, including PGlite regression coverage for team-scoped notes isolation, unauthorized mission notes exclusion, `includePersonal: false`, deterministic memory pagination, missing context envelope, unsupported resource, and cursor encode failure).
|
||||
- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
|
||||
- `pnpm --filter @mosaicstack/gateway lint` — PASS.
|
||||
- `pnpm format:check` — PASS.
|
||||
- `pnpm typecheck` — PASS (41/41 turbo tasks).
|
||||
- `pnpm lint` — PASS (23/23 turbo tasks).
|
||||
- `pnpm --filter @mosaicstack/gateway test` — FAIL in pre-existing/live-DB integration suite: `apps/gateway/src/__tests__/cross-user-isolation.test.ts` cleanup cannot connect to local PostgreSQL on `localhost:5433`. New list tests pass; failure is outside FED-M3-05.
|
||||
|
||||
## Review evidence
|
||||
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS after follow-up remediation; approve, no findings.
|
||||
- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS after follow-up remediation; risk level none, no findings.
|
||||
- Security-review note: read-path audit logging remains intentionally deferred to M4 per orchestrator clarification and FED-M3-05 scope.
|
||||
|
||||
## Risks / follow-up
|
||||
|
||||
- Read-path audit logging remains intentionally deferred to M4.
|
||||
@@ -1,65 +0,0 @@
|
||||
# FED-M3-07 — Capabilities Verb Scratchpad
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `GET /api/federation/v1/capabilities` in `apps/gateway/src/federation/server/verbs/capabilities.controller.ts`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add read-only capabilities controller under federation server verbs.
|
||||
- Use `FederationAuthGuard` only; active grant is sufficient and no native RBAC/scope-service eval runs.
|
||||
- Response shape: `{ resources, excluded_resources, max_rows_per_query, supported_verbs }` derived from grant scope.
|
||||
- Register controller in `FederationModule`.
|
||||
- Unit-test happy path, defaults, no-context guard seam, and invalid scope handling.
|
||||
|
||||
## Constraints / assumptions
|
||||
|
||||
- Issue: #462.
|
||||
- Branch: `feat/federation-m3-verb-capabilities` from `origin/main` (`3eeed04e`).
|
||||
- Depends on M3-03 auth guard; guard attaches `request.federationContext.scope` after active-grant validation.
|
||||
- ASSUMPTION: `supported_verbs` is the M3 verb set from `@mosaicstack/types` (`list`, `get`, `capabilities`).
|
||||
- ASSUMPTION: `filters`/`rate_limit` are intentionally omitted for FED-M3-07 because the card’s response shape lists only the four required fields.
|
||||
- Budget: no explicit hard cap from orchestrator; working cap ~4K-8K tokens for card implementation + tests + PR cycle.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Write controller unit tests first.
|
||||
2. Implement controller and module registration.
|
||||
3. Run scoped tests + typecheck/lint/format.
|
||||
4. Run Codex code/security review and remediate.
|
||||
5. Commit, queue guard, push, PR via wrapper.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-06-24: Intake complete; fresh worktree created from origin/main.
|
||||
- 2026-06-24: Added `CapabilitiesController`, registered it in `FederationModule`, and added 5 unit tests.
|
||||
- 2026-06-24: Code/security reviews passed with no findings.
|
||||
|
||||
## Tests run
|
||||
|
||||
- `pnpm --filter @mosaicstack/gateway test -- capabilities.controller.spec.ts` — PASS (5 tests).
|
||||
- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
|
||||
- `pnpm --filter @mosaicstack/gateway lint` — PASS.
|
||||
- `pnpm format:check` — PASS.
|
||||
- `pnpm typecheck` — PASS (41/41 turbo tasks).
|
||||
- `pnpm lint` — PASS (23/23 turbo tasks).
|
||||
- `pnpm test` — FAIL in pre-existing/live-DB integration suite: `apps/gateway/src/__tests__/cross-user-isolation.test.ts` cleanup hit PostgreSQL connection/schema state for the `messages` table. Changed capabilities tests passed; failure is outside FED-M3-07 surface. No `fleet-personas.spec` flake encountered.
|
||||
|
||||
## Review evidence
|
||||
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS/approve, no findings.
|
||||
- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS, risk level none, no findings.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- Full repo `pnpm test` may hit known `fleet-personas.spec` flake per orchestrator; ignore that specific flake if encountered.
|
||||
- Previous card saw local DB schema issue in `cross-user-isolation.test.ts`; scoped capabilities tests should be authoritative for this surface.
|
||||
|
||||
## Acceptance evidence mapping
|
||||
|
||||
| Acceptance criterion | Evidence |
|
||||
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
||||
| GET `/api/federation/v1/capabilities` exists | Route metadata test in `capabilities.controller.spec.ts`; scoped test PASS |
|
||||
| Uses active-grant auth guard and no RBAC eval | Guard metadata test confirms only `FederationAuthGuard`; controller has no service injections/RBAC calls; scoped test PASS |
|
||||
| Response enumerates resources/excluded/max rows/supported verbs from scope | Happy-path/default scope tests + response schema parse; scoped test PASS |
|
||||
| Read-only/no persistence side effects | Controller only parses request `federationContext.scope` and returns a DTO; no DB/service dependency; code review PASS |
|
||||
@@ -1,67 +0,0 @@
|
||||
# FED-M3-09 — Query Source Service Scratchpad
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `apps/gateway/src/federation/client/query-source.service.ts` for `source: "local" | "federated:<host>" | "all"` routing.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add QuerySourceService in gateway federation client layer.
|
||||
- Unit-test local-only, single federated peer, all-source fan-out/merge, and per-peer partial failures.
|
||||
- Keep `docs/federation/TASKS.md` read-only per project agent guidance.
|
||||
|
||||
## Constraints / assumptions
|
||||
|
||||
- Issue: #462.
|
||||
- Branch: `feat/federation-m3-query-source` from `origin/main` (`e0e7be70`).
|
||||
- ASSUMPTION: `federated:<host>` should match active outbound peers by `commonName` first and by `endpointUrl` host/hostname as compatibility fallback; source tags use `peer.commonName` per `@mosaicstack/types` source-tag docs.
|
||||
- ASSUMPTION: QuerySourceService provides list/fan-out behavior; get/source routing can be layered later because card acceptance says merge rows.
|
||||
- ASSUMPTION: `source: "all"` cannot safely return a single continuation cursor for multiple sub-sources; any subquery cursor marks the merged response `_partial: true` + `_truncated: true` while omitting `nextCursor`.
|
||||
- Budget: no explicit hard cap from orchestrator; working cap ~8K-12K tokens for card 1 implementation + tests + PR cycle.
|
||||
- OpenBrain unavailable: credential loader failed with missing `/home/jarvis/.config/mosaic/credentials.json`; not blocking code delivery.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Review federation client/types/db patterns.
|
||||
2. Write unit tests for source behavior.
|
||||
3. Implement QuerySourceService and export/register it in FederationModule.
|
||||
4. Run scoped tests, typecheck, lint, format.
|
||||
5. Run codex uncommitted review and remediate.
|
||||
6. Commit, queue guard, push, PR via wrapper.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-06-24: Intake complete; using isolated worktree to avoid dirty orchestrator files in original checkout.
|
||||
- 2026-06-24: Added QuerySourceService, module export, barrel export, and 7 unit tests.
|
||||
- 2026-06-24: First Codex review found pagination and port-host matching issues; both remediated with tests.
|
||||
|
||||
## Tests run
|
||||
|
||||
- `pnpm --filter @mosaicstack/gateway test -- query-source.service.spec.ts` — PASS (7 tests).
|
||||
- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
|
||||
- `pnpm --filter @mosaicstack/gateway lint` — PASS.
|
||||
- `pnpm format:check` — PASS.
|
||||
- `pnpm typecheck` — PASS (41/41 turbo tasks).
|
||||
- `pnpm lint` — PASS (23/23 turbo tasks).
|
||||
- `pnpm test` — FAIL in pre-existing/live-DB integration suite: `apps/gateway/src/__tests__/cross-user-isolation.test.ts` cleanup hit `relation "messages" does not exist` against local PostgreSQL. Changed QuerySource unit tests passed; failure is outside FED-M3-09 surface and appears tied to local DB schema state.
|
||||
|
||||
## Review evidence
|
||||
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — first pass request-changes, 2 should-fix findings (all-source cursor handling; endpoint port host matching).
|
||||
- Remediation: `_partial` + `_truncated` when any all-source subquery has `nextCursor`; endpoint match accepts URL `host` and `hostname`; added tests for both.
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS/approve, no findings.
|
||||
- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS, risk level none, no findings.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- Federation query layer is not yet wired; service API needs to be stable and easy to compose.
|
||||
- Must avoid hard-failing `source: all` on remote peer failures.
|
||||
|
||||
## Acceptance evidence mapping
|
||||
|
||||
| Acceptance criterion | Evidence |
|
||||
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| local source returns local rows tagged `_source: local` | `query-source.service.spec.ts` local test; scoped test PASS |
|
||||
| `federated:<host>` queries selected peer and tags rows with peer source | `query-source.service.spec.ts` commonName/endpoint-host tests; scoped test PASS |
|
||||
| `all` fans out local + active outbound peers in parallel and merges tagged rows | `query-source.service.spec.ts` all-source call-order/merge test; scoped test PASS |
|
||||
| per-peer failure on `all` returns `_partial: true`, not throw | `query-source.service.spec.ts` peer failure test; scoped test PASS |
|
||||
@@ -1,66 +0,0 @@
|
||||
# H1 — heartbeat readiness detection
|
||||
|
||||
## Objective
|
||||
|
||||
Add runtime-agnostic readiness classification to `mosaic fleet ps` so an agent can be reported as working/idle/stuck/stale/dead/unknown instead of treating pane liveness as progress.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/mosaic/src/commands/fleet.ts`
|
||||
- exported readiness state/types/default thresholds/helpers/classifier
|
||||
- `AgentPsRow.readiness` additive JSON field
|
||||
- table HB column and IDLE/STUCK flags
|
||||
- `packages/mosaic/src/commands/fleet.spec.ts`
|
||||
- pure classifier branch/boundary coverage
|
||||
- threshold helper coverage
|
||||
- legitimate render/JSON assertion updates for new HB text
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Branches covered: dead, unknown, stale, busy working, null-idle working, stuck boundary, idle boundary, working below idle.
|
||||
- Threshold env helpers default to 300s/900s and honor positive integer env values.
|
||||
- `fleet ps` rows populate `readiness` for roster and unmanaged socket sessions.
|
||||
- Table HB text becomes `<age>s/<readiness>` when heartbeat age exists; remains `unknown` when absent.
|
||||
- Flags include `IDLE`/`STUCK` for matching readiness.
|
||||
- Local gates green: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, fleet vitest.
|
||||
- Pre-push queue guard passes; PR opened off `origin/main`; no merge by worker.
|
||||
|
||||
## Constraints / Assumptions
|
||||
|
||||
- Source branch: `origin/main` @ `e3adc6a`.
|
||||
- No scope creep beyond readiness detection.
|
||||
- `docs/TASKS.md` and `docs/fleet/TASKS.md` are orchestrator-owned; worker will not modify them.
|
||||
- PRD alignment source: `docs/fleet/PRD.md` Phase 2 observability; this is a refinement of heartbeat observability, preserving existing unknown/stale behavior.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Install dependencies with requested PNPM environment.
|
||||
2. Add readiness types/helpers/classifier near heartbeat constants.
|
||||
3. Add `readiness` to `AgentPsRow` and populate both row paths.
|
||||
4. Update table render and flags.
|
||||
5. Add unit tests and update affected ps render/JSON assertions.
|
||||
6. Run build precheck + required gates.
|
||||
7. Run automated independent review, remediate findings.
|
||||
8. Queue guard, push, open PR.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-06-24: Branch created from `origin/main` @ `e3adc6a`.
|
||||
- 2026-06-24: Implemented readiness thresholds/classifier, JSON row field, HB column label, and IDLE/STUCK flags.
|
||||
- 2026-06-24: Added classifier branch/boundary tests, threshold helper tests, JSON shape assertions, and readiness table rendering assertions.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm install --store-dir "$HOME/.pnpm-store"` — pass.
|
||||
- `npx turbo build --filter=@mosaicstack/mosaic^...` — pass, 12/12 tasks successful.
|
||||
- `pnpm typecheck` — pass, 41/41 tasks successful.
|
||||
- `pnpm lint` — pass, 23/23 tasks successful.
|
||||
- `pnpm format:check` — pass, all matched files use Prettier style.
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — pass, 171 tests.
|
||||
- `pnpm --filter @mosaicstack/mosaic test` — pass, 39 files / 547 tests; `fleet.spec.ts` 171 tests.
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings (reviewed supplied diff; sandbox file-inspection limitation noted by tool).
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- No current blocker.
|
||||
- Review tool could not inspect repo files directly due sandbox wrapper limitation, but it reviewed the supplied diff and approved with no findings.
|
||||
@@ -1,53 +0,0 @@
|
||||
# H1b — tmux pane idle signal wiring
|
||||
|
||||
## Objective
|
||||
|
||||
Feed `classifyReadiness()` a real idle signal on tmux 3.4 by deriving `idleSeconds` from the first available tmux timestamp source: pane activity, then window activity, then session activity.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/mosaic/src/commands/fleet.ts`
|
||||
- Extend `buildTmuxListPanesCommand()` format to include `#{window_activity}` and `#{session_activity}` after the existing fields.
|
||||
- Update `parseTmuxListPanes()` to choose the first non-empty finite positive timestamp and clamp future idle values to 0.
|
||||
- `packages/mosaic/src/commands/fleet.spec.ts`
|
||||
- Cover pane/window/session activity parsing behavior, empty-field index alignment, null idle, future clamping, math correctness, and exact tmux format.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No changes to `classifyReadiness()`, thresholds, `AgentPsRow`, or `fleet ps` rendering.
|
||||
- No merge by worker; orchestrator routes review/merge.
|
||||
- Workers do not modify `docs/TASKS.md`.
|
||||
|
||||
## PRD Alignment
|
||||
|
||||
Aligned with `docs/fleet/PRD.md` FR-1 and acceptance criteria for truthful `mosaic fleet ps` pane/pid/idle observability.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Sync branch from latest `origin/main` and install dependencies with required pnpm env.
|
||||
2. Add/confirm reproducer tests for tmux 3.4 empty `pane_activity` and new fallback behavior.
|
||||
3. Implement the focused parser/format change only.
|
||||
4. Run required build, baseline gates, fleet vitest, and independent review.
|
||||
5. Run pre-push queue guard, push branch, and open PR to `main` with Mosaic wrapper.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-06-24: Branch `fix/fleet-pane-idle-activity` created from `origin/main` @ `ec8dd7c` after fetching.
|
||||
- 2026-06-24: Session-start generated local `.mosaic/orchestrator/*` changes on the previous release branch; stashed as `coder1 session-start state before H1b` to keep this branch clean.
|
||||
- 2026-06-24: Added TDD coverage for the tmux 3.4 production case (`pane_activity` empty, `window_activity` populated), exact new list-panes format, null/future/multiple-source behavior.
|
||||
- 2026-06-24: Implemented parser fallback without changing readiness classifier thresholds or render shape.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm install --store-dir "$HOME/.pnpm-store"` — pass.
|
||||
- Reproducer before implementation: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — failed as expected (old format, no fallback, negative future idle).
|
||||
- `npx turbo build --filter=@mosaicstack/mosaic^...` — pass, 12/12 tasks successful.
|
||||
- `pnpm typecheck` — pass, 41/41 tasks successful.
|
||||
- `pnpm lint` — pass, 23/23 tasks successful.
|
||||
- `pnpm format:check` — pass, all matched files use Prettier style.
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — pass, 176 tests.
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings (reviewed supplied diff; sandbox file-inspection limitation noted by tool).
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- No current blocker.
|
||||
@@ -1,70 +0,0 @@
|
||||
# H2 — readiness semantics: available, not stuck
|
||||
|
||||
## Objective
|
||||
|
||||
Correct fleet readiness semantics so a healthy long-idle agent is reported as `available` (good/assignable) instead of `stuck` (fault). Reserve `stuck` in the type/JSON value space for future positive block evidence.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/mosaic/src/commands/fleet.ts`
|
||||
- replace `idle` readiness state with `available`
|
||||
- keep `stuck` in the union but stop emitting it from idle-only heuristics
|
||||
- remove stuck threshold helper/env handling
|
||||
- remove IDLE/STUCK alarm flags from table rendering
|
||||
- `packages/mosaic/src/commands/fleet.spec.ts`
|
||||
- update classifier branch/boundary tests
|
||||
- assert very long idle maps to `available`, not `stuck`
|
||||
- update table/JSON assertions for available with no alarm flags
|
||||
- remove stuck threshold helper tests
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `classifyReadiness()` remains pure/total/never-throw and maps:
|
||||
- dead/stale/unknown unchanged
|
||||
- busy/null/undefined/non-finite idle to `working`
|
||||
- idle >= activity threshold to `available`
|
||||
- idle < activity threshold to `working`
|
||||
- No idle-derived path emits `stuck`.
|
||||
- `MOSAIC_HEARTBEAT_IDLE_THRESHOLD` remains backward compatible as the working→available activity threshold.
|
||||
- `MOSAIC_HEARTBEAT_STUCK_THRESHOLD` and helper/default are removed.
|
||||
- `fleet ps` keeps the idle-seconds column header `IDLE`, renders `available` in HB label, and does not add IDLE/STUCK warning flags.
|
||||
- Local gates green: build precheck, typecheck, lint, format:check, fleet vitest.
|
||||
- PR opened against `main`; no merge by worker.
|
||||
|
||||
## Constraints / Assumptions
|
||||
|
||||
- Source branch: `origin/main` @ `1020cfa`.
|
||||
- `docs/TASKS.md` is orchestrator-owned; worker will not modify it.
|
||||
- Documentation impact is captured in this scratchpad and PR description; no user/admin guide behavior beyond CLI readiness label semantics.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Install dependencies with requested PNPM environment.
|
||||
2. Inspect current H1/H1b readiness implementation and tests.
|
||||
3. Update classifier types/helpers/rendering.
|
||||
4. Update focused tests.
|
||||
5. Run build precheck + required gates.
|
||||
6. Run automated code review, remediate any findings.
|
||||
7. Queue guard, push, open PR.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-06-24: Branch created from `origin/main` @ `1020cfa`.
|
||||
- 2026-06-24: Replaced idle-derived `idle`/`stuck` outputs with `available`; retained `stuck` in type union for future positive block evidence.
|
||||
- 2026-06-24: Removed stuck threshold env/helper plumbing and IDLE/STUCK alarm flags.
|
||||
- 2026-06-24: Updated classifier and table-render tests for available semantics.
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm install --store-dir "$HOME/.pnpm-store"` — pass.
|
||||
- `npx turbo build --filter=@mosaicstack/mosaic^...` — pass, 12/12 tasks successful.
|
||||
- `pnpm typecheck` — pass, 41/41 tasks successful.
|
||||
- `pnpm lint` — pass, 23/23 tasks successful.
|
||||
- `pnpm format:check` — pass, all matched files use Prettier style.
|
||||
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — pass, 177 tests.
|
||||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings (reviewed supplied diff; sandbox file-inspection limitation noted by tool).
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- No current blocker.
|
||||
- Review tool could not inspect repo files directly due sandbox wrapper limitation, but it reviewed the supplied diff and approved with no findings.
|
||||
@@ -1,58 +0,0 @@
|
||||
# Scratchpad — Tess Interaction Agent
|
||||
|
||||
## 2026-07-12 — Mission intake
|
||||
|
||||
**Objective:** Build a Pi-native GPT-5.6 Sol high-reasoning Mosaic interaction agent, named Tess, as Jason's primary Discord/CLI access point for Mosaic fleet and transitional Hermes capabilities. Tess complements Mos and must not become a competing orchestrator.
|
||||
|
||||
**Issue:** #706
|
||||
|
||||
**Budget:** No explicit cap provided. Original working estimate was 290K implementation/review tokens. That estimate is superseded after six security prerequisite tasks were added; revised arithmetic total is pending because the calculation tool was blocked by runtime consent. Run at most two workers; prefer one implementation lane plus one independent review/discovery lane. Re-estimate after planning approval and each milestone.
|
||||
|
||||
**Evidence gathered:**
|
||||
- Mosaic already provides Pi lifecycle hooks, fleet/tmux sessions, Matrix connector/controller pieces, typed chat events, Discord/Telegram channel plugins, and command/plugin registries.
|
||||
- Current `IProviderAdapter` is an LLM model/completion abstraction, not an external agent/session provider.
|
||||
- Required new seam is `AgentRuntimeProvider`: sessions, stream, message, terminate, hierarchy, attach, health, capabilities.
|
||||
- Recurring cross-runtime needs: unified memory/retrieval, Discord routing/approvals, agent state/inbox/compaction recovery, runtime bootstrap, fleet/incident controls, and GitOps workflow.
|
||||
- Project truth must remain in canonical project/Mosaic stores; semantic memory is retrieval/mirror.
|
||||
|
||||
**Decisions:**
|
||||
1. Name: Tess (tessera). Stable machine key `tess`; display name configurable.
|
||||
2. Mos owns orchestration; Tess delegates Mos-owned work through an explicit coordination contract.
|
||||
3. Gateway owns ingress/auth/routing; Discord and CLI remain thin clients.
|
||||
4. tmux/fleet ships first behind an adapter; Matrix/native Mosaic is the forward transport.
|
||||
5. Hermes integration is transitional and capability-negotiated; unsupported operations fail closed.
|
||||
6. No unrestricted Discord shell. Privileged/destructive/customer-visible actions require authorization and approval.
|
||||
|
||||
**Plan:**
|
||||
1. Land requirements/architecture/task graph.
|
||||
2. Deliver runtime contracts and security model.
|
||||
3. Deliver durable Pi service/state.
|
||||
4. Deliver Discord and CLI.
|
||||
5. Deliver fleet/Mos/Hermes/memory/tool plugins.
|
||||
6. Deliver Matrix/native transport, migration matrix, recovery, docs, and qualification.
|
||||
|
||||
**Progress:** Issue #706 created. PRD/manifest/tasks initialized on clean branch `feat/tess-interaction-agent` from `origin/main`.
|
||||
|
||||
**Risks:** 14 GB root filesystem headroom; active fleet lanes; broad migration scope; Discord privilege boundary; possible duplicate orchestration authority.
|
||||
|
||||
## 2026-07-12 — Independent planning and threat review
|
||||
|
||||
**Verdict received:** BLOCK TESS-PLAN-001. Coding remains stopped.
|
||||
|
||||
**Blocking findings:** formal threat model absent; verification matrix absent; migration inventory implied but absent; non-existent task paths; AC-TESS-03 lacked a crisp test. Security review also identified command scope bypass, cross-tenant session attachment, MCP actor impersonation, unsafe Discord service ingress, pre-persistence/egress secret leakage, non-durable replay, and globally scoped GC.
|
||||
|
||||
**Remediation applied:**
|
||||
- Added `docs/tess/ARCHITECTURE.md`.
|
||||
- Added `docs/tess/THREAT-MODEL.md` with TM-01..12.
|
||||
- Added `docs/tess/VERIFICATION-MATRIX.md` mapping AC-TESS-01..11.
|
||||
- Added `docs/tess/MIGRATION-INVENTORY.md`.
|
||||
- Added hard requirements TESS-SEC-002..009.
|
||||
- Added six prerequisite security tasks before provider/ingress implementation.
|
||||
- Corrected task paths to existing package surfaces.
|
||||
- Added explicit GPT-5.6 Sol/high/tool-policy status verification for AC-TESS-03.
|
||||
|
||||
**Re-review 1:** BLOCK only on composite `repo` values that looked like nonexistent paths. Remediated by declaring comma-separated roots and validating every root.
|
||||
|
||||
**Final focused review:** PASS. Deterministic audit validated all task repository roots with zero missing paths; no planning placeholders remained; security prerequisites still gate Tess exposure; observability traceability is explicit.
|
||||
|
||||
**Current gate:** planning PR must merge to `main` with terminal-green CI before any source-code worker starts.
|
||||
@@ -1,38 +0,0 @@
|
||||
# TESS-M1-002 — Provider Registry
|
||||
|
||||
- **Issue:** #707
|
||||
- **Branch:** `feat/tess-provider-registry`
|
||||
- **Objective:** Build the runtime provider registry/service boundary that derives immutable actor/tenant/channel/correlation scope server-side, fail-closes unsupported and destructive runtime operations, binds termination approval to the exact structured action, and emits correlation-safe audit events.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add a provider-agnostic registry in `@mosaicstack/agent` over the merged `AgentRuntimeProvider` contract.
|
||||
2. Write abuse-case tests before implementation for duplicate/unknown providers, immutable server-derived scope, capability denial, approval mismatch/absence, and audit failure.
|
||||
3. Implement the Gateway service that converts only authenticated `ActorTenantScope` plus trusted ingress metadata into a frozen `RuntimeScope`, gates capabilities and terminate approval, and records metadata-only audits.
|
||||
4. Register the service in `AgentModule`, then run focused, baseline, cold-cache, and independent-review gates.
|
||||
|
||||
## Security Invariants
|
||||
|
||||
- Caller-supplied actor/tenant identity never reaches runtime providers.
|
||||
- Provider capability absence and approval/audit failure deny before side effects.
|
||||
- Termination approval is verified against provider, session, actor, tenant, channel, and correlation context.
|
||||
- Audit events retain correlation and authority metadata but never message content or approval material.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-07-12: Created fresh worktree from `origin/main` at `119f64e6`; source and Tess planning/security documentation reviewed.
|
||||
- 2026-07-12: Security TDD added registry and gateway abuse tests before implementation.
|
||||
- 2026-07-12: Implemented `AgentRuntimeProviderRegistry` and gateway `RuntimeProviderService`; registered both in `AgentModule` and documented the internal boundary.
|
||||
- 2026-07-12: Independent review found two audit correctness issues. Remediated completion-audit failure handling and provider execution failures: pre-invocation denials are audited as `denied`; post-invocation errors as `failed`; completion audit failure does not misreport a completed effect as retryable.
|
||||
- 2026-07-12: Final independent security review: no findings. Final code review had one false positive: `@mosaicstack/types` is already declared in `packages/agent/package.json`.
|
||||
|
||||
## Tests
|
||||
|
||||
- TDD red: `pnpm --filter @mosaicstack/gateway test -- runtime-provider-registry.service.test.ts` failed before both audit remediations, as expected.
|
||||
- Focused: package registry 2 tests and gateway security boundary 7 tests pass.
|
||||
- Cold-cache: removed this worktree's `node_modules`, then `pnpm install --offline --frozen-lockfile --store-dir /home/jarvis/.local/share/pnpm/store` passed.
|
||||
- Cold-cache baseline: `TURBO_FORCE=true pnpm typecheck` — 42/42 tasks passed; `TURBO_FORCE=true pnpm lint` — 23/23 tasks passed; `TURBO_FORCE=true pnpm format:check` passed; `TURBO_FORCE=true pnpm test` — 42/42 tasks passed (gateway 548 tests passed, 11 intentionally skipped).
|
||||
|
||||
## Risks / Blockers
|
||||
|
||||
- The canonical durable approval implementation is currently command-specific. This card introduces a fail-closed runtime approval verifier boundary so a runtime provider cannot terminate until its exact-action verifier is wired; later provider implementations cannot bypass it.
|
||||
@@ -1,27 +0,0 @@
|
||||
# TESS-M1-SEC-001 — Command authorization and exact-action approval
|
||||
|
||||
- Issue/milestone: #707 / M1
|
||||
- Branch: `fix/tess-command-authz`
|
||||
- Requirement: `TESS-SEC-002`, with approval binding controls from `TESS-SEC-007`
|
||||
- Scope: `apps/gateway` only, plus required in-repo security/developer documentation.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Locate the gateway command executor, command metadata, authorization context, and existing test conventions.
|
||||
2. Write abuse/authz tests before production changes. Expected red cases: non-admin blocked from admin/system command; forged caller scope cannot authorize; privileged/destructive action requires durable exact-action approval; expired/replayed/mutated approvals deny.
|
||||
3. Implement server-derived role/scope enforcement and durable approval validation/consumption with audit results.
|
||||
4. Run focused security tests, then repository baseline gates: typecheck, lint, format-check, test.
|
||||
5. Run independent security/code review, commit, queue-guard, push, and open the PR to `main` through the stated Gitea API fallback. Stop after PR creation.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- The existing gateway persistence interface is the available durable approval boundary. If no persistence abstraction exists, a minimal injectable repository interface will be introduced rather than an in-memory approval implementation, because TESS-SEC-002/007 require durable enforcement.
|
||||
- “Exact action” is a canonical digest over structured command identity and normalized arguments; role/scope checks always use authenticated server context, not client-declared claims.
|
||||
|
||||
## TDD evidence
|
||||
|
||||
- Pending: abuse/authz test written and observed red before implementation.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
- Pending.
|
||||
@@ -1,35 +0,0 @@
|
||||
# Scratchpad — TESS-M1-SEC-004 Discord ingress
|
||||
|
||||
- **Task / issue:** TESS-M1-SEC-004 / #707
|
||||
- **Branch:** `fix/tess-discord-ingress` from `origin/main` at `59e49cfd`
|
||||
- **Objective:** Authenticate the Discord plugin service at gateway ingress; enforce explicit guild/channel/user allowlists; attach Discord message and generated correlation IDs; reject replayed native message IDs.
|
||||
- **Scope:** `plugins/discord`, `apps/gateway`, and existing Discord admin/developer protocol docs.
|
||||
- **Budget:** Task estimate 28K; no explicit hard cap supplied.
|
||||
- **Assumptions:** The Discord plugin and gateway share an injected high-entropy `DISCORD_SERVICE_TOKEN`; a configured Discord plugin fails closed without it. Allowlist configuration is comma-separated Discord snowflakes. Discord native message ID is the replay key, with bounded in-memory retention pending the M2 durable inbox/idempotency work.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Add failing tests covering ingress service authentication/signing, unlisted guild/channel/user rejection, correlation propagation, and replay rejection.
|
||||
2. Implement the signed Discord ingress envelope and allowlist validation in the plugin.
|
||||
3. Authenticate and validate the envelope at the gateway boundary, then enforce bounded replay protection before agent dispatch.
|
||||
4. Document the service-token and allowlist operations; run focused and baseline gates; obtain independent review.
|
||||
|
||||
## Progress
|
||||
|
||||
- 2026-07-12: Intake complete; PRD TESS-SEC-005, architecture, and threat model reviewed.
|
||||
- Added service-token Socket.IO authentication, HMAC-signed Discord envelopes, default-deny guild/channel/user allowlists, correlated message metadata, bounded replay rejection, and fail-fast configuration checks.
|
||||
- Code and security reviews completed. Code review findings on service persistence ownership, package-boundary tests, disconnected ingress observability, and chat payload validation were remediated; final independent code review approved.
|
||||
|
||||
## Risks / blockers
|
||||
|
||||
- Existing `main` has known unrelated Prettier debt; only changed files will be held format-clean. Durable replay persistence is intentionally out of scope for this M1 prerequisite and belongs to TESS-M2 durable inbox/idempotency work.
|
||||
|
||||
## Verification evidence
|
||||
|
||||
- Focused ingress suite: `pnpm --filter @mosaicstack/gateway test -- discord-ingress.security.spec.ts` — 7 passed.
|
||||
- Gateway suite: `pnpm --filter @mosaicstack/gateway test` — 513 passed, 11 skipped.
|
||||
- Plugin suite: `pnpm --filter @mosaicstack/discord-plugin test` — no tests, passed by configured `--passWithNoTests`.
|
||||
- `pnpm typecheck` — passed.
|
||||
- `pnpm lint` — passed.
|
||||
- `pnpm format:check` — fails only on the known pre-existing Tess documentation debt listed in the task dispatch; changed files pass targeted Prettier verification.
|
||||
- Codex security review — no findings; final Codex code review — approved.
|
||||
@@ -1,77 +0,0 @@
|
||||
# Tess Architecture
|
||||
|
||||
## Purpose
|
||||
|
||||
Tess is the Mosaic operator interaction plane. Mos remains the coding/general fleet orchestration authority. Tess receives authorized operator intent, presents fleet/session state, delegates Mos-owned work to Mos, and exposes native Mosaic plus transitional external-agent capabilities through normalized providers.
|
||||
|
||||
## Component Boundaries
|
||||
|
||||
```text
|
||||
Discord plugin ─┐
|
||||
├─ authenticated ingress envelope ─> Mosaic Gateway
|
||||
mosaic tess CLI ┘ │
|
||||
├─ policy/approval/audit
|
||||
├─ Tess durable session service (Pi GPT-5.6 Sol high)
|
||||
├─ AgentRuntimeProvider registry
|
||||
│ ├─ native Pi provider
|
||||
│ ├─ fleet/tmux provider
|
||||
│ ├─ Hermes adapter
|
||||
│ └─ Matrix/native transport provider
|
||||
├─ memory/state/inbox plugins
|
||||
└─ Mos coordination adapter ─> Mos / fleet queue
|
||||
```
|
||||
|
||||
## Core Contract
|
||||
|
||||
`AgentRuntimeProvider` is separate from the existing model-completion `IProviderAdapter`. It normalizes external and native agent runtimes without leaking provider-specific schemas.
|
||||
|
||||
Required operations:
|
||||
|
||||
- `capabilities()` and `health()`
|
||||
- `listSessions(scope)`
|
||||
- `getSessionTree(scope)`
|
||||
- `streamSession(sessionRef, cursor, scope)`
|
||||
- `sendMessage(sessionRef, message, idempotencyKey, scope)`
|
||||
- `attach(sessionRef, mode, scope)` / `detach()`
|
||||
- `terminate(sessionRef, approvalRef, scope)`
|
||||
|
||||
Every call receives an immutable, server-derived actor/tenant/channel scope and correlation ID. Caller-supplied actor IDs are forbidden. Unsupported capabilities fail closed with typed errors.
|
||||
|
||||
### M1 Registry Boundary
|
||||
|
||||
`@mosaicstack/agent` owns the explicit `AgentRuntimeProviderRegistry`; duplicate provider IDs are rejected rather than replaced. Gateway owns `RuntimeProviderService`, which creates a frozen `RuntimeScope` from authenticated `ActorTenantScope` and trusted ingress channel/correlation metadata before every provider call. The service checks the declared provider capability before invoking a side effect and records metadata-only audit events (`providerId`, operation, outcome, actor/tenant/channel, correlation, and resource ID). It never records message bodies, idempotency keys, or approval references.
|
||||
|
||||
Termination is fail-closed: a runtime approval verifier must consume a one-time, exact action binding for the provider, session, actor, tenant, channel, and correlation ID before `terminate` reaches a provider. Until the durable verifier is wired, the default verifier denies termination. This internal service introduces no HTTP endpoint; later Discord, CLI, MCP, and provider adapters consume the same gateway boundary.
|
||||
|
||||
## Authority Model
|
||||
|
||||
| Intent | Owner | Tess behavior |
|
||||
| --------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------- |
|
||||
| Conversation, status, retrieval, safe diagnostics | Tess | Execute within policy |
|
||||
| Code/project decomposition, worker assignment, reviews, merge orchestration | Mos | Create a correlated handoff and observe result |
|
||||
| Destructive, privileged, external/customer-visible action | Human approval + policy | Propose, wait for durable one-time approval, then execute idempotently |
|
||||
| Provider-specific unsupported action | None | Fail closed; never emulate silently |
|
||||
|
||||
## Session and State Model
|
||||
|
||||
A Tess session has stable `sessionId`, `tenantId`, `ownerId`, provider/runtime identity, ingress bindings, cursor, checkpoint, inbox/outbox, and idempotency records. Discord and CLI bind to the same authorized session. Ownership is verified server-side on every list/read/attach/send/terminate operation.
|
||||
|
||||
Valkey may hold ephemeral coordination state; PostgreSQL is canonical for durable session bindings, approvals, audit, checkpoints, inbox/outbox, and idempotency. Pi session files are replay sources, not cross-agent truth.
|
||||
|
||||
## Transport Strategy
|
||||
|
||||
- **Initial:** fleet/tmux provider, including exact target, socket, identity, heartbeat, and safe attach semantics.
|
||||
- **Forward:** Matrix/native Mosaic provider using authenticated identity, idempotent transaction IDs, replay cursors, and the same contract suite.
|
||||
- Discord/CLI never call tmux or Matrix directly.
|
||||
|
||||
## Plugin Families
|
||||
|
||||
1. Channel: Discord now; other channels later.
|
||||
2. Runtime: Pi, fleet/tmux, Hermes, Matrix/native.
|
||||
3. Operator tools: fleet health, Mos handoff, GitOps wrappers, incident-safe diagnostics.
|
||||
4. Memory/state: search/recent/capture, durable inbox, checkpoint, handoff, compaction recovery.
|
||||
5. Migration: capability inventory, adapters, cutover, rollback, telemetry.
|
||||
|
||||
## Deployment
|
||||
|
||||
Tess runs as a rostered, systemd-supervised Pi agent using GPT-5.6 Sol and high reasoning. Secrets are supplied through approved runtime secret mechanisms. Startup fails when required model, gateway identity, Discord binding, or durable-state dependencies are missing. Health reports effective model/reasoning/tool policy without credential material.
|
||||
@@ -1,34 +0,0 @@
|
||||
# Tess Capability Migration Inventory
|
||||
|
||||
Status values: `native` · `adapt` · `defer` · `reject`. This is the initial inventory; M5 requires implementation and evidence fields to be completed before cutover.
|
||||
|
||||
| Capability | Current source | Target | Initial status | Cutover/rollback intent |
|
||||
| ---------------------------------------- | ---------------------------------------- | ------------------------------------------ | -------------- | ----------------------------------------------------------------------- |
|
||||
| Interactive agent chat/session streaming | Hermes/Pi/OpenClaw | Mosaic Tess session service | native | Dual-run per channel; revert binding to legacy gateway |
|
||||
| Discord dedicated-channel routing | Hermes/Claude/OpenClaw plugins | Mosaic Discord plugin + gateway | native | Per-channel binding switch; legacy bot disabled only after soak |
|
||||
| CLI/TUI session interaction and attach | Hermes/Pi/tmux | `mosaic tess` + AgentRuntimeProvider | native | Keep direct tmux attach as break-glass rollback |
|
||||
| Session list/tree/send/terminate | Hermes/fleet | AgentRuntimeProvider | native | Capability-negotiated adapter remains during migration |
|
||||
| Mos/fleet orchestration handoff | tmux messaging/Mosaic fleet | Mosaic coord/fleet provider | native | tmux handoff remains initial transport |
|
||||
| Kanban/projects/tasks | Hermes Kanban | Mosaic queue/coord/project providers | adapt | Read projection first; mutating cutover after parity/audit |
|
||||
| Skills catalog/load/manage | Hermes skills/Pi skills | Mosaic skill registry/provider | adapt | Import metadata/provenance; preserve source skill until validated |
|
||||
| Tools and MCP | Hermes/OpenClaw/MCP | Mosaic tool registry/MCP | adapt | Default deny; migrate allowlisted tools one capability at a time |
|
||||
| Cron/scheduled work | Hermes cron | Mosaic scheduler/queue | adapt | Shadow schedules; prevent duplicate execution; rollback owner field |
|
||||
| Memory search/recent/capture | jarvis-brain/OpenViking/OpenBrain/Hermes | Mosaic memory provider | adapt | Flat/project stores remain truth; semantic systems are mirrors |
|
||||
| User/profile preferences | Hermes memory/user profile | Mosaic user/memory domain | adapt | Provenance + explicit conflict rules; exportable rollback snapshot |
|
||||
| Agent state/inbox/handoff | OpenClaw extensions/session files | Mosaic durable state service | native | Read legacy handoff during coexistence; write Mosaic only after cutover |
|
||||
| Runtime contract/bootstrap | Mosaic framework/Hermes/OpenClaw | Mosaic compose/runtime provider | native | Legacy launchers remain until clean-host parity passes |
|
||||
| Repository/PR workflow | Mosaic wrappers/Hermes tools | Mosaic operator plugin | native | Wrapper-only; no raw-provider fallback |
|
||||
| Incident-safe diagnostics | Hermes skills/tools | Mosaic scoped operator plugin | adapt | Read-only first; privileged recovery requires approval |
|
||||
| Broad unrestricted shell from Discord | Hermes/OpenClaw configurations | None | reject | No cutover; replace with allowlisted typed operations |
|
||||
| Raw full transcript bulk migration | Hermes/Claude/OpenClaw histories | Indexed summaries/selective import | reject | Keep source archives subject to retention; no automatic copy |
|
||||
| Voice/video interaction | Hermes optional tools | Future Mosaic channel plugins | defer | Not required for Tess operational release |
|
||||
| Matrix transport | Mosaic connector | AgentRuntimeProvider Matrix implementation | native | Non-default until contract/reliability parity; tmux rollback |
|
||||
|
||||
## Cutover Gates
|
||||
|
||||
1. Capability contract and security tests pass.
|
||||
2. Data mapping/provenance and retention are documented.
|
||||
3. Shadow or dual-run shows no unauthorized access, loss, or duplicate effects.
|
||||
4. Operator runbook and rollback are exercised.
|
||||
5. Channel/provider binding changes are reversible without schema rollback.
|
||||
6. Legacy capability is disabled only after a defined soak period and evidence review.
|
||||
@@ -1,46 +0,0 @@
|
||||
# Mission Manifest — Tess Interaction Agent
|
||||
|
||||
## Mission
|
||||
|
||||
- **ID:** tess-20260712
|
||||
- **Issue:** #706
|
||||
- **Branch:** `feat/tess-interaction-agent`
|
||||
- **Phase:** Execution
|
||||
- **Current Milestone:** TESS-M1 — Runtime contracts and security foundation
|
||||
- **Progress:** 0 / 5 delivery milestones complete
|
||||
- **Status:** active
|
||||
- **Owner:** Mosaic orchestrator; Mos is coordinating fleet authority
|
||||
- **Source PRD:** `docs/PRD.md` — `TESS-*` requirements
|
||||
- **Scratchpad:** `docs/scratchpads/tess-20260712.md`
|
||||
|
||||
## Mission Statement
|
||||
|
||||
Ship Tess as Jason's durable Pi-native GPT-5.6 Sol high-reasoning interaction agent for Discord and CLI, with safe visibility/control of Mosaic fleet and transitional Hermes capabilities, while Mos remains the coding/general orchestration authority.
|
||||
|
||||
## Invariants
|
||||
|
||||
1. Mosaic is the enterprise AI hub; Hermes is a reference migration adapter.
|
||||
2. Gateway is the single API surface.
|
||||
3. Mos owns coding/general fleet orchestration; Tess owns human interaction, visibility, mediation, and migration access.
|
||||
4. Runtime, transport, channel, memory, and external-agent integrations are replaceable adapters.
|
||||
5. No source task completes before merged PR, terminal-green CI, independent review, and linked task/issue closure.
|
||||
|
||||
## Milestones
|
||||
|
||||
| ID | Issue | Name | Status | Exit gate |
|
||||
| ------- | ----- | ------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| TESS-M1 | #707 | Runtime contracts and security foundation | ready | AgentRuntimeProvider, normalized events/capabilities/errors, RBAC/audit contracts and contract tests merged |
|
||||
| TESS-M2 | #708 | Durable Pi Tess service and state | not-started | GPT-5.6 Sol high service starts, resumes, checkpoints, and passes restart/compaction tests |
|
||||
| TESS-M3 | #709 | Discord and CLI interaction surfaces | not-started | One durable session works through dedicated Discord binding and `mosaic tess`, including attach and approvals |
|
||||
| TESS-M4 | #710 | Fleet, Mos, Hermes, memory, state, and tool plugins | not-started | Fleet/Mos boundary and transitional capability matrix demonstrated end-to-end |
|
||||
| TESS-M5 | #711 | Matrix/native migration, recovery, documentation, and qualification | not-started | Transport parity, migration/rollback matrix, security review, docs, greenfield and deployment validation complete |
|
||||
|
||||
## Success Criteria
|
||||
|
||||
All `AC-TESS-*` criteria in `docs/PRD.md` are mapped to reproducible evidence. The final operational test must prove Discord + CLI session continuity, fleet/Mos coordination, authorized Hermes transition capabilities, denial/audit paths, restart recovery, and rollback.
|
||||
|
||||
## Session History
|
||||
|
||||
| Session | Date | Runtime | Outcome |
|
||||
| ------- | ---------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| S1 | 2026-07-12 | Hermes / GPT-5.6 Sol | User commission captured; Mosaic/OpenViking/session/code archaeology completed; issue #706 created; PRD and task control plane initialized. |
|
||||
@@ -1,34 +0,0 @@
|
||||
# Tasks — Tess Interaction Agent
|
||||
|
||||
> Mission: `tess-20260712` · Issue: #706 · PRD requirements: `TESS-*`
|
||||
> Orchestrator is sole writer. Workers must not modify this file.
|
||||
> `repo` contains one or more comma-separated repository-relative roots; every listed root must exist before dispatch.
|
||||
|
||||
| id | status | description | issue | agent | repo | branch | depends_on | estimate | notes |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| TESS-PLAN-001 | done | Finalize PRD, architecture, authority boundary, threat model, migration inventory, and verification matrix | #706 | sonnet | docs, packages/types, apps/gateway | feat/tess-interaction-agent | — | 22K | Independent gate PASS after two remediation rounds; completion effective when planning PR merges |
|
||||
| TESS-M1-SEC-001 | not-started | Enforce command scopes/roles and durable exact-action approval for privileged/destructive commands | #707 | codex | apps/gateway | fix/tess-command-authz | TESS-PLAN-001 | 25K | TESS-SEC-002; security TDD |
|
||||
| TESS-M1-SEC-002 | not-started | Enforce owner/tenant binding on session list/read/attach/send/terminate across REST and WS | #707 | codex | apps/gateway | fix/tess-session-ownership | TESS-PLAN-001 | 30K | TESS-SEC-003; security TDD |
|
||||
| TESS-M1-SEC-003 | not-started | Bind MCP actor/tenant to authenticated context and add per-tool scopes | #707 | codex | apps/gateway | fix/tess-mcp-identity | TESS-PLAN-001 | 22K | TESS-SEC-004; security TDD |
|
||||
| TESS-M1-SEC-004 | not-started | Add authenticated Discord service ingress, allowlists, correlation and replay protection | #707 | codex | plugins/discord, apps/gateway | fix/tess-discord-ingress | TESS-PLAN-001 | 28K | TESS-SEC-005; security TDD |
|
||||
| TESS-M1-SEC-005 | not-started | Redact/classify secret and PII before persistence/egress; harden provider login flow | #707 | codex | apps/gateway, packages/log | fix/tess-redaction | TESS-PLAN-001 | 28K | TESS-SEC-006; seeded canary tests |
|
||||
| TESS-M1-SEC-006 | not-started | Scope session GC/retention or separate authorized global retention job | #707 | codex | apps/gateway, packages/log | fix/tess-session-gc-scope | TESS-PLAN-001 | 18K | TESS-SEC-009; isolation TDD |
|
||||
| TESS-M1-001 | not-started | Define AgentRuntimeProvider, capabilities, session tree, normalized stream events/errors, attach semantics | #707 | codex | packages/types, packages/agent | feat/tess-runtime-contract | TESS-PLAN-001 | 25K | TESS-ARP-001, TESS-TRN-001; contract TDD |
|
||||
| TESS-M1-002 | not-started | Implement provider registry/service with immutable actor scope, approval, audit and correlation boundaries | #707 | codex | apps/gateway, packages/agent | feat/tess-provider-registry | TESS-M1-001,TESS-M1-SEC-001,TESS-M1-SEC-002,TESS-M1-SEC-003 | 30K | TESS-SEC-001..004,007; security TDD |
|
||||
| TESS-M1-003 | not-started | Implement tmux/fleet runtime provider and safe attach/message/terminate capability policy | #707 | codex | packages/mosaic, packages/agent | feat/tess-fleet-provider | TESS-M1-002 | 30K | TESS-FLT-001; exact target/identity tests |
|
||||
| TESS-M1-OBS-001 | not-started | Implement correlation propagation, structured runtime/provider/tool audit, health/readiness and safe effective-policy status | #707 | codex | apps/gateway, packages/agent, packages/log | feat/tess-observability | TESS-M1-002 | 24K | TESS-OBS-001; no credential material |
|
||||
| TESS-M1-V | not-started | Independent architecture/security review and complete contract/abuse-suite verification | #707 | sonnet | apps/gateway, packages/agent, packages/log, plugins/discord | review/tess-m1 | TESS-M1-SEC-001,TESS-M1-SEC-002,TESS-M1-SEC-003,TESS-M1-SEC-004,TESS-M1-SEC-005,TESS-M1-SEC-006,TESS-M1-003,TESS-M1-OBS-001 | 20K | Gate M2 |
|
||||
| TESS-M2-001 | not-started | Add Tess roster/profile/service pinned to GPT-5.6 Sol high with fail-fast config and observable effective policy | #708 | codex | packages/mosaic/framework | feat/tess-pi-service | TESS-M1-V | 22K | TESS-PI-001; explicit AC-TESS-03 test |
|
||||
| TESS-M2-002 | not-started | Implement durable session identity, inbox/outbox, approval, checkpoint, handoff, compaction and restart recovery | #708 | codex | apps/gateway, packages/agent, packages/db | feat/tess-durable-state | TESS-M2-001 | 38K | TESS-STA-001, TESS-SEC-007..008; recovery TDD |
|
||||
| TESS-M2-V | not-started | Clean-host Pi launch plus model/policy status and restart/compaction/duplicate-side-effect verification | #708 | sonnet | apps/gateway/src/__tests__/integration, packages/mosaic/src | review/tess-m2 | TESS-M2-002 | 18K | Gate M3; AC-TESS-03/06 |
|
||||
| TESS-M3-001 | not-started | Bind dedicated Tess Discord channel with streaming, threads, attachments, pairing/RBAC and approvals | #709 | codex | plugins/discord, apps/gateway | feat/tess-discord | TESS-M2-V,TESS-M1-SEC-004 | 35K | TESS-DSC-001 |
|
||||
| TESS-M3-002 | not-started | Implement `mosaic tess` chat/status/sessions/tree/attach/send/stop/health/recover CLI | #709 | codex | packages/mosaic | feat/tess-cli | TESS-M2-V | 30K | TESS-CLI-001 |
|
||||
| TESS-M3-V | not-started | Discord+CLI same-session E2E, denial/approval tests, and operator-flow review | #709 | sonnet | apps/gateway/src/__tests__/integration, plugins/discord, packages/mosaic/src | review/tess-m3 | TESS-M3-001,TESS-M3-002 | 20K | Gate M4 |
|
||||
| TESS-M4-001 | not-started | Implement Mos coordination handoff/observe/result contract with authority-boundary tests | #710 | codex | packages/coord, apps/gateway | feat/tess-mos-coordination | TESS-M3-V | 25K | TESS-MOS-001 |
|
||||
| TESS-M4-002 | not-started | Implement transitional Hermes runtime/capability adapter | #710 | codex | packages/agent, apps/gateway | feat/tess-hermes-adapter | TESS-M3-V | 40K | TESS-HRM-001; no legacy schema in core contracts |
|
||||
| TESS-M4-003 | not-started | Implement memory/retrieval, state/inbox, runtime bootstrap, fleet diagnostics and GitOps plugin foundations | #710 | codex | packages/memory, packages/agent, packages/mosaic | feat/tess-operator-plugins | TESS-M3-V | 40K | TESS-MEM-001, TESS-PLG-001 |
|
||||
| TESS-M4-V | not-started | Cross-provider capability, privacy, authority and failure-path qualification | #710 | sonnet | apps/gateway/src/__tests__/integration, packages/agent | review/tess-m4 | TESS-M4-001,TESS-M4-002,TESS-M4-003 | 22K | Gate M5 |
|
||||
| TESS-M5-001 | not-started | Implement Matrix/native runtime provider behind common contracts and parity suite | #711 | codex | packages/mosaic, packages/agent | feat/tess-matrix-provider | TESS-M4-V | 30K | TESS-TRN-001 |
|
||||
| TESS-M5-002 | not-started | Complete migration inventory, cutover, rollback, retention and deprecation evidence | #711 | sonnet | docs/tess | feat/tess-migration-docs | TESS-M4-V | 18K | TESS-MIG-001 |
|
||||
| TESS-M5-003 | not-started | Complete OpenAPI, user/admin/developer/plugin/operations docs and checklist | #711 | codex | docs | feat/tess-docs | TESS-M5-001,TESS-M5-002 | 22K | Documentation hard gate |
|
||||
| TESS-M5-V | not-started | Full baseline, contract, integration, Discord/CLI E2E, security review, recovery drill and rollback qualification | #711 | sonnet | apps/gateway, packages/agent, plugins/discord, packages/mosaic | review/tess-final | TESS-M5-003 | 35K | Maps AC-TESS-01..11 to evidence |
|
||||
@@ -1,46 +0,0 @@
|
||||
# Tess Threat Model
|
||||
|
||||
## Assets and Trust Boundaries
|
||||
|
||||
Assets: operator identity, tenant/project data, agent sessions, fleet control, approvals, credentials, memories, tool outputs, audit evidence, and provider transports.
|
||||
|
||||
Trust boundaries: Discord→plugin, CLI→gateway, plugin→gateway service identity, gateway→Pi/provider, Tess→Mos/fleet, Tess→Hermes, MCP→gateway, persistence, and tmux/Matrix transports.
|
||||
|
||||
## Threat Matrix
|
||||
|
||||
| ID | Severity | Threat | Required control | Required verification |
|
||||
| ----- | -------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
|
||||
| TM-01 | critical | Client invokes admin/system command without role | Server-side scope/role enforcement in executor; durable approval for privileged/destructive commands | Authenticated non-admin and forged-scope tests deny and audit |
|
||||
| TM-02 | critical | Cross-user/tenant list, attach, send, or terminate by guessed session ID | Owner/tenant binding on every session operation; admin override is explicit and audited | Cross-tenant matrix for REST, WS, CLI, Discord and provider methods |
|
||||
| TM-03 | high | MCP caller supplies another `userId` | Remove actor IDs from schemas; derive actor/tenant from authenticated context; per-tool scopes | Forged actor/tool calls deny; no victim data returned |
|
||||
| TM-04 | high | Discord ingress impersonates user/channel or bypasses gateway auth | Service-to-service identity, guild/channel/user allowlists, signed/correlated envelope, replay protection | Invalid service identity, unlisted IDs, replayed message IDs all deny |
|
||||
| TM-05 | high | Secrets/PII leak in chat, auth links, tool args, logs, memory, or DB | Redact before persistence/egress; DM/out-of-band auth flow; short-lived hashed token state; output classification | Seeded secret/PII canary absent from durable stores/logs/public channel |
|
||||
| TM-06 | high | Prompt/tool injection escalates from content to privileged action | Treat messages/files/tool output as untrusted data; structured proposals only; allowlisted tools; approval binds exact action digest | Injection corpus cannot invoke unapproved tools or alter authority |
|
||||
| TM-07 | high | Approval forged, replayed, or applied to modified action | One-time approval with actor, tenant, action digest, expiry, correlation and consumption record | Forged/replayed/expired/mutated approvals deny and audit |
|
||||
| TM-08 | medium | Restart causes message loss or duplicate side effects | Durable inbox/outbox/checkpoint; idempotency keys; transactional state transitions; bounded replay | Kill/restart at each state transition; exactly-once effect or safe dedupe |
|
||||
| TM-09 | medium | Session GC/retention crosses tenant/session scope | Session/user-scoped GC or separately authorized global retention job | GC one session; unrelated logs/memory remain unchanged |
|
||||
| TM-10 | high | tmux/Matrix transport target or identity spoofing | Exact target/socket binding, peer identity verification, Matrix whoami, authenticated transport metadata | Wrong socket/peer/room/identity refuses delivery/attach |
|
||||
| TM-11 | medium | Hermes adapter exposes unsupported or broader legacy powers | Capability negotiation, default deny, normalized scopes, adapter sandbox/timeouts | Unsupported and over-scoped operations fail closed |
|
||||
| TM-12 | medium | Tess competes with Mos or bypasses orchestration gates | Authority policy and correlated Mos handoff; no Tess worker-claim capability by default | Coding/decomposition intent produces handoff, not direct claim |
|
||||
|
||||
## Security Invariants
|
||||
|
||||
1. Authentication is not authorization; every command/tool/provider operation is authorized server-side.
|
||||
2. Actor, tenant, roles, and channel bindings come only from authenticated gateway context.
|
||||
3. No client-provided session ID grants ownership or attachment.
|
||||
4. No privileged action executes without a matching, unexpired, one-time approval when policy requires it.
|
||||
5. Redaction occurs before persistence and before channel egress.
|
||||
6. Every externally caused operation is replay-safe and correlated.
|
||||
7. Provider capability absence is a denial, not an invitation to shell around it.
|
||||
|
||||
## Existing Findings That Block Tess
|
||||
|
||||
- Command executor lacks server-side enforcement for declared scopes.
|
||||
- Session list/reuse/destroy surfaces are not owner-filtered consistently.
|
||||
- MCP schemas accept caller-supplied user identity.
|
||||
- Discord plugin lacks a complete authenticated service ingress and user/channel allowlists.
|
||||
- Chat/tool persistence lacks mandatory redaction.
|
||||
- Sessions/pending Discord output are in-memory and not restart-safe.
|
||||
- Session GC currently performs globally scoped promotion.
|
||||
|
||||
These are tracked as M1 security prerequisites and must pass independent security review before Tess ingress is enabled.
|
||||
@@ -1,30 +0,0 @@
|
||||
# Tess Verification Matrix
|
||||
|
||||
| Acceptance criterion | Requirements | Planned evidence | Gate |
|
||||
| -------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
|
||||
| AC-TESS-01 | TESS-PI-001, TESS-DSC-001, TESS-CLI-001 | Discord/CLI same-session integration and streaming E2E | M3-V |
|
||||
| AC-TESS-02 | TESS-ARP-001, TESS-CLI-001, TESS-FLT-001 | CLI contract tests for status/sessions/tree/attach/send/stop, typed denial/error snapshots | M3-V |
|
||||
| AC-TESS-03 | TESS-PI-001, TESS-OBS-001 | Clean service launch; status asserts GPT-5.6 Sol, high reasoning and effective tool policy with secret canaries absent | M2-V, M3-V |
|
||||
| AC-TESS-04 | TESS-MOS-001, TESS-FLT-001 | Authority E2E: coding request creates Mos handoff; safe status runs in Tess; no competing worker claim | M4-V |
|
||||
| AC-TESS-05 | TESS-HRM-001 | Hermes capability contract suite: sessions/stream/send/tree plus Kanban/skills/memory/tools/cron supported-or-denied matrix | M4-V |
|
||||
| AC-TESS-06 | TESS-STA-001, TESS-SEC-008 | Kill/restart/compaction fault injection across inbox/outbox/checkpoint transitions; duplicate side-effect detector | M2-V, M5-V |
|
||||
| AC-TESS-07 | TESS-SEC-001..009 | Threat-model abuse suite: authz, tenant isolation, forged identity/approval, injection, redaction, transport identity, GC scope | M1-V, M3-V, M5-V |
|
||||
| AC-TESS-08 | TESS-TRN-001 | Common provider contract suite against tmux/fleet and Matrix/native; identity and replay tests | M5-V |
|
||||
| AC-TESS-09 | all | `pnpm typecheck`, lint, format, unit/integration/contract/E2E; independent code and security reviews; CI URLs | Every milestone |
|
||||
| AC-TESS-10 | TESS-MIG-001 | Completed capability inventory with native/adapted/deferred/rejected state, owner, cutover/rollback evidence | M5-V |
|
||||
| AC-TESS-11 | TESS-PLG-001, TESS-OBS-001 | OpenAPI and user/admin/developer/plugin/ops docs, sitemap links, documentation checklist | M5-V |
|
||||
|
||||
## Security Abuse Suite Minimum
|
||||
|
||||
- Role/scope matrix for every command and provider capability.
|
||||
- Cross-tenant and cross-user session ID matrix across REST, WS, Discord, CLI, MCP, and providers.
|
||||
- Discord service identity, guild/channel/user allowlist, replay, attachment, and mention/DM policy cases.
|
||||
- Prompt/tool injection corpus and structured-proposal enforcement.
|
||||
- Approval action-digest mutation, replay, expiry, tenant, and actor mismatch cases.
|
||||
- Secret/PII canaries through message, attachment, tool args/output, logs, memory, audit, and error paths.
|
||||
- Restart fault injection before/after enqueue, provider send, side effect, response persistence, and acknowledgement.
|
||||
- Wrong tmux socket/target and Matrix identity/room/replay cases.
|
||||
|
||||
## Evidence Rules
|
||||
|
||||
Evidence must include command/test name, terminal result, CI run URL, PR/merge reference, environment, and artifact/log location. A worker self-report is not evidence until independently verified.
|
||||
@@ -30,7 +30,6 @@ export default tseslint.config(
|
||||
'apps/gateway/vitest.config.ts',
|
||||
'packages/db/vitest.config.ts',
|
||||
'packages/storage/vitest.config.ts',
|
||||
'packages/mosaic/vitest.config.ts',
|
||||
'packages/mosaic/__tests__/*.ts',
|
||||
'tools/federation-harness/*.ts',
|
||||
],
|
||||
|
||||
@@ -15,22 +15,6 @@ This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.)
|
||||
7. Branching/merging is consistent: `branch -> main` via PR with squash-only merges
|
||||
8. Steered-autonomy execution is enabled so agents can run end-to-end with escalation-only human intervention
|
||||
|
||||
## Agent Host Prerequisites
|
||||
|
||||
Agent hosts must provide the Python runtime shape that runtime agents and
|
||||
Mosaic automation assume is present.
|
||||
|
||||
For Debian/Ubuntu hosts:
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
# #561: bare python invocations from agents must resolve.
|
||||
sudo apt-get install -y python3 python-is-python3
|
||||
```
|
||||
|
||||
For non-Debian hosts, install the equivalent Python 3 runtime and ensure
|
||||
`/usr/bin/python` resolves to `python3` (for example, via a managed symlink).
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
|
||||
@@ -1,3 +1 @@
|
||||
export const VERSION = '0.0.0';
|
||||
|
||||
export * from './runtime-provider-registry.js';
|
||||
|
||||
@@ -1,95 +0,0 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import type {
|
||||
AgentRuntimeProvider,
|
||||
RuntimeAttachHandle,
|
||||
RuntimeAttachMode,
|
||||
RuntimeCapabilitySet,
|
||||
RuntimeHealth,
|
||||
RuntimeMessage,
|
||||
RuntimeScope,
|
||||
RuntimeSession,
|
||||
RuntimeSessionTree,
|
||||
RuntimeStreamEvent,
|
||||
} from '@mosaicstack/types';
|
||||
import { AgentRuntimeProviderRegistry } from './runtime-provider-registry.js';
|
||||
|
||||
class TestRuntimeProvider implements AgentRuntimeProvider {
|
||||
readonly id = 'test-runtime';
|
||||
|
||||
async capabilities(_scope: RuntimeScope): Promise<RuntimeCapabilitySet> {
|
||||
return { supported: ['session.list'] };
|
||||
}
|
||||
|
||||
async health(_scope: RuntimeScope): Promise<RuntimeHealth> {
|
||||
return { status: 'healthy', checkedAt: '2026-07-12T00:00:00.000Z' };
|
||||
}
|
||||
|
||||
async listSessions(_scope: RuntimeScope): Promise<RuntimeSession[]> {
|
||||
return [];
|
||||
}
|
||||
|
||||
async getSessionTree(_scope: RuntimeScope): Promise<RuntimeSessionTree[]> {
|
||||
return [];
|
||||
}
|
||||
|
||||
async *streamSession(
|
||||
_sessionId: string,
|
||||
_cursor: string | undefined,
|
||||
_scope: RuntimeScope,
|
||||
): AsyncIterable<RuntimeStreamEvent> {
|
||||
return;
|
||||
}
|
||||
|
||||
async sendMessage(
|
||||
_sessionId: string,
|
||||
_message: RuntimeMessage,
|
||||
_scope: RuntimeScope,
|
||||
): Promise<void> {}
|
||||
|
||||
async attach(
|
||||
_sessionId: string,
|
||||
_mode: RuntimeAttachMode,
|
||||
_scope: RuntimeScope,
|
||||
): Promise<RuntimeAttachHandle> {
|
||||
return {
|
||||
attachmentId: 'attachment-1',
|
||||
sessionId: 'session-1',
|
||||
mode: 'read',
|
||||
expiresAt: '2026-07-12T00:00:00.000Z',
|
||||
};
|
||||
}
|
||||
|
||||
async detach(_attachmentId: string, _scope: RuntimeScope): Promise<void> {}
|
||||
|
||||
async terminate(_sessionId: string, _approvalRef: string, _scope: RuntimeScope): Promise<void> {}
|
||||
}
|
||||
|
||||
describe('AgentRuntimeProviderRegistry', (): void => {
|
||||
it('resolves only registered runtime providers', (): void => {
|
||||
const registry = new AgentRuntimeProviderRegistry();
|
||||
const provider = new TestRuntimeProvider();
|
||||
|
||||
registry.register(provider);
|
||||
|
||||
expect(registry.get(provider.id)).toBe(provider);
|
||||
expect(registry.get('unknown-runtime')).toBeUndefined();
|
||||
expect(registry.list()).toEqual([provider]);
|
||||
});
|
||||
|
||||
it('rejects duplicate and blank provider identities rather than silently replacing a runtime', (): void => {
|
||||
const registry = new AgentRuntimeProviderRegistry();
|
||||
const provider = new TestRuntimeProvider();
|
||||
|
||||
registry.register(provider);
|
||||
|
||||
expect((): void => {
|
||||
registry.register(provider);
|
||||
}).toThrow(/already registered/);
|
||||
expect((): void => {
|
||||
registry.require('');
|
||||
}).toThrow(/provider ID is required/);
|
||||
expect((): void => {
|
||||
registry.require('unknown-runtime');
|
||||
}).toThrow(/not registered/);
|
||||
});
|
||||
});
|
||||
@@ -1,40 +0,0 @@
|
||||
import type { AgentRuntimeProvider } from '@mosaicstack/types';
|
||||
|
||||
/**
|
||||
* Registry for runtime providers. Registration is explicit and replacement is
|
||||
* forbidden so a provider identity cannot be silently hijacked at runtime.
|
||||
*/
|
||||
export class AgentRuntimeProviderRegistry {
|
||||
private readonly providers = new Map<string, AgentRuntimeProvider>();
|
||||
|
||||
register(provider: AgentRuntimeProvider): void {
|
||||
const providerId = provider.id.trim();
|
||||
if (providerId.length === 0) {
|
||||
throw new Error('Runtime provider ID is required');
|
||||
}
|
||||
if (this.providers.has(providerId)) {
|
||||
throw new Error(`Runtime provider is already registered: ${providerId}`);
|
||||
}
|
||||
this.providers.set(providerId, provider);
|
||||
}
|
||||
|
||||
get(providerId: string): AgentRuntimeProvider | undefined {
|
||||
return this.providers.get(providerId);
|
||||
}
|
||||
|
||||
require(providerId: string): AgentRuntimeProvider {
|
||||
const normalizedProviderId = providerId.trim();
|
||||
if (normalizedProviderId.length === 0) {
|
||||
throw new Error('Runtime provider ID is required');
|
||||
}
|
||||
const provider = this.providers.get(normalizedProviderId);
|
||||
if (!provider) {
|
||||
throw new Error(`Runtime provider is not registered: ${normalizedProviderId}`);
|
||||
}
|
||||
return provider;
|
||||
}
|
||||
|
||||
list(): AgentRuntimeProvider[] {
|
||||
return Array.from(this.providers.values());
|
||||
}
|
||||
}
|
||||
@@ -1,22 +0,0 @@
|
||||
CREATE TYPE "public"."backlog_status" AS ENUM('ready', 'claimed', 'blocked', 'done');--> statement-breakpoint
|
||||
CREATE TABLE "backlog" (
|
||||
"id" text PRIMARY KEY NOT NULL,
|
||||
"title" text NOT NULL,
|
||||
"body" text,
|
||||
"phase" text,
|
||||
"priority" integer DEFAULT 0 NOT NULL,
|
||||
"status" "backlog_status" DEFAULT 'ready' NOT NULL,
|
||||
"depends_on" jsonb DEFAULT '[]'::jsonb NOT NULL,
|
||||
"claim_owner" text,
|
||||
"claim_ttl_seconds" integer,
|
||||
"claimed_at" timestamp with time zone,
|
||||
"attempts" integer DEFAULT 0 NOT NULL,
|
||||
"idempotency_key" text,
|
||||
"acceptance" jsonb,
|
||||
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
|
||||
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
|
||||
);
|
||||
--> statement-breakpoint
|
||||
CREATE INDEX "backlog_status_priority_idx" ON "backlog" USING btree ("status","priority");--> statement-breakpoint
|
||||
CREATE INDEX "backlog_status_claimed_at_idx" ON "backlog" USING btree ("status","claimed_at");--> statement-breakpoint
|
||||
CREATE UNIQUE INDEX "backlog_idempotency_key_idx" ON "backlog" USING btree ("idempotency_key");
|
||||
File diff suppressed because it is too large
Load Diff
@@ -78,13 +78,6 @@
|
||||
"when": 1745366400000,
|
||||
"tag": "0010_federation_enrollment_tokens",
|
||||
"breakpoints": true
|
||||
},
|
||||
{
|
||||
"idx": 11,
|
||||
"version": "7",
|
||||
"when": 1782310438919,
|
||||
"tag": "0011_bitter_gateway",
|
||||
"breakpoints": true
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@mosaicstack/db",
|
||||
"version": "0.0.4",
|
||||
"version": "0.0.3",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
|
||||
|
||||
@@ -1,263 +0,0 @@
|
||||
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
|
||||
import { sql } from 'drizzle-orm';
|
||||
import { createPgliteDb } from './client-pglite.js';
|
||||
import { runPgliteMigrations } from './migrate.js';
|
||||
import type { DbHandle } from './client.js';
|
||||
import { BacklogService } from './backlog.js';
|
||||
import { backlog } from './schema.js';
|
||||
|
||||
// Helper: backdate a claim's claimed_at by 1 hour so it is past any short TTL.
|
||||
function sqlBackdate(id: string) {
|
||||
return sql`UPDATE ${backlog} SET claimed_at = now() - interval '1 hour' WHERE ${backlog.id} = ${id}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Real Postgres semantics, no external server: embedded in-memory PGlite.
|
||||
* The migration path creates the `backlog` table (and every other table) so the
|
||||
* service runs against the actual generated schema, including the row locks the
|
||||
* atomic-claim path depends on.
|
||||
*/
|
||||
async function freshService(): Promise<{ handle: DbHandle; svc: BacklogService }> {
|
||||
const handle = createPgliteDb('memory://');
|
||||
await runPgliteMigrations(handle);
|
||||
return { handle, svc: new BacklogService(handle.db) };
|
||||
}
|
||||
|
||||
describe('BacklogService', () => {
|
||||
let handle: DbHandle;
|
||||
let svc: BacklogService;
|
||||
|
||||
beforeEach(async () => {
|
||||
({ handle, svc } = await freshService());
|
||||
});
|
||||
|
||||
afterEach(async () => {
|
||||
await handle.close();
|
||||
});
|
||||
|
||||
it('create then list returns the card', async () => {
|
||||
await svc.create({ id: 'c1', title: 'First card', phase: 'M1', priority: 5 });
|
||||
const all = await svc.list();
|
||||
expect(all).toHaveLength(1);
|
||||
expect(all[0]).toMatchObject({ id: 'c1', title: 'First card', phase: 'M1', status: 'ready' });
|
||||
});
|
||||
|
||||
it('idempotency_key dedups create', async () => {
|
||||
const a = await svc.create({ id: 'c1', title: 'one', idempotencyKey: 'k-1' });
|
||||
const b = await svc.create({ id: 'c2', title: 'two', idempotencyKey: 'k-1' });
|
||||
expect(b.id).toBe(a.id);
|
||||
const all = await svc.list();
|
||||
expect(all).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('list filters by status and phase', async () => {
|
||||
await svc.create({ id: 'c1', title: 'a', phase: 'M1' });
|
||||
await svc.create({ id: 'c2', title: 'b', phase: 'M2' });
|
||||
await svc.block('c2');
|
||||
expect(await svc.list({ phase: 'M1' })).toHaveLength(1);
|
||||
expect(await svc.list({ status: 'blocked' })).toHaveLength(1);
|
||||
expect((await svc.list({ status: 'blocked' }))[0]!.id).toBe('c2');
|
||||
});
|
||||
|
||||
describe('atomic claim', () => {
|
||||
it('two concurrent claimers on one card => exactly one wins', async () => {
|
||||
await svc.create({ id: 'only', title: 'the one', priority: 10 });
|
||||
|
||||
// Two independent claimers race for the single ready card on the same db.
|
||||
// The atomic claim path (`FOR UPDATE SKIP LOCKED` inside a transaction)
|
||||
// guarantees the loser's locked row is skipped, so it can never also flip
|
||||
// the card to claimed — it gets the next candidate (none) and returns null.
|
||||
const svcA = new BacklogService(handle.db);
|
||||
const svcB = new BacklogService(handle.db);
|
||||
|
||||
const [a, b] = await Promise.all([
|
||||
svcA.claim({ owner: 'worker-A' }),
|
||||
svcB.claim({ owner: 'worker-B' }),
|
||||
]);
|
||||
|
||||
const winners = [a, b].filter((c) => c !== null);
|
||||
expect(winners).toHaveLength(1);
|
||||
expect(winners[0]!.id).toBe('only');
|
||||
expect(winners[0]!.status).toBe('claimed');
|
||||
expect(['worker-A', 'worker-B']).toContain(winners[0]!.claimOwner);
|
||||
|
||||
const card = await svc.get('only');
|
||||
expect(card!.status).toBe('claimed');
|
||||
expect(card!.attempts).toBe(1);
|
||||
});
|
||||
|
||||
it('many concurrent claimers on N cards => no card is double-claimed', async () => {
|
||||
// 5 ready cards, 8 concurrent claimers. Exactly 5 win, all distinct.
|
||||
for (let i = 0; i < 5; i++) {
|
||||
await svc.create({ id: `card-${i}`, title: `card ${i}`, priority: i });
|
||||
}
|
||||
const claimers = Array.from({ length: 8 }, (_, i) =>
|
||||
new BacklogService(handle.db).claim({ owner: `w-${i}` }),
|
||||
);
|
||||
const results = await Promise.all(claimers);
|
||||
const won = results.filter((c): c is NonNullable<typeof c> => c !== null);
|
||||
const wonIds = won.map((c) => c.id);
|
||||
expect(won).toHaveLength(5);
|
||||
expect(new Set(wonIds).size).toBe(5); // all distinct — no double-claim
|
||||
});
|
||||
|
||||
it('N concurrent claimers on N ready cards => every claimer wins a distinct card (no starvation)', async () => {
|
||||
// This is the direct benefit of locking exactly ONE ready row per claim
|
||||
// (`FOR UPDATE SKIP LOCKED LIMIT 1`): with as many ready cards as
|
||||
// claimers, NONE should starve. The old "lock the whole ready set"
|
||||
// behaviour let one claimer lock every row, forcing the rest to null even
|
||||
// though cards were free.
|
||||
const N = 6;
|
||||
for (let i = 0; i < N; i++) {
|
||||
await svc.create({ id: `n-${i}`, title: `card ${i}`, priority: i });
|
||||
}
|
||||
const results = await Promise.all(
|
||||
Array.from({ length: N }, (_, i) =>
|
||||
new BacklogService(handle.db).claim({ owner: `w-${i}` }),
|
||||
),
|
||||
);
|
||||
const won = results.filter((c): c is NonNullable<typeof c> => c !== null);
|
||||
// No claimer starved: all N won.
|
||||
expect(won).toHaveLength(N);
|
||||
// Each won a distinct card.
|
||||
expect(new Set(won.map((c) => c.id)).size).toBe(N);
|
||||
// Every ready card was consumed.
|
||||
expect(await svc.list({ status: 'ready' })).toHaveLength(0);
|
||||
});
|
||||
|
||||
it('sequential claims drain ready cards in priority order and never null while ready remain', async () => {
|
||||
// PGlite-stable fallback assertion of the same property without relying on
|
||||
// true parallelism or wall-clock timing: each claim returns the next
|
||||
// highest-priority distinct card and never spuriously returns null while
|
||||
// ready cards remain.
|
||||
const N = 4;
|
||||
for (let i = 0; i < N; i++) {
|
||||
await svc.create({ id: `s-${i}`, title: `card ${i}`, priority: i });
|
||||
}
|
||||
const order: string[] = [];
|
||||
for (let i = 0; i < N; i++) {
|
||||
const claimed = await svc.claim({ owner: `w-${i}` });
|
||||
expect(claimed).not.toBeNull();
|
||||
order.push(claimed!.id);
|
||||
}
|
||||
// Highest priority first, all distinct.
|
||||
expect(order).toEqual(['s-3', 's-2', 's-1', 's-0']);
|
||||
expect(new Set(order).size).toBe(N);
|
||||
// Now nothing ready remains => null.
|
||||
expect(await svc.claim({ owner: 'late' })).toBeNull();
|
||||
});
|
||||
|
||||
it('claim picks the highest-priority ready card', async () => {
|
||||
await svc.create({ id: 'low', title: 'low', priority: 1 });
|
||||
await svc.create({ id: 'high', title: 'high', priority: 9 });
|
||||
const claimed = await svc.claim({ owner: 'w' });
|
||||
expect(claimed!.id).toBe('high');
|
||||
});
|
||||
|
||||
it('claim of a specific --id', async () => {
|
||||
await svc.create({ id: 'a', title: 'a', priority: 9 });
|
||||
await svc.create({ id: 'b', title: 'b', priority: 1 });
|
||||
const claimed = await svc.claim({ owner: 'w', id: 'b' });
|
||||
expect(claimed!.id).toBe('b');
|
||||
});
|
||||
|
||||
it('claim returns null when nothing is ready', async () => {
|
||||
const claimed = await svc.claim({ owner: 'w' });
|
||||
expect(claimed).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('deps DAG gate', () => {
|
||||
it('card with an unfinished dep is not claimable and not ready', async () => {
|
||||
await svc.create({ id: 'dep', title: 'dependency' });
|
||||
await svc.create({ id: 'main', title: 'depends on dep', dependsOn: ['dep'] });
|
||||
|
||||
// `main` should NOT be claimable while `dep` is not done — `dep` wins.
|
||||
const first = await svc.claim({ owner: 'w' });
|
||||
expect(first!.id).toBe('dep');
|
||||
|
||||
// With dep claimed (not done), main still cannot be claimed.
|
||||
const second = await svc.claim({ owner: 'w' });
|
||||
expect(second).toBeNull();
|
||||
|
||||
// ready-only list excludes main while its dep is unfinished.
|
||||
const ready = await svc.list({ readyOnly: true });
|
||||
expect(ready.map((c) => c.id)).not.toContain('main');
|
||||
|
||||
// Once dep is done, main becomes ready and claimable.
|
||||
await svc.complete('dep');
|
||||
const readyAfter = await svc.list({ readyOnly: true });
|
||||
expect(readyAfter.map((c) => c.id)).toContain('main');
|
||||
const third = await svc.claim({ owner: 'w' });
|
||||
expect(third!.id).toBe('main');
|
||||
});
|
||||
|
||||
it('link adds a depends_on edge', async () => {
|
||||
await svc.create({ id: 'a', title: 'a' });
|
||||
await svc.create({ id: 'b', title: 'b' });
|
||||
const linked = await svc.link('a', 'b');
|
||||
expect(linked.dependsOn).toEqual(['b']);
|
||||
// a is now gated on b
|
||||
const claimed = await svc.claim({ owner: 'w' });
|
||||
expect(claimed!.id).toBe('b');
|
||||
});
|
||||
});
|
||||
|
||||
describe('reclaim TTL', () => {
|
||||
it('reclaim returns expired claims to ready', async () => {
|
||||
await svc.create({ id: 'c1', title: 'c1' });
|
||||
const claimed = await svc.claim({ owner: 'w', ttlSeconds: 60 });
|
||||
expect(claimed!.status).toBe('claimed');
|
||||
|
||||
// Backdate the claim so it is well past its TTL.
|
||||
await handle.db.execute(sqlBackdate('c1'));
|
||||
|
||||
const result = await svc.reclaim();
|
||||
expect(result.reclaimed).toEqual(['c1']);
|
||||
const card = await svc.get('c1');
|
||||
expect(card!.status).toBe('ready');
|
||||
expect(card!.claimOwner).toBeNull();
|
||||
expect(card!.claimedAt).toBeNull();
|
||||
});
|
||||
|
||||
it('reclaim does not touch a fresh (unexpired) claim', async () => {
|
||||
await svc.create({ id: 'c1', title: 'c1' });
|
||||
await svc.claim({ owner: 'w', ttlSeconds: 3600 });
|
||||
const result = await svc.reclaim();
|
||||
expect(result.reclaimed).toEqual([]);
|
||||
expect((await svc.get('c1'))!.status).toBe('claimed');
|
||||
});
|
||||
|
||||
it('reclaim --id releases a specific claim regardless of expiry', async () => {
|
||||
await svc.create({ id: 'c1', title: 'c1' });
|
||||
await svc.claim({ owner: 'w', ttlSeconds: 3600 });
|
||||
const result = await svc.reclaim({ id: 'c1' });
|
||||
expect(result.reclaimed).toEqual(['c1']);
|
||||
expect((await svc.get('c1'))!.status).toBe('ready');
|
||||
});
|
||||
});
|
||||
|
||||
describe('stats', () => {
|
||||
it('computes counts, oldest-ready age, and expired-claim count', async () => {
|
||||
await svc.create({ id: 'r1', title: 'r1' });
|
||||
await svc.create({ id: 'r2', title: 'r2' });
|
||||
await svc.create({ id: 'b1', title: 'b1' });
|
||||
await svc.block('b1');
|
||||
await svc.create({ id: 'd1', title: 'd1' });
|
||||
await svc.complete('d1');
|
||||
await svc.create({ id: 'cl1', title: 'cl1' });
|
||||
await svc.claim({ owner: 'w', id: 'cl1', ttlSeconds: 60 });
|
||||
await handle.db.execute(sqlBackdate('cl1'));
|
||||
|
||||
const stats = await svc.stats();
|
||||
expect(stats.counts.ready).toBe(2);
|
||||
expect(stats.counts.blocked).toBe(1);
|
||||
expect(stats.counts.done).toBe(1);
|
||||
expect(stats.counts.claimed).toBe(1);
|
||||
expect(stats.total).toBe(5);
|
||||
expect(stats.expiredClaimCount).toBe(1);
|
||||
expect(stats.oldestReadyAgeSeconds).not.toBeNull();
|
||||
expect(stats.oldestReadyAgeSeconds!).toBeGreaterThanOrEqual(0);
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -1,457 +0,0 @@
|
||||
/**
|
||||
* Mosaic-native backlog-of-record service (card A4).
|
||||
*
|
||||
* This is the backlog Mosaic owns end-to-end on its OWN Postgres storage layer.
|
||||
* It REPLACES the former Hermes adapter — there is NO runtime dependency on
|
||||
* Hermes here or anywhere downstream.
|
||||
*
|
||||
* The service takes a `Db` handle, so it works identically against:
|
||||
* - `createDb()` — server Postgres (DATABASE_URL / config), and
|
||||
* - `createPgliteDb()` — embedded Postgres (file or in-memory).
|
||||
* Same code, same semantics — PGlite gives real Postgres behaviour (including
|
||||
* row locks), so the atomic-claim path is exercised by the in-memory tests.
|
||||
*
|
||||
* Atomic claim: `claim()` selects the highest-priority, deps-satisfied, ready
|
||||
* card with `SELECT ... FOR UPDATE SKIP LOCKED` and flips it to `claimed` inside
|
||||
* one transaction. Two concurrent claimers can therefore NEVER both win the same
|
||||
* card — the loser's locked row is skipped and it picks the next candidate (or
|
||||
* gets null).
|
||||
*/
|
||||
|
||||
import { and, asc, desc, eq, sql } from 'drizzle-orm';
|
||||
import type { Db } from './client.js';
|
||||
import { backlog } from './schema.js';
|
||||
|
||||
export type BacklogStatus = 'ready' | 'claimed' | 'blocked' | 'done';
|
||||
|
||||
export interface BacklogCard {
|
||||
id: string;
|
||||
title: string;
|
||||
body: string | null;
|
||||
phase: string | null;
|
||||
priority: number;
|
||||
status: BacklogStatus;
|
||||
dependsOn: string[];
|
||||
claimOwner: string | null;
|
||||
claimTtlSeconds: number | null;
|
||||
claimedAt: Date | null;
|
||||
attempts: number;
|
||||
idempotencyKey: string | null;
|
||||
acceptance: unknown;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
export interface CreateCardInput {
|
||||
id: string;
|
||||
title: string;
|
||||
body?: string | null;
|
||||
phase?: string | null;
|
||||
priority?: number;
|
||||
dependsOn?: string[];
|
||||
acceptance?: unknown;
|
||||
idempotencyKey?: string | null;
|
||||
status?: BacklogStatus;
|
||||
}
|
||||
|
||||
export interface ListFilter {
|
||||
status?: BacklogStatus;
|
||||
phase?: string;
|
||||
/** When true, return only cards that are `ready` AND have all deps `done`. */
|
||||
readyOnly?: boolean;
|
||||
}
|
||||
|
||||
export interface ClaimOptions {
|
||||
owner: string;
|
||||
/** Claim time-to-live in seconds (default 900). */
|
||||
ttlSeconds?: number;
|
||||
/** Claim a specific card by id instead of the highest-priority ready one. */
|
||||
id?: string;
|
||||
}
|
||||
|
||||
export interface ReclaimResult {
|
||||
reclaimed: string[];
|
||||
}
|
||||
|
||||
export interface BacklogStats {
|
||||
counts: Record<BacklogStatus, number>;
|
||||
total: number;
|
||||
oldestReadyAgeSeconds: number | null;
|
||||
expiredClaimCount: number;
|
||||
}
|
||||
|
||||
export const DEFAULT_CLAIM_TTL_SECONDS = 900;
|
||||
|
||||
type Row = typeof backlog.$inferSelect;
|
||||
|
||||
/**
|
||||
* Row shape as returned by the raw `SELECT * ... FOR UPDATE SKIP LOCKED` path.
|
||||
* That path bypasses drizzle's column-name mapping, so JSON columns arrive as
|
||||
* the snake_case `depends_on` (and may be a JSON string under some drivers).
|
||||
*/
|
||||
interface RawRow extends Row {
|
||||
depends_on?: unknown;
|
||||
}
|
||||
|
||||
function toCard(row: Row): BacklogCard {
|
||||
return {
|
||||
id: row.id,
|
||||
title: row.title,
|
||||
body: row.body,
|
||||
phase: row.phase,
|
||||
priority: row.priority,
|
||||
status: row.status,
|
||||
dependsOn: row.dependsOn ?? [],
|
||||
claimOwner: row.claimOwner,
|
||||
claimTtlSeconds: row.claimTtlSeconds,
|
||||
claimedAt: row.claimedAt,
|
||||
attempts: row.attempts,
|
||||
idempotencyKey: row.idempotencyKey,
|
||||
acceptance: row.acceptance,
|
||||
createdAt: row.createdAt,
|
||||
updatedAt: row.updatedAt,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The backlog repository/service. Construct with any `Db` handle.
|
||||
*/
|
||||
export class BacklogService {
|
||||
constructor(private readonly db: Db) {}
|
||||
|
||||
/**
|
||||
* Create a card. If `idempotencyKey` is provided and a card already exists
|
||||
* with that key, the existing card is returned unchanged (no duplicate).
|
||||
*/
|
||||
async create(input: CreateCardInput): Promise<BacklogCard> {
|
||||
if (input.idempotencyKey) {
|
||||
const existing = await this.db
|
||||
.select()
|
||||
.from(backlog)
|
||||
.where(eq(backlog.idempotencyKey, input.idempotencyKey))
|
||||
.limit(1);
|
||||
if (existing[0]) return toCard(existing[0]);
|
||||
}
|
||||
|
||||
const inserted = await this.db
|
||||
.insert(backlog)
|
||||
.values({
|
||||
id: input.id,
|
||||
title: input.title,
|
||||
body: input.body ?? null,
|
||||
phase: input.phase ?? null,
|
||||
priority: input.priority ?? 0,
|
||||
status: input.status ?? 'ready',
|
||||
dependsOn: input.dependsOn ?? [],
|
||||
acceptance: input.acceptance ?? null,
|
||||
idempotencyKey: input.idempotencyKey ?? null,
|
||||
})
|
||||
.returning();
|
||||
|
||||
return toCard(inserted[0]!);
|
||||
}
|
||||
|
||||
/** Fetch a single card by id, or null. */
|
||||
async get(id: string): Promise<BacklogCard | null> {
|
||||
const rows = await this.db.select().from(backlog).where(eq(backlog.id, id)).limit(1);
|
||||
return rows[0] ? toCard(rows[0]) : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* List cards with optional filters. `readyOnly` enforces the DAG gate:
|
||||
* a card is "ready" only when its own status is `ready` AND every card in
|
||||
* `depends_on` exists and is `done`.
|
||||
*/
|
||||
async list(filter: ListFilter = {}): Promise<BacklogCard[]> {
|
||||
const conditions = [];
|
||||
if (filter.status) conditions.push(eq(backlog.status, filter.status));
|
||||
if (filter.phase) conditions.push(eq(backlog.phase, filter.phase));
|
||||
|
||||
const rows = await this.db
|
||||
.select()
|
||||
.from(backlog)
|
||||
.where(conditions.length ? and(...conditions) : undefined)
|
||||
.orderBy(desc(backlog.priority), asc(backlog.createdAt));
|
||||
|
||||
const cards = rows.map(toCard);
|
||||
if (!filter.readyOnly) return cards;
|
||||
|
||||
const doneIds = await this.doneIdSet();
|
||||
return cards.filter(
|
||||
(c) => c.status === 'ready' && c.dependsOn.every((dep) => doneIds.has(dep)),
|
||||
);
|
||||
}
|
||||
|
||||
private async doneIdSet(): Promise<Set<string>> {
|
||||
const done = await this.db
|
||||
.select({ id: backlog.id })
|
||||
.from(backlog)
|
||||
.where(eq(backlog.status, 'done'));
|
||||
return new Set(done.map((d) => d.id));
|
||||
}
|
||||
|
||||
/**
|
||||
* Atomically claim a card.
|
||||
*
|
||||
* Strategy: inside ONE transaction we lock the candidate row with
|
||||
* `FOR UPDATE SKIP LOCKED LIMIT 1`. A concurrent claimer that already holds
|
||||
* the lock on a row has that row skipped for us, so two claimers can never
|
||||
* both win the same card — and, crucially, each claimer locks exactly ONE
|
||||
* row, so concurrent claimers fan out across distinct ready cards instead of
|
||||
* one claimer locking the whole ready set and starving the rest.
|
||||
*
|
||||
* Candidate selection (when no explicit `id`):
|
||||
* - status = 'ready'
|
||||
* - all deps satisfied (every id in depends_on is currently 'done')
|
||||
* - ordered by priority DESC, created_at ASC
|
||||
*
|
||||
* Returns the claimed card, or null if nothing is claimable.
|
||||
*/
|
||||
async claim(opts: ClaimOptions): Promise<BacklogCard | null> {
|
||||
const ttl = opts.ttlSeconds ?? DEFAULT_CLAIM_TTL_SECONDS;
|
||||
|
||||
return this.db.transaction(async (tx) => {
|
||||
// Specific-id path: lock that one ready row (if free) and apply the
|
||||
// deps-satisfied gate in JS, exactly as before.
|
||||
if (opts.id) {
|
||||
const doneRows = await tx
|
||||
.select({ id: backlog.id })
|
||||
.from(backlog)
|
||||
.where(eq(backlog.status, 'done'));
|
||||
const doneIds = new Set(doneRows.map((r) => r.id));
|
||||
|
||||
const result = await tx.execute(
|
||||
sql`SELECT * FROM ${backlog}
|
||||
WHERE ${backlog.id} = ${opts.id} AND ${backlog.status} = 'ready'
|
||||
FOR UPDATE SKIP LOCKED`,
|
||||
);
|
||||
const candidate = rowsOf(result).find((row) =>
|
||||
normalizeDeps(row.depends_on).every((dep) => doneIds.has(dep)),
|
||||
);
|
||||
if (!candidate) return null;
|
||||
|
||||
const updated = await tx
|
||||
.update(backlog)
|
||||
.set({
|
||||
status: 'claimed',
|
||||
claimOwner: opts.owner,
|
||||
claimTtlSeconds: ttl,
|
||||
claimedAt: new Date(),
|
||||
attempts: sql`${backlog.attempts} + 1`,
|
||||
updatedAt: new Date(),
|
||||
})
|
||||
.where(eq(backlog.id, candidate.id))
|
||||
.returning();
|
||||
|
||||
return toCard(updated[0]!);
|
||||
}
|
||||
|
||||
// No-id path: claim the single highest-priority, deps-satisfied ready
|
||||
// card. We lock exactly ONE row in the inner SELECT (`FOR UPDATE SKIP
|
||||
// LOCKED LIMIT 1`) so concurrent claimers grab distinct cards rather than
|
||||
// one claimer locking every ready row and forcing the others to null.
|
||||
//
|
||||
// The deps-satisfied gate is pushed into SQL so `LIMIT 1` lands on the
|
||||
// next genuinely-eligible card: a card is eligible iff none of its
|
||||
// depends_on ids is absent from the set of 'done' card ids.
|
||||
const updated = await tx.execute(
|
||||
sql`UPDATE ${backlog}
|
||||
SET status = 'claimed',
|
||||
claim_owner = ${opts.owner},
|
||||
claim_ttl_seconds = ${ttl},
|
||||
claimed_at = now(),
|
||||
attempts = ${backlog.attempts} + 1,
|
||||
updated_at = now()
|
||||
WHERE ${backlog.id} = (
|
||||
SELECT b.id FROM ${backlog} AS b
|
||||
WHERE b.status = 'ready'
|
||||
AND NOT EXISTS (
|
||||
SELECT 1
|
||||
FROM jsonb_array_elements_text(b.depends_on) AS dep
|
||||
WHERE dep NOT IN (
|
||||
SELECT d.id FROM ${backlog} AS d WHERE d.status = 'done'
|
||||
)
|
||||
)
|
||||
ORDER BY b.priority DESC, b.created_at ASC
|
||||
FOR UPDATE SKIP LOCKED
|
||||
LIMIT 1
|
||||
)
|
||||
RETURNING *`,
|
||||
);
|
||||
|
||||
const row = rowsOf(updated)[0];
|
||||
return row ? toCard(rawToRow(row)) : null;
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Release expired claims (claimed_at + ttl < now) back to `ready`, OR release
|
||||
* a specific card by id regardless of expiry. Cleared claim fields.
|
||||
* Returns the ids that were released.
|
||||
*/
|
||||
async reclaim(opts: { id?: string } = {}): Promise<ReclaimResult> {
|
||||
if (opts.id) {
|
||||
const released = await this.db
|
||||
.update(backlog)
|
||||
.set({
|
||||
status: 'ready',
|
||||
claimOwner: null,
|
||||
claimTtlSeconds: null,
|
||||
claimedAt: null,
|
||||
updatedAt: new Date(),
|
||||
})
|
||||
.where(and(eq(backlog.id, opts.id), eq(backlog.status, 'claimed')))
|
||||
.returning({ id: backlog.id });
|
||||
return { reclaimed: released.map((r) => r.id) };
|
||||
}
|
||||
|
||||
// Expired = status claimed AND claimed_at + (ttl seconds) < now().
|
||||
const released = await this.db
|
||||
.update(backlog)
|
||||
.set({
|
||||
status: 'ready',
|
||||
claimOwner: null,
|
||||
claimTtlSeconds: null,
|
||||
claimedAt: null,
|
||||
updatedAt: new Date(),
|
||||
})
|
||||
.where(
|
||||
and(
|
||||
eq(backlog.status, 'claimed'),
|
||||
sql`${backlog.claimedAt} + make_interval(secs => ${backlog.claimTtlSeconds}) < now()`,
|
||||
),
|
||||
)
|
||||
.returning({ id: backlog.id });
|
||||
return { reclaimed: released.map((r) => r.id) };
|
||||
}
|
||||
|
||||
/** Add a `depends_on` edge (from → depends on → to). Idempotent. */
|
||||
async link(from: string, to: string): Promise<BacklogCard> {
|
||||
const card = await this.get(from);
|
||||
if (!card) throw new Error(`backlog card not found: ${from}`);
|
||||
const target = await this.get(to);
|
||||
if (!target) throw new Error(`backlog dependency not found: ${to}`);
|
||||
if (from === to) throw new Error('a card cannot depend on itself');
|
||||
|
||||
if (card.dependsOn.includes(to)) return card;
|
||||
const nextDeps = [...card.dependsOn, to];
|
||||
const updated = await this.db
|
||||
.update(backlog)
|
||||
.set({ dependsOn: nextDeps, updatedAt: new Date() })
|
||||
.where(eq(backlog.id, from))
|
||||
.returning();
|
||||
return toCard(updated[0]!);
|
||||
}
|
||||
|
||||
/** Mark a card blocked. */
|
||||
async block(id: string): Promise<BacklogCard | null> {
|
||||
return this.setStatus(id, 'blocked');
|
||||
}
|
||||
|
||||
/** Mark a card done (releasing any claim). */
|
||||
async complete(id: string): Promise<BacklogCard | null> {
|
||||
const updated = await this.db
|
||||
.update(backlog)
|
||||
.set({
|
||||
status: 'done',
|
||||
claimOwner: null,
|
||||
claimTtlSeconds: null,
|
||||
claimedAt: null,
|
||||
updatedAt: new Date(),
|
||||
})
|
||||
.where(eq(backlog.id, id))
|
||||
.returning();
|
||||
return updated[0] ? toCard(updated[0]) : null;
|
||||
}
|
||||
|
||||
private async setStatus(id: string, status: BacklogStatus): Promise<BacklogCard | null> {
|
||||
const updated = await this.db
|
||||
.update(backlog)
|
||||
.set({ status, updatedAt: new Date() })
|
||||
.where(eq(backlog.id, id))
|
||||
.returning();
|
||||
return updated[0] ? toCard(updated[0]) : null;
|
||||
}
|
||||
|
||||
/** Counts by status, oldest-ready age (seconds), and expired-claim count. */
|
||||
async stats(): Promise<BacklogStats> {
|
||||
const all = await this.db.select().from(backlog);
|
||||
const counts: Record<BacklogStatus, number> = {
|
||||
ready: 0,
|
||||
claimed: 0,
|
||||
blocked: 0,
|
||||
done: 0,
|
||||
};
|
||||
let oldestReady: Date | null = null;
|
||||
let expiredClaimCount = 0;
|
||||
const now = Date.now();
|
||||
|
||||
for (const row of all) {
|
||||
counts[row.status] += 1;
|
||||
if (row.status === 'ready') {
|
||||
if (oldestReady === null || row.createdAt < oldestReady) oldestReady = row.createdAt;
|
||||
}
|
||||
if (row.status === 'claimed' && row.claimedAt && row.claimTtlSeconds != null) {
|
||||
const expiry = row.claimedAt.getTime() + row.claimTtlSeconds * 1000;
|
||||
if (expiry < now) expiredClaimCount += 1;
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
counts,
|
||||
total: all.length,
|
||||
oldestReadyAgeSeconds:
|
||||
oldestReady === null ? null : Math.max(0, Math.floor((now - oldestReady.getTime()) / 1000)),
|
||||
expiredClaimCount,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
/** Extract rows from a drizzle `.execute()` result across drivers (pg / pglite). */
|
||||
function rowsOf(result: unknown): RawRow[] {
|
||||
if (Array.isArray(result)) return result as RawRow[];
|
||||
const maybe = result as { rows?: unknown };
|
||||
if (maybe && Array.isArray(maybe.rows)) return maybe.rows as RawRow[];
|
||||
return [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Map a raw `RETURNING *` row (snake_case columns, possibly string-encoded
|
||||
* timestamps/JSON depending on the driver) onto the drizzle `Row` shape that
|
||||
* `toCard` consumes. Mirrors the column ↔ property mapping in `schema.ts`.
|
||||
*/
|
||||
function rawToRow(raw: RawRow): Row {
|
||||
const r = raw as unknown as Record<string, unknown>;
|
||||
const toDate = (v: unknown): Date => (v instanceof Date ? v : new Date(v as string));
|
||||
return {
|
||||
id: r.id as string,
|
||||
title: r.title as string,
|
||||
body: (r.body ?? null) as string | null,
|
||||
phase: (r.phase ?? null) as string | null,
|
||||
priority: Number(r.priority),
|
||||
status: r.status as BacklogStatus,
|
||||
dependsOn: normalizeDeps(r.depends_on),
|
||||
claimOwner: (r.claim_owner ?? null) as string | null,
|
||||
claimTtlSeconds: r.claim_ttl_seconds == null ? null : Number(r.claim_ttl_seconds),
|
||||
claimedAt: r.claimed_at == null ? null : toDate(r.claimed_at),
|
||||
attempts: Number(r.attempts),
|
||||
idempotencyKey: (r.idempotency_key ?? null) as string | null,
|
||||
acceptance: r.acceptance ?? null,
|
||||
createdAt: toDate(r.created_at),
|
||||
updatedAt: toDate(r.updated_at),
|
||||
};
|
||||
}
|
||||
|
||||
/** A raw SQL row returns snake_case `depends_on`; normalize to string[]. */
|
||||
function normalizeDeps(value: unknown): string[] {
|
||||
if (Array.isArray(value)) return value as string[];
|
||||
if (typeof value === 'string') {
|
||||
try {
|
||||
const parsed = JSON.parse(value);
|
||||
return Array.isArray(parsed) ? (parsed as string[]) : [];
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
return [];
|
||||
}
|
||||
@@ -3,17 +3,6 @@ export { createPgliteDb } from './client-pglite.js';
|
||||
export { runMigrations, runPgliteMigrations } from './migrate.js';
|
||||
export * from './schema.js';
|
||||
export * from './federation.js';
|
||||
export {
|
||||
BacklogService,
|
||||
DEFAULT_CLAIM_TTL_SECONDS,
|
||||
type BacklogCard,
|
||||
type BacklogStatus,
|
||||
type BacklogStats,
|
||||
type ClaimOptions,
|
||||
type CreateCardInput,
|
||||
type ListFilter,
|
||||
type ReclaimResult,
|
||||
} from './backlog.js';
|
||||
export {
|
||||
eq,
|
||||
and,
|
||||
|
||||
@@ -587,62 +587,6 @@ export const summarizationJobs = pgTable(
|
||||
(t) => [index('summarization_jobs_status_idx').on(t.status)],
|
||||
);
|
||||
|
||||
// ─── Fleet Backlog ────────────────────────────────────────────────────────────
|
||||
// Mosaic-native backlog-of-record (card A4). This REPLACES the former Hermes
|
||||
// adapter — there is NO runtime dependency on Hermes. Cards form a dependency
|
||||
// DAG (`depends_on`), are claimed atomically by fleet workers via
|
||||
// `SELECT ... FOR UPDATE SKIP LOCKED`, and auto-expire via a TTL so a crashed
|
||||
// claimer's card returns to the pool.
|
||||
|
||||
/**
|
||||
* Lifecycle status of a backlog card.
|
||||
* - ready: eligible to be claimed (once its deps are all `done`).
|
||||
* - claimed: a worker holds it (claim_owner + claimed_at set); may expire via TTL.
|
||||
* - blocked: explicitly parked; never auto-claimed.
|
||||
* - done: completed; satisfies dependents.
|
||||
*/
|
||||
export const backlogStatusEnum = pgEnum('backlog_status', ['ready', 'claimed', 'blocked', 'done']);
|
||||
|
||||
export const backlog = pgTable(
|
||||
'backlog',
|
||||
{
|
||||
/** Stable, caller-supplied card id (e.g. "A4", "fleet-001"). PK. */
|
||||
id: text('id').primaryKey(),
|
||||
title: text('title').notNull(),
|
||||
body: text('body'),
|
||||
/** Board/phase grouping (e.g. "M1", "fleet"). Free-form. */
|
||||
phase: text('phase'),
|
||||
/** Higher number = higher priority; claim picks the max-priority ready card. */
|
||||
priority: integer('priority').notNull().default(0),
|
||||
status: backlogStatusEnum('status').notNull().default('ready'),
|
||||
/** DAG edges: ids of cards this one depends on. "ready" requires all done. */
|
||||
dependsOn: jsonb('depends_on').notNull().$type<string[]>().default([]),
|
||||
/** Owner token of the current claim (worker/agent id). NULL when unclaimed. */
|
||||
claimOwner: text('claim_owner'),
|
||||
/** TTL of the active claim in seconds. NULL when unclaimed. */
|
||||
claimTtlSeconds: integer('claim_ttl_seconds'),
|
||||
/** When the active claim was taken. NULL when unclaimed. claimed_at + ttl = expiry. */
|
||||
claimedAt: timestamp('claimed_at', { withTimezone: true }),
|
||||
/** Count of times this card has been claimed (incremented on each claim). */
|
||||
attempts: integer('attempts').notNull().default(0),
|
||||
/** Optional dedup key for `create`; a repeat key returns the existing card. */
|
||||
idempotencyKey: text('idempotency_key'),
|
||||
/** Acceptance criteria — free-form JSON (array of strings or object). */
|
||||
acceptance: jsonb('acceptance'),
|
||||
createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
|
||||
updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
|
||||
},
|
||||
(t) => [
|
||||
// Hot path: claim scans ready cards ordered by priority then age.
|
||||
index('backlog_status_priority_idx').on(t.status, t.priority),
|
||||
// reclaim sweeps claimed cards by claimed_at to find expired ones.
|
||||
index('backlog_status_claimed_at_idx').on(t.status, t.claimedAt),
|
||||
// Idempotent create dedups on this key (NULLs are distinct in Postgres, so
|
||||
// many unkeyed cards coexist; a repeated non-null key collides).
|
||||
uniqueIndex('backlog_idempotency_key_idx').on(t.idempotencyKey),
|
||||
],
|
||||
);
|
||||
|
||||
// ─── Federation ──────────────────────────────────────────────────────────────
|
||||
// Enums declared before tables that reference them.
|
||||
// All federation definitions live in this file (avoids CJS/ESM cross-import
|
||||
|
||||
@@ -10,8 +10,3 @@ export {
|
||||
type LogQuery,
|
||||
} from './agent-logs.js';
|
||||
export { registerLogCommand } from './cli.js';
|
||||
export {
|
||||
redactSensitiveContent,
|
||||
type RedactionResult,
|
||||
type SensitiveClassification,
|
||||
} from './redaction.js';
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { redactSensitiveContent } from './redaction.js';
|
||||
|
||||
describe('redactSensitiveContent', (): void => {
|
||||
it('redacts seeded secret and PII canaries before persistence or egress', (): void => {
|
||||
const result = redactSensitiveContent(
|
||||
'email canary@example.test token=sk_CANARY12345678 phone +1 555 555 1212',
|
||||
);
|
||||
expect(result.content).not.toContain('canary@example.test');
|
||||
expect(result.content).not.toContain('sk_CANARY12345678');
|
||||
expect(result.content).not.toContain('+1 555 555 1212');
|
||||
expect(result.classifications).toEqual(['secret', 'pii']);
|
||||
});
|
||||
|
||||
it('redacts common provider credential formats', (): void => {
|
||||
const result = redactSensitiveContent(
|
||||
'Authorization: Bearer canary.bearer.token jwt eyJcanary.eyJpayload.eyJsignature aws AKIACANARY1234567890',
|
||||
);
|
||||
|
||||
expect(result.content).not.toContain('canary.bearer.token');
|
||||
expect(result.content).not.toContain('eyJcanary.eyJpayload.eyJsignature');
|
||||
expect(result.content).not.toContain('AKIACANARY1234567890');
|
||||
expect(result.classifications).toEqual(['secret']);
|
||||
});
|
||||
});
|
||||
@@ -1,40 +0,0 @@
|
||||
export type SensitiveClassification = 'secret' | 'pii';
|
||||
|
||||
export interface RedactionResult {
|
||||
content: string;
|
||||
classifications: SensitiveClassification[];
|
||||
}
|
||||
|
||||
const SECRET_PATTERNS: RegExp[] = [
|
||||
/\b(?:sk|ghp|gitea)_[A-Za-z0-9_-]{8,}\b/g,
|
||||
/\b(?:api[_-]?key|token|password|secret)\s*[:=]\s*[^\s,;]+/gi,
|
||||
/\b(?:authorization\s*:\s*)?bearer\s+[A-Za-z0-9._~+/-]+=*/gi,
|
||||
/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
|
||||
/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
|
||||
/-----BEGIN(?: [A-Z]+)* KEY-----[\s\S]*?-----END(?: [A-Z]+)* KEY-----/g,
|
||||
/https?:\/\/[^\s?#]+[^\s]*[?&](?:token|key|secret|signature|sig)=[^\s&#]+/gi,
|
||||
];
|
||||
const PII_PATTERNS: RegExp[] = [
|
||||
/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi,
|
||||
/\b\+?\d[\d(). -]{7,}\d\b/g,
|
||||
];
|
||||
|
||||
export function redactSensitiveContent(content: string): RedactionResult {
|
||||
let redacted = content;
|
||||
const classifications: SensitiveClassification[] = [];
|
||||
for (const pattern of SECRET_PATTERNS) {
|
||||
if (pattern.test(redacted)) {
|
||||
classifications.push('secret');
|
||||
redacted = redacted.replace(pattern, '[REDACTED_SECRET]');
|
||||
}
|
||||
pattern.lastIndex = 0;
|
||||
}
|
||||
for (const pattern of PII_PATTERNS) {
|
||||
if (pattern.test(redacted)) {
|
||||
classifications.push('pii');
|
||||
redacted = redacted.replace(pattern, '[REDACTED_PII]');
|
||||
}
|
||||
pattern.lastIndex = 0;
|
||||
}
|
||||
return { content: redacted, classifications: [...new Set(classifications)] };
|
||||
}
|
||||
@@ -1,30 +0,0 @@
|
||||
id: business
|
||||
title: Business (Company-in-a-Box)
|
||||
description: >-
|
||||
A full company org: the CEO sets direction, the COO and CFO run execution and
|
||||
finance, and the functional leads (product, marketing, sales, operations,
|
||||
customer success) plus a small engineering slice deliver the work. reports_to
|
||||
encodes the org chart.
|
||||
lead: ceo
|
||||
floor:
|
||||
- ceo
|
||||
roster:
|
||||
- class: ceo
|
||||
- class: coo
|
||||
reports_to: ceo
|
||||
- class: cfo
|
||||
reports_to: ceo
|
||||
- class: product-manager
|
||||
reports_to: coo
|
||||
- class: marketing-lead
|
||||
reports_to: coo
|
||||
- class: sales-lead
|
||||
reports_to: coo
|
||||
- class: operations-manager
|
||||
reports_to: coo
|
||||
- class: customer-success-manager
|
||||
reports_to: coo
|
||||
- class: code
|
||||
reports_to: product-manager
|
||||
- class: review
|
||||
reports_to: product-manager
|
||||
@@ -1,25 +0,0 @@
|
||||
id: marketing
|
||||
title: Marketing
|
||||
description: >-
|
||||
A marketing org that owns strategy, content, channels, and growth. The
|
||||
marketing-lead sets strategy and budget and runs a roster of content, copy,
|
||||
SEO, social, brand, growth, and UX specialists.
|
||||
lead: marketing-lead
|
||||
floor:
|
||||
- marketing-lead
|
||||
roster:
|
||||
- class: marketing-lead
|
||||
- class: content-strategist
|
||||
reports_to: marketing-lead
|
||||
- class: copywriter
|
||||
reports_to: content-strategist
|
||||
- class: seo-specialist
|
||||
reports_to: marketing-lead
|
||||
- class: social-media-manager
|
||||
reports_to: content-strategist
|
||||
- class: brand-strategist
|
||||
reports_to: marketing-lead
|
||||
- class: growth-marketer
|
||||
reports_to: marketing-lead
|
||||
- class: ux-designer
|
||||
reports_to: marketing-lead
|
||||
@@ -1,19 +0,0 @@
|
||||
id: personal-assistant
|
||||
title: Personal Assistant
|
||||
description: >-
|
||||
A personal-logistics fleet for one principal: handles errands, reminders,
|
||||
calendar, inbox triage, and ad-hoc lookups. The personal-assistant leads and
|
||||
delegates scheduling, inbox triage, and research to specialist seats.
|
||||
lead: personal-assistant
|
||||
floor:
|
||||
- personal-assistant
|
||||
roster:
|
||||
- class: personal-assistant
|
||||
- class: executive-assistant
|
||||
reports_to: personal-assistant
|
||||
- class: scheduler
|
||||
reports_to: executive-assistant
|
||||
- class: inbox-manager
|
||||
reports_to: personal-assistant
|
||||
- class: researcher
|
||||
reports_to: personal-assistant
|
||||
@@ -1,24 +0,0 @@
|
||||
id: research
|
||||
title: Research
|
||||
description: >-
|
||||
A research fleet that decomposes a question, gathers and analyzes evidence, and
|
||||
synthesizes cited findings. The lead-researcher owns the agenda and assigns
|
||||
individual questions to researchers and the analytics seats.
|
||||
lead: lead-researcher
|
||||
floor:
|
||||
- lead-researcher
|
||||
roster:
|
||||
- class: lead-researcher
|
||||
- class: researcher
|
||||
reports_to: lead-researcher
|
||||
multiplicity: 2
|
||||
- class: data-analyst
|
||||
reports_to: lead-researcher
|
||||
- class: data-scientist
|
||||
reports_to: lead-researcher
|
||||
- class: market-analyst
|
||||
reports_to: lead-researcher
|
||||
- class: documentation
|
||||
reports_to: lead-researcher
|
||||
- class: review
|
||||
reports_to: lead-researcher
|
||||
@@ -1,75 +0,0 @@
|
||||
# Mosaic system-type profile — SCHEMA REFERENCE
|
||||
# ---------------------------------------------------------------------------
|
||||
# A profile is a DECLARATIVE mapping from a "system type" to a persona roster
|
||||
# plus its org topology. Profiles are DATA: drop a new <id>.yaml here and the
|
||||
# loader/CLI pick it up with no code change (North Star NS-9 / AC-NS-6).
|
||||
#
|
||||
# Every persona referenced below (lead, floor[], roster[].class, roster[].reports_to)
|
||||
# MUST resolve to a real persona in the library. The loader validates this against
|
||||
# the role contracts in ../roles/*.md (see LIBRARY.md for the grouped index).
|
||||
#
|
||||
# Schema (this file documents every key; other profiles omit the comments):
|
||||
#
|
||||
# id: kebab-case system-type id — MUST equal the filename stem.
|
||||
# title: human-readable name.
|
||||
# description: one paragraph — what this system does.
|
||||
# lead: persona class that coordinates the roster (the orchestrating seat).
|
||||
# floor: persistent minimum roster that must stay staffed (list of classes).
|
||||
# roster: the full default roster. Each entry:
|
||||
# - class: persona class (MUST resolve to a role file).
|
||||
# reports_to: optional — the class this seat reports to
|
||||
# (encodes org topology). Omit for the lead.
|
||||
# MUST resolve to a class present in this roster.
|
||||
# multiplicity: optional int (default 1) — e.g. 2 coders.
|
||||
# notes: optional free text.
|
||||
# ---------------------------------------------------------------------------
|
||||
id: software-delivery
|
||||
title: Software Delivery
|
||||
description: >-
|
||||
The engineering fleet that turns ratified objectives into shipped, reviewed,
|
||||
merged code. The lead (orchestrator) runs the supervisor loop and dispatches
|
||||
ready work; it hands goal-decomposition to the planner, which plans phased FRs
|
||||
into a depends_on DAG, decomposition splits them into one-PR-each cards, coders
|
||||
execute to green CI, and review / security-review / site-tester / merge-gate
|
||||
guard the merge. This mirrors today's coding fleet.
|
||||
# NOTE: the lead seat is the dedicated "orchestrator" — the always-on coordinator
|
||||
# that runs the supervisor tick, dispatches ready work, and routes PRs to the
|
||||
# merge-gate while holding only lean coordination state. The planner is now a
|
||||
# distinct seat (heavy goal-decomposition context) that reports to the
|
||||
# orchestrator. The two-agent floor is orchestrator + enhancer.
|
||||
lead: orchestrator
|
||||
floor:
|
||||
- orchestrator
|
||||
- enhancer
|
||||
roster:
|
||||
- class: orchestrator
|
||||
- class: board
|
||||
reports_to: orchestrator
|
||||
- class: planner
|
||||
reports_to: orchestrator
|
||||
- class: decomposition
|
||||
reports_to: planner
|
||||
- class: code
|
||||
reports_to: decomposition
|
||||
multiplicity: 2
|
||||
- class: review
|
||||
reports_to: orchestrator
|
||||
- class: security-review
|
||||
reports_to: review
|
||||
- class: site-tester
|
||||
reports_to: review
|
||||
- class: documentation
|
||||
reports_to: orchestrator
|
||||
- class: merge-gate
|
||||
reports_to: orchestrator
|
||||
- class: rebase
|
||||
reports_to: merge-gate
|
||||
- class: operator
|
||||
reports_to: orchestrator
|
||||
- class: session-review
|
||||
reports_to: orchestrator
|
||||
- class: enhancer
|
||||
reports_to: orchestrator
|
||||
notes: >-
|
||||
Two-agent floor (orchestrator + enhancer) is always staffed; every other seat is
|
||||
added on demand.
|
||||
@@ -1,119 +0,0 @@
|
||||
# Persona Library — fleet role index
|
||||
|
||||
This is the discoverable index of the fleet's **persona role library**. Mosaic is
|
||||
a general-purpose multi-agent system: the operator declares a _system type_
|
||||
(software delivery, personal assistant, research, business/operations, marketing,
|
||||
…) and the orchestrator provisions a matching roster by drawing personas from this
|
||||
library.
|
||||
|
||||
Each row points at a `*.md` role contract in this directory. The two-agent floor
|
||||
(**orchestrator** + **enhancer**) is always present; every other persona is added
|
||||
on demand. Engineering personas have no explicit `domain:` marker (they are the
|
||||
implicit `engineering` domain); cross-domain personas carry a `domain:` key in
|
||||
their intro so tooling can group them.
|
||||
|
||||
> This file is an index only — no code imports it. To add a persona, drop a new
|
||||
> `*.md` next to the others (mirroring the existing structure) and add a row here.
|
||||
|
||||
## engineering
|
||||
|
||||
| Persona | Purpose |
|
||||
| --------------- | ------------------------------------------------------------------------------ |
|
||||
| orchestrator | Always-on coordinator — runs the supervisor loop, dispatches ready work |
|
||||
| board | Multi-lens deliberation panel; owns the mission's direction, not its execution |
|
||||
| planner | Turns ratified objectives into a phased FR plan wired into a `depends_on` DAG |
|
||||
| decomposition | Splits FRs into one-PR-each cards wired with `depends_on` edges |
|
||||
| code | Primary executor — one card, one branch, one PR to green CI |
|
||||
| review | Correctness reviewer — judges an open PR on correctness, scope, and coverage |
|
||||
| security-review | Second line of review — secrets, auth, and forbidden-path safety |
|
||||
| site-tester | Runtime verifier — runs the change and checks behavior vs. acceptance criteria |
|
||||
| documentation | Prose maintainer — keeps human-facing docs and projections in sync |
|
||||
| merge-gate | Sole approver and auto-merger — the single chokepoint every PR passes through |
|
||||
| rebase | Freshness keeper — restores stale / unmergeable PR branches or escalates |
|
||||
| operator | Escalation and control surface — owns exceptions and the fleet pause switch |
|
||||
| session-review | Post-task retrospective — turns finished work into improvement signals |
|
||||
| enhancer | Continuous-improvement loop — upgrades the fleet's tools, skills, and harness |
|
||||
|
||||
## executive
|
||||
|
||||
| Persona | Purpose |
|
||||
| -------------- | ------------------------------------------------------------------------------ |
|
||||
| ceo | Direction-setter and final arbiter — owns the mission's _why_ and _whether_ |
|
||||
| coo | Runs execution and operations — turns strategy into a running machine |
|
||||
| cfo | Owns financial truth — budgets, runway, and unit economics |
|
||||
| cto | Owns technical strategy and architecture direction at the executive level |
|
||||
| chief-of-staff | Force-multiplier for the exec seat — drives priorities, unblocks, runs cadence |
|
||||
|
||||
## product
|
||||
|
||||
| Persona | Purpose |
|
||||
| --------------- | --------------------------------------------------------------------------- |
|
||||
| product-manager | Owns the roadmap and problem definition — decides _what_ to build and _why_ |
|
||||
| ux-designer | Owns interaction and flow design — the usability of the experience |
|
||||
| user-researcher | Owns generative and evaluative research — turns user evidence into insight |
|
||||
|
||||
## marketing
|
||||
|
||||
| Persona | Purpose |
|
||||
| -------------------- | ------------------------------------------------------------------------ |
|
||||
| marketing-lead | Owns marketing strategy, channel mix, and budget; runs the roster |
|
||||
| content-strategist | Owns the content plan, editorial calendar, and content-to-funnel mapping |
|
||||
| copywriter | Writes the actual copy — ads, landing pages, and emails |
|
||||
| seo-specialist | Owns organic search — keyword strategy, on-page/technical SEO, SERPs |
|
||||
| social-media-manager | Owns social presence, posting cadence, and community engagement |
|
||||
| brand-strategist | Owns brand positioning, voice, and identity guardrails |
|
||||
| growth-marketer | Owns funnel experiments — acquisition, activation, and retention loops |
|
||||
|
||||
## sales
|
||||
|
||||
| Persona | Purpose |
|
||||
| --------------------- | ----------------------------------------------------------- |
|
||||
| sales-lead | Owns sales strategy, pipeline targets, and the sales roster |
|
||||
| account-executive | Owns deals from qualified opportunity through to close |
|
||||
| sales-development-rep | Owns top-of-funnel qualification and booking meetings |
|
||||
|
||||
## operations
|
||||
|
||||
| Persona | Purpose |
|
||||
| ------------------ | ------------------------------------------------------------------------ |
|
||||
| operations-manager | Owns running processes, throughput, and operational SLAs day-to-day |
|
||||
| project-manager | Owns scope, schedule, and delivery of a defined project |
|
||||
| business-analyst | Owns requirements gathering, process mapping, and turning needs to specs |
|
||||
| hr-generalist | Owns people operations — onboarding, policy, and employee relations |
|
||||
| recruiter | Owns sourcing, screening, and filling open roles |
|
||||
| legal-counsel | Owns contracts, compliance, and legal-risk review |
|
||||
| finance-analyst | Owns financial modeling, reporting, and decision-support analysis |
|
||||
|
||||
## research
|
||||
|
||||
| Persona | Purpose |
|
||||
| --------------- | -------------------------------------------------------------------------- |
|
||||
| lead-researcher | Owns the research agenda — decomposes questions and synthesizes findings |
|
||||
| researcher | Executes a single research question — gathers, extracts, drafts findings |
|
||||
| data-analyst | Owns descriptive analysis, dashboards, and "what happened" from data |
|
||||
| data-scientist | Owns modeling, statistical inference, and predictive/experimental analysis |
|
||||
| market-analyst | Owns market sizing, competitive landscape, and trend analysis |
|
||||
|
||||
## assistant
|
||||
|
||||
| Persona | Purpose |
|
||||
| ------------------- | ------------------------------------------------------------------- |
|
||||
| personal-assistant | Owns the principal's personal logistics, reminders, and errands |
|
||||
| executive-assistant | Owns an executive's calendar, travel, meeting prep, and gatekeeping |
|
||||
| scheduler | Owns conflict-free meeting booking across multiple parties |
|
||||
| inbox-manager | Owns triage, drafting, and routing of incoming messages |
|
||||
|
||||
## customer
|
||||
|
||||
| Persona | Purpose |
|
||||
| ------------------------ | ---------------------------------------------------------------- |
|
||||
| customer-success-manager | Owns post-sale adoption, retention, and renewal for accounts |
|
||||
| support-agent | Owns resolving individual customer issues and tickets to closure |
|
||||
|
||||
## creative
|
||||
|
||||
| Persona | Purpose |
|
||||
| ---------------- | ----------------------------------------------------------------- |
|
||||
| graphic-designer | Owns visual assets — layouts and graphics executed to brand spec |
|
||||
| video-producer | Owns video from concept through shoot/assembly to delivery |
|
||||
| editor | Refines and polishes existing content for clarity and consistency |
|
||||
@@ -1,39 +0,0 @@
|
||||
# Account Executive — fleet role definition
|
||||
|
||||
The **account-executive** is the deal-level **closer and quota carrier**
|
||||
(`class: account-executive`, `domain: sales`). It owns each opportunity from the
|
||||
moment it is qualified to the moment it is won or lost, running the deal cycle
|
||||
the **sales-lead** designed the field for.
|
||||
|
||||
It is a **persistent** role (`persistent_persona: true`) but task-oriented in
|
||||
practice: the seat stays staffed against a quota, while its day-to-day work is
|
||||
the set of live deals it is driving at any moment.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Own deals to close** — take each qualified opportunity through discovery,
|
||||
proposal, negotiation, and signature, and own the outcome.
|
||||
2. **Carry and hit the quota** — manage a personal number, prioritize the deals
|
||||
most likely to land in-period, and report honest commit/best-case calls.
|
||||
3. **Run a clean pipeline** — keep stages, next steps, and close dates accurate
|
||||
so the rollup the **sales-lead** forecasts on is trustworthy.
|
||||
4. **Champion the customer internally** — surface real requirements and risks so
|
||||
the deal that closes is one the system can actually deliver.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT set strategy or quota** — territory, targets, and motion are the
|
||||
**sales-lead**'s call; the AE executes within them.
|
||||
- **Does NOT prospect cold top-of-funnel** — meeting generation and first-touch
|
||||
qualification are the **sales-development-rep**'s job; the AE picks up
|
||||
qualified handoffs.
|
||||
- **Does NOT redline contracts unilaterally** — non-standard terms and risk go
|
||||
to **legal-counsel** before commitment.
|
||||
|
||||
## Persona
|
||||
|
||||
A disciplined closer who lives in next-steps and mutual close plans. Its value
|
||||
is momentum without happy-ears: it qualifies hard, names blockers early, and
|
||||
never lets a stalled deal sit silently in the pipeline.
|
||||
|
||||
> Doctrine: cross-domain persona library (sales); see `LIBRARY.md`.
|
||||
@@ -1,38 +0,0 @@
|
||||
# Board — fleet role definition
|
||||
|
||||
The **board** is the fleet's **deliberation panel** (`class: board`). It is the
|
||||
forge **Board-of-Directors** reused as a fleet role — a multi-lens review body
|
||||
(moonshot, contrarian, technical, business, financial) that owns the mission's
|
||||
direction, not its execution.
|
||||
|
||||
It is a **front-office** role: it sets and guards intent, then steps back.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Own `NORTH_STAR.yaml`** — the single source of truth for goals, assumptions,
|
||||
and projections. The board is the only role that ratifies edits to it.
|
||||
2. **Ratify or veto goals and assumptions** — every new objective or load-bearing
|
||||
assumption passes the board's lenses before the fleet commits resources to it.
|
||||
3. **Hold the lenses** — moonshot (is the ambition right?), contrarian (what breaks
|
||||
this?), technical (is it buildable?), business (does it matter?), financial
|
||||
(can we afford it, in tokens and dollars?).
|
||||
4. **Re-deliberate on drift** — when results diverge from the north star, the board
|
||||
reconvenes, re-ratifies or vetoes, and updates `NORTH_STAR.yaml`.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT write product/source code.**
|
||||
- **Does NOT merge.**
|
||||
- **Does NOT decompose, plan phases, or dispatch tasks** — it ratifies the
|
||||
_what_ and _why_; planner and decomposition own the _how_.
|
||||
|
||||
The board deliberates and decides direction; it never touches the working tree or
|
||||
the merge path. When it approves a goal, the planner expands it.
|
||||
|
||||
## Persona
|
||||
|
||||
A standing panel of senior voices, each arguing from a fixed vantage. The board is
|
||||
deliberately slow and adversarial — its value is catching the expensive mistake
|
||||
before a single agent-hour is spent on it.
|
||||
|
||||
> Doctrine: `docs/fleet/north-star.md` ('board' role = forge BOD; role library).
|
||||
@@ -1,38 +0,0 @@
|
||||
# Brand Strategist — fleet role definition
|
||||
|
||||
The **brand-strategist** is the marketing system's **positioning and identity
|
||||
guardian** (`class: brand-strategist`, `domain: marketing`). It owns brand
|
||||
positioning, voice, and the visual and verbal identity guardrails — the rules
|
||||
that keep everything sounding and looking like one company, not their execution.
|
||||
|
||||
It is a **persistent** role (`persistent_persona: true`): brand is a long-lived
|
||||
asset that every other role draws on, so the seat stays staffed to keep the
|
||||
identity coherent across campaigns and channels.
|
||||
|
||||
## Mandate
|
||||
|
||||
1. **Own the positioning** — define who the brand is for, what it stands for,
|
||||
and how it is differentiated, in language the whole roster can apply.
|
||||
2. **Set the voice and tone** — establish the verbal identity and the rules for
|
||||
bending it per context, so copy across the system sounds unified.
|
||||
3. **Hold the visual and verbal guardrails** — maintain identity standards and
|
||||
review high-visibility work for consistency with them.
|
||||
4. **Protect the brand long-term** — flag drift, off-brand experiments, and
|
||||
short-term plays that would erode equity for a quick win.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- **Does NOT write production copy** — drafting is the **copywriter**'s craft;
|
||||
the strategist sets the voice the copy must honor.
|
||||
- **Does NOT plan the content calendar** — that is the **content-strategist**'s;
|
||||
brand supplies the identity those plans must express.
|
||||
- **Does NOT chase conversion metrics** — funnel optimization is the
|
||||
**growth-marketer**'s; brand optimizes for consistency and long-term equity.
|
||||
|
||||
## Persona
|
||||
|
||||
A steward of meaning who thinks in decades, not quarters. Its value is coherence:
|
||||
ensuring every touchpoint reinforces the same promise, and resisting the
|
||||
expedient choices that blur what the brand is supposed to stand for.
|
||||
|
||||
> Doctrine: cross-domain persona library (marketing); see `LIBRARY.md`.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user