@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/types/errors.js

@@ -0,0 +1,237 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/** HTTP status codes that indicate transient failures eligible for retry. Single source of truth. */
+export const RETRYABLE_STATUS_CODES = [429, 500, 503];
+function inferErrorCategory(message, statusCode) {
+    const msg = message.toLowerCase();
+    if (statusCode === 401)
+        return 'authentication';
+    if (statusCode === 402)
+        return 'billing';
+    if (statusCode === 403)
+        return 'authorization';
+    if (statusCode === 404)
+        return 'not_found';
+    if (statusCode === 408)
+        return 'timeout';
+    if (statusCode === 429)
+        return 'rate_limit';
+    if (statusCode === 400)
+        return 'bad_request';
+    if (statusCode !== undefined && statusCode >= 500)
+        return 'service';
+    if (/api[_\s-]?key|auth|token|credential|jwt|unauthoriz/.test(msg))
+        return 'authentication';
+    if (/forbidden|access denied|not allowed|permission denied/.test(msg))
+        return 'authorization';
+    if (/payment required|billing|credit|credits|quota|insufficient balance|depleted/.test(msg))
+        return 'billing';
+    if (/rate.limit|too many requests|throttl/.test(msg))
+        return 'rate_limit';
+    if (/timed?[\s_-]?out|etimedout|timeout|deadline exceeded/.test(msg))
+        return 'timeout';
+    if (/econnrefused|enotfound|ehostunreach|econnreset|socket hang up|fetch failed|dns|tls|ssl|certificate/.test(msg))
+        return 'network';
+    if (/not found|unknown model|no such model|unknown endpoint|unsupported model/.test(msg))
+        return 'not_found';
+    if (/invalid request|bad request|invalid argument|malformed|schema|unsupported parameter/.test(msg))
+        return 'bad_request';
+    if (/invalid json|parse|no response body|stream ended|unexpected eof|malformed response/.test(msg))
+        return 'protocol';
+    return 'unknown';
+}
+function inferProviderGuidance(category, statusCode) {
+    switch (category) {
+        case 'rate_limit':
+            return 'The provider rate limited this request. GoodVibes will retry automatically when the caller supports retries. If this keeps happening, wait, reduce request volume, or switch models/providers.';
+        case 'authentication':
+            return 'The provider rejected authentication. Possible causes include invalid or expired credentials, missing account/session state, account restrictions, or the wrong provider/endpoint receiving the request.';
+        case 'authorization':
+            return 'The provider rejected the request after authentication. Possible causes include missing model access, account permissions, policy restrictions, or provider routing to a service that does not expose this model.';
+        case 'billing':
+            return 'The provider reported a billing or quota problem. Check credits, subscription status, usage limits, or account entitlements.';
+        case 'timeout':
+            return 'The request timed out before the provider finished responding. Check network stability, provider latency, and request size.';
+        case 'network':
+            return 'The request did not complete over the network. Check connectivity, DNS, TLS certificates, base URL, or any local proxy/tunnel.';
+        case 'bad_request':
+            return 'The provider rejected the request shape. Check model id, parameters, message format, and tool schema.';
+        case 'not_found':
+            return 'The requested model or endpoint was not found. Check model id, provider selection, and API path.';
+        case 'protocol':
+            return 'The provider response was incomplete or malformed. Check upstream compatibility, streaming mode, and transport stability.';
+        case 'service':
+            return statusCode === 503
+                ? 'The provider is temporarily unavailable. Retry shortly or switch providers if the issue persists.'
+                : 'The provider returned a server-side failure. Retry shortly or switch providers if the issue persists.';
+        default:
+            return undefined;
+    }
+}
+function inferRetryAfterMs(message, statusCode, explicitRetryAfterMs) {
+    if (explicitRetryAfterMs !== undefined)
+        return explicitRetryAfterMs;
+    if (statusCode !== 429)
+        return undefined;
+    const match = message.match(/retry[-_\s]?after[:=\s]+(\d+)/i);
+    if (!match)
+        return undefined;
+    return parseInt(match[1], 10) * 1000;
+}
+/** Base class for all application errors. Provides a machine-readable code and recoverability hint. */
+export class AppError extends Error {
+    code;
+    recoverable;
+    statusCode;
+    category;
+    guidance;
+    detail;
+    source;
+    provider;
+    operation;
+    phase;
+    requestId;
+    providerCode;
+    providerType;
+    retryAfterMs;
+    rawMessage;
+    constructor(message, code, recoverable, options = {}) {
+        super(message);
+        this.code = code;
+        this.recoverable = recoverable;
+        this.name = this.constructor.name;
+        this.statusCode = options.statusCode;
+        this.category = options.category;
+        this.guidance = options.guidance;
+        this.detail = options.detail;
+        this.source = options.source;
+        this.provider = options.provider;
+        this.operation = options.operation;
+        this.phase = options.phase;
+        this.requestId = options.requestId;
+        this.providerCode = options.providerCode;
+        this.providerType = options.providerType;
+        this.retryAfterMs = options.retryAfterMs;
+        this.rawMessage = options.rawMessage;
+    }
+}
+/** Thrown when configuration is invalid or cannot be loaded. Non-recoverable. */
+export class ConfigError extends AppError {
+    constructor(message) {
+        super(message, 'CONFIG_ERROR', false, {
+            category: 'config',
+            source: 'config',
+        });
+    }
+}
+/** Thrown when an LLM provider API call fails. Recoverable when statusCode is in RETRYABLE_STATUS_CODES. */
+export class ProviderError extends AppError {
+    constructor(message, statusCodeOrOptions, maybeOptions = {}) {
+        const options = typeof statusCodeOrOptions === 'number'
+            ? { ...maybeOptions, statusCode: statusCodeOrOptions }
+            : (statusCodeOrOptions ?? {});
+        const statusCode = options.statusCode;
+        const category = options.category ?? inferErrorCategory(message, statusCode);
+        const retryAfterMs = inferRetryAfterMs(message, statusCode, options.retryAfterMs);
+        const guidance = options.guidance ?? inferProviderGuidance(category, statusCode);
+        super(message, 'PROVIDER_ERROR', statusCode !== undefined && RETRYABLE_STATUS_CODES.includes(statusCode), {
+            ...options,
+            statusCode,
+            category,
+            guidance,
+            retryAfterMs,
+            source: options.source ?? 'provider',
+            rawMessage: options.rawMessage ?? message,
+        });
+    }
+}
+/** Thrown when a tool execution fails. Recoverable by default. */
+export class ToolError extends AppError {
+    toolName;
+    constructor(message, toolName) {
+        super(message, 'TOOL_ERROR', true, {
+            category: 'tool',
+            source: 'tool',
+        });
+        this.toolName = toolName;
+    }
+}
+/** Thrown for ACP (Agent Control Protocol) errors. Recoverable by default. */
+export class AcpError extends AppError {
+    constructor(message) {
+        super(message, 'ACP_ERROR', true, {
+            source: 'acp',
+        });
+    }
+}
+/** Thrown when an operation is denied due to insufficient permissions. Non-recoverable. */
+export class PermissionError extends AppError {
+    constructor(message) {
+        super(message, 'PERMISSION_DENIED', false, {
+            category: 'permission',
+            source: 'permission',
+        });
+    }
+}
+/** Thrown when the renderer encounters a failure. Recoverable by default. */
+export class RenderError extends AppError {
+    constructor(message) {
+        super(message, 'RENDER_ERROR', true, {
+            source: 'render',
+        });
+    }
+}
+/**
+ * Returns true when the error indicates a rate limit or quota exhaustion.
+ * Used by SyntheticProvider and AgentOrchestrator to decide whether to
+ * back-off and retry vs. escalate the error.
+ */
+export function isRateLimitOrQuotaError(err) {
+    if (err instanceof ProviderError) {
+        if (err.statusCode === 429 || err.statusCode === 402)
+            return true;
+        const msg = err.message.toLowerCase();
+        return /rate.limit|too many requests|quota exceeded|throttl|depleted|credits/.test(msg);
+    }
+    if (err instanceof Error) {
+        const msg = err.message.toLowerCase();
+        return msg.includes('429') || msg.includes('402') || /rate.limit|too many requests|quota exceeded|depleted|credits/.test(msg);
+    }
+    return false;
+}
+/**
+ * Returns true when the error indicates the model's context window was exceeded.
+ * Covers OpenAI, Anthropic, and generic provider error messages.
+ */
+export function isContextSizeExceededError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const msg = err.message.toLowerCase();
+    return (msg.includes('context_length_exceeded') ||
+        msg.includes('context length exceeded') ||
+        msg.includes('context size exceeded') ||
+        msg.includes('context window exceeded') ||
+        msg.includes('maximum context length') ||
+        msg.includes('prompt is too long') ||
+        msg.includes('input too long') ||
+        msg.includes('tokens exceed') ||
+        msg.includes('exceeds the model') ||
+        (msg.includes('context') && msg.includes('exceed')));
+}
+/**
+ * Returns true when the error indicates the provider is non-transient
+ * (auth failures, connection refused, host not found, timeout).
+ * 500/503 are deliberately excluded — server errors are transient and
+ * eligible for retry. Only permanent auth/billing failures are flagged here.
+ * Used to trigger graceful degradation / alternative model suggestions.
+ */
+export function isNonTransientProviderFailure(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err instanceof ProviderError) {
+        const NON_TRANSIENT_CODES = new Set([401, 402, 403]);
+        if (err.statusCode !== undefined && NON_TRANSIENT_CODES.has(err.statusCode))
+            return true;
+    }
+    const msg = err.message.toLowerCase();
+    return msg.includes('econnrefused') || msg.includes('enotfound') || msg.includes('timeout') || msg.includes('fetch failed');
+}

