@perkos/perkos-a2a 0.12.63 → 0.12.64
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/dist/a2a-maintenance.d.ts +7 -2
- package/dist/a2a-maintenance.d.ts.map +1 -1
- package/dist/a2a-maintenance.js +15 -7
- package/dist/a2a-maintenance.js.map +1 -1
- package/dist/a2a-maintenance.test.js +17 -5
- package/dist/a2a-maintenance.test.js.map +1 -1
- package/dist/bridge-agent.js +11 -4
- package/dist/bridge-agent.js.map +1 -1
- package/dist/chat-client.d.ts +3 -0
- package/dist/chat-client.d.ts.map +1 -1
- package/dist/chat-client.js +9 -3
- package/dist/chat-client.js.map +1 -1
- package/dist/index.js +20 -10
- package/dist/index.js.map +2 -2
- package/dist/platform-heartbeat.d.ts +6 -0
- package/dist/platform-heartbeat.d.ts.map +1 -1
- package/dist/platform-heartbeat.js +6 -1
- package/dist/platform-heartbeat.js.map +1 -1
- package/docs/plans/2026-09-02-chat-bound-maintenance-capability-design.md +36 -0
- package/openclaw.plugin.json +1 -1
- package/package.json +1 -1
|
@@ -4,8 +4,13 @@ export type PlatformHeartbeatLogger = {
|
|
|
4
4
|
};
|
|
5
5
|
export type PlatformHeartbeatHandle = {
|
|
6
6
|
stop(): void;
|
|
7
|
+
reportNow(): void;
|
|
7
8
|
};
|
|
8
9
|
export type PlatformRuntimeStatus = "healthy" | "unreachable" | "unknown";
|
|
10
|
+
export type PlatformMaintenanceCapability = {
|
|
11
|
+
protocolVersion: 1;
|
|
12
|
+
bridgeInstanceId: string;
|
|
13
|
+
};
|
|
9
14
|
/**
|
|
10
15
|
* Keep the PerkOS agent presence record fresh while the bridge is alive.
|
|
11
16
|
*
|
|
@@ -23,6 +28,7 @@ export declare function startPlatformHeartbeat(opts: {
|
|
|
23
28
|
relayKey?: string;
|
|
24
29
|
runtimeKind?: "openclaw" | "hermes" | "custom";
|
|
25
30
|
runtimeStatus?: PlatformRuntimeStatus | (() => PlatformRuntimeStatus | Promise<PlatformRuntimeStatus>);
|
|
31
|
+
maintenanceCapability?: PlatformMaintenanceCapability | null | (() => PlatformMaintenanceCapability | null);
|
|
26
32
|
version?: string;
|
|
27
33
|
onResult?: (result: {
|
|
28
34
|
ok: boolean;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"platform-heartbeat.d.ts","sourceRoot":"","sources":["../src/platform-heartbeat.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,IAAI,IAAI,CAAC;
|
|
1
|
+
{"version":3,"file":"platform-heartbeat.d.ts","sourceRoot":"","sources":["../src/platform-heartbeat.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,IAAI,IAAI,CAAC;IACb,SAAS,IAAI,IAAI,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAAC;AAE1E,MAAM,MAAM,6BAA6B,GAAG;IAC1C,eAAe,EAAE,CAAC,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAKF;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,MAAM,EAAE,uBAAuB,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC/C,aAAa,CAAC,EAAE,qBAAqB,GAAG,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC;IACvG,qBAAqB,CAAC,EAAE,6BAA6B,GAAG,IAAI,GAAG,CAAC,MAAM,6BAA6B,GAAG,IAAI,CAAC,CAAC;IAC5G,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAClF,GAAG,uBAAuB,CAqF1B"}
|
|
@@ -14,7 +14,7 @@ export function startPlatformHeartbeat(opts) {
|
|
|
14
14
|
const url = opts.url?.trim() || env.PERKOS_HEARTBEAT_URL?.trim();
|
|
15
15
|
const relayKey = opts.relayKey?.trim() || env.A2A_RELAY_API_KEY?.trim();
|
|
16
16
|
if (!url || !relayKey)
|
|
17
|
-
return { stop: () => undefined };
|
|
17
|
+
return { stop: () => undefined, reportNow: () => undefined };
|
|
18
18
|
const configuredInterval = Number(opts.intervalMs ?? env.PERKOS_HEARTBEAT_INTERVAL_MS ?? DEFAULT_INTERVAL_MS);
|
|
19
19
|
const intervalMs = Number.isFinite(configuredInterval)
|
|
20
20
|
? Math.max(MIN_INTERVAL_MS, configuredInterval)
|
|
@@ -36,6 +36,9 @@ export function startPlatformHeartbeat(opts) {
|
|
|
36
36
|
const runtimeStatus = typeof opts.runtimeStatus === "function"
|
|
37
37
|
? await opts.runtimeStatus()
|
|
38
38
|
: opts.runtimeStatus ?? "unknown";
|
|
39
|
+
const maintenanceCapability = typeof opts.maintenanceCapability === "function"
|
|
40
|
+
? opts.maintenanceCapability()
|
|
41
|
+
: opts.maintenanceCapability ?? null;
|
|
39
42
|
const res = await fetcher(url, {
|
|
40
43
|
method: "POST",
|
|
41
44
|
headers: {
|
|
@@ -48,6 +51,7 @@ export function startPlatformHeartbeat(opts) {
|
|
|
48
51
|
version: opts.version?.trim() || env.PERKOS_A2A_VERSION?.trim() || "0.12.51",
|
|
49
52
|
ts: Date.now(),
|
|
50
53
|
runtimeStatus,
|
|
54
|
+
...(opts.maintenanceCapability !== undefined ? { maintenanceCapability } : {}),
|
|
51
55
|
}),
|
|
52
56
|
});
|
|
53
57
|
if (res.ok) {
|
|
@@ -72,6 +76,7 @@ export function startPlatformHeartbeat(opts) {
|
|
|
72
76
|
const timer = setInterval(() => void report(), intervalMs);
|
|
73
77
|
timer.unref?.();
|
|
74
78
|
return {
|
|
79
|
+
reportNow: () => void report(),
|
|
75
80
|
stop: () => {
|
|
76
81
|
stopped = true;
|
|
77
82
|
clearInterval(timer);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"platform-heartbeat.js","sourceRoot":"","sources":["../src/platform-heartbeat.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"platform-heartbeat.js","sourceRoot":"","sources":["../src/platform-heartbeat.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Chat-bound maintenance capability
|
|
2
|
+
|
|
3
|
+
## Problem
|
|
4
|
+
|
|
5
|
+
The platform inferred managed-update support from the reported A2A package
|
|
6
|
+
version. A bridge could therefore publish `0.12.63` while another legacy
|
|
7
|
+
process owned the active Chat registration. The App offered an update, but the
|
|
8
|
+
marker remained pending because no active consumer claimed it.
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
Managed maintenance is fail-closed and requires all of the following:
|
|
13
|
+
|
|
14
|
+
1. Hermes runtime and A2A package `>=0.12.64`.
|
|
15
|
+
2. Protocol-v1 capability in a recent heartbeat.
|
|
16
|
+
3. A UUID `bridgeInstanceId` generated once per bridge process.
|
|
17
|
+
4. An authenticated Chat connection owned by that same process.
|
|
18
|
+
5. A request and claim addressed to the same `bridgeInstanceId`.
|
|
19
|
+
|
|
20
|
+
The standalone bridge reports capability immediately after Chat authentication
|
|
21
|
+
and revokes it immediately after disconnect. The API leases the evidence for
|
|
22
|
+
125 seconds using server time. Every ordinary heartbeat without the capability
|
|
23
|
+
clears it. The App only renders the managed action while that lease is valid.
|
|
24
|
+
|
|
25
|
+
## Failure behavior
|
|
26
|
+
|
|
27
|
+
- A compatible semver without fresh capability shows bootstrap required.
|
|
28
|
+
- A duplicate or superseded process cannot claim a marker addressed elsewhere.
|
|
29
|
+
- Expired capability prevents request creation with `BOOTSTRAP_REQUIRED`.
|
|
30
|
+
- Voice remains an independent optional capability.
|
|
31
|
+
|
|
32
|
+
## Migration
|
|
33
|
+
|
|
34
|
+
Version `0.12.63` cannot advertise this stronger contract. Existing Hermes
|
|
35
|
+
agents need the one-time `update-hermes` bootstrap to `0.12.64`; subsequent
|
|
36
|
+
updates can use the managed marker flow.
|
package/openclaw.plugin.json
CHANGED