@tobi-or-not/quorum 0.4.0 → 0.6.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 (111) hide show
  1. package/README.md +3 -1
  2. package/dist/bench/fingerprint.d.ts +8 -5
  3. package/dist/bench/fingerprint.js +28 -9
  4. package/dist/bench/records.d.ts +168 -0
  5. package/dist/bench/records.js +106 -1
  6. package/dist/bench/runner.d.ts +18 -0
  7. package/dist/bench/runner.js +30 -4
  8. package/dist/cli/bench.d.ts +11 -4
  9. package/dist/cli/bench.js +34 -17
  10. package/dist/cli/bin.js +2 -2
  11. package/dist/cli/io.d.ts +5 -0
  12. package/dist/cli/main.d.ts +67 -24
  13. package/dist/cli/main.js +288 -59
  14. package/dist/cli/print-config.d.ts +8 -6
  15. package/dist/cli/print-config.js +26 -8
  16. package/dist/cli/render.d.ts +9 -3
  17. package/dist/cli/render.js +43 -2
  18. package/dist/config/claude-code.d.ts +2 -6
  19. package/dist/config/claude-code.js +6 -44
  20. package/dist/config/command.d.ts +10 -0
  21. package/dist/config/command.js +47 -0
  22. package/dist/config/env.d.ts +32 -19
  23. package/dist/config/env.js +95 -32
  24. package/dist/config/from-config.js +21 -3
  25. package/dist/config/resolve.d.ts +13 -1
  26. package/dist/config/resolve.js +27 -1
  27. package/dist/config/schema.d.ts +152 -5
  28. package/dist/config/schema.js +156 -12
  29. package/dist/core/clock.d.ts +17 -0
  30. package/dist/core/clock.js +14 -0
  31. package/dist/core/coverage.d.ts +74 -0
  32. package/dist/core/coverage.js +221 -0
  33. package/dist/core/diff.d.ts +101 -0
  34. package/dist/core/diff.js +178 -35
  35. package/dist/core/errors.d.ts +12 -3
  36. package/dist/core/errors.js +21 -2
  37. package/dist/core/estimate.d.ts +45 -0
  38. package/dist/core/estimate.js +188 -0
  39. package/dist/core/exclude.d.ts +42 -0
  40. package/dist/core/exclude.js +189 -0
  41. package/dist/core/flags.d.ts +14 -1
  42. package/dist/core/flags.js +56 -0
  43. package/dist/core/inputs.d.ts +38 -0
  44. package/dist/core/inputs.js +228 -0
  45. package/dist/core/limits.d.ts +83 -0
  46. package/dist/core/limits.js +169 -0
  47. package/dist/core/output.d.ts +3 -2
  48. package/dist/core/output.js +3 -2
  49. package/dist/core/parts.d.ts +146 -0
  50. package/dist/core/parts.js +388 -0
  51. package/dist/core/ports.d.ts +67 -2
  52. package/dist/core/ports.js +36 -1
  53. package/dist/core/prompts.d.ts +22 -3
  54. package/dist/core/prompts.js +43 -7
  55. package/dist/core/quorum.d.ts +26 -8
  56. package/dist/core/quorum.js +310 -73
  57. package/dist/core/retry.d.ts +36 -0
  58. package/dist/core/retry.js +46 -0
  59. package/dist/core/secrets.d.ts +98 -0
  60. package/dist/core/secrets.js +507 -0
  61. package/dist/core/stages/context.d.ts +131 -23
  62. package/dist/core/stages/context.js +331 -46
  63. package/dist/core/stages/panel.d.ts +13 -6
  64. package/dist/core/stages/panel.js +79 -19
  65. package/dist/core/stages/research.d.ts +110 -25
  66. package/dist/core/stages/research.js +338 -44
  67. package/dist/core/tokens.d.ts +31 -0
  68. package/dist/core/tokens.js +81 -0
  69. package/dist/core/types.d.ts +280 -25
  70. package/dist/core/verify.d.ts +6 -0
  71. package/dist/core/verify.js +6 -3
  72. package/dist/git/run.d.ts +223 -0
  73. package/dist/git/run.js +608 -0
  74. package/dist/git/tree.d.ts +43 -0
  75. package/dist/git/tree.js +171 -0
  76. package/dist/index.d.ts +26 -2
  77. package/dist/index.js +34 -2
  78. package/dist/providers/anthropic.d.ts +3 -1
  79. package/dist/providers/anthropic.js +10 -3
  80. package/dist/providers/claude-code.d.ts +56 -11
  81. package/dist/providers/claude-code.js +70 -25
  82. package/dist/providers/gemini.d.ts +5 -1
  83. package/dist/providers/gemini.js +65 -11
  84. package/dist/providers/http.d.ts +49 -4
  85. package/dist/providers/http.js +155 -14
  86. package/dist/providers/ollama.d.ts +4 -1
  87. package/dist/providers/ollama.js +13 -5
  88. package/dist/providers/openai-compatible.d.ts +4 -1
  89. package/dist/providers/openai-compatible.js +13 -5
  90. package/dist/providers/options.d.ts +12 -3
  91. package/dist/providers/options.js +30 -10
  92. package/dist/providers/size.d.ts +19 -15
  93. package/dist/providers/size.js +33 -73
  94. package/dist/sources/added.d.ts +49 -0
  95. package/dist/sources/added.js +134 -0
  96. package/dist/sources/diff.d.ts +13 -0
  97. package/dist/sources/diff.js +63 -0
  98. package/dist/sources/local.d.ts +41 -0
  99. package/dist/sources/local.js +251 -0
  100. package/dist/sources/paths.d.ts +45 -0
  101. package/dist/sources/paths.js +230 -0
  102. package/dist/sources/range.d.ts +21 -0
  103. package/dist/sources/range.js +75 -0
  104. package/dist/sources/read.d.ts +69 -0
  105. package/dist/sources/read.js +37 -0
  106. package/dist/sources/repository.d.ts +9 -0
  107. package/dist/sources/repository.js +28 -0
  108. package/dist/sources/skips.d.ts +49 -0
  109. package/dist/sources/skips.js +126 -0
  110. package/package.json +1 -1
  111. package/schema/quorum.schema.json +49 -1
