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.
Files changed (80) hide show
  1. package/API_STABILITY.md +35 -0
  2. package/CHANGELOG.md +78 -1
  3. package/README.md +7 -3
  4. package/dist/evaluate/media.d.ts +6 -2
  5. package/dist/evaluate/media.js +7 -21
  6. package/dist/index.d.ts +1 -1
  7. package/dist/mcp/client.d.ts +25 -2
  8. package/dist/mcp/client.js +82 -47
  9. package/dist/mcp/server.d.ts +1 -1
  10. package/dist/mcp/server.js +4 -1
  11. package/dist/protocols/acp-editor.js +42 -15
  12. package/dist/router/failover.js +19 -1
  13. package/dist/server/index.d.ts +1 -0
  14. package/dist/server/list-page.d.ts +38 -0
  15. package/dist/server/list-page.js +49 -0
  16. package/dist/server/regions.d.ts +15 -1
  17. package/dist/server/regions.js +70 -0
  18. package/dist/server/runs.d.ts +24 -0
  19. package/dist/server/runs.js +18 -4
  20. package/dist/server/server.js +17 -5
  21. package/dist/tracing/index.d.ts +2 -2
  22. package/dist/tracing/instrument.d.ts +7 -2
  23. package/dist/tracing/instrument.js +69 -2
  24. package/dist/tracing/otlp-proto.js +18 -0
  25. package/dist/tracing/otlp.d.ts +26 -1
  26. package/dist/tracing/otlp.js +19 -0
  27. package/dist/tracing/tracer.d.ts +36 -1
  28. package/dist/tracing/tracer.js +68 -2
  29. package/dist/types/response.d.ts +18 -0
  30. package/dist/types/tracing.d.ts +32 -0
  31. package/dist/utils/media-duration.d.ts +20 -0
  32. package/dist/utils/media-duration.js +334 -0
  33. package/dist/version.d.ts +1 -1
  34. package/dist/version.js +1 -1
  35. package/dist/video/google.d.ts +8 -0
  36. package/dist/video/google.js +31 -9
  37. package/dist/video/index.d.ts +18 -3
  38. package/dist/video/index.js +46 -3
  39. package/dist/video/mock.js +3 -1
  40. package/dist/video/runway.d.ts +2 -0
  41. package/dist/video/runway.js +45 -11
  42. package/dist-cjs/evaluate/media.d.ts +6 -2
  43. package/dist-cjs/evaluate/media.js +9 -21
  44. package/dist-cjs/index.d.ts +1 -1
  45. package/dist-cjs/mcp/client.d.ts +25 -2
  46. package/dist-cjs/mcp/client.js +82 -47
  47. package/dist-cjs/mcp/server.d.ts +1 -1
  48. package/dist-cjs/mcp/server.js +4 -1
  49. package/dist-cjs/protocols/acp-editor.js +42 -15
  50. package/dist-cjs/router/failover.js +19 -1
  51. package/dist-cjs/server/index.d.ts +1 -0
  52. package/dist-cjs/server/list-page.d.ts +38 -0
  53. package/dist-cjs/server/list-page.js +56 -0
  54. package/dist-cjs/server/regions.d.ts +15 -1
  55. package/dist-cjs/server/regions.js +70 -0
  56. package/dist-cjs/server/runs.d.ts +24 -0
  57. package/dist-cjs/server/runs.js +18 -4
  58. package/dist-cjs/server/server.js +17 -5
  59. package/dist-cjs/tracing/index.d.ts +2 -2
  60. package/dist-cjs/tracing/instrument.d.ts +7 -2
  61. package/dist-cjs/tracing/instrument.js +69 -2
  62. package/dist-cjs/tracing/otlp-proto.js +18 -0
  63. package/dist-cjs/tracing/otlp.d.ts +26 -1
  64. package/dist-cjs/tracing/otlp.js +19 -0
  65. package/dist-cjs/tracing/tracer.d.ts +36 -1
  66. package/dist-cjs/tracing/tracer.js +68 -2
  67. package/dist-cjs/types/response.d.ts +18 -0
  68. package/dist-cjs/types/tracing.d.ts +32 -0
  69. package/dist-cjs/utils/media-duration.d.ts +20 -0
  70. package/dist-cjs/utils/media-duration.js +337 -0
  71. package/dist-cjs/version.d.ts +1 -1
  72. package/dist-cjs/version.js +1 -1
  73. package/dist-cjs/video/google.d.ts +8 -0
  74. package/dist-cjs/video/google.js +31 -9
  75. package/dist-cjs/video/index.d.ts +18 -3
  76. package/dist-cjs/video/index.js +46 -3
  77. package/dist-cjs/video/mock.js +3 -1
  78. package/dist-cjs/video/runway.d.ts +2 -0
  79. package/dist-cjs/video/runway.js +45 -11
  80. package/package.json +1 -1
@@ -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
+ }
@@ -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
+ }
@@ -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({
@@ -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(', ')}`, {
@@ -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
  *
@@ -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
- const all = await this.state.list(THREADS, { limit: limit ?? 50 });
132
- return all.filter((thread) => sameTenant(thread.tenantId, principal));
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
- const all = await this.state.list(RUNS, { limit: options.limit ?? 50 });
153
- return all.filter((run) => sameTenant(run.tenantId, principal) && (!options.threadId || run.threadId === options.threadId));
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);
@@ -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 }) => json({ threads: await runs.threads(principal, numberParam(url, 'limit')) }));
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 }) => json({
100
- runs: await runs.runs(principal, { threadId: params.threadId, limit: numberParam(url, 'limit') }),
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 }) => json({ runs: await runs.runs(principal, { limit: numberParam(url, 'limit') }) }));
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
  }
@@ -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. Nothing inside the graph knows about tracing, and a run without it pays
39
- * nothing.
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
- active.set(event.taskId, root.child({
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);
@@ -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
  /**