@lensagent/core 0.1.0

package/dist/runtime/artifacts.d.ts

@@ -0,0 +1,15 @@
+import { type ArtifactOutput } from '../core/domain.js';
+import type { Document, Store } from '../store/store.js';
+export declare class ArtifactStore {
+    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>;
+    remove(relativePaths: readonly string[]): Promise<{
+        readonly deleted: number;
+        readonly failed: number;
+    }>;
+    resolve(relativePath: string): string;
+}

package/dist/runtime/artifacts.js

@@ -0,0 +1,72 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, relative, resolve, sep } from 'node:path';
+import { gunzipSync, gzipSync } from 'node:zlib';
+import { fail } from '../core/domain.js';
+export class ArtifactStore {
+    store;
+    mode;
+    root;
+    constructor(root, directory, store, mode) {
+        this.store = store;
+        this.mode = mode;
+        this.root = resolve(root, directory);
+    }
+    // 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) {
+        const ids = [];
+        for (const artifact of artifacts) {
+            const sha256 = createHash('sha256').update(artifact.bytes).digest('hex');
+            const relativePath = this.mode === 'content_addressed'
+                ? `${sha256.slice(0, 2)}/${sha256}`
+                : `${projectId}/${sha256}-${safeName(artifact.name)}`;
+            const path = this.resolve(relativePath);
+            await mkdir(dirname(path), { recursive: true });
+            const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+            await writeFile(temporary, gzipSync(artifact.bytes));
+            await rename(temporary, path);
+            const document = this.store.createArtifact(projectId, {
+                name: artifact.name,
+                mediaType: artifact.mediaType,
+                relativePath,
+                sha256,
+                sizeBytes: artifact.bytes.byteLength
+            });
+            ids.push(string(document.id));
+        }
+        return ids;
+    }
+    async read(artifact) {
+        return gunzipSync(await readFile(this.resolve(string(artifact.relative_path))));
+    }
+    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
+        };
+    }
+    resolve(relativePath) {
+        const path = resolve(this.root, relativePath);
+        const relation = relative(this.root, path);
+        if (relation === '..' || relation.startsWith(`..${sep}`))
+            fail('ARTIFACT_PATH_INVALID', 503, 'Artifact metadata escapes the Artifact root.');
+        return path;
+    }
+}
+function fileMissing(result) {
+    if (result.status !== 'rejected')
+        return false;
+    const reason = result.reason;
+    return typeof reason === 'object' && reason !== null && 'code' in reason && reason.code === 'ENOENT';
+}
+function safeName(value) {
+    return basename(value).replace(/[^a-zA-Z0-9._-]/g, '_') || 'artifact';
+}
+function string(value) {
+    if (typeof value !== 'string')
+        fail('DATABASE_CORRUPT', 503, 'Artifact metadata is invalid.');
+    return value;
+}

package/dist/runtime/cache.d.ts

@@ -0,0 +1,20 @@
+import type { ModelMessage, ModelTool } from '../core/domain.js';
+export interface CachePlanEntry {
+    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;
+}
+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 declare function planCache(messages: readonly ModelMessage[], tools: readonly ModelTool[], enabled: boolean, minimumTokens: number, maximumBreakpoints: number, stability: Readonly<Record<string, 'stable' | 'dynamic' | 'unknown'>>): CachePlan;

package/dist/runtime/cache.js

@@ -0,0 +1,44 @@
+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
+    };
+}

package/dist/runtime/calls.d.ts

@@ -0,0 +1,21 @@
+import type { Document, Store } from '../store/store.js';
+import type { ArtifactStore } from './artifacts.js';
+import type { CapabilityRegistry } from './capabilities.js';
+import type { Scheduler } from './scheduler.js';
+import type { EventBus } from './events.js';
+export declare class CallRuntime {
+    #private;
+    readonly store: Store;
+    readonly registry: CapabilityRegistry;
+    readonly scheduler: Scheduler;
+    readonly artifacts: ArtifactStore;
+    readonly events: EventBus;
+    constructor(store: Store, registry: CapabilityRegistry, scheduler: Scheduler, artifacts: ArtifactStore, events: EventBus);
+    dispatch(projectId: string, callId: string, parentSignal?: AbortSignal): void;
+    cancel(projectId: string, callId: string, expectedRevision?: number): {
+        readonly call: Document;
+        readonly result: Document | null;
+    };
+    waitAll(projectId: string, callIds: readonly string[], signal: AbortSignal): Promise<readonly Document[]>;
+    close(): Promise<void>;
+}

