Files
PaperClipAI/packages/plugins/sdk/src/environment-tasks.ts
T
Nicky LeachandClaude Opus 5.5 5df1ada9c1 feat(plugins): send configured environment on plugin task resume (#21352)
## 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>
2026-11-13 13:46:37 -08:00

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;
}