@@ -0,0 +1,171 @@
1
+ import { ConfigError } from "../core/errors.js";
2
+ import { checkedId, GitError, gitFailure, joined, MAX_GIT_OUTPUT_BYTES, runGit } from "./run.js";
3
+ const UNREADABLE = 'git ls-tree printed an entry quorum cannot read';
4
+ const UNSIZED = 'git ls-tree could not size an object the commit names: the repository lacks it, as a partial clone does';
5
+ const NOT_RETURNED = 'git cat-file did not return each listed blob at its listed size';
6
+ /** What of an entry comes before its tab. `BAD` is the size git prints for a blob it could not find. */
7
+ const HEADER = /^(100644|100755|120000|160000) (blob|commit) ([0-9a-f]+) +(\d+|-|BAD)$/;
8
+ /** The length of an id in each object format. */
9
+ const ID_LENGTH = { sha1: 40, sha256: 64 };
10
+ /** More than any header: a mode, a type, a 64-hex id, the size's padding and a size of up to 20 digits. */
11
+ const HEADER_BYTES = 128;
12
+ const TAB = 0x09;
13
+ const LINE_FEED = 0x0A;
14
+ const unreadable = () => new GitError(UNREADABLE, 'ls-tree');
15
+ /** The entry a record holds: every field is checked, whether or not the caller keeps the entry, and the id must be the length of `objectFormat`'s. */
16
+ function readRecord(record, objectFormat) {
17
+ const tab = record.indexOf(TAB);
18
+ if (tab === -1 || tab > HEADER_BYTES)
19
+ throw unreadable();
20
+ const fields = HEADER.exec(new TextDecoder().decode(record.subarray(0, tab)));
21
+ if (fields === null)
22
+ throw unreadable();
23
+ const [, mode, type, id, size] = fields;
24
+ const gitlink = type === 'commit';
25
+ const unsized = size === 'BAD' && !gitlink;
26
+ if (id.length !== ID_LENGTH[objectFormat] || gitlink !== (mode === '160000'))
27
+ throw unreadable();
28
+ if (!unsized && gitlink !== (size === '-'))
29
+ throw unreadable();
30
+ const bytes = gitlink || unsized
31
+ ? undefined
32
+ : Number(size);
33
+ if (bytes !== undefined && !Number.isSafeInteger(bytes))
34
+ throw unreadable();
35
+ return {
36
+ entry: {
37
+ mode: mode,
38
+ type: gitlink
39
+ ? 'commit'
40
+ : 'blob',
41
+ id,
42
+ size: bytes,
43
+ path: record.subarray(tab + 1),
44
+ },
45
+ unsized,
46
+ };
47
+ }
48
+ /**
49
+ * Reads `ls-tree -z` output chunk by chunk, every record checked in full. `feed` takes a chunk and says whether to go on, which it does
50
+ * not once the kept paths pass `maxPathBytes`, or once a record has gone on that far past its header with no
51
+ * NUL, which no kept path could end within; `end` hands over the kept entries when the output ended on a
52
+ * whole record. Only a record cut by a chunk's end is held, and only what it needs: a kept path is copied
53
+ * out of the chunk, so a long listing keeps nothing but the entries `keep` took.
54
+ */
55
+ function listingReader(objectFormat, keep, maxPathBytes) {
56
+ const entries = [];
57
+ const started = [];
58
+ let startedBytes = 0;
59
+ let keptBytes = 0;
60
+ const take = (record) => {
61
+ const { entry, unsized } = readRecord(record, objectFormat);
62
+ if (!keep(entry.path))
63
+ return true;
64
+ if (unsized)
65
+ throw new GitError(UNSIZED, 'ls-tree');
66
+ keptBytes += entry.path.length;
67
+ if (keptBytes > maxPathBytes)
68
+ return false;
69
+ entries.push({
70
+ ...entry,
71
+ path: new Uint8Array(entry.path),
72
+ });
73
+ return true;
74
+ };
75
+ return {
76
+ feed: (chunk) => {
77
+ let from = 0;
78
+ for (let nul = chunk.indexOf(0); nul !== -1; nul = chunk.indexOf(0, from)) {
79
+ const end = chunk.subarray(from, nul);
80
+ const record = started.length === 0
81
+ ? end
82
+ : joined([...started, end], startedBytes + end.length);
83
+ started.length = 0;
84
+ startedBytes = 0;
85
+ if (!take(record))
86
+ return false;
87
+ from = nul + 1;
88
+ }
89
+ if (from < chunk.length) {
90
+ started.push(new Uint8Array(chunk.subarray(from)));
91
+ startedBytes += chunk.length - from;
92
+ }
93
+ return startedBytes <= HEADER_BYTES + maxPathBytes;
94
+ },
95
+ end: () => {
96
+ if (started.length > 0)
97
+ throw unreadable();
98
+ return entries;
99
+ },
100
+ };
101
+ }
102
+ /**
103
+ * The entries of `commit`, an id, in git's order, one `ls-tree -r -z --long --full-tree`. The listing is
104
+ * parsed as it streams and only the entries `keep` takes are held, each path as bytes, so a large tree costs
105
+ * what its kept paths cost. Every record git prints is checked, kept or not, and a `GitError` follows for one
106
+ * quorum cannot read (a mode, a type or a record it does not know, an id that is not the length of the
107
+ * repository's object format, a gitlink with a size, a blob with none), and for a git that fails. A blob git
108
+ * could not size, as a partial clone's missing one, is a `GitError` only when `keep` takes it: an entry the
109
+ * caller does not read costs it nothing. `undefined` once the kept paths hold more than `maxPathBytes`, which
110
+ * the child is then stopped for: no entry is a partial answer.
111
+ */
112
+ export async function listTree(repository, commit, keep, maxPathBytes = MAX_GIT_OUTPUT_BYTES) {
113
+ const reader = listingReader(repository.objectFormat, keep, maxPathBytes);
114
+ const run = await runGit(repository.context, {
115
+ op: 'list-tree',
116
+ top: repository.top,
117
+ commit,
118
+ }, { onStdout: reader.feed });
119
+ if (run.over)
120
+ return undefined;
121
+ if (run.code !== 0)
122
+ throw gitFailure('list-tree', run);
123
+ return reader.end();
124
+ }
125
+ /**
126
+ * The bytes of each of `entries`' blobs, in the entries' order, through one `cat-file --batch --buffer` whose
127
+ * stdin is their ids. Each answer must be the header `<id> blob <size>`, the body of exactly that size and a
128
+ * line feed: a missing object, another type, size or id, a short answer and a byte past the last are each a
129
+ * `GitError`. The sizes are summed first, and a `ConfigError` at the run's flag comes before any spawn when
130
+ * they pass `limit`. A gitlink, which names no blob, and an id that is not 40 or 64 lowercase hexadecimal
131
+ * characters are a `RangeError`, also before any spawn. The blobs are views of one array.
132
+ */
133
+ export async function readBlobs(repository, entries, limit) {
134
+ const listed = entries.map((entry) => {
135
+ if (entry.size === undefined)
136
+ throw new RangeError('a gitlink names no blob to read');
137
+ return {
138
+ id: checkedId(entry.id),
139
+ size: entry.size,
140
+ header: `${entry.id} blob ${entry.size}\n`,
141
+ };
142
+ });
143
+ const total = listed.reduce((sum, blob) => sum + blob.size, 0);
144
+ if (total > limit) {
145
+ throw new ConfigError([
146
+ { path: repository.context.flag, message: `the files to read hold ${total} bytes, over the ${limit} a review reads` },
147
+ ]);
148
+ }
149
+ // Exactly what a faithful git prints, so one byte past it stops the child and fails closed below.
150
+ const expected = listed.reduce((sum, blob) => sum + blob.header.length + blob.size + 1, 0);
151
+ const run = await runGit(repository.context, { op: 'read-objects', top: repository.top }, {
152
+ input: listed.map(blob => `${blob.id}\n`).join(''),
153
+ maxStdout: expected,
154
+ });
155
+ if (run.over)
156
+ throw new GitError(NOT_RETURNED, 'cat-file');
157
+ if (run.code !== 0)
158
+ throw gitFailure('read-objects', run);
159
+ const decoder = new TextDecoder();
160
+ const blobs = [];
161
+ let at = 0;
162
+ for (const { header, size } of listed) {
163
+ const bodyAt = at + header.length;
164
+ const end = bodyAt + size;
165
+ if (decoder.decode(run.stdout.subarray(at, bodyAt)) !== header || run.stdout[end] !== LINE_FEED)
166
+ throw new GitError(NOT_RETURNED, 'cat-file');
167
+ blobs.push(run.stdout.subarray(bodyAt, end));
168
+ at = end + 1;
169
+ }
170
+ return blobs;
171
+ }
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { QuorumResult } from './core/types.ts';
2
+ import type { SourceContext, SourceRead, SourceSpec } from './sources/read.ts';
2
3
  export { defineConfig } from './config/define.ts';
