@basaltkit/ai 1.0.0 → 1.1.0

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://basaltkit-docs.pages.dev">
+    <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440">
+  </a>
+</p>
+
 # @basaltkit/ai
 
 AI-native developer experience for Basalt. A provider-agnostic engine plus a

package/dist/analysis.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Framework-free read-only surface: project detection, analysis, diagnostics
+ * (with in-memory fix previews) and the BasaltKit architectural knowledge —
+ * WITHOUT the `basalt ai` CLI command wiring, which imports `@basaltkit/cli`
+ * (→ `@basaltkit/core`). The main barrel (`@basaltkit/ai`) re-exports `aiCommands`
+ * and therefore transitively loads the framework runtime; this subpath does not.
+ *
+ * It exists so out-of-process, dev-only consumers — notably the `@basaltkit/ai-mcp`
+ * bridge — can use analyze/doctor/context without pulling `@basaltkit/core` or
+ * `@basaltkit/http` into their dependency graph. Everything here is also exported
+ * from the main barrel; this is a boundary-preserving subset, not a new API.
+ */
+export { detectProject, nodeReader, memoryReader, type AppFileInfo, type DetectedStack, type EnvFileInfo, type PrismaInfo, type PrismaModel, type ProjectContext, type ProjectReader, type ServerFileInfo, } from './context/project.js';
+export { analyze, type AnalysisReport } from './analyze/run.js';
+export { hasErrors, runDoctor } from './doctor/run.js';
+export { DEFAULT_RULES } from './doctor/rules.js';
+export { defineRule, type Diagnostic, type DiagnosticCategory, type DoctorRule, type Severity, } from './doctor/types.js';
+export { fixableIds, planFix, type FileEdit, type FixOutcome, type FixStatus, } from './doctor/fixes.js';
+export { BASALT_KNOWLEDGE } from './plan/knowledge.js';

package/dist/analysis.js

@@ -0,0 +1,24 @@
+/**
+ * Framework-free read-only surface: project detection, analysis, diagnostics
+ * (with in-memory fix previews) and the BasaltKit architectural knowledge —
+ * WITHOUT the `basalt ai` CLI command wiring, which imports `@basaltkit/cli`
+ * (→ `@basaltkit/core`). The main barrel (`@basaltkit/ai`) re-exports `aiCommands`
+ * and therefore transitively loads the framework runtime; this subpath does not.
+ *
+ * It exists so out-of-process, dev-only consumers — notably the `@basaltkit/ai-mcp`
+ * bridge — can use analyze/doctor/context without pulling `@basaltkit/core` or
+ * `@basaltkit/http` into their dependency graph. Everything here is also exported
+ * from the main barrel; this is a boundary-preserving subset, not a new API.
+ */
+// Project context — stack/schema/config detection.
+export { detectProject, nodeReader, memoryReader, } from './context/project.js';
+// Analysis report.
+export { analyze } from './analyze/run.js';
+// Diagnostics engine.
+export { hasErrors, runDoctor } from './doctor/run.js';
+export { DEFAULT_RULES } from './doctor/rules.js';
+export { defineRule, } from './doctor/types.js';
+// Fix previews — computed in memory; `planFix` never writes to disk.
+export { fixableIds, planFix, } from './doctor/fixes.js';
+// The framework conventions the planner is grounded in.
+export { BASALT_KNOWLEDGE } from './plan/knowledge.js';

package/dist/generate.d.ts

