mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-15 02:20:38 +09:00
aea35fe695
## Thinking Path
> - Paperclip orchestrates AI agents and provisions sandboxed execution
environments for them; one of those provisioners is the exe.dev plugin,
which runs each agent inside a long-lived VM reached over SSH.
> - The instance-config form for that plugin is rendered generically by
`JsonSchemaForm` from the plugin's `instanceConfigSchema`, so any UX
problem with the form is split between the shared form component and the
plugin's schema/runtime code.
> - Users coming in cold hit a 12-field flat config they couldn't reason
about (PAPA-407), a form that silently submitted `cpu: 0` for untouched
optional fields (PAPA-407 root cause), a `sshPrivateKey` textarea that
truncated RSA-4096 keys at 4096 chars (PAPA-449), a save flow that
accepted clearly-malformed keys and only blew up at lease time with raw
SSH stderr (PAPA-450, PAPA-451), and a manifest that didn't distinguish
"essential" from "advanced" knobs (PAPA-410 / PAPA-411 — duplicate
sub-issues with identical scope; PAPA-418 reconciliation kept PAPA-410
canonical).
> - These problems all point at the same surface (exe.dev sandbox
config) and are tightly coupled in code — PAPA-449/450/451 patch fields
that PAPA-410/411 introduce — so they get reviewed together.
> - This pull request lands the shared-form changes (advanced-options
disclosure, optional-scalar defaults) and the exe.dev-specific changes
(manifest restructure, longer `maxLength`, stderr translation, save-time
key validation) as five focused commits stacked on `master`.
> - The benefit is a config form that defaults to the two fields a new
user actually needs (API key + SSH private key) with a collapsible
disclosure for the rest, no silent truncation or zero-default
submissions, and SSH key problems surfaced at save time with actionable
messages instead of cryptic post-provision failures.
## What Changed
- **JsonSchemaForm advanced-options disclosure** (PAPA-410, PAPA-411 —
same scope, see note above): adds `x-paperclip-advanced` /
`x-paperclip-group` schema annotations and renders flagged fields behind
a collapsible "Advanced options" disclosure that auto-opens when a
hidden field has a validation error. Exe.dev manifest is restructured to
use the new annotations, so essentials (`apiKey`, `sshPrivateKey`) show
by default while the long tail of optional knobs is grouped under "SSH
access" / "VM resources" / "More options" headings.
- **Omit optional scalar defaults** (PAPA-407): `getDefaultForSchema` no
longer materialises `0` / `""` for optional
`number`/`integer`/`string`/`secret-ref` fields without an explicit
`default`. Object recursion drops properties whose default is
`undefined`. Fields that declare a `default` (e.g. `sshPort: 22`) still
round-trip. Adds a regression test against `getDefaultValues`.
- **Raise `sshPrivateKey` `maxLength`** (PAPA-449): bumps the exe.dev
manifest cap from 4096 to 8192 so RSA-4096 OpenSSH private keys (which
can exceed 4 KB with comments/metadata) aren't silently truncated at
submit.
- **Translate `invalid format` SSH stderr** (PAPA-450):
`formatSshFailure` now recognises `Load key … invalid format` in
combined stderr/stdout and returns a specific message naming the
key-format problem ("isn't an OpenSSH/PEM private key — confirm the
secret starts with `-----BEGIN … PRIVATE KEY-----` and isn't the `.pub`
or a PuTTY `.ppk` export") instead of dumping the raw stderr.
- **Save-time SSH key validation** (PAPA-451):
`onEnvironmentValidateConfig` inline-parses `sshPrivateKey` and rejects
common failure modes — pasted public keys, PuTTY `.ppk` format, missing
`-----END-----` footer, non-base64 body — so the form surfaces an inline
error before any VM is provisioned. Secret-ref bindings (UUIDs) are
still passed through unchanged.
## Verification
CI gates (`pnpm typecheck`, `pnpm test`, the targeted vitest suites
below) all pass.
Run locally:
```bash
# Shared form
pnpm --filter @paperclipai/ui exec vitest run src/components/JsonSchemaForm
# 9 tests pass — includes the new "omits optional scalar fields" regression
# and the three advanced-options-disclosure tests.
# exe.dev plugin
cd packages/plugins/sandbox-providers/exe-dev && pnpm test
# 32 tests pass — includes the new sshPrivateKey-validation cases
# and the new "invalid format" stderr-translation case.
```
Manual smoke (after reinstalling the plugin so the DB manifest
refreshes):
1. Open the exe.dev environment config page. **Default view shows API
Key + SSH Private Key only**, with an "Advanced options" disclosure for
everything else (PAPA-410 / PAPA-411).
2. Paste a `.pub` file's contents into SSH Private Key, click Save.
**Inline error** rejecting the wrong-format key (PAPA-451).
3. Re-paste a valid OpenSSH/PEM private key longer than 4096 bytes —
saves cleanly (PAPA-449).
4. Save the form with everything optional left blank — server no longer
rejects with `"cpu must be greater than 0 when provided"` (PAPA-407).
5. Force a bad key through via a stored secret-ref binding and lease a
VM — failure message names the key-format problem instead of dumping raw
SSH stderr (PAPA-450).
## Risks
- **PAPA-410 / PAPA-411 manifest restructure** is the largest surface
here. Schemas using `x-paperclip-*` extensions are forward-compatible
with stricter JSON Schema validators (extensions are ignored by
default), and the form gracefully renders a flat layout when no field
opts in.
- **PAPA-407** changes form-default behaviour: optional scalar fields
that previously round-tripped as `""` / `0` will now be `undefined` and
absent from the submitted payload. Downstream consumers that expected
the empty-string/zero shape need to treat the field as optional.
Spot-checked the existing exe.dev driver — it already uses
`parseOptionalString` / `parseOptionalInteger`, which treat missing
fields as `null` rather than `0`/`""`.
- **PAPA-451** adds a save-time check, so a
previously-saved-but-malformed `sshPrivateKey` raw value will now fail
to re-save. Bound secret-refs are unaffected, matching how the user
reaches the bad-key state today (via the secrets picker).
- **PAPA-449** simply raises a cap; no semantic risk.
- **PAPA-450** only kicks in on the "invalid format" code path; existing
onboarding-marker branch is untouched.
## Model Used
- Provider: Anthropic
- Model: Claude Opus 4.7 (`claude-opus-4-7`)
- Capabilities used: code reading, code editing, test execution, git/PR
mechanics, Paperclip API for issue coordination
## Checklist
- [x] PR body sections present (Thinking Path, What Changed,
Verification, Risks, Model Used, Checklist)
- [x] Unit tests added for the new behaviours (JsonSchemaForm
default-value omission + advanced disclosure; exe.dev plugin validation
+ stderr translation)
- [x] Existing tests still pass locally (`vitest run` on both packages)
- [x] No raw secrets, IP addresses, or machine-local config in commits
or PR body
- [x] Commits are atomic per linked issue (PAPA-410 / PAPA-411,
PAPA-407, PAPA-449, PAPA-450, PAPA-451)
- [x] Branch is up-to-date with `origin/master`
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
|
||
|---|---|---|
| .. | ||
| secrets | ||
| Activity.tsx | ||
| AdapterManager.tsx | ||
| AgentDetail.tsx | ||
| Agents.test.tsx | ||
| Agents.tsx | ||
| ApprovalDetail.tsx | ||
| Approvals.tsx | ||
| Auth.tsx | ||
| BoardClaim.tsx | ||
| BootstrapSetupUxLab.tsx | ||
| CliAuth.tsx | ||
| CloudUpstream.test.tsx | ||
| CloudUpstream.tsx | ||
| CloudUpstreamUxLab.tsx | ||
| Companies.tsx | ||
| CompanyAccess.test.tsx | ||
| CompanyAccess.tsx | ||
| CompanyEnvironments.tsx | ||
| CompanyExport.tsx | ||
| CompanyImport.tsx | ||
| CompanyInvites.test.tsx | ||
| CompanyInvites.tsx | ||
| CompanySettings.test.tsx | ||
| CompanySettings.tsx | ||
| CompanySettingsPluginPage.test.tsx | ||
| CompanySettingsPluginPage.tsx | ||
| CompanySkills.tsx | ||
| Costs.tsx | ||
| Dashboard.tsx | ||
| DashboardLive.tsx | ||
| DesignGuide.tsx | ||
| ExecutionWorkspaceDetail.test.tsx | ||
| ExecutionWorkspaceDetail.tsx | ||
| GoalDetail.test.tsx | ||
| GoalDetail.tsx | ||
| Goals.tsx | ||
| Inbox.test.tsx | ||
| Inbox.tsx | ||
| InstanceAccess.tsx | ||
| InstanceExperimentalSettings.tsx | ||
| InstanceGeneralSettings.tsx | ||
| InstanceSettings.tsx | ||
| InviteLanding.test.tsx | ||
| InviteLanding.tsx | ||
| InviteUxLab.test.tsx | ||
| InviteUxLab.tsx | ||
| IssueChatLongThreadPerf.tsx | ||
| IssueChatUxLab.tsx | ||
| IssueDetail.test.tsx | ||
| IssueDetail.tsx | ||
| Issues.test.tsx | ||
| Issues.tsx | ||
| JoinRequestQueue.tsx | ||
| MyIssues.tsx | ||
| NewAgent.tsx | ||
| NotFound.tsx | ||
| Org.tsx | ||
| OrgChart.test.tsx | ||
| OrgChart.tsx | ||
| PluginManager.tsx | ||
| PluginPage.test.tsx | ||
| PluginPage.tsx | ||
| PluginSettings.test.tsx | ||
| PluginSettings.tsx | ||
| ProfileSettings.test.tsx | ||
| ProfileSettings.tsx | ||
| ProjectDetail.test.tsx | ||
| ProjectDetail.tsx | ||
| Projects.test.tsx | ||
| Projects.tsx | ||
| ProjectWorkspaceDetail.test.tsx | ||
| ProjectWorkspaceDetail.tsx | ||
| RoutineDetail.tsx | ||
| Routines.test.tsx | ||
| Routines.tsx | ||
| RunTranscriptUxLab.tsx | ||
| Search.test.tsx | ||
| Search.tsx | ||
| Secrets.render.test.tsx | ||
| Secrets.test.ts | ||
| Secrets.tsx | ||
| SystemNoticeUxLab.tsx | ||
| UserProfile.tsx | ||
| Workspaces.tsx | ||