kiokuko 1.0.0

package/dist/embedding/vector.d.ts

@@ -0,0 +1,9 @@
+export declare const MIN_VECTOR_DIMENSIONS = 2;
+export declare const MAX_VECTOR_DIMENSIONS = 8192;
+export declare function normalizeVector(input: Float32Array | readonly number[], expectedDimensions?: number): Float32Array;
+export declare function encodeVector(input: Float32Array | readonly number[], expectedDimensions?: number): Uint8Array;
+export declare function decodeVector(blob: unknown, dimensions: number, expectedHash?: string): Float32Array;
+export declare function hashVectorBytes(bytes: Uint8Array): string;
+export declare function hashVector(input: Float32Array | readonly number[]): string;
+export declare function cosineDistance(left: Float32Array, right: Float32Array): number;
+//# sourceMappingURL=vector.d.ts.map

package/dist/embedding/vector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.d.ts","sourceRoot":"","sources":["../../src/embedding/vector.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAyB3C,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,YAAY,CAGlH;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,UAAU,CAQ7G;AASD,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,CAWnG;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEzD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,GAAG,MAAM,CAE1E;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAiB9E"}

package/dist/embedding/vector.js

@@ -0,0 +1,90 @@
+import { createHash } from 'node:crypto';
+import { KiokukoError } from '../errors.js';
+export const MIN_VECTOR_DIMENSIONS = 2;
+export const MAX_VECTOR_DIMENSIONS = 8_192;
+function invalid(message) {
+    throw new KiokukoError('VALIDATION_ERROR', message);
+}
+function dimensionsValue(dimensions) {
+    if (!Number.isSafeInteger(dimensions) || dimensions < MIN_VECTOR_DIMENSIONS || dimensions > MAX_VECTOR_DIMENSIONS) {
+        invalid('Vector dimensions are invalid');
+    }
+    return dimensions;
+}
+function validateFiniteVector(vector, expectedDimensions) {
+    const dimensions = dimensionsValue(expectedDimensions ?? vector.length);
+    if (vector.length !== dimensions)
+        invalid('Vector dimensions do not match');
+    let normSquared = 0;
+    for (const value of vector) {
+        if (!Number.isFinite(value))
+            invalid('Vector contains a non-finite value');
+        normSquared += value * value;
+    }
+    if (!Number.isFinite(normSquared) || normSquared === 0)
+        invalid('Vector norm must be non-zero');
+    return vector;
+}
+export function normalizeVector(input, expectedDimensions) {
+    const vector = input instanceof Float32Array ? new Float32Array(input) : new Float32Array(input);
+    return validateFiniteVector(vector, expectedDimensions);
+}
+export function encodeVector(input, expectedDimensions) {
+    const vector = normalizeVector(input, expectedDimensions);
+    const bytes = new Uint8Array(vector.byteLength);
+    const view = new DataView(bytes.buffer);
+    for (let index = 0; index < vector.length; index += 1) {
+        view.setFloat32(index * 4, vector[index], true);
+    }
+    return bytes;
+}
+function blobBytes(blob) {
+    if (blob instanceof Uint8Array)
+        return new Uint8Array(blob);
+    if (ArrayBuffer.isView(blob))
+        return new Uint8Array(blob.buffer.slice(blob.byteOffset, blob.byteOffset + blob.byteLength));
+    if (blob instanceof ArrayBuffer)
+        return new Uint8Array(blob.slice(0));
+    invalid('Vector BLOB is invalid');
+}
+export function decodeVector(blob, dimensions, expectedHash) {
+    const validDimensions = dimensionsValue(dimensions);
+    const bytes = blobBytes(blob);
+    if (bytes.byteLength !== validDimensions * 4)
+        invalid('Vector BLOB length does not match dimensions');
+    if (expectedHash !== undefined && hashVectorBytes(bytes) !== expectedHash) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Vector hash does not match its BLOB');
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const vector = new Float32Array(validDimensions);
+    for (let index = 0; index < validDimensions; index += 1)
+        vector[index] = view.getFloat32(index * 4, true);
+    return validateFiniteVector(vector, validDimensions);
+}
+export function hashVectorBytes(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+export function hashVector(input) {
+    return hashVectorBytes(encodeVector(input));
+}
+export function cosineDistance(left, right) {
+    if (left.length !== right.length)
+        invalid('Vectors must have matching dimensions');
+    const first = validateFiniteVector(left);
+    const second = validateFiniteVector(right, first.length);
+    let dot = 0;
+    let leftNorm = 0;
+    let rightNorm = 0;
+    for (let index = 0; index < first.length; index += 1) {
+        const leftValue = first[index];
+        const rightValue = second[index];
+        dot += leftValue * rightValue;
+        leftNorm += leftValue * leftValue;
+        rightNorm += rightValue * rightValue;
+    }
+    const similarity = dot / Math.sqrt(leftNorm * rightNorm);
+    if (!Number.isFinite(similarity))
+        invalid('Vector cosine distance is invalid');
+    return Math.min(2, Math.max(0, 1 - similarity));
+}
+//# sourceMappingURL=vector.js.map

package/dist/embedding/vector.js.map

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

package/dist/embedding/worker.d.ts

@@ -0,0 +1,23 @@
+import type { EmbeddingDrainResult, EmbeddingRuntime } from './types.js';
+export declare const DEFAULT_EMBEDDING_WORKER_INTERVAL_MS = 5000;
+export declare const DEFAULT_EMBEDDING_WORKER_MAX_JOBS = 64;
+export declare const DEFAULT_EMBEDDING_WORKER_DEADLINE_MS = 120000;
+export interface EmbeddingWorkerOptions {
+    readonly runtime: EmbeddingRuntime;
+    readonly intervalMs?: number;
+    readonly maxJobs?: number;
+    readonly deadlineMs?: number;
+    readonly setTimeout?: typeof setTimeout;
+    readonly clearTimeout?: typeof clearTimeout;
+    readonly onDrain?: (result: EmbeddingDrainResult) => void | PromiseLike<void>;
+    readonly onError?: (error: unknown) => void | PromiseLike<void>;
+}
+export interface EmbeddingWorker {
+    readonly running: boolean;
+    start(): void;
+    stop(): void;
+    close(): Promise<void>;
+}
+/** Run bounded embedding drains without overlapping provider calls or timers. */
+export declare function createEmbeddingWorker(options: EmbeddingWorkerOptions): EmbeddingWorker;
+//# sourceMappingURL=worker.d.ts.map

package/dist/embedding/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/embedding/worker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEzE,eAAO,MAAM,oCAAoC,OAAQ,CAAC;AAC1D,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,eAAO,MAAM,oCAAoC,SAAU,CAAC;AAE5D,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,UAAU,CAAC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAOD,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAqEtF"}

package/dist/embedding/worker.js

@@ -0,0 +1,84 @@
+export const DEFAULT_EMBEDDING_WORKER_INTERVAL_MS = 5_000;
+export const DEFAULT_EMBEDDING_WORKER_MAX_JOBS = 64;
+export const DEFAULT_EMBEDDING_WORKER_DEADLINE_MS = 120_000;
+function positiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new TypeError(`${label} must be a positive integer`);
+    return value;
+}
+/** Run bounded embedding drains without overlapping provider calls or timers. */
+export function createEmbeddingWorker(options) {
+    const intervalMs = positiveInteger(options.intervalMs ?? DEFAULT_EMBEDDING_WORKER_INTERVAL_MS, 'intervalMs');
+    const maxJobs = positiveInteger(options.maxJobs ?? DEFAULT_EMBEDDING_WORKER_MAX_JOBS, 'maxJobs');
+    const deadlineMs = positiveInteger(options.deadlineMs ?? DEFAULT_EMBEDDING_WORKER_DEADLINE_MS, 'deadlineMs');
+    const setTimer = options.setTimeout ?? setTimeout;
+    const clearTimer = options.clearTimeout ?? clearTimeout;
+    let started = false;
+    let closing = false;
+    let timer;
+    let active;
+    const schedule = (delay) => {
+        if (!started || closing || timer !== undefined)
+            return;
+        timer = setTimer(() => {
+            timer = undefined;
+            void run();
+        }, delay);
+    };
+    const run = async () => {
+        if (!started || closing || active !== undefined)
+            return;
+        const operation = (async () => {
+            try {
+                const result = await options.runtime.drain({ maxJobs, deadlineMs });
+                await options.onDrain?.(result);
+            }
+            catch (error) {
+                try {
+                    await options.onError?.(error);
+                }
+                catch {
+                    // A background observer must not create an unhandled rejection.
+                }
+            }
+        })();
+        active = operation;
+        try {
+            await operation;
+        }
+        finally {
+            if (active === operation)
+                active = undefined;
+            schedule(intervalMs);
+        }
+    };
+    const stop = () => {
+        if (closing)
+            return;
+        closing = true;
+        started = false;
+        if (timer !== undefined) {
+            clearTimer(timer);
+            timer = undefined;
+        }
+    };
+    const worker = {
+        get running() {
+            return started && !closing;
+        },
+        start() {
+            if (started || closing)
+                return;
+            started = true;
+            schedule(0);
+        },
+        stop,
+        async close() {
+            stop();
+            await options.runtime.close();
+            await active;
+        },
+    };
+    return Object.freeze(worker);
+}
+//# sourceMappingURL=worker.js.map

