@lensagent/core 0.1.0

package/dist/contracts/model.d.ts

@@ -0,0 +1,77 @@
+import type { Json } from './domain.js';
+export interface ModelMessage {
+    readonly role: 'system' | 'user' | 'assistant' | 'tool';
+    readonly content: string;
+    readonly toolCallId?: string;
+    readonly toolName?: string;
+    readonly toolCalls?: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly arguments: Json;
+    }[];
+}
+export interface ModelTool {
+    readonly id: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, Json>>;
+    readonly outputSchema?: Readonly<Record<string, Json>>;
+}
+export interface ModelToolBridgeInput {
+    readonly capabilityId: string;
+    readonly arguments: Json;
+    readonly providerCallId: string;
+    readonly ordinal: number;
+    readonly parentProviderCallId?: string;
+}
+export interface ProgrammaticToolCalling {
+    readonly capabilityIds: readonly string[];
+    readonly maxToolCalls: number;
+    execute(input: ModelToolBridgeInput, signal: AbortSignal | undefined): Promise<Json>;
+}
+export interface ModelRequest {
+    readonly model: string;
+    readonly messages: readonly ModelMessage[];
+    readonly tools: readonly ModelTool[];
+    readonly reasoningEffort: string | null;
+    readonly maxOutputTokens?: number;
+    readonly programmaticToolCalling?: ProgrammaticToolCalling;
+    readonly signal: AbortSignal;
+}
+export type ModelStreamEvent = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'thinking';
+    readonly text: string;
+} | {
+    readonly type: 'toolStart';
+    readonly ordinal: number;
+    readonly id: string;
+    readonly name: string;
+} | {
+    readonly type: 'tool';
+    readonly ordinal: number;
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: Json;
+    readonly parentProviderCallId?: string;
+    readonly providerExecuted?: boolean;
+    readonly programmaticCaller?: boolean;
+} | {
+    readonly type: 'toolResult';
+    readonly ordinal: number;
+    readonly id: string;
+    readonly name: string;
+    readonly output: Json;
+    readonly providerExecuted?: boolean;
+} | {
+    readonly type: 'usage';
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+} | {
+    readonly type: 'end';
+    readonly reason: string;
+};
+export interface ModelGateway {
+    stream(request: ModelRequest): AsyncIterable<ModelStreamEvent>;
+}

package/dist/contracts/model.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/ports.d.ts

@@ -0,0 +1,14 @@
+export declare const PORT_CONTRACT_VERSIONS: Readonly<{
+    access: "1.0.0";
+    config: "1.0.0";
+    store: "1.0.0";
+    event: "1.0.0";
+    capability: "1.0.0";
+    execution: "1.0.0";
+    result: "1.0.0";
+    model: "1.0.0";
+    tokenizer: "1.0.0";
+    observability: "1.0.0";
+    mcp: "1.0.0";
+    lsp: "1.0.0";
+}>;

package/dist/contracts/ports.js

@@ -0,0 +1,14 @@
+export const PORT_CONTRACT_VERSIONS = Object.freeze({
+    access: '1.0.0',
+    config: '1.0.0',
+    store: '1.0.0',
+    event: '1.0.0',
+    capability: '1.0.0',
+    execution: '1.0.0',
+    result: '1.0.0',
+    model: '1.0.0',
+    tokenizer: '1.0.0',
+    observability: '1.0.0',
+    mcp: '1.0.0',
+    lsp: '1.0.0'
+});

package/dist/core/access.d.ts

@@ -0,0 +1,24 @@
+import { type TrustedIngress } from './domain.js';
+type Headers = Readonly<Record<string, string | string[] | undefined>>;
+interface Identity {
+    readonly clientId: string;
+    readonly kind: 'native' | 'browser';
+    readonly mac: string | null;
+    readonly hardwareId: string | null;
+    readonly browserFingerprint: string | null;
+}
+export declare class PairStore {
+    #private;
+    readonly onRevoked: (clientId: string) => void;
+    readonly path: string;
+    constructor(root: string, path: string, onRevoked: (clientId: string) => void);
+    get metadataRevision(): number;
+    get pairDigest(): string;
+    load(): Promise<void>;
+    start(onError?: (error: Error) => void): void;
+    close(): void;
+    identify(headers: Headers): Identity;
+    authorize(headers: Headers, transport: 'http' | 'https', correlationId: string): Promise<TrustedIngress>;
+    reload(): Promise<void>;
+}
+export {};

