mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-23 09:07:46 +02:00
06689c1b3410000bcd65ff40cb469e600209c4db
4
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 SkilLab HR and TechandPaperclip
|
92bedaac4a |
fix(server): treat a scheme-less public base URL as absent instead of crashing startup (#13727)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - At boot the server selects the origin that agents must dial for the
control plane. It exports that origin to every run as
`PAPERCLIP_API_URL`
> - The selection starts from `auth.publicBaseUrl`. An operator writes
this value by hand
> - If the operator writes `host:port` and omits the scheme, the server
does not reject the value. The value is a valid URL with an opaque
scheme. The `origin` of such a URL serializes to the *string* `"null"`
> - The string `"null"` is truthy. Thus it gets through the `if (value)`
guard. The enclosing `try/catch` does not help, because the parse did
not fail. A later `new URL("null")` then throws `TypeError: Invalid URL`
on the startup path
> - The result is that the server does not start. The error message
names neither the configuration key nor the bad value
> - This pull request parses the public base URL in one helper. The
helper treats an unusable origin as absent configuration. This is the
same treatment that input which fails to parse gets today
> - The benefit is that a missing `https://` falls back to the existing
derived candidates. It no longer stops the boot
## Linked Issues or Issue Description
Fixes: #13576 — that issue reports this defect and includes a standalone
reproduction.
**Related PRs found by the duplicate search (none fix this defect).** I
searched the open PR list
for `runtime-api`, `publicBaseUrl`, `public base url`,
`PAPERCLIP_API_URL` and `Invalid URL`. I then
read the diff of every close neighbour. Refs #10517, Refs #9916, Refs
#7342, Refs #12886,
Refs #11564, Refs #9228. No one of them contains a test for an opaque
origin, and no one of them
compares an origin against `"null"`. They change *which reachable origin
wins*. This pull request
changes *how one unusable value is rejected*. The two subjects do not
overlap.
Refs #10517 and Refs #9916 are duplicates of each other. Neither touches
`server/src/runtime-api.ts`.
**One neighbour needs attention.** Refs #11564 adds a new function
`resolveRuntimeApiUrl`. That
function contains this code:
```ts
try {
const origin = new URL(explicitPublicBaseUrl).origin;
return { url: origin, reason: "explicit-public-base-url", ... };
} catch {
// Fall through to derived candidates if config parsing drifted.
}
```
This is the same defect in a third location. A scheme-less value parses
correctly. Thus the `catch`
does not run, and the function returns the literal string `"null"` as
the URL. The lines are pure
additions, so there is no text conflict with this pull request. But if
#11564 merges after this one,
it puts the defect back in a new function. The helper in this pull
request is module-private and
available to that function. I can add the one-line change to this branch
if the maintainers prefer
that.
## What Changed
`server/src/runtime-api.ts` — one new module-private helper, used at the
two existing call sites:
```ts
function parsePublicOrigin(rawUrl: string | null | undefined): string | null {
const trimmed = rawUrl?.trim();
if (!trimmed) return null;
let origin: string;
try {
origin = new URL(trimmed).origin;
} catch {
return null;
}
return origin === "null" ? null : origin;
}
```
- `choosePrimaryRuntimeApiUrl` now calls the helper. Its inline
`try/catch` is removed.
- `buildRuntimeApiCandidateUrls` now calls the helper. Its inline IIFE
is removed.
- `server/src/__tests__/runtime-api.test.ts` gets two new cases. One
case covers the wrong `"null"`
result. The other case covers the startup exception.
Counts: **+20 / −17** in `runtime-api.ts`. Five of the added lines are
the comment that explains the
opaque scheme. The test file is **+23 / −0**. There is no new
dependency. There is no `any` type. No
exported signature changes. The duplicated parse logic at the two call
sites becomes one function.
## Verification
I ran every step below against `master` at commit
`c65fc9e3c81c41aafe421aa90a00514b84343285`. That
commit is the merge base of this branch.
- **Unit tests**, with the repository runner (`vitest`), on the two
added cases:
- Before the fix: `Tests 2 failed | 6 passed (8)`. The two failures are
exactly the two new cases.
The assertion error is
`AssertionError: expected 'null' to be
'http://runtime-host.example.test:3102'`.
- After the fix: `Tests 8 passed (8)`.
- Both new cases are pure additions. No existing expectation changes,
because no existing test
uses a scheme-less `authPublicBaseUrl`.
- **Standalone reproduction with 8 arms** (attached to #13576): **6/8**
on unpatched `c65fc9e3`, and
**8/8** with the patch. The 5 regression arms and the 1 control arm give
the same result on both
sides. The control arm uses input that truly fails to parse. Thus the
reproduction discriminates
between the two builds. It does not pass by accident.
- **Typecheck**: `tsc --noEmit --strict --noEmitOnError --target ES2023
--module NodeNext` exits 0 on
the patched file. It also exits 0 on the unmodified file.
## Risks
**Low risk.** Reasons:
- The change only affects input that makes the server crash today. No
operator can depend on the
present behaviour, because the present behaviour stops the boot.
- The new path is not new code. The helper returns `null`, and `null`
goes to the fallback that
already exists for input that fails to parse.
- The second call site previously put the string `"null"` into the
candidate list. It now omits that
entry. A `"null"` origin is not reachable, so no caller can lose a
usable candidate.
**The one behaviour change a reviewer must agree with.** A bad value now
degrades quietly instead of
failing loudly. An operator who writes `host:port` gets a server that
starts on a derived origin. The
operator does not get an error.
I did not add a warning log, for one reason: the existing parse-failure
path is also silent. A log
would change behaviour that this pull request does not target, and it
would enlarge the diff. If the
maintainers want the warning, the correct fix is one log line inside
`parsePublicOrigin`, which
covers both input classes at once. This is now possible only because the
two call sites share one
function. Tell me if you want that, and I will add it.
**Migration:** none. No schema change, no data change, no configuration
change.
## Model Used
- Provider and model: Anthropic Claude, Opus 5
- Exact model ID: `claude-opus-5[1m]`
- Context window: 1M tokens
- Mode: extended thinking
- Capabilities used: tool use, shell execution, file editing, and GitHub
API access
- The human operator reviewed and authorized this submission. A human
approved the publication of
this pull request before I opened it.
## 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 — I read
the file. It has no item for the runtime API URL, for startup URL
validation, or for
configuration parsing.
- [x] I have searched GitHub for duplicate or related PRs and linked
them above — 5 queries, and I
read the diff of each close neighbour. See the linked-issues section.
- [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 — the branch is
`fix/scheme-less-public-base-url`
- [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 — no
user-facing document
describes this internal fallback, so no document change applies.
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green — not yet true, and I do not
check a box that is not true. On
commit `13ffb649`: 43 checks pass, 7 checks still run, 2 checks fail.
Both failures are the
PR-description gate that this update repairs. I will check this box when
the gates are green.
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups —
not yet true. Greptile gave
4/5 with one P2. That P2 is "Required PR sections missing", which this
update repairs.
- [x] I will address all Greptile and reviewer comments before
requesting merge — this update is
that work for the first review round.
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
|
||
|
Neeraj Kumar Singh BandNeeraj Kumar Singh
|
d5ceb82571 |
Prefer loopback runtime API URL for local agents (#5102)
## Thinking Path > - Paperclip is the open-source app that manages AI agents and their work coordination > - The server subsystem exposes a control-plane HTTP API that agents read and write task state against at runtime > - On local development machines, Paperclip binds to loopback (`127.0.0.1:3100`) but also advertises LAN hostnames via `allowedHostnames` for multi-device setups > - Agents inherit their API URL from `PAPERCLIP_API_URL` / `PAPERCLIP_RUNTIME_API_URL` env vars exported during server startup > - `choosePrimaryRuntimeApiUrl` was selecting the first entry in `allowedHostnames` (the LAN IP) before the loopback bind host, so agents on the same machine tried to connect to an unreachable LAN address (NEE-327) > - This PR fixes the chooser to return the normalized loopback bind host first, before considering LAN `allowedHostnames` > - The benefit is that local agents reliably reach the control plane regardless of `allowedHostnames` configuration ## What's going on Local Paperclip agents were sometimes inheriting `PAPERCLIP_API_URL=http://192.168.1.50:3100` even when the server was bound to loopback, which made the control plane unreachable from this workspace. This keeps the runtime API on the loopback bind host for local startup while still preserving LAN candidates for other callers. ## Problem `choosePrimaryRuntimeApiUrl` preferred the first allowed hostname over the actual loopback bind host. In the failing setup from NEE-327, that exported `http://192.168.1.50:3100` into agent env even though `http://127.0.0.1:3100` was the reachable control-plane URL. ## Solution The primary runtime URL chooser now returns the normalized loopback bind host before considering `allowedHostnames`. I added a focused unit test for the chooser and a startup regression that verifies `PAPERCLIP_RUNTIME_API_URL` / `PAPERCLIP_API_URL` stay on `127.0.0.1` while the candidate list still includes the LAN hostname. ## Testing - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/runtime-api.test.ts src/__tests__/server-startup-feedback-export.test.ts` - Result: `2` files passed, `13` tests passed - Runtime check: `curl -sS http://127.0.0.1:3100/api/health` returned `{"status":"ok",...}` during this heartbeat ## Notes Already-running local Paperclip servers need a restart to export the corrected `PAPERCLIP_API_URL` into new agent runs. Rollback is revert `df8d7fcf`. ## Model Used Claude Sonnet 4.6 (`claude-sonnet-4-6`), 1M context window, via the Paperclip Founding Engineer agent harness. Capabilities used: extended tool use, code editing, test execution, shell commands. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [ ] 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: Neeraj Kumar Singh <b.nirajkumarsingh@hotmail.com> |
||
|
Devin Foley
|
367d4cab72 |
Fix SSH callback URL selection for LAN and private networks (#4799)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Agents can run on remote hosts via SSH environments > - When a remote agent needs to call back to the Paperclip API, it needs a reachable URL > - But the runtime API URL candidate builder did not account for private network topologies where the server is only reachable via LAN or VPN addresses > - Agents on SSH hosts were failing to connect because the callback URL pointed to localhost or an unreachable address > - This PR fixes callback URL selection to honor `PAPERCLIP_API_URL`, prefer LAN-reachable candidates, filter unreachable link-local addresses, and include interface hosts in onboarding invite URLs > - The benefit is SSH-based agents can reliably reach the Paperclip API on private networks without manual URL configuration ## What Changed - `runtime-api.ts`: Added `PAPERCLIP_API_URL` as a first-priority candidate in `buildRuntimeApiCandidateUrls`; extracted `collectReachableInterfaceHosts` to enumerate non-loopback, non-link-local network interface IPs with IPv4 preference - `server/src/index.ts`: Export `PAPERCLIP_API_URL` from the server environment so it is available to callback candidate resolution - `server/src/routes/access.ts`: Include LAN interface hosts in onboarding invite connection candidates - `server/src/config.ts`: Attempted auto-allowing LAN interface hosts, then reverted to the per-instance allowlist approach (both commits included for history clarity) ## Verification - `pnpm test` — all existing and new tests pass, including new tests for LAN candidate ordering and link-local filtering - `pnpm typecheck` — clean - Manual: start a Paperclip server on a machine with a LAN IP, create an SSH environment pointing to another host on the same LAN, verify the agent's callback URL uses the LAN IP rather than localhost ## Risks - Low-medium. The candidate list now includes more addresses (all non-loopback LAN interfaces). These are candidates for the agent to try, not an allowlist — the server's allowed hostnames still gate which origins are accepted. Ordering change (LAN preferred over loopback) could affect existing setups where localhost was intentionally preferred. ## Model Used Codex GPT 5.4 high via Paperclip. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge |
||
|
Devin Foley
|
70679a3321 |
Add sandbox environment support (#4415)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - The environment/runtime layer decides where agent work executes and how the control plane reaches those runtimes. > - Today Paperclip can run locally and over SSH, but sandboxed execution needs a first-class environment model instead of one-off adapter behavior. > - We also want sandbox providers to be pluggable so the core does not hardcode every provider implementation. > - This branch adds the Sandbox environment path, the provider contract, and a deterministic fake provider plugin. > - That required synchronized changes across shared contracts, plugin SDK surfaces, server runtime orchestration, and the UI environment/workspace flows. > - The result is that sandbox execution becomes a core control-plane capability while keeping provider implementations extensible and testable. ## What Changed - Added sandbox runtime support to the environment execution path, including runtime URL discovery, sandbox execution targeting, orchestration, and heartbeat integration. - Added plugin-provider support for sandbox environments so providers can be supplied via plugins instead of hardcoded server logic. - Added the fake sandbox provider plugin with deterministic behavior suitable for local and automated testing. - Updated shared types, validators, plugin protocol definitions, and SDK helpers to carry sandbox provider and workspace-runtime contracts across package boundaries. - Updated server routes and services so companies can create sandbox environments, select them for work, and execute work through the sandbox runtime path. - Updated the UI environment and workspace surfaces to expose sandbox environment configuration and selection. - Added test coverage for sandbox runtime behavior, provider seams, environment route guards, orchestration, and the fake provider plugin. ## Verification - Ran locally before the final fixture-only scrub: - `pnpm -r typecheck` - `pnpm test:run` - `pnpm build` - Ran locally after the final scrub amend: - `pnpm vitest run server/src/__tests__/runtime-api.test.ts` - Reviewer spot checks: - create a sandbox environment backed by the fake provider plugin - run work through that environment - confirm sandbox provider execution does not inherit host secrets implicitly ## Risks - This touches shared contracts, plugin SDK plumbing, server runtime orchestration, and UI environment/workspace flows, so regressions would likely show up as cross-layer mismatches rather than isolated type errors. - Runtime URL discovery and sandbox callback selection are sensitive to host/bind configuration; if that logic is wrong, sandbox-backed callbacks may fail even when execution succeeds. - The fake provider plugin is intentionally deterministic and test-oriented; future providers may expose capability gaps that this branch does not yet cover. ## Model Used - OpenAI Codex coding agent on a GPT-5-class backend in the Paperclip/Codex harness. Exact backend model ID is not exposed in-session. Tool-assisted workflow with shell execution, file editing, git history inspection, and local 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) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge |