@perkos/perkos-a2a 0.12.39 → 0.12.41

package/README.md

@@ -198,9 +198,11 @@ files are created with owner-only permissions.
 It validates config and plugin health, then reads only plugin-owned runtime
 evidence. It never mutates `commands.restart`, sends `SIGUSR1`, waits for an
 OpenClaw gateway drain, launches a second relay/chat client, or scrapes gateway
-status/logs. Clean installs complete through hot reload. Certified upgrades use
-a fenced supervisor rollover while the gateway and its active model/runtime
-remain untouched. Relay, registration, heartbeat, and chat authentication must
+status/logs. Clean installs complete through hot reload. OpenClaw 2026.5 caches
+an already-loaded plugin module, so version upgrades stage the verified package
+and normalized config, then return `ACTION_REQUIRED_REAL_RESTART` immediately;
+the same command resumes after the operator restarts the gateway process or
+container. Relay, registration, heartbeat, and chat authentication must
 remain healthy—with no duplicate plugin or registration messages—for three
 continuous minutes and at least three fresh successful heartbeats. Success or
 failure is emitted as one JSON object; secret values are never printed.
@@ -221,14 +223,15 @@ start identity, boot id, claim time, and transport counts in private health
 evidence so `connect` can distinguish a certified owner from stale files.
 
 For a clean first install, OpenClaw's PID 1 hot reload remains supported without
-a gateway restart. A certified upgrade fences and stops the old supervisor,
-waits for `STOPPED` plus socket/process exit, starts the supervisor CLI from the
-new verified install root, and requires target-version health before opening a
-single relay client. When upgrading a pre-supervisor or otherwise uncertified
-installation, `connect` exits promptly with the machine-readable action
-`ACTION_REQUIRED_REAL_RESTART`; rerunning the same idempotent command after an
-out-of-band service/container restart resumes the migration without replacing
-identity or credentials.
+a gateway restart. A version upgrade keeps a certified entry enabled while it
+stages the new package, records why a real restart is required, and exits
+promptly with the machine-readable action `ACTION_REQUIRED_REAL_RESTART` instead
+of waiting for evidence that a cached VM cannot produce. The same action is used
+for a pre-supervisor or otherwise uncertified installation. Rerunning the exact
+idempotent command after an out-of-band service/container restart resumes the
+migration, verifies the changed PID/start identity and target supervisor, and
+never replaces identity or credentials. Same-version OpenClaw VM reloads remain
+serialized by the single-owner supervisor fence.
 
 On successful verification, `connect` removes the active-attempt file and marks
 the private repair journal `done`. Stale OpenClaw install metadata is reported

package/dist/index.d.ts

@@ -25,6 +25,12 @@ type OpenClawSessionEntry = Record<string, unknown>;
  * whose default model metadata can reference a plugin harness that is absent.
  */
 export declare function omitUnavailableAgentHarness(value: unknown, unavailableHarnessId: string): unknown;
+/**
+ * Select OpenClaw's built-in harness for the route OpenClaw itself resolved.
+ * This changes no provider/model selection: the temporary policy is scoped to
+ * that exact runtime-owned route and exists only for this retry.
+ */
+export declare function useNativeHarnessForResolvedRoute(value: unknown, provider?: string, model?: string): unknown;
 /**
  * Remove model and harness selections persisted by an earlier chat wake so
  * the next turn resolves the gateway's current default. A configured plugin
@@ -32,6 +38,10 @@ export declare function omitUnavailableAgentHarness(value: unknown, unavailableH
  * model, without imposing a provider on every invited agent.
  */
 export declare function alignOpenClawChatSessionModel(entry: OpenClawSessionEntry, configuredModel?: string): OpenClawSessionEntry;