package/dist/core/access.js

@@ -0,0 +1,205 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { watch } from 'node:fs';
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, resolve } from 'node:path';
+import { digest, now } from './codec.js';
+import { fail } from './domain.js';
+export class PairStore {
+    onRevoked;
+    path;
+    #records = new Map();
+    #digest = digest([]);
+    #metadataRevision = 0;
+    #watcher;
+    #writeTail = Promise.resolve();
+    constructor(root, path, onRevoked) {
+        this.onRevoked = onRevoked;
+        this.path = resolve(root, path);
+    }
+    get metadataRevision() {
+        return this.#metadataRevision;
+    }
+    get pairDigest() {
+        return this.#digest;
+    }
+    async load() {
+        await mkdir(dirname(this.path), { recursive: true });
+        try {
+            await stat(this.path);
+        }
+        catch {
+            await writeFile(this.path, '{\n  "clients": []\n}\n', { encoding: 'utf8', flag: 'wx' }).catch(() => undefined);
+        }
+        await this.reload();
+    }
+    start(onError) {
+        this.#watcher = watch(dirname(this.path), (_event, filename) => {
+            if (filename !== null && filename !== basename(this.path))
+                return;
+            this.#writeTail = this.#writeTail.then(() => this.reload()).catch((error) => {
+                this.#metadataRevision += 1;
+                onError?.(error instanceof Error ? error : new Error(String(error)));
+            });
+        });
+    }
+    close() {
+        this.#watcher?.close();
+        this.#watcher = undefined;
+    }
+    identify(headers) {
+        const kind = header(headers, 'x-lens-client-kind');
+        if (kind === 'native') {
+            const mac = normalizeMac(header(headers, 'x-lens-client-mac'));
+            const hardwareId = identityText(header(headers, 'x-lens-hardware-id'));
+            return identity('native', mac, hardwareId, null);
+        }
+        if (kind === 'browser') {
+            return identity('browser', null, null, identityText(header(headers, 'x-lens-browser-fingerprint')));
+        }
+        fail('CLIENT_ID_INVALID', 400, 'X-Lens-Client-Kind must be native or browser.');
+    }
+    async authorize(headers, transport, correlationId) {
+        const client = this.identify(headers);
+        const record = this.#records.get(client.clientId);
+        if (record?.isVerified !== true) {
+            if (record === undefined)
+                await this.#appendUnknown(client);
+            fail('CLIENT_UNVERIFIED', 403, 'The client has not been verified.', { client_id: client.clientId });
+        }
+        return { source: 'user', clientId: client.clientId, transport, correlationId };
+    }
+    async reload() {
+        const next = await readPairFile(this.path);
+        const previous = this.#records;
+        this.#records = new Map(next.map((entry) => [entry.client_id, entry]));
+        this.#digest = digest(next.filter((entry) => entry.isVerified).map((entry) => entry.client_id).sort());
+        this.#metadataRevision += 1;
+        for (const [clientId, record] of previous) {
+            if (record.isVerified && this.#records.get(clientId)?.isVerified !== true)
+                this.onRevoked(clientId);
+        }
+    }
+    #appendUnknown(identityValue) {
+        const write = this.#writeTail.then(async () => {
+            const records = await readPairFile(this.path);
+            if (records.some((entry) => entry.client_id === identityValue.clientId)) {
+                await this.reload();
+                return;
+            }
+            if (records.length >= 4096)
+                fail('PAIR_FILE_CAPACITY', 503, 'The pair file reached its client limit.');
+            const timestamp = now();
+            records.push({
+                client_id: identityValue.clientId,
+                client_kind: identityValue.kind,
+                mac: identityValue.mac,
+                hardware_id: identityValue.hardwareId,
+                browser_fingerprint: identityValue.browserFingerprint,
+                isVerified: false,
+                label: null,
+                first_seen_at: timestamp,
+                last_seen_at: timestamp
+            });
+            const source = `${JSON.stringify({ clients: records }, null, 2)}\n`;
+            if (Buffer.byteLength(source) > 1_048_576)
+                fail('PAIR_FILE_CAPACITY', 503, 'The pair file reached its size limit.');
+            const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+            await writeFile(temporary, source, 'utf8');
+            await rename(temporary, this.path);
+            await this.reload();
+        });
+        this.#writeTail = write.catch(() => undefined);
+        return write;
+    }
+}
+async function readPairFile(path) {
+    let document;
+    try {
+        const source = await readFile(path, 'utf8');
+        if (Buffer.byteLength(source) > 1_048_576)
+            fail('PAIR_FILE_CAPACITY', 503, 'The pair file reached its size limit.');
+        document = JSON.parse(source);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'LensError')
+            throw error;
+        fail('PAIR_FILE_INVALID', 503, 'The pair file could not be loaded.');
+    }
+    if (typeof document !== 'object' || document === null || Array.isArray(document))
+        fail('PAIR_FILE_INVALID', 503, 'The pair file is invalid.');
+    const clients = document.clients;
+    if (!Array.isArray(clients) || clients.length > 4096)
+        fail('PAIR_FILE_INVALID', 503, 'The pair file is invalid.');
+    return clients.map(pairRecord);
+}
+function pairRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        fail('PAIR_FILE_INVALID', 503, 'A pair record is invalid.');
+    const row = value;
+    const kind = row.client_kind;
+    if (kind !== 'native' && kind !== 'browser')
+        fail('PAIR_FILE_INVALID', 503, 'A pair client kind is invalid.');
+    const label = row.label === null ? null : string(row.label, 'label', 256);
+    return {
+        client_id: string(row.client_id, 'client_id'),
+        client_kind: kind,
+        mac: nullableString(row.mac),
+        hardware_id: nullableString(row.hardware_id),
+        browser_fingerprint: nullableString(row.browser_fingerprint),
+        isVerified: row.isVerified === true,
+        label,
+        first_seen_at: string(row.first_seen_at, 'first_seen_at'),
+        last_seen_at: string(row.last_seen_at, 'last_seen_at')
+    };
+}
+function identity(kind, mac, hardwareId, fingerprint) {
+    const payload = kind === 'native'
+        ? `lens-client-id-v1\nkind=native\nmac=${mac ?? ''}\nhardware_id_b64=${base64(hardwareId ?? '')}`
+        : `lens-client-id-v1\nkind=browser\nbrowser_fingerprint_b64=${base64(fingerprint ?? '')}`;
+    return {
+        clientId: `sha256:${createHash('sha256').update(payload).digest('hex')}`,
+        kind,
+        mac,
+        hardwareId,
+        browserFingerprint: fingerprint
+    };
+}
+function header(headers, name) {
+    const raw = headers[name];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof value !== 'string' || value.length === 0)
+        fail('CLIENT_ID_INVALID', 400, `${name} is required.`);
+    return value;
+}
+function normalizeMac(value) {
+    const compact = value.trim().toLowerCase().replaceAll('-', '').replaceAll(':', '');
+    if (!/^[0-9a-f]{12}$/.test(compact))
+        fail('CLIENT_ID_INVALID', 400, 'The client MAC address is invalid.');
+    return compact.match(/.{2}/g)?.join(':') ?? '';
+}
+function identityText(value) {
+    const trimmed = value.replace(/^[ \t]+|[ \t]+$/g, '');
+    if (trimmed.length === 0 || Buffer.byteLength(trimmed) > 1024 || hasControl(trimmed)) {
+        fail('CLIENT_ID_INVALID', 400, 'The client identity is invalid.');
+    }
+    return trimmed;
+}
+function hasControl(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 31 || code === 127)
+            return true;
+    }
+    return false;
+}
+function base64(value) {
+    return Buffer.from(value).toString('base64url');
+}
+function nullableString(value) {
+    return value === null ? null : string(value, 'pair field');
+}
+function string(value, field, maximum = 4096) {
+    if (typeof value !== 'string' || value.length === 0 || Buffer.byteLength(value) > maximum)
+        fail('PAIR_FILE_INVALID', 503, `${field} is invalid.`);
+    return value;
+}

