feat(persona-registry): warn when an agent's persona.json is stale

packages/cli/src/local-personas.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -1034,3 +1034,205 @@ test('a missing agents/ directory is not an error', () => {
  assert.deepEqual(loaded.warnings, []);
  });
 });
+
+// --- handler agents ---------------------------------------------------------
+// An agent driven by its `onEvent` entry has no interactive launch to
+// configure, so harness/model/systemPrompt are optional. Requiring them kept
+// exactly these agents out of the cascade the agents/ dir was added for.
+
+test('a handler persona loads without interactive fields', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.ok(spec);
+ assert.equal(spec.onEvent, './agent.ts');
+ assert.equal(spec.cloud, true);
+ assert.equal(spec.harness, undefined);
+ assert.equal(spec.model, undefined);
+ assert.equal(spec.systemPrompt, undefined);
+ });
+});
+
+test('a standalone persona with no handler still requires harness', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'interactive');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'interactive',
+ intent: 'documentation',
+ description: 'No handler, so an operator launches it.',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('interactive'), false);
+ assert.match(loaded.warnings[0] ?? '', /harness is required for standalone personas/);
+ });
+});
+
+test('an overlay tweaking env keeps the handler entry it inherits', () => {
+ withAgentLayer(({ cwd, homeDir, pwdDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ writeJson(join(pwdDir, 'digest.json'), { id: 'digest', env: { TONE: 'terse' } });
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.equal(spec?.onEvent, './agent.ts');
+ assert.equal(spec?.cloud, true);
+ assert.equal(spec?.env?.TONE, 'terse');
+ });
+});
+
+test('onEvent may not escape the agent directory', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes its directory.',
+ onEvent: '../../../elsewhere/agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a padded onEvent is normalized before it is stored', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Padded but legal handler path.',
+ onEvent: ' ./agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ // Stored untrimmed this resolves against a directory named " .".
+ assert.equal(loaded.byId.get('digest')?.onEvent, './agent.ts');
+ });
+});
+
+test('onEvent must point at a handler source file', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Points at prose, not a handler.',
+ onEvent: 'README.md',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ // Without the extension rule this would read as a handler and skip the
+ // interactive fields it never declared.
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /must point at a \.ts/);
+ });
+});
+
+test('a padded onEvent cannot smuggle a .. segment past the guard', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes once trimmed.',
+ onEvent: ' ../outside/agent.ts ',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ // Trimmed before validation, so the traversal guard sees the real path.
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a persona.json older than its authoring source warns but still loads', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker',
+ env: { COMPILED: 'stale' }
+ });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ // Backdate the artifact rather than sleeping — same relation, no wall clock.
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.ts/);
+ assert.match(loaded.warnings[0] ?? '', /agentworkforce persona compile/);
+ // Still served: a forgotten compile must not read as a missing persona.
+ assert.equal(loaded.byId.get('proposal-agent')?.env?.COMPILED, 'stale');
+ });
+});
+
+test('a persona.json newer than its authoring source is silent', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker'
+ });
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.ts'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ assert.ok(loaded.byId.has('proposal-agent'));
+ });
+});
+
+test('staleness is measured against the newest authoring file, not the first', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ // An abandoned persona.ts predates the artifact; the live persona.js is
+ // newer. Measuring against the .ts alone would call this fresh.
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), { id: 'proposal-agent', extends: 'persona-maker' });
+ writeFileSync(join(agentDir, 'persona.js'), 'export default {}\n');
+
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(join(agentDir, 'persona.ts'), old, old);
+ const mid = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), mid, mid);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.js/);
+ });
+});

packages/cli/src/local-personas.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -1034,3 +1034,205 @@ test('a missing agents/ directory is not an error', () => {
  assert.deepEqual(loaded.warnings, []);
  });
 });
