@haikeilabs/agentware 0.1.0

package/dist/memory/client.js

@@ -0,0 +1,210 @@
+/**
+ * Wiki memory - TypeScript client for the Go core's ontology-constrained
+ * wiki memory.
+ *
+ * WikiMemory spawns the Go MCP stdio server (`memctl serve`) scoped to one
+ * user. The subprocess owns enforcement: every call passes the Go
+ * middleware chain (declarative policy + ontology evaluator + audit), and
+ * in-band attempts to change user scope are denied. The API is async
+ * (subprocess I/O); inference stays in the Python SDK.
+ *
+ * ## Providing Your Own Ontology
+ *
+ * The T-box (schema) is fully composable — pass paths to your own TTL files.
+ * Multiple files are merged. Use absolute paths or paths relative to your
+ * working directory.
+ *
+ * Example TTL file (my-ontology.ttl):
+ * ```turtle
+ * @prefix ex: <http://example.org/> .
+ * @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+ * @prefix owl: <http://www.w3.org/2002/07/owl#> .
+ *
+ * ex:Project a owl:Class ;
+ *     rdfs:label "Project"@en ;
+ *     rdfs:comment "A software project" .
+ *
+ * ex:Task a owl:Class ;
+ *     rdfs:label "Task"@en ;
+ *     rdfs:subClassOf ex:Project .
+ *
+ * ex:hasStatus a owl:ObjectProperty ;
+ *     rdfs:domain ex:Project ;
+ *     rdfs:range ex:Status .
+ *
+ * ex:Status a owl:Class ;
+ *     rdfs:label "Status"@en .
+ * ```
+ *
+ * Example usage:
+ * ```typescript
+ * const wiki = new WikiMemory({
+ *   userId: "alice",
+ *   root: "./memory",
+ *   tboxPaths: [
+ *     "./my-ontology.ttl",    // your custom ontology
+ *     "./shared-skills.ttl",  // another TTL file
+ *   ],
+ * });
+ * ```
+ *
+ * The repo includes example ontologies in `ontologies/`:
+ * - `ontologies/education/TBOX_LEARNING_SOFTWARE.ttl` (learning software concepts)
+ * - `ontologies/social/twitch_topics.ttl` (SKOS concepts)
+ * - `ontologies/thesaurus/*.ttl` (SKOS testing)
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+export const MEMORY_TOOLS = [
+    "memory_ingest",
+    "memory_write_page",
+    "memory_query",
+    "memory_get_claims",
+    "memory_lint",
+];
+export const DIAGNOSTICS_MARKER = "diagnostics: ";
+/** Extract structured violations from a deny reason, if present. */
+export function parseDiagnostics(errorText) {
+    const idx = errorText.indexOf(DIAGNOSTICS_MARKER);
+    if (idx < 0)
+        return [];
+    try {
+        const raw = JSON.parse(errorText.slice(idx + DIAGNOSTICS_MARKER.length));
+        return raw.map((v) => ({
+            constraint: String(v.constraint ?? ""),
+            term: String(v.term ?? ""),
+            message: String(v.message ?? ""),
+            nearest: Array.isArray(v.nearest) ? v.nearest.map(String) : [],
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+export class MemoryServerError extends Error {
+}
+export class WikiMemory {
+    userId;
+    proc;
+    lines;
+    pending = [];
+    nextId = 0;
+    ready;
+    constructor(options) {
+        if (!options.userId)
+            throw new MemoryServerError("userId is required");
+        if (!options.tboxPaths.length) {
+            throw new MemoryServerError("tboxPaths is required (the T-box is a parameter)");
+        }
+        const binary = options.memctlPath ?? process.env.PEDRO_MEMCTL ?? "memctl";
+        const args = [
+            "serve",
+            "-root", options.root,
+            "-user", options.userId,
+            "-session", options.sessionId ?? "typescript-sdk",
+        ];
+        for (const path of options.tboxPaths)
+            args.push("-tbox", path);
+        this.userId = options.userId;
+        this.proc = spawn(binary, args, { stdio: ["pipe", "pipe", "pipe"] });
+        this.proc.on("error", (err) => this.failAll(new MemoryServerError(err.message)));
+        this.proc.on("exit", (code) => this.failAll(new MemoryServerError(`memory server exited (code=${code})`)));
+        this.lines = createInterface({ input: this.proc.stdout });
+        this.lines.on("line", (line) => this.onLine(line));
+        this.ready = this.request("initialize", {}).then(() => {
+            this.notify("notifications/initialized");
+        });
+    }
+    onLine(line) {
+        if (!line.trim())
+            return;
+        const next = this.pending.shift();
+        if (!next)
+            return;
+        let response;
+        try {
+            response = JSON.parse(line);
+        }
+        catch (err) {
+            next.reject(new MemoryServerError(`bad response: ${String(err)}`));
+            return;
+        }
+        if (response.error) {
+            next.reject(new MemoryServerError(`rpc ${response.error.code}: ${response.error.message}`));
+            return;
+        }
+        next.resolve(response.result ?? {});
+    }
+    failAll(err) {
+        const waiting = this.pending;
+        this.pending = [];
+        for (const p of waiting)
+            p.reject(err);
+    }
+    notify(method) {
+        this.proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", method }) + "\n");
+    }
+    request(method, params) {
+        this.nextId += 1;
+        const message = { jsonrpc: "2.0", id: this.nextId, method, params };
+        return new Promise((resolve, reject) => {
+            this.pending.push({ resolve, reject });
+            this.proc.stdin.write(JSON.stringify(message) + "\n");
+        });
+    }
+    /** Execute a memory tool. Resolves to [outputText, success, error]. */
+    async execute(toolName, args) {
+        await this.ready;
+        const result = await this.request("tools/call", {
+            name: toolName,
+            arguments: args,
+        });
+        const blocks = (result.content ?? []);
+        const text = blocks
+            .filter((b) => b.type === "text")
+            .map((b) => b.text ?? "")
+            .join("");
+        if (result.isError)
+            return [null, false, text];
+        return [text, true, ""];
+    }
+    /** List the memory tools served by the core. */
+    async tools() {
+        await this.ready;
+        const result = await this.request("tools/list", {});
+        return (result.tools ?? []);
+    }
+    async ingest(sourceId, text) {
+        return this.execute("memory_ingest", { source_id: sourceId, text });
+    }
+    async writePage(content) {
+        return this.execute("memory_write_page", { content });
+    }
+    async query(question) {
+        return this.parsed(await this.execute("memory_query", { question }));
+    }
+    async getClaims(pageId) {
+        const args = {};
+        if (pageId)
+            args.page_id = pageId;
+        return this.parsed(await this.execute("memory_get_claims", args));
+    }
+    async lint() {
+        return this.parsed(await this.execute("memory_lint", {}));
+    }
+    parsed([output, ok, err]) {
+        if (!ok || typeof output !== "string" || output === "")
+            return [output, ok, err];
+        try {
+            return [JSON.parse(output), ok, err];
+        }
+        catch {
+            return [output, ok, err];
+        }
+    }
+    /** Terminate the memory server subprocess. */
+    close() {
+        this.proc.stdin.end();
+        this.proc.kill();
+    }
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,5 @@
+export { DIAGNOSTICS_MARKER, MEMORY_TOOLS, MemoryServerError, WikiMemory, parseDiagnostics, } from "./client.js";
+export type { DiagnosticViolation, ToolResult, WikiMemoryOptions } from "./client.js";
+export { memoryTools } from "./tools.js";
+export type { MemoryTool } from "./tools.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,mBAAmB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/memory/index.js

@@ -0,0 +1,2 @@
+export { DIAGNOSTICS_MARKER, MEMORY_TOOLS, MemoryServerError, WikiMemory, parseDiagnostics, } from "./client.js";
+export { memoryTools } from "./tools.js";

package/dist/memory/tools.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Framework integration: expose wiki-memory tools in the Vercel AI SDK's
+ * tool shape ({ description, parameters, execute }).
+ *
+ * The returned record plugs directly into `generateText`/`streamText`:
+ *
+ *   const memory = new WikiMemory({ userId: "alice", root, tboxPaths });
+ *   const result = await generateText({ model, tools: memoryTools(memory), ... });
+ *
+ * Parameters are zod schemas (zod is already an SDK dependency). Denied
+ * writes resolve to "DENIED: ..." including the structured diagnostics
+ * payload, so the calling agent can self-correct and retry.
+ */
+import { z } from "zod";
+import type { WikiMemory } from "./client.js";
+export interface MemoryTool {
+    description: string;
+    parameters: z.ZodTypeAny;
+    execute: (args: Record<string, unknown>) => Promise<string>;
+}
+export declare function memoryTools(memory: WikiMemory): Record<string, MemoryTool>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/memory/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/memory/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC;IACzB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7D;AAQD,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAwC1E"}

package/dist/memory/tools.js

@@ -0,0 +1,57 @@
+/**
+ * Framework integration: expose wiki-memory tools in the Vercel AI SDK's
+ * tool shape ({ description, parameters, execute }).
+ *
+ * The returned record plugs directly into `generateText`/`streamText`:
+ *
+ *   const memory = new WikiMemory({ userId: "alice", root, tboxPaths });
+ *   const result = await generateText({ model, tools: memoryTools(memory), ... });
+ *
+ * Parameters are zod schemas (zod is already an SDK dependency). Denied
+ * writes resolve to "DENIED: ..." including the structured diagnostics
+ * payload, so the calling agent can self-correct and retry.
+ */
+import { z } from "zod";
+function render([output, ok, err]) {
+    if (!ok)
+        return `DENIED: ${err}`;
+    if (typeof output === "string")
+        return output;
+    return JSON.stringify(output, null, 2);
+}
+export function memoryTools(memory) {
+    return {
+        memory_ingest: {
+            description: "Store a raw source document in the user's memory vault.",
+            parameters: z.object({
+                source_id: z.string().describe("kebab-case source id, e.g. src-go-blog"),
+                text: z.string().describe("verbatim source text"),
+            }),
+            execute: async (args) => render(await memory.ingest(String(args.source_id), String(args.text))),
+        },
+        memory_write_page: {
+            description: "Create or update an ontology-validated wiki page. content is full " +
+                "page markdown with YAML frontmatter per the memory schema; on DENY " +
+                "the response includes structured diagnostics - fix and retry.",
+            parameters: z.object({
+                content: z.string().describe("full page markdown including frontmatter"),
+            }),
+            execute: async (args) => render(await memory.writePage(String(args.content))),
+        },
+        memory_query: {
+            description: "Query the user's wiki memory.",
+            parameters: z.object({ question: z.string() }),
+            execute: async (args) => render(await memory.query(String(args.question))),
+        },
+        memory_get_claims: {
+            description: "List claims tracked in the user's vault, optionally per page.",
+            parameters: z.object({ page_id: z.string().optional() }),
+            execute: async (args) => render(await memory.getClaims(args.page_id ? String(args.page_id) : undefined)),
+        },
+        memory_lint: {
+            description: "Report contract, ontology, and graph issues in the vault.",
+            parameters: z.object({}),
+            execute: async () => render(await memory.lint()),
+        },
+    };
+}

package/dist/middleware/audit.d.ts

@@ -0,0 +1,27 @@
+import type { Decision } from "./types.js";
+import { Action } from "./types.js";
+export interface AuditRecord {
+    session_id: string;
+    tool_name: string;
+    args: Record<string, unknown>;
+    decision: Decision;
+    timestamp: Date;
+}
+export interface AuditFilter {
+    session_id?: string;
+    tool_name?: string;
+    action?: Action;
+    since?: Date;
+    limit?: number;
+}
+export interface Auditor {
+    record(record: AuditRecord): void;
+    query(filter: AuditFilter): AuditRecord[];
+}
+export declare class InMemoryAuditor implements Auditor {
+    private records;
+    record(record: AuditRecord): void;
+    query(filter: AuditFilter): AuditRecord[];
+    clear(): void;
+}
+//# sourceMappingURL=audit.d.ts.map

package/dist/middleware/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/middleware/audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEpC,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,EAAE,CAAC;CAC3C;AAED,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,OAAO,CAAqB;IAEpC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAIjC,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,EAAE;IAazC,KAAK,IAAI,IAAI;CAGd"}

package/dist/middleware/audit.js

@@ -0,0 +1,26 @@
+export class InMemoryAuditor {
+    records = [];
+    record(record) {
+        this.records.push(record);
+    }
+    query(filter) {
+        const results = [];
+        for (const r of this.records) {
+            if (filter.session_id && r.session_id !== filter.session_id)
+                continue;
+            if (filter.tool_name && r.tool_name !== filter.tool_name)
+                continue;
+            if (filter.action && r.decision.action !== filter.action)
+                continue;
+            if (filter.since && r.timestamp < filter.since)
+                continue;
+            results.push(r);
+            if (filter.limit && results.length >= filter.limit)
+                break;
+        }
+        return results;
+    }
+    clear() {
+        this.records = [];
+    }
+}

package/dist/middleware/guardrails/error_tracker.d.ts

@@ -0,0 +1,34 @@
+export declare enum ErrorCategory {
+    TIMEOUT = "timeout",
+    NOT_FOUND = "not_found",
+    INVALID_ARGS = "invalid_args",
+    PERMISSION = "permission",
+    RATE_LIMIT = "rate_limit",
+    UNKNOWN = "unknown"
+}
+export interface ToolError {
+    timestamp: Date;
+    tool: string;
+    args: Record<string, unknown>;
+    category: ErrorCategory;
+    message: string;
+    sessionId: string;
+    retryCount: number;
+}
+export declare class ErrorTracker {
+    private errors;
+    private maxErrorsPerTool;
+    private windowDurationMs;
+    constructor(maxErrorsPerTool?: number, windowDurationMinutes?: number);
+    setThresholds(maxErrors: number, windowMinutes: number): void;
+    recordError(sessionId: string, tool: string, args: Record<string, unknown>, err: Error, category: ErrorCategory): void;
+    private getRetryCount;
+    private pruneOldErrors;
+    getErrorCount(sessionId: string, tool: string): number;
+    getRecentErrors(sessionId: string): ToolError[];
+    getErrorsByCategory(sessionId: string, category: ErrorCategory): ToolError[];
+    isErrorRateExceeded(sessionId: string, tool: string): boolean;
+    resetSession(sessionId: string): void;
+    shouldBlockTool(sessionId: string, tool: string): boolean;
+}
+//# sourceMappingURL=error_tracker.d.ts.map

package/dist/middleware/guardrails/error_tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error_tracker.d.ts","sourceRoot":"","sources":["../../../src/middleware/guardrails/error_tracker.ts"],"names":[],"mappings":"AAAA,oBAAY,aAAa;IACvB,OAAO,YAAY;IACnB,SAAS,cAAc;IACvB,YAAY,iBAAiB;IAC7B,UAAU,eAAe;IACzB,UAAU,eAAe;IACzB,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,IAAI,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,gBAAgB,CAAS;gBAErB,gBAAgB,GAAE,MAAU,EAAE,qBAAqB,GAAE,MAAU;IAM3E,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAK7D,WAAW,CACT,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,KAAK,EACV,QAAQ,EAAE,aAAa,GACtB,IAAI;IAqBP,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,cAAc;IAatB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAItD,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE;IAK/C,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,SAAS,EAAE;IAI5E,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7D,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;CAG1D"}

package/dist/middleware/guardrails/error_tracker.js

@@ -0,0 +1,70 @@
+export var ErrorCategory;
+(function (ErrorCategory) {
+    ErrorCategory["TIMEOUT"] = "timeout";
+    ErrorCategory["NOT_FOUND"] = "not_found";
+    ErrorCategory["INVALID_ARGS"] = "invalid_args";
+    ErrorCategory["PERMISSION"] = "permission";
+    ErrorCategory["RATE_LIMIT"] = "rate_limit";
+    ErrorCategory["UNKNOWN"] = "unknown";
+})(ErrorCategory || (ErrorCategory = {}));
+export class ErrorTracker {
+    errors;
+    maxErrorsPerTool;
+    windowDurationMs;
+    constructor(maxErrorsPerTool = 5, windowDurationMinutes = 5) {
+        this.errors = new Map();
+        this.maxErrorsPerTool = maxErrorsPerTool;
+        this.windowDurationMs = windowDurationMinutes * 60 * 1000;
+    }
+    setThresholds(maxErrors, windowMinutes) {
+        this.maxErrorsPerTool = maxErrors;
+        this.windowDurationMs = windowMinutes * 60 * 1000;
+    }
+    recordError(sessionId, tool, args, err, category) {
+        if (!this.errors.has(sessionId)) {
+            this.errors.set(sessionId, []);
+        }
+        const retryCount = this.getRetryCount(sessionId, tool);
+        const toolErr = {
+            timestamp: new Date(),
+            tool,
+            args,
+            category,
+            message: err.message,
+            sessionId,
+            retryCount,
+        };
+        this.errors.get(sessionId).push(toolErr);
+        this.pruneOldErrors(sessionId);
+    }
+    getRetryCount(sessionId, tool) {
+        return (this.errors.get(sessionId) || []).filter((e) => e.tool === tool).length;
+    }
+    pruneOldErrors(sessionId) {
+        const errors = this.errors.get(sessionId);
+        if (!errors || errors.length <= this.maxErrorsPerTool) {
+            return;
+        }
+        const cutoff = new Date(Date.now() - this.windowDurationMs);
+        this.errors.set(sessionId, errors.filter((e) => e.timestamp > cutoff));
+    }
+    getErrorCount(sessionId, tool) {
+        return (this.errors.get(sessionId) || []).filter((e) => e.tool === tool).length;
+    }
+    getRecentErrors(sessionId) {
+        this.pruneOldErrors(sessionId);
+        return [...(this.errors.get(sessionId) || [])];
+    }
+    getErrorsByCategory(sessionId, category) {
+        return (this.errors.get(sessionId) || []).filter((e) => e.category === category);
+    }
+    isErrorRateExceeded(sessionId, tool) {
+        return this.getErrorCount(sessionId, tool) >= this.maxErrorsPerTool;
+    }
+    resetSession(sessionId) {
+        this.errors.delete(sessionId);
+    }
+    shouldBlockTool(sessionId, tool) {
+        return this.isErrorRateExceeded(sessionId, tool);
+    }
+}

package/dist/middleware/guardrails/nudge.d.ts

@@ -0,0 +1,17 @@
+export declare enum NudgeKind {
+    RETRY = "retry",
+    UNKNOWN_TOOL = "unknown_tool",
+    STEP = "step",
+    PREREQUISITE = "prerequisite"
+}
+export interface Nudge {
+    role: string;
+    content: string;
+    kind: NudgeKind;
+    tier: number;
+}
+export declare function retryNudge(_rawResponse: string, toolNames: string[]): Nudge;
+export declare function unknownToolNudge(toolName: string, toolNames: string[]): Nudge;
+export declare function stepNudge(terminalTool: string, pendingSteps: string[], tier?: number): Nudge;
+export declare function prerequisiteNudge(toolName: string, missingPrereqs: string[]): Nudge;
+//# sourceMappingURL=nudge.d.ts.map

package/dist/middleware/guardrails/nudge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nudge.d.ts","sourceRoot":"","sources":["../../../src/middleware/guardrails/nudge.ts"],"names":[],"mappings":"AAAA,oBAAY,SAAS;IACnB,KAAK,UAAU;IACf,YAAY,iBAAiB;IAC7B,IAAI,SAAS;IACb,YAAY,iBAAiB;CAC9B;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAeD,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,KAAK,CAQ3E;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,KAAK,CAQ7E;AAED,wBAAgB,SAAS,CACvB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EAAE,EACtB,IAAI,GAAE,MAAU,GACf,KAAK,CAsBP;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EAAE,GACvB,KAAK,CAQP"}

package/dist/middleware/guardrails/nudge.js

@@ -0,0 +1,67 @@
+export var NudgeKind;
+(function (NudgeKind) {
+    NudgeKind["RETRY"] = "retry";
+    NudgeKind["UNKNOWN_TOOL"] = "unknown_tool";
+    NudgeKind["STEP"] = "step";
+    NudgeKind["PREREQUISITE"] = "prerequisite";
+})(NudgeKind || (NudgeKind = {}));
+function joinToolNames(names) {
+    if (names.length === 0) {
+        return "(no tools available)";
+    }
+    if (names.length === 1) {
+        return names[0];
+    }
+    if (names.length === 2) {
+        return `${names[0]} and ${names[1]}`;
+    }
+    return names.slice(0, -1).join(", ") + `, and ${names[names.length - 1]}`;
+}
+export function retryNudge(_rawResponse, toolNames) {
+    const toolsList = joinToolNames(toolNames);
+    return {
+        role: "user",
+        content: `Your previous response was not a valid tool call. You must respond with a tool call, not free text. Available tools: ${toolsList}. Please try again with a valid tool call.`,
+        kind: NudgeKind.RETRY,
+        tier: 0,
+    };
+}
+export function unknownToolNudge(toolName, toolNames) {
+    const toolsList = joinToolNames(toolNames);
+    return {
+        role: "user",
+        content: `Tool '${toolName}' does not exist. Available tools: ${toolsList}. Call one of them.`,
+        kind: NudgeKind.UNKNOWN_TOOL,
+        tier: 0,
+    };
+}
+export function stepNudge(terminalTool, pendingSteps, tier = 1) {
+    const clampedTier = Math.max(1, Math.min(3, tier));
+    const steps = joinToolNames(pendingSteps);
+    let content;
+    switch (clampedTier) {
+        case 1:
+            content = `You cannot call ${terminalTool} yet. You must first complete these required steps: ${steps}. Call one of them now.`;
+            break;
+        case 2:
+            content = `You must call one of these tools now: ${steps}. Pick one.`;
+            break;
+        default:
+            content = `STOP. You MUST call one of: ${steps}. Do NOT call ${terminalTool}. Your next response MUST be a tool call to one of: ${steps}.`;
+    }
+    return {
+        role: "user",
+        content,
+        kind: NudgeKind.STEP,
+        tier: clampedTier,
+    };
+}
+export function prerequisiteNudge(toolName, missingPrereqs) {
+    const prereqs = joinToolNames(missingPrereqs);
+    return {
+        role: "user",
+        content: `You cannot call ${toolName} yet. You must first call: ${prereqs}. Call the prerequisite tool now.`,
+        kind: NudgeKind.PREREQUISITE,
+        tier: 0,
+    };
+}

package/dist/middleware/guardrails/response_validator.d.ts

@@ -0,0 +1,29 @@
+import { Nudge } from "./nudge";
+export interface ToolCall {
+    tool: string;
+    args: Record<string, unknown>;
+}
+export interface ValidationResult {
+    toolCalls: ToolCall[];
+    nudge: Nudge | null;
+    needsRetry: boolean;
+}
+export declare class ResponseValidator {
+    private toolNames;
+    private rescueEnabled;
+    private retryNudgeFn;
+    private thinkPattern;
+    private pythonTagPattern;
+    private codeFencePattern;
+    private rehearsalPattern;
+    private qwenFunctionPattern;
+    constructor(toolNames: string[], rescueEnabled?: boolean, retryNudgeFn?: (rawResponse: string, toolNames: string[]) => Nudge);
+    validateTextResponse(response: string): ValidationResult;
+    validateToolCalls(toolCalls: ToolCall[]): ValidationResult;
+    private rescueToolCall;
+    private extractJsonToolCalls;
+    private tryParseToolCall;
+    private extractRehearsalToolCalls;
+    private extractQwenXmlToolCalls;
+}
+//# sourceMappingURL=response_validator.d.ts.map

package/dist/middleware/guardrails/response_validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response_validator.d.ts","sourceRoot":"","sources":["../../../src/middleware/guardrails/response_validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAgC,MAAM,SAAS,CAAC;AAE9D,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,aAAa,CAAU;IAC/B,OAAO,CAAC,YAAY,CAAsD;IAE1E,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,mBAAmB,CAAS;gBAGlC,SAAS,EAAE,MAAM,EAAE,EACnB,aAAa,GAAE,OAAc,EAC7B,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,KAAK;IAapE,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB;IAYxD,iBAAiB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,gBAAgB;IAoB1D,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,oBAAoB;IAqC5B,OAAO,CAAC,gBAAgB;IAuBxB,OAAO,CAAC,yBAAyB;IA0BjC,OAAO,CAAC,uBAAuB;CAGhC"}