glirastes 0.3.0 → 0.3.1

package/dist/cjs/server/core/zod-compact.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zodToCompactDescription = zodToCompactDescription;
+/**
+ * Convert a Zod schema to a compact TypeScript-like description string.
+ *
+ * Used to auto-generate "Returns: ..." suffixes for AI tool descriptions,
+ * so the LLM knows the response shape without bloating the system prompt.
+ *
+ * @example
+ * zodToCompactDescription(z.object({
+ *   tasks: z.array(z.object({ id: z.string(), title: z.string() })),
+ *   total: z.number(),
+ * }))
+ * // → '{ tasks: Array<{ id: string, title: string }>, total: number }'
+ *
+ * @param schema - Any Zod schema
+ * @param maxDepth - Maximum nesting depth before collapsing to "..." (default: 3)
+ */
+function zodToCompactDescription(schema, maxDepth = 3) {
+    return describeSchema(schema, 0, maxDepth);
+}
+function describeSchema(schema, depth, maxDepth) {
+    if (depth >= maxDepth)
+        return '...';
+    const def = schema._def;
+    const typeName = def?.typeName;
+    switch (typeName) {
+        case 'ZodString':
+            return 'string';
+        case 'ZodNumber':
+            return 'number';
+        case 'ZodBoolean':
+            return 'boolean';
+        case 'ZodDate':
+            return 'string'; // Dates serialize as strings in JSON
+        case 'ZodLiteral':
+            return JSON.stringify(def.value);
+        case 'ZodNull':
+            return 'null';
+        case 'ZodUndefined':
+            return 'undefined';
+        case 'ZodAny':
+            return 'any';
+        case 'ZodUnknown':
+            return 'unknown';
+        case 'ZodVoid':
+            return 'void';
+        case 'ZodEnum':
+            return def.values
+                .map((v) => `"${v}"`)
+                .join(' | ');
+        case 'ZodNativeEnum':
+            return Object.values(def.values)
+                .filter((v) => typeof v === 'string')
+                .map((v) => `"${v}"`)
+                .join(' | ');
+        case 'ZodArray':
+            return `Array<${describeSchema(def.type, depth + 1, maxDepth)}>`;
+        case 'ZodObject': {
+            const shape = def.shape();
+            const entries = Object.entries(shape);
+            if (entries.length === 0)
+                return '{}';
+            const fields = entries.map(([key, value]) => {
+                const optional = isOptional(value);
+                const desc = describeSchema(unwrap(value), depth + 1, maxDepth);
+                const nullable = isNullable(value);
+                const suffix = nullable ? ' | null' : '';
+                return `${key}${optional ? '?' : ''}: ${desc}${suffix}`;
+            });
+            return `{ ${fields.join(', ')} }`;
+        }
+        case 'ZodRecord':
+            return `Record<string, ${describeSchema(def.valueType, depth + 1, maxDepth)}>`;
+        case 'ZodUnion':
+        case 'ZodDiscriminatedUnion': {
+            const options = def.options;
+            return options
+                .map((o) => describeSchema(o, depth + 1, maxDepth))
+                .join(' | ');
+        }
+        case 'ZodTuple': {
+            const items = def.items;
+            return `[${items.map((i) => describeSchema(i, depth + 1, maxDepth)).join(', ')}]`;
+        }
+        case 'ZodNullable':
+            return `${describeSchema(def.innerType, depth, maxDepth)} | null`;
+        case 'ZodOptional':
+        case 'ZodDefault':
+            return describeSchema(def.innerType, depth, maxDepth);
+        case 'ZodEffects':
+            return describeSchema(def.schema, depth, maxDepth);
+        default:
+            return 'unknown';
+    }
+}
+/** Unwrap ZodOptional / ZodNullable / ZodDefault / ZodEffects to the inner schema. */
+function unwrap(schema) {
+    const def = schema._def;
+    const typeName = def?.typeName;
+    if (typeName === 'ZodOptional' ||
+        typeName === 'ZodNullable' ||
+        typeName === 'ZodDefault') {
+        return unwrap(def.innerType);
+    }
+    if (typeName === 'ZodEffects') {
+        return unwrap(def.schema);
+    }
+    return schema;
+}
+function isOptional(schema) {
+    const def = schema._def;
+    const typeName = def?.typeName;
+    if (typeName === 'ZodOptional' || typeName === 'ZodDefault')
+        return true;
+    if (typeName === 'ZodNullable')
+        return isOptional(def.innerType);
+    return false;
+}
+function isNullable(schema) {
+    const def = schema._def;
+    const typeName = def?.typeName;
+    if (typeName === 'ZodNullable')
+        return true;
+    if (typeName === 'ZodOptional' || typeName === 'ZodDefault')
+        return isNullable(def.innerType);
+    return false;
+}

