@pugi/cli 0.1.0-alpha.10

package/dist/core/credentials.js

@@ -0,0 +1,355 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+/**
+ * Local credentials store for the Pugi CLI.
+ *
+ * Stored at `~/.pugi/credentials.json` (mode 0o600). Mirrors the convention
+ * Codex CLI uses (`~/.codex/auth.json`) and matches gh CLI's per-host
+ * token model. The store is intentionally file-based, not OS keychain —
+ * adding the native `keytar` dep would force per-platform native builds
+ * across npm distribution and complicate the install path. The 0600
+ * file mode plus a strictly typed Zod schema is the minimum-viable
+ * substitute for the keychain path.
+ *
+ * Multi-host: each host (apiUrl) has its own record. `pugi login` adds
+ * or replaces the record for the active host; `pugi logout` removes it.
+ * `loadActiveCredential` returns the record for the active host (the one
+ * matching `PUGI_API_URL` or `apiUrl` from `~/.pugi/config.json`).
+ *
+ * Future device-flow tokens land in the same `tokens` array with a
+ * `kind: 'oauth-device'` discriminator and a refresh-on-use rotation.
+ */
+const CREDENTIALS_SCHEMA_VERSION = 1;
+/**
+ * How the credential was obtained. Surfaced by `pugi whoami` so the user
+ * can confirm at a glance whether a stored record came from an
+ * interactive device flow, a paste-in PAT, or an env-var prime in CI.
+ *
+ * Older credential files written before this discriminator was added do
+ * not carry `source` — the field is optional and `pugi whoami` falls
+ * back to `unknown` so we never crash on a legacy file.
+ */
+export const pugiTokenSourceSchema = z.enum(['token', 'device-flow', 'env']);
+export const pugiTokenRecordSchema = z.object({
+    apiUrl: z.string().url(),
+    apiKey: z.string().min(1),
+    label: z.string().min(1).optional(),
+    createdAt: z.string().datetime(),
+    /**
+     * When the credential was last refreshed in the store. Today the
+     * field is set on `storeApiKey` (create / replace) and on
+     * `switchActiveAccount`. Read paths (`pugi whoami`, every API call)
+     * intentionally do NOT touch the file to keep disk IO off the hot
+     * path — a recency value that lags is acceptable, a 0o600 write per
+     * `pugi <anything>` is not.
+     */
+    lastUsedAt: z.string().datetime().optional(),
+    /**
+     * Provenance discriminator — see `pugiTokenSourceSchema`. Optional so
+     * legacy records (pre-0048) still parse.
+     */
+    source: pugiTokenSourceSchema.optional(),
+});
+export const pugiCredentialsFileSchema = z.object({
+    schema: z.literal(CREDENTIALS_SCHEMA_VERSION),
+    tokens: z.array(pugiTokenRecordSchema).default([]),
+    /**
+     * URL of the host the user most recently logged into. `pugi whoami`
+     * and `resolveActiveCredential` read this when `PUGI_API_URL` is unset
+     * so a self-hosted user who runs `pugi login --api-url https://anvil.acme.corp`
+     * doesn't have to also export PUGI_API_URL for follow-up commands.
+     * Env still wins when set (CI fast path).
+     */
+    activeApiUrl: z.string().url().optional(),
+});
+export const DEFAULT_API_URL = 'https://api.pugi.io';
+export function credentialsPaths(home = homedir()) {
+    const pugiDir = resolve(home, '.pugi');
+    return {
+        homeDir: home,
+        pugiDir,
+        filePath: resolve(pugiDir, 'credentials.json'),
+    };
+}
+export function readCredentialsFile(home = homedir()) {
+    const { filePath } = credentialsPaths(home);
+    if (!existsSync(filePath)) {
+        return { schema: CREDENTIALS_SCHEMA_VERSION, tokens: [] };
+    }
+    const text = readFileSync(filePath, 'utf8');
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        // Corrupt JSON: a partial/empty write or hand-edit. Rename the bad
+        // file aside so the next write does not silently produce an empty
+        // token list (silent data loss). Returning empty here is acceptable
+        // because the corrupt copy is preserved for forensic recovery.
+        quarantineCorruptCredentials(filePath, 'json-parse');
+        return { schema: CREDENTIALS_SCHEMA_VERSION, tokens: [] };
+    }
+    const parsed = pugiCredentialsFileSchema.safeParse(raw);
+    if (parsed.success)
+        return parsed.data;
+    quarantineCorruptCredentials(filePath, 'schema-mismatch');
+    return { schema: CREDENTIALS_SCHEMA_VERSION, tokens: [] };
+}
+function quarantineCorruptCredentials(filePath, reason) {
+    try {
+        const backup = `${filePath}.corrupt-${reason}-${Date.now()}`;
+        renameSync(filePath, backup);
+        if (process.stderr?.write) {
+            process.stderr.write(`pugi: warning — corrupt credentials file preserved at ${backup}; starting from empty token list\n`);
+        }
+    }
+    catch {
+        // Best-effort. If we cannot rename (e.g. read-only fs), the next
+        // write will overwrite the corrupt file anyway.
+    }
+}
+export function writeCredentialsFile(file, home = homedir()) {
+    const paths = credentialsPaths(home);
+    if (!existsSync(paths.pugiDir)) {
+        mkdirSync(paths.pugiDir, { recursive: true, mode: 0o700 });
+    }
+    // Defensively tighten existing dir permissions — `mkdirSync(mode)` only
+    // applies on creation, not on pre-existing dirs that another tool may
+    // have created with 0o755.
+    try {
+        chmodSync(paths.pugiDir, 0o700);
+    }
+    catch {
+        // Best-effort; FAT/CI filesystems may not support chmod.
+    }
+    // Validate before persisting so a corrupt object never lands on disk.
+    const validated = pugiCredentialsFileSchema.parse(file);
+    // Atomic write: tmp + rename. `rename(2)` is atomic on POSIX same-fs,
+    // so a concurrent reader either sees the old file or the new one — never
+    // a truncated mid-write state that the corrupt-recovery path would
+    // quarantine as data loss. Two concurrent writers still race (no advisory
+    // lock yet), but neither corrupts the target file.
+    const tmp = `${paths.filePath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(validated, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    try {
+        chmodSync(tmp, 0o600);
+    }
+    catch {
+        // Best-effort on filesystems that don't support chmod (FAT, some CIs).
+    }
+    renameSync(tmp, paths.filePath);
+    try {
+        chmodSync(paths.filePath, 0o600);
+    }
+    catch {
+        // Best-effort — rename preserves the tmp file's mode on POSIX, this
+        // is belt-and-braces.
+    }
+}
+/**
+ * Add or replace the credential record for the given apiUrl. Returns the
+ * stored record (without the `apiKey` echoed back at the caller — the
+ * caller already has it). Idempotent.
+ */
+export function storeApiKey(input) {
+    const home = input.home ?? homedir();
+    const file = readCredentialsFile(home);
+    const apiUrl = normalizeApiUrl(input.apiUrl);
+    const now = new Date().toISOString();
+    const record = pugiTokenRecordSchema.parse({
+        apiUrl,
+        apiKey: input.apiKey,
+        label: input.label,
+        createdAt: now,
+        lastUsedAt: now,
+        source: input.source,
+    });
+    const others = file.tokens.filter((token) => normalizeApiUrl(token.apiUrl) !== apiUrl);
+    writeCredentialsFile({
+        schema: CREDENTIALS_SCHEMA_VERSION,
+        tokens: [...others, record],
+        // Promote the just-logged-in host to active so subsequent `whoami`
+        // and `review --remote` find it without the user re-exporting
+        // PUGI_API_URL. Env still wins via resolveActiveCredential.
+        activeApiUrl: apiUrl,
+    }, home);
+    return record;
+}
+export function clearApiKey(apiUrl, home = homedir()) {
+    const file = readCredentialsFile(home);
+    const target = normalizeApiUrl(apiUrl);
+    const before = file.tokens.length;
+    const tokens = file.tokens.filter((token) => normalizeApiUrl(token.apiUrl) !== target);
+    if (tokens.length === before)
+        return false;
+    // If the cleared host was the active one, demote `activeApiUrl` to the
+    // most recently-stored remaining record (or undefined when the store
+    // is now empty) so subsequent `whoami` doesn't point at a vanished host.
+    const nextActive = file.activeApiUrl && normalizeApiUrl(file.activeApiUrl) === target
+        ? tokens.at(-1)?.apiUrl
+        : file.activeApiUrl;
+    writeCredentialsFile({
+        schema: CREDENTIALS_SCHEMA_VERSION,
+        tokens,
+        ...(nextActive ? { activeApiUrl: nextActive } : {}),
+    }, home);
+    return true;
+}
+export function loadApiKey(apiUrl, home = homedir()) {
+    const file = readCredentialsFile(home);
+    const target = normalizeApiUrl(apiUrl);
+    return file.tokens.find((token) => normalizeApiUrl(token.apiUrl) === target) ?? null;
+}
+export function resolveActiveCredential(env = process.env, home = homedir()) {
+    // Resolve the active apiUrl with this precedence:
+    //   1. PUGI_API_URL env (lets CI / self-hosted users force a specific endpoint)
+    //   2. credentials.json `activeApiUrl` (set by `pugi login` to the host the
+    //      user most recently authenticated against — covers self-hosted Anvil
+    //      without re-exporting env between commands)
+    //   3. DEFAULT_API_URL (`https://api.pugi.io`)
+    const file = readCredentialsFile(home);
+    const apiUrl = normalizeApiUrl(env.PUGI_API_URL ?? file.activeApiUrl ?? DEFAULT_API_URL);
+    if (env.PUGI_API_KEY) {
+        return { apiUrl, apiKey: env.PUGI_API_KEY, source: 'env' };
+    }
+    const record = file.tokens.find((token) => normalizeApiUrl(token.apiUrl) === apiUrl);
+    if (record) {
+        return {
+            apiUrl: record.apiUrl,
+            apiKey: record.apiKey,
+            source: 'file',
+            fileSource: record.source ?? null,
+            ...(record.label ? { label: record.label } : {}),
+            ...(record.createdAt ? { createdAt: record.createdAt } : {}),
+            ...(record.lastUsedAt ? { lastUsedAt: record.lastUsedAt } : {}),
+        };
+    }
+    return null;
+}
+/**
+ * Re-point the credentials store at a different already-stored host or
+ * label. Used by `pugi accounts switch <label>` so subsequent commands
+ * authenticate against the chosen account without forcing the user to
+ * re-export PUGI_API_URL between commands.
+ *
+ * Match precedence:
+ *   1. exact `label` match (case-insensitive, label is user-chosen so
+ *      we forgive casing — same convention as `gh auth switch`)
+ *   2. exact `apiUrl` match (canonicalised) — lets `pugi accounts
+ *      switch https://api.acme.com` work without a label.
+ *
+ * Returns the now-active record, or null when nothing matched.
+ */
+export function switchActiveAccount(selector, home = homedir()) {
+    const file = readCredentialsFile(home);
+    const normalisedSelector = selector.trim();
+    if (!normalisedSelector)
+        return null;
+    const lower = normalisedSelector.toLowerCase();
+    const targetApiUrl = (() => {
+        try {
+            return normalizeApiUrl(normalisedSelector);
+        }
+        catch {
+            return null;
+        }
+    })();
+    const match = file.tokens.find((token) => {
+        if (token.label && token.label.toLowerCase() === lower)
+            return true;
+        if (targetApiUrl && normalizeApiUrl(token.apiUrl) === targetApiUrl)
+            return true;
+        return false;
+    });
+    if (!match)
+        return null;
+    const apiUrl = normalizeApiUrl(match.apiUrl);
+    const now = new Date().toISOString();
+    const updated = pugiTokenRecordSchema.parse({
+        ...match,
+        apiUrl,
+        lastUsedAt: now,
+    });
+    const others = file.tokens.filter((token) => normalizeApiUrl(token.apiUrl) !== apiUrl);
+    writeCredentialsFile({
+        schema: CREDENTIALS_SCHEMA_VERSION,
+        tokens: [...others, updated],
+        activeApiUrl: apiUrl,
+    }, home);
+    return updated;
+}
+/**
+ * List every stored credential in stable display order — most recently
+ * used first, falling back to creation order. Returned records carry
+ * the raw `apiKey`; callers must mask before printing.
+ */
+export function listStoredCredentials(home = homedir()) {
+    const file = readCredentialsFile(home);
+    const activeUrl = file.activeApiUrl ? normalizeApiUrl(file.activeApiUrl) : null;
+    return file.tokens
+        .map((token) => ({
+        ...token,
+        isActive: activeUrl !== null && normalizeApiUrl(token.apiUrl) === activeUrl,
+    }))
+        .sort((a, b) => {
+        // Active record always pinned to the top — it's the one the user
+        // is asking about whenever they run `pugi accounts list`.
+        if (a.isActive && !b.isActive)
+            return -1;
+        if (b.isActive && !a.isActive)
+            return 1;
+        const aWhen = a.lastUsedAt ?? a.createdAt;
+        const bWhen = b.lastUsedAt ?? b.createdAt;
+        return bWhen.localeCompare(aWhen);
+    });
+}
+/**
+ * Canonicalize an apiUrl so two equivalent inputs always resolve to the
+ * same record:
+ *   - lowercase scheme + host (URL spec: scheme/host are case-insensitive)
+ *   - strip trailing slashes
+ *   - preserve path/query/fragment case (those ARE case-sensitive)
+ *
+ * Falls back to the trimmed input when the URL is not parseable, so a
+ * caller that manages to pass a non-URL string still sees a stable key
+ * instead of throwing.
+ */
+export function normalizeApiUrl(input) {
+    const trimmed = input.trim();
+    try {
+        const url = new URL(trimmed);
+        const path = url.pathname + url.search + url.hash;
+        const stripped = path.replace(/\/+$/, '');
+        return `${url.protocol.toLowerCase()}//${url.host.toLowerCase()}${stripped}`;
+    }
+    catch {
+        return trimmed.replace(/\/+$/, '');
+    }
+}
+/**
+ * Best-effort masked token for log lines and `pugi whoami` output.
+ * Never returns the raw secret. Keeps the first 4 + last 4 characters so
+ * the user can correlate against an issued key without exposing it.
+ */
+export function maskApiKey(apiKey) {
+    if (apiKey.length <= 12)
+        return `${'*'.repeat(apiKey.length)}`;
+    return `${apiKey.slice(0, 4)}…${apiKey.slice(-4)}`;
+}
+/**
+ * Delete the entire credentials file. Used by `pugi logout --all` and
+ * by tests that want a clean slate.
+ */
+export function purgeAllCredentials(home = homedir()) {
+    const paths = credentialsPaths(home);
+    if (!existsSync(paths.filePath))
+        return false;
+    rmSync(paths.filePath);
+    return true;
+}
+//# sourceMappingURL=credentials.js.map

