@yaag/runtime 0.17.0 → 0.18.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.
- package/package.json +1 -1
- package/src/agent/index.ts +2 -0
- package/src/ask/index.ts +4 -0
- package/src/cassette/cassette-frame-shape.ts +62 -0
- package/src/cassette/cassette-loader.ts +15 -3
- package/src/cassette/cassette-publish.ts +4 -2
- package/src/cassette/cassette.ts +3 -1
- package/src/index.ts +1 -0
- package/src/summary/summary-agent.ts +22 -1
- package/src/summary/summary.ts +5 -1
package/package.json
CHANGED
package/src/agent/index.ts
CHANGED
|
@@ -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
|
|
24
|
+
let bytes: Uint8Array<ArrayBuffer>;
|
|
23
25
|
try {
|
|
24
|
-
|
|
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(
|
|
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:
|
|
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);
|
package/src/cassette/cassette.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
@@ -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
|
package/src/summary/summary.ts
CHANGED
|
@@ -254,7 +254,11 @@ function settleAsk(
|
|
|
254
254
|
event.agent,
|
|
255
255
|
endAsk(
|
|
256
256
|
summary.agents[event.agent],
|
|
257
|
-
{
|
|
257
|
+
{
|
|
258
|
+
index: event.index,
|
|
259
|
+
durationMs: event.durationMs,
|
|
260
|
+
recovered: event.cause === "recovered",
|
|
261
|
+
},
|
|
258
262
|
at,
|
|
259
263
|
),
|
|
260
264
|
);
|