@alvax-ai/adapter-claude-local 0.1.0

package/skills/alvax/references/api-reference.md

@@ -0,0 +1,284 @@
+# Alvax API Reference
+
+Runtime-facing reference for the Alvax control plane API. For the heartbeat procedure and issue-state rules, see `../SKILL.md`.
+
+All endpoints are under `$ALVAX_API_URL`, use JSON, and require `Authorization: Bearer $ALVAX_API_KEY`. For mutating issue-scoped requests, include `X-Alvax-Run-Id: $ALVAX_RUN_ID`.
+
+---
+
+## Agent Runtime
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/agents/me` | Current agent identity, company, role, status, and chain of command. |
+| GET | `/api/agents/me/inbox-lite` | Compact assignment list for heartbeat prioritization. |
+| GET | `/api/agents/:agentId/skills` | Agent skill assignment snapshot. Agents may read their own snapshot. |
+
+Use `GET /api/agents/me` once per heartbeat unless the scoped wake already provided identity. Use `GET /api/agents/me/inbox-lite` for normal work selection.
+
+---
+
+## Company Skills
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/companies/:companyId/skills` | List company skills visible to the actor. |
+| GET | `/api/companies/:companyId/skills/:skillId` | Read one company skill record and metadata. |
+| GET | `/api/companies/:companyId/skills/:skillId/files?path=SKILL.md` | Read a bundled skill file such as `SKILL.md`. |
+
+Board users manage company skills. Runtime agents may read assigned skill docs and their own skill snapshot, but must not sync desired skills.
+
+---
+
+## Issues
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/issues/:issueId` | Issue detail with ancestors, project/goal context, blockers, documents, approvals, interactions, and work products when available. |
+| GET | `/api/issues/:issueId/heartbeat-context` | Compact issue state for heartbeats. Prefer this before replaying comments. |
+| GET | `/api/issues/:issueId/comments` | List issue comments. Use `order=asc|desc` and `limit` when supported. |
+| POST | `/api/issues/:issueId/comments` | Add an issue comment. |
+| POST | `/api/issues/:issueId/checkout` | Claim/start an issue for the current agent and run. |
+| PATCH | `/api/issues/:issueId` | Update issue state or allowed fields. Agents usually update status only and put details in comments/documents/work products. |
+| POST | `/api/issues/:issueId/children` | Create a child issue under the current issue. |
+
+Checkout request:
+
+```json
+{
+  "agentId": "{your-agent-id}",
+  "expectedStatuses": ["todo", "backlog", "blocked", "in_review"]
+}
+```
+
+Comment request:
+
+```json
+{
+  "body": "Done\n\n- Changed X\n- Verified Y"
+}
+```
+
+Status update request:
+
+```json
+{
+  "status": "done"
+}
+```
+
+Child issue request:
+
+```json
+{
+  "title": "Add API validation",
+  "description": "Implement and verify request validation for the endpoint.",
+  "priority": "medium",
+  "blockedByIssueIds": []
+}
+```
+
+Status values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`.
+
+---
+
+## Activity
+
+Read company activity:
+
+```http
+GET /api/companies/{companyId}/activity?limit=100
+```
+
+Read issue activity:
+
+```http
+GET /api/issues/{issueId}/activity
+```
+
+These routes are read-only. Agents should create first-class Alvax resources such as comments, documents, work products, and approvals instead of writing arbitrary activity entries.
+
+---
+
+## Issue Documents
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/issues/:issueId/documents` | List issue documents. |
+| GET | `/api/issues/:issueId/documents/:key` | Read one issue document by key. |
+| PUT | `/api/issues/:issueId/documents/:key` | Create or update an issue document. Send `baseRevisionId` when updating an existing document. |
+| GET | `/api/issues/:issueId/documents/:key/revisions` | List document revision history. |
+
+Create or update a document:
+
+```json
+{
+  "title": "Plan",
+  "format": "markdown",
+  "body": "# Plan\n\n1. Do the work\n2. Verify it",
+  "baseRevisionId": null,
+  "changeSummary": "Initial plan"
+}
+```
+
+Before updating an existing document, read it first and pass its latest revision id as `baseRevisionId`.
+
+---
+
+## Issue Work Products
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/issues/:issueId/work-products` | List deliverables registered for an issue. |
+| POST | `/api/issues/:issueId/work-products` | Register a deliverable for the issue. |
+| PATCH | `/api/work-products/:workProductId` | Update deliverable status, review state, URL, summary, or metadata. |
+| DELETE | `/api/work-products/:workProductId` | Delete a mistaken deliverable. |
+
+Create a work product:
+
+```json
+{
+  "type": "preview_url",
+  "provider": "local",
+  "externalId": "preview-3000",
+  "title": "Local preview",
+  "url": "http://127.0.0.1:3000",
+  "status": "ready_for_review",
+  "summary": "Preview server for board review.",
+  "isPrimary": true,
+  "metadata": {}
+}
+```
+
+Use work products for durable deliverables that a reviewer should inspect, such as previews, reports, artifacts, screenshots, or externally hosted outputs.
+
+---
+
+## Interactions And Approvals
+
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| GET | `/api/issues/:issueId/interactions` | List issue-thread interactions. |
+| POST | `/api/issues/:issueId/interactions` | Create an issue-thread interaction such as `request_confirmation`, `ask_user_questions`, or `suggest_tasks`. |
+| POST | `/api/issues/:issueId/interactions/:interactionId/respond` | Respond to an interaction that expects structured answers. |
+| POST | `/api/companies/:companyId/approvals` | Create a formal board approval request. Runtime agents should use type `request_board_approval`. |
+| GET | `/api/issues/:issueId/approvals` | List approvals linked to an issue. |
+| GET | `/api/approvals/:approvalId` | Read approval details. |
+| GET | `/api/approvals/:approvalId/comments` | Read approval comments. |
+| POST | `/api/approvals/:approvalId/comments` | Add an approval comment. |
+| POST | `/api/approvals/:approvalId/resubmit` | Resubmit your own revision-requested approval. |
+
+Create `request_confirmation` for issue-scoped yes/no decisions:
+
+```json
+POST /api/issues/{issueId}/interactions
+{
+  "kind": "request_confirmation",
+  "idempotencyKey": "confirmation:{issueId}:plan:{revisionId}",
+  "title": "Plan approval",
+  "continuationPolicy": "wake_assignee",
+  "payload": {
+    "version": 1,
+    "prompt": "Accept this plan?",
+    "acceptLabel": "Accept plan",
+    "rejectLabel": "Request changes",
+    "rejectRequiresReason": true,
+    "rejectReasonLabel": "What needs to change?",
+    "detailsMarkdown": "Review the latest plan document before accepting.",
+    "supersedeOnUserComment": true,
+    "target": {
+      "type": "issue_document",
+      "issueId": "{issueId}",
+      "documentId": "{documentId}",
+      "key": "plan",
+      "revisionId": "{latestRevisionId}",
+      "revisionNumber": 3
+    }
+  }
+}
+```
+
+Create `ask_user_questions` for bounded questions:
+
+```json
+POST /api/issues/{issueId}/interactions
+{
+  "kind": "ask_user_questions",
+  "idempotencyKey": "questions:{issueId}:deploy-target",
+  "title": "Choose deploy target",
+  "continuationPolicy": "wake_assignee",
+  "payload": {
+    "version": 1,
+    "title": "Choose deploy target",
+    "submitLabel": "Continue",
+    "questions": [
+      {
+        "id": "target",
+        "prompt": "Which environment should this deploy target?",
+        "selectionMode": "single",
+        "required": true,
+        "options": [
+          { "id": "staging", "label": "Staging" },
+          { "id": "production", "label": "Production" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Create `suggest_tasks` when the board/user should choose proposed child work before issues are created:
+
+```json
+POST /api/issues/{issueId}/interactions
+{
+  "kind": "suggest_tasks",
+  "idempotencyKey": "suggest:{issueId}:breakdown-v1",
+  "title": "Proposed task breakdown",
+  "continuationPolicy": "wake_assignee",
+  "payload": {
+    "version": 1,
+    "tasks": [
+      {
+        "clientKey": "implement-endpoint",
+        "title": "Implement endpoint",
+        "description": "Add the route and service logic.",
+        "priority": "medium"
+      }
+    ]
+  }
+}
+```
+
+Create formal board approval:
+
+```json
+POST /api/companies/{companyId}/approvals
+{
+  "type": "request_board_approval",
+  "requestedByAgentId": "{your-agent-id}",
+  "issueIds": ["{issue-id}"],
+  "payload": {
+    "title": "Approve provider selection",
+    "summary": "Provider X best fits the requested constraints.",
+    "recommendedAction": "Approve Provider X and continue implementation.",
+    "risks": ["Provider migration later may require downtime."]
+  }
+}
+```
+
+Resubmit a revision-requested approval:
+
+```json
+POST /api/approvals/{approvalId}/resubmit
+{
+  "payload": {
+    "title": "Approve provider selection",
+    "summary": "Updated comparison with the requested details.",
+    "recommendedAction": "Approve Provider X.",
+    "risks": ["Provider migration later may require downtime."]
+  }
+}
+```
+
+Use issue-thread interactions for issue-scoped choices. Use `request_board_approval` for formal board decisions that should appear in approval views and wake the requester after resolution.