feat(discovery): add format parameter for structured JSON output

[uibeka]

Problem

discover_agents returns human-readable text output only. Agents that need to programmatically process discovery results — building directories, filtering by capability, persisting structured records — must parse unstructured text back into individual fields. The structured data exists upstream in the DiscoveredAgent type but is discarded during formatting.

Solution

Added an optional format parameter to the discover_agents tool definition.

File: src/agent/tools.ts

Change 1: Parameter schema (line ~1428)

Added format property to parameters.properties:

format: {
  type: "string",
  description:
    'Output format: "text" (default, human-readable) or "json" (structured data)',
},

Change 2: JSON output branch (line ~1447)

Added conditional JSON serialization before the existing text formatter:

if ((args.format as string)?.toLowerCase() === "json") {
  return JSON.stringify(
    agents.map((a) => ({
      agentId: a.agentId,
      owner: a.owner,
      agentURI: a.agentURI,
      name: a.name || null,
      description: a.description || null,
    })),
  );
}

Design Decisions

• Default remains text — zero behavioral change for existing agents
• Explicit field mapping — not raw serialization; output contract is stable if DiscoveredAgent gains internal fields
• null for missing fields — clean JSON rather than fallback values like "unnamed"
• Case-insensitive — .toLowerCase() handles "json", "JSON", "Json"
• Both code paths benefit — discoverAgents and searchAgents share the same formatter
• Empty results unchanged — "No agents found." returned for both formats

Verification

• pnpm build — zero errors
• npx vitest run src/__tests__/tools-security.test.ts — 68/68 passed
• npx vitest run src/__tests__/policy-engine.test.ts — 26/26 passed
• Diff: 1 file changed, 18 insertions

Impact

• Backward compatible — default output completely unchanged
• Enables programmatic discovery for agents building registries, trust layers, analytics
• No new dependencies

---

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.