mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agent runs can use remote sandboxes that a sandbox provider plugin supplies (for example Daytona) > - Each sandbox operation resolves the environment config, and that step reads the provider config schema to find the secret-ref fields > - On a hosted instance with 7 remote runs, this schema read was the most frequent statement: 17.95 per second, about 2.5 per second for each run > - The server runs all agents on one Node main thread, so each statement costs main-thread time; at 1,000 agents this read alone is about 2,500 statements per second > - This pull request reuses the retained schema for a short, bounded time and drops it at once when the plugin registry changes a plugin manifest > - The benefit is that a live remote run reads the schema about once per 5 seconds for each provider, not once per operation ## Linked Issues or Issue Description **What existing behavior does this improve?** Every plugin sandbox operation (exec, file sync in/out, runner ingress attach, capability snapshot, workspace realize, lease resume, lease release) calls `resolveEnvironmentDriverConfigForRuntime`. That call runs the `with selected_provider as materialized ...` statement in `resolvePluginSandboxProviderConfigSchema`, every time. **Subsystem affected** Server: plugin environment driver (`server/src/services/plugin-environment-driver.ts`) and the plugin registry manifest writes. **Current behavior** The schema read runs once per operation. A census test that drives the real runtime calls of one remote run counts 19 schema reads for 19 operations (see the table below). The hosted measurement was 17.95 executions per second with 7 runs. **Proposed behavior** The read runs at most once per 5 seconds for each provider and database client. A plugin install, upgrade or uninstall through the plugin registry in the same process takes effect on the next operation. **Reason and benefit** The schema is instance-wide plugin manifest data. It does not change during normal runs. Re-reading it per operation spends main-thread and database time for no new information. **Breaking changes** None. No API, schema or saved-state change. ## What Changed - `resolvePluginSandboxProviderConfigSchema` now returns the retained schema without a database read when the entry was checked less than `PROVIDER_SCHEMA_REUSE_MS` (5,000 ms) ago and the plugin manifest revision did not change. After that, it uses the existing cheap revision check, as before. - A lookup sequence number stops an older, slower lookup from replacing a newer retained entry. - A missing provider is still never retained, so a provider that becomes available is used on the next operation. - New module `plugin-manifest-revision.ts` holds an in-process manifest revision counter. It is a separate module so that the registry and the driver do not import each other. - `plugin-registry.ts`: `install` (both the new-row and the reinstall paths), `update` and `uninstall` announce a manifest change after the write completes. This is 5 changed lines plus 1 import line. Status-only writes do not announce, because the schema read does not use plugin status. - `plugin-loader.ts`: `installPlugin` runs `registry.install` inside an outer transaction. It now announces the manifest change again after that transaction settles, so a schema read made before the commit cannot be reused after it. This is 1 changed line plus 1 import line. - Statement census per operation, before and after. One remote run, one secret-ref field in the provider config, embedded test database, fake in-process plugin worker: | Operation | Count | Schema reads before | Schema reads after | All statements before | All statements after | | --- | --- | --- | --- | --- | --- | | Lease acquire | 1 | 1 | 1 | 26 | 26 | | Runner attach (ingress endpoint) | 1 | 2 | 0 | 11 | 9 | | Capability snapshot | 1 | 1 | 0 | 6 | 5 | | Exec | 10 | 10 | 0 | 50 | 40 | | File write (sync in) | 1 | 1 | 0 | 5 | 4 | | File read (sync out) | 1 | 1 | 0 | 5 | 4 | | Workspace realize | 1 | 1 | 0 | 5 | 4 | | Lease resume (reattach) | 1 | 1 | 0 | 6 | 5 | | Lease release | 1 | 1 | 0 | 18 | 17 | | **Total** | 18 | **19** | **1** | 132 | 114 | - Other reads that stay on each operation (reported, not changed in this pull request): each exec resolves each secret-ref field with 3 reads (secret, binding, version) and 1 `secret_access_events` insert. Runner attach and the capability snapshot also read the plugin row by id. These are part of the secret authorization and audit path, so they keep their own checks. ## Verification - `cd server && npx vitest run src/__tests__/plugin-sandbox-provider-schema-census.test.ts` (new). On master the census test fails with 19 schema reads. With this change it passes with 1. - The new tests also prove these points: - A registry upgrade that changes the secret-ref fields takes effect on the next call in the same process. - A direct manifest change (as from another server process) takes effect after the 5-second bound, and no read occurs inside the bound. - A registry uninstall takes effect at once. - A plugin reinstall through `pluginLoader.installPlugin` takes effect after its install transaction commits, even when a schema read ran inside the uncommitted transaction. This test failed before the post-commit announcement and passes with it. - A missing provider is not retained. The next call after install reads and uses it. - Two companies share the provider schema but each gets only its own secret values. A cross-company secret id still fails with "Secret must belong to same company". - A new database client (a process restart) starts cold, as before. - `cd server && npx vitest run src/__tests__/plugin-database.test.ts`: passed (plugin install transaction paths). - `cd server && npx vitest run src/__tests__/sandbox-provider-schema-reads.test.ts`: the existing tests now step the clock past the bound where they change the database directly. - `cd server && npx vitest run src/__tests__/environment-runtime.test.ts`: 210 passed. - `cd server && npx vitest run src/__tests__/bundled-plugin-registration.test.ts src/__tests__/external-object-refresh-work.test.ts src/__tests__/plugin-lifecycle-restart.test.ts src/__tests__/plugin-loader-error-retry.test.ts src/__tests__/plugin-environment-driver-sandbox-capabilities.test.ts src/__tests__/plugin-sandbox-provider-config-validation.test.ts src/__tests__/environment-probe.test.ts`: 82 passed, 1 skipped. - `cd server && pnpm typecheck`: passed. ## Risks - Staleness bound: a plugin manifest change made by a different server process (for example during an overlapping deploy) can take up to 5 seconds to apply here. During that time, a secret-ref field that an upgrade adds is not resolved yet, and a field that an upgrade removes is still resolved. The bound is short and it applies only to which config paths are secret refs. - The retained value is instance-wide plugin manifest data, keyed by database client and driver key. It contains no company data and no secret values. It does not take part in an authorization decision. Secret resolution, the environment binding check and the access audit still run on each operation for the calling company. - Memory stays bounded by the existing limits: 32 entries per database client, 64 KiB per schema. - `plugin-registry.ts` has a small edit in `install`, `update` and `uninstall`. Other open work in that file can cause a simple merge conflict. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file edit, test runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Refs #17581 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
809 lines
32 KiB
TypeScript
809 lines
32 KiB
TypeScript
import { agents, plugins, type Db } from "@paperclipai/db";
|
|
import { and, eq, inArray, isNull, or, sql } from "drizzle-orm";
|
|
import { conflict } from "../errors.js";
|
|
import type {
|
|
EnvironmentProbeResult,
|
|
PluginEnvironmentConfig,
|
|
PluginEnvironmentDriverDeclaration,
|
|
} from "@paperclipai/shared";
|
|
import type {
|
|
PluginEnvironmentExecuteParams,
|
|
PluginEnvironmentExecuteResult,
|
|
PluginEnvironmentInteractiveSetupSession,
|
|
PluginEnvironmentStartInteractiveSetupParams,
|
|
PluginEnvironmentGetInteractiveSetupParams,
|
|
PluginEnvironmentCaptureTemplateParams,
|
|
PluginEnvironmentCaptureTemplateResult,
|
|
PluginEnvironmentCancelInteractiveSetupParams,
|
|
PluginEnvironmentCancelInteractiveSetupResult,
|
|
PluginEnvironmentDeleteTemplateParams,
|
|
PluginEnvironmentDeleteTemplateResult,
|
|
PluginEnvironmentLease,
|
|
PluginEnvironmentRealizeWorkspaceParams,
|
|
PluginEnvironmentRealizeWorkspaceResult,
|
|
} from "@paperclipai/plugin-sdk";
|
|
import { unprocessable } from "../errors.js";
|
|
import {
|
|
collectSecretRefPaths,
|
|
parseSecretRefBindingObject,
|
|
readConfigValueAtPath,
|
|
writeConfigValueAtPath,
|
|
} from "./json-schema-secret-refs.js";
|
|
import { pluginManifestRevision } from "./plugin-manifest-revision.js";
|
|
import { pluginRegistryService } from "./plugin-registry.js";
|
|
import type { PluginWorkerManager } from "./plugin-worker-manager.js";
|
|
|
|
type AgentEnvironmentRef = { driver: string; config: Record<string, unknown> | null };
|
|
type AgentEnvironmentPlugin = {
|
|
pluginKey: string;
|
|
manifestJson: { environmentDrivers?: Array<{ driverKey: string; kind?: string; requiresAgent?: boolean }> };
|
|
};
|
|
|
|
export function pluginHasAgentEnvironments(plugin: AgentEnvironmentPlugin) {
|
|
const drivers = plugin.manifestJson.environmentDrivers?.filter(driver => driver.requiresAgent === true) ?? [];
|
|
return drivers.length > 0 && drivers.every(driver => driver.kind !== "sandbox_provider");
|
|
}
|
|
|
|
export function pluginServesAgentEnvironment(plugin: AgentEnvironmentPlugin, environment: AgentEnvironmentRef | null | undefined) {
|
|
if (environment?.driver !== "plugin" || environment.config?.pluginKey !== plugin.pluginKey) return false;
|
|
return plugin.manifestJson.environmentDrivers?.some(driver => driver.requiresAgent === true && driver.kind !== "sandbox_provider"
|
|
&& driver.driverKey === environment.config?.driverKey) ?? false;
|
|
}
|
|
|
|
export async function pluginForAgentEnvironment(db: Db, environment: AgentEnvironmentRef) {
|
|
const pluginKey = environment.config?.pluginKey;
|
|
if (environment.driver !== "plugin" || typeof pluginKey !== "string") return null;
|
|
const plugin = await pluginRegistryService(db).getByKey(pluginKey);
|
|
return plugin && pluginServesAgentEnvironment(plugin, environment) ? plugin : null;
|
|
}
|
|
|
|
/** Whether a saved environment change would give active agents a plugin that has not prepared them. */
|
|
export async function agentsNeedSetupForEnvironmentChange(db: Db, before: AgentEnvironmentRef | null | undefined,
|
|
after: AgentEnvironmentRef | null | undefined, users: { environmentId?: string; inheritsDefault: boolean }) {
|
|
const plugin = after ? await pluginForAgentEnvironment(db, after) : null;
|
|
if (!plugin || (before && (await pluginForAgentEnvironment(db, before))?.id === plugin.id)) return false;
|
|
const usesEnvironment = or(users.environmentId ? eq(agents.defaultEnvironmentId, users.environmentId) : undefined,
|
|
users.inheritsDefault ? isNull(agents.defaultEnvironmentId) : undefined);
|
|
if (!usesEnvironment) return false;
|
|
const [waiting] = await db.select({ id: agents.id }).from(agents).where(and(usesEnvironment,
|
|
inArray(agents.lifecycleState, ["ready", "verifying"]),
|
|
sql`not coalesce(${agents.lifecycleRequiredPluginIds}, '[]'::jsonb) @> ${JSON.stringify([plugin.id])}::jsonb`)).limit(1);
|
|
return Boolean(waiting);
|
|
}
|
|
|
|
/** Throws when a saved environment would give active agents a plugin that has not prepared them. */
|
|
export async function assertAgentsReadyForEnvironmentChange(db: Db, before: AgentEnvironmentRef | null | undefined,
|
|
after: AgentEnvironmentRef | null | undefined, users: { environmentId?: string; inheritsDefault: boolean }) {
|
|
if (await agentsNeedSetupForEnvironmentChange(db, before, after, users)) {
|
|
throw conflict("Agents that use this environment need setup first. Pause those agents, save this change, and then resume them.",
|
|
{ code: "environment_requires_agent_setup" });
|
|
}
|
|
}
|
|
|
|
export async function pluginEnvironmentRequiresAgent(db: Db, environment: AgentEnvironmentRef) {
|
|
return await pluginForAgentEnvironment(db, environment) !== null;
|
|
}
|
|
|
|
/**
|
|
* The worker methods a sandbox provider must advertise before the host reuses
|
|
* a provider lease across runs. The host resumes a lease through
|
|
* `environmentResumeLease`, ends it through `environmentReleaseLease`, and tears
|
|
* down a stale lease through `environmentDestroyLease`. The reuse path destroys
|
|
* the stale lease when a resume fails and then acquires a fresh lease, so a
|
|
* provider that omits any of the three methods can strand the stale lease and
|
|
* can never complete the reuse path.
|
|
*
|
|
* The runtime capability normalizer maps `reusableLeases` to these same methods,
|
|
* so the acquisition guard, the effective-capability snapshot, and the published
|
|
* provider-capabilities value all read one source and cannot drift.
|
|
*/
|
|
export const REUSABLE_LEASE_WORKER_METHODS = [
|
|
"environmentResumeLease",
|
|
"environmentReleaseLease",
|
|
"environmentDestroyLease",
|
|
] as const;
|
|
|
|
/**
|
|
* The worker methods a sandbox provider must advertise before the customImage
|
|
* setup gate in `environment-custom-images.ts` allows an interactive setup
|
|
* session. The setup lifecycle starts a session through
|
|
* `environmentStartInteractiveSetup`, polls it through
|
|
* `environmentGetInteractiveSetup`, and cancels it through
|
|
* `environmentCancelInteractiveSetup`. A provider that omits any of the three
|
|
* can strand a setup session partway through the lifecycle.
|
|
*/
|
|
export const INTERACTIVE_SETUP_WORKER_METHODS = [
|
|
"environmentStartInteractiveSetup",
|
|
"environmentGetInteractiveSetup",
|
|
"environmentCancelInteractiveSetup",
|
|
] as const;
|
|
|
|
/** The worker method the customImage template-capture gate in `environment-custom-images.ts` requires. */
|
|
export const TEMPLATE_CAPTURE_WORKER_METHODS = [
|
|
"environmentCaptureTemplate",
|
|
] as const;
|
|
|
|
/** The worker method the customImage template-delete gate in `environment-custom-images.ts` requires. */
|
|
export const TEMPLATE_DELETE_WORKER_METHODS = [
|
|
"environmentDeleteTemplate",
|
|
] as const;
|
|
|
|
export interface ReadyPluginWorkerRecovery {
|
|
pluginKeys: readonly string[];
|
|
startWorker(plugin: { id: string; pluginKey: string }): Promise<boolean>;
|
|
timeoutMs?: number;
|
|
}
|
|
|
|
/** Shared admission/presentation check for allocation, recovery, cleanup and PTY transport. */
|
|
export function pluginSupportsLoginPty(
|
|
driver: Pick<PluginEnvironmentDriverDeclaration, "supportsLoginPty" | "creationOperationVersion">,
|
|
methods: readonly string[],
|
|
requireCredentialRead = false,
|
|
): boolean {
|
|
return driver.supportsLoginPty === true && driver.creationOperationVersion === 1 && [
|
|
"environmentAcquireLease", "environmentInspectLease", "environmentReleaseLease",
|
|
"loginPtyOpen", "loginPtyInput", "loginPtyStop", "loginPtyClose",
|
|
...(requireCredentialRead ? ["loginPtyReadCredential"] : []),
|
|
].every(method => methods.includes(method));
|
|
}
|
|
|
|
export interface ReadyPluginEnvironmentDriver {
|
|
pluginId: string;
|
|
pluginKey: string;
|
|
driverKey: string;
|
|
displayName: string;
|
|
description?: string;
|
|
configSchema: PluginEnvironmentDriverDeclaration["configSchema"];
|
|
supportsReusableLeases?: PluginEnvironmentDriverDeclaration["supportsReusableLeases"];
|
|
sandboxCapabilities?: PluginEnvironmentDriverDeclaration["sandboxCapabilities"];
|
|
/**
|
|
* The running worker for this exact plugin advertises ALL reusable-lease
|
|
* lifecycle methods (`REUSABLE_LEASE_WORKER_METHODS`: resume, release, and
|
|
* destroy). The published provider-capabilities value grants reusable leases
|
|
* only when the declaration allows them AND this flag is true, so presentation
|
|
* matches the acquisition guard, which also verifies the same methods live.
|
|
*/
|
|
reusableLeaseMethodsVerified: boolean;
|
|
supportsCodexLogin?: boolean;
|
|
supportsInteractiveSetup?: PluginEnvironmentDriverDeclaration["supportsInteractiveSetup"];
|
|
interactiveSetupConnectionTypes?: PluginEnvironmentDriverDeclaration["interactiveSetupConnectionTypes"];
|
|
supportsTemplateCapture?: PluginEnvironmentDriverDeclaration["supportsTemplateCapture"];
|
|
templateRefKind?: PluginEnvironmentDriverDeclaration["templateRefKind"];
|
|
templateConfigBinding?: PluginEnvironmentDriverDeclaration["templateConfigBinding"];
|
|
supportsTemplateDelete?: PluginEnvironmentDriverDeclaration["supportsTemplateDelete"];
|
|
supportsLoginPty?: PluginEnvironmentDriverDeclaration["supportsLoginPty"];
|
|
}
|
|
|
|
export function pluginDriverProviderKey(config: Pick<PluginEnvironmentConfig, "pluginKey" | "driverKey">): string {
|
|
return `${config.pluginKey}:${config.driverKey}`;
|
|
}
|
|
|
|
const DEFAULT_READY_PLUGIN_WORKER_RECOVERY_TIMEOUT_MS = 2_000;
|
|
|
|
async function resolveWithTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutValue: T): Promise<T> {
|
|
if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return await promise;
|
|
let timeout: ReturnType<typeof setTimeout> | null = null;
|
|
try {
|
|
return await Promise.race([
|
|
promise,
|
|
new Promise<T>((resolve) => {
|
|
timeout = setTimeout(() => resolve(timeoutValue), timeoutMs);
|
|
}),
|
|
]);
|
|
} finally {
|
|
if (timeout) clearTimeout(timeout);
|
|
}
|
|
}
|
|
|
|
export async function resolvePluginEnvironmentDriver(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
config: PluginEnvironmentConfig;
|
|
}) {
|
|
const pluginRegistry = pluginRegistryService(input.db);
|
|
const plugin = await pluginRegistry.getByKey(input.config.pluginKey);
|
|
if (!plugin || plugin.status !== "ready") {
|
|
throw new Error(`Plugin environment driver "${pluginDriverProviderKey(input.config)}" is not ready.`);
|
|
}
|
|
const driver = plugin.manifestJson.environmentDrivers?.find(
|
|
(candidate) => candidate.driverKey === input.config.driverKey,
|
|
);
|
|
if (!driver) {
|
|
throw new Error(`Plugin "${input.config.pluginKey}" does not declare environment driver "${input.config.driverKey}".`);
|
|
}
|
|
if (!input.workerManager.isRunning(plugin.id)) {
|
|
throw new Error(`Plugin environment driver "${pluginDriverProviderKey(input.config)}" has no running worker.`);
|
|
}
|
|
return { plugin, driver };
|
|
}
|
|
|
|
export async function resolvePluginEnvironmentDriverByKey(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
driverKey: string;
|
|
}) {
|
|
return await resolvePluginSandboxProviderDriverByKey({
|
|
db: input.db,
|
|
driverKey: input.driverKey,
|
|
workerManager: input.workerManager,
|
|
requireRunning: true,
|
|
});
|
|
}
|
|
|
|
type CachedProviderSchema = {
|
|
pluginId: string; revision: string; schema: Record<string, unknown> | null;
|
|
checkedAt: number; manifestRevision: number; lookup: number;
|
|
};
|
|
const providerSchemas = new WeakMap<Db, Map<string, CachedProviderSchema>>();
|
|
const MAX_CACHED_PROVIDER_SCHEMAS = 32;
|
|
const MAX_CACHED_PROVIDER_SCHEMA_BYTES = 64 * 1024;
|
|
export const PROVIDER_SCHEMA_REUSE_MS = 5_000;
|
|
let providerSchemaLookups = 0;
|
|
|
|
export async function resolvePluginSandboxProviderConfigSchema(input: {
|
|
db: Db; driverKey: string;
|
|
}): Promise<Record<string, unknown> | null> {
|
|
const { db, driverKey } = input;
|
|
let cache = providerSchemas.get(db);
|
|
const cached = cache?.get(driverKey);
|
|
const manifestRevision = pluginManifestRevision();
|
|
const startedAt = Date.now();
|
|
const lookup = ++providerSchemaLookups;
|
|
if (cached && cached.manifestRevision === manifestRevision
|
|
&& startedAt >= cached.checkedAt && startedAt - cached.checkedAt < PROVIDER_SCHEMA_REUSE_MS) {
|
|
return structuredClone(cached.schema);
|
|
}
|
|
const unchanged = sql`coalesce(plugin_id = ${cached?.pluginId ?? null}::uuid
|
|
and revision = ${cached?.revision ?? null}, false)`;
|
|
const [row] = await db.execute<{
|
|
pluginId: string; revision: string; unchanged: boolean; configSchema: unknown;
|
|
}>(sql`with selected_provider as materialized (
|
|
select ${plugins.id} as plugin_id, (
|
|
select declaration.value->'configSchema'
|
|
from jsonb_array_elements(${plugins.manifestJson}->'environmentDrivers')
|
|
with ordinality as declaration(value, position)
|
|
where declaration.value->'driverKey' = to_jsonb(${driverKey}::text)
|
|
and declaration.value->>'kind' = 'sandbox_provider'
|
|
order by declaration.position limit 1
|
|
) as schema_value
|
|
from ${plugins}
|
|
where ${plugins.manifestJson} @> ${JSON.stringify({ environmentDrivers: [{ driverKey, kind: "sandbox_provider" }] })}::jsonb
|
|
order by ${plugins.installOrder} limit 1
|
|
), versioned_provider as materialized (
|
|
select plugin_id, schema_value,
|
|
encode(sha256(convert_to(coalesce(schema_value::text, 'null'), 'UTF8')), 'hex') as revision
|
|
from selected_provider
|
|
)
|
|
select plugin_id as "pluginId", revision, ${unchanged} as unchanged,
|
|
case when ${unchanged} then null else schema_value end as "configSchema"
|
|
from versioned_provider`);
|
|
if (!row) {
|
|
cache?.delete(driverKey);
|
|
return null;
|
|
}
|
|
if (row.unchanged) {
|
|
if (!cached || cached.pluginId !== row.pluginId || cached.revision !== row.revision) {
|
|
throw new Error("Sandbox provider schema revision did not match the retained definition");
|
|
}
|
|
if (cache!.get(driverKey) === cached) cache!.set(driverKey, { ...cached, checkedAt: startedAt, manifestRevision, lookup });
|
|
return structuredClone(cached.schema);
|
|
}
|
|
const schema = row.configSchema && typeof row.configSchema === "object" && !Array.isArray(row.configSchema)
|
|
? row.configSchema as Record<string, unknown> : null;
|
|
const current = cache?.get(driverKey);
|
|
if (current && current.lookup > lookup) return schema;
|
|
cache?.delete(driverKey);
|
|
if (Buffer.byteLength(JSON.stringify(schema)) <= MAX_CACHED_PROVIDER_SCHEMA_BYTES) {
|
|
if (!cache) { cache = new Map(); providerSchemas.set(db, cache); }
|
|
if (cache.size >= MAX_CACHED_PROVIDER_SCHEMAS) cache.delete(cache.keys().next().value!);
|
|
cache.set(driverKey, {
|
|
pluginId: row.pluginId, revision: row.revision, schema: structuredClone(schema), checkedAt: startedAt, manifestRevision, lookup,
|
|
});
|
|
}
|
|
return schema;
|
|
}
|
|
|
|
export async function resolvePluginSandboxProviderDriverByKey(input: {
|
|
db: Db;
|
|
driverKey: string;
|
|
workerManager?: PluginWorkerManager;
|
|
requireRunning?: boolean;
|
|
}): Promise<{ plugin: Awaited<ReturnType<ReturnType<typeof pluginRegistryService>["list"]>>[number]; driver: PluginEnvironmentDriverDeclaration } | null> {
|
|
const pluginRegistry = pluginRegistryService(input.db);
|
|
const plugins = await pluginRegistry.list({ sandboxProviderDriverKey: input.driverKey });
|
|
for (const plugin of plugins) {
|
|
const driver = plugin.manifestJson.environmentDrivers?.find(
|
|
(candidate) => candidate.driverKey === input.driverKey && candidate.kind === "sandbox_provider",
|
|
) as PluginEnvironmentDriverDeclaration | undefined;
|
|
if (!driver) continue;
|
|
if (input.requireRunning) {
|
|
if (plugin.status !== "ready") continue;
|
|
if (!input.workerManager?.isRunning(plugin.id)) continue;
|
|
}
|
|
return { plugin, driver };
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Resolve the sandbox-provider driver declaration from one exact plugin id.
|
|
*
|
|
* A driver key is only unique inside a single manifest. Two installed plugins
|
|
* can declare the same driver key. A lease pins the plugin that acquired it
|
|
* through `metadata.pluginId`. Use this resolver, not the by-key resolver, when
|
|
* the caller must read the declaration from that exact plugin. The by-key
|
|
* resolver returns the first installed plugin with the key, which can be a
|
|
* different, even disabled, plugin.
|
|
*
|
|
* This resolver fails closed. It returns `null` when the plugin id is unknown,
|
|
* or when that plugin no longer declares a `sandbox_provider` driver with the
|
|
* given key.
|
|
*/
|
|
export async function resolvePluginSandboxProviderDriverById(input: {
|
|
db: Db;
|
|
pluginId: string;
|
|
driverKey: string;
|
|
}): Promise<{ plugin: Awaited<ReturnType<ReturnType<typeof pluginRegistryService>["getById"]>>; driver: PluginEnvironmentDriverDeclaration } | null> {
|
|
const pluginRegistry = pluginRegistryService(input.db);
|
|
const plugin = await pluginRegistry.getById(input.pluginId);
|
|
if (!plugin) return null;
|
|
const driver = plugin.manifestJson.environmentDrivers?.find(
|
|
(candidate) => candidate.driverKey === input.driverKey && candidate.kind === "sandbox_provider",
|
|
) as PluginEnvironmentDriverDeclaration | undefined;
|
|
if (!driver) return null;
|
|
return { plugin, driver };
|
|
}
|
|
|
|
export async function listReadyPluginEnvironmentDrivers(input: {
|
|
kind?: "sandbox_provider" | "environment_driver";
|
|
db: Db;
|
|
workerManager?: PluginWorkerManager;
|
|
recoverMissingWorker?: ReadyPluginWorkerRecovery;
|
|
}) {
|
|
if (!input.workerManager) return [];
|
|
const pluginRegistry = pluginRegistryService(input.db);
|
|
const plugins = await pluginRegistry.list();
|
|
const recoverablePluginKeys = new Set(input.recoverMissingWorker?.pluginKeys ?? []);
|
|
const readyPlugins = plugins.filter((plugin) => plugin.status === "ready");
|
|
const recoveryAttempts: Promise<boolean>[] = [];
|
|
|
|
for (const plugin of readyPlugins) {
|
|
const hasSandboxProviderDriver = plugin.manifestJson.environmentDrivers?.some(
|
|
(driver) => driver.kind === "sandbox_provider",
|
|
) ?? false;
|
|
const canRecover =
|
|
hasSandboxProviderDriver
|
|
&& !input.workerManager.isRunning(plugin.id)
|
|
&& recoverablePluginKeys.has(plugin.pluginKey)
|
|
&& !input.workerManager.getWorker(plugin.id);
|
|
if (!canRecover || !input.recoverMissingWorker) continue;
|
|
const timeoutMs =
|
|
input.recoverMissingWorker.timeoutMs ?? DEFAULT_READY_PLUGIN_WORKER_RECOVERY_TIMEOUT_MS;
|
|
recoveryAttempts.push(resolveWithTimeout(
|
|
input.recoverMissingWorker.startWorker({
|
|
id: plugin.id,
|
|
pluginKey: plugin.pluginKey,
|
|
}).catch(() => false),
|
|
timeoutMs,
|
|
false,
|
|
));
|
|
}
|
|
|
|
if (recoveryAttempts.length > 0) {
|
|
await Promise.all(recoveryAttempts);
|
|
}
|
|
|
|
const rows: ReadyPluginEnvironmentDriver[] = [];
|
|
for (const plugin of readyPlugins) {
|
|
if (!input.workerManager.isRunning(plugin.id)) {
|
|
continue;
|
|
}
|
|
// The plugin is running, so read the live worker's verified methods once per
|
|
// plugin. A provider advertises reusable leases only when its worker carries
|
|
// all reuse lifecycle methods; the declaration alone never grants them.
|
|
const workerMethods = new Set(input.workerManager.getWorker(plugin.id)?.supportedMethods ?? []);
|
|
const reusableLeaseMethodsVerified = REUSABLE_LEASE_WORKER_METHODS.every(
|
|
(method) => workerMethods.has(method),
|
|
);
|
|
rows.push(
|
|
...(plugin.manifestJson.environmentDrivers ?? [])
|
|
.filter((driver) => driver.kind === (input.kind ?? "sandbox_provider"))
|
|
.map((driver) => ({
|
|
pluginId: plugin.id,
|
|
pluginKey: plugin.pluginKey,
|
|
driverKey: driver.driverKey,
|
|
displayName: driver.displayName,
|
|
description: driver.description,
|
|
configSchema: driver.configSchema,
|
|
supportsReusableLeases: driver.supportsReusableLeases,
|
|
sandboxCapabilities: driver.sandboxCapabilities,
|
|
reusableLeaseMethodsVerified,
|
|
supportsInteractiveSetup: driver.supportsInteractiveSetup,
|
|
interactiveSetupConnectionTypes: driver.interactiveSetupConnectionTypes,
|
|
supportsTemplateCapture: driver.supportsTemplateCapture,
|
|
templateRefKind: driver.templateRefKind,
|
|
templateConfigBinding: driver.templateConfigBinding,
|
|
supportsTemplateDelete: driver.supportsTemplateDelete,
|
|
supportsLoginPty: driver.kind === "environment_driver" ? pluginSupportsLoginPty(driver, [...workerMethods]) : driver.supportsLoginPty,
|
|
supportsCodexLogin: pluginSupportsLoginPty(driver, [...workerMethods], true),
|
|
})),
|
|
);
|
|
}
|
|
return rows;
|
|
}
|
|
|
|
export async function validatePluginSandboxProviderConfig(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
provider: string;
|
|
config: Record<string, unknown>;
|
|
}): Promise<{
|
|
normalizedConfig: Record<string, unknown>;
|
|
pluginId: string;
|
|
pluginKey: string;
|
|
driver: PluginEnvironmentDriverDeclaration;
|
|
}> {
|
|
const resolved = await resolvePluginSandboxProviderDriverByKey({
|
|
db: input.db,
|
|
driverKey: input.provider,
|
|
workerManager: input.workerManager,
|
|
requireRunning: true,
|
|
});
|
|
if (!resolved) {
|
|
throw unprocessable(`Sandbox provider "${input.provider}" is not installed or its plugin worker is not running.`);
|
|
}
|
|
|
|
// Secret pickers submit `{ type: "secret_ref", secretId, version }` binding
|
|
// objects for `format: "secret-ref"` fields. Plugins only understand string
|
|
// config values, so canonicalize bindings to the bare secret id (the
|
|
// persisted shape) before the plugin validates.
|
|
const configSchema =
|
|
resolved.driver.configSchema && typeof resolved.driver.configSchema === "object" && !Array.isArray(resolved.driver.configSchema)
|
|
? resolved.driver.configSchema as Record<string, unknown>
|
|
: null;
|
|
let config = input.config;
|
|
for (const path of collectSecretRefPaths(configSchema)) {
|
|
const binding = parseSecretRefBindingObject(readConfigValueAtPath(config, path));
|
|
if (!binding) continue;
|
|
if (binding.version !== "latest") {
|
|
throw unprocessable(
|
|
`Secret binding at ${path} pins version ${binding.version}; sandbox provider secret references always resolve the latest version.`,
|
|
);
|
|
}
|
|
config = writeConfigValueAtPath(config, path, binding.secretId);
|
|
}
|
|
|
|
const result = await input.workerManager.call(resolved.plugin.id, "environmentValidateConfig", {
|
|
driverKey: input.provider,
|
|
config,
|
|
});
|
|
|
|
if (!result.ok) {
|
|
throw unprocessable(
|
|
result.errors?.[0] ?? `Sandbox provider "${input.provider}" rejected its config.`,
|
|
{
|
|
errors: result.errors ?? [],
|
|
warnings: result.warnings ?? [],
|
|
},
|
|
);
|
|
}
|
|
|
|
return {
|
|
normalizedConfig: result.normalizedConfig ?? config,
|
|
pluginId: resolved.plugin.id,
|
|
pluginKey: resolved.plugin.pluginKey,
|
|
driver: resolved.driver,
|
|
};
|
|
}
|
|
|
|
export async function validatePluginEnvironmentDriverConfig(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
config: PluginEnvironmentConfig;
|
|
}): Promise<PluginEnvironmentConfig> {
|
|
const { plugin } = await resolvePluginEnvironmentDriver(input);
|
|
const result = await input.workerManager.call(plugin.id, "environmentValidateConfig", {
|
|
driverKey: input.config.driverKey,
|
|
config: input.config.driverConfig,
|
|
});
|
|
|
|
if (!result.ok) {
|
|
throw unprocessable(
|
|
result.errors?.[0] ?? `Plugin environment driver "${pluginDriverProviderKey(input.config)}" rejected its config.`,
|
|
{
|
|
errors: result.errors ?? [],
|
|
warnings: result.warnings ?? [],
|
|
},
|
|
);
|
|
}
|
|
|
|
return {
|
|
...input.config,
|
|
driverConfig: result.normalizedConfig ?? input.config.driverConfig,
|
|
};
|
|
}
|
|
|
|
export async function probePluginEnvironmentDriver(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
companyId: string;
|
|
environmentId: string;
|
|
config: PluginEnvironmentConfig;
|
|
}): Promise<EnvironmentProbeResult> {
|
|
const { plugin } = await resolvePluginEnvironmentDriver(input);
|
|
const result = await input.workerManager.call(plugin.id, "environmentProbe", {
|
|
driverKey: input.config.driverKey,
|
|
companyId: input.companyId,
|
|
environmentId: input.environmentId,
|
|
config: input.config.driverConfig,
|
|
}, 120_000);
|
|
|
|
return {
|
|
ok: result.ok,
|
|
driver: "plugin",
|
|
summary: result.summary ?? `Plugin environment driver "${pluginDriverProviderKey(input.config)}" probe ${result.ok ? "passed" : "failed"}.`,
|
|
details: {
|
|
pluginKey: input.config.pluginKey,
|
|
driverKey: input.config.driverKey,
|
|
diagnostics: result.diagnostics ?? [],
|
|
metadata: result.metadata ?? {},
|
|
},
|
|
};
|
|
}
|
|
|
|
export async function probePluginSandboxProviderDriver(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
companyId: string;
|
|
environmentId: string;
|
|
provider: string;
|
|
config: Record<string, unknown>;
|
|
}): Promise<EnvironmentProbeResult> {
|
|
const resolved = await resolvePluginEnvironmentDriverByKey({
|
|
db: input.db,
|
|
workerManager: input.workerManager,
|
|
driverKey: input.provider,
|
|
});
|
|
if (!resolved) {
|
|
return {
|
|
ok: false,
|
|
driver: "sandbox",
|
|
summary: `Sandbox provider "${input.provider}" is not installed or its plugin worker is not running.`,
|
|
details: {
|
|
provider: input.provider,
|
|
},
|
|
};
|
|
}
|
|
|
|
const { provider: _provider, ...driverConfig } = input.config;
|
|
const result = await input.workerManager.call(resolved.plugin.id, "environmentProbe", {
|
|
driverKey: input.provider,
|
|
companyId: input.companyId,
|
|
environmentId: input.environmentId,
|
|
config: driverConfig,
|
|
}, 120_000);
|
|
|
|
return {
|
|
ok: result.ok,
|
|
driver: "sandbox",
|
|
summary: result.summary ?? `Sandbox provider "${input.provider}" probe ${result.ok ? "passed" : "failed"}.`,
|
|
details: {
|
|
provider: input.provider,
|
|
pluginKey: resolved.plugin.pluginKey,
|
|
diagnostics: result.diagnostics ?? [],
|
|
metadata: result.metadata ?? {},
|
|
},
|
|
};
|
|
}
|
|
|
|
export async function resumePluginEnvironmentLease(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
companyId: string;
|
|
environmentId: string;
|
|
issueId?: string | null;
|
|
config: PluginEnvironmentConfig;
|
|
providerLeaseId: string;
|
|
leaseMetadata?: Record<string, unknown>;
|
|
requestedCwd?: string;
|
|
}): Promise<PluginEnvironmentLease> {
|
|
const { plugin } = await resolvePluginEnvironmentDriver(input);
|
|
return await input.workerManager.call(plugin.id, "environmentResumeLease", {
|
|
driverKey: input.config.driverKey,
|
|
companyId: input.companyId,
|
|
environmentId: input.environmentId,
|
|
issueId: input.issueId ?? null,
|
|
config: input.config.driverConfig,
|
|
providerLeaseId: input.providerLeaseId,
|
|
leaseMetadata: input.leaseMetadata,
|
|
...(input.requestedCwd !== undefined ? { requestedCwd: input.requestedCwd } : {}),
|
|
});
|
|
}
|
|
|
|
export async function destroyPluginEnvironmentLease(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
companyId: string;
|
|
environmentId: string;
|
|
issueId?: string | null;
|
|
config: PluginEnvironmentConfig;
|
|
providerLeaseId: string | null;
|
|
leaseMetadata?: Record<string, unknown>;
|
|
}): Promise<void> {
|
|
const { plugin } = await resolvePluginEnvironmentDriver(input);
|
|
await input.workerManager.call(plugin.id, "environmentDestroyLease", {
|
|
driverKey: input.config.driverKey,
|
|
companyId: input.companyId,
|
|
environmentId: input.environmentId,
|
|
issueId: input.issueId ?? null,
|
|
config: input.config.driverConfig,
|
|
providerLeaseId: input.providerLeaseId,
|
|
leaseMetadata: input.leaseMetadata,
|
|
});
|
|
}
|
|
|
|
export async function realizePluginEnvironmentWorkspace(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
pluginId?: string | null;
|
|
params: PluginEnvironmentRealizeWorkspaceParams;
|
|
config: PluginEnvironmentConfig;
|
|
}): Promise<PluginEnvironmentRealizeWorkspaceResult> {
|
|
const { plugin } = input.pluginId
|
|
? { plugin: { id: input.pluginId } }
|
|
: await resolvePluginEnvironmentDriver({
|
|
db: input.db,
|
|
workerManager: input.workerManager,
|
|
config: input.config,
|
|
});
|
|
return await input.workerManager.call(plugin.id, "environmentRealizeWorkspace", input.params);
|
|
}
|
|
|
|
export async function executePluginEnvironmentCommand(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
pluginId?: string | null;
|
|
params: PluginEnvironmentExecuteParams;
|
|
config: PluginEnvironmentConfig;
|
|
}): Promise<PluginEnvironmentExecuteResult> {
|
|
const { plugin } = input.pluginId
|
|
? { plugin: { id: input.pluginId } }
|
|
: await resolvePluginEnvironmentDriver({
|
|
db: input.db,
|
|
workerManager: input.workerManager,
|
|
config: input.config,
|
|
});
|
|
return await input.workerManager.call(
|
|
plugin.id,
|
|
"environmentExecute",
|
|
input.params,
|
|
resolvePluginExecuteRpcTimeoutMs({
|
|
requestedTimeoutMs: input.params.timeoutMs,
|
|
config: input.config.driverConfig,
|
|
}),
|
|
);
|
|
}
|
|
|
|
export async function startPluginEnvironmentInteractiveSetup(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
config: PluginEnvironmentConfig;
|
|
params: Omit<PluginEnvironmentStartInteractiveSetupParams, "driverKey" | "config">;
|
|
}): Promise<PluginEnvironmentInteractiveSetupSession> {
|
|
const { plugin } = await resolvePluginEnvironmentDriver({
|
|
db: input.db,
|
|
workerManager: input.workerManager,
|
|
config: input.config,
|
|
});
|
|
return await input.workerManager.call(plugin.id, "environmentStartInteractiveSetup", {
|
|
...input.params,
|
|
driverKey: input.config.driverKey,
|
|
config: input.config.driverConfig,
|
|
}, resolvePluginExecuteRpcTimeoutMs({
|
|
requestedTimeoutMs: undefined,
|
|
config: input.config.driverConfig,
|
|
}));
|
|
}
|
|
|
|
export async function getPluginEnvironmentInteractiveSetup(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
config: PluginEnvironmentConfig;
|
|
params: Omit<PluginEnvironmentGetInteractiveSetupParams, "driverKey" | "config">;
|
|
}): Promise<PluginEnvironmentInteractiveSetupSession> {
|
|
const { plugin } = await resolvePluginEnvironmentDriver({
|
|
db: input.db,
|
|
workerManager: input.workerManager,
|
|
config: input.config,
|
|
});
|
|
return await input.workerManager.call(plugin.id, "environmentGetInteractiveSetup", {
|
|
...input.params,
|
|
driverKey: input.config.driverKey,
|
|
config: input.config.driverConfig,
|
|
}, resolvePluginExecuteRpcTimeoutMs({
|
|
requestedTimeoutMs: undefined,
|
|
config: input.config.driverConfig,
|
|
}));
|
|
}
|
|
|
|
export async function capturePluginEnvironmentTemplate(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
config: PluginEnvironmentConfig;
|
|
params: Omit<PluginEnvironmentCaptureTemplateParams, "driverKey" | "config">;
|
|
}): Promise<PluginEnvironmentCaptureTemplateResult> {
|
|
const { plugin } = await resolvePluginEnvironmentDriver({
|
|
db: input.db,
|
|
workerManager: input.workerManager,
|
|
config: input.config,
|
|
});
|
|
return await input.workerManager.call(plugin.id, "environmentCaptureTemplate", {
|
|
...input.params,
|
|
driverKey: input.config.driverKey,
|
|
config: input.config.driverConfig,
|
|
}, resolvePluginExecuteRpcTimeoutMs({
|
|
requestedTimeoutMs: input.params.timeoutMs ?? undefined,
|
|
config: input.config.driverConfig,
|
|
}));
|
|
}
|
|
|
|
export async function cancelPluginEnvironmentInteractiveSetup(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
config: PluginEnvironmentConfig;
|
|
params: Omit<PluginEnvironmentCancelInteractiveSetupParams, "driverKey" | "config">;
|
|
}): Promise<PluginEnvironmentCancelInteractiveSetupResult> {
|
|
const { plugin } = await resolvePluginEnvironmentDriver({
|
|
db: input.db,
|
|
workerManager: input.workerManager,
|
|
config: input.config,
|
|
});
|
|
return await input.workerManager.call(plugin.id, "environmentCancelInteractiveSetup", {
|
|
...input.params,
|
|
driverKey: input.config.driverKey,
|
|
config: input.config.driverConfig,
|
|
}, resolvePluginExecuteRpcTimeoutMs({
|
|
requestedTimeoutMs: undefined,
|
|
config: input.config.driverConfig,
|
|
}));
|
|
}
|
|
|
|
export async function deletePluginEnvironmentTemplate(input: {
|
|
db: Db;
|
|
workerManager: PluginWorkerManager;
|
|
config: PluginEnvironmentConfig;
|
|
params: Omit<PluginEnvironmentDeleteTemplateParams, "driverKey" | "config">;
|
|
}): Promise<PluginEnvironmentDeleteTemplateResult> {
|
|
const { plugin } = await resolvePluginEnvironmentDriver({
|
|
db: input.db,
|
|
workerManager: input.workerManager,
|
|
config: input.config,
|
|
});
|
|
return await input.workerManager.call(plugin.id, "environmentDeleteTemplate", {
|
|
...input.params,
|
|
driverKey: input.config.driverKey,
|
|
config: input.config.driverConfig,
|
|
}, resolvePluginExecuteRpcTimeoutMs({
|
|
requestedTimeoutMs: undefined,
|
|
config: input.config.driverConfig,
|
|
}));
|
|
}
|
|
|
|
const RPC_OVERHEAD_BUFFER_MS = 30_000;
|
|
|
|
export function resolvePluginExecuteRpcTimeoutMs(input: {
|
|
requestedTimeoutMs?: number;
|
|
config: Record<string, unknown>;
|
|
}): number | undefined {
|
|
let baseMs: number | undefined;
|
|
if (Number.isFinite(input.requestedTimeoutMs) && (input.requestedTimeoutMs ?? 0) > 0) {
|
|
baseMs = Math.trunc(input.requestedTimeoutMs!);
|
|
} else {
|
|
const configTimeoutMs = typeof input.config.timeoutMs === "number" ? input.config.timeoutMs : null;
|
|
if (configTimeoutMs && Number.isFinite(configTimeoutMs) && configTimeoutMs > 0) {
|
|
baseMs = Math.trunc(configTimeoutMs);
|
|
}
|
|
}
|
|
return baseMs != null ? baseMs + RPC_OVERHEAD_BUFFER_MS : undefined;
|
|
}
|