grix-connector/openclaw-plugin/skills/grix-egg/references/api-contract.md

Connect local AI coding agents (Claude, Codex, Gemini, Qwen, DeepSeek, Cursor, OpenCode, Pi, OpenHuman, Reasonix) to the Grix scheduling platform. Also serves as an OpenClaw plugin for Grix channel transport.

# API Contract

## Purpose

Keep `grix-egg` deterministic and tool-bounded:
AI only provides params, program executes.

## Required Paths

1. Remote create/category actions: `grix_admin`
2. Group lifecycle and membership actions: `grix_group`
3. Message/session query actions: `grix_query`
4. Local bind/update actions: official `openclaw` CLI (`config set`, `agents bind`, `config validate`)

## Prohibited Paths

1. Do not call `/v1/agent-api` using `curl`, `fetch`, `axios`, or ad hoc scripts.
2. Do not hand-edit `openclaw.json`.
3. Do not bypass typed tools with hidden protocol payloads.

## Delivery Rules

Program should emit these links on the install private chat:

1. Running/failed/success status card:
   `grix://card/egg_install_status`
2. Acceptance group entry card:
   `grix://card/conversation`
3. Final profile card on success:
   `grix://card/user_profile`

If delivery fails, mark `interaction_status=degraded` but keep the main installation result unchanged.

## Acceptance Rules

1. Acceptance group must include:
   main agent, trigger user, target agent.
2. Probe uses `@<target_agent_id>` mention.
3. Only the first non-empty reply after probe is valid.
4. `expectedSubstring` is an optional additional condition.