mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-18 14:35:55 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - A plugin can be a project workspace provider and also an environment
driver for the agent runs that use those workspaces
> - Core asks the workspace provider to prepare the project workspace
before the run acquires its environment lease
> - The provider knows the run, agent, project, and execution workspace,
but not the environment that the run selected
> - A provider whose compute exists per run (for example, a sandbox that
it creates from the environment's driver config) cannot start or find
the run's compute for the workspace work
> - This pull request lets a provider opt in to receive the run's
selected environment, when that environment is one of the provider's own
drivers
> - The benefit is that such a provider can prepare the workspace on the
run's own compute, with no change to the order of operations in Core
## Linked Issues or Issue Description
**What existing behavior does this improve?**
Plugin workspace preparation for runs whose environment is a driver of
the same plugin.
**Subsystem affected**
Plugin SDK workspace provider params, the plugin manifest workspace
provider declaration, and `callWorkspaceProvider` /
`preparePluginWorkspace` in the server.
**Current behavior**
`prepare` params carry `runId`, `agentId`, `projectId`, and
`executionWorkspaceId`. They carry `taskLease` only when Core acquired
the lease first. They never name the run's environment.
**Proposed behavior**
A provider that declares `workspaceProvider.workspaceEnvironmentVersion:
1` receives `environment: { id, driverKey, config }` when the run's
selected environment is a plugin environment of that same provider.
`config` is the environment's `driverConfig`, the value that the
driver's acquire receives.
## What Changed
- SDK: optional strict `environment` field on
`pluginWorkspaceParamsSchema`.
- Manifest: optional `workspaceProvider.workspaceEnvironmentVersion: 1`,
next to the sibling version fields. Core sends the new field only to
providers that declare it, because providers parse the params with the
strict schema.
- Server: `callWorkspaceProvider` adds `environment` only when the
provider opted in, the environment driver is `plugin`, its `pluginKey`
is this provider, and it names a `driverKey`. The field is not part of
the operation ID.
- Server: `preparePluginWorkspace` passes the run's environment to its
prepare call. This covers normal, verify-existing, fresh, and
replacement prepares.
- Calls that do not have the run's environment do not send it: finalize,
inspect, remove, reservation reconciliation, and the retry-candidate
verification in `fresh-workspace-continuation.ts`.
- Lease acquisition, the `sessionHandoffVersion` gate, and the order of
operations do not change.
- Docs: `doc/plugins/PLUGIN_RUNNER_EXECUTION.md` describes the
capability and its exceptions.
## Verification
- `packages/plugins/sdk/tests/workspace-provider.test.ts`: 11 passed.
The schema accepts the field and rejects malformed values.
- `packages/shared/src/validators/plugin.test.ts`: 65 passed. The
manifest accepts only version 1.
- `server`: `plugin-workspaces.integration`,
`plugin-fresh-workspaces.integration`, `project-environments`, and
`heartbeat/workspace-preparation`: 226 passed, against embedded
Postgres. The new integration test checks the exact shape, an unchanged
operation ID, verification prepares, and omission for an undeclared
provider, another plugin's environment, non-plugin drivers, a missing
`driverKey`, and no environment. It fails when the server stops passing
the environment.
- `pnpm typecheck` passes in `packages/shared`, `packages/plugins/sdk`,
and `server`.
- The full suite was not run locally. CI runs it.
## Risks
- Low risk. Providers that do not declare the capability get the same
params as before.
- `config` is the stored `driverConfig`, in the same form that the
driver's acquire gets. Secret references in it reach the provider in
that same form.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, code search, test execution).
## 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)
- [ ] 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
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
572 lines
26 KiB
TypeScript
572 lines
26 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import { PLUGIN_CAPABILITIES } from "../constants.js";
|
|
import { resolveDeclaredSandboxCapabilities } from "../environment-support.js";
|
|
import { pluginApiRouteDeclarationSchema, pluginManagedRoutineDeclarationSchema, pluginManifestV1Schema, pluginUiSlotDeclarationSchema } from "./plugin.js";
|
|
|
|
function buildSandboxProviderManifest(driver: Record<string, unknown>) {
|
|
return {
|
|
id: "paperclip.capability-provider",
|
|
apiVersion: 1,
|
|
version: "0.1.0",
|
|
displayName: "Capability Provider",
|
|
description: "Sandbox provider that declares fine-grained capabilities.",
|
|
author: "Paperclip",
|
|
categories: ["automation"],
|
|
capabilities: ["environment.drivers.register"],
|
|
entrypoints: { worker: "./dist/worker.js" },
|
|
environmentDrivers: [
|
|
{
|
|
driverKey: "capability-provider",
|
|
kind: "sandbox_provider",
|
|
displayName: "Capability Provider",
|
|
configSchema: { type: "object" },
|
|
...driver,
|
|
},
|
|
],
|
|
};
|
|
}
|
|
|
|
describe("plugin capability constants", () => {
|
|
it("exposes each capability once", () => {
|
|
expect(new Set(PLUGIN_CAPABILITIES).size).toBe(PLUGIN_CAPABILITIES.length);
|
|
});
|
|
});
|
|
|
|
describe("plugin manifest validators", () => {
|
|
it("preserves explicit workspace ancestry support without changing legacy declarations", () => {
|
|
const manifest = { id: "example.storage", apiVersion: 1, version: "1.0.0", displayName: "Storage", description: "Storage", author: "Tests",
|
|
categories: ["workspace"], capabilities: ["workspaces.manage", "events.subscribe"], resourceLifecycle: ["project"],
|
|
entrypoints: { worker: "worker.js" }, workspaceProvider: { modes: ["isolated_workspace"], strategies: ["git_worktree"] } };
|
|
expect(pluginManifestV1Schema.parse(manifest).workspaceProvider?.supportsMergeAncestry).toBeUndefined();
|
|
for (const supportsMergeAncestry of [true, false]) {
|
|
expect(pluginManifestV1Schema.parse({ ...manifest, workspaceProvider: { ...manifest.workspaceProvider, supportsMergeAncestry } })
|
|
.workspaceProvider?.supportsMergeAncestry).toBe(supportsMergeAncestry);
|
|
}
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, workspaceProvider: { ...manifest.workspaceProvider, supportsMergeAncestry: "false" } }).success).toBe(false);
|
|
});
|
|
it("accepts only version 1 of the workspace environment capability", () => {
|
|
const manifest = { id: "example.storage", apiVersion: 1, version: "1.0.0", displayName: "Storage", description: "Storage", author: "Tests",
|
|
categories: ["workspace"], capabilities: ["workspaces.manage", "events.subscribe"], resourceLifecycle: ["project"],
|
|
entrypoints: { worker: "worker.js" }, workspaceProvider: { modes: ["isolated_workspace"], strategies: ["git_worktree"] } };
|
|
expect(pluginManifestV1Schema.parse(manifest).workspaceProvider?.workspaceEnvironmentVersion).toBeUndefined();
|
|
expect(pluginManifestV1Schema.parse({ ...manifest, workspaceProvider: { ...manifest.workspaceProvider, workspaceEnvironmentVersion: 1 } })
|
|
.workspaceProvider?.workspaceEnvironmentVersion).toBe(1);
|
|
for (const workspaceEnvironmentVersion of [2, "1", true])
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, workspaceProvider: { ...manifest.workspaceProvider, workspaceEnvironmentVersion } }).success).toBe(false);
|
|
});
|
|
it("limits environment skills to unique declarations owned by the plugin", () => {
|
|
const manifest = { ...buildSandboxProviderManifest({ skillKeys: ["desktop"] }),
|
|
capabilities: ["environment.drivers.register", "skills.managed"],
|
|
skills: [{ skillKey: "desktop", displayName: "Desktop" }] };
|
|
expect(pluginManifestV1Schema.parse(manifest).environmentDrivers![0].skillKeys).toEqual(["desktop"]);
|
|
for (const keys of [["missing"], ["desktop", "desktop"]]) {
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest,
|
|
environmentDrivers: [{ ...manifest.environmentDrivers[0], skillKeys: keys }] }).success).toBe(false);
|
|
}
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, capabilities: ["environment.drivers.register"] }).success).toBe(false);
|
|
});
|
|
it("accepts protected environment keys only as variable names", () => {
|
|
expect(pluginManifestV1Schema.parse(buildSandboxProviderManifest({ protectedEnvironmentKeys: ["DESKTOP_SESSION"] }))
|
|
.environmentDrivers?.[0]?.protectedEnvironmentKeys).toEqual(["DESKTOP_SESSION"]);
|
|
for (const keys of [["BAD-NAME"], ["1BAD"], "DESKTOP_SESSION", Array.from({ length: 65 }, (_, index) => `K${index}`)]) {
|
|
expect(pluginManifestV1Schema.safeParse(buildSandboxProviderManifest({ protectedEnvironmentKeys: keys })).success).toBe(false);
|
|
}
|
|
});
|
|
it("retains the agent prerequisite on environment drivers", () => {
|
|
const manifest = { ...buildSandboxProviderManifest({ requiresAgent: true }), agentLifecycle: true,
|
|
capabilities: ["environment.drivers.register", "agents.lifecycle.manage"] };
|
|
expect(pluginManifestV1Schema.parse(manifest).environmentDrivers?.[0]?.requiresAgent).toBe(true);
|
|
expect(pluginManifestV1Schema.safeParse(buildSandboxProviderManifest({ requiresAgent: "true" })).success).toBe(false);
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, agentLifecycle: undefined }).success).toBe(false);
|
|
});
|
|
it("requires authority for required agent lifecycle participants", () => {
|
|
const manifest = { id: "example.lifecycle", apiVersion: 1, version: "0.1.0", displayName: "Lifecycle", description: "Lifecycle tests", author: "Tests", categories: ["automation"], entrypoints: { worker: "worker.js" }, agentLifecycle: true };
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, capabilities: ["agents.read"] }).success).toBe(false);
|
|
expect(pluginManifestV1Schema.parse({ ...manifest, capabilities: ["agents.lifecycle.manage"] }).agentLifecycle).toBe(true);
|
|
});
|
|
|
|
it("requires subscription authority and known resource types for durable delivery", () => {
|
|
const manifest = { id: "example.lifecycle", apiVersion: 1, version: "1.0.0", displayName: "Lifecycle", description: "Lifecycle tests", author: "Tests", categories: ["automation"], entrypoints: { worker: "worker.js" }, resourceLifecycle: ["project"] };
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, capabilities: ["projects.read"] }).success).toBe(false);
|
|
expect(pluginManifestV1Schema.parse({ ...manifest, capabilities: ["events.subscribe"] }).resourceLifecycle).toEqual(["project"]);
|
|
for (const resourceLifecycle of [[], ["issue"]]) {
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, resourceLifecycle, capabilities: ["events.subscribe"] }).success).toBe(false);
|
|
}
|
|
});
|
|
|
|
it("requires routing authority for native pooled connector declarations without a custom UI bundle", () => {
|
|
const manifest = { id: "example.pool", apiVersion: 1, version: "0.1.0", displayName: "Pool", description: "Pool", author: "Tests", categories: ["connector"], entrypoints: { worker: "worker.js" }, aiConnectionRouter: { name: "AI connection pool", description: "Use saved connections" } };
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, capabilities: ["ui.page.register"] }).success).toBe(false);
|
|
expect(pluginManifestV1Schema.parse({ ...manifest, capabilities: ["ai.connections.route"] }).aiConnectionRouter).toEqual(manifest.aiConnectionRouter);
|
|
});
|
|
it("accepts existing-style plugins that do not request access or authorization capabilities", () => {
|
|
const parsed = pluginManifestV1Schema.parse({
|
|
id: "paperclip.compat-dashboard",
|
|
apiVersion: 1,
|
|
version: "0.1.0",
|
|
displayName: "Compat Dashboard",
|
|
description: "Dashboard-only plugin without access or authorization host APIs.",
|
|
author: "Paperclip",
|
|
categories: ["ui"],
|
|
capabilities: ["ui.dashboardWidget.register"],
|
|
entrypoints: {
|
|
worker: "./dist/worker.js",
|
|
ui: "./dist/ui.js",
|
|
},
|
|
ui: {
|
|
slots: [
|
|
{
|
|
type: "dashboardWidget",
|
|
id: "compat-dashboard",
|
|
displayName: "Compat Dashboard",
|
|
exportName: "CompatDashboard",
|
|
},
|
|
],
|
|
},
|
|
});
|
|
|
|
expect(parsed.capabilities).toEqual(["ui.dashboardWidget.register"]);
|
|
});
|
|
|
|
it("accepts sandbox provider template config bindings", () => {
|
|
const parsed = pluginManifestV1Schema.parse({
|
|
id: "paperclip.template-provider",
|
|
apiVersion: 1,
|
|
version: "0.1.0",
|
|
displayName: "Template Provider",
|
|
description: "Sandbox provider with captured template config binding.",
|
|
author: "Paperclip",
|
|
categories: ["automation"],
|
|
capabilities: ["environment.drivers.register"],
|
|
entrypoints: { worker: "./dist/worker.js" },
|
|
environmentDrivers: [
|
|
{
|
|
driverKey: "template-provider",
|
|
kind: "sandbox_provider",
|
|
displayName: "Template Provider",
|
|
supportsTemplateCapture: true,
|
|
templateRefKind: "provider_template",
|
|
templateConfigBinding: {
|
|
field: "templateId",
|
|
unsetFields: ["image"],
|
|
},
|
|
configSchema: { type: "object" },
|
|
},
|
|
],
|
|
});
|
|
|
|
expect(parsed.environmentDrivers?.[0]?.templateConfigBinding).toEqual({
|
|
field: "templateId",
|
|
unsetFields: ["image"],
|
|
});
|
|
});
|
|
|
|
it("rejects template config bindings that replace provider identity", () => {
|
|
const parsed = pluginManifestV1Schema.safeParse({
|
|
id: "paperclip.bad-template-provider",
|
|
apiVersion: 1,
|
|
version: "0.1.0",
|
|
displayName: "Bad Template Provider",
|
|
categories: ["automation"],
|
|
capabilities: ["environment.drivers.register"],
|
|
entrypoints: { worker: "./dist/worker.js" },
|
|
environmentDrivers: [
|
|
{
|
|
driverKey: "bad-template-provider",
|
|
kind: "sandbox_provider",
|
|
displayName: "Bad Template Provider",
|
|
templateConfigBinding: {
|
|
field: "provider",
|
|
},
|
|
configSchema: { type: "object" },
|
|
},
|
|
],
|
|
});
|
|
|
|
expect(parsed.success).toBe(false);
|
|
if (parsed.success) return;
|
|
expect(parsed.error.issues.some((issue) => issue.message.includes("provider key"))).toBe(true);
|
|
});
|
|
});
|
|
|
|
describe("plugin managed routine validators", () => {
|
|
it("accepts core issue surface visibility values in routine templates", () => {
|
|
const parsed = pluginManagedRoutineDeclarationSchema.parse({
|
|
routineKey: "wiki.refresh",
|
|
title: "Refresh Wiki",
|
|
activityGatePolicy: "require_external_activity",
|
|
activityGateScope: "project",
|
|
issueTemplate: { surfaceVisibility: "default" },
|
|
});
|
|
|
|
expect(parsed.issueTemplate?.surfaceVisibility).toBe("default");
|
|
expect(parsed.activityGatePolicy).toBe("require_external_activity");
|
|
expect(parsed.activityGateScope).toBe("project");
|
|
});
|
|
|
|
it("rejects non-core issue surface visibility values in routine templates", () => {
|
|
const parsed = pluginManagedRoutineDeclarationSchema.safeParse({
|
|
routineKey: "wiki.refresh",
|
|
title: "Refresh Wiki",
|
|
issueTemplate: { surfaceVisibility: "normal" },
|
|
});
|
|
|
|
expect(parsed.success).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe("plugin managed skill validators", () => {
|
|
const baseManifest = {
|
|
id: "paperclip.test-managed-skills",
|
|
apiVersion: 1,
|
|
version: "0.1.0",
|
|
displayName: "Managed Skills",
|
|
description: "Managed skills test plugin.",
|
|
author: "Paperclip",
|
|
categories: ["automation"],
|
|
entrypoints: { worker: "./dist/worker.js" },
|
|
} as const;
|
|
|
|
it("requires skills.managed when managed skills are declared", () => {
|
|
const parsed = pluginManifestV1Schema.safeParse({
|
|
...baseManifest,
|
|
capabilities: [],
|
|
skills: [{ skillKey: "wiki-maintainer", displayName: "Wiki Maintainer" }],
|
|
});
|
|
|
|
expect(parsed.success).toBe(false);
|
|
if (parsed.success) return;
|
|
expect(parsed.error.issues.some((issue) => issue.message.includes("skills.managed"))).toBe(true);
|
|
});
|
|
|
|
it("accepts managed skills with the skills.managed capability", () => {
|
|
const parsed = pluginManifestV1Schema.parse({
|
|
...baseManifest,
|
|
capabilities: ["skills.managed"],
|
|
skills: [{ skillKey: "wiki-maintainer", displayName: "Wiki Maintainer" }],
|
|
});
|
|
|
|
expect(parsed.skills?.[0]?.skillKey).toBe("wiki-maintainer");
|
|
});
|
|
});
|
|
|
|
describe("plugin UI slot validators", () => {
|
|
it("accepts route-scoped sidebar slots with a routePath", () => {
|
|
const parsed = pluginUiSlotDeclarationSchema.parse({
|
|
type: "routeSidebar",
|
|
id: "wiki-route-sidebar",
|
|
displayName: "Wiki Sidebar",
|
|
exportName: "WikiSidebar",
|
|
routePath: "wiki",
|
|
});
|
|
|
|
expect(parsed.routePath).toBe("wiki");
|
|
});
|
|
|
|
it("requires route-scoped sidebar slots to declare a routePath", () => {
|
|
const parsed = pluginUiSlotDeclarationSchema.safeParse({
|
|
type: "routeSidebar",
|
|
id: "wiki-route-sidebar",
|
|
displayName: "Wiki Sidebar",
|
|
exportName: "WikiSidebar",
|
|
});
|
|
|
|
expect(parsed.success).toBe(false);
|
|
if (parsed.success) return;
|
|
expect(parsed.error.issues[0]?.message).toBe("routeSidebar slots require routePath");
|
|
});
|
|
|
|
it("keeps reserved company route protection for route-scoped sidebars", () => {
|
|
const parsed = pluginUiSlotDeclarationSchema.safeParse({
|
|
type: "routeSidebar",
|
|
id: "settings-route-sidebar",
|
|
displayName: "Settings Sidebar",
|
|
exportName: "SettingsSidebar",
|
|
routePath: "settings",
|
|
});
|
|
|
|
expect(parsed.success).toBe(false);
|
|
if (parsed.success) return;
|
|
expect(parsed.error.issues.some((issue) => issue.message.includes("reserved by the host"))).toBe(true);
|
|
});
|
|
|
|
it("accepts workspace entity types as detailTab targets", () => {
|
|
const parsed = pluginUiSlotDeclarationSchema.parse({
|
|
type: "detailTab",
|
|
id: "workspace-diff-viewer",
|
|
displayName: "Diff",
|
|
exportName: "WorkspaceDiffViewer",
|
|
entityTypes: ["execution_workspace", "project_workspace"],
|
|
});
|
|
|
|
expect(parsed.entityTypes).toEqual(["execution_workspace", "project_workspace"]);
|
|
});
|
|
|
|
it("accepts execution_workspace as a toolbarButton entityType", () => {
|
|
const parsed = pluginUiSlotDeclarationSchema.parse({
|
|
type: "toolbarButton",
|
|
id: "workspace-open-diff",
|
|
displayName: "Open diff",
|
|
exportName: "OpenWorkspaceDiffButton",
|
|
entityTypes: ["execution_workspace"],
|
|
});
|
|
|
|
expect(parsed.entityTypes).toEqual(["execution_workspace"]);
|
|
});
|
|
|
|
it("accepts company settings page slots with a non-core settings route", () => {
|
|
const parsed = pluginUiSlotDeclarationSchema.parse({
|
|
type: "companySettingsPage",
|
|
id: "permissions-settings",
|
|
displayName: "Permissions",
|
|
exportName: "PermissionsSettingsPage",
|
|
routePath: "permissions",
|
|
});
|
|
|
|
expect(parsed.routePath).toBe("permissions");
|
|
});
|
|
|
|
it("prevents company settings page slots from shadowing core settings routes", () => {
|
|
const parsed = pluginUiSlotDeclarationSchema.safeParse({
|
|
type: "companySettingsPage",
|
|
id: "instance-settings",
|
|
displayName: "Instance",
|
|
exportName: "InstanceSettingsPage",
|
|
routePath: "instance",
|
|
});
|
|
|
|
expect(parsed.success).toBe(false);
|
|
if (parsed.success) return;
|
|
expect(parsed.error.issues.some((issue) => issue.message.includes("reserved by the host"))).toBe(true);
|
|
});
|
|
});
|
|
|
|
describe("sandbox provider capability declaration validators", () => {
|
|
it("preserves a declared acquisition budget and keeps it optional", () => {
|
|
const parsed = pluginManifestV1Schema.parse(
|
|
buildSandboxProviderManifest({ defaultAcquireTimeoutMs: 300_000 }),
|
|
);
|
|
expect(parsed.environmentDrivers?.[0]?.defaultAcquireTimeoutMs).toBe(300_000);
|
|
const legacy = pluginManifestV1Schema.parse(buildSandboxProviderManifest({}));
|
|
expect(legacy.environmentDrivers?.[0]?.defaultAcquireTimeoutMs).toBeUndefined();
|
|
});
|
|
|
|
it.each([0, -1, 1.5, Infinity, NaN, "300000", 86_400_001])(
|
|
"rejects an invalid acquisition budget: %s",
|
|
(defaultAcquireTimeoutMs) => {
|
|
expect(pluginManifestV1Schema.safeParse(
|
|
buildSandboxProviderManifest({ defaultAcquireTimeoutMs }),
|
|
).success).toBe(false);
|
|
},
|
|
);
|
|
|
|
it("test_manifest_accepts_sandbox_capabilities_and_rejects_unknown_capability_keys", () => {
|
|
const parsed = pluginManifestV1Schema.parse(
|
|
buildSandboxProviderManifest({
|
|
sandboxCapabilities: {
|
|
reusableLeases: true,
|
|
nativeSyncIn: true,
|
|
nativeSyncOut: false,
|
|
persistentProcessSessions: true,
|
|
independentControlCommands: false,
|
|
incrementalSessionOutput: true,
|
|
},
|
|
}),
|
|
);
|
|
|
|
expect(parsed.environmentDrivers?.[0]?.sandboxCapabilities).toEqual({
|
|
reusableLeases: true,
|
|
nativeSyncIn: true,
|
|
nativeSyncOut: false,
|
|
persistentProcessSessions: true,
|
|
independentControlCommands: false,
|
|
incrementalSessionOutput: true,
|
|
});
|
|
|
|
const rejected = pluginManifestV1Schema.safeParse(
|
|
buildSandboxProviderManifest({
|
|
sandboxCapabilities: {
|
|
reusableLeases: true,
|
|
// A typo or unknown capability name must fail validation, not drop
|
|
// silently. The nested schema is `.strict()`.
|
|
nativeSync: true,
|
|
},
|
|
}),
|
|
);
|
|
|
|
expect(rejected.success).toBe(false);
|
|
});
|
|
|
|
it("test_manifest_accepts_concurrent_sync_operations_capability", () => {
|
|
// A provider opts in to parallel bidirectional file sync with this key. The
|
|
// strict schema accepts it and keeps the declared value.
|
|
const parsed = pluginManifestV1Schema.parse(
|
|
buildSandboxProviderManifest({
|
|
sandboxCapabilities: { concurrentSyncOperations: true },
|
|
}),
|
|
);
|
|
|
|
expect(parsed.environmentDrivers?.[0]?.sandboxCapabilities).toEqual({
|
|
concurrentSyncOperations: true,
|
|
});
|
|
});
|
|
|
|
it("test_manifest_rejects_unknown_sync_concurrency_capability_key", () => {
|
|
// A neighboring but unknown concurrency key must fail validation, not drop
|
|
// silently. The strict schema rejects a capability the host does not honor.
|
|
const rejected = pluginManifestV1Schema.safeParse(
|
|
buildSandboxProviderManifest({
|
|
sandboxCapabilities: { concurrentSyncAndExec: true },
|
|
}),
|
|
);
|
|
expect(rejected.success).toBe(false);
|
|
});
|
|
|
|
it("test_supports_reusable_leases_compat_maps_to_reusable_leases", () => {
|
|
const parsed = pluginManifestV1Schema.parse(
|
|
buildSandboxProviderManifest({ supportsReusableLeases: true }),
|
|
);
|
|
const driver = parsed.environmentDrivers?.[0];
|
|
|
|
expect(driver?.sandboxCapabilities).toBeUndefined();
|
|
expect(resolveDeclaredSandboxCapabilities(driver!).reusableLeases).toBe(true);
|
|
});
|
|
|
|
it("test_sandbox_capabilities_reusable_leases_wins_over_compat_field", () => {
|
|
const parsed = pluginManifestV1Schema.parse(
|
|
buildSandboxProviderManifest({
|
|
supportsReusableLeases: true,
|
|
sandboxCapabilities: { reusableLeases: false },
|
|
}),
|
|
);
|
|
const driver = parsed.environmentDrivers?.[0];
|
|
|
|
// The nested declaration wins over the legacy compat flag when both exist.
|
|
expect(resolveDeclaredSandboxCapabilities(driver!).reusableLeases).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe("login pty transport capability and legacy alias", () => {
|
|
it("test_login_pty_new_field_parses_and_carries_the_flag", () => {
|
|
const parsed = pluginManifestV1Schema.parse(
|
|
buildSandboxProviderManifest({ supportsLoginPty: true }),
|
|
);
|
|
|
|
expect(parsed.environmentDrivers?.[0]?.supportsLoginPty).toBe(true);
|
|
});
|
|
|
|
it("test_legacy_alias_only_canonicalizes_onto_login_pty", () => {
|
|
const parsed = pluginManifestV1Schema.parse(
|
|
buildSandboxProviderManifest({ supportsSetupTokenLogin: true }),
|
|
);
|
|
const driver = parsed.environmentDrivers?.[0];
|
|
|
|
// The validator maps the deprecated alias onto the canonical field at parse
|
|
// time, and it drops the alias so a downstream reader cannot read the old
|
|
// name.
|
|
expect(driver?.supportsLoginPty).toBe(true);
|
|
expect(driver).not.toHaveProperty("supportsSetupTokenLogin");
|
|
});
|
|
|
|
it("test_conflicting_alias_and_new_field_reject", () => {
|
|
const rejected = pluginManifestV1Schema.safeParse(
|
|
buildSandboxProviderManifest({
|
|
supportsLoginPty: true,
|
|
supportsSetupTokenLogin: false,
|
|
}),
|
|
);
|
|
|
|
expect(rejected.success).toBe(false);
|
|
});
|
|
|
|
it("test_matching_alias_and_new_field_pass", () => {
|
|
const parsed = pluginManifestV1Schema.parse(
|
|
buildSandboxProviderManifest({
|
|
supportsLoginPty: true,
|
|
supportsSetupTokenLogin: true,
|
|
}),
|
|
);
|
|
|
|
expect(parsed.environmentDrivers?.[0]?.supportsLoginPty).toBe(true);
|
|
});
|
|
|
|
it("test_unknown_login_field_misspelling_rejects", () => {
|
|
const rejected = pluginManifestV1Schema.safeParse(
|
|
buildSandboxProviderManifest({ supportsLoginPTY: true }),
|
|
);
|
|
|
|
expect(rejected.success).toBe(false);
|
|
});
|
|
|
|
it("test_login_pty_accepts_literal_booleans_only", () => {
|
|
const rejected = pluginManifestV1Schema.safeParse(
|
|
buildSandboxProviderManifest({ supportsLoginPty: "true" }),
|
|
);
|
|
|
|
expect(rejected.success).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe("plugin WebSocket company resolution", () => {
|
|
const route = { routeKey: "channel.connect", method: "GET", path: "/channels/:channelId", auth: "board", capability: "api.routes.register" };
|
|
|
|
it("rejects body resolution only for WebSocket routes", () => {
|
|
const companyResolution = { from: "body", key: "companyId" };
|
|
expect(pluginApiRouteDeclarationSchema.safeParse({ ...route, companyResolution }).success).toBe(true);
|
|
expect(pluginApiRouteDeclarationSchema.safeParse({ ...route, companyResolution, transport: "websocket" }).success).toBe(false);
|
|
});
|
|
|
|
it.each([
|
|
undefined,
|
|
{ from: "query", key: "companyId" },
|
|
{ from: "issue", param: "issueId" },
|
|
{ from: "agent", param: "agentId" },
|
|
])("accepts body-free resolution %j", (companyResolution) => {
|
|
expect(pluginApiRouteDeclarationSchema.safeParse({ ...route, companyResolution, transport: "websocket" }).success).toBe(true);
|
|
});
|
|
});
|
|
|
|
describe("plugin task side-panel declarations", () => {
|
|
const slot = { type: "detailTab", id: "view", displayName: "Live view", exportName: "LiveView", entityTypes: ["agent"], taskSidePanel: { availabilityPath: "/agents/:entityId/view/availability" } };
|
|
const route = { routeKey: "view.availability", method: "GET", path: slot.taskSidePanel.availabilityPath, auth: "board", capability: "api.routes.register", companyResolution: { from: "agent", param: "entityId" } };
|
|
const manifest = { id: "example.live-view", apiVersion: 1, version: "1.0.0", displayName: "Live view", description: "Live view", author: "Tests", categories: ["ui"], capabilities: ["ui.detailTab.register", "api.routes.register"], entrypoints: { worker: "worker.js", ui: "ui.js" }, ui: { slots: [slot] }, apiRoutes: [route] };
|
|
it("accepts an optional panel backed by an authorized plugin-local agent route", () => {
|
|
expect(pluginManifestV1Schema.parse(manifest).ui?.slots?.[0]?.taskSidePanel).toEqual(slot.taskSidePanel);
|
|
});
|
|
it("accepts an explicit UI-independent activity mapping and preserves legacy declarations", () => {
|
|
const activation = { namespace: "example.runtime", activityKey: "desktop.used" };
|
|
expect(pluginUiSlotDeclarationSchema.parse({ ...slot, taskSidePanel: { ...slot.taskSidePanel, activation } }).taskSidePanel?.activation).toEqual(activation);
|
|
expect(pluginUiSlotDeclarationSchema.parse(slot).taskSidePanel?.activation).toBeUndefined();
|
|
for (const value of ["视".repeat(60), "😀".repeat(160)]) {
|
|
expect(pluginUiSlotDeclarationSchema.safeParse({ ...slot, taskSidePanel: { ...slot.taskSidePanel, activation: { namespace: value, activityKey: value } } }).success).toBe(true);
|
|
}
|
|
for (const activation of [{ namespace: "", activityKey: "used" }, { namespace: "runtime", activityKey: "😀".repeat(161) }, { namespace: "runtime", activityKey: "\u007f" }, { namespace: "runtime", activityKey: "used", runId: "other" }]) {
|
|
expect(pluginUiSlotDeclarationSchema.safeParse({ ...slot, taskSidePanel: { ...slot.taskSidePanel, activation } }).success).toBe(false);
|
|
}
|
|
});
|
|
it("accepts a GET availability route when a POST at the same path is declared first", () => {
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, apiRoutes: [{ ...route, routeKey: "view.update", method: "POST" }, route] }).success).toBe(true);
|
|
});
|
|
it.each(["https://example.test/:entityId", "//example/:entityId", "/../:entityId", "/agents/:entityId?redirect=elsewhere", "/agents/:agentId/view"])("rejects unsafe or unsupported path %s", availabilityPath => {
|
|
expect(pluginUiSlotDeclarationSchema.safeParse({ ...slot, taskSidePanel: { availabilityPath } }).success).toBe(false);
|
|
});
|
|
it("rejects non-agent and non-detail contributions", () => {
|
|
expect(pluginUiSlotDeclarationSchema.safeParse({ ...slot, entityTypes: ["issue"] }).success).toBe(false);
|
|
expect(pluginUiSlotDeclarationSchema.safeParse({ ...slot, type: "page" }).success).toBe(false);
|
|
});
|
|
it.each([[], [{ ...route, method: "POST" }], [{ ...route, auth: "agent" }], [{ ...route, companyResolution: { from: "query", key: "companyId" } }]].map(apiRoutes => ({ apiRoutes })))("requires a declared board GET route scoped to the supplied agent", ({ apiRoutes }) => {
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, apiRoutes }).success).toBe(false);
|
|
});
|
|
});
|
|
|
|
|
|
describe("agent environment slot requirements", () => {
|
|
const slot = { type: "detailTab", id: "view", displayName: "View", exportName: "View", entityTypes: ["agent"], agentEnvironmentDriver: "tasks" };
|
|
it("preserves the optional driver requirement", () => {
|
|
expect(pluginUiSlotDeclarationSchema.parse(slot).agentEnvironmentDriver).toBe("tasks");
|
|
});
|
|
it.each([{ agentEnvironmentDriver: "" }, { entityTypes: ["issue"] }, { entityTypes: ["agent", "issue"] }, { type: "page" }])("rejects unsupported requirements %j", patch => {
|
|
expect(pluginUiSlotDeclarationSchema.safeParse({ ...slot, ...patch }).success).toBe(false);
|
|
});
|
|
});
|