@yaag/runtime 0.17.0 → 0.18.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yaag/runtime",
3
- "version": "0.17.0",
3
+ "version": "0.18.1",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -3,6 +3,8 @@
3
3
  * Files inside this directory import each other directly.
4
4
  */
5
5
  export { Agent } from "./agent.ts";
6
+ // Frame reader, exported for the ADR-0051 Frame Shape drift guard.
7
+ export { AgentUsage, type AgentUsageSnapshot } from "./agent-usage.ts";
6
8
  export {
7
9
  type AgentConfig,
8
10
  type AgentDefinition,
package/src/ask/index.ts CHANGED
@@ -2,7 +2,11 @@
2
2
  * Public surface of the `ask/` module: the live Ask exchange.
3
3
  * Files inside this directory import each other directly.
4
4
  */
5
+ // Frame readers, exported for the ADR-0051 Frame Shape drift guard.
6
+ export { AskActivityTracker } from "./ask-activity.ts";
5
7
  export { exchangeAsk } from "./ask-exchange.ts";
6
8
  export type { AskModelFallback } from "./ask-exchange-options.ts";
7
9
  export { askHash, askMarkerContext, type EffectiveAskOptions } from "./ask-hash.ts";
10
+ export { AskOutputTail } from "./ask-output-tail.ts";
11
+ export { AskTurn } from "./ask-turn.ts";
8
12
  export type { SettlementCause } from "./stall-watchdog.ts";
@@ -0,0 +1,62 @@
1
+ import type { Frame } from "../transport/index.ts";
2
+
3
+ /**
4
+ * Reduces one received frame to its Frame Shape: the subset a Cassette keeps
5
+ * (ADR-0051).
6
+ *
7
+ * The rule, not a list: a field stays when a reader in this package reads it
8
+ * during replay, and goes when pi only echoes it. The readers are
9
+ * `agent-usage` (`message_end.message.usage`), `ask-turn` (`message_end`,
10
+ * `agent_settled`), `report-result` and `node-tracker` (`tool_execution_*`
11
+ * names, `args`, `details`, `isError`), `ask-activity` and `ask-output-tail`
12
+ * (`message_update.assistantMessageEvent`), and `CassetteReplay` (`response`
13
+ * frames). `cassette-frame-shape.test.ts` guards that a shaped frame drives
14
+ * each of them to the same output as the live frame did.
15
+ *
16
+ * A new reader that needs a dropped field extends this function; a Cassette
17
+ * recorded before that lacks the field, and the reader must tolerate it.
18
+ */
19
+ export function shapeFrame(frame: Frame): Frame {
20
+ switch (frame.type) {
21
+ case "agent_end":
22
+ // The full transcript; every message already arrived as `message_end`.
23
+ return without(frame, "messages");
24
+ case "turn_end":
25
+ // A copy of the assistant `message_end` that preceded it.
26
+ return without(frame, "message");
27
+ case "message_start":
28
+ // The user prompt is the `prompt` frame in `sentFrames`.
29
+ return isUserMessage(frame.message) ? without(frame, "message") : frame;
30
+ case "message_update":
31
+ // Running usage per delta; the final usage rides on `message_end`.
32
+ return without(frame, "usage");
33
+ case "tool_execution_update":
34
+ // `args` repeat `tool_execution_start`; `content` is a partial of `_end.result`.
35
+ return shapeToolUpdate(frame);
36
+ default:
37
+ return frame;
38
+ }
39
+ }
40
+
41
+ function shapeToolUpdate(frame: Frame): Frame {
42
+ const stripped = without(frame, "args");
43
+ const partial = stripped.partialResult;
44
+ if (!isRecord(partial) || !("content" in partial)) return stripped;
45
+ return { ...stripped, partialResult: without(partial, "content") };
46
+ }
47
+
48
+ /** A frame with one key removed; `type` is never the key, so the result is still a Frame. */
49
+ function without<T extends Readonly<Record<string, unknown>>>(value: T, key: string): T;
50
+ function without(value: Readonly<Record<string, unknown>>, key: string): Record<string, unknown> {
51
+ if (!(key in value)) return value;
52
+ const { [key]: _dropped, ...rest } = value;
53
+ return rest;
54
+ }
55
+
56
+ function isUserMessage(message: unknown): boolean {
57
+ return isRecord(message) && message.role === "user";
58
+ }
59
+
60
+ function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
61
+ return typeof value === "object" && value !== null && !Array.isArray(value);
62
+ }
@@ -17,17 +17,19 @@ import { CassetteSchema } from "./cassette-schema.ts";
17
17
  * schema checks structure; the five named invariants below check semantics.
