Skip to content

Commit 8f09b5d

Browse files
telivity-otaipclaude
telivity-otaip
and
claude
committed
feat(integration): live Duffel availability search through the gates + durable, readable traces
Add @otaip/integration — the caller-facing seam that runs a contracted agent against a live distribution adapter through the existing six pipeline gates, and reads the run's execution + gate trace back by id. No parallel execution or validation path: it wires the real AvailabilitySearch agent (1.1), DuffelAdapter, PipelineOrchestrator, availabilitySearchContract, and ReferenceAgentDataProvider, reusing core's gates, event types, and unified output model. Deliverable 1 — one real adapter path, live sandbox: - runAvailabilitySearch() runs Agent 1.1 via the live Duffel REST API and returns real, normalized offers through the gates. Verified against the Duffel sandbox (JFK->LHR, live_mode:false): 168 offers, all gates pass. - Credentials: the Duffel key is read once at adapter construction from options.duffelApiKey or DUFFEL_API_KEY; never written to events, traces, logs, or returned payloads (asserted by test). Deliverable 2 — durable, readable traces: - Emits the existing agent.executed (gate results + timing) and adapter.health events. - FileEventStore: durable JSONL EventStore composing core's InMemoryEventStore for query/aggregate (single filter implementation, not a fork). - getRunTrace(store, sessionId): by-id trace read-back, proven across a fresh store instance on the same file. Also: - Fix stale duffel-e2e.test.ts (wrong constructor + total_price/itineraries vs the unified price/itinerary model); now passes live 3/3. - Register the new package's tsconfig in both eslint configs; ignore scripts/. - gitignore traces/. - INTEGRATION.md documents adapter execution, trace read, versions/env, and the real sandbox request/response + emitted trace (keys redacted). Booking/ticketing against a live supplier is explicitly NOT claimed; left unstubbed rather than presented as a working "live" result. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 370892b commit 8f09b5d

15 files changed

Lines changed: 1164 additions & 53 deletions

File tree

