@pellux/goodvibes-sdk 0.30.3 → 0.33.0

package/dist/platform/utils/clipboard.js

@@ -7,47 +7,76 @@ const IMAGE_MIME_TYPES = [
     { mime: 'image/webp', mediaType: 'image/webp' },
     { mime: 'image/gif', mediaType: 'image/gif' },
 ];
+function bytesToString(value) {
+    if (!value)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Uint8Array)
+        return Buffer.from(value).toString('utf-8');
+    return String(value);
+}
+function recordClipboardAttempt(attempts, command, result) {
+    if (attempts.length >= 8)
+        return;
+    const stderr = bytesToString(result.stderr).trim();
+    attempts.push({
+        command,
+        exitCode: result.exitCode,
+        stderr: stderr ? stderr.slice(0, 300) : undefined,
+    });
+}
+function logClipboardAttempts(message, attempts) {
+    if (attempts.length === 0)
+        return;
+    logger.debug(message, { attempts: [...attempts] });
+}
 /**
  * pasteFromClipboard - Attempts to read from system clipboard using platform tools.
  */
 export function pasteFromClipboard() {
+    const attempts = [];
     try {
         if (process.platform === 'linux') {
             // Try wl-paste (Wayland) then xclip (X11)
             const wl = Bun.spawnSync(['wl-paste', '--no-newline'], {
                 stdin: 'ignore',
                 stdout: 'pipe',
-                stderr: 'ignore',
+                stderr: 'pipe',
                 timeout: 3000,
             });
             if (wl.exitCode === 0 && wl.stdout) {
                 return Buffer.from(wl.stdout).toString();
             }
+            recordClipboardAttempt(attempts, 'wl-paste', wl);
             const xclip = Bun.spawnSync(['xclip', '-selection', 'clipboard', '-o'], {
                 stdin: 'ignore',
                 stdout: 'pipe',
-                stderr: 'ignore',
+                stderr: 'pipe',
                 timeout: 3000,
             });
             if (xclip.exitCode === 0 && xclip.stdout) {
                 return Buffer.from(xclip.stdout).toString();
             }
+            recordClipboardAttempt(attempts, 'xclip', xclip);
         }
         else if (process.platform === 'darwin') {
             const pb = Bun.spawnSync(['pbpaste'], {
                 stdin: 'ignore',
                 stdout: 'pipe',
-                stderr: 'ignore',
+                stderr: 'pipe',
                 timeout: 3000,
             });
             if (pb.exitCode === 0 && pb.stdout) {
                 return Buffer.from(pb.stdout).toString();
             }
+            recordClipboardAttempt(attempts, 'pbpaste', pb);
         }
     }
     catch (err) {
         logger.error('Clipboard: Paste failed', { error: summarizeError(err) });
     }
+    logClipboardAttempts('Clipboard text read returned no data', attempts);
     return '';
 }
 /**
@@ -55,6 +84,7 @@ export function pasteFromClipboard() {
  * Returns base64-encoded image data and mediaType, or null if no image is available.
  */
 export function pasteImageFromClipboard() {
+    const attempts = [];
     try {
         if (process.platform === 'linux') {
             // Try wl-paste (Wayland) for each supported MIME type
@@ -62,7 +92,7 @@ export function pasteImageFromClipboard() {
                 const wl = Bun.spawnSync(['wl-paste', '--type', mime, '--no-newline'], {
                     stdin: 'ignore',
                     stdout: 'pipe',
-                    stderr: 'ignore',
+                    stderr: 'pipe',
                     timeout: 3000,
                 });
                 if (wl.exitCode === 0 && wl.stdout) {
@@ -71,13 +101,14 @@ export function pasteImageFromClipboard() {
                         return { data: buf.toString('base64'), mediaType };
                     }
                 }
+                recordClipboardAttempt(attempts, `wl-paste ${mime}`, wl);
             }
             // Try xclip (X11) for each supported MIME type
             for (const { mime, mediaType } of IMAGE_MIME_TYPES) {
                 const xclip = Bun.spawnSync(['xclip', '-selection', 'clipboard', '-t', mime, '-o'], {
                     stdin: 'ignore',
                     stdout: 'pipe',
-                    stderr: 'ignore',
+                    stderr: 'pipe',
                     timeout: 3000,
                 });
                 if (xclip.exitCode === 0 && xclip.stdout) {
@@ -86,6 +117,7 @@ export function pasteImageFromClipboard() {
                         return { data: buf.toString('base64'), mediaType };
                     }
                 }
+                recordClipboardAttempt(attempts, `xclip ${mime}`, xclip);
             }
         }
         else if (process.platform === 'darwin') {
@@ -93,7 +125,7 @@ export function pasteImageFromClipboard() {
             const pp = Bun.spawnSync(['pngpaste', '-'], {
                 stdin: 'ignore',
                 stdout: 'pipe',
-                stderr: 'ignore',
+                stderr: 'pipe',
                 timeout: 3000,
             });
             if (pp.exitCode === 0 && pp.stdout) {
@@ -102,12 +134,13 @@ export function pasteImageFromClipboard() {
                     return { data: ppBuf.toString('base64'), mediaType: 'image/png' };
                 }
             }
-            // Fallback: osascript — reads clipboard as PNG hex data
+            recordClipboardAttempt(attempts, 'pngpaste', pp);
+            // Next try osascript, which reads clipboard as PNG hex data.
             // Output format: «data PNGf<hex>» — extract hex after 'PNGf'
             const osa = Bun.spawnSync(['osascript', '-e', 'the clipboard as «class PNGf»'], {
                 stdin: 'ignore',
                 stdout: 'pipe',
-                stderr: 'ignore',
+                stderr: 'pipe',
                 timeout: 5000,
             });
             if (osa.exitCode === 0 && osa.stdout) {
@@ -121,10 +154,12 @@ export function pasteImageFromClipboard() {
                     }
                 }
             }
+            recordClipboardAttempt(attempts, 'osascript PNGf', osa);
         }
     }
     catch (err) {
-        logger.debug('Clipboard image access failed', { error: summarizeError(err) });
+        logger.warn('Clipboard image access failed', { error: summarizeError(err) });
     }
+    logClipboardAttempts('Clipboard image read returned no data', attempts);
     return null;
 }

