@oxap/sdk 0.0.0-stage → 0.1.0-alpha.33
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +575 -2
- package/dist/src/abort_signal.d.ts +5 -0
- package/dist/src/abort_signal.js +52 -0
- package/dist/src/auth_protocol.d.ts +67 -0
- package/dist/src/auth_protocol.js +113 -0
- package/dist/src/binary_resolver.d.ts +29 -0
- package/dist/src/binary_resolver.js +207 -0
- package/dist/src/execution_client.d.ts +23 -0
- package/dist/src/execution_client.js +7 -0
- package/dist/src/execution_types.d.ts +204 -0
- package/dist/src/execution_types.js +28 -0
- package/dist/src/index.d.ts +9 -0
- package/dist/src/index.js +30 -0
- package/dist/src/logger.d.ts +8 -0
- package/dist/src/logger.js +16 -0
- package/dist/src/models_types.d.ts +75 -0
- package/dist/src/models_types.js +14 -0
- package/dist/src/oap_client.d.ts +64 -0
- package/dist/src/oap_client.js +1023 -0
- package/dist/src/timeout_diagnostics.d.ts +22 -0
- package/dist/src/timeout_diagnostics.js +44 -0
- package/package.json +43 -3
package/README.md
CHANGED
|
@@ -1,3 +1,576 @@
|
|
|
1
|
-
#
|
|
1
|
+
# OAP TypeScript SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
TypeScript SDK published as `@oxap/sdk`. The default client spawns `oapx serve agent,provider --stdio` and speaks OAP v0.1 on both profiles: agent sessions and authentication on `agent-control-core`, direct inference and provider model discovery on `model-provider-core`.
|
|
4
|
+
|
|
5
|
+
`createOapClient()` is the preferred entry point. `createMakaiClient()` remains an alias for it.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @oxap/sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
No release has been published yet; until one is, install from a checkout of this repository.
|
|
14
|
+
|
|
15
|
+
The package is a library and ships no executable, so you also need the runtime binary. It optionally depends on `@oxap/cli` at its own version, which carries the runtime for the platform; failing that, it uses a local build under `zig-out/bin/oxap` or `zig/zig-out/bin/oxap`, then `oxap` on `PATH`, and the `oapx` names keep resolving in every step. See [Configuration](#configuration) for explicit binary resolver options.
|
|
16
|
+
|
|
17
|
+
## Quick start
|
|
18
|
+
|
|
19
|
+
Create a client, resolve a model, send one chat message, and print the assistant response.
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import { createMakaiClient } from "@oxap/sdk";
|
|
23
|
+
|
|
24
|
+
async function main(): Promise<void> {
|
|
25
|
+
const client = await createMakaiClient();
|
|
26
|
+
|
|
27
|
+
try {
|
|
28
|
+
const { model } = await client.models.resolve({
|
|
29
|
+
provider_id: "anthropic",
|
|
30
|
+
api: "anthropic-messages",
|
|
31
|
+
model_id: "claude-sonnet-4-5",
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
const response = await client.provider.complete({
|
|
35
|
+
model_ref: model.model_ref,
|
|
36
|
+
messages: [{ role: "user", content: "Write a haiku about streams." }],
|
|
37
|
+
options: { max_tokens: 128 },
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
const content = response.message.content;
|
|
41
|
+
console.log(typeof content === "string" ? content : JSON.stringify(content, null, 2));
|
|
42
|
+
} finally {
|
|
43
|
+
await client.close();
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
main().catch((error: unknown) => {
|
|
48
|
+
console.error(error);
|
|
49
|
+
process.exitCode = 1;
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Streaming completions
|
|
54
|
+
|
|
55
|
+
Use `client.provider.stream(...)` for provider-level streaming. It is the SDK's streaming form of `complete`; each `text_delta` contains newly generated text.
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
import { createMakaiClient } from "@oxap/sdk";
|
|
59
|
+
|
|
60
|
+
async function main(): Promise<void> {
|
|
61
|
+
const client = await createMakaiClient();
|
|
62
|
+
|
|
63
|
+
try {
|
|
64
|
+
const { model } = await client.models.resolve({
|
|
65
|
+
provider_id: "anthropic",
|
|
66
|
+
api: "anthropic-messages",
|
|
67
|
+
model_id: "claude-sonnet-4-5",
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
for await (const event of client.provider.stream({
|
|
71
|
+
model_ref: model.model_ref,
|
|
72
|
+
messages: [{ role: "user", content: "Explain lock-free queues in one paragraph." }],
|
|
73
|
+
options: { max_tokens: 256 },
|
|
74
|
+
})) {
|
|
75
|
+
switch (event.type) {
|
|
76
|
+
case "message_start":
|
|
77
|
+
console.error(`Streaming ${event.provider_id ?? "provider"}/${event.model_id ?? "model"}`);
|
|
78
|
+
break;
|
|
79
|
+
case "text_delta":
|
|
80
|
+
process.stdout.write(event.delta);
|
|
81
|
+
break;
|
|
82
|
+
case "thinking_delta":
|
|
83
|
+
// Reasoning output is surfaced separately from normal text.
|
|
84
|
+
break;
|
|
85
|
+
case "tool_call":
|
|
86
|
+
console.error(`\nTool call requested: ${event.name}(${event.arguments_json})`);
|
|
87
|
+
break;
|
|
88
|
+
case "message_end":
|
|
89
|
+
process.stdout.write("\n");
|
|
90
|
+
console.error("Stop reason:", event.stop_reason);
|
|
91
|
+
break;
|
|
92
|
+
case "error":
|
|
93
|
+
throw new Error(event.message);
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
} finally {
|
|
97
|
+
await client.close();
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
void main();
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
If you are migrating from an API that used `client.complete({ stream: true })`, the equivalent call is `client.provider.stream(request)`; non-streaming calls use `client.provider.complete(request)`.
|
|
105
|
+
|
|
106
|
+
## Agent runs and model switching
|
|
107
|
+
|
|
108
|
+
Use `client.agent.run(...)` for an agent session, or `client.agent.stream(...)` for lifecycle and content events. A run naming `options.session_id` opens that session the first time and submits into it after that, so a later run carries only the new messages: the endpoint keeps the history. A session's tools, `reasoning_effort` and `max_tokens` are fixed when it opens; a later run that omits them keeps them, and one that names different ones fails with `OapUnsupportedFeatureError`. `switchModel(sessionId, modelRef)` changes the selected model of an open session; `runSelected(sessionId, messages)` uses that selection on the next run. An agent request's `tools` are provided to the session at open (`action.tools.provide`), owned by the SDK's participant `sdk`; when the model calls one, the SDK runs its `execute` callback and answers with `action.call.resolve.request`, and a tool without `execute` is answered with an error. Against an endpoint that does not advertise `action.tools.provide`, a request with tools fails with `OapUnsupportedFeatureError` before the open rather than having its tools ignored, and once a tool has run, an `auto_once` auth failure is not retried, so the tool is not run twice. The stream yields `tool_execution_start` and `tool_execution_end` for every call, the endpoint's own tools included. An agent run's `reasoning_effort` becomes the session's reasoning level and `max_tokens` (an integer from 1 to 4294967295) the oapx output limit, both at open, the output limit only on the `oapx.agent` endpoint that reads it (elsewhere `OapUnsupportedFeatureError`); `temperature` and `reasoning_effort: "minimal"` fail with `OapUnsupportedFeatureError`, since the agent loop takes no temperature and runs minimal as low. The open also turns off the loop's `request_user_input` tool, which the SDK cannot answer, and an abort stops waiting on a tool that is still running. Direct provider calls may carry declaration-only tools, but client-side `execute` callbacks are unsupported there.
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
import { createOapClient } from "@oxap/sdk";
|
|
112
|
+
|
|
113
|
+
async function main(): Promise<void> {
|
|
114
|
+
const client = await createOapClient();
|
|
115
|
+
|
|
116
|
+
try {
|
|
117
|
+
const { model } = await client.models.resolve({
|
|
118
|
+
provider_id: "anthropic",
|
|
119
|
+
api: "anthropic-messages",
|
|
120
|
+
model_id: "claude-sonnet-4-5",
|
|
121
|
+
});
|
|
122
|
+
|
|
123
|
+
const response = await client.agent.run({
|
|
124
|
+
model_ref: model.model_ref,
|
|
125
|
+
messages: [{ role: "user", content: "Say hello." }],
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
console.log(response.message.content);
|
|
129
|
+
} finally {
|
|
130
|
+
await client.close();
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
void main();
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
For agent streaming, iterate over `client.agent.stream(request)` and handle `agent_start`, content deltas, and the terminal `agent_end` event. Tools with an `execute` callback run in your process when the endpoint advertises `action.tools.provide`.
|
|
138
|
+
|
|
139
|
+
### Agent model discovery
|
|
140
|
+
|
|
141
|
+
`client.agent.models` is a compatibility alias for the provider model catalog exposed as `client.models` on the same OAP connection.
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
import { createMakaiClient } from "@oxap/sdk";
|
|
145
|
+
|
|
146
|
+
async function main(): Promise<void> {
|
|
147
|
+
const client = await createMakaiClient();
|
|
148
|
+
|
|
149
|
+
// Both read the provider model catalog on the same OAP connection:
|
|
150
|
+
const { models } = await client.models.list();
|
|
151
|
+
const { models: agentModels } = await client.agent.models.list();
|
|
152
|
+
|
|
153
|
+
void models;
|
|
154
|
+
void agentModels;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
void main;
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Prefer `client.models` when you only need model discovery. Use `client.agent.models` when chaining discovery with an agent call on the same namespace.
|
|
161
|
+
|
|
162
|
+
## Auth
|
|
163
|
+
|
|
164
|
+
Use `client.auth.listProviders()` to inspect auth state, and `client.auth.login(providerId, handlers)` to start a browser login flow. Token material and manual-code answers stay within the runtime; no answer travels in an OAP envelope. A flow requiring manual input without a host-owned input path fails with `auth_input_unavailable`. `openai-codex` offers two ways at once: its URL is the ChatGPT sign-in, which returns to a `localhost:1455` callback the runtime listens on, and its instructions also give `https://auth.openai.com/codex/device` and a one-time code for signing in from any other device, which needs device code login turned on in ChatGPT's security settings (or by a workspace admin). Whichever finishes first completes the login. `anthropic` signs in through a browser on the same computer: its URL returns to a `localhost` callback the runtime listens on (macOS and Linux). Where no browser can reach that computer, give the runtime a Claude subscription token, such as one from `claude setup-token`, as `ANTHROPIC_AUTH_TOKEN` in its environment.
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
import { createMakaiClient, type MakaiAuthEvent } from "@oxap/sdk";
|
|
168
|
+
|
|
169
|
+
async function main(): Promise<void> {
|
|
170
|
+
const client = await createMakaiClient();
|
|
171
|
+
|
|
172
|
+
try {
|
|
173
|
+
const providers = await client.auth.listProviders();
|
|
174
|
+
const anthropic = providers.find((provider) => provider.id === "anthropic");
|
|
175
|
+
|
|
176
|
+
if (anthropic?.auth_status !== "authenticated") {
|
|
177
|
+
await client.auth.login("anthropic", {
|
|
178
|
+
onEvent(event: MakaiAuthEvent): void {
|
|
179
|
+
if (event.type === "auth_url") {
|
|
180
|
+
console.log(`Open ${event.url}`);
|
|
181
|
+
if (event.instructions) console.log(event.instructions);
|
|
182
|
+
} else if (event.type === "progress") {
|
|
183
|
+
console.log(event.message);
|
|
184
|
+
}
|
|
185
|
+
},
|
|
186
|
+
});
|
|
187
|
+
}
|
|
188
|
+
} finally {
|
|
189
|
+
await client.close();
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
void main();
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
You can also configure automatic one-shot auth retry for `provider` and `agent` calls:
|
|
197
|
+
|
|
198
|
+
```ts
|
|
199
|
+
import { createMakaiClient } from "@oxap/sdk";
|
|
200
|
+
|
|
201
|
+
async function main(): Promise<void> {
|
|
202
|
+
const client = await createMakaiClient({
|
|
203
|
+
auth: {
|
|
204
|
+
auth_retry_policy: "auto_once",
|
|
205
|
+
handlers: {
|
|
206
|
+
onEvent: (event) => {
|
|
207
|
+
if (event.type === "auth_url") console.log(`Open ${event.url}`);
|
|
208
|
+
},
|
|
209
|
+
},
|
|
210
|
+
},
|
|
211
|
+
});
|
|
212
|
+
|
|
213
|
+
try {
|
|
214
|
+
// Calls that hit auth_required can now trigger one login attempt automatically.
|
|
215
|
+
} finally {
|
|
216
|
+
await client.close();
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
void main();
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## Models
|
|
224
|
+
|
|
225
|
+
Models are discovered through `client.models`. Use `model_ref` from the returned descriptor in completion and agent requests. Treat `model_ref` as opaque; do not parse or construct it in application code.
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
import { createMakaiClient } from "@oxap/sdk";
|
|
229
|
+
|
|
230
|
+
async function main(): Promise<void> {
|
|
231
|
+
const client = await createMakaiClient();
|
|
232
|
+
|
|
233
|
+
try {
|
|
234
|
+
const { models, fetched_at_ms, cache_max_age_ms } = await client.models.list({
|
|
235
|
+
provider_id: "anthropic",
|
|
236
|
+
include_login_required: true,
|
|
237
|
+
});
|
|
238
|
+
|
|
239
|
+
console.log(`Fetched ${models.length} models at ${new Date(fetched_at_ms).toISOString()}`);
|
|
240
|
+
console.log(`Cache max age: ${cache_max_age_ms}ms`);
|
|
241
|
+
|
|
242
|
+
for (const model of models) {
|
|
243
|
+
console.log(`${model.display_name}: ${model.model_ref} [${model.auth_status}]`);
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
const resolved = await client.models.resolve({
|
|
247
|
+
provider_id: "anthropic",
|
|
248
|
+
api: "anthropic-messages",
|
|
249
|
+
model_id: "claude-sonnet-4-5",
|
|
250
|
+
});
|
|
251
|
+
|
|
252
|
+
console.log("Use this model_ref:", resolved.model.model_ref);
|
|
253
|
+
} finally {
|
|
254
|
+
await client.close();
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
void main();
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
## Configuration
|
|
262
|
+
|
|
263
|
+
`createOapClient(...)` and `createMakaiClient(...)` accept stdio transport and binary resolver options.
|
|
264
|
+
|
|
265
|
+
### Explicit binary path
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
import { createMakaiClient } from "@oxap/sdk";
|
|
269
|
+
|
|
270
|
+
async function main(): Promise<void> {
|
|
271
|
+
const client = await createMakaiClient({
|
|
272
|
+
resolver: {
|
|
273
|
+
binaryPath: "/opt/oapx/bin/oapx",
|
|
274
|
+
},
|
|
275
|
+
});
|
|
276
|
+
|
|
277
|
+
try {
|
|
278
|
+
// Use client.provider, client.agent, client.auth, or client.models here.
|
|
279
|
+
} finally {
|
|
280
|
+
await client.close();
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
void main();
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
You can also set `OXAP_SDK_BINARY_PATH=/opt/oxap/bin/oxap`, which outranks the
|
|
288
|
+
legacy `OAP_SDK_BINARY_PATH=/opt/oapx/bin/oapx`.
|
|
289
|
+
|
|
290
|
+
### Download from URL with checksum
|
|
291
|
+
|
|
292
|
+
```ts
|
|
293
|
+
import { createMakaiClient } from "@oxap/sdk";
|
|
294
|
+
|
|
295
|
+
async function main(): Promise<void> {
|
|
296
|
+
const client = await createMakaiClient({
|
|
297
|
+
resolver: {
|
|
298
|
+
binaryUrl: "https://example.com/releases/oapx-darwin-arm64",
|
|
299
|
+
checksumSha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
|
300
|
+
cacheDir: "/tmp/oapx-bin-cache",
|
|
301
|
+
},
|
|
302
|
+
});
|
|
303
|
+
|
|
304
|
+
try {
|
|
305
|
+
// Use client.provider, client.agent, client.auth, or client.models here.
|
|
306
|
+
} finally {
|
|
307
|
+
await client.close();
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
void main();
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Environment variable equivalents are `OXAP_SDK_BINARY_URL` and
|
|
315
|
+
`OXAP_SDK_BINARY_SHA256`, with the legacy `OAP_SDK_BINARY_URL` and
|
|
316
|
+
`OAP_SDK_BINARY_SHA256` still read. Each environment URL takes the checksum
|
|
317
|
+
written beside it, so a checksum is never borrowed across the two pairs;
|
|
318
|
+
`checksumSha256` from the resolver options is the fallback for any URL, and a
|
|
319
|
+
URL passed as `resolver.binaryUrl` takes either environment checksum, the OXAP
|
|
320
|
+
one first, then `checksumSha256`.
|
|
321
|
+
|
|
322
|
+
### PATH lookup and local builds
|
|
323
|
+
|
|
324
|
+
With no resolver options, the SDK checks, in order:
|
|
325
|
+
|
|
326
|
+
1. The platform package `@oxap/cli` installs (`@oxap/cli-<platform>-<arch>`), then the legacy `@oap-sdk/cli-<platform>-<arch>`, when present: `oxap`, then `oapx` in each
|
|
327
|
+
2. `./zig-out/bin/oxap`, `./zig/zig-out/bin/oxap`, `./zig-out/bin/oapx`, then `./zig/zig-out/bin/oapx`
|
|
328
|
+
3. `oxap` on `PATH`, then `oapx`
|
|
329
|
+
|
|
330
|
+
On Windows each name carries an `.exe` suffix.
|
|
331
|
+
|
|
332
|
+
Step 1 outranks both local build paths, so an installed platform package wins over a fresh `zig build`. It arrives as the optional dependency `@oxap/cli` at the SDK's own version, so a plain install gets a runtime unless the platform is unsupported; npm skips an optional dependency it cannot satisfy. Set `OXAP_SDK_BINARY_PATH` (or `resolver.binaryPath`) to pin an exact binary; the legacy `OAP_SDK_BINARY_PATH` still resolves.
|
|
333
|
+
|
|
334
|
+
The client initializes the agent profile and describes the provider profile. `responseTimeoutMs` bounds the reply to each request; `frameTimeoutMs` bounds auth event waits. A running agent run or provider inference has no idle limit by default, because a tool or a reasoning model can be silent for minutes; set `idleTimeoutMs` to give up after that long without an event, which also cancels the run, or pass an `AbortSignal` to stop it yourself. A failed connection closes the spawned process.
|
|
335
|
+
|
|
336
|
+
```ts
|
|
337
|
+
import { createMakaiClient } from "@oxap/sdk";
|
|
338
|
+
|
|
339
|
+
async function main(): Promise<void> {
|
|
340
|
+
const client = await createMakaiClient({
|
|
341
|
+
// Optional transport settings:
|
|
342
|
+
args: ["serve", "agent,provider", "--stdio"],
|
|
343
|
+
cwd: process.cwd(),
|
|
344
|
+
env: { ...process.env, OAPX_LOG: "info" },
|
|
345
|
+
handshakeTimeoutMs: 2_000,
|
|
346
|
+
responseTimeoutMs: 30_000,
|
|
347
|
+
frameTimeoutMs: 30_000,
|
|
348
|
+
});
|
|
349
|
+
|
|
350
|
+
try {
|
|
351
|
+
// Use client.provider, client.agent, client.auth, or client.models here.
|
|
352
|
+
} finally {
|
|
353
|
+
await client.close();
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
void main();
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
`args` can name a harness backend instead, such as `["serve", "agent", "--stdio", "--backend", "claude"]`. Such an endpoint serves the agent profile alone: the client connects to it and runs agents through it, and `client.provider` and `client.models` fail with `OapUnsupportedFeatureError`. The SDK does not answer permission requests yet, so a run on a backend that asks one waits until a timeout or an abort ends it.
|
|
361
|
+
|
|
362
|
+
Close clients when done:
|
|
363
|
+
|
|
364
|
+
```ts
|
|
365
|
+
async function closeClient(client: { close(): Promise<void> }): Promise<void> {
|
|
366
|
+
await client.close();
|
|
367
|
+
}
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
## Cancellation
|
|
371
|
+
|
|
372
|
+
Pass an `AbortSignal` as `options.signal` to cancel a `provider` or `agent` call; these reject with an `Error` whose `name` is `"AbortError"`. `client.auth.login(providerId, handlers, { signal })` also accepts a signal and reports cancellation as `MakaiAuthError` with `kind: "cancelled"`.
|
|
373
|
+
|
|
374
|
+
```ts
|
|
375
|
+
import { createMakaiClient, isAbortError } from "@oxap/sdk";
|
|
376
|
+
|
|
377
|
+
async function main(): Promise<void> {
|
|
378
|
+
const client = await createMakaiClient();
|
|
379
|
+
const { model } = await client.models.resolve({
|
|
380
|
+
provider_id: "anthropic",
|
|
381
|
+
api: "anthropic-messages",
|
|
382
|
+
model_id: "claude-sonnet-4-5",
|
|
383
|
+
});
|
|
384
|
+
|
|
385
|
+
const controller = new AbortController();
|
|
386
|
+
setTimeout(() => controller.abort(), 5_000);
|
|
387
|
+
|
|
388
|
+
try {
|
|
389
|
+
for await (const event of client.provider.stream({
|
|
390
|
+
model_ref: model.model_ref,
|
|
391
|
+
messages: [{ role: "user", content: "Explain lock-free queues." }],
|
|
392
|
+
options: { signal: controller.signal },
|
|
393
|
+
})) {
|
|
394
|
+
if (event.type === "text_delta") process.stdout.write(event.delta);
|
|
395
|
+
}
|
|
396
|
+
} catch (error: unknown) {
|
|
397
|
+
if (!isAbortError(error)) throw error;
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
void main;
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
Leaving an OAP stream early also cancels it: the SDK sends a best-effort `inference.cancel.request` for direct inference or `run.cancel.request` for an agent run.
|
|
405
|
+
|
|
406
|
+
## Error handling
|
|
407
|
+
|
|
408
|
+
The SDK exports error classes for common failure surfaces:
|
|
409
|
+
|
|
410
|
+
- `MakaiStreamError` — provider, stream, transport, or unknown failures while running `provider` or `agent` calls, including a call made on a closed transport (`kind: "transport_error"`). Aborts do **not** use this class; see [Cancellation](#cancellation).
|
|
411
|
+
- `MakaiAuthRequiredError` — specialized `MakaiStreamError` for `auth_required` failures. It includes `provider_id`.
|
|
412
|
+
- `MakaiProtocolError` — models API protocol failures such as `invalid_request`, malformed responses, or request `nack`s. A `client.models` call made on a closed transport rejects with a plain `Error` instead.
|
|
413
|
+
- `MakaiAuthError` — auth provider listing and login failures. The `kind` can be `provider_error`, `cancelled`, `transport_error`, or `unknown`.
|
|
414
|
+
- `StdioProtocolError` — handshake failures from `connect()`, such as a protocol `version_mismatch`. A handshake timeout rejects with a plain `Error`.
|
|
415
|
+
|
|
416
|
+
```ts
|
|
417
|
+
import {
|
|
418
|
+
MakaiAuthError,
|
|
419
|
+
MakaiAuthRequiredError,
|
|
420
|
+
MakaiProtocolError,
|
|
421
|
+
MakaiStreamError,
|
|
422
|
+
createMakaiClient,
|
|
423
|
+
} from "@oxap/sdk";
|
|
424
|
+
|
|
425
|
+
async function run(): Promise<void> {
|
|
426
|
+
const client = await createMakaiClient();
|
|
427
|
+
|
|
428
|
+
try {
|
|
429
|
+
const { model } = await client.models.resolve({
|
|
430
|
+
provider_id: "anthropic",
|
|
431
|
+
api: "anthropic-messages",
|
|
432
|
+
model_id: "claude-sonnet-4-5",
|
|
433
|
+
});
|
|
434
|
+
|
|
435
|
+
await client.provider.complete({
|
|
436
|
+
model_ref: model.model_ref,
|
|
437
|
+
messages: [{ role: "user", content: "Hello" }],
|
|
438
|
+
});
|
|
439
|
+
} catch (error: unknown) {
|
|
440
|
+
if (error instanceof MakaiAuthRequiredError) {
|
|
441
|
+
console.error(`Login required for ${error.provider_id}`);
|
|
442
|
+
} else if (error instanceof MakaiStreamError) {
|
|
443
|
+
console.error(`Stream failed (${error.kind}/${error.code ?? "no-code"}): ${error.message}`);
|
|
444
|
+
} else if (error instanceof MakaiProtocolError) {
|
|
445
|
+
console.error(`Protocol failed (${error.code ?? "no-code"}): ${error.message}`);
|
|
446
|
+
} else if (error instanceof MakaiAuthError) {
|
|
447
|
+
console.error(`Auth failed (${error.kind}/${error.code ?? "no-code"}): ${error.message}`);
|
|
448
|
+
} else {
|
|
449
|
+
throw error;
|
|
450
|
+
}
|
|
451
|
+
} finally {
|
|
452
|
+
await client.close();
|
|
453
|
+
}
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
void run();
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
## TypeScript types
|
|
460
|
+
|
|
461
|
+
Public types are exported from the package root and generated in `dist/src/index.d.ts` when you run `npm run build:sdk`. Key API types include:
|
|
462
|
+
|
|
463
|
+
```ts
|
|
464
|
+
import type {
|
|
465
|
+
AgentRunRequest,
|
|
466
|
+
AgentRunResponse,
|
|
467
|
+
AgentStreamEvent,
|
|
468
|
+
AuthFlowHandlers,
|
|
469
|
+
AuthStatus,
|
|
470
|
+
BinaryResolverOptions,
|
|
471
|
+
ChatMessage,
|
|
472
|
+
CompletionResponse,
|
|
473
|
+
ContentPart,
|
|
474
|
+
CreateMakaiClientOptions,
|
|
475
|
+
ListModelsRequest,
|
|
476
|
+
ListModelsResponse,
|
|
477
|
+
MakaiAgentApi,
|
|
478
|
+
MakaiAgentModelsApi,
|
|
479
|
+
MakaiAuthApi,
|
|
480
|
+
MakaiClient,
|
|
481
|
+
MakaiModelsApi,
|
|
482
|
+
MakaiProviderApi,
|
|
483
|
+
ModelDescriptor,
|
|
484
|
+
ProviderCompleteRequest,
|
|
485
|
+
ProviderCompleteResponse,
|
|
486
|
+
ProviderStreamEvent,
|
|
487
|
+
RunOptions,
|
|
488
|
+
TextContentPart,
|
|
489
|
+
ToolDefinition,
|
|
490
|
+
UsageSummary,
|
|
491
|
+
} from "@oxap/sdk";
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
Most requests share this shape:
|
|
495
|
+
|
|
496
|
+
```ts
|
|
497
|
+
import type { ContentPart, TextContentPart } from "@oxap/sdk";
|
|
498
|
+
|
|
499
|
+
type ChatMessage = {
|
|
500
|
+
role: "system" | "developer" | "user" | "assistant" | "tool";
|
|
501
|
+
content: string | ContentPart[];
|
|
502
|
+
name?: string;
|
|
503
|
+
tool_call_id?: string;
|
|
504
|
+
};
|
|
505
|
+
|
|
506
|
+
type ToolDefinition = {
|
|
507
|
+
name: string;
|
|
508
|
+
description: string;
|
|
509
|
+
parameters_schema_json: string;
|
|
510
|
+
execute?: (
|
|
511
|
+
args: Record<string, unknown>,
|
|
512
|
+
context: { tool_call_id: string; tool_name: string; args_json: string },
|
|
513
|
+
) => Promise<string | TextContentPart[]> | string | TextContentPart[];
|
|
514
|
+
};
|
|
515
|
+
|
|
516
|
+
type RunOptions = {
|
|
517
|
+
temperature?: number;
|
|
518
|
+
max_tokens?: number;
|
|
519
|
+
reasoning_effort?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
|
|
520
|
+
auth_retry_policy?: "manual" | "auto_once";
|
|
521
|
+
/**
|
|
522
|
+
* OAP session identity. Use `agent.switchModel(session_id, model_ref)` to
|
|
523
|
+
* select a new model mid-session, then `agent.runSelected(session_id, messages)`.
|
|
524
|
+
*/
|
|
525
|
+
session_id?: string;
|
|
526
|
+
metadata?: Record<string, string>;
|
|
527
|
+
signal?: AbortSignal;
|
|
528
|
+
};
|
|
529
|
+
```
|
|
530
|
+
|
|
531
|
+
Core namespaces:
|
|
532
|
+
|
|
533
|
+
```ts
|
|
534
|
+
import type {
|
|
535
|
+
MakaiAuthApi,
|
|
536
|
+
MakaiModelsApi,
|
|
537
|
+
MakaiAgentModelsApi,
|
|
538
|
+
MakaiProviderApi,
|
|
539
|
+
} from "@oxap/sdk";
|
|
540
|
+
|
|
541
|
+
type MakaiClient = {
|
|
542
|
+
auth: MakaiAuthApi;
|
|
543
|
+
models: MakaiModelsApi;
|
|
544
|
+
agent: MakaiAgentModelsApi; // extends MakaiAgentApi with a `models` convenience alias
|
|
545
|
+
provider: MakaiProviderApi;
|
|
546
|
+
close(): Promise<void>;
|
|
547
|
+
};
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
|
|
551
|
+
## Usage counts and precision
|
|
552
|
+
|
|
553
|
+
Decision 0063 makes all six `UsageSummary` counters optional `number` values.
|
|
554
|
+
An absent counter is unknown; a measured zero stays `0`. Reported totals are
|
|
555
|
+
retained, never inferred from partial counts. Check for `undefined` before
|
|
556
|
+
using `input` or `output`, which were previously required.
|
|
557
|
+
|
|
558
|
+
The wire decoder retains each numeric literal before conversion. Counts up to
|
|
559
|
+
`Number.MAX_SAFE_INTEGER` (`2^53-1`) stay exact numbers. A valid larger count
|
|
560
|
+
through `uint64` maximum leaves that numeric field absent and adds a typed
|
|
561
|
+
`UnrepresentableUsageCount` to `usage.unrepresentable_counts`, for example:
|
|
562
|
+
|
|
563
|
+
```json
|
|
564
|
+
{"output":0,"unrepresentable_counts":[{"code":"unrepresentable_count","field":"input_tokens","value":"18446744073709551615"}]}
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
This signal is SDK metadata, not an additional OAP wire field. The response
|
|
568
|
+
and stream complete normally, and the exact decimal string remains available.
|
|
569
|
+
Counters stay simple numeric values for consumers; no `number | bigint` union
|
|
570
|
+
or rounded count is exposed. This representation is a TypeScript SDK choice,
|
|
571
|
+
not a change to Decision 0063's wire meanings.
|
|
572
|
+
|
|
573
|
+
Present null, negative, fractional, malformed and out-of-uint64 counts return
|
|
574
|
+
`MakaiProtocolError` with `malformed_response`. Integer spellings stay strict:
|
|
575
|
+
`1.0`, `1e3` and `-0` are refused by Decision 0065: supplied usage counts have
|
|
576
|
+
canonical unsigned decimal spelling, even when another spelling has an integral value.
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export declare function checkAbort(signal: AbortSignal | undefined, context?: string): void;
|
|
2
|
+
export declare function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined, context?: string): Promise<T>;
|
|
3
|
+
export declare function isAbortError(error: unknown): error is Error & {
|
|
4
|
+
name: "AbortError";
|
|
5
|
+
};
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.checkAbort = checkAbort;
|
|
4
|
+
exports.raceWithAbort = raceWithAbort;
|
|
5
|
+
exports.isAbortError = isAbortError;
|
|
6
|
+
function checkAbort(signal, context = "operation aborted") {
|
|
7
|
+
if (signal?.aborted) {
|
|
8
|
+
const error = new Error(context);
|
|
9
|
+
error.name = "AbortError";
|
|
10
|
+
throw error;
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
function raceWithAbort(promise, signal, context = "operation aborted") {
|
|
14
|
+
if (!signal)
|
|
15
|
+
return promise;
|
|
16
|
+
if (signal.aborted) {
|
|
17
|
+
const error = new Error(context);
|
|
18
|
+
error.name = "AbortError";
|
|
19
|
+
promise.catch(() => { });
|
|
20
|
+
return Promise.reject(error);
|
|
21
|
+
}
|
|
22
|
+
return new Promise((resolve, reject) => {
|
|
23
|
+
let settled = false;
|
|
24
|
+
const onAbort = () => {
|
|
25
|
+
queueMicrotask(() => {
|
|
26
|
+
if (settled)
|
|
27
|
+
return;
|
|
28
|
+
settled = true;
|
|
29
|
+
const error = new Error(context);
|
|
30
|
+
error.name = "AbortError";
|
|
31
|
+
reject(error);
|
|
32
|
+
});
|
|
33
|
+
};
|
|
34
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
35
|
+
promise.then((result) => {
|
|
36
|
+
if (settled)
|
|
37
|
+
return;
|
|
38
|
+
settled = true;
|
|
39
|
+
signal.removeEventListener("abort", onAbort);
|
|
40
|
+
resolve(result);
|
|
41
|
+
}, (error) => {
|
|
42
|
+
if (settled)
|
|
43
|
+
return;
|
|
44
|
+
settled = true;
|
|
45
|
+
signal.removeEventListener("abort", onAbort);
|
|
46
|
+
reject(error);
|
|
47
|
+
});
|
|
48
|
+
});
|
|
49
|
+
}
|
|
50
|
+
function isAbortError(error) {
|
|
51
|
+
return error instanceof Error && error.name === "AbortError";
|
|
52
|
+
}
|