@pugi/cli 0.1.0-alpha.3 → 0.1.0-alpha.6

package/dist/core/context/builder.js

@@ -0,0 +1,114 @@
+/**
+ * Context builder — separates static and dynamic blocks so the model's
+ * prompt cache stays warm across turns.
+ *
+ * Per `docs/research/pugi-cli-corpus/patterns/context-compaction.md` §6,
+ * static and dynamic context live in different sections:
+ *
+ *   STATIC                        DYNAMIC
+ *   - system instructions         - transcript turns (recent)
+ *   - tool schemas (sorted)       - session memory ref
+ *   - safety rules                - open task graph snapshot
+ *   - PUGI.md + AGENTS.md
+ *
+ * Static blocks hash deterministically; identical session starts emit
+ * identical static prefixes, hitting the model provider's prompt cache.
+ * Dynamic blocks rebuild every turn — compaction touches dynamic only.
+ *
+ * This module is pure: no fs, no network. Markdown loading happens in
+ * `markdown-loader.ts` and is passed in. Hash inputs are sorted to keep
+ * the static hash stable under map-iteration-order changes.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Build a `BuiltContext` from input. Pure function: same input always
+ * produces byte-identical static blocks (and therefore byte-identical
+ * static hashes). Dynamic blocks are returned as-is in transcript order;
+ * compaction reshuffles dynamic only.
+ *
+ * Marked async to match the codebase convention even though the body is
+ * fully sync. Callers chain `await buildContext(...)` so a future move
+ * to async markdown reloading or RAG injection does not break callers.
+ */
+export async function buildContext(input) {
+    const blocks = [];
+    // 1. Tools first — alphabetically sorted by name, per pattern card §6.
+    const sortedTools = [...input.tools].sort((a, b) => a.name.localeCompare(b.name));
+    const toolBundle = sortedTools.map((t) => `${t.name}:${t.schema}`).join('\n');
+    blocks.push({
+        kind: 'tool_schema',
+        name: 'tools',
+        content: toolBundle,
+        bytes: Buffer.byteLength(toolBundle, 'utf8'),
+    });
+    // 2. Instructions — single deterministic block.
+    const instructionsContent = normalizeNewlines(input.instructions);
+    blocks.push({
+        kind: 'instructions',
+        name: 'instructions',
+        content: instructionsContent,
+        bytes: Buffer.byteLength(instructionsContent, 'utf8'),
+    });
+    // 3. Safety rules — optional, hashed into the instructions block via
+    //    concatenation when present so consumers can read both as one.
+    if (input.safetyRules) {
+        const safety = normalizeNewlines(input.safetyRules);
+        blocks.push({
+            kind: 'safety_rules',
+            name: 'safety',
+            content: safety,
+            bytes: Buffer.byteLength(safety, 'utf8'),
+        });
+    }
+    // 4. PUGI.md / AGENTS.md — loaded markdown in workspace-root order.
+    for (const md of input.markdown) {
+        blocks.push({
+            kind: md.source === 'PUGI.md' ? 'pugi_md' : 'agents_md',
+            name: md.source,
+            content: md.content,
+            bytes: Buffer.byteLength(md.content, 'utf8'),
+        });
+    }
+    const staticBytes = blocks.reduce((sum, b) => sum + b.bytes, 0);
+    const instructionsBlock = blocks.find((b) => b.kind === 'instructions');
+    const toolBlock = blocks.find((b) => b.kind === 'tool_schema');
+    const mdBlocks = blocks.filter((b) => b.kind === 'pugi_md' || b.kind === 'agents_md');
+    const instructionsHash = sha256(instructionsBlock?.content ?? '');
+    const toolSchemaHash = sha256(toolBundle);
+    const pugiMdHash = mdBlocks.length > 0 ? sha256(mdBlocks.map((b) => b.content).join('\n---\n')) : undefined;
+    const dynamicBytes = input.transcript.reduce((sum, t) => sum + Buffer.byteLength(t.content, 'utf8'), 0) +
+        (input.sessionMemory?.bytes ?? 0) +
+        estimateTaskGraphBytes(input.openTaskGraph);
+    const totalBytes = staticBytes + dynamicBytes;
+    return {
+        static: {
+            instructionsHash,
+            toolSchemaHash,
+            pugiMdHash,
+            blocks,
+            bytes: staticBytes,
+        },
+        dynamic: {
+            transcriptTurns: input.transcript,
+            sessionMemory: input.sessionMemory,
+            openTaskGraph: input.openTaskGraph,
+            bytes: dynamicBytes,
+        },
+        totalBytes,
+        estimatedTokens: Math.ceil(totalBytes / 4),
+    };
+}
+function sha256(input) {
+    return createHash('sha256').update(input, 'utf8').digest('hex');
+}
+function normalizeNewlines(input) {
+    // CRLF normalization plus trailing-newline strip so identical source
+    // emitted by different OS shells hashes identically.
+    return input.replace(/\r\n/g, '\n').replace(/\n+$/, '');
+}
+function estimateTaskGraphBytes(graph) {
+    if (!graph)
+        return 0;
+    return Buffer.byteLength(JSON.stringify(graph), 'utf8');
+}
+//# sourceMappingURL=builder.js.map

