@tobi-or-not/quorum 0.5.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 (88) hide show
  1. package/README.md +2 -0
  2. package/dist/bench/fingerprint.d.ts +6 -5
  3. package/dist/bench/fingerprint.js +11 -5
  4. package/dist/bench/records.d.ts +100 -2
  5. package/dist/bench/records.js +80 -5
  6. package/dist/bench/runner.js +1 -1
  7. package/dist/cli/io.d.ts +5 -0
  8. package/dist/cli/main.d.ts +36 -13
  9. package/dist/cli/main.js +194 -44
  10. package/dist/cli/print-config.d.ts +5 -5
  11. package/dist/cli/print-config.js +10 -5
  12. package/dist/cli/render.d.ts +7 -1
  13. package/dist/cli/render.js +25 -3
  14. package/dist/config/claude-code.d.ts +2 -6
  15. package/dist/config/claude-code.js +6 -44
  16. package/dist/config/command.d.ts +10 -0
  17. package/dist/config/command.js +47 -0
  18. package/dist/config/from-config.js +8 -2
  19. package/dist/config/resolve.d.ts +4 -0
  20. package/dist/config/resolve.js +10 -0
  21. package/dist/config/schema.d.ts +13 -2
  22. package/dist/config/schema.js +36 -5
  23. package/dist/core/coverage.d.ts +38 -13
  24. package/dist/core/coverage.js +105 -28
  25. package/dist/core/diff.d.ts +77 -0
  26. package/dist/core/diff.js +122 -24
  27. package/dist/core/estimate.d.ts +45 -0
  28. package/dist/core/estimate.js +188 -0
  29. package/dist/core/flags.d.ts +14 -1
  30. package/dist/core/flags.js +56 -0
  31. package/dist/core/inputs.d.ts +38 -0
  32. package/dist/core/inputs.js +228 -0
  33. package/dist/core/limits.d.ts +5 -4
  34. package/dist/core/limits.js +11 -5
  35. package/dist/core/parts.d.ts +146 -0
  36. package/dist/core/parts.js +388 -0
  37. package/dist/core/ports.d.ts +10 -0
  38. package/dist/core/prompts.d.ts +22 -3
  39. package/dist/core/prompts.js +43 -7
  40. package/dist/core/quorum.d.ts +7 -5
  41. package/dist/core/quorum.js +164 -58
  42. package/dist/core/secrets.d.ts +98 -0
  43. package/dist/core/secrets.js +507 -0
  44. package/dist/core/stages/context.d.ts +16 -3
  45. package/dist/core/stages/context.js +44 -17
  46. package/dist/core/stages/panel.d.ts +8 -2
  47. package/dist/core/stages/panel.js +50 -9
  48. package/dist/core/stages/research.d.ts +107 -31
  49. package/dist/core/stages/research.js +290 -53
  50. package/dist/core/types.d.ts +217 -29
  51. package/dist/core/verify.d.ts +6 -0
  52. package/dist/core/verify.js +6 -3
  53. package/dist/git/run.d.ts +223 -0
  54. package/dist/git/run.js +608 -0
  55. package/dist/git/tree.d.ts +43 -0
  56. package/dist/git/tree.js +171 -0
  57. package/dist/index.d.ts +26 -2
  58. package/dist/index.js +34 -2
  59. package/dist/providers/anthropic.d.ts +2 -1
  60. package/dist/providers/anthropic.js +4 -2
  61. package/dist/providers/claude-code.d.ts +5 -0
  62. package/dist/providers/claude-code.js +11 -1
  63. package/dist/providers/gemini.d.ts +2 -1
  64. package/dist/providers/gemini.js +4 -2
  65. package/dist/providers/ollama.d.ts +2 -1
  66. package/dist/providers/ollama.js +4 -2
  67. package/dist/providers/openai-compatible.d.ts +2 -1
  68. package/dist/providers/openai-compatible.js +4 -2
  69. package/dist/providers/size.d.ts +9 -1
  70. package/dist/providers/size.js +18 -4
  71. package/dist/sources/added.d.ts +49 -0
  72. package/dist/sources/added.js +134 -0
  73. package/dist/sources/diff.d.ts +13 -0
  74. package/dist/sources/diff.js +63 -0
  75. package/dist/sources/local.d.ts +41 -0
  76. package/dist/sources/local.js +251 -0
  77. package/dist/sources/paths.d.ts +45 -0
  78. package/dist/sources/paths.js +230 -0
  79. package/dist/sources/range.d.ts +21 -0
  80. package/dist/sources/range.js +75 -0
  81. package/dist/sources/read.d.ts +69 -0
  82. package/dist/sources/read.js +37 -0
  83. package/dist/sources/repository.d.ts +9 -0
  84. package/dist/sources/repository.js +28 -0
  85. package/dist/sources/skips.d.ts +49 -0
  86. package/dist/sources/skips.js +126 -0
  87. package/package.json +1 -1
  88. package/schema/quorum.schema.json +15 -0
