@lensagent/core 0.1.0 → 0.1.2

package/dist/runtime/artifacts.d.ts

@@ -1,15 +1,27 @@
-import { type ArtifactOutput } from '../core/domain.js';
+import { type ArtifactOutput, type Json } from '../core/domain.js';
 import type { Document, Store } from '../store/store.js';
 export declare class ArtifactStore {
+    #private;
     readonly store: Store;
     readonly mode: 'filesystem' | 'content_addressed';
     readonly root: string;
     constructor(root: string, directory: string, store: Store, mode: 'filesystem' | 'content_addressed');
     save(projectId: string, artifacts: readonly ArtifactOutput[]): Promise<readonly string[]>;
     read(artifact: Document): Promise<Buffer>;
+    readRange(artifact: Document, offset: number, limit: number, signal?: AbortSignal): Promise<Json>;
+    search(artifact: Document, query: string, offset: number, limit: number, signal?: AbortSignal): Promise<Json>;
     remove(relativePaths: readonly string[]): Promise<{
         readonly deleted: number;
         readonly failed: number;
     }>;
     resolve(relativePath: string): string;
 }
+/** UTF-8 byte offsets; advance a non-boundary start, never split a code point. */
+export declare function utf8Page(bytes: Buffer, offset: number, limit: number, total: number): {
+    content: string;
+    offset: number;
+    end_offset: number;
+    total_bytes: number;
+    has_more: boolean;
+    next_offset: number | null;
+};

package/dist/runtime/artifacts.js

