@davidorex/pi-jit-agents 0.14.6

package/dist/errors.js

@@ -0,0 +1,56 @@
+/**
+ * Typed errors for pi-jit-agents.
+ *
+ * Each error carries enough context for consumer error messages without
+ * requiring the consumer to know anything about internal paths or state.
+ */
+/** Thrown when an agent spec file is not found in any discovery tier. */
+export class AgentNotFoundError extends Error {
+    agentName;
+    searchPaths;
+    constructor(agentName, searchPaths) {
+        const pathList = searchPaths.map((p) => `  - ${p}`).join("\n");
+        super(`Agent '${agentName}' not found. Searched:\n${pathList}`);
+        this.name = "AgentNotFoundError";
+        this.agentName = agentName;
+        this.searchPaths = searchPaths;
+    }
+}
+/** Thrown when an agent spec file exists but cannot be read or parsed. */
+export class AgentParseError extends Error {
+    agentName;
+    filePath;
+    cause;
+    constructor(agentName, filePath, cause) {
+        super(`Agent '${agentName}' at ${filePath}: ${cause.message}`);
+        this.name = "AgentParseError";
+        this.agentName = agentName;
+        this.filePath = filePath;
+        this.cause = cause;
+    }
+}
+/** Thrown when compileAgent cannot produce any prompt content. */
+export class AgentCompileError extends Error {
+    agentName;
+    cause;
+    constructor(agentName, message, cause) {
+        super(`Agent '${agentName}' compile failed: ${message}`);
+        this.name = "AgentCompileError";
+        this.agentName = agentName;
+        this.cause = cause;
+    }
+}
+/** Thrown when executeAgent fails or is cancelled. */
+export class AgentDispatchError extends Error {
+    agentName;
+    stopReason;
+    cause;
+    constructor(agentName, message, opts) {
+        super(`Agent '${agentName}' dispatch failed: ${message}`);
+        this.name = "AgentDispatchError";
+        this.agentName = agentName;
+        this.stopReason = opts?.stopReason;
+        this.cause = opts?.cause;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yEAAyE;AACzE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC5B,SAAS,CAAS;IAClB,WAAW,CAAW;IAEtC,YAAY,SAAiB,EAAE,WAAqB;QACnD,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/D,KAAK,CAAC,UAAU,SAAS,2BAA2B,QAAQ,EAAE,CAAC,CAAC;QAChE,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IAChC,CAAC;CACD;AAED,0EAA0E;AAC1E,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACzB,SAAS,CAAS;IAClB,QAAQ,CAAS;IACjB,KAAK,CAAQ;IAE7B,YAAY,SAAiB,EAAE,QAAgB,EAAE,KAAY;QAC5D,KAAK,CAAC,UAAU,SAAS,QAAQ,QAAQ,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;CACD;AAED,kEAAkE;AAClE,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC3B,SAAS,CAAS;IAClB,KAAK,CAAS;IAE9B,YAAY,SAAiB,EAAE,OAAe,EAAE,KAAa;QAC5D,KAAK,CAAC,UAAU,SAAS,qBAAqB,OAAO,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;CACD;AAED,sDAAsD;AACtD,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC5B,SAAS,CAAS;IAClB,UAAU,CAAU;IACpB,KAAK,CAAS;IAE9B,YAAY,SAAiB,EAAE,OAAe,EAAE,IAA6C;QAC5F,KAAK,CAAC,UAAU,SAAS,sBAAsB,OAAO,EAAE,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,IAAI,EAAE,UAAU,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC;IAC1B,CAAC;CACD"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @davidorex/pi-jit-agents — Agent spec compilation and in-process dispatch runtime.
+ *
+ * Owns everything between "I have a spec" and "I have a typed result."
+ * See docs/planning/jit-agents-spec.md for the boundary contract and principles.
+ */
+export { createAgentLoader, parseAgentYaml } from "./agent-spec.js";
+export type { AgentTraceQuery } from "./agent-trace-sdk.js";
+export { agentTrace, agentTraceChildren, agentTraceEntry } from "./agent-trace-sdk.js";
+export { compileAgent } from "./compile.js";
+export * from "./errors.js";
+export { agentContract } from "./introspect.js";
+export type { CompleteFn, NormalizedToolChoice } from "./jit-runtime.js";
+export { buildPhantomTool, executeAgent, normalizeToolChoice } from "./jit-runtime.js";
+export type { TemplateEnvContext } from "./template.js";
+export { createTemplateEnv, renderTemplate, renderTemplateFile } from "./template.js";
+export type { RedactionConfig, RedactionPattern } from "./trace-redactor.js";
+export { BUILTIN_PATTERNS, loadProjectRedactionConfig, redactLlmResponse, redactSensitiveData, } from "./trace-redactor.js";
+export type { WriteTraceOptions } from "./trace-writer.js";
+export { dateRotatedPath, writeAgentTrace } from "./trace-writer.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvF,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACtF,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE7E,OAAO,EACN,gBAAgB,EAChB,0BAA0B,EAC1B,iBAAiB,EACjB,mBAAmB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACrE,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @davidorex/pi-jit-agents — Agent spec compilation and in-process dispatch runtime.
+ *
+ * Owns everything between "I have a spec" and "I have a typed result."
+ * See docs/planning/jit-agents-spec.md for the boundary contract and principles.
+ */
+export { createAgentLoader, parseAgentYaml } from "./agent-spec.js";
+export { agentTrace, agentTraceChildren, agentTraceEntry } from "./agent-trace-sdk.js";
+export { compileAgent } from "./compile.js";
+export * from "./errors.js";
+export { agentContract } from "./introspect.js";
+export { buildPhantomTool, executeAgent, normalizeToolChoice } from "./jit-runtime.js";
+export { createTemplateEnv, renderTemplate, renderTemplateFile } from "./template.js";
+// Trace subsystem (issue-023)
+export { BUILTIN_PATTERNS, loadProjectRedactionConfig, redactLlmResponse, redactSensitiveData, } from "./trace-redactor.js";
+export { dateRotatedPath, writeAgentTrace } from "./trace-writer.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvF,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEtF,8BAA8B;AAC9B,OAAO,EACN,gBAAgB,EAChB,0BAA0B,EAC1B,iBAAiB,EACjB,mBAAmB,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACrE,cAAc,YAAY,CAAC"}

package/dist/introspect.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Agent contract introspection — projection of an AgentSpec for SDK queries.
+ *
+ * Implements the introspection surface of the jit-agents boundary contract
+ * (jit-agents-spec.md §2). Consumers ask "what does this agent accept and
+ * produce" without dispatching it.
+ */
+import type { AgentContract, AgentSpec } from "./types.js";
+/**
+ * Project an AgentSpec into an AgentContract.
+ *
+ * Internal fields (loadedFrom, inline prompt text, template paths) are not
+ * exposed. Only the contract-relevant fields: name, role, input schema,
+ * context block declarations, output format and schema.
+ */
+export declare function agentContract(spec: AgentSpec): AgentContract;
+//# sourceMappingURL=introspect.d.ts.map

package/dist/introspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspect.d.ts","sourceRoot":"","sources":["../src/introspect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,CAQ5D"}

package/dist/introspect.js

@@ -0,0 +1,22 @@
+/**
+ * Project an AgentSpec into an AgentContract.
+ *
+ * Internal fields (loadedFrom, inline prompt text, template paths) are not
+ * exposed. Only the contract-relevant fields: name, role, input schema,
+ * context block declarations, output format and schema.
+ */
+export function agentContract(spec) {
+    const contract = { name: spec.name };
+    if (spec.role !== undefined)
+        contract.role = spec.role;
+    if (spec.inputSchema !== undefined)
+        contract.inputSchema = spec.inputSchema;
+    if (spec.contextBlocks !== undefined)
+        contract.contextBlocks = spec.contextBlocks;
+    if (spec.outputFormat !== undefined)
+        contract.outputFormat = spec.outputFormat;
+    if (spec.outputSchema !== undefined)
+        contract.outputSchema = spec.outputSchema;
+    return contract;
+}
+//# sourceMappingURL=introspect.js.map

package/dist/introspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspect.js","sourceRoot":"","sources":["../src/introspect.ts"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAe;IAC5C,MAAM,QAAQ,GAAkB,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IACpD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS;QAAE,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;IAC5E,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS;QAAE,QAAQ,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;IAClF,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;QAAE,QAAQ,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IAC/E,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;QAAE,QAAQ,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IAC/E,OAAO,QAAQ,CAAC;AACjB,CAAC"}

