@selesai/code 0.13.24 → 0.13.25

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [0.13.25] - 2026-09-14
+
+### Added
+- **Graft deep-build model override.** Set `graft.deepModel` to pin a model on the active provider for Graft deep builds.
+
+### Changed
+- **Graft deep-build fallback.** When the active model returns no usable Graft summaries, the deep build retries up to two other models scoped to that provider before reporting the deep-build failure.
+
 ## [0.13.24] - 2026-09-13
 
 ### Added

package/dist/extensions/pi-graft/commands.test.ts

@@ -387,7 +387,7 @@ describe("mutation-capable commands", () => {
 		const [title, message] = ctx.ui.confirm.mock.calls[0] as [string, string];
 		expect(title).toContain("provider-backed");
 		expect(message).toContain("leaves this machine");
-		expect(message).toContain("credential is passed only to this Graft child process");
+		expect(message).toContain("Credentials are passed only to this Graft child process");
 		expect(harness.runBuild).toHaveBeenCalledWith(true, ctx);
 	});
 

package/dist/extensions/pi-graft/commands.ts

@@ -330,7 +330,7 @@ export function registerGraftCommands(pi: ExtensionAPI, runtime: GraftCommandRun
 								? "Set up Graft for this repository?"
 								: "Build the Graft graph?",
 						deep
-							? `This runs \`graft build --deep\` in ${repo}.\n\nThe structural graph stays local and deterministic. The deep pass summarizes each changed file and extracts per-symbol cruxes using Selesai's active compatible model, so source-derived content leaves this machine. Its credential is passed only to this Graft child process.\n\nFiles it can write:\n${buildEffects(true)}`
+							? `This runs \`graft build --deep\` in ${repo}.\n\nThe structural graph stays local and deterministic. The deep pass summarizes each changed file and extracts per-symbol cruxes using Selesai's active compatible model, falling back to another model you scoped on the same provider when that model cannot produce Graft summaries. Source-derived content leaves this machine either way. Credentials are passed only to this Graft child process.\n\nFiles it can write:\n${buildEffects(true)}`
 							: `This runs \`graft build\` in ${repo} and can write:\n\n${buildEffects(false)}`,
 						manualCommand,
 					);

package/dist/extensions/pi-graft/index.ts

@@ -183,32 +183,94 @@ const GRAFT_PROVIDER_FOR_SELESAI_PROVIDER: Record<string, "openai" | "anthropic"
 	tokenin: "litellm",
 };
 
