ai-runtime-engine 1.1.0

package/dist/store/area.js

@@ -0,0 +1,164 @@
+/**
+ * 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.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+const STORE_VERSION = 1;
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+/** Matches an orphaned atomic-write temp file: `<id>.json.tmp-<pid>-<n>` / `<id>.jsonl.tmp-…`. */
+const TEMP_RE = /\.(?:json|jsonl)\.tmp-/;
+function assertId(id) {
+    if (!ID_RE.test(id))
+        throw new Error(`invalid store id: ${JSON.stringify(id)}`);
+}
+function checksum(data) {
+    return createHash('sha256').update(JSON.stringify(data)).digest('hex');
+}
+export class FileArea {
+    dir;
+    enabled = true;
+    ensured = false;
+    counter = 0;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    ensure() {
+        if (!this.ensured) {
+            mkdirSync(this.dir, { recursive: true });
+            this.ensured = true;
+        }
+    }
+    jsonPath(id) {
+        return join(this.dir, `${id}.json`);
+    }
+    logPath(id) {
+        return join(this.dir, `${id}.jsonl`);
+    }
+    atomicWrite(path, contents) {
+        this.ensure();
+        this.counter += 1;
+        const tmp = `${path}.tmp-${process.pid}-${this.counter}`;
+        writeFileSync(tmp, contents);
+        renameSync(tmp, path);
+    }
+    readJson(id) {
+        assertId(id);
+        const path = this.jsonPath(id);
+        if (!existsSync(path))
+            return undefined;
+        const wrapper = JSON.parse(readFileSync(path, 'utf8'));
+        if (wrapper.checksum !== checksum(wrapper.data))
+            throw new Error(`integrity check failed for ${path}`);
+        return wrapper.data;
+    }
+    tryReadJson(id) {
+        try {
+            return this.readJson(id);
+        }
+        catch {
+            return undefined; // a corrupt record must not brick bulk listing/search
+        }
+    }
+    writeJson(id, data) {
+        assertId(id);
+        const wrapper = { v: STORE_VERSION, checksum: checksum(data), data };
+        this.atomicWrite(this.jsonPath(id), JSON.stringify(wrapper));
+    }
+    remove(id) {
+        assertId(id);
+        for (const p of [this.jsonPath(id), this.logPath(id)])
+            if (existsSync(p))
+                rmSync(p);
+    }
+    listIds() {
+        if (!existsSync(this.dir))
+            return [];
+        // `endsWith('.json')` already excludes temp files (they end `.json.tmp-<n>`), so a valid id that
+        // merely contains ".tmp-" is not wrongly hidden.
+        return readdirSync(this.dir)
+            .filter((f) => f.endsWith('.json'))
+            .map((f) => f.slice(0, -'.json'.length));
+    }
+    appendLine(id, obj) {
+        assertId(id);
+        this.ensure();
+        appendFileSync(this.logPath(id), JSON.stringify(obj) + '\n');
+    }
+    readLines(id) {
+        assertId(id);
+        const path = this.logPath(id);
+        if (!existsSync(path))
+            return [];
+        const out = [];
+        for (const line of readFileSync(path, 'utf8').split('\n')) {
+            if (!line)
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                /* skip a corrupt line rather than failing the whole log (surfaced by check()) */
+            }
+        }
+        return out;
+    }
+    check() {
+        if (!existsSync(this.dir))
+            return [];
+        const issues = [];
+        for (const f of readdirSync(this.dir)) {
+            const path = join(this.dir, f);
+            if (TEMP_RE.test(f)) {
+                issues.push({ file: path, problem: 'unreadable', detail: 'orphaned temp file' });
+                continue;
+            }
+            if (f.endsWith('.json')) {
+                try {
+                    const wrapper = JSON.parse(readFileSync(path, 'utf8'));
+                    if (wrapper.checksum !== checksum(wrapper.data))
+                        issues.push({ file: path, problem: 'checksum-mismatch' });
+                }
+                catch (err) {
+                    issues.push({ file: path, problem: 'invalid-json', detail: err instanceof Error ? err.message : String(err) });
+                }
+            }
+            else if (f.endsWith('.jsonl')) {
+                const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+                lines.forEach((line, i) => {
+                    try {
+                        JSON.parse(line);
+                    }
+                    catch {
+                        issues.push({ file: path, problem: 'invalid-json', detail: `line ${i + 1}` });
+                    }
+                });
+            }
+        }
+        return issues;
+    }
+}
+/** No-op area used in stateless mode. */
+export class NullArea {
+    enabled = false;
+    readJson() {
+        return undefined;
+    }
+    tryReadJson() {
+        return undefined;
+    }
+    writeJson() { }
+    remove() { }
+    listIds() {
+        return [];
+    }
+    appendLine() { }
+    readLines() {
+        return [];
+    }
+    check() {
+        return [];
+    }
+}

