@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/ops/playbooks/compaction-failure.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Playbook: Compaction Failure
+ *
+ * Diagnoses and resolves conversation compaction failures that block
+ * new turns from starting.
+ */
+import type { Playbook } from '../types.js';
+/** Compaction failure resolution playbook. */
+export declare const compactionFailurePlaybook: Playbook;
+//# sourceMappingURL=compaction-failure.d.ts.map

package/dist/_internal/platform/runtime/ops/playbooks/compaction-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction-failure.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/ops/playbooks/compaction-failure.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,aAAa,CAAC;AAGnE,8CAA8C;AAC9C,eAAO,MAAM,yBAAyB,EAAE,QAgHvC,CAAC"}

package/dist/_internal/platform/runtime/ops/playbooks/compaction-failure.js

@@ -0,0 +1,106 @@
+import { safeCheck } from '../safe-check.js';
+/** Compaction failure resolution playbook. */
+export const compactionFailurePlaybook = {
+    id: 'compaction-failure',
+    name: 'Compaction Failure',
+    description: 'Diagnoses and resolves conversation compaction failures. ' +
+        'When compaction fails, new turns are blocked until the issue is resolved.',
+    symptoms: [
+        'Compaction health check reports FAILED',
+        'New turn submissions rejected with BLOCK_NEW cascade',
+        'CompactionStateMachine stuck in error state',
+        'Context window approaching limit with no successful compaction',
+        'Compaction span shows repeated ERROR status',
+    ],
+    checks: [
+        {
+            id: 'compaction.strategy-available',
+            label: 'Compaction strategy available',
+            description: 'Checks whether a compaction strategy is configured and operative.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Compaction strategy availability requires live CompactionManager context.',
+                severity: 'error',
+                context: { hint: 'Inspect CompactionManager.currentStrategy — confirm it is not null' },
+            })),
+        },
+        {
+            id: 'compaction.token-budget',
+            label: 'Token budget within limit',
+            description: 'Checks whether the current context window token count is within the compaction trigger threshold.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Token budget check requires live ContextWindowManager context.',
+                severity: 'warning',
+                context: { hint: 'Compare ContextWindowManager.currentTokens with config.compactionTriggerTokens' },
+            })),
+        },
+        {
+            id: 'compaction.state-machine',
+            label: 'Compaction state machine in error state',
+            description: 'Confirms the CompactionStateMachine is in an error state, not idle or running.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'State machine inspection requires live CompactionStateMachine context.',
+                severity: 'error',
+                context: { hint: 'Call CompactionStateMachine.getState() — expect "error" or "failed"' },
+            })),
+        },
+    ],
+    steps: [
+        {
+            step: 1,
+            title: 'Inspect compaction error telemetry',
+            action: 'Review compaction.* spans in the local ledger for ERROR status. ' +
+                'Note the error message, strategy, and token count at time of failure.',
+            kind: 'observe',
+            expectedOutcome: 'Root cause identified from span error messages.',
+            automatable: false,
+        },
+        {
+            step: 2,
+            title: 'Reset the compaction state machine',
+            action: 'Call runtime.compaction.reset() to transition the state machine back to idle. ' +
+                'This unblocks new turns without re-attempting the failed compaction.',
+            kind: 'command',
+            command: 'runtime.compaction.reset()',
+            expectedOutcome: 'CompactionStateMachine returns to idle; new turns unblocked.',
+            automatable: true,
+        },
+        {
+            step: 3,
+            title: 'Switch to a fallback compaction strategy',
+            action: 'If the default strategy continues to fail, switch to a simpler fallback ' +
+                '(e.g. truncation or summarization) to restore turn availability.',
+            kind: 'config',
+            command: 'runtime.compaction.setStrategy("truncate")',
+            expectedOutcome: 'Compaction succeeds with fallback strategy; turns resume.',
+            automatable: false,
+        },
+        {
+            step: 4,
+            title: 'Manually compact the conversation',
+            action: 'Trigger a manual compaction run with verbose logging to isolate the failure point.',
+            kind: 'command',
+            command: 'runtime.compaction.runNow({ verbose: true })',
+            expectedOutcome: 'Compaction completes or fails with a detailed error message.',
+            automatable: false,
+        },
+        {
+            step: 5,
+            title: 'Review context window limits',
+            action: 'Verify that the configured context window limit matches the active model capabilities. ' +
+                'Reduce the turn token budget if needed to prevent repeated overflow.',
+            kind: 'config',
+            expectedOutcome: 'Token budget aligned with model; compaction triggering correctly.',
+            automatable: false,
+        },
+    ],
+    escalationCriteria: [
+        'Compaction fails consistently across all available strategies',
+        'Context window overflow preventing any new model calls',
+        'CompactionStateMachine crash-loops on reset',
+        'Token budget configuration is corrupt or missing',
+    ],
+    tags: ['compaction', 'context-window', 'token-budget', 'turn-blocking'],
+};

