@weave-kit/engine 0.1.0

package/dist/runtime/sql-analyzer/index.d.ts

@@ -0,0 +1,47 @@
+import type { Locale } from '../../core/index.js';
+/**
+ * SQL analyzer — PostgreSQL query analysis for the script sandbox's restricted
+ * SQL (`this.db.query`) and, later, any consumer that needs to understand the
+ * tables/columns a query references.
+ *
+ * Parsing is done by `pgsql-parser` (a WASM build of PostgreSQL's own parser,
+ * `libpg_query`), so a query that parses here is guaranteed valid PG syntax —
+ * the parser and the database share a grammar. The analyzer is **fail-closed**:
+ * any parse error, multi-statement input, or non-SELECT statement throws
+ * `script.query.invalid`, so the caller can never run SQL the analyzer does not
+ * fully understand.
+ *
+ * The returned column references cover the whole statement tree (target list,
+ * WHERE/HAVING, ORDER BY, GROUP BY, join conditions, subqueries) because the
+ * AST walk visits every `ColumnRef` regardless of position. The AST also
+ * disambiguates what a string scan cannot: a projection `*`/`t.*` is a
+ * `ColumnRef` with `A_Star`, while `count(*)` is a `FuncCall` `agg_star` flag
+ * and produces no column reference at all.
+ */
+export interface SqlColumnRef {
+    /** table alias or table name (the `ColumnRef` qualifier); undefined for bare columns */
+    qualifier?: string;
+    /** column name, or `'*'` for a star reference (`*` / `t.*`) */
+    column: string;
+    /** whether this reference is a star */
+    star: boolean;
+}
+export interface SqlAnalysis {
+    /** distinct referenced table names (`RangeVar.relname`) */
+    tables: string[];
+    /** alias → table-name map (table names map to themselves) for qualifier resolution */
+    resolvers: Record<string, string>;
+    /** every column reference in the statement (target/where/order/group/having/joins/subqueries) */
+    columnRefs: SqlColumnRef[];
+}
+export interface SqlAnalyzer {
+    /** warm up the WASM module (engine startup preload — avoids cold start on first use) */
+    ensureLoaded(): Promise<void>;
+    /**
+     * Parse + analyze exactly one SELECT statement.
+     * @throws SchemaError('script.query.invalid') on parse error, multi-statement input, or non-SELECT
+     */
+    analyzeSelect(sql: string, locale?: Locale): Promise<SqlAnalysis>;
+}
+export declare function createSqlAnalyzer(): SqlAnalyzer;
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/sql-analyzer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/sql-analyzer/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAIlD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,YAAY;IAC3B,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,iGAAiG;IACjG,UAAU,EAAE,YAAY,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,wFAAwF;IACxF,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B;;;OAGG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACnE;AAOD,wBAAgB,iBAAiB,IAAI,WAAW,CAyD/C"}

package/dist/runtime/sql-analyzer/index.js