package/dist/core/codec.d.ts

@@ -0,0 +1,33 @@
+import { type Json } from './domain.js';
+export declare function id(kind: string): string;
+export declare function now(): string;
+export declare function digest(value: Json): string;
+export declare function json(value: Json): string;
+export declare function parseJson(value: string | null): Json | null;
+export declare function jsonValue(value: unknown): Json;
+/**
+ * Tool-call arguments, always as an object.
+ *
+ * A Provider is entitled to hand back the arguments as a raw JSON string rather than a parsed object,
+ * and it does exactly that when the model calls a tool that was not in the request's schema manifest --
+ * there is nothing to parse against, so the text passes through. Stored verbatim, that string then
+ * replays as `toolUse.input`, which Bedrock rejects: "The format of the value at
+ * messages.N.content.0.toolUse.input is invalid. Provide a json object for the field and try again."
+ *
+ * The damage is that it is permanent. The bad block sits in the Context, so every later request in that
+ * Session is rejected before the model is reached, and Retry cannot help because the poison is in the
+ * history rather than in the attempt. Normalising here is what keeps one malformed tool call from
+ * ending a conversation.
+ *
+ * An empty or unparseable value becomes `{}` rather than a failure: the Call itself will be rejected on
+ * its own arguments by the Capability's schema, which reports something the reader can act on, whereas
+ * a corrupt Context reports nothing and cannot be recovered.
+ */
+export declare function toolArguments(value: unknown): Json;
+export declare function record(value: unknown, field?: string): Readonly<Record<string, unknown>>;
+export declare function text(value: unknown, field: string, maximum?: number): string;
+export declare function optionalText(value: unknown, field: string, maximum?: number): string | undefined;
+export declare function integer(value: unknown, field: string, minimum?: number): number;
+export declare function expectedRevision(value: unknown): number;
+export declare function boolean(value: unknown, field: string): boolean;
+export declare function nullable(value: unknown): string | null;

