feat(persona-registry): load personal agents from the workforce home

packages/cli/README.md

@@ -379,7 +379,9 @@ agentworkforce sources remove <dir|config-position>
 
 Two fixed project sources always lead the cascade:
 `<cwd>/.agentworkforce/workforce/personas/*.json`, then
-`<cwd>/.agentworkforce/workforce/agents/<name>/persona.json`.
+`<cwd>/.agentworkforce/workforce/agents/<name>/persona.json`. A third fixed
+source, `~/.agentworkforce/workforce/agents/<name>/persona.json`, carries
+personal agents and follows the personal personas dir wherever it ranks.
 
 After that, the CLI reads an ordered list of configurable persona directories
 from `~/.agentworkforce/workforce/config.json`. If no config exists, the list
@@ -477,13 +479,23 @@ wins):
 2. `<cwd>/.agentworkforce/workforce/agents/<name>/persona.json` — **cwd:agents**
 3. Configurable persona source dirs, in order. Default:
    `~/.agentworkforce/workforce/personas/*.json` — **user**
-4. Internal built-in system personas in `/personas/` — **library**
+4. `~/.agentworkforce/workforce/agents/<name>/persona.json` — **user:agents**,
+   the personal mirror of `cwd:agents`. It rides directly behind the personal
+   personas dir, so moving that dir in the cascade moves both. The tables
+   printed by `list` and `sources list` show it as **personal:agents**,
+   following `user` → `personal`; `user:agents` is the value `--json` emits.
+5. Internal built-in system personas in `/personas/` — **library**
 
 Local files are **partial overlays**: only the fields you set replace the
 inherited value. Everything else cascades through from below.
 
 ### Agents that ship their own handler
 
+The same directory layout works in a repo (`cwd:agents`) and in your personal
+config (`user:agents`), so an agent you want everywhere lives in
+`~/.agentworkforce/workforce/agents/<name>/` and a repo's own agents live in its
+working tree. A repo agent outranks a personal one of the same id.
+
 An agent with code of its own keeps persona, handler, tests, and README in one
 directory:
 

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,281 @@ 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/);
+  });
+});
+
+// --- user:agents layer ------------------------------------------------------
+// The personal mirror of cwd:agents — an agent-with-handler a user keeps
+// across every repo, in the `agents/` sibling of their personal personas dir.
+
+test('the personal agents dir loads as user:agents', () => {
+  withLayers(({ cwd, home, homeDir }) => {
+    const userAgents = join(home, '.agentworkforce', 'workforce', 'agents');
+    mkdirSync(join(userAgents, 'note-taker'), { recursive: true });
+    writeJson(join(userAgents, 'note-taker', 'persona.json'), {
+      id: 'note-taker',
+      extends: 'persona-maker',
+      env: { SCOPE: 'personal' }
+    });
+    const loaded = loadLocalPersonas({ cwd, homeDir });
+    assert.deepEqual(loaded.warnings, []);
+    assert.equal(loaded.sources.get('note-taker'), 'user:agents');
+    assert.equal(loaded.byId.get('note-taker')?.env?.SCOPE, 'personal');
+  });
+});
+
+test('a personal agent resolves its skills against its own directory', () => {
+  withLayers(({ cwd, home, homeDir }) => {
+    const workforceHome = join(home, '.agentworkforce', 'workforce');
+    mkdirSync(join(workforceHome, 'skills'), { recursive: true });
+    writeFileSync(join(workforceHome, 'skills', 'voice.md'), '# voice\n');
+    const agentDir = join(workforceHome, 'agents', 'note-taker');
+    mkdirSync(agentDir, { recursive: true });
+    writeJson(join(agentDir, 'persona.json'), {
+      id: 'note-taker',
+      extends: 'persona-maker',
+      skills: [{ id: 'local/voice', source: '../../skills/voice.md', description: 'voice' }]
+    });
+    const loaded = loadLocalPersonas({ cwd, homeDir });
+    assert.deepEqual(loaded.warnings, []);
+    assert.equal(
+      loaded.byId.get('note-taker')?.skills[0]?.source,
+      join(workforceHome, 'skills', 'voice.md')
+    );
+  });
+});
+
+test('a repo agent outranks a personal agent of the same id', () => {
+  withAgentLayer(({ cwd, home, homeDir, agentsDir }) => {
+    const userAgents = join(home, '.agentworkforce', 'workforce', 'agents');
+    mkdirSync(join(userAgents, 'note-taker'), { recursive: true });
+    writeJson(join(userAgents, 'note-taker', 'persona.json'), {
+      id: 'note-taker',
+      extends: 'persona-maker',
+      env: { SCOPE: 'personal', KEPT: 'yes' }
+    });
+    mkdirSync(join(agentsDir, 'note-taker'), { recursive: true });
+    writeJson(join(agentsDir, 'note-taker', 'persona.json'), {
+      id: 'note-taker',
+      env: { SCOPE: 'repo' }
+    });
+    const loaded = loadLocalPersonas({ cwd, homeDir });
+    assert.deepEqual(loaded.warnings, []);
+    assert.equal(loaded.sources.get('note-taker'), 'cwd:agents');
+    const spec = loaded.byId.get('note-taker');
+    assert.equal(spec?.env?.SCOPE, 'repo');
+    assert.equal(spec?.env?.KEPT, 'yes');
+  });
+});
+
+test('user:agents displays as personal:agents, following user -> personal', () => {
+  assert.equal(formatPersonaSourceLabel('user:agents'), 'personal:agents');
+  assert.equal(formatPersonaSourceLabel('cwd:agents'), 'cwd:agents');
+});
+
+test('a missing personal agents dir is not an error', () => {
+  withLayers(({ cwd, homeDir }) => {
+    const loaded = loadLocalPersonas({ cwd, homeDir });
+    assert.deepEqual(loaded.warnings, []);
+  });
+});

packages/persona-registry/README.md

@@ -2,7 +2,7 @@
 
 Programmatic resolution for AgentWorkforce personas. It owns the same source
 cascade used by the CLI: cwd personas, cwd agents, configured directories
-(including the personal directory), then the built-in catalog.
+(including the personal directory), personal agents, then the built-in catalog.
 
 ```ts
 import { resolvePersonaReference } from '@agentworkforce/persona-registry';