@team-harness/memory-algorithms 0.1.0

package/dist/runtime/l1.d.ts

@@ -0,0 +1,10 @@
+import type { Atom, Continuation, Dependencies, ExtractionResult, Message, RunInput } from "../contracts.js";
+export interface L1Input extends RunInput {
+    messages: Message[];
+    continuation?: Continuation;
+    maxNewMessages?: number;
+    maxBackgroundMessages?: number;
+    conflictRecallTopK?: number;
+}
+export declare function validateMessages(messages: Message[]): void;
+export declare function extractL1(deps: Dependencies, input: L1Input): Promise<ExtractionResult<Atom>>;

package/dist/runtime/l1.js

@@ -0,0 +1,172 @@
+import { formatExtractionPrompt, getExtractMemoriesSystemPrompt } from "../upstream/core/prompts/l1-extraction.js";
+import { formatBatchConflictPrompt, getConflictDetectionSystemPrompt } from "../upstream/core/prompts/l1-dedup.js";
+import { parseExtractionResult, normalizeType } from "../upstream/core/record/l1-extractor.js";
+import { parseBatchResult } from "../upstream/core/record/l1-dedup.js";
+import { composeMemorySystemPrompt } from "../upstream/core/memory-prompt/composer.js";
+import { shouldExtractL1 } from "../upstream/utils/sanitize.js";
+import { ALGORITHM_VERSION, Run, coverage, hash, uniqueRefs } from "./run.js";
+// Port of l1-candidate-recall.ts: native hybrid first, otherwise parallel legs + RRF(k=60).
+async function recall(run, query, topK) {
+    const search = run.deps.memories;
+    if (!search)
+        return [];
+    if (++run.recallQueries > run.limits.maxRecallQueries)
+        throw new Error("Candidate recall budget exhausted");
+    const leg = async (fn) => {
+        try {
+            return await run.wait(fn());
+        }
+        catch {
+            run.check();
+            run.diagnostics.push("Candidate recall leg failed; dedup may be incomplete");
+            return [];
+        }
+    };
+    let lists;
+    if (search.hybrid)
+        lists = [await leg(() => search.hybrid(query, run.input.scopeKey, topK, run.signal))];
+    else {
+        lists = await Promise.all([
+            search.fts ? leg(() => search.fts(query, run.input.scopeKey, topK, run.signal)) : Promise.resolve([]),
+            search.embed && search.vector ? leg(async () => search.vector(await run.wait(search.embed(query, run.signal)), run.input.scopeKey, topK, run.signal)) : Promise.resolve([]),
+        ]);
+    }
+    const ranked = new Map();
+    for (const list of lists) {
+        const seen = new Set();
+        for (const [rank, value] of list.entries()) {
+            const atom = run.read(value);
+            if (seen.has(atom.id))
+                continue;
+            seen.add(atom.id);
+            const old = ranked.get(atom.id);
+            ranked.set(atom.id, { atom, score: (old?.score ?? 0) + 1 / (60 + rank + 1) });
+        }
+    }
+    return [...ranked.values()].sort((a, b) => b.score - a.score).slice(0, topK).map(r => r.atom);
+}
+export function validateMessages(messages) {
+    const ids = new Set();
+    for (const m of messages) {
+        if (!m.id || ids.has(m.id) || !Number.isFinite(m.timestamp) || !Array.isArray(m.evidence) || !m.evidence.length)
+            throw new Error("Invalid or duplicate source message");
+        if (!["user", "assistant", "tool_call", "tool_result"].includes(m.role) || typeof m.content !== "string")
+            throw new Error("Invalid message content");
+        for (const ref of m.evidence)
+            if (!ref.id || ref.version === undefined || ref.version === null)
+                throw new Error("Missing evidence version");
+        ids.add(m.id);
+    }
+    uniqueRefs(messages.flatMap(m => m.evidence));
+}
+export async function extractL1(deps, input) {
+    input = { ...input, messages: structuredClone(input.messages), strategy: structuredClone(input.strategy) };
+    const inputHash = hash({ scopeKey: input.scopeKey, mode: input.mode ?? "code", messages: input.messages, strategy: input.strategy,
+        maxNewMessages: input.maxNewMessages ?? 10, maxBackgroundMessages: input.maxBackgroundMessages ?? 5, conflictRecallTopK: input.conflictRecallTopK ?? 5 });
+    const run = new Run(deps, input, "l1", inputHash);
+    const cov = coverage(input.messages.map(m => m.id));
+    try {
+        run.check();
+        validateMessages(input.messages);
+        const start = input.continuation?.nextIndex ?? 0;
+        if (input.continuation && (input.continuation.algorithmVersion !== ALGORITHM_VERSION || input.continuation.inputHash !== inputHash))
+            throw new Error("Stale continuation");
+        const count = input.maxNewMessages ?? 10, bgCount = input.maxBackgroundMessages ?? 5, topK = input.conflictRecallTopK ?? 5;
+        if (![start, count, bgCount, topK].every(Number.isSafeInteger) || start < 0 || start > input.messages.length || count < 1 || bgCount < 0 || topK < 1)
+            throw new Error("Invalid window options");
+        const end = Math.min(start + count, input.messages.length);
+        const window = input.messages.slice(start, end);
+        const fresh = window.filter(m => shouldExtractL1(m.content));
+        const background = bgCount === 0 ? [] : input.messages.slice(0, start).filter(m => shouldExtractL1(m.content)).slice(-bgCount);
+        cov.processed = window.map(m => m.id);
+        cov.filtered = window.filter(m => !fresh.includes(m)).map(m => m.id);
+        cov.background = background.map(m => m.id);
+        cov.truncated = [...window, ...background].filter(m => m.completeness === "truncated").map(m => m.id);
+        cov.remaining = input.messages.slice(end).map(m => m.id);
+        const extracted = [];
+        let sceneNames = [];
+        if (fresh.length) {
+            const system = composeMemorySystemPrompt(getExtractMemoriesSystemPrompt(input.mode ?? "code"), input.strategy);
+            const raw = await run.model(system, formatExtractionPrompt({ newMessages: fresh, backgroundMessages: background, previousSceneName: input.continuation?.previousSceneName }));
+            const parsed = parseExtractionResult(raw);
+            if (parsed.emptyReason && parsed.emptyReason !== "empty_scenes")
+                throw new Error(`L1 parse failed: ${parsed.emptyReason}`);
+            sceneNames = parsed.scenes.map(s => s.scene_name);
+            const allowed = new Set(fresh.map(m => m.id));
+            for (const scene of parsed.scenes) {
+                if (scene.message_ids.some(id => !allowed.has(id)))
+                    throw new Error("Scene cites evidence outside new messages");
+                for (const memory of scene.memories) {
+                    const type = normalizeType(memory.type);
+                    if (!type)
+                        throw new Error("Invalid memory type");
+                    if (!memory.source_message_ids.length || memory.source_message_ids.some(id => !allowed.has(id)))
+                        throw new Error("Memory cites evidence outside new messages");
+                    if (!Number.isFinite(memory.priority) || memory.priority < -1 || memory.priority > 100)
+                        throw new Error("Invalid priority");
+                    extracted.push({ ...memory, metadata: memory.metadata, type, scene_name: scene.scene_name, record_id: run.id() });
+                    if (extracted.length > run.limits.maxExtractedMemories)
+                        throw new Error("Extracted memory budget exhausted");
+                }
+            }
+        }
+        if (new Set(extracted.map(m => m.record_id)).size !== extracted.length)
+            throw new Error("Duplicate generated ID");
+        const matches = [];
+        for (const memory of extracted)
+            matches.push({ newMemory: memory, candidates: await recall(run, memory.content, topK) });
+        let decisions = extracted.map(m => ({ record_id: m.record_id, action: "store", target_ids: [] }));
+        if (matches.some(m => m.candidates.length)) {
+            const raw = await run.model(getConflictDetectionSystemPrompt(input.mode ?? "code"), formatBatchConflictPrompt(matches));
+            decisions = parseBatchResult(raw, extracted, { warn: () => run.diagnostics.push("Dedup parser degraded; conflict status unverified"), debug: () => run.diagnostics.push("Missing dedup decision; stored without conflict verification") });
+        }
+        const candidates = new Map(matches.flatMap(m => m.candidates).map(m => [m.id, m]));
+        if (extracted.some(m => candidates.has(m.record_id)))
+            throw new Error("Generated ID collides with existing memory");
+        const usedTargets = new Set(), usedDecisions = new Set();
+        const changes = [];
+        for (const d of decisions) {
+            const memory = extracted.find(m => m.record_id === d.record_id);
+            if (!memory || usedDecisions.has(d.record_id))
+                throw new Error("Unknown or duplicate dedup decision");
+            usedDecisions.add(d.record_id);
+            const targetIds = [...new Set(d.target_ids)];
+            for (const id of targetIds)
+                if (!candidates.has(id) || usedTargets.has(id))
+                    throw new Error("Invalid or overlapping dedup targets");
+            const old = targetIds.map(id => candidates.get(id));
+            if ((d.action === "merge" || d.action === "update") && (!old.length || !d.merged_content?.trim()))
+                throw new Error("Incomplete dedup update");
+            if (d.action === "store" && old.length)
+                throw new Error("Store cannot replace existing memory");
+            if (d.action !== "skip")
+                targetIds.forEach(id => usedTargets.add(id));
+            const before = old.map(m => ({ id: m.id, version: m.version }));
+            if (d.action === "skip") {
+                changes.push({ action: "skip", before });
+                continue;
+            }
+            const isMerge = d.action === "merge" || d.action === "update";
+            if (d.merged_priority !== undefined && (!Number.isFinite(d.merged_priority) || d.merged_priority < -1 || d.merged_priority > 100))
+                throw new Error("Invalid merged priority");
+            const evidence = uniqueRefs([...fresh.filter(m => memory.source_message_ids.includes(m.id)).flatMap(m => m.evidence.map(ref => m.completeness === "truncated" ? { ...ref, completeness: "truncated" } : ref)), ...old.flatMap(m => m.evidence)]);
+            changes.push({ action: d.action === "store" ? "create" : d.action, before, after: {
+                    id: memory.record_id, content: isMerge ? d.merged_content : memory.content,
+                    type: d.merged_type ?? memory.type, priority: d.merged_priority ?? memory.priority,
+                    scene_name: memory.scene_name, source_message_ids: [...new Set([...memory.source_message_ids, ...old.flatMap(m => m.source_message_ids)])],
+                    metadata: memory.metadata, timestamps: [...new Set([run.time, ...old.flatMap(m => m.timestamps), ...(d.merged_timestamps ?? [])])].sort(),
+                    createdAt: run.time, updatedAt: run.time, version: Math.max(0, ...old.map(m => m.version)) + 1,
+                    sessionKey: input.scopeKey, sessionId: input.runId, scopeKey: input.scopeKey, evidence,
+                } });
+        }
+        run.check();
+        const result = run.result(changes, cov, end < input.messages.length ? "partial" : "completed");
+        result.sceneNames = sceneNames;
+        if (end < input.messages.length)
+            result.continuation = { algorithmVersion: ALGORITHM_VERSION, inputHash, nextIndex: end, previousSceneName: sceneNames.at(-1) ?? input.continuation?.previousSceneName };
+        return result;
+    }
+    catch (error) {
+        return run.failure(error, cov);
+    }
+}