@@ -0,0 +1,58 @@
+import { SchemaError } from '../../core/index.js';
+import { parse } from 'pgsql-parser';
+import { walk } from '@pgsql/traverse';
+export function createSqlAnalyzer() {
+    // `parse` awaits the WASM module init on first call — preloading with a
+    // trivial probe removes the cold start from the first real db.query.
+    let loaded;
+    return {
+        async ensureLoaded() {
+            if (loaded === undefined) {
+                loaded = parse('SELECT 1').then(() => undefined);
+            }
+            await loaded;
+        },
+        async analyzeSelect(sql, locale) {
+            let ast;
+            try {
+                ast = await parse(sql);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new SchemaError('script.query.invalid', { detail: message }, locale);
+            }
+            const stmts = ast.stmts ?? [];
+            if (stmts.length !== 1) {
+                throw new SchemaError('script.query.invalid', { detail: 'exactly one statement is allowed' }, locale);
+            }
+            if (stmts[0]?.stmt?.SelectStmt === undefined) {
+                throw new SchemaError('script.query.invalid', { detail: 'only SELECT statements are allowed' }, locale);
+            }
+            const tables = [];
+            const resolvers = {};
+            const columnRefs = [];
+            walk(ast, {
+                RangeVar: (path) => {
+                    const node = path.node;
+                    if (node.relname === undefined)
+                        return;
+                    tables.push(node.relname);
+                    resolvers[node.relname] = node.relname;
+                    if (node.alias?.aliasname !== undefined)
+                        resolvers[node.alias.aliasname] = node.relname;
+                },
+                ColumnRef: (path) => {
+                    const node = path.node;
+                    const fields = node.fields ?? [];
+                    const quals = fields.filter((f) => f.String !== undefined).map((f) => f.String.sval);
+                    const star = fields.some((f) => f.A_Star !== undefined);
+                    columnRefs.push(star
+                        ? { qualifier: quals.length >= 1 ? quals[0] : undefined, column: '*', star: true }
+                        : { qualifier: quals.length > 1 ? quals[0] : undefined, column: quals[quals.length - 1] ?? '', star: false });
+                },
+            });
+            return { tables: [...new Set(tables)], resolvers, columnRefs };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/runtime/sql-analyzer/index.js.map

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

package/dist/runtime/tools/executor.d.ts

@@ -0,0 +1,69 @@
+import type { Pool } from 'pg';
+import type { AuditSink, RbacSubject, Locale, ObjectRegistry, ToolActor, ToolApprovals, ApprovalsBackend, ToolDefinition, ToolGuardrails, ToolJsonSchema, ToolResult, ApprovalStatus, PendingApproval, GuardrailPolicy } from '../../core/index.js';
+import type { ObjectDataAccess } from '../data-access/index.js';
+/**
+ * Custom-tool execution pipeline (M10b, protocol-agnostic). Wraps the injected
+ * (RBAC-decorated) data-access with the controlled `ToolDataAccess` surface,
+ * builds the `ToolCallContext` a handler receives, runs the handler with
+ * auto-audit and wires `withTx`. `adapters/mcp` binds protocol specifics
+ * (`McpSession → ToolActor`, `mcp.tool.<name>` action) on top of this.
+ *
+ * M10c adds the guardrail policy pipeline (`evaluatePolicies`) in front of
+ * `execute`; approvals already live here as the queue the executor exposes.
+ */
+/** deterministic approval key for a pending decision (repeat calls don't duplicate) */
+export declare function approvalKeyFor(actor: ToolActor, action: string, args: Record<string, unknown>): string;
+/** full approval queue handle (query/approve/reject + enqueue for the policy gate; async — persisted backend) */
+export type ApprovalsQueue = ToolApprovals & {
+    pending(action: string, args: Record<string, unknown>, actor: ToolActor, key?: string): Promise<void>;
+};
+/**
+ * Approval queue (D1, release-grade): thin facade over a pluggable
+ * `ApprovalsBackend` (in-memory default; PG in `subsystems/approvals`). No Redis
+ * backend is implemented. `approvalKey` stays deterministic; resolution (A7)
+ * is audited here, never by the store. Async because the backend performs I/O.
+ */
+export declare function createApprovals(options?: {
+    audit?: AuditSink;
+    backend?: ApprovalsBackend;
+}): ApprovalsQueue;
+export interface ToolExecutorOptions {
+    /** RBAC-decorated object data-access the controlled surface wraps */
+    dataAccess: ObjectDataAccess;
+    /** pool + registry the tool data-access contexts are built on */
+    pool: Pool;
+    registry: ObjectRegistry;
+    audit?: AuditSink;
+    /** rate-limit / alert handle (adapter-provided; agentKey scope) */
+    guardrails: ToolGuardrails;
+    approvals?: ApprovalsQueue;
+    /** M10c: guardrail policies evaluated before every custom-tool call (empty = no gate) */
+    policies?: GuardrailPolicy[];
+    locale?: Locale;
+}
+export interface CustomToolExecuteRequest {
+    subject: RbacSubject;
+    actor: ToolActor;
+    /** audit action, e.g. `mcp.tool.<name>` (protocol binding decides the prefix) */
+    action: string;
+    /** caller-supplied arguments passed through to the handler ctx */
+    args: Record<string, unknown>;
+    locale?: Locale;
+}
+/** a compiled, subject-visible custom tool entry (used by `tools/list` merging) */
+export interface CustomToolSurfaceEntry {
+    name: string;
+    description: string;
+    inputSchema: ToolJsonSchema;
+}
+export interface ToolExecutor {
+    /** roles-filtered custom-tool surface for a subject (per-subject cached, D8) */
+    surface(subject: RbacSubject, customTools: ToolDefinition[]): CustomToolSurfaceEntry[];
+    /** execute a custom tool with a controlled ctx + auto-audit (+ policies in M10c) */
+    execute(def: ToolDefinition, args: Record<string, unknown>, req: CustomToolExecuteRequest): Promise<ToolResult>;
+    /** approval queue handle (M10c promotes it to `engine.tools.approvals`) */
+    approvals: ToolApprovals;
+}
+export declare function createToolExecutor(options: ToolExecutorOptions): ToolExecutor;
+export type { ToolApprovals, ApprovalStatus, PendingApproval };
+//# sourceMappingURL=executor.d.ts.map

package/dist/runtime/tools/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/runtime/tools/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAG/B,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAuD,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,eAAe,EAAoB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3T,OAAO,KAAK,EAAE,gBAAgB,EAAkC,MAAM,yBAAyB,CAAC;AAIhG;;;;;;;;;GASG;AAEH,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAQtG;AAED,iHAAiH;AACjH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG;IAC3C,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvG,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAAO,GAC9D,cAAc,CAqDhB;AAED,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,UAAU,EAAE,gBAAgB,CAAC;IAC7B,iEAAiE;IACjE,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,mEAAmE;IACnE,UAAU,EAAE,cAAc,CAAC;IAC3B,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,EAAE,SAAS,CAAC;IACjB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,cAAc,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,sBAAsB,EAAE,CAAC;IACvF,oFAAoF;IACpF,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,wBAAwB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAChH,2EAA2E;IAC3E,SAAS,EAAE,aAAa,CAAC;CAC1B;AAcD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAiH7E;AAED,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC"}

package/dist/runtime/tools/executor.js

@@ -0,0 +1,204 @@
+import { NOOP_AUDIT_SINK, createMemoryApprovalsBackend } from '../../core/index.js';
+import { AUDIT_ACTOR_TYPES } from '../../core/index.js';
+import { withTx as dataAccessWithTx } from '../data-access/index.js';
+import { applyMask, evaluateCall } from './policies.js';
+/**
+ * Custom-tool execution pipeline (M10b, protocol-agnostic). Wraps the injected
+ * (RBAC-decorated) data-access with the controlled `ToolDataAccess` surface,
+ * builds the `ToolCallContext` a handler receives, runs the handler with
+ * auto-audit and wires `withTx`. `adapters/mcp` binds protocol specifics
+ * (`McpSession → ToolActor`, `mcp.tool.<name>` action) on top of this.
+ *
+ * M10c adds the guardrail policy pipeline (`evaluatePolicies`) in front of
+ * `execute`; approvals already live here as the queue the executor exposes.
+ */
+/** deterministic approval key for a pending decision (repeat calls don't duplicate) */
+export function approvalKeyFor(actor, action, args) {
+    const raw = JSON.stringify([actor.key, action, args]);
+    let hash = 0;
+    for (let i = 0; i < raw.length; i += 1) {
+        hash = (hash << 5) - hash + raw.charCodeAt(i);
+        hash |= 0;
+    }
+    return `ap-${Math.abs(hash).toString(36)}`;
+}
+/**
+ * Approval queue (D1, release-grade): thin facade over a pluggable
+ * `ApprovalsBackend` (in-memory default; PG in `subsystems/approvals`). No Redis
+ * backend is implemented. `approvalKey` stays deterministic; resolution (A7)
+ * is audited here, never by the store. Async because the backend performs I/O.
+ */
+export function createApprovals(options = {}) {
+    const backend = options.backend ?? createMemoryApprovalsBackend();
+    const audit = options.audit ?? NOOP_AUDIT_SINK;
+    const resolve = async (approvalKey, by, status) => {
+        const ok = await backend.resolve(approvalKey, by, status);
+        if (ok) {
+            const entry = await backend.get(approvalKey);
+            // A7: approval/rejection actions are audited against the same action
+            void audit
+                .record({
+                actorType: AUDIT_ACTOR_TYPES.USER,
+                actorId: by,
+                action: entry?.action ?? '',
+                objectName: undefined,
+                changes: entry?.args,
+                isError: false,
+                meta: { approvalKey, approver: by, status },
+                timestamp: new Date(),
+            })
+                .catch(() => { });
+        }
+        return ok;
+    };
+    return {
+        list(filter) {
+            return backend.list(filter);
+        },
+        count(filter) {
+            return backend.count(filter);
+        },
+        async query(status) {
+            return backend.list(status === undefined ? {} : { status });
+        },
+        approve(approvalKey, by) {
+            return resolve(approvalKey, by, 'approved');
+        },
+        reject(approvalKey, by) {
+            return resolve(approvalKey, by, 'rejected');
+        },
+        async pending(action, args, actor, key) {
+            const entry = {
+                approvalKey: key ?? approvalKeyFor(actor, action, args),
+                action,
+                args,
+                status: 'pending',
+                createdAt: new Date(),
+                actorKey: actor.key,
+            };
+            await backend.upsert(entry);
+        },
+    };
+}
+function rolesKey(subject) {
+    return `${subject.id}:${[...subject.roles].sort().join(',')}`;
+}
+function toolsKey(customTools) {
+    return customTools.map((t) => t.name).sort().join(',');
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function createToolExecutor(options) {
+    const real = options.dataAccess;
+    const audit = options.audit ?? NOOP_AUDIT_SINK;
+    const approvals = options.approvals ?? createApprovals({ audit });
+    const surfaceCache = new Map();
+    /** controlled surface over a data-access context (base = pool/registry/locale, + client in tx) */
+    function toolDataAccess(base) {
+        return {
+            find: (n, o, c) => real.find(n, o, { ...base, ...c }),
+            findOne: (n, id, c) => real.findOne(n, id, { ...base, ...c }),
+            create: (n, d, c) => real.create(n, d, { ...base, ...c }),
+            update: (n, id, ch, c) => real.update(n, id, ch, { ...base, ...c }),
+            delete: (n, id, c) => real.delete(n, id, { ...base, ...c }),
+        };
+    }
+    /** the ToolCallContext a handler receives for the given data-access base */
+    function toolContext(base, req) {
+        const da = toolDataAccess(base);
+        return {
+            dataAccess: da,
+            subject: req.subject,
+            actor: req.actor,
+            args: req.args,
+            action: req.action,
+            audit,
+            guardrails: options.guardrails,
+            approvals,
+            withTx: async (fn) => {
+                return dataAccessWithTx(base, async (txCtx) => fn(toolContext(txCtx, req)));
+            },
+        };
+    }
+    return {
+        approvals,
+        surface(subject, customTools) {
+            const key = `${rolesKey(subject)}:${toolsKey(customTools)}`;
+            const hit = surfaceCache.get(key);
+            if (hit !== undefined)
+                return hit;
+            const roles = new Set(subject.roles);
+            const entries = customTools
+                .filter((t) => t.roles === undefined || t.roles.some((r) => roles.has(r)))
+                .map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }));
+            surfaceCache.set(key, entries);
+            return entries;
+        },
+        async execute(def, args, req) {
+            const base = {
+                pool: options.pool,
+                registry: options.registry,
+                locale: req.locale ?? options.locale,
+            };
+            const ctx = toolContext(base, req);
+            const started = Date.now();
+            const event = (isError, errorCode, extra) => ({
+                actorType: AUDIT_ACTOR_TYPES.AGENT,
+                actorId: req.actor.key,
+                action: req.action,
+                objectName: undefined,
+                changes: args,
+                isError,
+                errorCode,
+                meta: {
+                    onBehalfOf: req.actor.onBehalfOf,
+                    subjectId: req.subject.id,
+                    roles: req.subject.roles,
+                    agentLabel: req.actor.label,
+                    tool: def.name,
+                    latencyMs: Date.now() - started,
+                    ...extra,
+                },
+                timestamp: new Date(),
+            });
+            // M10c: guardrail policy gate before the handler (allow / deny / requireApproval / mask)
+            let mask;
+            if (options.policies !== undefined && options.policies.length > 0) {
+                const guardrailCtx = {
+                    actor: req.actor,
+                    subject: req.subject,
+                    action: req.action,
+                    args,
+                    dataAccess: toolDataAccess(base),
+                };
+                const gate = await evaluateCall(options.policies, approvals, guardrailCtx);
+                if (gate.kind === 'deny') {
+                    void audit.record(event(true, gate.errorCode, { policyReason: gate.reason })).catch(() => { });
+                    return { content: [{ type: 'text', text: gate.reason }], isError: true };
+                }
+                if (gate.kind === 'pending') {
+                    void audit.record(event(true, 'mcp.approval.pending', { approvalKey: gate.approvalKey })).catch(() => { });
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({ approvalKey: gate.approvalKey, status: 'pending' }) }],
+                        isError: true,
+                    };
+                }
+                mask = gate.mask;
+            }
+            try {
+                let result = await def.handler(ctx);
+                if (mask !== undefined && Object.keys(mask).length > 0)
+                    result = applyMask(result, mask);
+                void audit.record(event(false)).catch(() => { });
+                return result;
+            }
+            catch (error) {
+                const code = error instanceof Error && 'code' in error ? String(error.code) : undefined;
+                void audit.record(event(true, code)).catch(() => { });
+                return { content: [{ type: 'text', text: errorText(error) }], isError: true };
+            }
+        },
+    };
+}
+//# sourceMappingURL=executor.js.map

