ai-runtime-engine 1.1.0

package/dist/runtime/types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Public Runtime types (Phase 1). The Runtime is a thin orchestration facade OVER the existing `AI`
+ * router — it never routes itself. These types are additive and provider-agnostic; nothing here
+ * duplicates a router concept.
+ */
+import type { InputPart, RouterConfig, RouterErrorInfo, RoutingPreferences, RoutingReport, RunRequest, Sensitivity, Strategy } from '../types.js';
+import type { CompileMetrics, ContextValidation } from '../context/compiler.js';
+import type { PermissionPolicy } from './policy.js';
+import type { ExecutionPlan } from '../orchestration/plan.js';
+import type { ComparisonPin, ComparisonResult } from '../comparison/comparison.js';
+export declare const RUNTIME_MODES: readonly ["auto", "chat", "plan", "execute", "orchestrate", "agent", "compare", "debug"];
+export type RuntimeMode = (typeof RUNTIME_MODES)[number];
+/** A mode that can actually run — never 'auto' (auto resolves TO one of these). */
+export type ExecutableMode = Exclude<RuntimeMode, 'auto'>;
+/** Which rung of the precedence chain decided the selected mode. */
+export type ModeSource = 'explicit' | 'config' | 'env' | 'auto';
+export interface ModeResolution {
+    /** What the caller asked for on this run; 'auto' when omitted. */
+    requested: RuntimeMode;
+    /** What precedence + detection decided. */
+    selected: ExecutableMode;
+    /** What actually ran. In Phase 1 always 'chat' (unimplemented modes degrade to chat). */
+    executed: ExecutableMode;
+    /** 1.0 for explicit/config/env; the classifier score for auto detection. */
+    confidence: number;
+    /** Human-readable; carries the degrade notice when executed !== selected. */
+    reason: string;
+    /** Which precedence rung fixed `selected`. */
+    source: ModeSource;
+}
+export interface ArtifactRef {
+    id: string;
+    type: string;
+    source: string;
+    /** Where the actual content lives (resolved by the Artifact Store, Phase 7). */
+    contentRef: string;
+    checksum?: string;
+    size?: number;
+    metadata?: Record<string, unknown>;
+}
+/** Task-level status. `ok` (on RuntimeResult) is whether the Runtime OP succeeded; this is whether the TASK is done/waiting. */
+export type RuntimeStatus = 'completed' | 'waiting_for_clarification' | 'waiting_for_approval' | 'failed';
+export interface Clarification {
+    question: string;
+    options?: string[];
+}
+export interface RuntimeSettings {
+    /** Project default mode. 'auto' means "always detect". */
+    defaultMode?: RuntimeMode;
+    defaultStrategy?: Strategy;
+    /** Context-compilation settings (token budget for the compiled model context). */
+    context?: {
+        maxTokens?: number;
+    };
+    /** Project exclude/prefer routing (merged with env + per-run; EXCLUDE hard, PREFER soft). */
+    routing?: RoutingPreferences;
+    /** Skill discovery: consented local paths, npm skill packs to load, and whether to auto-load on load. */
+    skills?: {
+        paths?: string[];
+        packages?: string[];
+        autoload?: boolean;
+    };
+}
+export interface RuntimeConfig {
+    runtime?: RuntimeSettings;
+    /** Tool permission grants (deny-by-default for write/exec; see PermissionPolicy). */
+    permissions?: PermissionPolicy;
+    /** The existing router configuration (providers, strategy, learning, verification, budget, policy, tasks…). */
+    router: RouterConfig;
+}
+export interface RuntimeRunInput {
+    input: string | {
+        text?: string;
+        parts?: InputPart[];
+    };
+    /** Explicit per-run mode (highest precedence; never overridden by detection). */
+    mode?: RuntimeMode;
+    /** Explicit per-run strategy (highest precedence). */
+    strategy?: Strategy;
+    /** System prompt, appended after the workspace summary line. */
+    system?: string;
+    sensitivity?: Sensitivity;
+    output?: RunRequest['output'];
+    /** Prepend a one-line workspace summary to the system prompt (default true). Never sends repo contents. */
+    workspaceContext?: boolean;
+    /** Per-run context-compilation overrides (highest-precedence token budget). */
+    context?: {
+        maxTokens?: number;
+    };
+    /** Dry-run: plan + report what WOULD happen, performing zero mutations (plan/execute/orchestrate). */
+    dryRun?: boolean;
+    /** Caller idempotency identity (dedup enforced from Phase 7). */
+    requestId?: string;
+    /** Per-run exclude/prefer routing (highest precedence; merged with config + env). */
+    routing?: RoutingPreferences;
+    /** Compare-mode options (Phase 8): which pins to fan out across, an optional judge, the router task. */
+    compare?: CompareRunOptions;
+    /** Escape hatch: merged onto the generated RunRequest last, but cannot override task/input. */
+    request?: Partial<Omit<RunRequest, 'task' | 'input'>>;
+}
+/** Compare-mode inputs. With no pins, the runtime fans out across every enabled provider (default model). */
+export interface CompareRunOptions {
+    /** Candidate provider/model pins. Default: one pin per enabled provider. */
+    pins?: ComparisonPin[];
+    /** Optional judge model (a labeled opinion used only when no evidence function is supplied). */
+    judge?: ComparisonPin;
+    /** Router task each pin runs (default 'chat'). */
+    task?: string;
+    /** Agreement/clustering similarity threshold, 0..1 (default 0.75). */
+    agreementThreshold?: number;
+}
+export interface RuntimeResult {
+    /** Whether the Runtime operation itself succeeded (NOT whether the task is complete — see `status`). */
+    ok: boolean;
+    /** Identity of this single runtime.run() invocation. */
+    runId: string;
+    mode: ModeResolution;
+    status: RuntimeStatus;
+    response?: {
+        text?: string;
+        json?: unknown;
+    };
+    /** Present when the runtime needs the user to disambiguate. Never a failure. */
+    clarification?: Clarification;
+    /** Verbatim passthrough of the router's decision trace when a model ran. */
+    routing?: RoutingReport;
+    error?: RouterErrorInfo;
+    /** Artifact references produced by this run (empty until the Artifact Store lands in Phase 7). */
+    artifacts: ArtifactRef[];
+    /** What memory was retrieved into context and/or captured this run (Phase 3). */
+    memory?: MemoryTrace;
+    /** How the model context was compiled this run: metrics + loss validation (Phase 4). */
+    context?: ContextReport;
+    /** The plan the orchestrator produced/executed (with per-step statuses) — Phase 6. */
+    plan?: ExecutionPlan;
+    /** The multi-model comparison this run produced (compare mode / runtime.compare) — Phase 8. */
+    comparison?: ComparisonResult;
+    execution?: unknown;
+    learning?: unknown;
+}
+/** Memory activity for a run: facts pulled into context, and any fact captured from the input. */
+export interface MemoryTrace {
+    retrieved: string[];
+    captured?: {
+        id: string;
+        scope: string;
+    };
+}
+/** How the context compiler built the model context this run. */
+export interface ContextReport {
+    metrics: CompileMetrics;
+    validation: ContextValidation;
+}

