pilotswarm-sdk 0.5.20 → 0.5.21

package/dist/distiller-tools.js

@@ -0,0 +1,102 @@
+/**
+ * Distiller Tools — the regen-distiller service session's toolset.
+ *
+ * One tool: `read_transcript_page`, which pages through the ARCHIVED
+ * transcript (`transcript-e<E>-<attemptId>.jsonl`) of the session the
+ * distiller serves. The security model is CMS truth, not registration-time
+ * gating: the tool is registered on every worker (any pod can host the
+ * distiller's turn), but at call time it requires the CALLER's session row
+ * to carry `service_kind = "regen-distiller"` and reads only from that
+ * row's `service_of` session, only artifacts matching the archive name
+ * shape. A spoofed session named "regen-distiller" has no service columns
+ * (they are set exclusively by the worker's spawn activity) and gets
+ * nothing.
+ *
+ * @internal
+ */
+import { defineTool } from "@github/copilot-sdk";
+export const REGEN_DISTILLER_SERVICE_KIND = "regen-distiller";
+/** Archive artifact name shape — the ONLY thing the pager will open. */
+const ARCHIVE_NAME_RE = /^transcript-e\d+-[A-Za-z0-9._:-]+\.jsonl$/;
+const DEFAULT_PAGE_SIZE = 40;
+const MAX_PAGE_SIZE = 100;
+/** Per-entry content clip — keeps a page well inside one tool result. */
+const ENTRY_CLIP = 2_000;
+export function createDistillerTools(opts) {
+    const { catalog, blobStore } = opts;
+    const readTranscriptPage = defineTool("read_transcript_page", {
+        description: "Regen-distiller ONLY: read one page of the archived transcript you were spawned to distill. "
+            + "Call with the archive artifact id from your seed prompt and page=1, then keep incrementing "
+            + "page until has_more is false. Other sessions: this tool always refuses.",
+        parameters: {
+            type: "object",
+            properties: {
+                artifact: {
+                    type: "string",
+                    description: "Archive artifact id (transcript-e<E>-<attemptId>.jsonl) from the seed prompt.",
+                },
+                page: { type: "number", description: "1-based page number." },
+                page_size: { type: "number", description: `Messages per page (default ${DEFAULT_PAGE_SIZE}, max ${MAX_PAGE_SIZE}).` },
+            },
+            required: ["artifact", "page"],
+        },
+        handler: async (params, context) => {
+            const callerId = context?.durableSessionId;
+            if (!callerId)
+                return { error: "read_transcript_page: no session context" };
+            let caller;
+            try {
+                caller = await catalog.getSession(callerId);
+            }
+            catch (err) {
+                return { error: `read_transcript_page: ${err?.message || String(err)}` };
+            }
+            if (!caller || caller.serviceKind !== REGEN_DISTILLER_SERVICE_KIND || !caller.serviceOf) {
+                return { error: "read_transcript_page is reserved for the regen-distiller service session." };
+            }
+            const artifact = String(params.artifact || "").trim();
+            if (!ARCHIVE_NAME_RE.test(artifact)) {
+                return { error: "read_transcript_page: artifact must be a transcript-e<E>-<attemptId>.jsonl archive id." };
+            }
+            const pageSize = Math.max(1, Math.min(MAX_PAGE_SIZE, Number(params.page_size) || DEFAULT_PAGE_SIZE));
+            const page = Math.max(1, Math.floor(Number(params.page) || 1));
+            let body;
+            try {
+                const download = await blobStore.downloadArtifact(caller.serviceOf, artifact);
+                body = download.body;
+            }
+            catch (err) {
+                return { error: `read_transcript_page: archive not readable (${err?.message || String(err)})` };
+            }
+            const lines = body.toString("utf8").split("\n").filter((l) => l.trim());
+            const totalPages = Math.max(1, Math.ceil(lines.length / pageSize));
+            const start = (page - 1) * pageSize;
+            const entries = lines.slice(start, start + pageSize).map((line) => {
+                try {
+                    const evt = JSON.parse(line);
+                    const role = evt.eventType === "user.message"
+                        ? "user"
+                        : evt.eventType === "assistant.message" ? "assistant" : "system";
+                    const content = String(evt?.data?.content ?? "");
+                    return {
+                        seq: evt.seq,
+                        role,
+                        content: content.length > ENTRY_CLIP ? content.slice(0, ENTRY_CLIP) + "…" : content,
+                    };
+                }
+                catch {
+                    return { role: "unparseable", content: line.slice(0, 200) };
+                }
+            });
+            return {
+                page,
+                total_pages: totalPages,
+                total_messages: lines.length,
+                has_more: page < totalPages,
+                entries,
+            };
+        },
+    });
+    return [readTranscriptPage];
+}
+//# sourceMappingURL=distiller-tools.js.map

