296: deriveAgentCard(personaSpec): canonical persona → A2A agent card in persona-kit

examples/review-agent/agent-card.json

@@ -0,0 +1,47 @@
+{
+  "name": "review-agent",
+  "description": "Reviews opened PRs, responds to @mentions in comments, attempts autofix on red CI.",
+  "url": "http://localhost:3000",
+  "version": "0.0.0",
+  "skills": [
+    {
+      "id": "review-rubric",
+      "name": "Review Rubric",
+      "description": "Apply a consistent correctness and regression-risk review rubric.",
+      "tags": [
+        "https://prpm.dev/packages/@agentworkforce/review-rubric",
+        "github",
+        "slack"
+      ]
+    },
+    {
+      "id": "review",
+      "name": "Review",
+      "description": "Persona capability: Review",
+      "tags": [
+        "github",
+        "slack"
+      ]
+    }
+  ],
+  "provider": {
+    "organization": "AgentWorkforce",
+    "persona_id": "review-agent",
+    "intent": "review",
+    "tags": [
+      "review"
+    ]
+  },
+  "capabilities": {
+    "streaming": false,
+    "pushNotifications": false
+  },
+  "default_input_modes": [
+    "text/plain",
+    "application/json"
+  ],
+  "default_output_modes": [
+    "text/plain",
+    "application/json"
+  ]
+}

examples/review-agent/persona.json

@@ -5,6 +5,17 @@
     "review"
   ],
   "description": "Reviews opened PRs, responds to @mentions in comments, attempts autofix on red CI.",
+  "skills": [
+    {
+      "id": "review-rubric",
+      "source": "https://prpm.dev/packages/@agentworkforce/review-rubric",
+      "description": "Apply a consistent correctness and regression-risk review rubric."
+    }
+  ],
+  "capabilities": {
+    "review": true,
+    "issueClaim": false
+  },
   "cloud": true,
   "useSubscription": true,
   "integrations": {

examples/review-agent/persona.ts

@@ -6,6 +6,17 @@ export default definePersona({
   tags: ['review'],
   description:
     'Reviews opened PRs, responds to @mentions in comments, attempts autofix on red CI.',
+  skills: [
+    {
+      id: 'review-rubric',
+      source: 'https://prpm.dev/packages/@agentworkforce/review-rubric',
+      description: 'Apply a consistent correctness and regression-risk review rubric.'
+    }
+  ],
+  capabilities: {
+    review: true,
+    issueClaim: false
+  },
   cloud: true,
   useSubscription: true,
   // Connection config only — which events fire this agent lives in agent.ts
@@ -16,7 +27,14 @@ export default definePersona({
   },
   memory: {
     enabled: true,
-    scopes: ['workspace']
+    scopes: ['workspace'],
+    trajectories: {
+      enabled: true,
+      autoCompact: true
+    },
+    aiMemory: {
+      enabled: true
+    }
   },
   onEvent: './agent.ts',
   harness: 'codex',

package.json

@@ -23,8 +23,10 @@
     }
   },
   "devDependencies": {
+    "@relaycast/a2a": "^6.2.0",
     "@types/node": "^22.18.0",
     "agent-trajectories": "^0.5.3",
+    "tsx": "^4.23.1",
     "typescript": "^5.9.2"
   },
   "scripts": {
@@ -33,7 +35,8 @@
     "dev:cli": "node packages/cli/dist/cli.js",
     "typecheck": "pnpm -r typecheck && pnpm run typecheck:examples",
     "typecheck:examples": "tsc -p examples/tsconfig.json --noEmit",
-    "test": "node --test scripts/release-workflows.test.mjs && pnpm -r test",
+    "test": "node --test scripts/release-workflows.test.mjs && pnpm -r test && pnpm run test:e2e:agent-card",
+    "test:e2e:agent-card": "pnpm -r build && tsx scripts/e2e-agent-card.ts",
     "lint": "pnpm -r lint",
     "check": "pnpm run lint && pnpm run typecheck && pnpm run test"
   }

packages/cli/src/agent-card-command.test.ts

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { parseAgentCardCommandArgs } from './agent-card-command.js';
+
+test('parseAgentCardCommandArgs parses the shared card contract flags', () => {
+  assert.deepEqual(
+    parseAgentCardCommandArgs([
+      'persona.ts',
+      '--base-url',
+      'https://agent.example.test',
+      '--version=2.0.0',
+      '--documentation-url',
+      'https://docs.example.test/agent',
+      '--input-mode',
+      'application/json',
+      '--input-mode=text/plain',
+      '--output-mode=text/markdown',
+      '--json'
+    ]),
+    {
+      personaPath: 'persona.ts',
+      json: true,
+      options: {
+        baseUrl: 'https://agent.example.test',
+        version: '2.0.0',
+        documentationUrl: 'https://docs.example.test/agent',
+        inputModes: ['application/json', 'text/plain'],
+        outputModes: ['text/markdown']
+      }
+    }
+  );
+});
+
+test('parseAgentCardCommandArgs defaults compile-time deployment values', () => {
+  assert.deepEqual(parseAgentCardCommandArgs(['persona.json']), {
+    personaPath: 'persona.json',
+    json: false,
+    options: { baseUrl: 'http://localhost:3000', version: '0.0.0' }
+  });
+});
+
+test('parseAgentCardCommandArgs rejects missing and extra persona paths', () => {
+  assert.throws(
+    () => parseAgentCardCommandArgs([]),
+    /missing <path\/to\/persona\.ts\|persona\.json>/
+  );
+  assert.throws(
+    () => parseAgentCardCommandArgs(['one.json', 'two.json']),
+    /unexpected argument "two\.json"/
+  );
+});

packages/cli/src/agent-card-command.ts

@@ -0,0 +1,90 @@
+import {
+  deriveAgentCard,
+  type DeriveAgentCardOptions
+} from '@agentworkforce/persona-kit';
+
+import {
+  DEFAULT_COMPILED_AGENT_CARD_OPTIONS,
+  loadParsedPersonaSourceFile,
+  parseAgentCardOptions
+} from './persona-compile.js';
+
+interface Writable {
+  write(chunk: string): unknown;
+}
+
+interface AgentCardCommandDeps {
+  stdout?: Writable;
+}
+
+export async function runAgentCardCommand(
+  args: readonly string[],
+  deps: AgentCardCommandDeps = {}
+): Promise<void> {
+  const stdout = deps.stdout ?? process.stdout;
+  if (args[0] === '-h' || args[0] === '--help') {
+    stdout.write(AGENT_CARD_USAGE);
+    return;
+  }
+
+  const { personaPath, json, options } = parseAgentCardCommandArgs(args);
+  const { persona } = await loadParsedPersonaSourceFile(personaPath);
+  const card = deriveAgentCard(persona, options);
+
+  // MCP's JSON text content uses JSON.stringify without whitespace. Keep the
+  // CLI --json surface byte-identical so either presenter is interchangeable.
+  stdout.write(json ? JSON.stringify(card) : `${JSON.stringify(card, null, 2)}\n`);
+}
+
+export function parseAgentCardCommandArgs(args: readonly string[]): {
+  personaPath: string;
+  json: boolean;
+  options: DeriveAgentCardOptions;
+} {
+  let personaPath: string | undefined;
+  let json = false;
+  const optionArgs: string[] = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--json') {
+      json = true;
+    } else if (arg?.startsWith('--')) {
+      optionArgs.push(arg);
+      if (!arg.includes('=')) {
+        const value = args[++index];
+        if (value !== undefined) optionArgs.push(value);
+      }
+    } else if (!personaPath && arg) {
+      personaPath = arg;
+    } else {
+      throw new Error(`agent-card: unexpected argument "${arg}"`);
+    }
+  }
+
+  if (!personaPath) {
+    throw new Error('agent-card: missing <path/to/persona.ts|persona.json>');
+  }
+
+  return {
+    personaPath,
+    json,
+    options: {
+      ...DEFAULT_COMPILED_AGENT_CARD_OPTIONS,
+      ...parseAgentCardOptions(optionArgs, 'agent-card')
+    }
+  };
+}
+
+const AGENT_CARD_USAGE = `Usage: agentworkforce agent-card <path/to/persona.ts|persona.json> [flags]
+
+Derive a schema-validated A2A agent card from a persona.
+
+Flags:
+  --base-url <url>          Deployed agent origin (default: http://localhost:3000)
+  --version <version>       Deployment/package version (default: 0.0.0)
+  --documentation-url <url> Optional persona documentation URL
+  --input-mode <mime>       Override an input mode; repeat for multiple modes
+  --output-mode <mime>      Override an output mode; repeat for multiple modes
+  --json                     Emit compact JSON matching get_agent_card exactly
+`;