package/dist/_internal/platform/runtime/ops/playbooks/export-recovery.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Playbook: Export Recovery
+ *
+ * Diagnoses and resolves telemetry / OTLP export pipeline failures.
+ * Covers queue overflow, endpoint unreachability, and exporter misconfiguration.
+ */
+import type { Playbook } from '../types.js';
+/** Telemetry export recovery playbook. */
+export declare const exportRecoveryPlaybook: Playbook;
+//# sourceMappingURL=export-recovery.d.ts.map

package/dist/_internal/platform/runtime/ops/playbooks/export-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-recovery.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/ops/playbooks/export-recovery.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,aAAa,CAAC;AAGnE,0CAA0C;AAC1C,eAAO,MAAM,sBAAsB,EAAE,QAoHpC,CAAC"}

package/dist/_internal/platform/runtime/ops/playbooks/export-recovery.js

@@ -0,0 +1,110 @@
+import { safeCheck } from '../safe-check.js';
+/** Telemetry export recovery playbook. */
+export const exportRecoveryPlaybook = {
+    id: 'export-recovery',
+    name: 'Export Recovery',
+    description: 'Diagnoses and resolves telemetry / OTLP export pipeline failures. ' +
+        'The runtime continues operating during export failures — this playbook ' +
+        'focuses on restoring span delivery without interrupting agent work.',
+    symptoms: [
+        'Console logs show "[ExportQueue] Export failed" or "[OtlpExporter] Export failed permanently"',
+        'Console warnings show "[ExportQueue] Queue overflow"',
+        'Local ledger file is not growing despite active spans',
+        'OTLP endpoint returning non-2xx responses',
+        'Diagnostics panel shows exporter health as DEGRADED',
+    ],
+    checks: [
+        {
+            id: 'export.otlp-endpoint-reachable',
+            label: 'OTLP endpoint reachable',
+            description: 'Checks whether the configured OTLP endpoint responds to HTTP.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'OTLP endpoint reachability requires live network context.',
+                severity: 'warning',
+                context: { hint: 'curl -sf -X POST <otlpEndpoint> -d "{}" -H "Content-Type: application/json"' },
+            })),
+        },
+        {
+            id: 'export.queue-overflow',
+            label: 'Export queue not overflowing',
+            description: 'Checks whether the ExportQueue is within its configured size limit.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Queue size requires live ExportQueue reference.',
+                severity: 'warning',
+                context: { hint: 'Inspect exportQueue.size vs exportQueue config.maxSize' },
+            })),
+        },
+        {
+            id: 'export.ledger-writable',
+            label: 'Local ledger file writable',
+            description: 'Checks whether the local ledger file path is writable.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Ledger writeability requires live filesystem access.',
+                severity: 'warning',
+                context: { hint: 'Run: touch <ledgerFilePath> to test writability' },
+            })),
+        },
+    ],
+    steps: [
+        {
+            step: 1,
+            title: 'Check OTLP endpoint connectivity',
+            action: 'Verify the configured OTLP endpoint is reachable. ' +
+                'A minimal POST should return HTTP 200 or 204.',
+            kind: 'observe',
+            command: 'curl -sf -X POST <otlpEndpoint>/v1/traces -H "Content-Type: application/json" -d \'{"resourceSpans":[]}\' ',
+            expectedOutcome: 'HTTP 200 or 204 response.',
+            automatable: true,
+        },
+        {
+            step: 2,
+            title: 'Verify local ledger path',
+            action: 'Confirm the local ledger file path exists and is writable. ' +
+                'Check disk space if the file exists but is not growing.',
+            kind: 'observe',
+            command: 'ls -lh <ledgerFilePath> && df -h <ledgerDirectory>',
+            expectedOutcome: 'File exists and is writable; adequate disk space.',
+            automatable: true,
+        },
+        {
+            step: 3,
+            title: 'Increase export queue size',
+            action: 'If spans are being dropped due to queue overflow, increase the queue ' +
+                'maxSize in the OtlpExporter configuration and restart the exporter.',
+            kind: 'config',
+            command: 'new OtlpExporter({ ..., queue: { maxSize: 512 } })',
+            expectedOutcome: 'Queue overflow warnings cease; no more span drops.',
+            automatable: false,
+        },
+        {
+            step: 4,
+            title: 'Switch to console exporter temporarily',
+            action: 'Replace the failing OTLP exporter with a ConsoleExporter to preserve ' +
+                'span visibility while the pipeline is being restored.',
+            kind: 'config',
+            command: 'tracer.config.exporters = [new ConsoleExporter({ verbosity: "compact" })]',
+            expectedOutcome: 'Spans visible in console output; no data lost.',
+            automatable: false,
+        },
+        {
+            step: 5,
+            title: 'Restore OTLP exporter',
+            action: 'After fixing the endpoint or configuration, re-add the OtlpExporter. ' +
+                'Verify the first batch of spans is acknowledged by the OTLP receiver.',
+            kind: 'config',
+            command: 'tracer.config.exporters.push(new OtlpExporter({ endpoint: "<fixed-endpoint>" }))',
+            expectedOutcome: 'Export result callback reports code: "success".',
+            automatable: false,
+        },
+    ],
+    escalationCriteria: [
+        'OTLP endpoint unreachable for > 30 minutes with spans being dropped',
+        'Local ledger disk full and no alternative export target available',
+        'Export failures causing memory pressure (queue too large for available RAM)',
+        'All configured exporters failing simultaneously',
+    ],
+    tags: ['telemetry', 'otlp', 'export', 'queue', 'ledger', 'exporter'],
+};