package/dist/embedding/worker.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+export type ErrorCode = 'USAGE_ERROR' | 'VALIDATION_ERROR' | 'NOT_FOUND' | 'CONFLICT' | 'DATABASE_ERROR' | 'BACKPRESSURE' | 'SERVICE_UNAVAILABLE' | 'SECURITY_REJECTION' | 'AUTHENTICATION_ERROR' | 'INTEGRITY_ERROR' | 'PARTIAL_FAILURE' | 'NOT_IMPLEMENTED';
+export declare class KiokukoError extends Error {
+    readonly code: ErrorCode;
+    readonly details: Record<string, unknown>;
+    readonly exitCode: number;
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown>);
+}
+export declare const STORED_MEMORY_INTEGRITY_MESSAGE: string;
+export declare function storedMemoryIntegrityError(): KiokukoError;
+export declare const DATABASE_BACKUP_RECOVERY_MESSAGE: string;
+export declare function databaseBackupIntegrityError(cause?: unknown): KiokukoError;
+export declare function exitCodeFor(error: unknown): number;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,aAAa,GACb,kBAAkB,GAClB,WAAW,GACX,UAAU,GACV,gBAAgB,GAChB,cAAc,GACd,qBAAqB,GACrB,oBAAoB,GACpB,sBAAsB,GACtB,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,CAAC;AAiBtB,qBAAa,YAAa,SAAQ,KAAK;IAInC,QAAQ,CAAC,IAAI,EAAE,SAAS;IAExB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAL3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAGf,IAAI,EAAE,SAAS,EACxB,OAAO,EAAE,MAAM,EACN,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAMjD;AAED,eAAO,MAAM,+BAA+B,QAMhC,CAAC;AAEb,wBAAgB,0BAA0B,IAAI,YAAY,CAEzD;AAED,eAAO,MAAM,gCAAgC,QAIjC,CAAC;AAEb,wBAAgB,4BAA4B,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,YAAY,CAI1E;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGlD"}