packages/cli/src/cli-impl.ts

@@ -248,7 +248,10 @@ Commands:
                         --json        emit the resolved PersonaSpec as JSON
   persona compile <path/to/persona.ts>
                       Compile a typed persona.ts authoring file to sibling
-                      persona.json after validating it with persona-kit.
+                      persona.json and agent-card.json after validation.
+  agent-card <path> [--base-url <url>] [--version <version>] [--json]
+                      Derive a canonical A2A agent card. Compact --json output
+                      is byte-identical to mcp-workforce get_agent_card.
   install [flags] <pkg|path>
                       Copy persona JSON files from an npm package or local
                       package directory into
@@ -5069,6 +5072,16 @@ export async function main(): Promise<void> {
     }
   }
 
+  if (subcommand === 'agent-card') {
+    try {
+      const { runAgentCardCommand } = await import('./agent-card-command.js');
+      await runAgentCardCommand(rest);
+      return;
+    } catch (err) {
+      die((err as Error)?.message ?? String(err), false);
+    }
+  }
+
   if (subcommand === 'install') {
     runPersonaInstall(rest);
   }

packages/cli/src/cli.test.ts

@@ -729,11 +729,18 @@ test('main: persona compile dispatches to the typed persona compiler', async ()
     );
     assert.equal(exitCode, 0);
     assert.equal(stderr, '');
-    assert.match(stdout, /Compiled .*persona\.ts -> .*persona\.json \(cli-compiled\)/);
+    assert.match(
+      stdout,
+      /Compiled .*persona\.ts -> .*persona\.json, .*agent-card\.json \(cli-compiled\)/
+    );
     const compiled = JSON.parse(readFileSync(join(root, 'persona.json'), 'utf8')) as {
       id: string;
     };
+    const agentCard = JSON.parse(
+      readFileSync(join(root, 'agent-card.json'), 'utf8')
+    ) as { name: string };
     assert.equal(compiled.id, 'cli-compiled');
+    assert.equal(agentCard.name, 'cli-compiled');
   } finally {
     rmSync(root, { recursive: true, force: true });
   }