@davidorex/pi-jit-agents 0.14.6

package/dist/template.js

@@ -0,0 +1,78 @@
+/**
+ * Nunjucks template environment and rendering.
+ *
+ * Implements D3 (no .pi/ reads) for the template discovery side. The template
+ * search mirrors the agent-spec three-tier pattern:
+ *   1. {cwd}/.project/templates/
+ *   2. {userDir ?? ~/.pi/agent/templates/}
+ *   3. {builtinDir}   (only when supplied)
+ *
+ * Autoescape is disabled (agents render markdown, not HTML). throwOnUndefined
+ * is disabled (templates may reference optional context without error).
+ *
+ * `${{ }}` workflow expressions are protected from Nunjucks interpretation
+ * by escape-and-restore. This preserves the invariant that workflow-level
+ * expression resolution happens at workflow dispatch time, not at agent
+ * compile time.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import nunjucks from "nunjucks";
+/**
+ * Create a Nunjucks environment with three-tier template discovery.
+ *
+ * Returns a no-op loader environment (plain strings pass through) when no
+ * tier directory exists. This is not an error — an agent with an entirely
+ * inline prompt uses no templates at all.
+ */
+export function createTemplateEnv(ctx) {
+    const projectDir = path.join(ctx.cwd, ".project", "templates");
+    const userDir = ctx.userDir ?? path.join(os.homedir(), ".pi", "agent", "templates");
+    const searchPaths = [];
+    if (fs.existsSync(projectDir))
+        searchPaths.push(projectDir);
+    if (fs.existsSync(userDir))
+        searchPaths.push(userDir);
+    if (ctx.builtinDir && fs.existsSync(ctx.builtinDir))
+        searchPaths.push(ctx.builtinDir);
+    const loader = searchPaths.length > 0 ? new nunjucks.FileSystemLoader(searchPaths) : undefined;
+    return new nunjucks.Environment(loader, {
+        autoescape: false,
+        throwOnUndefined: false,
+    });
+}
+/** Sentinel used to protect `${{ }}` workflow expressions from Nunjucks rendering. */
+const WORKFLOW_EXPR_PLACEHOLDER = "\x00__PI_WORKFLOW_EXPR__";
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Render a template string through Nunjucks.
+ *
+ * Protects `${{ }}` workflow expressions from Nunjucks by escaping them
+ * before rendering and restoring them after.
+ */
+export function renderTemplate(env, templateStr, context) {
+    const escaped = templateStr.replace(/\$\{\{/g, WORKFLOW_EXPR_PLACEHOLDER);
+    const rendered = env.renderString(escaped, context);
+    return rendered.replace(new RegExp(escapeRegExp(WORKFLOW_EXPR_PLACEHOLDER), "g"), "${{");
+}
+/**
+ * Render a named template file through Nunjucks.
+ *
+ * The template name is resolved by the environment's FileSystemLoader through
+ * the configured three-tier search.
+ *
+ * Absolute paths bypass the loader and are read directly. This supports
+ * fully-resolved AgentSpec fields where systemPromptTemplate / taskPromptTemplate
+ * carry absolute paths after loadAgent (per D1).
+ */
+export function renderTemplateFile(env, templateName, context) {
+    if (path.isAbsolute(templateName)) {
+        const content = fs.readFileSync(templateName, "utf-8");
+        return renderTemplate(env, content, context);
+    }
+    return env.render(templateName, context);
+}
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,QAAQ,MAAM,UAAU,CAAC;AAWhC;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAuB;IACxD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;IAEpF,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC5D,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtD,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAEtF,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE/F,OAAO,IAAI,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE;QACvC,UAAU,EAAE,KAAK;QACjB,gBAAgB,EAAE,KAAK;KACvB,CAAC,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,MAAM,yBAAyB,GAAG,0BAA0B,CAAC;AAE7D,SAAS,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC7B,GAAyB,EACzB,WAAmB,EACnB,OAAgC;IAEhC,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,yBAAyB,CAAC,CAAC;IAC1E,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACpD,OAAO,QAAQ,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,yBAAyB,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;AAC1F,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CACjC,GAAyB,EACzB,YAAoB,EACpB,OAAgC;IAEhC,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC"}

package/dist/trace-redactor.d.ts

@@ -0,0 +1,43 @@
+export interface RedactionPattern {
+    name: string;
+    regex: RegExp;
+    replacement: string;
+}
+export interface RedactionConfig {
+    /** Additional patterns from project-extension config, applied after BUILTIN_PATTERNS in order. */
+    patterns?: RedactionPattern[];
+}
+/**
+ * Exhaustive built-in pattern set as of the audit. Order matters: more specific shapes
+ * (e.g. `sk-or-` OpenRouter prefix) come before less specific (e.g. generic `sk-` OpenAI)
+ * to keep replacement labels accurate where prefixes overlap.
+ */
+export declare const BUILTIN_PATTERNS: ReadonlyArray<RedactionPattern>;
+/**
+ * Apply all redaction patterns to a string and return the redacted result.
+ * Builtin patterns run first, then any additional patterns from `config.patterns` in order.
+ * Idempotent: running the function on its own output produces an identical string, because
+ * the replacement tokens (e.g. `[REDACTED:...]`) do not match any builtin pattern shape.
+ */
+export declare function redactSensitiveData(text: string, config?: RedactionConfig): string;
+/**
+ * Apply redaction to an LLM AssistantMessage's content array. Preserves message structure
+ * (returns same shape as input). For each content item:
+ *   - if it has a string `text` field, that field is redacted.
+ *   - if it has an array `content` field, recurse.
+ *   - otherwise, the item is passed through unchanged.
+ *
+ * Type erased via `T extends { content: unknown[] }` so the helper composes with any
+ * pi-ai content shape (text blocks, tool calls, thinking blocks, structured content).
+ */
+export declare function redactLlmResponse<T extends {
+    content: unknown[];
+}>(message: T, config?: RedactionConfig): T;
+/**
+ * Load redaction patterns from a project-extension config file.
+ * Expected shape: `{ patterns: [{ name, regex: "<string-pattern>", replacement?, domain? }] }`.
+ * Compiles each `regex` string to a RegExp with the `g` flag.
+ * Throws if the file does not exist, parses to invalid JSON, or contains malformed entries.
+ */
+export declare function loadProjectRedactionConfig(configPath: string): RedactionPattern[];
+//# sourceMappingURL=trace-redactor.d.ts.map

package/dist/trace-redactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-redactor.d.ts","sourceRoot":"","sources":["../src/trace-redactor.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC/B,kGAAkG;IAClG,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAAa,CAAC,gBAAgB,CAkD5D,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,CAYlF;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,OAAO,EAAE,OAAO,EAAE,CAAA;CAAE,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,CAAC,CAG3G;AA0BD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,EAAE,CA8CjF"}

package/dist/trace-redactor.js

@@ -0,0 +1,173 @@
+// trace-redactor: credential / sensitive-data redaction for monitor-classify trace records.
+//
+// Per DEC-0005 and the canonical-compliance audit for issue-023, trace records produced by
+// the monitor-classify capture path may contain rendered LLM prompts and full assistant
+// responses. Those payloads can carry credentials echoed by users (pasted API keys, OAuth
+// tokens, secrets in code samples). Pi-mono's SessionManager performs no redaction; this
+// module is the pre-write filter that aims to strip well-known sensitive shapes BEFORE
+// trace records are persisted.
+//
+// Scope intent (not a guarantee):
+//   - Match known credential surface shapes via the BUILTIN_PATTERNS set.
+//   - Allow per-project augmentation via .workflows/monitors/<name>/trace-config.json.
+//   - Preserve LLM message structure while redacting text fields recursively.
+// Limits:
+//   - Pattern-based redaction is best-effort; it cannot detect arbitrary opaque secrets.
+//   - Operators remain responsible for reviewing trace output before sharing externally.
+import { existsSync, readFileSync } from "node:fs";
+/**
+ * Exhaustive built-in pattern set as of the audit. Order matters: more specific shapes
+ * (e.g. `sk-or-` OpenRouter prefix) come before less specific (e.g. generic `sk-` OpenAI)
+ * to keep replacement labels accurate where prefixes overlap.
+ */
+export const BUILTIN_PATTERNS = [
+    { name: "anthropic_api_key", regex: /sk-ant-[a-zA-Z0-9_-]{20,}/g, replacement: "[REDACTED:anthropic_api_key]" },
+    { name: "openrouter_api_key", regex: /sk-or-[a-zA-Z0-9_-]{20,}/g, replacement: "[REDACTED:openrouter_api_key]" },
+    { name: "openai_api_key", regex: /sk-(?:proj-)?[a-zA-Z0-9_-]{20,}/g, replacement: "[REDACTED:openai_api_key]" },
+    { name: "google_api_key", regex: /AIza[0-9A-Za-z\-_]{35}/g, replacement: "[REDACTED:google_api_key]" },
+    { name: "aws_access_key", regex: /AKIA[0-9A-Z]{16}/g, replacement: "[REDACTED:aws_access_key]" },
+    {
+        name: "aws_secret_key",
+        // Matches the `aws_secret_access_key` field name followed by `=` or `:` separator and a
+        // secret value, optionally wrapped in single or double quotes. Body uses `+` (1-or-more)
+        // rather than `{40}` so we tolerate the canonical 40-char AWS shape AND test fixtures /
+        // generated keys that diverge from that exact length. Case-insensitive to cover env-var
+        // uppercasing (AWS_SECRET_ACCESS_KEY).
+        regex: /aws_secret_access_key\s*[=:]\s*["']?[A-Za-z0-9/+=]{16,}["']?/gi,
+        replacement: "[REDACTED:aws_secret_key]",
+    },
+    {
+        name: "gcp_service_account",
+        regex: /"type":\s*"service_account"[\s\S]*?"private_key":\s*"[^"]*"/g,
+        replacement: "[REDACTED:gcp_service_account]",
+    },
+    { name: "github_token_ghp", regex: /ghp_[a-zA-Z0-9_]{36,}/g, replacement: "[REDACTED:github_token_ghp]" },
+    { name: "github_token_gho", regex: /gho_[a-zA-Z0-9_]{36,}/g, replacement: "[REDACTED:github_token_gho]" },
+    { name: "github_token_ghs", regex: /ghs_[a-zA-Z0-9_]{36,}/g, replacement: "[REDACTED:github_token_ghs]" },
+    { name: "github_token_ghu", regex: /ghu_[a-zA-Z0-9_]{36,}/g, replacement: "[REDACTED:github_token_ghu]" },
+    { name: "jwt", regex: /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, replacement: "[REDACTED:jwt]" },
+    {
+        name: "bearer_token",
+        regex: /Authorization:\s*Bearer\s+([a-zA-Z0-9_\-.]+)/gi,
+        replacement: "Authorization: Bearer [REDACTED:bearer_token]",
+    },
+    {
+        name: "ssh_private_key",
+        // PEM marker shape: `-----BEGIN <ALGO> PRIVATE KEY-----\n<base64 body, possibly multi-line>\n-----END <ALGO> PRIVATE KEY-----`.
+        // The previous form omitted the closing `-----` of the BEGIN line and used `[^-]*` for
+        // the body — neither admitted a real PEM block (the very next chars after `KEY` are
+        // `-----`, hyphens). `[\s\S]*?` is non-greedy match-anything-including-newlines, which
+        // stops at the first `-----END...KEY-----` sequence. Algorithm token kept optional so
+        // PEM blocks without an explicit ALGO (rare, OpenSSH) still match.
+        regex: /-----BEGIN\s+(?:RSA|DSA|EC|OPENSSH|PGP|ENCRYPTED)?\s*PRIVATE\s+KEY-----[\s\S]*?-----END\s+(?:RSA|DSA|EC|OPENSSH|PGP|ENCRYPTED)?\s*PRIVATE\s+KEY-----/g,
+        replacement: "[REDACTED:ssh_private_key]",
+    },
+    { name: "postgres_conn_string", regex: /postgres:\/\/[^:]+:[^@]+@[^/]+\/\S+/g, replacement: "postgres://[REDACTED]" },
+    { name: "mysql_conn_string", regex: /mysql:\/\/[^:]+:[^@]+@[^/]+\/\S+/g, replacement: "mysql://[REDACTED]" },
+    {
+        name: "mongodb_conn_string",
+        regex: /mongodb(?:\+srv)?:\/\/[^:]+:[^@]+@[^/]+/g,
+        replacement: "mongodb://[REDACTED]",
+    },
+];
+/**
+ * Apply all redaction patterns to a string and return the redacted result.
+ * Builtin patterns run first, then any additional patterns from `config.patterns` in order.
+ * Idempotent: running the function on its own output produces an identical string, because
+ * the replacement tokens (e.g. `[REDACTED:...]`) do not match any builtin pattern shape.
+ */
+export function redactSensitiveData(text, config) {
+    if (typeof text !== "string" || text.length === 0)
+        return text;
+    let out = text;
+    for (const pattern of BUILTIN_PATTERNS) {
+        out = out.replace(pattern.regex, pattern.replacement);
+    }
+    if (config?.patterns) {
+        for (const pattern of config.patterns) {
+            out = out.replace(pattern.regex, pattern.replacement);
+        }
+    }
+    return out;
+}
+/**
+ * Apply redaction to an LLM AssistantMessage's content array. Preserves message structure
+ * (returns same shape as input). For each content item:
+ *   - if it has a string `text` field, that field is redacted.
+ *   - if it has an array `content` field, recurse.
+ *   - otherwise, the item is passed through unchanged.
+ *
+ * Type erased via `T extends { content: unknown[] }` so the helper composes with any
+ * pi-ai content shape (text blocks, tool calls, thinking blocks, structured content).
+ */
+export function redactLlmResponse(message, config) {
+    const redactedContent = message.content.map((item) => redactContentItem(item, config));
+    return { ...message, content: redactedContent };
+}
+function redactContentItem(item, config) {
+    if (item === null || typeof item !== "object")
+        return item;
+    const obj = item;
+    const result = { ...obj };
+    if (typeof obj.text === "string") {
+        result.text = redactSensitiveData(obj.text, config);
+    }
+    if (Array.isArray(obj.content)) {
+        result.content = obj.content.map((nested) => redactContentItem(nested, config));
+    }
+    return result;
+}
+/**
+ * Load redaction patterns from a project-extension config file.
+ * Expected shape: `{ patterns: [{ name, regex: "<string-pattern>", replacement?, domain? }] }`.
+ * Compiles each `regex` string to a RegExp with the `g` flag.
+ * Throws if the file does not exist, parses to invalid JSON, or contains malformed entries.
+ */
+export function loadProjectRedactionConfig(configPath) {
+    if (!existsSync(configPath)) {
+        throw new Error(`trace redaction config not found: ${configPath}`);
+    }
+    const raw = readFileSync(configPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`trace redaction config is not valid JSON: ${configPath}: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error(`trace redaction config must be a JSON object: ${configPath}`);
+    }
+    const patterns = parsed.patterns;
+    if (patterns === undefined)
+        return [];
+    if (!Array.isArray(patterns)) {
+        throw new Error(`trace redaction config 'patterns' must be an array: ${configPath}`);
+    }
+    const out = [];
+    for (let i = 0; i < patterns.length; i++) {
+        const entry = patterns[i];
+        if (!entry || typeof entry !== "object") {
+            throw new Error(`trace redaction config patterns[${i}] must be an object: ${configPath}`);
+        }
+        if (typeof entry.name !== "string" || entry.name.length === 0) {
+            throw new Error(`trace redaction config patterns[${i}].name must be a non-empty string: ${configPath}`);
+        }
+        if (typeof entry.regex !== "string" || entry.regex.length === 0) {
+            throw new Error(`trace redaction config patterns[${i}].regex must be a non-empty string: ${configPath}`);
+        }
+        let compiled;
+        try {
+            compiled = new RegExp(entry.regex, "g");
+        }
+        catch (err) {
+            throw new Error(`trace redaction config patterns[${i}].regex did not compile: ${configPath}: ${err.message}`);
+        }
+        const replacement = typeof entry.replacement === "string" && entry.replacement.length > 0
+            ? entry.replacement
+            : `[REDACTED:${entry.name}]`;
+        out.push({ name: entry.name, regex: compiled, replacement });
+    }
+    return out;
+}
+//# sourceMappingURL=trace-redactor.js.map

package/dist/trace-redactor.js.map

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

package/dist/trace-writer.d.ts

@@ -0,0 +1,13 @@
+export interface WriteTraceOptions {
+    /** Path to the JSONL file. Will be created if it does not exist. Parent directories will be created. */
+    tracePath: string;
+    /** Maximum file size in bytes before rotation overflow split. Default 500MB. */
+    maxFileSizeBytes?: number;
+    /** Skip schema validation. Default false. ONLY for tests. */
+    skipValidation?: boolean;
+}
+/** Append a single TraceEntry to the JSONL file. Validates against the schema. Atomic per-entry write via flock. */
+export declare function writeAgentTrace(entry: unknown, options: WriteTraceOptions): void;
+/** Mint a date-rotated trace file path: <baseDir>/<YYYY-MM-DD>.jsonl. Caller passes baseDir; helper handles date math. */
+export declare function dateRotatedPath(baseDir: string, date?: Date): string;
+//# sourceMappingURL=trace-writer.d.ts.map

package/dist/trace-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-writer.d.ts","sourceRoot":"","sources":["../src/trace-writer.ts"],"names":[],"mappings":"AA+CA,MAAM,WAAW,iBAAiB;IACjC,wGAAwG;IACxG,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,oHAAoH;AACpH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CA2BhF;AAkCD,0HAA0H;AAC1H,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,CAMpE"}

package/dist/trace-writer.js

@@ -0,0 +1,112 @@
+// trace-writer: JSONL persistence layer for the monitor-classify trace capture pipeline (issue-023).
+//
+// Layered above trace-redactor (T2) and below the executeAgent integration point (T5/T6),
+// this module accepts an already-redacted TraceEntry, validates it against
+// packages/pi-jit-agents/schemas/agent-trace.schema.json, and atomically appends one JSONL
+// line to the configured trace file. Per DEC-0005 (push-write divergence from pi-mono's
+// pull/replay model) entries are written immediately at the moment of occurrence inside
+// executeAgent rather than reconstructed at session close, so each append must be self-
+// validating and crash-safe — a partial write or interleaved write from a concurrent process
+// would corrupt the JSONL invariant (one valid JSON document per line).
+//
+// Crash-safety strategy:
+//   - JSONL append uses fs.appendFileSync, mirroring pi-coding-agent's session-manager pattern.
+//   - Cross-process safety uses proper-lockfile (already present in the workspace via
+//     pi-coding-agent's transitive dependency tree). Node 23.x exposes node:fs flockSync as
+//     `undefined` in the version this repo targets, so the userspace lockfile approach is
+//     the working option; the lock is held only for the duration of the append.
+//   - Schema validation reuses validateFromFile from @davidorex/pi-project/schema-validator
+//     so the AJV runtime, error format, and ESM/CJS interop shim live in one place.
+//
+// Size-rotation strategy:
+//   - Before append, stat the target. If it exceeds maxFileSizeBytes (default 500 MB), the
+//     writer mints the next available `<base>-NNN.jsonl` split file and appends there. The
+//     prior file is left as a closed split. Date-based rotation is exposed separately via
+//     dateRotatedPath() so callers compose the two without coupling.
+import { appendFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateFromFile } from "@davidorex/pi-project/schema-validator";
+// proper-lockfile is CommonJS — under Node16 module resolution + ESM consumer the default
+// import resolves to the module namespace, so lockSync hangs off the default export.
+import _properLockfile from "proper-lockfile";
+// CJS interop: depending on bundler / tsconfig, the default may be the namespace itself or
+// a wrapping `{ default: ns }`. Resolve once at module load.
+const properLockfile = (_properLockfile.default ??
+    _properLockfile);
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+// In dist the module sits at packages/pi-jit-agents/dist/trace-writer.js, in src at
+// packages/pi-jit-agents/src/trace-writer.ts. Both resolve to ../schemas relative to the
+// module file, since schemas/ ships at the package root.
+const TRACE_SCHEMA_PATH = path.resolve(moduleDir, "..", "schemas", "agent-trace.schema.json");
+const DEFAULT_MAX_FILE_SIZE_BYTES = 500_000_000;
+/** Append a single TraceEntry to the JSONL file. Validates against the schema. Atomic per-entry write via flock. */
+export function writeAgentTrace(entry, options) {
+    const maxSize = options.maxFileSizeBytes ?? DEFAULT_MAX_FILE_SIZE_BYTES;
+    if (!options.skipValidation) {
+        // Throws ValidationError on schema mismatch; descriptive message includes instancePath + reason.
+        validateFromFile(TRACE_SCHEMA_PATH, entry, "agent-trace entry");
+    }
+    const targetPath = resolveSplitTarget(options.tracePath, maxSize);
+    // Ensure parent dir exists. mkdirSync is idempotent with recursive: true.
+    mkdirSync(path.dirname(targetPath), { recursive: true });
+    // Acquire the per-file lock. Fail-fast on contention: proper-lockfile defaults to a
+    // short retry window which we override with retries: 0 so a contended write surfaces
+    // rather than blocking the dispatch loop indefinitely. The lock requires the target
+    // path to exist; create an empty file first if it doesn't.
+    if (!existsSync(targetPath)) {
+        appendFileSync(targetPath, "");
+    }
+    const release = properLockfile.lockSync(targetPath, { retries: 0, stale: 5_000, realpath: false });
+    try {
+        appendFileSync(targetPath, `${JSON.stringify(entry)}\n`);
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Resolve the actual file path to write to, honoring the size-overflow split policy.
+ * If the base path is missing or under maxSize, returns it unchanged. Otherwise scans
+ * for the next available `<base>-NNN.jsonl` split.
+ */
+function resolveSplitTarget(basePath, maxSize) {
+    if (!existsSync(basePath))
+        return basePath;
+    let size;
+    try {
+        size = statSync(basePath).size;
+    }
+    catch {
+        return basePath;
+    }
+    if (size < maxSize)
+        return basePath;
+    const ext = path.extname(basePath); // typically ".jsonl"
+    const stem = basePath.slice(0, basePath.length - ext.length);
+    for (let i = 1; i <= 9999; i++) {
+        const suffix = String(i).padStart(3, "0");
+        const candidate = `${stem}-${suffix}${ext}`;
+        if (!existsSync(candidate))
+            return candidate;
+        let candSize;
+        try {
+            candSize = statSync(candidate).size;
+        }
+        catch {
+            return candidate;
+        }
+        if (candSize < maxSize)
+            return candidate;
+    }
+    throw new Error(`trace-writer: exhausted split suffix range (-001..-9999) for ${basePath}`);
+}
+/** Mint a date-rotated trace file path: <baseDir>/<YYYY-MM-DD>.jsonl. Caller passes baseDir; helper handles date math. */
+export function dateRotatedPath(baseDir, date) {
+    const d = date ?? new Date();
+    const yyyy = d.getUTCFullYear().toString().padStart(4, "0");
+    const mm = (d.getUTCMonth() + 1).toString().padStart(2, "0");
+    const dd = d.getUTCDate().toString().padStart(2, "0");
+    return path.join(baseDir, `${yyyy}-${mm}-${dd}.jsonl`);
+}
+//# sourceMappingURL=trace-writer.js.map

package/dist/trace-writer.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Type surface for pi-jit-agents.
+ *
+ * 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 nunjucks from "nunjucks";
+/**
+ * A loaded agent specification.
+ *
+ * Per D1 (jit-agents-spec.md §4), every path field is fully resolved to an
+ * absolute filesystem path by the time loadAgent returns. Consumers never see
+ * relative paths and never need to know which directory the spec was loaded
+ * from to interpret its references.
+ */
+export interface AgentSpec {
+    name: string;
+    description?: string;
+    role?: string;
+    model?: string;
+    thinking?: string;
+    tools?: string[];
+    extensions?: string[];
+    skills?: string[];
+    /** Inline system prompt text (alternative to systemPromptTemplate). */
+    systemPrompt?: string;
+    /** Absolute path to a Nunjucks template file for the system prompt. */
+    systemPromptTemplate?: string;
+    /** Absolute path to a Nunjucks template file for the task prompt. */
+    taskPromptTemplate?: string;
+    /** Inline task prompt text (alternative to taskPromptTemplate). */
+    taskPrompt?: string;
+    inputSchema?: Record<string, unknown>;
+    outputFormat?: "json" | "text";
+    /**
+     * Absolute path to a JSON Schema file. May also be a `block:<name>` sentinel
+     * that resolves to `.project/schemas/<name>.schema.json` at compile time
+     * against the invocation cwd.
+     */
+    outputSchema?: string;
+    contextBlocks?: string[];
+    /**
+     * 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;
+}
+/**
+ * Options for loadAgent / createAgentLoader.
+ *
+ * Per D7 (jit-agents-spec.md §4), the loader searches three tiers in order:
+ *   1. {cwd}/.project/agents/
+ *   2. {userDir ?? ~/.pi/agent/agents/}
+ *   3. {builtinDir}   (only when supplied)
+ *
+ * Per D3, .pi/agents/ is NOT searched — that path is Pi platform territory.
+ */
+export interface LoadContext {
+    /** Project root. Used to resolve the project-level tier and as base for block reads. */
+    cwd: string;
+    /** Optional consumer-supplied builtin agents directory. When absent, builtin tier is skipped. */
+    builtinDir?: string;
+    /** Test hook to override the user tier. Defaults to `~/.pi/agent/agents/`. */
+    userDir?: string;
+}
+/**
+ * Options for compileAgent.
+ */
+export interface CompileContext {
+    /** Nunjucks environment from createTemplateEnv — used to render template references. */
+    env: nunjucks.Environment;
+    /** Resolved input for template rendering. Object fields become top-level template variables. */
+    input: unknown;
+    /** Project root. Used for `.project/` block reads during contextBlocks injection. */
+    cwd: string;
+}
+/**
+ * A compiled agent ready for dispatch.
+ */
+export interface CompiledAgent {
+    /** The originating spec (fully resolved paths). */
+    spec: AgentSpec;
+    /** Rendered system prompt, if the spec declared one. */
+    systemPrompt?: string;
+    /** Rendered task prompt. Required — dispatch has nothing to send without it. */
+    taskPrompt: string;
+    /** Model spec copied from the agent spec for dispatch convenience. */
+    model?: string;
+    /** Absolute output schema path (copied from spec — already resolved). */
+    outputSchema?: string;
+    /**
+     * Resolved per-collector context values, keyed by the contextBlock name
+     * (e.g. "conventions"), populated when contextBlocks are read from `.project/`
+     * during compilation. Surfaced for trace capture (issue-023 T5/T6) so the
+     * push-write trace stream can emit one `context_collection` entry per
+     * resolved block. Empty object when the spec declares no contextBlocks.
+     *
+     * The values stored here are the raw (unwrapped) block payloads — distinct
+     * from the anti-injection-wrapped strings that the templates see under the
+     * `_<name>` key. Trace consumers want the structured value for downstream
+     * inspection, not the rendered string.
+     */
+    contextValues: Record<string, unknown>;
+}
+/**
+ * Dispatch-time context for executeAgent.
+ */
+export interface DispatchContext {
+    /** Resolved pi-ai Model instance from the consumer's model registry. */
+    model: Model<Api>;
+    /** API auth — apiKey and headers from the consumer's model registry. */
+    auth: JitAgentAuth;
+    /** Max tokens for the LLM call. Defaults to 1024. */
+    maxTokens?: number;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+    /**
+     * Trace destination for the monitor-classify trace capture pipeline (issue-023).
+     * - `undefined` → use the default resolution (env var or null fallback).
+     * - `null` → tracing explicitly disabled; no JSONL is written.
+     * - `string` → absolute path to the JSONL trace file the writer should append to.
+     *
+     * Per DEC-0005 the trace stream is push-write (emitted at the moment of occurrence
+     * inside executeAgent), divergent from pi-mono's pull/replay session model.
+     */
+    tracePath?: string | null;
+    /**
+     * 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
+     * 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
+     * tracing itself is disabled.
+     */
+    redactionConfigPath?: string | null;
+    /**
+     * Optional monitor name for stamping `session_start.monitorName`. The
+     * `executeAgent` boundary itself does not know whether its caller is a
+     * monitor classify path or a workflow agent step — the monitor wrapper
+     * (T6's `classifyViaAgent`) sets this when dispatching as a classifier.
+     * `null` / absent for non-monitor traces.
+     */
+    monitorName?: string | null;
+}
+/**
+ * API credentials for an LLM call.
+ */
+export interface JitAgentAuth {
+    apiKey: string;
+    headers: Record<string, string>;
+}
+/**
+ * Result of an executeAgent invocation.
+ */
+export interface JitAgentResult {
+    /** Parsed output — tool_call arguments if schema-bound, extracted text otherwise. */
+    output: unknown;
+    /** Raw AssistantMessage for debugging and tracing. */
+    raw: AssistantMessage;
+    /** Token usage and cost from the call. */
+    usage: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: number;
+    };
+}
+/**
+ * Projection of an AgentSpec for introspection.
+ *
+ * Used by SDK query surfaces to answer "what does this agent accept/produce"
+ * without dispatching it. Internal fields (loadedFrom) are not exposed.
+ */
+export interface AgentContract {
+    name: string;
+    role?: string;
+    inputSchema?: Record<string, unknown>;
+    contextBlocks?: string[];
+    outputFormat?: "json" | "text";
+    outputSchema?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map