@astrosheep/pi-context 0.13.0 → 0.15.0

package/src/tool-schema.ts

@@ -1,8 +1,24 @@
 import { Type } from "@earendil-works/pi-ai";
 export const nullableString = () => Type.Optional(Type.Union([Type.String(), Type.Null()]));
-export const nullableInteger = () => Type.Optional(Type.Union([Type.Integer(), Type.Null()]));
 export const positiveInteger = () => Type.Optional(Type.Integer({ minimum: 1 }));
 export const cursor = () => Type.Optional(Type.Integer({ minimum: 0, description: "Continuation cursor: pass the previous next_cursor back unchanged, with the same filters and ordering. Omit to start. next_cursor is null only when the set is exhausted." }));
 export const recentFirst = () => Type.Optional(Type.Boolean({ description: "Return newest-first. Only an explicit false returns oldest-first. Defaults to true." }));
-export const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()]);
+/** Role filter. `developer` is the known author for this extension's own custom entries. */
+export const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()], { description: "Filter by the entry's known author: user/assistant/tool from the conversation, system for native Pi compaction summaries, developer for entries this extension authored (its boot, guidance, warning, and continuation messages, its reset-window compaction summaries, and any other pi-context/* entry)." });
+
+/** Search query parameter: one literal, or several literals combined with OR. */
+export const searchQuery = () => Type.Union([Type.String(), Type.Array(Type.String(), { minItems: 1 })]);
+
+/**
+ * Normalize a search `query` parameter into the literal needles to match.
+ * A bare string is a one-element list, so single-query behavior is unchanged.
+ * An empty list or a non-string element is refused rather than silently searching
+ * for nothing: an empty array is an argument error, not an empty result set.
+ */
+export function searchQueries(query: unknown): string[] {
+	if (typeof query === "string") return [query];
+	if (!Array.isArray(query) || query.length === 0) throw new Error("query must be a string or a non-empty array of strings");
+	if (!query.every((candidate) => typeof candidate === "string")) throw new Error("query array elements must be strings");
+	return query as string[];
+}
 

package/src/warning.ts

@@ -0,0 +1,46 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { WARNING_TYPE, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG, WARNING_PROMPT } from "./protocol.js";
+import { thresholdsFor, resetThresholds, type ResolvedThresholds } from "./thresholds.js";
+import { hasWindowMessage, currentWindowId } from "./history.js";
+
+/**
+ * The final checkpoint warning, steered to the model once per window. Like the early
+ * reminder, the steer text is model-facing only (display: false); the human learns
+ * about it from the warning-level notify, not from a chat-visible message.
+ */
+
+/** Trigger: does the steer fire at this remaining-token count? Pure. */
+export function warningDue(remaining: number, thresholds: ResolvedThresholds): boolean {
+	return remaining <= thresholds.warning;
+}
+
+/** Delivery: what happens when it fires. */
+export function steerWarning(pi: ExtensionAPI, ctx: ExtensionContext, thresholds: ResolvedThresholds, remaining: number): void {
+	pi.sendMessage({ customType: WARNING_TYPE, content: `${GUIDANCE_OPEN_TAG}\n${WARNING_PROMPT}\n${GUIDANCE_CLOSE_TAG}`, display: false }, { triggerTurn: true });
+	ctx.ui.notify(`pi-context: context budget critical (${Math.max(0, remaining - thresholds.reserve)} tokens before reserve) — final checkpoint warning steered to the model.`, "warning");
+}
+
+/** Registration: once-per-window guard plus trigger+delivery on the context hook. */
+export function registerWarning(pi: ExtensionAPI, isEnabled: () => boolean): void {
+	let firedInWindow: string | undefined;
+	// Threshold resolution is owned by budget.ts; this module only consumes the shared
+	// cache (lazily on the context hook) so session_start never warns twice.
+	pi.on("session_start", () => { firedInWindow = undefined; });
+	pi.on("session_tree", () => { firedInWindow = undefined; resetThresholds(); });
+	pi.on("context", (_event, ctx) => {
+		const windowId = currentWindowId(ctx);
+		if (!isEnabled() || firedInWindow === windowId || hasWindowMessage(ctx, WARNING_TYPE)) return undefined;
+		const usage = ctx.getContextUsage();
+		if (!usage || usage.tokens === null) return undefined;
+		const remaining = Math.max(0, usage.contextWindow - usage.tokens);
+		const thresholds = thresholdsFor(ctx);
+		if (!warningDue(remaining, thresholds)) return undefined;
+		firedInWindow = windowId;
+		// The steer reaches the model at the next sampling step with at most the runway
+		// of invisible budget left. After it, the model decides for itself: end the
+		// window, or ride it into Pi's automatic compaction, which resets on the spot
+		// with no turn (see reset-lifecycle).
+		steerWarning(pi, ctx, thresholds, remaining);
+		return undefined;
+	});
+}