package/dist/core/engine/adapter-runner.js

@@ -0,0 +1,8 @@
+export async function collectEngineEvents(adapter, task, ctx) {
+    const events = [];
+    for await (const event of adapter.run(task, ctx)) {
+        events.push(event);
+    }
+    return events;
+}
+//# sourceMappingURL=adapter-runner.js.map

package/dist/core/engine/anvil-client.js

@@ -0,0 +1,156 @@
+/**
+ * Anvil-backed engine loop client.
+ *
+ * Wire format: OpenAI-compatible `/v1/chat/completions` shape proxied
+ * through the admin-api Pugi runtime endpoint. The CLI POSTs:
+ *
+ *   POST {apiUrl}/api/pugi/engine
+ *   Authorization: Bearer {apiKey}
+ *   {
+ *     "personaSlug": "oes-dev",
+ *     "messages":   [...],
+ *     "tools":      [...],
+ *     "maxTokens":  4096,
+ *     "temperature": 0.2
+ *   }
+ *
+ * and expects:
+ *
+ *   200 OK
+ *   {
+ *     "stop":  "tool_use" | "text",
+ *     "content": "...",                    // present when stop=text
+ *     "toolCalls": [{id, name, arguments}], // present when stop=tool_use
+ *     "tokensUsed": 1234,
+ *     "model": "deepseek-chat-v3.1"
+ *   }
+ *
+ *   401/403 -> auth_missing
+ *   404     -> endpoint_missing
+ *   429     -> rate_limited
+ *   other   -> failed
+ *
+ * The endpoint itself ships in Sprint 2 (Track 2A). Until then the CLI
+ * surfaces `endpoint_missing` cleanly and the operator runs `pugi code`
+ * with `PUGI_ENGINE_FIXTURE` to point at a fixture client.
+ */
+export class AnvilEngineLoopClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async send(messages, tools, options) {
+        // Use `new URL(path, base)` so an `apiUrl` that already carries a
+        // path prefix (rare, but possible for self-hosted deployments)
+        // composes correctly instead of double-pathing via raw string
+        // concatenation. The leading `/` anchors resolution to the base
+        // host. Self-hosted operators who need their engine endpoint
+        // nested under a prefix should bake the prefix into `apiUrl`
+        // itself and drop the leading slash here.
+        const url = new URL('/api/pugi/engine', this.config.apiUrl).toString();
+        const controller = new AbortController();
+        const onAbort = () => controller.abort();
+        if (options.signal)
+            options.signal.addEventListener('abort', onAbort);
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${this.config.apiKey}`,
+                    'user-agent': 'pugi-cli/0.0.1',
+                },
+                body: JSON.stringify({
+                    personaSlug: options.personaSlug,
+                    messages,
+                    tools,
+                    maxTokens: options.maxTokens,
+                    temperature: options.temperature,
+                }),
+                signal: controller.signal,
+            });
+            const text = await res.text();
+            if (res.status === 200) {
+                try {
+                    const json = JSON.parse(text);
+                    if (json.stop === 'text') {
+                        return {
+                            stop: 'text',
+                            assistantMessage: {
+                                role: 'assistant',
+                                content: json.content ?? '',
+                            },
+                            content: json.content ?? '',
+                            tokensUsed: json.tokensUsed ?? 0,
+                        };
+                    }
+                    if (json.stop === 'tool_use') {
+                        const calls = json.toolCalls ?? [];
+                        return {
+                            stop: 'tool_use',
+                            assistantMessage: {
+                                role: 'assistant',
+                                content: json.content ?? '',
+                                toolCalls: calls,
+                            },
+                            tokensUsed: json.tokensUsed ?? 0,
+                        };
+                    }
+                    return {
+                        stop: 'error',
+                        code: 'failed',
+                        message: `runtime returned 200 with unknown stop=${String(json.stop)}`,
+                    };
+                }
+                catch (error) {
+                    return {
+                        stop: 'error',
+                        code: 'failed',
+                        message: `runtime returned 200 with non-JSON body: ${error.message}`,
+                    };
+                }
+            }
+            if (res.status === 404) {
+                return {
+                    stop: 'error',
+                    code: 'endpoint_missing',
+                    message: 'POST /api/pugi/engine not deployed on this runtime',
+                };
+            }
+            if (res.status === 401 || res.status === 403) {
+                return {
+                    stop: 'error',
+                    code: 'auth_missing',
+                    message: `runtime rejected credentials (HTTP ${res.status})`,
+                };
+            }
+            if (res.status === 429) {
+                return {
+                    stop: 'error',
+                    code: 'rate_limited',
+                    message: 'runtime rate limit reached for this tenant',
+                };
+            }
+            return {
+                stop: 'error',
+                code: 'failed',
+                message: `runtime returned HTTP ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error
+                ? error.name === 'AbortError'
+                    ? `runtime call timed out after ${this.config.timeoutMs}ms`
+                    : error.message
+                : 'unknown error';
+            return { stop: 'error', code: 'failed', message };
+        }
+        finally {
+            clearTimeout(timeout);
+            if (options.signal)
+                options.signal.removeEventListener('abort', onAbort);
+        }
+    }
+}
+//# sourceMappingURL=anvil-client.js.map

