@hybridaione/hybridclaw 0.25.2 → 0.25.3

package/AGENTS.md

@@ -264,6 +264,13 @@ hybridclaw gateway status             # gateway liveness, PID, build/version dia
   `await import()` and static `import` for the same module in production paths.
 - **Dependencies:** root `package.json` is for gateway/CLI deps. Container-only
   deps go in `container/package.json`. Never add container deps to root.
+- When changing npm dependencies, update every generated dependency artifact in
+  the same change: the relevant `package-lock.json`, matching
+  `npm-shrinkwrap.json`, and the approved lockfile hashes in
+  `scripts/dependency-policy-baseline.json`. Use `npm run deps:update-lockfile`
+  when practical, or copy the updated lockfile to its shrinkwrap pair and
+  update the baseline hash after reviewing the lockfile diff. Run
+  `npm run deps:policy` before handing off.
 
 ### Git Discipline
 

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 ## Unreleased
 
+## [0.25.3](https://github.com/HybridAIOne/hybridclaw/tree/v0.25.3) - 2026-06-22
+
+### Added
+
+- **Langfuse skill**: LLM observability and evaluation based on the official
+  Langfuse skill (`github.com/langfuse/skills`, MIT). Reads traces, observations,
+  sessions, scores, prompts, datasets, models, and metrics, and creates scores,
+  comments, datasets, dataset items, and prompt versions through the
+  gateway-proxied `langfuse.cjs` helper. Auth uses a SecretRef-backed
+  `Authorization: Basic <secret:LANGFUSE_BASIC_AUTH>` header with a
+  `LANGFUSE_HOST` config variable; reads are green and writes are grant-gated.
+  Bundles the upstream reference docs (instrumentation, prompt migration, error
+  analysis, judge calibration, SDK upgrade, CI/CD) plus Langfuse documentation
+  lookup (llms.txt / markdown / search-docs).
+
+### Changed
+
+- **Quick Start guide**: Rewrote the getting-started quickstart into a
+  zero-to-working funnel -- a fast HybridAI Cloud path (model preselected,
+  already in web chat) and a numbered local path (onboard -> start gateway ->
+  confirm healthy with `gateway status` / `doctor` -> open chat -> send a first
+  message) with explicit success signals, a troubleshooting block, and a command
+  cheat sheet. Relocated the per-channel startup auto-connect conditions into the
+  Channels overview.
+- **Apple desktop release**: README and docs point at the signed/notarized Apple
+  Silicon DMG, and the desktop wrapper captures gateway startup logs, recent
+  child output, spawn failures, and early exits so packaged app launch failures
+  are diagnosable.
+
+### Fixed
+
+- **MCP server startup isolation**: A single MCP server that fails to connect or
+  disconnect is logged and skipped instead of aborting the whole chat turn, and
+  unchanged failed server configs are not retried every turn.
+- **Empty heartbeat context**: Workspace bootstrap context skips the default
+  empty `HEARTBEAT.md` template and legacy "no recurring heartbeat tasks"
+  placeholders, avoiding noise in agent startup context.
+
 ## [0.25.2](https://github.com/HybridAIOne/hybridclaw/tree/v0.25.2) - 2026-06-20
 
 ### Fixed
@@ -13,6 +51,12 @@
 
 ## [0.25.1](https://github.com/HybridAIOne/hybridclaw/tree/v0.25.1) - 2026-06-20
 
+### Changed
+
+- **Desktop packaging**: Desktop build commands rebuild the app before
+  packaging, reuse current icon/runtime stages, cache the staged Node runtime,
+  and strip non-runtime dependency files from packaged desktop bundles.
+
 ### Fixed
 
 - **HybridAI cloud admin sessions**: HybridAI-launched sessions without scoped

package/README.md