package/dist/core/codec.js

@@ -0,0 +1,105 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { canonicalize } from 'json-canonicalize';
+import { fail } from './domain.js';
+export function id(kind) {
+    return `${kind}_${randomUUID()}`;
+}
+export function now() {
+    return new Date().toISOString();
+}
+export function digest(value) {
+    return createHash('sha256').update(canonicalize(value)).digest('hex');
+}
+export function json(value) {
+    return JSON.stringify(value);
+}
+export function parseJson(value) {
+    return value === null ? null : JSON.parse(value);
+}
+export function jsonValue(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return value.map(jsonValue);
+    if (typeof value === 'object') {
+        const result = {};
+        for (const [key, entry] of Object.entries(value))
+            result[key] = jsonValue(entry);
+        return result;
+    }
+    fail('INVALID_INPUT', 400, 'The value must be JSON.');
+}
+/**
+ * Tool-call arguments, always as an object.
+ *
+ * A Provider is entitled to hand back the arguments as a raw JSON string rather than a parsed object,
+ * and it does exactly that when the model calls a tool that was not in the request's schema manifest --
+ * there is nothing to parse against, so the text passes through. Stored verbatim, that string then
+ * replays as `toolUse.input`, which Bedrock rejects: "The format of the value at
+ * messages.N.content.0.toolUse.input is invalid. Provide a json object for the field and try again."
+ *
+ * The damage is that it is permanent. The bad block sits in the Context, so every later request in that
+ * Session is rejected before the model is reached, and Retry cannot help because the poison is in the
+ * history rather than in the attempt. Normalising here is what keeps one malformed tool call from
+ * ending a conversation.
+ *
+ * An empty or unparseable value becomes `{}` rather than a failure: the Call itself will be rejected on
+ * its own arguments by the Capability's schema, which reports something the reader can act on, whereas
+ * a corrupt Context reports nothing and cannot be recovered.
+ */
+export function toolArguments(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed.length === 0)
+            return {};
+        try {
+            const parsed = JSON.parse(trimmed);
+            return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? jsonValue(parsed) : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    if (value === undefined || value === null)
+        return {};
+    const normalized = jsonValue(value);
+    return typeof normalized === 'object' && normalized !== null && !Array.isArray(normalized) ? normalized : {};
+}
+export function record(value, field = 'body') {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        fail('INVALID_INPUT', 400, `${field} must be an object.`);
+    }
+    return value;
+}
+export function text(value, field, maximum = 1_048_576) {
+    if (typeof value !== 'string' || value.length === 0 || Buffer.byteLength(value) > maximum) {
+        fail('INVALID_INPUT', 400, `${field} must be a non-empty string.`);
+    }
+    return value;
+}
+export function optionalText(value, field, maximum = 1_048_576) {
+    return value === undefined ? undefined : text(value, field, maximum);
+}
+export function integer(value, field, minimum = 0) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum) {
+        fail('INVALID_INPUT', 400, `${field} must be an integer greater than or equal to ${minimum}.`);
+    }
+    return value;
+}
+export function expectedRevision(value) {
+    return integer(value, 'expected_revision');
+}
+export function boolean(value, field) {
+    if (typeof value !== 'boolean')
+        fail('INVALID_INPUT', 400, `${field} must be a boolean.`);
+    return value;
+}
+export function nullable(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string')
+        return value;
+    fail('DATABASE_CORRUPT', 503, 'A stored value has an invalid type.');
+}