package/dist/_internal/platform/runtime/ops/playbooks/permission-deadlock.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Playbook: Permission Deadlock
+ *
+ * Diagnoses and resolves situations where permission requests are blocking
+ * forward progress — typically from circular approval chains, missing
+ * policy rules, or a stalled host permission prompt.
+ */
+import type { Playbook } from '../types.js';
+/** Permission deadlock resolution playbook. */
+export declare const permissionDeadlockPlaybook: Playbook;
+//# sourceMappingURL=permission-deadlock.d.ts.map

package/dist/_internal/platform/runtime/ops/playbooks/permission-deadlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-deadlock.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/ops/playbooks/permission-deadlock.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,aAAa,CAAC;AAGnE,+CAA+C;AAC/C,eAAO,MAAM,0BAA0B,EAAE,QAkHxC,CAAC"}

package/dist/_internal/platform/runtime/ops/playbooks/permission-deadlock.js

@@ -0,0 +1,108 @@
+import { safeCheck } from '../safe-check.js';
+/** Permission deadlock resolution playbook. */
+export const permissionDeadlockPlaybook = {
+    id: 'permission-deadlock',
+    name: 'Permission Deadlock',
+    description: 'Diagnoses and resolves permission deadlocks where tool execution is ' +
+        'blocked waiting for approvals that never arrive or form a cycle.',
+    symptoms: [
+        'Tool calls stuck in AWAITING_PERMISSION state for > 30 s',
+        'Host permission prompt displayed but not responding to input',
+        'Turn throughput drops to zero with CPU near 0%',
+        'Permission span shows no RESOLVED event',
+        'Multiple tools queued behind a single blocked permission request',
+    ],
+    checks: [
+        {
+            id: 'permission.pending-requests',
+            label: 'Pending permission requests',
+            description: 'Checks how many permission requests are currently awaiting approval.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Pending request count requires live PermissionManager context.',
+                severity: 'warning',
+                context: { hint: 'Inspect PermissionManager.pendingRequests()' },
+            })),
+        },
+        {
+            id: 'permission.policy-match',
+            label: 'Policy rule matched',
+            description: 'Checks whether the blocked permission request matches any configured allow/deny rule.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Policy matching requires live policy engine context.',
+                severity: 'warning',
+                context: { hint: 'Run PermissionPolicyEngine.evaluate(request) to test match' },
+            })),
+        },
+        {
+            id: 'permission.ui-responsive',
+            label: 'Permission UI responsive',
+            description: 'Checks whether the host permission prompt is rendered and responding to input.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'UI responsiveness requires live render context.',
+                severity: 'warning',
+                context: { hint: 'Check Ink render tree for active PermissionPrompt component' },
+            })),
+        },
+    ],
+    steps: [
+        {
+            step: 1,
+            title: 'List pending permission requests',
+            action: 'Enumerate all requests currently in the AWAITING_PERMISSION state. ' +
+                'Note the tool name, requested capability, and how long it has been pending.',
+            kind: 'observe',
+            command: 'runtime.permissions.listPending()',
+            expectedOutcome: 'List of pending requests with ages.',
+            automatable: true,
+        },
+        {
+            step: 2,
+            title: 'Check policy coverage',
+            action: 'Evaluate each pending request against the configured policy rules. ' +
+                'Identify requests with no matching rule (falling through to manual approval).',
+            kind: 'observe',
+            command: 'runtime.permissions.evaluatePolicy(requestId)',
+            expectedOutcome: 'Each request either has a matching rule or is identified as uncovered.',
+            automatable: true,
+        },
+        {
+            step: 3,
+            title: 'Add a temporary allow rule',
+            action: 'Add a scoped allow rule for the blocked capability to unblock forward progress. ' +
+                'Log the rule addition for audit review.',
+            kind: 'config',
+            command: 'runtime.permissions.addRule({ effect: "allow", tool: "<tool>", capability: "<cap>" })',
+            expectedOutcome: 'Pending request auto-approved; tool execution resumes.',
+            automatable: false,
+        },
+        {
+            step: 4,
+            title: 'Deny and skip blocked tool',
+            action: 'If adding an allow rule is not appropriate, deny the pending request and ' +
+                'allow the turn to continue without the blocked tool.',
+            kind: 'command',
+            command: 'runtime.permissions.deny(requestId, { reason: "ops-override" })',
+            expectedOutcome: 'Tool call skipped; turn resumes with remaining tools.',
+            automatable: true,
+        },
+        {
+            step: 5,
+            title: 'Review and update policy ruleset',
+            action: 'Audit the permission policy configuration to add appropriate rules ' +
+                'that prevent this deadlock from recurring.',
+            kind: 'config',
+            expectedOutcome: 'Policy updated; future similar requests handled automatically.',
+            automatable: false,
+        },
+    ],
+    escalationCriteria: [
+        'Permission UI is rendering but unresponsive to keyboard input (Ink render stall)',
+        'Adding allow rules does not unblock the pending request',
+        'Multiple concurrent permission deadlocks across different turns',
+        'Policy engine itself is throwing on evaluation',
+    ],
+    tags: ['permission', 'deadlock', 'tools', 'policy', 'approval'],
+};

