Skip to content

The open-source app everyone uses to manage agents at work

feat(adapters/gemini-local): add auth detection, turn-limit handling, sandbox, and approval modes

Aaron4e5f67ef9618
diff --git a/packages/adapters/gemini-local/src/index.ts b/packages/adapters/gemini-local/src/index.ts
index 947d4735ef..2c85dc513b 100644
--- a/packages/adapters/gemini-local/src/index.ts
+++ b/packages/adapters/gemini-local/src/index.ts
@@ -7,6 +7,8 @@ export const models = [
{ id: "gemini-2.5-pro", label: "Gemini 2.5 Pro" },
{ id: "gemini-2.5-flash", label: "Gemini 2.5 Flash" },
{ id: "gemini-2.5-flash-lite", label: "Gemini 2.5 Flash Lite" },
+ { id: "gemini-2.0-flash", label: "Gemini 2.0 Flash" },
+ { id: "gemini-2.0-flash-lite", label: "Gemini 2.0 Flash Lite" },
];
export const agentConfigurationDoc = `# gemini_local agent configuration
@@ -28,7 +30,8 @@ Core fields:
- instructionsFilePath (string, optional): absolute path to a markdown instructions file prepended to the run prompt
- promptTemplate (string, optional): run prompt template
- model (string, optional): Gemini model id. Defaults to auto.
-- yolo (boolean, optional): pass --approval-mode yolo for unattended operation
+- approvalMode (string, optional): "default", "auto_edit", or "yolo" (default: "default")
+- sandbox (boolean, optional): run in sandbox mode (default: false, passes --sandbox=none)
- command (string, optional): defaults to "gemini"
- extraArgs (string[], optional): additional CLI args
- env (object, optional): KEY=VALUE environment variables
diff --git a/packages/adapters/gemini-local/src/server/execute.ts b/packages/adapters/gemini-local/src/server/execute.ts
index 457284fa99..f9495a4ba2 100644
--- a/packages/adapters/gemini-local/src/server/execute.ts
+++ b/packages/adapters/gemini-local/src/server/execute.ts
@@ -19,7 +19,13 @@ import {
runChildProcess,
} from "@paperclipai/adapter-utils/server-utils";
import { DEFAULT_GEMINI_LOCAL_MODEL } from "../index.js";
-import { isGeminiUnknownSessionError, parseGeminiJsonl } from "./parse.js";
+import {
+ describeGeminiFailure,
+ detectGeminiAuthRequired,
+ isGeminiTurnLimitResult,
+ isGeminiUnknownSessionError,
+ parseGeminiJsonl,
+} from "./parse.js";
import { firstNonEmptyLine } from "./utils.js";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -93,7 +99,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
);
const command = asString(config.command, "gemini");
const model = asString(config.model, DEFAULT_GEMINI_LOCAL_MODEL).trim();
- const yolo = asBoolean(config.yolo, false);
+ const approvalMode = asString(config.approvalMode, asBoolean(config.yolo, false) ? "yolo" : "default");
+ const sandbox = asBoolean(config.sandbox, false);
const workspaceContext = parseObject(context.paperclipWorkspace);
const workspaceCwd = asString(workspaceContext.cwd, "");
@@ -211,7 +218,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
}
const commandNotes = (() => {
const notes: string[] = ["Prompt is passed to Gemini as the final positional argument."];
- if (yolo) notes.push("Added --approval-mode yolo for unattended execution.");
+ if (approvalMode !== "default") notes.push(`Added --approval-mode ${approvalMode} for unattended execution.`);
if (!instructionsFilePath) return notes;
if (instructionsPrefix.length > 0) {
notes.push(
@@ -242,7 +249,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
const args = ["--output-format", "stream-json"];
if (resumeSessionId) args.push("--resume", resumeSessionId);
if (model && model !== DEFAULT_GEMINI_LOCAL_MODEL) args.push("--model", model);
- if (yolo) args.push("--approval-mode", "yolo");
+ if (approvalMode !== "default") args.push("--approval-mode", approvalMode);
+ if (sandbox) {
+ args.push("--sandbox");
+ } else {
+ args.push("--sandbox=none");
+ }
if (extraArgs.length > 0) args.push(...extraArgs);
args.push(prompt);
return args;
@@ -290,18 +302,31 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
parsed: ReturnType<typeof parseGeminiJsonl>;
},
clearSessionOnMissingSession = false,
+ isRetry = false,
): AdapterExecutionResult => {
+ const authMeta = detectGeminiAuthRequired({
+ parsed: attempt.parsed.resultEvent,
+ stdout: attempt.proc.stdout,
+ stderr: attempt.proc.stderr,
+ });
+
if (attempt.proc.timedOut) {
return {
exitCode: attempt.proc.exitCode,
signal: attempt.proc.signal,
timedOut: true,
errorMessage: `Timed out after ${timeoutSec}s`,
+ errorCode: authMeta.requiresAuth ? "gemini_auth_required" : null,
clearSession: clearSessionOnMissingSession,
};
}
- const resolvedSessionId = attempt.parsed.sessionId ?? runtimeSessionId ?? runtime.sessionId ?? null;
+ const clearSessionForTurnLimit = isGeminiTurnLimitResult(attempt.parsed.resultEvent, attempt.proc.exitCode);
+
+ // On retry, don't fall back to old session ID — the old session was stale
+ const canFallbackToRuntimeSession = !isRetry;
+ const resolvedSessionId = attempt.parsed.sessionId
+ ?? (canFallbackToRuntimeSession ? (runtimeSessionId ?? runtime.sessionId ?? null) : null);
const resolvedSessionParams = resolvedSessionId
? ({
sessionId: resolvedSessionId,
@@ -313,8 +338,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
: null;
const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
+ const structuredFailure = attempt.parsed.resultEvent
+ ? describeGeminiFailure(attempt.parsed.resultEvent)
+ : null;
const fallbackErrorMessage =
parsedError ||
+ structuredFailure ||
stderrLine ||
`Gemini exited with code ${attempt.proc.exitCode ?? -1}`;
@@ -323,6 +352,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
signal: attempt.proc.signal,
timedOut: false,
errorMessage: (attempt.proc.exitCode ?? 0) === 0 ? null : fallbackErrorMessage,
+ errorCode: authMeta.requiresAuth ? "gemini_auth_required" : null,
usage: attempt.parsed.usage,
sessionId: resolvedSessionId,
sessionParams: resolvedSessionParams,
@@ -331,12 +361,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
model,
billingType,
costUsd: attempt.parsed.costUsd,
- resultJson: {
+ resultJson: attempt.parsed.resultEvent ?? {
stdout: attempt.proc.stdout,
stderr: attempt.proc.stderr,
},
summary: attempt.parsed.summary,
- clearSession: Boolean(clearSessionOnMissingSession && !resolvedSessionId),
+ clearSession: clearSessionForTurnLimit || Boolean(clearSessionOnMissingSession && !resolvedSessionId),
};
};
@@ -353,7 +383,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
`[paperclip] Gemini resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
);
const retry = await runAttempt(null);
- return toResult(retry, true);
+ return toResult(retry, true, true);
}
return toResult(initial);
diff --git a/packages/adapters/gemini-local/src/server/index.ts b/packages/adapters/gemini-local/src/server/index.ts
index 22b04f31be..1d35a2bf2b 100644
--- a/packages/adapters/gemini-local/src/server/index.ts
+++ b/packages/adapters/gemini-local/src/server/index.ts
@@ -1,6 +1,12 @@
export { execute } from "./execute.js";
export { testEnvironment } from "./test.js";
-export { parseGeminiJsonl, isGeminiUnknownSessionError } from "./parse.js";
+export {
+ parseGeminiJsonl,
+ isGeminiUnknownSessionError,
+ describeGeminiFailure,
+ detectGeminiAuthRequired,
+ isGeminiTurnLimitResult,
+} from "./parse.js";
import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
function readNonEmptyString(value: unknown): string | null {
diff --git a/packages/adapters/gemini-local/src/server/parse.ts b/packages/adapters/gemini-local/src/server/parse.ts
index e700815b84..343961f939 100644
--- a/packages/adapters/gemini-local/src/server/parse.ts
+++ b/packages/adapters/gemini-local/src/server/parse.ts
@@ -77,6 +77,7 @@ export function parseGeminiJsonl(stdout: string) {
const messages: string[] = [];
let errorMessage: string | null = null;
let costUsd: number | null = null;
+ let resultEvent: Record<string, unknown> | null = null;
const usage = {
inputTokens: 0,
cachedInputTokens: 0,
@@ -101,6 +102,7 @@ export function parseGeminiJsonl(stdout: string) {
}
if (type === "result") {
+ resultEvent = event;
accumulateUsage(usage, event.usage ?? event.usageMetadata);
const resultText =
asString(event.result, "").trim() ||
@@ -151,6 +153,7 @@ export function parseGeminiJsonl(stdout: string) {
usage,
costUsd,
errorMessage,
+ resultEvent,
};
}
@@ -165,3 +168,75 @@ export function isGeminiUnknownSessionError(stdout: string, stderr: string): boo
haystack,
);
}
+
+function extractGeminiErrorMessages(parsed: Record<string, unknown>): string[] {
+ const messages: string[] = [];
+ const errorMsg = asString(parsed.error, "").trim();
+ if (errorMsg) messages.push(errorMsg);
+
+ const raw = Array.isArray(parsed.errors) ? parsed.errors : [];
+ for (const entry of raw) {
+ if (typeof entry === "string") {
+ const msg = entry.trim();
+ if (msg) messages.push(msg);
+ continue;
+ }
+ if (typeof entry !== "object" || entry === null || Array.isArray(entry)) continue;
+ const obj = entry as Record<string, unknown>;
+ const msg = asString(obj.message, "") || asString(obj.error, "") || asString(obj.code, "");
+ if (msg) {
+ messages.push(msg);
+ continue;
+ }
+ try {
+ messages.push(JSON.stringify(obj));
+ } catch {
+ // skip non-serializable entry
+ }
+ }
+
+ return messages;
+}
+
+export function describeGeminiFailure(parsed: Record<string, unknown>): string | null {
+ const status = asString(parsed.status, "");
+ const errors = extractGeminiErrorMessages(parsed);
+
+ const detail = errors[0] ?? "";
+ const parts = ["Gemini run failed"];
+ if (status) parts.push(`status=${status}`);
+ if (detail) parts.push(detail);
+ return parts.length > 1 ? parts.join(": ") : null;
+}
+
+const GEMINI_AUTH_REQUIRED_RE = /(?:not\s+authenticated|please\s+authenticate|api[_ ]?key\s+(?:required|missing|invalid)|authentication\s+required|unauthorized|invalid\s+credentials|GEMINI_API_KEY|GOOGLE_API_KEY|not\s+logged\s+in|login\s+required|run\s+`?gemini\s+auth(?:\s+login)?`?\s+first)/i;
+
+export function detectGeminiAuthRequired(input: {
+ parsed: Record<string, unknown> | null;
+ stdout: string;
+ stderr: string;
+}): { requiresAuth: boolean } {
+ const errors = extractGeminiErrorMessages(input.parsed ?? {});
+ const messages = [...errors, input.stdout, input.stderr]
+ .join("\n")
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .filter(Boolean);
+
+ const requiresAuth = messages.some((line) => GEMINI_AUTH_REQUIRED_RE.test(line));
+ return { requiresAuth };
+}
+
+export function isGeminiTurnLimitResult(
+ parsed: Record<string, unknown> | null | undefined,
+ exitCode?: number | null,
+): boolean {
+ if (exitCode === 53) return true;
+ if (!parsed) return false;
+
+ const status = asString(parsed.status, "").trim().toLowerCase();
+ if (status === "turn_limit" || status === "max_turns") return true;
+
+ const error = asString(parsed.error, "").trim();
+ return /turn\s*limit|max(?:imum)?\s+turns?/i.test(error);
+}
diff --git a/packages/adapters/gemini-local/src/server/test.ts b/packages/adapters/gemini-local/src/server/test.ts
index 49bdb28f92..b7762af865 100644
--- a/packages/adapters/gemini-local/src/server/test.ts
+++ b/packages/adapters/gemini-local/src/server/test.ts
@@ -15,7 +15,7 @@ import {
runChildProcess,
} from "@paperclipai/adapter-utils/server-utils";
import { DEFAULT_GEMINI_LOCAL_MODEL } from "../index.js";
-import { parseGeminiJsonl } from "./parse.js";
+import { detectGeminiAuthRequired, parseGeminiJsonl } from "./parse.js";
import { firstNonEmptyLine } from "./utils.js";
function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
@@ -41,9 +41,6 @@ function summarizeProbeDetail(stdout: string, stderr: string, parsedError: strin
return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
}
-const GEMINI_AUTH_REQUIRED_RE =
- /(?:authentication\s+required|not\s+authenticated|not\s+logged\s+in|login\s+required|unauthorized|invalid(?:\s+or\s+missing)?\s+api(?:[_\s-]?key)?|gemini[_\s-]?api[_\s-]?key|google[_\s-]?api[_\s-]?key|run\s+`?gemini\s+auth(?:\s+login)?`?\s+first|api(?:[_\s-]?key)?(?:\s+is)?\s+required)/i;
-
export async function testEnvironment(
ctx: AdapterEnvironmentTestContext,
): Promise<AdapterEnvironmentTestResult> {
@@ -94,15 +91,19 @@ export async function testEnvironment(
const hostGeminiApiKey = process.env.GEMINI_API_KEY;
const configGoogleApiKey = env.GOOGLE_API_KEY;
const hostGoogleApiKey = process.env.GOOGLE_API_KEY;
+ const hasGca = env.GOOGLE_GENAI_USE_GCA === "true" || process.env.GOOGLE_GENAI_USE_GCA === "true";
if (
isNonEmpty(configGeminiApiKey) ||
isNonEmpty(hostGeminiApiKey) ||
isNonEmpty(configGoogleApiKey) ||
- isNonEmpty(hostGoogleApiKey)
+ isNonEmpty(hostGoogleApiKey) ||
+ hasGca
) {
- const source = isNonEmpty(configGeminiApiKey) || isNonEmpty(configGoogleApiKey)
- ? "adapter config env"
- : "server environment";
+ const source = hasGca
+ ? "Google account login (GCA)"
+ : isNonEmpty(configGeminiApiKey) || isNonEmpty(configGoogleApiKey)
+ ? "adapter config env"
+ : "server environment";
checks.push({
code: "gemini_api_key_present",
level: "info",
@@ -114,7 +115,7 @@ export async function testEnvironment(
code: "gemini_api_key_missing",
level: "warn",
message: "No Gemini API key was detected. Gemini runs may fail until auth is configured.",
- hint: "Set GEMINI_API_KEY or GOOGLE_API_KEY in adapter env/shell, or run `gemini auth` / `gemini auth login`.",
+ hint: "Set GEMINI_API_KEY or GOOGLE_API_KEY in adapter env/shell, run `gemini auth` / `gemini auth login`, or set GOOGLE_GENAI_USE_GCA=true for Google account auth.",
});
}
@@ -158,7 +159,11 @@ export async function testEnvironment(
);
const parsed = parseGeminiJsonl(probe.stdout);
const detail = summarizeProbeDetail(probe.stdout, probe.stderr, parsed.errorMessage);
- const authEvidence = `${parsed.errorMessage ?? ""}\n${probe.stdout}\n${probe.stderr}`.trim();
+ const authMeta = detectGeminiAuthRequired({
+ parsed: parsed.resultEvent,
+ stdout: probe.stdout,
+ stderr: probe.stderr,
+ });
if (probe.timedOut) {
checks.push({
@@ -183,7 +188,7 @@ export async function testEnvironment(
hint: "Try `gemini --output-format json \"Respond with hello.\"` manually to inspect full output.",
}),
});
- } else if (GEMINI_AUTH_REQUIRED_RE.test(authEvidence)) {
+ } else if (authMeta.requiresAuth) {
checks.push({
code: "gemini_hello_probe_auth_required",
level: "warn",
diff --git a/packages/adapters/gemini-local/src/ui/build-config.ts b/packages/adapters/gemini-local/src/ui/build-config.ts
index 12f6257eee..1fd7ac65a2 100644
--- a/packages/adapters/gemini-local/src/ui/build-config.ts
+++ b/packages/adapters/gemini-local/src/ui/build-config.ts
@@ -67,7 +67,8 @@ export function buildGeminiLocalConfig(v: CreateConfigValues): Record<string, un
}
}
if (Object.keys(env).length > 0) ac.env = env;
- if (v.dangerouslyBypassSandbox) ac.yolo = true;
+ if (v.dangerouslyBypassSandbox) ac.approvalMode = "yolo";
+ ac.sandbox = !v.dangerouslyBypassSandbox;
if (v.command) ac.command = v.command;
if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
return ac;