package/dist/jit-runtime.d.ts

@@ -0,0 +1,106 @@
+import type { Api, Tool } from "@mariozechner/pi-ai";
+import { complete as piAiComplete } from "@mariozechner/pi-ai";
+import type { CompiledAgent, DispatchContext, JitAgentResult } from "./types.js";
+/**
+ * Injection point for the pi-ai `complete` function. Defaults to the real
+ * implementation. Tests override via the optional `completeFn` parameter on
+ * `executeAgent`.
+ */
+export type CompleteFn = typeof piAiComplete;
+/**
+ * Build a phantom Tool from a JSON Schema file for forced structured output.
+ *
+ * For the common shape (top-level `type: object` with `required` and
+ * `properties` where each property has a primitive `type` and optional
+ * `enum`), produces a TypeBox Type.Object matching the schema. Complex shapes
+ * (allOf, anyOf, conditional) fall back to a relaxed Type.Object that accepts
+ * any object — post-hoc validation via `validateFromFile` catches violations.
+ *
+ * The tool is never executed — it exists only as a schema constraint that
+ * pi-ai enforces via forced toolChoice.
+ */
+export declare function buildPhantomTool(schemaPath: string, toolName?: string, description?: string): Tool;
+/**
+ * Provider-aware shape returned by `normalizeToolChoice`. The type union
+ * covers every shape that any pi-ai 0.70.2 driver currently honors for
+ * forced structured output:
+ *
+ *   - Anthropic-native object form (anthropic-messages, bedrock-converse-stream)
+ *   - OpenAI-compatible function form (openai-completions, mistral-conversations,
+ *     and the canonical shape for openai-responses / openai-codex-responses /
+ *     azure-openai-responses if/when those drivers begin honoring toolChoice)
+ *   - Google string-mode form (google-generative-ai, google-gemini-cli,
+ *     google-vertex) — only `"any"` is emitted; specific-tool pinning is
+ *     not exposed by the Google providers in pi-ai 0.70.2
+ *
+ * pi-ai itself accepts any `unknown` here (toolChoice rides on the
+ * `Record<string, unknown>` half of `ProviderStreamOptions`); the explicit
+ * union exists for callers that want compile-time discrimination of the
+ * normalization output.
+ */
+export type NormalizedToolChoice = {
+    type: "tool";
+    name: string;
+} | {
+    type: "function";
+    function: {
+        name: string;
+    };
+} | "any";
+/**
+ * Map a pi-ai `Api` kind plus a phantom tool name to the `toolChoice` shape
+ * the corresponding driver expects.
+ *
+ * This is the architectural normalization point referenced by ADR-0003: the
+ * forced-toolChoice protocol divergence across Anthropic / OpenAI-compatible
+ * / Google providers is collapsed here, not at each consumer call site.
+ *
+ * Coverage map (pi-ai 0.70.2 — verified against
+ * `node_modules/@mariozechner/pi-ai/dist/providers/*`):
+ *
+ *   - `anthropic-messages` — passes object through unchanged. Anthropic
+ *     Messages API expects `{type:"tool", name}`.
+ *   - `bedrock-converse-stream` — accepts `{type:"tool", name}` and translates
+ *     internally to Bedrock Converse's `{tool:{name}}` shape (driver line
+ *     611-612 of amazon-bedrock.js).
+ *   - `openai-completions` — passthrough. OpenAI / OpenRouter / OpenAI-
+ *     compatible gateways expect `{type:"function", function:{name}}` or
+ *     string `"required"`. Mismatch here is the proximate cause of the
+ *     "Tool '' not found in provided tools" 400 surfaced post-7edf3a2.
+ *   - `mistral-conversations` — driver passes the object through its own
+ *     `mapToolChoice` which reads `choice.function.name`, so the OpenAI-
+ *     compatible function form is required.
+ *   - `openai-responses`, `openai-codex-responses`, `azure-openai-responses`
+ *     — pi-ai 0.70.2 drivers do NOT honor `options.toolChoice` (codex hard-
+ *     codes `tool_choice: "auto"`; the other two drop it entirely). The
+ *     OpenAI-compatible function form is emitted here as the canonical
+ *     shape for the day pi-ai begins forwarding it; today the value is
+ *     ignored and forced toolChoice is unenforceable on these drivers.
+ *     Tracked as a pi-ai upstream gap; do not paper over here.
+ *   - `google-generative-ai`, `google-gemini-cli`, `google-vertex` — drivers
+ *     accept only string `"any" | "auto" | "none"` (mapped to FunctionCalling-
+ *     ConfigMode). Specific-tool pinning is not exposed. `"any"` forces
+ *     tool use; adequate for the phantom-tool single-tool pattern (the model
+ *     has only one tool to call) but fails to pin a specific tool when
+ *     multiple tools are present.
+ *   - Unknown / custom api strings — Anthropic-format default. Matches the
+ *     pre-fix behavior that worked end-to-end for `anthropic-messages` and
+ *     preserves backward compatibility for any consumer that registered a
+ *     custom api provider expecting that shape.
+ */
+export declare function normalizeToolChoice(api: Api, toolName: string): NormalizedToolChoice;
+/**
+ * Execute a compiled agent in-process.
+ *
+ * When `compiled.outputSchema` is set: build a phantom tool from the schema,
+ * call pi-ai's `complete` with forced toolChoice, extract ToolCall.arguments,
+ * and validate post-hoc against the schema file.
+ *
+ * When `compiled.outputSchema` is absent: call `complete` without tools and
+ * return the extracted text as `output`.
+ *
+ * Test hook: `completeFn` overrides the pi-ai `complete` import for unit
+ * tests that do not make real LLM calls.
+ */
+export declare function executeAgent(compiled: CompiledAgent, dispatch: DispatchContext, completeFn?: CompleteFn): Promise<JitAgentResult>;
+//# sourceMappingURL=jit-runtime.d.ts.map

package/dist/jit-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jit-runtime.d.ts","sourceRoot":"","sources":["../src/jit-runtime.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,GAAG,EAAkD,IAAI,EAAY,MAAM,qBAAqB,CAAC;AAC/G,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAQ,MAAM,qBAAqB,CAAC;AAUrE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAwJjF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,YAAY,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC/B,UAAU,EAAE,MAAM,EAClB,QAAQ,SAAe,EACvB,WAAW,SAA4B,GACrC,IAAI,CASN;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,oBAAoB,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAChD,KAAK,CAAC;AAET;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAkBpF;AAyFD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CACjC,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,eAAe,EACzB,UAAU,GAAE,UAAyB,GACnC,OAAO,CAAC,cAAc,CAAC,CAoSzB"}