package/dist/runtime/tools/executor.js.map

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

package/dist/runtime/tools/index.d.ts

@@ -0,0 +1,5 @@
+export { loadToolsDir, validateToolDefinition } from './loader.js';
+export type { LoadedTool } from './loader.js';
+export { createToolExecutor, createApprovals, approvalKeyFor } from './executor.js';
+export type { ToolExecutor, ToolExecutorOptions, CustomToolExecuteRequest, CustomToolSurfaceEntry, ApprovalsQueue, } from './executor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACnE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpF,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,cAAc,GACf,MAAM,eAAe,CAAC"}

package/dist/runtime/tools/index.js

@@ -0,0 +1,3 @@
+export { loadToolsDir, validateToolDefinition } from './loader.js';
+export { createToolExecutor, createApprovals, approvalKeyFor } from './executor.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/runtime/tools/loader.d.ts

@@ -0,0 +1,14 @@
+import type { Locale, ToolDefinition } from '../../core/index.js';
+export interface LoadedTool {
+    /** absolute path of the tool module */
+    path: string;
+    /** validated tool definition */
+    definition: ToolDefinition;
+}
+/** structural validation of a tool module's default export */
+export declare function validateToolDefinition(raw: unknown, locale?: Locale): ToolDefinition;
+/** load + validate every tool module under a directory (missing dir → `tools.dir.missing`) */
+export declare function loadToolsDir(dir: string, options?: {
+    locale?: Locale;
+}): Promise<LoadedTool[]>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/runtime/tools/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/runtime/tools/loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAgBlE,MAAM,WAAW,UAAU;IACzB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,UAAU,EAAE,cAAc,CAAC;CAC5B;AAUD,8DAA8D;AAC9D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc,CA2CpF;AAUD,8FAA8F;AAC9F,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAwBxG"}

