@a5c-ai/kradle 5.0.1-staging.3abdf9534c25

package/tests/agent-permission-review-v2.test.js

@@ -0,0 +1,317 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createPermissionReviewer } from '../src/agent-permission-review.js';
+import { createResource } from '../src/resource-model.js';
+
+// ---------- shared helpers ----------
+
+function makeStack(name, specOverrides = {}) {
+  return createResource('AgentStack', { name }, {
+    organizationRef: 'org-a',
+    baseAgent: 'claude-code',
+    adapter: 'babysitter',
+    runtimeIdentity: { serviceAccountRef: 'sa-agent' },
+    ...specOverrides
+  });
+}
+
+function makeServiceAccount(name, orgRef = 'org-a') {
+  return createResource('AgentServiceAccount', { name }, {
+    organizationRef: orgRef,
+    namespace: 'kradle-agents',
+    serviceAccountName: name
+  });
+}
+
+function makeRoleBinding(name, subject, orgRef = 'org-a') {
+  return createResource('AgentRoleBinding', { name }, {
+    organizationRef: orgRef,
+    subject,
+    roleRef: 'agent-role',
+    scope: 'namespace'
+  });
+}
+
+function makeSecretGrant(name, subject, purpose, overrides = {}) {
+  return createResource('AgentSecretGrant', { name }, {
+    organizationRef: 'org-a',
+    subject,
+    secretRef: 'api-keys',
+    purpose,
+    ...overrides
+  });
+}
+
+function makeWorkspacePolicy(name, specOverrides = {}) {
+  return createResource('KradleWorkspacePolicy', { name }, {
+    organizationRef: 'org-a',
+    mode: 'ephemeral',
+    retentionPolicy: 'delete-on-completion',
+    ...specOverrides
+  });
+}
+
+function fullyGrantedResources(stackOverrides = {}) {
+  return {
+    AgentStack: [makeStack('test-stack', stackOverrides)],
+    AgentServiceAccount: [makeServiceAccount('sa-agent')],
+    AgentRoleBinding: [makeRoleBinding('rb-1', 'sa-agent')],
+    AgentSecretGrant: [makeSecretGrant('sg-model', 'sa-agent', 'model-provider')],
+    AgentConfigGrant: [],
+    AgentMcpServer: [],
+    KradleWorkspacePolicy: []
+  };
+}
+
+const baseInput = {
+  repository: 'org-a/my-repo',
+  ref: 'refs/heads/main',
+  actor: 'user-1',
+  agentStack: 'test-stack',
+  triggerSource: 'manual',
+  taskKind: 'fix'
+};
+
+// ==========================================================
+// Group 1 — Cross-org denial
+// ==========================================================
+
+describe('agent permission review v2 — cross-org denial', () => {
+  it('allows access when agent org matches repository org', () => {
+    const reviewer = createPermissionReviewer();
+    const resources = fullyGrantedResources({ organizationRef: 'org-a' });
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      repository: 'org-a/my-repo',
+      resources
+    });
+    assert.equal(result.decision, 'allowed');
+    assert.ok(Array.isArray(result.crossOrgDenials), 'crossOrgDenials should be present');
+    assert.equal(result.crossOrgDenials.length, 0, 'no cross-org denials expected');
+  });
+
+  it('denies access and populates crossOrgDenials when agent org differs from repository org', () => {
+    const reviewer = createPermissionReviewer();
+    // stack is in org-a but repository is in org-b
+    const resources = fullyGrantedResources({ organizationRef: 'org-a' });
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      repository: 'org-b/their-repo',
+      resources
+    });
+    assert.equal(result.decision, 'denied');
+    assert.ok(Array.isArray(result.crossOrgDenials), 'crossOrgDenials must be an array');
+    assert.ok(result.crossOrgDenials.length > 0, 'should have at least one cross-org denial entry');
+    const denial = result.crossOrgDenials[0];
+    assert.ok(denial.agentOrg, 'denial should include agentOrg');
+    assert.ok(denial.resourceOrg, 'denial should include resourceOrg');
+  });
+
+  it('cross-org denial error is reflected in the reasons array with severity error', () => {
+    const reviewer = createPermissionReviewer();
+    const resources = fullyGrantedResources({ organizationRef: 'org-a' });
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      repository: 'org-z/external-repo',
+      resources
+    });
+    assert.ok(
+      result.reasons.some((r) => r.severity === 'error' && r.message.toLowerCase().includes('org')),
+      'reasons should contain an error mentioning org mismatch'
+    );
+  });
+});
+
+// ==========================================================
+// Group 2 — Approval mode validation
+// ==========================================================
+
+describe('agent permission review v2 — approval mode', () => {
+  it("approvalMode 'yolo' auto-approves and decision is allowed when permissions are otherwise valid", () => {
+    const reviewer = createPermissionReviewer();
+    const resources = fullyGrantedResources({ approvalMode: 'yolo' });
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      resources
+    });
+    assert.equal(result.decision, 'allowed');
+    assert.equal(result.approvalMode, 'yolo');
+  });
+
+  it("approvalMode 'deny' blocks all requests and returns denied", () => {
+    const reviewer = createPermissionReviewer();
+    const resources = fullyGrantedResources({ approvalMode: 'deny' });
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      resources
+    });
+    assert.equal(result.decision, 'denied');
+    assert.equal(result.approvalMode, 'deny');
+    assert.ok(
+      result.reasons.some((r) => r.severity === 'error' && r.message.toLowerCase().includes('deny')),
+      'reason should mention deny mode'
+    );
+  });
+
+  it("approvalMode 'prompt' keeps requires-approval when grants need approval", () => {
+    const reviewer = createPermissionReviewer();
+    const mcpServer = createResource('AgentMcpServer', { name: 'mcp-prod' }, {
+      organizationRef: 'org-a',
+      transport: 'stdio',
+      scope: 'workspace',
+      secretRef: 'prod-secret'
+    });
+    const stack = makeStack('test-stack', {
+      approvalMode: 'prompt',
+      mcpServerRefs: ['mcp-prod']
+    });
+    const mcpGrant = makeSecretGrant('sg-prod', 'sa-agent', 'mcp-server:mcp-prod', {
+      requiredApproval: 'always'
+    });
+    const resources = {
+      AgentStack: [stack],
+      AgentServiceAccount: [makeServiceAccount('sa-agent')],
+      AgentRoleBinding: [makeRoleBinding('rb-1', 'sa-agent')],
+      AgentSecretGrant: [mcpGrant, makeSecretGrant('sg-model', 'sa-agent', 'model-provider')],
+      AgentConfigGrant: [],
+      AgentMcpServer: [mcpServer],
+      KradleWorkspacePolicy: []
+    };
+    const result = reviewer.reviewPermissions({ ...baseInput, resources });
+    assert.equal(result.decision, 'requires-approval');
+    assert.equal(result.approvalMode, 'prompt');
+  });
+
+  it('invalid approvalMode value causes denied with validation error', () => {
+    const reviewer = createPermissionReviewer();
+    const resources = fullyGrantedResources({ approvalMode: 'auto-accept-everything' });
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      resources
+    });
+    assert.equal(result.decision, 'denied');
+    assert.ok(
+      result.reasons.some((r) => r.severity === 'error' && r.message.toLowerCase().includes('approvalmode')),
+      'reasons should flag invalid approvalMode'
+    );
+  });
+});
+
+// ==========================================================
+// Group 3 — Workspace policy enforcement
+// ==========================================================
+
+describe('agent permission review v2 — workspace policy', () => {
+  it('allowed when requested tool is in workspace policy allowedTools', () => {
+    const reviewer = createPermissionReviewer();
+    const policy = makeWorkspacePolicy('wp-1', { allowedTools: ['bash', 'read_file'] });
+    const resources = {
+      ...fullyGrantedResources(),
+      KradleWorkspacePolicy: [policy]
+    };
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      workspacePolicyRef: 'wp-1',
+      toolRefs: ['bash'],
+      resources
+    });
+    assert.equal(result.decision, 'allowed');
+  });
+
+  it('denied when requested tool is in workspace policy deniedTools', () => {
+    const reviewer = createPermissionReviewer();
+    const policy = makeWorkspacePolicy('wp-1', { deniedTools: ['bash'] });
+    const resources = {
+      ...fullyGrantedResources(),
+      KradleWorkspacePolicy: [policy]
+    };
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      workspacePolicyRef: 'wp-1',
+      toolRefs: ['bash'],
+      resources
+    });
+    assert.equal(result.decision, 'denied');
+    assert.ok(
+      result.reasons.some((r) => r.severity === 'error' && r.message.toLowerCase().includes('denied')),
+      'reason should mention denied tool'
+    );
+  });
+
+  it('denied when maxConcurrentSessions is 0 (no sessions allowed by policy)', () => {
+    const reviewer = createPermissionReviewer();
+    const policy = makeWorkspacePolicy('wp-strict', { maxConcurrentSessions: 0 });
+    const resources = {
+      ...fullyGrantedResources(),
+      KradleWorkspacePolicy: [policy]
+    };
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      workspacePolicyRef: 'wp-strict',
+      resources
+    });
+    assert.equal(result.decision, 'denied');
+    assert.ok(
+      result.reasons.some((r) => r.severity === 'error' && r.message.toLowerCase().includes('maxconcurrentsessions')),
+      'reason should mention maxConcurrentSessions'
+    );
+  });
+});
+
+// ==========================================================
+// Group 4 — Untrusted fork detection
+// ==========================================================
+
+describe('agent permission review v2 — untrusted fork detection', () => {
+  it('no untrustedForkWarnings when ref is from the canonical repository', () => {
+    const reviewer = createPermissionReviewer();
+    const resources = fullyGrantedResources();
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      repository: 'org-a/my-repo',
+      ref: 'refs/heads/main',
+      resources
+    });
+    assert.ok(Array.isArray(result.untrustedForkWarnings), 'untrustedForkWarnings must be present');
+    assert.equal(result.untrustedForkWarnings.length, 0);
+  });
+
+  it('untrustedForkWarnings populated when ref indicates a fork (refs/pull/*/head from external fork)', () => {
+    const reviewer = createPermissionReviewer();
+    // A pull_request ref from a fork is commonly refs/pull/<n>/head where the head sha is from a fork
+    const resources = fullyGrantedResources();
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      repository: 'org-a/my-repo',
+      ref: 'refs/pull/42/head',
+      isFork: true,
+      resources
+    });
+    assert.ok(Array.isArray(result.untrustedForkWarnings), 'untrustedForkWarnings must be present');
+    assert.ok(result.untrustedForkWarnings.length > 0, 'should have at least one fork warning');
+  });
+
+  it('privileged grants (ServiceAccount, Secret) are blocked for untrusted forks', () => {
+    const reviewer = createPermissionReviewer();
+    const resources = fullyGrantedResources();
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      repository: 'org-a/my-repo',
+      ref: 'refs/pull/99/head',
+      isFork: true,
+      resources
+    });
+    // Privileged grants that existed should not be in the approved grants list
+    // or the decision should downgrade
+    const hasPrivilegedGrant = result.grants.some(
+      (g) => (g.kind === 'AgentServiceAccount' || g.kind === 'AgentSecretGrant') && g.status === 'granted'
+    );
+    // Either the grants are stripped or decision is denied/requires-approval
+    const isRestricted = !hasPrivilegedGrant || result.decision === 'denied' || result.decision === 'requires-approval';
+    assert.ok(isRestricted, 'privileged grants must not be silently approved for untrusted forks');
+    assert.ok(
+      result.untrustedForkWarnings.some((w) => w.blockedKinds && w.blockedKinds.length > 0),
+      'fork warning should list blocked kinds'
+    );
+  });
+});

