@mantyx/sdk 0.9.0 → 0.10.0
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/CHANGELOG.md +15 -1
- package/README.md +75 -2
- package/dist/a2a-server.cjs +13 -1
- package/dist/a2a-server.cjs.map +1 -1
- package/dist/a2a-server.d.cts +1 -1
- package/dist/a2a-server.d.ts +1 -1
- package/dist/a2a-server.js +1 -1
- package/dist/{chunk-TYRJBHLM.js → chunk-XMUCELMH.js} +146 -26
- package/dist/chunk-XMUCELMH.js.map +1 -0
- package/dist/{client-CeWCSsmD.d.cts → client-DHwh8MPj.d.cts} +500 -3
- package/dist/{client-CeWCSsmD.d.ts → client-DHwh8MPj.d.ts} +500 -3
- package/dist/index.cjs +436 -26
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -48
- package/dist/index.d.ts +3 -48
- package/dist/index.js +287 -2
- package/dist/index.js.map +1 -1
- package/docs/agent-runs-protocol.md +113 -6
- package/docs/oauth.md +356 -0
- package/docs/wire-protocol.md +1102 -0
- package/package.json +1 -1
- package/dist/chunk-TYRJBHLM.js.map +0 -1
|
@@ -1,5 +1,345 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
2
|
|
|
3
|
+
/**
|
|
4
|
+
* Error types raised by the MANTYX SDK.
|
|
5
|
+
*/
|
|
6
|
+
declare class MantyxError extends Error {
|
|
7
|
+
readonly code: string;
|
|
8
|
+
readonly status: number | undefined;
|
|
9
|
+
readonly hint: string | undefined;
|
|
10
|
+
constructor(message: string, opts?: {
|
|
11
|
+
code?: string;
|
|
12
|
+
status?: number;
|
|
13
|
+
hint?: string;
|
|
14
|
+
});
|
|
15
|
+
}
|
|
16
|
+
declare class MantyxNetworkError extends MantyxError {
|
|
17
|
+
constructor(message: string, opts?: {
|
|
18
|
+
cause?: unknown;
|
|
19
|
+
});
|
|
20
|
+
}
|
|
21
|
+
declare class MantyxAuthError extends MantyxError {
|
|
22
|
+
constructor(message?: string);
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Raised on `403 insufficient_scope`, returned when an OAuth access token
|
|
26
|
+
* is missing one of the scopes a route demands (see
|
|
27
|
+
* `docs/agent-runs-protocol.md` §2.2 for the per-endpoint table).
|
|
28
|
+
*
|
|
29
|
+
* `requiredScopes` carries the verbatim `required` value from the
|
|
30
|
+
* server's response — a single scope for most routes, an array when the
|
|
31
|
+
* route demands more than one. The SDK is expected to surface this so
|
|
32
|
+
* callers can drive a re-consent flow (e.g. "please re-authorise the
|
|
33
|
+
* app with `sessions:write` enabled").
|
|
34
|
+
*
|
|
35
|
+
* Workspace API keys never trip this error — they carry no granular
|
|
36
|
+
* scopes. It is OAuth-only.
|
|
37
|
+
*/
|
|
38
|
+
declare class MantyxScopeError extends MantyxError {
|
|
39
|
+
/**
|
|
40
|
+
* Scope(s) the route demanded. Always at least one entry; usually
|
|
41
|
+
* exactly one. New routes may demand more scopes in the future.
|
|
42
|
+
*/
|
|
43
|
+
readonly requiredScopes: readonly string[];
|
|
44
|
+
constructor(message: string, requiredScopes: readonly string[]);
|
|
45
|
+
}
|
|
46
|
+
declare class MantyxToolError extends MantyxError {
|
|
47
|
+
readonly toolName: string;
|
|
48
|
+
constructor(toolName: string, message: string);
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Optional triage attributes the runner attaches to terminal `error`
|
|
52
|
+
* events. Mirrors the wire fields described in
|
|
53
|
+
* `docs/agent-runs-protocol.md` §7 ("error event payload fields") so SDK
|
|
54
|
+
* callers can render structured UI status notes ("model truncated — JSON
|
|
55
|
+
* likely incomplete") and drive retry policy without re-parsing the
|
|
56
|
+
* human-readable `message`.
|
|
57
|
+
*/
|
|
58
|
+
interface MantyxRunErrorInit {
|
|
59
|
+
/**
|
|
60
|
+
* Canonical category of failure. One of `"rate_limit"`, `"overloaded"`,
|
|
61
|
+
* `"server"`, `"context_window"`, `"truncation"`, `"invalid_request"`,
|
|
62
|
+
* `"auth"`, `"timeout"`, `"local_timeout"`, `"upstream_deadline"`,
|
|
63
|
+
* `"unknown"`. New categories may land additively — callers should
|
|
64
|
+
* default-branch to `"unknown"` for unrecognized values.
|
|
65
|
+
*/
|
|
66
|
+
errorClass?: string;
|
|
67
|
+
/**
|
|
68
|
+
* Canonical lowercase stop reason normalized across providers
|
|
69
|
+
* (`"max_tokens"`, `"refusal"`, `"malformed_function_call"`, …). When
|
|
70
|
+
* present, mirrors the value carried on the last `assistant_message`
|
|
71
|
+
* event preceding the failure.
|
|
72
|
+
*/
|
|
73
|
+
finishReason?: string | null;
|
|
74
|
+
/**
|
|
75
|
+
* **Best-effort raw bytes** the model emitted before the failure. For
|
|
76
|
+
* `outputSchema` runs this is likely **incomplete JSON** that will
|
|
77
|
+
* fail `JSON.parse` — treat it as diagnostic data, never as a
|
|
78
|
+
* schema-conformant reply.
|
|
79
|
+
*/
|
|
80
|
+
partialText?: string;
|
|
81
|
+
/**
|
|
82
|
+
* Coarse retry hint inherited from the pipeline's error classifier.
|
|
83
|
+
* Informational; the SDK still owns the actual retry decision.
|
|
84
|
+
*/
|
|
85
|
+
retryable?: boolean;
|
|
86
|
+
}
|
|
87
|
+
declare class MantyxRunError extends MantyxError {
|
|
88
|
+
readonly runId: string;
|
|
89
|
+
readonly subtype: string;
|
|
90
|
+
/** See {@link MantyxRunErrorInit.errorClass}. */
|
|
91
|
+
readonly errorClass: string | undefined;
|
|
92
|
+
/** See {@link MantyxRunErrorInit.finishReason}. */
|
|
93
|
+
readonly finishReason: string | null | undefined;
|
|
94
|
+
/** See {@link MantyxRunErrorInit.partialText}. */
|
|
95
|
+
readonly partialText: string | undefined;
|
|
96
|
+
/** See {@link MantyxRunErrorInit.retryable}. */
|
|
97
|
+
readonly retryable: boolean | undefined;
|
|
98
|
+
constructor(runId: string, subtype: string, message: string, init?: MantyxRunErrorInit);
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Thrown by {@link parseRunOutput} when the run's terminal text was supposed
|
|
102
|
+
* to be a JSON document (because `outputSchema` was set on the spec) but
|
|
103
|
+
* either failed to JSON.parse or failed the user-supplied validator.
|
|
104
|
+
*
|
|
105
|
+
* The original `text` is preserved on the `text` field so callers can log
|
|
106
|
+
* the raw model output for debugging.
|
|
107
|
+
*/
|
|
108
|
+
declare class MantyxParseError extends MantyxError {
|
|
109
|
+
readonly text: string;
|
|
110
|
+
constructor(message: string, text: string, opts?: {
|
|
111
|
+
cause?: unknown;
|
|
112
|
+
});
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* MANTYX OAuth 2.0 client: authorization-code exchange, refresh-token
|
|
117
|
+
* minting, client-credentials grant, and token revocation, plus typed
|
|
118
|
+
* {@link TokenSource}s that {@link MantyxClient} can consume to refresh
|
|
119
|
+
* access tokens transparently before they expire (and again on 401).
|
|
120
|
+
*
|
|
121
|
+
* The wire contract this implements is `docs/oauth.md` in the SDK monorepo:
|
|
122
|
+
*
|
|
123
|
+
* - Token endpoint: `POST <baseUrl>/api/oauth/token`, form-encoded.
|
|
124
|
+
* - Revoke endpoint: `POST <baseUrl>/api/oauth/revoke`, form-encoded.
|
|
125
|
+
* - Access tokens (`mantyx_at_…`) live 1 hour (`expires_in: 3600`).
|
|
126
|
+
* - Refresh tokens (`mantyx_rt_…`) are **persistent and non-rotating**:
|
|
127
|
+
* `grant_type=refresh_token` echoes back the same value the client
|
|
128
|
+
* sent. The caller persists the refresh token once at first sign-in
|
|
129
|
+
* (encrypted at rest) and the SDK re-mints access tokens from it on
|
|
130
|
+
* demand.
|
|
131
|
+
*
|
|
132
|
+
* See also `docs/oauth.md` for the authorization-code + PKCE consent
|
|
133
|
+
* flow (which the SDK does **not** drive — the calling app owns the
|
|
134
|
+
* redirect dance; once it has the auth code, `exchangeAuthorizationCode`
|
|
135
|
+
* swaps it for the initial `{access_token, refresh_token}` pair).
|
|
136
|
+
*/
|
|
137
|
+
|
|
138
|
+
declare const DEFAULT_OAUTH_BASE_URL = "https://app.mantyx.io";
|
|
139
|
+
/** Skew (ms) before `expiresAt` at which a TokenSource will pre-emptively refresh. Default 60s. */
|
|
140
|
+
declare const DEFAULT_REFRESH_SKEW_MS = 60000;
|
|
141
|
+
/**
|
|
142
|
+
* Raised on a non-2xx response from `POST /api/oauth/token` or
|
|
143
|
+
* `POST /api/oauth/revoke`. Carries the RFC 6749 `error` discriminator
|
|
144
|
+
* (`"invalid_grant"`, `"invalid_client"`, `"unsupported_grant_type"`,
|
|
145
|
+
* …) and the optional `error_description` so callers can branch on
|
|
146
|
+
* machine-readable values without parsing the human message.
|
|
147
|
+
*
|
|
148
|
+
* `invalid_grant` from the refresh path specifically signals that the
|
|
149
|
+
* refresh token has been revoked (or the OAuth grant / application
|
|
150
|
+
* was deleted). The SDK never loops on this — callers should route
|
|
151
|
+
* the user back to a fresh sign-in.
|
|
152
|
+
*/
|
|
153
|
+
declare class MantyxOAuthError extends MantyxError {
|
|
154
|
+
readonly oauthError: string;
|
|
155
|
+
readonly oauthErrorDescription: string | undefined;
|
|
156
|
+
constructor(oauthError: string, oauthErrorDescription: string | undefined, status: number);
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* Decoded `POST /api/oauth/token` response, augmented with an absolute
|
|
160
|
+
* `expiresAt` timestamp the SDK can use to decide when to refresh.
|
|
161
|
+
*
|
|
162
|
+
* `refreshToken` is present on the initial `authorization_code` exchange
|
|
163
|
+
* and on subsequent `refresh_token` calls (where it is identical to the
|
|
164
|
+
* value the client just sent — refresh tokens never rotate). The
|
|
165
|
+
* `client_credentials` grant never returns one.
|
|
166
|
+
*/
|
|
167
|
+
interface OAuthToken {
|
|
168
|
+
readonly accessToken: string;
|
|
169
|
+
readonly refreshToken: string | undefined;
|
|
170
|
+
readonly tokenType: string;
|
|
171
|
+
readonly expiresIn: number;
|
|
172
|
+
/** Absolute Unix-ms timestamp set when the SDK parsed the response. */
|
|
173
|
+
readonly expiresAt: number;
|
|
174
|
+
readonly scope: string | undefined;
|
|
175
|
+
}
|
|
176
|
+
/** Why the SDK asked the {@link TokenSource} for the current access token. */
|
|
177
|
+
type TokenRequestReason = "initial" | "expired" | "unauthorized";
|
|
178
|
+
/**
|
|
179
|
+
* A `TokenSource` produces the current access token on demand. The
|
|
180
|
+
* {@link MantyxClient} HTTP layer calls it before every request. When
|
|
181
|
+
* called with `reason: "unauthorized"` the source MUST force a refresh
|
|
182
|
+
* (do not return a cached value); this is how the SDK recovers from
|
|
183
|
+
* 401s caused by a token that the server already invalidated.
|
|
184
|
+
*
|
|
185
|
+
* Implementations should be safe to call from many concurrent requests.
|
|
186
|
+
*/
|
|
187
|
+
type TokenSource = (reason?: TokenRequestReason) => Promise<string>;
|
|
188
|
+
/** Caller-supplied options for `MantyxOAuthClient`. */
|
|
189
|
+
interface MantyxOAuthClientOptions {
|
|
190
|
+
/**
|
|
191
|
+
* OAuth `client_id` issued at app registration (token prefix
|
|
192
|
+
* `mantyx_oa_`).
|
|
193
|
+
*/
|
|
194
|
+
clientId: string;
|
|
195
|
+
/**
|
|
196
|
+
* OAuth `client_secret` issued at app registration (token prefix
|
|
197
|
+
* `mantyx_oas_`). Every MANTYX OAuth app is a confidential client,
|
|
198
|
+
* so this is always required for token + revoke calls. Treat as a
|
|
199
|
+
* deployment secret — do not bundle into browser builds.
|
|
200
|
+
*/
|
|
201
|
+
clientSecret: string;
|
|
202
|
+
/**
|
|
203
|
+
* Origin of the MANTYX deployment. Defaults to `https://app.mantyx.io`.
|
|
204
|
+
* The OAuth endpoints are mounted at `<baseUrl>/api/oauth/...`.
|
|
205
|
+
*/
|
|
206
|
+
baseUrl?: string;
|
|
207
|
+
/** Optional `fetch` override (e.g. node-fetch wrapper). Default: global `fetch`. */
|
|
208
|
+
fetch?: typeof fetch;
|
|
209
|
+
/** Default per-request timeout in milliseconds. Default: 30s. */
|
|
210
|
+
timeoutMs?: number;
|
|
211
|
+
}
|
|
212
|
+
interface ExchangeAuthorizationCodeOptions {
|
|
213
|
+
code: string;
|
|
214
|
+
redirectUri: string;
|
|
215
|
+
codeVerifier: string;
|
|
216
|
+
}
|
|
217
|
+
interface RefreshOptions {
|
|
218
|
+
refreshToken: string;
|
|
219
|
+
/**
|
|
220
|
+
* Optional scope narrowing. Must be a subset of the scopes already
|
|
221
|
+
* granted to the refresh token (server enforces this). Useful when
|
|
222
|
+
* an SDK consumer wants a short-scope access token for a specific
|
|
223
|
+
* sub-operation.
|
|
224
|
+
*/
|
|
225
|
+
scope?: string | readonly string[];
|
|
226
|
+
}
|
|
227
|
+
interface ClientCredentialsOptions {
|
|
228
|
+
scope?: string | readonly string[];
|
|
229
|
+
}
|
|
230
|
+
interface RevokeOptions {
|
|
231
|
+
token: string;
|
|
232
|
+
}
|
|
233
|
+
interface RefreshTokenSourceOptions {
|
|
234
|
+
refreshToken: string;
|
|
235
|
+
/** Optional scope narrowing applied on every refresh. */
|
|
236
|
+
scope?: string | readonly string[];
|
|
237
|
+
/**
|
|
238
|
+
* How many ms before `expiresAt` the source proactively refreshes.
|
|
239
|
+
* Defaults to {@link DEFAULT_REFRESH_SKEW_MS} (60s).
|
|
240
|
+
*/
|
|
241
|
+
refreshSkewMs?: number;
|
|
242
|
+
/**
|
|
243
|
+
* Optional initial access token + expiry to seed the source's cache
|
|
244
|
+
* with (e.g. the token already in hand from the authorization-code
|
|
245
|
+
* exchange). When omitted, the source mints one on the first call.
|
|
246
|
+
*/
|
|
247
|
+
initialToken?: OAuthToken;
|
|
248
|
+
}
|
|
249
|
+
interface ClientCredentialsTokenSourceOptions {
|
|
250
|
+
scope?: string | readonly string[];
|
|
251
|
+
refreshSkewMs?: number;
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* Wraps the MANTYX OAuth 2.0 authorization-server endpoints. App-scoped
|
|
255
|
+
* (one per `{clientId, clientSecret}` pair); construct independently of
|
|
256
|
+
* {@link MantyxClient}, then either call its grant helpers directly or
|
|
257
|
+
* hand a `TokenSource` it produces to `MantyxClient` for fully
|
|
258
|
+
* transparent refresh.
|
|
259
|
+
*/
|
|
260
|
+
declare class MantyxOAuthClient {
|
|
261
|
+
readonly clientId: string;
|
|
262
|
+
readonly baseUrl: string;
|
|
263
|
+
private readonly clientSecret;
|
|
264
|
+
private readonly fetchImpl;
|
|
265
|
+
private readonly timeoutMs;
|
|
266
|
+
constructor(opts: MantyxOAuthClientOptions);
|
|
267
|
+
/**
|
|
268
|
+
* Swap an authorization-code + PKCE verifier for the initial
|
|
269
|
+
* `{access_token, refresh_token}` pair. Call this exactly once per
|
|
270
|
+
* sign-in after the browser/native redirect lands back on your
|
|
271
|
+
* `redirectUri` with a `code` parameter. Persist the returned
|
|
272
|
+
* `refreshToken` against the user record — it is long-lived and
|
|
273
|
+
* non-rotating per `docs/oauth.md` §"Token lifetimes & lifecycle".
|
|
274
|
+
*/
|
|
275
|
+
exchangeAuthorizationCode(opts: ExchangeAuthorizationCodeOptions): Promise<OAuthToken>;
|
|
276
|
+
/**
|
|
277
|
+
* Mint a fresh access token from a stored refresh token. The
|
|
278
|
+
* returned `refreshToken` is identical to the input — the field is
|
|
279
|
+
* surfaced for symmetry with {@link exchangeAuthorizationCode} only.
|
|
280
|
+
*
|
|
281
|
+
* On `400 invalid_grant` the refresh token has been revoked (or its
|
|
282
|
+
* grant / app was deleted); the SDK surfaces a
|
|
283
|
+
* {@link MantyxOAuthError} and callers must drive a fresh sign-in.
|
|
284
|
+
*/
|
|
285
|
+
refresh(opts: RefreshOptions): Promise<OAuthToken>;
|
|
286
|
+
/**
|
|
287
|
+
* Request a workspace-scoped access token without a user via the
|
|
288
|
+
* `client_credentials` grant. Available only on private OAuth apps
|
|
289
|
+
* that were registered with `allowsClientCredentials: true`. No
|
|
290
|
+
* refresh token is issued; re-call this method whenever a new
|
|
291
|
+
* access token is needed.
|
|
292
|
+
*/
|
|
293
|
+
clientCredentials(opts?: ClientCredentialsOptions): Promise<OAuthToken>;
|
|
294
|
+
/**
|
|
295
|
+
* Revoke an access or refresh token (RFC 7009). The server always
|
|
296
|
+
* returns 200, even for unknown tokens. Revoking a **refresh**
|
|
297
|
+
* token kills the refresh and every live access token tied to its
|
|
298
|
+
* grant; revoking an **access** token kills only that one.
|
|
299
|
+
*/
|
|
300
|
+
revoke(opts: RevokeOptions): Promise<void>;
|
|
301
|
+
/**
|
|
302
|
+
* Build a long-lived {@link TokenSource} that re-mints access
|
|
303
|
+
* tokens from the supplied refresh token. Pass the returned source
|
|
304
|
+
* to `new MantyxClient({ tokenSource, workspaceSlug, ... })`. The
|
|
305
|
+
* source caches the access token in-memory and refreshes
|
|
306
|
+
* proactively when the cached value is within `refreshSkewMs` of
|
|
307
|
+
* `expiresAt`, or eagerly when `MantyxClient` reports a 401.
|
|
308
|
+
*/
|
|
309
|
+
refreshTokenSource(opts: RefreshTokenSourceOptions): TokenSource;
|
|
310
|
+
/**
|
|
311
|
+
* Build a long-lived {@link TokenSource} backed by the
|
|
312
|
+
* `client_credentials` grant. On every refresh the source re-mints
|
|
313
|
+
* a workspace-scoped access token by calling the token endpoint
|
|
314
|
+
* with `grant_type=client_credentials`. Available only on private
|
|
315
|
+
* apps with `allowsClientCredentials: true`.
|
|
316
|
+
*/
|
|
317
|
+
clientCredentialsTokenSource(opts?: ClientCredentialsTokenSourceOptions): TokenSource;
|
|
318
|
+
/**
|
|
319
|
+
* POST `application/x-www-form-urlencoded` to `/api/oauth/token` and
|
|
320
|
+
* decode the {@link OAuthToken} response. Always injects `client_id`
|
|
321
|
+
* + `client_secret` from the constructor.
|
|
322
|
+
*/
|
|
323
|
+
private token;
|
|
324
|
+
private formPost;
|
|
325
|
+
}
|
|
326
|
+
/**
|
|
327
|
+
* Generate a high-entropy PKCE `code_verifier` (RFC 7636 §4.1). The
|
|
328
|
+
* verifier is the raw secret you keep across the redirect; the
|
|
329
|
+
* `code_challenge` you send on `/api/oauth/authorize` is derived from
|
|
330
|
+
* it via {@link pkceChallenge}.
|
|
331
|
+
*
|
|
332
|
+
* Default length is 64 characters (≈ 384 bits of entropy after
|
|
333
|
+
* base64url-encoding the 32 random bytes). Pass `length` to clamp to
|
|
334
|
+
* the RFC's 43..128 inclusive range.
|
|
335
|
+
*/
|
|
336
|
+
declare function generatePkceVerifier(length?: number): string;
|
|
337
|
+
/**
|
|
338
|
+
* Compute the PKCE `S256` `code_challenge` for a given verifier:
|
|
339
|
+
* `base64url(sha256(verifier))` with no padding (RFC 7636 §4.2).
|
|
340
|
+
*/
|
|
341
|
+
declare function pkceChallenge(verifier: string): string;
|
|
342
|
+
|
|
3
343
|
/**
|
|
4
344
|
* Public tool helpers for the MANTYX SDK.
|
|
5
345
|
*
|
|
@@ -332,7 +672,64 @@ declare function isLocalMcpServer(t: ToolRef): t is LocalMcpServer;
|
|
|
332
672
|
|
|
333
673
|
declare const DEFAULT_BASE_URL = "https://app.mantyx.io";
|
|
334
674
|
interface MantyxClientOptions {
|
|
335
|
-
|
|
675
|
+
/**
|
|
676
|
+
* Workspace API key (token prefix `mantyx_`) **or** a MANTYX OAuth 2.0
|
|
677
|
+
* access token (token prefix `mantyx_at_`). The server resolves either
|
|
678
|
+
* kind by token-prefix, so the SDK uses a single credential code path.
|
|
679
|
+
*
|
|
680
|
+
* Prefer the {@link accessToken} alias when wiring up an OAuth-based
|
|
681
|
+
* application — the two options are semantically identical (the value
|
|
682
|
+
* is forwarded as `Authorization: Bearer <credential>`), but
|
|
683
|
+
* `accessToken` makes the intent obvious at the call site.
|
|
684
|
+
*
|
|
685
|
+
* Exactly one of `apiKey` / `accessToken` must be set. Passing both —
|
|
686
|
+
* even to the same value — throws `MantyxError` at construction time.
|
|
687
|
+
*
|
|
688
|
+
* See `docs/agent-runs-protocol.md` §2 for the full credential table
|
|
689
|
+
* (including which prefix means what, scope semantics, and the
|
|
690
|
+
* `insufficient_scope` 403 SDKs surface via
|
|
691
|
+
* {@link MantyxScopeError}).
|
|
692
|
+
*/
|
|
693
|
+
apiKey?: string;
|
|
694
|
+
/**
|
|
695
|
+
* MANTYX OAuth 2.0 access token (token prefix `mantyx_at_…`). Exactly
|
|
696
|
+
* one of {@link apiKey} / `accessToken` / {@link tokenSource} must be
|
|
697
|
+
* set; passing more than one throws `MantyxError` at construction
|
|
698
|
+
* time.
|
|
699
|
+
*
|
|
700
|
+
* Functionally identical to {@link apiKey} — the SDK ships either
|
|
701
|
+
* value verbatim on `Authorization: Bearer <credential>` — but using
|
|
702
|
+
* the OAuth-specific name makes scope-driven applications easier to
|
|
703
|
+
* read.
|
|
704
|
+
*
|
|
705
|
+
* OAuth tokens additionally enforce per-route **scopes**
|
|
706
|
+
* (`runs:read`, `runs:write`, `sessions:read`, `sessions:write`,
|
|
707
|
+
* `models:read`, `mantyx.identity:read`); see
|
|
708
|
+
* `docs/agent-runs-protocol.md` §2.2 for the table. Missing scopes
|
|
709
|
+
* land as {@link MantyxScopeError} so callers can route the user
|
|
710
|
+
* back to a re-consent flow.
|
|
711
|
+
*
|
|
712
|
+
* Static `accessToken` values are 1-hour-lived per `docs/oauth.md`
|
|
713
|
+
* §"Token lifetimes & lifecycle" — for long-running processes
|
|
714
|
+
* prefer {@link tokenSource} so the SDK can refresh transparently.
|
|
715
|
+
*/
|
|
716
|
+
accessToken?: string;
|
|
717
|
+
/**
|
|
718
|
+
* Dynamic credential provider. The SDK calls it before every request
|
|
719
|
+
* to obtain the current access token, and again with
|
|
720
|
+
* `reason: "unauthorized"` after a 401 so it can refresh and retry
|
|
721
|
+
* the request exactly once.
|
|
722
|
+
*
|
|
723
|
+
* Build one via `oauthClient.refreshTokenSource({ refreshToken })`
|
|
724
|
+
* or `oauthClient.clientCredentialsTokenSource()` — see
|
|
725
|
+
* [`./oauth.ts`](./oauth.ts) for the helpers, or pass any function
|
|
726
|
+
* matching the {@link TokenSource} signature for full custom
|
|
727
|
+
* control (e.g. tokens minted by an upstream auth proxy).
|
|
728
|
+
*
|
|
729
|
+
* Exactly one of {@link apiKey} / {@link accessToken} / `tokenSource`
|
|
730
|
+
* must be set.
|
|
731
|
+
*/
|
|
732
|
+
tokenSource?: TokenSource;
|
|
336
733
|
workspaceSlug: string;
|
|
337
734
|
/** Defaults to `https://app.mantyx.io`. Override for self-hosted instances. */
|
|
338
735
|
baseUrl?: string;
|
|
@@ -545,7 +942,34 @@ interface ThinkingDeltaEvent extends RunEventBase {
|
|
|
545
942
|
}
|
|
546
943
|
interface AssistantMessageEvent extends RunEventBase {
|
|
547
944
|
type: "assistant_message";
|
|
945
|
+
/**
|
|
946
|
+
* Full assistant text for this turn (concatenation of every preceding
|
|
947
|
+
* `assistant_delta` for the turn, plus any non-streaming snapshot the
|
|
948
|
+
* engine appended at close). May be empty when the turn was tool-only.
|
|
949
|
+
*/
|
|
548
950
|
text: string;
|
|
951
|
+
/**
|
|
952
|
+
* 0-based tool-turn index this assistant message closes. Useful for
|
|
953
|
+
* SDK clients pairing the message with the subsequent `tool_result`
|
|
954
|
+
* rows.
|
|
955
|
+
*/
|
|
956
|
+
turn?: number;
|
|
957
|
+
/**
|
|
958
|
+
* Canonical lowercase stop reason normalized across providers
|
|
959
|
+
* (`"end_turn"`, `"tool_use"`, `"max_tokens"`, `"refusal"`,
|
|
960
|
+
* `"malformed_function_call"`, …). `null` / omitted when the provider
|
|
961
|
+
* did not report one.
|
|
962
|
+
*/
|
|
963
|
+
finishReason?: string | null;
|
|
964
|
+
/**
|
|
965
|
+
* Tool calls the model emitted on this turn. Omitted when the model
|
|
966
|
+
* did not call any tools.
|
|
967
|
+
*/
|
|
968
|
+
toolCalls?: Array<{
|
|
969
|
+
id: string;
|
|
970
|
+
name: string;
|
|
971
|
+
input: Record<string, unknown>;
|
|
972
|
+
}>;
|
|
549
973
|
}
|
|
550
974
|
interface ServerToolResultEvent extends RunEventBase {
|
|
551
975
|
type: "tool_result";
|
|
@@ -654,8 +1078,41 @@ interface ResultEvent extends RunEventBase {
|
|
|
654
1078
|
}
|
|
655
1079
|
interface ErrorEvent extends RunEventBase {
|
|
656
1080
|
type: "error";
|
|
1081
|
+
/** Human-readable failure message. */
|
|
657
1082
|
error: string;
|
|
1083
|
+
/**
|
|
1084
|
+
* Legacy alias for {@link errorClass}. Equals `errorClass` when present;
|
|
1085
|
+
* otherwise a small lowercase token (`"error"`, `"invalid_spec"`,
|
|
1086
|
+
* `"worker_error"`, …).
|
|
1087
|
+
*/
|
|
658
1088
|
code?: string;
|
|
1089
|
+
/**
|
|
1090
|
+
* Canonical failure category. One of `"rate_limit"`, `"overloaded"`,
|
|
1091
|
+
* `"server"`, `"context_window"`, `"truncation"`, `"invalid_request"`,
|
|
1092
|
+
* `"auth"`, `"timeout"`, `"local_timeout"`, `"upstream_deadline"`,
|
|
1093
|
+
* `"unknown"`. New categories may land additively. See
|
|
1094
|
+
* `docs/agent-runs-protocol.md` §7 for the full list.
|
|
1095
|
+
*/
|
|
1096
|
+
errorClass?: string;
|
|
1097
|
+
/**
|
|
1098
|
+
* Canonical lowercase stop reason normalized across providers
|
|
1099
|
+
* (`"max_tokens"`, `"refusal"`, `"malformed_function_call"`, …). When
|
|
1100
|
+
* present, mirrors the value on the last `assistant_message` event.
|
|
1101
|
+
*/
|
|
1102
|
+
finishReason?: string | null;
|
|
1103
|
+
/**
|
|
1104
|
+
* **Best-effort raw bytes** the model emitted before the failure. For
|
|
1105
|
+
* `outputSchema` runs this is likely **incomplete JSON** that will
|
|
1106
|
+
* fail `JSON.parse` — see the wire-protocol truncation contract. Also
|
|
1107
|
+
* persisted on `EphemeralAgentRun.finalText` so SDKs can recover it
|
|
1108
|
+
* via `GET /agent-runs/:runId` after the SSE stream closes.
|
|
1109
|
+
*/
|
|
1110
|
+
partialText?: string;
|
|
1111
|
+
/**
|
|
1112
|
+
* Coarse retry hint inherited from the pipeline's error classifier.
|
|
1113
|
+
* Informational; the SDK still owns the actual retry decision.
|
|
1114
|
+
*/
|
|
1115
|
+
retryable?: boolean;
|
|
659
1116
|
}
|
|
660
1117
|
interface CancelledEvent extends RunEventBase {
|
|
661
1118
|
type: "cancelled";
|
|
@@ -681,9 +1138,28 @@ interface SessionInfo {
|
|
|
681
1138
|
metadata: Record<string, string>;
|
|
682
1139
|
}
|
|
683
1140
|
declare class MantyxClient {
|
|
684
|
-
readonly options: Required<Pick<MantyxClientOptions, "
|
|
1141
|
+
readonly options: Required<Pick<MantyxClientOptions, "workspaceSlug" | "baseUrl">> & {
|
|
1142
|
+
/**
|
|
1143
|
+
* Single resolved bearer credential — either a workspace API key
|
|
1144
|
+
* (token prefix `mantyx_`) or an OAuth access token (`mantyx_at_…`).
|
|
1145
|
+
* The SDK does not need to distinguish them on the wire; the value
|
|
1146
|
+
* is forwarded verbatim on `Authorization: Bearer …`.
|
|
1147
|
+
*
|
|
1148
|
+
* Kept as `apiKey` (instead of e.g. `credential`) for backwards
|
|
1149
|
+
* compatibility — older releases exposed it under this name.
|
|
1150
|
+
*
|
|
1151
|
+
* Empty string when a {@link tokenSource} is configured — every
|
|
1152
|
+
* request resolves the bearer from the source instead.
|
|
1153
|
+
*/
|
|
1154
|
+
apiKey: string;
|
|
685
1155
|
fetch: typeof fetch;
|
|
686
1156
|
timeoutMs: number;
|
|
1157
|
+
/**
|
|
1158
|
+
* Dynamic credential provider when constructed with
|
|
1159
|
+
* `tokenSource` — see {@link MantyxClientOptions.tokenSource}.
|
|
1160
|
+
* `null` for static `apiKey` / `accessToken` clients.
|
|
1161
|
+
*/
|
|
1162
|
+
tokenSource: TokenSource | null;
|
|
687
1163
|
};
|
|
688
1164
|
constructor(opts: MantyxClientOptions);
|
|
689
1165
|
listModels(): Promise<ModelCatalog>;
|
|
@@ -719,6 +1195,26 @@ declare class MantyxClient {
|
|
|
719
1195
|
}): Promise<void>;
|
|
720
1196
|
cancelRun(runId: string): Promise<void>;
|
|
721
1197
|
private absoluteUrl;
|
|
1198
|
+
/**
|
|
1199
|
+
* Resolve the bearer credential to send on the next request. With a
|
|
1200
|
+
* static `apiKey` / `accessToken` this is a synchronous reach into
|
|
1201
|
+
* `options.apiKey`; with a {@link TokenSource} it delegates so the
|
|
1202
|
+
* source can refresh expired access tokens before we hit the wire.
|
|
1203
|
+
*
|
|
1204
|
+
* The `reason` is forwarded to the source verbatim. Pass
|
|
1205
|
+
* `"unauthorized"` immediately after a 401 so the source forces a
|
|
1206
|
+
* refresh rather than handing back its (now-invalid) cached value.
|
|
1207
|
+
*/
|
|
1208
|
+
private resolveBearer;
|
|
1209
|
+
/**
|
|
1210
|
+
* Open an SSE stream against `reqUrl` with at-most-one refresh +
|
|
1211
|
+
* retry on 401. The caller is responsible for the subsequent
|
|
1212
|
+
* `readSseStream` loop; this helper only handles the initial GET.
|
|
1213
|
+
* Mid-stream 401s propagate as `MantyxNetworkError` from the read
|
|
1214
|
+
* loop and trigger a reconnect via the outer `while` in
|
|
1215
|
+
* {@link streamRunEvents}.
|
|
1216
|
+
*/
|
|
1217
|
+
private openSseStream;
|
|
722
1218
|
private authHeaders;
|
|
723
1219
|
request<T>(args: {
|
|
724
1220
|
method: string;
|
|
@@ -726,6 +1222,7 @@ declare class MantyxClient {
|
|
|
726
1222
|
body?: unknown;
|
|
727
1223
|
timeoutMs?: number;
|
|
728
1224
|
}): Promise<T>;
|
|
1225
|
+
private requestWithRetry;
|
|
729
1226
|
private errorFromResponse;
|
|
730
1227
|
}
|
|
731
1228
|
declare class AgentSession {
|
|
@@ -822,4 +1319,4 @@ interface LocalHandlers {
|
|
|
822
1319
|
*/
|
|
823
1320
|
declare function parseRunOutput<T = unknown>(result: RunResult, validator?: (value: unknown) => T): T;
|
|
824
1321
|
|
|
825
|
-
export {
|
|
1322
|
+
export { type RevokeOptions as $, type A2AToolRef as A, MantyxNetworkError as B, type CancelledEvent as C, DEFAULT_BASE_URL as D, type ErrorEvent as E, MantyxOAuthClient as F, type MantyxOAuthClientOptions as G, MantyxOAuthError as H, MantyxParseError as I, type MantyxPluginToolRef as J, MantyxRunError as K, type LocalA2ATool as L, MantyxClient as M, type MantyxRunErrorInit as N, MantyxScopeError as O, MantyxToolError as P, type MantyxToolRef as Q, type ReasoningLevel as R, type McpToolRef as S, type ToolRef as T, type ModelCatalog as U, type ModelInfo as V, type OAuthToken as W, type OutputSchema as X, type RefreshOptions as Y, type RefreshTokenSourceOptions as Z, type ResultEvent as _, AgentSession as a, type RunEvent as a0, type RunEventBase as a1, type RunResult as a2, type RunSpec as a3, type ServerToolResultEvent as a4, type SessionInfo as a5, type SessionSpec as a6, type ThinkingDeltaEvent as a7, type TokenRequestReason as a8, type TokenSource as a9, type ToolBudget as aa, type ToolBudgetExceededEvent as ab, type ToolBudgets as ac, type ZodLikeObject as ad, defineLocalA2A as ae, defineLocalMcp as af, defineLocalTool as ag, generatePkceVerifier as ah, isLocalA2ATool as ai, isLocalMcpServer as aj, isLocalTool as ak, mantyxA2A as al, mantyxMcp as am, mantyxPluginTool as an, mantyxTool as ao, parseRunOutput as ap, pkceChallenge as aq, type AgentSpecBase as b, type AssistantDeltaEvent as c, type AssistantMessageEvent as d, type ClientCredentialsOptions as e, type ClientCredentialsTokenSourceOptions as f, DEFAULT_OAUTH_BASE_URL as g, DEFAULT_REFRESH_SKEW_MS as h, type DefineLocalA2AOptions as i, type DefineLocalMcpOptions as j, type DefineLocalToolOptions as k, type ExchangeAuthorizationCodeOptions as l, type LocalHandlers as m, type LocalMcpHttpTransport as n, type LocalMcpServer as o, type LocalMcpStdioTransport as p, type LocalTool as q, type LocalToolCallEvent as r, type LocalToolResultInEvent as s, type LoopDetectedEvent as t, type LoopDetection as u, type MantyxA2AOptions as v, MantyxAuthError as w, type MantyxClientOptions as x, MantyxError as y, type MantyxMcpOptions as z };
|