+
+// --- handler agents ---------------------------------------------------------
+// An agent driven by its `onEvent` entry has no interactive launch to
+// configure, so harness/model/systemPrompt are optional. Requiring them kept
+// exactly these agents out of the cascade the agents/ dir was added for.
+
+test('a handler persona loads without interactive fields', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.ok(spec);
+ assert.equal(spec.onEvent, './agent.ts');
+ assert.equal(spec.cloud, true);
+ assert.equal(spec.harness, undefined);
+ assert.equal(spec.model, undefined);
+ assert.equal(spec.systemPrompt, undefined);
+ });
+});
+
+test('a standalone persona with no handler still requires harness', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'interactive');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'interactive',
+ intent: 'documentation',
+ description: 'No handler, so an operator launches it.',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('interactive'), false);
+ assert.match(loaded.warnings[0] ?? '', /harness is required for standalone personas/);
+ });
+});
+
+test('an overlay tweaking env keeps the handler entry it inherits', () => {
+ withAgentLayer(({ cwd, homeDir, pwdDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ writeJson(join(pwdDir, 'digest.json'), { id: 'digest', env: { TONE: 'terse' } });
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.equal(spec?.onEvent, './agent.ts');
+ assert.equal(spec?.cloud, true);
+ assert.equal(spec?.env?.TONE, 'terse');
+ });
+});
+
+test('onEvent may not escape the agent directory', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes its directory.',
+ onEvent: '../../../elsewhere/agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a padded onEvent is normalized before it is stored', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Padded but legal handler path.',
+ onEvent: ' ./agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ // Stored untrimmed this resolves against a directory named " .".
+ assert.equal(loaded.byId.get('digest')?.onEvent, './agent.ts');
+ });
+});
+
+test('onEvent must point at a handler source file', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Points at prose, not a handler.',
+ onEvent: 'README.md',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ // Without the extension rule this would read as a handler and skip the
+ // interactive fields it never declared.
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /must point at a \.ts/);
+ });
+});
+
+test('a padded onEvent cannot smuggle a .. segment past the guard', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes once trimmed.',
+ onEvent: ' ../outside/agent.ts ',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ // Trimmed before validation, so the traversal guard sees the real path.
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a persona.json older than its authoring source warns but still loads', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker',
+ env: { COMPILED: 'stale' }
+ });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ // Backdate the artifact rather than sleeping — same relation, no wall clock.
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.ts/);
+ assert.match(loaded.warnings[0] ?? '', /agentworkforce persona compile/);
+ // Still served: a forgotten compile must not read as a missing persona.
+ assert.equal(loaded.byId.get('proposal-agent')?.env?.COMPILED, 'stale');
+ });
+});
+
+test('a persona.json newer than its authoring source is silent', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker'
+ });
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.ts'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ assert.ok(loaded.byId.has('proposal-agent'));
+ });
+});
+
+test('staleness is measured against the newest authoring file, not the first', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ // An abandoned persona.ts predates the artifact; the live persona.js is
+ // newer. Measuring against the .ts alone would call this fresh.
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), { id: 'proposal-agent', extends: 'persona-maker' });
+ writeFileSync(join(agentDir, 'persona.js'), 'export default {}\n');
+
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(join(agentDir, 'persona.ts'), old, old);
+ const mid = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), mid, mid);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.js/);
+ });
+});

packages/cli/src/local-personas.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -1034,3 +1034,205 @@ test('a missing agents/ directory is not an error', () => {
  assert.deepEqual(loaded.warnings, []);
  });
 });