package/dist/_internal/platform/types/foundation-contract.d.ts

@@ -0,0 +1,9 @@
+export type { ContractHttpDefinition, JsonSchema, OperatorContractManifest, OperatorEventContract, OperatorEventCoverageContract, OperatorMethodContract, OperatorSchemaCoverageContract, PeerContractManifest, PeerEndpointContract, RuntimeEventDomain, } from '../../contracts.js';
+export type GatewayMethodTransport = 'http' | 'ws' | 'internal';
+export type GatewayMethodSource = 'builtin' | 'plugin';
+export type GatewayMethodAccess = 'public' | 'authenticated' | 'admin' | 'remote-peer';
+export type GatewayEventTransport = 'sse' | 'ws' | 'internal';
+export type DistributedPeerKind = 'node' | 'device';
+export type DistributedWorkType = 'invoke' | 'status.request' | 'location.request' | 'session.message' | 'automation.run';
+export type DistributedWorkStatus = 'queued' | 'claimed' | 'completed' | 'failed' | 'cancelled' | 'expired';
+//# sourceMappingURL=foundation-contract.d.ts.map

package/dist/_internal/platform/types/foundation-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation-contract.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/types/foundation-contract.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,sBAAsB,EACtB,UAAU,EACV,wBAAwB,EACxB,qBAAqB,EACrB,6BAA6B,EAC7B,sBAAsB,EACtB,8BAA8B,EAC9B,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,IAAI,GAAG,UAAU,CAAC;AAChE,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,QAAQ,CAAC;AACvD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,eAAe,GAAG,OAAO,GAAG,aAAa,CAAC;AACvF,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG,IAAI,GAAG,UAAU,CAAC;AAC9D,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAC3B,QAAQ,GACR,gBAAgB,GAChB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,CAAC;AACrB,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC"}