package/dist/runtime/types.js

@@ -0,0 +1,9 @@
+/**
+ * Public Runtime types (Phase 1). The Runtime is a thin orchestration facade OVER the existing `AI`
+ * router — it never routes itself. These types are additive and provider-agnostic; nothing here
+ * duplicates a router concept.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Modes
+// ─────────────────────────────────────────────────────────────────────────────
+export const RUNTIME_MODES = ['auto', 'chat', 'plan', 'execute', 'orchestrate', 'agent', 'compare', 'debug'];

package/dist/runtime/workspace/detectors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Table-driven workspace trait detection. Pure data + tiny helpers — fs marker lookups only, never a
+ * child process, never a recursive walk. Adding a marker is the sanctioned way to grow detection.
+ */
+/** Marker file (in the workspace root) → language it implies. */
+export declare const LANGUAGE_MARKERS: ReadonlyArray<readonly [string, string]>;
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'poetry' | 'uv' | 'cargo' | 'go' | 'maven' | 'gradle';
+/** Lockfile/marker (in the root) → package manager. First match wins; JS lockfiles are checked first. */
+export declare const LOCKFILE_TO_PM: ReadonlyArray<readonly [string, PackageManager]>;
+/** Dependency name (in package.json deps/devDeps) → framework. First match wins. */
+export declare const DEP_TO_FRAMEWORK: ReadonlyArray<readonly [string, string]>;
+/** Dependency name → test framework. First match wins; node:test inferred separately from scripts.test. */
+export declare const DEP_TO_TEST_FRAMEWORK: ReadonlyArray<readonly [string, string]>;
+/** Parse the current branch out of raw `.git/HEAD` text. Returns 'detached' for a raw SHA. */
+export declare function branchFromHead(headText: string): string;