package/dist/runtime/tools/loader.js

@@ -0,0 +1,98 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { SchemaError, TOOL_NAME_PATTERN, isReservedToolName } from '../../core/index.js';
+/**
+ * Tool loader (`toolsDir`). Dynamic-imports a directory of tool modules whose
+ * default export satisfies `ToolDefinition`. Startup validation is structural
+ * only: name format, reserved-name collision, description/inputSchema/handler
+ * presence. `roles` is an allow-list and is NOT validated (the engine has no
+ * role registry) — a single informational warn is emitted per tool.
+ *
+ * Node runtime import constraint: the engine loads compiled products
+ * (`.js/.mjs/.cjs`); `.ts` is accepted when a tsx/loader is registered (dev).
+ * The CLI (`weave dev/build`) compiles `tools/*.ts` for production.
+ */
+const TOOL_FILE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.ts'];
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function invalid(detail, locale) {
+    return new SchemaError('tools.tool.invalid', { detail }, locale);
+}
+/** structural validation of a tool module's default export */
+export function validateToolDefinition(raw, locale) {
+    if (!isPlainObject(raw)) {
+        throw invalid('tool module must default-export a plain object', locale);
+    }
+    const { name, description, inputSchema, roles, handler } = raw;
+    if (typeof name !== 'string') {
+        throw new SchemaError('tools.tool.name.invalid', { name: String(name ?? ''), pattern: TOOL_NAME_PATTERN }, locale);
+    }
+    // reserved-name collision (incl. the `mcp.` audit namespace) reported before
+    // the pattern so `mcp.<x>` names surface the explicit reserved error
+    if (isReservedToolName(name)) {
+        throw new SchemaError('tools.tool.name.reserved', { name }, locale);
+    }
+    if (!new RegExp(TOOL_NAME_PATTERN).test(name)) {
+        throw new SchemaError('tools.tool.name.invalid', { name, pattern: TOOL_NAME_PATTERN }, locale);
+    }
+    if (typeof description !== 'string') {
+        throw invalid(`"${String(name)}" requires a string description`, locale);
+    }
+    if (typeof handler !== 'function') {
+        throw new SchemaError('tools.tool.handler.missing', { name }, locale);
+    }
+    if (!isPlainObject(inputSchema)) {
+        throw new SchemaError('tools.tool.schema.invalid', { name }, locale);
+    }
+    if (roles !== undefined && (!Array.isArray(roles) || roles.some((r) => typeof r !== 'string'))) {
+        throw invalid(`"${String(name)}" roles must be a string array`, locale);
+    }
+    if (roles !== undefined) {
+        // allow-list semantics; the engine cannot validate roles, so just inform
+        console.warn(`[weavekit:tools] tool "${name}" roles are an allow-list — roles not listed here never see this tool`);
+    }
+    return {
+        name,
+        description,
+        inputSchema: inputSchema,
+        roles: roles,
+        handler: handler,
+    };
+}
+async function collectToolFiles(dir, out) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (TOOL_FILE_EXTENSIONS.some((ext) => entry.name.endsWith(ext)))
+            out.push(join(dir, entry.name));
+    }
+}
+/** load + validate every tool module under a directory (missing dir → `tools.dir.missing`) */
+export async function loadToolsDir(dir, options = {}) {
+    let isDir = false;
+    try {
+        isDir = (await stat(dir)).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        throw new SchemaError('tools.dir.missing', { dir }, options.locale);
+    }
+    const files = [];
+    await collectToolFiles(dir, files);
+    const tools = [];
+    for (const file of files.sort()) {
+        const mod = await import(pathToFileURL(file).href);
+        const raw = mod.default;
+        if (raw === undefined) {
+            throw invalid(`"${file}" has no default export`, options.locale);
+        }
+        tools.push({ path: file, definition: validateToolDefinition(raw, options.locale) });
+    }
+    return tools;
+}
+//# sourceMappingURL=loader.js.map