package/dist/cjs/server/index.d.ts

@@ -0,0 +1,6 @@
+export * from './core/index.js';
+export * from './pipeline.js';
+export * from './lancer/index.js';
+export { createPiiShield } from './pii-shield/index.js';
+export { createAegisDetector } from './pii-shield/index.js';
+export type { AegisLike } from './pii-shield/index.js';

package/dist/cjs/server/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAegisDetector = exports.createPiiShield = void 0;
+// Server core (includes native telemetry forwarding via TelemetrySink interface)
+__exportStar(require("./core/index.js"), exports);
+// AI pipeline (multi-stage: guardrails → classify → route → model select)
+__exportStar(require("./pipeline.js"), exports);
+// Lancer (platform client) — createLancer, ServiceBlockedError, types
+__exportStar(require("./lancer/index.js"), exports);
+// PII shield
+var index_js_1 = require("./pii-shield/index.js");
+Object.defineProperty(exports, "createPiiShield", { enumerable: true, get: function () { return index_js_1.createPiiShield; } });
+var index_js_2 = require("./pii-shield/index.js");
+Object.defineProperty(exports, "createAegisDetector", { enumerable: true, get: function () { return index_js_2.createAegisDetector; } });

package/dist/cjs/server/lancer/cache.d.ts

@@ -0,0 +1,9 @@
+export declare class Cache<T = unknown> {
+    private readonly ttl;
+    private store;
+    constructor(ttl: number);
+    set(key: string, value: T): void;
+    get(key: string): T | undefined;
+    delete(key: string): void;
+    clear(): void;
+}

package/dist/cjs/server/lancer/cache.js