+
+// --- handler agents ---------------------------------------------------------
+// An agent driven by its `onEvent` entry has no interactive launch to
+// configure, so harness/model/systemPrompt are optional. Requiring them kept
+// exactly these agents out of the cascade the agents/ dir was added for.
+
+test('a handler persona loads without interactive fields', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.ok(spec);
+ assert.equal(spec.onEvent, './agent.ts');
+ assert.equal(spec.cloud, true);
+ assert.equal(spec.harness, undefined);
+ assert.equal(spec.model, undefined);
+ assert.equal(spec.systemPrompt, undefined);
+ });
+});
+
+test('a standalone persona with no handler still requires harness', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'interactive');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'interactive',
+ intent: 'documentation',
+ description: 'No handler, so an operator launches it.',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('interactive'), false);
+ assert.match(loaded.warnings[0] ?? '', /harness is required for standalone personas/);
+ });
+});
+
+test('an overlay tweaking env keeps the handler entry it inherits', () => {
+ withAgentLayer(({ cwd, homeDir, pwdDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ writeJson(join(pwdDir, 'digest.json'), { id: 'digest', env: { TONE: 'terse' } });
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.equal(spec?.onEvent, './agent.ts');
+ assert.equal(spec?.cloud, true);
+ assert.equal(spec?.env?.TONE, 'terse');
+ });
+});
+
+test('onEvent may not escape the agent directory', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes its directory.',
+ onEvent: '../../../elsewhere/agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a padded onEvent is normalized before it is stored', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Padded but legal handler path.',
+ onEvent: ' ./agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ // Stored untrimmed this resolves against a directory named " .".
+ assert.equal(loaded.byId.get('digest')?.onEvent, './agent.ts');
+ });
+});
+
+test('onEvent must point at a handler source file', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Points at prose, not a handler.',
+ onEvent: 'README.md',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ // Without the extension rule this would read as a handler and skip the
+ // interactive fields it never declared.
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /must point at a \.ts/);
+ });
+});
+
+test('a padded onEvent cannot smuggle a .. segment past the guard', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes once trimmed.',
+ onEvent: ' ../outside/agent.ts ',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ // Trimmed before validation, so the traversal guard sees the real path.
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a persona.json older than its authoring source warns but still loads', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker',
+ env: { COMPILED: 'stale' }
+ });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ // Backdate the artifact rather than sleeping — same relation, no wall clock.
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.ts/);
+ assert.match(loaded.warnings[0] ?? '', /agentworkforce persona compile/);
+ // Still served: a forgotten compile must not read as a missing persona.
+ assert.equal(loaded.byId.get('proposal-agent')?.env?.COMPILED, 'stale');
+ });
+});
+
+test('a persona.json newer than its authoring source is silent', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker'
+ });
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.ts'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ assert.ok(loaded.byId.has('proposal-agent'));
+ });
+});
+
+test('staleness is measured against the newest authoring file, not the first', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ // An abandoned persona.ts predates the artifact; the live persona.js is
+ // newer. Measuring against the .ts alone would call this fresh.
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), { id: 'proposal-agent', extends: 'persona-maker' });
+ writeFileSync(join(agentDir, 'persona.js'), 'export default {}\n');
+
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(join(agentDir, 'persona.ts'), old, old);
+ const mid = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), mid, mid);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.js/);
+ });
+});

packages/cli/src/local-personas.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -1034,3 +1034,205 @@ test('a missing agents/ directory is not an error', () => {
  assert.deepEqual(loaded.warnings, []);
  });
 });
+
+// --- handler agents ---------------------------------------------------------
+// An agent driven by its `onEvent` entry has no interactive launch to
+// configure, so harness/model/systemPrompt are optional. Requiring them kept
+// exactly these agents out of the cascade the agents/ dir was added for.
+
+test('a handler persona loads without interactive fields', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.ok(spec);
+ assert.equal(spec.onEvent, './agent.ts');
+ assert.equal(spec.cloud, true);
+ assert.equal(spec.harness, undefined);
+ assert.equal(spec.model, undefined);
+ assert.equal(spec.systemPrompt, undefined);
+ });
+});
+
+test('a standalone persona with no handler still requires harness', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'interactive');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'interactive',
+ intent: 'documentation',
+ description: 'No handler, so an operator launches it.',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('interactive'), false);
+ assert.match(loaded.warnings[0] ?? '', /harness is required for standalone personas/);
+ });
+});
+
+test('an overlay tweaking env keeps the handler entry it inherits', () => {
+ withAgentLayer(({ cwd, homeDir, pwdDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ writeJson(join(pwdDir, 'digest.json'), { id: 'digest', env: { TONE: 'terse' } });
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.equal(spec?.onEvent, './agent.ts');
+ assert.equal(spec?.cloud, true);
+ assert.equal(spec?.env?.TONE, 'terse');
+ });
+});
+
+test('onEvent may not escape the agent directory', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes its directory.',
+ onEvent: '../../../elsewhere/agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a padded onEvent is normalized before it is stored', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Padded but legal handler path.',
+ onEvent: ' ./agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ // Stored untrimmed this resolves against a directory named " .".
+ assert.equal(loaded.byId.get('digest')?.onEvent, './agent.ts');
+ });
+});
+
+test('onEvent must point at a handler source file', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Points at prose, not a handler.',
+ onEvent: 'README.md',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ // Without the extension rule this would read as a handler and skip the
+ // interactive fields it never declared.
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /must point at a \.ts/);
+ });
+});
+
+test('a padded onEvent cannot smuggle a .. segment past the guard', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes once trimmed.',
+ onEvent: ' ../outside/agent.ts ',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ // Trimmed before validation, so the traversal guard sees the real path.
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a persona.json older than its authoring source warns but still loads', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker',
+ env: { COMPILED: 'stale' }
+ });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ // Backdate the artifact rather than sleeping — same relation, no wall clock.
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.ts/);
+ assert.match(loaded.warnings[0] ?? '', /agentworkforce persona compile/);
+ // Still served: a forgotten compile must not read as a missing persona.
+ assert.equal(loaded.byId.get('proposal-agent')?.env?.COMPILED, 'stale');
+ });
+});
+
+test('a persona.json newer than its authoring source is silent', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker'
+ });
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.ts'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ assert.ok(loaded.byId.has('proposal-agent'));
+ });
+});
+
+test('staleness is measured against the newest authoring file, not the first', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ // An abandoned persona.ts predates the artifact; the live persona.js is
+ // newer. Measuring against the .ts alone would call this fresh.
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), { id: 'proposal-agent', extends: 'persona-maker' });
+ writeFileSync(join(agentDir, 'persona.js'), 'export default {}\n');
+
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(join(agentDir, 'persona.ts'), old, old);
+ const mid = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), mid, mid);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.js/);
+ });
+});

