@agentuity/migrate 3.0.0-alpha.6 → 3.0.0-beta.0

package/src/migrate-v3.ts

@@ -20,7 +20,14 @@
  *   8. Print final summary
  */
 
-import { existsSync, writeFileSync, unlinkSync, mkdirSync, readdirSync } from 'node:fs';
+import {
+	existsSync,
+	writeFileSync,
+	unlinkSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+} from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 
 import { detectV3 } from './detect-v3';
@@ -42,10 +49,15 @@ import { generateServicesFile } from './transforms/v3/services';
 import {
 	transformRouteServices,
 	computeServicesRelativePath,
+	insertAfterImports,
 	removeRuntimeImports,
+	rewriteV2AgentMethods,
+	stripAgentuityValidators,
+	stubV2HonoContext,
 } from './transforms/v3/routes';
 import { transformPackageJsonV3 } from './transforms/v3/package-json';
 import { generateDevSetup } from './transforms/v3/dev-setup';
+import { schemaToZod } from './transforms/v3/schema-to-zod';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -80,6 +92,14 @@ async function isGitWorktreeClean(projectDir: string): Promise<boolean> {
 	}
 }
 
+function readFileSyncSafe(path: string): string | null {
+	try {
+		return readFileSync(path, 'utf8');
+	} catch {
+		return null;
+	}
+}
+
 function isGitRepo(projectDir: string): boolean {
 	try {
 		const result = Bun.spawnSync(['git', 'rev-parse', '--is-inside-work-tree'], {
@@ -255,6 +275,55 @@ export async function migrateV3(opts: MigrateV3Options = {}): Promise<MigrateV3R
 		}
 	}
 
+	// ── 5a′. Delete @agentuity/evals files ─────────────────────────────────
+	// The evals framework was removed entirely in v3. Any file that imports
+	// @agentuity/evals — conventionally '*eval.ts' or '*eval.tsx' alongside
+	// an agent — is dropped wholesale. Keeping it would produce unrecoverable
+	// typecheck errors because `agent.createEval()` no longer exists on the
+	// plain function that replaces the v2 agent.
+	{
+		const srcDir = join(projectDir, 'src');
+		const evalFiles: string[] = [];
+		const walkForEvals = (dir: string) => {
+			if (!existsSync(dir)) return;
+			for (const entry of readdirSync(dir, { withFileTypes: true })) {
+				const full = join(dir, entry.name);
+				if (entry.isDirectory()) {
+					if (['node_modules', 'dist', '.agentuity', '.git'].includes(entry.name)) continue;
+					walkForEvals(full);
+				} else if (
+					entry.isFile() &&
+					(entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))
+				) {
+					const content = readFileSyncSafe(full);
+					if (content && content.includes("from '@agentuity/evals'")) {
+						evalFiles.push(full);
+					}
+				}
+			}
+		};
+		walkForEvals(srcDir);
+
+		for (const file of evalFiles) {
+			const rel = file.replace(projectDir + '/', '');
+			try {
+				unlinkSync(file);
+				changedFiles.push(rel);
+				allChangeSummary.push({
+					file: rel,
+					changes: ['Deleted — @agentuity/evals removed in v3'],
+				});
+			} catch {
+				// ignore
+			}
+		}
+
+		if (evalFiles.length > 0) {
+			printStep(`Deleted ${evalFiles.length} @agentuity/evals file(s)`);
+			printStepDone();
+		}
+	}
+
 	// ── 5b. Transform agent files ─────────────────────────────────────────
 	if (detection.agentFiles.length > 0) {
 		console.log(`\n  Transforming ${detection.agentFiles.length} agent file(s):`);
@@ -335,6 +404,7 @@ export async function migrateV3(opts: MigrateV3Options = {}): Promise<MigrateV3R
 			walkForRuntimeImports(srcDir);
 
 			let removedCount = 0;
+			let anyFileNeededEnvType = false;
 			for (const file of runtimeImportFiles) {
 				const relPath = file.replace(projectDir + '/', '');
 				// Skip files we've already modified
@@ -343,13 +413,52 @@ export async function migrateV3(opts: MigrateV3Options = {}): Promise<MigrateV3R
 				const src = await Bun.file(file).text();
 				if (!src.includes('@agentuity/runtime')) continue;
 
-				const { source: cleaned, removed } = removeRuntimeImports(src);
-				if (removed) {
+				const cleanup = removeRuntimeImports(src);
+				if (cleanup.removed) {
+					let cleaned = cleanup.source;
+					const extra: string[] = [];
+
+					// If this file imported Env, add a typed import from the
+					// local types helper. The helper file itself is emitted
+					// once later in this step.
+					if (cleanup.needsEnvType) {
+						anyFileNeededEnvType = true;
+						cleaned = insertAfterImports(
+							cleaned,
+							"import type { Env } from '../types/hono-env';"
+						);
+						extra.push("Added: import type { Env } from '../types/hono-env'");
+					}
+
+					// If the file had `validator` imported (or any <agent>.validator()
+					// middleware style), strip those call sites too — v3 has no
+					// equivalent.
+					const stripped = stripAgentuityValidators(cleaned);
+					if (stripped.changed) {
+						cleaned = stripped.source;
+						extra.push(...stripped.changes);
+					}
+
+					// Rewrite v2 agent method invocations (<agent>.run → <agent>,
+					// c.req.valid('json') → await c.req.json()).
+					const agentRewrite = rewriteV2AgentMethods(cleaned);
+					if (agentRewrite.changed) {
+						cleaned = agentRewrite.source;
+						extra.push(...agentRewrite.changes);
+					}
+
+					// Stub v2 Hono context (c.var.thread, c.var.sessionId).
+					const stub = stubV2HonoContext(cleaned);
+					if (stub.changed) {
+						cleaned = stub.source;
+						extra.push(...stub.changes);
+					}
+
 					writeFileSync(file, cleaned, 'utf8');
 					changedFiles.push(relPath);
 					allChangeSummary.push({
 						file: relPath,
-						changes: ['Removed @agentuity/runtime imports'],
+						changes: ['Removed @agentuity/runtime imports', ...extra],
 					});
 					removedCount++;
 				}
@@ -359,6 +468,48 @@ export async function migrateV3(opts: MigrateV3Options = {}): Promise<MigrateV3R
 				printStep(`Removed @agentuity/runtime imports from ${removedCount} additional file(s)`);
 				printStepDone();
 			}
+			void anyFileNeededEnvType; // subsumed by post-scan below
+		}
+	}
+
+	// ── 5c″. Emit src/types/hono-env.ts if any changed file references it ───
+	// Both the route service rewrite (5c) and the runtime import cleanup (5c′)
+	// can emit `import type { Env } from '../types/hono-env'`. We create the
+	// helper file once here by scanning the final content of changed files.
+	{
+		let helperNeeded = false;
+		for (const rel of changedFiles) {
+			try {
+				const content = readFileSyncSafe(join(projectDir, rel));
+				if (content && /from ['"]\.\.\/types\/hono-env['"]/.test(content)) {
+					helperNeeded = true;
+					break;
+				}
+			} catch {
+				// ignore
+			}
+		}
+
+		if (helperNeeded) {
+			const helperPath = join(projectDir, 'src', 'types', 'hono-env.ts');
+			if (!existsSync(helperPath)) {
+				mkdirSync(dirname(helperPath), { recursive: true });
+				const body =
+					'/**\n' +
+					' * Hono context variable type for Agentuity services.\n' +
+					' *\n' +
+					' * Generated by @agentuity/migrate during the v2 → v3 migration as the\n' +
+					" * replacement for `import type { Env } from '@agentuity/runtime'`.\n" +
+					' */\n' +
+					"import type { Services } from '@agentuity/hono';\n\n" +
+					'export type Env = { Variables: Services };\n';
+				writeFileSync(helperPath, body, 'utf8');
+				changedFiles.push('src/types/hono-env.ts');
+				allChangeSummary.push({
+					file: 'src/types/hono-env.ts',
+					changes: ['Created — replaces `Env` type from @agentuity/runtime'],
+				});
+			}
 		}
 	}
 
@@ -451,6 +602,58 @@ export async function migrateV3(opts: MigrateV3Options = {}): Promise<MigrateV3R
 		}
 	}
 