package/dist/core/context/compaction-events.js

@@ -0,0 +1,99 @@
+/**
+ * Compaction event emitter — appends `compaction.*` events to the
+ * session's events.jsonl using the shared AuditEvent discriminated union
+ * in `@pugi/sdk/audit-trace.ts`.
+ *
+ * Until PR #307 these events were written with the ad-hoc shape
+ * `{ id, ts, sessionId, ... }` and the comment in this header claimed
+ * "we keep `session.ts` untouched and write our events through a
+ * dedicated helper that bypasses the AuditEvent schema". The downside,
+ * caught by Claude review on PR #307, is that every consumer that
+ * calls `auditEventSchema.parse(line)` (cabinet UI, replay tooling,
+ * `core/index-store.ts`) would throw on every compaction event, and
+ * `safeParse` consumers would silently drop them.
+ *
+ * Fix: extend the discriminated union with four compaction event
+ * shapes and emit using the `timestamp` (full word) field name to
+ * match every other event already in the schema. The events now
+ * round-trip through `auditEventSchema.parse` without loss.
+ *
+ * Events emitted:
+ *
+ *   compaction.started            { sessionId, tier, trigger }
+ *   compaction.completed          { sessionId, tier, bytesReclaimed,
+ *                                   newContextSize, artifactsCreated }
+ *   compaction.skipped            { sessionId, tier, reason }
+ *   compaction.invariant_violated { sessionId, invariant, evidence,
+ *                                   artifactRef? }
+ *
+ * All four are appended in mode 0o600 and respect the
+ * `session.enabled` flag (no-op when `.pugi/` is absent).
+ */
+import { appendFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+export function emitCompactionStarted(session, tier, trigger) {
+    if (!session.enabled)
+        return;
+    appendCompactionEvent(session, {
+        type: 'compaction.started',
+        id: randomUUID(),
+        timestamp: nowIso(),
+        sessionId: session.id,
+        tier,
+        trigger,
+    });
+}
+export function emitCompactionCompleted(session, tier, bytesReclaimed, newContextSize, artifactsCreated) {
+    if (!session.enabled)
+        return;
+    appendCompactionEvent(session, {
+        type: 'compaction.completed',
+        id: randomUUID(),
+        timestamp: nowIso(),
+        sessionId: session.id,
+        tier,
+        bytesReclaimed,
+        newContextSize,
+        artifactsCreated: artifactsCreated.map((a) => ({
+            sha256: a.sha256,
+            size: a.size,
+            producedBy: a.producedBy,
+        })),
+    });
+}
+export function emitCompactionSkipped(session, tier, reason) {
+    if (!session.enabled)
+        return;
+    appendCompactionEvent(session, {
+        type: 'compaction.skipped',
+        id: randomUUID(),
+        timestamp: nowIso(),
+        sessionId: session.id,
+        tier,
+        reason,
+    });
+}
+export function emitCompactionInvariantViolated(session, violation) {
+    if (!session.enabled)
+        return;
+    const event = {
+        type: 'compaction.invariant_violated',
+        id: randomUUID(),
+        timestamp: nowIso(),
+        sessionId: session.id,
+        invariant: violation.invariant,
+        evidence: violation.evidence,
+        ...(violation.artifactRef !== undefined ? { artifactRef: violation.artifactRef } : {}),
+    };
+    appendCompactionEvent(session, event);
+}
+function appendCompactionEvent(session, event) {
+    appendFileSync(session.eventsPath, `${JSON.stringify(event)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+//# sourceMappingURL=compaction-events.js.map