package/dist/_internal/platform/types/foundation-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/_internal/platform/types/generated/foundation-client-types.d.ts

@@ -0,0 +1,2 @@
+export type { OperatorEventPayload, OperatorEventPayloadMap, OperatorMethodInput, OperatorMethodInputMap, OperatorMethodOutput, OperatorMethodOutputMap, OperatorStreamMethodId, OperatorTypedEventId, OperatorTypedMethodId, PeerEndpointInput, PeerEndpointInputMap, PeerEndpointOutput, PeerEndpointOutputMap, PeerTypedEndpointId, RuntimeDomainEventPayload, RuntimeDomainEventPayloadMap, RuntimeDomainEventType, RuntimeEventTypedDomain, } from '../../../contracts.js';
+//# sourceMappingURL=foundation-client-types.d.ts.map

package/dist/_internal/platform/types/generated/foundation-client-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation-client-types.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/types/generated/foundation-client-types.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,4BAA4B,EAC5B,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC"}

package/dist/_internal/platform/types/generated/foundation-client-types.js

@@ -0,0 +1,2 @@
+// Generated by scripts/export-foundation-artifacts.ts. Do not edit manually.
+export {};

package/dist/_internal/platform/types/grid.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Cell - The atomic unit of the terminal surface grid.
+ */
+export interface Cell {
+    char: string;
+    fg: string;
+    bg: string;
+    bold: boolean;
+    dim: boolean;
+    underline: boolean;
+    italic: boolean;
+    strikethrough: boolean;
+    /** OSC 8 hyperlink URL. If set, the DiffEngine wraps this cell with OSC 8 sequences. */
+    link?: string;
+}
+/**
+ * Line - A single horizontal row of Cells.
+ */
+export type Line = Cell[];
+export declare const createEmptyCell: () => Cell;
+export declare const createEmptyLine: (width: number) => Line;
+/**
+ * createStyledCell - Create a Cell with all defaults, applying only the provided overrides.
+ * Eliminates the need to write out all 8 Cell properties at every call site.
+ */
+export declare const createStyledCell: (char: string, overrides?: Partial<Omit<Cell, "char">>) => Cell;
+//# sourceMappingURL=grid.d.ts.map

