nexus-ai-pro 2.18.0 → 2.20.2

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 (81) hide show
  1. package/API_STABILITY.md +64 -1
  2. package/CHANGELOG.md +113 -1
  3. package/README.md +11 -3
  4. package/dist/agent/capabilities.d.ts +3 -0
  5. package/dist/agent/openapi.d.ts +139 -0
  6. package/dist/agent/openapi.js +455 -0
  7. package/dist/capabilities/negotiate.js +5 -0
  8. package/dist/decisions/completion.d.ts +48 -0
  9. package/dist/decisions/completion.js +195 -0
  10. package/dist/decisions/core.d.ts +525 -0
  11. package/dist/decisions/core.js +493 -0
  12. package/dist/decisions/index.d.ts +9 -0
  13. package/dist/decisions/index.js +3 -0
  14. package/dist/decisions/integrations.d.ts +142 -0
  15. package/dist/decisions/integrations.js +170 -0
  16. package/dist/decisions/mock.d.ts +32 -0
  17. package/dist/decisions/mock.js +47 -0
  18. package/dist/decisions/typesafe.d.ts +45 -0
  19. package/dist/decisions/typesafe.js +144 -0
  20. package/dist/evaluate/emulate.d.ts +73 -6
  21. package/dist/evaluate/emulate.js +114 -12
  22. package/dist/index.d.ts +1 -1
  23. package/dist/optimizer/densifier.js +20 -11
  24. package/dist/protocols/a2a-grpc.js +1 -1
  25. package/dist/protocols/a2a-proto.d.ts +2 -2
  26. package/dist/protocols/a2a-proto.js +76 -1
  27. package/dist/protocols/a2a.d.ts +121 -0
  28. package/dist/protocols/a2a.js +88 -29
  29. package/dist/providers/google.js +28 -0
  30. package/dist/providers/ollama.js +23 -0
  31. package/dist/providers/openai.d.ts +6 -0
  32. package/dist/providers/openai.js +26 -0
  33. package/dist/types/lifecycle.d.ts +1 -1
  34. package/dist/types/messages.d.ts +9 -0
  35. package/dist/types/providers.d.ts +2 -0
  36. package/dist/types/response.d.ts +17 -0
  37. package/dist/types/tracing.d.ts +1 -1
  38. package/dist/version.d.ts +1 -1
  39. package/dist/version.js +1 -1
  40. package/dist/workflow/chains.d.ts +13 -1
  41. package/dist/workflow/chains.js +40 -0
  42. package/dist-cjs/agent/capabilities.d.ts +3 -0
  43. package/dist-cjs/agent/openapi.d.ts +139 -0
  44. package/dist-cjs/agent/openapi.js +461 -0
  45. package/dist-cjs/capabilities/negotiate.js +5 -0
  46. package/dist-cjs/decisions/completion.d.ts +48 -0
  47. package/dist-cjs/decisions/completion.js +198 -0
  48. package/dist-cjs/decisions/core.d.ts +525 -0
  49. package/dist-cjs/decisions/core.js +509 -0
  50. package/dist-cjs/decisions/index.d.ts +9 -0
  51. package/dist-cjs/decisions/index.js +27 -0
  52. package/dist-cjs/decisions/integrations.d.ts +142 -0
  53. package/dist-cjs/decisions/integrations.js +178 -0
  54. package/dist-cjs/decisions/mock.d.ts +32 -0
  55. package/dist-cjs/decisions/mock.js +51 -0
  56. package/dist-cjs/decisions/typesafe.d.ts +45 -0
  57. package/dist-cjs/decisions/typesafe.js +148 -0
  58. package/dist-cjs/evaluate/emulate.d.ts +73 -6
  59. package/dist-cjs/evaluate/emulate.js +116 -13
  60. package/dist-cjs/index.d.ts +1 -1
  61. package/dist-cjs/optimizer/densifier.js +20 -11
  62. package/dist-cjs/protocols/a2a-grpc.js +1 -1
  63. package/dist-cjs/protocols/a2a-proto.d.ts +2 -2
  64. package/dist-cjs/protocols/a2a-proto.js +76 -1
  65. package/dist-cjs/protocols/a2a.d.ts +121 -0
  66. package/dist-cjs/protocols/a2a.js +88 -29
  67. package/dist-cjs/providers/google.js +28 -0
  68. package/dist-cjs/providers/ollama.js +23 -0
  69. package/dist-cjs/providers/openai.d.ts +6 -0
  70. package/dist-cjs/providers/openai.js +26 -0
  71. package/dist-cjs/types/lifecycle.d.ts +1 -1
  72. package/dist-cjs/types/messages.d.ts +9 -0
  73. package/dist-cjs/types/providers.d.ts +2 -0
  74. package/dist-cjs/types/response.d.ts +17 -0
  75. package/dist-cjs/types/tracing.d.ts +1 -1
  76. package/dist-cjs/version.d.ts +1 -1
  77. package/dist-cjs/version.js +1 -1
  78. package/dist-cjs/workflow/chains.d.ts +13 -1
  79. package/dist-cjs/workflow/chains.js +40 -0
  80. package/llms.txt +2 -1
  81. package/package.json +54 -2