@@ -0,0 +1,43 @@
+import { abortError, isAbortError, throwIfAborted } from './provider/abort.js';
+import type { AIProvider, GenerateOptions } from './provider/types.js';
+/**
+ * A progress event from a long-running workflow step. `chunk`/`text` carry
+ * streamed model output (streaming generations); `message` carries a coarse
+ * status (e.g. a `make` phase). All fields optional so a consumer maps whatever
+ * is present onto its own progress surface (e.g. MCP `notifications/progress`).
+ */
+export interface WorkflowProgress {
+    /** A short human-readable status. */
+    message?: string;
+    /** The newest streamed text fragment. */
+    chunk?: string;
+    /** All model text received so far. */
+    text?: string;
+}
+export type OnProgress = (progress: WorkflowProgress) => void;
+/** Cross-cutting options threaded through the workflow engine. */
+export interface WorkflowRunOptions {
+    /** Abort the operation. Forwarded to the provider's fetch and raced at this layer. */
+    signal?: AbortSignal;
+    /** Receive progress as it happens. When set, streaming providers stream. */
+    onProgress?: OnProgress;
+}
+/**
+ * Run a provider completion. With `onProgress`, consume `provider.stream` and
+ * emit each fragment (real token streaming where the provider supports it; a
+ * single final chunk otherwise). Without it, the one-shot `provider.generate`
+ * path is used unchanged.
+ */
+export declare function generateText(provider: AIProvider, options: GenerateOptions, onProgress?: OnProgress): Promise<string>;
+/**
+ * Race a task against an abort signal so cancellation is prompt even if the
+ * underlying provider doesn't honour the signal itself.
+ */
+export declare function withAbort<T>(signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T>;
+/**
+ * Provider generation with optional streaming (`onProgress`) and cancellation
+ * (`signal`) — the single seam the workflow steps call so signal + progress are
+ * threaded consistently.
+ */
+export declare function runGeneration(provider: AIProvider, options: GenerateOptions, run?: WorkflowRunOptions): Promise<string>;
+export { abortError, isAbortError, throwIfAborted };

package/dist/generate.js

@@ -0,0 +1,46 @@
+import { abortError, isAbortError, throwIfAborted } from './provider/abort.js';
+/**
+ * Run a provider completion. With `onProgress`, consume `provider.stream` and
+ * emit each fragment (real token streaming where the provider supports it; a
+ * single final chunk otherwise). Without it, the one-shot `provider.generate`
+ * path is used unchanged.
+ */
+export async function generateText(provider, options, onProgress) {
+    if (!onProgress)
+        return provider.generate(options);
+    let text = '';
+    for await (const chunk of provider.stream(options)) {
+        if (!chunk)
+            continue;
+        text += chunk;
+        onProgress({ chunk, text });
+    }
+    return text;
+}
+/**
+ * Race a task against an abort signal so cancellation is prompt even if the
+ * underlying provider doesn't honour the signal itself.
+ */
+export async function withAbort(signal, run) {
+    if (!signal)
+        return run();
+    throwIfAborted(signal);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        void Promise.resolve()
+            .then(run)
+            .then(resolve, reject)
+            .finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+/**
+ * Provider generation with optional streaming (`onProgress`) and cancellation
+ * (`signal`) — the single seam the workflow steps call so signal + progress are
+ * threaded consistently.
+ */
+export function runGeneration(provider, options, run = {}) {
+    const genOptions = run.signal ? { ...options, signal: run.signal } : options;
+    return withAbort(run.signal, () => generateText(provider, genOptions, run.onProgress));
+}
+export { abortError, isAbortError, throwIfAborted };

package/dist/index.d.ts

@@ -4,7 +4,8 @@ export { OllamaProvider, type OllamaProviderOptions } from './provider/ollama.js
 export { OpenAICompatibleProvider, type OpenAICompatibleProviderOptions, } from './provider/openai.js';
 export { fetchWithRetry, type RetryOptions } from './provider/http.js';
 export { globalSseFetch, parseSseContent, type SseFetch, type SseResponse } from './provider/sse.js';
-export { createProvider, providerEnvFromProcess, type CreateProviderOptions, type ProviderEnv, type ProviderName, } from './provider/factory.js';
+export { createProvider, providerEnvFrom, providerEnvFromProcess, type CreateProviderOptions, type ProviderEnv, type ProviderName, } from './provider/factory.js';
+export { runGeneration, generateText, withAbort, throwIfAborted, abortError, isAbortError, type OnProgress, type WorkflowProgress, type WorkflowRunOptions, } from './generate.js';
 export { detectProject, nodeReader, memoryReader, type AppFileInfo, type DetectedStack, type EnvFileInfo, type PrismaInfo, type PrismaModel, type ProjectContext, type ProjectReader, type ServerFileInfo, } from './context/project.js';
 export { defineRule, type Diagnostic, type DiagnosticCategory, type DoctorRule, type Severity, } from './doctor/types.js';
 export { DEFAULT_RULES } from './doctor/rules.js';
@@ -26,10 +27,11 @@ export { injectOpenApiMeta } from './make/openapi.js';
 export { externalRelationTargets, foreignKey, injectPrismaRelations, inverseRelationLines, relationFieldLines, relationForeignKeys, } from './make/relations.js';
 export { injectAuditPlugin, injectAuditService, injectPermissionGuards } from './make/wire.js';
 export { extractModelBlock, mergeModelsIntoSchema, runPrismaPush, type ModelBlock, } from './make/schema.js';
-export type { MakeOptions, MakeResult, Migration, ResourceBuild, ReviewItem, ReviewResult, ReviewStatus, SchemaMerge, } from './make/types.js';
+export type { MakeOptions, MakeResult, MakePreview, FilePreview, Migration, ResourceBuild, ReviewItem, ReviewResult, ReviewStatus, SchemaMerge, } from './make/types.js';
 export { buildReviewContext, parseReview, reviewImplementation, type ReviewOptions } from './review/review.js';
 export { REVIEW_KNOWLEDGE } from './review/knowledge.js';
 export { renderAgentReview } from './review/render.js';
 export type { AgentReview, ReviewIssue } from './review/types.js';
 export { renderAnalysis, renderDoctor, type LineWriter } from './render.js';
 export { aiCommands, type AiCommandsOptions } from './commands.js';
+export { PLAN_SCHEMA_VERSION, MAKE_SCHEMA_VERSION, toJsonSchema, ArchitecturePlanSchema, MakeResultSchema, AnalysisReportSchema, ProjectContextSchema, AgentReviewSchema, DiagnosticSchema, DetectedStackSchema, } from './schema/index.js';

package/dist/index.js

@@ -5,7 +5,9 @@ export { OllamaProvider } from './provider/ollama.js';
 export { OpenAICompatibleProvider, } from './provider/openai.js';
 export { fetchWithRetry } from './provider/http.js';
 export { globalSseFetch, parseSseContent } from './provider/sse.js';
-export { createProvider, providerEnvFromProcess, } from './provider/factory.js';
+export { createProvider, providerEnvFrom, providerEnvFromProcess, } from './provider/factory.js';
+// Workflow progress + cancellation (spec §D.1(2)).
+export { runGeneration, generateText, withAbort, throwIfAborted, abortError, isAbortError, } from './generate.js';
 // Project context — stack/schema/config detection (spec §18, Context Engineering).
 export { detectProject, nodeReader, memoryReader, } from './context/project.js';
 // Diagnostics engine (spec §6, Doctor).
@@ -38,3 +40,6 @@ export { renderAgentReview } from './review/render.js';
 // Rendering + CLI wiring.
 export { renderAnalysis, renderDoctor } from './render.js';
 export { aiCommands } from './commands.js';
+// Runtime schemas + JSON Schema derivation for the public data contracts (also
+// available at the `@basaltkit/ai/schema` subpath).
+export { PLAN_SCHEMA_VERSION, MAKE_SCHEMA_VERSION, toJsonSchema, ArchitecturePlanSchema, MakeResultSchema, AnalysisReportSchema, ProjectContextSchema, AgentReviewSchema, DiagnosticSchema, DetectedStackSchema, } from './schema/index.js';

package/dist/make/diff.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A minimal, dependency-free unified-diff generator for the safe-make preview.
+ * Line-based LCS with configurable context — enough to show an agent exactly
+ * what a write would change (empty `oldText` → an all-additions "new file" diff).
+ */
+/**
+ * Produce a unified diff of `oldText` → `newText` labelled with `path`.
+ * Returns '' when the texts are identical.
+ */
+export declare function unifiedDiff(oldText: string, newText: string, path: string, context?: number): string;

package/dist/make/diff.js

@@ -0,0 +1,120 @@
+/**
+ * A minimal, dependency-free unified-diff generator for the safe-make preview.
+ * Line-based LCS with configurable context — enough to show an agent exactly
+ * what a write would change (empty `oldText` → an all-additions "new file" diff).
+ */
+/** Compute the length table of the longest common subsequence of two line arrays. */
+function lcsLengths(a, b) {
+    const table = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    return table;
+}
+/** Backtrack the LCS table into an edit script over lines. */
+function editScript(a, b) {
+    const table = lcsLengths(a, b);
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            ops.push({ kind: 'eq', line: a[i] });
+            i++;
+            j++;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1]) {
+            ops.push({ kind: 'del', line: a[i] });
+            i++;
+        }
+        else {
+            ops.push({ kind: 'add', line: b[j] });
+            j++;
+        }
+    }
+    while (i < a.length)
+        ops.push({ kind: 'del', line: a[i++] });
+    while (j < b.length)
+        ops.push({ kind: 'add', line: b[j++] });
+    return ops;
+}
+/** Split into lines without a trailing empty element for a final newline. */
+function toLines(text) {
+    if (text === '')
+        return [];
+    const lines = text.split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    return lines;
+}
+/**
+ * Produce a unified diff of `oldText` → `newText` labelled with `path`.
+ * Returns '' when the texts are identical.
+ */
+export function unifiedDiff(oldText, newText, path, context = 3) {
+    if (oldText === newText)
+        return '';
+    const a = toLines(oldText);
+    const b = toLines(newText);
+    const ops = editScript(a, b);
+    const hunks = [];
+    let aLine = 0;
+    let bLine = 0;
+    let current = null;
+    let trailingEq = 0;
+    const flushIfIdle = () => {
+        if (current && trailingEq > context) {
+            // trim the surplus trailing context off the current hunk
+            const surplus = trailingEq - context;
+            current.lines.splice(current.lines.length - surplus);
+            current.aCount -= surplus;
+            current.bCount -= surplus;
+            hunks.push(current);
+            current = null;
+            trailingEq = 0;
+        }
+    };
+    for (const op of ops) {
+        if (op.kind === 'eq') {
+            if (current) {
+                current.lines.push(` ${op.line}`);
+                current.aCount++;
+                current.bCount++;
+                trailingEq++;
+                flushIfIdle();
+            }
+            aLine++;
+            bLine++;
+        }
+        else {
+            if (!current) {
+                const lead = Math.min(context, /* leading context available */ Math.min(aLine, bLine));
+                current = { aStart: aLine - lead + 1, bStart: bLine - lead + 1, lines: [], aCount: lead, bCount: lead };
+                // pull the leading context lines back in
+                const leadLines = a.slice(aLine - lead, aLine).map((l) => ` ${l}`);
+                current.lines.push(...leadLines);
+            }
+            trailingEq = 0;
+            if (op.kind === 'del') {
+                current.lines.push(`-${op.line}`);
+                current.aCount++;
+                aLine++;
+            }
+            else {
+                current.lines.push(`+${op.line}`);
+                current.bCount++;
+                bLine++;
+            }
+        }
+    }
+    if (current)
+        hunks.push(current);
+    const out = [`--- a/${path}`, `+++ b/${path}`];
+    for (const h of hunks) {
+        out.push(`@@ -${h.aStart},${h.aCount} +${h.bStart},${h.bCount} @@`);
+        out.push(...h.lines);
+    }
+    return out.join('\n');
+}