3
4
  export type { Env } from './config/env.ts';
4
5
  export { fromConfig } from './config/from-config.ts';
@@ -13,7 +14,8 @@ export type { PolicyRules, Rule } from './core/policy.ts';
13
14
  export type { ChatMessage, CompletionRequest, CompletionResponse, EventSink, JsonSchema, ProfilePorts, Provider, QuorumPorts } from './core/ports.ts';
14
15
  export { createQuorum } from './core/quorum.ts';
15
16
  export { inertJson, inertLine } from './core/sanitize.ts';
16
- export type { Confidence, Finding, Flag, FlagCode, IncompleteEntry, IncompleteReason, Lens, LensVote, Profile, ProfileMeta, ProfileProviders, Prompts, ProviderRef, Quorum, QuorumEvent, QuorumMeta, QuorumOptions, QuorumResult, StageName, Thresholds, Usage, Verdict, VerdictStatus, Vote, } from './core/types.ts';
17
+ export type { Confidence, CoverageEntry, CoverageReason, CoverageStatus, CredentialKind, Estimate, Finding, Flag, FlagCode, IncompleteEntry, IncompleteReason, LeftOutFile, LeftOutReason, LeftRange, Lens, LensVote, ObjectFormat, Profile, ProfileEstimate, ProfileMeta, ProfileProviders, Prompts, ProviderRef, Quorum, QuorumEvent, QuorumMeta, QuorumOptions, QuorumResult, ReviewInput, ReviewSource, SecretRule, SkipRule, StageName, Thresholds, Usage, Verdict, VerdictStatus, Vote, VoteFailure, VoteFailureKind, } from './core/types.ts';
18
+ export { GitError } from './git/run.ts';
17
19
  export { securityProfile } from './profiles/security.ts';
