ai-runtime-engine 1.3.0 → 2.8.0

package/dist/executions/agentTasks.js

@@ -0,0 +1,149 @@
+/**
+ * Persisted agent tasks (Phase 3.5) — the schema, and the ONE way anything reads them back.
+ *
+ * An `Execution` is a JSON file in the user's home. Invariant 21 says persisted agent state is
+ * schema-validated on read, and the reason is concrete: a record's `innerPlan` is EXECUTED on resume and
+ * its hashes decide whether completed work may be reused, so a malformed record is not a display problem
+ * — it is an execution problem. Validation is fail-closed per record: anything that does not parse is
+ * dropped whole and counted, never coerced or half-read.
+ *
+ * READING IS NOT WRITING. `parseAgentTasks` returns a filtered VIEW and never touches the stored record,
+ * so merely listing or acquiring an execution cannot destroy tasks it could not parse. The dropped count
+ * travels with the view so a silently shrinking list is visible instead of inferred.
+ */
+import { z } from 'zod';
+/** Structural only. A persisted inner plan still faces `validatePlan` against the envelope before it runs. */
+const planStep = z
+    .object({
+    id: z.string().min(1),
+    description: z.string(),
+    skill: z.string().optional(),
+    tool: z.string().optional(),
+    agent: z.string().optional(),
+    motivatedBy: z.array(z.string()).optional(),
+    input: z.unknown().optional(),
+    dependsOn: z.array(z.string()).optional(),
+    status: z.enum(['pending', 'running', 'succeeded', 'failed', 'skipped']),
+})
+    .strict();
+const executionPlan = z.object({ id: z.string(), goal: z.string(), version: z.number(), steps: z.array(planStep), reason: z.string().optional() }).strict();
+const observation = z
+    .object({
+    stepId: z.string(),
+    skill: z.string().optional(),
+    tool: z.string().optional(),
+    agent: z.string().optional(),
+    agentTaskId: z.string().optional(),
+    ok: z.boolean(),
+    output: z.string().optional(),
+    error: z.string().optional(),
+    code: z.string().optional(),
+    data: z.unknown().optional(),
+    artifacts: z.array(z.unknown()).optional(),
+    callsUsed: z.number().optional(),
+})
+    .passthrough();
+const evidence = z.object({ kind: z.string(), ref: z.string().optional(), detail: z.string().optional(), stepId: z.string().optional() }).passthrough();
+const finding = z
+    .object({
+    id: z.string().min(1),
+    agentId: z.string(),
+    agentTaskId: z.string(),
+    type: z.string(),
+    subject: z.string().optional(),
+    claim: z.string(),
+    verdict: z.string().optional(),
+    executionCoverage: z.number().min(0).max(1),
+    confidence: z.number().min(0).max(1),
+    evidence: z.array(evidence),
+    artifacts: z.array(z.unknown()),
+    sourceSteps: z.array(z.string()),
+    provenance: z.object({ executionId: z.string().optional(), planVersion: z.number() }).passthrough(),
+    status: z.enum(['active', 'superseded', 'contradicted']),
+    supersededBy: z.string().optional(),
+    createdAt: z.number(),
+})
+    .passthrough();
+const checkpoint = z
+    .object({
+    at: z.number(),
+    planVersion: z.number(),
+    gitHead: z.string().optional(),
+    fileHashes: z.record(z.string(), z.string()),
+    configHash: z.string().optional(),
+    skillVersions: z.record(z.string(), z.string()),
+    completedSteps: z.array(z.string()),
+    mcpTools: z.record(z.string(), z.string()).optional(),
+})
+    .passthrough();
+/** A counter read back into arithmetic: a whole number, never negative, never absurd. */
+const count = z.number().int().min(0).max(1_000_000);
+/** Bounds on the per-record collections, so one task cannot make an execution file unreadable. */
+const FINDINGS_MAX = 200;
+const DIAGNOSTICS_MAX = 200;
+const AGENT_STATES = ['created', 'queued', 'running', 'completed', 'failed', 'cancelled', 'waiting_for_input', 'waiting_for_clarification', 'paused'];
+/**
+ * The record schema. `v` is a LITERAL: a record written by a future, wider version is dropped rather
+ * than parsed as this shape — reinterpreting an unknown layout is how a resume executes something its
+ * author never wrote.
+ */
+export const persistedAgentTask = z
+    .object({
+    v: z.literal(1),
+    agentTaskId: z.string().min(1),
+    agentId: z.string().min(1),
+    stepId: z.string().min(1),
+    state: z.enum(AGENT_STATES),
+    createdAt: z.number(),
+    updatedAt: z.number(),
+    startedAt: z.number().optional(),
+    endedAt: z.number().optional(),
+    interruption: z.object({ kind: z.enum(['crash', 'pause', 'parent-cancel']), at: z.number(), detail: z.string().optional() }).strict().optional(),
+    provenance: z.object({ executionId: z.string().optional(), planVersion: z.number() }).strict(),
+    agentDefHash: z.string().min(1),
+    envelopeHash: z.string().min(1),
+    stepInputHash: z.string().min(1),
+    attempt: z.number().int().min(1),
+    innerPlanVersion: z.number().optional(),
+    innerPlan: executionPlan.optional(),
+    innerCompletedSteps: z.array(z.string()),
+    innerObservations: z.array(observation),
+    innerObservationsOmitted: z.number().int().min(0),
+    innerCheckpoint: checkpoint.optional(),
+    pendingInner: z.object({ kind: z.literal('clarification'), question: z.string(), at: z.number() }).strict().optional(),
+    // Bounded and non-negative. These are read back into budget arithmetic and into rendered status
+    // lines, so a tampered or corrupted file must not be able to inject a negative or absurd count.
+    innerSteps: z.object({ total: count, succeeded: count }).strict(),
+    callsReserved: count,
+    callsUsed: count,
+    callsRefunded: count,
+    toolCallsUsed: count,
+    findings: z.array(finding).max(FINDINGS_MAX),
+    diagnostics: z.array(z.unknown()).max(DIAGNOSTICS_MAX),
+    failure: z.object({ code: z.string(), message: z.string() }).passthrough().optional(),
+})
+    .strict();
+/**
+ * Validate the agent tasks on an execution. Pure: it reads, it never writes. Callers that then persist
+ * the execution are choosing to drop the unparseable records — reading alone never does.
+ */
+export function parseAgentTasks(exec) {
+    const raw = exec.agentTasks;
+    if (!Array.isArray(raw))
+        return { tasks: [], dropped: 0 };
+    const tasks = [];
+    let dropped = 0;
+    for (const entry of raw) {
+        const parsed = persistedAgentTask.safeParse(entry);
+        if (!parsed.success) {
+            dropped += 1;
+            continue;
+        }
+        tasks.push(parsed.data);
+    }
+    return { tasks, dropped };
+}
+/** One task by id, validated — the lookup every resume path uses. */
+export function findAgentTask(exec, agentTaskId) {
+    return parseAgentTasks(exec).tasks.find((t) => t.agentTaskId === agentTaskId);
+}