@@ -7,6 +7,7 @@ export const A2A_ERRORS = {
7
7
  unsupportedOperation: -32004,
8
8
  extendedCardNotConfigured: -32007,
9
9
  versionNotSupported: -32009,
10
+ permissionDenied: -32099,
10
11
  };
11
12
  export class A2aError extends Error {
12
13
  code;
@@ -45,7 +46,8 @@ export class MemoryA2aTaskStore {
45
46
  list(query) {
46
47
  const matching = [...this.tasks.values()]
47
48
  .filter((record) => (query.contextId === undefined || record.task.contextId === query.contextId) &&
48
- (query.state === undefined || record.task.status.state === query.state))
49
+ (query.state === undefined || record.task.status.state === query.state) &&
50
+ (query.tenant === undefined || record.tenant === query.tenant))
49
51
  .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
50
52
  return {
51
53
  records: matching.slice(query.offset, query.offset + query.limit).map((record) => structuredClone(record)),
@@ -83,6 +85,7 @@ export function storeA2aTasks(store, options = {}) {
83
85
  const filter = {
84
86
  ...(query.contextId === undefined ? {} : { 'task.contextId': query.contextId }),
85
87
  ...(query.state === undefined ? {} : { 'task.status.state': query.state }),
88
+ ...(query.tenant === undefined ? {} : { tenant: query.tenant }),
86
89
  };
87
90
  const items = await store.search(tasks, {
88
91
  limit: query.limit,
@@ -129,6 +132,7 @@ const ERROR_STATUS = {
129
132
  [-32007]: { httpStatus: 400, grpcStatus: 'FAILED_PRECONDITION', reason: 'EXTENDED_AGENT_CARD_NOT_CONFIGURED' },
130
133
  [-32008]: { httpStatus: 400, grpcStatus: 'FAILED_PRECONDITION', reason: 'EXTENSION_SUPPORT_REQUIRED' },
131
134
  [-32009]: { httpStatus: 400, grpcStatus: 'UNIMPLEMENTED', reason: 'VERSION_NOT_SUPPORTED' },
135
+ [-32099]: { httpStatus: 403, grpcStatus: 'PERMISSION_DENIED', reason: 'PERMISSION_DENIED' },
132
136
  [-32700]: { httpStatus: 400, grpcStatus: 'INVALID_ARGUMENT', reason: 'INVALID_PARAMS' },
133
137
  [-32600]: { httpStatus: 400, grpcStatus: 'INVALID_ARGUMENT', reason: 'INVALID_PARAMS' },
134
138
  [-32601]: { httpStatus: 404, grpcStatus: 'UNIMPLEMENTED', reason: 'METHOD_NOT_FOUND' },
@@ -184,7 +188,12 @@ export function a2aHandler(graph, options) {
184
188
  defaultInputModes: options.card.defaultInputModes ?? ['text/plain', 'application/json'],
185
189
  defaultOutputModes: options.card.defaultOutputModes ?? ['text/plain'],
186
190
  skills: options.card.skills,
191
+ ...(options.card.securitySchemes ? { securitySchemes: options.card.securitySchemes } : {}),
192
+ ...(options.card.securityRequirements ? { securityRequirements: options.card.securityRequirements } : {}),
193
+ ...(options.card.signatures ? { signatures: options.card.signatures } : {}),
187
194
  };
195
+ const tenancy = options.tenants ? (options.tenants === true ? {} : options.tenants) : undefined;
196
+ const conversationKey = (record) => record.tenant === undefined ? record.task.contextId : `${record.tenant}\u0000${record.task.contextId}`;
188
197
  const store = options.store ?? new MemoryA2aTaskStore({ maxTasks: options.maxTasks ?? 10_000 });
189
198
  const owner = options.lease?.owner ?? protocolId('replica');
190
199
  const leaseMs = options.lease?.ms ?? 30_000;
@@ -385,8 +394,8 @@ export function a2aHandler(graph, options) {
385
394
  const text = answerOf(result.state);
386
395
  const reply = agentMessage(task, text);
387
396
  record.history.push(reply);
388
- const before = (await store.conversation(task.contextId)) ?? [];
389
- await store.saveConversation(task.contextId, transcriptOf(result.state, [...before, messageOf('assistant', text)]));
397
+ const before = (await store.conversation(conversationKey(record))) ?? [];
398
+ await store.saveConversation(conversationKey(record), transcriptOf(result.state, [...before, messageOf('assistant', text)]));
390
399
  task.artifacts = [{ artifactId: `${task.id}:answer`, name: 'answer', parts: [{ text }] }];
391
400
  if (streamed) {
392
401
  const last = {
@@ -426,10 +435,10 @@ export function a2aHandler(graph, options) {
426
435
  }
427
436
  };
428
437
  const startRun = async (record, message, runOptions) => {
429
- const history = (await store.conversation(record.task.contextId)) ?? [];
438
+ const history = (await store.conversation(conversationKey(record))) ?? [];
430
439
  const said = messageOf('user', textOfParts(message.parts));
431
440
  const result = await graph.invoke(options.input ? options.input(message, history) : { messages: [...history, said] }, runOptions);
432
- await store.saveConversation(record.task.contextId, [...history, said]);
441
+ await store.saveConversation(conversationKey(record), [...history, said]);
433
442
  return result;
434
443
  };
435
444
  const carryOn = async (record, runOptions) => {
@@ -481,11 +490,12 @@ export function a2aHandler(graph, options) {
481
490
  void recover().catch((error) => options.onError?.(error));
482
491
  }, options.recoverEveryMs);
483
492
  timer?.unref?.();
484
- const taskFor = async (message, principal) => {
493
+ const taskFor = async (message, principal, mine, tenant) => {
485
494
  if (message.taskId) {
486
495
  const existing = await store.get(message.taskId);
487
- if (!existing)
496
+ if (!existing || !mine(existing)) {
488
497
  return { error: A2A_ERRORS.taskNotFound, message: `Task ${message.taskId} was not found` };
498
+ }
489
499
  if (existing.task.status.state !== 'TASK_STATE_INPUT_REQUIRED') {
490
500
  return { error: A2A_ERRORS.unsupportedOperation, message: `Task ${message.taskId} is not waiting for input` };
491
501
  }
@@ -504,6 +514,7 @@ export function a2aHandler(graph, options) {
504
514
  history: [said],
505
515
  run: { kind: 'invoke', message: said, ...(principal ? { principal } : {}) },
506
516
  updatedAt: new Date().toISOString(),
517
+ ...(tenant !== undefined ? { tenant } : {}),
507
518
  };
508
519
  await store.put(record);
509
520
  return record;
@@ -590,9 +601,29 @@ export function a2aHandler(graph, options) {
590
601
  const pushAnswer = (taskId, config, binding) => binding === 'JSONRPC' ? { taskId, ...config, pushNotificationConfig: config } : { taskId, ...config };
591
602
  const fail = (code, message) => ({ error: { code, message } });
592
603
  const call = async (method, params, context = {}) => {
593
- const principal = context.principal;
604
+ let principal = context.principal;
594
605
  const binding = context.binding ?? 'JSONRPC';
595
606
  const pushOn = Boolean(options.pushNotifications);
607
+ const named = typeof params.tenant === 'string' && params.tenant !== '' ? params.tenant : undefined;
608
+ if (tenancy) {
609
+ if (named === undefined) {
610
+ if (tenancy.required !== false)
611
+ return fail(-32602, 'This agent serves several tenants: name one as tenant');
612
+ }
613
+ else {
614
+ const allowed = tenancy.authorize ? await tenancy.authorize(named, principal) : principal?.tenantId === named;
615
+ if (!allowed)
616
+ return fail(A2A_ERRORS.permissionDenied, `This caller may not act for tenant ${named}`);
617
+ if (principal?.tenantId !== named)
618
+ principal = { ...principal, tenantId: named };
619
+ }
620
+ }
621
+ const tenant = tenancy ? named : undefined;
622
+ const mine = (record) => !tenancy || record.tenant === tenant;
623
+ const own = async (id) => {
624
+ const record = await store.get(id);
625
+ return record && mine(record) ? record : undefined;
626
+ };
596
627
  try {
597
628
  switch (method) {
598
629
  case 'SendMessage':
@@ -605,7 +636,7 @@ export function a2aHandler(graph, options) {
605
636
  if (pushConfig && !pushOn) {
606
637
  return fail(A2A_ERRORS.pushNotificationNotSupported, 'This agent does not push notifications');
607
638
  }
608
- const record = await taskFor(message, principal);
639
+ const record = await taskFor(message, principal, mine, tenant);
609
640
  if ('error' in record)
610
641
  return fail(record.error, record.message);
611
642
  if (pushConfig) {
@@ -623,7 +654,7 @@ export function a2aHandler(graph, options) {
623
654
  return { events: follow(record, () => execute(record, message, principal), context.signal) };
624
655
  }
625
656
  case 'GetTask': {
626
- const record = await store.get(String(params.id ?? ''));
657
+ const record = await own(String(params.id ?? ''));
627
658
  if (!record)
628
659
  return fail(A2A_ERRORS.taskNotFound, `Task ${String(params.id)} was not found`);
629
660
  return { result: view(record, typeof params.historyLength === 'number' ? params.historyLength : undefined) };
@@ -639,6 +670,7 @@ export function a2aHandler(graph, options) {
639
670
  const listed = await store.list({
640
671
  ...(typeof params.contextId === 'string' && params.contextId !== '' ? { contextId: params.contextId } : {}),
641
672
  ...(filtered ? { state: status } : {}),
673
+ ...(tenant !== undefined ? { tenant } : {}),
642
674
  limit: pageSize,
643
675
  offset,
644
676
  });
@@ -648,6 +680,7 @@ export function a2aHandler(graph, options) {
648
680
  return {
649
681
  result: {
650
682
  tasks: listed.records
683
+ .filter(mine)
651
684
  .filter((record) => !after || (record.task.status.timestamp ?? '') >= after)
652
685
  .map((record) => view(record, historyLength))
653
686
  .map(({ artifacts, ...task }) => params.includeArtifacts === false ? task : { ...task, ...(artifacts ? { artifacts } : {}) }),
@@ -658,7 +691,7 @@ export function a2aHandler(graph, options) {
658
691
  };
659
692
  }
660
693
  case 'SubscribeToTask': {
661
- const record = await store.get(String(params.id ?? ''));
694
+ const record = await own(String(params.id ?? ''));
662
695
  if (!record)
663
696
  return fail(A2A_ERRORS.taskNotFound, `Task ${String(params.id)} was not found`);
664
697
  if (TERMINAL.has(record.task.status.state)) {
@@ -670,7 +703,7 @@ export function a2aHandler(graph, options) {
670
703
  return { events: follow(record, undefined, context.signal) };
671
704
  }
672
705
  case 'CancelTask': {
673
- const record = await store.get(String(params.id ?? ''));
706
+ const record = await own(String(params.id ?? ''));
674
707
  if (!record)
675
708
  return fail(A2A_ERRORS.taskNotFound, `Task ${String(params.id)} was not found`);
676
709
  if (TERMINAL.has(record.task.status.state)) {
@@ -690,7 +723,7 @@ export function a2aHandler(graph, options) {
690
723
  if (!pushOn)
691
724
  return fail(A2A_ERRORS.pushNotificationNotSupported, 'This agent does not push notifications');
692
725
  const taskId = String(params.taskId ?? params.id ?? '');
693
- const record = await store.get(taskId);
726
+ const record = await own(taskId);
694
727
  if (!record)
695
728
  return fail(A2A_ERRORS.taskNotFound, `Task ${taskId} was not found`);
696
729
  if (method === 'CreateTaskPushNotificationConfig') {
@@ -771,8 +804,21 @@ export function a2aHandler(graph, options) {
771
804
  return rpcError(id, outcome.error.code, outcome.error.message);
772
805
  return rpcResult(id, outcome.result);
773
806
  };
774
- const httpJson = async (request, route) => {
807
+ const httpJson = async (request, path) => {
775
808
  const verb = request.method;
809
+ const known = /^\/(?:message:send$|message:stream$|tasks(?:$|\/)|extendedAgentCard$)/;
810
+ let route = path;
811
+ let routedTenant;
812
+ const prefixed = /^\/([^/]+)(\/.*)$/.exec(path);
813
+ if (!known.test(path) && prefixed && known.test(prefixed[2])) {
814
+ try {
815
+ routedTenant = decodeURIComponent(prefixed[1]);
816
+ }
817
+ catch {
818
+ return restError(-32602, 'The tenant in the path is not valid percent-encoding');
819
+ }
820
+ route = prefixed[2];
821
+ }
776
822
  const query = new URL(request.url).searchParams;
777
823
  const number = (name) => (query.has(name) ? Number(query.get(name)) : undefined);
778
824
  const id = (value) => decodeURIComponent(value ?? '');
@@ -824,6 +870,8 @@ export function a2aHandler(graph, options) {
824
870
  const refused = versionRefused(request);
825
871
  if (refused)
826
872
  return restError(A2A_ERRORS.versionNotSupported, refused);
873
+ if (routedTenant !== undefined)
874
+ params = { ...params, tenant: routedTenant };
827
875
  if (body) {
828
876
  const text = await request.text();
829
877
  try {
@@ -1034,23 +1082,34 @@ export function a2aClient(options) {
1034
1082
  });
1035
1083
  return cached;
1036
1084
  };
1037
- const endpoint = async () => isCard
1038
- ? ((await card()).supportedInterfaces.find((item) => item.protocolBinding === binding)?.url ?? options.url)
1039
- : options.url;
1085
+ const target = async () => {
1086
+ if (!isCard)
1087
+ return { url: options.url, ...(options.tenant ? { tenant: options.tenant } : {}) };
1088
+ const chosen = (await card()).supportedInterfaces.find((item) => item.protocolBinding === binding);
1089
+ const tenant = options.tenant ?? chosen?.tenant;
1090
+ return { url: chosen?.url ?? options.url, ...(tenant ? { tenant } : {}) };
1091
+ };
1040
1092
  const headers = { 'content-type': 'application/json', 'a2a-version': A2A_PROTOCOL_VERSION, ...options.headers };
1041
1093
  let ids = 0;
1042
- const rpc = async (method, params, signal) => fetcher(await endpoint(), {
1043
- method: 'POST',
1044
- headers,
1045
- body: JSON.stringify({ jsonrpc: '2.0', id: ++ids, method, params }),
1046
- ...(signal ? { signal } : {}),
1047
- });
1048
- const route = async (verb, path, body, signal) => fetcher(`${(await endpoint()).replace(/\/+$/, '')}${path}`, {
1049
- method: verb,
1050
- headers: body === undefined ? { ...headers, 'content-type': 'application/json' } : headers,
1051
- ...(body === undefined ? {} : { body: JSON.stringify(body) }),
1052
- ...(signal ? { signal } : {}),
1053
- });
1094
+ const rpc = async (method, params, signal) => {
1095
+ const { url, tenant } = await target();
1096
+ return fetcher(url, {
1097
+ method: 'POST',
1098
+ headers,
1099
+ body: JSON.stringify({ jsonrpc: '2.0', id: ++ids, method, params: tenant ? { tenant, ...params } : params }),
1100
+ ...(signal ? { signal } : {}),
1101
+ });
1102
+ };
1103
+ const route = async (verb, path, body, signal) => {
1104
+ const { url, tenant } = await target();
1105
+ const under = tenant ? `/${encodeURIComponent(tenant)}` : '';
1106
+ return fetcher(`${url.replace(/\/+$/, '')}${under}${path}`, {
1107
+ method: verb,
1108
+ headers: body === undefined ? { ...headers, 'content-type': 'application/json' } : headers,
1109
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }),
1110
+ ...(signal ? { signal } : {}),
1111
+ });
1112
+ };
1054
1113
  const restFailure = async (response) => {
1055
1114
  const body = (await response.json().catch(() => ({})));
1056
1115
  const reason = body.error?.details?.find((detail) => detail.reason)?.reason;
@@ -42,11 +42,13 @@ export class GoogleProvider extends BaseProvider {
42
42
  const content = this.extractText(candidate?.content);
43
43
  const toolCalls = this.extractToolCalls(candidate?.content);
44
44
  const assets = this.extractAssets(candidate?.content);
45
+ const logprobs = geminiLogprobs(candidate?.logprobsResult);
45
46
  return {
46
47
  content,
47
48
  role: 'assistant',
48
49
  toolCalls: toolCalls.length ? toolCalls : undefined,
49
50
  ...(assets.length ? { assets } : {}),
51
+ ...(logprobs ? { logprobs } : {}),
50
52
  finishReason: toolCalls.length ? 'tool_calls' : this.mapFinishReason(candidate?.finishReason),
51
53
  meta: buildMeta({
52
54
  provider: 'google',
@@ -145,6 +147,12 @@ export class GoogleProvider extends BaseProvider {
145
147
  maxOutputTokens: request.maxTokens,
146
148
  stopSequences: request.stop ? (Array.isArray(request.stop) ? request.stop : [request.stop]) : undefined,
147
149
  thinkingConfig: this.thinkingConfig(request),
150
+ ...(request.logprobs
151
+ ? {
152
+ responseLogprobs: true,
153
+ ...(request.logprobs.top ? { logprobs: Math.min(20, Math.max(0, Math.floor(request.logprobs.top))) } : {}),
154
+ }
155
+ : {}),
148
156
  };
149
157
  if (request.responseFormat?.type === 'json') {
150
158
  generationConfig.responseMimeType = 'application/json';
@@ -322,3 +330,23 @@ export class GoogleProvider extends BaseProvider {
322
330
  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
323
331
  }
324
332
  }
333
+ function geminiLogprobs(result) {
334
+ const chosen = result?.chosenCandidates;
335
+ if (!chosen?.length)
336
+ return undefined;
337
+ return chosen.map((item, index) => {
338
+ const alternatives = result?.topCandidates?.[index]?.candidates;
339
+ return {
340
+ token: item.token ?? '',
341
+ logprob: item.logProbability ?? Number.NEGATIVE_INFINITY,
342
+ ...(alternatives?.length
343
+ ? {
344
+ top: alternatives.map((alternative) => ({
345
+ token: alternative.token ?? '',
346
+ logprob: alternative.logProbability ?? Number.NEGATIVE_INFINITY,
347
+ })),
348
+ }
349
+ : {}),
350
+ };
351
+ });
352
+ }
@@ -42,16 +42,39 @@ export class OllamaProvider extends BaseProvider {
42
42
  messages: this.formatMessages(request.messages),
43
43
  format: this.formatResponseFormat(request),
44
44
  signal: request.signal,
45
+ ...(request.logprobs
46
+ ? {
47
+ logprobs: true,
48
+ ...(request.logprobs.top
49
+ ? { top_logprobs: Math.min(20, Math.max(0, Math.floor(request.logprobs.top))) }
50
+ : {}),
51
+ }
52
+ : {}),
45
53
  options: {
46
54
  ...this.samplingOptions(request),
47
55
  stop: request.stop ? (Array.isArray(request.stop) ? request.stop : [request.stop]) : undefined,
48
56
  },
49
57
  });
50
58
  const latency = Date.now() - startTime;
59
+ const logprobs = result.logprobs?.length
60
+ ? result.logprobs.map((item) => ({
61
+ token: item.token ?? '',
62
+ logprob: item.logprob ?? Number.NEGATIVE_INFINITY,
63
+ ...(item.top_logprobs?.length
64
+ ? {
65
+ top: item.top_logprobs.map((alternative) => ({
66
+ token: alternative.token ?? '',
67
+ logprob: alternative.logprob ?? Number.NEGATIVE_INFINITY,
68
+ })),
69
+ }
70
+ : {}),
71
+ }))
72
+ : undefined;
51
73
  return {
52
74
  content: result.message?.content || '',
53
75
  role: 'assistant',
54
76
  finishReason: 'stop',
77
+ ...(logprobs ? { logprobs } : {}),
55
78
  meta: buildMeta({
56
79
  provider: 'ollama',
57
80
  model,
@@ -26,6 +26,12 @@ export declare class OpenAIProvider extends BaseProvider {
26
26
  /** Streams one completion. */
27
27
  stream(request: CompletionRequest, context?: ProviderCallContext): NexusStream;
28
28
  private createChatParams;
29
+ /**
30
+ * Whether the server reports token log probabilities, so a request that asks for them sends
31
+ * `logprobs`. Groq and Mistral refuse the option, so it is not sent to them; a model that cannot
32
+ * report them is told so by declaring `logprobs: false`.
33
+ */
34
+ protected reportsLogprobs(): boolean;
29
35
  /**
30
36
  * Whether to ask for usage totals on the final streamed chunk.
31
37
  *
@@ -129,11 +129,13 @@ export class OpenAIProvider extends BaseProvider {
129
129
  if (!choice?.message) {
130
130
  throw new Error('OpenAI chat response did not include a message choice');
131
131
  }
132
+ const logprobs = chatLogprobs(choice.logprobs?.content);
132
133
  return {
133
134
  content: choice.message.content || '',
134
135
  role: 'assistant',
135
136
  toolCalls: this.extractChatToolCalls(choice.message.tool_calls),
136
137
  finishReason: this.mapFinishReason(choice.finish_reason),
138
+ ...(logprobs ? { logprobs } : {}),
137
139
  meta: this.createMeta(result.model, Date.now() - startTime, chatUsage(result.usage)),
138
140
  };
139
141
  }
@@ -250,8 +252,16 @@ export class OpenAIProvider extends BaseProvider {
250
252
  }
251
253
  if (request.reasoning?.effort)
252
254
  params.reasoning_effort = request.reasoning.effort;
255
+ if (request.logprobs && this.reportsLogprobs()) {
256
+ params.logprobs = true;
257
+ if (request.logprobs.top)
258
+ params.top_logprobs = Math.min(20, Math.max(0, Math.floor(request.logprobs.top)));
259
+ }
253
260
  return params;
254
261
  }
262
+ reportsLogprobs() {
263
+ return this.info.name !== 'groq' && this.info.name !== 'mistral';
264
+ }
255
265
  includeStreamUsage() {
256
266
  return this.config.streamUsage ?? this.info.name === 'openai';
257
267
  }
@@ -646,3 +656,19 @@ function mapResponsesToolChoice(choice) {
646
656
  return choice;
647
657
  return { type: 'function', name: choice.name };
648
658
  }
659
+ function chatLogprobs(content) {
660
+ if (!content?.length)
661
+ return undefined;
662
+ return content.map((item) => ({
663
+ token: item.token ?? '',
664
+ logprob: item.logprob ?? Number.NEGATIVE_INFINITY,
665
+ ...(item.top_logprobs?.length
666
+ ? {
667
+ top: item.top_logprobs.map((alternative) => ({
668
+ token: alternative.token ?? '',
669
+ logprob: alternative.logprob ?? Number.NEGATIVE_INFINITY,
670
+ })),
671
+ }
672
+ : {}),
673
+ }));
674
+ }
@@ -7,7 +7,7 @@ import type { CallResidency, ResidencyPolicy } from './residency.js';
7
7
  * budgets, hooks, audit, metrics, and finalization behave the same whichever family runs.
8
8
  */
9
9
  /** The families an operation can belong to. */
10
- export type OperationFamily = 'completion' | 'embedding' | 'voice' | 'realtime' | 'telephony' | 'image' | 'batch' | 'job' | 'graph' | 'agent' | 'media' | 'video' | 'messaging';
10
+ export type OperationFamily = 'completion' | 'embedding' | 'voice' | 'realtime' | 'telephony' | 'image' | 'batch' | 'job' | 'graph' | 'agent' | 'media' | 'video' | 'messaging' | 'decision';
11
11
  /**
12
12
  * The stages every operation passes through, in this order. A family skips a stage it has nothing
13
13
  * for: a transcription resolves no assets, and a graph run calls no provider directly.
@@ -343,6 +343,15 @@ export interface CompletionRequest {
343
343
  seed?: number;
344
344
  /** Adjusts the likelihood of specific tokens, by token id. */
345
345
  logitBias?: Record<string, number>;
346
+ /**
347
+ * Asks for each answer token's log probability, and with `top`, its most likely alternatives, up
348
+ * to 20, on `response.logprobs`. OpenAI and the OpenAI-compatible providers that report them,
349
+ * Gemini, and Ollama send it; a model that declares `logprobs: false` has it removed. A provider
350
+ * that reports none leaves `response.logprobs` absent, and a stream reports none.
351
+ */
352
+ logprobs?: {
353
+ top?: number;
354
+ };
346
355
  /** Timeout per provider attempt, in milliseconds, overriding the client's. */
347
356
  timeoutMs?: number;
348
357
  /** Refuses or flags this request when its estimated cost exceeds this many US dollars. */
@@ -77,6 +77,8 @@ export interface ModelCapabilities {
77
77
  topK?: boolean;
78
78
  /** Whether it accepts frequency and presence penalties. */
79
79
  penalties?: boolean;
80
+ /** Whether it reports token log probabilities. */
81
+ logprobs?: boolean;
80
82
  /** Context window, in tokens. */
81
83
  maxContextTokens: number;
82
84
  /** Longest output, in tokens. */
@@ -153,9 +153,26 @@ export interface NexusResponse {
153
153
  * error.
154
154
  */
155
155
  finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter' | 'error';
156
+ /**
157
+ * Each token of the answer with its log probability, and its most likely alternatives, when the
158
+ * request asked for `logprobs` and the provider reported them.
159
+ */
160
+ logprobs?: TokenLogprob[];
156
161
  /** How the completion was produced. */
157
162
  meta: ResponseMeta;
158
163
  }
164
+ /** One token of an answer: its text, its log probability, and the alternatives most likely in its place. */
165
+ export interface TokenLogprob {
166
+ /** The token's text. */
167
+ token: string;
168
+ /** Its natural log probability, 0 or below. */
169
+ logprob: number;
170
+ /** The most likely tokens at its place, itself among them, most likely first, when they were asked for. */
171
+ top?: Array<{
172
+ token: string;
173
+ logprob: number;
174
+ }>;
175
+ }
159
176
  /**
160
177
  * One streamed event.
161
178
  *
@@ -8,7 +8,7 @@
8
8
  * an evaluation dataset.
9
9
  */
10
10
  /** What kind of work a run was, so a trace can be filtered and drawn by family. */
11
- export type RunKind = 'chain' | 'model' | 'tool' | 'graph' | 'node' | 'agent' | 'retriever' | 'embedding' | 'image' | 'voice' | 'realtime' | 'operation';
11
+ export type RunKind = 'chain' | 'model' | 'tool' | 'graph' | 'node' | 'agent' | 'retriever' | 'embedding' | 'image' | 'voice' | 'realtime' | 'operation' | 'decision';
12
12
  /** Where a run stands: still going, finished, or failed. */
13
13
  export type RunStatus = 'running' | 'ok' | 'error';
14
14
  /** A judgement attached to a run, by a person or an evaluator. */
package/dist/version.d.ts CHANGED
@@ -2,4 +2,4 @@
2
2
  * This package's version, recorded where provenance matters, such as on every experiment. A test
3
3
  * keeps it equal to `package.json`.
4
4
  */
5
- export declare const NEXUS_VERSION = "2.18.0";
5
+ export declare const NEXUS_VERSION = "2.20.2";
package/dist/version.js CHANGED
@@ -1 +1 @@
1
- export const NEXUS_VERSION = '2.18.0';
1
+ export const NEXUS_VERSION = '2.20.2';
@@ -1,4 +1,5 @@
1
1
  import { type RagChunk } from '../hallucination/rag.js';
2
+ import type { DecisionManagerLike } from '../decisions/integrations.js';
2
3
  import type { ResponseFormatConfig } from '../types/config.js';
3
4
  import type { CompletionRequest } from '../types/messages.js';
4
5
  import type { NexusResponse } from '../types/response.js';
@@ -73,6 +74,16 @@ export interface ClassifyRouteOptions {
73
74
  labels: string[];
74
75
  /** Replaces the default classification instruction. */
75
76
  instruction?: string;
77
+ /**
78
+ * Classifies by decision instead: the label as a choice, answered with every label's probability and
79
+ * a confidence read from them, not the confidence a model claims. `model` is then the decision's
80
+ * model only when `decisions.model` names none, and the client is not called.
81
+ */
82
+ decisions?: {
83
+ manager: DecisionManagerLike;
84
+ provider?: string;
85
+ model?: string;
86
+ };
76
87
  }
77
88
  /** Options for `compareAndDecide`. */
78
89
  export interface CompareOptions {
@@ -99,7 +110,8 @@ export declare function ragAnswer(client: WorkflowClient, options: RagAnswerOpti
99
110
  export declare function extractStructured(client: WorkflowClient, options: ExtractStructuredOptions): Promise<WorkflowResult>;
100
111
  /**
101
112
  * Picks exactly one label for the input, at temperature 0, returning `{ label, confidence }` as
102
- * JSON.
113
+ * JSON. With `decisions`, the label is a decision's choice, and the JSON carries every label's
114
+ * `probabilities` and the confidence read from them.
103
115
  */
104
116
  export declare function classifyRoute(client: WorkflowClient, options: ClassifyRouteOptions): Promise<WorkflowResult>;
105
117
  /** Compares options against criteria and chooses one, reasoning privately before answering. */
@@ -86,6 +86,46 @@ export async function extractStructured(client, options) {
86
86
  return { content: response.content, response, steps: [{ step: 'extract-structured', response }] };
87
87
  }
88
88
  export async function classifyRoute(client, options) {
89
+ if (options.decisions) {
90
+ const started = Date.now();
91
+ const { manager, provider, model } = options.decisions;
92
+ const result = await manager.decide({
93
+ state: options.input,
94
+ questions: {
95
+ label: {
96
+ type: 'choice',
97
+ question: options.instruction || 'Classify the input into exactly one label.',
98
+ options: options.labels,
99
+ },
100
+ },
101
+ ...(provider ? { provider } : {}),
102
+ model: model ?? options.model,
103
+ });
104
+ const answer = result.answers.label;
105
+ const content = JSON.stringify({
106
+ label: answer.choice,
107
+ confidence: answer.confidence,
108
+ probabilities: answer.probabilities,
109
+ });
110
+ const response = {
111
+ content,
112
+ role: 'assistant',
113
+ finishReason: 'stop',
114
+ meta: {
115
+ requestId: `decision-${started}`,
116
+ providerUsed: result.provider,
117
+ modelUsed: result.model,
118
+ latencyMs: result.latencyMs,
119
+ tokensInput: result.usage?.inputTokens ?? 0,
120
+ tokensOutput: result.usage?.outputTokens ?? 0,
121
+ tokensSaved: 0,
122
+ ...(result.cost ? { cost: result.cost } : {}),
123
+ cacheHit: result.cached === true,
124
+ guardrailsApplied: [],
125
+ },
126
+ };
127
+ return { content, response, steps: [{ step: 'classify-route', response }] };
128
+ }
89
129
  const response = await client.complete({
90
130
  model: options.model,
91
131
  messages: [
@@ -12,6 +12,9 @@ import type { ToolDefinition } from '../types/messages.js';
12
12
  * | `mcp.read:<server>/<tool>` | An MCP tool its server says only reads |
13
13
  * | `mcp.write:<server>/<tool>` | An MCP tool its server says changes things but destroys nothing |
14
14
  * | `mcp.destructive:<server>/<tool>` | An MCP tool its server says may destroy or overwrite |
15
+ * | `api.read:<api>/<operation>` | An operation of an OpenAPI document whose method only reads |
16
+ * | `api.write:<api>/<operation>` | One whose method changes things |
17
+ * | `api.destructive:<api>/<operation>` | One whose method deletes |
15
18
  * | `<name>`, `<name>:<detail>` | Anything the application names, such as `payments:refund` |
16
19
  *
17
20
  * A tool that declares `capabilities: []` does nothing to the world; one that declares none at all