@contextrail/assess 0.0.0-stage → 1.0.0-alpha.1

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 (73) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +82 -2
  3. package/assets/brand/icon-dark.png +0 -0
  4. package/assets/brand/icon-light.png +0 -0
  5. package/dist/assess.d.ts +109 -0
  6. package/dist/assess.js +1548 -0
  7. package/dist/assessment.d.ts +566 -0
  8. package/dist/assessment.js +404 -0
  9. package/dist/budget.d.ts +24 -0
  10. package/dist/budget.js +52 -0
  11. package/dist/candidate.d.ts +147 -0
  12. package/dist/candidate.js +321 -0
  13. package/dist/change-summary.d.ts +33 -0
  14. package/dist/change-summary.js +26 -0
  15. package/dist/cli.d.ts +2 -0
  16. package/dist/cli.js +406 -0
  17. package/dist/contracts.d.ts +99 -0
  18. package/dist/contracts.js +62 -0
  19. package/dist/diagnostics.d.ts +44 -0
  20. package/dist/diagnostics.js +412 -0
  21. package/dist/evidence.d.ts +73 -0
  22. package/dist/evidence.js +297 -0
  23. package/dist/feedback.d.ts +21 -0
  24. package/dist/feedback.js +140 -0
  25. package/dist/git.d.ts +40 -0
  26. package/dist/git.js +207 -0
  27. package/dist/github.d.ts +90 -0
  28. package/dist/github.js +1342 -0
  29. package/dist/index.d.ts +14 -0
  30. package/dist/index.js +14 -0
  31. package/dist/mcp.d.ts +28 -0
  32. package/dist/mcp.js +173 -0
  33. package/dist/pack.d.ts +160 -0
  34. package/dist/pack.js +377 -0
  35. package/dist/phases.d.ts +65 -0
  36. package/dist/phases.js +63 -0
  37. package/dist/planning.d.ts +64 -0
  38. package/dist/planning.js +135 -0
  39. package/dist/pr-context.d.ts +316 -0
  40. package/dist/pr-context.js +198 -0
  41. package/dist/prepare.d.ts +71 -0
  42. package/dist/prepare.js +335 -0
  43. package/dist/presentation.d.ts +309 -0
  44. package/dist/presentation.js +1026 -0
  45. package/dist/provider-diagnostics.d.ts +93 -0
  46. package/dist/provider-diagnostics.js +233 -0
  47. package/dist/providers.d.ts +45 -0
  48. package/dist/providers.js +291 -0
  49. package/dist/report-contract.d.ts +132 -0
  50. package/dist/report-contract.js +240 -0
  51. package/dist/results.d.ts +90 -0
  52. package/dist/results.js +128 -0
  53. package/dist/resume.d.ts +25 -0
  54. package/dist/resume.js +116 -0
  55. package/dist/source.d.ts +167 -0
  56. package/dist/source.js +675 -0
  57. package/dist/verification.d.ts +386 -0
  58. package/dist/verification.js +168 -0
  59. package/dist/version.d.ts +2 -0
  60. package/dist/version.js +9 -0
  61. package/docs/README.md +24 -0
  62. package/docs/action-reference.md +85 -0
  63. package/docs/architecture.md +156 -0
  64. package/docs/configuration.md +83 -0
  65. package/docs/contributing.md +46 -0
  66. package/docs/getting-started.md +92 -0
  67. package/docs/github-actions.md +141 -0
  68. package/docs/operations.md +203 -0
  69. package/docs/review-results.md +173 -0
  70. package/docs/security.md +64 -0
  71. package/docs/standards.md +62 -0
  72. package/examples/assess-pull-request.yml +109 -0
  73. package/package.json +56 -5
