@amodalai/core 0.1.0

package/dist/src/runtime/session-setup.js

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { randomUUID } from 'node:crypto';
+import { ScrubTracker } from '../security/scrub-tracker.js';
+import { FieldScrubber } from '../security/field-scrubber.js';
+import { OutputGuard } from '../security/output-guard.js';
+import { ActionGate } from '../security/action-gate.js';
+import { TokenAllocator, getModelContextWindow } from './token-allocator.js';
+import { ContextCompiler } from './context-compiler.js';
+import { OutputPipeline } from './output-pipeline.js';
+import { RuntimeTelemetry } from './telemetry-hooks.js';
+import { buildAccessConfigs, buildConnectionsMap } from './connection-bridge.js';
+import { resolveScopeLabels, generateFieldGuidance, generateAlternativeLookupGuidance, } from './user-context.js';
+/**
+ * Sets up a complete session runtime from a loaded repo.
+ *
+ * This is synchronous — the repo must already be loaded and no HTTP calls
+ * are made. All security components, context compilation, and telemetry
+ * are initialized and ready for use.
+ */
+export function setupSession(options) {
+    const { repo } = options;
+    const isDelegated = options.isDelegated ?? false;
+    const userRoles = options.userRoles ?? [];
+    const sessionId = randomUUID();
+    // Build connection maps
+    const accessConfigs = buildAccessConfigs(repo.connections);
+    const connectionsMap = buildConnectionsMap(repo.connections);
+    // Resolve scope and field guidance
+    const { scopeLabels, scopeRules } = resolveScopeLabels(repo.connections, userRoles);
+    const fieldGuidance = generateFieldGuidance(repo.connections, userRoles);
+    const alternativeLookupGuidance = generateAlternativeLookupGuidance(repo.connections);
+    // Security components
+    const scrubTracker = new ScrubTracker();
+    const fieldScrubber = new FieldScrubber({
+        accessConfigs,
+        userRoles,
+        tracker: scrubTracker,
+    });
+    const outputGuard = new OutputGuard({
+        tracker: scrubTracker,
+        accessConfigs,
+        userRoles,
+        scopeContext: { scopeRules, scopeLabels },
+    });
+    const actionGate = new ActionGate({
+        accessConfigs,
+        isDelegated,
+    });
+    // Context compilation
+    const modelWindow = getModelContextWindow(repo.config.models.main.model);
+    const allocator = new TokenAllocator(modelWindow);
+    const contextCompiler = new ContextCompiler({ repo, allocator });
+    const sessionConfig = {
+        repo,
+        userRoles,
+        scopeLabels,
+        fieldGuidance,
+        alternativeLookupGuidance,
+        planMode: false,
+        isDelegated,
+        sessionId,
+    };
+    const compiledContext = contextCompiler.compile(sessionConfig);
+    const exploreContext = contextCompiler.compileExplore(sessionConfig);
+    // Output pipeline
+    const outputPipeline = new OutputPipeline({ outputGuard });
+    // Telemetry
+    const telemetry = new RuntimeTelemetry(sessionId, options.telemetrySink);
+    return {
+        repo,
+        scrubTracker,
+        fieldScrubber,
+        outputGuard,
+        actionGate,
+        contextCompiler,
+        compiledContext,
+        exploreContext,
+        outputPipeline,
+        telemetry,
+        connectionsMap,
+        userRoles,
+        sessionId,
+        isDelegated,
+    };
+}
+//# sourceMappingURL=session-setup.js.map

package/dist/src/runtime/session-setup.js.map

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

package/dist/src/runtime/telemetry-client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { TelemetrySink } from './telemetry-hooks.js';
+/**
+ * Buffers RuntimeTelemetryEvents and batch-POSTs them to the platform API.
+ * Errors are swallowed — telemetry must never crash the runtime.
+ */
+export declare class PlatformTelemetrySink {
+    private readonly buffer;
+    private readonly platformUrl;
+    private readonly apiKey;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private flushTimer;
+    private destroyed;
+    constructor(platformUrl: string, apiKey: string, options?: {
+        batchSize?: number;
+        flushIntervalMs?: number;
+    });
+    /**
+     * Returns a TelemetrySink callback for use with RuntimeTelemetry.
+     */
+    sink(): TelemetrySink;
+    /**
+     * Flush all buffered events to the platform.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop the flush timer and flush remaining events.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Number of events currently buffered (for testing).
+     */
+    get bufferedCount(): number;
+}