package/dist/_internal/platform/types/grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/types/grid.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;IACvB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC;AAE1B,eAAO,MAAM,eAAe,QAAO,IASjC,CAAC;AAEH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,KAAG,IACA,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,EAAE,YAAW,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAM,KAAG,IAU3F,CAAC"}

package/dist/_internal/platform/types/grid.js

@@ -0,0 +1,26 @@
+export const createEmptyCell = () => ({
+    char: ' ',
+    fg: '',
+    bg: '',
+    bold: false,
+    dim: false,
+    underline: false,
+    italic: false,
+    strikethrough: false
+});
+export const createEmptyLine = (width) => Array.from({ length: width }, createEmptyCell);
+/**
+ * createStyledCell - Create a Cell with all defaults, applying only the provided overrides.
+ * Eliminates the need to write out all 8 Cell properties at every call site.
+ */
+export const createStyledCell = (char, overrides = {}) => ({
+    char,
+    fg: overrides.fg ?? '',
+    bg: overrides.bg ?? '',
+    bold: overrides.bold ?? false,
+    dim: overrides.dim ?? false,
+    underline: overrides.underline ?? false,
+    italic: overrides.italic ?? false,
+    strikethrough: overrides.strikethrough ?? false,
+    link: overrides.link,
+});

package/dist/_internal/platform/types/tools.d.ts

@@ -0,0 +1,37 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/** Represents a tool the LLM can invoke. Parameters follow JSON Schema. */
+export type ToolSideEffect = 'read_fs' | 'write_fs' | 'network' | 'exec' | 'agent' | 'workflow' | 'state';
+export type ToolConcurrencyMode = 'serial' | 'parallel' | 'singleton';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    /** Side effects the tool may perform when executed successfully. */
+    sideEffects?: readonly ToolSideEffect[];
+    /** Whether multiple calls can safely run in parallel. */
+    concurrency?: ToolConcurrencyMode;
+    /** Whether the tool can emit meaningful progress before final completion. */
+    supportsProgress?: boolean;
+    /** Whether results may be streamed or delivered incrementally. */
+    supportsStreamingOutput?: boolean;
+}
+/** A tool invocation requested by the LLM. */
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** The outcome of executing a tool. */
+export interface ToolResult {
+    callId: string;
+    success: boolean;
+    output?: string;
+    error?: string;
+}
+/** A registered tool with its definition and executor. */
+export interface Tool {
+    definition: ToolDefinition;
+    /** Tools return a result without callId — the registry injects callId when wrapping. */
+    execute(args: Record<string, unknown>): Promise<Omit<ToolResult, 'callId'>>;
+}
+//# sourceMappingURL=tools.d.ts.map