package/dist/platform/utils/error-display.d.ts

@@ -1,30 +1,30 @@
-import { ProviderError, type ErrorCategory, type ErrorSource, type ProviderErrorOptions } from '../types/errors.js';
+import { ProviderError, type PlatformErrorCategory, type PlatformErrorSource, type ProviderErrorOptions } from '../types/errors.js';
 import type { StructuredDaemonErrorBody } from '../types/daemon-error-contract.js';
 export interface NormalizedError {
     readonly name: string;
     readonly message: string;
     readonly summary: string;
-    readonly hint?: string;
-    readonly code?: string;
-    readonly category: ErrorCategory;
-    readonly source: ErrorSource;
+    readonly hint?: string | undefined;
+    readonly code?: string | undefined;
+    readonly category: PlatformErrorCategory;
+    readonly source: PlatformErrorSource;
     readonly recoverable: boolean;
-    readonly statusCode?: number;
-    readonly provider?: string;
-    readonly operation?: string;
-    readonly phase?: string;
-    readonly requestId?: string;
-    readonly providerCode?: string;
-    readonly providerType?: string;
-    readonly retryAfterMs?: number;
+    readonly statusCode?: number | undefined;
+    readonly provider?: string | undefined;
+    readonly operation?: string | undefined;
+    readonly phase?: string | undefined;
+    readonly requestId?: string | undefined;
+    readonly providerCode?: string | undefined;
+    readonly providerType?: string | undefined;
+    readonly retryAfterMs?: number | undefined;
 }
 export interface ErrorNormalizationOptions {
-    readonly provider?: string;
-    readonly fallbackMessage?: string;
-    readonly source?: ErrorSource;
+    readonly provider?: string | undefined;
+    readonly fallbackMessage?: string | undefined;
+    readonly source?: PlatformErrorSource | undefined;
 }
 export interface ProviderErrorNormalizationOptions extends ProviderErrorOptions {
-    readonly fallbackMessage?: string;
+    readonly fallbackMessage?: string | undefined;
 }
 export declare function normalizeError(error: unknown, options?: ErrorNormalizationOptions): NormalizedError;
 export declare function summarizeError(error: unknown, options?: ErrorNormalizationOptions): string;

package/dist/platform/utils/error-display.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-display.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/error-display.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9H,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAuBnF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,iCAAkC,SAAQ,oBAAoB;IAC7E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAmJD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,eAAe,CA6CvG;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,MAAM,CAE9F;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,MAAM,CAU3F;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,yBAAyB,CAkBzH;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,iCAAsC,GAAG,aAAa,CA0D9G;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnF"}
+{"version":3,"file":"error-display.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/error-display.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,aAAa,EAAE,KAAK,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9I,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAuBnF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACnD;AAED,MAAM,WAAW,iCAAkC,SAAQ,oBAAoB;IAC7E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/C;AAmJD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,eAAe,CA6CvG;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,MAAM,CAE9F;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,MAAM,CAU3F;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,yBAA8B,GAAG,yBAAyB,CAkBzH;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,iCAAsC,GAAG,aAAa,CA0D9G;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnF"}