package/dist/src/runtime/telemetry-client.js

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+const DEFAULT_BATCH_SIZE = 50;
+const DEFAULT_FLUSH_INTERVAL_MS = 5_000;
+/**
+ * Buffers RuntimeTelemetryEvents and batch-POSTs them to the platform API.
+ * Errors are swallowed — telemetry must never crash the runtime.
+ */
+export class PlatformTelemetrySink {
+    buffer = [];
+    platformUrl;
+    apiKey;
+    batchSize;
+    flushIntervalMs;
+    flushTimer = null;
+    destroyed = false;
+    constructor(platformUrl, apiKey, options) {
+        this.platformUrl = platformUrl.replace(/\/$/, '');
+        this.apiKey = apiKey;
+        this.batchSize = options?.batchSize ?? DEFAULT_BATCH_SIZE;
+        this.flushIntervalMs = options?.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+        this.flushTimer = setInterval(() => {
+            void this.flush();
+        }, this.flushIntervalMs);
+        if (this.flushTimer && typeof this.flushTimer === 'object' && 'unref' in this.flushTimer) {
+            this.flushTimer.unref();
+        }
+    }
+    /**
+     * Returns a TelemetrySink callback for use with RuntimeTelemetry.
+     */
+    sink() {
+        return (event) => {
+            if (this.destroyed)
+                return;
+            this.buffer.push(event);
+            if (this.buffer.length >= this.batchSize) {
+                void this.flush();
+            }
+        };
+    }
+    /**
+     * Flush all buffered events to the platform.
+     */
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const events = this.buffer.splice(0, this.buffer.length);
+        try {
+            const response = await fetch(`${this.platformUrl}/api/telemetry/ingest`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({ events }),
+            });
+            if (!response.ok) {
+                // Swallow — telemetry failures must not affect the runtime
+            }
+        }
+        catch {
+            // Swallow network errors
+        }
+    }
+    /**
+     * Stop the flush timer and flush remaining events.
+     */
+    async destroy() {
+        this.destroyed = true;
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush();
+    }
+    /**
+     * Number of events currently buffered (for testing).
+     */
+    get bufferedCount() {
+        return this.buffer.length;
+    }
+}
+//# sourceMappingURL=telemetry-client.js.map

package/dist/src/runtime/telemetry-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-client.js","sourceRoot":"","sources":["../../../src/runtime/telemetry-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAC9B,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAExC;;;GAGG;AACH,MAAM,OAAO,qBAAqB;IACf,MAAM,GAA4B,EAAE,CAAC;IACrC,WAAW,CAAS;IACpB,MAAM,CAAS;IACf,SAAS,CAAS;IAClB,eAAe,CAAS;IACjC,UAAU,GAA0C,IAAI,CAAC;IACzD,SAAS,GAAG,KAAK,CAAC;IAE1B,YACE,WAAmB,EACnB,MAAc,EACd,OAAwD;QAExD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,kBAAkB,CAAC;QAC1D,IAAI,CAAC,eAAe,GAAG,OAAO,EAAE,eAAe,IAAI,yBAAyB,CAAC;QAE7E,IAAI,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;YACjC,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;QAEzB,IAAI,IAAI,CAAC,UAAU,IAAI,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,IAAI,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACzF,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QAC1B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI;QACF,OAAO,CAAC,KAA4B,EAAE,EAAE;YACtC,IAAI,IAAI,CAAC,SAAS;gBAAE,OAAO;YAC3B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACxB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACzC,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YACpB,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAErC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAEzD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,WAAW,uBAAuB,EAAE;gBACvE,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,eAAe,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;iBACzC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAC,MAAM,EAAC,CAAC;aAC/B,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,2DAA2D;YAC7D,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,yBAAyB;QAC3B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;CACF"}