package/tests/agent-permission-review.test.js

@@ -0,0 +1,209 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createPermissionReviewer } from '../src/agent-permission-review.js';
+import { createResource } from '../src/resource-model.js';
+
+function makeStack(name, overrides = {}) {
+  return createResource('AgentStack', { name }, {
+    organizationRef: 'default',
+    baseAgent: 'claude-code',
+    adapter: 'babysitter',
+    runtimeIdentity: { serviceAccountRef: overrides.serviceAccountRef || 'sa-agent' },
+    ...(overrides.spec || {})
+  });
+}
+
+function makeServiceAccount(name) {
+  return createResource('AgentServiceAccount', { name }, {
+    organizationRef: 'default',
+    namespace: 'kradle-agents',
+    serviceAccountName: name
+  });
+}
+
+function makeRoleBinding(name, subject) {
+  return createResource('AgentRoleBinding', { name }, {
+    organizationRef: 'default',
+    subject,
+    roleRef: 'agent-role',
+    scope: 'namespace'
+  });
+}
+
+function makeSecretGrant(name, subject, purpose, overrides = {}) {
+  return createResource('AgentSecretGrant', { name }, {
+    organizationRef: 'default',
+    subject,
+    secretRef: 'api-keys',
+    purpose,
+    ...overrides
+  });
+}
+
+function makeMcpServer(name, overrides = {}) {
+  return createResource('AgentMcpServer', { name }, {
+    organizationRef: 'default',
+    transport: 'stdio',
+    scope: 'workspace',
+    ...overrides
+  });
+}
+
+function makeModelProviderGrant(subject) {
+  return makeSecretGrant('sg-model', subject, 'model-provider');
+}
+
+const baseInput = {
+  repository: 'my-repo',
+  ref: 'refs/heads/main',
+  actor: 'user-1',
+  agentStack: 'test-stack',
+  triggerSource: 'manual',
+  taskKind: 'fix'
+};
+
+describe('agent permission review', () => {
+  it('fully granted stack returns allowed', () => {
+    const reviewer = createPermissionReviewer();
+    const resources = {
+      AgentStack: [makeStack('test-stack')],
+      AgentServiceAccount: [makeServiceAccount('sa-agent')],
+      AgentRoleBinding: [makeRoleBinding('rb-1', 'sa-agent')],
+      AgentSecretGrant: [makeModelProviderGrant('sa-agent')],
+      AgentConfigGrant: [],
+      AgentMcpServer: []
+    };
+    const result = reviewer.reviewPermissions({ ...baseInput, resources });
+    assert.equal(result.decision, 'allowed');
+    assert.ok(result.grants.length > 0, 'should have at least one grant');
+    assert.ok(result.grants.some((g) => g.kind === 'AgentServiceAccount' && g.status === 'bound'));
+    assert.ok(result.grants.some((g) => g.kind === 'AgentRoleBinding' && g.status === 'bound'));
+    assert.ok(typeof result.digest === 'string' && result.digest.length > 0);
+  });
+
+  it('missing service account returns denied with missing-runtime-identity reason', () => {
+    const reviewer = createPermissionReviewer();
+    const resources = {
+      AgentStack: [makeStack('test-stack', { serviceAccountRef: 'nonexistent-sa' })],
+      AgentServiceAccount: [],
+      AgentRoleBinding: [],
+      AgentSecretGrant: [],
+      AgentConfigGrant: [],
+      AgentMcpServer: []
+    };
+    const result = reviewer.reviewPermissions({ ...baseInput, resources });
+    assert.equal(result.decision, 'denied');
+    assert.ok(result.reasons.some((r) => r.severity === 'error' && r.message.includes('Missing AgentServiceAccount')));
+  });
+
+  it('missing secret grant returns denied with missingGrants information', () => {
+    const reviewer = createPermissionReviewer();
+    const mcpServer = makeMcpServer('mcp-github', { secretRef: 'github-token' });
+    const stack = makeStack('test-stack', {
+      spec: {
+        organizationRef: 'default',
+        baseAgent: 'claude-code',
+        adapter: 'babysitter',
+        runtimeIdentity: { serviceAccountRef: 'sa-agent' },
+        mcpServerRefs: ['mcp-github']
+      }
+    });
+    const resources = {
+      AgentStack: [stack],
+      AgentServiceAccount: [makeServiceAccount('sa-agent')],
+      AgentRoleBinding: [makeRoleBinding('rb-1', 'sa-agent')],
+      AgentSecretGrant: [],
+      AgentConfigGrant: [],
+      AgentMcpServer: [mcpServer]
+    };
+    const result = reviewer.reviewPermissions({ ...baseInput, resources });
+    assert.equal(result.decision, 'denied');
+    assert.ok(result.reasons.some((r) => r.severity === 'error' && r.message.includes('Missing AgentSecretGrant')));
+  });
+
+  it('grant requiring approval returns requires-approval', () => {
+    const reviewer = createPermissionReviewer();
+    const mcpServer = makeMcpServer('mcp-prod', { secretRef: 'prod-secret' });
+    const stack = makeStack('test-stack', {
+      spec: {
+        organizationRef: 'default',
+        baseAgent: 'claude-code',
+        adapter: 'babysitter',
+        runtimeIdentity: { serviceAccountRef: 'sa-agent' },
+        mcpServerRefs: ['mcp-prod']
+      }
+    });
+    const mcpGrant = makeSecretGrant('sg-prod', 'sa-agent', 'mcp-server:mcp-prod', {
+      requiredApproval: 'always'
+    });
+    const resources = {
+      AgentStack: [stack],
+      AgentServiceAccount: [makeServiceAccount('sa-agent')],
+      AgentRoleBinding: [makeRoleBinding('rb-1', 'sa-agent')],
+      AgentSecretGrant: [mcpGrant, makeModelProviderGrant('sa-agent')],
+      AgentConfigGrant: [],
+      AgentMcpServer: [mcpServer]
+    };
+    const result = reviewer.reviewPermissions({ ...baseInput, resources });
+    assert.equal(result.decision, 'requires-approval');
+    assert.ok(result.grants.some((g) => g.status === 'requires-approval' && g.requiredApproval === 'always'));
+  });
+
+  it('empty capabilities stack returns allowed', () => {
+    const reviewer = createPermissionReviewer();
+    const stack = makeStack('test-stack');
+    const resources = {
+      AgentStack: [stack],
+      AgentServiceAccount: [makeServiceAccount('sa-agent')],
+      AgentRoleBinding: [makeRoleBinding('rb-1', 'sa-agent')],
+      AgentSecretGrant: [makeModelProviderGrant('sa-agent')],
+      AgentConfigGrant: [],
+      AgentMcpServer: []
+    };
+    const result = reviewer.reviewPermissions({
+      ...baseInput,
+      toolRefs: [],
+      skillRefs: [],
+      mcpServerRefs: [],
+      contextLabelRefs: [],
+      resources
+    });
+    assert.equal(result.decision, 'allowed');
+  });
+
+  it('same input produces deterministic digest', () => {
+    const reviewer = createPermissionReviewer();
+    const resources = {
+      AgentStack: [makeStack('test-stack')],
+      AgentServiceAccount: [makeServiceAccount('sa-agent')],
+      AgentRoleBinding: [makeRoleBinding('rb-1', 'sa-agent')],
+      AgentSecretGrant: [makeModelProviderGrant('sa-agent')],
+      AgentConfigGrant: [],
+      AgentMcpServer: []
+    };
+    const result1 = reviewer.reviewPermissions({ ...baseInput, resources });
+    const result2 = reviewer.reviewPermissions({ ...baseInput, resources });
+    assert.equal(result1.digest, result2.digest);
+    assert.ok(typeof result1.digest === 'string' && result1.digest.length === 64, 'digest should be a 64-char hex SHA-256');
+  });
+
+  it('createPermissionSnapshot returns frozen object with timestamp', () => {
+    const reviewer = createPermissionReviewer();
+    const resources = {
+      AgentStack: [makeStack('test-stack')],
+      AgentServiceAccount: [makeServiceAccount('sa-agent')],
+      AgentRoleBinding: [makeRoleBinding('rb-1', 'sa-agent')],
+      AgentSecretGrant: [makeModelProviderGrant('sa-agent')],
+      AgentConfigGrant: [],
+      AgentMcpServer: []
+    };
+    const review = reviewer.reviewPermissions({ ...baseInput, resources });
+    const snapshot = reviewer.createPermissionSnapshot(review);
+    assert.ok(Object.isFrozen(snapshot), 'snapshot should be frozen');
+    assert.ok(typeof snapshot.snapshotAt === 'string' && snapshot.snapshotAt.length > 0, 'snapshot should have a timestamp');
+    assert.equal(snapshot.frozen, true);
+    assert.equal(snapshot.digest, review.digest);
+    assert.equal(snapshot.decision, review.decision);
+    assert.throws(() => { snapshot.decision = 'denied'; }, TypeError);
+  });
+});