package/dist/runtime/tools/loader.js.map

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

package/dist/runtime/tools/policies.d.ts

@@ -0,0 +1,46 @@
+import type { ApprovalStatus, GuardrailContext, GuardrailPolicy, ToolResult } from '../../core/index.js';
+/**
+ * Guardrail policy pipeline (M10c) on top of the pure `evaluatePolicies` core:
+ * policy loading (array or directory of `.js` modules), the approval gate
+ * (deterministic key → pending → host approve → client retry, A2) and result
+ * masking (JSON top-level field replacement, A4). Fail-closed and the
+ * decision matrix live in the core evaluator.
+ */
+export type PolicyGateResult = {
+    kind: 'allow';
+    mask?: Record<string, string>;
+} | {
+    kind: 'deny';
+    reason: string;
+    errorCode: string;
+} | {
+    kind: 'pending';
+    approvalKey: string;
+};
+export interface PolicyApprovals {
+    query(): Promise<Array<{
+        approvalKey: string;
+        status: ApprovalStatus;
+        action: string;
+        args: Record<string, unknown>;
+    }>>;
+    pending(action: string, args: Record<string, unknown>, actor: {
+        key: string;
+    }, key?: string): Promise<void>;
+}
+/** deterministic approval key (repeat calls don't duplicate) — mirror of the executor helper */
+export declare function policyApprovalKey(actorKey: string, action: string, args: Record<string, unknown>): string;
+/**
+ * Run the decision pipeline and resolve the approval lifecycle for one call:
+ * already approved → allow (client retry path); rejected → deny; unknown →
+ * enqueue pending → report `pending`. The caller (executor) turns deny/pending
+ * into isError results + audits.
+ */
+export declare function evaluateCall(policies: GuardrailPolicy[], approvals: PolicyApprovals, ctx: GuardrailContext): Promise<PolicyGateResult>;
+/** mask a tool result's JSON top-level fields (A4): non-JSON / parse failure passes through */
+export declare function applyMask(result: ToolResult, mask: Record<string, string>): ToolResult;
+/** load a policies directory: each module's default export is a policy or a policy array */
+export declare function loadPoliciesDir(dir: string): Promise<GuardrailPolicy[]>;
+/** resolve `tools.guardrails.policies` (array or directory path) into an array */
+export declare function resolvePolicies(source: GuardrailPolicy[] | string | undefined, baseDir: string): Promise<GuardrailPolicy[]>;
+//# sourceMappingURL=policies.d.ts.map

package/dist/runtime/tools/policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../../../src/runtime/tools/policies.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEzG;;;;;;GAMG;AAEH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC9B,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,cAAc,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC,CAAC;IACxH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7G;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAQzG;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,eAAe,EAC1B,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AAED,+FAA+F;AAC/F,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,UAAU,CAuBtF;AAID,4FAA4F;AAC5F,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAsB7E;AAED,kFAAkF;AAClF,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAIjI"}