package/dist/runtime/workspace/detectors.js

@@ -0,0 +1,57 @@
+/**
+ * Table-driven workspace trait detection. Pure data + tiny helpers — fs marker lookups only, never a
+ * child process, never a recursive walk. Adding a marker is the sanctioned way to grow detection.
+ */
+/** Marker file (in the workspace root) → language it implies. */
+export const LANGUAGE_MARKERS = [
+    ['tsconfig.json', 'typescript'],
+    ['package.json', 'javascript'],
+    ['pyproject.toml', 'python'],
+    ['requirements.txt', 'python'],
+    ['setup.py', 'python'],
+    ['go.mod', 'go'],
+    ['Cargo.toml', 'rust'],
+    ['pom.xml', 'java'],
+    ['build.gradle', 'java'],
+];
+/** Lockfile/marker (in the root) → package manager. First match wins; JS lockfiles are checked first. */
+export const LOCKFILE_TO_PM = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['bun.lockb', 'bun'],
+    ['bun.lock', 'bun'],
+    ['package-lock.json', 'npm'],
+    ['poetry.lock', 'poetry'],
+    ['uv.lock', 'uv'],
+    ['Cargo.lock', 'cargo'],
+    ['go.sum', 'go'],
+    ['pom.xml', 'maven'],
+    ['build.gradle', 'gradle'],
+];
+/** Dependency name (in package.json deps/devDeps) → framework. First match wins. */
+export const DEP_TO_FRAMEWORK = [
+    ['next', 'next'],
+    ['@remix-run/react', 'remix'],
+    ['nuxt', 'nuxt'],
+    ['@angular/core', 'angular'],
+    ['svelte', 'svelte'],
+    ['vue', 'vue'],
+    ['react', 'react'],
+    ['@nestjs/core', 'nest'],
+    ['fastify', 'fastify'],
+    ['express', 'express'],
+];
+/** Dependency name → test framework. First match wins; node:test inferred separately from scripts.test. */
+export const DEP_TO_TEST_FRAMEWORK = [
+    ['@playwright/test', 'playwright'],
+    ['playwright', 'playwright'],
+    ['vitest', 'vitest'],
+    ['jest', 'jest'],
+    ['mocha', 'mocha'],
+    ['pytest', 'pytest'],
+];
+/** Parse the current branch out of raw `.git/HEAD` text. Returns 'detached' for a raw SHA. */
+export function branchFromHead(headText) {
+    const m = /^ref:\s*refs\/heads\/(.+)\s*$/m.exec(headText);
+    return m?.[1]?.trim() ?? 'detached';
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Workspace detection — fs-only, deterministic, never throws. It probes a fixed marker list in the
+ * root directory (no recursion, no child process; git branch is parsed from `.git/HEAD` text) and
+ * produces a WorkspaceInfo. The ONLY thing that ever reaches a provider is summarizeWorkspace()'s one
+ * line (trait names + basename), never file contents and never the absolute path.
+ */
+import type { Clock } from '../../util/clock.js';
+import type { PackageManager } from './detectors.js';
+export interface WorkspaceInfo {
+    /** Absolute root. */
+    root: string;
+    name?: string;
+    exists: boolean;
+    git: {
+        isRepo: boolean;
+        branch?: string;
+    };
+    languages: string[];
+    packageManager?: PackageManager;
+    framework?: string;
+    testFramework?: string;
+    /** Marker files actually found (relative names). */
+    projectFiles: string[];
+    detectedAt: number;
+}
+/** Detect workspace traits under `root`. Never throws; a missing/unreadable root yields exists:false. */
+export declare function detectWorkspace(root: string, clock?: Clock): WorkspaceInfo;
+/** One-line, provider-safe summary: trait names + basename only — never paths (beyond basename) or contents. */
+export declare function summarizeWorkspace(info: WorkspaceInfo): string;

package/dist/runtime/workspace/workspace.js

@@ -0,0 +1,116 @@
+/**
+ * Workspace detection — fs-only, deterministic, never throws. It probes a fixed marker list in the
+ * root directory (no recursion, no child process; git branch is parsed from `.git/HEAD` text) and
+ * produces a WorkspaceInfo. The ONLY thing that ever reaches a provider is summarizeWorkspace()'s one
+ * line (trait names + basename), never file contents and never the absolute path.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { systemClock } from '../../util/clock.js';
+import { LANGUAGE_MARKERS, LOCKFILE_TO_PM, DEP_TO_FRAMEWORK, DEP_TO_TEST_FRAMEWORK, branchFromHead } from './detectors.js';
+function readJsonSafe(path) {
+    try {
+        if (!existsSync(path))
+            return undefined;
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readTextSafe(path) {
+    try {
+        return existsSync(path) ? readFileSync(path, 'utf8') : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Detect workspace traits under `root`. Never throws; a missing/unreadable root yields exists:false. */
+export function detectWorkspace(root, clock = systemClock) {
+    const detectedAt = clock.now();
+    const info = {
+        root,
+        exists: existsSync(root),
+        git: { isRepo: false },
+        languages: [],
+        projectFiles: [],
+        detectedAt,
+    };
+    if (!info.exists)
+        return info;
+    // Language markers + recorded project files.
+    const found = new Set();
+    for (const [marker, language] of LANGUAGE_MARKERS) {
+        if (existsSync(join(root, marker))) {
+            found.add(marker);
+            if (!info.languages.includes(language))
+                info.languages.push(language);
+        }
+    }
+    // Package manager (first lockfile/marker hit).
+    for (const [marker, pm] of LOCKFILE_TO_PM) {
+        if (existsSync(join(root, marker))) {
+            found.add(marker);
+            info.packageManager = pm;
+            break;
+        }
+    }
+    // package.json: name, framework, test framework, node:test inference.
+    const pkg = readJsonSafe(join(root, 'package.json'));
+    if (pkg) {
+        found.add('package.json');
+        if (typeof pkg.name === 'string')
+            info.name = pkg.name;
+        const deps = {
+            ...pkg.dependencies,
+            ...pkg.devDependencies,
+        };
+        const depNames = new Set(Object.keys(deps));
+        for (const [dep, framework] of DEP_TO_FRAMEWORK) {
+            if (depNames.has(dep)) {
+                info.framework = framework;
+                break;
+            }
+        }
+        for (const [dep, tf] of DEP_TO_TEST_FRAMEWORK) {
+            if (depNames.has(dep)) {
+                info.testFramework = tf;
+                break;
+            }
+        }
+        if (!info.testFramework) {
+            const testScript = pkg.scripts?.test;
+            if (typeof testScript === 'string' && /(^|\s)--test(\s|$)/.test(testScript))
+                info.testFramework = 'node:test';
+        }
+    }
+    if (!info.name)
+        info.name = basename(root);
+    // Git (parse .git/HEAD; no child process).
+    const head = readTextSafe(join(root, '.git', 'HEAD'));
+    if (head !== undefined) {
+        info.git = { isRepo: true, branch: branchFromHead(head) };
+    }
+    info.projectFiles = [...found].sort();
+    return info;
+}
+/** One-line, provider-safe summary: trait names + basename only — never paths (beyond basename) or contents. */
+export function summarizeWorkspace(info) {
+    if (!info.exists)
+        return 'Workspace: (not found).';
+    const name = info.name ?? basename(info.root);
+    const bits = [];
+    if (info.languages.length)
+        bits.push(info.languages.join('/') + (info.packageManager ? ` (${info.packageManager})` : ''));
+    else if (info.packageManager)
+        bits.push(info.packageManager);
+    if (info.framework)
+        bits.push(`framework: ${info.framework}`);
+    if (info.testFramework)
+        bits.push(`tests: ${info.testFramework}`);
+    if (info.git.isRepo && info.git.branch)
+        bits.push(`git: ${info.git.branch}`);
+    return `Workspace "${name}"${bits.length ? ': ' + bits.join(', ') : ''}.`;
+}

package/dist/security/credentials.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Credential resolution. Config carries the NAME of an env var; this reads the value at construction,
+ * registers it with the redactor, and holds it in a private (`#`) field so it is non-enumerable and
+ * never serialized. `use()` is the only accessor and is called solely by the HTTP layer to build the
+ * auth header. `toJSON()` deliberately omits the key, so logging or returning a Credential is safe.
+ */
+/**
+ * Enterprise credential management: a pluggable resolver lets keys come from an OS keychain,
+ * a cloud secret manager, or a CI secret store instead of the process environment. It receives only
+ * the env-var NAME and returns the value; the resolved value is still held non-enumerably and redacted.
+ */
+export type CredentialResolver = (envName: string) => string | undefined;
+/** Install a custom credential resolver (e.g. a secret-manager lookup). Pass undefined to clear. */
+export declare function setCredentialResolver(resolver: CredentialResolver | undefined): void;
+export declare class Credential {
+    #private;
+    readonly envName?: string;
+    readonly hasKey: boolean;
+    constructor(envName?: string, env?: NodeJS.ProcessEnv);
+    /** The resolved key value — call site is the HTTP header builder only. Returns undefined when unset. */
+    use(): string | undefined;
+    toJSON(): {
+        envName?: string;
+        hasKey: boolean;
+    };
+}

package/dist/security/credentials.js

@@ -0,0 +1,34 @@
+/**
+ * Credential resolution. Config carries the NAME of an env var; this reads the value at construction,
+ * registers it with the redactor, and holds it in a private (`#`) field so it is non-enumerable and
+ * never serialized. `use()` is the only accessor and is called solely by the HTTP layer to build the
+ * auth header. `toJSON()` deliberately omits the key, so logging or returning a Credential is safe.
+ */
+import { registerSecret } from './redact.js';
+let customResolver;
+/** Install a custom credential resolver (e.g. a secret-manager lookup). Pass undefined to clear. */
+export function setCredentialResolver(resolver) {
+    customResolver = resolver;
+}
+export class Credential {
+    envName;
+    hasKey;
+    #key;
+    constructor(envName, env = process.env) {
+        if (envName !== undefined)
+            this.envName = envName;
+        // Precedence: explicit env (process/test) first, then a custom resolver (secret manager).
+        const value = envName ? (env[envName] ?? customResolver?.(envName)) : undefined;
+        this.#key = value;
+        this.hasKey = Boolean(value);
+        if (value)
+            registerSecret(value);
+    }
+    /** The resolved key value — call site is the HTTP header builder only. Returns undefined when unset. */
+    use() {
+        return this.#key;
+    }
+    toJSON() {
+        return { ...(this.envName !== undefined ? { envName: this.envName } : {}), hasKey: this.hasKey };
+    }
+}

package/dist/security/redact.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reference-based secret redaction, applied at every egress (logs, telemetry, errors, CLI output).
+ *
+ * Shape-only redaction (matching `sk-`/`Bearer` patterns) is fail-open for unknown key formats, so
+ * the primary defense here is REFERENCE-based: the credential layer registers each resolved key VALUE
+ * via `registerSecret`, and we scrub those exact values wherever they appear. Shape-based patterns
+ * remain only as defense-in-depth. This runs BEFORE any truncation so a secret can never survive at a
+ * truncation boundary.
+ */
+/** Register a resolved key value so it is scrubbed from every egress. Short values are ignored to avoid over-redaction. */
+export declare function registerSecret(value: string | null | undefined): void;
+/** Test/utility hook. */
+export declare function clearSecrets(): void;
+export declare function redactString(input: string): string;
+/** Deep-redact any value, returning a scrubbed clone. Non-plain objects are stringified defensively. */
+export declare function redact<T>(value: T): T;

package/dist/security/redact.js

@@ -0,0 +1,57 @@
+/**
+ * Reference-based secret redaction, applied at every egress (logs, telemetry, errors, CLI output).
+ *
+ * Shape-only redaction (matching `sk-`/`Bearer` patterns) is fail-open for unknown key formats, so
+ * the primary defense here is REFERENCE-based: the credential layer registers each resolved key VALUE
+ * via `registerSecret`, and we scrub those exact values wherever they appear. Shape-based patterns
+ * remain only as defense-in-depth. This runs BEFORE any truncation so a secret can never survive at a
+ * truncation boundary.
+ */
+const secretValues = new Set();
+/** Register a resolved key value so it is scrubbed from every egress. Short values are ignored to avoid over-redaction. */
+export function registerSecret(value) {
+    if (value && value.length >= 8)
+        secretValues.add(value);
+}
+/** Test/utility hook. */
+export function clearSecrets() {
+    secretValues.clear();
+}
+const SHAPE_PATTERNS = [
+    [/(authorization"?\s*[:=]\s*"?bearer\s+)[^\s"',}]+/gi, '$1[redacted]'],
+    [/(x-api-key"?\s*[:=]\s*"?)[^\s"',}]+/gi, '$1[redacted]'],
+    [/([?&](?:key|api_key|access_token)=)[^&\s"']+/gi, '$1[redacted]'],
+    [/\b(sk-[a-z]*-?)[A-Za-z0-9_-]{6,}\b/gi, '$1[redacted]'],
+    [/\b(gsk_)[A-Za-z0-9_-]{6,}\b/g, '$1[redacted]'],
+];
+export function redactString(input) {
+    let out = input;
+    for (const secret of secretValues) {
+        if (secret)
+            out = out.split(secret).join('[redacted]');
+    }
+    for (const [pattern, replacement] of SHAPE_PATTERNS) {
+        out = out.replace(pattern, replacement);
+    }
+    return out;
+}
+/** Deep-redact any value, returning a scrubbed clone. Non-plain objects are stringified defensively. */
+export function redact(value) {
+    return redactValue(value, new WeakSet());
+}
+function redactValue(value, seen) {
+    if (typeof value === 'string')
+        return redactString(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return '[circular]';
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((v) => redactValue(v, seen));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = redactValue(v, seen);
+    }
+    return out;
+}

package/dist/skills/builtins/fileAnalyzer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * file-analyzer — a generic skill: read a file (via the jailed filesystem tool), then ask a model to
+ * analyze it. Validates that a file was actually read and a non-empty analysis was produced (evidence,
+ * not a model claim). QA-neutral.
+ */
+import type { Skill } from '../skill.js';
+export declare const fileAnalyzerSkill: Skill;

package/dist/skills/builtins/fileAnalyzer.js

@@ -0,0 +1,47 @@
+/**
+ * file-analyzer — a generic skill: read a file (via the jailed filesystem tool), then ask a model to
+ * analyze it. Validates that a file was actually read and a non-empty analysis was produced (evidence,
+ * not a model claim). QA-neutral.
+ */
+import { wrapUntrusted } from '../../tools/untrusted.js';
+export const fileAnalyzerSkill = {
+    id: 'file-analyzer',
+    version: '1.0.0',
+    runtimeCompatibility: '>=0.1.0',
+    name: 'File analyzer',
+    description: 'Read a file within the workspace and analyze it.',
+    capabilities: [
+        { group: 'intelligence', key: 'reasoning' },
+        { group: 'output', key: 'text' },
+    ],
+    tools: ['filesystem'],
+    async plan() {
+        return { steps: [{ description: 'read the file', tool: 'filesystem' }, { description: 'analyze its contents' }] };
+    },
+    async execute(ctx) {
+        const { path, question } = (ctx.input ?? {});
+        if (!path)
+            return { ok: false, error: { message: 'file-analyzer requires { path }' } };
+        const read = await ctx.callTool('filesystem', { op: 'read', path });
+        if (!read.ok)
+            return { ok: false, error: { message: `could not read ${path}: ${read.error?.message ?? 'unknown'}` } };
+        const content = String(read.output ?? '');
+        // File content is UNTRUSTED data — fence it so its text can't act as instructions.
+        const prompt = `${question ? question + '\n\n' : 'Analyze the following file and summarize its purpose and structure.\n\n'}File: ${path}\n${wrapUntrusted(path, content)}`;
+        const run = await ctx.ai.run({ task: 'file-analyzer', input: prompt, requirements: { intelligence: ['reasoning'], output: ['text'] } });
+        if (!run.ok)
+            return { ok: false, error: { message: `analysis failed: ${run.error?.category ?? 'unknown'}` } };
+        return { ok: true, output: run.response?.text ?? '', data: { path, bytes: content.length } };
+    },
+    async validate(result) {
+        const readOk = !!result.data?.bytes;
+        const analyzed = !!result.output && result.output.trim().length > 0;
+        return {
+            ok: readOk && analyzed,
+            checks: [
+                { name: 'file-read', ok: readOk, ...(readOk ? {} : { why: 'no file content was read' }) },
+                { name: 'analysis-produced', ok: analyzed, ...(analyzed ? {} : { why: 'the model returned no analysis' }) },
+            ],
+        };
+    },
+};

package/dist/skills/builtins/repositoryAnalyzer.d.ts

@@ -0,0 +1,6 @@
+/**
+ * repository-analyzer — a generic skill: list the workspace root (via the jailed filesystem tool) and
+ * ask a model to characterize the project. Validates that entries were listed and a summary produced.
+ */
+import type { Skill } from '../skill.js';
+export declare const repositoryAnalyzerSkill: Skill;

package/dist/skills/builtins/repositoryAnalyzer.js

@@ -0,0 +1,47 @@
+/**
+ * repository-analyzer — a generic skill: list the workspace root (via the jailed filesystem tool) and
+ * ask a model to characterize the project. Validates that entries were listed and a summary produced.
+ */
+import { wrapUntrusted } from '../../tools/untrusted.js';
+export const repositoryAnalyzerSkill = {
+    id: 'repository-analyzer',
+    version: '1.0.0',
+    runtimeCompatibility: '>=0.1.0',
+    name: 'Repository analyzer',
+    description: 'Survey the workspace and summarize the project at a high level.',
+    capabilities: [
+        { group: 'intelligence', key: 'reasoning' },
+        { group: 'intelligence', key: 'summarization' },
+        { group: 'output', key: 'text' },
+    ],
+    tools: ['filesystem'],
+    async plan() {
+        return { steps: [{ description: 'list the workspace root', tool: 'filesystem' }, { description: 'summarize the project' }] };
+    },
+    async execute(ctx) {
+        const list = await ctx.callTool('filesystem', { op: 'list', path: '.' });
+        if (!list.ok)
+            return { ok: false, error: { message: `could not list the workspace: ${list.error?.message ?? 'unknown'}` } };
+        const entries = list.data ?? [];
+        // Directory entries are UNTRUSTED (attacker-chosen filenames) — fence them.
+        const run = await ctx.ai.run({
+            task: 'repository-analyzer',
+            input: `${wrapUntrusted('workspace-listing', entries.join('\n'))}\n\nBriefly characterize this project (language, purpose, structure) from the entries above.`,
+            requirements: { intelligence: ['reasoning', 'summarization'], output: ['text'] },
+        });
+        if (!run.ok)
+            return { ok: false, error: { message: `summary failed: ${run.error?.category ?? 'unknown'}` } };
+        return { ok: true, output: run.response?.text ?? '', data: { entryCount: entries.length } };
+    },
+    async validate(result) {
+        const listed = (result.data?.entryCount ?? 0) > 0;
+        const summarized = !!result.output && result.output.trim().length > 0;
+        return {
+            ok: listed && summarized,
+            checks: [
+                { name: 'workspace-listed', ok: listed, ...(listed ? {} : { why: 'no entries were listed' }) },
+                { name: 'summary-produced', ok: summarized, ...(summarized ? {} : { why: 'the model returned no summary' }) },
+            ],
+        };
+    },
+};