package/dist/store/paths.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Local runtime-store path + identity resolution. All persistent state lives under `~/.ai-runtime/`
+ * (override with AI_RUNTIME_HOME), NEVER inside the user's repository. Project identity is derived from
+ * the absolute workspace root, so sibling packages in a monorepo get distinct project stores; a shared
+ * `repository` identity (the git repo root) backs repository-scoped memory across those packages.
+ */
+/** Where a memory record physically lives. */
+export type StoreScope = 'user' | 'project' | 'repository';
+export declare function resolveHome(env?: NodeJS.ProcessEnv): string;
+/** Walk up from a directory to find the git repo root (dir containing `.git`). Undefined if none. */
+export declare function findRepoRoot(start: string): string | undefined;
+/** Stable, human-readable project id for the workspace root: `<slug>-<hash>`. */
+export declare function projectId(root: string, name?: string): string;
+/** Stable id for the enclosing git repository (falls back to the project id when not a repo). */
+export declare function repositoryId(root: string, name?: string): string;

package/dist/store/paths.js

@@ -0,0 +1,48 @@
+/**
+ * Local runtime-store path + identity resolution. All persistent state lives under `~/.ai-runtime/`
+ * (override with AI_RUNTIME_HOME), NEVER inside the user's repository. Project identity is derived from
+ * the absolute workspace root, so sibling packages in a monorepo get distinct project stores; a shared
+ * `repository` identity (the git repo root) backs repository-scoped memory across those packages.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, basename } from 'node:path';
+export function resolveHome(env = process.env) {
+    const override = env.AI_RUNTIME_HOME;
+    return override && override.trim() ? resolve(override) : join(homedir(), '.ai-runtime');
+}
+function slug(s) {
+    return (s || 'project')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 32) || 'project';
+}
+function hash8(s) {
+    return createHash('sha256').update(s).digest('hex').slice(0, 12);
+}
+/** Walk up from a directory to find the git repo root (dir containing `.git`). Undefined if none. */
+export function findRepoRoot(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, '.git')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Stable, human-readable project id for the workspace root: `<slug>-<hash>`. */
+export function projectId(root, name) {
+    const abs = resolve(root);
+    return `${slug(name ?? basename(abs))}-${hash8(abs)}`;
+}
+/** Stable id for the enclosing git repository (falls back to the project id when not a repo). */
+export function repositoryId(root, name) {
+    const repo = findRepoRoot(root);
+    if (!repo)
+        return projectId(root, name);
+    return `${slug(basename(repo))}-${hash8(repo)}`;
+}

package/dist/store/store.d.ts

@@ -0,0 +1,59 @@
+/**
+ * RuntimeStore — the factory that maps the local home dir + project/repository identity to areas
+ * (memory per scope, conversations, indexes, cache, …). Stamps a store version, offers an advisory
+ * per-project lock, and an aggregate integrity check. In stateless mode every area is a NullArea.
+ */
+import type { Clock } from '../util/clock.js';
+import type { Area, IntegrityIssue } from './area.js';
+import type { StoreScope } from './paths.js';
+export declare const STORE_VERSION = 1;
+export interface RuntimeStoreOptions {
+    workspaceRoot: string;
+    workspaceName?: string;
+    env?: NodeJS.ProcessEnv;
+    clock?: Clock;
+    /** When false, a stateless (in-memory / no-op) store is returned. */
+    enabled?: boolean;
+}
+export interface StorePaths {
+    home: string;
+    project: string;
+    repository: string;
+    user: string;
+}
+export declare class RuntimeStore {
+    readonly enabled: boolean;
+    readonly projectId: string;
+    readonly repositoryId: string;
+    private readonly clock;
+    private readonly home;
+    private readonly projectDir;
+    private readonly repoDir;
+    private readonly userDir;
+    private readonly areas;
+    private metaStamped;
+    constructor(options: RuntimeStoreOptions);
+    paths(): StorePaths;
+    private area;
+    /** Memory area for a physical scope. */
+    memory(scope: StoreScope): Area;
+    conversations(): Area;
+    indexes(): Area;
+    cache(): Area;
+    executions(): Area;
+    artifacts(): Area;
+    /** Learning is store-wide (provider/skill/workflow/plan outcomes apply across projects). */
+    learning(): Area;
+    preferences(): Area;
+    /** Write the version stamp once (creates the project dir). No-op when stateless. */
+    stampMeta(): void;
+    /** The stored version, or undefined when absent — a migration hook seam for future versions. */
+    storedVersion(): number | undefined;
+    /**
+     * Advisory per-project lock. Best-effort: acquires an exclusive lock file, steals a stale one, and
+     * otherwise proceeds anyway (advisory). Hard mutual exclusion for executions is a Phase 7 lease.
+     */
+    withLock<T>(fn: () => T, staleMs?: number): T;
+    /** Aggregate integrity check across the project areas. */
+    check(): IntegrityIssue[];
+}