18
20
  export { anthropic } from './providers/anthropic.ts';
19
21
  export type { AnthropicOptions } from './providers/anthropic.ts';
@@ -29,10 +31,32 @@ export type { OpenAICompatibleOptions } from './providers/openai-compatible.ts';
29
31
  export type { Auth, HttpProviderOptions, StructuredOutput } from './providers/options.ts';
30
32
  export { presets } from './providers/presets.ts';
31
33
  export type { Preset, PresetName, Protocol } from './providers/presets.ts';
34
+ export type { SourceRead, SourceSpec } from './sources/read.ts';
35
+ /**
36
+ * Read the diff a review is about from a source, as the CLI does for a diff, `--range`, `--local`, `--staged`
37
+ * and `--path`: `spec` names the source and `context` the working directory, the environment, a `signal`, the
38
+ * config's `exclude` patterns, which a source that reads files applies before it reads them, and its `send`,
39
+ * the files a path review reads though it skips a secret otherwise, each a path as the diff writes it. It
40
+ * answers with the `diff`, where it came from (`source`) and the files it left out (`leftOut`), which `review`
41
+ * takes as its input.
42
+ * A git source runs the system's git, found on the `PATH` of `context.env`, on the platform of this process: it
43
+ * needs git 2.41 or later, and Linux or macOS. No source cuts a diff, drops a file without listing it or reads
44
+ * outside the repository's top level.
45
+ *
46
+ * @throws ConfigError, its every issue naming the flag the CLI names, when the source refuses what it was given
47
+ * or the working directory is no repository it can read, or `kind` is none of the five
48
+ * @throws GitError when a git command the source runs fails
49
+ *
50
+ * @example
51
+ * const input = await readSource({ kind: 'paths', paths: ['src'] }, { cwd: process.cwd(), env: process.env })
52
+ * const result = await quorum.review(input)
53
+ */
54
+ export declare function readSource(spec: SourceSpec, context: Omit<SourceContext, 'platform' | 'git'>): Promise<SourceRead>;
32
55
  /**
33
56
  * Review a diff as the CLI does with no flag: with the file `QUORUM_CONFIG` names, if any (an absolute
34
57
  * path), and the `QUORUM_*` variables of `process.env` with their `RESEARCH_*` and `VOTER_*` aliases, on the profiles
35
- * they select, the security profile alone by default. `onProgress` receives the progress lines the CLI
58
+ * they select, the security profile alone by default, sending the files the config's `send` names though
59
+ * they are held as secrets. `onProgress` receives the progress lines the CLI
36
60
  * prints on stderr after its banner, never the banner or a warning. A configuration error, a missing
37
61
  * model included, rejects with a `ConfigError`, even for an empty diff.
38
62
  *
package/dist/index.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { progressSink } from "./cli/render.js";
2
2
  import { fromConfig } from "./config/from-config.js";
3
3
  import { loadConfig } from "./config/load.js";
4
+ import { readSource as readSourceOf } from "./sources/read.js";
4
5
  export { defineConfig } from "./config/define.js";
5
6
  export { fromConfig } from "./config/from-config.js";
6
7
  export { loadConfig } from "./config/load.js";
@@ -8,6 +9,7 @@ export { ConfigError, OutputError, ProviderError, QuorumError } from "./core/err
8
9
  export { defaultPolicy } from "./core/policy.js";
9
10
  export { createQuorum } from "./core/quorum.js";
10
11
  export { inertJson, inertLine } from "./core/sanitize.js";
12
+ export { GitError } from "./git/run.js";
11
13
  export { securityProfile } from "./profiles/security.js";
12
14
  export { anthropic } from "./providers/anthropic.js";
13
15
  export { claudeCode } from "./providers/claude-code.js";
@@ -15,10 +17,40 @@ export { gemini } from "./providers/gemini.js";
15
17
  export { ollama } from "./providers/ollama.js";
16
18
  export { openaiCompatible } from "./providers/openai-compatible.js";
17
19
  export { presets } from "./providers/presets.js";
20
+ /**
21
+ * Read the diff a review is about from a source, as the CLI does for a diff, `--range`, `--local`, `--staged`
22
+ * and `--path`: `spec` names the source and `context` the working directory, the environment, a `signal`, the
23
+ * config's `exclude` patterns, which a source that reads files applies before it reads them, and its `send`,
24
+ * the files a path review reads though it skips a secret otherwise, each a path as the diff writes it. It
25
+ * answers with the `diff`, where it came from (`source`) and the files it left out (`leftOut`), which `review`
26
+ * takes as its input.
27
+ * A git source runs the system's git, found on the `PATH` of `context.env`, on the platform of this process: it
28
+ * needs git 2.41 or later, and Linux or macOS. No source cuts a diff, drops a file without listing it or reads
29
+ * outside the repository's top level.
30
+ *
31
+ * @throws ConfigError, its every issue naming the flag the CLI names, when the source refuses what it was given
32
+ * or the working directory is no repository it can read, or `kind` is none of the five
33
+ * @throws GitError when a git command the source runs fails
34
+ *
35
+ * @example
36
+ * const input = await readSource({ kind: 'paths', paths: ['src'] }, { cwd: process.cwd(), env: process.env })
37
+ * const result = await quorum.review(input)
38
+ */
39
+ export async function readSource(spec, context) {
40
+ return readSourceOf(spec, {
41
+ cwd: context.cwd,
42
+ env: context.env,
43
+ signal: context.signal,
44
+ exclude: context.exclude,
45
+ send: context.send,
46
+ platform: process.platform,
47
+ });
48
+ }
18
49
  /**
19
50
  * Review a diff as the CLI does with no flag: with the file `QUORUM_CONFIG` names, if any (an absolute
20
51
  * path), and the `QUORUM_*` variables of `process.env` with their `RESEARCH_*` and `VOTER_*` aliases, on the profiles
21
- * they select, the security profile alone by default. `onProgress` receives the progress lines the CLI
52
+ * they select, the security profile alone by default, sending the files the config's `send` names though
53
+ * they are held as secrets. `onProgress` receives the progress lines the CLI
22
54
  * prints on stderr after its banner, never the banner or a warning. A configuration error, a missing
23
55
  * model included, rejects with a `ConfigError`, even for an empty diff.
24
56
  *
@@ -34,5 +66,5 @@ export async function runQuorum(diff, onProgress) {
34
66
  ? undefined
35
67
  : progressSink(onProgress),
36
68
  });
37
- return quorum.review({ diff });
69
+ return quorum.review({ diff, send: config.send });
38
70
  }
@@ -7,7 +7,9 @@ export type AnthropicOptions = HttpProviderOptions;
7
7
  * there is one, travels only in the header `auth` names, `Authorization: Bearer` by default (invariant
8
8
  * I1). It never sends an assistant prefill, which current models reject. It refuses, before any request,
9
9
  * a request that may not fit `contextTokens`. It always sends a token limit, since the Messages API
10
- * requires one: `maxTokens`, else the reply budget of the size guard.
10
+ * requires one: `maxTokens`, else the reply budget of the size guard. It states its worst case from the
11
+ * count its size guard keeps: the text it sends, the template reserve and that budget, and the room its
12
+ * guard leaves from the same count: `contextTokens` less those three.
11
13
  *
12
14
  * @throws ConfigError with every problem of the options, before any request
13
15
  */