-/** Resolve the active Selesai model into the isolated environment Graft needs. */
-async function activeModelGraftEnvironment(ctx: ExtensionContext): Promise<NodeJS.ProcessEnv | undefined> {
+/**
+ * The deep tier either has a plan, or a human-readable reason it does not.
+ * Automatic builds fall back to the structural tier on `ok: false`; the
+ * explicit `/graft deep` command reports the reason instead.
+ */
+type DeepBuildPlan =
+	| { ok: true; env: NodeJS.ProcessEnv | undefined; models: readonly string[] }
+	| { ok: false; reason: string };
+
+/** Graft's per-symbol summary pass is model-sensitive; this is its failure signature. */
+const UNUSABLE_SUMMARIES = /no usable symbol summaries|empty-parsed/i;
+
+/**
+ * Deep-build candidates in order: an explicit `graft.deepModel` pin, the active
+ * model, then the models this session scoped on the same provider. No new
+ * setting is needed — models the user already chose are tried before giving up
+ * on the deep tier.
+ */
+function deepBuildModels(ctx: ExtensionContext, settings: { deepModel?: string }): readonly string[] {
+	const active = ctx.model;
+	const scoped = (ctx.scopedModels ?? [])
+		.map((entry) => entry.model)
+		.filter((candidate) => candidate.provider === active?.provider)
+		.map((candidate) => candidate.id);
+	const ordered = [settings.deepModel, active?.id, ...scoped].filter((id): id is string => Boolean(id));
+	return [...new Set(ordered)].slice(0, 3);
+}
+
+/**
+ * Resolve the active Selesai model into the isolated environment Graft needs.
+ *
+ * Credentials are read from Selesai's own auth storage — TokenIn keys live in
+ * `~/.selesai/agent`, not in the shell environment — and passed only to the
+ * Graft child process.
+ */
+async function resolveDeepBuildPlan(
+	ctx: ExtensionContext,
+	settings: { deepModel?: string } = {},
+): Promise<DeepBuildPlan> {
+	const models = deepBuildModels(ctx, settings);
+	// A user who already configured Graft's own provider environment outranks us.
+	if (process.env.GRAFT_PROVIDER && process.env.GRAFT_API_KEY) return { ok: true, env: undefined, models };
+
 	const model = ctx.model;
-	const provider = model ? GRAFT_PROVIDER_FOR_SELESAI_PROVIDER[model.provider] : undefined;
-	if (!provider) return undefined;
+	if (!model) return { ok: false, reason: "no active model is selected" };
+	const provider = GRAFT_PROVIDER_FOR_SELESAI_PROVIDER[model.provider];
+	if (!provider) {
+		return {
+			ok: false,
+			reason: `provider "${model.provider}" has no Graft wire format (use TokenIn, LiteLLM, OpenAI, Anthropic, or OrcaRouter)`,
+		};
+	}
 
-	let auth: Awaited<ReturnType<typeof ctx.modelRegistry.getProviderAuth>>;
+	let apiKey: string | undefined;
+	let authBaseUrl: string | undefined;
 	try {
-		auth = await ctx.modelRegistry.getProviderAuth(model.provider);
+		const auth = await ctx.modelRegistry.getProviderAuth(model.provider);
+		apiKey = auth?.auth.apiKey;
+		authBaseUrl = auth?.auth.baseUrl;
 	} catch {
-		return undefined;
+		// Fall through to the missing-credential reason below.
+	}
+	if (!apiKey) return { ok: false, reason: `no credential is stored for "${model.provider}"` };
+
+	// The composed model carries the endpoint; auth only sometimes does.
+	const baseUrl = authBaseUrl || model.baseUrl || ctx.modelRegistry.getProvider(model.provider)?.baseUrl;
+	if (provider === "litellm" && !baseUrl) {
+		return { ok: false, reason: `"${model.provider}" has no base URL to send Graft to` };
 	}
-	const apiKey = auth?.auth.apiKey;
-	const baseUrl = auth?.auth.baseUrl;
-	if (!apiKey || (provider === "litellm" && !baseUrl)) return undefined;
 
-	const { GRAFT_PROVIDER: _provider, GRAFT_MODEL: _model, GRAFT_API_KEY: _apiKey, GRAFT_BASE_URL: _baseUrl, ...env } = process.env;
+	const { GRAFT_PROVIDER: _p, GRAFT_MODEL: _m, GRAFT_API_KEY: _k, GRAFT_BASE_URL: _u, ...env } = process.env;
 	return {
-		...env,
-		GRAFT_PROVIDER: provider,
-		GRAFT_MODEL: model.id,
-		GRAFT_API_KEY: apiKey,
-		...(baseUrl ? { GRAFT_BASE_URL: baseUrl } : {}),
+		ok: true,
+		models,
+		env: {
+			...env,
+			GRAFT_PROVIDER: provider,
+			GRAFT_API_KEY: apiKey,
+			...(baseUrl ? { GRAFT_BASE_URL: baseUrl } : {}),
+		},
 	};
 }
 
+/** Graft's environment for one candidate model; undefined keeps the user's own GRAFT_* setup. */
+function deepEnvFor(plan: Extract<DeepBuildPlan, { ok: true }>, modelId: string): NodeJS.ProcessEnv | undefined {
+	return plan.env ? { ...plan.env, GRAFT_MODEL: modelId } : undefined;
+}
+
 export default function graftExtension(pi: ExtensionAPI): void {
 	registerBuiltinAgentAugmentation(pi);
 	const exec: ExecLike = (command, args, options) => pi.exec(command, args, options);
@@ -277,6 +339,48 @@ export default function graftExtension(pi: ExtensionAPI): void {
 		}
 	};
 
+	/**
+	 * Build the graph: deep with a compatible active model, structural otherwise.
+	 *
+	 * A model that cannot produce Graft-parsable summaries is not fatal — the
+	 * next candidate the session already offers is tried before downgrading.
+	 */
+	const buildGraph = async (
+		ctx: ExtensionContext,
+		activeSession: GraftSession,
+		phase: "build" | "refresh" = "build",
+	): Promise<GraftRun> => {
+		const repoRoot = activeSession.repoRoot!;
+		// A refresh has already announced its own "syncing" phase at the caller.
+		const started = (deep: boolean): void => {
+			if (phase === "refresh") return;
+			if (session === activeSession && !activeSession.disposed) applyEvent(ctx, { type: "build-started", deep });
+		};
+		const structural = async (): Promise<GraftRun> => {
+			started(false);
+			return runGraft(exec, repoRoot, { kind: "build", deep: false });
+		};
+
+		const plan = await resolveDeepBuildPlan(ctx, activeSession.settings);
+		if (!plan.ok) return structural();
+
+		// The user's own GRAFT_* environment names the model; never second-guess it.
+		const candidates = plan.env ? plan.models : plan.models.slice(0, 1);
+		let failed: GraftRun | undefined;
+		for (const [index, model] of candidates.entries()) {
+			started(true);
+			const run = await runGraft(exec, repoRoot, { kind: "build", deep: true }, { env: deepEnvFor(plan, model) });
+			if (run.code === 0 || !UNUSABLE_SUMMARIES.test(`${run.stderr}\n${run.stdout}`)) return run;
+			failed = run;
+			if (index === 0 && candidates.length > 1 && ctx.hasUI) {
+				ctx.ui.notify(`Graft cannot summarize with ${model}; retrying the deep pass with another scoped model.`, "info");
+			}
+		}
+		// Nothing left to try: report the last run rather than pretending the
+		// structural tier explained the failure.
+		return failed ?? (await structural());
+	};
+
 	/**
 	 * Start the graph once. Compatible active Selesai models add the deep tier;
 	 * otherwise the free local structural tier remains usable.
@@ -290,11 +394,7 @@ export default function graftExtension(pi: ExtensionAPI): void {
 			activeSession.state.name === "failed"
 		) return undefined;
 
-		const pending = activeModelGraftEnvironment(ctx).then(async (env) => {
-			const deep = env !== undefined;
-			if (session === activeSession && !activeSession.disposed) applyEvent(ctx, { type: "build-started", deep });
-			return runGraft(exec, activeSession.repoRoot!, { kind: "build", deep }, { env });
-		});
+		const pending = buildGraph(ctx, activeSession);
 		structuralBuildPromise = pending;
 		structuralBuildSession = activeSession;
 		void pending.then(
@@ -544,11 +644,9 @@ export default function graftExtension(pi: ExtensionAPI): void {
 
 		void (async () => {
 			try {
-				const env = await activeModelGraftEnvironment(ctx);
-				const deep = env !== undefined;
-				const run = await runGraft(exec, session.repoRoot!, { kind: "build", deep }, { env });
+				const run = await buildGraph(ctx, session, "refresh");
 				if (session.disposed) return;
-				recordBuild(ctx, run, deep);
+				recordBuild(ctx, run, run.op.kind === "build" && run.op.deep);
 			} catch (error) {
 				if (session.disposed) return;
 				applyEvent(ctx, {
@@ -584,24 +682,27 @@ export default function graftExtension(pi: ExtensionAPI): void {
 			if (!deep) {
 				const pending = autoBuild(ctx, session);
 				if (pending) return pending;
+				applyEvent(ctx, { type: "build-started", deep: false });
+				const structural = await runGraft(exec, session.repoRoot!, { kind: "build", deep: false });
+				recordBuild(ctx, structural, false);
+				return structural;
 			}
-			const env = deep ? await activeModelGraftEnvironment(ctx) : undefined;
-			if (deep && !env) {
+			const plan = await resolveDeepBuildPlan(ctx, session.settings);
+			if (!plan.ok) {
 				return {
-					op: { kind: "build", deep },
+					op: { kind: "build", deep: true },
 					argv: ["graft", "build", "--deep"],
 					cwd: session.repoRoot!,
 					code: 1,
 					stdout: "",
-					stderr: "The active Selesai model cannot be used for Graft deep builds.",
+					stderr: `No deep build is possible for the active model: ${plan.reason}.`,
 					killed: false,
 					cancelled: false,
 					timedOut: false,
 				};
 			}
-			applyEvent(ctx, { type: "build-started", deep });
-			const run = await runGraft(exec, session.repoRoot!, { kind: "build", deep }, { env });
-			recordBuild(ctx, run, deep);
+			const run = await buildGraph(ctx, session);
+			recordBuild(ctx, run, run.op.kind === "build" && run.op.deep);
 			return run;
 		},
 		runRefresh: async (ctx) => {
@@ -609,10 +710,8 @@ export default function graftExtension(pi: ExtensionAPI): void {
 			await ensureReady(ctx, { kind: "build", deep: false });
 			session.lastRefreshAt = Date.now();
 			applyEvent(ctx, { type: "refresh-started" });
-			const env = await activeModelGraftEnvironment(ctx);
-			const deep = env !== undefined;
-			const run = await runGraft(exec, session.repoRoot!, { kind: "build", deep }, { env });
-			recordBuild(ctx, run, deep);
+			const run = await buildGraph(ctx, session, "refresh");
+			recordBuild(ctx, run, run.op.kind === "build" && run.op.deep);
 			return run;
 		},
 		providerEnvNames: () => PROVIDER_ENV_NAMES.filter((name) => Boolean(process.env[name])),

package/dist/extensions/pi-graft/lifecycle.test.ts

@@ -304,11 +304,11 @@ describe("proactive refresh", () => {
 		});
 		graftExtension(harness.pi as never);
 		const ctx = makeCtx({ cwd: bare });
+		// Mirrors the real TokenIn shape: the key lives in ~/.selesai auth storage and
+		// the endpoint comes from the composed model, not from the auth resolution.
 		Object.assign(ctx, {
-			model: { provider: "tokenin", id: "deepseek-v4-flash" },
-			modelRegistry: {
-				getProviderAuth: vi.fn(async () => ({ auth: { apiKey: "test-token", baseUrl: "https://lite.andlet.me/v1" } })),
-			},
+			model: { provider: "tokenin", id: "deepseek-v4.1-flash", baseUrl: "https://lite.andlet.me/v1" },
+			modelRegistry: { getProviderAuth: vi.fn(async () => ({ auth: { apiKey: "test-token" } })) },
 		});
 		await (handlerFor(harness, "session_start") as (e: unknown, c: unknown) => Promise<void>)(
 			{ type: "session_start", reason: "startup" },
@@ -317,7 +317,80 @@ describe("proactive refresh", () => {
 		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● deep v0.18.0"));
 		const build = harness.exec.mock.calls.find((call) => (call[1] as string[]).includes("build"))!;
 		expect(build[1]).toEqual(["build", "--deep"]);
-		expect(build[2]).toMatchObject({ env: { GRAFT_PROVIDER: "litellm", GRAFT_MODEL: "deepseek-v4-flash" } });
+		expect(build[2]).toMatchObject({
+			env: {
+				GRAFT_PROVIDER: "litellm",
+				GRAFT_MODEL: "deepseek-v4.1-flash",
+				GRAFT_API_KEY: "test-token",
+				GRAFT_BASE_URL: "https://lite.andlet.me/v1",
+			},
+		});
+	});
+
+	it("retries the deep pass with another scoped model when the active one cannot summarize", async () => {
+		process.env.PI_CODING_AGENT_DIR = agentDir;
+		const bare = join(root, "retry-repo");
+		mkdirSync(join(bare, ".selesai"), { recursive: true });
+		writeFileSync(join(bare, ".selesai", "settings.json"), JSON.stringify({ graft: {} }), "utf-8");
+		const models: string[] = [];
+		const harness = makePi(async (command: string, args: string[], options?: unknown) => {
+			if (command === "git") return { ...OK, stdout: `${bare}\n` };
+			if (args.includes("--version")) return { ...OK, stdout: "0.18.0\n" };
+			if (args.includes("build")) {
+				const model = (options as { env?: Record<string, string> }).env?.GRAFT_MODEL ?? "";
+				models.push(model);
+				if (model === "deepseek-v4.1-flash") {
+					return { ...OK, code: 1, stderr: "calc.ts: model returned no usable symbol summaries [empty-parsed]" };
+				}
+				mkdirSync(join(bare, "graft", ".graph"), { recursive: true });
+				writeFileSync(join(bare, "graft", ".graph", "wiring.json"), "{}", "utf-8");
+				writeFileSync(join(bare, "graft", "concept.md"), "# Concept", "utf-8");
+			}
+			return { ...OK, stdout: ASK_JSON };
+		});
+		graftExtension(harness.pi as never);
+		const ctx = makeCtx({ cwd: bare });
+		Object.assign(ctx, {
+			model: { provider: "tokenin", id: "deepseek-v4.1-flash", baseUrl: "https://lite.andlet.me/v1" },
+			modelRegistry: { getProviderAuth: vi.fn(async () => ({ auth: { apiKey: "test-token" } })) },
+			scopedModels: [{ model: { provider: "tokenin", id: "glm-5.3-flash" } }],
+		});
+		await (handlerFor(harness, "session_start") as (e: unknown, c: unknown) => Promise<void>)(
+			{ type: "session_start", reason: "startup" },
+			ctx,
+		);
+		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● deep v0.18.0"));
+		expect(models).toEqual(["deepseek-v4.1-flash", "glm-5.3-flash"]);
+		expect(notified(ctx)).toContain("retrying the deep pass");
+	});
+
+	it("falls back to the structural build when the active model cannot go deep", async () => {
+		process.env.PI_CODING_AGENT_DIR = agentDir;
+		const bare = join(root, "fallback-repo");
+		mkdirSync(join(bare, ".selesai"), { recursive: true });
+		writeFileSync(join(bare, ".selesai", "settings.json"), JSON.stringify({ graft: {} }), "utf-8");
+		const harness = makePi(async (command: string, args: string[]) => {
+			if (command === "git") return { ...OK, stdout: `${bare}\n` };
+			if (args.includes("--version")) return { ...OK, stdout: "0.18.0\n" };
+			if (args.includes("build")) {
+				mkdirSync(join(bare, "graft", ".graph"), { recursive: true });
+				writeFileSync(join(bare, "graft", ".graph", "wiring.json"), "{}", "utf-8");
+			}
+			return { ...OK, stdout: ASK_JSON };
+		});
+		graftExtension(harness.pi as never);
+		const ctx = makeCtx({ cwd: bare });
+		Object.assign(ctx, {
+			model: { provider: "google", id: "gemini-3-pro" },
+			modelRegistry: { getProviderAuth: vi.fn(async () => ({ auth: { apiKey: "test-key" } })) },
+		});
+		await (handlerFor(harness, "session_start") as (e: unknown, c: unknown) => Promise<void>)(
+			{ type: "session_start", reason: "startup" },
+			ctx,
+		);
+		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● structural v0.18.0"));
+		const build = harness.exec.mock.calls.find((call) => (call[1] as string[]).includes("build"))!;
+		expect(build[1]).toEqual(["build"]);
 	});
 
 	it("re-indexes after edits, shows the sync phase, and returns to fresh", async () => {

package/dist/extensions/pi-graft/state.test.ts

@@ -240,12 +240,18 @@ describe("readGraftSettings", () => {
 				maxInjectionBytes: -1,
 				maxResultBytes: 0,
 				refreshDebounceSeconds: "60",
+				deepModel: "  ",
 				in: "   ",
 			},
 		});
 		expect(read(false)).toEqual({});
 	});
 
+	it("keeps a deep-build model override for the active provider", () => {
+		write(join(agentDir, "settings.json"), { graft: { deepModel: " glm-5.3-flash " } });
+		expect(read(false)).toEqual({ deepModel: "glm-5.3-flash" });
+	});
+
 	it("keeps a valid enabled flag and telemetry preference", () => {
 		write(join(agentDir, "settings.json"), { graft: { enabled: false, telemetry: "inherit" } });
 		expect(read(false)).toEqual({ enabled: false, telemetry: "inherit" });

package/dist/extensions/pi-graft/state.ts

@@ -57,6 +57,11 @@ export interface GraftSettings {
 	in?: string;
 	/** Seconds a mutation stays "changed" before a proactive refresh is attempted. */
 	refreshDebounceSeconds?: number;
+	/**
+	 * Model id for deep builds, on the active provider. Defaults to the active
+	 * model; set it when that model cannot produce Graft-parsable summaries.
+	 */
+	deepModel?: string;
 }
 
 export const SETTINGS_KEY = "graft";
@@ -97,6 +102,7 @@ function normalizeSettings(raw: unknown): GraftSettings {
 		if (typeof candidate === "number" && Number.isFinite(candidate) && candidate > 0) settings[key] = candidate;
 	}
 	if (typeof value.in === "string" && value.in.trim()) settings.in = value.in.trim();
+	if (typeof value.deepModel === "string" && value.deepModel.trim()) settings.deepModel = value.deepModel.trim();
 	return settings;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@selesai/code",
-  "version": "0.13.24",
+  "version": "0.13.25",
   "description": "Maintained, extension-first Pi coding agent with built-in workflows, subagents, web research, questions, skills, and an enhanced terminal UI.",
   "type": "module",
   "repository": {