Skip to content

Commit 21b052d

Browse files
George-iamgeobon
George-iam
and
geobon
authored
docs: publish intent lifecycle continuation guides (#13)
Add non-RPC positioning and MCP+AXME continuation docs, plus a message-to-intent migration guide and quickstart updates for stream/polling/reply_to flows so public integrators can implement durable completion patterns end-to-end. Made-with: Cursor Co-authored-by: George-iam <georgeb@gmail.com>
1 parent 10ac504 commit 21b052d

7 files changed

Lines changed: 172 additions & 9 deletions

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ Canonical OpenAPI specifications live under `docs/openapi/`:
2626
- `docs/public-api-families-d3-users.md`
2727
- `docs/public-api-families-d4-invites-media.md`
2828
- `docs/public-api-families-d5-schemas.md`
29+
- `docs/axme-is-not-rpc.md`
30+
- `docs/mcp-axme-continuation-pattern.md`
31+
- `docs/migration-message-centric-to-intent-lifecycle.md`
2932
- `docs/integration-quickstart.md`
3033
- `docs/external-integrator-dry-run.md`
3134
- `docs/migration-and-deprecation-policy.md`

‎docs/axme-is-not-rpc.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# AXME Is Not RPC
2+
3+
Canonical statement:
4+
5+
- **AXP is the Intent Protocol (durable execution layer).**
6+
7+
This means the API is modeled around durable intent lifecycle state, not synchronous call/return semantics.
8+
9+
## What This Changes
10+
11+
- `POST /v1/intents` records requested outcome and returns `intent_id`.
12+
- Completion is discovered through lifecycle observation, not request blocking.
13+
- Clients can disconnect and reconnect without losing completion visibility.
14+
- Event ordering is protocol-level (`seq`) and replayable (`since`).
15+
16+
## Continuation Delivery (v1)
17+
18+
AXME supports three continuation mechanisms:
19+
20+
- Event stream: `GET /v1/intents/{intent_id}/events/stream`
21+
- Polling: `GET /v1/intents/{intent_id}` and `GET /v1/intents/{intent_id}/events?since=<seq>`
22+
- Deliver-to-inbox: pass `reply_to` on create and observe completion in that inbox
23+
24+
## Design Rules
25+
26+
- Do not model `create_intent` as "remote function call that must finish now".
27+
- Do not rely on HTTP callbacks as the only completion path.
28+
- Treat `intent_id` as the durable join key across retries, observability, and recovery.
29+
- Use idempotency keys for retryable writes and preserve payload identity across replays.
30+
31+
## Anti-Pattern vs Pattern
32+
33+
- Anti-pattern: "submit intent, block until done, fail if socket closes"
34+
- Pattern: "submit intent, persist `intent_id`, resume via stream/poll/inbox"

‎docs/external-integrator-dry-run.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,18 @@ Provide a repeatable public-only verification that a third-party integrator can
1515
- `axme-docs/docs/migration-and-deprecation-policy.md`
1616
- `axme-docs/docs/openapi/gateway.v1.json`
1717
- `axme-docs/docs/integration-quickstart.md`
18+
- `axme-docs/docs/axme-is-not-rpc.md`
19+
- `axme-docs/docs/mcp-axme-continuation-pattern.md`
20+
- `axme-docs/docs/migration-message-centric-to-intent-lifecycle.md`
1821

1922
## Dry-Run Steps
2023

2124
1. Identify required auth headers and token/key semantics from `public-api-auth.md`.
2225
2. Generate client request models from OpenAPI and/or JSON schemas.
2326
3. Implement minimal API flow:
2427
- `POST /v1/intents`
28+
- `GET /v1/intents/{intent_id}/events/stream`
29+
- `GET /v1/intents/{intent_id}/events?since=<seq>`
2530
- `GET /v1/intents/{intent_id}`
2631
- `GET /v1/inbox`
2732
4. Add retry/idempotency behavior for retryable write paths.

‎docs/integration-quickstart.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ Canonical model for this guide:
2626
- `docs/public-api-families-d3-users.md`
2727
- `docs/public-api-families-d4-invites-media.md`
2828
- `docs/public-api-families-d5-schemas.md`
29+
- `docs/axme-is-not-rpc.md`
30+
- `docs/mcp-axme-continuation-pattern.md`
31+
- `docs/migration-message-centric-to-intent-lifecycle.md`
2932

3033
## Step 2: Pick Integration Surface
3134

@@ -40,9 +43,15 @@ Canonical model for this guide:
4043
Recommended baseline:
4144

4245
1. Submit intent (`POST /v1/intents`)
43-
2. Poll/get intent status (`GET /v1/intents/{intent_id}`)
44-
3. Read inbox (`GET /v1/inbox`)
45-
4. Reply/delegate/decision on inbox thread as needed
46+
2. Observe continuation (primary stream):
47+
- `GET /v1/intents/{intent_id}/events/stream`
48+
3. Keep polling fallback:
49+
- `GET /v1/intents/{intent_id}`
50+
- `GET /v1/intents/{intent_id}/events?since=<seq>`
51+
4. Enable offline completion when needed:
52+
- set `reply_to` in `POST /v1/intents`
53+
- consume completion from `GET /v1/inbox?owner_agent=<reply_to>`
54+
5. Reply/delegate/decision on inbox thread as needed
4655

4756
## Step 4: Apply Auth, Limits, and Error Handling
4857

‎docs/mcp-axme-continuation-pattern.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# MCP + AXME Continuation Pattern
2+
3+
Use MCP and AXME together with clear role separation:
4+
5+
- MCP: capability and tool invocation surface.
6+
- AXME: durable continuation and completion observation surface.
7+
8+
## Why Split Responsibilities
9+
10+
- MCP calls can be short-lived and capability-focused.
11+
- Intent execution can be long-lived, stateful, and human-in-the-loop.
12+
- AXME gives a stable continuation contract when initiators disconnect.
13+
14+
## Reference Flow
15+
16+
1. A client or service chooses tool/capability through MCP.
17+
2. The same client submits execution via `POST /v1/intents`.
18+
3. The client tracks lifecycle with one of:
19+
- stream: `/v1/intents/{intent_id}/events/stream`
20+
- polling: `/v1/intents/{intent_id}/events?since=<seq>`
21+
- inbox continuation: `reply_to` on create
22+
4. Terminal event (`intent.completed`, `intent.failed`, `intent.canceled`) closes loop.
23+
24+
## Operational Guidance
25+
26+
- Persist `intent_id` and latest seen `seq`.
27+
- Resume on reconnect with `since=<last_seq>`.
28+
- Keep polling as compatibility fallback when stream transport is unavailable.
29+
- Keep `reply_to` for offline/worker scenarios where persistent stream is not practical.
30+
31+
## Minimal Pseudocode
32+
33+
```text
34+
intent_id = axme.create_intent(...)
35+
for event in axme.observe(intent_id, since=last_seq):
36+
persist(event.seq)
37+
if event.status in {COMPLETED, FAILED, CANCELED}:
38+
break
39+
```

‎docs/migration-message-centric-to-intent-lifecycle.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Migration: Message-Centric to Intent Lifecycle
2+
3+
This guide helps teams move from message/RPC-centric integration patterns to the Intent Protocol lifecycle model.
4+
5+
## Before and After
6+
7+
- Before: "send request, wait synchronously, infer completion from transport success"
8+
- After: "submit intent, track durable lifecycle until terminal state"
9+
10+
## Step 1: Replace Request-Coupled Completion
11+
12+
- Replace blocking request semantics with `intent_id` persistence.
13+
- Store `intent_id`, correlation ID, and idempotency key in your job record.
14+
15+
## Step 2: Adopt Lifecycle Observation
16+
17+
- Add event polling with cursor:
18+
- `GET /v1/intents/{intent_id}/events?since=<seq>`
19+
- Add stream observation where available:
20+
- `GET /v1/intents/{intent_id}/events/stream`
21+
- Keep polling as mandatory fallback path.
22+
23+
## Step 3: Add Offline Continuation
24+
25+
- Provide `reply_to` during create when producer and consumer are decoupled.
26+
- Consume completion from `reply_to` inbox for worker or batch-driven systems.
27+
28+
## Step 4: Normalize Terminal Handling
29+
30+
Treat terminal statuses as protocol truth:
31+
32+
- `COMPLETED`
33+
- `FAILED`
34+
- `CANCELED`
35+
36+
Do not derive terminal outcome from HTTP transport lifecycle.
37+
38+
## Step 5: Harden Retry and Recovery
39+
40+
- Use idempotency keys for all retryable writes.
41+
- Reuse the same key only with byte-identical payload.
42+
- Resume from last acknowledged `seq` after process restarts.
43+
44+
## Cutover Checklist
45+
46+
- [ ] submit path stores `intent_id`
47+
- [ ] stream + polling parity verified
48+
- [ ] `reply_to` path validated for offline completion
49+
- [ ] terminal immutability tested (`second terminal transition -> conflict`)
50+
- [ ] observability dashboards keyed by `intent_id` and `seq`

‎docs/public-api-families-d1-intents-inbox-approvals.md‎

Lines changed: 29 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ This guide covers the first additive parity batch for family-level integration d
44

55
- `intents.create`
66
- `intents.get`
7+
- `intents.events`
8+
- `intents.events.stream`
9+
- `intents.resolve`
710
- `inbox.list`
811
- `inbox.thread`
912
- `inbox.reply`
@@ -29,12 +32,18 @@ Intents are the primary write/read entry for assistant-integrator workflows. Int
2932

3033
- `POST /v1/intents` -> create intent
3134
- `GET /v1/intents/{intent_id}` -> read intent
35+
- `GET /v1/intents/{intent_id}/events` -> list lifecycle events
36+
- `GET /v1/intents/{intent_id}/events/stream` -> stream lifecycle events (SSE)
37+
- `POST /v1/intents/{intent_id}/resolve` -> append terminal lifecycle event
3238

3339
### Canonical schemas
3440

3541
- `axme-spec/schemas/public_api/api.intents.create.request.v1.json`
3642
- `axme-spec/schemas/public_api/api.intents.create.response.v1.json`
3743
- `axme-spec/schemas/public_api/api.intents.get.response.v1.json`
44+
- `axme-spec/schemas/public_api/api.intents.events.list.response.v1.json`
45+
- `axme-spec/schemas/public_api/api.intents.resolve.request.v1.json`
46+
- `axme-spec/schemas/public_api/api.intents.resolve.response.v1.json`
3847

3948
### Request example (`POST /v1/intents`)
4049

@@ -79,14 +88,29 @@ Intents are the primary write/read entry for assistant-integrator workflows. Int
7988

8089
- Python GA: `AxmeClient.create_intent(...)`
8190
- TypeScript GA: `AxmeClient.createIntent(...)`
82-
- Gap to close in Track C parity: direct `intents.get` helper in GA SDKs.
91+
- Python GA:
92+
- `AxmeClient.send_intent(...)`
93+
- `AxmeClient.list_intent_events(...)`
94+
- `AxmeClient.observe(...)`
95+
- `AxmeClient.wait_for(...)`
96+
- `AxmeClient.resolve_intent(...)`
97+
- TypeScript GA:
98+
- `AxmeClient.sendIntent(...)`
99+
- `AxmeClient.listIntentEvents(...)`
100+
- `AxmeClient.observe(...)`
101+
- `AxmeClient.waitFor(...)`
102+
- `AxmeClient.resolveIntent(...)`
83103

84104
### Conformance expectation
85105

86106
- Existing executable checks:
87107
- `intent_create`
88108
- `intent_create_idempotency`
89-
- Track C expansion should add explicit `intents.get` read-shape checks.
109+
- `intents_get`
110+
- `intents_events`
111+
- `intents_stream_resume`
112+
- `intents_resolve`
113+
- `intent_completion_delivery`
90114

91115
## 2) Inbox Family
92116

@@ -246,11 +270,10 @@ Approvals provide explicit workflow decision points for external assistants and
246270

247271
### SDK call mapping
248272

249-
- Python GA: no dedicated helper yet (use direct HTTP path until parity batch lands).
250-
- TypeScript GA: no dedicated helper yet (use direct HTTP path until parity batch lands).
273+
- Python GA: `AxmeClient.decide_approval(...)`
274+
- TypeScript GA: `AxmeClient.decideApproval(...)`
251275
- Beta SDKs (`Go/Java/.NET`): parity pending.
252276

253277
### Conformance expectation
254278

255-
- Not yet covered by an executable conformance check.
256-
- Track C conformance expansion must add `approvals.decision` happy-path and conflict-path checks.
279+
- Executable check: `approvals_decision`.

0 commit comments

Comments
 (0)