Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

[RSI] fix(coding-agent): hint full selector form in model validation errors (#2308)

Seth Karten284eebc2d09b
diff --git a/packages/coding-agent/.changes/rlm-model-selector-hint.md b/packages/coding-agent/.changes/rlm-model-selector-hint.md
new file mode 100644
index 0000000000..0665ab0bd3
--- /dev/null
+++ b/packages/coding-agent/.changes/rlm-model-selector-hint.md
@@ -0,0 +1,2 @@
+- Fixed vague subagent and top-level session model validation errors: unambiguous bare model ids (like "z-ai/glm-5.3") now resolve to their full selector ("prime-inference/z-ai/glm-5.3"), and unresolved references state the expected "provider/model-id" form with close matches instead of only "unavailable, unauthenticated, or expired".
+- A bare reference that matches no authenticated catalog model still resolves to the parent model when it matches the parent's full selector, covering offline discovery or expired provider credentials; ambiguous references remain unresolved.
diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts
index 50e0153f08..edd6e1c10c 100644
--- a/packages/coding-agent/src/core/agent-session.ts
+++ b/packages/coding-agent/src/core/agent-session.ts
@@ -260,6 +260,8 @@ import {
createRlmListSubagentsHostHandler,
createRlmRunHostHandler,
findRlmModelMatches,
+ findUniqueRlmShortFormModelMatch,
+ formatRlmModelUnavailableError,
normalizeRequestedRlmSubagentModel,
normalizeRequestedRlmSubagentSessionName,
normalizeRequestedRlmSubagentThinkingLevel,
@@ -11518,11 +11520,17 @@ export class AgentSession {
}
return { model: parentModel };
}
- const model = (await this._authenticatedRlmModels()).find(
- (candidate) => `${candidate.provider}/${candidate.id}`.toLowerCase() === normalizedReference,
- );
+ const candidates = await this._authenticatedRlmModels();
+ // The parent model can be missing from the authenticated catalog (offline
+ // discovery or expired credentials) while staying selectable, so it backs
+ // the short-form lookup when the catalog has no match. Several catalog
+ // matches still leave the reference unresolved.
+ const model =
+ candidates.find(
+ (candidate) => `${candidate.provider}/${candidate.id}`.toLowerCase() === normalizedReference,
+ ) ?? findUniqueRlmShortFormModelMatch(reference, candidates, parentModel);
if (!model) {
- throw new Error(`Requested ${target} model "${reference}" is unavailable, unauthenticated, or expired`);
+ throw new Error(formatRlmModelUnavailableError(reference, target, candidates));
}
const auth = await this._modelRegistry.getApiKeyAndHeaders(model);
diff --git a/packages/coding-agent/src/core/rlm-runtime.ts b/packages/coding-agent/src/core/rlm-runtime.ts
index ea8bdf5946..ac2b1ee95b 100644
--- a/packages/coding-agent/src/core/rlm-runtime.ts
+++ b/packages/coding-agent/src/core/rlm-runtime.ts
@@ -108,6 +108,7 @@ export type RlmFindModelsHandler = (query: string, limit: number) => RlmFindMode
const RLM_SUBAGENT_SESSION_NAME_MAX_LENGTH = 64;
export const DEFAULT_RLM_MODEL_SEARCH_LIMIT = 8;
export const MAX_RLM_MODEL_SEARCH_LIMIT = 20;
+const RLM_MODEL_ERROR_SUGGESTION_LIMIT = 3;
export function normalizeRequestedRlmSubagentSessionName(value: unknown, operation = "rlm.spawn"): string | undefined {
if (value === undefined) {
@@ -214,6 +215,52 @@ export function findRlmModelMatches(query: string, models: Model<Api>[], limit:
}));
}
+/**
+ * Models whose full selector ends with the reference, so a bare model id like
+ * "z-ai/glm-5.3" also matches "prime-inference/z-ai/glm-5.3".
+ */
+function findRlmShortFormModelMatches(reference: string, models: Model<Api>[]): Model<Api>[] {
+ const normalized = reference.trim().toLowerCase();
+ if (!normalized) return [];
+ return models.filter((model) => `${model.provider}/${model.id}`.toLowerCase().endsWith(`/${normalized}`));
+}
+
+/**
+ * The single model a short-form reference resolves to: its unique match among
+ * models, or the fallback model when no model matches. Stays undefined when
+ * several models match, so an ambiguous reference is never auto-resolved.
+ */
+export function findUniqueRlmShortFormModelMatch(
+ reference: string,
+ models: Model<Api>[],
+ fallback?: Model<Api>,
+): Model<Api> | undefined {
+ const matches = findRlmShortFormModelMatches(reference, models);
+ if (matches.length === 1) return matches[0];
+ if (matches.length === 0 && fallback && findRlmShortFormModelMatches(reference, [fallback]).length === 1) {
+ return fallback;
+ }
+ return undefined;
+}
+
+/**
+ * Rejection message for an unresolved model reference: states that the model is
+ * unavailable, unauthenticated, or expired, then the expected selector form and
+ * close matches so the user can retry with a full selector.
+ */
+export function formatRlmModelUnavailableError(reference: string, target: string, models: Model<Api>[]): string {
+ const base = `Requested ${target} model "${reference}" is unavailable, unauthenticated, or expired`;
+ const hint = `selectors use the form "provider/model-id" (e.g. "prime-inference/z-ai/glm-5.3")`;
+ const normalizedReference = normalizeModelSearchText(reference);
+ const closeMatches = normalizedReference
+ ? findRlmModelMatches(reference, models, RLM_MODEL_ERROR_SUGGESTION_LIMIT).map((match) => match.selector)
+ : [];
+ if (closeMatches.length === 0) {
+ return `${base}; ${hint}`;
+ }
+ return `${base}; ${hint}; close matches: ${closeMatches.map((selector) => `"${selector}"`).join(", ")}`;
+}
+
export function createRlmCreateSessionHostHandler(handler: RlmCreateSessionHandler): HostRequestHandler {
return async (payload) => {
if (typeof payload.prompt !== "string") {
diff --git a/packages/coding-agent/test/suite/regressions/4649-subagent-model-selection.test.ts b/packages/coding-agent/test/suite/regressions/4649-subagent-model-selection.test.ts
index 78b2f5ec02..0eb22da67e 100644
--- a/packages/coding-agent/test/suite/regressions/4649-subagent-model-selection.test.ts
+++ b/packages/coding-agent/test/suite/regressions/4649-subagent-model-selection.test.ts
@@ -1,11 +1,16 @@
-import { fauxAssistantMessage } from "@earendil-works/pi-ai";
+import { type Api, fauxAssistantMessage, type Model } from "@earendil-works/pi-ai";
import { describe, expect, it, vi } from "vitest";
import type { HostRequestHandlers } from "../../../src/core/kernel/index.js";
+import { findUniqueRlmShortFormModelMatch, formatRlmModelUnavailableError } from "../../../src/core/rlm-runtime.js";
import { SessionManager } from "../../../src/core/session-manager.js";
import { createHarness } from "../harness.js";
const provider = "faux-eng-4649";
+function catalogModel(provider: string, id: string): Model<Api> {
+ return { id, name: id, provider } as Model<Api>;
+}
+
function openAICodexToken(accountId: string): string {
const payload = Buffer.from(
JSON.stringify({ "https://api.openai.com/auth": { chatgpt_account_id: accountId } }),
@@ -190,6 +195,35 @@ describe("ENG-4649 subagent model selection", () => {
}
});
+ it("resolves the parent model as its own short form when the catalog lacks it", async () => {
+ const codexProvider = "openai-codex";
+ const harness = await createHarness({ provider: codexProvider, models: [{ id: "parent-model" }] });
+ const fetchModels = vi.fn().mockRejectedValue(new Error("offline"));
+ vi.stubGlobal("fetch", fetchModels);
+ try {
+ harness.authStorage.setRuntimeApiKey(codexProvider, openAICodexToken("account-1"));
+ await expect(harness.session.findRlmModels("parent", 8)).resolves.toEqual({ models: [] });
+ harness.setResponses([fauxAssistantMessage("short form parent answer")]);
+
+ const result = await harness.session.runRlmChild("keep the parent model by short form", {
+ model: "parent-model",
+ });
+
+ expect(result.model).toBe(`${codexProvider}/parent-model`);
+ await vi.waitFor(
+ async () => {
+ const childEntry = (await harness.session.listRlmSubagents()).subagents[0];
+ expect(childEntry?.status).toBe("completed");
+ expect(harness.session.getRlmChildSession(childEntry!.rlm_child_id)?.model?.id).toBe("parent-model");
+ },
+ { timeout: 5_000 },
+ );
+ } finally {
+ vi.unstubAllGlobals();
+ harness.cleanup();
+ }
+ });
+
it("does not start a child after its parent is disposed during preflight", async () => {
const harness = await createHarness({
provider,
@@ -457,4 +491,111 @@ describe("ENG-4649 subagent model selection", () => {
harness.cleanup();
}
});
+
+ it("resolves an unambiguous bare model id to its full selector", async () => {
+ const harness = await createHarness({
+ provider,
+ models: [{ id: "parent-model" }, { id: "z-ai/glm-5.3" }],
+ });
+ try {
+ harness.setResponses([fauxAssistantMessage("short form child answer")]);
+
+ const result = await harness.session.runRlmChild("use the reported short form", {
+ model: "z-ai/glm-5.3",
+ });
+
+ expect(result.model).toBe(`${provider}/z-ai/glm-5.3`);
+ await vi.waitFor(async () => {
+ const childEntry = (await harness.session.listRlmSubagents()).subagents[0];
+ expect(childEntry?.status).toBe("completed");
+ expect(harness.session.getRlmChildSession(childEntry!.rlm_child_id)?.model?.id).toBe("z-ai/glm-5.3");
+ });
+ } finally {
+ harness.cleanup();
+ }
+ });
+
+ it("does not auto-resolve an ambiguous bare id and hints the full selectors", async () => {
+ const harness = await createHarness({
+ provider,
+ models: [{ id: "parent-model" }, { id: "glm-5.3" }, { id: "z-ai/glm-5.3" }],
+ });
+ try {
+ await expect(harness.session.runRlmChild("ambiguous bare id", { model: "glm-5.3" })).rejects.toThrow(
+ `close matches: "${provider}/glm-5.3", "${provider}/z-ai/glm-5.3"`,
+ );
+ expect((await harness.session.listRlmSubagents()).subagents).toEqual([]);
+ } finally {
+ harness.cleanup();
+ }
+ });
+
+ it("does not auto-resolve an ambiguous bare id that also matches the parent", async () => {
+ const harness = await createHarness({
+ provider,
+ models: [{ id: "z-ai/glm-5.3" }, { id: "glm-5.3" }, { id: "other/glm-5.3" }],
+ });
+ try {
+ // The parent is the first model, "z-ai/glm-5.3", whose selector ends with
+ // "/glm-5.3"; two other authenticated models share that short form, so the
+ // reference must stay unresolved instead of silently selecting the parent.
+ await expect(harness.session.runRlmChild("ambiguous parent short form", { model: "glm-5.3" })).rejects.toThrow(
+ `close matches: "${provider}/glm-5.3", "${provider}/other/glm-5.3", "${provider}/z-ai/glm-5.3"`,
+ );
+ expect((await harness.session.listRlmSubagents()).subagents).toEqual([]);
+ } finally {
+ harness.cleanup();
+ }
+ });
+
+ it("hints the expected selector form when a requested model is unavailable", async () => {
+ const harness = await createHarness({
+ provider,
+ models: [{ id: "parent-model" }, { id: "z-ai/glm-5.3" }],
+ });
+ try {
+ await expect(harness.session.runRlmChild("unknown short form", { model: "glm-5.4" })).rejects.toThrow(
+ 'selectors use the form "provider/model-id" (e.g. "prime-inference/z-ai/glm-5.3")',
+ );
+ expect((await harness.session.listRlmSubagents()).subagents).toEqual([]);
+ } finally {
+ harness.cleanup();
+ }
+ });
+});
+
+describe("rlm model selector resolution", () => {
+ const primeModel = catalogModel("prime-inference", "z-ai/glm-5.3");
+
+ it("resolves an unambiguous short form to its full selector", () => {
+ expect(findUniqueRlmShortFormModelMatch("z-ai/glm-5.3", [primeModel])).toBe(primeModel);
+ expect(findUniqueRlmShortFormModelMatch("glm-5.3", [primeModel])).toBe(primeModel);
+ });
+
+ it("stays unresolved when a short form matches zero or several models", () => {
+ const otherModel = catalogModel("other-provider", "glm-5.3");
+ expect(findUniqueRlmShortFormModelMatch("glm-5.3", [primeModel, otherModel])).toBeUndefined();
+ expect(findUniqueRlmShortFormModelMatch("glm-5.4", [primeModel, otherModel])).toBeUndefined();
+ });
+
+ it("uses the fallback model only when the catalog has no short-form match", () => {
+ const parentModel = catalogModel("prime-inference", "z-ai/glm-5.3");
+ const siblingModel = catalogModel("other-provider", "z-ai/glm-5.3");
+ expect(findUniqueRlmShortFormModelMatch("glm-5.3", [], parentModel)).toBe(parentModel);
+ expect(findUniqueRlmShortFormModelMatch("glm-5.4", [], parentModel)).toBeUndefined();
+ expect(findUniqueRlmShortFormModelMatch("glm-5.3", [siblingModel], parentModel)).toBe(siblingModel);
+ expect(findUniqueRlmShortFormModelMatch("glm-5.3", [primeModel, siblingModel], parentModel)).toBeUndefined();
+ });
+
+ it("hints the expected selector form when no model resolves", () => {
+ expect(formatRlmModelUnavailableError("glm-5.4", "subagent", [primeModel])).toBe(
+ 'Requested subagent model "glm-5.4" is unavailable, unauthenticated, or expired; selectors use the form "provider/model-id" (e.g. "prime-inference/z-ai/glm-5.3")',
+ );
+ });
+
+ it("lists close matches alongside the form hint", () => {
+ expect(formatRlmModelUnavailableError("glm-5", "top-level session", [primeModel])).toBe(
+ 'Requested top-level session model "glm-5" is unavailable, unauthenticated, or expired; selectors use the form "provider/model-id" (e.g. "prime-inference/z-ai/glm-5.3"); close matches: "prime-inference/z-ai/glm-5.3"',
+ );
+ });
});