@@ -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, LeftOutFile, LeftOutReason, Lens, LensVote, Profile, ProfileMeta, ProfileProviders, Prompts, ProviderRef, Quorum, QuorumEvent, QuorumMeta, QuorumOptions, QuorumResult, StageName, Thresholds, Usage, Verdict, VerdictStatus, Vote, VoteFailure, VoteFailureKind, } 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
  }
@@ -8,7 +8,8 @@ export type AnthropicOptions = HttpProviderOptions;
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
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.
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.
12
13
  *
13
14
  * @throws ConfigError with every problem of the options, before any request
14
15
  */
@@ -3,7 +3,7 @@ import { postJson } from "./http.js";
3
3
  import { shapeMessages } from "./messages.js";
4
4
  import { isRecord, mergeBody, prepareHttp } from "./options.js";
5
5
  import { endedEarly, joinedText, replyFailure, tokenUsage } from "./reply.js";
6
- import { checkFits, contextBudget, DEFAULT_REPLY_TOKENS, worstCaseTokens } from "./size.js";
6
+ import { checkFits, contextBudget, DEFAULT_REPLY_TOKENS, roomTokens, worstCaseTokens } from "./size.js";
7
7
  /**
8
8
  * The API version every request names. For this call it differs from `2023-06-01` only in refusing any
9
9
  * `temperature`, `top_p` or `top_k`, so no temperature is sent unless one is set.
@@ -78,7 +78,8 @@ function readReply(reply, { id, model }, redact) {
78
78
  * I1). It never sends an assistant prefill, which current models reject. It refuses, before any request,
79
79
  * a request that may not fit `contextTokens`. It always sends a token limit, since the Messages API
80
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.
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.
82
83
  *
83
84
  * @throws ConfigError with every problem of the options, before any request
84
85
  */