@@ -1,12 +1,17 @@
+import { createReadStream } from 'node:fs';
+import { Writable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { mkdir, stat, rename, unlink, writeFile } from 'node:fs/promises';
 import { basename, dirname, relative, resolve, sep } from 'node:path';
-import { gunzipSync, gzipSync } from 'node:zlib';
+import { createGunzip, gzipSync } from 'node:zlib';
 import { fail } from '../core/domain.js';
+const maximumArtifactBytes = 64 * 1024 * 1024;
 export class ArtifactStore {
     store;
     mode;
     root;
+    #fileTail = Promise.resolve();
     constructor(root, directory, store, mode) {
         this.store = store;
         this.mode = mode;
@@ -15,7 +20,12 @@ export class ArtifactStore {
     // Bytes are gzipped on disk; `sha256`/`size_bytes` describe the original, uncompressed content
     // (so identical logical content still dedups by hash regardless of compression, and API
     // consumers see the size they'll actually get back from read()) rather than the stored form.
-    async save(projectId, artifacts) {
+    save(projectId, artifacts) {
+        return this.#mutate(() => this.#save(projectId, artifacts));
+    }
+    async #save(projectId, artifacts) {
+        if (artifacts.some((artifact) => artifact.bytes.byteLength > maximumArtifactBytes))
+            fail('ARTIFACT_WRITE_LIMIT', 413, 'Artifact exceeds the 64 MiB verification limit.');
         const ids = [];
         for (const artifact of artifacts) {
             const sha256 = createHash('sha256').update(artifact.bytes).digest('hex');
@@ -38,15 +48,106 @@ export class ArtifactStore {
         }
         return ids;
     }
+    /** Verify the entire object before releasing any requested bytes. Memory is bounded by the selected range. */
+    async #scan(artifact, consume, signal) {
+        const maximum = maximumArtifactBytes;
+        const size = Number(artifact.size_bytes);
+        if (!Number.isSafeInteger(size) || size < 0)
+            fail('ARTIFACT_METADATA_INVALID', 503, 'Invalid Artifact size.');
+        if (size > maximum)
+            fail('ARTIFACT_READ_LIMIT', 413, 'Artifact exceeds the 64 MiB verification limit.');
+        const path = this.resolve(string(artifact.relative_path));
+        const hash = createHash('sha256');
+        let bytes = 0;
+        const boundedSignal = AbortSignal.any([AbortSignal.timeout(15000), ...(signal === undefined ? [] : [signal])]);
+        try {
+            if ((await stat(path)).size > maximum + 65536)
+                fail('ARTIFACT_READ_LIMIT', 413, 'Compressed Artifact exceeds the read limit.');
+            await pipeline(createReadStream(path), createGunzip(), new Writable({
+                write(chunk, _encoding, done) {
+                    try {
+                        const offset = bytes;
+                        bytes += chunk.length;
+                        if (bytes > size || bytes > maximum)
+                            fail('ARTIFACT_INTEGRITY_FAILED', 422, 'Artifact decompressed size exceeds its declaration.');
+                        hash.update(chunk);
+                        consume(chunk, offset);
+                        done();
+                    }
+                    catch (error) {
+                        done(error);
+                    }
+                }
+            }), { signal: boundedSignal });
+        }
+        catch (error) {
+            if (boundedSignal.aborted)
+                throw boundedSignal.reason;
+            const code = error.code;
+            if (code === 'ENOENT')
+                fail('ARTIFACT_MISSING', 404, 'Artifact bytes are no longer available.');
+            if (code?.startsWith('Z_'))
+                fail('ARTIFACT_INTEGRITY_FAILED', 422, 'Artifact compression is corrupt.');
+            throw error;
+        }
+        if (bytes !== size || hash.digest('hex') !== artifact.sha256)
+            fail('ARTIFACT_INTEGRITY_FAILED', 422, 'Artifact size or SHA-256 does not match.');
+    }
     async read(artifact) {
-        return gunzipSync(await readFile(this.resolve(string(artifact.relative_path))));
+        const chunks = [];
+        await this.#scan(artifact, (chunk) => { chunks.push(chunk); });
+        return Buffer.concat(chunks);
+    }
+    async readRange(artifact, offset, limit, signal) {
+        checkRange(offset, limit, 3000, 4);
+        const chunks = [];
+        await this.#scan(artifact, (chunk, start) => {
+            const from = Math.max(offset - start, 0);
+            const to = Math.min(offset + limit + 4 - start, chunk.length);
+            if (to > from)
+                chunks.push(chunk.subarray(from, to));
+        }, signal);
+        return { artifact_id: string(artifact.id), sha256: string(artifact.sha256), integrity: 'verified', capture: artifact.capture ?? 'unknown', stored: 'full', view: 'range',
+            ...utf8Page(Buffer.concat(chunks), offset, limit, Number(artifact.size_bytes)) };
+    }
+    async search(artifact, query, offset, limit, signal) {
+        checkRange(offset, limit, 10, 1);
+        const needle = Buffer.from(query);
+        if (needle.length === 0 || needle.length > 256)
+            fail('INVALID_INPUT', 400, 'Search query must be 1-256 UTF-8 bytes.');
+        let tail = Buffer.alloc(0);
+        const matches = [];
+        await this.#scan(artifact, (chunk, start) => {
+            const data = Buffer.concat([tail, chunk]);
+            const base = start - tail.length;
+            let index = data.indexOf(needle, Math.max(0, offset - base));
+            while (index >= 0) {
+                if (matches.length <= limit)
+                    matches.push({ offset: base + index, text: query });
+                else
+                    break;
+                index = data.indexOf(needle, index + 1);
+            }
+            tail = data.subarray(Math.max(0, data.length - needle.length + 1));
+        }, signal);
+        return { artifact_id: string(artifact.id), sha256: string(artifact.sha256), integrity: 'verified', capture: artifact.capture ?? 'unknown', stored: 'full', view: 'search', query, matches: matches.slice(0, limit),
+            next_offset: matches.length > limit ? (matches[limit - 1]?.offset ?? offset) + 1 : null, has_more: matches.length > limit };
     }