package/dist/_internal/platform/types/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/types/tools.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,UAAU,GACV,SAAS,GACT,MAAM,GACN,OAAO,GACP,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AAEtE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,oEAAoE;IACpE,WAAW,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACxC,yDAAyD;IACzD,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kEAAkE;IAClE,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0DAA0D;AAC1D,MAAM,WAAW,IAAI;IACnB,UAAU,EAAE,cAAc,CAAC;IAC3B,wFAAwF;IACxF,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;CAC7E"}

package/dist/_internal/platform/types/tools.js

@@ -0,0 +1,2 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export {};

package/dist/_internal/platform/utils/clipboard.d.ts

@@ -0,0 +1,18 @@
+export declare const MIN_IMAGE_BYTES = 100;
+/**
+ * copyToClipboard - Uses OSC 52 escape sequence to copy text.
+ */
+export declare function copyToClipboard(text: string): void;
+/**
+ * pasteFromClipboard - Attempts to read from system clipboard using platform tools.
+ */
+export declare function pasteFromClipboard(): string;
+/**
+ * pasteImageFromClipboard - Attempts to read image data from system clipboard.
+ * Returns base64-encoded image data and mediaType, or null if no image is available.
+ */
+export declare function pasteImageFromClipboard(): {
+    data: string;
+    mediaType: string;
+} | null;
+//# sourceMappingURL=clipboard.d.ts.map

package/dist/_internal/platform/utils/clipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/utils/clipboard.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,eAAe,MAAM,CAAC;AASnC;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,QAW3C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAqC3C;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA0EpF"}

package/dist/_internal/platform/utils/clipboard.js