packages/cli/src/local-personas.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -1034,3 +1034,205 @@ test('a missing agents/ directory is not an error', () => {
  assert.deepEqual(loaded.warnings, []);
  });
 });
+
+// --- handler agents ---------------------------------------------------------
+// An agent driven by its `onEvent` entry has no interactive launch to
+// configure, so harness/model/systemPrompt are optional. Requiring them kept
+// exactly these agents out of the cascade the agents/ dir was added for.
+
+test('a handler persona loads without interactive fields', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.ok(spec);
+ assert.equal(spec.onEvent, './agent.ts');
+ assert.equal(spec.cloud, true);
+ assert.equal(spec.harness, undefined);
+ assert.equal(spec.model, undefined);
+ assert.equal(spec.systemPrompt, undefined);
+ });
+});
+
+test('a standalone persona with no handler still requires harness', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'interactive');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'interactive',
+ intent: 'documentation',
+ description: 'No handler, so an operator launches it.',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('interactive'), false);
+ assert.match(loaded.warnings[0] ?? '', /harness is required for standalone personas/);
+ });
+});
+
+test('an overlay tweaking env keeps the handler entry it inherits', () => {
+ withAgentLayer(({ cwd, homeDir, pwdDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ writeJson(join(pwdDir, 'digest.json'), { id: 'digest', env: { TONE: 'terse' } });
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.equal(spec?.onEvent, './agent.ts');
+ assert.equal(spec?.cloud, true);
+ assert.equal(spec?.env?.TONE, 'terse');
+ });
+});
+
+test('onEvent may not escape the agent directory', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes its directory.',
+ onEvent: '../../../elsewhere/agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a padded onEvent is normalized before it is stored', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Padded but legal handler path.',
+ onEvent: ' ./agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ // Stored untrimmed this resolves against a directory named " .".
+ assert.equal(loaded.byId.get('digest')?.onEvent, './agent.ts');
+ });
+});
+
+test('onEvent must point at a handler source file', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Points at prose, not a handler.',
+ onEvent: 'README.md',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ // Without the extension rule this would read as a handler and skip the
+ // interactive fields it never declared.
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /must point at a \.ts/);
+ });
+});
+
+test('a padded onEvent cannot smuggle a .. segment past the guard', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes once trimmed.',
+ onEvent: ' ../outside/agent.ts ',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ // Trimmed before validation, so the traversal guard sees the real path.
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a persona.json older than its authoring source warns but still loads', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker',
+ env: { COMPILED: 'stale' }
+ });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ // Backdate the artifact rather than sleeping — same relation, no wall clock.
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.ts/);
+ assert.match(loaded.warnings[0] ?? '', /agentworkforce persona compile/);
+ // Still served: a forgotten compile must not read as a missing persona.
+ assert.equal(loaded.byId.get('proposal-agent')?.env?.COMPILED, 'stale');
+ });
+});
+
+test('a persona.json newer than its authoring source is silent', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker'
+ });
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.ts'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ assert.ok(loaded.byId.has('proposal-agent'));
+ });
+});
+
+test('staleness is measured against the newest authoring file, not the first', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ // An abandoned persona.ts predates the artifact; the live persona.js is
+ // newer. Measuring against the .ts alone would call this fresh.
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), { id: 'proposal-agent', extends: 'persona-maker' });
+ writeFileSync(join(agentDir, 'persona.js'), 'export default {}\n');
+
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(join(agentDir, 'persona.ts'), old, old);
+ const mid = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), mid, mid);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.js/);
+ });
+});