package/dist/distiller-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"distiller-tools.js","sourceRoot":"","sources":["../src/distiller-tools.ts"],"names":[],"mappings":"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"}

package/dist/footprint.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Session footprint — the "how degraded is this session" sensor
+ * (docs/proposals/session-regen-and-footprint.md §11).
+ *
+ * Control-plane only by construction: every axis is answered from CMS
+ * aggregates, persisted metric summaries, and orchestration runtime stats —
+ * computing a footprint never wakes a dehydrated session.
+ *
+ * The context/compaction counters are DERIVED from persisted SDK transcript
+ * events (`session.usage_info`, `session.compaction_start/_complete` — none
+ * of which are in the ephemeral filter), using the type-scoped event index.
+ * Definitions (per the proposal):
+ *   - compactionCount        completes observed this epoch
+ *   - compactionGeneration   summaries-of-summaries depth. Under infinite
+ *                            sessions the transcript permanently contains a
+ *                            summary after the first compaction, so every
+ *                            subsequent compaction's input includes one:
+ *                            generation = max(0, completes - 1).
+ *   - failedOrStuck          failed completes + starts with no complete
+ *   - sustained utilization  the last SUSTAINED_WINDOW usage readings all
+ *                            above the threshold — never a single reading.
+ */
+import type { SessionCompactionStats, SessionEventStats, SessionMetricSummary } from "./cms.js";
+export declare const FOOTPRINT_UTILIZATION_ELEVATED = 0.7;
+export declare const FOOTPRINT_UTILIZATION_DEGRADED = 0.85;
+export declare const FOOTPRINT_SUSTAINED_WINDOW = 3;
+export declare const FOOTPRINT_GENERATION_DEGRADED = 2;
+export declare const FOOTPRINT_EVENTS_PRUNE_BYTES: number;
+export declare const FOOTPRINT_CACHE_TTL_MS = 15000;
+/** An unmatched compaction start younger than this is RUNNING, not stuck. */
+export declare const FOOTPRINT_STUCK_COMPACTION_MS: number;
+/** Sweep threshold: entries are pruned on write once the cache exceeds this. */
+export declare const FOOTPRINT_CACHE_SWEEP_SIZE = 512;
+export type FootprintLevel = "ok" | "elevated" | "degraded" | "rebuilding";
+export type FootprintRecommendation = "none" | "regenerate" | "prune-events";
+export interface SessionFootprint {
+    sessionId: string;
+    transcriptEpoch: number;
+    regenCount: number;
+    epochAgeDays: number | null;
+    turnsThisEpoch: number | null;
+    context: {
+        tokenLimit: number | null;
+        currentTokens: number | null;
+        utilization: number | null;
+        /** True when the last SUSTAINED_WINDOW readings all exceed the degraded threshold. */
+        sustainedHighUtilization: boolean;
+        compactionCount: number;
+        compactionGeneration: number;
+        tokensRemovedCumulative: number;
+        failedOrStuckCompactions: number;
+    };
+    transcript: {
+        snapshotSizeBytes: number | null;
+        rawSizeBytes: number | null;
+    };
+    events: {
+        count: number;
+        bytes: number;
+        maxSeq: number;
+        sinceEpochStart: number;
+    };
+    facts: {
+        count: number;
+        bytes: number;
+    } | null;
+    children: {
+        descendantCount: number;
+    } | null;
+    orchestration: {
+        historyEventCount?: number;
+        historySizeBytes?: number;
+        queuePendingCount?: number;
+        orchestrationVersion?: string;
+    } | null;
+    /** Regen eligibility read model (§10.2). Advisory; the cmd handler is the authority. */
+    regenEligibility: {
+        eligible: boolean;
+        reason?: string;
+    };
+    assessment: {
+        level: FootprintLevel;
+        reasons: string[];
+        recommendation: FootprintRecommendation;
+    };
+    computedAt: number;
+}
+/** Structural dependencies — satisfied by ManagementClient's catalog + helpers. */
+export interface FootprintSources {
+    getSession(sessionId: string): Promise<{
+        createdAt?: number | Date | null;
+        currentIteration?: number | null;
+        transcriptEpoch?: number | null;
+        lastRegeneratedAt?: number | Date | null;
+    } | null>;
+    getSessionEventStats(sessionId: string, afterSeq?: number): Promise<SessionEventStats>;
+    getSessionCompactionStats(sessionId: string, afterSeq?: number): Promise<SessionCompactionStats>;
+    /** Reverse-ordered read of typed events (existing getSessionEventsBefore proc). */
+    getSessionEventsBefore(sessionId: string, beforeSeq: number, limit?: number, eventTypes?: string[]): Promise<Array<{
+        seq: number;
+        data?: unknown;
+    }>>;
+    getSessionMetricSummary(sessionId: string): Promise<SessionMetricSummary | null>;
+    getDescendantSessionIds?(sessionId: string): Promise<string[]>;
+    getSessionFactsStats?(sessionId: string): Promise<{
+        totalCount: number;
+        totalBytes: number;
+    }>;
+    getOrchestrationStats?(sessionId: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Epoch boundary seq (the session.epoch_committed event) when the session
+     * has regenerated. Absent/0 → epoch 0, whole-session axes. Wired in M1.
+     */
+    getEpochBoundarySeq?(sessionId: string): Promise<number | null>;
+}
+/**
+ * Compute a session's footprint. `notFoundOk` is false: callers should have
+ * resolved the session first; a missing session throws.
+ */
+export declare function computeSessionFootprint(sources: FootprintSources, sessionId: string): Promise<SessionFootprint>;
+export declare class FootprintCache {
+    private readonly ttlMs;
+    private readonly entries;
+    constructor(ttlMs?: number);
+    get(sessionId: string): SessionFootprint | null;
+    set(footprint: SessionFootprint): void;
+    clear(): void;
+}
+//# sourceMappingURL=footprint.d.ts.map

package/dist/footprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"footprint.d.ts","sourceRoot":"","sources":["../src/footprint.ts"],"names":[],"mappings":"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"}