@@ -0,0 +1,147 @@
+import { logger } from './logger.js';
+import { summarizeError } from './error-display.js';
+export const MIN_IMAGE_BYTES = 100;
+const IMAGE_MIME_TYPES = [
+    { mime: 'image/png', mediaType: 'image/png' },
+    { mime: 'image/jpeg', mediaType: 'image/jpeg' },
+    { mime: 'image/webp', mediaType: 'image/webp' },
+    { mime: 'image/gif', mediaType: 'image/gif' },
+];
+/**
+ * copyToClipboard - Uses OSC 52 escape sequence to copy text.
+ */
+export function copyToClipboard(text) {
+    if (!text)
+        return;
+    logger.info('Clipboard: Attempting to copy via OSC 52', { length: text.length });
+    try {
+        const base64 = Buffer.from(text).toString('base64');
+        const sequence = `\x1b]52;c;${base64}\x07`;
+        process.stdout.write(sequence);
+        logger.info('Clipboard: OSC 52 sequence written');
+    }
+    catch (err) {
+        logger.error('Clipboard: OSC 52 copy failed', { error: summarizeError(err) });
+    }
+}
+/**
+ * pasteFromClipboard - Attempts to read from system clipboard using platform tools.
+ */
+export function pasteFromClipboard() {
+    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',
+                timeout: 3000,
+            });
+            if (wl.exitCode === 0 && wl.stdout) {
+                return Buffer.from(wl.stdout).toString();
+            }
+            const xclip = Bun.spawnSync(['xclip', '-selection', 'clipboard', '-o'], {
+                stdin: 'ignore',
+                stdout: 'pipe',
+                stderr: 'ignore',
+                timeout: 3000,
+            });
+            if (xclip.exitCode === 0 && xclip.stdout) {
+                return Buffer.from(xclip.stdout).toString();
+            }
+        }
+        else if (process.platform === 'darwin') {
+            const pb = Bun.spawnSync(['pbpaste'], {
+                stdin: 'ignore',
+                stdout: 'pipe',
+                stderr: 'ignore',
+                timeout: 3000,
+            });
+            if (pb.exitCode === 0 && pb.stdout) {
+                return Buffer.from(pb.stdout).toString();
+            }
+        }
+    }
+    catch (err) {
+        logger.error('Clipboard: Paste failed', { error: summarizeError(err) });
+    }
+    return '';
+}
+/**
+ * pasteImageFromClipboard - Attempts to read image data from system clipboard.
+ * Returns base64-encoded image data and mediaType, or null if no image is available.
+ */
+export function pasteImageFromClipboard() {
+    try {
+        if (process.platform === 'linux') {
+            // Try wl-paste (Wayland) for each supported MIME type
+            for (const { mime, mediaType } of IMAGE_MIME_TYPES) {
+                const wl = Bun.spawnSync(['wl-paste', '--type', mime, '--no-newline'], {
+                    stdin: 'ignore',
+                    stdout: 'pipe',
+                    stderr: 'ignore',
+                    timeout: 3000,
+                });
+                if (wl.exitCode === 0 && wl.stdout) {
+                    const buf = Buffer.from(wl.stdout);
+                    if (buf.length > MIN_IMAGE_BYTES) {
+                        return { data: buf.toString('base64'), mediaType };
+                    }
+                }
+            }
+            // 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',
+                    timeout: 3000,
+                });
+                if (xclip.exitCode === 0 && xclip.stdout) {
+                    const buf = Buffer.from(xclip.stdout);
+                    if (buf.length > MIN_IMAGE_BYTES) {
+                        return { data: buf.toString('base64'), mediaType };
+                    }
+                }
+            }
+        }
+        else if (process.platform === 'darwin') {
+            // macOS: try pngpaste first (brew install pngpaste), then fall back to osascript
+            const pp = Bun.spawnSync(['pngpaste', '-'], {
+                stdin: 'ignore',
+                stdout: 'pipe',
+                stderr: 'ignore',
+                timeout: 3000,
+            });
+            if (pp.exitCode === 0 && pp.stdout) {
+                const ppBuf = Buffer.from(pp.stdout);
+                if (ppBuf.length > MIN_IMAGE_BYTES) {
+                    return { data: ppBuf.toString('base64'), mediaType: 'image/png' };
+                }
+            }
+            // Fallback: osascript — 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',
+                timeout: 5000,
+            });
+            if (osa.exitCode === 0 && osa.stdout) {
+                const raw = Buffer.from(osa.stdout).toString('utf8').trim();
+                // raw is like: «data PNGf89504e47...»
+                const match = raw.match(/«data PNGf([0-9a-fA-F]+)»/);
+                if (match) {
+                    const osaBuf = Buffer.from(match[1], 'hex');
+                    if (osaBuf.length > MIN_IMAGE_BYTES) {
+                        return { data: osaBuf.toString('base64'), mediaType: 'image/png' };
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        logger.debug('Clipboard image access failed', { error: summarizeError(err) });
+    }
+    return null;
+}

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

@@ -0,0 +1,35 @@
+import { ProviderError, type ErrorCategory, type ErrorSource, 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 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;
+}
+export interface ErrorNormalizationOptions {
+    readonly provider?: string;
+    readonly fallbackMessage?: string;
+    readonly source?: ErrorSource;
+}
+export interface ProviderErrorNormalizationOptions extends ProviderErrorOptions {
+    readonly fallbackMessage?: string;
+}
+export declare function normalizeError(error: unknown, options?: ErrorNormalizationOptions): NormalizedError;
+export declare function summarizeError(error: unknown, options?: ErrorNormalizationOptions): string;
+export declare function formatError(error: unknown, options?: ErrorNormalizationOptions): string;
+export declare function buildErrorResponseBody(error: unknown, options?: ErrorNormalizationOptions): StructuredDaemonErrorBody;
+export declare function toProviderError(error: unknown, options?: ProviderErrorNormalizationOptions): ProviderError;
+export declare function formatProviderError(error: ProviderError, provider?: string): string;
+//# sourceMappingURL=error-display.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error-display.d.ts","sourceRoot":"","sources":["../../../../src/_internal/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;AAsBnF,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,CA4CvG;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"}