packages/cli/src/local-personas.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -1034,3 +1034,205 @@ test('a missing agents/ directory is not an error', () => {
  assert.deepEqual(loaded.warnings, []);
  });
 });
+
+// --- handler agents ---------------------------------------------------------
+// An agent driven by its `onEvent` entry has no interactive launch to
+// configure, so harness/model/systemPrompt are optional. Requiring them kept
+// exactly these agents out of the cascade the agents/ dir was added for.
+
+test('a handler persona loads without interactive fields', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.ok(spec);
+ assert.equal(spec.onEvent, './agent.ts');
+ assert.equal(spec.cloud, true);
+ assert.equal(spec.harness, undefined);
+ assert.equal(spec.model, undefined);
+ assert.equal(spec.systemPrompt, undefined);
+ });
+});
+
+test('a standalone persona with no handler still requires harness', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'interactive');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'interactive',
+ intent: 'documentation',
+ description: 'No handler, so an operator launches it.',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('interactive'), false);
+ assert.match(loaded.warnings[0] ?? '', /harness is required for standalone personas/);
+ });
+});
+
+test('an overlay tweaking env keeps the handler entry it inherits', () => {
+ withAgentLayer(({ cwd, homeDir, pwdDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ writeJson(join(pwdDir, 'digest.json'), { id: 'digest', env: { TONE: 'terse' } });
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.equal(spec?.onEvent, './agent.ts');
+ assert.equal(spec?.cloud, true);
+ assert.equal(spec?.env?.TONE, 'terse');
+ });
+});
+
+test('onEvent may not escape the agent directory', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes its directory.',
+ onEvent: '../../../elsewhere/agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a padded onEvent is normalized before it is stored', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Padded but legal handler path.',
+ onEvent: ' ./agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ // Stored untrimmed this resolves against a directory named " .".
+ assert.equal(loaded.byId.get('digest')?.onEvent, './agent.ts');
+ });
+});
+
+test('onEvent must point at a handler source file', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Points at prose, not a handler.',
+ onEvent: 'README.md',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ // Without the extension rule this would read as a handler and skip the
+ // interactive fields it never declared.
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /must point at a \.ts/);
+ });
+});
+
+test('a padded onEvent cannot smuggle a .. segment past the guard', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes once trimmed.',
+ onEvent: ' ../outside/agent.ts ',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ // Trimmed before validation, so the traversal guard sees the real path.
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a persona.json older than its authoring source warns but still loads', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker',
+ env: { COMPILED: 'stale' }
+ });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ // Backdate the artifact rather than sleeping — same relation, no wall clock.
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.ts/);
+ assert.match(loaded.warnings[0] ?? '', /agentworkforce persona compile/);
+ // Still served: a forgotten compile must not read as a missing persona.
+ assert.equal(loaded.byId.get('proposal-agent')?.env?.COMPILED, 'stale');
+ });
+});
+
+test('a persona.json newer than its authoring source is silent', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker'
+ });
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.ts'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ assert.ok(loaded.byId.has('proposal-agent'));
+ });
+});
+
+test('staleness is measured against the newest authoring file, not the first', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ // An abandoned persona.ts predates the artifact; the live persona.js is
+ // newer. Measuring against the .ts alone would call this fresh.
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), { id: 'proposal-agent', extends: 'persona-maker' });
+ writeFileSync(join(agentDir, 'persona.js'), 'export default {}\n');
+
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(join(agentDir, 'persona.ts'), old, old);
+ const mid = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), mid, mid);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.js/);
+ });
+});