package/dist/runtime/calls.js

@@ -0,0 +1,130 @@
+import { LensError, UserInputRequiredError, fail } from '../core/domain.js';
+import { McpElicitationError } from '../adapters/mcp.js';
+import { normalizeOutput } from './results.js';
+export class CallRuntime {
+    store;
+    registry;
+    scheduler;
+    artifacts;
+    events;
+    #running = new Map();
+    #controllers = new Map();
+    constructor(store, registry, scheduler, artifacts, events) {
+        this.store = store;
+        this.registry = registry;
+        this.scheduler = scheduler;
+        this.artifacts = artifacts;
+        this.events = events;
+    }
+    dispatch(projectId, callId, parentSignal) {
+        if (this.#running.has(callId))
+            return;
+        const controller = new AbortController();
+        parentSignal?.addEventListener('abort', () => controller.abort(parentSignal.reason), { once: true });
+        this.#controllers.set(callId, controller);
+        const running = this.#execute(projectId, callId, controller.signal)
+            .finally(() => {
+            this.#running.delete(callId);
+            this.#controllers.delete(callId);
+        });
+        this.#running.set(callId, running);
+    }
+    cancel(projectId, callId, expectedRevision) {
+        const decision = this.store.decideCall(projectId, callId, 'cancel', expectedRevision);
+        this.#controllers.get(callId)?.abort(new Error('Call cancelled.'));
+        this.scheduler.cancel(callId);
+        return decision;
+    }
+    async waitAll(projectId, callIds, signal) {
+        while (!signal.aborted) {
+            const calls = callIds.map((callId) => this.store.getCall(projectId, callId));
+            if (calls.every((call) => call.state === 'TERMINAL'))
+                return calls;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        throw signal.reason;
+    }
+    async close() {
+        for (const controller of this.#controllers.values())
+            controller.abort(new Error('Call runtime closed.'));
+        await Promise.allSettled(this.#running.values());
+    }
+    async #execute(projectId, callId, signal) {
+        let call = this.store.getCall(projectId, callId);
+        if (call.state !== 'QUEUED')
+            return;
+        let acquired = false;
+        try {
+            const capabilityId = string(call.capability_id);
+            const definition = this.registry.get(capabilityId);
+            // Every Workspace in the Project, the Call's own first. A Project is one working set: an
+            // Agent bound to one folder can still read and search the others, which is what makes a Skill
+            // in one Workspace able to act on data in another.
+            const workspacePaths = this.store.projectWorkspacePaths(projectId, string(call.workspace_id));
+            const argumentsValue = jsonValue(call.input);
+            const validationArguments = originalArguments(argumentsValue);
+            const claims = this.registry.claims(capabilityId, { projectId, workspaceId: string(call.workspace_id), workspacePaths, arguments: validationArguments });
+            const executionSignal = await this.scheduler.acquire(callId, definition.adapterId, optionalString(call.step_id) ?? null, claims, () => { call = this.store.startCall(projectId, callId); }, signal);
+            acquired = true;
+            const output = await this.registry.execute({
+                callId,
+                projectId,
+                agentId: optionalString(call.agent_id) ?? null,
+                capabilityId,
+                arguments: capabilityId === 'ask_user' || capabilityId.startsWith('mcp:') ? argumentsValue : validationArguments,
+                workspacePaths,
+                workspaceId: string(call.workspace_id),
+                ...(call.policy === 'full_access' ? { fullAccess: true } : {}),
+                signal: executionSignal
+            }, validationArguments);
+            const normalized = normalizeOutput(output, definition.outputLimitBytes);
+            const artifactIds = await this.artifacts.save(projectId, normalized.artifacts);
+            if (this.store.getCall(projectId, callId).state === 'RUNNING') {
+                const outcome = output.outcome ?? 'success';
+                this.store.completeCall(projectId, callId, outcome, normalized.content, outcome === 'failed' ? output.errorCode ?? 'CAPABILITY_FAILED' : null, null, artifactIds, normalized.truncated);
+            }
+        }
+        catch (error) {
+            let current = this.store.getCall(projectId, callId);
+            if (current.state === 'QUEUED')
+                current = this.store.startCall(projectId, callId);
+            if (current.state === 'RUNNING' && (error instanceof McpElicitationError || error instanceof UserInputRequiredError)) {
+                current = this.store.waitCall(projectId, callId, error.prompt);
+                this.events.emit(projectId, this.store.stateRevision(), 'attention.required', { code: 'CALL_WAITING_USER', entity_type: 'call', entity_id: callId, agent_id: current.agent_id ?? null });
+            }
+            else if (current.state === 'RUNNING') {
+                const cancelled = signal.aborted;
+                this.store.completeCall(projectId, callId, cancelled ? 'cancelled' : 'failed', {}, cancelled ? 'CALL_CANCELLED' : errorCode(error), error instanceof Error ? error.message : String(error));
+            }
+        }
+        finally {
+            if (acquired)
+                this.scheduler.release(callId);
+        }
+    }
+}
+function errorCode(error) {
+    if (error instanceof LensError)
+        return error.code;
+    if (typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string')
+        return error.code;
+    return 'CAPABILITY_FAILED';
+}
+function string(value) {
+    if (typeof value !== 'string')
+        fail('DATABASE_CORRUPT', 503, 'A Call field is invalid.');
+    return value;
+}
+function optionalString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function jsonValue(value) {
+    if (value === undefined)
+        fail('DATABASE_CORRUPT', 503, 'Call input is missing.');
+    return value;
+}
+function originalArguments(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return value;
+    return 'arguments' in value && ('answer' in value || 'prompt' in value) ? value.arguments : value;
+}

package/dist/runtime/capabilities.d.ts

@@ -0,0 +1,58 @@
+import { type AdapterManifest, type CapabilityAdapter, type CapabilityDefinition, type CapabilityInvocation, type CapabilityOutput, type EffectScope, type Json } from '../core/domain.js';
+import { type AdapterTarget } from './manifests.js';
+export interface ResourceClaim {
+    readonly resource: string;
+    readonly mode: 'read' | 'write';
+}
+export interface ClaimContext {
+    readonly projectId: string;
+    readonly workspaceId: string;
+    readonly workspacePaths: readonly string[];
+    readonly arguments: Json;
+}
+export interface RegisteredCapability {
+    readonly definition: CapabilityDefinition;
+    readonly adapter: CapabilityAdapter;
+    readonly manifest: AdapterManifest;
+    effect?(argumentsValue: Json): EffectScope;
+    claims(context: ClaimContext): readonly ResourceClaim[];
+}
+export declare class CapabilityRegistry {
+    #private;
+    readonly target: AdapterTarget;
+    constructor(target: AdapterTarget);
+    register(capability: RegisteredCapability): void;
+    removeByAdapter(adapterId: string): void;
+    list(): readonly CapabilityDefinition[];
+    /**
+     * `CAP-01` `CapabilityCatalogEntry`: the documented, safe projection of the Registry.
+     *
+     * The Route used to return the internal `CapabilityDefinition` instead, which both used
+     * camelCase names the contract does not define -- so a client reading `capability_id`,
+     * `short_description` or `load_mode` got nothing -- and published the adapter id, the input JSON
+     * Schema and the output limit, none of which the catalog entry contains. Ordering follows 02A:
+     * `kind`, then `capability_id`, then `definition_version`.
+     */
+    catalog(): readonly Readonly<Record<string, Json>>[];
+    manifests(): readonly AdapterManifest[];
+    removeKind(kind: NonNullable<CapabilityDefinition['kind']>): void;
+    /**
+     * The manifests that make up the runtime contract.
+     *
+     * Workspace Skills are excluded deliberately. They are Project-local file content, so including
+     * them made `runtime_contract_digest` -- which `/health/ready` publishes with no Project scope --
+     * depend on which Project was asked. Two Projects with different Skills then reported different
+     * values for the same global field, and the handshake check comparing readiness against
+     * `subscription.ready` could never pass for a Project whose Skills differed from the default
+     * one's: a permanent resync loop rather than a transient mismatch. A changed Skill is still
+     * visible through `metadata_revision` and the Agent's Assignment digest.
+     */
+    contractManifests(): readonly AdapterManifest[];
+    get(capabilityId: string): CapabilityDefinition;
+    find(capabilityId: string): CapabilityDefinition | undefined;
+    search(query: string, limit: number): readonly CapabilityDefinition[];
+    claims(capabilityId: string, context: ClaimContext): readonly ResourceClaim[];
+    effect(capabilityId: string, argumentsValue: Json): EffectScope;
+    execute(invocation: CapabilityInvocation, validationArguments?: Json): Promise<CapabilityOutput>;
+}
+export declare function claimsConflict(left: readonly ResourceClaim[], right: readonly ResourceClaim[]): boolean;

package/dist/runtime/capabilities.js

@@ -0,0 +1,196 @@
+import { isAbsolute, resolve, sep } from 'node:path';
+import { Ajv } from 'ajv';
+import { fail } from '../core/domain.js';
+import { assertCapabilityManifest } from './manifests.js';
+export class CapabilityRegistry {
+    target;
+    #entries = new Map();
+    #ajv = new Ajv({ allErrors: true, strict: false });
+    constructor(target) {
+        this.target = target;
+    }
+    register(capability) {
+        if (this.#entries.has(capability.definition.id))
+            fail('CAPABILITY_DUPLICATE', 503, `Capability ${capability.definition.id} is already registered.`);
+        assertCapabilityManifest(capability.manifest, capability.definition, this.target);
+        this.#entries.set(capability.definition.id, {
+            ...capability,
+            validate: this.#ajv.compile(capability.definition.inputSchema),
+            ...(capability.definition.outputSchema === undefined ? {} : { validateOutput: this.#ajv.compile(capability.definition.outputSchema) })
+        });
+    }
+    removeByAdapter(adapterId) {
+        for (const [capabilityId, entry] of this.#entries) {
+            if (entry.definition.adapterId === adapterId)
+                this.#entries.delete(capabilityId);
+        }
+    }
+    list() {
+        return [...this.#entries.values()].map((entry) => entry.definition).sort((left, right) => left.id.localeCompare(right.id));
+    }
+    /**
+     * `CAP-01` `CapabilityCatalogEntry`: the documented, safe projection of the Registry.
+     *
+     * The Route used to return the internal `CapabilityDefinition` instead, which both used
+     * camelCase names the contract does not define -- so a client reading `capability_id`,
+     * `short_description` or `load_mode` got nothing -- and published the adapter id, the input JSON
+     * Schema and the output limit, none of which the catalog entry contains. Ordering follows 02A:
+     * `kind`, then `capability_id`, then `definition_version`.
+     */
+    catalog() {
+        return [...this.#entries.values()]
+            .map((entry) => ({
+            capability_id: entry.definition.id,
+            kind: entry.definition.kind ?? 'tool',
+            name: entry.definition.title,
+            short_description: entry.definition.description,
+            // The definition carries no hint list; an empty array states that rather than inventing
+            // tokens that would then rank search results.
+            search_hints: [],
+            load_mode: entry.definition.loadMode,
+            model_surfaces: entry.definition.promptText === undefined
+                ? ['callable_schema']
+                : ['callable_schema', 'prompt_instruction'],
+            definition_version: entry.manifest.version,
+            definition_digest: entry.manifest.configSchemaDigest
+        }))
+            .sort((left, right) => left.kind.localeCompare(right.kind)
+            || left.capability_id.localeCompare(right.capability_id)
+            || left.definition_version.localeCompare(right.definition_version));
+    }
+    manifests() {
+        return [...this.#entries.values()].map((entry) => entry.manifest).sort((left, right) => left.id.localeCompare(right.id));
+    }
+    removeKind(kind) {
+        for (const [capabilityId, entry] of this.#entries) {
+            if (entry.definition.kind === kind)
+                this.#entries.delete(capabilityId);
+        }
+    }
+    /**
+     * The manifests that make up the runtime contract.
+     *
+     * Workspace Skills are excluded deliberately. They are Project-local file content, so including
+     * them made `runtime_contract_digest` -- which `/health/ready` publishes with no Project scope --
+     * depend on which Project was asked. Two Projects with different Skills then reported different
+     * values for the same global field, and the handshake check comparing readiness against
+     * `subscription.ready` could never pass for a Project whose Skills differed from the default
+     * one's: a permanent resync loop rather than a transient mismatch. A changed Skill is still
+     * visible through `metadata_revision` and the Agent's Assignment digest.
+     */
+    contractManifests() {
+        const contract = new Set(this.list().filter((definition) => definition.kind !== 'skill').map((definition) => definition.id));
+        return this.manifests().filter((manifest) => manifest.capabilities.every((capability) => contract.has(capability)));
+    }
+    get(capabilityId) {
+        return this.#entry(capabilityId).definition;
+    }
+    find(capabilityId) {
+        return this.#entries.get(capabilityId)?.definition;
+    }
+    search(query, limit) {
+        const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+        return this.list()
+            .map((entry) => ({ entry, score: words.reduce((score, word) => score + `${entry.id} ${entry.title} ${entry.description}`.toLowerCase().split(word).length - 1, 0) }))
+            .filter(({ score }) => score > 0)
+            .sort((left, right) => right.score - left.score || left.entry.id.localeCompare(right.entry.id))
+            .slice(0, limit)
+            .map(({ entry }) => entry);
+    }
+    // Any failure to work out the resources falls back to a global write claim: AGENTS.md requires the
+    // conservative answer when concurrency safety cannot be determined.
+    claims(capabilityId, context) {
+        const entry = this.#validated(capabilityId, context.arguments);
+        try {
+            return entry.claims(context);
+        }
+        catch {
+            return [{ resource: '*', mode: 'write' }];
+        }
+    }
+    effect(capabilityId, argumentsValue) {
+        const entry = this.#validated(capabilityId, argumentsValue);
+        const effect = entry.effect?.(argumentsValue) ?? entry.definition.effect;
+        if (!entry.manifest.effectScopes.includes(effect))
+            fail('ADAPTER_INCOMPATIBLE', 503, `Adapter manifest ${entry.manifest.id} does not cover effect ${effect}.`);
+        return effect;
+    }
+    async execute(invocation, validationArguments = invocation.arguments) {
+        const entry = this.#validated(invocation.capabilityId, validationArguments);
+        const output = await entry.adapter.execute(invocation);
+        if (entry.validateOutput !== undefined) {
+            const content = jsonObject(output.content);
+            const structured = content?.structured_content;
+            if (structured !== undefined && !entry.validateOutput(structured)) {
+                fail('RESULT_NORMALIZATION_FAILED', 422, 'Capability output does not match the declared Schema.');
+            }
+        }
+        return output;
+    }
+    #validated(capabilityId, argumentsValue) {
+        const entry = this.#entry(capabilityId);
+        if (!entry.validate(argumentsValue)) {
+            fail('CAPABILITY_ARGUMENT_INVALID', 400, 'Capability arguments do not match the declared Schema.', {
+                capability_id: capabilityId,
+                issues: (entry.validate.errors ?? []).map((error) => ({ path: error.instancePath, message: error.message ?? 'invalid' }))
+            });
+        }
+        return entry;
+    }
+    #entry(capabilityId) {
+        const entry = this.#entries.get(capabilityId);
+        if (entry === undefined)
+            fail('CAPABILITY_NOT_FOUND', 404, `Capability ${capabilityId} is not registered.`);
+        return entry;
+    }
+}
+function jsonObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    return value;
+}
+export function claimsConflict(left, right) {
+    for (const first of left) {
+        for (const second of right) {
+            if (!resourcesOverlap(first.resource, second.resource))
+                continue;
+            if (first.mode === 'write' || second.mode === 'write')
+                return true;
+        }
+    }
+    return false;
+}
+// Two resources overlap when a Call touching one can affect the other. '*' covers everything.
+//
+// Filesystem resources overlap when either contains the other: a Call claiming a directory --
+// terminal_command_run's cwd, or glob/grep over a Workspace root -- must conflict with one claiming a
+// file inside it, even though the strings differ. Exact string equality missed that entirely, so a
+// command running in a directory could execute in parallel with a write to a file under it.
+//
+// Non-path resources (`network`, `mcp:<id>`, `agent:<id>`) only ever match exactly; prefix logic there
+// would make `mcp:a` collide with `mcp:ab`.
+//
+// This is the "父子目录重叠" rule from 05 调用、执行和 Result. It can only add conflicts, never hide
+// one, which is the direction AGENTS.md requires when concurrency safety is uncertain -- at the cost
+// of serializing a Workspace-wide grep against any write in that Workspace.
+function resourcesOverlap(left, right) {
+    if (left === '*' || right === '*')
+        return true;
+    const first = fileKey(left);
+    const second = fileKey(right);
+    if (first === undefined || second === undefined)
+        return left === right;
+    return first === second || contains(first, second) || contains(second, first);
+}
+// Case folded wherever the platform's filesystem is case-insensitive, so /ws/A.ts and /ws/a.ts are one
+// resource on Windows and macOS but two on Linux. Folding can only add conflicts, so a case-sensitive
+// volume on macOS loses parallelism rather than safety.
+function fileKey(resource) {
+    if (!isAbsolute(resource))
+        return undefined;
+    const normalized = resolve(resource);
+    return process.platform === 'linux' ? normalized : normalized.toLowerCase();
+}
+function contains(parent, child) {
+    return child.startsWith(parent.endsWith(sep) ? parent : `${parent}${sep}`);
+}

package/dist/runtime/cleanup.d.ts

@@ -0,0 +1,7 @@
+import type { ExecutorClient } from '../adapters/executor.js';
+import type { Document } from '../store/store.js';
+import type { ArtifactStore } from './artifacts.js';
+export declare function applyPurge(purged: Document, artifacts: ArtifactStore, executor: ExecutorClient): Promise<{
+    readonly deleted: number;
+    readonly failed: number;
+}>;

package/dist/runtime/cleanup.js

@@ -0,0 +1,33 @@
+import { fail } from '../core/domain.js';
+// The out-of-transaction half of a Task purge. Store#purgeTaskRows deletes the rows and reports what
+// is left over: Artifact files on disk, and the Calls whose file history the Executor still holds
+// (see docs/architecture/harness-level3/09-file-snapshot-storage-decision.md). Neither can happen
+// inside the transaction, which does no file or network I/O.
+//
+// Errors propagate. The purge has already committed and those Call ids no longer exist in SQLite, so
+// a failure here leaks Executor-side history permanently -- the Executor never expires history on
+// its own. Surfacing that once is better than hiding it.
+export async function applyPurge(purged, artifacts, executor) {
+    const paths = purged.orphaned_artifact_paths;
+    if (!Array.isArray(paths) || paths.some((entry) => typeof entry !== 'string'))
+        fail('DATABASE_CORRUPT', 503, 'Task purge returned invalid Artifact paths.');
+    const files = await artifacts.remove(paths);
+    for (const [workspaceId, callIds] of byWorkspace(purged.purged_calls)) {
+        await executor.deleteCallHistory(workspaceId, callIds);
+    }
+    return files;
+}
+function byWorkspace(value) {
+    const grouped = new Map();
+    if (!Array.isArray(value))
+        return grouped;
+    for (const entry of value) {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry))
+            continue;
+        const record = entry;
+        if (typeof record.workspace_id !== 'string' || typeof record.call_id !== 'string')
+            continue;
+        grouped.set(record.workspace_id, [...grouped.get(record.workspace_id) ?? [], record.call_id]);
+    }
+    return grouped;
+}

package/dist/runtime/context.d.ts

@@ -0,0 +1,34 @@
+import { type Json, type ModelMessage } from '../core/domain.js';
+import type { Store } from '../store/store.js';
+import type { HarnessConfig } from '../config/schema.js';
+import type { Document } from '../store/store.js';
+import type { ResolvedProfile } from './profile.js';
+import type { CapabilityRegistry } from './capabilities.js';
+import { type TokenEstimate } from './tokenizer.js';
+export interface ContextDecision {
+    readonly stage: 'tool_result_budget' | 'snip' | 'microcompact' | 'context_collapse';
+    readonly sourceTokens: number;
+    readonly projectedTokens: number;
+}
+export interface PreparedContext {
+    readonly source: ContextSource;
+    readonly messages: readonly ModelMessage[];
+    readonly estimate: TokenEstimate;
+    readonly sourceRevision: number;
+    readonly digest: string;
+    readonly decisions: readonly ContextDecision[];
+}
+export interface ContextSource {
+    readonly agent: Document;
+    readonly items: readonly Document[];
+    readonly overrides: readonly Document[];
+    readonly capabilities: readonly Document[];
+}
+export declare class ContextEngine {
+    readonly store: Store;
+    readonly registry: CapabilityRegistry;
+    constructor(store: Store, registry: CapabilityRegistry);
+    capture(projectId: string, agentId: string): ContextSource;
+    prepare(projectId: string, agentId: string, config: HarnessConfig, contextWindowTokens: number, profile: ResolvedProfile, requestFrame?: Json): PreparedContext;
+    prepareSource(source: ContextSource, config: HarnessConfig, contextWindowTokens: number, profile: ResolvedProfile, requestFrame?: Json): PreparedContext;
+}