package/dist/runtime/run.d.ts

@@ -0,0 +1,44 @@
+import type { Change, Coverage, Dependencies, ExtractionResult, Limits, RunInput, Stage, VersionRef } from "../contracts.js";
+import type { LocalTool } from "./tools.js";
+export declare const ALGORITHM_VERSION = "0.1.0";
+export declare const UPSTREAM_COMMIT = "906b5823b5106eed8f842b62f16d23228838149a";
+export declare function hash(value: unknown): string;
+export declare function uniqueRefs<T extends {
+    id: string;
+    version: string | number;
+    hash?: string;
+    completeness?: "full" | "truncated";
+}>(refs: T[]): T[];
+export declare class Run {
+    readonly deps: Dependencies;
+    readonly input: RunInput;
+    readonly stage: Stage;
+    readonly inputHash: string;
+    readonly limits: Limits;
+    readonly signal: AbortSignal;
+    readonly time: string;
+    readonly diagnostics: string[];
+    readonly readSet: Map<string, VersionRef>;
+    private readonly readHashes;
+    readonly promptHashes: string[];
+    calls: number;
+    toolCalls: number;
+    recallQueries: number;
+    private integrityError?;
+    private usageKnown;
+    private usage;
+    constructor(deps: Dependencies, input: RunInput, stage: Stage, inputHash: string);
+    id(): string;
+    check(): void;
+    invalidate(message: string): never;
+    wait<T>(promise: Promise<T>): Promise<T>;
+    read<T extends {
+        id: string;
+        version: number;
+        scopeKey: string;
+    }>(value: T): T;
+    model(systemPrompt: string, prompt: string, tools?: Record<string, LocalTool<any>>, maxIterations?: number, maxOutputTokens?: number): Promise<string>;
+    result<T>(changes: Change<T>[], coverage: Coverage, status?: ExtractionResult<T>["status"]): ExtractionResult<T>;
+    failure<T>(error: unknown, coverage: Coverage): ExtractionResult<T>;
+}
+export declare function coverage(ids?: string[]): Coverage;