+export declare function prepareOpenClawChatSession(api: any, config: A2APluginConfig, sessionKey: string, logger: {
+    info: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}): Promise<void>;
 type EmbeddedChatRunResult = {
     payloads?: Array<{
         text?: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAGV,WAAW,EAEZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,cAAc,YAAY,CAAC;AA0C3B,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAItF;AAED,KAAK,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AASpD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,oBAAoB,EAAE,MAAM,GAC3B,OAAO,CA2BT;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,oBAAoB,EAC3B,eAAe,CAAC,EAAE,MAAM,GACvB,oBAAoB,CA+BtB;AAiED,KAAK,qBAAqB,GAAG;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,CAAC,CAAC;IACH,IAAI,CAAC,EAAE;QACL,yBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;CACH,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAYrF;AAQD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CAAE,GAClF,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuFxB;AAYD,oFAAoF;AACpF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,WAAW,EAAE,EACvB,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAWR;AA4CD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAe/D;AAMD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAc7E;AAED,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,GAAG,QAszBxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -29443,6 +29443,58 @@ function openclawChatSessionKey(config, convId) {
   const safe = convId.replace(/[^a-zA-Z0-9_.-]/g, "-").slice(0, 120) || "unknown";
   return `${configured}:perkos-chat-${safe}`;
 }
+async function mutateOpenClawChatSession(api, config, sessionKey, update) {
+  const sessionApi = api.runtime?.agent?.session;
+  const patchSessionEntry = sessionApi?.patchSessionEntry;
+  if (typeof patchSessionEntry === "function") {
+    await patchSessionEntry({
+      sessionKey,
+      fallbackEntry: { sessionId: randomUUID7(), updatedAt: Date.now() },
+      preserveActivity: true,
+      replaceEntry: true,
+      update
+    });
+    return "modern";
+  }
+  const resolveStorePath = sessionApi?.resolveStorePath;
+  const updateSessionStore = sessionApi?.updateSessionStore;
+  if (typeof resolveStorePath !== "function" || typeof updateSessionStore !== "function") {
+    return null;
+  }
+  const agentId = openclawAgentId(config);
+  const storePath = resolveStorePath(void 0, { agentId });
+  await updateSessionStore(
+    storePath,
+    (store) => {
+      const current = store[sessionKey] ?? { sessionId: randomUUID7(), updatedAt: Date.now() };
+      store[sessionKey] = update(current);
+      return store[sessionKey];
+    },
+    { activeSessionKey: sessionKey }
+  );
+  return "legacy";
+}
+function readOpenClawChatSession(api, agentId, sessionKey) {
+  const sessionApi = api.runtime?.agent?.session;
+  const modernEntry = sessionApi?.getSessionEntry?.({ agentId, sessionKey });
+  if (modernEntry && typeof modernEntry === "object") return { entry: modernEntry };
+  const resolveStorePath = sessionApi?.resolveStorePath;
+  const loadSessionStore = sessionApi?.loadSessionStore;
+  if (typeof resolveStorePath !== "function" || typeof loadSessionStore !== "function") {
+    return {};
+  }
+  try {
+    const storePath = resolveStorePath(void 0, { agentId });
+    const store = loadSessionStore(storePath, { skipCache: true, clone: true });
+    const entry = store?.[sessionKey];
+    const sessionId = typeof entry?.sessionId === "string" ? entry.sessionId : void 0;
+    const resolveSessionFilePath = sessionApi?.resolveSessionFilePath;
+    const sessionFile = sessionId && typeof resolveSessionFilePath === "function" ? resolveSessionFilePath(sessionId, entry, { agentId, storePath }) : void 0;
+    return { entry, sessionFile };
+  } catch {
+    return {};
+  }
+}
 var MISSING_AGENT_HARNESS_RE = /Requested agent harness "([^"]+)" is not registered\./u;
 function missingAgentHarnessId(error) {
   const message = error instanceof Error ? error.message : String(error);
@@ -29466,6 +29518,33 @@ function omitUnavailableAgentHarness(value, unavailableHarnessId) {
   }
   return next;
 }