+	// ── 5g′. Port @agentuity/schema usage to zod ─────────────────────────
+	// Walk all .ts/.tsx files under src/ one more time and rewrite
+	// `import { s } from '@agentuity/schema'` + `s.*` calls to the zod
+	// equivalents. Track whether the rewrite actually fired anywhere — if
+	// it did, we'll add zod (and drop @agentuity/schema) in the package
+	// update step below.
+	let anyFilePortedToZod = false;
+	{
+		const srcDir = join(projectDir, 'src');
+		const walkAllTs = (dir: string): string[] => {
+			if (!existsSync(dir)) return [];
+			const out: string[] = [];
+			for (const entry of readdirSync(dir, { withFileTypes: true })) {
+				const full = join(dir, entry.name);
+				if (entry.isDirectory()) {
+					if (['node_modules', 'dist', '.agentuity', '.git'].includes(entry.name)) continue;
+					out.push(...walkAllTs(full));
+				} else if (
+					entry.isFile() &&
+					(entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))
+				) {
+					out.push(full);
+				}
+			}
+			return out;
+		};
+
+		for (const file of walkAllTs(srcDir)) {
+			const rel = file.replace(projectDir + '/', '');
+			const src = readFileSyncSafe(file);
+			if (!src) continue;
+			const ported = schemaToZod(src);
+			if (ported.changed) {
+				writeFileSync(file, ported.source, 'utf8');
+				anyFilePortedToZod = true;
+				if (!changedFiles.includes(rel)) {
+					changedFiles.push(rel);
+					allChangeSummary.push({ file: rel, changes: ported.changes });
+				} else {
+					// Merge into the existing entry so we don't lose earlier changes.
+					const entry = allChangeSummary.find((c) => c.file === rel);
+					if (entry) entry.changes.push(...ported.changes);
+				}
+			}
+		}
+
+		if (anyFilePortedToZod) {
+			printStep('Ported @agentuity/schema usage to zod');
+			printStepDone();
+		}
+	}
+
 	// ── 5h. Update package.json ───────────────────────────────────────────
 	const packageJsonPath = join(projectDir, 'package.json');
 	if (existsSync(packageJsonPath)) {
@@ -465,6 +668,7 @@ export async function migrateV3(opts: MigrateV3Options = {}): Promise<MigrateV3R
 				{
 					removeRuntime: detection.hasRuntimeDep,
 					removeReact: detection.hasReactPackage,
+					addZod: anyFilePortedToZod,
 					devScripts,
 				}
 			);

