@margay/ccl-core 1.3.6-alpha.1 → 1.3.6-alpha.3

package/dist/sdk/errorDiagnostics.d.ts

@@ -0,0 +1,14 @@
+export declare function sanitizeErrorText(text: string): string;
+export type RecoveryOutcome = {
+    status: 'needs_user' | 'blocked_external';
+    reason: string;
+    attempts: number;
+};
+/** Optional wire extension. Omit invalid data; never spread arbitrary payloads. */
+export declare function sanitizeRecoveryOutcome(value: unknown): RecoveryOutcome | undefined;
+export declare function describeError(value: unknown): string;
+export declare function errorDetailsList(errors: unknown): string[];
+/** Preserve successful data and the wire shape; sanitize diagnostic fields only. */
+export declare function sanitizeErrorEnvelope<T extends {
+    type: string;
+}>(message: T): T;

package/dist/sdk/errorDiagnostics.js

@@ -0,0 +1,86 @@
+/** Shared CLI/SDK host diagnostics. Never serialize arbitrary error/request objects. */
+const MAX_DETAIL = 4096;
+const MAX_SCAN = 65_536;
+// Credential syntax redaction, NOT semantic diagnosis or retry classification.
+export function sanitizeErrorText(text) {
+    return text.slice(0, MAX_SCAN)
+        .replace(/\b(?:Bearer|Basic)\s+[^\s,;"'<>]+/gi, '[REDACTED]')
+        .replace(/\bsk-[a-zA-Z0-9_-]+/g, '[REDACTED]')
+        .replace(/\beyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/g, '[REDACTED]')
+        .replace(/((?:["']?)(?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|password|secret|authorization|cookie)(?:["']?)\s*[:=]\s*)(?:"[^"\n]*"|'[^'\n]*'|[^\s&,;]+)/gi, '$1[REDACTED]')
+        .replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, '$1[REDACTED]@')
+        .slice(0, MAX_DETAIL);
+}
+function own(value, key) {
+    // Accessors/custom toString/proxies must not break the error handler itself.
+    try {
+        return Object.getOwnPropertyDescriptor(value, key)?.value;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Optional wire extension. Omit invalid data; never spread arbitrary payloads. */
+export function sanitizeRecoveryOutcome(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const status = own(value, 'status'), reason = own(value, 'reason'), attempts = own(value, 'attempts');
+    if ((status !== 'needs_user' && status !== 'blocked_external') || typeof reason !== 'string' ||
+        !Number.isSafeInteger(attempts) || attempts < 0)
+        return undefined;
+    return { status, reason: sanitizeErrorText(reason), attempts: attempts };
+}
+export function describeError(value) {
+    const seen = new Set();
+    const parts = [];
+    function visit(node, depth) {
+        if (depth > 4 || parts.length >= 16)
+            return;
+        if (typeof node === 'string') {
+            if (node.trim())
+                parts.push(sanitizeErrorText(node));
+            return;
+        }
+        if (typeof node === 'number' || typeof node === 'boolean') {
+            parts.push(String(node));
+            return;
+        }
+        if (!node || typeof node !== 'object' || seen.has(node))
+            return;
+        seen.add(node);
+        const message = own(node, 'message');
+        if (typeof message === 'string')
+            visit(message, depth + 1);
+        for (const key of ['code', 'status', 'statusCode', 'requestId', 'request_id']) {
+            const field = own(node, key);
+            if (typeof field === 'string' || (typeof field === 'number' && Number.isFinite(field))) {
+                parts.push(`${key}=${sanitizeErrorText(String(field))}`);
+            }
+        }
+        visit(own(node, 'error'), depth + 1);
+        visit(own(node, 'cause'), depth + 1);
+    }
+    visit(value, 0);
+    return [...new Set(parts)].join('; ').slice(0, MAX_DETAIL) ||
+        'Error details were not supplied. Check the service logs for this request; no cause or automatic retry was inferred.';
+}
+export function errorDetailsList(errors) {
+    return Array.isArray(errors) ? errors.slice(0, 16).map(describeError) : [describeError(errors)];
+}
+/** Preserve successful data and the wire shape; sanitize diagnostic fields only. */
+export function sanitizeErrorEnvelope(message) {
+    const wire = message;
+    if (wire.type === 'result' && wire.is_error === true) {
+        return {
+            ...message,
+            ...(wire.errors !== undefined ? { errors: errorDetailsList(wire.errors) } : {}),
+            ...(typeof wire.result === 'string' ? { result: sanitizeErrorText(wire.result) } : {}),
+            ...(wire.recovery !== undefined ? { recovery: sanitizeRecoveryOutcome(wire.recovery) } : {}),
+        };
+    }
+    const assistant = message;
+    if (assistant.type === 'assistant' && assistant.error !== undefined && Array.isArray(assistant.message?.content)) {
+        return { ...message, message: { ...assistant.message, content: assistant.message.content.map(block => block?.type === 'text' && typeof block.text === 'string' ? { ...block, text: sanitizeErrorText(block.text) } : block) } };
+    }
+    return message;
+}

package/dist/sdk/interactionResponseSchema.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod/v4';
+export declare const interactionResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    outcome: z.ZodLiteral<"clarification_requested">;
+    intent: z.ZodEnum<{
+        clarify: "clarify";
+        finish_plan: "finish_plan";
+    }>;
+    answers: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    outcome: z.ZodLiteral<"cancelled">;
+}, z.core.$strict>, z.ZodObject<{
+    outcome: z.ZodLiteral<"interaction_unavailable">;
+}, z.core.$strict>, z.ZodObject<{
+    outcome: z.ZodLiteral<"timed_out">;
+}, z.core.$strict>]>;
+export type InteractionResponse = z.infer<typeof interactionResponseSchema>;

package/dist/sdk/interactionResponseSchema.js

@@ -0,0 +1,13 @@
+import { z } from 'zod/v4';
+// Additive field on deny-shaped wire responses for older host compatibility.
+// It never turns a permission denial into authorization to execute a tool.
+export const interactionResponseSchema = z.discriminatedUnion('outcome', [
+    z.object({
+        outcome: z.literal('clarification_requested'),
+        intent: z.enum(['clarify', 'finish_plan']),
+        answers: z.record(z.string(), z.string()),
+    }).strict(),
+    z.object({ outcome: z.literal('cancelled') }).strict(),
+    z.object({ outcome: z.literal('interaction_unavailable') }).strict(),
+    z.object({ outcome: z.literal('timed_out') }).strict(),
+]);

package/dist/sdk/query.d.ts

@@ -25,6 +25,7 @@
  *   the model re-generated. Deny works symmetrically. One-shot: the record
  *   is deleted after it is applied.
  */
+import { type InteractionResponse } from './interactionResponseSchema.js';
 import type { CanUseToolFn, PendingDecision, QueryOptions, SDKEvent, SessionStore, Transport } from './types.js';
 /** Builds the CLI argv for a query. Exported for unit tests. */
 export declare function buildCliArgs(options: QueryOptions): string[];
@@ -43,6 +44,7 @@ type PermissionDecisionWire = {
 } | {
     behavior: 'deny';
     message: string;
+    interaction?: InteractionResponse;
     interrupt?: boolean;
     toolUseID: string;
 };

package/dist/sdk/query.js

@@ -26,6 +26,8 @@
  *   is deleted after it is applied.
  */
 import { existsSync, mkdtempSync, symlinkSync } from 'fs';
+import { describeError, errorDetailsList, sanitizeErrorText, sanitizeRecoveryOutcome } from './errorDiagnostics.js';
+import { interactionResponseSchema } from './interactionResponseSchema.js';
 import { tmpdir } from 'os';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
@@ -147,9 +149,12 @@ function resolveCliPath(options) {
  * tool does not execute. `pending` is surfaced to the caller for suspend.
  */
 export async function decideFailClosed(callback, toolName, input, context, timeoutMs) {
+    let timedOut = false;
     const deny = (message, failClosedReason) => ({
         kind: 'decision',
-        decision: { behavior: 'deny', message, toolUseID: context.toolUseId },
+        decision: { behavior: 'deny', message, toolUseID: context.toolUseId,
+            ...(toolName === 'AskUserQuestion' ? { interaction: { outcome: timedOut ? 'timed_out' : 'interaction_unavailable' } } : {}),
+        },
         failClosedReason,
     });
     let raw;
@@ -161,13 +166,13 @@ export async function decideFailClosed(callback, toolName, input, context, timeo
                 ? await Promise.race([
                     callbackPromise,
                     new Promise((_, reject) => {
-                        timer = setTimeout(() => reject(new Error(`canUseTool timed out after ${timeoutMs}ms`)), timeoutMs);
+                        timer = setTimeout(() => { timedOut = true; reject(new Error(`canUseTool timed out after ${timeoutMs}ms`)); }, timeoutMs);
                     }),
                 ])
                 : await callbackPromise;
     }
     catch (error) {
-        return deny(`Denied (fail-closed): canUseTool callback failed: ${error instanceof Error ? error.message : String(error)}`, 'callback_error');
+        return deny(`Permission callback failed; no user rejection or permission was inferred: ${describeError(error)}`, 'callback_error');
     }
     finally {
         if (timer)
@@ -190,16 +195,22 @@ export async function decideFailClosed(callback, toolName, input, context, timeo
                 },
             };
         }
-        case 'deny':
+        case 'deny': {
+            const interaction = interactionResponseSchema.safeParse(raw.interaction);
+            if (raw.interaction !== undefined && !interaction.success) {
+                return deny('Interaction response was invalid; no user choice was inferred.', 'unrecognized_result');
+            }
             return {
                 kind: 'decision',
                 decision: {
                     behavior: 'deny',
-                    message: raw.message ?? 'Denied by host',
+                    message: sanitizeErrorText(raw.message ?? 'Denied by host'),
+                    ...(toolName === 'AskUserQuestion' && interaction.success ? { interaction: interaction.data } : {}),
                     ...(raw.interrupt !== undefined && { interrupt: raw.interrupt }),
                     toolUseID: context.toolUseId,
                 },
             };
+        }
         case 'pending':
             return { kind: 'pending' };
         default:
@@ -355,10 +366,15 @@ export async function* queryWithTransport(prompt, options, transport) {
                         if (block.type === 'tool_result') {
                             const toolUseId = String(block.tool_use_id ?? '');
                             const isError = block.is_error === true;
+                            const resultContent = isError
+                                ? typeof block.content === 'string' ? sanitizeErrorText(block.content)
+                                    : Array.isArray(block.content) ? block.content.map(part => part?.type === 'text' && typeof part.text === 'string' ? { ...part, text: sanitizeErrorText(part.text) } : part)
+                                        : describeError(block.content)
+                                : block.content;
                             yield {
                                 type: 'tool_result',
                                 toolUseId,
-                                content: block.content,
+                                content: resultContent,
                                 isError,
                                 sessionId,
                             };
@@ -366,7 +382,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                                 (() => hooks.onToolUse({
                                     toolUseId,
                                     toolName: toolNamesById.get(toolUseId),
-                                    content: block.content,
+                                    content: resultContent,
                                     isError,
                                     sessionId,
                                 })));
@@ -461,6 +477,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                                 behavior: 'deny',
                                 message: 'Denied (fail-closed): no canUseTool callback configured',
                                 toolUseID: toolUseId,
+                                ...(toolName === 'AskUserQuestion' ? { interaction: { outcome: 'interaction_unavailable' } } : {}),
                             },
                             failClosedReason: 'no_callback',
                         };
@@ -538,6 +555,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                         requestId,
                         toolUseId,
                         behavior: outcome.decision.behavior,
+                        ...(outcome.decision.behavior === 'deny' && outcome.decision.interaction ? { interaction: outcome.decision.interaction } : {}),
                         source: 'callback',
                         ...(outcome.failClosedReason && {
                             failClosedReason: outcome.failClosedReason,
@@ -587,8 +605,12 @@ export async function* queryWithTransport(prompt, options, transport) {
                             ? message.duration_ms
                             : undefined,
                         isError: message.is_error === true,
+                        ...(message.errors !== undefined ? { errors: errorDetailsList(message.errors) } : {}),
+                        ...(message.recovery !== undefined ? { recovery: sanitizeRecoveryOutcome(message.recovery) } : {}),
                         sessionId,
-                        result: typeof message.result === 'string' ? message.result : undefined,
+                        result: typeof message.result === 'string'
+                            ? message.is_error === true ? sanitizeErrorText(message.result) : message.result
+                            : undefined,
                         // slice sdk-json-schema-output (G4): surface the CLI's schema-validated structured
                         // output (present only when the query ran with jsonSchema).
                         structuredOutput: message

package/dist/sdk/types.d.ts

@@ -25,6 +25,8 @@ export type CanUseToolResult = {
 } | {
     behavior: 'deny';
     message?: string;
+    /** AskUserQuestion only; missing field preserves legacy deny behavior. */
+    interaction?: import('./interactionResponseSchema.js').InteractionResponse;
     /** Also interrupt the current turn instead of letting the agent continue. */
     interrupt?: boolean;
 } | {
@@ -304,6 +306,7 @@ export type SDKEvent = {
     behavior: 'allow' | 'deny';
     /** Why the SDK decided this way when the host callback did not decide. */
     failClosedReason?: string;
+    interaction?: import('./interactionResponseSchema.js').InteractionResponse;
     /** 'pending_decision' when resolved by resumeWithDecision, not the live callback. */
     source?: 'callback' | 'pending_decision';
 } | {
@@ -324,6 +327,9 @@ export type SDKEvent = {
     isError: boolean;
     sessionId?: string;
     result?: string;
+    /** Sanitized execution diagnostics; absent on older CLI result envelopes. */
+    errors?: string[];
+    recovery?: import('./errorDiagnostics.js').RecoveryOutcome;
     /**
      * slice sdk-json-schema-output (G4): the schema-validated structured output, present only
      * when the query was run with `jsonSchema`. undefined otherwise. subtype

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@margay/ccl-core",
-  "version": "1.3.6-alpha.1",
+  "version": "1.3.6-alpha.3",
   "description": "Core runtime extracted from Claude Code (ccl) for Margay integration",
   "license": "SEE LICENSE IN README.md",
   "type": "module",