package/dist/footprint.js

@@ -0,0 +1,254 @@
+/**
+ * Session footprint — the "how degraded is this session" sensor
+ * (docs/proposals/session-regen-and-footprint.md §11).
+ *
+ * Control-plane only by construction: every axis is answered from CMS
+ * aggregates, persisted metric summaries, and orchestration runtime stats —
+ * computing a footprint never wakes a dehydrated session.
+ *
+ * The context/compaction counters are DERIVED from persisted SDK transcript
+ * events (`session.usage_info`, `session.compaction_start/_complete` — none
+ * of which are in the ephemeral filter), using the type-scoped event index.
+ * Definitions (per the proposal):
+ *   - compactionCount        completes observed this epoch
+ *   - compactionGeneration   summaries-of-summaries depth. Under infinite
+ *                            sessions the transcript permanently contains a
+ *                            summary after the first compaction, so every
+ *                            subsequent compaction's input includes one:
+ *                            generation = max(0, completes - 1).
+ *   - failedOrStuck          failed completes + starts with no complete
+ *   - sustained utilization  the last SUSTAINED_WINDOW usage readings all
+ *                            above the threshold — never a single reading.
+ */
+// ── Assessment thresholds (exported for tests) ──────────────────
+export const FOOTPRINT_UTILIZATION_ELEVATED = 0.7;
+export const FOOTPRINT_UTILIZATION_DEGRADED = 0.85;
+export const FOOTPRINT_SUSTAINED_WINDOW = 3;
+export const FOOTPRINT_GENERATION_DEGRADED = 2;
+export const FOOTPRINT_EVENTS_PRUNE_BYTES = 64 * 1024 * 1024;
+export const FOOTPRINT_CACHE_TTL_MS = 15_000;
+/** An unmatched compaction start younger than this is RUNNING, not stuck. */
+export const FOOTPRINT_STUCK_COMPACTION_MS = 10 * 60 * 1000;
+/** Sweep threshold: entries are pruned on write once the cache exceeds this. */
+export const FOOTPRINT_CACHE_SWEEP_SIZE = 512;
+/** Sentinel "after everything" seq for reverse event reads. */
+const MAX_SEQ = Number.MAX_SAFE_INTEGER;
+function toEpochMs(value) {
+    if (value == null)
+        return null;
+    if (value instanceof Date)
+        return value.getTime();
+    return Number.isFinite(value) ? Number(value) : null;
+}
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Compute a session's footprint. `notFoundOk` is false: callers should have
+ * resolved the session first; a missing session throws.
+ */
+export async function computeSessionFootprint(sources, sessionId) {
+    const session = await sources.getSession(sessionId);
+    if (!session)
+        throw new Error(`session not found: ${sessionId}`);
+    const transcriptEpoch = finite(session.transcriptEpoch) ?? 0;
+    let boundarySeq = 0;
+    if (transcriptEpoch > 0) {
+        // A regenerated session assessed from WHOLE-SESSION counters would
+        // inherit the dead epoch's degradation — refuse loudly rather than
+        // silently lie (the caller wires getEpochBoundarySeq; its absence or
+        // failure here is a bug, not a fallback).
+        if (!sources.getEpochBoundarySeq) {
+            throw new Error(`footprint: session ${sessionId} is at epoch ${transcriptEpoch} but no epoch boundary source is wired`);
+        }
+        const seq = await sources.getEpochBoundarySeq(sessionId);
+        if (seq == null || seq <= 0) {
+            throw new Error(`footprint: session ${sessionId} is at epoch ${transcriptEpoch} but the epoch boundary seq is unavailable`);
+        }
+        boundarySeq = seq;
+    }
+    const afterSeq = boundarySeq > 0 ? boundarySeq : undefined;
+    const [eventStatsAll, eventStatsEpoch, compaction, usageEvents, summary] = await Promise.all([
+        sources.getSessionEventStats(sessionId),
+        afterSeq != null
+            ? sources.getSessionEventStats(sessionId, afterSeq)
+            : Promise.resolve(null),
+        sources.getSessionCompactionStats(sessionId, afterSeq),
+        sources.getSessionEventsBefore(sessionId, MAX_SEQ, FOOTPRINT_SUSTAINED_WINDOW + 3, [
+            "session.usage_info",
+        ]),
+        sources.getSessionMetricSummary(sessionId),
+    ]);
+    // Optional axes degrade independently — a failure in one never sinks the rest.
+    const [factsResult, descendantsResult, orchResult] = await Promise.allSettled([
+        sources.getSessionFactsStats?.(sessionId) ?? Promise.resolve(null),
+        sources.getDescendantSessionIds?.(sessionId) ?? Promise.resolve(null),
+        sources.getOrchestrationStats?.(sessionId) ?? Promise.resolve(null),
+    ]);
+    // ── context axis from the most recent usage readings ────────
+    const readings = usageEvents
+        .slice()
+        .sort((a, b) => a.seq - b.seq)
+        .map((e) => {
+        const data = (e.data ?? {});
+        const tokenLimit = finite(data.tokenLimit);
+        const currentTokens = finite(data.currentTokens);
+        return tokenLimit != null && currentTokens != null && tokenLimit > 0
+            ? { tokenLimit, currentTokens, utilization: currentTokens / tokenLimit }
+            : null;
+    })
+        .filter((r) => r != null)
+        // Collapse consecutive identical readings: usage_info fires more than
+        // once per turn, and the sustained window must span distinct states,
+        // not one long turn echoing the same number.
+        .filter((r, i, all) => i === 0 || r.currentTokens !== all[i - 1].currentTokens);
+    const latest = readings.length > 0 ? readings[readings.length - 1] : null;
+    const window = readings.slice(-FOOTPRINT_SUSTAINED_WINDOW);
+    const sustainedHighUtilization = window.length >= FOOTPRINT_SUSTAINED_WINDOW &&
+        window.every((r) => r.utilization > FOOTPRINT_UTILIZATION_DEGRADED);
+    // Failed completes inject no summary — they cannot deepen the
+    // summaries-of-summaries chain, so depth counts SUCCEEDED compactions only.
+    const succeeded = Math.max(0, compaction.completes - compaction.failed);
+    const compactionCount = succeeded;
+    const compactionGeneration = Math.max(0, succeeded - 1);
+    // A single unmatched start is a compaction IN FLIGHT until the stuck
+    // timeout passes — without the age gate every live compaction (and,
+    // permanently, one crashed worker) would read degraded.
+    const unmatchedStarts = Math.max(0, compaction.starts - compaction.completes);
+    const newestStartMs = compaction.lastStartAtMs ?? 0;
+    const trailingStartIsStuck = unmatchedStarts > 0 &&
+        (newestStartMs === 0 || Date.now() - newestStartMs > FOOTPRINT_STUCK_COMPACTION_MS);
+    const stuck = trailingStartIsStuck ? unmatchedStarts : Math.max(0, unmatchedStarts - 1);
+    const failedOrStuck = compaction.failed + stuck;
+    // ── assessment ──────────────────────────────────────────────
+    const reasons = [];
+    if (compactionGeneration >= FOOTPRINT_GENERATION_DEGRADED) {
+        reasons.push(`compactionGeneration >= ${FOOTPRINT_GENERATION_DEGRADED}`);
+    }
+    if (sustainedHighUtilization) {
+        reasons.push(`utilization > ${FOOTPRINT_UTILIZATION_DEGRADED} sustained`);
+    }
+    if (failedOrStuck >= 1)
+        reasons.push("failed or stuck compaction");
+    let level;
+    if (reasons.length > 0) {
+        level = "degraded";
+    }
+    else if (compactionCount >= 1 ||
+        (latest != null && latest.utilization > FOOTPRINT_UTILIZATION_ELEVATED)) {
+        level = "elevated";
+        if (compactionCount >= 1)
+            reasons.push("compaction has occurred");
+        if (latest != null && latest.utilization > FOOTPRINT_UTILIZATION_ELEVATED) {
+            reasons.push(`utilization > ${FOOTPRINT_UTILIZATION_ELEVATED}`);
+        }
+    }
+    else {
+        level = "ok";
+    }
+    let recommendation = "none";
+    if (level === "degraded")
+        recommendation = "regenerate";
+    else if (eventStatsAll.dataBytes > FOOTPRINT_EVENTS_PRUNE_BYTES)
+        recommendation = "prune-events";
+    const createdAtMs = toEpochMs(session.createdAt);
+    const lastRegenMs = toEpochMs(session.lastRegeneratedAt);
+    const epochStartMs = transcriptEpoch > 0 ? lastRegenMs : createdAtMs;
+    const epochAgeDays = epochStartMs != null ? (Date.now() - epochStartMs) / (24 * 60 * 60 * 1000) : null;
+    const facts = factsResult.status === "fulfilled" && factsResult.value
+        ? { count: factsResult.value.totalCount, bytes: factsResult.value.totalBytes }
+        : null;
+    const descendants = descendantsResult.status === "fulfilled" && Array.isArray(descendantsResult.value)
+        ? { descendantCount: descendantsResult.value.length }
+        : null;
+    const orchStatsRaw = orchResult.status === "fulfilled" ? orchResult.value : null;
+    const orchestration = orchStatsRaw
+        ? {
+            ...(finite(orchStatsRaw.historyEventCount) != null
+                ? { historyEventCount: Number(orchStatsRaw.historyEventCount) }
+                : {}),
+            ...(finite(orchStatsRaw.historySizeBytes) != null
+                ? { historySizeBytes: Number(orchStatsRaw.historySizeBytes) }
+                : {}),
+            ...(finite(orchStatsRaw.queuePendingCount) != null
+                ? { queuePendingCount: Number(orchStatsRaw.queuePendingCount) }
+                : {}),
+            ...(typeof orchStatsRaw.orchestrationVersion === "string"
+                ? { orchestrationVersion: orchStatsRaw.orchestrationVersion }
+                : {}),
+        }
+        : null;
+    return {
+        sessionId,
+        transcriptEpoch,
+        regenCount: summary?.regenCount ?? transcriptEpoch,
+        epochAgeDays,
+        turnsThisEpoch: finite(session.currentIteration),
+        context: {
+            tokenLimit: latest?.tokenLimit ?? null,
+            currentTokens: latest?.currentTokens ?? null,
+            utilization: latest != null ? Number(latest.utilization.toFixed(4)) : null,
+            sustainedHighUtilization,
+            compactionCount,
+            compactionGeneration,
+            tokensRemovedCumulative: compaction.tokensRemoved,
+            failedOrStuckCompactions: failedOrStuck,
+        },
+        transcript: {
+            snapshotSizeBytes: summary?.snapshotSizeBytes ?? null,
+            rawSizeBytes: summary?.rawSizeBytes ?? null,
+        },
+        events: {
+            count: eventStatsAll.eventCount,
+            bytes: eventStatsAll.dataBytes,
+            maxSeq: eventStatsAll.maxSeq,
+            sinceEpochStart: (eventStatsEpoch ?? eventStatsAll).eventCount,
+        },
+        facts,
+        children: descendants,
+        orchestration,
+        // Regeneration ships in M1; until then the read model reports it plainly.
+        regenEligibility: { eligible: false, reason: "not_available" },
+        assessment: { level, reasons, recommendation },
+        computedAt: Date.now(),
+    };
+}
+// ── TTL cache ───────────────────────────────────────────────────
+//
+// TTL-only by design: no cross-process invalidation is claimed — checking
+// max seq is itself a query, and every consumer tolerates seconds of
+// staleness. A maintained aggregate row is the upgrade path if this bites.
+export class FootprintCache {
+    ttlMs;
+    entries = new Map();
+    constructor(ttlMs = FOOTPRINT_CACHE_TTL_MS) {
+        this.ttlMs = ttlMs;
+    }
+    get(sessionId) {
+        const entry = this.entries.get(sessionId);
+        if (!entry)
+            return null;
+        if (Date.now() - entry.at > this.ttlMs) {
+            this.entries.delete(sessionId);
+            return null;
+        }
+        return entry.value;
+    }
+    set(footprint) {
+        if (this.entries.size > FOOTPRINT_CACHE_SWEEP_SIZE) {
+            const cutoff = Date.now() - this.ttlMs;
+            for (const [key, entry] of this.entries) {
+                if (entry.at < cutoff)
+                    this.entries.delete(key);
+            }
+            // Pathological churn (fleet-wide pollers): hard reset beats growth.
+            if (this.entries.size > FOOTPRINT_CACHE_SWEEP_SIZE * 8)
+                this.entries.clear();
+        }
+        this.entries.set(footprint.sessionId, { at: Date.now(), value: footprint });
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+//# sourceMappingURL=footprint.js.map

package/dist/footprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"footprint.js","sourceRoot":"","sources":["../src/footprint.ts"],"names":[],"mappings":"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"}

package/dist/inspect-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inspect-tools.d.ts","sourceRoot":"","sources":["../src/inspect-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,UAAU,CAAC;AAsF7D,MAAM,WAAW,yBAAyB;IACtC,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,GAAG,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,kBAAkB,EAAE,SAAS,CAAC;CACpD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAoiC/E"}
+{"version":3,"file":"inspect-tools.d.ts","sourceRoot":"","sources":["../src/inspect-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,UAAU,CAAC;AA0F7D,MAAM,WAAW,yBAAyB;IACtC,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,GAAG,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,kBAAkB,EAAE,SAAS,CAAC;CACpD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAomC/E"}

package/dist/inspect-tools.js

@@ -20,6 +20,7 @@
  * @internal
  */
 import { defineTool } from "@github/copilot-sdk";
+import { computeSessionFootprint, FootprintCache } from "./footprint.js";
 import { isEnhancedFactStore } from "./facts-store.js";
 import { formatOwnerBucketLabel, formatSessionOwnerLabel, getSessionOwnerKind, matchesOwnerBucketFilters, matchesSessionOwnerFilters } from "./session-owner-utils.js";
 const TUNER_AGENT_ID = "agent-tuner";
@@ -32,6 +33,8 @@ const SYSTEM_AGENT_IDS = new Set([
 ]);
 const DEFAULT_LIMIT = 50;
 const MAX_LIMIT = 200;
+/** Shared TTL cache for the context_health tool (per worker process). */
+const contextHealthCache = new FootprintCache();
 const MAX_DATA_BYTES = 4 * 1024;
 const MAX_RESPONSE_BYTES = 64 * 1024;
 function normalizeSessionId(raw) {
@@ -838,11 +841,68 @@ export function createInspectTools(opts) {
         readSessionGraphNodeUsageTool,
         readSessionGraphEdgeSearchUsageTool,
     ];
+    // context_health is a SELF-scoped footprint sensor: it reads the CALLER's
+    // own session (ctx.sessionId) and returns epoch, turns-this-epoch, context
+    // utilization, compaction depth, transcript/event sizes and an ok/elevated/
+    // degraded assessment. Every agent needs it to detect its own degradation
+    // and decide whether to regenerate — so it must ship to ordinary
+    // (non-system) sessions, not just the tuner. Defined before the tool-set
+    // branches so all return paths can include it.
+    const contextHealthTool = defineTool("context_health", {
+        description: "Check YOUR OWN context health: transcript epoch, token utilization, compaction depth "
+            + "(summaries-of-summaries), event-log and snapshot sizes, and an overall assessment "
+            + "(ok / elevated / degraded) with a recommendation. This is the regeneration/footprint "
+            + "sensor — call it when asked for regen or context stats, when you have been running a "
+            + "long time, notice yourself losing track of earlier work, or want to decide whether to "
+            + "regenerate your context at a natural boundary. Cheap (control-plane, cached).",
+        parameters: { type: "object", properties: {} },
+        handler: async (_args, ctx) => {
+            const sessionId = ctx?.sessionId;
+            if (!sessionId)
+                return { error: "context_health: caller session id is required" };
+            try {
+                const cached = contextHealthCache.get(sessionId);
+                const footprint = cached ?? await computeSessionFootprint({
+                    getSession: (id) => catalog.getSession(id),
+                    getSessionEventStats: (id, afterSeq) => catalog.getSessionEventStats(id, afterSeq),
+                    getSessionCompactionStats: (id, afterSeq) => catalog.getSessionCompactionStats(id, afterSeq),
+                    getSessionEventsBefore: (id, beforeSeq, limit, eventTypes) => catalog.getSessionEventsBefore(id, beforeSeq, limit, eventTypes),
+                    getSessionMetricSummary: (id) => catalog.getSessionMetricSummary(id),
+                    getEpochBoundarySeq: async (id) => {
+                        const rows = await catalog.getSessionEventsBefore(id, Number.MAX_SAFE_INTEGER, 1, ["session.epoch_committed"]);
+                        return rows.length > 0 ? Number(rows[0].seq) : null;
+                    },
+                }, sessionId);
+                if (!cached)
+                    contextHealthCache.set(footprint);
+                const { assessment } = footprint;
+                const recommendationText = assessment.level === "degraded"
+                    ? "Consider calling regenerate_context at a natural boundary (finish the current step first)."
+                    : assessment.level === "elevated"
+                        ? "Context is aging but workable. Re-anchor on facts if you feel unsure about earlier work."
+                        : "Context is healthy. No action needed.";
+                return {
+                    sessionId: footprint.sessionId,
+                    transcriptEpoch: footprint.transcriptEpoch,
+                    epochAgeDays: footprint.epochAgeDays,
+                    turnsThisEpoch: footprint.turnsThisEpoch,
+                    context: footprint.context,
+                    transcript: footprint.transcript,
+                    events: footprint.events,
+                    assessment,
+                    recommendation: recommendationText,
+                };
+            }
+            catch (err) {
+                return { error: `context_health: ${err?.message || String(err)}` };
+            }
+        },
+    });
     if (!isSystemAgent) {
-        return [readAgentEventsTool, ...lineageRetrievalTools];
+        return [readAgentEventsTool, contextHealthTool, ...lineageRetrievalTools];
     }
     if (!isTuner) {
-        return [readAgentEventsTool, ...systemReadTools, ...lineageRetrievalTools];
+        return [readAgentEventsTool, contextHealthTool, ...systemReadTools, ...lineageRetrievalTools];
     }
     const factsTools = [];
     if (factStore) {
@@ -966,6 +1026,7 @@ export function createInspectTools(opts) {
     }
     const tools = [
         readAgentEventsTool,
+        contextHealthTool,
         ...systemReadTools,
         readSessionMetricSummaryTool,
         readSessionTokensByModelTool,