@@ -1,8 +1,9 @@
1
+ import { DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS } from "../core/ports.js";
1
2
  import { postJson } from "./http.js";
2
3
  import { shapeMessages } from "./messages.js";
3
4
  import { isRecord, mergeBody, prepareHttp } from "./options.js";
4
5
  import { endedEarly, joinedText, replyFailure, tokenUsage } from "./reply.js";
5
- import { checkFits, contextBudget, DEFAULT_REPLY_TOKENS } from "./size.js";
6
+ import { checkFits, contextBudget, DEFAULT_REPLY_TOKENS, roomTokens, worstCaseTokens } from "./size.js";
6
7
  /**
7
8
  * The API version every request names. For this call it differs from `2023-06-01` only in refusing any
8
9
  * `temperature`, `top_p` or `top_k`, so no temperature is sent unless one is set.
@@ -76,12 +77,14 @@ function readReply(reply, { id, model }, redact) {
76
77
  * there is one, travels only in the header `auth` names, `Authorization: Bearer` by default (invariant
77
78
  * I1). It never sends an assistant prefill, which current models reject. It refuses, before any request,
78
79
  * a request that may not fit `contextTokens`. It always sends a token limit, since the Messages API
79
- * requires one: `maxTokens`, else the reply budget of the size guard.
80
+ * requires one: `maxTokens`, else the reply budget of the size guard. It states its worst case from the
81
+ * count its size guard keeps: the text it sends, the template reserve and that budget, and the room its
82
+ * guard leaves from the same count: `contextTokens` less those three.
80
83
  *
81
84
  * @throws ConfigError with every problem of the options, before any request
82
85
  */
