ai-runtime-engine 1.1.0

package/dist/skills/discovery.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Local skill discovery. Finds skills the user keeps in their workspace — declarative manifests
+ * (`*.skill.yaml`/`*.skill.json`) and JS-module skills (`*.skill.js`/`*.skill.mjs`, exporting
+ * `skills: Skill[]`). Two modes:
+ *   • CONSENTED sources — the conventional `.ai-runtime/skills/` dir and any `skills.paths` in config —
+ *     are discovered AND loadable (the user put them there / named them).
+ *   • A repo-wide scan (`scanRepoForSkills`) only REPORTS candidates found elsewhere; nothing is loaded
+ *     until the user explicitly enables it. Loading a module runs the user's code, so it is never
+ *     implicit.
+ * Everything is path-jailed to the workspace root — discovery never reads or imports outside it.
+ */
+import type { Skill } from './skill.js';
+export type SkillSourceKind = 'manifest' | 'module';
+export interface SkillSource {
+    /** Absolute path, guaranteed inside the workspace root. */
+    path: string;
+    /** Path relative to the workspace root, for display. */
+    relative: string;
+    kind: SkillSourceKind;
+    /** True when the source is consented (conventional dir or a configured path) → safe to load. */
+    consented: boolean;
+}
+export interface LoadedSource {
+    source: SkillSource;
+    skills: Skill[];
+    status: 'loaded' | 'error';
+    detail?: string;
+}
+/**
+ * Discover CONSENTED skill sources: the conventional `<root>/.ai-runtime/skills/` dir plus any configured
+ * `paths` (each jailed to the root). These are safe to load. Deterministic order.
+ */
+export declare function discoverSkills(opts: {
+    root: string;
+    paths?: string[];
+}): SkillSource[];
+/**
+ * Scan the whole workspace for skill-looking files and REPORT them (never loaded here). Skips vendored /
+ * build dirs and the already-consented `.ai-runtime/skills/`. Depth-capped and jailed.
+ */
+export declare function scanRepoForSkills(opts: {
+    root: string;
+    maxDepth?: number;
+}): SkillSource[];
+/**
+ * Load a source into concrete Skills. Manifests are parsed as data; modules are dynamically imported
+ * (executing the file) and must export `skills: Skill[]` or a default Skill/Skill[]. Never throws — a
+ * bad source becomes `status: 'error'`.
+ */
+export declare function loadSkillSource(source: SkillSource): Promise<LoadedSource>;
+/**
+ * Load a skill pack by module specifier — an installed npm package (`ai-runtime-example-skills`) or any
+ * import()-able path. Unlike local file discovery, a package is NOT workspace-jailed: it is a declared
+ * dependency resolved from node_modules, trusted like any other npm dependency. Never throws — a bad
+ * package becomes `status: 'error'`.
+ */
+export declare function loadSkillPackage(specifier: string): Promise<LoadedSource>;
+/** Structural check that an imported value implements the Skill contract. */
+export declare function isSkill(v: unknown): v is Skill;
+/** True when a path is absolute and inside the root — a guard for callers resolving user paths. */
+export declare function withinRoot(root: string, p: string): boolean;

package/dist/skills/discovery.js