package/dist/store/store.js

@@ -0,0 +1,140 @@
+/**
+ * RuntimeStore — the factory that maps the local home dir + project/repository identity to areas
+ * (memory per scope, conversations, indexes, cache, …). Stamps a store version, offers an advisory
+ * per-project lock, and an aggregate integrity check. In stateless mode every area is a NullArea.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { systemClock } from '../util/clock.js';
+import { FileArea, NullArea } from './area.js';
+import { projectId as computeProjectId, repositoryId as computeRepositoryId, resolveHome } from './paths.js';
+export const STORE_VERSION = 1;
+export class RuntimeStore {
+    enabled;
+    projectId;
+    repositoryId;
+    clock;
+    home;
+    projectDir;
+    repoDir;
+    userDir;
+    areas = new Map();
+    metaStamped = false;
+    constructor(options) {
+        const env = options.env ?? process.env;
+        this.enabled = options.enabled !== false;
+        this.clock = options.clock ?? systemClock;
+        this.home = resolveHome(env);
+        this.projectId = computeProjectId(options.workspaceRoot, options.workspaceName);
+        this.repositoryId = computeRepositoryId(options.workspaceRoot, options.workspaceName);
+        this.projectDir = join(this.home, 'projects', this.projectId);
+        this.repoDir = join(this.home, 'repos', this.repositoryId);
+        this.userDir = join(this.home, 'user');
+    }
+    paths() {
+        return { home: this.home, project: this.projectDir, repository: this.repoDir, user: this.userDir };
+    }
+    area(dir) {
+        if (!this.enabled)
+            return new NullArea();
+        let a = this.areas.get(dir);
+        if (!a) {
+            a = new FileArea(dir);
+            this.areas.set(dir, a);
+        }
+        return a;
+    }
+    /** Memory area for a physical scope. */
+    memory(scope) {
+        if (scope === 'user')
+            return this.area(join(this.userDir, 'memory'));
+        if (scope === 'repository')
+            return this.area(join(this.repoDir, 'memory'));
+        return this.area(join(this.projectDir, 'memory'));
+    }
+    conversations() {
+        return this.area(join(this.projectDir, 'conversations'));
+    }
+    indexes() {
+        return this.area(join(this.projectDir, 'indexes'));
+    }
+    cache() {
+        return this.area(join(this.projectDir, 'cache'));
+    }
+    executions() {
+        return this.area(join(this.projectDir, 'executions'));
+    }
+    artifacts() {
+        return this.area(join(this.projectDir, 'artifacts'));
+    }
+    /** Learning is store-wide (provider/skill/workflow/plan outcomes apply across projects). */
+    learning() {
+        return this.area(join(this.home, 'learning'));
+    }
+    preferences() {
+        return this.area(join(this.userDir, 'preferences'));
+    }
+    /** Write the version stamp once (creates the project dir). No-op when stateless. */
+    stampMeta() {
+        if (!this.enabled || this.metaStamped)
+            return;
+        mkdirSync(this.projectDir, { recursive: true });
+        const metaPath = join(this.projectDir, 'meta.json');
+        if (!existsSync(metaPath))
+            writeFileSync(metaPath, JSON.stringify({ version: STORE_VERSION, projectId: this.projectId }));
+        this.metaStamped = true;
+    }
+    /** The stored version, or undefined when absent — a migration hook seam for future versions. */
+    storedVersion() {
+        const metaPath = join(this.projectDir, 'meta.json');
+        if (!existsSync(metaPath))
+            return undefined;
+        try {
+            return JSON.parse(readFileSync(metaPath, 'utf8')).version;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Advisory per-project lock. Best-effort: acquires an exclusive lock file, steals a stale one, and
+     * otherwise proceeds anyway (advisory). Hard mutual exclusion for executions is a Phase 7 lease.
+     */
+    withLock(fn, staleMs = 30_000) {
+        if (!this.enabled)
+            return fn();
+        mkdirSync(this.projectDir, { recursive: true });
+        const lockPath = join(this.projectDir, '.lock');
+        let held = false;
+        try {
+            writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+            held = true;
+        }
+        catch {
+            // Held already — steal if stale.
+            try {
+                const age = this.clock.now() - statSync(lockPath).mtimeMs;
+                if (age > staleMs) {
+                    writeFileSync(lockPath, String(process.pid));
+                    held = true;
+                }
+            }
+            catch {
+                /* proceed advisory */
+            }
+        }
+        try {
+            return fn();
+        }
+        finally {
+            if (held && existsSync(lockPath))
+                rmSync(lockPath);
+        }
+    }
+    /** Aggregate integrity check across the project areas. */
+    check() {
+        if (!this.enabled)
+            return [];
+        return [...this.memory('project').check(), ...this.memory('user').check(), ...this.memory('repository').check(), ...this.conversations().check(), ...this.indexes().check()];
+    }
+}

package/dist/telemetry/sinks/file.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Append-only JSONL telemetry sink. Metadata only, redacted before write. A telemetry write must
+ * NEVER fail a run, so all IO is wrapped and swallowed. The path should be outside the repo or
+ * gitignored (`init` adds `.ai-runtime/`).
+ */
+import type { TelemetrySink } from '../telemetry.js';
+import type { TelemetryEvent } from '../../types.js';
+export declare class FileSink implements TelemetrySink {
+    private readonly path;
+    constructor(path: string);
+    emit(event: TelemetryEvent): void;
+}

package/dist/telemetry/sinks/file.js

@@ -0,0 +1,28 @@
+/**
+ * Append-only JSONL telemetry sink. Metadata only, redacted before write. A telemetry write must
+ * NEVER fail a run, so all IO is wrapped and swallowed. The path should be outside the repo or
+ * gitignored (`init` adds `.ai-runtime/`).
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { redact } from '../../security/redact.js';
+export class FileSink {
+    path;
+    constructor(path) {
+        this.path = path;
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+        }
+        catch {
+            /* ignore — a telemetry setup failure must not break the router */
+        }
+    }
+    emit(event) {
+        try {
+            appendFileSync(this.path, `${JSON.stringify(redact(event))}\n`);
+        }
+        catch {
+            /* a telemetry write must never fail a run */
+        }
+    }
+}