-    async remove(relativePaths) {
-        const results = await Promise.allSettled(relativePaths.map((entry) => unlink(this.resolve(entry))));
-        return {
-            deleted: results.filter((entry) => entry.status === 'fulfilled' || fileMissing(entry)).length,
-            failed: results.filter((entry) => entry.status === 'rejected' && !fileMissing(entry)).length
-        };
+    remove(relativePaths) {
+        return this.#mutate(async () => {
+            // A formerly orphaned content-addressed object may have acquired a new owner since purge.
+            const paths = relativePaths.filter(path => !this.store.artifactPathReferenced(path));
+            const results = await Promise.allSettled(paths.map((entry) => unlink(this.resolve(entry))));
+            return {
+                deleted: results.filter((entry) => entry.status === 'fulfilled' || fileMissing(entry)).length,
+                failed: results.filter((entry) => entry.status === 'rejected' && !fileMissing(entry)).length
+            };
+        });
+    }
+    #mutate(action) {
+        const result = this.#fileTail.then(action);
+        this.#fileTail = result.catch(() => undefined);
+        return result;
     }
     resolve(relativePath) {
         const path = resolve(this.root, relativePath);
@@ -70,3 +171,29 @@ function string(value) {
         fail('DATABASE_CORRUPT', 503, 'Artifact metadata is invalid.');
     return value;
 }
+/** UTF-8 byte offsets; advance a non-boundary start, never split a code point. */
+export function utf8Page(bytes, offset, limit, total) {
+    if (offset > total)
+        fail('INVALID_INPUT', 400, 'Offset is past the end of the object.');
+    let start = 0;
+    while (start < bytes.length && ((bytes[start] ?? 0) & 0xc0) === 0x80)
+        start++;
+    let end = Math.min(bytes.length, limit);
+    while (end > start && end < bytes.length && ((bytes[end] ?? 0) & 0xc0) === 0x80)
+        end--;
+    const next = offset + end;
+    let content;
+    try {
+        content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes.subarray(start, end));
+    }
+    catch {
+        fail('ARTIFACT_NOT_TEXT', 422, 'Requested range is not valid UTF-8 text; use the binary download API.');
+    }
+    return { content,
+        offset: offset + start, end_offset: next, total_bytes: total, has_more: next < total, next_offset: next < total ? next : null };
+}
+function checkRange(offset, limit, maximum, minimum) {
+    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < minimum || limit > maximum) {
+        fail('INVALID_INPUT', 400, 'Invalid read/search range.');
+    }
+}

package/dist/runtime/cache.d.ts