package/dist/runtime/run.js

@@ -0,0 +1,191 @@
+import { createHash, randomUUID } from "node:crypto";
+import { Ajv } from "ajv";
+export const ALGORITHM_VERSION = "0.1.0";
+export const UPSTREAM_COMMIT = "906b5823b5106eed8f842b62f16d23228838149a";
+export function hash(value) {
+    return createHash("sha256").update(JSON.stringify(value, (_key, item) => {
+        if (item && typeof item === "object" && !Array.isArray(item))
+            return Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]]));
+        return item;
+    })).digest("hex");
+}
+export function uniqueRefs(refs) {
+    const result = new Map();
+    for (const ref of refs) {
+        const key = JSON.stringify([ref.id, ref.version]), old = result.get(key);
+        if (old?.hash && ref.hash && old.hash !== ref.hash)
+            throw new Error("Conflicting evidence hashes for the same version");
+        const merged = { ...old, ...ref };
+        if (old?.hash)
+            merged.hash = old.hash;
+        if (old?.completeness === "truncated")
+            merged.completeness = "truncated";
+        result.set(key, merged);
+    }
+    return [...result.values()];
+}
+const defaults = {
+    maxCalls: 20, maxIterations: 16, maxInputChars: 120_000,
+    maxOutputTokens: 8192, timeoutMs: 180_000, maxToolCalls: 64, maxWorkspaceChars: 1_000_000,
+    maxRecallQueries: 100, maxExtractedMemories: 100,
+};
+export class Run {
+    deps;
+    input;
+    stage;
+    inputHash;
+    limits;
+    signal;
+    time;
+    diagnostics = [];
+    readSet = new Map();
+    readHashes = new Map();
+    promptHashes = [];
+    calls = 0;
+    toolCalls = 0;
+    recallQueries = 0;
+    integrityError;
+    usageKnown = true;
+    usage = { inputTokens: 0, outputTokens: 0 };
+    constructor(deps, input, stage, inputHash) {
+        this.deps = deps;
+        this.input = input;
+        this.stage = stage;
+        this.inputHash = inputHash;
+        if (!input.runId || !input.scopeKey)
+            throw new Error("runId and scopeKey are required");
+        if (input.strategy && input.strategy.layer !== stage)
+            throw new Error("Strategy layer mismatch");
+        this.limits = { ...defaults, ...Object.fromEntries(Object.entries(input.limits ?? {}).filter(([, value]) => value !== undefined)) };
+        for (const [key, value] of Object.entries(this.limits)) {
+            if (!Number.isSafeInteger(value) || value <= 0)
+                throw new Error(`Invalid limit: ${key}`);
+        }
+        const timeout = AbortSignal.timeout(this.limits.timeoutMs);
+        this.signal = input.signal ? AbortSignal.any([input.signal, timeout]) : timeout;
+        this.time = (deps.now?.() ?? new Date()).toISOString();
+    }
+    id() { return this.deps.createId?.() ?? randomUUID(); }
+    check() { this.signal.throwIfAborted(); if (this.integrityError)
+        throw this.integrityError; }
+    invalidate(message) { this.integrityError = new Error(message); throw this.integrityError; }
+    async wait(promise) {
+        this.check();
+        return new Promise((resolve, reject) => {
+            const abort = () => reject(this.signal.reason);
+            this.signal.addEventListener("abort", abort, { once: true });
+            promise.then(value => {
+                this.signal.removeEventListener("abort", abort);
+                if (this.signal.aborted)
+                    reject(this.signal.reason);
+                else
+                    resolve(value);
+            }, error => { this.signal.removeEventListener("abort", abort); reject(error); });
+        });
+    }
+    read(value) {
+        if (!value.id || value.scopeKey !== this.input.scopeKey || !Number.isSafeInteger(value.version) || value.version < 1) {
+            this.invalidate("Read outside requested scope or invalid entity version");
+        }
+        const prior = this.readSet.get(value.id);
+        if (prior && prior.version !== value.version)
+            this.invalidate("Snapshot changed during analysis");
+        const digest = hash(value);
+        if (this.readHashes.has(value.id) && this.readHashes.get(value.id) !== digest)
+            this.invalidate("Entity content changed without a version change");
+        this.readSet.set(value.id, { id: value.id, version: value.version });
+        this.readHashes.set(value.id, digest);
+        return structuredClone(value);
+    }
+    async model(systemPrompt, prompt, tools = {}, maxIterations = this.limits.maxIterations, maxOutputTokens = this.limits.maxOutputTokens) {
+        const ajv = new Ajv({ strict: false, allErrors: true });
+        const validators = new Map(Object.entries(tools).map(([name, t]) => [name, ajv.compile(t.inputSchema)]));
+        const messages = [{ role: "user", content: prompt }];
+        const textParts = [];
+        this.promptHashes.push(hash({ systemPrompt, prompt, tools: Object.entries(tools).map(([name, t]) => ({ name, inputSchema: t.inputSchema })) }));
+        for (let step = 0; step < Math.min(maxIterations, this.limits.maxIterations); step++) {
+            this.check();
+            if (this.calls >= this.limits.maxCalls)
+                throw new Error("Model call budget exhausted");
+            const definitions = Object.entries(tools).map(([name, t]) => ({ name, description: t.description, inputSchema: t.inputSchema }));
+            if (systemPrompt.length + JSON.stringify(messages).length + JSON.stringify(definitions).length > this.limits.maxInputChars)
+                throw new Error("Model input budget exhausted");
+            this.calls++;
+            const response = await this.wait(this.deps.model.complete({ stage: this.stage, systemPrompt,
+                messages: structuredClone(messages), tools: definitions,
+                maxOutputTokens: Math.min(maxOutputTokens, this.limits.maxOutputTokens), signal: this.signal }));
+            textParts.push(response.text);
+            if (response.usage) {
+                for (const n of Object.values(response.usage))
+                    if (!Number.isFinite(n) || n < 0)
+                        throw new Error("Invalid model usage");
+                this.usage.inputTokens += response.usage.inputTokens;
+                this.usage.outputTokens += response.usage.outputTokens;
+            }
+            else
+                this.usageKnown = false;
+            if (response.finishReason === "length" || response.finishReason === "error")
+                throw new Error(`Model stopped: ${response.finishReason}`);
+            if (JSON.stringify(response).length > this.limits.maxWorkspaceChars)
+                throw new Error("Model response too large");
+            const calls = response.toolCalls ?? [];
+            if (!calls.length) {
+                if (response.finishReason !== "stop")
+                    throw new Error("Missing tool calls");
+                return textParts.join("\n");
+            }
+            if (response.finishReason !== "tool_calls")
+                throw new Error("Unexpected tool calls");
+            if (new Set(calls.map(c => c.id)).size !== calls.length || calls.some(c => !c.id))
+                throw new Error("Invalid tool call IDs");
+            messages.push({ role: "assistant", content: response.text, toolCalls: calls });
+            for (const call of calls) {
+                this.check();
+                if (++this.toolCalls > this.limits.maxToolCalls)
+                    throw new Error("Tool call budget exhausted");
+                let result;
+                const validate = validators.get(call.name);
+                if (!validate || !validate(call.arguments))
+                    result = JSON.stringify({ error: "INVALID_TOOL_ARGUMENTS" });
+                else {
+                    try {
+                        result = await this.wait(tools[call.name].execute(call.arguments));
+                    }
+                    catch (error) {
+                        this.check();
+                        result = JSON.stringify({ error: error instanceof Error ? error.message : "Tool failed" });
+                    }
+                }
+                try {
+                    const outcome = JSON.parse(result);
+                    if (outcome && typeof outcome === "object" && outcome.error)
+                        this.diagnostics.push(`Tool ${call.name} rejected an operation`);
+                }
+                catch { /* Document reads need not contain JSON. */ }
+                const next = { role: "tool", toolCallId: call.id, content: result };
+                if (systemPrompt.length + JSON.stringify([...messages, next]).length + JSON.stringify(definitions).length > this.limits.maxInputChars) {
+                    result = JSON.stringify({ error: "TOOL_RESULT_TOO_LARGE", message: "Result exceeds remaining context budget. Use a smaller read or finish the current task." });
+                    this.diagnostics.push(`Tool ${call.name} result exceeded context budget`);
+                }
+                messages.push({ role: "tool", toolCallId: call.id, content: result });
+            }
+        }
+        throw new Error("Tool iteration budget exhausted");
+    }
+    result(changes, coverage, status = "completed") {
+        return { status, changes, readSet: [...this.readSet.values()], coverage, diagnostics: [...this.diagnostics], provenance: {
+                algorithmVersion: ALGORITHM_VERSION, upstreamCommit: UPSTREAM_COMMIT, profile: "bounded-analysis-v1",
+                evidenceGranularity: this.stage === "l1" ? "record" : "run",
+                runId: this.input.runId, scopeKey: this.input.scopeKey, stage: this.stage, model: this.deps.model.id,
+                inputHash: this.inputHash, promptHashes: this.promptHashes, calls: this.calls,
+                usage: this.usageKnown ? { ...this.usage } : null,
+            } };
+    }
+    failure(error, coverage) {
+        this.diagnostics.push(error instanceof Error ? error.message : "Analysis failed");
+        return this.result([], { ...coverage, processed: [], remaining: [...new Set([...coverage.processed, ...coverage.remaining])] }, this.input.signal?.aborted ? "cancelled" : "failed");
+    }
+}
+export function coverage(ids = []) {
+    return { processed: [], background: [], filtered: [], truncated: [], remaining: ids };
+}