package/src/transforms/v3/agents.ts

@@ -1,14 +1,21 @@
 /**
  * Transform: createAgent() → plain exported functions
  *
+ * v3 is an "eject" — the createAgent() wrapper, ctx.* service magic, thread
+ * state, sessions and evals are all replaced by user-visible primitives.
+ *
  * For "simple" agents (handler + optional schema only), we:
  *   1. Remove the createAgent() wrapper
  *   2. Extract the handler as a named exported async function
  *   3. Preserve schema validation if present
- *   4. Replace ctx.* service access with imports from services module
+ *   4. Replace ctx.* service access with imports from the services module
  *
- * For "complex" agents, we add a prominent migration comment and leave
- * the code untouched for manual review.
+ * For "complex" agents (setup/shutdown/onEvent/ctx.config), we additionally:
+ *   5. Hoist setup() return values into module-level lazy-init singletons
+ *      so the handler body still compiles after the ctx.config.* → direct
+ *      reference rewrite.
+ *   6. Replace ctx.thread.*, ctx.sessionId, ctx.app.* with TODO comments —
+ *      these concepts are gone in v3.
  *
  * We use a combination of regex and AST analysis — regex for the mechanical
  * transforms (preserving formatting), AST for detection (already done in detect-v3).
@@ -45,7 +52,7 @@ export function transformAgentFile(
 	servicesRelativePath: string
 ): AgentTransformResult {
 	if (agentInfo.complexity === 'complex') {
-		return addManualMigrationComment(source, agentInfo);
+		return forceConvertComplexAgent(source, agentInfo, servicesRelativePath);
 	}
 
 	const changes: string[] = [];
@@ -117,7 +124,270 @@ export function transformAgentFile(
 }
 
 /**
- * For complex agents, add a migration comment block.
+ * Force-convert a "complex" agent (setup/shutdown/onEvent/ctx.config) to
+ * a plain exported async function plus module-level lazy-init singletons.
+ *
+ * v3 is an eject — we prefer working-but-TODO'd code over compilation errors
+ * that block the whole migration. Every hoisted singleton and every dropped
+ * feature is annotated so the user can review.
+ */
+function forceConvertComplexAgent(
+	source: string,
+	agentInfo: AgentFile,
+	servicesRelativePath: string
+): AgentTransformResult {
+	const changes: string[] = [];
+	const sourceFile = ts.createSourceFile(agentInfo.path, source, ts.ScriptTarget.ESNext, true);
+
+	const extracted = extractHandlerFromCreateAgent(sourceFile, source);
+	if (!extracted) {
+		// Fall back to the comment-only path so the file at least still parses.
+		return addManualMigrationComment(source, agentInfo);
+	}
+
+	const setupInfo = extractSetupFromCreateAgent(sourceFile);
+
+	let output = source;
+
+	// Step 1: Remove createAgent import
+	output = removeCreateAgentImport(output);
+	changes.push('Removed createAgent import from @agentuity/runtime');
+
+	// Step 2: Add services import if needed
+	if (agentInfo.ctxServices.length > 0) {
+		const importLine = `import { ${agentInfo.ctxServices.join(', ')} } from '${servicesRelativePath}';`;
+		output = insertAfterImports(output, importLine);
+		changes.push(`Added services import: ${agentInfo.ctxServices.join(', ')}`);
+	}
+
+	// Step 3: Rewrite handler body to remove ctx.* magic.
+	let handlerBody = extracted.handlerBody;
+
+	// 3a. ctx.config.<name> → (await get_<name>()) — wired to the hoisted
+	// module-level lazy init emitted in step 5 below. We wrap with parens so
+	// subsequent `.foo.bar` chains still parse correctly.
+	const configRefs = new Set<string>();
+	for (const ctxName of CTX_PARAM_NAMES) {
+		const pattern = new RegExp(`\\b${ctxName}\\.config\\.([A-Za-z_$][A-Za-z0-9_$]*)`, 'g');
+		handlerBody = handlerBody.replace(pattern, (_m, id: string) => {
+			configRefs.add(id);
+			return `(await get_${id}())`;
+		});
+	}
+	if (configRefs.size > 0) {
+		changes.push(`Rewrote ctx.config.{${[...configRefs].join(', ')}} → (await get_‹key›())`);
+	}
+
+	// 3b. ctx.logger → logger (expected to come from services barrel).
+	for (const ctxName of CTX_PARAM_NAMES) {
+		handlerBody = handlerBody.replace(new RegExp(`\\b${ctxName}\\.logger\\b`, 'g'), 'logger');
+	}
+
+	// 3c. Replace ctx.<service> → <service> for all detected services.
+	for (const service of agentInfo.ctxServices) {
+		for (const ctxName of CTX_PARAM_NAMES) {
+			const pattern = new RegExp(`\\b${ctxName}\\.${service}\\b`, 'g');
+			handlerBody = handlerBody.replace(pattern, service);
+		}
+	}
+
+	// 3d. Replace ctx.thread / ctx.sessionId / ctx.app with obvious stubs.
+	// These concepts have no v3 equivalent. We rewrite whole ctx.<x>.*
+	// expression chains by scanning the handler AST so we don't mangle
+	// surrounding punctuation the way a pure regex would.
+	const droppedAccessors = new Set<string>();
+	const handlerSf = ts.createSourceFile('handler.ts', handlerBody, ts.ScriptTarget.ESNext, true);
+	const edits: Array<{ start: number; end: number; replacement: string }> = [];
+
+	// Walk expressions that START with a ctx-named identifier and whose full
+	// chain matches our pattern. We accumulate all unique full-chain ranges
+	// and, later, keep only the outermost chain at each location.
+	function visitExpr(node: ts.Node): void {
+		if (ts.isPropertyAccessExpression(node) || ts.isCallExpression(node)) {
+			// Find the leftmost identifier by walking .expression left.
+			let cur: ts.Node = node;
+			while (true) {
+				if (ts.isPropertyAccessExpression(cur)) {
+					cur = cur.expression;
+				} else if (ts.isCallExpression(cur)) {
+					cur = cur.expression;
+				} else if (ts.isElementAccessExpression(cur)) {
+					cur = cur.expression;
+				} else {
+					break;
+				}
+			}
+			if (ts.isIdentifier(cur) && CTX_PARAM_NAMES.includes(cur.text)) {
+				// Need to check the first property access is one of our removed keys
+				// by re-walking from the leaf.
+				const parent: ts.Node | undefined = cur.parent;
+				let firstProp: string | undefined;
+				if (parent && ts.isPropertyAccessExpression(parent) && parent.expression === cur) {
+					firstProp = parent.name.text;
+				}
+				if (firstProp && (firstProp === 'thread' || firstProp === 'app')) {
+					edits.push({
+						start: node.getStart(handlerSf),
+						end: node.getEnd(),
+						replacement: `(undefined /* v3: ${cur.text}.${firstProp} removed */ as any)`,
+					});
+					droppedAccessors.add(`${cur.text}.${firstProp}`);
+				} else if (firstProp === 'sessionId') {
+					edits.push({
+						start: node.getStart(handlerSf),
+						end: node.getEnd(),
+						replacement: "('v3-no-session-id' /* v3: ctx.sessionId removed */)",
+					});
+					droppedAccessors.add(`${cur.text}.sessionId`);
+				}
+			}
+		}
+		ts.forEachChild(node, visitExpr);
+	}
+	ts.forEachChild(handlerSf, visitExpr);
+
+	// Keep only the **outermost** ctx.x.y.z chain per location. The AST visitor
+	// emits overlapping edits for every nested property access, so sort by
+	// length descending and drop anything contained within a larger accepted
+	// edit.
+	if (edits.length > 0) {
+		edits.sort((a, b) => b.end - b.start - (a.end - a.start) || a.start - b.start);
+		const kept: Array<{ start: number; end: number; replacement: string }> = [];
+		for (const e of edits) {
+			const overlaps = kept.some((k) => !(e.end <= k.start || e.start >= k.end));
+			if (!overlaps) kept.push(e);
+		}
+		// Apply right-to-left so earlier offsets stay valid.
+		kept.sort((a, b) => b.start - a.start);
+		let body = handlerBody;
+		for (const e of kept) {
+			body = body.slice(0, e.start) + e.replacement + body.slice(e.end);
+		}
+		handlerBody = body;
+	}
+	if (droppedAccessors.size > 0) {
+		changes.push(`Stubbed out ctx accessors removed in v3: ${[...droppedAccessors].join(', ')}`);
+	}
+
+	// Update extracted payload with rewritten body.
+	const rewrittenExtracted = { ...extracted, handlerBody };
+
+	// Step 4: Replace the createAgent() statement with the plain function.
+	output = replaceCreateAgentWithFunction(output, agentInfo, rewrittenExtracted);
+	changes.push(`Converted complex agent "${agentInfo.name}" to plain exported async function`);
+
+	// Step 5: Hoist setup() body to module-level singletons.
+	if (setupInfo && configRefs.size > 0) {
+		const singletonBlock = buildLazyInitBlock(configRefs, setupInfo);
+		output = insertAfterImports(output, singletonBlock);
+		changes.push(
+			`Hoisted setup() return values to module-level lazy init: ${[...configRefs].join(', ')}`
+		);
+	}
+
+	// Step 6: Prepend a review banner so the user knows this was auto-ejected.
+	const banner =
+		'// ℹ️  v3 migration — complex agent auto-ejected\n' +
+		`//    Reason: ${agentInfo.complexityReason ?? 'unknown'}\n` +
+		'//    Review the hoisted singletons, TODO comments, and the stubbed-out\n' +
+		'//    thread/session accessors — these v2 features have no v3 equivalent.\n';
+	output = banner + output;
+
+	return { source: output, changes, manualRequired: true };
+}
+
+/**
+ * Build a module-level lazy init block from the setup() body.
+ *
+ * Output shape (singleton pattern):
+ *
+ *   let _client: ReturnType<typeof __buildSetup>['client'] | undefined;
+ *   function getClient() {
+ *     return _client ?? (_client = (() => { ... setup body returns .client ... })());
+ *   }
+ *
+ * For simplicity and to avoid having to type-reason about return shape, we
+ * emit a single IIFE that runs setup() on first access and caches per-key.
+ */
+function buildLazyInitBlock(keys: Set<string>, setup: { setupBodyText: string }): string {
+	const keyList = [...keys];
+	const lines: string[] = [];
+	lines.push(
+		'\n// v3: lazy-init singletons hoisted from the former setup() hook.\n' +
+			'// Each key is computed lazily on first access so we keep the original\n' +
+			'// semantics (constructors run at handler-time, not at module load).'
+	);
+	lines.push(`let __setupResult: Record<string, unknown> | undefined;`);
+	lines.push(`async function __runSetup(): Promise<Record<string, unknown>> {`);
+	lines.push(`\tif (__setupResult) return __setupResult;`);
+	lines.push(
+		`\t// Original setup() body — adjust by hand if it referenced ctx:\n\tconst __result = await (async () => ${setup.setupBodyText})();`
+	);
+	lines.push(`\t__setupResult = __result as Record<string, unknown>;`);
+	lines.push(`\treturn __setupResult;`);
+	lines.push(`}`);
+	for (const key of keyList) {
+		lines.push(
+			`async function get_${key}() { return (await __runSetup())[${JSON.stringify(key)}] as any; }`
+		);
+		// We also expose a sync alias for cases where the original code read ctx.config.X
+		// synchronously — the user will need to await. We emit a `const X = await get_X()` stub
+		// near the start of the handler via the handler-body rewriter later on.
+	}
+	return lines.join('\n') + '\n';
+}
+
+/**
+ * Extract the body of the setup() property/method on the createAgent() config.
+ */
+function extractSetupFromCreateAgent(sourceFile: ts.SourceFile): { setupBodyText: string } | null {
+	let result: { setupBodyText: string } | null = null;
+
+	function visit(node: ts.Node) {
+		if (result) return;
+
+		if (
+			ts.isCallExpression(node) &&
+			ts.isIdentifier(node.expression) &&
+			node.expression.text === 'createAgent'
+		) {
+			const configArg = node.arguments[1];
+			if (!configArg || !ts.isObjectLiteralExpression(configArg)) return;
+
+			for (const prop of configArg.properties) {
+				const name =
+					(ts.isPropertyAssignment(prop) || ts.isMethodDeclaration(prop)) &&
+					ts.isIdentifier(prop.name)
+						? prop.name.text
+						: undefined;
+				if (name !== 'setup') continue;
+
+				let body: ts.Block | ts.Expression | undefined;
+				if (ts.isPropertyAssignment(prop)) {
+					const init = prop.initializer;
+					if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+						body = init.body;
+					}
+				} else if (ts.isMethodDeclaration(prop)) {
+					body = prop.body;
+				}
+				if (!body) continue;
+
+				const bodyText = body.getText(sourceFile);
+				result = { setupBodyText: bodyText };
+			}
+		}
+
+		ts.forEachChild(node, visit);
+	}
+
+	visit(sourceFile);
+	return result;
+}
+
+/**
+ * For complex agents we cannot auto-migrate, add a migration comment block
+ * only (fallback if the handler couldn't be extracted).
  */
 function addManualMigrationComment(source: string, agentInfo: AgentFile): AgentTransformResult {
 	const comment =
@@ -214,7 +484,12 @@ function extractHandlerFromCreateAgent(
 
 			if (!body) return;
 
-			// Get parameter text (skip ctx/context parameter, keep input)
+			// Get parameter text (skip ctx/context parameter, keep input).
+			// We also ensure every surviving param has a type annotation — the v2
+			// scaffold relied on createAgent<Schema>() to type the handler's input,
+			// which is gone in v3. Rather than lose type information, we fall back
+			// to `: unknown` + a TODO so the resulting plain function compiles
+			// under strict mode. Users can tighten the type by parsing with zod.
 			const paramTexts: string[] = [];
 			if (params) {
 				for (let i = 0; i < params.length; i++) {
@@ -223,7 +498,14 @@ function extractHandlerFromCreateAgent(
 					const paramName = param.name.getText(sourceFile);
 					// Skip the first param if it's ctx/context (agent context)
 					if (i === 0 && CTX_PARAM_NAMES.includes(paramName)) continue;
-					paramTexts.push(param.getText(sourceFile));
+					let paramText = param.getText(sourceFile);
+					// If the param has no type annotation (v2 scaffold relied on
+					// createAgent generics), inject `: any` so the plain function
+					// still compiles.
+					if (!param.type) {
+						paramText += ': any';
+					}
+					paramTexts.push(paramText);
 				}
 			}
 

package/src/transforms/v3/package-json.ts

@@ -10,6 +10,22 @@
 
 import { SERVICE_PACKAGE_MAP, type V3OutdatedPackage } from '../../detect-v3';
 
+/**
+ * Packages that existed in v2 but are removed in v3.
+ *
+ * v3 is a deliberate "eject" — agent framework magic (evals, workbench) and
+ * helper facades (frontend, react) are replaced by user-visible primitives.
+ * These packages have no v3 counterpart and must be deleted from package.json,
+ * not bumped to a non-existent ^3.0.0.
+ *
+ * Note: @agentuity/react is handled separately via options.removeReact.
+ */
+const PACKAGES_REMOVED_IN_V3 = [
+	'@agentuity/evals',
+	'@agentuity/frontend',
+	'@agentuity/workbench',
+] as const;
+
 export interface V3PackageJsonResult {
 	/** Transformed package.json content, or null if no changes */
 	content: string | null;
@@ -29,6 +45,8 @@ export function transformPackageJsonV3(
 		removeRuntime?: boolean;
 		/** Whether to remove @agentuity/react */
 		removeReact?: boolean;
+		/** Whether any source file was ported from @agentuity/schema to zod */
+		addZod?: boolean;
 		/** Dev scripts to add (from dev-setup transform) */
 		devScripts?: Record<string, string>;
 	}
@@ -87,8 +105,24 @@ export function transformPackageJsonV3(
 		}
 	}
 
-	// ── 5. Bump existing @agentuity/* packages to ^3.0.0 ──────────────────
+	// ── 5a. Remove v2-only packages that have no v3 counterpart ────────────
+	// (These would otherwise be bumped to ^3.0.0 in step 5b, which fails to
+	// resolve because the packages were deleted entirely in v3.)
+	for (const removed of PACKAGES_REMOVED_IN_V3) {
+		if (deps[removed]) {
+			delete deps[removed];
+			changes.push(`Removed ${removed} from dependencies (no longer exists in v3)`);
+		}
+		if (devDeps[removed]) {
+			delete devDeps[removed];
+			changes.push(`Removed ${removed} from devDependencies (no longer exists in v3)`);
+		}
+	}
+
+	// ── 5b. Bump existing @agentuity/* packages to ^3.0.0 ─────────────────
+	// Skip packages we just removed — they'd otherwise come back.
 	for (const outdated of outdatedPackages) {
+		if ((PACKAGES_REMOVED_IN_V3 as readonly string[]).includes(outdated.name)) continue;
 		const section = outdated.section === 'dependencies' ? deps : devDeps;
 		if (section[outdated.name]) {
 			section[outdated.name] = '^3.0.0';
@@ -96,7 +130,23 @@ export function transformPackageJsonV3(
 		}
 	}
 
-	// ── 6. Remove @agentuity/react if requested ───────────────────────────
+	// ── 6. Add zod + remove @agentuity/schema when the schema→zod port fired ──
+	if (options?.addZod) {
+		if (!deps['zod']) {
+			deps['zod'] = '^4.0.0';
+			changes.push('Added zod@^4.0.0 to dependencies');
+		}
+		if (deps['@agentuity/schema']) {
+			delete deps['@agentuity/schema'];
+			changes.push('Removed @agentuity/schema (usage ported to zod)');
+		}
+		if (devDeps['@agentuity/schema']) {
+			delete devDeps['@agentuity/schema'];
+			changes.push('Removed @agentuity/schema from devDependencies (usage ported to zod)');
+		}
+	}
+
+	// ── 7. Remove @agentuity/react if requested ───────────────────────────
 	if (options?.removeReact) {
 		if (deps['@agentuity/react']) {
 			delete deps['@agentuity/react'];