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 > - #21335 lets a plugin task provider that restarts the Runner on `resume` opt in (`resumeCredentialVersion: 1`) to receive the claimant run's harness credential > - A provider restarting the Runner also needs the agent's configured environment, which Core sends on `resume` only during a session handoff > - Without it, a Runner a provider moves to a new computer starts without the agent's configured environment variables > - This pull request widens that opt-in to both launch inputs, under a name that says so, before any provider adopts the old name > - The benefit is that a provider can restart a parked Runner on resume with the same credential and environment a `submit` would carry ## Linked Issues or Issue Description Refs #21289 Follows: #21335 **What existing behavior does this improve?** The opt-in resume launch inputs added in #21335. **Subsystem affected** Plugin SDK environment task schema (`describe` capability), the plugin Runner task owner's `resume`, and the plugin environment task docs. **Current behavior** With `resumeCredentialVersion: 1`, `resume` carries `credential`. `configuredEnvironment` is sent on `resume` only for a session handoff. **Proposed behavior** The capability is renamed `resumeLaunchInputsVersion: 1`. With it, `resume` carries `credential` as before and also `configuredEnvironment` (same builder as `submit`) when the provider advertises `configuredEnvironmentVersion: 1`. Session handoff is unchanged. **Reason and benefit** A provider that restarts the Runner on resume gets both launch inputs it needs. **Breaking changes** The capability name changes from `resumeCredentialVersion` to `resumeLaunchInputsVersion`. No provider advertises the old name yet (it merged in #21335 and has no adopter), so nothing changes behavior. ## What Changed - Rename `resumeCredentialVersion` → `resumeLaunchInputsVersion` in the SDK `describe` result schema, executor plumbing, owner input, docs and tests. - With the capability, `resume` also adds `configuredEnvironment` when the provider advertises `configuredEnvironmentVersion: 1`. A normal resume does not mark the variables as delivered, since a live Runner keeps the environment it started with. - Docs: the "Release and resume" section describes both fields; the "Configured environment" section points to it. - The runner-e2e SDK public-input pin is updated. ## Verification - SDK vitest `tests/environment-task-release-resume.test.ts` and `tests/environment-tasks.test.ts`: 68 passed. - Server vitest `plugin-runner-task.test.ts` and `environment-task-runtime.test.ts`: 153 passed, including a normal resume with the capability (credential sent, variables added only with `configuredEnvironmentVersion: 1`, delivered flag unset) and redaction of both fields from metadata writes and sanitized errors. - `native-session-executor.test.ts -t "uses a task-only"`: 5 passed. - runner-e2e `source-sdk-evidence.test.ts` and `source-sdk-public-type.test.ts`: 46 passed. - `pnpm typecheck` in `server/` (builds shared and plugin-sdk) passed. - Not run locally: the full suite and `pnpm verify`; required CI covers them. ## Risks - A provider restarting the Runner gets the claimant run's current variables, which can differ from the ones the parked Runner started with. That is intended. - Rollback: revert this pull request. No migration. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, test runs), implemented by a sub-agent and reviewed before opening. ## 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
280 lines
17 KiB
TypeScript
280 lines
17 KiB
TypeScript
import { z } from "zod";
|
|
import type { PluginEnvironmentDriverBaseParams, PluginEnvironmentLease } from "./protocol.js";
|
|
import type { PluginAgentRuntimeIdentity } from "./types.js";
|
|
|
|
export const MAX_ENVIRONMENT_TASK_FILE_BYTES = 10 * 1024 * 1024;
|
|
const taskFilePath = z.string().min(1).max(2000).refine(value =>
|
|
!/[\\\u0000-\u001f\u007f]/u.test(value) && !/^[a-z][a-z0-9+.-]*:/iu.test(value) &&
|
|
value.replace(/^\//u, "").split("/").every(part => part !== "" && part !== "." && part !== ".."), "Expected a canonical task file path");
|
|
// Provider IDs are opaque; providers validate their own addressing constraints.
|
|
const providerId = z.string().min(1);
|
|
// PRP identity.schema.json stableId.
|
|
const runnerIdentity = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/);
|
|
const durableIdentity = z.object({ runnerInstanceId: runnerIdentity, environmentLeaseId: runnerIdentity,
|
|
runId: runnerIdentity, normalizedSessionId: runnerIdentity, turnId: runnerIdentity, itemId: runnerIdentity }).strict();
|
|
const identifier = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$/);
|
|
const secureUrl = z.string().url().refine(value => {
|
|
const url = new URL(value);
|
|
return url.protocol === "wss:" && !url.username && !url.password && !url.search && !url.hash;
|
|
}, "Expected a credential-free WSS URL");
|
|
|
|
const credentialValue = z.string().min(1).max(65_536).refine(value => !value.includes("\0"));
|
|
const githubBroker = z.object({ url: z.string().url().max(2000).refine(value => {
|
|
try {
|
|
const url = new URL(value);
|
|
return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password && !url.search && !url.hash;
|
|
} catch { return false; }
|
|
}, "Expected a credential-free HTTP broker URL"), token: credentialValue }).strict();
|
|
const claudeCredentialEnvironment = z.object({
|
|
CLAUDE_CODE_OAUTH_TOKEN: credentialValue.optional(), ANTHROPIC_API_KEY: credentialValue.optional(),
|
|
}).strict().refine(env => Object.values(env).filter(Boolean).length === 1, "Select one Claude credential");
|
|
export const MAX_CONFIGURED_ENVIRONMENT_KEYS = 128;
|
|
export const MAX_CONFIGURED_ENVIRONMENT_ENTRY_BYTES = 65_536;
|
|
export const MAX_CONFIGURED_ENVIRONMENT_BYTES = 262_144;
|
|
const utf8 = new TextEncoder();
|
|
const utf8Bytes = (value: string) => utf8.encode(value).byteLength;
|
|
export const environmentTaskConfiguredEnvironmentSchema = z.record(
|
|
z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/),
|
|
z.string().refine(value => !value.includes("\0"), "Expected a NUL-free value"),
|
|
).superRefine((environment, ctx) => {
|
|
const entries = Object.entries(environment);
|
|
if (entries.length > MAX_CONFIGURED_ENVIRONMENT_KEYS) {
|
|
ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Too many configured environment variables" });
|
|
return;
|
|
}
|
|
let total = 0;
|
|
for (const [name, value] of entries) {
|
|
const size = utf8Bytes(name) + utf8Bytes(value);
|
|
total += size;
|
|
if (size > MAX_CONFIGURED_ENVIRONMENT_ENTRY_BYTES) {
|
|
ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Configured environment variable is too large", path: [name] });
|
|
}
|
|
}
|
|
if (total > MAX_CONFIGURED_ENVIRONMENT_BYTES) {
|
|
ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Configured environment is too large" });
|
|
}
|
|
});
|
|
export type PluginEnvironmentTaskConfiguredEnvironment = z.infer<typeof environmentTaskConfiguredEnvironmentSchema>;
|
|
|
|
/** Only provider authentication is transferred. Paths and executable settings remain provider-owned. */
|
|
export const environmentTaskCredentialSchema = z.discriminatedUnion("type", [
|
|
z.object({ type: z.literal("codex-auth-json"), authJson: credentialValue }).strict(),
|
|
z.object({ type: z.literal("claude-env"), environment: claudeCredentialEnvironment }).strict(),
|
|
]);
|
|
export type PluginEnvironmentTaskCredential = z.infer<typeof environmentTaskCredentialSchema>;
|
|
|
|
/** Runner owns this versioned data contract. The plugin resolves its execution-host locations. */
|
|
export const environmentRunnerLaunchRequirementsSchema = z.object({
|
|
schema: z.literal("paperclip.runner.launch-requirements.v1"),
|
|
identity: durableIdentity,
|
|
provider: z.enum(["codex", "opencode", "acpx", "claude_managed", "aws_agentcore"]),
|
|
model: z.string().min(1).nullable(), instructions: z.string().max(1024 * 1024),
|
|
runtimeContext: z.record(z.string(), z.unknown()).nullable(),
|
|
settings: z.object({ acpxAgent: identifier.optional(), acpxMode: z.string().optional(),
|
|
acpxPermissionMode: z.enum(["approve-all", "approve-paperclip", "approve-reads", "deny-all"]).optional(),
|
|
acpxPermissionModePinned: z.boolean().optional(), piThinkingLevel: z.enum(["off", "low", "high", "max"]).optional(),
|
|
claudeEffort: z.enum(["low", "medium", "high", "xhigh", "max"]).optional(),
|
|
opencodePermissionMode: z.enum(["allow", "ask", "deny"]).optional(),
|
|
disableCodexWebSearch: z.literal(true).optional(),
|
|
disableCodexProjectInstructions: z.literal(true).optional(),
|
|
managedProfile: z.record(z.string(), z.unknown()).optional(), agentCoreProfile: z.record(z.string(), z.unknown()).optional(),
|
|
}).strict(),
|
|
approvalPolicy: z.enum(["never", "on-request", "untrusted"]), readOnly: z.boolean(),
|
|
preparedConversation: z.boolean(), includeCollaborationModeInstructions: z.boolean(),
|
|
}).strict();
|
|
const preparedLaunch = z.object({ configurationId: providerId.max(1024),
|
|
requirementsDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/),
|
|
provider: z.record(z.string(), z.unknown()),
|
|
}).strict();
|
|
|
|
/** One plugin-provided Runner execution attempt with a PRP connection. Secrets are transient RPC input. */
|
|
export const environmentTaskOperationSchema = z.discriminatedUnion("kind", [
|
|
z.object({ kind: z.literal("describe") }).strict(),
|
|
z.object({ kind: z.literal("copilot_metadata"), token: credentialValue, model: z.string().min(1).max(1024).optional() }).strict(),
|
|
z.object({ kind: z.literal("prepare"), requirements: environmentRunnerLaunchRequirementsSchema,
|
|
githubBroker: githubBroker.optional(),
|
|
recovery: preparedLaunch.optional(), resumeFrom: providerId.optional(),
|
|
priorIdentity: durableIdentity.optional(), accountIdentity: z.string().min(1).max(1024).optional(),
|
|
projectIds: z.array(z.string().uuid()).max(64).refine(ids => new Set(ids).size === ids.length, "Duplicate project IDs"),
|
|
}).strict(),
|
|
z.object({
|
|
kind: z.literal("submit"),
|
|
projectIds: z.array(z.string().uuid()).max(64).refine(ids => new Set(ids).size === ids.length, "Duplicate project IDs"),
|
|
runner: z.object({
|
|
/** Inclusive PRP version range supported by the submitting client. */
|
|
protocolMin: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
|
|
protocolMax: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
|
|
harness: identifier,
|
|
runnerId: runnerIdentity, leaseId: runnerIdentity, runId: runnerIdentity,
|
|
sessionId: runnerIdentity, turnId: runnerIdentity, itemId: runnerIdentity,
|
|
}).strict().refine(value => value.protocolMin <= value.protocolMax, "Invalid PRP version range"),
|
|
bootstrapTicket: z.string().min(1).max(65_536),
|
|
/** Opaque prior provider task; Core authorizes the saved session before supplying it. */
|
|
resumeFrom: z.string().min(1).optional(),
|
|
preparedLaunchId: providerId.max(1024).optional(),
|
|
/** Require the externally installed account to match this Core-selected credential revision. */
|
|
credentialIdentity: z.string().min(1).max(1024).optional(),
|
|
/** Stable account selection; distinct from its current credential revision. */
|
|
accountIdentity: z.string().min(1).max(1024).optional(),
|
|
credential: environmentTaskCredentialSchema.optional(),
|
|
configuredEnvironment: environmentTaskConfiguredEnvironmentSchema.optional(),
|
|
/** Core supplies these protected launch inputs for native agent runs. */
|
|
launch: z.object({
|
|
runnerVersion: z.string().min(1), runnerDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/),
|
|
maxOutboxBytes: z.number().int().positive(), p0ReserveBytes: z.number().int().positive(),
|
|
maxRuntimeMs: z.number().int().nonnegative().optional(), maxLifetimeMs: z.number().int().nonnegative().optional(),
|
|
reconnectGraceMs: z.number().int().nonnegative().optional(),
|
|
lifecyclePolicy: z.discriminatedUnion("mode", [
|
|
z.object({ mode: z.literal("per_turn"), idleTimeoutMs: z.null() }).strict(),
|
|
z.object({ mode: z.literal("warm"), idleTimeoutMs: z.number().int().positive().max(86_400_000) }).strict(),
|
|
]),
|
|
}).strict().optional(),
|
|
}).strict(),
|
|
z.object({ kind: z.literal("check_project_auth"), configurationId: providerId.max(1024),
|
|
provider: identifier, projectIds: z.array(z.string().uuid()).max(64)
|
|
.refine(ids => new Set(ids).size === ids.length, "Duplicate project IDs") }).strict(),
|
|
z.object({ kind: z.literal("read_file"), identity: durableIdentity,
|
|
path: taskFilePath, maxBytes: z.number().int().positive().max(MAX_ENVIRONMENT_TASK_FILE_BYTES),
|
|
projectIds: z.array(z.string().uuid()).max(64).refine(ids => new Set(ids).size === ids.length, "Duplicate project IDs"),
|
|
}).strict(),
|
|
z.object({ kind: z.literal("read_state"), identity: durableIdentity, resumeFrom: providerId.optional() }).strict(),
|
|
z.object({ kind: z.literal("archive_state"), priorIdentity: durableIdentity,
|
|
archiveKey: z.string().regex(/^[a-f0-9]{24}$/), resumeFrom: providerId }).strict(),
|
|
z.object({ kind: z.literal("credentials"), accountIdentity: z.string().min(1).max(1024) }).strict(),
|
|
z.object({ kind: z.literal("status") }).strict(),
|
|
z.object({ kind: z.literal("connection") }).strict(),
|
|
z.object({ kind: z.literal("release"), identity: durableIdentity }).strict(),
|
|
z.object({ kind: z.literal("resume"), identity: durableIdentity, bootstrapTicket: credentialValue,
|
|
handoffCredential: z.object({ accountIdentity: z.string().min(1).max(1024), environment: claudeCredentialEnvironment }).strict().optional(),
|
|
credential: environmentTaskCredentialSchema.optional(),
|
|
configuredEnvironment: environmentTaskConfiguredEnvironmentSchema.optional(),
|
|
}).strict(),
|
|
z.object({
|
|
kind: z.literal("ensure_ownership"),
|
|
operationId: z.string().uuid(),
|
|
identity: durableIdentity,
|
|
sourceTaskId: providerId.max(1024),
|
|
sourceGeneration: providerId.max(1024),
|
|
targetGeneration: providerId.max(1024),
|
|
policy: z.enum(["ordinary", "reclaim_if_needed"]),
|
|
}).strict(),
|
|
z.object({ kind: z.literal("complete") }).strict(),
|
|
z.object({ kind: z.literal("stop") }).strict(),
|
|
]);
|
|
|
|
export const environmentTaskResultSchema = z.discriminatedUnion("kind", [
|
|
z.object({ kind: z.literal("accepted"), taskId: providerId }).strict(),
|
|
z.object({ kind: z.literal("admission_rejected"), taskId: providerId,
|
|
reason: z.enum(["session_state_unavailable", "account_binding_mismatch"]) }).strict(),
|
|
z.object({ kind: z.literal("released"), taskId: providerId }).strict(),
|
|
z.object({ kind: z.literal("resume"), taskId: providerId, outcome: z.enum(["resumed", "unavailable"]) }).strict(),
|
|
z.object({
|
|
kind: z.literal("ownership"),
|
|
taskId: providerId,
|
|
operationId: z.string().uuid(),
|
|
targetGeneration: providerId.max(1024),
|
|
status: z.enum(["pending", "ready"]),
|
|
checkpointUnavailable: z.literal(true).optional(),
|
|
}).strict(),
|
|
z.object({ kind: z.literal("copilot_metadata"), taskId: providerId, metadata: z.record(z.string(), z.unknown()),
|
|
executionStopped: z.literal(true) }).strict(),
|
|
z.object({ kind: z.literal("project_auth"), taskId: providerId, configurationId: providerId.max(1024),
|
|
provider: identifier, allowed: z.boolean() }).strict(),
|
|
z.object({ kind: z.literal("file"), taskId: providerId,
|
|
base64: z.string().max(4 * Math.ceil(MAX_ENVIRONMENT_TASK_FILE_BYTES / 3)),
|
|
byteSize: z.number().int().nonnegative().max(MAX_ENVIRONMENT_TASK_FILE_BYTES),
|
|
sha256: z.string().regex(/^[a-f0-9]{64}$/),
|
|
}).strict(),
|
|
z.object({ kind: z.literal("state"), taskId: providerId, state: z.record(z.string(), z.unknown()) }).strict(),
|
|
z.object({ kind: z.literal("prepared"), taskId: providerId, launch: preparedLaunch, projectAuthCheckAtSubmit: z.literal(true).optional() }).strict(),
|
|
z.object({ kind: z.literal("credentials"), taskId: providerId, /** Null proves that cancellation fenced admission before the task could start. It must not mean an unavailable export. */
|
|
credential: environmentTaskCredentialSchema.nullable() }).strict(),
|
|
z.object({ kind: z.literal("description"), taskId: providerId,
|
|
runner: z.object({ version: z.string().min(1), digest: z.string().regex(/^sha256:[a-f0-9]{64}$/) }).strict(),
|
|
warmTaskVersion: z.literal(1).optional(),
|
|
releaseResumeVersion: z.literal(1).optional(),
|
|
sessionHandoffVersion: z.literal(1).optional(),
|
|
launchPreparationVersion: z.literal(1).optional(),
|
|
executionContextVersion: z.literal(1).optional(),
|
|
/** Each version attests stopped-source recovery for its provider independently. */
|
|
codexSourceRecoveryVersion: z.literal(1).optional(),
|
|
acpxSourceRecoveryVersion: z.literal(1).optional(),
|
|
freshWorkspaceVersion: z.literal(1).optional(),
|
|
projectAuthCheckVersion: z.literal(1).optional(),
|
|
workspaceFileReadVersion: z.literal(1).optional(),
|
|
githubCredentialBrokerVersion: z.literal(1).optional(),
|
|
configuredEnvironmentVersion: z.literal(1).optional(),
|
|
resumeLaunchInputsVersion: z.literal(1).optional(),
|
|
}).strict(),
|
|
z.object({
|
|
kind: z.literal("status"), taskId: providerId,
|
|
phase: z.enum(["preparing", "running", "completed", "failed", "cancelled", "interrupted"]),
|
|
exitCode: z.number().int().optional(),
|
|
/** Provider observed the task and all descendants stopped; terminal phase alone is insufficient. */
|
|
executionStopped: z.boolean().optional(),
|
|
preparationStopped: z.boolean().optional(),
|
|
/** The provider retains this task's recoverable session state for a later launch. */
|
|
sessionStateAvailable: z.boolean().optional(),
|
|
}).strict(),
|
|
z.object({
|
|
kind: z.literal("connection"), taskId: providerId,
|
|
endpoint: z.object({
|
|
kind: z.literal("authenticated_websocket"), websocketUrl: secureUrl,
|
|
generation: providerId,
|
|
secretHeaders: z.array(z.object({
|
|
name: z.string().regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/),
|
|
value: z.string().min(1).max(65_536).regex(/^[^\r\n]+$/),
|
|
}).strict()).max(16),
|
|
}).strict(),
|
|
}).strict(),
|
|
]);
|
|
|
|
export type PluginEnvironmentRunnerLaunchRequirements = z.infer<typeof environmentRunnerLaunchRequirementsSchema>;
|
|
export type PluginEnvironmentPreparedLaunch = z.infer<typeof preparedLaunch>;
|
|
|
|
export type PluginEnvironmentTaskOperation = z.infer<typeof environmentTaskOperationSchema>;
|
|
export type PluginEnvironmentTaskResult = z.infer<typeof environmentTaskResultSchema>;
|
|
|
|
export interface PluginEnvironmentTaskExecutionContext {
|
|
id: string;
|
|
deadlineAtMs: number;
|
|
transport: {
|
|
instanceSecrets: PluginAgentRuntimeIdentity["instanceSecrets"];
|
|
configuration: Record<string, unknown>;
|
|
};
|
|
}
|
|
|
|
export interface PluginEnvironmentTaskParams extends Omit<PluginEnvironmentDriverBaseParams, "environmentId"> {
|
|
/** Null during cleanup after the environment is deleted. */
|
|
environmentId: string | null;
|
|
lease: PluginEnvironmentLease;
|
|
/** Provider-issued task identifier persisted in the lease, stable across ambiguous submission retries. */
|
|
taskId: string;
|
|
/** Null during cleanup after the associated run is deleted. */
|
|
runId: string | null;
|
|
agentId: string | null;
|
|
/** Company-validated projects to prepare on submit; empty during cleanup. */
|
|
projectIds: string[];
|
|
workspace?: import("@paperclipai/shared").WorkspaceProviderBinding;
|
|
fresh?: import("./workspace-provider.js").PluginFreshWorkspace;
|
|
operation: PluginEnvironmentTaskOperation;
|
|
executionContextSupported?: 1;
|
|
executionContext?: PluginEnvironmentTaskExecutionContext;
|
|
}
|
|
|
|
/** An accepted stop is not proof of process termination. */
|
|
export function parseEnvironmentTaskResult(operation: PluginEnvironmentTaskOperation, taskId: string, value: unknown): PluginEnvironmentTaskResult {
|
|
const result = environmentTaskResultSchema.parse(value);
|
|
if (operation.kind === "ensure_ownership") {
|
|
if (result.kind !== "ownership" || result.taskId !== taskId || result.operationId !== operation.operationId ||
|
|
result.targetGeneration !== operation.targetGeneration) {
|
|
throw new Error("Invalid plugin-provided session ownership response");
|
|
}
|
|
return result;
|
|
}
|
|
const expected = operation.kind === "release" ? "released" : operation.kind === "resume" ? "resume" : operation.kind === "read_file" ? "file" : operation.kind === "describe" ? "description" : operation.kind === "prepare" ? "prepared" : operation.kind === "check_project_auth" ? "project_auth" : ["read_state", "archive_state"].includes(operation.kind) ? "state" : ["status", "connection", "credentials", "copilot_metadata"].includes(operation.kind) ? operation.kind : "accepted";
|
|
const rejectedSubmit = operation.kind === "submit" && result.kind === "admission_rejected";
|
|
if (result.taskId !== taskId || (result.kind !== expected && !rejectedSubmit)) throw new Error("Invalid plugin-provided Runner execution response");
|
|
return result;
|
|
}
|