@@ -94,6 +95,7 @@ export function anthropic(options) {
94
95
  timeoutMs,
95
96
  retries,
96
97
  worstCase: request => worstCaseTokens(shapeMessages(request, systemPrompt), request.output, budget),
98
+ room: request => roomTokens(shapeMessages(request, systemPrompt), request.output, budget),
97
99
  async complete(request) {
98
100
  const { system, messages } = shapeMessages(request, systemPrompt);
99
101
  checkFits(id, { system, messages }, request.output, budget);
@@ -242,6 +242,11 @@ export declare function trackRun(run: LiveRun): () => void;
242
242
  * it continues after its limit, up to three times a turn, and its own retries: those count once the run
243
243
  * reports its usage.
244
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.
249
+ *
245
250
  * @throws ConfigError with every problem of the options, before any request
246
251
  */
247
252
  export declare function claudeCode(options: ClaudeCodeOptions): Provider;
@@ -5,10 +5,11 @@ import { tmpdir } from 'node:os';
5
5
  import { isAbsolute, join, resolve } from 'node:path';
6
6
  import { ConfigError } from "../core/errors.js";
7
7
  import { DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS } from "../core/ports.js";
8
+ import { tokenBound } from "../core/tokens.js";
8
9
  import { snippet } from "./http.js";
9
10
  import { attemptIssues, contextTokensIssues, isRecord, maxTokensIssues, NOT_VISIBLE_ASCII, wordList } from "./options.js";
10
11
  import { replyFailure, tokenUsage } from "./reply.js";
11
- import { checkFits, contextBudget, DEFAULT_REPLY_TOKENS, utf8Length, worstCaseTokens } from "./size.js";
12
+ import { checkFits, contextBudget, DEFAULT_REPLY_TOKENS, roomTokens, utf8Length, worstCaseTokens } from "./size.js";
12
13
  /**
13
14
  * The `claude-code` adapter runs the user's installed `claude` CLI once per request, headless and isolated,
14
15
  * as a pure completion: no tool but the schema tool, no settings file, MCP server, slash command or
@@ -935,6 +936,11 @@ async function requireVersion(launch, signal, fail) {
935
936
  * it continues after its limit, up to three times a turn, and its own retries: those count once the run
936
937
  * reports its usage.
937
938
  *
939
+ * It states the room its checks leave: the lesser of what its size guard leaves, from the same count, and what
940
+ * the stdin cap leaves, `MAX_STDIN_BYTES` less the message at one token per byte, which bounds the bytes the
941
+ * cap checks, so a request whose room is not negative passes both and text added to the message lowers the
942
+ * room by exactly its count.
943
+ *
938
944
  * @throws ConfigError with every problem of the options, before any request
939
945
  */
940
946
  export function claudeCode(options) {
@@ -959,6 +965,10 @@ export function claudeCode(options) {
959
965
  }, request.output, budget, structuredOutput === 'schema'
960
966
  ? 2
961
967
  : 1),
968
+ room: request => Math.min(roomTokens({
969
+ system: request.system,
970
+ messages: [...request.messages],
971
+ }, request.output, budget), MAX_STDIN_BYTES - tokenBound(request.messages[0]?.content ?? '')),
962
972
  async complete(request) {
963
973
  const fail = replyFailure(id);
964
974
  const message = messageOf(request, fail);
@@ -8,7 +8,8 @@ export type GeminiOptions = HttpProviderOptions;
8
8
  * refuses, before any request, a request that may not fit `contextTokens`. It sends the reply's limit,
9
9
  * `maxTokens` else the budget of the size guard, as `generationConfig.maxOutputTokens`, so the server bounds
10
10
  * a reply's length. It states its worst case from the count its size guard keeps: the text it sends, the
11
- * template reserve and that budget.
11
+ * template reserve and that budget, and the room its guard leaves from the same count: `contextTokens` less
12
+ * those three.
12
13
  *
13
14
  * @throws ConfigError with every problem of the options, before any request
14
15
  */
@@ -4,7 +4,7 @@ import { postJson, snippet } from "./http.js";
4
4
  import { shapeMessages } from "./messages.js";
5
5
  import { bodyKeyForm, isRecord, mergeBody, prepareHttp, spellingIssues } from "./options.js";
6
6
  import { endedEarly, joinedText, replyFailure, tokenUsage } from "./reply.js";
7
- import { checkFits, contextBudget, worstCaseTokens } from "./size.js";
7
+ import { checkFits, contextBudget, roomTokens, worstCaseTokens } from "./size.js";
8
8
  /** A Gemini model id, such as `gemini-3.8-flash`. It goes in the URL's path, so it holds no `/`, `?`, `#`, `%` or `:`. */
9
9
  const MODEL_ID = /^[a-z0-9][a-z0-9.-]*$/i;
10
10
  /** The longest block reason quoted, in characters: the pattern's bound and the quote's cut. */
@@ -172,7 +172,8 @@ function readReply(reply, { id, model }, redact) {
172
172
  * refuses, before any request, a request that may not fit `contextTokens`. It sends the reply's limit,
173
173
  * `maxTokens` else the budget of the size guard, as `generationConfig.maxOutputTokens`, so the server bounds
174
174
  * a reply's length. It states its worst case from the count its size guard keeps: the text it sends, the
175
- * template reserve and that budget.
175
+ * template reserve and that budget, and the room its guard leaves from the same count: `contextTokens` less
176
+ * those three.
176
177
  *
177
178
  * @throws ConfigError with every problem of the options, before any request
178
179
  */
@@ -198,6 +199,7 @@ export function gemini(options) {
198
199
  timeoutMs,
199
200
  retries,
200
201
  worstCase: request => worstCaseTokens(shapeMessages(request, systemPrompt), request.output, budget),
202
+ room: request => roomTokens(shapeMessages(request, systemPrompt), request.output, budget),
201
203
  async complete(request) {
202
204
  const { system, messages } = shapeMessages(request, systemPrompt);
203
205
  checkFits(id, { system, messages }, request.output, budget);
@@ -12,7 +12,8 @@ export type OllamaOptions = HttpProviderOptions;
12
12
  * loads the context the size guard counts with, and refuses, before any request, a request that may not
13
13
  * fit it. It sends the reply's limit, `maxTokens` else the budget of the size guard, as `options.num_predict`,
14
14
  * so the server bounds a reply's length. It states its worst case from the count its size guard keeps: the
15
- * text it sends, the template reserve and that budget.
15
+ * text it sends, the template reserve and that budget, and the room its guard leaves from the same count:
16
+ * `contextTokens` less those three.
16
17
  *
17
18
  * @throws ConfigError with every problem of the options, before any request
18
19
  */
@@ -4,7 +4,7 @@ import { postJson, snippet } from "./http.js";
4
4
  import { shapeMessages } from "./messages.js";
5
5
  import { bodyKeyForm, isRecord, mergeBody, prepareHttp, spellingIssues } from "./options.js";
6
6
  import { MAX_MODEL_TEXT, replyFailure, tokenUsage } from "./reply.js";
7
- import { checkFits, contextBudget, worstCaseTokens } from "./size.js";
7
+ import { checkFits, contextBudget, roomTokens, worstCaseTokens } from "./size.js";
8
8
  /**
9
9
  * The protocol's rules. The tool fields: `tools`, its only one, and `_debug_render_only`, which answers
10
10
  * 200 with the rendered template instead of a reply.
@@ -101,7 +101,8 @@ function readReply(reply, { id, model }, redact) {
101
101
  * loads the context the size guard counts with, and refuses, before any request, a request that may not
102
102
  * fit it. It sends the reply's limit, `maxTokens` else the budget of the size guard, as `options.num_predict`,
103
103
  * so the server bounds a reply's length. It states its worst case from the count its size guard keeps: the
104
- * text it sends, the template reserve and that budget.
104
+ * text it sends, the template reserve and that budget, and the room its guard leaves from the same count:
105
+ * `contextTokens` less those three.
105
106
  *
106
107
  * @throws ConfigError with every problem of the options, before any request
107
108
  */
@@ -115,6 +116,7 @@ export function ollama(options) {
115
116
  timeoutMs,
116
117
  retries,
117
118
  worstCase: request => worstCaseTokens(shapeMessages(request, systemPrompt), request.output, budget),
119
+ room: request => roomTokens(shapeMessages(request, systemPrompt), request.output, budget),
118
120
  async complete(request) {
119
121
  const { system, messages } = shapeMessages(request, systemPrompt);
120
122
  checkFits(id, { system, messages }, request.output, budget);
@@ -10,7 +10,8 @@ export interface OpenAICompatibleOptions extends HttpProviderOptions {
10
10
  * only in the header `auth` names, `Authorization: Bearer` by default (invariant I1). It refuses, before
11
11
  * any request, a request that may not fit `contextTokens`. It sends the reply's limit, `maxTokens` else the
12
12
  * budget of the size guard, under `maxTokensField`, so the server bounds a reply's length. It states its
13
- * worst case from the count its size guard keeps: the text it sends, the template reserve and that budget.
13
+ * worst case from the count its size guard keeps: the text it sends, the template reserve and that budget,
14
+ * and the room its guard leaves from the same count: `contextTokens` less those three.
14
15
  *
15
16
  * @throws ConfigError with every problem of the options, before any request
16
17
  */
@@ -3,7 +3,7 @@ import { postJson, snippet } from "./http.js";
3
3
  import { shapeMessages } from "./messages.js";
4
4
  import { isRecord, mergeBody, prepareHttp } from "./options.js";
5
5
  import { endedEarly, joinedText, MAX_MODEL_TEXT, replyFailure, tokenUsage } from "./reply.js";
6
- import { checkFits, contextBudget, worstCaseTokens } from "./size.js";
6
+ import { checkFits, contextBudget, roomTokens, worstCaseTokens } from "./size.js";
7
7
  /**
8
8
  * The protocol's rules. The tool fields are the union over the OpenAI-compatible vendors: OpenAI's and
9
9
  * the others' function tools and web search, OpenRouter's plugins, server-tool loop, presets and model
@@ -148,7 +148,8 @@ function readReply(reply, { id, model }, redact) {
148
148
  * only in the header `auth` names, `Authorization: Bearer` by default (invariant I1). It refuses, before
149
149
  * any request, a request that may not fit `contextTokens`. It sends the reply's limit, `maxTokens` else the
150
150
  * budget of the size guard, under `maxTokensField`, so the server bounds a reply's length. It states its
151
- * worst case from the count its size guard keeps: the text it sends, the template reserve and that budget.
151
+ * worst case from the count its size guard keeps: the text it sends, the template reserve and that budget,
152
+ * and the room its guard leaves from the same count: `contextTokens` less those three.
152
153
  *
153
154
  * @throws ConfigError with every problem of the options, before any request
154
155
  */
@@ -167,6 +168,7 @@ export function openaiCompatible(options) {
167
168
  timeoutMs,
168
169
  retries,
169
170
  worstCase: request => worstCaseTokens(shapeMessages(request, systemPrompt), request.output, budget),
171
+ room: request => roomTokens(shapeMessages(request, systemPrompt), request.output, budget),
170
172
  async complete(request) {
171
173
  const { system, messages } = shapeMessages(request, systemPrompt);
172
174
  checkFits(id, { system, messages }, request.output, budget);
@@ -34,11 +34,19 @@ export declare function textTokens(shaped: ShapedMessages, output: CompletionReq
34
34
  * One turn is the text, the template reserve and the reply budget, which `checkFits` keeps within the context.
35
35
  */
36
36
  export declare function worstCaseTokens(shaped: ShapedMessages, output: CompletionRequest['output'], budget: ContextBudget, turns?: number): number;
37
+ /**
38
+ * How many more tokens of text a request could hold and still fit the model's context, from what the guard
39
+ * counts: the context less the text, the budget's template reserve (`TEMPLATE_TOKENS` unless it names one)
40
+ * and the reply budget. It is negative exactly when the request does not fit, and `checkFits` reads the same
41
+ * count, so the guard and the room an adapter states never drift: a request at a room of 0 is sent, one at -1
42
+ * is refused.
43
+ */
44
+ export declare function roomTokens(shaped: ShapedMessages, output: CompletionRequest['output'], budget: ContextBudget): number;
37
45
  /**
38
46
  * Refuse, before it is sent, a request that may not fit the model's context: some endpoints cut an oversized
39
47
  * prompt in silence and answer 200, which would leave a review of text the model never read. The request
40
48
  * fits only when its text, the budget's template reserve (`TEMPLATE_TOKENS` unless it names one) and the
41
- * reply budget together stay within `contextTokens`.
49
+ * reply budget together stay within `contextTokens`, which is when its room is not negative.
42
50
  * The message holds the provider id and numbers, never the text.
43
51
  *
44
52
  * @throws ProviderError of kind `too-large`, which is not retryable
@@ -39,19 +39,33 @@ export function worstCaseTokens(shaped, output, budget, turns = 1) {
39
39
  const template = budget.templateTokens ?? TEMPLATE_TOKENS;
40
40
  return turns * (textTokens(shaped, output) + template) + (2 * turns - 1) * budget.replyTokens;
41
41
  }
42
+ /** What a request needs of its context: the tokens of its text, the template reserve, the reply budget, and their sum. */
43
+ function neededOf(shaped, output, budget) {
44
+ const text = textTokens(shaped, output);
45
+ const template = budget.templateTokens ?? TEMPLATE_TOKENS;
46
+ return { text, template, need: text + template + budget.replyTokens };
47
+ }
48
+ /**
49
+ * How many more tokens of text a request could hold and still fit the model's context, from what the guard
50
+ * counts: the context less the text, the budget's template reserve (`TEMPLATE_TOKENS` unless it names one)
51
+ * and the reply budget. It is negative exactly when the request does not fit, and `checkFits` reads the same
52
+ * count, so the guard and the room an adapter states never drift: a request at a room of 0 is sent, one at -1
53
+ * is refused.
54
+ */
55
+ export function roomTokens(shaped, output, budget) {
56
+ return budget.contextTokens - neededOf(shaped, output, budget).need;
57
+ }
42
58
  /**
43
59
  * Refuse, before it is sent, a request that may not fit the model's context: some endpoints cut an oversized
44
60
  * prompt in silence and answer 200, which would leave a review of text the model never read. The request
45
61
  * fits only when its text, the budget's template reserve (`TEMPLATE_TOKENS` unless it names one) and the
46
- * reply budget together stay within `contextTokens`.
62
+ * reply budget together stay within `contextTokens`, which is when its room is not negative.
47
63
  * The message holds the provider id and numbers, never the text.
48
64
  *
49
65
  * @throws ProviderError of kind `too-large`, which is not retryable
50
66
  */
51
67
  export function checkFits(providerId, shaped, output, budget) {
52
- const text = textTokens(shaped, output);
53
- const template = budget.templateTokens ?? TEMPLATE_TOKENS;
54
- const need = text + template + budget.replyTokens;
68
+ const { text, template, need } = neededOf(shaped, output, budget);
55
69
  if (need <= budget.contextTokens)
56
70
  return;
57
71
  throw new ProviderError({
@@ -0,0 +1,49 @@
1
+ /**
2
+ * The all-added writer: files that have no diff of their own (a path review's, the untracked files of a
3
+ * local review) written as git writes a new file, so the core reads them as it reads any diff. The form
4
+ * is git's new-file form less its `index` line, with each name quoted as git quotes it, and a file cut
5
+ * into hunks of at most `HUNK_BYTES` at line ends, so research in parts spreads a large file across
6
+ * parts. It is a reading form and not a patch: `git apply` refuses a new file cut in several hunks.
7
+ *
8
+ * @see ../../docs/95-reference/40-architecture.md for where it sits in the layers.
9
+ */
10
+ /** The most bytes of rows a hunk holds, line feeds included, a longer line aside, which goes alone in its hunk. */
11
+ export declare const HUNK_BYTES = 4096;
12
+ /** How many leading bytes git looks at for a NUL to call a file binary. */
13
+ export declare const BINARY_PROBE_BYTES = 8000;
14
+ /** The modes git gives a new file: a file, an executable, a link and a gitlink (a submodule's commit). */
15
+ export type AddedMode = '100644' | '100755' | '120000' | '160000';
16
+ /** One file to write. */
17
+ export interface AddedFile {
18
+ /** The path as git names it: bytes, not text, since a name can hold any byte but NUL. */
19
+ readonly path: Uint8Array;
20
+ readonly mode: AddedMode;
21
+ /** The file's bytes, or a link's target; empty for a gitlink, which holds another repository's commit. */
22
+ readonly content: Uint8Array;
23
+ }
24
+ /**
25
+ * The inside of git's quoting of a name, as `core.quotePath=true` writes it: `\a \b \t \n \v \f \r \" \\`
26
+ * for those nine bytes and three octal digits for every other byte below 0x20 and from 0x7F up.
27
+ * `undefined` when git writes the name as it is.
28
+ */
29
+ export declare function quotedPath(raw: Uint8Array): string | undefined;
30
+ /**
31
+ * The name `diffSections` reads back from the header this writer writes for `raw`: the name itself when
32
+ * git writes it as it is, else `decodeQuoted`, the core's own reading of git's quoted names, of its
33
+ * quoting, so writer and reader cannot drift.
34
+ */
35
+ export declare function pathName(raw: Uint8Array): string;
36
+ /** Whether git would call `content` binary: a NUL among its first `BINARY_PROBE_BYTES` bytes. */
37
+ export declare function isBinary(content: Uint8Array): boolean;
38
+ /** The text of a blob: a byte that is not UTF-8 becomes U+FFFD, as `decodeDiff` makes it of git's own output, and a leading byte-order mark stays. */
39
+ export declare function blobText(content: Uint8Array): string;
40
+ /**
41
+ * One file as git's new-file diff less its `index` line, with no final line feed: the header, the mode,
42
+ * then `--- /dev/null`, `+++` and the hunks, or git's binary line for a file with a NUL among its first
43
+ * 8000 bytes, or nothing more for an empty file and a gitlink. The `+++` line ends with a tab when its
44
+ * label holds a space, as git writes it, and a last line with no line feed is followed by git's
45
+ * ``.
46
+ */
47
+ export declare function addedSection(file: AddedFile): string;
48
+ /** The sections of `files`, joined by line feeds and ending with one: `''` for no file. */
49
+ export declare function addedDiff(files: readonly AddedFile[]): string;