@@ -0,0 +1,211 @@
+/**
+ * Local skill discovery. Finds skills the user keeps in their workspace — declarative manifests
+ * (`*.skill.yaml`/`*.skill.json`) and JS-module skills (`*.skill.js`/`*.skill.mjs`, exporting
+ * `skills: Skill[]`). Two modes:
+ *   • CONSENTED sources — the conventional `.ai-runtime/skills/` dir and any `skills.paths` in config —
+ *     are discovered AND loadable (the user put them there / named them).
+ *   • A repo-wide scan (`scanRepoForSkills`) only REPORTS candidates found elsewhere; nothing is loaded
+ *     until the user explicitly enables it. Loading a module runs the user's code, so it is never
+ *     implicit.
+ * Everything is path-jailed to the workspace root — discovery never reads or imports outside it.
+ */
+import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, extname, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import { resolveInJail, JailError } from '../tools/jail.js';
+import { parseManifest, manifestToSkill } from './manifest.js';
+const MANIFEST_EXT = new Set(['.yaml', '.yml', '.json']);
+const MODULE_EXT = new Set(['.js', '.mjs']);
+const SKILL_FILE = /\.skill\.(ya?ml|json|m?js)$/i;
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.cache']);
+function kindOf(file) {
+    const ext = extname(file).toLowerCase();
+    if (MANIFEST_EXT.has(ext))
+        return 'manifest';
+    if (MODULE_EXT.has(ext))
+        return 'module';
+    return undefined;
+}
+/**
+ * List `*.skill.*` files directly under a directory (one level; sorted). Jail-checked: a directory that
+ * resolves (via a symlink) outside the workspace is never read — so its listing can't leak or be loaded.
+ */
+function skillFilesIn(root, dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        resolveInJail(root, relative(root, dir)); // a symlinked-out dir throws → don't even read it
+    }
+    catch (err) {
+        if (err instanceof JailError)
+            return [];
+        throw err;
+    }
+    if (!statSync(dir).isDirectory())
+        return [];
+    return readdirSync(dir)
+        .filter((f) => SKILL_FILE.test(f))
+        .sort()
+        .map((f) => join(dir, f));
+}
+/**
+ * Build a SkillSource for a candidate file, jail-checking its REAL path. A file that resolves (via a
+ * symlink) outside the workspace is dropped — this is what makes `SkillSource.path` genuinely in-jail, so
+ * loadSkillSource can import it safely (loadSkillSource has no root and cannot re-verify).
+ */
+function toSource(root, absPath, consented) {
+    const kind = kindOf(absPath);
+    if (!kind)
+        return undefined;
+    try {
+        resolveInJail(root, relative(root, absPath)); // follows the file's final symlink; throws if it escapes root
+    }
+    catch (err) {
+        if (err instanceof JailError)
+            return undefined;
+        throw err;
+    }
+    return { path: absPath, relative: relative(root, absPath) || absPath, kind, consented };
+}
+/**
+ * Discover CONSENTED skill sources: the conventional `<root>/.ai-runtime/skills/` dir plus any configured
+ * `paths` (each jailed to the root). These are safe to load. Deterministic order.
+ */
+export function discoverSkills(opts) {
+    const out = [];
+    const seen = new Set();
+    const add = (absPath) => {
+        const src = toSource(opts.root, absPath, true);
+        if (src && !seen.has(src.path)) {
+            seen.add(src.path);
+            out.push(src);
+        }
+    };
+    for (const f of skillFilesIn(opts.root, join(opts.root, '.ai-runtime', 'skills')))
+        add(f);
+    for (const p of opts.paths ?? []) {
+        let resolved;
+        try {
+            resolved = resolveInJail(opts.root, p);
+        }
+        catch (err) {
+            if (err instanceof JailError)
+                continue; // a configured path outside the workspace is ignored
+            throw err;
+        }
+        if (!existsSync(resolved))
+            continue;
+        if (statSync(resolved).isDirectory())
+            for (const f of skillFilesIn(opts.root, resolved))
+                add(f);
+        else
+            add(resolved);
+    }
+    return out;
+}
+/**
+ * Scan the whole workspace for skill-looking files and REPORT them (never loaded here). Skips vendored /
+ * build dirs and the already-consented `.ai-runtime/skills/`. Depth-capped and jailed.
+ */
+export function scanRepoForSkills(opts) {
+    const maxDepth = opts.maxDepth ?? 4;
+    const conventional = join(opts.root, '.ai-runtime', 'skills');
+    const out = [];
+    const walk = (dir, depth) => {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries.sort()) {
+            const abs = join(dir, name);
+            let st;
+            // lstat (not stat) so a symlinked directory is NOT traversed — the scan never reads outside the jail.
+            try {
+                st = lstatSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (SKIP_DIRS.has(name) || abs === conventional)
+                    continue;
+                walk(abs, depth + 1);
+            }
+            else if (st.isFile() && SKILL_FILE.test(name)) {
+                const src = toSource(opts.root, abs, false); // toSource jail-checks (a symlinked-out file is dropped)
+                if (src)
+                    out.push(src);
+            }
+        }
+    };
+    walk(opts.root, 0);
+    return out;
+}
+/**
+ * Load a source into concrete Skills. Manifests are parsed as data; modules are dynamically imported
+ * (executing the file) and must export `skills: Skill[]` or a default Skill/Skill[]. Never throws — a
+ * bad source becomes `status: 'error'`.
+ */
+export async function loadSkillSource(source) {
+    try {
+        if (source.kind === 'manifest') {
+            const text = readFileSync(source.path, 'utf8');
+            const raw = source.path.endsWith('.json') ? JSON.parse(text) : parseYaml(text);
+            const { manifest, error } = parseManifest(raw);
+            if (!manifest)
+                return { source, skills: [], status: 'error', detail: error };
+            return { source, skills: [manifestToSkill(manifest, source.relative)], status: 'loaded' };
+        }
+        // module — importing runs the file's top-level code (the user's own repo code).
+        const mod = (await import(pathToFileURL(source.path).href));
+        const raw = mod.skills ?? mod.default;
+        const list = Array.isArray(raw) ? raw : raw ? [raw] : [];
+        const skills = list.filter(isSkill);
+        if (skills.length === 0)
+            return { source, skills: [], status: 'error', detail: 'module exported no valid skills (need `export const skills: Skill[]`)' };
+        return { source, skills, status: 'loaded' };
+    }
+    catch (err) {
+        return { source, skills: [], status: 'error', detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Load a skill pack by module specifier — an installed npm package (`ai-runtime-example-skills`) or any
+ * import()-able path. Unlike local file discovery, a package is NOT workspace-jailed: it is a declared
+ * dependency resolved from node_modules, trusted like any other npm dependency. Never throws — a bad
+ * package becomes `status: 'error'`.
+ */
+export async function loadSkillPackage(specifier) {
+    const source = { path: specifier, relative: specifier, kind: 'module', consented: true };
+    try {
+        const mod = (await import(specifier));
+        const raw = mod.skills ?? mod.default;
+        const list = Array.isArray(raw) ? raw : raw ? [raw] : [];
+        const skills = list.filter(isSkill);
+        if (skills.length === 0)
+            return { source, skills: [], status: 'error', detail: `package '${specifier}' exported no valid skills (need \`export const skills: Skill[]\`)` };
+        return { source, skills, status: 'loaded' };
+    }
+    catch (err) {
+        return { source, skills: [], status: 'error', detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Structural check that an imported value implements the Skill contract. */
+export function isSkill(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const s = v;
+    return typeof s.id === 'string' && typeof s.version === 'string' && typeof s.plan === 'function' && typeof s.execute === 'function' && typeof s.validate === 'function';
+}
+/** True when a path is absolute and inside the root — a guard for callers resolving user paths. */
+export function withinRoot(root, p) {
+    const abs = isAbsolute(p) ? p : join(root, p);
+    const rel = relative(root, abs);
+    return !rel.startsWith('..') && !isAbsolute(rel);
+}

package/dist/skills/manifest.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Declarative skill manifests (`*.skill.yaml` / `*.skill.json`). A manifest describes a skill as an
+ * ordered sequence of steps over REGISTERED tools — pure data, no arbitrary code, so it is safe to load
+ * from a repo. `manifestToSkill` compiles one into a real Skill whose execute() runs the steps through
+ * the permission-gated tool layer and whose validate() confirms every step produced evidence (a tool
+ * `ok`). Anything richer than composing tools belongs in a JS-module skill instead.
+ */
+import type { Skill } from './skill.js';
+export interface ManifestStep {
+    /** A registered tool id (filesystem, shell, git, or a user-registered tool). */
+    tool: string;
+    description?: string;
+    /** Static input for the tool. When omitted, the skill's own input is passed through. */
+    input?: unknown;
+}
+export interface SkillManifest {
+    id: string;
+    version: string;
+    name: string;
+    description: string;
+    runtimeCompatibility?: string;
+    steps: ManifestStep[];
+}
+/** Validate an arbitrary parsed object as a SkillManifest. Returns the manifest or a reason it is invalid. */
+export declare function parseManifest(raw: unknown): {
+    manifest?: SkillManifest;
+    error?: string;
+};
+/** Compile a manifest into a Skill. execute() runs each tool step in order; validate() checks evidence. */
+export declare function manifestToSkill(m: SkillManifest, sourcePath: string): Skill;

package/dist/skills/manifest.js

@@ -0,0 +1,75 @@
+/**
+ * Declarative skill manifests (`*.skill.yaml` / `*.skill.json`). A manifest describes a skill as an
+ * ordered sequence of steps over REGISTERED tools — pure data, no arbitrary code, so it is safe to load
+ * from a repo. `manifestToSkill` compiles one into a real Skill whose execute() runs the steps through
+ * the permission-gated tool layer and whose validate() confirms every step produced evidence (a tool
+ * `ok`). Anything richer than composing tools belongs in a JS-module skill instead.
+ */
+/** Validate an arbitrary parsed object as a SkillManifest. Returns the manifest or a reason it is invalid. */
+export function parseManifest(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return { error: 'manifest must be a mapping' };
+    const o = raw;
+    for (const key of ['id', 'version', 'name', 'description']) {
+        if (typeof o[key] !== 'string' || !o[key].trim())
+            return { error: `manifest.${key} must be a non-empty string` };
+    }
+    if (!Array.isArray(o.steps) || o.steps.length === 0)
+        return { error: 'manifest.steps must be a non-empty array' };
+    const steps = [];
+    for (const [i, s] of o.steps.entries()) {
+        if (!s || typeof s !== 'object' || Array.isArray(s))
+            return { error: `manifest.steps[${i}] must be a mapping` };
+        const step = s;
+        if (typeof step.tool !== 'string' || !step.tool.trim())
+            return { error: `manifest.steps[${i}].tool must be a tool id` };
+        steps.push({ tool: step.tool, ...(typeof step.description === 'string' ? { description: step.description } : {}), ...('input' in step ? { input: step.input } : {}) });
+    }
+    return {
+        manifest: {
+            id: o.id,
+            version: o.version,
+            name: o.name,
+            description: o.description,
+            ...(typeof o.runtimeCompatibility === 'string' ? { runtimeCompatibility: o.runtimeCompatibility } : {}),
+            steps,
+        },
+    };
+}
+/** Compile a manifest into a Skill. execute() runs each tool step in order; validate() checks evidence. */
+export function manifestToSkill(m, sourcePath) {
+    const tools = [...new Set(m.steps.map((s) => s.tool))];
+    return {
+        id: m.id,
+        version: m.version,
+        name: m.name,
+        description: m.description,
+        ...(m.runtimeCompatibility ? { runtimeCompatibility: m.runtimeCompatibility } : {}),
+        tools,
+        async plan() {
+            return { steps: m.steps.map((s) => ({ description: s.description ?? `run ${s.tool}`, tool: s.tool })) };
+        },
+        async execute(ctx) {
+            const outcomes = [];
+            let lastOutput = '';
+            for (const step of m.steps) {
+                if (ctx.signal?.aborted)
+                    return { ok: false, output: lastOutput, data: { steps: outcomes, source: sourcePath }, error: { message: 'aborted' } };
+                const input = step.input !== undefined ? step.input : ctx.input;
+                const res = await ctx.callTool(step.tool, input);
+                outcomes.push({ tool: step.tool, ok: res.ok, ...(res.ok ? {} : { error: res.error?.message ?? 'failed' }) });
+                if (res.output !== undefined)
+                    lastOutput = String(res.output);
+                if (!res.ok)
+                    return { ok: false, output: lastOutput, data: { steps: outcomes, source: sourcePath }, error: { message: `step '${step.tool}' failed: ${res.error?.message ?? 'unknown'}` } };
+            }
+            return { ok: true, output: lastOutput, data: { steps: outcomes, source: sourcePath } };
+        },
+        async validate(result) {
+            const steps = result.data?.steps ?? [];
+            const checks = steps.map((s) => ({ name: `step:${s.tool}`, ok: s.ok, ...(s.ok ? {} : { why: s.error ?? 'failed' }) }));
+            // Evidence-based: the skill succeeded only if it ran at least one step and every step's tool returned ok.
+            return { ok: result.ok && steps.length > 0 && steps.every((s) => s.ok), checks };
+        },
+    };
+}

package/dist/skills/registry.d.ts

@@ -0,0 +1,15 @@
+/** A registry of skills, keyed by id, with a simple capability/tool matcher. */
+import type { Skill } from './skill.js';
+export interface MatchCriteria {
+    /** Tool ids currently registered — a skill matches only if all its required tools are present. */
+    tools?: string[];
+}
+export declare class SkillRegistry {
+    private readonly skills;
+    register(skill: Skill): this;
+    get(id: string): Skill | undefined;
+    has(id: string): boolean;
+    list(): Skill[];
+    /** Skills whose required tools are all available (capability-vs-model matching arrives with routing). */
+    match(criteria?: MatchCriteria): Skill[];
+}

package/dist/skills/registry.js

@@ -0,0 +1,22 @@
+/** A registry of skills, keyed by id, with a simple capability/tool matcher. */
+export class SkillRegistry {
+    skills = new Map();
+    register(skill) {
+        this.skills.set(skill.id, skill);
+        return this;
+    }
+    get(id) {
+        return this.skills.get(id);
+    }
+    has(id) {
+        return this.skills.has(id);
+    }
+    list() {
+        return [...this.skills.values()];
+    }
+    /** Skills whose required tools are all available (capability-vs-model matching arrives with routing). */
+    match(criteria = {}) {
+        const tools = new Set(criteria.tools ?? []);
+        return this.list().filter((s) => (s.tools ?? []).every((t) => tools.has(t)));
+    }
+}

package/dist/skills/skill.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The Skill contract. A skill is a reusable capability (NOT a provider, NOT a tool). It plans a small
+ * sequence, executes it (composing tools + AI.run through the SkillContext), and validates the result
+ * against success conditions — never trusting a model's "I did it" claim. Skills are versioned so
+ * learning can reference an exact version and a runtime can check compatibility. QA-neutral by design;
+ * QA/dev skills live in packs, never in the core.
+ */
+import type { AI } from '../plugin/ai.js';
+import type { CapabilityRequirement } from '../types.js';
+import type { ArtifactRef } from '../runtime/types.js';
+import type { PermissionPolicy } from '../runtime/policy.js';
+import type { ToolResult } from '../tools/tool.js';
+export interface SkillContext {
+    input: unknown;
+    /** The inner router facade for model work. */
+    ai: AI;
+    /** Invoke a registered tool, pre-bound to this run's resolved permissions/approval/workspace. */
+    callTool(id: string, input: unknown): Promise<ToolResult>;
+    signal?: AbortSignal;
+}
+export interface SkillPlanStep {
+    description: string;
+    tool?: string;
+}
+export interface SkillPlan {
+    steps: SkillPlanStep[];
+}
+export interface SkillResult {
+    ok: boolean;
+    output?: string;
+    data?: unknown;
+    artifacts?: ArtifactRef[];
+    error?: {
+        message: string;
+    };
+}
+export interface SkillValidation {
+    ok: boolean;
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        why?: string;
+    }>;
+}
+export interface Skill {
+    id: string;
+    /** Semver of the skill implementation (learning references this exact version). */
+    version: string;
+    /** Semver range of runtime versions this skill supports (advisory in Phase 5). */
+    runtimeCompatibility?: string;
+    name: string;
+    description: string;
+    /** Model capabilities the skill needs from whatever model AI.run selects. */
+    capabilities?: CapabilityRequirement[];
+    /** Tool ids the skill uses (matched against the registered tools). */
+    tools?: string[];
+    /** Other skill ids this skill depends on. */
+    dependencies?: string[];
+    /** Permissions the skill needs (advisory; the run's ExecutionPolicy is authoritative). */
+    permissions?: PermissionPolicy;
+    plan(ctx: SkillContext): Promise<SkillPlan>;
+    execute(ctx: SkillContext, plan: SkillPlan): Promise<SkillResult>;
+    validate(result: SkillResult, ctx: SkillContext): Promise<SkillValidation>;
+}

package/dist/skills/skill.js

@@ -0,0 +1,8 @@
+/**
+ * The Skill contract. A skill is a reusable capability (NOT a provider, NOT a tool). It plans a small
+ * sequence, executes it (composing tools + AI.run through the SkillContext), and validates the result
+ * against success conditions — never trusting a model's "I did it" claim. Skills are versioned so
+ * learning can reference an exact version and a runtime can check compatibility. QA-neutral by design;
+ * QA/dev skills live in packs, never in the core.
+ */
+export {};

package/dist/store/area.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A single managed directory in the runtime store. JSON records are written atomically (tmp + rename)
+ * with a sha256 integrity wrapper so corruption is detectable; append logs are JSONL. `NullArea` is the
+ * no-op used in stateless mode. Ids are validated to prevent path traversal.
+ */
+export interface IntegrityIssue {
+    file: string;
+    problem: 'unreadable' | 'checksum-mismatch' | 'invalid-json';
+    detail?: string;
+}
+export interface Area {
+    readonly enabled: boolean;
+    /** Strict read: throws on corruption (use for an explicit single-record read). */
+    readJson<T>(id: string): T | undefined;
+    /** Fail-soft read: returns undefined on a missing OR corrupt record (use in bulk iteration). */
+    tryReadJson<T>(id: string): T | undefined;
+    writeJson(id: string, data: unknown): void;
+    remove(id: string): void;
+    listIds(): string[];
+    appendLine(id: string, obj: unknown): void;
+    readLines(id: string): unknown[];
+    check(): IntegrityIssue[];
+}
+export declare class FileArea implements Area {
+    private readonly dir;
+    readonly enabled = true;
+    private ensured;
+    private counter;
+    constructor(dir: string);
+    private ensure;
+    private jsonPath;
+    private logPath;
+    private atomicWrite;
+    readJson<T>(id: string): T | undefined;
+    tryReadJson<T>(id: string): T | undefined;
+    writeJson(id: string, data: unknown): void;
+    remove(id: string): void;
+    listIds(): string[];
+    appendLine(id: string, obj: unknown): void;
+    readLines(id: string): unknown[];
+    check(): IntegrityIssue[];
+}
+/** No-op area used in stateless mode. */
+export declare class NullArea implements Area {
+    readonly enabled = false;
+    readJson<T>(): T | undefined;
+    tryReadJson<T>(): T | undefined;
+    writeJson(): void;
+    remove(): void;
+    listIds(): string[];
+    appendLine(): void;
+    readLines(): unknown[];
+    check(): IntegrityIssue[];
+}