package/dist/executions/checkpoint.d.ts

@@ -16,6 +16,10 @@ export interface CaptureInput {
     skills: Skill[];
     completedSteps: string[];
     clock?: Clock;
+    /** Phase 3.5: plan-referenced MCP tool id → a hash of its live declaration. An MCP server is remote
+     *  and mutable: it can change a tool's schema, or drop it, while a plan sits paused. That is drift in
+     *  exactly the same sense as an edited file, and it was invisible before. */
+    mcpTools?: Record<string, string>;
 }
 export declare function captureCheckpoint(input: CaptureInput): Checkpoint;
 export interface Reconciliation {
@@ -23,4 +27,4 @@ export interface Reconciliation {
     reasons: string[];
 }
 /** Recompute the fingerprint and compare to a checkpoint. Any difference is drift. */
-export declare function reconcile(checkpoint: Checkpoint, root: string, skills: Skill[]): Reconciliation;
+export declare function reconcile(checkpoint: Checkpoint, root: string, skills: Skill[], mcpTools?: Record<string, string>): Reconciliation;

package/dist/executions/checkpoint.js

@@ -85,10 +85,11 @@ export function captureCheckpoint(input) {
         ...(cfg !== undefined ? { configHash: cfg } : {}),
         skillVersions,
         completedSteps: [...input.completedSteps],
+        ...(input.mcpTools && Object.keys(input.mcpTools).length ? { mcpTools: input.mcpTools } : {}),
     };
 }
 /** Recompute the fingerprint and compare to a checkpoint. Any difference is drift. */