@@ -69,7 +69,15 @@ HybridClaw on HybridAI Cloud in a few minutes at
 
 Fastest managed launch: [HybridClaw on HybridAI Cloud](https://hybridclaw.io).
 
-Linux/macOS one-line installer:
+Apple Desktop App for macOS:
+
+- Download the signed and notarized Apple Silicon DMG:
+  [HybridClaw-0.25.3-arm64.dmg](https://github.com/HybridAIOne/hybridclaw/releases/download/v0.25.3/HybridClaw-0.25.3-arm64.dmg)
+- Open the DMG, drag `HybridClaw.app` into `/Applications`, and launch it.
+- The desktop app starts the local gateway and opens the chat, agents, and
+  admin surfaces in a native macOS window.
+
+Linux/macOS CLI one-line installer:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/HybridAIOne/hybridclaw/main/scripts/install.sh | bash
@@ -98,7 +106,7 @@ After the gateway starts, open:
 | TUI | `hybridclaw tui` | Terminal chat, approvals, status, resume |
 | OpenAI-compatible API | `http://127.0.0.1:9090/v1/chat/completions` | Local evals and compatible clients |
 
-For signed macOS desktop builds, use the
+For signed macOS desktop builds and future architectures, use the
 [GitHub Releases](https://github.com/HybridAIOne/hybridclaw/releases/latest)
 page.
 
@@ -220,7 +228,7 @@ Core pieces:
 | Build desktop releases | [Desktop Release Builds](https://hybridaione.github.io/hybridclaw/docs/developer-guide/desktop-release) |
 | Contribute | [CONTRIBUTING.md](./CONTRIBUTING.md), [docs/content/README.md](./docs/content/README.md) |
 
-Latest release: [v0.25.2](https://github.com/HybridAIOne/hybridclaw/releases/tag/v0.25.2).
+Latest release: [v0.25.3](https://github.com/HybridAIOne/hybridclaw/releases/tag/v0.25.3).
 Release notes: [CHANGELOG.md](./CHANGELOG.md)
 
 ## Development

package/console/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hybridaione/hybridclaw-console",
   "private": true,
-  "version": "0.25.2",
+  "version": "0.25.3",
   "type": "module",
   "scripts": {
     "build": "tsc --noEmit && vite build",

package/container/dist/mcp/config-watcher.js

@@ -28,12 +28,28 @@ export class McpConfigWatcher {
         for (const name of Object.keys(previous)) {
             if (nextNames.has(name))
                 continue;
-            await this.manager.removeClient(name);
+            // Tearing down one server must not abort the whole apply.
+            try {
+                await this.manager.removeClient(name);
+            }
+            catch (error) {
+                this.logServerFailure('disconnect', name, error);
+            }
         }
         for (const [name, config] of Object.entries(nextConfig)) {
-            if (!configsEqual(previous[name], config)) {
+            if (configsEqual(previous[name], config))
+                continue;
+            // A single MCP server failing to connect (e.g. an expired OAuth token
+            // answering the initial POST with 401/invalid_token) must NOT reject
+            // applyConfig — that rejection propagates up through syncMcpConfig into
+            // the chat turn and crashes it, taking down ALL chat for the agent.
+            // Log and skip the bad server so the turn proceeds with the rest.
+            try {
                 await this.manager.replaceClient(name, config);
             }
+            catch (error) {
+                this.logServerFailure('connect', name, error);
+            }
         }
         this.lastConfig = nextConfig;
         this.lastHash = nextHash;
@@ -43,5 +59,9 @@ export class McpConfigWatcher {
         this.lastConfig = {};
         this.lastHash = stableHash('{}');
     }
+    logServerFailure(phase, name, error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        console.error(`[mcp:${name}] failed to ${phase}: ${detail}`);
+    }
 }
 //# sourceMappingURL=config-watcher.js.map

package/container/dist/mcp/config-watcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-watcher.js","sourceRoot":"","sources":["../../src/mcp/config-watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAKzC,SAAS,WAAW,CAClB,OAAoD;IAEpD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC,CAG9C,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,YAAY,CACnB,IAAiC,EACjC,KAAsB;IAEtB,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,OAAO,gBAAgB;IAIE;IAHrB,UAAU,GAAoC,EAAE,CAAC;IACjD,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAEpC,YAA6B,OAAyB;QAAzB,YAAO,GAAP,OAAO,CAAkB;IAAG,CAAC;IAE1D,KAAK,CAAC,KAAK,CAAC,OAAyC;QACnD,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,WAAW,CACf,OAAyC;QAEzC,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QACxD,IAAI,QAAQ,KAAK,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QAE7C,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;QACjC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAEnD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzC,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YAClC,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC;QAED,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YACxD,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC;gBAC1C,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACjD,CAAC;QACH,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI;QACF,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;CACF"}
+{"version":3,"file":"config-watcher.js","sourceRoot":"","sources":["../../src/mcp/config-watcher.ts"],"names":[],"mappings":"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"}

package/container/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "hybridclaw-agent",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hybridclaw-agent",
-      "version": "0.25.2",
+      "version": "0.25.3",
       "dependencies": {
         "@modelcontextprotocol/sdk": "1.29.0",
         "@mozilla/readability": "0.6.0",

package/container/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "hybridclaw-agent",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hybridclaw-agent",
-      "version": "0.25.2",
+      "version": "0.25.3",
       "dependencies": {
         "@modelcontextprotocol/sdk": "1.29.0",
         "@mozilla/readability": "0.6.0",

package/container/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hybridclaw-agent",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "type": "module",
   "main": "dist/index.js",
   "packageManager": "npm@11.10.0",

package/container/src/mcp/config-watcher.ts

@@ -45,12 +45,25 @@ export class McpConfigWatcher {
 
     for (const name of Object.keys(previous)) {
       if (nextNames.has(name)) continue;
-      await this.manager.removeClient(name);
+      // Tearing down one server must not abort the whole apply.
+      try {
+        await this.manager.removeClient(name);
+      } catch (error) {
+        this.logServerFailure('disconnect', name, error);
+      }
     }
 
     for (const [name, config] of Object.entries(nextConfig)) {
-      if (!configsEqual(previous[name], config)) {
+      if (configsEqual(previous[name], config)) continue;
+      // A single MCP server failing to connect (e.g. an expired OAuth token
+      // answering the initial POST with 401/invalid_token) must NOT reject
+      // applyConfig — that rejection propagates up through syncMcpConfig into
+      // the chat turn and crashes it, taking down ALL chat for the agent.
+      // Log and skip the bad server so the turn proceeds with the rest.
+      try {
         await this.manager.replaceClient(name, config);
+      } catch (error) {
+        this.logServerFailure('connect', name, error);
       }
     }
 
@@ -63,4 +76,13 @@ export class McpConfigWatcher {
     this.lastConfig = {};
     this.lastHash = stableHash('{}');
   }
+
+  private logServerFailure(
+    phase: 'connect' | 'disconnect',
+    name: string,
+    error: unknown,
+  ): void {
+    const detail = error instanceof Error ? error.message : String(error);
+    console.error(`[mcp:${name}] failed to ${phase}: ${detail}`);
+  }
 }

package/dist/gateway/gateway-http-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-http-server.d.ts","sourceRoot":"","sources":["../../src/gateway/gateway-http-server.ts"],"names":[],"mappings":"AA8zNA,MAAM,WAAW,iBAAiB;IAChC,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,wBAAgB,sBAAsB,IAAI,iBAAiB,CAk3B1D"}
+{"version":3,"file":"gateway-http-server.d.ts","sourceRoot":"","sources":["../../src/gateway/gateway-http-server.ts"],"names":[],"mappings":"AA40NA,MAAM,WAAW,iBAAiB;IAChC,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,wBAAgB,sBAAsB,IAAI,iBAAiB,CAw3B1D"}

package/dist/gateway/gateway-http-server.js

@@ -1584,6 +1584,17 @@ function resolveRequestOrigin(req, bodyBaseUrl) {
     const host = forwardedHost || req.headers.host || `127.0.0.1:${HEALTH_PORT}`;
     return `${proto}://${host}`;
 }
+function resolveA2AAgentCardOrigin(req) {
+    const configuredPublicUrl = getRuntimeConfig().deployment.public_url.trim();
+    if (configuredPublicUrl) {
+        const origin = normalizePublicBaseUrl(configuredPublicUrl);
+        if (origin)
+            return origin;
+        logger.warn({ publicUrl: configuredPublicUrl }, 'Invalid deployment.public_url for A2A Agent Card');
+        return null;
+    }
+    return resolveRequestOrigin(req);
+}
 function buildMobileLaunchUrl(params) {
     const url = new URL('/chat/continue', params.origin);
     url.searchParams.set('token', params.token);
@@ -5057,7 +5068,13 @@ export function startGatewayHttpServer() {
         }
         const voicePaths = resolveVoiceWebhookPaths(getRuntimeConfig().voice.webhookPath);
         if (pathname === '/.well-known/agent.json' && method === 'GET') {
-            const origin = resolveRequestOrigin(req);
+            const origin = resolveA2AAgentCardOrigin(req);
+            if (!origin) {
+                sendJson(res, 500, {
+                    error: 'deployment.public_url must be an HTTP(S) URL.',
+                });
+                return;
+            }
             const trust = resolveA2AAgentCardPeerTrust({
                 authorization: req.headers.authorization || '',
                 audience: new URL('/.well-known/agent.json', origin).toString(),