@@ -0,0 +1,33 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Simple in-memory Map cache with TTL
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cache = void 0;
+class Cache {
+    ttl;
+    store = new Map();
+    constructor(ttl) {
+        this.ttl = ttl;
+    }
+    set(key, value) {
+        this.store.set(key, { value, expiresAt: Date.now() + this.ttl });
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    delete(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+exports.Cache = Cache;

package/dist/cjs/server/lancer/client.d.ts

@@ -0,0 +1,2 @@
+import type { Lancer, LancerConfig } from './types.js';
+export declare function createLancer(config: LancerConfig): Lancer;

package/dist/cjs/server/lancer/client.js

@@ -0,0 +1,279 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// createLancer — factory for the Lancer platform client
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLancer = createLancer;
+const cache_js_1 = require("./cache.js");
+const errors_js_1 = require("./errors.js");
+const telemetry_buffer_js_1 = require("./telemetry-buffer.js");
+const DEFAULT_BASE_URL = 'https://api.glirastes.chainmatics.io';
+const DEFAULT_CACHE_TTL = 60_000;
+const DEFAULT_MAX_RETRIES = 3;
+/** Built-in action per service when nothing is explicitly configured. */
+const SERVICE_DEFAULT_ACTIONS = {
+    warden: 'fallback',
+    primus: 'fallback',
+    aegis: 'fallback',
+    proctor: 'silent', // telemetry-only service — failures are always silent
+    config: 'fallback',
+    approvals: 'fallback',
+};
+/**
+ * Call `fn`; on failure resolve the degradation action for `service` and act:
+ * - 'fallback': call onDegraded (if set) and return `fallback`.
+ * - 'silent':   return `fallback` without calling onDegraded.
+ * - 'block':    throw ServiceBlockedError (propagates to the caller).
+ *
+ * Resolution order: onServiceUnavailable callback > degradation defaults > built-in default.
+ */
+async function callWithFallback(fn, fallback, service, cfg) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        // 1. Start from static default
+        let action = cfg.defaults?.[service] ?? SERVICE_DEFAULT_ACTIONS[service];
+        // 2. Let the dynamic callback override (last word)
+        if (cfg.onServiceUnavailable) {
+            action = await cfg.onServiceUnavailable({ service, error });
+        }
+        if (action === 'block') {
+            throw new errors_js_1.ServiceBlockedError(service, error);
+        }
+        if (action === 'fallback') {
+            cfg.onDegraded?.();
+        }
+        // 'silent': return fallback without notifying
+        return fallback;
+    }
+}
+function createLancer(config) {
+    const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const cacheTtl = config.cache?.ttl ?? DEFAULT_CACHE_TTL;
+    const maxRetries = config.retry?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const agentId = config.agentId;
+    const agentType = config.agentType;
+    const headers = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${config.apiKey}`,
+        ...(agentId ? { 'X-Agent-Id': agentId } : {}),
+        ...(agentType ? { 'X-Agent-Type': agentType } : {}),
+    };
+    const cache = new cache_js_1.Cache(cacheTtl);
+    const telemetryBuffer = new telemetry_buffer_js_1.TelemetryBuffer(`${baseUrl}/v1/proctor/events`, headers, maxRetries);
+    // Track config ETags per cache-key for conditional requests
+    const etags = new Map();
+    // Shared degradation config — built once, reused by every callWithFallback call.
+    const degradationCfg = {
+        defaults: config.degradation,
+        onServiceUnavailable: config.onServiceUnavailable,
+        onDegraded: config.onDegraded,
+    };
+    // ------ API helpers ------------------------------------------------------
+    async function apiFetch(path, init) {
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const res = await fetch(`${baseUrl}${path}`, {
+                    ...init,
+                    headers: { ...headers, ...init?.headers },
+                });
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                return (await res.json());
+            }
+            catch (err) {
+                lastError = err;
+            }
+        }
+        throw lastError;
+    }
+    // ------ Primus namespace (intent classification) -------------------------
+    const primus = {
+        async classify(message, modules, locale) {
+            const moduleIds = modules.map(m => m.moduleId);
+            return callWithFallback(() => apiFetch('/v1/primus/classify', {
+                method: 'POST',
+                body: JSON.stringify({ message, modules: moduleIds, ...(locale && { locale }) }),
+            }), { moduleId: '', confidence: 0, modelTier: 'standard' }, 'primus', degradationCfg);
+        },
+    };
+    // ------ Warden namespace (guardrail checks) ------------------------------
+    const warden = {
+        async check(input, policies) {
+            // Map Glirastes response (policy -> rule) so SDK interface matches
+            const result = await callWithFallback(async () => {
+                const raw = await apiFetch('/v1/warden/check', {
+                    method: 'POST',
+                    body: JSON.stringify({ input, policies }),
+                });
+                return {
+                    passed: raw.passed,
+                    violations: raw.violations.map(v => ({
+                        rule: v.policy,
+                        severity: v.severity,
+                        message: v.message,
+                    })),
+                };
+            }, { passed: true, violations: [] }, 'warden', degradationCfg);
+            return result;
+        },
+    };
+    // ------ Aegis namespace (PII detection) ----------------------------------
+    const aegis = {
+        async analyze(text, options) {
+            return callWithFallback(() => apiFetch('/v1/aegis/analyze', {
+                method: 'POST',
+                body: JSON.stringify({
+                    text,
+                    locales: options?.locales,
+                    mode: options?.mode ?? 'pseudonymize',
+                    sessionId: options?.sessionId,
+                }),
+            }), { entities: [], anonymized: text, mappingToken: null }, 'aegis', degradationCfg);
+        },
+        async rehydrate(text, mappingToken) {
+            const result = await callWithFallback(() => apiFetch('/v1/aegis/rehydrate', {
+                method: 'POST',
+                body: JSON.stringify({ text, mappingToken }),
+            }), { rehydrated: text }, 'aegis', degradationCfg);
+            return result.rehydrated;
+        },
+        async checkLeakage(text, mappingToken, locales) {
+            return callWithFallback(() => apiFetch('/v1/aegis/check-leakage', {
+                method: 'POST',
+                body: JSON.stringify({ text, mappingToken, locales }),
+            }), { leaked: false, entities: [], totalDetected: 0, filteredAsKnown: 0 }, 'aegis', degradationCfg);
+        },
+    };
+    // ------ Config namespace -------------------------------------------------
+    const configNs = {
+        async fetch(modules) {
+            const cacheKey = `config:fetch:${modules.sort().join(',')}`;
+            const cached = cache.get(cacheKey);
+            if (cached)
+                return cached;
+            const extraHeaders = {};
+            const etag = etags.get(cacheKey);
+            if (etag)
+                extraHeaders['If-None-Match'] = etag;
+            const result = await callWithFallback(async () => {
+                let lastError;
+                for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                    try {
+                        const res = await fetch(`${baseUrl}/v1/config?modules=${modules.join(',')}`, {
+                            method: 'GET',
+                            headers: { ...headers, ...extraHeaders },
+                        });
+                        if (res.status === 304) {
+                            const prev = cache.get(cacheKey);
+                            return prev ?? { modules: {} };
+                        }
+                        if (!res.ok)
+                            throw new Error(`HTTP ${res.status}`);
+                        const body = (await res.json());
+                        const newEtag = res.headers.get('etag');
+                        if (newEtag)
+                            etags.set(cacheKey, newEtag);
+                        return body;
+                    }
+                    catch (err) {
+                        lastError = err;
+                    }
+                }
+                throw lastError;
+            }, { modules: {} }, 'config', degradationCfg);
+            cache.set(cacheKey, result);
+            return result;
+        },
+        async reportModels(models) {
+            try {
+                await apiFetch('/v1/config/models/defaults', {
+                    method: 'POST',
+                    body: JSON.stringify({ models }),
+                });
+            }
+            catch {
+                // Fire-and-forget: silently ignore errors
+            }
+        },
+    };
+    // ------ Telemetry namespace ----------------------------------------------
+    const telemetry = {
+        emit(event) {
+            const enrichedEvent = agentId
+                ? {
+                    ...event,
+                    actor: {
+                        ...event.actor,
+                        agentId,
+                        ...(agentType ? { agentType } : {}),
+                    },
+                }
+                : event;
+            telemetryBuffer.add(enrichedEvent);
+        },
+        async flush() {
+            // TelemetrySink contract: flush must never throw.
+            // Errors are already handled inside TelemetryBuffer (events re-queued).
+            try {
+                await telemetryBuffer.flush();
+            }
+            catch {
+                // Silently ignore — telemetry is fire-and-forget
+            }
+        },
+    };
+    // ------ Approvals namespace -----------------------------------------------
+    const approvals = {
+        async check(req) {
+            return callWithFallback(() => apiFetch('/v1/approvals/check', {
+                method: 'POST',
+                body: JSON.stringify(req),
+            }), { required: true, requestId: null, status: 'local-fallback' }, 'approvals', degradationCfg);
+        },
+        async decide(requestId, decision) {
+            return callWithFallback(() => apiFetch(`/v1/approvals/pending/${requestId}/decide`, {
+                method: 'POST',
+                body: JSON.stringify(decision),
+            }), { ok: false }, 'approvals', degradationCfg);
+        },
+        async resolve(req) {
+            return callWithFallback(() => apiFetch('/v1/approvals/resolve', {
+                method: 'POST',
+                body: JSON.stringify(req),
+            }), { resolved: false }, 'approvals', degradationCfg);
+        },
+        hashInput(args) {
+            // Deterministic JSON hash: recursively sort keys, stringify, then hash
+            const sortKeys = (_, v) => v && typeof v === 'object' && !Array.isArray(v)
+                ? Object.keys(v).sort().reduce((o, k) => {
+                    o[k] = v[k];
+                    return o;
+                }, {})
+                : v;
+            const sorted = JSON.stringify(args, sortKeys);
+            let hash = 0;
+            for (let i = 0; i < sorted.length; i++) {
+                const char = sorted.charCodeAt(i);
+                hash = ((hash << 5) - hash + char) | 0;
+            }
+            return hash.toString(36);
+        },
+    };
+    // ------ Public surface ---------------------------------------------------
+    return {
+        primus,
+        warden,
+        aegis,
+        config: configNs,
+        telemetry,
+        approvals,
+        destroy() {
+            telemetryBuffer.destroy();
+            cache.clear();
+        },
+    };
+}

package/dist/cjs/server/lancer/errors.d.ts

@@ -0,0 +1,13 @@
+import type { LancerServiceName } from './types.js';
+/**
+ * Thrown by the Lancer client when a service is unreachable and the configured
+ * degradation action for that service is 'block'.
+ *
+ * Consumers (e.g. server-pro pipeline) should catch this error and treat the
+ * request as blocked rather than falling back silently.
+ */
+export declare class ServiceBlockedError extends Error {
+    readonly service: LancerServiceName;
+    readonly cause: Error | undefined;
+    constructor(service: LancerServiceName, cause?: Error);
+}

package/dist/cjs/server/lancer/errors.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceBlockedError = void 0;
+/**
+ * Thrown by the Lancer client when a service is unreachable and the configured
+ * degradation action for that service is 'block'.
+ *
+ * Consumers (e.g. server-pro pipeline) should catch this error and treat the
+ * request as blocked rather than falling back silently.
+ */
+class ServiceBlockedError extends Error {
+    service;
+    cause;
+    constructor(service, cause) {
+        super(`Service '${service}' blocked the request due to degradation policy`);
+        this.service = service;
+        this.name = 'ServiceBlockedError';
+        this.cause = cause;
+    }
+}
+exports.ServiceBlockedError = ServiceBlockedError;

package/dist/cjs/server/lancer/index.d.ts

@@ -0,0 +1,3 @@
+export { createLancer } from './client.js';
+export { ServiceBlockedError } from './errors.js';
+export type { AegisNamespace, AnalyzeOptions, AnalyzeResult, ApprovalCheckResult, ApprovalDecideResult, ApprovalResolveResult, ApprovalsNamespace, CheckResult, ClassifyResult, ConfigNamespace, ConfigResult, DegradationAction, DegradationContext, DegradationDefaults, Lancer, LancerConfig, LancerServiceName, LeakageResult, OnServiceUnavailable, PiiEntity, PrimusNamespace, PromptOverride, TelemetryEvent, TelemetryNamespace, Violation, WardenNamespace, } from './types.js';

package/dist/cjs/server/lancer/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceBlockedError = exports.createLancer = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "createLancer", { enumerable: true, get: function () { return client_js_1.createLancer; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "ServiceBlockedError", { enumerable: true, get: function () { return errors_js_1.ServiceBlockedError; } });

package/dist/cjs/server/lancer/telemetry-buffer.d.ts

@@ -0,0 +1,15 @@
+import type { TelemetryEvent } from './types.js';
+export declare class TelemetryBuffer {
+    private readonly endpoint;
+    private readonly headers;
+    private readonly maxRetries;
+    private buffer;
+    private timer;
+    constructor(endpoint: string, headers: Record<string, string>, maxRetries: number);
+    /** Add an event to the buffer. Auto-flushes at threshold. */
+    add(event: TelemetryEvent): void;
+    /** Flush buffered events to the Proctor API. */
+    flush(): Promise<void>;
+    /** Tear down the auto-flush interval. */
+    destroy(): void;
+}

package/dist/cjs/server/lancer/telemetry-buffer.js

@@ -0,0 +1,64 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Telemetry event buffer — batches events and flushes to the Proctor API
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryBuffer = void 0;
+const FLUSH_THRESHOLD = 50;
+const FLUSH_INTERVAL_MS = 5_000;
+class TelemetryBuffer {
+    endpoint;
+    headers;
+    maxRetries;
+    buffer = [];
+    timer = null;
+    constructor(endpoint, headers, maxRetries) {
+        this.endpoint = endpoint;
+        this.headers = headers;
+        this.maxRetries = maxRetries;
+        this.timer = setInterval(() => {
+            if (this.buffer.length > 0)
+                this.flush().catch(() => { });
+        }, FLUSH_INTERVAL_MS);
+    }
+    /** Add an event to the buffer. Auto-flushes at threshold. */
+    add(event) {
+        this.buffer.push(event);
+        if (this.buffer.length >= FLUSH_THRESHOLD) {
+            this.flush().catch(() => { });
+        }
+    }
+    /** Flush buffered events to the Proctor API. */
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const batch = this.buffer.splice(0);
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const res = await fetch(this.endpoint, {
+                    method: 'POST',
+                    headers: this.headers,
+                    body: JSON.stringify({ events: batch }),
+                });
+                if (res.ok)
+                    return;
+                lastError = new Error(`HTTP ${res.status}`);
+            }
+            catch (err) {
+                lastError = err;
+            }
+        }
+        // All retries exhausted — push events back to the buffer
+        this.buffer.unshift(...batch);
+        throw lastError;
+    }
+    /** Tear down the auto-flush interval. */
+    destroy() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+exports.TelemetryBuffer = TelemetryBuffer;