forked from farhoodlabs/paperclip
Devin Foley
367d4cab72
## 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
77 lines
3.1 KiB
TypeScript
77 lines
3.1 KiB
TypeScript
import { afterEach, describe, expect, it } from "vitest";
|
|
import { buildPaperclipEnv } from "../adapters/utils.js";
|
|
|
|
const ORIGINAL_PAPERCLIP_RUNTIME_API_URL = process.env.PAPERCLIP_RUNTIME_API_URL;
|
|
const ORIGINAL_PAPERCLIP_API_URL = process.env.PAPERCLIP_API_URL;
|
|
const ORIGINAL_PAPERCLIP_LISTEN_HOST = process.env.PAPERCLIP_LISTEN_HOST;
|
|
const ORIGINAL_PAPERCLIP_LISTEN_PORT = process.env.PAPERCLIP_LISTEN_PORT;
|
|
const ORIGINAL_HOST = process.env.HOST;
|
|
const ORIGINAL_PORT = process.env.PORT;
|
|
|
|
afterEach(() => {
|
|
if (ORIGINAL_PAPERCLIP_RUNTIME_API_URL === undefined) delete process.env.PAPERCLIP_RUNTIME_API_URL;
|
|
else process.env.PAPERCLIP_RUNTIME_API_URL = ORIGINAL_PAPERCLIP_RUNTIME_API_URL;
|
|
|
|
if (ORIGINAL_PAPERCLIP_API_URL === undefined) delete process.env.PAPERCLIP_API_URL;
|
|
else process.env.PAPERCLIP_API_URL = ORIGINAL_PAPERCLIP_API_URL;
|
|
|
|
if (ORIGINAL_PAPERCLIP_LISTEN_HOST === undefined) delete process.env.PAPERCLIP_LISTEN_HOST;
|
|
else process.env.PAPERCLIP_LISTEN_HOST = ORIGINAL_PAPERCLIP_LISTEN_HOST;
|
|
|
|
if (ORIGINAL_PAPERCLIP_LISTEN_PORT === undefined) delete process.env.PAPERCLIP_LISTEN_PORT;
|
|
else process.env.PAPERCLIP_LISTEN_PORT = ORIGINAL_PAPERCLIP_LISTEN_PORT;
|
|
|
|
if (ORIGINAL_HOST === undefined) delete process.env.HOST;
|
|
else process.env.HOST = ORIGINAL_HOST;
|
|
|
|
if (ORIGINAL_PORT === undefined) delete process.env.PORT;
|
|
else process.env.PORT = ORIGINAL_PORT;
|
|
});
|
|
|
|
describe("buildPaperclipEnv", () => {
|
|
it("prefers an explicit PAPERCLIP_RUNTIME_API_URL", () => {
|
|
process.env.PAPERCLIP_RUNTIME_API_URL = "http://203.0.113.42:3102";
|
|
process.env.PAPERCLIP_API_URL = "http://localhost:4100";
|
|
process.env.PAPERCLIP_LISTEN_HOST = "127.0.0.1";
|
|
process.env.PAPERCLIP_LISTEN_PORT = "3101";
|
|
|
|
const env = buildPaperclipEnv({ id: "agent-1", companyId: "company-1" });
|
|
|
|
expect(env.PAPERCLIP_API_URL).toBe("http://203.0.113.42:3102");
|
|
});
|
|
|
|
it("falls back to PAPERCLIP_API_URL when no runtime URL is configured", () => {
|
|
delete process.env.PAPERCLIP_RUNTIME_API_URL;
|
|
process.env.PAPERCLIP_API_URL = "http://localhost:4100";
|
|
process.env.PAPERCLIP_LISTEN_HOST = "127.0.0.1";
|
|
process.env.PAPERCLIP_LISTEN_PORT = "3101";
|
|
|
|
const env = buildPaperclipEnv({ id: "agent-1", companyId: "company-1" });
|
|
|
|
expect(env.PAPERCLIP_API_URL).toBe("http://localhost:4100");
|
|
});
|
|
|
|
it("uses runtime listen host/port when explicit URL is not set", () => {
|
|
delete process.env.PAPERCLIP_RUNTIME_API_URL;
|
|
delete process.env.PAPERCLIP_API_URL;
|
|
process.env.PAPERCLIP_LISTEN_HOST = "0.0.0.0";
|
|
process.env.PAPERCLIP_LISTEN_PORT = "3101";
|
|
process.env.PORT = "3100";
|
|
|
|
const env = buildPaperclipEnv({ id: "agent-1", companyId: "company-1" });
|
|
|
|
expect(env.PAPERCLIP_API_URL).toBe("http://localhost:3101");
|
|
});
|
|
|
|
it("formats IPv6 hosts safely in fallback URL generation", () => {
|
|
delete process.env.PAPERCLIP_RUNTIME_API_URL;
|
|
delete process.env.PAPERCLIP_API_URL;
|
|
process.env.PAPERCLIP_LISTEN_HOST = "::1";
|
|
process.env.PAPERCLIP_LISTEN_PORT = "3101";
|
|
|
|
const env = buildPaperclipEnv({ id: "agent-1", companyId: "company-1" });
|
|
|
|
expect(env.PAPERCLIP_API_URL).toBe("http://[::1]:3101");
|
|
});
|
|
});
|