83
86
  export function anthropic(options) {
84
- const { id, model, auth = 'bearer', temperature, maxTokens = DEFAULT_REPLY_TOKENS, contextTokens, systemPrompt = 'native', structuredOutput = 'prompt' } = options;
87
+ const { id, model, auth = 'bearer', temperature, maxTokens = DEFAULT_REPLY_TOKENS, contextTokens, systemPrompt = 'native', structuredOutput = 'prompt', timeoutMs = DEFAULT_TIMEOUT_MS, retries = DEFAULT_RETRIES } = options;
85
88
  const { url, headers, redact, extraBody } = prepareHttp(options, { ...RULES, auth }, '/v1/messages');
86
89
  // The version goes last, so no header can replace it.
87
90
  const sent = { ...headers, 'anthropic-version': ANTHROPIC_VERSION };
@@ -89,6 +92,10 @@ export function anthropic(options) {
89
92
  return {
90
93
  id,
91
94
  model,
95
+ timeoutMs,
96
+ retries,
97
+ worstCase: request => worstCaseTokens(shapeMessages(request, systemPrompt), request.output, budget),
98
+ room: request => roomTokens(shapeMessages(request, systemPrompt), request.output, budget),
92
99
  async complete(request) {
93
100
  const { system, messages } = shapeMessages(request, systemPrompt);
94
101
  checkFits(id, { system, messages }, request.output, budget);
@@ -38,10 +38,16 @@ export interface ClaudeCodeOptions {
38
38
  model: string;
39
39
  /**
40
40
  * The model's context window in tokens, prompt and reply together. Required: every request is checked
41
- * against it and refused, before it is run, when it may not fit. It must be more than 20096, the reply
42
- * budget and the reserve for what Claude Code adds.
41
+ * against it and refused, before it is run, when it may not fit. It must be more than `maxTokens` and the
42
+ * 4096 tokens reserved for what Claude Code adds: 20096 by default.
43
43
  */
44
44
  contextTokens: number;
45
+ /**
46
+ * The most tokens each reply may hold, thinking included, which Claude Code reads from
47
+ * `CLAUDE_CODE_MAX_OUTPUT_TOKENS` and caps at the model's own limit: a whole number of at least 1. Default 16000.
48
+ * It replaces a `CLAUDE_CODE_MAX_OUTPUT_TOKENS` of the environment.
49
+ */
50
+ maxTokens?: number;
45
51
  /** Whose credentials `claude` uses. Default `inherit`. */
46
52
  auth?: ClaudeCodeAuth;
47
53
  /**
@@ -62,6 +68,19 @@ export interface ClaudeCodeOptions {
62
68
  command?: string;
63
69
  /** The environment `claude` inherits, less what its auth mode removes. Read once, when the provider is made. Default `process.env`. */
64
70
  env?: Readonly<Record<string, string | undefined>>;
71
+ /**
72
+ * How long Claude Code waits for the response headers of each attempt at its API call (`API_TIMEOUT_MS`), in
73
+ * milliseconds, from 1000 to 86400000. Default 600000. It bounds that wait only. The provider states
74
+ * `timeoutMs` times `retries` plus one to the core as the deadline of the whole run, so raise it for a long run.
75
+ * It replaces an `API_TIMEOUT_MS` of the environment.
76
+ */
77
+ timeoutMs?: number;
78
+ /**
79
+ * Claude Code's own retries of an API call that failed in passing, from 0 to 5. Default 2, where Claude Code
80
+ * alone makes 10. The provider states no retry to the core, which would retry what Claude Code retried. It
81
+ * replaces a `CLAUDE_CODE_MAX_RETRIES` of the environment.
82
+ */
83
+ retries?: number;
65
84
  }
66
85
  /** The command-line settings of a run. */
67
86
  export interface ClaudeArgsSettings {
@@ -111,13 +130,19 @@ export declare function claudeArgs(settings: ClaudeArgsSettings, systemPromptFil
111
130
  * every credential, header and endpoint variable, so a login or a key never reaches another host or travels
112
131
  * with another credential. Names are matched in any letter case, since Windows reads them so. Under
113
132
  * `api-key`, `ANTHROPIC_API_KEY` is then `apiKey` when it is a non-empty string, else the environment's
114
- * own, trimmed, when that is not blank. Last come ten variables the run sets over whatever the environment
133
+ * own, trimmed, when that is not blank. Last come thirteen variables the run sets over whatever the environment
115
134
  * held, in any case: no auto memory, no compaction of a long prompt, a temporary directory of its own, no
116
- * IDE connection or claude.ai MCP connector, which are on by default, and no attachment, file mention,
117
- * `CLAUDE.md` file, bundled skill or managed skill. A line naming a path (`@/path`) in the message makes
118
- * Claude Code attach that file for the model to read, with every tool off, unless the first two are set.
135
+ * IDE connection or claude.ai MCP connector, which are on by default, no attachment, file mention,
136
+ * `CLAUDE.md` file, bundled skill or managed skill, Claude Code's wait for each attempt's response headers
137
+ * and its own retries, and, the last, its limit on each reply, which follow the provider's settings
138
+ * (`settings`). A line naming a path (`@/path`) in the message makes Claude Code attach that file for the
139
+ * model to read, with every tool off, unless the first two are set.
119
140
  */
120
- export declare function childEnv(env: Readonly<Record<string, string | undefined>>, auth: ClaudeCodeAuth, apiKey: string | undefined, tmpDir: string): Record<string, string>;
141
+ export declare function childEnv(env: Readonly<Record<string, string | undefined>>, auth: ClaudeCodeAuth, apiKey: string | undefined, tmpDir: string, settings: {
142
+ readonly timeoutMs: number;
143
+ readonly retries: number;
144
+ readonly maxTokens: number;
145
+ }): Record<string, string>;
121
146
  /**
122
147
  * The values a quoted text must be redacted of: those of the credential variables of the environment a run
123
148
  * gets (`childEnv`'s result), each as written and trimmed, with names matched in any letter case. A value
@@ -137,7 +162,7 @@ export declare function versionProblem(output: string): string | undefined;
137
162
  * JSON result: a signal, a non-zero exit with a quote of stderr, or nothing at all, each a failure. Every
138
163
  * quoted text goes through `snippet`, redacted of the key.
139
164
  *
140
- * @throws ProviderError of the kind the failure is: `too-large`, `refusal`, `http`, `process` or `invalid-response`
165
+ * @throws ProviderError of the kind the failure is: `too-large`, `refusal`, `truncated`, `http`, `process` or `invalid-response`
141
166
  */
142
167
  export declare function readResult(run: ClaudeRun, context: ResultContext): CompletionResponse;
143
168
  /** The directory of one run and what it holds. */
@@ -180,7 +205,8 @@ export declare function trackRun(run: LiveRun): () => void;
180
205
  * 1. exactly one message, a user message, else `unsupported`;
181
206
  * 2. a message that starts with `/` after white space, which `-p` would run as a command: `unsupported`;
182
207
  * 3. a message over `MAX_STDIN_BYTES` bytes: `too-large`;
183
- * 4. the size guard, with `CLAUDE_CODE_TEMPLATE_TOKENS` kept for the context Claude Code adds: `too-large`;
208
+ * 4. the size guard, with the reply budget, `maxTokens`, and `CLAUDE_CODE_TEMPLATE_TOKENS` kept for the
209
+ * context Claude Code adds: `too-large`;
184
210
  * 5. an aborted signal: `aborted`;
185
211
  * 6. a directory of its own, under the temporary directory, holding an empty working directory, `claude`'s
186
212
  * scratch directory and the system text's file: a failure to make it is `process`;
@@ -199,8 +225,27 @@ export declare function trackRun(run: LiveRun): () => void;
199
225
  * 13. an aborted signal: `aborted`; else `readResult`'s reply or failure, with every credential of the
200
226
  * child's environment redacted from the text it quotes (`credentialValues`).
201
227
  *
202
- * No timeout is set: Claude Code retries a failed API call by itself, for minutes, and a deadline is the
203
- * caller's own (a signal).
228
+ * Claude Code retries a failed API call by itself, ten times by default, so the provider sets `API_TIMEOUT_MS`
229
+ * and `CLAUDE_CODE_MAX_RETRIES` in the child's environment from `timeoutMs` and `retries` (600000 ms and 2 by
230
+ * default) over any the environment held, and states no retry to the core, which would retry what Claude Code
231
+ * retried. It sets `CLAUDE_CODE_MAX_OUTPUT_TOKENS` the same way from `maxTokens` (16000 by default, where
232
+ * Claude Code asks for up to 128000 by itself), so the model's API bounds every reply. It states one deadline
233
+ * for the whole run, `timeoutMs` times `retries` plus one: Claude Code's own attempts and the waits between
234
+ * them, its start and the version check, and each reply's time after its headers all count against it, where
235
+ * `API_TIMEOUT_MS` limits only an attempt's wait for its headers. At it the core aborts the signal, which
236
+ * stops the child's group as step 11 says.
237
+ *
238
+ * It states its worst case from the count its size guard keeps, over the model turns of a run: in `schema`
239
+ * mode two, since the model answers by calling the schema tool and `claude` then makes a second turn after
240
+ * the tool's result, which carries the first reply as input, so `2 * (text + 4096) + 3 * maxTokens`; in
241
+ * `prompt` mode one, `text + 4096 + maxTokens`. It leaves out what Claude Code spends beyond that, a reply
242
+ * it continues after its limit, up to three times a turn, and its own retries: those count once the run
243
+ * reports its usage.
244
+ *
245
+ * It states the room its checks leave: the lesser of what its size guard leaves, from the same count, and what
246
+ * the stdin cap leaves, `MAX_STDIN_BYTES` less the message at one token per byte, which bounds the bytes the
247
+ * cap checks, so a request whose room is not negative passes both and text added to the message lowers the
248
+ * room by exactly its count.
204
249
  *
205
250
  * @throws ConfigError with every problem of the options, before any request
206
251
  */