‎.eslintrc.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"parserOptions": {
55
"ecmaVersion": 2022,
66
"sourceType": "module",
7-
"project": ["./packages/core/tsconfig.json", "./packages/agents/reference/tsconfig.json", "./packages/agents/search/tsconfig.json", "./packages/agents/pricing/tsconfig.json", "./packages/agents/booking/tsconfig.json", "./packages/agents/ticketing/tsconfig.json", "./packages/agents/exchange/tsconfig.json", "./packages/agents/settlement/tsconfig.json", "./packages/agents/reconciliation/tsconfig.json", "./packages/agents/lodging/tsconfig.json", "./packages/agents-tmc/tsconfig.json", "./packages/agents-platform/tsconfig.json", "./packages/adapters/duffel/tsconfig.json", "./packages/connect/tsconfig.json"]
7+
"project": ["./packages/core/tsconfig.json", "./packages/agents/reference/tsconfig.json", "./packages/agents/search/tsconfig.json", "./packages/agents/pricing/tsconfig.json", "./packages/agents/booking/tsconfig.json", "./packages/agents/ticketing/tsconfig.json", "./packages/agents/exchange/tsconfig.json", "./packages/agents/settlement/tsconfig.json", "./packages/agents/reconciliation/tsconfig.json", "./packages/agents/lodging/tsconfig.json", "./packages/agents-tmc/tsconfig.json", "./packages/agents-platform/tsconfig.json", "./packages/adapters/duffel/tsconfig.json", "./packages/connect/tsconfig.json", "./packages/integration/tsconfig.json"]
88
},
99
"plugins": ["@typescript-eslint"],
1010
"extends": [
@@ -20,5 +20,5 @@
2020
"@typescript-eslint/require-await": "off",
2121
"no-console": ["warn", { "allow": ["warn", "error"] }]
2222
},
23-
"ignorePatterns": ["dist", "node_modules", "data", "*.js", "*.mjs", "**/__tests__/**"]
23+
"ignorePatterns": ["dist", "node_modules", "data", "*.js", "*.mjs", "**/__tests__/**", "**/scripts/**"]
2424
}

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# reference data
22
/data/*
33

4+
# OTAIP run/gate traces (durable JSONL written by @otaip/integration)
5+
traces/
6+
47
# Logs
58
logs
69
*.log

‎INTEGRATION.md‎

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
# OTAIP Integration Guide
2+
3+
How to run a contracted OTAIP agent against a **live distribution supplier** through
4+
the six pipeline gates, and how to read the run's **execution + gate trace** back by id.
5+
6+
This guide covers exactly one proven path, end to end:
7+
8+
> **Agent 1.1 — Availability Search → Duffel NDC sandbox → real offers → durable trace**
9+
10+
It is implemented in a single caller-facing package, [`@otaip/integration`](packages/integration),
11+
which wires the **real** components together with **no parallel execution or validation path**:
12+
13+
```
14+
runAvailabilitySearch() ← packages/integration
15+
└─ AvailabilitySearch (Agent 1.1) ← @otaip/agents-search (unchanged)
16+
└─ DuffelAdapter (DistributionAdapter) ← @otaip/adapter-duffel (live Duffel REST)
17+
└─ PipelineOrchestrator.runAgent() ← @otaip/core (the six gates)
18+
└─ availabilitySearchContract ← @otaip/agents-search (Zod + semantic gate)
19+
└─ ReferenceAgentDataProvider ← @otaip/agents-reference (OurAirports data)
20+
└─ agent.executed + adapter.health events → EventStore (in-memory or FileEventStore)
21+
```
22+
23+
The gates, event types, and unified output model are the existing ones in `@otaip/core`.
24+
The integration package only adds the glue function, a durable file-backed `EventStore`,
25+
and a by-id trace reader.
26+
27+
---
28+
29+
## 1. Adapter execution — run Agent 1.1 via Duffel
30+
31+
**Mechanism:** in-process (package import). There is no HTTP server in this path.
32+
33+
```ts
34+
import { runAvailabilitySearch, getRunTrace } from '@otaip/integration';
35+
36+
const result = await runAvailabilitySearch(
37+
{
38+
origin: 'JFK', // IATA, 3 letters
39+
destination: 'LHR', // IATA, 3 letters
40+
departure_date: '2026-07-23', // ISO YYYY-MM-DD, must be in the future
41+
passengers: [{ type: 'ADT', count: 1 }],
42+
cabin_class: 'economy', // economy | premium_economy | business | first
43+
currency: 'GBP', // optional ISO 4217 (see sandbox note below)
44+
max_results: 3,
45+
sort_by: 'price',
46+
},
47+
{
48+
duffelApiKey: process.env.DUFFEL_API_KEY, // see "Credentials" below
49+
// eventStore, reference, adapter, now are all optional — sensible defaults
50+
},
51+
);
52+
53+
if (result.ok) {
54+
console.log(result.output.offers.length, 'offers'); // unified SearchOffer[]
55+
} else {
56+
console.error(result.failure.reason, result.failure.issues); // gate rejection
57+
}
58+
```
59+
60+
### Input shape — `AvailabilitySearchInput`
61+
62+
The input is Agent 1.1's own contract input (`@otaip/agents-search`), validated by the
63+
`schema_in` Zod gate and the `semantic_in` gate before the adapter is ever called:
64+
65+
| Field | Type | Required | Notes |
66+
|------------------|----------------------------------------|----------|-------|
67+
| `origin` | `string` (len 3) | yes | resolved against reference data (semantic gate) |
68+
| `destination` | `string` (len 3) | yes | must differ from `origin` |
69+
| `departure_date` | `string` `YYYY-MM-DD` | yes | must not be in the past (semantic gate) |
70+
| `return_date` | `string` `YYYY-MM-DD` | no | if set, must be ≥ `departure_date` |
71+
| `passengers` | `{ type: 'ADT'\|'CHD'\|'INF'\|…; count: number }[]` | yes | ≥ 1 |
72+
| `cabin_class` | `'economy'\|'premium_economy'\|'business'\|'first'` | no | |
73+
| `currency` | `string` (len 3) | no | ISO 4217 |
74+
| `max_connections`, `direct_only`, `max_results`, `sort_by`, `sort_order`, `sources` | various | no | see [types.ts](packages/agents/search/src/availability-search/types.ts) |
75+
76+
### Credentials-injection contract
77+
78+
The Duffel API key is read **once, at adapter construction**, from either:
79+
80+
1. **`options.duffelApiKey`** passed to `runAvailabilitySearch`, **or**
81+
2. **`process.env.DUFFEL_API_KEY`** if (1) is omitted (the `DuffelAdapter` default).
82+
83+
A `duffel_test_…` key targets the **sandbox**; a `duffel_live_…` key targets **production**.
84+
The environment is determined by the key prefix, not by code.
85+
86+
**The key is server-side only.** It is never written to an event, a trace, a log line, or
87+
the returned payload. The trace contains only `OtaipEvent` objects (gate booleans, timing,
88+
adapter id, status) — there is no field that can carry a credential or PII. The offline test
89+
[`run-search.test.ts`](packages/integration/src/__tests__/run-search.test.ts) asserts the
90+
on-disk trace file never matches `/duffel_test_|duffel_live_|Bearer/`.
91+
92+
To target a different supplier or a recorded-fixture server, inject a pre-built adapter:
93+
`runAvailabilitySearch(input, { adapter: myAdapter })` (then `duffelApiKey` is ignored).
94+
95+
### Output shape — `RunSearchResult`
96+
97+
```ts
98+
interface RunSearchResult {
99+
sessionId: string; // use this to read the trace back
100+
ok: boolean; // true ⇔ every gate passed
101+
output?: AvailabilitySearchOutput; // present iff ok (the unified model)
102+
failure?: { reason: string; failureClass: 'infra'|'execution'|'validation'; issues: SemanticIssue[] };
103+
trace: RunTrace; // also durably in eventStore
104+
eventStore: EventStore; // the store this run wrote to
105+
}
106+
```
107+
108+
`output` is the existing unified output model — `AvailabilitySearchOutput` with
109+
`offers: SearchOffer[]` (`offer_id`, `source`, `itinerary`, `price`, …), `total_raw_offers`,
110+
`source_status[]`, `truncated`. The Duffel adapter normalizes the raw NDC response into this
111+
model; nothing here forks the shape.
112+
113+
`failureClass` distinguishes an infrastructure/setup problem (`infra`) from a real agent
114+
execution error (`execution`) from a genuine contract-gate rejection (`validation`) — so a
115+
caller never mistakes a wiring bug for a data/model rejection.
116+
117+
> **Runtime note:** the default `ReferenceAgentDataProvider` loads airport data from
118+
> `${process.cwd()}/data/reference/airports.json`. Run `pnpm run data:download` once, and
119+
> invoke from the **repo root** (or pass your own `reference` provider). If the data is
120+
> missing, the run fails at the semantic gate, not silently.
121+
122+
---
123+
124+
## 2. Trace read — fetch a run's trace by id
125+
126+
**Mechanism:** in-process API over the same `EventStore` the run wrote to.
127+
128+
```ts
129+
import { getRunTrace, FileEventStore } from '@otaip/integration';
130+
131+
// Durable: a DIFFERENT process can re-open the same file and read the trace by id.
132+
const store = await FileEventStore.open('./traces/run.jsonl');
133+
const result = await runAvailabilitySearch(input, { eventStore: store });
134+
135+
// …later, anywhere with access to the file:
136+
const reopened = await FileEventStore.open('./traces/run.jsonl');
137+
const trace = await getRunTrace(reopened, result.sessionId);
138+
```
139+
140+
`getRunTrace(store, sessionId)` is a pure projection over the event store (no re-execution).
141+
Auth for the trace is **the same as filesystem access to the JSONL file** (or to whichever
142+
`EventStore` backend you supply) — there is no separate auth surface in this in-process path.
143+
144+
### Trace response shape — `RunTrace`
145+
146+
```ts
147+
interface RunTrace {
148+
sessionId: string;
149+
outcome: 'ok' | 'rejected' | 'empty';
150+
agentExecutions: {
151+
agentId: string; success: boolean; confidence: number; durationMs: number;
152+
timestamp: string; gateResults: { gate: string; passed: boolean }[];
153+
}[];
154+
adapterHealth: { adapterId: string; status: 'healthy'|'degraded'|'unhealthy'; latencyMs?: number; timestamp: string }[];
155+
events: OtaipEvent[]; // raw, chronological — the durable source of truth
156+
}
157+
```
158+
159+
The underlying events are the existing core types: `agent.executed` (gate results + timing,
160+
emitted exactly as the `agentToTool` bridge does) and `adapter.health` (derived from the real
161+
search's per-source status). `EventStore.query({ sessionId })` / `.aggregate()` are the
162+
existing core APIs; `FileEventStore` reuses core's `InMemoryEventStore` for them and only adds
163+
durable JSONL persistence.
164+
165+
---
166+
167+
## 3. Package versions & environment
168+
169+
All packages are workspace version **`0.7.2`** (Node **≥ 24.14.1**, pnpm 10):
170+
171+
| Package | Role |
172+
|--------------------------|------|
173+
| `@otaip/integration@0.7.2` | the entry point in this guide (new) |
174+
| `@otaip/core@0.7.2` | gates, event types, unified model |
175+
| `@otaip/adapter-duffel@0.7.2` | live Duffel REST adapter |
176+
| `@otaip/agents-search@0.7.2` | Agent 1.1 + contract |
177+
| `@otaip/agents-reference@0.7.2` | airport/airline reference provider |
178+
179+
**Environment variables a caller must set:**
180+
181+
| Var | Required | Purpose |
182+
|-----|----------|---------|
183+
| `DUFFEL_API_KEY` | yes (unless `options.duffelApiKey` is passed) | Duffel token; `duffel_test_…` = sandbox, `duffel_live_…` = production |
184+
185+
One-time data setup: `pnpm run data:download` (populates `data/reference/` from OurAirports;
186+
gitignored). No other new env vars are introduced.
187+
188+
### Reproduce the proof yourself
189+
190+
```bash
191+
pnpm install
192+
pnpm run data:download # one-time reference data
193+
export DUFFEL_API_KEY=duffel_test_xxx # your sandbox key
194+
pnpm exec tsx packages/integration/scripts/duffel-search.ts # run from repo root
195+
```
196+
197+
Source: [`scripts/duffel-search.ts`](packages/integration/scripts/duffel-search.ts).
198+
199+
---
200+
201+
## 4. Sandbox proof (real Duffel sandbox, keys redacted)
202+
203+
Captured **2026-06-23** against `https://api.duffel.com` with a `duffel_test_…` key
204+
(`live_mode: false`). Route **JFK → LHR**, `2026-07-23`, 1 ADT, economy.
205+
206+
### 4a. Request the adapter POSTs to `POST /air/offer_requests?return_offers=true`
207+
208+
```json
209+
{
210+
"data": {
211+
"slices": [{ "origin": "JFK", "destination": "LHR", "departure_date": "2026-07-23" }],
212+
"passengers": [{ "type": "adult" }],
213+
"cabin_class": "economy",
214+
"return_offers": true
215+
}
216+
}
217+
```
218+
219+
Headers (key redacted): `Authorization: Bearer duffel_test_***REDACTED***`,
220+
`Duffel-Version: v2`, `Content-Type: application/json`.
221+
222+
### 4b. Real Duffel response (first offer, trimmed — `live_mode: false` confirms sandbox)
223+
224+
```json
225+
{
226+
"offer_request_id": "orq_0000B7dFlto81bmCx4mQXw",
227+
"offer": {
228+
"id": "off_0000B7dFlu2f9ZP1g9a2CY",
229+
"total_amount": "215.74",
230+
"total_currency": "USD",
231+
"base_amount": "182.83",
232+
"tax_amount": "32.91",
233+
"live_mode": false,
234+
"slices": [{
235+
"origin": "JFK", "destination": "LHR", "duration": "PT7H58M",
236+
"segments": [{
237+
"marketing_carrier": "ZZ", "flight_number": "7611",
238+
"origin": "JFK", "destination": "LHR",
239+
"departing_at": "2026-07-23T17:01:00", "arriving_at": "2026-07-24T05:59:00",
240+
"cabin": "economy"
241+
}]
242+
}]
243+
},
244+
"total_offers": 168
245+
}
246+
```
247+
248+
### 4c. Normalized output via `runAvailabilitySearch` (gates PASS, 168 raw offers → top 3)
249+
250+
```
251+
Gate outcome: PASS (all gates)
252+
Session id: sess_mqqxj2pe_bsunoc
253+
Raw offers: 168 | returned: 3
254+
255+
1. off_0000B7dF1KBJAIvVkG0qB8 BA0107 JFK→LHR dep 2026-07-23T17:01:00 215.15 USD (0 stop(s), 478m)
256+
2. off_0000B7dF1KAxBcdvj9qYcs ZZ7611 JFK→LHR dep 2026-07-23T17:01:00 228.95 USD (0 stop(s), 478m)
257+
3. off_0000B7dF1KBJAIvVkG0qBB IB3177 JFK→LHR dep 2026-07-23T17:01:00 229.96 USD (0 stop(s), 478m)
258+
259+
source_status: [{ "source": "duffel", "success": true, "offer_count": 168, "response_time_ms": 2054 }]
260+
```
261+
262+
> **Sandbox note (honest):** `currency: 'GBP'` was requested but the Duffel sandbox returned
263+
> offers in **USD**. The unified model faithfully reports whatever the supplier returns; OTAIP
264+
> does not coerce it. `ZZ` is Duffel's sandbox test airline ("Duffel Airways"); real carriers
265+
> (BA, IB) also appear because the sandbox blends fixture and live-schedule data.
266+
267+
### 4d. Real emitted trace for that run (durable JSONL, read back by session id)
268+
269+
The exact two lines written to `traces/duffel-jfk-lhr-2026-07-23.jsonl` — no secrets, no PII:
270+
271+
```json
272+
{"eventId":"evt_mqqxj4aj_1","type":"agent.executed","timestamp":"2026-06-23T17:39:50.779Z","sessionId":"sess_mqqxj2pe_bsunoc","agentId":"1.1","inputHash":"6fcd2f57","confidence":1,"durationMs":2057,"success":true,"gateResults":[{"gate":"intent_lock","passed":true},{"gate":"schema_in","passed":true},{"gate":"semantic_in","passed":true},{"gate":"cross_agent","passed":true},{"gate":"execute","passed":true},{"gate":"schema_out","passed":true},{"gate":"confidence","passed":true},{"gate":"action_class","passed":true}]}
273+
{"eventId":"evt_mqqxj4ak_2","type":"adapter.health","timestamp":"2026-06-23T17:39:50.780Z","sessionId":"sess_mqqxj2pe_bsunoc","adapterId":"duffel","status":"healthy","latencyMs":2054}
274+
```
275+
276+
`getRunTrace(store, 'sess_mqqxj2pe_bsunoc')` projects this into:
277+
278+
```json
279+
{
280+
"sessionId": "sess_mqqxj2pe_bsunoc",
281+
"outcome": "ok",
282+
"agentExecutions": [{
283+
"agentId": "1.1", "success": true, "confidence": 1, "durationMs": 2057,
284+
"timestamp": "2026-06-23T17:39:50.779Z",
285+
"gateResults": [
286+
{ "gate": "intent_lock", "passed": true }, { "gate": "schema_in", "passed": true },
287+
{ "gate": "semantic_in", "passed": true }, { "gate": "cross_agent", "passed": true },
288+
{ "gate": "execute", "passed": true }, { "gate": "schema_out", "passed": true },
289+
{ "gate": "confidence", "passed": true }, { "gate": "action_class", "passed": true }
290+
]
291+
}],
292+
"adapterHealth": [{ "adapterId": "duffel", "status": "healthy", "latencyMs": 2054, "timestamp": "2026-06-23T17:39:50.780Z" }]
293+
}
294+
```
295+
296+
---
297+
298+
## What runs end to end vs. what does not
299+
300+
- ✅ **Live**: Duffel sandbox **availability search** (Agent 1.1) → real, normalized offers,
301+
through all six gates, with a durable, re-readable trace. Verified above and by the live e2e
302+
test [`duffel-e2e.test.ts`](packages/adapters/duffel/src/__tests__/duffel-e2e.test.ts)
303+
(runs when `DUFFEL_API_KEY` is set; skipped otherwise).
304+
- ⛔ **Not claimed**: booking/ticketing against a live supplier. The Duffel adapter has
305+
`book()`, but creating real orders needs more than a sandbox search key (payment/balance
306+
setup, passenger PII handling, order-management lifecycle) and is **not** proven here. It is
307+
left unstubbed rather than presented as a working "live" result.
308+
309+
### Note for maintainers
310+
311+
The previous `duffel-e2e.test.ts` was **stale**: it constructed `new DuffelAdapter({ apiKey })`
312+
(the real constructor is positional `(apiKey?, baseUrl?)` with `DUFFEL_API_KEY` fallback) and
313+
asserted on `offer.total_price` / `offer.itineraries`, which the unified model does not have
314+
(`offer.price` / `offer.itinerary`). It could not compile or pass against the shipped adapter.
315+
It has been corrected to the real API and unified output model, and now passes live (3/3).

‎eslint.config.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ export default defineConfig([
1818
"**/*.js",
1919
"**/*.mjs",
2020
"**/__tests__/**/*",
21+
"**/scripts/**",
2122
]), {
2223

2324
plugins: {
@@ -47,6 +48,7 @@ export default defineConfig([
4748
"./packages/adapters/hotelbeds/tsconfig.json",
4849
"./packages/connect/tsconfig.json",
4950
"./packages/cli/tsconfig.json",
51+
"./packages/integration/tsconfig.json",
5052
],
5153
},
5254
},

0 commit comments

Comments
 (0)