agent_citizenship_status

Instructions

Implementation Reference

• src/mcp/tools/citizenship.ts:22-104 (handler)

  The main handler function that defines the 'agent_citizenship_status' MCP tool. It registers the tool with McpServer, accepts 'action', 'agent_id', and 'limit' parameters, and supports three actions: status (GET citizenship data), assess (POST to trigger merit re-evaluation), and leaderboard (GET top agents by merit). It proxies requests to the GIA Express API and returns results as JSON text content.

  export function registerCitizenshipTools(server: McpServer, engine: GovernanceEngine): void {
    server.tool(
      'agent_citizenship_status',
      'Query agent citizenship tier and merit score (Colony Layer 5). Actions: status (view citizenship and metrics), assess (trigger merit re-evaluation), leaderboard (top agents by merit). Agents earn trust through deliberation quality, behavioral health, gate approval rates, and responsible rights exercise.',
      {
        action: z.enum(['status', 'assess', 'leaderboard']).describe(
          'Action: status = view agent citizenship; assess = trigger merit assessment; leaderboard = top agents'
        ),
        agent_id: z.string().optional().describe('Agent ID (required for status and assess)'),
        limit: z.number().min(1).max(50).optional().describe('Max results for leaderboard (default: 10)'),
      },
      {
        title: 'Agent Citizenship & Merit',
        readOnlyHint: false,
        idempotentHint: true,
        destructiveHint: false,
        openWorldHint: false,
      } as Record<string, unknown>,
      async (input) => {
        const apiBase = process.env.GIA_API_URL || 'http://localhost:3001';
        // GIA_INTERNAL_API_KEY = server-side name; GIA_API_KEY = MCP container name (same value)
        const apiKey = process.env.GIA_INTERNAL_API_KEY || process.env.GIA_API_KEY || '';
        const authHeaders = {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
        };
        let result: Record<string, unknown>;
  
        try {
          if (input.action === 'status') {
            if (!input.agent_id) {
              result = { error: 'agent_id required for status action' };
            } else {
              const resp = await fetch(`${apiBase}/api/citizenship/${encodeURIComponent(input.agent_id)}`, { headers: authHeaders });
              if (!resp.ok) {
                const body = await resp.json() as Record<string, unknown>;
                result = { error: body.error || `HTTP ${resp.status}`, agentId: input.agent_id };
              } else {
                result = await resp.json() as Record<string, unknown>;
              }
            }
          } else if (input.action === 'assess') {
            if (!input.agent_id) {
              result = { error: 'agent_id required for assess action' };
            } else {
              const resp = await fetch(`${apiBase}/api/citizenship/${encodeURIComponent(input.agent_id)}/assess`, {
                method: 'POST',
                headers: authHeaders,
              });
              if (!resp.ok) {
                const body = await resp.json() as Record<string, unknown>;
                result = { error: body.error || `HTTP ${resp.status}`, agentId: input.agent_id };
              } else {
                result = await resp.json() as Record<string, unknown>;
              }
            }
          } else if (input.action === 'leaderboard') {
            const limit = input.limit ?? 10;
            const resp = await fetch(`${apiBase}/api/citizenship/leaderboard?limit=${limit}`, { headers: authHeaders });
            if (!resp.ok) {
              result = { error: `Leaderboard request failed (HTTP ${resp.status})` };
            } else {
              result = await resp.json() as Record<string, unknown>;
            }
          } else {
            result = { error: `Unknown action: ${input.action}` };
          }
        } catch (err: unknown) {
          result = {
            error: 'Failed to query citizenship — GIA Express API may be unreachable',
            detail: err instanceof Error ? err.message : String(err),
          };
        }
  
        // Telemetry
        engine.telemetryService.emitToolCall('agent_citizenship_status', `cit-${Date.now().toString(36)}`, 'INFORMATIONAL', true);
  
        return {
          content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
        };
      }
    );
  }

• src/mcp/tools/citizenship.ts:26-32 (schema)

  Input schema for the tool using Zod validation. Defines: 'action' (enum of status/assess/leaderboard, required), 'agent_id' (optional string, required for status and assess), and 'limit' (optional number 1-50, default 10 for leaderboard).

  {
    action: z.enum(['status', 'assess', 'leaderboard']).describe(
      'Action: status = view agent citizenship; assess = trigger merit assessment; leaderboard = top agents'
    ),
    agent_id: z.string().optional().describe('Agent ID (required for status and assess)'),
    limit: z.number().min(1).max(50).optional().describe('Max results for leaderboard (default: 10)'),
  },

• src/mcp/server.ts:115-115 (registration)

  Registration entry in the TOOL_REGISTRY array. Maps the registerCitizenshipTools function to the 'tenant' visibility tier with description 'agent_citizenship_status (Colony Layer 5 — merit-based trust)'.

  { tier: 'tenant', register: registerCitizenshipTools, description: 'agent_citizenship_status (Colony Layer 5 — merit-based trust)' },

• src/mcp/server.ts:38-38 (registration)

  Import statement for the registerCitizenshipTools function from './tools/citizenship.js'.

  import { registerCitizenshipTools } from './tools/citizenship.js';

• src/onboarding/generate-client-config.ts:214-214 (helper)

  Reference to agent_citizenship_status in the onboarding client config generator, listing it as a Colony tool.

  | Colony | agent_citizenship_status, agent_rights, colony_health, colony_suggestion |