@@ -1,20 +1,63 @@
-import type { ModelMessage, ModelTool } from '../core/domain.js';
-export interface CachePlanEntry {
+import type { Json, ModelMessage } from '../core/domain.js';
+export interface PrefixEntry {
     readonly ordinal: number;
-    readonly container: 'message' | 'tool';
-    readonly stability: 'stable' | 'dynamic' | 'unknown';
-    readonly tokens: number;
-    readonly digest: string;
     readonly prefixDigest: string;
-    readonly prefixReachable: boolean;
-    readonly breakpoint: boolean;
+    readonly prefixTokens: number;
+    readonly blocks: number;
 }
-export interface CachePlan {
-    readonly status: 'planned' | 'disabled';
-    readonly fingerprintVersion: 1;
-    readonly providerVisibleFingerprint: string;
-    readonly barrierOrdinal: number | null;
-    readonly hintsApplied: false;
-    readonly entries: readonly CachePlanEntry[];
+export interface CacheCandidate {
+    readonly ordinal: number;
+    readonly kind: 'tools' | 'system' | 'summary' | 'user' | 'tool_group' | 'tail' | 'user_mark' | 'lookback_anchor';
+    readonly status: 'applied' | 'rejected';
+    readonly reason: string | null;
 }
-export declare function planCache(messages: readonly ModelMessage[], tools: readonly ModelTool[], enabled: boolean, minimumTokens: number, maximumBreakpoints: number, stability: Readonly<Record<string, 'stable' | 'dynamic' | 'unknown'>>): CachePlan;
+/** Select semantic cuts, never an interior of a tool protocol group. */
+export declare function selectCacheBreakpoints(messages: readonly ModelMessage[], entries: readonly PrefixEntry[], options: {
+    readonly mode: string;
+    readonly maximum: number;
+    readonly minimum: number;
+    readonly positions: readonly string[];
+    readonly supported: readonly boolean[];
+    readonly toolsTokens: number;
+    readonly hasTools: boolean;
+    readonly ttl: '5m' | '1h';
+    readonly previous?: Json | undefined;
+}): {
+    breakpoints: number[];
+    candidates: CacheCandidate[];
+    ttls: Record<string, "5m" | "1h">;
+};
+export declare function userCacheMark(message: ModelMessage): boolean;
+export declare function cacheMark(message: ModelMessage, mode: string): {
+    error: string | null;
+    ttl?: '5m' | '1h';
+};
+/** Local reusable-prefix estimates are not server hit counts. */
+export declare function compareCachePrefix(previous: Json | undefined, current: {
+    readonly entries: readonly {
+        readonly prefixDigest: string;
+        readonly prefixTokens: number;
+    }[];
+    readonly model?: string;
+    readonly systemDigest?: string;
+    readonly toolsDigest?: string;
+    readonly routeDigest?: string;
+    readonly toolsTokens?: number;
+    readonly historyKinds?: readonly string[];
+    readonly snippedIds?: readonly string[];
+    readonly historyIds?: readonly string[];
+    readonly requestOptionsDigest?: string;
+}): {
+    comparison: string;
+    unchangedPrefixMessages: number;
+    unchangedPrefixTokens: number;
+    reasons: string[];
+    firstChangedMessage?: never;
+} | {
+    comparison: string;
+    unchangedPrefixMessages: number;
+    unchangedPrefixTokens: number;
+    firstChangedMessage: number | null;
+    reasons: string[];
+};
+export declare function record(value: Json | undefined): Readonly<Record<string, Json>> | undefined;

package/dist/runtime/cache.js

@@ -1,44 +1,125 @@
-import { digest } from '../core/codec.js';
-import { estimateTokens } from './tokenizer.js';
-export function planCache(messages, tools, enabled, minimumTokens, maximumBreakpoints, stability) {
-    const segments = [
-        ...messages.map((message) => ({
-            container: 'message',
-            stability: stability[message.role === 'system' ? 'system' : 'context'] ?? 'unknown',
-            value: message
-        })),
-        ...tools.map((tool) => ({ container: 'tool', stability: stability.tools ?? 'unknown', value: tool }))
-    ];
-    let prefix = '';
-    let barrier = null;
-    let breakpoints = 0;
-    const entries = segments.map((segment, ordinal) => {
-        const segmentDigest = digest(segment.value);
-        prefix = digest([prefix, segmentDigest]);
-        if (barrier === null && segment.stability !== 'stable')
-            barrier = ordinal;
-        const tokens = estimateTokens(JSON.stringify(segment.value)).expected;
-        const reachable = barrier === null;
-        const breakpoint = enabled && reachable && tokens >= minimumTokens && breakpoints < maximumBreakpoints;
-        if (breakpoint)
-            breakpoints += 1;
-        return {
-            ordinal,
-            container: segment.container,
-            stability: segment.stability,
-            tokens,
-            digest: segmentDigest,
-            prefixDigest: prefix,
-            prefixReachable: reachable,
-            breakpoint
-        };
-    });
-    return {
-        status: enabled ? 'planned' : 'disabled',
-        fingerprintVersion: 1,
-        providerVisibleFingerprint: digest(segments.map((segment) => segment.value)),
-        barrierOrdinal: barrier,
-        hintsApplied: false,
-        entries
-    };
+import { assertContextBoundaries } from '../core/context-boundaries.js';
+/** Select semantic cuts, never an interior of a tool protocol group. */
+export function selectCacheBreakpoints(messages, entries, options) {
+    const legal = new Set(assertContextBoundaries(messages).legalCuts);
+    const candidates = [];
+    const add = (ordinal, kind, priority) => { if (ordinal >= 0)
+        candidates.push({ ordinal, kind, priority }); };
+    if (options.hasTools)
+        candidates.push({ ordinal: -1, kind: 'tools', priority: 50 });
+    add(messages.findLastIndex((m) => m.role === 'system'), 'system', 70);
+    add(messages.findLastIndex((m) => m.metadata?.purpose === 'compaction'), 'summary', 60);
+    add(messages.findLastIndex((m) => m.role === 'user' && m.metadata?.purpose !== 'todo_reminder'), 'user', 65);
+    add(messages.findLastIndex((m, i) => m.role === 'tool' && legal.has(i + 1)), 'tool_group', 80);
+    add(messages.length - 1, 'tail', 100);
+    for (const [ordinal, message] of messages.entries()) {
+        if (userCacheMark(message))
+            add(ordinal, 'user_mark', 95);
+    }
+    const previous = record(options.previous);
+    const oldEntries = previous?.entries;
+    const oldPoints = previous?.breakpoints;
+    const last = entries.at(-1);
+    if (options.mode === 'anthropic' && Array.isArray(oldEntries) && Array.isArray(oldPoints) && last !== undefined) {
+        for (const value of oldPoints) {
+            if (typeof value !== 'number')
+                continue;
+            const old = record(oldEntries[value]);
+            const current = entries[value];
+            // A moving tail cannot find this old write through Anthropic's 20-block window.
+            if (current !== undefined && old?.prefixDigest === current.prefixDigest && last.blocks - current.blocks > 20)
+                add(value, 'lookback_anchor', 90);
+        }
+    }
+    const selected = new Set();
+    const reports = [];
+    for (const candidate of candidates.sort((a, b) => b.priority - a.priority || b.ordinal - a.ordinal)) {
+        const message = messages[candidate.ordinal];
+        const entry = entries[candidate.ordinal];
+        const explicit = options.mode === 'anthropic' || options.mode === 'openai-explicit';
+        const mark = message === undefined ? undefined : cacheMark(message, options.mode);
+        let reason = !explicit ? 'cache_mode' : candidate.kind === 'user_mark' && mark?.error !== null ? mark?.error ?? 'invalid_user_mark' : !legal.has(candidate.ordinal + 1) ? 'inside_tool_group'
+            : candidate.ordinal === -1 ? (options.mode !== 'anthropic' || !options.positions.includes('tool') ? 'unsupported_position' : options.toolsTokens < options.minimum ? 'below_minimum' : selected.size >= options.maximum ? 'breakpoint_budget' : null)
+                : !options.supported[candidate.ordinal] ? 'unsupported_block'
+                    : !options.positions.includes(message?.role === 'system' ? 'system' : 'message') ? 'unsupported_position'
+                        : (entry?.prefixTokens ?? 0) < options.minimum ? 'below_minimum'
+                            : selected.has(candidate.ordinal) ? 'duplicate_position'
+                                : selected.size >= options.maximum ? 'breakpoint_budget' : null;
+        if (reason === null && options.mode === 'anthropic') {
+            const marked = [...selected, candidate.ordinal].sort((a, b) => a - b).flatMap((ordinal) => {
+                const item = messages[ordinal];
+                const ttl = item === undefined ? undefined : cacheMark(item, options.mode).ttl;
+                return ttl === undefined ? [] : [ttl];
+            });
+            const short = marked.indexOf('5m');
+            if (short >= 0 && marked.slice(short + 1).includes('1h'))
+                reason = 'ttl_order';
+        }
+        reports.push({ ordinal: candidate.ordinal, kind: candidate.kind, status: reason === null ? 'applied' : 'rejected', reason });
+        if (reason === null)
+            selected.add(candidate.ordinal);
+    }
+    const breakpoints = [...selected].sort((a, b) => a - b);
+    const ttls = {};
+    for (const ordinal of breakpoints) {
+        const explicitTtl = (index) => messages[index] === undefined ? undefined : cacheMark(messages[index], options.mode).ttl;
+        ttls[ordinal] = breakpoints.some((index) => index <= ordinal && explicitTtl(index) === '5m') ? '5m'
+            : breakpoints.some((index) => index >= ordinal && explicitTtl(index) === '1h') ? '1h' : options.ttl;
+    }
+    return { breakpoints, candidates: reports, ttls };
+}
+export function userCacheMark(message) {
+    const options = record(message.metadata?.providerOptions);
+    const anthropic = record(options?.anthropic);
+    const openai = record(options?.openai);
+    return message.metadata?.cache_prefix === true || anthropic?.cacheControl !== undefined || anthropic?.cache_control !== undefined || openai?.promptCacheBreakpoint !== undefined;
+}
+export function cacheMark(message, mode) {
+    const options = record(message.metadata?.providerOptions);
+    const anthropic = record(options?.anthropic);
+    const openai = record(options?.openai);
+    const control = anthropic?.cacheControl ?? anthropic?.cache_control;
+    const point = openai?.promptCacheBreakpoint;
+    if (control !== undefined) {
+        if (mode !== 'anthropic')
+            return { error: 'user_mark_provider_mismatch' };
+        const value = record(control);
+        if (value?.type !== 'ephemeral' || (value.ttl !== undefined && value.ttl !== '5m' && value.ttl !== '1h'))
+            return { error: 'invalid_user_mark' };
+        return { error: null, ...(value.ttl === undefined ? {} : { ttl: value.ttl }) };
+    }
+    if (point !== undefined && (mode !== 'openai-explicit' || record(point)?.mode !== 'explicit'))
+        return { error: 'invalid_user_mark' };
+    return { error: null };
+}
+/** Local reusable-prefix estimates are not server hit counts. */
+export function compareCachePrefix(previous, current) {
+    const plan = record(record(previous)?.cache_plan);
+    const entries = plan?.entries;
+    if (!Array.isArray(entries))
+        return { comparison: 'unavailable', unchangedPrefixMessages: 0, unchangedPrefixTokens: 0, reasons: ['no_previous_request'] };
+    let count = 0;
+    while (count < current.entries.length && count < entries.length && record(entries[count])?.prefixDigest === current.entries[count]?.prefixDigest)
+        count += 1;
+    const reasons = [];
+    for (const [field, reason] of [['model', 'model_switch'], ['routeDigest', 'route_change'], ['systemDigest', 'system_change'], ['toolsDigest', 'tool_schema_change'], ['requestOptionsDigest', 'request_options_change']]) {
+        if (current[field] !== undefined && plan?.[field] !== current[field])
+            reasons.push(reason);
+    }
+    const oldSnips = Array.isArray(plan?.snippedIds) ? plan.snippedIds : [];
+    if (current.snippedIds?.some((id) => !oldSnips.includes(id)))
+        reasons.push('snip');
+    const oldIds = Array.isArray(plan?.historyIds) ? plan.historyIds : [];
+    if (current.historyKinds?.some((kind, i) => kind === 'compaction' && !oldIds.includes(current.historyIds?.[i] ?? '')))
+        reasons.push('compact');
+    if (current.historyKinds?.some((kind, i) => kind === 'todo_reminder' && !oldIds.includes(current.historyIds?.[i] ?? '')))
+        reasons.push('todo_reminder');
+    if (reasons.length === 0)
+        reasons.push(count === entries.length && count === current.entries.length ? 'unchanged' : count === entries.length ? 'append' : 'history_edit');
+    return { comparison: 'available', unchangedPrefixMessages: count,
+        unchangedPrefixTokens: current.entries[count - 1]?.prefixTokens ?? (plan?.model === current.model && plan?.routeDigest === current.routeDigest && plan?.toolsDigest === current.toolsDigest ? current.toolsTokens ?? 0 : 0),
+        firstChangedMessage: count < Math.max(entries.length, current.entries.length) ? count : null, reasons };
+}
+export function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }

package/dist/runtime/calls.d.ts

@@ -17,5 +17,5 @@ export declare class CallRuntime {
         readonly result: Document | null;
     };
     waitAll(projectId: string, callIds: readonly string[], signal: AbortSignal): Promise<readonly Document[]>;
-    close(): Promise<void>;
+    close(projectId?: string): Promise<void>;
 }