noteconnection 1.7.0 → 1.9.0

package/dist/src/learning/agentResponseBudget.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_RESPONSE_UNBOUNDED_RUNTIME_GOVERNOR = exports.AGENT_RESPONSE_BUDGET_TIERS = void 0;
+exports.resolveAgentResponseBudget = resolveAgentResponseBudget;
+exports.applyRuntimeGovernor = applyRuntimeGovernor;
+exports.resolveHostedAgentResponseBudget = resolveHostedAgentResponseBudget;
+const STANDARD_RUNTIME_GOVERNOR = Object.freeze({
+    timeoutMs: 60000,
+    maxSerializedBytes: 8 * 1024 * 1024,
+    maxFragmentsProcessed: 512,
+    maxReportChars: 48000,
+});
+const EXTENDED_RUNTIME_GOVERNOR = Object.freeze({
+    timeoutMs: 90000,
+    maxSerializedBytes: 16 * 1024 * 1024,
+    maxFragmentsProcessed: 1024,
+    maxReportChars: 80000,
+});
+const MAX_RUNTIME_GOVERNOR = Object.freeze({
+    timeoutMs: 120000,
+    maxSerializedBytes: 32 * 1024 * 1024,
+    maxFragmentsProcessed: 2048,
+    maxReportChars: 160000,
+});
+const UNBOUNDED_RUNTIME_GOVERNOR = Object.freeze({
+    timeoutMs: 180000,
+    maxSerializedBytes: 64 * 1024 * 1024,
+    maxFragmentsProcessed: 4096,
+    maxReportChars: 320000,
+});
+function createProductBudgetDefinition(maxFragments, maxCharsPerFragment, maxTotalChars, reportMaxChars, runtimeGovernor) {
+    return Object.freeze({
+        rag: Object.freeze({
+            maxFragments,
+            maxCharsPerFragment,
+            maxTotalChars,
+            productCapDisabled: false,
+            runtimeMaxFragments: runtimeGovernor.maxFragmentsProcessed,
+            runtimeMaxCharsPerFragment: maxCharsPerFragment,
+            runtimeMaxTotalChars: reportMaxChars,
+        }),
+        reportMaxChars,
+        runtimeGovernor,
+    });
+}
+exports.AGENT_RESPONSE_BUDGET_TIERS = Object.freeze({
+    standard: createProductBudgetDefinition(120, 8000, 64000, 48000, STANDARD_RUNTIME_GOVERNOR),
+    extended: createProductBudgetDefinition(160, 12000, 128000, 80000, EXTENDED_RUNTIME_GOVERNOR),
+    max: createProductBudgetDefinition(256, 16000, 256000, 160000, MAX_RUNTIME_GOVERNOR),
+});
+exports.AGENT_RESPONSE_UNBOUNDED_RUNTIME_GOVERNOR = UNBOUNDED_RUNTIME_GOVERNOR;
+function normalizedMemoryClass(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    return normalized === 'low' || normalized === 'standard' || normalized === 'high'
+        ? normalized
+        : undefined;
+}
+function normalizedWorkload(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    return normalized === 'normal' || normalized === 'large' || normalized === 'max'
+        ? normalized
+        : undefined;
+}
+function normalizedCapability(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    const record = value;
+    const capability = {};
+    const memoryClass = normalizedMemoryClass(record.memoryClass ?? record.memory_class);
+    const workload = normalizedWorkload(record.workload ?? record.workload_class);
+    if (memoryClass) {
+        capability.memoryClass = memoryClass;
+    }
+    if (workload) {
+        capability.workload = workload;
+    }
+    return capability;
+}
+function resolveAdaptiveTier(capability) {
+    if (capability.memoryClass === 'low') {
+        return 'standard';
+    }
+    if (capability.memoryClass === 'high' && capability.workload === 'max') {
+        return 'max';
+    }
+    if (capability.workload === 'max' || (capability.memoryClass === 'high' && capability.workload === 'large')) {
+        return 'extended';
+    }
+    return 'standard';
+}
+function cloneRuntimeGovernor(governor) {
+    return {
+        timeoutMs: governor.timeoutMs,
+        maxSerializedBytes: governor.maxSerializedBytes,
+        maxFragmentsProcessed: governor.maxFragmentsProcessed,
+        maxReportChars: governor.maxReportChars,
+    };
+}
+function cloneRagBudget(rag, productCapDisabled = false) {
+    const cloned = {
+        maxFragments: rag.maxFragments,
+        maxCharsPerFragment: rag.maxCharsPerFragment,
+        maxTotalChars: rag.maxTotalChars,
+    };
+    if (productCapDisabled) {
+        cloned.productCapDisabled = true;
+        cloned.runtimeMaxFragments = rag.runtimeMaxFragments;
+        cloned.runtimeMaxCharsPerFragment = rag.runtimeMaxCharsPerFragment;
+        cloned.runtimeMaxTotalChars = rag.runtimeMaxTotalChars;
+    }
+    return cloned;
+}
+function resolveAgentResponseBudget(input = {}) {
+    const responseMode = input.responseMode === 'full' ? 'full' : 'slim';
+    const mobile = input.mobile === true;
+    const requestedMode = input.responseBudgetMode === 'unbounded'
+        ? 'unbounded'
+        : 'adaptive';
+    if (responseMode !== 'full' || mobile) {
+        const standard = exports.AGENT_RESPONSE_BUDGET_TIERS.standard;
+        return {
+            mode: 'adaptive',
+            tier: 'standard',
+            productCapDisabled: false,
+            rag: cloneRagBudget(standard.rag),
+            reportMaxChars: standard.reportMaxChars,
+            runtimeGovernor: cloneRuntimeGovernor(standard.runtimeGovernor),
+        };
+    }
+    if (requestedMode === 'unbounded') {
+        return {
+            mode: 'unbounded',
+            tier: 'unbounded',
+            productCapDisabled: true,
+            rag: cloneRagBudget({
+                maxFragments: UNBOUNDED_RUNTIME_GOVERNOR.maxFragmentsProcessed,
+                maxCharsPerFragment: exports.AGENT_RESPONSE_BUDGET_TIERS.max.rag.maxCharsPerFragment,
+                maxTotalChars: exports.AGENT_RESPONSE_UNBOUNDED_RUNTIME_GOVERNOR.maxReportChars,
+                runtimeMaxFragments: UNBOUNDED_RUNTIME_GOVERNOR.maxFragmentsProcessed,
+                runtimeMaxCharsPerFragment: exports.AGENT_RESPONSE_BUDGET_TIERS.max.rag.maxCharsPerFragment,
+                runtimeMaxTotalChars: UNBOUNDED_RUNTIME_GOVERNOR.maxReportChars,
+            }, true),
+            runtimeGovernor: cloneRuntimeGovernor(UNBOUNDED_RUNTIME_GOVERNOR),
+        };
+    }
+    const tier = resolveAdaptiveTier(normalizedCapability(input.capability));
+    const definition = exports.AGENT_RESPONSE_BUDGET_TIERS[tier];
+    return {
+        mode: 'adaptive',
+        tier,
+        productCapDisabled: false,
+        rag: cloneRagBudget(definition.rag),
+        reportMaxChars: definition.reportMaxChars,
+        runtimeGovernor: cloneRuntimeGovernor(definition.runtimeGovernor),
+    };
+}
+function applyRuntimeGovernor(input) {
+    const governor = input.budget.runtimeGovernor;
+    if (Number(input.nowMs) - Number(input.startedAtMs) > governor.timeoutMs) {
+        return { allowed: false, truncated: true, reason: 'runtime_timeout' };
+    }
+    if (Number(input.processedFragments) > governor.maxFragmentsProcessed) {
+        return { allowed: false, truncated: true, reason: 'runtime_fragment_limit' };
+    }
+    if (Number(input.serializedBytes) > governor.maxSerializedBytes) {
+        return { allowed: false, truncated: true, reason: 'runtime_serialized_bytes_limit' };
+    }
+    if (Number(input.reportChars) > governor.maxReportChars) {
+        return { allowed: false, truncated: true, reason: 'runtime_report_chars_limit' };
+    }
+    return { allowed: true, truncated: false };
+}
+function resolveHostedAgentResponseBudget(input, hostCapability) {
+    const requested = resolveAgentResponseBudget(input);
+    const ceiling = resolveAgentResponseBudget({ ...input, capability: hostCapability });
+    const rank = { standard: 0, extended: 1, max: 2, unbounded: 3 };
+    return rank[requested.tier] <= rank[ceiling.tier] ? requested : ceiling;
+}

