board_convene_session

Instructions

Implementation Reference

• src/mcp/tools/institution.ts:207-234 (handler)

  The handler function for the board_convene_session tool. Calls the backend API POST /api/institution/{institution_id}/charter/{charter_id}/convene with topic and context, then returns the session_id and status.

    async (args) => {
      try {
        const data = await apiCall(
          `/api/institution/${args.institution_id}/charter/${args.charter_id}/convene`,
          'POST',
          {
            topic:       args.topic,
            context:     args.context,
            triggeredBy: 'mcp-client',
          }
        ) as any;
  
        return {
          content: [{ type: 'text' as const, text: JSON.stringify({
            session_id:     data.sessionId || data.session_id,
            charter_id:     args.charter_id,
            institution_id: args.institution_id,
            topic:          args.topic,
            status:         data.status || 'running',
            message:        data.message || 'Session convened — deliberation in progress',
            next_step:      `Call board_get_session with session_id "${data.sessionId || data.session_id}" to retrieve the deliberation output. Sessions typically complete in 30–90 seconds.`,
          }, null, 2) }],
        };
      } catch (err: unknown) {
        return boardErrorResponse(err);
      }
    }
  );

• src/mcp/tools/institution.ts:200-205 (schema)

  Input schema for board_convene_session: required institution_id, charter_id, topic; optional context string.

  {
    institution_id: z.string().describe('Institution ID'),
    charter_id:     z.string().describe('Charter ID of the board or committee to convene'),
    topic:          z.string().describe('The question, decision, or matter to deliberate on. Be specific — this is what every seat will reason about.'),
    context:        z.string().optional().describe('Additional background context, documents, or data to inject into all seat prompts'),
  },

• src/mcp/tools/institution.ts:197-234 (registration)

  Registration of the tool via server.tool('board_convene_session', ...) with description, schema, metadata flags, and handler.

  server.tool(
    'board_convene_session',
    'Convene a governed deliberation session for a charter. Each seat (AI model with a specific role) deliberates on the topic according to the charter\'s mode (parallel/chain/adversarial/roundtable/auto). Returns a session_id — use board_get_session to retrieve the output once complete. Typical runtime: 30–120 seconds depending on seat count and mode.',
    {
      institution_id: z.string().describe('Institution ID'),
      charter_id:     z.string().describe('Charter ID of the board or committee to convene'),
      topic:          z.string().describe('The question, decision, or matter to deliberate on. Be specific — this is what every seat will reason about.'),
      context:        z.string().optional().describe('Additional background context, documents, or data to inject into all seat prompts'),
    },
    { title: 'Convene Governed Session', readOnlyHint: false, idempotentHint: false, destructiveHint: false, openWorldHint: false },
    async (args) => {
      try {
        const data = await apiCall(
          `/api/institution/${args.institution_id}/charter/${args.charter_id}/convene`,
          'POST',
          {
            topic:       args.topic,
            context:     args.context,
            triggeredBy: 'mcp-client',
          }
        ) as any;
  
        return {
          content: [{ type: 'text' as const, text: JSON.stringify({
            session_id:     data.sessionId || data.session_id,
            charter_id:     args.charter_id,
            institution_id: args.institution_id,
            topic:          args.topic,
            status:         data.status || 'running',
            message:        data.message || 'Session convened — deliberation in progress',
            next_step:      `Call board_get_session with session_id "${data.sessionId || data.session_id}" to retrieve the deliberation output. Sessions typically complete in 30–90 seconds.`,
          }, null, 2) }],
        };
      } catch (err: unknown) {
        return boardErrorResponse(err);
      }
    }
  );

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

  Registration of registerInstitutionTools in the TENANT tier tool registry, which includes board_convene_session as part of the board tools group.

  { tier: 'tenant', register: (server, _engine) => registerInstitutionTools(server), description: 'board (list_institutions, list_charters, convene_session, get_session, install_kit)' },

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

  Onboarding config listing board_convene_session under the 'Reasoning' category for client configuration.

  | Reasoning | chain_of_reasoning, board_convene_session, board_search_precedent |
  | Colony | agent_citizenship_status, agent_rights, colony_health, colony_suggestion |
  | Phoenix Recovery | phoenix_snapshot, phoenix_verify_integrity, phoenix_recovery_health |
  | Value Metrics | record_value_metric, record_governance_event, generate_impact_report |
  | SRT | srt_run_watchdog, srt_diagnose, srt_approve_repair, srt_generate_postmortem |