18
18
  * A version 1 artifact is upgraded in memory to version 2 (ADR-0021).
19
19
  * Unknown fields are retained, never dropped (forward tolerance).
20
+ * The bytes are gzip-compressed JSON, or the plain JSON that older runtimes
21
+ * wrote; the gzip magic bytes decide, never the file name (ADR-0051).
20
22
  */
21
23
  export async function loadCassette(path: string): Promise<Cassette> {
22
- let text: string;
24
+ let bytes: Uint8Array<ArrayBuffer>;
23
25
  try {
24
- text = await Bun.file(path).text();
26
+ bytes = await Bun.file(path).bytes();
25
27
  } catch (error) {
26
28
  throw new Error(`cannot read cassette "${path}": ${String(error)}`, { cause: error });
27
29
  }
28
30
  let value: unknown;
29
31
  try {
30
- value = JSON.parse(text);
32
+ value = JSON.parse(decodeCassetteBytes(bytes));
31
33
  } catch (error) {
32
34
  throw new Error(`cannot parse cassette "${path}": ${String(error)}`, { cause: error });
33
35
  }
@@ -47,6 +49,16 @@ export async function loadCassette(path: string): Promise<Cassette> {
47
49
  return upgrade(artifact);
48
50
  }
49
51
 
52
+ /** Inflates a gzip artifact; passes plain JSON text through. */
53
+ function decodeCassetteBytes(bytes: Uint8Array<ArrayBuffer>): string {
54
+ return new TextDecoder().decode(isGzip(bytes) ? Bun.gunzipSync(bytes) : bytes);
55
+ }
56
+
57
+ /** The gzip file signature (RFC 1952 §2.3.1): the first two bytes are `1f 8b`. */
58
+ function isGzip(bytes: Uint8Array): boolean {
59
+ return bytes[0] === 0x1f && bytes[1] === 0x8b;
60
+ }
61
+
50
62
  /** Invariant 1: the version gate, with its distinct non-"malformed" message. */
51
63
  function gateVersion(value: unknown, path: string): void {
52
64
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -8,6 +8,8 @@ export const CASSETTE_TEMP_PREFIX = ".yaag-tmp-";
8
8
  /**
9
9
  * Publishes a Cassette crash-durably: temp file, fsync, rename, destination
10
10
  * directory fsync. Resolves only after all four steps complete (ADR-0021).
11
+ * The bytes on disk are gzip-compressed JSON (ADR-0051); `loadCassette`
12
+ * reads both this and the plain JSON that older runtimes wrote.
11
13
  *
12
14
  * Rejects with an error naming `path` when any step fails; the temp file is
13
15
  * removed on a best-effort basis first.
@@ -16,7 +18,7 @@ export async function publishCassette(path: string, cassette: Cassette): Promise
16
18
  const directory = dirname(path);
17
19
  const temp = join(directory, `${CASSETTE_TEMP_PREFIX}${process.pid}-${basename(path)}`);
18
20
  try {
19
- await writeDurable(temp, JSON.stringify(cassette));
21
+ await writeDurable(temp, Bun.gzipSync(JSON.stringify(cassette)));
20
22
  await rename(temp, path);
21
23
  await syncDirectory(directory);
22
24
  } catch (error) {
@@ -30,7 +32,7 @@ export async function publishCassette(path: string, cassette: Cassette): Promise
30
32
  }
31
33
 
32
34
  /** Private artifact: the checkpoint may quote Agent output, so it is owner-only (ADR-0021). */
33
- async function writeDurable(path: string, contents: string): Promise<void> {
35
+ async function writeDurable(path: string, contents: Uint8Array): Promise<void> {
34
36
  const file = await open(path, "w", 0o600);
35
37
  try {
36
38
  await file.writeFile(contents);
@@ -14,6 +14,7 @@ import type {
14
14
  WorktreeResolution,
15
15
  } from "../transport/index.ts";
16
16
  import type { ThinkingLevel } from "../types.ts";
17
+ import { shapeFrame } from "./cassette-frame-shape.ts";
17
18
 
18
19
  /** The Cassette format this runtime writes; the loader also reads version 1. */
19
20
  export const CASSETTE_VERSION = 2 as const;
@@ -239,7 +240,8 @@ export class CassetteCollector implements CassetteSink {
239
240
  this.#agents[slot] = null;
240
241
  },
241
242
  sent: (frame): void => append(agent, "sentFrames", frame),
242
- received: (frame): void => append(agent, "receivedFrames", frame),
243
+ // Stored in its Frame Shape, so memory and every flush carry the reduced form (ADR-0051).
244
+ received: (frame): void => append(agent, "receivedFrames", shapeFrame(frame)),
243
245
  beginAsk: (marker): void => {
244
246
  if (!agent) return;
245
247
  const ask = { ...marker, sentFrames: [], receivedFrames: [] };
package/src/index.ts CHANGED
@@ -74,6 +74,7 @@ export {
74
74
  EMPTY_EFFECTIVE_CONFIG,
75
75
  loadEffectiveConfig,
76
76
  PROJECT_CONFIG_DIR,
77
+ resolveGlobalConfigDirectory,
77
78
  } from "./config/index.ts";
78
79
  export type {
79
80
  AskInvalidOutputOutcome,
@@ -45,6 +45,13 @@ interface AgentInfoBase {
45
45
  /** Timestamp ordering only cumulative live accounting, never lifecycle state. */
46
46
  readonly usageUpdatedAt: number | null;
47
47
  readonly askStartedAt: number | null;
48
+ /**
49
+ * Time this Agent spent inside Asks that ended: the sum of every settled
50
+ * `ask_end.durationMs`, plus the live stretch of an Ask its exit cut short.
51
+ * A renderer adds the Ask that runs now itself, so a Summary-only view — a
52
+ * stored Run record, `yaag_status` — reports the same total as a live one.
53
+ */
54
+ readonly activeMs: number;
48
55
  /** Compactions of this Agent's context so far (ADR-0043). */
49
56
  readonly compactions: number;
50
57
  /** What the newest compaction reported, or null when the Agent compacted none. */
@@ -131,6 +138,7 @@ export function placeholderAgent(): IdleAgentInfo {
131
138
  stateChangedAt: null,
132
139
  usageUpdatedAt: null,
133
140
  askStartedAt: null,
141
+ activeMs: 0,
134
142
  nodes: [],
135
143
  finishedNodesPruned: 0,
136
144
  modelFallbacks: [],
@@ -236,6 +244,8 @@ export function setActivity(
236
244
  /** One Ask settlement as the fold sees it. */
237
245
  export interface AskSettlement {
238
246
  readonly index: number;
247
+ /** The Ask's own measured duration, the authoritative source of `activeMs`. */
248
+ readonly durationMs: number;
239
249
  /** A recovered settlement makes this Agent's accounting a floor, not a total. */
240
250
  readonly recovered: boolean;
241
251
  }
@@ -245,7 +255,7 @@ export function endAsk(
245
255
  settlement: AskSettlement,
246
256
  at: number | null,
247
257
  ): AgentRecord {
248
- const { index, recovered } = settlement;
258
+ const { index, durationMs, recovered } = settlement;
249
259
  const agent = current ?? placeholderAgent();
250
260
  if (
251
261
  !canChangeAskState(agent, at) ||
@@ -260,6 +270,7 @@ export function endAsk(
260
270
  askIndex: index,
261
271
  activity: null,
262
272
  incomplete: agent.incomplete || recovered,
273
+ activeMs: agent.activeMs + Math.max(0, durationMs),
263
274
  stateChangedAt: at,
264
275
  };
265
276
  }
@@ -328,10 +339,20 @@ export function exitAgent(
328
339
  tokens: observation.tokens,
329
340
  cost: observation.cost,
330
341
  incomplete: observation.incomplete || observation.cost === null,
342
+ activeMs: agent.activeMs + cutShortAskMs(agent, at),
331
343
  stateChangedAt: at,
332
344
  };
333
345
  }
334
346
 
347
+ /**
348
+ * The live stretch of an Ask that the exit cut short. No `ask_end` follows such
349
+ * an Ask, so this is the only place its time can enter the total.
350
+ */
351
+ function cutShortAskMs(agent: AgentRecord, at: number | null): number {
352
+ if (agent.state !== "asking" || agent.askStartedAt === null || at === null) return 0;
353
+ return Math.max(0, at - agent.askStartedAt);
354
+ }
355
+
335
356
  /**
336
357
  * Computes Run-wide accounting from every Agent's newest snapshot. A live Agent
337
358
  * without an assistant completion contributes zero; an exited Agent without
@@ -254,7 +254,11 @@ function settleAsk(
254
254
  event.agent,
255
255
  endAsk(
256
256
  summary.agents[event.agent],
257
- { index: event.index, recovered: event.cause === "recovered" },
257
+ {
258
+ index: event.index,
259
+ durationMs: event.durationMs,
260
+ recovered: event.cause === "recovered",
261
+ },
258
262
  at,
259
263
  ),
260
264
  );