package/dist/core/domain.d.ts

@@ -0,0 +1,13 @@
+export * from '../contracts/index.js';
+import type { Json } from '../contracts/index.js';
+export declare class LensError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details: Readonly<Record<string, Json>>;
+    constructor(code: string, status: number, message: string, details?: Readonly<Record<string, Json>>);
+}
+export declare class UserInputRequiredError extends Error {
+    readonly prompt: Json;
+    constructor(prompt: Json);
+}
+export declare function fail(code: string, status: number, message: string, details?: Readonly<Record<string, Json>>): never;

package/dist/core/domain.js

@@ -0,0 +1,24 @@
+export * from '../contracts/index.js';
+export class LensError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, status, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = 'LensError';
+    }
+}
+export class UserInputRequiredError extends Error {
+    prompt;
+    constructor(prompt) {
+        super('The Call requires user input.');
+        this.prompt = prompt;
+        this.name = 'UserInputRequiredError';
+    }
+}
+export function fail(code, status, message, details) {
+    throw new LensError(code, status, message, details);
+}

package/dist/core/host.d.ts

@@ -0,0 +1,19 @@
+export interface LaunchOptions {
+    readonly installRoot?: string;
+    readonly configPath?: string;
+    readonly runtime?: 'node' | 'bun';
+}
+export interface LensRuntime {
+    readonly url: string;
+    /**
+     * Resolves when a graceful stop has been requested through the Server's shutdown control path.
+     *
+     * Deciding what to do about it belongs to the caller. The entry module closes the runtime and
+     * exits the process; an embedding host is free to do something else. Exiting here would make
+     * `launch()` unusable as a library, because a control request from outside would take down a
+     * process that Core does not own.
+     */
+    readonly shutdownRequested: Promise<void>;
+    close(): Promise<void>;
+}
+export declare function launchCore(options?: LaunchOptions): Promise<LensRuntime>;