package/tests/agent-persona-controller.test.js

@@ -0,0 +1,127 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createAgentPersonaController, createResource } from '../src/index.js';
+
+function persona(name = 'aria', spec = {}) {
+  return createResource('AgentPersona', { name, namespace: 'kradle-org-default' }, {
+    organizationRef: 'default',
+    displayName: 'Aria',
+    soul: { ref: 'aria-soul' },
+    appearance: { ref: 'aria-appearance' },
+    voiceProfile: { ref: 'aria-voice' },
+    ...spec
+  });
+}
+
+function soul(name = 'aria-soul') {
+  return createResource('AgentSoul', { name, namespace: 'kradle-org-default' }, {
+    organizationRef: 'default',
+    personaRef: 'aria',
+    content: 'You are Aria.'
+  });
+}
+
+function appearance(name = 'aria-appearance') {
+  return createResource('AgentAppearance', { name, namespace: 'kradle-org-default' }, {
+    organizationRef: 'default',
+    personaRef: 'aria',
+    avatar: { type: 'initials', fallbackInitials: 'AR' }
+  });
+}
+
+function voice(name = 'aria-voice') {
+  return createResource('AgentVoiceProfile', { name, namespace: 'kradle-org-default' }, {
+    organizationRef: 'default',
+    personaRef: 'aria',
+    ttsProvider: 'openai',
+    ttsConfig: { voice: 'nova' }
+  });
+}
+
+function stack(name = 'review-stack') {
+  return createResource('AgentStack', { name, namespace: 'kradle-org-default' }, {
+    organizationRef: 'default',
+    baseAgent: 'claude-code',
+    adapter: 'claude-code',
+    runtimeIdentity: { serviceAccountRef: 'sa-default' }
+  });
+}
+
+function definition(name = 'aria-reviewer', spec = {}) {
+  return createResource('AgentDefinition', { name, namespace: 'kradle-org-default' }, {
+    organizationRef: 'default',
+    personaRef: 'aria',
+    stackRef: 'review-stack',
+    roleContext: 'Review pull requests for security issues.',
+    ...spec
+  });
+}
+
+test('resolveAgentDefinition resolves persona, stack, and referenced soul appearance voice', () => {
+  const controller = createAgentPersonaController();
+  const resources = {
+    AgentDefinition: [definition()],
+    AgentPersona: [persona()],
+    AgentSoul: [soul()],
+    AgentAppearance: [appearance()],
+    AgentVoiceProfile: [voice()],
+    AgentStack: [stack()]
+  };
+
+  const resolved = controller.resolveAgentDefinition('aria-reviewer', { resources, organizationRef: 'default' });
+
+  assert.equal(resolved.error, false);
+  assert.equal(resolved.definition.metadata.name, 'aria-reviewer');
+  assert.equal(resolved.persona.metadata.name, 'aria');
+  assert.equal(resolved.soul.spec.content, 'You are Aria.');
+  assert.equal(resolved.appearance.spec.avatar.fallbackInitials, 'AR');
+  assert.equal(resolved.voiceProfile.spec.ttsProvider, 'openai');
+  assert.equal(resolved.stack.metadata.name, 'review-stack');
+  assert.deepEqual(resolved.errors, []);
+});
+
+test('resolveAgentDefinition supports inline soul, appearance, and voice profile data', () => {
+  const controller = createAgentPersonaController();
+  const resources = {
+    AgentDefinition: [definition()],
+    AgentPersona: [persona('aria', {
+      soul: { inline: 'Inline soul' },
+      appearance: { inline: { avatar: { type: 'emoji', emoji: 'A' } } },
+      voiceProfile: { inline: { ttsProvider: 'local-piper', ttsConfig: { voice: 'alto' } } }
+    })],
+    AgentStack: [stack()]
+  };
+
+  const resolved = controller.resolveAgentDefinition('aria-reviewer', { resources, organizationRef: 'default' });
+
+  assert.equal(resolved.error, false);
+  assert.equal(resolved.soul.spec.content, 'Inline soul');
+  assert.equal(resolved.appearance.spec.avatar.type, 'emoji');
+  assert.equal(resolved.voiceProfile.spec.ttsProvider, 'local-piper');
+});
+
+test('resolveAgentDefinition reports missing referenced resources', () => {
+  const controller = createAgentPersonaController();
+  const resources = {
+    AgentDefinition: [definition()],
+    AgentPersona: [persona()],
+    AgentStack: []
+  };
+
+  const resolved = controller.resolveAgentDefinition('aria-reviewer', { resources, organizationRef: 'default' });
+
+  assert.equal(resolved.error, true);
+  assert.ok(resolved.errors.some((error) => error.includes('AgentSoul not found: aria-soul')));
+  assert.ok(resolved.errors.some((error) => error.includes('AgentAppearance not found: aria-appearance')));
+  assert.ok(resolved.errors.some((error) => error.includes('AgentVoiceProfile not found: aria-voice')));
+  assert.ok(resolved.errors.some((error) => error.includes('AgentStack not found: review-stack')));
+});
+
+test('validateAgentDefinition requires personaRef and stackRef', () => {
+  const controller = createAgentPersonaController();
+  const result = controller.validateAgentDefinition({ kind: 'AgentDefinition', spec: { organizationRef: 'default' } });
+
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.includes('spec.personaRef is required'));
+  assert.ok(result.errors.includes('spec.stackRef is required'));
+});