package/dist/runtime/skill-workspace.d.ts

@@ -0,0 +1,70 @@
+import type { Change, Skill, SkillResource } from "../contracts.js";
+import { Run } from "./run.js";
+export declare class SkillCoreError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+type Identity = {
+    user_id: string;
+    team_id: string;
+    agent_id: string;
+    task_id?: string;
+};
+type SkillView = Skill & {
+    skill_id: string;
+    manifest: SkillResource[];
+};
+export declare function safePath(path: string): string;
+export declare class SkillCore {
+    private run;
+    private originals;
+    private current;
+    private history;
+    constructor(run: Run);
+    private load;
+    private save;
+    list(p: Identity & {
+        pagination?: {
+            limit?: number;
+            offset?: number;
+        };
+    }): Promise<{
+        items: SkillView[];
+        total: number;
+    }>;
+    search(p: Identity & {
+        query: string;
+        top_k?: number;
+    }): Promise<{
+        skill: SkillView;
+        score: number;
+    }[]>;
+    get(p: Identity & {
+        skill_id: string;
+        version?: number;
+    }): Promise<SkillView>;
+    create(p: Identity & {
+        name: string;
+        content: string;
+    }): Promise<SkillView>;
+    private writable;
+    update(p: Identity & {
+        skill_id: string;
+        expected_version: number;
+        content: string;
+    }): Promise<SkillView>;
+    patch(p: Identity & {
+        skill_id: string;
+        expected_version: number;
+        old_string: string;
+        new_string: string;
+        replace_all?: boolean;
+    }): Promise<SkillView>;
+    writeFiles(p: Identity & {
+        skill_id: string;
+        expected_version: number;
+        files: SkillResource[];
+    }): Promise<SkillView>;
+    changes(): Change<Skill>[];
+}
+export {};