package/dist/src/learning/agentResponseBudget.test.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const agentResponseBudget_1 = require("./agentResponseBudget");
+describe('agent response budget resolver', () => {
+    test.each([
+        [{}, 'standard'],
+        [{ memoryClass: 'standard', workload: 'normal' }, 'standard'],
+        [{ memoryClass: 'high', workload: 'large' }, 'extended'],
+        [{ memoryClass: 'standard', workload: 'max' }, 'extended'],
+        [{ memoryClass: 'high', workload: 'max' }, 'max'],
+        [{ memoryClass: 'low', workload: 'max' }, 'standard'],
+    ])('adaptive capability %j resolves to %s', (capability, expectedTier) => {
+        const budget = (0, agentResponseBudget_1.resolveAgentResponseBudget)({
+            responseMode: 'full',
+            responseBudgetMode: 'adaptive',
+            capability,
+        });
+        expect(budget.tier).toBe(expectedTier);
+        expect(budget.mode).toBe('adaptive');
+        expect(budget.productCapDisabled).toBe(false);
+        expect(budget.rag?.maxFragments).toBe(agentResponseBudget_1.AGENT_RESPONSE_BUDGET_TIERS[expectedTier].rag.maxFragments);
+    });
+    test('explicit unbounded disables product caps but keeps a finite runtime governor', () => {
+        const budget = (0, agentResponseBudget_1.resolveAgentResponseBudget)({
+            responseMode: 'full',
+            responseBudgetMode: 'unbounded',
+            capability: { memoryClass: 'low', workload: 'normal' },
+        });
+        expect(budget.mode).toBe('unbounded');
+        expect(budget.tier).toBe('unbounded');
+        expect(budget.productCapDisabled).toBe(true);
+        expect(budget.reportMaxChars).toBeUndefined();
+        expect(budget.runtimeGovernor.maxReportChars).toBeGreaterThan(agentResponseBudget_1.AGENT_RESPONSE_BUDGET_TIERS.max.reportMaxChars);
+        expect(Number.isFinite(budget.runtimeGovernor.maxSerializedBytes)).toBe(true);
+        expect(budget.rag?.productCapDisabled).toBe(true);
+    });
+    test('slim and mobile requests cannot select desktop full budgets', () => {
+        const slim = (0, agentResponseBudget_1.resolveAgentResponseBudget)({
+            responseMode: 'slim',
+            responseBudgetMode: 'unbounded',
+            capability: { memoryClass: 'high', workload: 'max' },
+        });
+        const mobile = (0, agentResponseBudget_1.resolveAgentResponseBudget)({
+            responseMode: 'full',
+            responseBudgetMode: 'unbounded',
+            capability: { memoryClass: 'high', workload: 'max' },
+            mobile: true,
+        });
+        expect(slim.tier).toBe('standard');
+        expect(slim.productCapDisabled).toBe(false);
+        expect(mobile.tier).toBe('standard');
+        expect(mobile.productCapDisabled).toBe(false);
+    });
+    test('numeric capability hints are bounded and cannot promote a tier', () => {
+        const budget = (0, agentResponseBudget_1.resolveAgentResponseBudget)({
+            responseMode: 'full',
+            responseBudgetMode: 'adaptive',
+            capability: {
+                memoryClass: 'standard',
+                workload: 'normal',
+                maxReportCharsHint: Number.MAX_SAFE_INTEGER,
+                maxSerializedBytesHint: Number.MAX_SAFE_INTEGER,
+            },
+        });
+        expect(budget.tier).toBe('standard');
+        expect(budget.reportMaxChars).toBeLessThanOrEqual(agentResponseBudget_1.AGENT_RESPONSE_BUDGET_TIERS.max.reportMaxChars);
+        expect(budget.runtimeGovernor.maxSerializedBytes).toBeLessThanOrEqual(agentResponseBudget_1.AGENT_RESPONSE_BUDGET_TIERS.max.runtimeGovernor.maxSerializedBytes);
+    });
+    test('runtime governor reports deterministic stop reasons', () => {
+        const budget = (0, agentResponseBudget_1.resolveAgentResponseBudget)({ responseMode: 'full', responseBudgetMode: 'unbounded' });
+        const startedAtMs = 1000;
+        expect((0, agentResponseBudget_1.applyRuntimeGovernor)({
+            budget,
+            startedAtMs,
+            nowMs: startedAtMs + 10,
+            processedFragments: 1,
+            serializedBytes: 100,
+            reportChars: 100,
+        })).toEqual({ allowed: true, truncated: false });
+        expect((0, agentResponseBudget_1.applyRuntimeGovernor)({
+            budget,
+            startedAtMs,
+            nowMs: startedAtMs + budget.runtimeGovernor.timeoutMs + 1,
+            processedFragments: 1,
+            serializedBytes: 100,
+            reportChars: 100,
+        })).toEqual({ allowed: false, truncated: true, reason: 'runtime_timeout' });
+        expect((0, agentResponseBudget_1.applyRuntimeGovernor)({
+            budget,
+            startedAtMs,
+            nowMs: startedAtMs + 10,
+            processedFragments: budget.runtimeGovernor.maxFragmentsProcessed + 1,
+            serializedBytes: 100,
+            reportChars: 100,
+        })).toEqual({ allowed: false, truncated: true, reason: 'runtime_fragment_limit' });
+    });
+});