package/dist/make/make.js

@@ -1,4 +1,9 @@
-import { FileExistsError, generateResource, names, registerResourceInApp, writeGenerated, } from '@basaltkit/generator';
+import { FileExistsError, generateResource, names, registerResourceInApp, writeGenerated, } from '@basaltkit/generator/resource';
+import { MAKE_SCHEMA_VERSION } from '../schema/index.js';
+import { throwIfAborted } from '../generate.js';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { unifiedDiff } from './diff.js';
 import { domainFields, injectPrismaFields, injectZodFields } from './fields.js';
 import { externalRelationTargets, injectPrismaRelations, inverseRelationLines, relationFieldLines, relationForeignKeys, } from './relations.js';
 import { injectOpenApiMeta } from './openapi.js';
@@ -21,10 +26,13 @@ export async function runMake(ctx, plan, options = {}) {
     if (entities.length === 0) {
         throw new Error('ai:make — the plan has no entity to generate.');
     }
+    throwIfAborted(options.signal);
     const baseDir = options.baseDir ?? process.cwd();
     const prismaDefault = ctx.stack.orm === 'prisma';
     const resources = [];
     for (const entity of entities) {
+        throwIfAborted(options.signal);
+        options.onProgress?.({ message: `Building ${entity.name}…` });
         const gen = findGeneratorCommand(plan, entity.name);
         const prisma = options.prisma ?? gen?.prisma ?? prismaDefault;
         const softDelete = options.softDelete ?? gen?.softDelete ?? false;
@@ -69,7 +77,11 @@ export async function runMake(ctx, plan, options = {}) {
     const { schema, migration } = await mergeSchema(resources, baseDir, options);
     const followUps = buildFollowUps(plan, resources, schema, migration);
     const review = reviewBuild(ctx, plan, resources, schema, migration);
+    // Safe preview (dry-run only): stat every target and attach a unified diff, so a
+    // caller sees exactly what an apply would create/overwrite before anything is written.
+    const preview = options.dryRun ? await buildPreview(resources, baseDir) : undefined;
     return {
+        schemaVersion: MAKE_SCHEMA_VERSION,
         request: plan.request,
         dryRun: options.dryRun === true,
         resources,
@@ -77,6 +89,7 @@ export async function runMake(ctx, plan, options = {}) {
         ...(migration ? { migration } : {}),
         followUps,
         review,
+        ...(preview ? { preview } : {}),
     };
 }
 async function mergeSchema(resources, baseDir, options) {
@@ -308,6 +321,29 @@ function hasTenantId(resource) {
         return false;
     return /^[ \t]*tenantId[ \t]+/m.test(model.content);
 }
+async function readFileOrNull(target) {
+    try {
+        return await readFile(target, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** Stat every generated file and build a per-file plan (create|overwrite) with a unified diff. */
+async function buildPreview(resources, baseDir) {
+    const perFile = [];
+    const clashes = [];
+    for (const resource of resources) {
+        for (const file of resource.files) {
+            const existing = await readFileOrNull(join(baseDir, file.path));
+            const action = existing !== null ? 'overwrite' : 'create';
+            if (existing !== null)
+                clashes.push(file.path);
+            perFile.push({ path: file.path, action, diff: unifiedDiff(existing ?? '', file.content, file.path) });
+        }
+    }
+    return { perFile, clashes };
+}
 function kebab(name) {
     return name
         .replace(/([a-z0-9])([A-Z])/g, '$1-$2')

package/dist/make/openapi.js

@@ -1,4 +1,4 @@
-import { names } from '@basaltkit/generator';
+import { names } from '@basaltkit/generator/resource';
 /** Human summary for a generated CRUD route, from its method + url. */
 function summaryFor(method, url, singular, plural) {
     switch (method.toUpperCase()) {

package/dist/make/permissions.js

@@ -1,4 +1,4 @@
-import { names } from '@basaltkit/generator';
+import { names } from '@basaltkit/generator/resource';
 /**
  * The RBAC permissions for a resource — the exact `<plural>.<action>` strings its
  * route guards check on (F5 derives guards from the entity name, so declaring

package/dist/make/relations.js

@@ -1,4 +1,4 @@
-import { names } from '@basaltkit/generator';
+import { names } from '@basaltkit/generator/resource';
 /**
  * Real Prisma relations (Fase 6). A belongs-to relation on an entity generates:
  * a `<name>Id` FK column, a `<name> <Model> @relation(...)` field, and — on the

package/dist/make/repository.js

@@ -1,4 +1,4 @@
-import { names } from '@basaltkit/generator';
+import { names } from '@basaltkit/generator/resource';
 import { canonicalType, domainFields } from './fields.js';
 /** TypeScript type of a Prisma row column for the mapper's parameter. */
 function rowType(t) {

package/dist/make/types.d.ts

@@ -1,4 +1,5 @@
-import type { GeneratedFile } from '@basaltkit/generator';
+import type { GeneratedFile } from '@basaltkit/generator/resource';
+import type { OnProgress } from '../generate.js';
 export interface MakeOptions {
     /** Skip writing to disk — return what would be generated. */
     dryRun?: boolean;
@@ -14,6 +15,10 @@ export interface MakeOptions {
     schemaPath?: string;
     /** After merging models, run `prisma db push` (creates tables + regenerates the client). */
     migrate?: boolean;
+    /** Abort the operation (checked at each resource boundary). */
+    signal?: AbortSignal;
+    /** Receive coarse progress as each resource is built. */
+    onProgress?: OnProgress;
 }
 /** How the generated models were merged into prisma/schema.prisma. */
 export interface SchemaMerge {
@@ -52,6 +57,20 @@ export interface ResourceBuild {
     /** Why a step didn't complete (e.g. a file clash). */
     note?: string;
 }
+/** One file the build would write, with the change it would make. */
+export interface FilePreview {
+    path: string;
+    /** `create` = the file does not exist; `overwrite` = it exists and would be replaced. */
+    action: 'create' | 'overwrite';
+    /** Unified diff of the change (empty old side for a new file). */
+    diff: string;
+}
+/** A dry-run preview: exactly what would be written, and which files clash. */
+export interface MakePreview {
+    perFile: FilePreview[];
+    /** Paths that already exist and would be overwritten (an apply needs `force`). */
+    clashes: string[];
+}
 export type ReviewStatus = 'pass' | 'warn' | 'fail';
 export interface ReviewItem {
     label: string;
@@ -64,6 +83,11 @@ export interface ReviewResult {
     ok: boolean;
 }
 export interface MakeResult {
+    /**
+     * Serialization contract version. `runMake` always sets it; optional on the
+     * type so older, unversioned results still satisfy the interface.
+     */
+    schemaVersion?: number;
     request: string;
     dryRun: boolean;
     resources: ResourceBuild[];
@@ -74,4 +98,6 @@ export interface MakeResult {
     /** Manual follow-ups the scaffold can't do yet. */
     followUps: string[];
     review: ReviewResult;
+    /** Dry-run only: the exact per-file plan (clash flags + diffs). Absent on apply. */
+    preview?: MakePreview;
 }

package/dist/make/wire.js

@@ -1,4 +1,4 @@
-import { names } from '@basaltkit/generator';
+import { names } from '@basaltkit/generator/resource';
 function insertAfterLastImport(content, line) {
     const imports = [...content.matchAll(/^import .*$/gm)];
     const last = imports.at(-1);

package/dist/plan/plan.d.ts

@@ -1,9 +1,14 @@
 import type { ProjectContext } from '../context/project.js';
 import type { AIProvider } from '../provider/types.js';
+import { type OnProgress } from '../generate.js';
 import type { ArchitecturePlan } from './types.js';
 export interface CreatePlanOptions {
     temperature?: number;
     maxTokens?: number;
+    /** Abort the request. */
+    signal?: AbortSignal;
+    /** Receive streamed progress. When set, a streaming provider streams. */
+    onProgress?: OnProgress;
 }
 /**
  * Turn a natural-language request into a grounded {@link ArchitecturePlan}. The

package/dist/plan/plan.js

@@ -1,3 +1,5 @@
+import { ArchitecturePlanSchema } from '../schema/index.js';
+import { runGeneration } from '../generate.js';
 import { buildPlanContext } from './context.js';
 import { BASALT_KNOWLEDGE } from './knowledge.js';
 const STEP_KINDS = [
@@ -18,7 +20,12 @@ const STEP_KINDS = [
  * it produces a plan, it changes nothing.
  */
 export async function createPlan(provider, ctx, request, options = {}) {
-    const raw = await provider.generate({
+    const run = {};
+    if (options.signal)
+        run.signal = options.signal;
+    if (options.onProgress)
+        run.onProgress = options.onProgress;
+    const raw = await runGeneration(provider, {
         messages: [
             { role: 'system', content: BASALT_KNOWLEDGE },
             {
@@ -28,7 +35,7 @@ export async function createPlan(provider, ctx, request, options = {}) {
         ],
         temperature: options.temperature ?? 0,
         maxTokens: options.maxTokens ?? 4096,
-    });
+    }, run);
     return parsePlan(raw, request);
 }
 /** Parse + normalize the model's JSON into a validated plan. Tolerant of fences and missing arrays. */
@@ -41,7 +48,11 @@ export function parsePlan(raw, request) {
     catch {
         throw new Error(`ai:plan — the model did not return valid JSON. Got: ${raw.slice(0, 160)}…`);
     }
-    return {
+    // Coerce first (tolerant of fences, missing arrays and loose shapes), then
+    // validate the coerced object against the schema. `schemaVersion` defaults in
+    // when absent; an incoming version (a plan round-tripped from a client) is kept.
+    const coerced = {
+        ...(typeof obj['schemaVersion'] === 'number' ? { schemaVersion: obj['schemaVersion'] } : {}),
         request,
         summary: typeof obj['summary'] === 'string' ? obj['summary'] : '',
         entities: normalizeEntities(obj['entities']),
@@ -51,6 +62,10 @@ export function parsePlan(raw, request) {
         tenantScoped: obj['tenantScoped'] === true,
         warnings: stringArray(obj['warnings']),
     };
+    // The zod output is runtime-identical to ArchitecturePlan (optional keys are
+    // omitted, never `undefined`); the cast only bridges the `| undefined` that
+    // `z.infer` adds to optionals under `exactOptionalPropertyTypes`.
+    return ArchitecturePlanSchema.parse(coerced);
 }
 /** Strip markdown fences and isolate the outermost JSON object. */
 function extractJson(raw) {

package/dist/plan/types.d.ts

@@ -32,6 +32,12 @@ export interface PlanStep {
     files?: string[];
 }
 export interface ArchitecturePlan {
+    /**
+     * Serialization contract version. Producers (`createPlan`/`parsePlan`) always
+     * set it; it is optional on the type so hand-constructed plans and older,
+     * unversioned plans round-tripped from a client still satisfy the interface.
+     */
+    schemaVersion?: number;
     request: string;
     summary: string;
     entities: PlanEntity[];

package/dist/provider/abort.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Cancellation helpers shared by the provider layer and the workflow engine.
+ * Kept dependency-free so both the low-level fetch and the high-level workflows
+ * speak the same abort vocabulary.
+ */
+/** An `AbortError` with the conventional name, for signal-based cancellation. */
+export declare function abortError(message?: string): Error;
+/** Throw an {@link abortError} if the signal is already aborted. */
+export declare function throwIfAborted(signal?: AbortSignal): void;
+/** True when an error is an abort (from a cancelled fetch or {@link abortError}). */
+export declare function isAbortError(error: unknown): boolean;

package/dist/provider/abort.js

@@ -0,0 +1,20 @@
+/**
+ * Cancellation helpers shared by the provider layer and the workflow engine.
+ * Kept dependency-free so both the low-level fetch and the high-level workflows
+ * speak the same abort vocabulary.
+ */
+/** An `AbortError` with the conventional name, for signal-based cancellation. */
+export function abortError(message = 'The operation was aborted') {
+    const error = new Error(message);
+    error.name = 'AbortError';
+    return error;
+}
+/** Throw an {@link abortError} if the signal is already aborted. */
+export function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw abortError();
+}
+/** True when an error is an abort (from a cancelled fetch or {@link abortError}). */
+export function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}

package/dist/provider/anthropic.js

@@ -40,6 +40,7 @@ export class AnthropicProvider {
                 'x-api-key': this.apiKey,
                 'anthropic-version': API_VERSION,
             },
+            ...(options.signal ? { signal: options.signal } : {}),
             body: JSON.stringify({
                 model: this.model,
                 max_tokens: options.maxTokens ?? 4096,

package/dist/provider/factory.d.ts

@@ -14,6 +14,8 @@ export interface CreateProviderOptions {
     /** Override the injected fetch (tests). */
     fetch?: FetchLike;
 }
+/** Read the provider-relevant vars off an env record into a typed {@link ProviderEnv}. */
+export declare function providerEnvFrom(env: Record<string, string | undefined>): ProviderEnv;
 /** Read the provider-relevant vars off `process.env` into a typed {@link ProviderEnv}. */
 export declare function providerEnvFromProcess(): ProviderEnv;
 /**