@@ -0,0 +1,93 @@
1
+ /** Provider payloads are inspected transiently; diagnostic output is a fixed vocabulary and counts. */
2
+ export declare const PROVIDER_FAILURE_CODES: readonly ["provider_credit_limit", "provider_credential_invalid", "provider_rate_limited", "provider_permission_denied", "provider_schema_invalid", "provider_context_limit", "provider_request_too_large", "provider_parameter_unsupported", "provider_model_unavailable", "provider_timeout", "provider_unavailable", "provider_request_failed"];
3
+ export type ProviderFailureCode = (typeof PROVIDER_FAILURE_CODES)[number];
4
+ /** Never retain arbitrary provider codes, parameters, messages, metadata, or response bodies. */
5
+ export declare function providerHttpDiagnostics(status: number, body: unknown): {
6
+ parameter: string | null;
7
+ bodyFormat: "object" | "json" | "empty" | "non_json" | "too_large";
8
+ code: "provider_credit_limit" | "provider_credential_invalid" | "provider_rate_limited" | "provider_permission_denied" | "provider_schema_invalid" | "provider_context_limit" | "provider_request_too_large" | "provider_parameter_unsupported" | "provider_model_unavailable" | "provider_timeout" | "provider_unavailable" | "provider_request_failed";
9
+ reason: string;
10
+ evidence: "http_status";
11
+ } | {
12
+ parameter: string | null;
13
+ bodyFormat: "object" | "json" | "empty" | "non_json" | "too_large";
14
+ code: "provider_credit_limit" | "provider_credential_invalid" | "provider_rate_limited" | "provider_permission_denied" | "provider_schema_invalid" | "provider_context_limit" | "provider_request_too_large" | "provider_parameter_unsupported" | "provider_model_unavailable" | "provider_timeout" | "provider_unavailable" | "provider_request_failed";
15
+ reason: string;
16
+ evidence: "structured_code";
17
+ } | {
18
+ parameter: string | null;
19
+ bodyFormat: "object" | "json" | "empty" | "non_json" | "too_large";
20
+ code: "provider_credit_limit" | "provider_credential_invalid" | "provider_rate_limited" | "provider_permission_denied" | "provider_schema_invalid" | "provider_context_limit" | "provider_request_too_large" | "provider_parameter_unsupported" | "provider_model_unavailable" | "provider_timeout" | "provider_unavailable" | "provider_request_failed";
21
+ reason: string;
22
+ evidence: "message_pattern";
23
+ } | {
24
+ parameter: string | null;
25
+ bodyFormat: "object" | "json" | "empty" | "non_json" | "too_large";
26
+ code: "provider_request_failed";
27
+ reason: string;
28
+ evidence: "unknown";
29
+ };
30
+ export declare function providerHttpFailure(status: number, body: unknown): ProviderFailureCode;
31
+ /** Count the serialized wire request without retaining input, tool descriptions, schema properties or model IDs. */
32
+ export declare function providerRequestDiagnostics(body: unknown): {
33
+ requestBytes: number | null;
34
+ messageCount: number | null;
35
+ toolCount: number | null;
36
+ toolSchemaBytes: number | null;
37
+ maxOutputTokens: number | null;
38
+ requestFormat: string;
39
+ };
40
+ /** Transport diagnoses are observed exception codes, never inferred from arbitrary error prose. */
41
+ export declare function providerTransportDiagnostics(error: unknown): {
42
+ transport: string | undefined;
43
+ };
44
+ /** Inspect a bounded clone; preserve the original response for the SDK and never mask its failure. */
45
+ export declare function providerResponseDiagnostics(response: Response): Promise<{
46
+ parameter: string | null;
47
+ bodyFormat: "object" | "json" | "empty" | "non_json" | "too_large";
48
+ code: "provider_credit_limit" | "provider_credential_invalid" | "provider_rate_limited" | "provider_permission_denied" | "provider_schema_invalid" | "provider_context_limit" | "provider_request_too_large" | "provider_parameter_unsupported" | "provider_model_unavailable" | "provider_timeout" | "provider_unavailable" | "provider_request_failed";
49
+ reason: string;
50
+ evidence: "http_status";
51
+ } | {
52
+ parameter: string | null;
53
+ bodyFormat: "object" | "json" | "empty" | "non_json" | "too_large";
54
+ code: "provider_credit_limit" | "provider_credential_invalid" | "provider_rate_limited" | "provider_permission_denied" | "provider_schema_invalid" | "provider_context_limit" | "provider_request_too_large" | "provider_parameter_unsupported" | "provider_model_unavailable" | "provider_timeout" | "provider_unavailable" | "provider_request_failed";
55
+ reason: string;
56
+ evidence: "structured_code";
57
+ } | {
58
+ parameter: string | null;
59
+ bodyFormat: "object" | "json" | "empty" | "non_json" | "too_large";
60
+ code: "provider_credit_limit" | "provider_credential_invalid" | "provider_rate_limited" | "provider_permission_denied" | "provider_schema_invalid" | "provider_context_limit" | "provider_request_too_large" | "provider_parameter_unsupported" | "provider_model_unavailable" | "provider_timeout" | "provider_unavailable" | "provider_request_failed";
61
+ reason: string;
62
+ evidence: "message_pattern";
63
+ } | {
64
+ parameter: string | null;
65
+ bodyFormat: "object" | "json" | "empty" | "non_json" | "too_large";
66
+ code: "provider_request_failed";
67
+ reason: string;
68
+ evidence: "unknown";
69
+ } | {
70
+ bodyFormat: "unreadable";
71
+ parameter: string | null;
72
+ code: "provider_credit_limit" | "provider_credential_invalid" | "provider_rate_limited" | "provider_permission_denied" | "provider_schema_invalid" | "provider_context_limit" | "provider_request_too_large" | "provider_parameter_unsupported" | "provider_model_unavailable" | "provider_timeout" | "provider_unavailable" | "provider_request_failed";
73
+ reason: string;
74
+ evidence: "http_status";
75
+ } | {
76
+ bodyFormat: "unreadable";
77
+ parameter: string | null;
78
+ code: "provider_credit_limit" | "provider_credential_invalid" | "provider_rate_limited" | "provider_permission_denied" | "provider_schema_invalid" | "provider_context_limit" | "provider_request_too_large" | "provider_parameter_unsupported" | "provider_model_unavailable" | "provider_timeout" | "provider_unavailable" | "provider_request_failed";
79
+ reason: string;
80
+ evidence: "structured_code";
81
+ } | {
82
+ bodyFormat: "unreadable";
83
+ parameter: string | null;
84
+ code: "provider_credit_limit" | "provider_credential_invalid" | "provider_rate_limited" | "provider_permission_denied" | "provider_schema_invalid" | "provider_context_limit" | "provider_request_too_large" | "provider_parameter_unsupported" | "provider_model_unavailable" | "provider_timeout" | "provider_unavailable" | "provider_request_failed";
85
+ reason: string;
86
+ evidence: "message_pattern";
87
+ } | {
88
+ bodyFormat: "unreadable";
89
+ parameter: string | null;
90
+ code: "provider_request_failed";
91
+ reason: string;
92
+ evidence: "unknown";
93
+ }>;
@@ -0,0 +1,233 @@
1
+ /** Provider payloads are inspected transiently; diagnostic output is a fixed vocabulary and counts. */
2
+ export const PROVIDER_FAILURE_CODES = [
3
+ 'provider_credit_limit',
4
+ 'provider_credential_invalid',
5
+ 'provider_rate_limited',
6
+ 'provider_permission_denied',
7
+ 'provider_schema_invalid',
8
+ 'provider_context_limit',
9
+ 'provider_request_too_large',
10
+ 'provider_parameter_unsupported',
11
+ 'provider_model_unavailable',
12
+ 'provider_timeout',
13
+ 'provider_unavailable',
14
+ 'provider_request_failed',
15
+ ];
16
+ const errorBytesLimit = 64 * 1024;
17
+ const requestBytesLimit = 4 * 1024 * 1024;
18
+ const parameterNames = new Set([
19
+ 'tools',
20
+ 'response_format',
21
+ 'max_tokens',
22
+ 'max_completion_tokens',
23
+ 'max_output_tokens',
24
+ 'reasoning_effort',
25
+ 'temperature',
26
+ 'top_p',
27
+ 'messages',
28
+ 'input',
29
+ 'model',
30
+ 'tool_choice',
31
+ 'parallel_tool_calls',
32
+ 'stream',
33
+ ]);
34
+ function object(value) {
35
+ return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
36
+ }
37
+ function parseBody(body, limit) {
38
+ if (body === null || body === undefined || body === '')
39
+ return { value: null, format: 'empty' };
40
+ if (typeof body !== 'string')
41
+ return { value: object(body), format: object(body) ? 'object' : 'non_json' };
42
+ if (Buffer.byteLength(body, 'utf8') > limit)
43
+ return { value: null, format: 'too_large' };
44
+ try {
45
+ return { value: object(JSON.parse(body)), format: 'json' };
46
+ }
47
+ catch {
48
+ return { value: null, format: 'non_json' };
49
+ }
50
+ }
51
+ const rules = [
52
+ {
53
+ code: 'provider_context_limit',
54
+ reason: 'context_length_exceeded',
55
+ codes: ['context_length_exceeded', 'context_window_exceeded'],
56
+ message: /\b(?:maximum context length|context (?:length|window).{0,40}(?:exceed|limit)|too many tokens)\b/iu,
57
+ },
58
+ {
59
+ code: 'provider_request_too_large',
60
+ reason: 'request_too_large',
61
+ codes: ['request_too_large', 'payload_too_large'],
62
+ message: /\b(?:request|payload|body) (?:is )?too large\b/iu,
63
+ },
64
+ {
65
+ code: 'provider_schema_invalid',
66
+ reason: 'invalid_schema',
67
+ codes: ['invalid_json_schema', 'invalid_function_parameters'],
68
+ message: /\binvalid (?:json |function |tool )?schema\b/iu,
69
+ },
70
+ {
71
+ code: 'provider_parameter_unsupported',
72
+ reason: 'unsupported_parameter',
73
+ codes: ['unsupported_parameter', 'unsupported_value'],
74
+ message: /\b(?:unsupported (?:parameter|value)|(?:parameter|argument).{0,80}(?:not supported|unsupported))\b/iu,
75
+ },
76
+ {
77
+ code: 'provider_model_unavailable',
78
+ reason: 'model_unavailable',
79
+ codes: ['model_not_found', 'model_not_available'],
80
+ message: /\b(?:model.{0,80}(?:not found|does not exist|not available)|no endpoints found)\b/iu,
81
+ },
82
+ {
83
+ code: 'provider_credit_limit',
84
+ reason: 'credit_limit',
85
+ codes: ['insufficient_quota', 'insufficient_credits'],
86
+ message: /\b(?:key spending limit exceeded|insufficient (?:quota|credits))\b/iu,
87
+ },
88
+ ];
89
+ function errorRecords(body) {
90
+ const records = [];
91
+ let current = body;
92
+ for (let depth = 0; current && depth < 3; depth++) {
93
+ const error = object(current.error) ?? current;
94
+ records.push(error);
95
+ const raw = object(error.metadata)?.raw;
96
+ current = parseBody(raw, errorBytesLimit).value;
97
+ }
98
+ return records;
99
+ }
100
+ function classification(status, records) {
101
+ const fixed = {
102
+ 401: ['provider_credential_invalid', 'credential_invalid'],
103
+ 402: ['provider_credit_limit', 'credit_limit'],
104
+ 408: ['provider_timeout', 'request_timeout'],
105
+ 413: ['provider_request_too_large', 'request_too_large'],
106
+ 429: ['provider_rate_limited', 'rate_limited'],
107
+ };
108
+ if (fixed[status])
109
+ return { code: fixed[status][0], reason: fixed[status][1], evidence: 'http_status' };
110
+ if (status >= 500 && status <= 599)
111
+ return {
112
+ code: 'provider_unavailable',
113
+ reason: 'service_unavailable',
114
+ evidence: 'http_status',
115
+ };
116
+ for (const record of records) {
117
+ for (const rule of rules) {
118
+ if (typeof record.code === 'string' && rule.codes.includes(record.code))
119
+ return { code: rule.code, reason: rule.reason, evidence: 'structured_code' };
120
+ if (typeof record.message === 'string' && rule.message.test(record.message.slice(0, 4096)))
121
+ return { code: rule.code, reason: rule.reason, evidence: 'message_pattern' };
122
+ }
123
+ }
124
+ if (status === 403)
125
+ return {
126
+ code: 'provider_permission_denied',
127
+ reason: 'permission_denied',
128
+ evidence: 'http_status',
129
+ };
130
+ return { code: 'provider_request_failed', reason: 'unknown', evidence: 'unknown' };
131
+ }
132
+ /** Never retain arbitrary provider codes, parameters, messages, metadata, or response bodies. */
133
+ export function providerHttpDiagnostics(status, body) {
134
+ const parsed = parseBody(body, errorBytesLimit);
135
+ const records = errorRecords(parsed.value);
136
+ const parameter = records
137
+ .map((record) => record.param)
138
+ .find((value) => typeof value === 'string' && parameterNames.has(value));
139
+ return {
140
+ ...classification(status, records),
141
+ parameter: typeof parameter === 'string' ? parameter : null,
142
+ bodyFormat: parsed.format,
143
+ };
144
+ }
145
+ export function providerHttpFailure(status, body) {
146
+ return providerHttpDiagnostics(status, body).code;
147
+ }
148
+ function nonnegativeInteger(value) {
149
+ return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
150
+ }
151
+ /** Count the serialized wire request without retaining input, tool descriptions, schema properties or model IDs. */
152
+ export function providerRequestDiagnostics(body) {
153
+ const text = typeof body === 'string' ? body : body instanceof Uint8Array ? Buffer.from(body).toString('utf8') : null;
154
+ const requestBytes = typeof body === 'string'
155
+ ? Buffer.byteLength(body, 'utf8')
156
+ : body instanceof Uint8Array
157
+ ? body.byteLength
158
+ : null;
159
+ const parsed = parseBody(text, requestBytesLimit);
160
+ const value = parsed.value;
161
+ const messages = value?.messages ?? value?.input;
162
+ const tools = value?.tools;
163
+ return {
164
+ requestBytes,
165
+ messageCount: Array.isArray(messages) ? messages.length : null,
166
+ toolCount: Array.isArray(tools) ? tools.length : null,
167
+ toolSchemaBytes: Array.isArray(tools)
168
+ ? Buffer.byteLength(JSON.stringify(tools.map((tool) => {
169
+ const entry = object(tool);
170
+ return object(entry?.function)?.parameters ?? entry?.parameters ?? null;
171
+ })), 'utf8')
172
+ : null,
173
+ maxOutputTokens: nonnegativeInteger(value?.max_output_tokens ?? value?.max_completion_tokens ?? value?.max_tokens),
174
+ requestFormat: text === null ? 'unavailable' : parsed.format,
175
+ };
176
+ }
177
+ /** Transport diagnoses are observed exception codes, never inferred from arbitrary error prose. */
178
+ export function providerTransportDiagnostics(error) {
179
+ const known = {
180
+ ENOTFOUND: 'dns_not_found',
181
+ EAI_AGAIN: 'dns_temporary_failure',
182
+ ECONNREFUSED: 'connection_refused',
183
+ ECONNRESET: 'connection_reset',
184
+ EPIPE: 'connection_closed',
185
+ ETIMEDOUT: 'timeout',
186
+ UND_ERR_CONNECT_TIMEOUT: 'connect_timeout',
187
+ UND_ERR_HEADERS_TIMEOUT: 'headers_timeout',
188
+ UND_ERR_BODY_TIMEOUT: 'body_timeout',
189
+ UND_ERR_SOCKET: 'socket_failure',
190
+ };
191
+ let current = object(error);
192
+ for (let depth = 0; current && depth < 5; depth++) {
193
+ if (current.name === 'AbortError')
194
+ return { transport: 'aborted' };
195
+ if (current.name === 'TimeoutError')
196
+ return { transport: 'timeout' };
197
+ if (typeof current.code === 'string' && Object.hasOwn(known, current.code))
198
+ return { transport: known[current.code] };
199
+ current = object(current.cause);
200
+ }
201
+ return { transport: 'unknown' };
202
+ }
203
+ /** Inspect a bounded clone; preserve the original response for the SDK and never mask its failure. */
204
+ export async function providerResponseDiagnostics(response) {
205
+ const fallback = providerHttpDiagnostics(response.status, null);
206
+ let reader;
207
+ try {
208
+ reader = response.clone().body?.getReader();
209
+ if (!reader)
210
+ return fallback;
211
+ const chunks = [];
212
+ let bytes = 0;
213
+ for (;;) {
214
+ const chunk = await reader.read();
215
+ if (chunk.done)
216
+ break;
217
+ bytes += chunk.value.byteLength;
218
+ if (bytes > errorBytesLimit) {
219
+ // A tee cancellation can wait for the SDK's original stream; do not await it here.
220
+ void reader.cancel().catch(() => undefined);
221
+ return { ...fallback, bodyFormat: 'too_large' };
222
+ }
223
+ chunks.push(chunk.value);
224
+ }
225
+ return providerHttpDiagnostics(response.status, Buffer.concat(chunks).toString('utf8'));
226
+ }
227
+ catch {
228
+ return { ...fallback, bodyFormat: 'unreadable' };
229
+ }
230
+ finally {
231
+ reader?.releaseLock();
232
+ }
233
+ }
@@ -0,0 +1,45 @@
1
+ import { wrapLanguageModel } from 'ai';
2
+ export type AssessmentProvider = 'openai' | 'openrouter';
3
+ export type ProviderConfiguration = {
4
+ provider: AssessmentProvider;
5
+ model: string;
6
+ effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
7
+ };
8
+ export { PROVIDER_FAILURE_CODES, providerHttpFailure, providerHttpDiagnostics, providerRequestDiagnostics, providerTransportDiagnostics, providerResponseDiagnostics, } from './provider-diagnostics.js';
9
+ export type { ProviderFailureCode } from './provider-diagnostics.js';
10
+ /** Capture schema failures without copying exception messages, response values or arbitrary field names. */
11
+ export declare function providerFailureDiagnostics(error: unknown): {
12
+ parse?: {
13
+ code: string;
14
+ bytes: number | null;
15
+ } | undefined;
16
+ causes: string[];
17
+ validation: {
18
+ code: string;
19
+ path: Array<string | number>;
20
+ expected: string;
21
+ actual: string;
22
+ }[];
23
+ };
24
+ /** A local record failed after a provider response; repeating the paid request cannot repair it. */
25
+ export declare class ProviderAccountingError extends Error {
26
+ constructor(cause: unknown);
27
+ }
28
+ /** Retry only failed provider operations, before any response tools execute. */
29
+ export declare function recoverProviderCalls(model: Parameters<typeof wrapLanguageModel>[0]['model'], signal: AbortSignal, onRecovery: (event: 'provider_retry' | 'provider_recovered' | 'provider_retry_exhausted', retry: number, error?: unknown) => Promise<unknown>): ReturnType<typeof wrapLanguageModel>;
30
+ /** Construction only; no model substitution, retries, or domain policy. */
31
+ export declare function assessmentModel(config: ProviderConfiguration, fetcher?: typeof fetch): {
32
+ model: Parameters<typeof wrapLanguageModel>[0]['model'];
33
+ providerOptions: Record<string, Record<string, string | boolean>>;
34
+ };
35
+ /** Normalize only provider-reported numbers; SDK fallbacks must not turn absence into zero. */
36
+ export declare function reportedUsage(provider: AssessmentProvider, value: unknown): {
37
+ inputTokens: number | null;
38
+ outputTokens: number | null;
39
+ totalTokens: number | null;
40
+ cachedInputTokens: number | null;
41
+ reasoningTokens: number | null;
42
+ cost: number | null;
43
+ raw: Record<string, unknown> | null;
44
+ missing: string | null;
45
+ };
@@ -0,0 +1,291 @@
1
+ import { wrapLanguageModel } from 'ai';
2
+ import { setTimeout as delay } from 'node:timers/promises';
3
+ import { createOpenAI } from '@ai-sdk/openai';
4
+ export { PROVIDER_FAILURE_CODES, providerHttpFailure, providerHttpDiagnostics, providerRequestDiagnostics, providerTransportDiagnostics, providerResponseDiagnostics, } from './provider-diagnostics.js';
5
+ const categories = new Set([
6
+ 'ProviderRequestTimeout',
7
+ 'AI_APICallError',
8
+ 'AI_TypeValidationError',
9
+ 'AI_JSONParseError',
10
+ 'ZodError',
11
+ 'SyntaxError',
12
+ ]);
13
+ const fields = new Set([
14
+ 'choices',
15
+ 'message',
16
+ 'role',
17
+ 'content',
18
+ 'reasoning',
19
+ 'reasoning_details',
20
+ 'type',
21
+ 'data',
22
+ 'format',
23
+ 'id',
24
+ 'index',
25
+ 'text',
26
+ 'summary',
27
+ 'signature',
28
+ 'tool_calls',
29
+ 'function',
30
+ 'name',
31
+ 'arguments',
32
+ 'finish_reason',
33
+ 'usage',
34
+ 'prompt_tokens',
35
+ 'completion_tokens',
36
+ 'total_tokens',
37
+ 'error',
38
+ 'code',
39
+ 'output',
40
+ 'status',
41
+ 'annotations',
42
+ 'images',
43
+ ]);
44
+ const types = new Set(['string', 'number', 'integer', 'boolean', 'array', 'object', 'null', 'undefined']);
45
+ const codes = new Set(['invalid_type', 'invalid_value', 'too_big', 'too_small', 'invalid_format', 'unrecognized_keys']);
46
+ function diagnosticValueAt(value, path) {
47
+ let actual = value;
48
+ for (const key of path) {
49
+ actual =
50
+ actual && typeof actual === 'object' && (typeof key === 'string' || typeof key === 'number')
51
+ ? actual[key]
52
+ : undefined;
53
+ }
54
+ return actual;
55
+ }
56
+ function diagnosticPathPart(key) {
57
+ if (typeof key === 'number' && Number.isSafeInteger(key) && key >= 0)
58
+ return key;
59
+ return typeof key === 'string' && fields.has(key) ? key : '[field]';
60
+ }
61
+ function diagnosticType(value, available) {
62
+ if (!available)
63
+ return 'unavailable';
64
+ if (value === null)
65
+ return 'null';
66
+ return Array.isArray(value) ? 'array' : typeof value;
67
+ }
68
+ /** Map parser messages to fixed categories; never retain the message or rejected text. */
69
+ function parseFailure(cause) {
70
+ const message = typeof cause.message === 'string' ? cause.message : '';
71
+ if (message === 'Object contains forbidden prototype property')
72
+ return 'prototype_property_rejected';
73
+ if (message === 'Unexpected end of JSON input')
74
+ return 'unexpected_end';
75
+ if (message.startsWith('Unterminated string'))
76
+ return 'unterminated_string';
77
+ if (message.startsWith('Bad control character'))
78
+ return 'invalid_control_character';
79
+ if (message.startsWith('Unexpected token'))
80
+ return 'unexpected_token';
81
+ return 'syntax_error';
82
+ }
83
+ /** Capture schema failures without copying exception messages, response values or arbitrary field names. */
84
+ export function providerFailureDiagnostics(error) {
85
+ const causes = [];
86
+ const validation = [];
87
+ let parse;
88
+ let rejectedBytes = null;
89
+ let value;
90
+ let hasValue = false;
91
+ const collect = (issues, depth = 0) => {
92
+ if (!Array.isArray(issues) || depth > 4)
93
+ return;
94
+ for (const issue of issues.slice(0, 16)) {
95
+ if (!issue || typeof issue !== 'object' || validation.length >= 16)
96
+ continue;
97
+ if (issue.code === 'invalid_union' && Array.isArray(issue.errors)) {
98
+ for (const branch of issue.errors.slice(0, 8))
99
+ collect(branch, depth + 1);
100
+ }
101
+ if (!codes.has(issue.code) || !Array.isArray(issue.path))
102
+ continue;
103
+ const path = issue.path.slice(0, 16);
104
+ validation.push({
105
+ code: issue.code,
106
+ path: path.map(diagnosticPathPart),
107
+ expected: types.has(issue.expected) ? issue.expected : 'unavailable',
108
+ actual: diagnosticType(diagnosticValueAt(value, path), hasValue),
109
+ });
110
+ }
111
+ };
112
+ let current = error;
113
+ for (let depth = 0; current && typeof current === 'object' && depth < 5; depth++) {
114
+ const cause = current;
115
+ causes.push(typeof cause.name === 'string' && categories.has(cause.name) ? cause.name : 'other');
116
+ if (cause.name === 'AI_JSONParseError' && typeof cause.text === 'string')
117
+ rejectedBytes = Buffer.byteLength(cause.text, 'utf8');
118
+ if (cause.name === 'SyntaxError')
119
+ parse = { code: parseFailure(cause), bytes: rejectedBytes };
120
+ if (cause.name === 'AI_TypeValidationError' && 'value' in cause) {
121
+ value = cause.value;
122
+ hasValue = true;
123
+ }
124
+ collect(cause.issues);
125
+ current = cause.cause;
126
+ }
127
+ return { causes, validation, ...(parse ? { parse } : {}) };
128
+ }
129
+ /** A local record failed after a provider response; repeating the paid request cannot repair it. */
130
+ export class ProviderAccountingError extends Error {
131
+ constructor(cause) {
132
+ super('provider_accounting_failed', { cause });
133
+ this.name = 'ProviderAccountingError';
134
+ }
135
+ }
136
+ class ProviderRequestTimeout extends Error {
137
+ constructor() {
138
+ super('provider_request_timeout');
139
+ this.name = 'ProviderRequestTimeout';
140
+ }
141
+ }
142
+ /** Retry only failed provider operations, before any response tools execute. */
143
+ export function recoverProviderCalls(model, signal, onRecovery) {
144
+ return wrapLanguageModel({
145
+ model,
146
+ middleware: {
147
+ specificationVersion: 'v4',
148
+ wrapGenerate: async ({ model: underlying, params }) => {
149
+ let retries = 0;
150
+ for (;;) {
151
+ signal.throwIfAborted();
152
+ params.abortSignal?.throwIfAborted();
153
+ let response;
154
+ try {
155
+ const timeout = new AbortController();
156
+ const timer = setTimeout(() => timeout.abort(new ProviderRequestTimeout()), 180_000);
157
+ const signals = [signal, params.abortSignal, timeout.signal].filter((value) => value !== undefined);
158
+ try {
159
+ response = await underlying.doGenerate({
160
+ ...params,
161
+ abortSignal: AbortSignal.any(signals),
162
+ });
163
+ }
164
+ catch (error) {
165
+ if (timeout.signal.aborted &&
166
+ !signal.aborted &&
167
+ !params.abortSignal?.aborted &&
168
+ !accountingFailure(error))
169
+ throw new ProviderRequestTimeout();
170
+ throw error;
171
+ }
172
+ finally {
173
+ clearTimeout(timer);
174
+ }
175
+ }
176
+ catch (error) {
177
+ if (signal.aborted || params.abortSignal?.aborted || !recoverableProviderError(error))
178
+ throw error;
179
+ if (retries >= 2) {
180
+ await onRecovery('provider_retry_exhausted', retries, error);
181
+ throw error;
182
+ }
183
+ retries++;
184
+ await onRecovery('provider_retry', retries, error);
185
+ await delay(250 * 2 ** (retries - 1), undefined, { signal });
186
+ continue;
187
+ }
188
+ // Recovery telemetry is local work and must never repeat a successful request.
189
+ if (retries)
190
+ await onRecovery('provider_recovered', retries);
191
+ return response;
192
+ }
193
+ },
194
+ },
195
+ });
196
+ }
197
+ function accountingFailure(error) {
198
+ const seen = new Set();
199
+ let cause = error;
200
+ while (cause instanceof Error && !seen.has(cause)) {
201
+ if (cause instanceof ProviderAccountingError)
202
+ return true;
203
+ seen.add(cause);
204
+ cause = cause.cause;
205
+ }
206
+ return false;
207
+ }
208
+ function recoverableProviderError(error) {
209
+ if (accountingFailure(error))
210
+ return false;
211
+ if (error instanceof ProviderRequestTimeout)
212
+ return true;
213
+ // Our usage reader parses the same response before the SDK; malformed JSON can surface here directly.
214
+ if (error instanceof SyntaxError)
215
+ return true;
216
+ if (!(error instanceof Error) || error.name !== 'AI_APICallError')
217
+ return false;
218
+ const failure = error;
219
+ const status = failure.statusCode;
220
+ if (status === 408 || status === 429 || (status !== undefined && status >= 500 && status <= 599))
221
+ return true;
222
+ if (status === undefined)
223
+ return failure.isRetryable === true;
224
+ // A successful HTTP response can still fail SDK parsing/validation. Never relax that validation.
225
+ return (status >= 200 &&
226
+ status < 300 &&
227
+ providerFailureDiagnostics(error).causes.some((cause) => cause === 'AI_JSONParseError' || cause === 'AI_TypeValidationError'));
228
+ }
229
+ /** Construction only; no model substitution, retries, or domain policy. */
230
+ export function assessmentModel(config, fetcher = fetch) {
231
+ if (!['openai', 'openrouter'].includes(config.provider))
232
+ throw new Error('provider_selection_invalid');
233
+ const key = process.env[config.provider === 'openai' ? 'OPENAI_API_KEY' : 'OPENROUTER_API_KEY'];
234
+ if (!key?.trim())
235
+ throw new Error('provider_credential_missing');
236
+ if (!config.model.trim())
237
+ throw new Error('provider_model_missing');
238
+ if (config.provider === 'openai') {
239
+ return {
240
+ model: createOpenAI({ apiKey: key, fetch: fetcher }).responses(config.model),
241
+ providerOptions: { openai: { store: false, ...(config.effort ? { reasoningEffort: config.effort } : {}) } },
242
+ };
243
+ }
244
+ return {
245
+ // The OpenRouter adapter currently drops function.strict. The existing
246
+ // OpenAI-compatible chat adapter forwards it without rewriting requests.
247
+ model: createOpenAI({
248
+ apiKey: key,
249
+ baseURL: 'https://openrouter.ai/api/v1',
250
+ name: 'openrouter',
251
+ fetch: fetcher,
252
+ }).chat(config.model),
253
+ providerOptions: {
254
+ openai: {
255
+ store: false,
256
+ forceReasoning: true,
257
+ ...(config.effort ? { reasoningEffort: config.effort } : {}),
258
+ },
259
+ },
260
+ };
261
+ }
262
+ /** Normalize only provider-reported numbers; SDK fallbacks must not turn absence into zero. */
263
+ export function reportedUsage(provider, value) {
264
+ const raw = value && typeof value === 'object' ? value : null;
265
+ const number = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
266
+ const names = provider === 'openai'
267
+ ? {
268
+ input: 'input_tokens',
269
+ output: 'output_tokens',
270
+ inputDetails: 'input_tokens_details',
271
+ outputDetails: 'output_tokens_details',
272
+ }
273
+ : {
274
+ input: 'prompt_tokens',
275
+ output: 'completion_tokens',
276
+ inputDetails: 'prompt_tokens_details',
277
+ outputDetails: 'completion_tokens_details',
278
+ };
279
+ const inputDetails = raw?.[names.inputDetails];
280
+ const outputDetails = raw?.[names.outputDetails];
281
+ return {
282
+ inputTokens: number(raw?.[names.input]),
283
+ outputTokens: number(raw?.[names.output]),
284
+ totalTokens: number(raw?.total_tokens),
285
+ cachedInputTokens: number(inputDetails?.cached_tokens),
286
+ reasoningTokens: number(outputDetails?.reasoning_tokens),
287
+ cost: number(raw?.cost),
288
+ raw,
289
+ missing: raw === null ? 'provider_did_not_report' : null,
290
+ };
291
+ }