-export function reconcile(checkpoint, root, skills) {
+export function reconcile(checkpoint, root, skills, mcpTools) {
     const reasons = [];
     // Compare directly so an ADDITION (absent at capture, present now — e.g. git initialized, config
     // added) also counts as drift, not just a change to something already captured.
@@ -110,5 +111,16 @@ export function reconcile(checkpoint, root, skills) {
         else if (cur !== ver)
             reasons.push(`skill ${id} version changed (${ver} → ${cur})`);
     }
+    // Phase 3.5: an absent `mcpTools` means the checkpoint predates this dimension — "nothing to
+    // compare", never "everything changed". A tool that vanished is drift: the plan references it.
+    if (checkpoint.mcpTools) {
+        for (const [id, hash] of Object.entries(checkpoint.mcpTools)) {
+            const cur = mcpTools?.[id];
+            if (cur === undefined)
+                reasons.push(`MCP tool ${id} is no longer available`);
+            else if (cur !== hash)
+                reasons.push(`MCP tool ${id} changed shape`);
+        }
+    }
     return { drifted: reasons.length > 0, reasons };
 }

package/dist/executions/execution.d.ts

@@ -7,6 +7,7 @@
 import type { ExecutionPlan } from '../orchestration/plan.js';
 import type { StepObservation } from '../orchestration/executor.js';
 import type { ArtifactRef } from '../runtime/types.js';
+import type { AgentTaskRecord } from '../agents/task.js';
 export type ExecutionStatus = 'planned' | 'running' | 'paused' | 'waiting_for_input' | 'waiting_for_clarification' | 'completed' | 'failed' | 'cancelled';
 /** A time-boxed claim on an execution by one process. */
 export interface Lease {
@@ -23,12 +24,31 @@ export interface Checkpoint {
     configHash?: string;
     skillVersions: Record<string, string>;
     completedSteps: string[];
+    /** Phase 3.5: plan-referenced MCP tool id → a hash of its declaration at plan time. A server that
+     *  changed a tool's shape under a paused plan is drift, exactly like an edited file. Absent on every
+     *  pre-3.5 checkpoint, which reconcile must read as "nothing to compare", never as "everything changed". */
+    mcpTools?: Record<string, string>;
 }
-/** What an execution is waiting for (approval or clarification), persisted so a restart can resume it. */
+/** A plan's estimated vs available model-call budget (Phase 22), carried on a budget-paused execution. */
+export interface BudgetInfo {
+    /** Estimated model calls the plan needs (its skill steps). */
+    estCalls: number;
+    /** The call budget in force (`policy.maxCalls`). */
+    maxCalls: number;
+    /** Steps already completed (0 on a notify-before-start pause). */
+    completedSteps: number;
+    totalSteps: number;
+}
+/** What an execution is waiting for (approval / clarification / budget), persisted so a restart resumes it. */
 export interface PendingInput {
-    kind: 'approval' | 'clarification';
+    kind: 'approval' | 'clarification' | 'budget';
     question?: string;
     action?: string;
+    budget?: BudgetInfo;
+    /** Phase 3.5: set when the wait belongs to an AGENT's inner run. The answer is then routed into that
+     *  task's inner resume — appending it to the OUTER goal would replan and destroy every sibling's
+     *  progress. Absent ⇒ the wait is the outer run's, which is the pre-3.5 behaviour unchanged. */
+    agentTaskId?: string;
 }
 export interface Execution {
     id: string;
@@ -46,6 +66,20 @@ export interface Execution {
     createdAt: number;
     updatedAt: number;
     lease?: Lease;
+    /** Phase 3.5: budgeted step-calls charged across every run AND resume of this execution — the unit
+     *  `foldCalls` counts, NOT provider requests (planning calls are deliberately outside the pool).
+     *
+     *  ACCOUNTING, NOT A CAP. It is deliberately not subtracted from `maxCalls` on resume: `AI_MAX_CALLS`
+     *  bounds a RUN, and "raise it and resume" is how a partially-budgeted plan makes progress (Phase 22).
+     *  Treating it as a cumulative task ceiling would make `AI_MAX_CALLS=1` un-resumable — the first run
+     *  spends the whole allowance and every resume gets a budget of zero. See DECISIONS D132.
+     *  Optional because records written before 3.5 do not have it: always read `?? 0`. */
+    callsUsed?: number;
+    /** Phase 3.5: the agent tasks this execution owns, in creation order. Schema-validated on read. */
+    agentTasks?: AgentTaskRecord[];
+    /** Phase 3.5, diagnostic: how many persisted agent tasks failed validation on the last read. Counted
+     *  so a silently shrinking list is visible; the dropped records are never rendered as content. */
+    agentTasksDropped?: number;
 }
 export declare const RESUMABLE: ReadonlySet<ExecutionStatus>;
 export declare const TERMINAL: ReadonlySet<ExecutionStatus>;

package/dist/executions/store.d.ts

@@ -21,6 +21,26 @@ export interface AcquireResult {
     execution?: Execution;
     reason?: string;
 }
+/**
+ * Why a mid-run progress commit was accepted or refused (Phase 3.5).
+ *
+ * Every refusal means the same thing to the caller: SOMEONE ELSE now owns this execution's fate, and
+ * this process must stop — not retry, not carry on discarding writes. A run that keeps executing after a
+ * refused commit doubles every tool side effect and every model call while another owner re-runs the
+ * same steps, so the caller is required to abort. That is why this is an enum and not a boolean: a
+ * boolean invites an ignored return value at the call site, which is exactly the bug.
+ */
+export type CommitOutcome = 'ok'
+/** The record is gone from disk (deleted under us). */
+ | 'missing'
+/** Another owner holds the lease, or ours is gone — writing would clobber a live run. */
+ | 'foreign-lease'
+/** The lease was released out from under us. Never write leaseless: an unleased record is claimable. */
+ | 'released'
+/** Disk reached a terminal status. TERMINAL IS STICKY — a snapshot from before it may not undo it. */
+ | 'terminal'
+/** Someone paused us. `paused` is not terminal, but this owner cannot produce it, so it is not ours to overwrite. */
+ | 'paused';
 export declare class ExecutionStore {
     private readonly area;
     readonly owner: string;
@@ -42,6 +62,23 @@ export declare class ExecutionStore {
     /** Claim an execution. Fails if a DIFFERENT owner holds a live lease; steals an expired one. Re-reads
      * after writing to detect losing a concurrent steal (best-effort — no OS lock). */
     acquire(id: string): AcquireResult;
+    /**
+     * THE mid-run write (Phase 3.5). Every incremental commit point goes through here and nothing else
+     * writes an execution while a run is in flight, so all four ordering rules live in one place:
+     *
+     *  1. TERMINAL IS STICKY. A commit carries a snapshot taken before it was built; if the record reached
+     *     `completed`/`failed`/`cancelled` in the meantime, that verdict stands. Without this, a cancel is
+     *     undone by the next in-flight wave's commit milliseconds later.
+     *  2. `paused` IS NOT OURS TO OVERWRITE. A running owner never writes `paused`, so finding it on disk
+     *     means someone else did — and the pre-3.5 behaviour (clobber it at end of run) is far worse here,
+     *     because commits are frequent: the pause would be erased within one batch, before any heartbeat
+     *     tick could observe it.
+     *  3. NEVER WRITE LEASELESS. An unleased record is claimable by any process; writing one back without
+     *     a lease invites a second owner to acquire and re-run everything this owner is still doing.
+     *  4. THE DISK LEASE WINS. Lease bookkeeping belongs to acquire/heartbeat; a progress commit carries a
+     *     possibly-stale copy and must not push it back.
+     */
+    commitProgress(exec: Execution): CommitOutcome;
     /** Write only if we still hold the lease (or it's free/expired) — never clobber a live different owner. */
     commit(exec: Execution): boolean;
     /** Renew this owner's lease. Returns false if we no longer hold it. */

package/dist/executions/store.js

@@ -9,6 +9,7 @@
  */
 import { hostname } from 'node:os';
 import { systemClock } from '../util/clock.js';
+import { TERMINAL } from './execution.js';
 export class ExecutionStore {
     area;
     owner;
@@ -85,6 +86,38 @@ export class ExecutionStore {
             return { ok: false, reason: 'lost the acquire race' };
         return { ok: true, execution: confirmed };
     }
+    /**
+     * THE mid-run write (Phase 3.5). Every incremental commit point goes through here and nothing else
+     * writes an execution while a run is in flight, so all four ordering rules live in one place:
+     *
+     *  1. TERMINAL IS STICKY. A commit carries a snapshot taken before it was built; if the record reached
+     *     `completed`/`failed`/`cancelled` in the meantime, that verdict stands. Without this, a cancel is
+     *     undone by the next in-flight wave's commit milliseconds later.
+     *  2. `paused` IS NOT OURS TO OVERWRITE. A running owner never writes `paused`, so finding it on disk
+     *     means someone else did — and the pre-3.5 behaviour (clobber it at end of run) is far worse here,
+     *     because commits are frequent: the pause would be erased within one batch, before any heartbeat
+     *     tick could observe it.
+     *  3. NEVER WRITE LEASELESS. An unleased record is claimable by any process; writing one back without
+     *     a lease invites a second owner to acquire and re-run everything this owner is still doing.
+     *  4. THE DISK LEASE WINS. Lease bookkeeping belongs to acquire/heartbeat; a progress commit carries a
+     *     possibly-stale copy and must not push it back.
+     */
+    commitProgress(exec) {
+        const disk = this.get(exec.id);
+        if (!disk)
+            return 'missing';
+        if (TERMINAL.has(disk.status))
+            return 'terminal';
+        if (disk.status === 'paused' && exec.status !== 'paused')
+            return 'paused';
+        if (!disk.lease)
+            return 'released';
+        if (disk.lease.owner !== this.owner)
+            return 'foreign-lease';
+        exec.lease = disk.lease;
+        this.save(exec);
+        return 'ok';
+    }
     /** Write only if we still hold the lease (or it's free/expired) — never clobber a live different owner. */
     commit(exec) {
         const disk = this.get(exec.id);

package/dist/generation/generateAdapter.d.ts

@@ -6,6 +6,7 @@
  */
 import { type OpenApiAnalysis } from '../discovery/openapi.js';
 import type { ProviderConfig } from '../types.js';
+import type { AI } from '../plugin/ai.js';
 export interface GenerateOptions {
     id?: string;
     apiKeyEnv?: string;
@@ -15,3 +16,16 @@ export interface GenerateOptions {
 /** Turn an OpenAPI analysis into a ProviderConfig. Throws if the spec yielded no usable mapping. */
 export declare function generateProviderConfig(analysis: OpenApiAnalysis, overrides?: GenerateOptions): ProviderConfig;
 export declare function generateProviderConfigFromFile(specPath: string, overrides?: GenerateOptions): ProviderConfig;
+export interface SuggestResult {
+    ok: boolean;
+    config?: ProviderConfig;
+    error?: string;
+}
+/**
+ * AI-assisted adapter rung (Phase 21a) — an opt-in gap-filler on top of the DETERMINISTIC
+ * `generateProviderConfig`. When the spec doesn't enumerate models, a model proposes a likely model-id
+ * list; the OUTPUT is STILL produced by `generateProviderConfig` (a validated `ProviderConfig`, never code),
+ * so a bad suggestion can only propose model-id strings the operator then confirms — it can never inject an
+ * unvalidated config. Any model/parse failure falls back to the deterministic result (or its error).
+ */
+export declare function suggestProviderConfig(analysis: OpenApiAnalysis, ai: AI, overrides?: GenerateOptions): Promise<SuggestResult>;

package/dist/generation/generateAdapter.js

@@ -6,6 +6,8 @@
  */
 import { AIError } from '../core/fallback/errors.js';
 import { analyzeOpenApiFile } from '../discovery/openapi.js';
+import { extractJson } from '../util/extractJson.js';
+import { wrapUntrusted } from '../tools/untrusted.js';
 /** Turn an OpenAPI analysis into a ProviderConfig. Throws if the spec yielded no usable mapping. */
 export function generateProviderConfig(analysis, overrides = {}) {
     const base = analysis.suggestedProviderConfig;
@@ -28,3 +30,39 @@ export function generateProviderConfig(analysis, overrides = {}) {
 export function generateProviderConfigFromFile(specPath, overrides = {}) {
     return generateProviderConfig(analyzeOpenApiFile(specPath), overrides);
 }
+/**
+ * AI-assisted adapter rung (Phase 21a) — an opt-in gap-filler on top of the DETERMINISTIC
+ * `generateProviderConfig`. When the spec doesn't enumerate models, a model proposes a likely model-id
+ * list; the OUTPUT is STILL produced by `generateProviderConfig` (a validated `ProviderConfig`, never code),
+ * so a bad suggestion can only propose model-id strings the operator then confirms — it can never inject an
+ * unvalidated config. Any model/parse failure falls back to the deterministic result (or its error).
+ */
+export async function suggestProviderConfig(analysis, ai, overrides = {}) {
+    let modelList = Array.isArray(overrides.models) ? overrides.models : [];
+    // Only consult the model when we actually have a gap to fill (no explicit models, none in the spec).
+    const specModels = analysis.suggestedProviderConfig?.models;
+    const needsModels = modelList.length === 0 && (specModels === undefined || specModels === 'auto');
+    if (needsModels) {
+        try {
+            const prompt = `An OpenAPI spec describes an AI provider. Suggest the model IDs it most likely exposes for chat/completions. ` +
+                `Reply ONLY with JSON: {"models": ["<model-id>", ...]}.\n\n` +
+                wrapUntrusted('openapi-summary', `title: ${analysis.title ?? '(unknown)'}\nbaseUrl: ${analysis.baseUrl ?? '(unknown)'}\nwireShape: ${analysis.wireShape}\nendpoints: ${analysis.endpoints.map((e) => e.path).slice(0, 20).join(', ')}`);
+            const run = await ai.run({ task: 'suggest-provider-config', input: prompt, output: { format: 'json' }, requirements: { intelligence: ['reasoning'], output: ['json'] } });
+            if (run.ok && run.response) {
+                const parsed = (run.response.json ?? extractJson(run.response.text ?? ''));
+                if (Array.isArray(parsed?.models))
+                    modelList = parsed.models.filter((m) => typeof m === 'string' && m.trim().length > 0);
+            }
+        }
+        catch {
+            /* a suggestion failure just falls through to the deterministic path */
+        }
+    }
+    try {
+        const config = generateProviderConfig(analysis, { ...overrides, ...(modelList.length && !overrides.models ? { models: modelList } : {}) });
+        return { ok: true, config };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/generation/generateSkill.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Skill scaffolding (Phase 21a) — the generative seam for skills, mirroring `generateAdapter`'s
+ * "emit validated CONFIG/manifest, never code" rule. A model drafts a `*.skill.yaml` MANIFEST (pure data,
+ * parsed by the existing `parseManifest`); we then validate it three ways before offering it:
+ *   1. `parseManifest` (shape),
+ *   2. every step names an AVAILABLE tool (a `validatePlan`-style membership check — no invented tools),
+ *   3. a dry `manifestToSkill` compile (it must not throw).
+ * Nothing is written here — the caller writes it only on explicit confirm into the consented
+ * `.ai-runtime/skills/` directory. A drafted manifest that fails any check is refused with a reason.
+ */
+import type { AI } from '../plugin/ai.js';
+import { type SkillManifest } from '../skills/manifest.js';
+export interface GenerateSkillInput {
+    goal: string;
+    /** Tool ids the drafted manifest may use (the host's registered tools). */
+    tools: string[];
+    ai: AI;
+}
+export interface GenerateSkillResult {
+    ok: boolean;
+    manifest?: SkillManifest;
+    /** The manifest serialized as `*.skill.yaml`, ready to write on confirm. */
+    yaml?: string;
+    error?: string;
+}
+export declare function generateSkillManifest(input: GenerateSkillInput): Promise<GenerateSkillResult>;

package/dist/generation/generateSkill.js

@@ -0,0 +1,51 @@
+/**
+ * Skill scaffolding (Phase 21a) — the generative seam for skills, mirroring `generateAdapter`'s
+ * "emit validated CONFIG/manifest, never code" rule. A model drafts a `*.skill.yaml` MANIFEST (pure data,
+ * parsed by the existing `parseManifest`); we then validate it three ways before offering it:
+ *   1. `parseManifest` (shape),
+ *   2. every step names an AVAILABLE tool (a `validatePlan`-style membership check — no invented tools),
+ *   3. a dry `manifestToSkill` compile (it must not throw).
+ * Nothing is written here — the caller writes it only on explicit confirm into the consented
+ * `.ai-runtime/skills/` directory. A drafted manifest that fails any check is refused with a reason.
+ */
+import { stringify as toYaml } from 'yaml';
+import { parseManifest, manifestToSkill } from '../skills/manifest.js';
+import { wrapUntrusted } from '../tools/untrusted.js';
+import { extractJson } from '../util/extractJson.js';
+export async function generateSkillManifest(input) {
+    const goal = String(input.goal ?? '').trim();
+    if (!goal)
+        return { ok: false, error: 'a goal is required' };
+    const tools = input.tools ?? [];
+    if (tools.length === 0)
+        return { ok: false, error: 'no tools are available to compose a skill from' };
+    const prompt = `Draft an ai-runtime skill MANIFEST (pure data — NOT code) that achieves the goal below. ` +
+        `The manifest runs a sequence of tool steps. Use ONLY these registered tools: ${tools.join(', ')}.\n\n` +
+        `Goal:\n${wrapUntrusted('scaffold-goal', goal)}\n\n` +
+        `Reply ONLY with JSON of this exact shape: {"id":"<kebab-case-id>","version":"1.0.0","name":"<short name>",` +
+        `"description":"<one line>","runtimeCompatibility":">=1.0.0","steps":[{"tool":"<one of the tools>","description":"<what this step does>"}]}.`;
+    // The whole model round-trip is wrapped: a bad model reply (e.g. non-JSON, which makes `extractJson`
+    // throw) must surface as { ok:false }, never as a thrown error — scaffolding is an assist, not a hard op.
+    try {
+        const run = await input.ai.run({ task: 'generate-skill', input: prompt, output: { format: 'json' }, requirements: { intelligence: ['reasoning'], output: ['json'] } });
+        if (!run.ok || !run.response)
+            return { ok: false, error: `generation failed (${run.error?.category ?? 'no response'})` };
+        const raw = run.response.json ?? extractJson(run.response.text ?? '');
+        const { manifest, error } = parseManifest(raw);
+        if (!manifest)
+            return { ok: false, error: `drafted manifest is invalid: ${error ?? 'unparseable'}` };
+        // Membership: a drafted step may only name a tool the host actually has (no invented capabilities).
+        const unknown = [...new Set(manifest.steps.map((s) => s.tool).filter((t) => !tools.includes(t)))];
+        if (unknown.length)
+            return { ok: false, error: `manifest names unregistered tool(s): ${unknown.join(', ')}` };
+        // A safe, filesystem-friendly id (also the filename); reject anything that could escape the skills dir.
+        if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(manifest.id))
+            return { ok: false, error: `manifest id must be kebab-case ([a-z0-9-]): got ${JSON.stringify(manifest.id)}` };
+        // Dry compile — the manifest must produce a runnable Skill without throwing.
+        manifestToSkill(manifest, '(scaffold)');
+        return { ok: true, manifest, yaml: toYaml(manifest) };
+    }
+    catch (e) {
+        return { ok: false, error: `could not scaffold a skill: ${e instanceof Error ? e.message : String(e)}` };
+    }
+}

package/dist/index.d.ts

@@ -44,14 +44,20 @@ export { analyzeOpenApi, analyzeOpenApiFile } from './discovery/openapi.js';
 export type { OpenApiAnalysis } from './discovery/openapi.js';
 export { benchmark } from './benchmark/benchmark.js';
 export type { BenchResult, BenchTaskSpec } from './benchmark/benchmark.js';
-export { generateProviderConfig, generateProviderConfigFromFile } from './generation/generateAdapter.js';
-export type { GenerateOptions } from './generation/generateAdapter.js';
+export { generateProviderConfig, generateProviderConfigFromFile, suggestProviderConfig } from './generation/generateAdapter.js';
+export type { GenerateOptions, SuggestResult } from './generation/generateAdapter.js';
+export { generateSkillManifest } from './generation/generateSkill.js';
+export type { GenerateSkillInput, GenerateSkillResult } from './generation/generateSkill.js';
 export { McpRegistry, StaticMcpSource } from './mcp/mcp.js';
 export type { McpToolSource } from './mcp/mcp.js';
 export { setCredentialResolver, Credential } from './security/credentials.js';
 export type { CredentialResolver } from './security/credentials.js';
 export { CallbackSink, MemorySink, MultiSink, NullSink } from './telemetry/telemetry.js';
 export type { TelemetrySink } from './telemetry/telemetry.js';
+export { FileSink } from './telemetry/sinks/file.js';
+export { OtlpSink } from './telemetry/sinks/otlp.js';
+export type { OtlpSinkOptions } from './telemetry/sinks/otlp.js';
+export { KeyedSemaphore } from './util/semaphore.js';
 export { MARKETPLACE, listPresets, findPreset, presetToConfig } from './marketplace/presets.js';
 export type { ProviderPreset } from './marketplace/presets.js';
 export { loadRemoteConfig, loadConfigAsync } from './config/load.js';
@@ -64,6 +70,7 @@ export { resolvePolicy, defaultAutonomyForMode } from './runtime/policy.js';
 export type { ExecutionPolicy, PermissionPolicy, Autonomy, ApprovalLevel, PolicyOverrides } from './runtime/policy.js';
 export { parseRuntimeConfig, loadRuntimeConfig, findRuntimeConfigFile } from './runtime/config.js';
 export { HeuristicIntentClassifier } from './runtime/intent/classifier.js';
+export { AIIntentClassifier } from './runtime/intent/aiClassifier.js';
 export type { IntentClassifier, IntentClassification, IntentInput } from './runtime/intent/classifier.js';
 export { detectWorkspace, summarizeWorkspace } from './runtime/workspace/workspace.js';
 export type { WorkspaceInfo } from './runtime/workspace/workspace.js';
@@ -77,8 +84,33 @@ export type { AccessState, ProviderView, ModelView, ProviderViewSource } from '.
 export { RuntimeStore, STORE_VERSION } from './store/store.js';
 export type { RuntimeStoreOptions, StorePaths } from './store/store.js';
 export { FileArea, NullArea } from './store/area.js';
-export type { Area, IntegrityIssue } from './store/area.js';
-export { resolveHome, projectId, repositoryId, findRepoRoot } from './store/paths.js';
+export type { Area, IntegrityIssue, ContentCodec } from './store/area.js';
+export { makeCodec, deriveKey, encryptString, decryptString, ENVELOPE_PREFIX } from './store/crypto.js';
+export { resolveHome, projectId, repositoryId, organizationId, findRepoRoot } from './store/paths.js';
+export { deriveCapabilities, deriveCapabilitiesOffline, candidatesFrom, candidateSlate, DERIVE_MAX_CANDIDATES, DERIVE_MAX_IDS } from './runtime/planning/deriveCapabilities.js';
+export type { CapabilityCandidate, DeriveCapabilitiesInput, DeriveCapabilitiesResult } from './runtime/planning/deriveCapabilities.js';
+export { ActionCapabilityRegistry, capabilityReportFrom } from './capabilities/registry.js';
+export type { ActionCapabilityQuery, CapabilityConfig, RegistryAccessors } from './capabilities/registry.js';
+export { CURATED_VOCABULARY, curated, isCurated } from './capabilities/vocabulary.js';
+export type { CuratedCapability, PermissionHint } from './capabilities/vocabulary.js';
+export type { ActionCapability, ActionCapabilityDecl, ActionCapabilityEffect, ActionCapabilityProvider, ActionCapabilitySource, CapabilityGap, CapabilityGapReason, CapabilityResolution, GapSuggestion, MissingCapabilityReport, ProviderAvailability, } from './capabilities/capability.js';
+export type { AgentDefinition } from './agents/definition.js';
+export type { AgentEnvelope } from './agents/envelope.js';
+export type { AgentTaskRecord, AgentTaskState } from './agents/task.js';
+export type { Finding, FindingEvidence, FindingEvidenceKind, FindingStatus } from './agents/finding.js';
+export type { AdmissionRejection, AdmissionResult } from './agents/admit.js';
+export type { StepObservationCode } from './orchestration/executor.js';
+export { PLAN_STEP_STATUSES } from './orchestration/plan.js';
+export { parseAgentTasks, findAgentTask } from './executions/agentTasks.js';
+export type { AgentTaskView } from './executions/agentTasks.js';
+export { AGENT_TERMINAL, AGENT_RESUMABLE } from './agents/task.js';
+export type { ProgressSnapshot } from './orchestration/executor.js';
+export { mcpToolId } from './mcp/toolAdapter.js';
+export { MCP_PROTOCOL_VERSION } from './mcp/protocol.js';
+export type { McpServerConfig, McpServerState, McpServerStatus, McpTransportKind } from './mcp/manager.js';
+export type { McpServerSettings } from './runtime/types.js';
+export type { McpServerGrant } from './tools/permissions.js';
+export { clampMcpPermissions, clampPermissions } from './tools/permissions.js';
 export type { StoreScope } from './store/paths.js';
 export { ConversationStore } from './conversations/conversations.js';
 export type { ConversationTurn, ConversationMeta, TurnRole } from './conversations/conversations.js';
@@ -87,9 +119,18 @@ export type { MemoryRecord, MemoryScope, MemorySource, RememberInput, SearchOpti
 export { classifyMemory } from './memory/classifier.js';
 export type { MemoryCandidate } from './memory/classifier.js';
 export { bm25Search, tokenize } from './memory/bm25.js';
+export { cosineSimilarity, semanticRank } from './memory/semantic.js';
+export type { VecDoc, RankedHit } from './memory/semantic.js';
+export { HashEmbedder } from './memory/embedders/hash.js';
+export { HttpEmbedder } from './memory/embedders/http.js';
+export type { HttpEmbedderConfig } from './memory/embedders/http.js';
 export type { MemoryTrace } from './runtime/types.js';
 export { compileContext } from './context/compiler.js';
 export type { ContextBlock, CompiledBlock, CompiledContext, CompileMetrics, CompileOptions, ContextValidation, RetentionLevel } from './context/compiler.js';
+export { verifyContextLoss } from './context/lossVerifier.js';
+export type { VerifyLossInput, LossCheck } from './context/lossVerifier.js';
+export { summarizeOverBudget } from './context/summarize.js';
+export type { SummarizeInput } from './context/summarize.js';
 export { TokenEstimator, estimateTokens } from './context/tokens.js';
 export { resolveContextBudget, DEFAULT_CONTEXT_TOKENS } from './context/budget.js';
 export type { ContextBudgetInputs } from './context/budget.js';
@@ -141,6 +182,8 @@ export type { LearningOutcome, LearnedStat, SkillRef } from './learning/learning
 export { classifyFeedback } from './learning/feedback.js';
 export type { FeedbackSignal } from './learning/feedback.js';
 export { resolveRoutingPrefs, withPreferredProviders } from './runtime/routing.js';
+export { parseModelProfile, parseDirective, resolveModelDirective, directiveToOverrides, loadModelProfile } from './runtime/models/modelProfile.js';
+export type { ModelProfile, ModelDirective } from './runtime/models/modelProfile.js';
 export type { RoutingSources } from './runtime/routing.js';
 export { isExcluded, isPreferred } from './core/router/routingPrefs.js';
 export type { RoutingPreferences } from './types.js';