@jjanczur/tyran 0.1.25 → 0.1.27

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.
package/scripts/tiers.mjs CHANGED
@@ -36,6 +36,8 @@ import { fileURLToPath } from 'node:url';
36
36
  import { parse } from './yaml-lite.mjs';
37
37
  import { validateConfig, PROFILES, TIER_KEYS } from './schema.mjs';
38
38
  import { escapeInvisible } from './invisible.mjs';
39
+ import { APPROVING_RE } from './project.mjs';
40
+ import { readJournal } from './journal.mjs';
39
41
 
40
42
  /** Capability tiers, cheapest first. Index order is the escalation ladder. */
41
43
  export const TIER_ORDER = TIER_KEYS;
@@ -117,6 +119,52 @@ export const ROLE_FLOOR = Object.freeze({
117
119
 
118
120
  export const ROLES = Object.freeze(Object.keys(ROLE_TIERS));
119
121
 
122
+ /**
123
+ * The tier a fallback or an escalation may never pass.
124
+ *
125
+ * `top` is the most expensive thing Tyran can spend, and an automatic climb to
126
+ * it is a decision about money made while nobody is watching. Roles whose
127
+ * FLOOR is already `top` still resolve there — this bounds what escalation
128
+ * ADDS, not what the table asks for.
129
+ */
130
+ export const ESCALATION_CEILING = 'deep';
131
+
132
+ /** How many steps repeated failure may add, however many attempts there were. */
133
+ export const MAX_ESCALATION_STEPS = 2;
134
+
135
+ /**
136
+ * What the journal says about a ticket that is being re-tried.
137
+ *
138
+ * Both facts live in the ledger rather than in the conductor's memory, which
139
+ * iron rule 7 already names the least reliable store in the system: a session
140
+ * that compacts, or a second conductor picking the work up, otherwise re-spawns
141
+ * at the tier that has already failed twice and on the model that has already
142
+ * run out.
143
+ *
144
+ * - `attempts` counts reviews that did NOT approve. The regex is the board's
145
+ * own, imported, because "did this attempt fail" must not have two answers.
146
+ * - `unavailable` collects models an `error` event named as out of capacity.
147
+ * The convention is `{class: 'model-unavailable', model: '<alias>'}` and it
148
+ * is a convention on purpose: the failure surfaces inside a subagent's API
149
+ * call, where no hook can see it, so SOMETHING has to write it down before
150
+ * routing can act on it.
151
+ */
152
+ export function ticketHistory(events, ticket) {
153
+ const id = String(ticket);
154
+ let attempts = 0;
155
+ const unavailable = [];
156
+ for (const e of events) {
157
+ if (e?.ev === 'review' && String(e.data?.ticket) === id && !APPROVING_RE.test(String(e.data?.verdict ?? ''))) {
158
+ attempts += 1;
159
+ }
160
+ if (e?.ev === 'error' && e.data?.class === 'model-unavailable' && typeof e.data?.model === 'string') {
161
+ // NOT scoped to the ticket: a model that ran out is out for everything.
162
+ if (!unavailable.includes(e.data.model)) unavailable.push(e.data.model);
163
+ }
164
+ }
165
+ return { attempts, unavailable };
166
+ }
167
+
120
168
  function validateInputs(role, profile, risk) {
121
169
  if (!Object.hasOwn(ROLE_TIERS, role)) {
122
170
  throw new Error(`unknown role "${escapeInvisible(role)}" (known: ${ROLES.join(', ')})`);
@@ -208,14 +256,99 @@ function clamp(value, min, max) {
208
256
  export function resolveModel(config, role, profile, risk = 'normal', override = {}) {
209
257
  const tier = resolveTier(role, profile, risk, override);
210
258
  const effort = resolveEffort(role, profile, risk, override);
211
- const alias = config?.tiers?.[tier];
212
- if (typeof alias !== 'string' || alias.length === 0) {
213
- throw new Error(`config has no model alias for tier "${tier}" — fix tiers in .tyran/config.yaml`);
214
- }
259
+ const aliasFor = (key) => {
260
+ const alias = config?.tiers?.[key];
261
+ if (typeof alias !== 'string' || alias.length === 0) {
262
+ throw new Error(`config has no model alias for tier "${key}" — fix tiers in .tyran/config.yaml`);
263
+ }
264
+ return alias;
265
+ };
215
266
  const floored =
216
267
  (ROLE_FLOOR[role] !== undefined && override.tier !== undefined && override.tier !== ROLE_FLOOR[role]) ||
217
268
  (ROLE_EFFORT_FLOOR[role] !== undefined && override.effort !== undefined && override.effort !== effort);
218
- return { tier, model: alias, effort, floored };
269
+
270
+ const unavailable = normalizeUnavailable(override.unavailable);
271
+ // Escalation first, fallback second, and the order matters: a re-try should
272
+ // ask for a stronger model, and only then discover whether that model is
273
+ // available. Doing it the other way round would fall back from a tier the
274
+ // run was never going to use.
275
+ const attempts = Number.isInteger(override.attempts) && override.attempts > 0 ? override.attempts : 0;
276
+ const climbed = attempts === 0 ? tier : escalateTier(tier, attempts);
277
+ const resolved = {
278
+ tier: climbed,
279
+ model: aliasFor(climbed),
280
+ effort,
281
+ floored,
282
+ fell_from: null,
283
+ escalated_from: climbed === tier ? null : tier,
284
+ attempts,
285
+ };
286
+ if (unavailable.length === 0 || !unavailable.includes(resolved.model)) return resolved;
287
+
288
+ const substitute = fallbackTier(config, role, resolved.tier, unavailable);
289
+ return {
290
+ ...resolved,
291
+ tier: substitute,
292
+ model: aliasFor(substitute),
293
+ // Effort follows the ORIGINAL tier, not the substitute. The judgement
294
+ // "this task needs deep reasoning" did not change because a model ran out
295
+ // of capacity, and dropping both dials at once turns a substitution into a
296
+ // second, unasked-for downgrade.
297
+ fell_from: resolved.tier,
298
+ };
299
+ }
300
+
301
+ /**
302
+ * One step up per failed attempt, capped twice over: by MAX_ESCALATION_STEPS,
303
+ * and by the ceiling. A ticket that has failed four times does not need the
304
+ * most expensive model in the table — it needs a human, and the board's
305
+ * changes-requested lane is where that is already visible.
306
+ */
307
+ function escalateTier(from, attempts) {
308
+ const ceiling = Math.min(TIER_ORDER.indexOf(ESCALATION_CEILING), TIER_ORDER.length - 1);
309
+ const start = TIER_ORDER.indexOf(from);
310
+ // Never lower a role that already resolves above the ceiling.
311
+ if (start >= ceiling) return from;
312
+ return TIER_ORDER[Math.min(start + Math.min(attempts, MAX_ESCALATION_STEPS), ceiling)];
313
+ }
314
+
315
+ function normalizeUnavailable(value) {
316
+ if (value === undefined || value === null) return [];
317
+ const list = Array.isArray(value) ? value : [value];
318
+ return list.filter((v) => typeof v === 'string' && v.length > 0);
319
+ }
320
+
321
+ /**
322
+ * The next tier DOWN whose model is still available.
323
+ *
324
+ * Down, never up, and that is the answer to the question this feature was
325
+ * blocked on. A fallback that climbed would spend more than the routing table
326
+ * promised, silently, at the exact moment nobody is watching — and the whole
327
+ * point of the table is that what a run costs is legible before it runs. Down
328
+ * is also the direction the observed incident needed: the strongest tier hit
329
+ * its limit while the tier below it had capacity, and the work died rather
330
+ * than finishing on the model one step cheaper.
331
+ *
332
+ * The trade is stated rather than hidden: falling produces a WEAKER answer.
333
+ * That is why it stops at the role floor instead of walking to the bottom —
334
+ * a security review that ran on the cheapest model is not a security review,
335
+ * and the floors already say which roles those are.
336
+ */
337
+ export function fallbackTier(config, role, from, unavailable) {
338
+ const floorIndex = ROLE_FLOOR[role] === undefined ? 0 : TIER_ORDER.indexOf(ROLE_FLOOR[role]);
339
+ for (let i = TIER_ORDER.indexOf(from) - 1; i >= floorIndex; i -= 1) {
340
+ const alias = config?.tiers?.[TIER_ORDER[i]];
341
+ if (typeof alias === 'string' && alias.length > 0 && !unavailable.includes(alias)) return TIER_ORDER[i];
342
+ }
343
+ // Exhausting the ladder is NOT a substitution problem. Every model this role
344
+ // is allowed to use is unavailable, which means waiting, not routing — and
345
+ // the thing that already knows how to wait is overnight mode.
346
+ const reachable = TIER_ORDER.slice(floorIndex, TIER_ORDER.indexOf(from) + 1);
347
+ throw new Error(
348
+ `every tier "${escapeInvisible(role)}" may use is unavailable (${reachable.join(' -> ')}), so there is ` +
349
+ 'nothing to fall back to. This is a pause, not a substitution: see docs/overnight.md.' +
350
+ (ROLE_FLOOR[role] === undefined ? '' : ` The floor for this role is "${ROLE_FLOOR[role]}" and is not lowered by a fallback.`),
351
+ );
219
352
  }
220
353
 
221
354
  /** The whole routing map for one profile — what the conductor reads once. */
@@ -278,7 +411,30 @@ function main() {
278
411
  const risk = flag('risk', 'normal');
279
412
  const role = flag('role', null);
280
413
  const field = flag('field', 'model');
281
- const override = { tier: flag('tier', undefined), effort: flag('effort', undefined) };
414
+ // Repeatable: an overnight run can exhaust more than one tier.
415
+ const unavailable = args.reduce((acc, arg, i) => (arg === '--unavailable' && args[i + 1] ? [...acc, args[i + 1]] : acc), []);
416
+ // The ledger, not the conductor's memory. `--journal <path> --ticket T-n`
417
+ // counts the failed attempts on that ticket and picks up any model an error
418
+ // event has recorded as out of capacity, so a re-spawn after a compaction
419
+ // routes the same way a re-spawn before it would have.
420
+ const journalPath = flag('journal', null);
421
+ const ticket = flag('ticket', null);
422
+ let history = { attempts: 0, unavailable: [] };
423
+ if (journalPath !== null && ticket !== null) {
424
+ try {
425
+ history = ticketHistory(readJournal(resolve(journalPath)).events, ticket);
426
+ } catch (error) {
427
+ // Routing must not depend on a readable journal: a missing or damaged
428
+ // one means no history, which is the same answer as a first attempt.
429
+ console.error(`tiers: could not read ${escapeInvisible(journalPath)} (${error.message}) — routing without history`);
430
+ }
431
+ }
432
+ const override = {
433
+ tier: flag('tier', undefined),
434
+ effort: flag('effort', undefined),
435
+ unavailable: [...unavailable, ...history.unavailable],
436
+ attempts: history.attempts,
437
+ };
282
438
 
283
439
  try {
284
440
  if (role === null) {
@@ -303,6 +459,25 @@ function main() {
303
459
  'change its model mid-flight — this is the tier your config says it should be running.',
304
460
  );
305
461
  }
462
+ // A substitution that said nothing would be the routing table quietly
463
+ // meaning something else than it says.
464
+ if (resolved.escalated_from) {
465
+ // The tier the CLIMB reached, which is what a fallback then fell FROM.
466
+ // Reporting `resolved.tier` here narrated "work -> work" whenever both
467
+ // happened, which is the one case where a reader most needs the two
468
+ // steps told apart.
469
+ const climbedTo = resolved.fell_from ?? resolved.tier;
470
+ console.error(
471
+ `tiers: ESCALATED ${resolved.escalated_from} -> ${climbedTo} after ${resolved.attempts} failed attempt(s) ` +
472
+ `on ${escapeInvisible(String(ticket))} (ceiling ${ESCALATION_CEILING}).`,
473
+ );
474
+ }
475
+ if (resolved.fell_from !== null) {
476
+ console.error(
477
+ `tiers: FELL BACK ${resolved.fell_from} -> ${resolved.tier} because the ${resolved.fell_from} model is ` +
478
+ 'unavailable. This is a WEAKER model than the routing table asked for; effort is unchanged.',
479
+ );
480
+ }
306
481
  console.error(`tiers: ${role} @ ${profile}/${risk} -> ${resolved.tier} · effort ${resolved.effort}`);
307
482
  if (field === 'json') console.log(JSON.stringify(resolved));
308
483
  else if (Object.hasOwn(resolved, field)) console.log(resolved[field]);
@@ -174,7 +174,11 @@ function stripComment(line, lineNo) {
174
174
 
175
175
  /** Parse a YAML-subset document into a plain JS object. */
176
176
  export function parse(text) {
177
- const rawLines = text.split('\n');
177
+ // A leading BOM is an encoding marker, not content. Left in place it becomes
178
+ // one column of "indentation" on line 1, and the parser rejected the whole
179
+ // file with "indentation must be a multiple of 2 spaces" — pointing at a
180
+ // line the operator can see nothing wrong with.
181
+ const rawLines = (text.charCodeAt(0) === 0xfeff ? text.slice(1) : text).split('\n');
178
182
  const lines = [];
179
183
  let sawDocStart = false;
180
184
  rawLines.forEach((raw, i) => {
@@ -272,7 +276,16 @@ export function parse(text) {
272
276
  return result;
273
277
  }
274
278
 
275
- function keyColonIndex(text) {
279
+ /**
280
+ * Where a mapping key ends, by this subset's own rule: the colon must be
281
+ * followed by whitespace or end-of-line.
282
+ *
283
+ * Exported for the same reason as `splitInlineComment` and `formatScalar` — an
284
+ * editor that locates a key must locate it by the rule the PARSER uses. A bare
285
+ * `indexOf(':')` finds the colon inside `a:b: 1` and lands the edit on a
286
+ * different key's line, which is a wrong write, not a failed one.
287
+ */
288
+ export function keyColonIndex(text) {
276
289
  let inSingle = false;
277
290
  let inDouble = false;
278
291
  for (let i = 0; i < text.length; i++) {
@@ -286,7 +299,8 @@ function keyColonIndex(text) {
286
299
  return -1;
287
300
  }
288
301
 
289
- function unquoteKey(raw, lineNo) {
302
+ /** A key as the parser reads it, quotes and all. Exported alongside `keyColonIndex`. */
303
+ export function unquoteKey(raw, lineNo) {
290
304
  const key = raw.trim();
291
305
  if (key === '') throw new YamlLiteError('empty key', lineNo);
292
306
  if ((key[0] === '"' && key.at(-1) === '"' && key.length > 1) ||
@@ -422,6 +436,12 @@ export function formatScalar(value) {
422
436
  Object.hasOwn(BOOL, s.toLowerCase()) ||
423
437
  s === 'null' ||
424
438
  s === '~' ||
425
- /^-?\d+(\.\d+)?$/.test(s);
439
+ // The READER's two number tests, not an approximation of them. They
440
+ // disagreed on a leading-dot decimal: `parseScalar` reads `.5` as the
441
+ // number 0.5, while this rule required a digit before the dot and so
442
+ // wrote the STRING ".5" unquoted — a value that came back as a different
443
+ // type. Found by yaml-patch's round-trip proof, which is what it is for.
444
+ /^-?\d+$/.test(s) ||
445
+ /^-?\d*\.\d+$/.test(s);
426
446
  return needsQuotes ? `'${s.replace(/'/g, "''")}'` : s;
427
447
  }
@@ -37,7 +37,7 @@
37
37
  * refused instead, with the line number, because the alternative is the
38
38
  * silent loss this whole module exists to prevent.
39
39
  */
40
- import { YamlLiteError, formatScalar, parse, splitInlineComment } from './yaml-lite.mjs';
40
+ import { YamlLiteError, formatScalar, keyColonIndex, parse, splitInlineComment, unquoteKey } from './yaml-lite.mjs';
41
41
 
42
42
  export class YamlPatchError extends Error {}
43
43
 
@@ -181,9 +181,18 @@ function locate(lines, path) {
181
181
  for (let i = from; i < to; i += 1) {
182
182
  const line = asKeyLine(lines[i], dashIndent, indent);
183
183
  if (line.blank || line.indent !== indent) continue;
184
- const colon = line.trimmed.indexOf(':');
184
+ // The PARSER's key rule, not a bare indexOf: a colon inside a key name
185
+ // (`a:b: 1`) otherwise ends the key early, and the edit lands on a
186
+ // different key's line — a wrong write rather than a failed one.
187
+ const colon = keyColonIndex(line.trimmed);
185
188
  if (colon === -1) continue;
186
- if (line.trimmed.slice(0, colon).trim().replace(/^['"]|['"]$/g, '') !== segment) continue;
189
+ let key;
190
+ try {
191
+ key = unquoteKey(line.trimmed.slice(0, colon), line.i + 1);
192
+ } catch {
193
+ continue;
194
+ }
195
+ if (key !== segment) continue;
187
196
  hit = i;
188
197
  view = line;
189
198
  break;
@@ -205,11 +214,15 @@ function locate(lines, path) {
205
214
  /**
206
215
  * Deep structural equality over the plain data yaml-lite produces.
207
216
  *
208
- * Exported so the proof at the end of `patch()` can be tested directly. It is
209
- * defence in depth with no input known to reach it — every wrong case found so
210
- * far is refused earlier, by the locator, by the comment guard, or by
211
- * `formatScalar` — so a test that goes through `patch()` cannot make it fire,
212
- * and this is the mutable logic the guarantee actually rests on.
217
+ * Exported so the proof at the end of `patch()` can be tested directly, and
218
+ * because it is the mutable logic the guarantee rests on.
219
+ *
220
+ * It is NOT unreachable, and an earlier version of this comment said it was.
221
+ * A review found the case: `formatScalar` used a stricter number pattern than
222
+ * `parseScalar`, so the string ".5" was written unquoted and read back as the
223
+ * number 0.5 — a changed type, caught here and nowhere else. That specific
224
+ * disagreement is fixed in yaml-lite, which is the right place for it; this
225
+ * check is what noticed.
213
226
  */
214
227
  export function sameValue(a, b) {
215
228
  if (a === b) return true;
@@ -242,9 +255,16 @@ function writeAt(doc, path, value) {
242
255
  /** Rewrite the value on a `key: value` line, keeping indent, comment and ending. */
243
256
  function scalarLine(line, target, value) {
244
257
  const body = target.dash ? line.trimmed.slice(2).trim() : line.trimmed;
245
- const colon = body.indexOf(':');
246
- const head = `${' '.repeat(line.indent)}${target.dash ? '- ' : ''}${body.slice(0, colon + 1)}`;
258
+ const colon = keyColonIndex(body);
247
259
  const tail = line.comment === '' ? '' : ` ${line.comment}`;
260
+ // A plain sequence item (`- npm test`) is a value with no key at all, which
261
+ // an address ending in an integer reaches. Treating it like a mapping line
262
+ // dropped the dash and shifted the indent by one, and the round-trip proof
263
+ // then blamed a NEIGHBOURING line for the indentation it had broken.
264
+ if (colon === -1) {
265
+ return `${' '.repeat(line.indent)}- ${formatScalar(value)}${tail}${line.eol}`;
266
+ }
267
+ const head = `${' '.repeat(line.indent)}${target.dash ? '- ' : ''}${body.slice(0, colon + 1)}`;
248
268
  return `${head} ${formatScalar(value)}${tail}${line.eol}`;
249
269
  }
250
270
 
@@ -256,6 +276,14 @@ function scalarLine(line, target, value) {
256
276
  * parse back to exactly the document intended.
257
277
  */
258
278
  export function patch(text, path, value) {
279
+ // A BOM is an encoding marker, not content — and `trimStart` counts it as
280
+ // whitespace, so it read as one column of indentation and the rebuilt line
281
+ // replaced it with a SPACE, producing an odd indent the parser then refused.
282
+ // Split it off here and put it back on the result, so the file keeps the
283
+ // marker it came with and nothing downstream has to know about it.
284
+ const bom = text.charCodeAt(0) === 0xfeff ? text.slice(0, 1) : '';
285
+ if (bom !== '') return bom + patch(text.slice(1), path, value);
286
+
259
287
  let before;
260
288
  try {
261
289
  before = parse(text);
@@ -300,12 +328,17 @@ function edit(text, path, value, before) {
300
328
  const body = target.dash ? line.trimmed.slice(2).trim() : line.trimmed;
301
329
  const colon = body.indexOf(':');
302
330
  const inlineValue = body.slice(colon + 1).trim();
303
- const end = inlineValue === '' ? blockEnd(lines, target.line + 1, line.indent) : target.line + 1;
331
+ // The block boundary is the KEY's indent, not the line's. On the first key
332
+ // of a sequence item (`- tags:`) the line is indented at the DASH, so
333
+ // using it ran the block to the end of the whole item and the splice took
334
+ // the item's sibling keys out with the list.
335
+ const ownIndent = target.dash ? target.keyIndent : line.indent;
336
+ const end = inlineValue === '' ? blockEnd(lines, target.line + 1, ownIndent) : target.line + 1;
304
337
  // The items' indent is the one they already have; a list with none yet
305
338
  // (`shared_zones: []`) takes the step the rest of the document uses.
306
- const discovered = childIndentOf(lines, target.line + 1, end, line.indent);
339
+ const discovered = childIndentOf(lines, target.line + 1, end, ownIndent);
307
340
  const childIndent = discovered === -1
308
- ? line.indent + documentStep(lines, first === undefined ? 0 : first.indent)
341
+ ? ownIndent + documentStep(lines, first === undefined ? 0 : first.indent)
309
342
  : discovered;
310
343
  // Rewriting the block rewrites its lines, so a comment living among the
311
344
  // items would disappear. Refusing keeps the promise this module is for.