@davidorex/pi-jit-agents 0.14.6 → 0.26.0

package/dist/types.d.ts

@@ -4,8 +4,11 @@
  * Implements the jit-agents-spec.md §2 boundary contract: four public surfaces
  * (load, compile, execute, introspect) with typed inputs and outputs.
  */
-import type { Api, AssistantMessage, Model } from "@mariozechner/pi-ai";
+import type { ItemLocation } from "@davidorex/pi-context";
+import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
 import type nunjucks from "nunjucks";
+import type { BudgetWarning } from "./budget-enforcer.js";
+import type { RendererRegistry } from "./renderer-registry.js";
 /**
  * A loaded agent specification.
  *
@@ -39,13 +42,50 @@ export interface AgentSpec {
      * against the invocation cwd.
      */
     outputSchema?: string;
-    contextBlocks?: string[];
+    /**
+     * Block-context references injected into the agent's template environment.
+     *
+     * Two element shapes are accepted:
+     *
+     * - **Bare string** (e.g. `"requirements"`): whole-block injection — the
+     *   entire `.project/<name>.json` payload is read at compile time and
+     *   surfaced to the template under `_<name>`. This is the established
+     *   surface and remains unchanged for existing specs.
+     *
+     * - **Object** ({@link ContextBlockRef}): per-item or scoped injection —
+     *   declares a specific item id and/or kind-specific focus hints to be
+     *   resolved by the compile-time injector. Plan 4 (Wave 2) owns the
+     *   resolution semantics; the parser only typechecks the shape here.
+     */
+    contextBlocks?: (string | ContextBlockRef)[];
     /**
      * Directory the spec was loaded from. Internal use — exposed on the type
      * for tier-aware operations but never relied on by consumers directly.
      */
     readonly loadedFrom: string;
 }
+/**
+ * Typed object form for {@link AgentSpec.contextBlocks} entries.
+ *
+ * Bare-string entries in `contextBlocks` denote whole-block injection
+ * (existing behaviour); object entries denote per-item or scoped injection
+ * — the surface Plan 4 (Wave 2) consumes to inject specific block items
+ * (e.g. one decision, one feature) rather than entire blocks.
+ *
+ * `compileAgent` does not yet honour these fields; this interface defines
+ * the parsing-time contract only. Plan 4 wires resolution through the
+ * cross-block resolver and per-item macros.
+ */
+export interface ContextBlockRef {
+    /** Block name, e.g. "decisions", "features". Required. */
+    name: string;
+    /** Optional ID of a specific item to inject. Plan 4 resolves via cross-block resolver. */
+    item?: string;
+    /** Optional kind-specific scope hints (e.g., { story: "STORY-001" }). Plan 4 passes through to macros. */
+    focus?: Record<string, string>;
+    /** Optional traversal depth. 0 = bare-ID refs (default), 1 = inline direct, 2+ recurse. */
+    depth?: number;
+}
 /**
  * Options for loadAgent / createAgentLoader.
  *
@@ -66,6 +106,10 @@ export interface LoadContext {
 }
 /**
  * Options for compileAgent.
+ *
+ * Plan 4 (Wave 2) extends this with two optional fields supporting object-form
+ * `contextBlocks` resolution. Both default to internal lazy construction when
+ * absent so existing callers (string-only `contextBlocks`) require no changes.
  */
 export interface CompileContext {
     /** Nunjucks environment from createTemplateEnv — used to render template references. */
@@ -74,6 +118,22 @@ export interface CompileContext {
     input: unknown;
     /** Project root. Used for `.project/` block reads during contextBlocks injection. */
     cwd: string;
+    /**
+     * Optional renderer registry for per-item macro resolution. When absent,
+     * object-form `contextBlocks` entries still inject the resolved item under
+     * `_<name>_item`, but the `render_recursive` Nunjucks global cannot
+     * dispatch — recursive rendering returns a `[unrendered: <kind>/<id>]`
+     * fallback marker rather than throwing.
+     */
+    rendererRegistry?: RendererRegistry;
+    /**
+     * Optional pre-built ID index. When absent and any object-form
+     * `contextBlocks` entry needs item resolution (or the `resolve`/
+     * `render_recursive` Nunjucks globals are invoked), `compileAgent` builds
+     * one on demand via `buildIdIndex(cwd)`. Callers performing many compiles
+     * in one pass should build once and pass it in for reuse.
+     */
+    idIndex?: Map<string, ItemLocation>;
 }
 /**
  * A compiled agent ready for dispatch.
@@ -102,6 +162,24 @@ export interface CompiledAgent {
      * inspection, not the rendered string.
      */
     contextValues: Record<string, unknown>;
+    /**
+     * Optional list of budget-truncation warnings collected during compile.
+     *
+     * Populated by the `enforceBudget` Nunjucks global registered by
+     * `compileAgent`: every macro invocation that exceeds the field's
+     * `x-prompt-budget` annotation appends one entry naming the field path,
+     * the declared budget, the actual measured token/word counts, and whether
+     * truncation was applied. Surfaces composition-time prompt-size signals
+     * to callers without breaking existing consumers (optional field; absent
+     * when no enforceBudget call has produced a warning during this compile).
+     *
+     * Distinct from runtime errors — a warning here means the rendered prompt
+     * is fully formed but a budgeted field carried more text than its
+     * annotation declared. The truncated text appears in the rendered prompt
+     * with the `[…truncated to budget]` marker; this array preserves the
+     * full warning record for trace / inspection consumers.
+     */
+    budgetWarnings?: BudgetWarning[];
 }
 /**
  * Dispatch-time context for executeAgent.
@@ -128,7 +206,7 @@ export interface DispatchContext {
     /**
      * Optional path to a project-extension trace redaction config
      * (`.workflows/monitors/<name>/trace-config.json` shape). When set,
-     * `loadProjectRedactionConfig` is invoked once per executeAgent call and
+     * `loadContextRedactionConfig` is invoked once per executeAgent call and
      * the resulting custom patterns are layered atop `BUILTIN_PATTERNS` for
      * every redacted field. When unset / null, only the builtin pattern set
      * applies. Independent of `tracePath` — config loading is a no-op when
@@ -178,7 +256,7 @@ export interface AgentContract {
     name: string;
     role?: string;
     inputSchema?: Record<string, unknown>;
-    contextBlocks?: string[];
+    contextBlocks?: (string | ContextBlockRef)[];
     outputFormat?: "json" | "text";
     outputSchema?: string;
 }

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davidorex/pi-jit-agents",
-	"version": "0.14.6",
+	"version": "0.26.0",
 	"description": "Agent spec compilation and in-process dispatch runtime — the package that owns everything between 'I have a spec' and 'I have a typed result'",
 	"license": "MIT",
 	"author": "David Ryan",
@@ -58,8 +58,8 @@
 		"test": "tsx --test src/*.test.ts"
 	},
 	"dependencies": {
-		"@davidorex/pi-project": "^0.14.6",
-		"@mariozechner/pi-ai": "^0.70.2",
+		"@davidorex/pi-context": "^0.26.0",
+		"@earendil-works/pi-ai": "^0.75.4",
 		"nunjucks": "^3.2.4",
 		"proper-lockfile": "^4.1.2",
 		"yaml": "^2.7.1"
@@ -67,5 +67,8 @@
 	"devDependencies": {
 		"@types/nunjucks": "^3.2.6",
 		"@types/proper-lockfile": "^4.1.4"
+	},
+	"engines": {
+		"node": ">=22.19.0"
 	}
 }