package/dist/runtime/skill-workspace.js

@@ -0,0 +1,156 @@
+import { parseSkillFile, validateSkillFile } from "../upstream/core/skill/skill-format.js";
+export class SkillCoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function safePath(path) {
+    if (!path || path.startsWith("/") || path.includes("\\") || path.includes("\0") || path.includes(":"))
+        throw new Error("Invalid path");
+    if (path.split("/").some(part => !part || part === "." || part === ".."))
+        throw new Error("Invalid path");
+    return path;
+}
+function view(skill) { return { ...structuredClone(skill), skill_id: skill.id, manifest: structuredClone(skill.resources) }; }
+function boundedLimit(value) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new Error("Invalid Skill query limit");
+    return Math.min(100, value);
+}
+function validated(content, name) {
+    const file = parseSkillFile(content);
+    validateSkillFile(file);
+    if (name && file.frontmatter.name !== name)
+        throw new Error("Skill name mismatch");
+    return file.frontmatter;
+}
+export class SkillCore {
+    run;
+    originals = new Map();
+    current = new Map();
+    history = new Map();
+    constructor(run) {
+        this.run = run;
+    }
+    load(skill) {
+        const checked = this.run.read(skill);
+        if (!this.originals.has(checked.id)) {
+            this.originals.set(checked.id, checked);
+            this.current.set(checked.id, structuredClone(checked));
+        }
+        return this.current.get(checked.id);
+    }
+    save(skill) {
+        this.run.check();
+        // Strip compatibility view fields before returning a public Skill entity.
+        skill = { id: skill.id, version: skill.version, scopeKey: skill.scopeKey,
+            filename: skill.filename, content: skill.content, evidence: skill.evidence,
+            name: skill.name, description: skill.description, resources: skill.resources, writable: skill.writable };
+        const others = [...this.current.values()].filter(s => s.id !== skill.id);
+        if (others.some(s => s.name === skill.name))
+            throw new Error("Skill name already exists");
+        if (JSON.stringify([...others, skill]).length > this.run.limits.maxWorkspaceChars)
+            throw new Error("Skill workspace budget exhausted");
+        this.current.set(skill.id, structuredClone(skill));
+        this.history.set(`${skill.id}:${skill.version}`, structuredClone(skill));
+        return view(skill);
+    }
+    async list(p) {
+        const limit = boundedLimit(p.pagination?.limit ?? 50);
+        const reader = this.run.deps.skills;
+        const page = reader ? await this.run.wait(reader.list(this.run.input.scopeKey, limit, this.run.signal)) : { items: [], total: 0 };
+        page.items.forEach(s => this.load(s));
+        const staged = [...this.current].filter(([id, skill]) => this.originals.get(id)?.version !== skill.version);
+        const items = [...new Map([...staged, ...page.items.map(s => [s.id, this.current.get(s.id)]), ...this.current]).values()];
+        const newCount = [...this.current.keys()].filter(id => !this.originals.has(id)).length;
+        return { items: items.slice(0, limit).map(view), total: Math.max(page.total + newCount, items.length) };
+    }
+    async search(p) {
+        const limit = boundedLimit(p.top_k ?? 10);
+        const hits = this.run.deps.skills ? await this.run.wait(this.run.deps.skills.search(this.run.input.scopeKey, p.query, limit, this.run.signal)) : [];
+        const results = new Map(hits.map(hit => [hit.skill.id, { skill: view(this.load(hit.skill)), score: hit.score }]));
+        const terms = p.query.toLocaleLowerCase().trim().split(/\s+/).filter(Boolean);
+        for (const skill of this.current.values()) {
+            const original = this.originals.get(skill.id);
+            if (original && original.version === skill.version)
+                continue;
+            const content = `${skill.name} ${skill.description} ${skill.content}`.toLocaleLowerCase();
+            if (terms.length && terms.every(term => content.includes(term)))
+                results.set(skill.id, { skill: view(skill), score: 1 });
+            else
+                results.delete(skill.id);
+        }
+        return [...results.values()].sort((a, b) => b.score - a.score).slice(0, limit);
+    }
+    async get(p) {
+        let skill = this.current.get(p.skill_id);
+        if (!skill) {
+            if (!this.run.deps.skills)
+                throw new Error("Skill not found");
+            const loaded = await this.run.wait(this.run.deps.skills.get(this.run.input.scopeKey, p.skill_id, this.run.signal));
+            if (loaded.id !== p.skill_id)
+                this.run.invalidate("Skill reader returned a different ID");
+            skill = this.load(loaded);
+        }
+        if (p.version !== undefined && p.version !== skill.version) {
+            const historical = this.history.get(`${p.skill_id}:${p.version}`) ?? this.originals.get(p.skill_id);
+            if (!historical || historical.version !== p.version)
+                throw new Error("Historical version unavailable");
+            return view(historical);
+        }
+        return view(skill);
+    }
+    async create(p) {
+        const fm = validated(p.content, p.name);
+        const id = this.run.id();
+        if (this.current.has(id))
+            throw new Error("Duplicate generated ID");
+        return this.save({ id, version: 1, scopeKey: this.run.input.scopeKey, filename: "SKILL.md",
+            name: fm.name, description: fm.description, content: p.content, resources: [], evidence: [], writable: true });
+    }
+    async writable(p) {
+        const skill = await this.get(p);
+        if (!skill.writable)
+            throw new SkillCoreError("FORBIDDEN", "Skill is read-only");
+        if (skill.version !== p.expected_version)
+            throw new SkillCoreError("VERSION_CONFLICT", "Skill version changed");
+        return skill;
+    }
+    async update(p) {
+        const skill = await this.writable(p);
+        const fm = validated(p.content, skill.name);
+        return this.save({ ...skill, version: skill.version + 1, content: p.content, description: fm.description });
+    }
+    async patch(p) {
+        const skill = await this.writable(p);
+        if (!p.old_string)
+            throw new Error("Empty patch target");
+        const count = skill.content.split(p.old_string).length - 1;
+        if (count === 0 || (count > 1 && !p.replace_all))
+            throw new Error("Patch target missing or ambiguous");
+        const content = p.replace_all ? skill.content.split(p.old_string).join(p.new_string) : skill.content.replace(p.old_string, () => p.new_string);
+        return this.update({ ...p, content });
+    }
+    async writeFiles(p) {
+        const skill = await this.writable(p);
+        const files = new Map(skill.resources.map(f => [f.path, f]));
+        for (const f of p.files) {
+            safePath(f.path);
+            if (f.encoding === "base64" && Buffer.from(f.content, "base64").toString("base64") !== f.content)
+                throw new Error("Invalid base64");
+            files.set(f.path, structuredClone(f));
+        }
+        return this.save({ ...skill, version: skill.version + 1, resources: [...files.values()] });
+    }
+    changes() {
+        return [...this.current.values()].flatMap(skill => {
+            const old = this.originals.get(skill.id);
+            if (old && JSON.stringify(old) === JSON.stringify(skill))
+                return [];
+            return [{ action: old ? "update" : "create",
+                    before: old ? [{ id: old.id, version: old.version }] : [], after: structuredClone(skill) }];
+        });
+    }
+}

package/dist/runtime/skills.d.ts

@@ -0,0 +1,9 @@
+import type { Dependencies, ExtractionResult, Message, RunInput, Skill } from "../contracts.js";
+export interface SkillInput extends Omit<RunInput, "strategy" | "mode"> {
+    messages: Message[];
+    prefixSkillsLimit?: number;
+    headChars?: number;
+    tailChars?: number;
+    reason?: string;
+}
+export declare function extractSkills(deps: Dependencies, input: SkillInput): Promise<ExtractionResult<Skill>>;