package/dist/errors.js

@@ -0,0 +1,53 @@
+const EXIT_CODES = {
+    USAGE_ERROR: 2,
+    VALIDATION_ERROR: 3,
+    NOT_FOUND: 4,
+    CONFLICT: 5,
+    DATABASE_ERROR: 6,
+    BACKPRESSURE: 6,
+    SERVICE_UNAVAILABLE: 6,
+    SECURITY_REJECTION: 7,
+    AUTHENTICATION_ERROR: 7,
+    INTEGRITY_ERROR: 8,
+    PARTIAL_FAILURE: 9,
+    NOT_IMPLEMENTED: 2,
+};
+export class KiokukoError extends Error {
+    code;
+    details;
+    exitCode;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'KiokukoError';
+        this.exitCode = EXIT_CODES[code];
+    }
+}
+export const STORED_MEMORY_INTEGRITY_MESSAGE = [
+    'Stored entry or revision is invalid.',
+    'Kiokuko does not automatically repair or convert stored memory.',
+    'Keep the database and its WAL/SHM files unchanged. Do not delete database rows manually.',
+    'To start with a new database, choose a new absolute directory and run:',
+    'KIOKUKO_DATA_DIR=/absolute/new-directory kiokuko init',
+].join('\n');
+export function storedMemoryIntegrityError() {
+    return new KiokukoError('INTEGRITY_ERROR', STORED_MEMORY_INTEGRITY_MESSAGE);
+}
+export const DATABASE_BACKUP_RECOVERY_MESSAGE = [
+    'Database backup could not be created; the source database was not changed.',
+    'Check that Node.js is version 24.16.0 or newer and that the backup destination is new and writable.',
+    'Do not delete or replace the source database. If backup still fails, preserve the original file for repair or recovery.',
+].join('\n');
+export function databaseBackupIntegrityError(cause) {
+    const error = new KiokukoError('INTEGRITY_ERROR', DATABASE_BACKUP_RECOVERY_MESSAGE);
+    if (cause !== undefined)
+        Object.defineProperty(error, 'cause', { value: cause });
+    return error;
+}
+export function exitCodeFor(error) {
+    if (error instanceof KiokukoError)
+        return error.exitCode;
+    return EXIT_CODES.INTEGRITY_ERROR;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,GAA8B;IAC5C,WAAW,EAAE,CAAC;IACd,gBAAgB,EAAE,CAAC;IACnB,SAAS,EAAE,CAAC;IACZ,QAAQ,EAAE,CAAC;IACX,cAAc,EAAE,CAAC;IACjB,YAAY,EAAE,CAAC;IACf,mBAAmB,EAAE,CAAC;IACtB,kBAAkB,EAAE,CAAC;IACrB,oBAAoB,EAAE,CAAC;IACvB,eAAe,EAAE,CAAC;IAClB,eAAe,EAAE,CAAC;IAClB,eAAe,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,OAAO,YAAa,SAAQ,KAAK;IAI1B;IAEA;IALF,QAAQ,CAAS;IAE1B,YACW,IAAe,EACxB,OAAe,EACN,UAAmC,EAAE;QAE9C,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,SAAI,GAAJ,IAAI,CAAW;QAEf,YAAO,GAAP,OAAO,CAA8B;QAG9C,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;CACF;AAED,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,sCAAsC;IACtC,iEAAiE;IACjE,0FAA0F;IAC1F,wEAAwE;IACxE,uDAAuD;CACxD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,UAAU,0BAA0B;IACxC,OAAO,IAAI,YAAY,CAAC,iBAAiB,EAAE,+BAA+B,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,4EAA4E;IAC5E,qGAAqG;IACrG,yHAAyH;CAC1H,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,UAAU,4BAA4B,CAAC,KAAe;IAC1D,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,iBAAiB,EAAE,gCAAgC,CAAC,CAAC;IACpF,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACjF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,YAAY;QAAE,OAAO,KAAK,CAAC,QAAQ,CAAC;IACzD,OAAO,UAAU,CAAC,eAAe,CAAC;AACpC,CAAC"}

package/dist/gateway/agent-service.d.ts

@@ -0,0 +1,72 @@
+import type { SqliteDatabase } from '../db/adapter.js';
+import { type AppendAck, type RunStatus } from '../ledger/types.js';
+import type { AkinatorQuestion, AkinatorResult, TaskProfile } from '../akinator/types.js';
+import type { LedgerEventsPage, LedgerRunView, LedgerRunsPage } from '../ledger/query.js';
+declare const TERMINAL_STATUS_VALUES: readonly ["completed", "failed", "cancelled", "interrupted"];
+type TerminalStatus = (typeof TERMINAL_STATUS_VALUES)[number];
+type GatewayIntakeResponse = {
+    runId: string;
+    runStatus: RunStatus;
+    intakeSessionId: string;
+    intakeStatus: AkinatorResult['status'];
+    intake: {
+        status: AkinatorResult['status'];
+        sessionId: string;
+        question: AkinatorQuestion | null;
+    };
+    question: AkinatorQuestion | null;
+    currentQuestion: AkinatorQuestion | null;
+    missingFields: Array<keyof TaskProfile>;
+    recommendedTags: string[];
+    taskProfile: TaskProfile;
+    profileHash: string | null;
+    context: null;
+    untrusted: true;
+};
+type GatewayAppendResponse = AppendAck & {
+    runStatus: RunStatus;
+    untrusted: true;
+};
+type GatewayCloseResponse = AppendAck & {
+    status: TerminalStatus;
+    runStatus: TerminalStatus;
+    untrusted: true;
+};
+export interface AgentGatewayServiceOptions {
+    readonly now?: () => string;
+    readonly home?: string;
+    readonly runIdFactory?: () => string;
+    readonly sessionIdFactory?: () => string;
+    readonly eventIdFactory?: () => string;
+}
+interface AgentGatewayAnswerOptions {
+    readonly assertBeforeAnswer?: () => void;
+}
+export declare class AgentGatewayService {
+    private readonly database;
+    private readonly options;
+    constructor(database: SqliteDatabase, options?: AgentGatewayServiceOptions);
+    openRun(input: unknown): GatewayIntakeResponse;
+    answerIntake(input: unknown, options?: AgentGatewayAnswerOptions): GatewayIntakeResponse;
+    appendEvents(input: unknown): GatewayAppendResponse;
+    closeRun(input: unknown): GatewayCloseResponse;
+    listRuns(input: unknown): LedgerRunsPage & {
+        untrusted: true;
+    };
+    readRun(input: unknown): LedgerRunView;
+    readIntake(input: unknown): GatewayIntakeResponse;
+    listEvents(input: unknown): LedgerEventsPage & {
+        untrusted: true;
+    };
+    private intakeResponse;
+    private lifecycleEvent;
+    private ledgerStore;
+    private requireRun;
+    private scopedOperation;
+    private currentTime;
+    private nextRunId;
+    private nextSessionId;
+    private nextEventId;
+}
+export type { GatewayAppendResponse, GatewayCloseResponse, GatewayIntakeResponse, };
+//# sourceMappingURL=agent-service.d.ts.map

package/dist/gateway/agent-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-service.d.ts","sourceRoot":"","sources":["../../src/gateway/agent-service.ts"],"names":[],"mappings":"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"}