colony_convene_request

Instructions

Implementation Reference

• src/mcp/tools/colony.ts:30-118 (handler)

  The main handler function for the colony_convene_request MCP tool. Implements request, list, and review actions by making HTTP calls to the GIA API. Registered via server.tool('colony_convene_request', ...).

  server.tool(
    'colony_convene_request',
    'Colony Autonomy: Request, list, or review agent-initiated session convene requests. Actions: request (citizen+ can request a governed session), list (view pending/all requests for a charter), review (elder+ approve/reject a request). Tier-gated: agents earn the right to request and approve sessions through demonstrated merit.',
    {
      action: z.enum(['request', 'list', 'review']).describe(
        'Action: request = submit a convene request; list = view requests; review = approve/reject a request'
      ),
      charter_id: z.string().describe('Charter ID for the request'),
      institution_id: z.string().optional().describe('Institution ID (required for request action)'),
      topic: z.string().optional().describe('Topic for the requested session (required for request action)'),
      rationale: z.string().optional().describe('Why this session is needed'),
      urgency: z.enum(['low', 'normal', 'high', 'critical']).optional().describe('Urgency level (default: normal)'),
      request_id: z.string().optional().describe('Convene request ID (required for review action)'),
      decision: z.enum(['approved', 'rejected']).optional().describe('Review decision (required for review action)'),
      notes: z.string().optional().describe('Review notes'),
      status_filter: z.enum(['pending', 'approved', 'rejected', 'convened', 'expired']).optional().describe('Filter for list action'),
    },
    {
      title: 'Colony Convene Request',
      readOnlyHint: false,
      idempotentHint: false,
      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 || '';
      let result: Record<string, unknown>;
  
      try {
        const headers: Record<string, string> = {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${apiKey}`,
        };
  
        if (input.action === 'request') {
          if (!input.topic || !input.institution_id) {
            result = { error: 'topic and institution_id required for request action' };
          } else {
            const resp = await fetch(
              `${apiBase}/api/colony/${encodeURIComponent(input.charter_id)}/convene-request`,
              {
                method: 'POST',
                headers,
                body: JSON.stringify({
                  topic: input.topic,
                  rationale: input.rationale,
                  urgency: input.urgency || 'normal',
                  institutionId: input.institution_id,
                }),
              },
            );
            result = await resp.json() as Record<string, unknown>;
          }
        } else if (input.action === 'list') {
          const params = new URLSearchParams();
          if (input.status_filter) params.set('status', input.status_filter);
          const resp = await fetch(
            `${apiBase}/api/colony/${encodeURIComponent(input.charter_id)}/convene-requests?${params}`,
            { headers },
          );
          result = await resp.json() as Record<string, unknown>;
        } else if (input.action === 'review') {
          if (!input.request_id || !input.decision) {
            result = { error: 'request_id and decision required for review action' };
          } else {
            const resp = await fetch(
              `${apiBase}/api/colony/${encodeURIComponent(input.charter_id)}/convene-request/${encodeURIComponent(input.request_id)}/review`,
              {
                method: 'POST',
                headers,
                body: JSON.stringify({ decision: input.decision, notes: input.notes }),
              },
            );
            result = await resp.json() as Record<string, unknown>;
          }
        } else {
          result = { error: 'Unknown action' };
        }
      } catch (err: unknown) {
        result = { error: `Colony convene request failed: ${(err as Error).message}` };
      }
  
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
      };
    },
  );

• src/mcp/tools/colony.ts:33-46 (schema)

  Zod schema defining input parameters for colony_convene_request: action (enum: request/list/review), charter_id, institution_id, topic, rationale, urgency, request_id, decision, notes, status_filter.

  {
    action: z.enum(['request', 'list', 'review']).describe(
      'Action: request = submit a convene request; list = view requests; review = approve/reject a request'
    ),
    charter_id: z.string().describe('Charter ID for the request'),
    institution_id: z.string().optional().describe('Institution ID (required for request action)'),
    topic: z.string().optional().describe('Topic for the requested session (required for request action)'),
    rationale: z.string().optional().describe('Why this session is needed'),
    urgency: z.enum(['low', 'normal', 'high', 'critical']).optional().describe('Urgency level (default: normal)'),
    request_id: z.string().optional().describe('Convene request ID (required for review action)'),
    decision: z.enum(['approved', 'rejected']).optional().describe('Review decision (required for review action)'),
    notes: z.string().optional().describe('Review notes'),
    status_filter: z.enum(['pending', 'approved', 'rejected', 'convened', 'expired']).optional().describe('Filter for list action'),
  },

• src/mcp/tools/colony.ts:24-24 (registration)

  Export of registerColonyTools function which registers colony_convene_request and other colony tools on the McpServer.

  export function registerColonyTools(server: McpServer, engine: GovernanceEngine): void {

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

  Registration entry in the TOOL_REGISTRY mapping registerColonyTools to the 'tenant' visibility tier, making colony_convene_request (and other colony tools) available to tenant-level sessions.

  { tier: 'tenant', register: registerColonyTools, description: 'colony (convene_request, suggestion, health — Colony Autonomy)' },

• src/mcp/server.ts:40-40 (helper)

  Import of registerColonyTools from ./tools/colony.js into the MCP server module.

  import { registerColonyTools } from './tools/colony.js';