package/dist/platform/utils/error-display.js

@@ -178,7 +178,7 @@ function extractErrorMessage(error) {
     return String(error);
 }
 export function normalizeError(error, options = {}) {
-    // OBS-24: Redact Bearer tokens and API keys before any further processing.
+    // Redact Bearer tokens and API keys before any further processing.
     const rawMessage = redactSensitiveData(extractErrorMessage(error));
     const statusCode = error instanceof AppError
         ? error.statusCode

package/dist/platform/utils/fetch-with-timeout.d.ts

@@ -1,6 +1,5 @@
 /**
  * Sanitize a URL for logging: strip query params that might contain secrets.
- * @internal Exported for testing only.
  */
 export declare function sanitizeUrlForLog(url: string | URL | Request): string;
 /**

package/dist/platform/utils/fetch-with-timeout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-with-timeout.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/fetch-with-timeout.ts"],"names":[],"mappings":"AAWA;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,GAAG,MAAM,CAarE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC3B,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,QAAQ,CAAC,CAkBnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC3B,IAAI,CAAC,EAAE,WAAW,EAClB,SAAS,SAAS,GACjB,OAAO,CAAC,QAAQ,CAAC,CAmBnB"}
+{"version":3,"file":"fetch-with-timeout.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/fetch-with-timeout.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,GAAG,MAAM,CAarE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC3B,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,QAAQ,CAAC,CAkBnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAC3B,IAAI,CAAC,EAAE,WAAW,EAClB,SAAS,SAAS,GACjB,OAAO,CAAC,QAAQ,CAAC,CAmBnB"}

package/dist/platform/utils/fetch-with-timeout.js

@@ -9,7 +9,6 @@ const SENSITIVE_PARAMS = new Set([
 ]);
 /**
  * Sanitize a URL for logging: strip query params that might contain secrets.
- * @internal Exported for testing only.
  */
 export function sanitizeUrlForLog(url) {
     try {

package/dist/platform/utils/logger.js

@@ -43,7 +43,7 @@ class ActivityLogger {
         const chunk = this.buffer.splice(0).join('');
         appendFile(this.logPath, chunk, (err) => {
             if (err) {
-                // Best-effort: cannot log the logger's own error without recursion
+                // Cannot log the logger's own error without recursion.
                 process.stderr.write(`[ActivityLogger] flush error: ${err.message}\n`);
             }
         });

package/dist/platform/utils/markdown-disclosure.js

@@ -40,7 +40,7 @@ function parseSimpleYamlFrontmatter(frontmatter) {
         }
         const listItem = line.match(/^\s+-\s+(.+)$/);
         if (collectingList && listItem) {
-            listBuffer.push(stripWrappingQuotes(listItem[1].trim()));
+            listBuffer.push(stripWrappingQuotes((listItem[1] ?? '').trim()));
             continue;
         }
         const kv = line.match(/^([\w.-]+):\s*(.*)$/);
@@ -48,8 +48,8 @@ function parseSimpleYamlFrontmatter(frontmatter) {
             continue;
         if (collectingList)
             flushList();
-        currentKey = kv[1];
-        const rawValue = kv[2].trim();
+        currentKey = kv[1] ?? '';
+        const rawValue = (kv[2] ?? '').trim();
         if (!rawValue) {
             collectingList = true;
             continue;
@@ -94,7 +94,7 @@ export function extractMarkdownSections(body) {
     const headingRegex = /^\s{0,3}(#{1,6})\s+(.+?)\s*$/gm;
     let match;
     while ((match = headingRegex.exec(body)) !== null) {
-        sections.push(match[2].trim());
+        sections.push((match[2] ?? '').trim());
     }
     return sections;
 }

package/dist/platform/utils/notify.d.ts

@@ -1,7 +1,7 @@
 /** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
 /**
  * notifyCompletion - Emit terminal bell and/or desktop notification on turn completion.
- * Non-fatal: notification errors are reported and never crash the app.
+ * Notification errors are reported and never crash the app.
  *
  * @param title     - Notification title
  * @param message   - Notification body

package/dist/platform/utils/notify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/notify.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAKrF;;;;;;;GAOG;AACH,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CA4BzF"}
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/notify.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAKrF;;;;;;;GAOG;AACH,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAiCD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAmBzF"}

package/dist/platform/utils/notify.js

@@ -3,7 +3,7 @@ import { summarizeError } from './error-display.js';
 import { logger } from './logger.js';
 /**
  * notifyCompletion - Emit terminal bell and/or desktop notification on turn completion.
- * Non-fatal: notification errors are reported and never crash the app.
+ * Notification errors are reported and never crash the app.
  *
  * @param title     - Notification title
  * @param message   - Notification body
@@ -13,6 +13,36 @@ import { logger } from './logger.js';
 export function escapeAppleScript(s) {
     return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 }
+function trimNotificationOutput(value) {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed.slice(0, 500) : undefined;
+}
+function spawnNotification(command) {
+    try {
+        const proc = Bun.spawn(command, { stdin: 'ignore', stdout: 'ignore', stderr: 'pipe' });
+        const stderr = new Response(proc.stderr).text();
+        void Promise.all([proc.exited, stderr])
+            .then(([exitCode, stderrText]) => {
+            if (exitCode !== 0) {
+                logger.warn('Completion notification command failed', {
+                    command: command[0],
+                    exitCode,
+                    stderr: trimNotificationOutput(stderrText),
+                });
+            }
+        })
+            .catch((error) => {
+            logger.warn('Completion notification failed', {
+                error: summarizeError(error),
+            });
+        });
+    }
+    catch (error) {
+        logger.warn('Completion notification failed', {
+            error: summarizeError(error),
+        });
+    }
+}
 export function notifyCompletion(title, message, durationMs) {
     // Terminal bell for responses > 5s.
     // Surface-specific: this writes directly to stdout and is only meaningful
@@ -23,20 +53,13 @@ export function notifyCompletion(title, message, durationMs) {
     }
     // Desktop notification for responses > 30s
     if (durationMs > 30000) {
-        try {
-            if (process.platform === 'linux') {
-                Bun.spawn(['notify-send', title, message], { stdin: 'ignore', stdout: 'ignore', stderr: 'ignore' });
-            }
-            else if (process.platform === 'darwin') {
-                const safeTitle = escapeAppleScript(title);
-                const safeMessage = escapeAppleScript(message);
-                Bun.spawn(['osascript', '-e', `display notification "${safeMessage}" with title "${safeTitle}"`], { stdin: 'ignore', stdout: 'ignore', stderr: 'ignore' });
-            }
+        if (process.platform === 'linux') {
+            spawnNotification(['notify-send', title, message]);
         }
-        catch (error) {
-            logger.debug('Completion notification failed', {
-                error: summarizeError(error),
-            });
+        else if (process.platform === 'darwin') {
+            const safeTitle = escapeAppleScript(title);
+            const safeMessage = escapeAppleScript(message);
+            spawnNotification(['osascript', '-e', `display notification "${safeMessage}" with title "${safeTitle}"`]);
         }
     }
 }

package/dist/platform/utils/open-external.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"open-external.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/open-external.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAiBrF,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAenE"}
+{"version":3,"file":"open-external.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/open-external.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAwErF,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAenE"}

package/dist/platform/utils/open-external.js

@@ -1,30 +1,82 @@
 /** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
 import { spawn } from 'node:child_process';
-function spawnDetached(command, args) {
-    try {
-        const child = spawn(command, args, {
-            stdio: 'ignore',
-            detached: true,
+import { summarizeError } from './error-display.js';
+import { logger } from './logger.js';
+const OPEN_EXTERNAL_TIMEOUT_MS = 5000;
+function trimOutput(value) {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed.slice(0, 500) : undefined;
+}
+function spawnLauncher(command, args) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let child;
+        try {
+            child = spawn(command, args, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            logger.warn('External URL launcher failed', {
+                command,
+                argCount: args.length,
+                error: summarizeError(error),
+            });
+            resolve(false);
+            return;
+        }
+        const finish = (ok, detail) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (!ok) {
+                logger.warn('External URL launcher failed', {
+                    command,
+                    argCount: args.length,
+                    stdout: trimOutput(stdout),
+                    stderr: trimOutput(stderr),
+                    ...detail,
+                });
+            }
+            resolve(ok);
+        };
+        const timeout = setTimeout(() => {
+            child.kill();
+            finish(false, { error: `timed out after ${OPEN_EXTERNAL_TIMEOUT_MS}ms` });
+        }, OPEN_EXTERNAL_TIMEOUT_MS);
+        timeout.unref?.();
+        child.stdout?.on('data', (chunk) => {
+            if (stdout.length < 4096)
+                stdout += chunk.toString();
         });
-        child.unref();
-        return true;
-    }
-    catch {
-        return false;
-    }
+        child.stderr?.on('data', (chunk) => {
+            if (stderr.length < 4096)
+                stderr += chunk.toString();
+        });
+        child.once('error', (error) => {
+            finish(false, { error: summarizeError(error) });
+        });
+        child.once('close', (code, signal) => {
+            finish(code === 0, { exitCode: code, signal });
+        });
+    });
 }
 export async function openExternalUrl(url) {
     if (process.platform === 'darwin') {
-        return spawnDetached('open', [url]);
+        return spawnLauncher('open', [url]);
     }
     if (process.platform === 'win32') {
-        return spawnDetached('cmd.exe', ['/c', 'start', '', url]);
+        return spawnLauncher('cmd.exe', ['/c', 'start', '', url]);
     }
     if (process.env['WSL_DISTRO_NAME']) {
-        if (spawnDetached('wslview', [url]))
+        if (await spawnLauncher('wslview', [url]))
             return true;
-        if (spawnDetached('cmd.exe', ['/c', 'start', '', url]))
+        if (await spawnLauncher('cmd.exe', ['/c', 'start', '', url]))
             return true;
     }
-    return spawnDetached('xdg-open', [url]);
+    return spawnLauncher('xdg-open', [url]);
 }

package/dist/platform/utils/prompt-loader.d.ts

@@ -1,6 +1,7 @@
 /**
  * Read a prompt file, resolving `@path/to/file` includes recursively.
- * Circular includes and missing files are silently skipped.
+ * Missing files, unreadable files, circular includes, and depth-limited
+ * includes are skipped and logged.
  * Max include depth: 5 (depths 0-4 inclusive; depth >= 5 returns '').
  *
  * The `visited` Set is intentionally shared across all recursive calls
@@ -18,8 +19,8 @@ export declare function readPromptFile(filePath: string, visited?: Set<string>,
 export interface LoadSystemPromptOptions {
     readonly workingDirectory: string;
     readonly homeDirectory: string;
-    readonly getConfigPath?: () => string | undefined;
-    readonly argv?: readonly string[];
+    readonly getConfigPath?: (() => string | undefined) | undefined;
+    readonly argv?: readonly string[] | undefined;
 }
 export declare function loadSystemPrompt(options: LoadSystemPromptOptions): string;
 //# sourceMappingURL=prompt-loader.d.ts.map

package/dist/platform/utils/prompt-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-loader.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/prompt-loader.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EACrB,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAqDR;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,GAC/B,MAAM,CAiCR"}
+{"version":3,"file":"prompt-loader.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/prompt-loader.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EACrB,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CA+DR;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC/C;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,GAC/B,MAAM,CAiCR"}

package/dist/platform/utils/prompt-loader.js

@@ -4,7 +4,8 @@ import { logger } from './logger.js';
 import { summarizeError } from './error-display.js';
 /**
  * Read a prompt file, resolving `@path/to/file` includes recursively.
- * Circular includes and missing files are silently skipped.
+ * Missing files, unreadable files, circular includes, and depth-limited
+ * includes are skipped and logged.
  * Max include depth: 5 (depths 0-4 inclusive; depth >= 5 returns '').
  *
  * The `visited` Set is intentionally shared across all recursive calls
@@ -16,12 +17,20 @@ export function readPromptFile(filePath, visited, depth) {
     const maxDepth = 5;
     const currentDepth = depth ?? 0;
     const seen = visited ?? new Set();
+    const resolved = resolve(filePath);
     // Fix #3: >= maxDepth so depths 0-4 are valid (5 levels of nesting)
-    if (currentDepth >= maxDepth)
+    if (currentDepth >= maxDepth) {
+        logger.debug('System prompt include skipped because max depth was reached', {
+            path: resolved,
+            depth: currentDepth,
+            maxDepth,
+        });
         return '';
-    const resolved = resolve(filePath);
-    if (seen.has(resolved))
-        return ''; // circular include guard
+    }
+    if (seen.has(resolved)) {
+        logger.debug('System prompt include skipped because it was already visited', { path: resolved });
+        return '';
+    }
     seen.add(resolved);
     let content;
     try {

package/dist/platform/utils/request-body.js

@@ -1,6 +1,6 @@
 export const DEFAULT_MAX_REQUEST_BODY_BYTES = 1_000_000;
 function ignoreCancelError() {
-    // Best-effort stream cancellation.
+    // Stream cancellation failure is intentionally non-blocking.
 }
 export async function readTextBodyWithinLimit(req, maxBytes = DEFAULT_MAX_REQUEST_BODY_BYTES) {
     const contentLength = Number.parseInt(req.headers.get('content-length') ?? '0', 10);

package/dist/platform/utils/retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/retry.ts"],"names":[],"mappings":"AAGA,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAOzE;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAaxD;AASD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EAC7B,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GACjE,OAAO,CAAC,CAAC,CAAC,CA4BZ"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/retry.ts"],"names":[],"mappings":"AAIA,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAOzE;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAaxD;AASD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EAC7B,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GACjE,OAAO,CAAC,CAAC,CAAC,CA4BZ"}

package/dist/platform/utils/retry.js

@@ -1,3 +1,4 @@
+import { randomInt } from 'node:crypto';
 import { AppError, RETRYABLE_STATUS_CODES } from '../types/errors.js';
 import { summarizeError } from './error-display.js';
 const DEFAULT_CONFIG = {
@@ -41,7 +42,7 @@ export function isRetryableError(error) {
 function computeDelay(attempt, initialDelayMs, maxDelayMs) {
     // Exponential backoff: initialDelay * 2^attempt, with jitter
     const exponential = initialDelayMs * Math.pow(2, attempt);
-    const jitter = Math.random() * initialDelayMs;
+    const jitter = randomInt(0, Math.max(1, Math.floor(initialDelayMs) + 1));
     return Math.min(exponential + jitter, maxDelayMs);
 }
 /**

package/dist/platform/utils/ring-buffer.d.ts

@@ -1,12 +1,16 @@
 /**
  * Generic fixed-capacity ring buffer (circular buffer).
  *
- * All writes are O(1). When the buffer is full the oldest entry is silently
- * evicted (FIFO). Reading all entries is O(n) where n ≤ capacity.
+ * All writes are O(1). When the buffer is full the oldest entry is evicted
+ * (FIFO); eviction is observable through `evictedCount` and the optional
+ * `onEvict` callback. Reading all entries is O(n) where n ≤ capacity.
  *
  * This is the canonical ring-buffer utility for the SDK. Prefer this over
  * ad-hoc implementations when bounded-memory queues are needed.
  */
+export interface RingBufferOptions<T> {
+    readonly onEvict?: ((item: T) => void) | undefined;
+}
 /**
  * A generic ring buffer with a fixed capacity.
  *
@@ -15,18 +19,23 @@
  */
 export declare class RingBuffer<T> {
     private readonly _buf;
+    private readonly _onEvict;
     private _head;
     private _count;
+    private _evictedCount;
     readonly capacity: number;
-    constructor(capacity: number);
+    constructor(capacity: number, options?: RingBufferOptions<T>);
     /** Number of entries currently stored (≤ capacity). */
     get size(): number;
     /** True when the buffer holds at least one entry. */
     get isEmpty(): boolean;
+    /** Number of entries evicted since construction or the last `clear()`. */
+    get evictedCount(): number;
     /**
      * Push an entry into the buffer.
      *
-     * If the buffer is full the oldest entry is evicted to make room.
+     * If the buffer is full the oldest entry is evicted to make room and
+     * `evictedCount` is incremented.
      * Always O(1).
      */
     push(item: T): void;

package/dist/platform/utils/ring-buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/ring-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,MAAM,CAAK;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;IAM5B,uDAAuD;IACvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,qDAAqD;IACrD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAMnB;;;;OAIG;IACH,OAAO,IAAI,CAAC,EAAE;IAUd;;;;OAIG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE;IAMxB;;;;OAIG;IACH,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE;IAYhC,0EAA0E;IAC1E,KAAK,IAAI,IAAI;CAKd"}
+{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["../../../src/platform/utils/ring-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACpD;AAED;;;;;GAKG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,aAAa,CAAK;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAiB,CAAC,CAAC,CAAM;IAOhE,uDAAuD;IACvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,qDAAqD;IACrD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,0EAA0E;IAC1E,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAWnB;;;;OAIG;IACH,OAAO,IAAI,CAAC,EAAE;IAUd;;;;OAIG;IACH,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE;IAMxB;;;;OAIG;IACH,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE;IAYhC,0EAA0E;IAC1E,KAAK,IAAI,IAAI;CAMd"}