Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(server): a pushed platform boots on an older runtime again (#1058)

lmliheng9ffd5f19ac3f
diff --git a/changelog/unreleased/2026-10-28-platform-config-candidates.md b/changelog/unreleased/2026-10-28-platform-config-candidates.md
new file mode 100644
index 00000000..870d4262
--- /dev/null
+++ b/changelog/unreleased/2026-10-28-platform-config-candidates.md
@@ -0,0 +1,38 @@
+# A pushed platform boots on an older runtime again
+
+- **Date:** 2026-10-28
+- **Type:** fix
+- **Scope:** `server`
+- **Breaking:** no
+
+[中文](2026-10-28-platform-config-candidates.zh.md)
+
+Ported from PenguinHarness `64aebf0f` (`#1058`).
+
+A hot push replaces the platform, never the runtime. Because `penguinGoOrigin` was listed among the
+config members a platform claims, every installed runtime that predates that member — anything
+before the Go-provider work — refused the handshake, so a compatible platform could not be pushed
+to it, and each refused push could still restart the server. The same rule now also covers
+`modelscopeBridgeUrl`, which the handshake never required but whose consumer had no fallback and
+could read `undefined` on such a runtime.
+
+A config member added after runtimes shipped no longer enters the claimed list: it is optional on
+`ServerConfig`, and its consumer supplies the production default when the runtime publishes none —
+the same shape `cliEntry` already had.
+
+## Details
+
+- `packages/server/src/hmr/capabilities.ts`: `penguinGoOrigin` leaves `HMR_INTERFACES.config`, with
+ the rule written above the list naming `cliEntry`, `penguinGoOrigin` and `modelscopeBridgeUrl` as
+ the members that must stay out.
+- `packages/server/src/config.ts`: both members are optional on `ServerConfig` and say why.
+- `packages/server/src/services/{platform,modelscope}-auth-service.ts`: the providers fall back to
+ `normalizePenguinGoOrigin(undefined)` / `normalizeModelScopeBridgeUrl(undefined)` — the
+ production origin and bridge — instead of passing `undefined` on.
+- `packages/server/test/hmr-resources.test.ts`: one regression case — no member added after
+ runtimes shipped is named, and a runtime claiming today's list without them still claims.
+
+## Compatibility
+
+- No API, wire-format or stored-data change: the same values are published to a current runtime,
+ and an older runtime now gets the handshake instead of a refusal.
diff --git a/changelog/unreleased/2026-10-28-platform-config-candidates.zh.md b/changelog/unreleased/2026-10-28-platform-config-candidates.zh.md
new file mode 100644
index 00000000..985dae01
--- /dev/null
+++ b/changelog/unreleased/2026-10-28-platform-config-candidates.zh.md
@@ -0,0 +1,33 @@
+# 热推的平台又能在旧运行时上启动了
+
+- **Date:** 2026-10-28
+- **Type:** fix
+- **Scope:** `server`
+- **Breaking:** 否
+
+[English](2026-10-28-platform-config-candidates.md)
+
+移植自 PenguinHarness `64aebf0f`(`#1058`)。
+
+热推换的是平台,从来不是运行时。`penguinGoOrigin` 此前被列进平台声明的配置成员里,于是每一个
+比这个成员更早装上的运行时(Go provider 之前的所有安装)都拒绝握手 —— 本来兼容的平台推不过去,
+而每一次被拒的推送仍可能把服务端重启一遍。同一条规则现在也管住 `modelscopeBridgeUrl`:握手从来不
+要求它,但它的消费者没有兜底,在这样的运行时上会读到 `undefined`。
+
+运行时发货之后才加的配置成员,不再进入声明列表:它在 `ServerConfig` 上是可选的,消费者在没有值时
+补上生产默认值 —— 与 `cliEntry` 一直是同一个形状。
+
+## 细节
+
+- `packages/server/src/hmr/capabilities.ts`:`penguinGoOrigin` 移出 `HMR_INTERFACES.config`,规则
+ 写在列表上方,点名 `cliEntry` / `penguinGoOrigin` / `modelscopeBridgeUrl` 这三个必须留在外面的成员。
+- `packages/server/src/config.ts`:两个成员在 `ServerConfig` 上改为可选,并写明缘由。
+- `packages/server/src/services/{platform,modelscope}-auth-service.ts`:两个 provider 在没有值时回落到
+ `normalizePenguinGoOrigin(undefined)` / `normalizeModelScopeBridgeUrl(undefined)` —— 也就是生产用的
+ 源站与桥 —— 而不是把 `undefined` 传下去。
+- `packages/server/test/hmr-resources.test.ts`:一条回归用例 —— 「运行时之后才加的成员一个都没被点名」,
+ 且一个「今天的列表减去它们」的旧运行时仍然握手成功。
+
+## 兼容性
+
+- 接口、线上格式与已存数据都没变:当前运行时拿到的还是同样的值,旧运行时拿到的是握手而不是拒绝。
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index 0b95c496..d2e9a06b 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -47,16 +47,24 @@ export interface ServerConfig {
* derived per request instead.
*/
previewOrigin: string | null;
- /** Trusted Penguin Go origin; never supplied by a browser request. */
- penguinGoOrigin: string;
+ /**
+ * Trusted Penguin Go origin, never supplied by a browser request.
+ *
+ * OPTIONAL like `cliEntry`: a runtime older than this field publishes none, and a pushed
+ * platform must still boot there — its consumer (PlatformAuthProvider) then falls back to
+ * the default `normalizePenguinGoOrigin(undefined)` returns.
+ */
+ penguinGoOrigin?: string;
/**
* Base URL of the ModelScope authorization bridge (MODELSCOPE_BRIDGE_URL), without a
* trailing slash — e.g. `https://go.penguin.ooo/modelscope`. The harness sends the
* start/poll exchange here and never to ModelScope itself: the bridge holds the OAuth
* client secret. Unlike `penguinGoOrigin` this value carries a path prefix in production,
* because the bridge is mounted under one and strips it from the incoming request.
+ *
+ * OPTIONAL for the same reason as `penguinGoOrigin`; ModelScopeAuthProvider defaults it.
*/
- modelscopeBridgeUrl: string;
+ modelscopeBridgeUrl?: string;
/**
* Fixed initial password for the seeded built-in admin (ADELIE_SEED_ADMIN_PASSWORD),
* used by automated tests and e2e. Null is the norm: the seed then generates a random
diff --git a/packages/server/src/hmr/capabilities.ts b/packages/server/src/hmr/capabilities.ts
index 6cbaed1b..9aca2b5e 100644
--- a/packages/server/src/hmr/capabilities.ts
+++ b/packages/server/src/hmr/capabilities.ts
@@ -100,6 +100,11 @@ interface HmrInterfaces extends Interfaces {
export const HMR_INTERFACES: HmrInterfaces = {
family: PENGUIN_FAMILY,
+ // A config member added after runtimes shipped does NOT go in this list: naming it here
+ // refuses every installed runtime that predates it, and a push can never replace the
+ // runtime — only a reinstall can. Such a member is optional on ServerConfig and its
+ // consumer defaults it when the runtime does not publish it: cliEntry, penguinGoOrigin,
+ // modelscopeBridgeUrl.
config: [
"root",
"host",
@@ -114,7 +119,6 @@ export const HMR_INTERFACES: HmrInterfaces = {
"portFile",
"trustProxy",
"supervised",
- "penguinGoOrigin",
],
db: ["prepare", "exec", "close"],
channels: ["get", "peek", "broadcast", "dispose", "setActivityProbe"],
diff --git a/packages/server/src/services/modelscope-auth-service.ts b/packages/server/src/services/modelscope-auth-service.ts
index e32c7477..95f22eeb 100644
--- a/packages/server/src/services/modelscope-auth-service.ts
+++ b/packages/server/src/services/modelscope-auth-service.ts
@@ -19,6 +19,7 @@ import { randomBytes } from "node:crypto";
import { Interface, Module, Provide, Use } from "@adelie/core/kernel";
import { MODELSCOPE_PROVIDER_ID } from "@adelie/core/model-catalog";
import { HttpError } from "../http/errors.js";
+import { normalizeModelScopeBridgeUrl } from "../config.js";
import { Config } from "../hmr/capabilities.js";
import type {
ModelProviderAuthToken,
@@ -633,7 +634,8 @@ export class ModelScopeAuthProvider {
setup() {
this.auth = new ModelScopeAuthService({
- bridgeUrl: this.config.modelscopeBridgeUrl,
+ // A runtime older than the field publishes none; the default is the production bridge.
+ bridgeUrl: this.config.modelscopeBridgeUrl ?? normalizeModelScopeBridgeUrl(undefined),
applyCredential: async (projectId, credential, options) => {
if (credential.refreshToken !== undefined) {
return this.projectConfig.setGroupApiKeyWithProviderAuthToken(
diff --git a/packages/server/src/services/platform-auth-service.ts b/packages/server/src/services/platform-auth-service.ts
index bb76d24f..0f88ef96 100644
--- a/packages/server/src/services/platform-auth-service.ts
+++ b/packages/server/src/services/platform-auth-service.ts
@@ -11,6 +11,7 @@ import { randomBytes } from "node:crypto";
import { Interface, Module, Provide, Use } from "@adelie/core/kernel";
import { PENGUIN_GO_PROVIDER_ID } from "@adelie/core/model-catalog";
import { HttpError } from "../http/errors.js";
+import { normalizePenguinGoOrigin } from "../config.js";
import { Config } from "../hmr/capabilities.js";
import type { ProjectConfigStore } from "../mechanisms/projects.js";
import type { PlatformAuthFlowStatusResponse } from "../api/types.js";
@@ -604,7 +605,8 @@ export class PlatformAuthProvider {
setup() {
this.auth = new PlatformAuthService({
- origin: this.config.penguinGoOrigin,
+ // A runtime older than the field publishes none; the default is the production origin.
+ origin: this.config.penguinGoOrigin ?? normalizePenguinGoOrigin(undefined),
getKey: (projectId) => this.projectConfig.getGroupApiKey(projectId, PENGUIN_GO_PROVIDER_ID),
applyCatalog: (projectId, catalog, apiKey, applyKeyToExisting) =>
this.projectConfig.mergePlatformModels(
diff --git a/packages/server/test/hmr-resources.test.ts b/packages/server/test/hmr-resources.test.ts
index 194bd34b..c1295a3d 100644
--- a/packages/server/test/hmr-resources.test.ts
+++ b/packages/server/test/hmr-resources.test.ts
@@ -342,6 +342,23 @@ describe("runtime capability handshake", () => {
expect(claimHmrCapabilities(r)).toMatchObject({ kind: "refused" });
});
+ it("names no config member added after runtimes shipped, so an older runtime still claims", () => {
+ // Naming one would refuse every installed runtime that predates it, and a push can never
+ // replace the runtime. These are optional on ServerConfig and defaulted by their consumer.
+ for (const later of ["cliEntry", "penguinGoOrigin", "modelscopeBridgeUrl"]) {
+ expect(HMR_INTERFACES.config).not.toContain(later);
+ }
+ // A runtime that published today's list minus nothing more: the pre-#716 shape, whose
+ // config object has no `penguinGoOrigin` to offer.
+ const r = new HotResources();
+ stubCaps(r);
+ r.register(HMR_CONFIG_RESOURCE_ID, {
+ ...Object.fromEntries(HMR_INTERFACES.config.map((m) => [m, () => undefined])),
+ });
+ r.register(HMR_INTERFACES_RESOURCE_ID, { ...HMR_INTERFACES });
+ expect(claimHmrCapabilities(r)).toMatchObject({ kind: "claimed" });
+ });
+
it("claims on a matching descriptor", () => {
const r = new HotResources();
stubCaps(r);