composio

Composio Governance Wrapper

@matimo/composio gives you governed, auditable access to Composio's tool catalog — Jira, Linear, Asana, Google Workspace, Microsoft 365, Salesforce, and dozens of other toolkits — without giving up Matimo's policy engine, risk classification, or human-in-the-loop (HITL) approval flow.

Every tool in this package is named composio_<toolkit>_<action> (e.g. composio_jira_get_issue, composio_linear_create_linear_issue) and proxies exactly one Composio action via Composio's REST execute endpoint. These tool definitions are generated by scripts/generate-tools.ts — do not hand-edit tools/composio_*/definition.yaml files; adjust scripts/risk-overrides.json and re-run the generator instead.

How a composio_* Call Works

Agent calls composio_jira_get_issue(
  composio_user_id: "...",
  composio_connected_account_id: "...",
  issue_id_or_key: "PROJ-123"
)
        │
        ▼
Matimo's standard policy checks run (canExecute: deprecation, draft
status, requires_approval + role checks) — see "Risk Levels" below for
what the explicit `risk:` field does and does not gate automatically.
        │
        ▼
HTTP POST https://backend.composio.dev/api/v3/tools/execute/JIRA_GET_ISSUE
  headers: { "x-api-key": <COMPOSIO_API_KEY> }
  body: {
    user_id: composio_user_id,
    connected_account_id: composio_connected_account_id,
    arguments: { _matimo_tool: "composio_jira_get_issue", issue_id_or_key: "PROJ-123" }
  }
        │
        ▼
Response envelope: { success, data: { data, error, successful } }

arguments._matimo_tool is a generated marker (always present, even when every other argument is omitted) — Composio's execute endpoint requires the arguments key to exist in the request body, and Matimo's HTTP executor drops empty nested objects. Ignore this field; it carries no semantic meaning beyond keeping arguments non-empty and tagging Composio-side logs with the originating Matimo tool name.

Every Tool Needs Three Things