+function useNativeHarnessForResolvedRoute(value, provider, model) {
+  const selectedProvider = provider?.trim();
+  const selectedModel = model?.trim();
+  if (!value || typeof value !== "object" || !selectedProvider || !selectedModel) return value;
+  const source = value;
+  const agents = source.agents && typeof source.agents === "object" ? source.agents : {};
+  const defaults = agents.defaults && typeof agents.defaults === "object" ? agents.defaults : {};
+  const models = defaults.models && typeof defaults.models === "object" ? defaults.models : {};
+  const modelKey = selectedModel.includes("/") ? selectedModel : `${selectedProvider}/${selectedModel}`;
+  const modelEntry = models[modelKey] && typeof models[modelKey] === "object" ? models[modelKey] : {};
+  return {
+    ...source,
+    agents: {
+      ...agents,
+      defaults: {
+        ...defaults,
+        models: {
+          ...models,
+          [modelKey]: {
+            ...modelEntry,
+            agentRuntime: { id: "pi" }
+          }
+        }
+      }
+    }
+  };
+}
 function alignOpenClawChatSessionModel(entry, configuredModel) {
   const next = { ...entry };
   for (const key of [
@@ -29498,21 +29577,19 @@ function alignOpenClawChatSessionModel(entry, configuredModel) {
   return next;
 }
 async function prepareOpenClawChatSession(api, config, sessionKey, logger) {
-  const patchSessionEntry = api.runtime?.agent?.session?.patchSessionEntry;
-  if (typeof patchSessionEntry !== "function") {
-    logger.info("[perkos-chat] OpenClaw session metadata API unavailable \u2014 using gateway session defaults");
-    return;
-  }
   try {
-    await patchSessionEntry({
+    const source = await mutateOpenClawChatSession(
+      api,
+      config,
       sessionKey,
-      fallbackEntry: { sessionId: randomUUID7(), updatedAt: Date.now() },
-      preserveActivity: true,
-      replaceEntry: true,
-      update: (entry) => alignOpenClawChatSessionModel(entry, config.runtime?.model)
-    });
+      (entry) => alignOpenClawChatSessionModel(entry, config.runtime?.model)
+    );
+    if (!source) {
+      logger.info("[perkos-chat] OpenClaw session metadata API unavailable \u2014 using gateway session defaults");
+      return;
+    }
     logger.info(
-      config.runtime?.model ? `[perkos-chat] session ${sessionKey} pinned to ${config.runtime.model}` : `[perkos-chat] session ${sessionKey} aligned to the gateway's active default model`
+      config.runtime?.model ? `[perkos-chat] session ${sessionKey} pinned to ${config.runtime.model}` : `[perkos-chat] session ${sessionKey} aligned to the gateway's active default model (${source} session API)`
     );
   } catch (err) {
     logger.error(
@@ -29521,23 +29598,22 @@ async function prepareOpenClawChatSession(api, config, sessionKey, logger) {
   }
 }
 async function forceNativeOpenClawChatRuntime(api, config, sessionKey, logger) {
-  const patchSessionEntry = api.runtime?.agent?.session?.patchSessionEntry;
-  if (typeof patchSessionEntry !== "function") return;
   try {
-    await patchSessionEntry({
+    const source = await mutateOpenClawChatSession(
+      api,
+      config,
       sessionKey,
-      fallbackEntry: { sessionId: randomUUID7(), updatedAt: Date.now() },
-      preserveActivity: true,
-      replaceEntry: true,
-      update: (entry) => ({
+      (entry) => ({
         ...alignOpenClawChatSessionModel(entry, config.runtime?.model),
         // OpenClaw <= 2026.5.x calls its built-in runtime "pi". Newer
         // gateways normalize the alias to their native "openclaw" harness.
         agentRuntimeOverride: "pi",
         agentHarnessId: "pi"
       })
-    });
-    logger.info(`[perkos-chat] session ${sessionKey} retrying with the native OpenClaw harness`);
+    );
+    if (source) {
+      logger.info(`[perkos-chat] session ${sessionKey} retrying with the native OpenClaw harness (${source} session API)`);
+    }
   } catch (err) {
     logger.error(
       `[perkos-chat] failed to select native OpenClaw harness: ${err instanceof Error ? err.message : String(err)}`
@@ -29566,19 +29642,23 @@ async function runOpenClawChatTurn(api, config, sessionKey, prompt, transcriptPr
   const agentId = openclawAgentId(config);
   const runtimeConfig = currentConfig();
   const workspaceDir = resolveAgentWorkspaceDir(runtimeConfig, agentId);
-  const entry = api.runtime?.agent?.session?.getSessionEntry?.({ agentId, sessionKey });
+  const sessionContext = readOpenClawChatSession(api, agentId, sessionKey);
+  const entry = sessionContext.entry;
   const sessionId = typeof entry?.sessionId === "string" && entry.sessionId.trim() ? entry.sessionId : randomUUID7();
   const configuredTimeout = api.runtime?.agent?.resolveAgentTimeoutMs?.(runtimeConfig);
   const timeoutMs = Math.min(
     75e3,
     typeof configuredTimeout === "number" && configuredTimeout > 0 ? configuredTimeout : 75e3
   );
+  let selectedProvider;
+  let selectedModel;
   const run = async (configOverride, retryNative = false) => runEmbeddedAgent({
     sessionId,
     sessionKey,
     agentId,
     workspaceDir,
     config: configOverride,
+    ...sessionContext.sessionFile ? { sessionFile: sessionContext.sessionFile } : {},
     prompt,
     transcriptPrompt,
     timeoutMs,
@@ -29590,6 +29670,10 @@ async function runOpenClawChatTurn(api, config, sessionKey, prompt, transcriptPr
     terminalReplyExpectation: "required",
     suppressLiveStreamOutput: true,
     cleanupBundleMcpOnRunEnd: true,
+    onExecutionPhase: (info) => {
+      if (info.provider?.trim()) selectedProvider = info.provider.trim();
+      if (info.model?.trim()) selectedModel = info.model.trim();
+    },
     ...retryNative ? {
       // Cross-version compatibility: 2026.5.x recognizes `pi`, while
       // current gateways recognize the explicit native runtime override.
@@ -29610,7 +29694,11 @@ async function runOpenClawChatTurn(api, config, sessionKey, prompt, transcriptPr
       );
       await forceNativeOpenClawChatRuntime(api, config, sessionKey, logger);
       result = await run(
-        omitUnavailableAgentHarness(runtimeConfig, unavailableHarnessId),
+        useNativeHarnessForResolvedRoute(
+          omitUnavailableAgentHarness(runtimeConfig, unavailableHarnessId),
+          selectedProvider,
+          selectedModel
+        ),
         true
       );
     }
@@ -30418,7 +30506,9 @@ export {
   normalizeOpenClawPluginConfig,
   omitUnavailableAgentHarness,
   openclawChatSessionKey,
-  runOpenClawChatTurn
+  prepareOpenClawChatSession,
+  runOpenClawChatTurn,
+  useNativeHarnessForResolvedRoute
 };
 /*! Bundled license information: