@jungjaehoon/mama-core 1.5.0 → 1.6.0

package/dist/model-runs/tool-trace-store.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendToolTrace = appendToolTrace;
+exports.listToolTracesForRun = listToolTracesForRun;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const db_manager_js_1 = require("../db-manager.js");
+function traceId() {
+    return `tr_${node_crypto_1.default.randomUUID().replace(/-/g, '')}`;
+}
+function requiredString(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`tool_traces.${field} must be a non-empty string: ${formatInvalidValue(value)}`);
+    }
+    return value;
+}
+function formatInvalidValue(value) {
+    return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+function nullableString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function normalizeTimestamp(value) {
+    if (value === undefined || value === null) {
+        return Date.now();
+    }
+    return requiredInteger(value, 'created_at');
+}
+function normalizeDuration(value) {
+    if (value === undefined || value === null) {
+        return 0;
+    }
+    return requiredNonNegativeInteger(value, 'duration_ms');
+}
+function requiredInteger(value, field) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`tool_traces.${field} must be a finite number: ${formatInvalidValue(value)}`);
+    }
+    return Math.floor(value);
+}
+function requiredNonNegativeInteger(value, field) {
+    const normalized = requiredInteger(value, field);
+    if (normalized < 0) {
+        throw new Error(`tool_traces.${field} must be non-negative: ${formatInvalidValue(value)}`);
+    }
+    return normalized;
+}
+function mapToolTraceRow(row) {
+    return {
+        trace_id: requiredString(row.trace_id, 'trace_id'),
+        model_run_id: requiredString(row.model_run_id, 'model_run_id'),
+        gateway_call_id: nullableString(row.gateway_call_id),
+        tool_name: requiredString(row.tool_name, 'tool_name'),
+        input_summary: nullableString(row.input_summary),
+        output_summary: nullableString(row.output_summary),
+        execution_status: nullableString(row.execution_status),
+        duration_ms: requiredNonNegativeInteger(row.duration_ms, 'duration_ms'),
+        envelope_hash: nullableString(row.envelope_hash),
+        created_at: requiredInteger(row.created_at, 'created_at'),
+    };
+}
+async function initializedAdapter() {
+    await (0, db_manager_js_1.initDB)();
+    return (0, db_manager_js_1.getAdapter)();
+}
+function selectToolTrace(adapter, id) {
+    const row = adapter
+        .prepare(`
+        SELECT
+          trace_id, model_run_id, gateway_call_id, tool_name, input_summary,
+          output_summary, execution_status, duration_ms, envelope_hash, created_at
+        FROM tool_traces
+        WHERE trace_id = ?
+      `)
+        .get(id);
+    if (!row) {
+        throw new Error(`Tool trace not found: ${id}`);
+    }
+    return mapToolTraceRow(row);
+}
+async function appendToolTrace(input) {
+    const adapter = await initializedAdapter();
+    const id = nullableString(input.trace_id) ?? traceId();
+    const modelRunId = requiredString(input.model_run_id, 'model_run_id');
+    const toolName = requiredString(input.tool_name, 'tool_name');
+    adapter
+        .prepare(`
+        INSERT INTO tool_traces (
+          trace_id, model_run_id, gateway_call_id, tool_name, input_summary,
+          output_summary, execution_status, duration_ms, envelope_hash, created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+        .run(id, modelRunId, nullableString(input.gateway_call_id), toolName, nullableString(input.input_summary), nullableString(input.output_summary), nullableString(input.execution_status), normalizeDuration(input.duration_ms), nullableString(input.envelope_hash), normalizeTimestamp(input.created_at));
+    return selectToolTrace(adapter, id);
+}
+async function listToolTracesForRun(modelRunId) {
+    const adapter = await initializedAdapter();
+    const id = requiredString(modelRunId, 'model_run_id');
+    const rows = adapter
+        .prepare(`
+        SELECT
+          trace_id, model_run_id, gateway_call_id, tool_name, input_summary,
+          output_summary, execution_status, duration_ms, envelope_hash, created_at
+        FROM tool_traces
+        WHERE model_run_id = ?
+        ORDER BY created_at DESC, rowid DESC
+      `)
+        .all(id);
+    return rows.map(mapToolTraceRow);
+}
+//# sourceMappingURL=tool-trace-store.js.map

package/dist/model-runs/types.d.ts

@@ -0,0 +1,69 @@
+export declare const MODEL_RUN_STATUSES: readonly ["running", "committed", "failed", "legacy"];
+export type ModelRunStatus = (typeof MODEL_RUN_STATUSES)[number];
+export interface BeginModelRunInput {
+    model_run_id?: string;
+    model_id?: string | null;
+    model_provider?: string | null;
+    prompt_version?: string | null;
+    tool_manifest_version?: string | null;
+    output_schema_version?: string | null;
+    agent_id?: string | null;
+    instance_id?: string | null;
+    envelope_hash?: string | null;
+    parent_model_run_id?: string | null;
+    input_snapshot_ref?: string | null;
+    input_refs?: Record<string, unknown> | null;
+    input_refs_json?: string | null;
+    status?: ModelRunStatus;
+    error_summary?: string | null;
+    token_count?: number | null;
+    cost_estimate?: number | null;
+    created_at?: number;
+}
+export interface ModelRunRecord {
+    model_run_id: string;
+    model_id: string | null;
+    model_provider: string | null;
+    prompt_version: string | null;
+    tool_manifest_version: string | null;
+    output_schema_version: string | null;
+    agent_id: string | null;
+    instance_id: string | null;
+    envelope_hash: string | null;
+    parent_model_run_id: string | null;
+    input_snapshot_ref: string | null;
+    input_refs_json: string | null;
+    input_refs: Record<string, unknown> | null;
+    completion_summary: string | null;
+    status: ModelRunStatus;
+    error_summary: string | null;
+    token_count: number;
+    cost_estimate: number | null;
+    created_at: number;
+    completed_at: number | null;
+}
+export interface AppendToolTraceInput {
+    trace_id?: string;
+    model_run_id: string;
+    gateway_call_id?: string | null;
+    tool_name: string;
+    input_summary?: string | null;
+    output_summary?: string | null;
+    execution_status?: string | null;
+    duration_ms?: number | null;
+    envelope_hash?: string | null;
+    created_at?: number;
+}
+export interface ToolTraceRecord {
+    trace_id: string;
+    model_run_id: string;
+    gateway_call_id: string | null;
+    tool_name: string;
+    input_summary: string | null;
+    output_summary: string | null;
+    execution_status: string | null;
+    duration_ms: number;
+    envelope_hash: string | null;
+    created_at: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/model-runs/types.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_RUN_STATUSES = void 0;
+exports.MODEL_RUN_STATUSES = ['running', 'committed', 'failed', 'legacy'];
+//# sourceMappingURL=types.js.map

package/dist/runtime/trusted-provenance.d.ts

@@ -0,0 +1,3 @@
+export { createTrustedProvenanceCapability } from '../memory/provenance.js';
+export type { TrustedMemoryWriteOptions, TrustedProvenanceCapability, } from '../memory/provenance.js';
+//# sourceMappingURL=trusted-provenance.d.ts.map

package/dist/runtime/trusted-provenance.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTrustedProvenanceCapability = void 0;
+var provenance_js_1 = require("../memory/provenance.js");
+Object.defineProperty(exports, "createTrustedProvenanceCapability", { enumerable: true, get: function () { return provenance_js_1.createTrustedProvenanceCapability; } });
+//# sourceMappingURL=trusted-provenance.js.map

package/dist/search/search-quality.d.ts

@@ -0,0 +1,36 @@
+export type SearchStrictness = 'recall' | 'balanced' | 'strict';
+export interface SearchQualityOptions {
+    threshold?: number;
+    strict?: boolean;
+    strictness?: SearchStrictness;
+    disableRecency?: boolean;
+    includeRelated?: boolean;
+    topicPrefix?: string;
+    minLexicalSupport?: boolean;
+    diagnostics?: boolean;
+}
+export interface NormalizedSearchQualityOptions {
+    threshold: number;
+    strictness: SearchStrictness;
+    disableRecency: boolean;
+    includeRelated: boolean;
+    topicPrefix?: string;
+    minLexicalSupport: boolean;
+    diagnostics: boolean;
+}
+export interface SearchHitDiagnostics {
+    retrieval_source: string;
+    vector_similarity: number | null;
+    lexical_support: boolean;
+    entity_support: boolean;
+    scope_support: boolean;
+    graph_source: 'primary' | 'expanded' | null;
+    is_vector_only: boolean;
+    /** Relevance confirmations only: never include scope or graph position here. */
+    confirmation_signals: string[];
+    /** Non-relevance metadata useful for diagnostics and audit output. */
+    metadata_signals: string[];
+    candidate_threshold_used: number;
+}
+export declare function normalizeSearchQualityOptions(options?: SearchQualityOptions): NormalizedSearchQualityOptions;
+//# sourceMappingURL=search-quality.d.ts.map

package/dist/search/search-quality.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSearchQualityOptions = normalizeSearchQualityOptions;
+function normalizeSearchQualityOptions(options = {}) {
+    // Validate strictness at runtime — untyped callers can otherwise pass invalid
+    // strings that silently fall through and skew filtering.
+    const strictnessCandidate = options.strict === true ? 'strict' : options.strictness;
+    const strictness = strictnessCandidate === 'strict' ||
+        strictnessCandidate === 'balanced' ||
+        strictnessCandidate === 'recall'
+        ? strictnessCandidate
+        : 'recall';
+    const defaultThreshold = strictness === 'strict' ? 0.6 : strictness === 'balanced' ? 0.45 : 0.3;
+    const rawThreshold = typeof options.threshold === 'number' ? options.threshold : defaultThreshold;
+    // Clamp threshold to [0, 1]; fall back to default for non-finite values (NaN, ±Inf).
+    const threshold = Number.isFinite(rawThreshold)
+        ? Math.min(1, Math.max(0, rawThreshold))
+        : defaultThreshold;
+    return {
+        threshold,
+        strictness,
+        disableRecency: options.disableRecency === true,
+        includeRelated: options.includeRelated ?? strictness !== 'strict',
+        topicPrefix: options.topicPrefix,
+        minLexicalSupport: options.minLexicalSupport ?? strictness !== 'recall',
+        diagnostics: options.diagnostics === true,
+    };
+}
+//# sourceMappingURL=search-quality.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungjaehoon/mama-core",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "MAMA Core - Shared modules for Memory-Augmented MCP Assistant",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -45,7 +45,13 @@
     "./cases/wiki-page-index": "./dist/cases/wiki-page-index.js",
     "./connectors": "./dist/connectors/event-index.js",
     "./connectors/event-index": "./dist/connectors/event-index.js",
-    "./connectors/types": "./dist/connectors/types.js"
+    "./connectors/raw-query": "./dist/connectors/raw-query.js",
+    "./connectors/types": "./dist/connectors/types.js",
+    "./agent-situation": "./dist/agent-situation/index.js",
+    "./agent-graph": "./dist/agent-graph/index.js",
+    "./edges/types": "./dist/edges/types.js",
+    "./edges/store": "./dist/edges/store.js",
+    "./edges/ref-validation": "./dist/edges/ref-validation.js"
   },
   "scripts": {
     "build": "tsc",
@@ -90,6 +96,7 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.0.0",
     "@types/ws": "^8.18.1",
+    "typescript": "^5.9.3",
     "vitest": "^1.0.0"
   },
   "files": [