packages/cli/src/local-personas.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -1034,3 +1034,205 @@ test('a missing agents/ directory is not an error', () => {
  assert.deepEqual(loaded.warnings, []);
  });
 });
+
+// --- handler agents ---------------------------------------------------------
+// An agent driven by its `onEvent` entry has no interactive launch to
+// configure, so harness/model/systemPrompt are optional. Requiring them kept
+// exactly these agents out of the cascade the agents/ dir was added for.
+
+test('a handler persona loads without interactive fields', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.ok(spec);
+ assert.equal(spec.onEvent, './agent.ts');
+ assert.equal(spec.cloud, true);
+ assert.equal(spec.harness, undefined);
+ assert.equal(spec.model, undefined);
+ assert.equal(spec.systemPrompt, undefined);
+ });
+});
+
+test('a standalone persona with no handler still requires harness', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'interactive');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'interactive',
+ intent: 'documentation',
+ description: 'No handler, so an operator launches it.',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('interactive'), false);
+ assert.match(loaded.warnings[0] ?? '', /harness is required for standalone personas/);
+ });
+});
+
+test('an overlay tweaking env keeps the handler entry it inherits', () => {
+ withAgentLayer(({ cwd, homeDir, pwdDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ writeJson(join(pwdDir, 'digest.json'), { id: 'digest', env: { TONE: 'terse' } });
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.equal(spec?.onEvent, './agent.ts');
+ assert.equal(spec?.cloud, true);
+ assert.equal(spec?.env?.TONE, 'terse');
+ });
+});
+
+test('onEvent may not escape the agent directory', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes its directory.',
+ onEvent: '../../../elsewhere/agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a padded onEvent is normalized before it is stored', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Padded but legal handler path.',
+ onEvent: ' ./agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ // Stored untrimmed this resolves against a directory named " .".
+ assert.equal(loaded.byId.get('digest')?.onEvent, './agent.ts');
+ });
+});
+
+test('onEvent must point at a handler source file', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Points at prose, not a handler.',
+ onEvent: 'README.md',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ // Without the extension rule this would read as a handler and skip the
+ // interactive fields it never declared.
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /must point at a \.ts/);
+ });
+});
+
+test('a padded onEvent cannot smuggle a .. segment past the guard', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes once trimmed.',
+ onEvent: ' ../outside/agent.ts ',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ // Trimmed before validation, so the traversal guard sees the real path.
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a persona.json older than its authoring source warns but still loads', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker',
+ env: { COMPILED: 'stale' }
+ });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ // Backdate the artifact rather than sleeping — same relation, no wall clock.
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.ts/);
+ assert.match(loaded.warnings[0] ?? '', /agentworkforce persona compile/);
+ // Still served: a forgotten compile must not read as a missing persona.
+ assert.equal(loaded.byId.get('proposal-agent')?.env?.COMPILED, 'stale');
+ });
+});
+
+test('a persona.json newer than its authoring source is silent', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker'
+ });
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.ts'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ assert.ok(loaded.byId.has('proposal-agent'));
+ });
+});
+
+test('staleness is measured against the newest authoring file, not the first', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ // An abandoned persona.ts predates the artifact; the live persona.js is
+ // newer. Measuring against the .ts alone would call this fresh.
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), { id: 'proposal-agent', extends: 'persona-maker' });
+ writeFileSync(join(agentDir, 'persona.js'), 'export default {}\n');
+
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(join(agentDir, 'persona.ts'), old, old);
+ const mid = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), mid, mid);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.js/);
+ });
+});

packages/cli/src/local-personas.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -1034,3 +1034,205 @@ test('a missing agents/ directory is not an error', () => {
  assert.deepEqual(loaded.warnings, []);
  });
 });