package/dist/_internal/platform/runtime/ops/playbooks/plugin-degradation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Playbook: Plugin Degradation
+ *
+ * Diagnoses and resolves scenarios where a plugin is operating in a
+ * degraded state — returning errors, crashing, or producing incorrect output.
+ */
+import type { Playbook } from '../types.js';
+/** Plugin degradation resolution playbook. */
+export declare const pluginDegradationPlaybook: Playbook;
+//# sourceMappingURL=plugin-degradation.d.ts.map

package/dist/_internal/platform/runtime/ops/playbooks/plugin-degradation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-degradation.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/ops/playbooks/plugin-degradation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,aAAa,CAAC;AAGnE,8CAA8C;AAC9C,eAAO,MAAM,yBAAyB,EAAE,QAiHvC,CAAC"}

package/dist/_internal/platform/runtime/ops/playbooks/plugin-degradation.js

@@ -0,0 +1,107 @@
+import { safeCheck } from '../safe-check.js';
+/** Plugin degradation resolution playbook. */
+export const pluginDegradationPlaybook = {
+    id: 'plugin-degradation',
+    name: 'Plugin Degradation',
+    description: 'Diagnoses and resolves plugins operating in a degraded state. ' +
+        'Covers plugin crashes, capability failures, and incompatible plugin versions.',
+    symptoms: [
+        'Plugin health check returns DEGRADED or ERROR',
+        'Tool calls routed to the plugin consistently failing',
+        'Plugin span shows repeated ERROR events with short durations',
+        'Plugin capability telemetry shows 0 successful invocations',
+        'MCP server for the plugin is unresponsive',
+    ],
+    checks: [
+        {
+            id: 'plugin.health-status',
+            label: 'Plugin health status',
+            description: 'Checks the current health status reported by the plugin.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Plugin health status requires live PluginManager context.',
+                severity: 'warning',
+                context: { hint: 'Inspect PluginManager.getHealth(pluginId)' },
+            })),
+        },
+        {
+            id: 'plugin.capability-available',
+            label: 'Required capability available',
+            description: 'Checks whether the plugin exposes the expected capability/tool.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Capability availability requires live plugin registry context.',
+                severity: 'warning',
+                context: { hint: 'Run PluginRegistry.listCapabilities(pluginId)' },
+            })),
+        },
+        {
+            id: 'plugin.version-compat',
+            label: 'Plugin version compatible',
+            description: 'Checks whether the plugin version is compatible with the current runtime version.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Version compatibility requires live plugin manifest context.',
+                severity: 'warning',
+                context: { hint: 'Compare plugin.manifest.runtimeVersion with runtime.version' },
+            })),
+        },
+    ],
+    steps: [
+        {
+            step: 1,
+            title: 'Inspect plugin error telemetry',
+            action: 'Review the local ledger for plugin.* spans with ERROR status. ' +
+                'Note the error message, plugin ID, and capability being invoked.',
+            kind: 'observe',
+            expectedOutcome: 'Root cause identified from span error messages.',
+            automatable: false,
+        },
+        {
+            step: 2,
+            title: 'Restart the plugin',
+            action: 'Trigger a graceful plugin restart via the PluginManager. ' +
+                'This resets the plugin process and re-establishes MCP connection.',
+            kind: 'command',
+            command: 'runtime.plugins.restart(pluginId)',
+            expectedOutcome: 'Plugin lifecycle spans show INIT → READY sequence.',
+            automatable: true,
+        },
+        {
+            step: 3,
+            title: 'Disable degraded plugin',
+            action: 'If the restart does not recover the plugin, disable it to prevent ' +
+                'further tool-call failures. Other plugins and turns can continue.',
+            kind: 'command',
+            command: 'runtime.plugins.disable(pluginId)',
+            expectedOutcome: 'Plugin disabled; tool calls routed away or failing fast.',
+            automatable: true,
+        },
+        {
+            step: 4,
+            title: 'Check plugin version compatibility',
+            action: 'Verify that the installed plugin version is compatible with the current runtime. ' +
+                'Update or downgrade the plugin if needed.',
+            kind: 'observe',
+            expectedOutcome: 'Compatible version identified and installed.',
+            automatable: false,
+        },
+        {
+            step: 5,
+            title: 'Re-enable plugin after fix',
+            action: 'After resolving the root cause, re-enable the plugin and verify ' +
+                'capability invocations succeed.',
+            kind: 'command',
+            command: 'runtime.plugins.enable(pluginId)',
+            expectedOutcome: 'Plugin health returns to HEALTHY; tool calls succeed.',
+            automatable: false,
+        },
+    ],
+    escalationCriteria: [
+        'Plugin crashes immediately after restart (< 5 s uptime)',
+        'All available plugin versions are incompatible with the runtime',
+        'Plugin degradation causes cascading failures in dependent plugins',
+        'MCP server for the plugin cannot be started (port conflict, missing binary)',
+    ],
+    tags: ['plugin', 'mcp', 'capability', 'crash', 'degradation'],
+};