package/dist/src/runtime/telemetry-hooks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { ScrubResult, GuardResult, GateResult } from '../security/security-types.js';
+/**
+ * All telemetry event types the runtime can emit.
+ */
+export type TelemetryEventType = 'field_scrub' | 'output_guard' | 'action_gate' | 'explore_dispatch' | 'plan_mode' | 'tool_call' | 'session_summary';
+/**
+ * A telemetry event emitted by the runtime.
+ */
+export interface RuntimeTelemetryEvent {
+    type: TelemetryEventType;
+    sessionId: string;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+/**
+ * A function that receives telemetry events.
+ */
+export type TelemetrySink = (event: RuntimeTelemetryEvent) => void;
+/**
+ * Structured telemetry for runtime security and orchestration events.
+ * Each log method constructs a RuntimeTelemetryEvent and sends it
+ * to the configured sink. If no sink is provided, all methods are no-ops.
+ */
+export declare class RuntimeTelemetry {
+    private readonly sessionId;
+    private readonly sink?;
+    constructor(sessionId: string, sink?: TelemetrySink);
+    logScrub(result: ScrubResult, connectionName: string, endpointPath: string): void;
+    logGuard(result: GuardResult): void;
+    logGate(result: GateResult): void;
+    logExplore(query: string, resultTokens: number): void;
+    logPlanMode(action: 'enter' | 'approve' | 'exit'): void;
+    logToolCall(toolName: string, durationMs: number, tokenCount: number, modelProvider?: string, modelName?: string): void;
+    logSessionSummary(summary: {
+        totalTokens: number;
+        totalDurationMs: number;
+        toolCallCount: number;
+        scrubCount: number;
+        guardCount: number;
+        estimatedCostMicros: number;
+    }): void;
+}

package/dist/src/runtime/telemetry-hooks.js

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Structured telemetry for runtime security and orchestration events.
+ * Each log method constructs a RuntimeTelemetryEvent and sends it
+ * to the configured sink. If no sink is provided, all methods are no-ops.
+ */
+export class RuntimeTelemetry {
+    sessionId;
+    sink;
+    constructor(sessionId, sink) {
+        this.sessionId = sessionId;
+        this.sink = sink;
+    }
+    logScrub(result, connectionName, endpointPath) {
+        if (!this.sink)
+            return;
+        this.sink({
+            type: 'field_scrub',
+            sessionId: this.sessionId,
+            timestamp: Date.now(),
+            data: {
+                connectionName,
+                endpointPath,
+                strippedCount: result['strippedCount'],
+                redactableCount: result['redactableCount'],
+            },
+        });
+    }
+    logGuard(result) {
+        if (!this.sink)
+            return;
+        const findingTypes = [...new Set(result['findings'].map((f) => f.type))];
+        this.sink({
+            type: 'output_guard',
+            sessionId: this.sessionId,
+            timestamp: Date.now(),
+            data: {
+                modified: result['modified'],
+                blocked: result['blocked'],
+                findingCount: result['findings'].length,
+                findingTypes,
+            },
+        });
+    }
+    logGate(result) {
+        if (!this.sink)
+            return;
+        this.sink({
+            type: 'action_gate',
+            sessionId: this.sessionId,
+            timestamp: Date.now(),
+            data: {
+                decision: result['decision'],
+                escalated: result['escalated'],
+                endpointPath: result['endpointPath'],
+            },
+        });
+    }
+    logExplore(query, resultTokens) {
+        if (!this.sink)
+            return;
+        this.sink({
+            type: 'explore_dispatch',
+            sessionId: this.sessionId,
+            timestamp: Date.now(),
+            data: {
+                query,
+                resultTokens,
+            },
+        });
+    }
+    logPlanMode(action) {
+        if (!this.sink)
+            return;
+        this.sink({
+            type: 'plan_mode',
+            sessionId: this.sessionId,
+            timestamp: Date.now(),
+            data: {
+                action,
+            },
+        });
+    }
+    logToolCall(toolName, durationMs, tokenCount, modelProvider, modelName) {
+        if (!this.sink)
+            return;
+        this.sink({
+            type: 'tool_call',
+            sessionId: this.sessionId,
+            timestamp: Date.now(),
+            data: {
+                toolName,
+                durationMs,
+                tokenCount,
+                modelProvider,
+                modelName,
+            },
+        });
+    }
+    logSessionSummary(summary) {
+        if (!this.sink)
+            return;
+        this.sink({
+            type: 'session_summary',
+            sessionId: this.sessionId,
+            timestamp: Date.now(),
+            data: summary,
+        });
+    }
+}
+//# sourceMappingURL=telemetry-hooks.js.map

package/dist/src/runtime/telemetry-hooks.js.map

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

package/dist/src/runtime/token-allocator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { ContextSection } from './runtime-types.js';
+/**
+ * Returns the context window size for a given model string.
+ */
+export declare function getModelContextWindow(model: string): number;
+/**
+ * Allocates token budget across context sections using priority-based trimming.
+ *
+ * Sections with lower priority numbers are trimmed first when the total
+ * exceeds the available budget.
+ */
+export declare class TokenAllocator {
+    readonly budget: number;
+    constructor(modelContextWindow: number, reserveForResponse?: number);
+    /**
+     * Estimates the number of tokens in a text string.
+     * Uses the chars / 4 heuristic.
+     */
+    estimateTokens(text: string): number;
+    /**
+     * Allocates budget to sections, trimming lowest-priority sections first
+     * when the total exceeds available budget.
+     */
+    allocate(sections: ContextSection[]): {
+        included: ContextSection[];
+        trimmed: ContextSection[];
+        totalTokens: number;
+    };
+}

package/dist/src/runtime/token-allocator.js

@@ -0,0 +1,86 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+const DEFAULT_RESPONSE_RESERVE = 4096;
+/**
+ * Returns the context window size for a given model string.
+ */
+export function getModelContextWindow(model) {
+    const lower = model.toLowerCase();
+    if (lower.includes('gemini')) {
+        return 1_000_000;
+    }
+    if (lower.includes('claude')) {
+        return 200_000;
+    }
+    if (lower.includes('gpt-4o')) {
+        return 128_000;
+    }
+    return 128_000;
+}
+/**
+ * Allocates token budget across context sections using priority-based trimming.
+ *
+ * Sections with lower priority numbers are trimmed first when the total
+ * exceeds the available budget.
+ */
+export class TokenAllocator {
+    budget;
+    constructor(modelContextWindow, reserveForResponse = DEFAULT_RESPONSE_RESERVE) {
+        this.budget = Math.max(0, modelContextWindow - reserveForResponse);
+    }
+    /**
+     * Estimates the number of tokens in a text string.
+     * Uses the chars / 4 heuristic.
+     */
+    estimateTokens(text) {
+        return Math.ceil(text.length / 4);
+    }
+    /**
+     * Allocates budget to sections, trimming lowest-priority sections first
+     * when the total exceeds available budget.
+     */
+    allocate(sections) {
+        // Calculate tokens for each section
+        const withTokens = sections.map((s) => ({
+            ...s,
+            tokens: this.estimateTokens(s.content),
+        }));
+        const totalNeeded = withTokens.reduce((sum, s) => sum + s.tokens, 0);
+        // Everything fits
+        if (totalNeeded <= this.budget) {
+            return {
+                included: withTokens.map((s) => ({ ...s, trimmed: false })),
+                trimmed: [],
+                totalTokens: totalNeeded,
+            };
+        }
+        // Sort by priority ascending to trim lowest first
+        const sortedByPriority = [...withTokens].sort((a, b) => a.priority - b.priority);
+        let excess = totalNeeded - this.budget;
+        const trimmedNames = new Set();
+        for (const section of sortedByPriority) {
+            if (excess <= 0) {
+                break;
+            }
+            trimmedNames.add(section.name);
+            excess -= section.tokens;
+        }
+        const included = [];
+        const trimmed = [];
+        let totalTokens = 0;
+        for (const section of withTokens) {
+            if (trimmedNames.has(section.name)) {
+                trimmed.push({ ...section, content: '', tokens: 0, trimmed: true });
+            }
+            else {
+                included.push({ ...section, trimmed: false });
+                totalTokens += section.tokens;
+            }
+        }
+        return { included, trimmed, totalTokens };
+    }
+}
+//# sourceMappingURL=token-allocator.js.map

package/dist/src/runtime/token-allocator.js.map

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

package/dist/src/runtime/user-context.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { LoadedConnection } from '../repo/connection-types.js';
+import type { ScopingRule } from '../repo/connection-schemas.js';
+/**
+ * The result of processing a user context response.
+ */
+export interface UserContextResult {
+    raw: Record<string, unknown>;
+    roles: string[];
+    scopeLabels: Record<string, string>;
+    scopeRules: Record<string, ScopingRule>;
+    fieldGuidance: string;
+    alternativeLookupGuidance: string;
+}
+/**
+ * Extract roles from a user context response object.
+ * Looks for: role (string), roles (string[]), permissions.role, user.role.
+ */
+export declare function extractRoles(data: Record<string, unknown>): string[];
+/**
+ * Resolve scope labels for a user's roles from all connections' rowScoping.
+ *
+ * For each entity in each connection's rowScoping, finds the first matching
+ * role's scoping rule label. If no role matches, the entity is skipped.
+ */
+export declare function resolveScopeLabels(connections: Map<string, LoadedConnection>, userRoles: string[]): {
+    scopeLabels: Record<string, string>;
+    scopeRules: Record<string, ScopingRule>;
+};
+/**
+ * Generate field guidance text from all connections' fieldRestrictions.
+ *
+ * Lists never_retrieve fields as "Do not request: entity.field (reason)"
+ * Lists role_gated fields with allowed roles
+ * Lists retrieve_but_redact fields as "Will be redacted: entity.field"
+ */
+export declare function generateFieldGuidance(connections: Map<string, LoadedConnection>, userRoles: string[]): string;
+/**
+ * Generate alternative lookup guidance from all connections' alternativeLookups.
+ */
+export declare function generateAlternativeLookupGuidance(connections: Map<string, LoadedConnection>): string;
+/**
+ * Create a default empty UserContextResult.
+ */
+export declare function defaultUserContext(): UserContextResult;