package/dist/telemetry/telemetry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Telemetry sinks. Events are ROUTING/PERF METADATA only — never prompt text, input, or keys — and
+ * are defensively passed through `redact()` before storage so a stray secret can never land in a sink.
+ */
+import type { TelemetryEvent } from '../types.js';
+export interface TelemetrySink {
+    emit(event: TelemetryEvent): void;
+    events?(): TelemetryEvent[];
+}
+export declare class MemorySink implements TelemetrySink {
+    private readonly limit;
+    private readonly buffer;
+    constructor(limit?: number);
+    emit(event: TelemetryEvent): void;
+    events(): TelemetryEvent[];
+}
+export declare class NullSink implements TelemetrySink {
+    emit(): void;
+}
+/**
+ * Centralized observability: forward each redacted event to a user callback — e.g. push to
+ * a collector, OpenTelemetry, or a log pipeline. Failures are swallowed so observability never breaks
+ * a run. Events are already metadata-only and redacted by the emitting sink chain.
+ */
+export declare class CallbackSink implements TelemetrySink {
+    private readonly forward;
+    constructor(forward: (event: TelemetryEvent) => void);
+    emit(event: TelemetryEvent): void;
+}
+/** Fan an event out to several sinks; `events()` reports the first queryable sink's buffer. */
+export declare class MultiSink implements TelemetrySink {
+    private readonly sinks;
+    constructor(sinks: TelemetrySink[]);
+    emit(event: TelemetryEvent): void;
+    events(): TelemetryEvent[];
+}

package/dist/telemetry/telemetry.js

