nexus-ai-pro 2.17.0 → 2.18.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/API_STABILITY.md +35 -0
- package/CHANGELOG.md +78 -1
- package/README.md +7 -3
- package/dist/evaluate/media.d.ts +6 -2
- package/dist/evaluate/media.js +7 -21
- package/dist/index.d.ts +1 -1
- package/dist/mcp/client.d.ts +25 -2
- package/dist/mcp/client.js +82 -47
- package/dist/mcp/server.d.ts +1 -1
- package/dist/mcp/server.js +4 -1
- package/dist/protocols/acp-editor.js +42 -15
- package/dist/router/failover.js +19 -1
- package/dist/server/index.d.ts +1 -0
- package/dist/server/list-page.d.ts +38 -0
- package/dist/server/list-page.js +49 -0
- package/dist/server/regions.d.ts +15 -1
- package/dist/server/regions.js +70 -0
- package/dist/server/runs.d.ts +24 -0
- package/dist/server/runs.js +18 -4
- package/dist/server/server.js +17 -5
- package/dist/tracing/index.d.ts +2 -2
- package/dist/tracing/instrument.d.ts +7 -2
- package/dist/tracing/instrument.js +69 -2
- package/dist/tracing/otlp-proto.js +18 -0
- package/dist/tracing/otlp.d.ts +26 -1
- package/dist/tracing/otlp.js +19 -0
- package/dist/tracing/tracer.d.ts +36 -1
- package/dist/tracing/tracer.js +68 -2
- package/dist/types/response.d.ts +18 -0
- package/dist/types/tracing.d.ts +32 -0
- package/dist/utils/media-duration.d.ts +20 -0
- package/dist/utils/media-duration.js +334 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/video/google.d.ts +8 -0
- package/dist/video/google.js +31 -9
- package/dist/video/index.d.ts +18 -3
- package/dist/video/index.js +46 -3
- package/dist/video/mock.js +3 -1
- package/dist/video/runway.d.ts +2 -0
- package/dist/video/runway.js +45 -11
- package/dist-cjs/evaluate/media.d.ts +6 -2
- package/dist-cjs/evaluate/media.js +9 -21
- package/dist-cjs/index.d.ts +1 -1
- package/dist-cjs/mcp/client.d.ts +25 -2
- package/dist-cjs/mcp/client.js +82 -47
- package/dist-cjs/mcp/server.d.ts +1 -1
- package/dist-cjs/mcp/server.js +4 -1
- package/dist-cjs/protocols/acp-editor.js +42 -15
- package/dist-cjs/router/failover.js +19 -1
- package/dist-cjs/server/index.d.ts +1 -0
- package/dist-cjs/server/list-page.d.ts +38 -0
- package/dist-cjs/server/list-page.js +56 -0
- package/dist-cjs/server/regions.d.ts +15 -1
- package/dist-cjs/server/regions.js +70 -0
- package/dist-cjs/server/runs.d.ts +24 -0
- package/dist-cjs/server/runs.js +18 -4
- package/dist-cjs/server/server.js +17 -5
- package/dist-cjs/tracing/index.d.ts +2 -2
- package/dist-cjs/tracing/instrument.d.ts +7 -2
- package/dist-cjs/tracing/instrument.js +69 -2
- package/dist-cjs/tracing/otlp-proto.js +18 -0
- package/dist-cjs/tracing/otlp.d.ts +26 -1
- package/dist-cjs/tracing/otlp.js +19 -0
- package/dist-cjs/tracing/tracer.d.ts +36 -1
- package/dist-cjs/tracing/tracer.js +68 -2
- package/dist-cjs/types/response.d.ts +18 -0
- package/dist-cjs/types/tracing.d.ts +32 -0
- package/dist-cjs/utils/media-duration.d.ts +20 -0
- package/dist-cjs/utils/media-duration.js +337 -0
- package/dist-cjs/version.d.ts +1 -1
- package/dist-cjs/version.js +1 -1
- package/dist-cjs/video/google.d.ts +8 -0
- package/dist-cjs/video/google.js +31 -9
- package/dist-cjs/video/index.d.ts +18 -3
- package/dist-cjs/video/index.js +46 -3
- package/dist-cjs/video/mock.js +3 -1
- package/dist-cjs/video/runway.d.ts +2 -0
- package/dist-cjs/video/runway.js +45 -11
- package/package.json +1 -1
package/dist/router/failover.js
CHANGED
|
@@ -7,6 +7,7 @@ export class FailoverExecutor {
|
|
|
7
7
|
async complete(request, decision, providers, options = {}) {
|
|
8
8
|
const attempts = attemptsOf(decision);
|
|
9
9
|
const errors = [];
|
|
10
|
+
const failures = [];
|
|
10
11
|
const retry = this.mergeRetry(options.retry, request.retry);
|
|
11
12
|
const timeoutMs = this.resolveTimeout(request.timeoutMs, options.timeoutMs);
|
|
12
13
|
const refreshed = new Set();
|
|
@@ -37,6 +38,8 @@ export class FailoverExecutor {
|
|
|
37
38
|
if (retryIndex > 0) {
|
|
38
39
|
response.meta.guardrailsApplied.push(`provider-retry-${retryIndex}`);
|
|
39
40
|
}
|
|
41
|
+
if (failures.length)
|
|
42
|
+
response.meta.failedAttempts = failures;
|
|
40
43
|
return response;
|
|
41
44
|
}
|
|
42
45
|
catch (caught) {
|
|
@@ -53,6 +56,7 @@ export class FailoverExecutor {
|
|
|
53
56
|
}
|
|
54
57
|
const message = `${attempt.providerName}/${attempt.model}: ${error instanceof Error ? error.message : String(error)}`;
|
|
55
58
|
errors.push(message);
|
|
59
|
+
failures.push(failureOf(attempt, error));
|
|
56
60
|
if (error instanceof UnsettledProviderAttemptError) {
|
|
57
61
|
break attemptsLoop;
|
|
58
62
|
}
|
|
@@ -108,6 +112,7 @@ export class FailoverExecutor {
|
|
|
108
112
|
const retry = this.mergeRetry(options.retry, request.retry);
|
|
109
113
|
const timeoutMs = this.resolveTimeout(request.timeoutMs, options.timeoutMs);
|
|
110
114
|
const errors = [];
|
|
115
|
+
const failures = [];
|
|
111
116
|
const refreshed = new Set();
|
|
112
117
|
attemptsLoop: for (const attempt of attempts) {
|
|
113
118
|
const provider = providers.get(attempt.providerName);
|
|
@@ -151,7 +156,9 @@ export class FailoverExecutor {
|
|
|
151
156
|
if (chunk.type === 'error')
|
|
152
157
|
throw new Error(chunk.error || 'stream error');
|
|
153
158
|
emitted = emitted || chunk.type === 'text' || chunk.type === 'tool_call';
|
|
154
|
-
yield chunk
|
|
159
|
+
yield chunk.type === 'done' && failures.length
|
|
160
|
+
? { ...chunk, meta: { ...chunk.meta, failedAttempts: [...failures] } }
|
|
161
|
+
: chunk;
|
|
155
162
|
}
|
|
156
163
|
}
|
|
157
164
|
catch (caught) {
|
|
@@ -184,6 +191,7 @@ export class FailoverExecutor {
|
|
|
184
191
|
return;
|
|
185
192
|
}
|
|
186
193
|
errors.push(`${attempt.providerName}/${attempt.model}: ${attemptError instanceof Error ? attemptError.message : String(attemptError)}`);
|
|
194
|
+
failures.push(failureOf(attempt, attemptError));
|
|
187
195
|
if (attemptError instanceof UnsettledProviderAttemptError)
|
|
188
196
|
break attemptsLoop;
|
|
189
197
|
if (emitted)
|
|
@@ -423,3 +431,13 @@ function attemptsOf(decision) {
|
|
|
423
431
|
function maxRetriesFor(attempt, retry) {
|
|
424
432
|
return Math.max(retry.maxRetries, attempt.rateLimit?.maxRetries ?? 0);
|
|
425
433
|
}
|
|
434
|
+
function failureOf(attempt, error) {
|
|
435
|
+
const category = error instanceof NexusProviderError ? error.category : undefined;
|
|
436
|
+
return {
|
|
437
|
+
provider: attempt.providerName,
|
|
438
|
+
model: attempt.model,
|
|
439
|
+
error: error instanceof Error ? error.message : String(error),
|
|
440
|
+
...(category ? { category } : {}),
|
|
441
|
+
at: new Date().toISOString(),
|
|
442
|
+
};
|
|
443
|
+
}
|
package/dist/server/index.d.ts
CHANGED
|
@@ -12,6 +12,7 @@ export { CronScheduler, type CronSchedulerOptions, type DueCronJob, parseCron }
|
|
|
12
12
|
export { AssistantCapabilityError, BadRequestError, ForbiddenError, NotFoundError, RunHandOffError, ServerError, type TenantLimit, TenantLimitError, ThreadBusyError, UnauthorizedError, } from './errors.js';
|
|
13
13
|
export { MemoryRunEventLog, type MemoryRunEventLogOptions, type RedisEventLogLikeClient, RedisRunEventLog, type RedisRunEventLogOptions, } from './events.js';
|
|
14
14
|
export { type NodeListenerOptions, type NodeRequestLike, type NodeResponseLike, toNodeListener, } from './node.js';
|
|
15
|
+
export type { ListPage } from './list-page.js';
|
|
15
16
|
export { type DrainResult, RunManager, type RunManagerOptions, type RunQueueOptions, type StartRunOptions, } from './runs.js';
|
|
16
17
|
export { type AgentServer, type AgentServerOptions, createAgentServer } from './server.js';
|
|
17
18
|
export { fromStore, MemoryServerStore, type StoreLike } from './state.js';
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The order an agent server lists threads and runs in, and the cursor that pages through it. The
|
|
3
|
+
* regional gateway reads both, so a cursor one region gave pages every region the same way.
|
|
4
|
+
*/
|
|
5
|
+
/** A page of a list, newest first, and the cursor of the page after it. */
|
|
6
|
+
export interface ListPage<T> {
|
|
7
|
+
/** The page's records, newest first. */
|
|
8
|
+
items: T[];
|
|
9
|
+
/** Asks for the page after this one, as `cursor`. Absent on the last page. */
|
|
10
|
+
nextCursor?: string;
|
|
11
|
+
}
|
|
12
|
+
/** A record as a list places it: by its last write, then its id. */
|
|
13
|
+
interface Listed {
|
|
14
|
+
id?: unknown;
|
|
15
|
+
updatedAt?: unknown;
|
|
16
|
+
createdAt?: unknown;
|
|
17
|
+
}
|
|
18
|
+
/** Where a record falls in a list. */
|
|
19
|
+
interface Place {
|
|
20
|
+
at: string;
|
|
21
|
+
id: string;
|
|
22
|
+
}
|
|
23
|
+
/** Every list's order: the newest written first, and by id among records written at the same time. */
|
|
24
|
+
export declare function newestFirst(a: Listed, b: Listed): number;
|
|
25
|
+
/** The cursor of the page after one that ends with `record`. */
|
|
26
|
+
export declare function cursorAfter(record: Listed): string;
|
|
27
|
+
/** The place a cursor names, or `undefined` for one no list gave. */
|
|
28
|
+
export declare function readCursor(cursor: string): Place | undefined;
|
|
29
|
+
/** Whether `record` comes after `place`, so belongs to the pages after the cursor that names it. */
|
|
30
|
+
export declare function isAfter(record: Listed, place: Place): boolean;
|
|
31
|
+
/**
|
|
32
|
+
* The page of the records `keep` takes, after `after`, from a store that lists newest written first.
|
|
33
|
+
* It reads more of the store until the page is full or the store ends. Until the store ends, only
|
|
34
|
+
* records newer than the oldest one read are placed for sure: another written in that same instant
|
|
35
|
+
* may be unread yet, and come before them by id.
|
|
36
|
+
*/
|
|
37
|
+
export declare function pageOf<R extends Listed>(list: (limit: number) => Promise<R[]> | R[], keep: (record: R) => boolean, limit: number, after: Place | undefined): Promise<ListPage<R>>;
|
|
38
|
+
export {};
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
const placeOf = (record) => ({
|
|
2
|
+
at: String(record.updatedAt ?? record.createdAt ?? ''),
|
|
3
|
+
id: String(record.id ?? ''),
|
|
4
|
+
});
|
|
5
|
+
const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
|
|
6
|
+
export function newestFirst(a, b) {
|
|
7
|
+
const x = placeOf(a);
|
|
8
|
+
const y = placeOf(b);
|
|
9
|
+
return compare(y.at, x.at) || compare(x.id, y.id);
|
|
10
|
+
}
|
|
11
|
+
export function cursorAfter(record) {
|
|
12
|
+
const { at, id } = placeOf(record);
|
|
13
|
+
const bytes = new TextEncoder().encode(JSON.stringify([at, id]));
|
|
14
|
+
return btoa(String.fromCharCode(...bytes))
|
|
15
|
+
.replace(/\+/g, '-')
|
|
16
|
+
.replace(/\//g, '_')
|
|
17
|
+
.replace(/=+$/, '');
|
|
18
|
+
}
|
|
19
|
+
export function readCursor(cursor) {
|
|
20
|
+
try {
|
|
21
|
+
const binary = atob(cursor.replace(/-/g, '+').replace(/_/g, '/'));
|
|
22
|
+
const parsed = JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0))));
|
|
23
|
+
if (Array.isArray(parsed) && parsed.length === 2 && parsed.every((part) => typeof part === 'string')) {
|
|
24
|
+
return { at: parsed[0], id: parsed[1] };
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
catch {
|
|
28
|
+
}
|
|
29
|
+
return undefined;
|
|
30
|
+
}
|
|
31
|
+
export function isAfter(record, place) {
|
|
32
|
+
const own = placeOf(record);
|
|
33
|
+
return own.at < place.at || (own.at === place.at && own.id > place.id);
|
|
34
|
+
}
|
|
35
|
+
export async function pageOf(list, keep, limit, after) {
|
|
36
|
+
for (let window = limit + 2;; window *= 4) {
|
|
37
|
+
const read = await list(window);
|
|
38
|
+
const ended = read.length < window;
|
|
39
|
+
const times = read.map((record) => placeOf(record).at);
|
|
40
|
+
const oldest = times.reduce((min, at) => (at < min ? at : min), times[0] ?? '');
|
|
41
|
+
const placed = read
|
|
42
|
+
.filter((record) => keep(record) && (!after || isAfter(record, after)) && (ended || placeOf(record).at > oldest))
|
|
43
|
+
.sort(newestFirst);
|
|
44
|
+
if (placed.length > limit || ended) {
|
|
45
|
+
const items = placed.slice(0, limit);
|
|
46
|
+
return placed.length > limit ? { items, nextCursor: cursorAfter(items[limit - 1]) } : { items };
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
}
|
package/dist/server/regions.d.ts
CHANGED
|
@@ -32,6 +32,12 @@ export interface RegionalGatewayOptions {
|
|
|
32
32
|
health?: RegionHealthOptions;
|
|
33
33
|
/** Replaces the global `fetch` for regions given by URL. */
|
|
34
34
|
fetch?: typeof globalThis.fetch;
|
|
35
|
+
/**
|
|
36
|
+
* How `GET /threads` and `GET /runs` are answered: `merged`, the default, asks every region the
|
|
37
|
+
* tenant may reach and merges their answers, newest first; `home` asks the home region alone, as
|
|
38
|
+
* before 2.18.
|
|
39
|
+
*/
|
|
40
|
+
lists?: 'merged' | 'home';
|
|
35
41
|
/** Hears each failure to reach a region. */
|
|
36
42
|
onError?: (error: unknown, region: string) => void;
|
|
37
43
|
/** Replaces the system clock, for tests. */
|
|
@@ -67,13 +73,21 @@ export interface RegionalGateway {
|
|
|
67
73
|
/** Stops `start()`. */
|
|
68
74
|
stop(): void;
|
|
69
75
|
}
|
|
76
|
+
/** A region a merged list could not ask, and why. */
|
|
77
|
+
export interface RegionListGap {
|
|
78
|
+
/** The region. */
|
|
79
|
+
region: string;
|
|
80
|
+
/** Why it is missing: down, unreachable, or what it answered. */
|
|
81
|
+
reason: string;
|
|
82
|
+
}
|
|
70
83
|
/**
|
|
71
84
|
* A gateway in front of one agent server per region. A request for a thread or a run, whose id names
|
|
72
85
|
* the region that holds its data, goes to that region only: refused with a 403 when the tenant may not
|
|
73
86
|
* reach it, and answered 503 while the region is down, since its data is there and nowhere else. A
|
|
74
87
|
* request for new work goes to the tenant's home region, the first region it may reach, and, when that
|
|
75
88
|
* is down or does not answer, to the next one it may reach, never to another. A tenant that may reach
|
|
76
|
-
* no region the gateway serves is refused with a 403 naming the rule.
|
|
89
|
+
* no region the gateway serves is refused with a 403 naming the rule. A list of the tenant's threads or
|
|
90
|
+
* runs is gathered from every region it may reach, newest first, naming any that could not answer.
|
|
77
91
|
*
|
|
78
92
|
* ```ts
|
|
79
93
|
* const gateway = regionalGateway({
|
package/dist/server/regions.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { ResidencyError } from '../residency/errors.js';
|
|
2
|
+
import { cursorAfter, isAfter, newestFirst, readCursor } from './list-page.js';
|
|
2
3
|
const REGIONAL_ID = /^([A-Za-z0-9_.-]+)~(?:thread|run)-/;
|
|
4
|
+
const LIST = /\/(threads|runs)\/?$/;
|
|
3
5
|
export function regionalGateway(options) {
|
|
4
6
|
const now = options.now ?? (() => new Date());
|
|
5
7
|
const failuresToDown = Math.max(1, options.health?.failuresToDown ?? 1);
|
|
@@ -45,6 +47,71 @@ export function regionalGateway(options) {
|
|
|
45
47
|
});
|
|
46
48
|
const residencyRefusal = (region, decision, detail) => refuse(403, 'RESIDENCY_DENIED', new ResidencyError({ kind: 'region', name: region ?? 'any', ...(region ? { region } : {}) }, decision, detail)
|
|
47
49
|
.message);
|
|
50
|
+
const merged = async (kind, request, allowed) => {
|
|
51
|
+
const query = new URL(request.url).searchParams;
|
|
52
|
+
const cursor = query.get('cursor') || undefined;
|
|
53
|
+
const after = cursor === undefined ? undefined : readCursor(cursor);
|
|
54
|
+
if (cursor !== undefined && !after)
|
|
55
|
+
return refuse(400, 'BAD_REQUEST', '"cursor" is not one a list gave');
|
|
56
|
+
const gaps = allowed
|
|
57
|
+
.filter((region) => !isUp(region))
|
|
58
|
+
.map((region) => ({ region, reason: 'down' }));
|
|
59
|
+
const answers = await Promise.all(allowed.filter(isUp).map(async (region) => {
|
|
60
|
+
try {
|
|
61
|
+
const response = await send(region, request, undefined);
|
|
62
|
+
if (!response.ok) {
|
|
63
|
+
if (response.status === 502 || response.status === 504)
|
|
64
|
+
failed(region, `answered ${response.status}`);
|
|
65
|
+
return { region, response };
|
|
66
|
+
}
|
|
67
|
+
succeeded(region);
|
|
68
|
+
const body = (await response.json());
|
|
69
|
+
return {
|
|
70
|
+
region,
|
|
71
|
+
items: Array.isArray(body[kind]) ? body[kind] : [],
|
|
72
|
+
more: typeof body.nextCursor === 'string',
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
catch (error) {
|
|
76
|
+
options.onError?.(error, region);
|
|
77
|
+
failed(region, error instanceof Error ? error.message : String(error));
|
|
78
|
+
return { region, error: error instanceof Error ? error.message : String(error) };
|
|
79
|
+
}
|
|
80
|
+
}));
|
|
81
|
+
const answered = answers.filter((answer) => answer.items).map((answer) => answer.region);
|
|
82
|
+
for (const answer of answers) {
|
|
83
|
+
if (answer.response)
|
|
84
|
+
gaps.push({ region: answer.region, reason: `answered ${answer.response.status}` });
|
|
85
|
+
else if (answer.error !== undefined)
|
|
86
|
+
gaps.push({ region: answer.region, reason: answer.error });
|
|
87
|
+
}
|
|
88
|
+
if (answered.length === 0) {
|
|
89
|
+
const refused = answers.find((answer) => answer.response && answer.response.status < 500)?.response;
|
|
90
|
+
if (refused)
|
|
91
|
+
return refused;
|
|
92
|
+
return refuse(503, 'REGION_DOWN', `No region this list may reach answered: ${allowed.join(', ')}`, {
|
|
93
|
+
'retry-after': String(Math.ceil((options.health?.everyMs ?? 10_000) / 1000)),
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
const requested = Number(query.get('limit'));
|
|
97
|
+
const limit = Number.isInteger(requested) && requested > 0 ? requested : 50;
|
|
98
|
+
const all = answers
|
|
99
|
+
.flatMap((answer) => answer.items ?? [])
|
|
100
|
+
.filter((item) => !after || isAfter(item, after))
|
|
101
|
+
.sort(newestFirst);
|
|
102
|
+
const items = all.slice(0, limit);
|
|
103
|
+
const more = all.length > limit || answers.some((answer) => answer.more);
|
|
104
|
+
const last = items[items.length - 1];
|
|
105
|
+
return new Response(JSON.stringify({
|
|
106
|
+
[kind]: items,
|
|
107
|
+
...(more && last ? { nextCursor: cursorAfter(last) } : {}),
|
|
108
|
+
regions: answered,
|
|
109
|
+
...(gaps.length ? { incomplete: gaps } : {}),
|
|
110
|
+
}), {
|
|
111
|
+
status: 200,
|
|
112
|
+
headers: { 'content-type': 'application/json; charset=utf-8', 'x-nexus-region': answered.join(',') },
|
|
113
|
+
});
|
|
114
|
+
};
|
|
48
115
|
const gateway = {
|
|
49
116
|
async handle(request) {
|
|
50
117
|
const decision = await options.residency.regionsFor(await options.tenantOf(request));
|
|
@@ -78,6 +145,9 @@ export function regionalGateway(options) {
|
|
|
78
145
|
const allowed = (decision.regions ?? Object.keys(options.regions)).filter((region) => region in options.regions);
|
|
79
146
|
if (allowed.length === 0)
|
|
80
147
|
return residencyRefusal(undefined, decision, 'no region it may reach is served here');
|
|
148
|
+
const list = request.method === 'GET' ? LIST.exec(path)?.[1] : undefined;
|
|
149
|
+
if (list && (options.lists ?? 'merged') === 'merged')
|
|
150
|
+
return merged(list, request, allowed);
|
|
81
151
|
const candidates = allowed.filter(isUp);
|
|
82
152
|
if (candidates.length === 0) {
|
|
83
153
|
return refuse(503, 'REGION_DOWN', `Every region this request may reach is down: ${allowed.join(', ')}`, {
|
package/dist/server/runs.d.ts
CHANGED
|
@@ -3,6 +3,7 @@ import type { Tracer } from '../tracing/tracer.js';
|
|
|
3
3
|
import type { ResidencyPolicy } from '../types/residency.js';
|
|
4
4
|
import type { RunFeedback } from '../types/tracing.js';
|
|
5
5
|
import type { Principal, ReplicaReport, RunEventLog, RunRecord, ScalingSnapshot, ServerAssistant, ServerDeployments, ServerStateStore, TenantGate, ThreadBusyPolicy, ThreadRecord } from '../types/server.js';
|
|
6
|
+
import { type ListPage } from './list-page.js';
|
|
6
7
|
import { ServerMetrics } from './metrics.js';
|
|
7
8
|
/** What a run needs to start. */
|
|
8
9
|
export interface StartRunOptions {
|
|
@@ -168,6 +169,20 @@ export declare class RunManager {
|
|
|
168
169
|
thread(threadId: string, principal?: Principal): Promise<ThreadRecord>;
|
|
169
170
|
/** Threads of a tenant, newest written first. */
|
|
170
171
|
threads(principal?: Principal, limit?: number): Promise<ThreadRecord[]>;
|
|
172
|
+
/**
|
|
173
|
+
* A page of a tenant's threads, newest written first, 50 unless `limit` says otherwise. `cursor` is
|
|
174
|
+
* a page's `nextCursor`, and asks for the page after it.
|
|
175
|
+
*/
|
|
176
|
+
listThreads(principal?: Principal, options?: {
|
|
177
|
+
limit?: number;
|
|
178
|
+
cursor?: string;
|
|
179
|
+
}): Promise<ListPage<ThreadRecord>>;
|
|
180
|
+
/**
|
|
181
|
+
* Reads a namespace, newest written first, until a page of the records `keep` takes is full or the
|
|
182
|
+
* namespace ends, so another tenant's newer records never crowd a tenant's page out. A page deep in
|
|
183
|
+
* a long list reads every record before it.
|
|
184
|
+
*/
|
|
185
|
+
private page;
|
|
171
186
|
/** Deletes a thread's record. The assistant's own checkpoints are left alone. */
|
|
172
187
|
deleteThread(threadId: string, principal?: Principal): Promise<void>;
|
|
173
188
|
/** The assistant's state for a thread, from the revision the thread last ran on. */
|
|
@@ -179,6 +194,15 @@ export declare class RunManager {
|
|
|
179
194
|
threadId?: string;
|
|
180
195
|
limit?: number;
|
|
181
196
|
}): Promise<RunRecord[]>;
|
|
197
|
+
/**
|
|
198
|
+
* A page of a tenant's runs, newest written first, optionally for one thread, 50 unless `limit` says
|
|
199
|
+
* otherwise. `cursor` is a page's `nextCursor`, and asks for the page after it.
|
|
200
|
+
*/
|
|
201
|
+
listRuns(principal?: Principal, options?: {
|
|
202
|
+
threadId?: string;
|
|
203
|
+
limit?: number;
|
|
204
|
+
cursor?: string;
|
|
205
|
+
}): Promise<ListPage<RunRecord>>;
|
|
182
206
|
/**
|
|
183
207
|
* Accepts a run and starts it in the background.
|
|
184
208
|
*
|
package/dist/server/runs.js
CHANGED
|
@@ -4,6 +4,7 @@ import { operationStats } from '../operations/stats.js';
|
|
|
4
4
|
import { MemoryOperationStore } from '../operations/store.js';
|
|
5
5
|
import { AssistantCapabilityError, BadRequestError, NotFoundError, TenantLimitError, ThreadBusyError, } from './errors.js';
|
|
6
6
|
import { MemoryRunEventLog } from './events.js';
|
|
7
|
+
import { pageOf, readCursor } from './list-page.js';
|
|
7
8
|
import { gauge, gauges, ServerMetrics } from './metrics.js';
|
|
8
9
|
import { MemoryServerStore, RUNS_NAMESPACE } from './state.js';
|
|
9
10
|
const THREADS = ['nexus', 'server', 'threads'];
|
|
@@ -128,8 +129,19 @@ export class RunManager {
|
|
|
128
129
|
return thread;
|
|
129
130
|
}
|
|
130
131
|
async threads(principal, limit) {
|
|
131
|
-
|
|
132
|
-
|
|
132
|
+
return (await this.listThreads(principal, { limit })).items;
|
|
133
|
+
}
|
|
134
|
+
async listThreads(principal, options = {}) {
|
|
135
|
+
return this.page(THREADS, (thread) => sameTenant(thread.tenantId, principal), options);
|
|
136
|
+
}
|
|
137
|
+
async page(namespace, keep, options) {
|
|
138
|
+
const limit = options.limit ?? 50;
|
|
139
|
+
if (!Number.isInteger(limit) || limit < 1)
|
|
140
|
+
throw new BadRequestError('"limit" must be a whole number above 0');
|
|
141
|
+
const after = options.cursor === undefined ? undefined : readCursor(options.cursor);
|
|
142
|
+
if (options.cursor !== undefined && !after)
|
|
143
|
+
throw new BadRequestError('"cursor" is not one a list gave');
|
|
144
|
+
return pageOf((window) => this.state.list(namespace, { limit: window }), keep, limit, after);
|
|
133
145
|
}
|
|
134
146
|
async deleteThread(threadId, principal) {
|
|
135
147
|
await this.thread(threadId, principal);
|
|
@@ -149,8 +161,10 @@ export class RunManager {
|
|
|
149
161
|
return run;
|
|
150
162
|
}
|
|
151
163
|
async runs(principal, options = {}) {
|
|
152
|
-
|
|
153
|
-
|
|
164
|
+
return (await this.listRuns(principal, options)).items;
|
|
165
|
+
}
|
|
166
|
+
async listRuns(principal, options = {}) {
|
|
167
|
+
return this.page(RUNS, (run) => sameTenant(run.tenantId, principal) && (!options.threadId || run.threadId === options.threadId), options);
|
|
154
168
|
}
|
|
155
169
|
async start(options) {
|
|
156
170
|
const base = this.assistant(options.assistant);
|
package/dist/server/server.js
CHANGED
|
@@ -93,12 +93,16 @@ export function createAgentServer(options) {
|
|
|
93
93
|
const thread = await runs.createThread({ ...body, assistant: body.assistant, principal });
|
|
94
94
|
return json(thread, 201);
|
|
95
95
|
});
|
|
96
|
-
read('GET', '/threads', async ({ principal, url }) =>
|
|
96
|
+
read('GET', '/threads', async ({ principal, url }) => {
|
|
97
|
+
const page = await runs.listThreads(principal, listParams(url));
|
|
98
|
+
return json({ threads: page.items, ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}) });
|
|
99
|
+
});
|
|
97
100
|
read('GET', '/threads/:threadId', async ({ params, principal }) => json(await runs.thread(params.threadId, principal)));
|
|
98
101
|
read('GET', '/threads/:threadId/state', async ({ params, principal }) => json({ threadId: params.threadId, state: await runs.threadState(params.threadId, principal) }));
|
|
99
|
-
read('GET', '/threads/:threadId/runs', async ({ params, principal, url }) =>
|
|
100
|
-
|
|
101
|
-
|
|
102
|
+
read('GET', '/threads/:threadId/runs', async ({ params, principal, url }) => {
|
|
103
|
+
const page = await runs.listRuns(principal, { threadId: params.threadId, ...listParams(url) });
|
|
104
|
+
return json({ runs: page.items, ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}) });
|
|
105
|
+
});
|
|
102
106
|
write('DELETE', '/threads/:threadId', async ({ params, principal }) => {
|
|
103
107
|
await runs.deleteThread(params.threadId, principal);
|
|
104
108
|
return new Response(null, { status: 204 });
|
|
@@ -135,7 +139,10 @@ export function createAgentServer(options) {
|
|
|
135
139
|
});
|
|
136
140
|
return body.stream || url.searchParams.get('stream') === 'true' ? streamRun(run.id) : json(run, 202);
|
|
137
141
|
});
|
|
138
|
-
read('GET', '/runs', async ({ principal, url }) =>
|
|
142
|
+
read('GET', '/runs', async ({ principal, url }) => {
|
|
143
|
+
const page = await runs.listRuns(principal, listParams(url));
|
|
144
|
+
return json({ runs: page.items, ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}) });
|
|
145
|
+
});
|
|
139
146
|
read('GET', '/runs/:runId', async ({ params, principal }) => json(await runs.run(params.runId, principal)));
|
|
140
147
|
write('POST', '/runs/:runId/cancel', async ({ request, params, principal }) => {
|
|
141
148
|
const body = await readJson(request);
|
|
@@ -309,6 +316,11 @@ function numberParam(url, name) {
|
|
|
309
316
|
throw new ServerError(`"${name}" must be a number`, 'BAD_REQUEST', 400);
|
|
310
317
|
return parsed;
|
|
311
318
|
}
|
|
319
|
+
function listParams(url) {
|
|
320
|
+
const limit = numberParam(url, 'limit');
|
|
321
|
+
const cursor = url.searchParams.get('cursor');
|
|
322
|
+
return { ...(limit === undefined ? {} : { limit }), ...(cursor ? { cursor } : {}) };
|
|
323
|
+
}
|
|
312
324
|
function isFinishedStatus(status) {
|
|
313
325
|
return status === 'succeeded' || status === 'failed' || status === 'cancelled' || status === 'expired';
|
|
314
326
|
}
|
package/dist/tracing/index.d.ts
CHANGED
|
@@ -2,5 +2,5 @@ export { type AlertEvent, AlertEvaluator, type AlertMetric, type AlertNotifier,
|
|
|
2
2
|
export { compareTraces, formatTree, type RunDifference, type TraceComparison } from './compare.js';
|
|
3
3
|
export { type GraphTracing, type GraphTracingOptions, type ModelClientLike, type RetrieverLike, traceGraph, traceModelClient, traceRetriever, } from './instrument.js';
|
|
4
4
|
export { applyQuery, assembleTree, closeAbandonedRuns, type CloseAbandonedRunsOptions, isAfterCursor, JsonlTraceStore, type JsonlTraceStoreOptions, MemoryTraceStore, type MemoryTraceStoreOptions, runCursor, } from './stores.js';
|
|
5
|
-
export { type FinishRunOptions, type RunHandle, type StartRunOptions, stripFields, Tracer, type TracerOptions, w3cSpanId, w3cTraceId, } from './tracer.js';
|
|
6
|
-
export type { RedactionPolicy, Run, RunCursor, RunFeedback, RunKind, RunQuery, RunStatus, RunTree, SamplingPolicy, TraceExporter, TraceStore, } from '../types/tracing.js';
|
|
5
|
+
export { type FinishRunOptions, type RunEventInput, type RunHandle, type RunLinkInput, type StartRunOptions, stripFields, Tracer, type TracerOptions, w3cSpanId, w3cTraceId, } from './tracer.js';
|
|
6
|
+
export type { RedactionPolicy, Run, RunAttributeValue, RunCursor, RunEvent, RunFeedback, RunKind, RunLink, RunQuery, RunStatus, RunTree, SamplingPolicy, TraceExporter, TraceStore, } from '../types/tracing.js';
|
|
@@ -35,8 +35,9 @@ export interface GraphTracing {
|
|
|
35
35
|
* Records a graph or agent run as a trace.
|
|
36
36
|
*
|
|
37
37
|
* The graph already reports every task starting, retrying, and finishing; tracing is that stream
|
|
38
|
-
* written down as a tree.
|
|
39
|
-
*
|
|
38
|
+
* written down as a tree. A retry is an event on its task's run, and a tool's progress an event on
|
|
39
|
+
* the tool's. A task that follows a step of several tasks, such as the join after a fan-out, links to
|
|
40
|
+
* each of them. Nothing inside the graph knows about tracing, and a run without it pays nothing.
|
|
40
41
|
*/
|
|
41
42
|
export declare function traceGraph(tracer: Tracer, options?: GraphTracingOptions): GraphTracing;
|
|
42
43
|
/** Any client with a `complete()` method. */
|
|
@@ -49,6 +50,10 @@ export interface ModelClientLike {
|
|
|
49
50
|
*
|
|
50
51
|
* `parent` decides where the call hangs: pass `() => tracing.runFor('model')` and a model call lands
|
|
51
52
|
* inside the node that made it rather than beside it.
|
|
53
|
+
*
|
|
54
|
+
* What the response reports becomes the run's events: each attempt that failed before it, as `retry`
|
|
55
|
+
* on the same provider or `failover` to another, at the time it failed; each guardrail applied, as
|
|
56
|
+
* `guardrail`; the cache's answer, as `cache`; and each capability warning.
|
|
52
57
|
*/
|
|
53
58
|
export declare function traceModelClient<T extends ModelClientLike>(client: T, tracer: Tracer, options?: {
|
|
54
59
|
parent?: () => RunHandle | undefined;
|
|
@@ -12,20 +12,29 @@ export function traceGraph(tracer, options = {}) {
|
|
|
12
12
|
const emitted = new Map();
|
|
13
13
|
const tools = new Map();
|
|
14
14
|
const progress = new Map();
|
|
15
|
+
const steps = new Map();
|
|
15
16
|
const onEvent = (event) => {
|
|
16
17
|
switch (event.type) {
|
|
17
18
|
case 'task_start': {
|
|
18
19
|
if (active.has(event.taskId))
|
|
19
20
|
return;
|
|
20
|
-
|
|
21
|
+
const scope = (event.namespace ?? []).join('/');
|
|
22
|
+
const before = steps.get(`${scope}:${event.step - 1}`) ?? [];
|
|
23
|
+
const handle = root.child({
|
|
21
24
|
name: event.node,
|
|
22
25
|
kind: 'node',
|
|
23
26
|
metadata: { step: event.step, taskId: event.taskId },
|
|
24
|
-
|
|
27
|
+
...(before.length > 1 ? { links: before.map((run) => run.link({ 'nexus.link': 'previous_step' })) } : {}),
|
|
28
|
+
});
|
|
29
|
+
active.set(event.taskId, handle);
|
|
30
|
+
const key = `${scope}:${event.step}`;
|
|
31
|
+
steps.set(key, [...(steps.get(key) ?? []), handle]);
|
|
32
|
+
steps.delete(`${scope}:${event.step - 2}`);
|
|
25
33
|
return;
|
|
26
34
|
}
|
|
27
35
|
case 'task_retry': {
|
|
28
36
|
retries.set(event.taskId, event.attempt);
|
|
37
|
+
active.get(event.taskId)?.event('retry', { 'nexus.attempt': event.attempt, 'error.message': event.error });
|
|
29
38
|
return;
|
|
30
39
|
}
|
|
31
40
|
case 'tool': {
|
|
@@ -41,6 +50,7 @@ export function traceGraph(tracer, options = {}) {
|
|
|
41
50
|
return;
|
|
42
51
|
}
|
|
43
52
|
if (event.tool.phase === 'progress') {
|
|
53
|
+
tools.get(key)?.event('progress', progressAttributes(event.tool.progress));
|
|
44
54
|
const reports = [
|
|
45
55
|
...(progress.get(key) ?? []),
|
|
46
56
|
{ at: new Date().toISOString(), progress: event.tool.progress },
|
|
@@ -146,6 +156,7 @@ export function traceModelClient(client, tracer, options = {}) {
|
|
|
146
156
|
...(response.meta?.cost?.amount === undefined ? {} : { cost: response.meta.cost.amount }),
|
|
147
157
|
...(response.meta?.modelUsed ? { model: response.meta.modelUsed } : {}),
|
|
148
158
|
...(response.meta?.providerUsed ? { provider: response.meta.providerUsed } : {}),
|
|
159
|
+
events: responseEvents(response),
|
|
149
160
|
metadata: {
|
|
150
161
|
provider: response.meta?.providerUsed,
|
|
151
162
|
model: response.meta?.modelUsed,
|
|
@@ -194,3 +205,59 @@ export function traceRetriever(retriever, tracer, options = {}) {
|
|
|
194
205
|
},
|
|
195
206
|
});
|
|
196
207
|
}
|
|
208
|
+
function progressAttributes(report) {
|
|
209
|
+
if (typeof report === 'number')
|
|
210
|
+
return { 'nexus.progress': report };
|
|
211
|
+
if (typeof report === 'string')
|
|
212
|
+
return { 'nexus.progress.message': report };
|
|
213
|
+
if (report && typeof report === 'object') {
|
|
214
|
+
const { progress, total, message } = report;
|
|
215
|
+
const attributes = {};
|
|
216
|
+
if (typeof progress === 'number')
|
|
217
|
+
attributes['nexus.progress'] = progress;
|
|
218
|
+
if (typeof total === 'number')
|
|
219
|
+
attributes['nexus.progress.total'] = total;
|
|
220
|
+
if (typeof message === 'string')
|
|
221
|
+
attributes['nexus.progress.message'] = message;
|
|
222
|
+
if (Object.keys(attributes).length)
|
|
223
|
+
return attributes;
|
|
224
|
+
}
|
|
225
|
+
return { 'nexus.progress.message': JSON.stringify(report)?.slice(0, 1024) ?? String(report) };
|
|
226
|
+
}
|
|
227
|
+
function responseEvents(response) {
|
|
228
|
+
const meta = response.meta;
|
|
229
|
+
if (!meta)
|
|
230
|
+
return [];
|
|
231
|
+
const events = [];
|
|
232
|
+
for (const attempt of meta.failedAttempts ?? []) {
|
|
233
|
+
events.push({
|
|
234
|
+
name: attempt.provider === meta.providerUsed ? 'retry' : 'failover',
|
|
235
|
+
time: attempt.at,
|
|
236
|
+
attributes: {
|
|
237
|
+
'gen_ai.provider.name': attempt.provider,
|
|
238
|
+
'gen_ai.request.model': attempt.model,
|
|
239
|
+
'error.message': attempt.error,
|
|
240
|
+
...(attempt.category ? { 'error.type': attempt.category } : {}),
|
|
241
|
+
},
|
|
242
|
+
});
|
|
243
|
+
}
|
|
244
|
+
for (const name of meta.guardrailsApplied ?? [])
|
|
245
|
+
events.push({ name: 'guardrail', attributes: { 'nexus.guardrail': name } });
|
|
246
|
+
if (meta.cache) {
|
|
247
|
+
events.push({
|
|
248
|
+
name: 'cache',
|
|
249
|
+
attributes: {
|
|
250
|
+
'nexus.cache.outcome': meta.cache.outcome,
|
|
251
|
+
...(meta.cache.layer ? { 'nexus.cache.layer': meta.cache.layer } : {}),
|
|
252
|
+
'nexus.cache.reason': meta.cache.reason,
|
|
253
|
+
},
|
|
254
|
+
});
|
|
255
|
+
}
|
|
256
|
+
for (const warning of meta.capabilityWarnings ?? []) {
|
|
257
|
+
events.push({
|
|
258
|
+
name: 'capability_warning',
|
|
259
|
+
attributes: { 'nexus.capability.feature': warning.feature, 'nexus.capability.action': String(warning.action) },
|
|
260
|
+
});
|
|
261
|
+
}
|
|
262
|
+
return events;
|
|
263
|
+
}
|
|
@@ -108,6 +108,24 @@ function span(writer, item) {
|
|
|
108
108
|
writer.fixed64(8, BigInt(item.endTimeUnixNano));
|
|
109
109
|
for (const attribute of item.attributes)
|
|
110
110
|
writer.message(9, (inner) => keyValue(inner, attribute));
|
|
111
|
+
for (const event of item.events ?? []) {
|
|
112
|
+
writer.message(11, (inner) => {
|
|
113
|
+
inner.fixed64(1, BigInt(event.timeUnixNano));
|
|
114
|
+
inner.string(2, event.name);
|
|
115
|
+
for (const attribute of event.attributes)
|
|
116
|
+
inner.message(3, (kv) => keyValue(kv, attribute));
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
if (item.droppedEventsCount)
|
|
120
|
+
writer.uint(12, item.droppedEventsCount);
|
|
121
|
+
for (const link of item.links ?? []) {
|
|
122
|
+
writer.message(13, (inner) => {
|
|
123
|
+
inner.bytes(1, hex(link.traceId));
|
|
124
|
+
inner.bytes(2, hex(link.spanId));
|
|
125
|
+
for (const attribute of link.attributes)
|
|
126
|
+
inner.message(4, (kv) => keyValue(kv, attribute));
|
|
127
|
+
});
|
|
128
|
+
}
|
|
111
129
|
writer.message(15, (status) => {
|
|
112
130
|
if (item.status.message)
|
|
113
131
|
status.string(2, item.status.message);
|
package/dist/tracing/otlp.d.ts
CHANGED
|
@@ -97,12 +97,36 @@ export interface OtlpSpan {
|
|
|
97
97
|
endTimeUnixNano: string;
|
|
98
98
|
/** Typed attributes. */
|
|
99
99
|
attributes: OtlpKeyValue[];
|
|
100
|
+
/** What happened inside it, each at its time. */
|
|
101
|
+
events?: OtlpSpanEvent[];
|
|
102
|
+
/** Events the run counted rather than kept. */
|
|
103
|
+
droppedEventsCount?: number;
|
|
104
|
+
/** The spans it came from, beside its parent. */
|
|
105
|
+
links?: OtlpSpanLink[];
|
|
100
106
|
/** 1 ok, 2 error. */
|
|
101
107
|
status: {
|
|
102
108
|
code: number;
|
|
103
109
|
message?: string;
|
|
104
110
|
};
|
|
105
111
|
}
|
|
112
|
+
/** A span event in OTLP's JSON encoding. */
|
|
113
|
+
export interface OtlpSpanEvent {
|
|
114
|
+
/** Nanoseconds since the epoch, as a decimal string. */
|
|
115
|
+
timeUnixNano: string;
|
|
116
|
+
/** What happened. */
|
|
117
|
+
name: string;
|
|
118
|
+
/** What it carries. */
|
|
119
|
+
attributes: OtlpKeyValue[];
|
|
120
|
+
}
|
|
121
|
+
/** A span link in OTLP's JSON encoding. */
|
|
122
|
+
export interface OtlpSpanLink {
|
|
123
|
+
/** 32 hex digits. */
|
|
124
|
+
traceId: string;
|
|
125
|
+
/** 16 hex digits. */
|
|
126
|
+
spanId: string;
|
|
127
|
+
/** Why it is linked. */
|
|
128
|
+
attributes: OtlpKeyValue[];
|
|
129
|
+
}
|
|
106
130
|
/**
|
|
107
131
|
* Turns one finished run into an OpenTelemetry span, with the GenAI semantic conventions.
|
|
108
132
|
*
|
|
@@ -110,7 +134,8 @@ export interface OtlpSpan {
|
|
|
110
134
|
* `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, and
|
|
111
135
|
* `gen_ai.usage.input_tokens` and `output_tokens`. A tool run carries `gen_ai.tool.name`, an agent
|
|
112
136
|
* run `gen_ai.agent.name`. What only Nexus knows goes under `nexus.*`: the run kind, a graph node and
|
|
113
|
-
* its step, the cost, and the run id. A failed run has `error.type` and an error status.
|
|
137
|
+
* its step, the cost, and the run id. A failed run has `error.type` and an error status. The run's
|
|
138
|
+
* events become the span's events, and its links the span's links, to the spans of the runs named.
|
|
114
139
|
*/
|
|
115
140
|
export declare function runToOtlpSpan(run: Run): OtlpSpan;
|
|
116
141
|
/**
|