+
+// --- handler agents ---------------------------------------------------------
+// An agent driven by its `onEvent` entry has no interactive launch to
+// configure, so harness/model/systemPrompt are optional. Requiring them kept
+// exactly these agents out of the cascade the agents/ dir was added for.
+
+test('a handler persona loads without interactive fields', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.ok(spec);
+ assert.equal(spec.onEvent, './agent.ts');
+ assert.equal(spec.cloud, true);
+ assert.equal(spec.harness, undefined);
+ assert.equal(spec.model, undefined);
+ assert.equal(spec.systemPrompt, undefined);
+ });
+});
+
+test('a standalone persona with no handler still requires harness', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'interactive');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'interactive',
+ intent: 'documentation',
+ description: 'No handler, so an operator launches it.',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('interactive'), false);
+ assert.match(loaded.warnings[0] ?? '', /harness is required for standalone personas/);
+ });
+});
+
+test('an overlay tweaking env keeps the handler entry it inherits', () => {
+ withAgentLayer(({ cwd, homeDir, pwdDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Weekly digest handler.',
+ cloud: true,
+ onEvent: './agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ writeJson(join(pwdDir, 'digest.json'), { id: 'digest', env: { TONE: 'terse' } });
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ const spec = loaded.byId.get('digest');
+ assert.equal(spec?.onEvent, './agent.ts');
+ assert.equal(spec?.cloud, true);
+ assert.equal(spec?.env?.TONE, 'terse');
+ });
+});
+
+test('onEvent may not escape the agent directory', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes its directory.',
+ onEvent: '../../../elsewhere/agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a padded onEvent is normalized before it is stored', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Padded but legal handler path.',
+ onEvent: ' ./agent.ts',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ // Stored untrimmed this resolves against a directory named " .".
+ assert.equal(loaded.byId.get('digest')?.onEvent, './agent.ts');
+ });
+});
+
+test('onEvent must point at a handler source file', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Points at prose, not a handler.',
+ onEvent: 'README.md',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ // Without the extension rule this would read as a handler and skip the
+ // interactive fields it never declared.
+ assert.equal(loaded.byId.has('digest'), false);
+ assert.match(loaded.warnings[0] ?? '', /must point at a \.ts/);
+ });
+});
+
+test('a padded onEvent cannot smuggle a .. segment past the guard', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'digest');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'digest',
+ intent: 'documentation',
+ description: 'Escapes once trimmed.',
+ onEvent: ' ../outside/agent.ts ',
+ harnessSettings: { reasoning: 'medium', timeoutSeconds: 600 }
+ });
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.byId.has('digest'), false);
+ // Trimmed before validation, so the traversal guard sees the real path.
+ assert.match(loaded.warnings[0] ?? '', /onEvent must not contain "\.\." segments/);
+ });
+});
+
+test('a persona.json older than its authoring source warns but still loads', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker',
+ env: { COMPILED: 'stale' }
+ });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ // Backdate the artifact rather than sleeping — same relation, no wall clock.
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.ts/);
+ assert.match(loaded.warnings[0] ?? '', /agentworkforce persona compile/);
+ // Still served: a forgotten compile must not read as a missing persona.
+ assert.equal(loaded.byId.get('proposal-agent')?.env?.COMPILED, 'stale');
+ });
+});
+
+test('a persona.json newer than its authoring source is silent', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), {
+ id: 'proposal-agent',
+ extends: 'persona-maker'
+ });
+ const past = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.ts'), past, past);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.deepEqual(loaded.warnings, []);
+ assert.ok(loaded.byId.has('proposal-agent'));
+ });
+});
+
+test('staleness is measured against the newest authoring file, not the first', () => {
+ withAgentLayer(({ cwd, homeDir, agentsDir }) => {
+ const agentDir = join(agentsDir, 'proposal-agent');
+ mkdirSync(agentDir, { recursive: true });
+ // An abandoned persona.ts predates the artifact; the live persona.js is
+ // newer. Measuring against the .ts alone would call this fresh.
+ writeFileSync(join(agentDir, 'persona.ts'), 'export default {}\n');
+ writeJson(join(agentDir, 'persona.json'), { id: 'proposal-agent', extends: 'persona-maker' });
+ writeFileSync(join(agentDir, 'persona.js'), 'export default {}\n');
+
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(join(agentDir, 'persona.ts'), old, old);
+ const mid = new Date(Date.now() - 60_000);
+ utimesSync(join(agentDir, 'persona.json'), mid, mid);
+
+ const loaded = loadLocalPersonas({ cwd, homeDir });
+ assert.equal(loaded.warnings.length, 1);
+ assert.match(loaded.warnings[0] ?? '', /persona\.json is older than persona\.js/);
+ });
+});