@@ -0,0 +1,63 @@
+/**
+ * Telemetry sinks. Events are ROUTING/PERF METADATA only — never prompt text, input, or keys — and
+ * are defensively passed through `redact()` before storage so a stray secret can never land in a sink.
+ */
+import { redact } from '../security/redact.js';
+export class MemorySink {
+    limit;
+    buffer = [];
+    constructor(limit = 1000) {
+        this.limit = limit;
+    }
+    emit(event) {
+        this.buffer.push(redact(event));
+        if (this.buffer.length > this.limit)
+            this.buffer.shift();
+    }
+    events() {
+        return [...this.buffer];
+    }
+}
+export class NullSink {
+    emit() {
+        /* no-op */
+    }
+}
+/**
+ * Centralized observability: forward each redacted event to a user callback — e.g. push to
+ * a collector, OpenTelemetry, or a log pipeline. Failures are swallowed so observability never breaks
+ * a run. Events are already metadata-only and redacted by the emitting sink chain.
+ */
+export class CallbackSink {
+    forward;
+    constructor(forward) {
+        this.forward = forward;
+    }
+    emit(event) {
+        try {
+            this.forward(redact(event));
+        }
+        catch {
+            /* observability must never break a run */
+        }
+    }
+}
+/** Fan an event out to several sinks; `events()` reports the first queryable sink's buffer. */
+export class MultiSink {
+    sinks;
+    constructor(sinks) {
+        this.sinks = sinks;
+    }
+    emit(event) {
+        for (const sink of this.sinks)
+            sink.emit(event);
+    }
+    events() {
+        for (const sink of this.sinks) {
+            const ev = sink.events?.();
+            if (ev)
+                return ev;
+        }
+        return [];
+    }
+}

package/dist/tools/builtins/filesystem.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Filesystem tool — read/write/list/exists, strictly jailed to the workspace. Reads are gated on
+ * `filesystem.read`; writes on `filesystem.write` (or interactive approval). Every path is resolved
+ * through the jail, so `..`, absolute escapes, and symlink/junction/UNC escapes are rejected.
+ */
+import type { Tool } from '../tool.js';
+export declare const filesystemTool: Tool;

package/dist/tools/builtins/filesystem.js

@@ -0,0 +1,53 @@
+/**
+ * Filesystem tool — read/write/list/exists, strictly jailed to the workspace. Reads are gated on
+ * `filesystem.read`; writes on `filesystem.write` (or interactive approval). Every path is resolved
+ * through the jail, so `..`, absolute escapes, and symlink/junction/UNC escapes are rejected.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { authorize, denied } from '../tool.js';
+import { resolveInJail, JailError } from '../jail.js';
+export const filesystemTool = {
+    id: 'filesystem',
+    description: 'Read, write, list, and check files within the workspace (jailed; no escape).',
+    parameters: { op: 'read | write | list | exists', path: 'string (relative to workspace)', content: 'string (write only)' },
+    async execute(input, ctx) {
+        const { op, path, content } = (input ?? {});
+        if (!op || typeof path !== 'string' || path === '')
+            return denied('INVALID_INPUT', 'filesystem requires { op, path }');
+        let abs;
+        try {
+            abs = resolveInJail(ctx.workspaceRoot, path);
+        }
+        catch (e) {
+            if (e instanceof JailError)
+                return denied('JAILBREAK', e.message);
+            throw e;
+        }
+        if (op === 'read' || op === 'list' || op === 'exists') {
+            if (!ctx.permissions.filesystem.read)
+                return denied('PERMISSION', 'filesystem read is not permitted');
+            if (op === 'exists')
+                return { ok: true, data: existsSync(abs) };
+            if (!existsSync(abs))
+                return denied('NOT_FOUND', `no such path: ${path}`);
+            if (op === 'list') {
+                if (!statSync(abs).isDirectory())
+                    return denied('INVALID_INPUT', `not a directory: ${path}`);
+                const entries = readdirSync(abs);
+                return { ok: true, data: entries, output: entries.join('\n') };
+            }
+            const text = readFileSync(abs, 'utf8');
+            return { ok: true, output: text, data: text };
+        }
+        if (op === 'write') {
+            const allowed = await authorize(ctx, ctx.permissions.filesystem.write, { action: `write file ${path}`, risk: 'medium' });
+            if (!allowed)
+                return denied('PERMISSION', `filesystem write is not permitted: ${path}`);
+            mkdirSync(dirname(abs), { recursive: true });
+            writeFileSync(abs, content ?? '');
+            return { ok: true, output: `wrote ${path}` };
+        }
+        return denied('INVALID_INPUT', `unknown filesystem op: ${String(op)}`);
+    },
+};

package/dist/tools/builtins/git.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Git tool. Reads (status/diff/log) are always allowed. Mutations are gated: commit on `git.commit`,
+ * push on `git.push` (or interactive approval). `status` reports whether the working tree is dirty so a
+ * caller can confirm before the first mutating step. Uses the injectable runner (hermetic in tests).
+ */
+import type { Tool } from '../tool.js';
+import type { CommandRunner } from '../runner.js';
+export declare function createGitTool(runner?: CommandRunner): Tool;
+/** The git tool with the default (real) runner. */
+export declare const gitTool: Tool;