mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 20:29:18 +01:00
Stage the selected agent account in a private remote home and restore refreshed credentials before cleanup. Preserve remote authentication for existing SSH environments and expose it as an advanced option. Co-Authored-By: Paperclip <noreply@paperclip.ing>
825 lines
34 KiB
TypeScript
825 lines
34 KiB
TypeScript
import { createProviderStoppedBoundary } from "@paperclipai/adapter-utils/provider-stopped-boundary";
|
|
import { createUsageCheckpointLog } from "@paperclipai/adapter-utils/usage-checkpoint";
|
|
import fs from "node:fs/promises";
|
|
import type { Dirent } from "node:fs";
|
|
import os from "node:os";
|
|
import path from "node:path";
|
|
import { fileURLToPath } from "node:url";
|
|
import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
|
|
import {
|
|
managedRemoteHomeEnvironment,
|
|
adapterExecutionTargetIsRemote,
|
|
adapterExecutionTargetRemoteCwd,
|
|
overrideAdapterExecutionTargetRemoteCwd,
|
|
adapterExecutionTargetSessionIdentity,
|
|
adapterExecutionTargetSessionMatches,
|
|
adapterExecutionTargetUsesManagedHome,
|
|
adapterExecutionTargetUsesPaperclipBridge,
|
|
describeAdapterExecutionTarget,
|
|
ensureAdapterExecutionTargetCommandResolvable,
|
|
ensureAdapterExecutionTargetRuntimeCommandInstalled,
|
|
prepareAdapterExecutionTargetRuntime,
|
|
adapterExecutionTargetDuplexObservabilityRecorder,
|
|
adapterExecutionTargetEnablesSandboxDuplexBridge,
|
|
readAdapterExecutionTarget,
|
|
readAdapterExecutionTargetHomeDir,
|
|
resolveAdapterExecutionTargetTimeoutSec,
|
|
resolveAdapterExecutionTargetCommandForLogs,
|
|
runAdapterExecutionTargetProcess,
|
|
runAdapterExecutionTargetShellCommand,
|
|
startAdapterExecutionTargetPaperclipBridge,
|
|
} from "@paperclipai/adapter-utils/execution-target";
|
|
import {
|
|
asBoolean,
|
|
asNumber,
|
|
asString,
|
|
asStringArray,
|
|
buildPaperclipEnv,
|
|
buildRuntimeToolsEnv,
|
|
buildInvocationEnvForLogs,
|
|
ensureAbsoluteDirectory,
|
|
ensurePaperclipSkillSymlink,
|
|
joinPromptSections,
|
|
ensurePathInEnv,
|
|
refreshPaperclipWorkspaceEnvForExecution,
|
|
isPaperclipSkillSourceMissing,
|
|
readPaperclipRuntimeSkillEntries,
|
|
readPaperclipIssueWorkModeFromContext,
|
|
resolveLegacyPaperclipDesiredSkillNames,
|
|
removeMaintainerOnlySkillSymlinks,
|
|
parseObject,
|
|
renderTemplate,
|
|
hydrateFreshSessionHandoff,
|
|
selectPaperclipPromptSections,
|
|
selectInitialCommunicationGuidance,
|
|
isPaperclipRecoveryWakePayload,
|
|
DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
|
|
DEFAULT_PAPERCLIP_CONVERSATION_PROMPT_TEMPLATE,
|
|
runChildProcess,
|
|
} from "@paperclipai/adapter-utils/server-utils";
|
|
import { DEFAULT_GEMINI_LOCAL_MODEL, SANDBOX_INSTALL_COMMAND } from "../index.js";
|
|
import {
|
|
describeGeminiFailure,
|
|
detectGeminiAuthRequired,
|
|
isGeminiTransientNetworkError,
|
|
isGeminiTurnLimitResult,
|
|
isGeminiSessionUnrecoverableError,
|
|
parseGeminiJsonl, createGeminiJsonlParser,
|
|
} from "./parse.js";
|
|
import { firstNonEmptyLine } from "./utils.js";
|
|
import {
|
|
createGeminiAcpExecutor,
|
|
resolveGeminiExecutionEngineForRun,
|
|
} from "./acp.js";
|
|
import { resolveGeminiSkillsHome } from "./skills.js";
|
|
|
|
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
|
|
const executeGeminiAcp = createGeminiAcpExecutor();
|
|
|
|
function hasNonEmptyEnvValue(env: Record<string, string>, key: string): boolean {
|
|
const raw = env[key];
|
|
return typeof raw === "string" && raw.trim().length > 0;
|
|
}
|
|
|
|
function resolveGeminiBillingType(env: Record<string, string>): "api" | "subscription" {
|
|
return hasNonEmptyEnvValue(env, "GEMINI_API_KEY") || hasNonEmptyEnvValue(env, "GOOGLE_API_KEY")
|
|
? "api"
|
|
: "subscription";
|
|
}
|
|
|
|
function buildGeminiHeadlessEnv(env: Record<string, string>): Record<string, string> {
|
|
const next = { ...env };
|
|
const term = env.TERM?.trim().toLowerCase();
|
|
if (!term || term === "dumb" || term === "vt100") {
|
|
next.TERM = "xterm-256color";
|
|
}
|
|
if (!next.COLORTERM?.trim()) {
|
|
next.COLORTERM = "truecolor";
|
|
}
|
|
next.NO_BROWSER = "1";
|
|
delete next.NO_COLOR;
|
|
return next;
|
|
}
|
|
|
|
function buildGeminiRuntimeEnv(env: Record<string, string>): Record<string, string> {
|
|
return Object.fromEntries(
|
|
Object.entries(ensurePathInEnv({ ...process.env, ...buildGeminiHeadlessEnv(env) })).filter(
|
|
(entry): entry is [string, string] => typeof entry[1] === "string",
|
|
),
|
|
);
|
|
}
|
|
|
|
function renderPaperclipEnvNote(env: Record<string, string>): string {
|
|
const paperclipKeys = Object.keys(env)
|
|
.filter((key) => key.startsWith("PAPERCLIP_"))
|
|
.sort();
|
|
if (paperclipKeys.length === 0) return "";
|
|
return [
|
|
"Paperclip runtime note:",
|
|
`The following PAPERCLIP_* environment variables are available in this run: ${paperclipKeys.join(", ")}`,
|
|
"Do not assume these variables are missing without checking your shell environment.",
|
|
"",
|
|
"",
|
|
].join("\n");
|
|
}
|
|
|
|
function renderApiAccessNote(env: Record<string, string>): string {
|
|
if (!hasNonEmptyEnvValue(env, "PAPERCLIP_API_URL") || !hasNonEmptyEnvValue(env, "PAPERCLIP_API_KEY")) return "";
|
|
return [
|
|
"Paperclip API access note:",
|
|
"Use run_shell_command with curl to make Paperclip API requests.",
|
|
"GET example:",
|
|
` run_shell_command({ command: "curl -s -H \\"Authorization: Bearer $PAPERCLIP_API_KEY\\" \\"$PAPERCLIP_API_URL/api/agents/me\\"" })`,
|
|
"POST/PATCH example:",
|
|
` run_shell_command({ command: "curl -s -X POST -H \\"Authorization: Bearer $PAPERCLIP_API_KEY\\" -H 'Content-Type: application/json' -H \\"X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID\\" -d '{...}' \\"$PAPERCLIP_API_URL/api/issues/$PAPERCLIP_TASK_ID/checkout\\"" })`,
|
|
"When PAPERCLIP_TASK_ID is not set, substitute a real issue id from the current context; never send a placeholder like {id} in the URL.",
|
|
"",
|
|
"",
|
|
].join("\n");
|
|
}
|
|
|
|
/**
|
|
* Inject Paperclip skills directly into the effective Gemini skills home.
|
|
* This avoids needing GEMINI_CLI_HOME overrides, so the CLI naturally finds
|
|
* both its auth credentials and the injected skills under the child HOME.
|
|
*/
|
|
async function ensureGeminiSkillsInjected(
|
|
onLog: AdapterExecutionContext["onLog"],
|
|
skillsEntries: Array<{ key: string; runtimeName: string; source: string }>,
|
|
desiredSkillNames?: string[],
|
|
skillsHome = resolveGeminiSkillsHome({}),
|
|
): Promise<void> {
|
|
const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.key));
|
|
const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.key));
|
|
if (selectedEntries.length === 0) return;
|
|
|
|
try {
|
|
await fs.mkdir(skillsHome, { recursive: true });
|
|
} catch (err) {
|
|
await onLog(
|
|
"stderr",
|
|
`[paperclip] Failed to prepare Gemini skills directory ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
|
|
);
|
|
return;
|
|
}
|
|
const removedSkills = await removeMaintainerOnlySkillSymlinks(
|
|
skillsHome,
|
|
selectedEntries.map((entry) => entry.runtimeName),
|
|
);
|
|
for (const skillName of removedSkills) {
|
|
await onLog(
|
|
"stderr",
|
|
`[paperclip] Removed maintainer-only Gemini skill "${skillName}" from ${skillsHome}\n`,
|
|
);
|
|
}
|
|
|
|
for (const entry of selectedEntries) {
|
|
const target = path.join(skillsHome, entry.runtimeName);
|
|
|
|
try {
|
|
const result = await ensurePaperclipSkillSymlink(entry.source, target);
|
|
if (result === "skipped") continue;
|
|
await onLog(
|
|
"stderr",
|
|
`[paperclip] ${result === "repaired" ? "Repaired" : "Linked"} Gemini skill: ${entry.key}\n`,
|
|
);
|
|
} catch (err) {
|
|
await onLog(
|
|
"stderr",
|
|
`[paperclip] Failed to link Gemini skill "${entry.key}": ${err instanceof Error ? err.message : String(err)}\n`,
|
|
);
|
|
}
|
|
}
|
|
}
|
|
|
|
async function buildGeminiSkillsDir(
|
|
config: Record<string, unknown>,
|
|
): Promise<string> {
|
|
const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-gemini-skills-"));
|
|
const target = path.join(tmp, "skills");
|
|
await fs.mkdir(target, { recursive: true });
|
|
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
|
|
const desiredNames = new Set(resolveLegacyPaperclipDesiredSkillNames(config, availableEntries));
|
|
for (const entry of availableEntries) {
|
|
if (!desiredNames.has(entry.key)) continue;
|
|
if (isPaperclipSkillSourceMissing(entry)) continue;
|
|
await fs.symlink(entry.source, path.join(target, entry.runtimeName));
|
|
}
|
|
return target;
|
|
}
|
|
|
|
export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
|
|
const providerStop = createProviderStoppedBoundary(ctx.onProviderStopped);
|
|
const engineSelection = await resolveGeminiExecutionEngineForRun(ctx);
|
|
if (engineSelection.unavailableReason) {
|
|
return {
|
|
exitCode: 1,
|
|
signal: null,
|
|
timedOut: false,
|
|
errorCode: "adapter_engine_unavailable",
|
|
errorMessage: engineSelection.unavailableReason,
|
|
resultJson: {
|
|
executionRecovery: { kind: "bootstrap", providerWorkStarted: false },
|
|
},
|
|
};
|
|
}
|
|
if (engineSelection.engine === "acp") {
|
|
return executeGeminiAcp(ctx);
|
|
}
|
|
|
|
const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;
|
|
const executionTarget = readAdapterExecutionTarget({
|
|
executionTarget: ctx.executionTarget,
|
|
legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
|
|
});
|
|
const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);
|
|
|
|
const promptTemplate = asString(
|
|
config.promptTemplate,
|
|
context.conversationMode === true
|
|
? DEFAULT_PAPERCLIP_CONVERSATION_PROMPT_TEMPLATE
|
|
: DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
|
|
);
|
|
const command = asString(config.command, "gemini");
|
|
const model = asString(config.model, DEFAULT_GEMINI_LOCAL_MODEL).trim();
|
|
const sandbox = asBoolean(config.sandbox, false);
|
|
|
|
const workspaceContext = parseObject(context.paperclipWorkspace);
|
|
const workspaceCwd = asString(workspaceContext.cwd, "");
|
|
const workspaceSource = asString(workspaceContext.source, "");
|
|
const workspaceId = asString(workspaceContext.workspaceId, "");
|
|
const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
|
|
const workspaceRepoRef = asString(workspaceContext.repoRef, "");
|
|
const agentHome = asString(workspaceContext.agentHome, "");
|
|
const workspaceHints = Array.isArray(context.paperclipWorkspaces)
|
|
? context.paperclipWorkspaces.filter(
|
|
(value): value is Record<string, unknown> => typeof value === "object" && value !== null,
|
|
)
|
|
: [];
|
|
const configuredCwd = asString(config.cwd, "");
|
|
const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
|
|
const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
|
|
const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
|
|
let effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);
|
|
await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
|
|
const geminiSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
|
|
const desiredGeminiSkillNames = resolveLegacyPaperclipDesiredSkillNames(config, geminiSkillEntries);
|
|
if (!executionTargetIsRemote) {
|
|
await ensureGeminiSkillsInjected(
|
|
onLog,
|
|
geminiSkillEntries.filter((entry) => !isPaperclipSkillSourceMissing(entry)),
|
|
desiredGeminiSkillNames,
|
|
resolveGeminiSkillsHome(config),
|
|
);
|
|
}
|
|
|
|
const envConfig = parseObject(config.env);
|
|
const env: Record<string, string> = {
|
|
...buildPaperclipEnv(agent, ctx.agentIdentity),
|
|
...buildRuntimeToolsEnv(ctx.runtimeTools),
|
|
};
|
|
env.PAPERCLIP_RUN_ID = runId;
|
|
const wakeTaskId =
|
|
(typeof context.taskId === "string" && context.taskId.trim().length > 0 && context.taskId.trim()) ||
|
|
(typeof context.issueId === "string" && context.issueId.trim().length > 0 && context.issueId.trim()) ||
|
|
null;
|
|
const wakeReason =
|
|
typeof context.wakeReason === "string" && context.wakeReason.trim().length > 0
|
|
? context.wakeReason.trim()
|
|
: null;
|
|
const wakeCommentId =
|
|
(typeof context.wakeCommentId === "string" && context.wakeCommentId.trim().length > 0 && context.wakeCommentId.trim()) ||
|
|
(typeof context.commentId === "string" && context.commentId.trim().length > 0 && context.commentId.trim()) ||
|
|
null;
|
|
const approvalId =
|
|
typeof context.approvalId === "string" && context.approvalId.trim().length > 0
|
|
? context.approvalId.trim()
|
|
: null;
|
|
const approvalStatus =
|
|
typeof context.approvalStatus === "string" && context.approvalStatus.trim().length > 0
|
|
? context.approvalStatus.trim()
|
|
: null;
|
|
const linkedIssueIds = Array.isArray(context.issueIds)
|
|
? context.issueIds.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
|
|
: [];
|
|
const issueWorkMode = readPaperclipIssueWorkModeFromContext(context);
|
|
if (wakeTaskId) env.PAPERCLIP_TASK_ID = wakeTaskId;
|
|
if (issueWorkMode) env.PAPERCLIP_ISSUE_WORK_MODE = issueWorkMode;
|
|
if (wakeReason) env.PAPERCLIP_WAKE_REASON = wakeReason;
|
|
if (wakeCommentId) env.PAPERCLIP_WAKE_COMMENT_ID = wakeCommentId;
|
|
if (approvalId) env.PAPERCLIP_APPROVAL_ID = approvalId;
|
|
if (approvalStatus) env.PAPERCLIP_APPROVAL_STATUS = approvalStatus;
|
|
if (linkedIssueIds.length > 0) env.PAPERCLIP_LINKED_ISSUE_IDS = linkedIssueIds.join(",");
|
|
refreshPaperclipWorkspaceEnvForExecution({
|
|
env,
|
|
envConfig,
|
|
workspaceCwd: effectiveWorkspaceCwd,
|
|
workspaceSource,
|
|
workspaceId,
|
|
workspaceRepoUrl,
|
|
workspaceRepoRef,
|
|
workspaceHints,
|
|
agentHome,
|
|
executionTargetIsRemote,
|
|
executionCwd: effectiveExecutionCwd,
|
|
});
|
|
if (executionTargetIsRemote && typeof env.GEMINI_CLI_TRUST_WORKSPACE !== "string") {
|
|
env.GEMINI_CLI_TRUST_WORKSPACE = "true";
|
|
}
|
|
if (authToken) {
|
|
env.PAPERCLIP_API_KEY = authToken;
|
|
}
|
|
const runtimeEnv = buildGeminiRuntimeEnv(env);
|
|
const billingType = resolveGeminiBillingType(runtimeEnv);
|
|
const timeoutSec = resolveAdapterExecutionTargetTimeoutSec(
|
|
executionTarget,
|
|
asNumber(config.timeoutSec, 0),
|
|
);
|
|
const graceSec = asNumber(config.graceSec, 20);
|
|
await ensureAdapterExecutionTargetRuntimeCommandInstalled({
|
|
runId,
|
|
target: executionTarget,
|
|
installCommand: ctx.runtimeCommandSpec?.installCommand,
|
|
detectCommand: ctx.runtimeCommandSpec?.detectCommand,
|
|
cwd,
|
|
env: runtimeEnv,
|
|
timeoutSec,
|
|
graceSec,
|
|
onLog,
|
|
});
|
|
await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv, {
|
|
installCommand: SANDBOX_INSTALL_COMMAND,
|
|
timeoutSec,
|
|
});
|
|
const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);
|
|
const extraArgs = (() => {
|
|
const fromExtraArgs = asStringArray(config.extraArgs);
|
|
if (fromExtraArgs.length > 0) return fromExtraArgs;
|
|
return asStringArray(config.args);
|
|
})();
|
|
let restoreRemoteWorkspace: (() => Promise<void>) | null = null;
|
|
let remoteSkillsDir: string | null = null;
|
|
let localSkillsDir: string | null = null;
|
|
let remoteRuntimeRootDir: string | null = null;
|
|
let paperclipBridge: Awaited<ReturnType<typeof startAdapterExecutionTargetPaperclipBridge>> = null;
|
|
|
|
try {
|
|
if (executionTargetIsRemote) {
|
|
try {
|
|
localSkillsDir = await buildGeminiSkillsDir(config);
|
|
await onLog(
|
|
"stdout",
|
|
`[paperclip] Syncing workspace and Gemini runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
|
|
);
|
|
const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
|
|
privateRuntime: Boolean(config.managedAiConnection),
|
|
runId,
|
|
target: executionTarget,
|
|
adapterKey: "gemini",
|
|
timeoutSec,
|
|
workspaceLocalDir: cwd,
|
|
installCommand: SANDBOX_INSTALL_COMMAND,
|
|
detectCommand: command,
|
|
onProgress: (line) => onLog("stdout", line),
|
|
onRuntimeProgress: ctx.onRuntimeProgress,
|
|
assets: [{
|
|
key: "skills",
|
|
localDir: localSkillsDir,
|
|
followSymlinks: true,
|
|
}],
|
|
});
|
|
restoreRemoteWorkspace = () =>
|
|
preparedExecutionTargetRuntime.restoreWorkspace((line) => onLog("stdout", line));
|
|
effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
|
|
refreshPaperclipWorkspaceEnvForExecution({
|
|
env,
|
|
envConfig,
|
|
workspaceCwd: effectiveWorkspaceCwd,
|
|
workspaceSource,
|
|
workspaceId,
|
|
workspaceRepoUrl,
|
|
workspaceRepoRef,
|
|
workspaceHints,
|
|
agentHome,
|
|
executionTargetIsRemote,
|
|
executionCwd: effectiveExecutionCwd,
|
|
});
|
|
remoteRuntimeRootDir = preparedExecutionTargetRuntime.runtimeRootDir;
|
|
if (executionTarget?.kind === "remote" && executionTarget.transport === "ssh" && executionTarget.spec.useHostAuth === false && config.managedAiConnection && remoteRuntimeRootDir) Object.assign(env, managedRemoteHomeEnvironment(remoteRuntimeRootDir));
|
|
const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget, Boolean(config.managedAiConnection));
|
|
const managedRemoteHomeDir =
|
|
managedHome && preparedExecutionTargetRuntime.runtimeRootDir
|
|
? preparedExecutionTargetRuntime.runtimeRootDir
|
|
: null;
|
|
if (managedRemoteHomeDir) {
|
|
env.HOME = managedRemoteHomeDir;
|
|
}
|
|
const remoteHomeDir =
|
|
managedRemoteHomeDir ??
|
|
(await readAdapterExecutionTargetHomeDir(runId, executionTarget, {
|
|
cwd,
|
|
env,
|
|
timeoutSec,
|
|
graceSec,
|
|
onLog,
|
|
}));
|
|
if (remoteHomeDir && preparedExecutionTargetRuntime.assetDirs.skills) {
|
|
remoteSkillsDir = path.posix.join(remoteHomeDir, ".gemini", "skills");
|
|
await runAdapterExecutionTargetShellCommand(
|
|
runId,
|
|
executionTarget,
|
|
`mkdir -p ${JSON.stringify(path.posix.dirname(remoteSkillsDir))} && rm -rf ${JSON.stringify(remoteSkillsDir)} && cp -a ${JSON.stringify(preparedExecutionTargetRuntime.assetDirs.skills)} ${JSON.stringify(remoteSkillsDir)}`,
|
|
{ cwd, env, timeoutSec, graceSec, onLog },
|
|
);
|
|
}
|
|
// Gemini CLI refuses headless runs without an auth selection persisted in
|
|
// $HOME/.gemini/settings.json ("Invalid auth method selected."); env vars
|
|
// alone (GEMINI_DEFAULT_AUTH_TYPE) do not satisfy it. With a managed HOME
|
|
// the runtime root replaces the image home, so any settings baked into the
|
|
// image are invisible -- pre-select the api-key auth whenever an API key
|
|
// is provided. Both settings schema generations are written (legacy
|
|
// selectedAuthType + current security.auth.selectedType). An existing
|
|
// settings.json (user-shipped via workspace) is left untouched.
|
|
// Only the managed HOME (the per-run runtime root) is touched: on
|
|
// non-managed remote targets remoteHomeDir is the user's real home, where
|
|
// creating files is out of scope and existing settings remain visible.
|
|
// Key presence check spans the run env AND the host process env: in the
|
|
// managed sandbox path the key never enters the adapter's run env -- it
|
|
// reaches the agent pod via the provider's per-run secret (envKeys
|
|
// passthrough from the host env), so the host env is the signal here.
|
|
const hasGeminiApiKey = Boolean(
|
|
env.GEMINI_API_KEY || env.GOOGLE_API_KEY ||
|
|
process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY,
|
|
);
|
|
if (managedRemoteHomeDir && hasGeminiApiKey) {
|
|
const remoteSettingsPath = path.posix.join(managedRemoteHomeDir, ".gemini", "settings.json");
|
|
const authSettingsJson = JSON.stringify({
|
|
selectedAuthType: "gemini-api-key",
|
|
security: { auth: { selectedType: "gemini-api-key" } },
|
|
});
|
|
await runAdapterExecutionTargetShellCommand(
|
|
runId,
|
|
executionTarget,
|
|
`mkdir -p ${JSON.stringify(path.posix.dirname(remoteSettingsPath))} && { [ -f ${JSON.stringify(remoteSettingsPath)} ] || printf '%s' ${JSON.stringify(authSettingsJson)} > ${JSON.stringify(remoteSettingsPath)}; }`,
|
|
{ cwd, env, timeoutSec, graceSec, onLog },
|
|
);
|
|
}
|
|
} catch (error) {
|
|
await Promise.allSettled([
|
|
restoreRemoteWorkspace?.(),
|
|
localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
|
|
]);
|
|
restoreRemoteWorkspace = null;
|
|
throw error;
|
|
}
|
|
}
|
|
const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
|
|
if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(executionTarget)) {
|
|
paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
|
|
runId,
|
|
target: runtimeExecutionTarget,
|
|
enableSandboxDuplexBridge: adapterExecutionTargetEnablesSandboxDuplexBridge(runtimeExecutionTarget),
|
|
duplexObservabilityRecorder: adapterExecutionTargetDuplexObservabilityRecorder(runtimeExecutionTarget),
|
|
runtimeRootDir: remoteRuntimeRootDir,
|
|
adapterKey: "gemini",
|
|
timeoutSec,
|
|
hostApiToken: env.PAPERCLIP_API_KEY,
|
|
onLog,
|
|
});
|
|
if (paperclipBridge) {
|
|
Object.assign(env, paperclipBridge.env);
|
|
}
|
|
}
|
|
|
|
const runtimeSessionParams = parseObject(runtime.sessionParams);
|
|
const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
|
|
const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
|
|
const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
|
|
const canResumeSession =
|
|
runtimeSessionId.length > 0 &&
|
|
(runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
|
|
adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
|
|
const sessionId = canResumeSession ? runtimeSessionId : null;
|
|
if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
|
|
await onLog(
|
|
"stdout",
|
|
`[paperclip] Gemini session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,
|
|
);
|
|
} else if (runtimeSessionId && !canResumeSession) {
|
|
await onLog(
|
|
"stdout",
|
|
`[paperclip] Gemini session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
|
|
);
|
|
}
|
|
|
|
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
|
|
const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
|
|
let instructionsPrefix = "";
|
|
if (instructionsFilePath) {
|
|
try {
|
|
const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
|
|
instructionsPrefix =
|
|
`${instructionsContents}\n\n` +
|
|
`The above agent instructions were loaded from ${instructionsFilePath}. ` +
|
|
`Resolve any relative file references from ${instructionsDir}.\n\n`;
|
|
} catch (err) {
|
|
const reason = err instanceof Error ? err.message : String(err);
|
|
await onLog(
|
|
"stdout",
|
|
`[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
|
|
);
|
|
}
|
|
}
|
|
const commandNotes = (() => {
|
|
const notes: string[] = ["Prompt is passed to Gemini via --prompt for non-interactive execution."];
|
|
notes.push("Added --approval-mode yolo for unattended execution.");
|
|
notes.push("Set headless terminal/browser env so Gemini fails fast instead of opening interactive auth or color prompts.");
|
|
if (executionTargetIsRemote) {
|
|
notes.push("Set GEMINI_CLI_TRUST_WORKSPACE=true for remote headless execution.");
|
|
}
|
|
if (!instructionsFilePath) return notes;
|
|
if (instructionsPrefix.length > 0) {
|
|
notes.push(
|
|
`Loaded agent instructions from ${instructionsFilePath}`,
|
|
`Prepended instructions + path directive to prompt (relative references from ${instructionsDir}).`,
|
|
);
|
|
return notes;
|
|
}
|
|
notes.push(
|
|
`Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
|
|
);
|
|
return notes;
|
|
})();
|
|
|
|
const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
|
|
const templateData = {
|
|
agentId: agent.id,
|
|
companyId: agent.companyId,
|
|
runId,
|
|
company: { id: agent.companyId },
|
|
agent,
|
|
run: { id: runId, source: "on_demand" },
|
|
context,
|
|
};
|
|
const buildPrompt = (resumedSession: boolean) => {
|
|
const renderedBootstrapPrompt =
|
|
!resumedSession && bootstrapPromptTemplate.trim().length > 0
|
|
? renderTemplate(bootstrapPromptTemplate, templateData).trim()
|
|
: "";
|
|
const { taskContextNote, wakePrompt } = selectPaperclipPromptSections(context, {
|
|
resumedSession,
|
|
includeCommunicationGuidance: false,
|
|
});
|
|
const shouldUseResumeDeltaPrompt = resumedSession && wakePrompt.length > 0;
|
|
const renderedPrompt = shouldUseResumeDeltaPrompt || isPaperclipRecoveryWakePayload(context.paperclipWake)
|
|
? ""
|
|
: renderTemplate(promptTemplate, templateData);
|
|
const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
|
|
const paperclipEnvNote = renderPaperclipEnvNote(env);
|
|
const apiAccessNote = renderApiAccessNote(env);
|
|
const basePrompt = joinPromptSections([
|
|
instructionsPrefix,
|
|
renderedBootstrapPrompt,
|
|
wakePrompt,
|
|
taskContextNote,
|
|
sessionHandoffNote,
|
|
paperclipEnvNote,
|
|
apiAccessNote,
|
|
renderedPrompt,
|
|
]);
|
|
return {
|
|
basePrompt,
|
|
promptMetrics: {
|
|
promptChars: basePrompt.length,
|
|
instructionsChars: instructionsPrefix.length,
|
|
bootstrapPromptChars: renderedBootstrapPrompt.length,
|
|
wakePromptChars: wakePrompt.length,
|
|
taskContextChars: taskContextNote.length,
|
|
sessionHandoffChars: sessionHandoffNote.length,
|
|
runtimeNoteChars: paperclipEnvNote.length + apiAccessNote.length,
|
|
heartbeatPromptChars: renderedPrompt.length,
|
|
},
|
|
};
|
|
};
|
|
|
|
const buildArgs = (resumeSessionId: string | null, prompt: string) => {
|
|
const args = ["--output-format", "stream-json"];
|
|
if (resumeSessionId) args.push("--resume", resumeSessionId);
|
|
if (model && model !== DEFAULT_GEMINI_LOCAL_MODEL) args.push("--model", model);
|
|
args.push("--approval-mode", "yolo");
|
|
if (sandbox) {
|
|
args.push("--sandbox");
|
|
} else {
|
|
args.push("--sandbox=none");
|
|
}
|
|
if (extraArgs.length > 0) args.push(...extraArgs);
|
|
args.push("--prompt", prompt);
|
|
return args;
|
|
};
|
|
|
|
const runAttempt = async (resumeSessionId: string | null) => {
|
|
await hydrateFreshSessionHandoff(ctx, { resumedSession: Boolean(resumeSessionId) });
|
|
const { basePrompt, promptMetrics } = buildPrompt(Boolean(resumeSessionId));
|
|
const prompt = joinPromptSections([
|
|
selectInitialCommunicationGuidance(context, { resumedSession: Boolean(resumeSessionId) }),
|
|
basePrompt,
|
|
]);
|
|
const args = buildArgs(resumeSessionId, prompt);
|
|
const invocationEnv = buildGeminiHeadlessEnv(env);
|
|
const invocationRuntimeEnv = buildGeminiRuntimeEnv(env);
|
|
const loggedEnv = buildInvocationEnvForLogs(invocationEnv, {
|
|
runtimeEnv: invocationRuntimeEnv,
|
|
includeRuntimeKeys: ["HOME"],
|
|
resolvedCommand,
|
|
});
|
|
if (onMeta) {
|
|
await onMeta({
|
|
adapterType: "gemini_local",
|
|
command: resolvedCommand,
|
|
cwd: effectiveExecutionCwd,
|
|
commandNotes,
|
|
commandArgs: args.map((value, index) => (
|
|
index === args.length - 1 ? `<prompt ${prompt.length} chars>` : value
|
|
)),
|
|
env: loggedEnv,
|
|
prompt,
|
|
promptMetrics: { ...promptMetrics, promptChars: prompt.length },
|
|
context,
|
|
});
|
|
}
|
|
|
|
const consumeAccounting = createGeminiJsonlParser();
|
|
const accountingLog = createUsageCheckpointLog(onLog, ctx.onUsage, stdout => {
|
|
const parsed = consumeAccounting(stdout);
|
|
return { usage: parsed.usage, costUsd: parsed.costUsd, usageBasis: "per_run", provider: "google", biller: "google", billingType, model, complete: parsed.resultEvent !== null };
|
|
});
|
|
const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
|
|
onProcessStopped: providerStop.beginInvocation(),
|
|
cwd,
|
|
env: invocationEnv,
|
|
timeoutSec,
|
|
graceSec,
|
|
onSpawn,
|
|
onRuntimeProgress: ctx.onRuntimeProgress,
|
|
onLog: accountingLog,
|
|
runLogTail: paperclipBridge?.runLogTail,
|
|
settleRunDisposition: paperclipBridge?.settleRunDisposition,
|
|
});
|
|
await accountingLog.flush();
|
|
return {
|
|
proc,
|
|
parsed: parseGeminiJsonl(proc.stdout),
|
|
};
|
|
};
|
|
|
|
const toResult = (
|
|
attempt: {
|
|
proc: {
|
|
exitCode: number | null;
|
|
signal: string | null;
|
|
timedOut: boolean;
|
|
stdout: string;
|
|
stderr: string;
|
|
errorCode?: string | null;
|
|
};
|
|
parsed: ReturnType<typeof parseGeminiJsonl>;
|
|
},
|
|
clearSessionOnMissingSession = false,
|
|
isRetry = false,
|
|
): AdapterExecutionResult => {
|
|
const authMeta = detectGeminiAuthRequired({
|
|
parsed: attempt.parsed.resultEvent,
|
|
stdout: attempt.proc.stdout,
|
|
stderr: attempt.proc.stderr,
|
|
});
|
|
const networkUnavailable = isGeminiTransientNetworkError(attempt.proc.stdout, attempt.proc.stderr);
|
|
|
|
if (attempt.proc.timedOut) {
|
|
return {
|
|
exitCode: attempt.proc.exitCode,
|
|
signal: attempt.proc.signal,
|
|
timedOut: true,
|
|
usageComplete: attempt.parsed.resultEvent !== null,
|
|
usage: attempt.parsed.usage,
|
|
usageBasis: "per_run",
|
|
provider: "google",
|
|
biller: "google",
|
|
model,
|
|
billingType,
|
|
costUsd: attempt.parsed.costUsd,
|
|
errorMessage: `Timed out after ${timeoutSec}s`,
|
|
errorCode: authMeta.requiresAuth
|
|
? "gemini_auth_required"
|
|
: networkUnavailable
|
|
? "gemini_network_unavailable"
|
|
: null,
|
|
clearSession: clearSessionOnMissingSession,
|
|
};
|
|
}
|
|
|
|
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}`;
|
|
const failed = (attempt.proc.exitCode ?? 0) !== 0;
|
|
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,
|
|
cwd: effectiveExecutionCwd,
|
|
...(workspaceId ? { workspaceId } : {}),
|
|
...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
|
|
...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
|
|
...(executionTargetIsRemote
|
|
? {
|
|
remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
|
|
}
|
|
: {}),
|
|
} as Record<string, unknown>)
|
|
: null;
|
|
const resultJson: Record<string, unknown> = {
|
|
...(attempt.parsed.resultEvent ?? {
|
|
stdout: attempt.proc.stdout,
|
|
stderr: attempt.proc.stderr,
|
|
}),
|
|
...(failed && clearSessionForTurnLimit ? { stopReason: "max_turns_exhausted" } : {}),
|
|
};
|
|
|
|
return {
|
|
exitCode: attempt.proc.exitCode,
|
|
signal: attempt.proc.signal,
|
|
timedOut: false,
|
|
usageComplete: attempt.parsed.resultEvent !== null,
|
|
usageBasis: "per_run",
|
|
errorMessage: failed ? fallbackErrorMessage : null,
|
|
// Forward the transport-level error code from the run-disposition seam
|
|
// first. A lost duplex control channel surfaces the typed
|
|
// `duplex_channel_lost` code before any provider classification.
|
|
errorCode: attempt.proc.errorCode
|
|
? attempt.proc.errorCode
|
|
: failed && authMeta.requiresAuth
|
|
? "gemini_auth_required"
|
|
: failed && clearSessionForTurnLimit
|
|
? "max_turns_exhausted"
|
|
: failed && networkUnavailable
|
|
? "gemini_network_unavailable"
|
|
: null,
|
|
usage: attempt.parsed.usage,
|
|
sessionId: resolvedSessionId,
|
|
sessionParams: resolvedSessionParams,
|
|
sessionDisplayId: resolvedSessionId,
|
|
provider: "google",
|
|
biller: "google",
|
|
model,
|
|
billingType,
|
|
costUsd: attempt.parsed.costUsd,
|
|
resultJson,
|
|
summary: attempt.parsed.summary,
|
|
question: attempt.parsed.question,
|
|
clearSession: clearSessionForTurnLimit || Boolean(clearSessionOnMissingSession && !resolvedSessionId),
|
|
};
|
|
};
|
|
|
|
const initial = await runAttempt(sessionId);
|
|
if (
|
|
sessionId &&
|
|
!initial.proc.timedOut &&
|
|
(initial.proc.exitCode ?? 0) !== 0 &&
|
|
isGeminiSessionUnrecoverableError(initial.proc.stdout, initial.proc.stderr)
|
|
) {
|
|
await onLog(
|
|
"stdout",
|
|
`[paperclip] Gemini resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
|
|
);
|
|
const retry = await runAttempt(null);
|
|
return toResult(retry, true, true);
|
|
}
|
|
|
|
return toResult(initial);
|
|
} finally {
|
|
try {
|
|
await providerStop.collectBeforeRestore();
|
|
} finally {
|
|
await Promise.all([
|
|
paperclipBridge?.stop(),
|
|
restoreRemoteWorkspace?.(),
|
|
localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
|
|
]);
|
|
}
|
|
}
|
|
}
|