package/dist/src/learning/agentWorkspaceCapabilityContracts.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_WORKSPACE_EXECUTION_KINDS = exports.AGENT_WORKSPACE_RESULT_PRESENTATIONS = exports.AGENT_WORKSPACE_OPERATION_IDS = void 0;
+/** Wire tokens shared by capability producers and independently checked UI registries. */
+exports.AGENT_WORKSPACE_OPERATION_IDS = Object.freeze([
+    'build_learning_path',
+    'search_conversation_memory',
+    'fetch_conversation_turn_cache_diagnostics',
+    'fetch_conversation_turn_cache_alert_trend',
+    'fetch_conversation_turn_cache_alert_trend_index',
+    'fetch_conversation_turn_cache_alert_trend_export',
+    'compare_query_backends',
+    'fetch_query_backend_diagnostics',
+    'fetch_query_backend_comparison_history',
+    'fetch_query_backend_comparison_trend',
+    'fetch_tutor_adapter_telemetry',
+    'fetch_tutor_trace_diagnostics',
+    'fetch_learning_quality_trend',
+    'fetch_learning_quality_history',
+    'evaluate_learning_quality_baseline',
+    'fetch_session_plan_quality_trend',
+    'fetch_session_plan_quality_history',
+    'verify_runtime_capability_runbook',
+    'fetch_runtime_capability_runbook_history',
+    'fetch_runtime_capability_runbook_checks',
+    'fetch_runtime_capability_runbook_action_queue',
+    'fetch_session_history',
+    'fetch_workflow_artifacts',
+    'execute_workflow_artifact_review_follow_up',
+    'execute_study_session_action',
+    'build_study_session',
+    'execute_tutor_action',
+]);
+exports.AGENT_WORKSPACE_RESULT_PRESENTATIONS = Object.freeze([
+    'learning_path_pane',
+    'assistant_message',
+    'workflow_artifact_review_follow_up',
+    'conversation_turn_cache_diagnostics_card',
+    'conversation_turn_cache_alert_trend_card',
+    'query_backend_comparison_card',
+    'query_backend_diagnostics_card',
+    'query_backend_comparison_history_card',
+    'query_backend_comparison_trend_card',
+    'tutor_adapter_telemetry_card',
+    'tutor_trace_diagnostics_card',
+    'learning_quality_trend_card',
+    'learning_quality_history_card',
+    'learning_quality_baseline_evaluation_card',
+    'session_plan_quality_trend_card',
+    'session_plan_quality_history_card',
+    'runtime_capability_runbook_verify_card',
+    'runtime_capability_runbook_history_card',
+    'runtime_capability_runbook_checks_card',
+    'runtime_capability_runbook_action_queue_card',
+    'session_history_card',
+    'flashcard_batch_card',
+    'knowledge_run_card',
+    'knowledge_run_history_card',
+    'study_session_card',
+    'tutor_action_card',
+]);
+exports.AGENT_WORKSPACE_EXECUTION_KINDS = Object.freeze([
+    'knowledge_operation',
+    'local_focus_mode',
+]);