package/dist/core/engine/compaction-hook.js

@@ -0,0 +1,154 @@
+/**
+ * Engine loop integration point for the six-tier compaction engine.
+ *
+ * `maybeCompactAfterTool` is the single function the engine loop calls
+ * after each tool result has been appended to the transcript. It:
+ *
+ *   1. Estimates current context-window pressure (transcript bytes
+ *      against the model's budget, plus the static blocks).
+ *   2. Calls `selectTier` on the snapshot.
+ *   3. Runs the tier. Microcompact / cached_microcompact are sync;
+ *      reactive_summary / session_memory / full_compaction / reset
+ *      are async-shaped (the call returns before commit when run
+ *      against a long transcript) but currently run inline — the
+ *      engine loop is single-threaded today, so true backgrounding
+ *      waits for the SSE consumer refactor in α5.7.
+ *   4. Runs invariant checks against the result. On any violation,
+ *      emits `compaction.invariant_violated` and returns the
+ *      pre-compaction transcript untouched.
+ *   5. On success, emits `compaction.completed` with reclaim numbers
+ *      and returns the new transcript for the caller to adopt.
+ *   6. On no-op, emits `compaction.skipped` and returns the original.
+ *
+ * Why a separate file (not inlined into `native-pugi.ts`):
+ *
+ *   Sprint α5.3 (feat/pugi-cli-hooks-lifecycle-m1-gap-c) is in flight
+ *   and already modifies session.ts + tool-bridge + permission. Editing
+ *   native-pugi.ts in this PR risks a merge conflict against α5.3's
+ *   landing PR. Keeping the wiring as an exported helper means the
+ *   one-line callsite in native-pugi.ts can be added in a tiny
+ *   follow-up after both α5.3 and α5.5 have landed.
+ *
+ * Expected callsite in `apps/pugi-cli/src/core/engine/native-pugi.ts`,
+ * inside `onToolResult`:
+ *
+ *   ```ts
+ *   const compactionOutcome = await maybeCompactAfterTool({
+ *     session,
+ *     transcript: currentTranscript,
+ *     toolOutputs: recentToolOutputs,
+ *     contextBudgetUsed: estimatedTokens,
+ *     contextBudgetMax: budget.maxTokens,
+ *     workspaceRoot: root,
+ *     contextStaticHash: {
+ *       instructionsHash,
+ *       toolSchemaHash,
+ *     },
+ *   });
+ *   if (compactionOutcome.committed) {
+ *     currentTranscript = compactionOutcome.newTranscript;
+ *   }
+ *   ```
+ */
+import { runCompaction, selectTier, } from '../context/compaction.js';
+import { checkInvariants } from '../context/invariants.js';
+import { emitCompactionCompleted, emitCompactionInvariantViolated, emitCompactionSkipped, emitCompactionStarted, } from '../context/compaction-events.js';
+/**
+ * Engine-loop callback. See file header for the expected callsite shape.
+ *
+ * Contract:
+ *   - Never throws. All errors degrade to `committed: false` with the
+ *     original transcript and an event record.
+ *   - On `committed: true`, the caller MUST adopt `newTranscript` as
+ *     the live working transcript for the next model turn.
+ *   - On `committed: false`, the caller MUST keep the input transcript
+ *     and try again on the next tool turn (compaction will retry once
+ *     pressure stays above threshold).
+ */
+export async function maybeCompactAfterTool(input) {
+    const compactionInput = {
+        sessionId: input.session.id,
+        contextBudgetUsed: input.contextBudgetUsed,
+        contextBudgetMax: input.contextBudgetMax,
+        toolOutputs: input.toolOutputs,
+        transcript: input.transcript,
+        workspaceRoot: input.workspaceRoot,
+    };
+    const tier = selectTier(compactionInput);
+    emitCompactionStarted(input.session, tier, {
+        budgetUsed: input.contextBudgetUsed,
+        budgetMax: input.contextBudgetMax,
+    });
+    let result;
+    try {
+        result = await runCompaction(compactionInput, tier);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        emitCompactionSkipped(input.session, tier, `compaction crashed: ${reason}`);
+        return {
+            committed: false,
+            tier,
+            newTranscript: input.transcript,
+            bytesReclaimed: 0,
+            newContextSize: byteSize(input.transcript),
+            violations: [],
+            skipped: true,
+            skipReason: `crashed: ${reason}`,
+        };
+    }
+    if (result.skipped) {
+        emitCompactionSkipped(input.session, tier, result.skipReason || 'no work');
+        return {
+            committed: false,
+            tier,
+            newTranscript: input.transcript,
+            bytesReclaimed: 0,
+            newContextSize: byteSize(input.transcript),
+            violations: [],
+            skipped: true,
+            skipReason: result.skipReason,
+        };
+    }
+    // Invariant gate: static-hash-unchanged is enforced by passing the
+    // same hashes in for `before` and `after` — compaction never touches
+    // static blocks, so the hashes are equal by construction. We pass
+    // both so the contract is explicit; if a future tier introduces a
+    // bug that overwrites static state, the check still catches it.
+    const violations = checkInvariants({
+        before: compactionInput,
+        after: result,
+        summaryText: result.summaryText,
+        staticHashBefore: input.contextStaticHash,
+        staticHashAfter: input.contextStaticHash,
+    });
+    if (violations.length > 0) {
+        for (const v of violations)
+            emitCompactionInvariantViolated(input.session, v);
+        return {
+            committed: false,
+            tier,
+            newTranscript: input.transcript,
+            bytesReclaimed: 0,
+            newContextSize: byteSize(input.transcript),
+            violations,
+            skipped: false,
+            skipReason: '',
+        };
+    }
+    emitCompactionCompleted(input.session, tier, result.bytesReclaimed, result.newContextSize, result.artifactsCreated);
+    return {
+        committed: true,
+        tier,
+        newTranscript: result.newTranscript,
+        bytesReclaimed: result.bytesReclaimed,
+        newContextSize: result.newContextSize,
+        violations: [],
+        skipped: false,
+        skipReason: '',
+    };
+}
+function byteSize(transcript) {
+    return transcript.reduce((sum, t) => sum + Buffer.byteLength(t.content, 'utf8'), 0);
+}
+//# sourceMappingURL=compaction-hook.js.map

package/dist/core/engine/index.js

@@ -0,0 +1,12 @@
+export * from './adapter-runner.js';
+export * from './anvil-client.js';
+export * from './native-pugi.js';
+export * from './noop.js';
+export * from './prompts.js';
+export * from './tool-bridge.js';
+// Subagent dispatch helper. Engine adapter code calls this from a
+// future `task_dispatch` tool (alpha-5.7 REPL); the re-export keeps the
+// import path stable so adapter code does not have to reach into the
+// subagents submodule.
+export { spawnSubagent } from '../subagents/spawn.js';
+//# sourceMappingURL=index.js.map