package/dist/_internal/platform/runtime/ops/playbooks/reconnect-failure.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Playbook: Reconnect Failure
+ *
+ * Diagnoses and resolves persistent transport/connection failures.
+ * Covers MCP server disconnects, WebSocket drops, and HTTP transport errors.
+ */
+import type { Playbook } from '../types.js';
+/** Reconnect failure resolution playbook. */
+export declare const reconnectFailurePlaybook: Playbook;
+//# sourceMappingURL=reconnect-failure.d.ts.map

package/dist/_internal/platform/runtime/ops/playbooks/reconnect-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect-failure.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/ops/playbooks/reconnect-failure.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,aAAa,CAAC;AAGnE,6CAA6C;AAC7C,eAAO,MAAM,wBAAwB,EAAE,QAoHtC,CAAC"}

package/dist/_internal/platform/runtime/ops/playbooks/reconnect-failure.js

@@ -0,0 +1,109 @@
+import { safeCheck } from '../safe-check.js';
+/** Reconnect failure resolution playbook. */
+export const reconnectFailurePlaybook = {
+    id: 'reconnect-failure',
+    name: 'Reconnect Failure',
+    description: 'Diagnoses persistent transport or connection failures. ' +
+        'Covers MCP server disconnects, WebSocket drops, and HTTP transport errors.',
+    symptoms: [
+        'Transport span shows repeated CONNECT → DISCONNECT cycles',
+        'MCP server reports connection refused or timeout',
+        'RuntimeEventBus emitting transport.error at high frequency',
+        'Tool calls failing with "connection not available" errors',
+        'Health check reports transport as DEGRADED or CRITICAL',
+    ],
+    checks: [
+        {
+            id: 'transport.endpoint-reachable',
+            label: 'Endpoint reachable',
+            description: 'Checks whether the transport endpoint responds to a health ping.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Endpoint reachability requires a live network context. ' +
+                    'Use the transport.ping() diagnostic API or check connectivity manually.',
+                severity: 'warning',
+                context: { hint: 'Run: curl -sf <endpoint>/health' },
+            })),
+        },
+        {
+            id: 'transport.retry-budget',
+            label: 'Retry budget remaining',
+            description: 'Checks whether the transport retry budget has been exhausted.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Retry budget state requires live transport context.',
+                severity: 'warning',
+                context: { hint: 'Inspect TransportManager.retryState()' },
+            })),
+        },
+        {
+            id: 'transport.auth-valid',
+            label: 'Authentication credentials valid',
+            description: 'Checks whether transport credentials (API keys, tokens) are valid and not expired.',
+            run: async () => safeCheck(async () => ({
+                passed: false,
+                summary: 'Credential validation requires live auth context.',
+                severity: 'warning',
+                context: { hint: 'Check token expiry in AuthManager.status()' },
+            })),
+        },
+    ],
+    steps: [
+        {
+            step: 1,
+            title: 'Verify endpoint reachability',
+            action: 'Ping the transport endpoint outside the runtime to confirm basic network connectivity. ' +
+                'Check DNS resolution and TLS certificate validity.',
+            kind: 'observe',
+            command: 'curl -sf --max-time 5 <endpoint>/health',
+            expectedOutcome: 'HTTP 200 or endpoint-specific health response.',
+            automatable: true,
+        },
+        {
+            step: 2,
+            title: 'Check authentication credentials',
+            action: 'Verify API keys / bearer tokens are set, not expired, and have the required scopes. ' +
+                'Rotate credentials if expired.',
+            kind: 'observe',
+            command: 'runtime.auth.status()',
+            expectedOutcome: 'Credentials valid and not expiring within 5 minutes.',
+            automatable: false,
+        },
+        {
+            step: 3,
+            title: 'Inspect transport error telemetry',
+            action: 'Review the local ledger or console exporter for transport.* spans with ERROR status. ' +
+                'Note the error message and last successful connection timestamp.',
+            kind: 'observe',
+            expectedOutcome: 'Root cause identified (auth, network, server-side error).',
+            automatable: false,
+        },
+        {
+            step: 4,
+            title: 'Force reconnect',
+            action: 'Emit a transport.reconnect event to trigger an immediate reconnection attempt, ' +
+                'bypassing the backoff timer.',
+            kind: 'command',
+            command: 'eventBus.emit("transport.reconnect", { transportId })',
+            expectedOutcome: 'Connection re-established; transport spans show CONNECT success.',
+            automatable: true,
+        },
+        {
+            step: 5,
+            title: 'Switch to fallback transport',
+            action: 'If the primary transport remains unreachable after forced reconnect, ' +
+                'configure a fallback transport endpoint in TransportManager.',
+            kind: 'config',
+            command: 'runtime.transport.setFallback({ endpoint: "<fallback-url>" })',
+            expectedOutcome: 'Runtime connected via fallback; primary transport monitored in background.',
+            automatable: false,
+        },
+    ],
+    escalationCriteria: [
+        'All configured transports (primary + fallback) are unreachable',
+        'Reconnect attempts failing for > 10 minutes',
+        'Authentication service itself is reporting downtime',
+        'Network-level errors (TCP refused, DNS failure) on all endpoints',
+    ],
+    tags: ['transport', 'mcp', 'websocket', 'network', 'reconnect'],
+};

package/dist/_internal/platform/runtime/ops/safe-check.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared diagnostic check safety wrapper.
+ *
+ * Runs a diagnostic check function and catches any unexpected errors,
+ * returning a structured failure result instead of throwing.
+ */
+import type { DiagnosticCheckResult } from './types.js';
+/** @internal Run a check safely — never throws. */
+export declare function safeCheck(fn: () => Promise<DiagnosticCheckResult>): Promise<DiagnosticCheckResult>;
+//# sourceMappingURL=safe-check.d.ts.map

package/dist/_internal/platform/runtime/ops/safe-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-check.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/ops/safe-check.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD,mDAAmD;AACnD,wBAAsB,SAAS,CAC7B,EAAE,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,GACvC,OAAO,CAAC,qBAAqB,CAAC,CAUhC"}

package/dist/_internal/platform/runtime/ops/safe-check.js

@@ -0,0 +1,14 @@
+import { summarizeError } from '../../utils/error-display.js';
+/** @internal Run a check safely — never throws. */
+export async function safeCheck(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        return {
+            passed: false,
+            summary: `Check threw unexpectedly: ${summarizeError(err)}`,
+            severity: 'error',
+        };
+    }
+}