adonis-ai-kit 0.0.0-stage → 1.2.0

package/dist/src/error_classifier.js

@@ -0,0 +1,206 @@
+import { AiException, ProviderUnavailableError } from './errors.js';
+const NETWORK_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ECONNABORTED',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'EPIPE',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'UND_ERR_SOCKET',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT',
+]);
+const FATAL_NAMES = new Set([
+    'AI_TypeValidationError',
+    'AI_InvalidPromptError',
+    'AI_InvalidArgumentError',
+    'AI_NoObjectGeneratedError',
+    'AI_NoSuchToolError',
+    'AI_InvalidToolInputError',
+    'AI_JSONParseError',
+    'AI_UnsupportedFunctionalityError',
+    'AI_LoadAPIKeyError',
+    'ZodError',
+]);
+const NETWORK_MESSAGE = /fetch failed|network|socket hang up|timed? ?out|connection (reset|refused|closed)/i;
+/**
+ * Returns the first value `pick` extracts from the error or from its `cause` / `lastError`
+ * chain (AI SDK `RetryError` keeps the real failure in `lastError`), looking at most `depth` levels down.
+ */
+function findErrorField(error, pick, depth = 5) {
+    if (error === null || typeof error !== 'object')
+        return undefined;
+    const node = error;
+    const own = pick(node);
+    if (own !== undefined)
+        return own;
+    if (depth <= 0)
+        return undefined;
+    return findErrorField(node.cause, pick, depth - 1) ?? findErrorField(node.lastError, pick, depth - 1);
+}
+const asNumber = (v) => (typeof v === 'number' ? v : undefined);
+function statusOf(error) {
+    return findErrorField(error, (n) => asNumber(n.statusCode) ?? asNumber(n.status) ?? asNumber(n.response?.status));
+}
+function codeOf(error) {
+    return findErrorField(error, (n) => (typeof n.code === 'string' ? n.code : undefined));
+}
+function classByStatusCode(status, message) {
+    if (status === 429)
+        return 'rate_limit';
+    if (status === 529 || status === 409 || status === 425)
+        return 'overloaded';
+    if (status === 408)
+        return 'timeout';
+    if (status === 401 || status === 403)
+        return 'auth_error';
+    if (status === 404)
+        return 'model_not_found';
+    if (status === 400) {
+        if (message.includes('too long') || message.includes('max_tokens') || message.includes('context length')) {
+            return 'prompt_too_long';
+        }
+        return 'invalid_request';
+    }
+    if (status >= 500)
+        return 'server_error';
+    return 'unknown';
+}
+/**
+ * Classifies an error into the fine-grained {@link ErrorClass} taxonomy.
+ * The HTTP status and error code are looked up through the `cause` / `lastError` chain.
+ */
+export function classifyErrorClass(error) {
+    const isObject = error !== null && typeof error === 'object';
+    const name = isObject ? error.name : undefined;
+    const message = isObject ? String(error.message ?? '') : '';
+    const status = statusOf(error);
+    if (status !== undefined)
+        return classByStatusCode(status, message);
+    if (name === 'AI_NoOutputGeneratedError' || name === 'NoOutputGeneratedError') {
+        if (message.includes('403') || message.includes('401'))
+            return 'auth_error';
+        if (message.includes('429'))
+            return 'rate_limit';
+        if (message.includes('500') || message.includes('502') || message.includes('503'))
+            return 'server_error';
+        return 'no_output_generated';
+    }
+    if (name === 'TimeoutError')
+        return 'timeout';
+    const code = codeOf(error);
+    if (code && NETWORK_CODES.has(code))
+        return 'network_error';
+    if (message.includes('fetch failed') || message.includes('ECONNREFUSED') || message.includes('ENOTFOUND')) {
+        return 'network_error';
+    }
+    if (message.includes('timeout') || message.includes('ETIMEDOUT'))
+        return 'timeout';
+    if (message.includes('too long') || message.includes('context length'))
+        return 'prompt_too_long';
+    return 'unknown';
+}
+const RETRYABLE_ERROR_CLASSES = new Set([
+    'rate_limit',
+    'overloaded',
+    'timeout',
+    'server_error',
+    'network_error',
+    'prompt_too_long',
+    'no_output_generated',
+]);
+/**
+ * Whether an error class is transient and therefore eligible for fallback routing.
+ */
+export function isRetryableError(errorClass) {
+    return RETRYABLE_ERROR_CLASSES.has(errorClass);
+}
+const BREAKER_ERROR_CLASSES = new Set([
+    'rate_limit',
+    'overloaded',
+    'timeout',
+    'server_error',
+    'network_error',
+]);
+/**
+ * Whether an error class reflects upstream health and should count against the circuit breaker.
+ * `prompt_too_long` and `no_output_generated` fall back to another model but never open the breaker.
+ */
+export function countsAsBreakerFailure(errorClass) {
+    return BREAKER_ERROR_CLASSES.has(errorClass);
+}
+/**
+ * Classifies an error for fallback / circuit-breaker decisions.
+ * `abortSignal` is the caller's signal: when it is aborted the failure is the caller's doing.
+ */
+export function classifyError(error, abortSignal) {
+    const outcome = (kind, reason, errorClass = 'unknown') => ({
+        kind,
+        reason,
+        errorClass,
+        countsAsFailure: kind === 'retryable' && countsAsBreakerFailure(errorClass),
+    });
+    if (abortSignal?.aborted)
+        return outcome('fatal', 'aborted by caller');
+    if (error instanceof ProviderUnavailableError)
+        return outcome('skip', 'circuit breaker open');
+    if (error instanceof AiException &&
+        (error.code === 'E_AI_MISSING_DEPENDENCY' || error.code === 'E_AI_CONFIG_ERROR')) {
+        return outcome('skip', error.code);
+    }
+    if (error === null || typeof error !== 'object')
+        return outcome('fatal', 'unknown error');
+    const err = error;
+    if (err.name === 'AbortError')
+        return outcome('fatal', 'aborted');
+    if (FATAL_NAMES.has(err.name))
+        return outcome('fatal', `validation (${err.name})`);
+    const errorClass = classifyErrorClass(error);
+    if (isRetryableError(errorClass))
+        return outcome('retryable', errorClass, errorClass);
+    if (errorClass !== 'unknown')
+        return outcome('fatal', errorClass, errorClass);
+    // Unclassified: keep the loose heuristics, but never override an explicit HTTP status.
+    if (statusOf(error) === undefined) {
+        if (NETWORK_MESSAGE.test(typeof err.message === 'string' ? err.message : '')) {
+            return outcome('retryable', 'network', 'network_error');
+        }
+        if (err.isRetryable === true)
+            return outcome('retryable', 'provider marked retryable');
+    }
+    return outcome('fatal', 'unclassified error');
+}
+/**
+ * Human-readable message for an error class, safe to show to an operator.
+ */
+export function getUserFriendlyMessage(errorClass) {
+    switch (errorClass) {
+        case 'rate_limit':
+            return 'Rate limited by API provider';
+        case 'overloaded':
+            return 'API provider overloaded';
+        case 'timeout':
+            return 'API request timed out';
+        case 'auth_error':
+            return 'API authentication failed — check API key';
+        case 'model_not_found':
+            return 'Model not found — check LLM_MODEL config';
+        case 'prompt_too_long':
+            return 'Context too large for model — consider compaction';
+        case 'invalid_request':
+            return 'Invalid API request';
+        case 'server_error':
+            return 'API server error';
+        case 'network_error':
+            return 'Network error — check connectivity';
+        case 'no_output_generated':
+            return 'Model produced no output — transient error, will retry';
+        default:
+            return 'Unknown API error';
+    }
+}
+//# sourceMappingURL=error_classifier.js.map

package/dist/src/error_classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error_classifier.js","sourceRoot":"","sources":["../../src/error_classifier.ts"],"names":[],"mappings":"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"}

package/dist/src/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Base exception class for all Adonis AI package errors.
+ */
+export declare class AiException extends Error {
+    code: string;
+    cause?: unknown | undefined;
+    constructor(message: string, code?: string, cause?: unknown | undefined);
+}
+/**
+ * Thrown when an AI provider is unreachable or circuit breaker is open.
+ */
+export declare class ProviderUnavailableError extends AiException {
+    provider: string;
+    constructor(provider: string, reason?: string);
+}
+/**
+ * Thrown when provider configuration is invalid or missing required credentials.
+ */
+export declare class ProviderConfigError extends AiException {
+    provider: string;
+    constructor(provider: string, message: string);
+}
+/**
+ * Thrown when primary provider and all fallback cascade providers fail.
+ */
+export declare class CascadingFallbackError extends AiException {
+    attempts: Array<{
+        provider: string;
+        model: string;
+        error: Error;
+    }>;
+    constructor(attempts: Array<{
+        provider: string;
+        model: string;
+        error: Error;
+    }>);
+}
+/**
+ * Thrown when token or cost budget thresholds are exceeded.
+ */
+export declare class BudgetExceededError extends AiException {
+    currentUsage?: unknown | undefined;
+    constructor(message: string, currentUsage?: unknown | undefined);
+}
+/**
+ * Thrown when a tool execution is rejected by security policy or fails during run.
+ */
+export declare class ToolExecutionError extends AiException {
+    toolName: string;
+    constructor(toolName: string, message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAG3B,IAAI,EAAE,MAAM;IACZ,KAAK,CAAC,EAAE,OAAO;gBAFtB,OAAO,EAAE,MAAM,EACR,IAAI,GAAE,MAAqB,EAC3B,KAAK,CAAC,EAAE,OAAO,YAAA;CAKzB;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,WAAW;IACpC,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAOrD;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAC/B,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAIrD;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,WAAW;IAClC,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC;gBAAlE,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC;CAKtF;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IACd,YAAY,CAAC,EAAE,OAAO;gBAA9C,OAAO,EAAE,MAAM,EAAS,YAAY,CAAC,EAAE,OAAO,YAAA;CAI3D;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;IAC9B,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAItE"}

package/dist/src/errors.js

@@ -0,0 +1,70 @@
+/**
+ * Base exception class for all Adonis AI package errors.
+ */
+export class AiException extends Error {
+    code;
+    cause;
+    constructor(message, code = 'E_AI_ERROR', cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'AiException';
+    }
+}
+/**
+ * Thrown when an AI provider is unreachable or circuit breaker is open.
+ */
+export class ProviderUnavailableError extends AiException {
+    provider;
+    constructor(provider, reason) {
+        super(`AI provider "${provider}" is currently unavailable: ${reason ?? 'Circuit breaker is OPEN'}`, 'E_AI_PROVIDER_UNAVAILABLE');
+        this.provider = provider;
+        this.name = 'ProviderUnavailableError';
+    }
+}
+/**
+ * Thrown when provider configuration is invalid or missing required credentials.
+ */
+export class ProviderConfigError extends AiException {
+    provider;
+    constructor(provider, message) {
+        super(`Invalid configuration for AI provider "${provider}": ${message}`, 'E_AI_CONFIG_ERROR');
+        this.provider = provider;
+        this.name = 'ProviderConfigError';
+    }
+}
+/**
+ * Thrown when primary provider and all fallback cascade providers fail.
+ */
+export class CascadingFallbackError extends AiException {
+    attempts;
+    constructor(attempts) {
+        const errorDetails = attempts.map((a) => `[${a.provider}:${a.model}] ${a.error.message}`).join('; ');
+        super(`All AI fallback providers failed: ${errorDetails}`, 'E_AI_FALLBACK_FAILED');
+        this.attempts = attempts;
+        this.name = 'CascadingFallbackError';
+    }
+}
+/**
+ * Thrown when token or cost budget thresholds are exceeded.
+ */
+export class BudgetExceededError extends AiException {
+    currentUsage;
+    constructor(message, currentUsage) {
+        super(message, 'E_AI_BUDGET_EXCEEDED');
+        this.currentUsage = currentUsage;
+        this.name = 'BudgetExceededError';
+    }
+}
+/**
+ * Thrown when a tool execution is rejected by security policy or fails during run.
+ */
+export class ToolExecutionError extends AiException {
+    toolName;
+    constructor(toolName, message, cause) {
+        super(`Tool execution error for "${toolName}": ${message}`, 'E_AI_TOOL_EXECUTION_ERROR', cause);
+        this.toolName = toolName;
+        this.name = 'ToolExecutionError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAG3B;IACA;IAHT,YACE,OAAe,EACR,OAAe,YAAY,EAC3B,KAAe;QAEtB,KAAK,CAAC,OAAO,CAAC,CAAA;QAHP,SAAI,GAAJ,IAAI,CAAuB;QAC3B,UAAK,GAAL,KAAK,CAAU;QAGtB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;IAC3B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,wBAAyB,SAAQ,WAAW;IACpC;IAAnB,YAAmB,QAAgB,EAAE,MAAe;QAClD,KAAK,CACH,gBAAgB,QAAQ,+BAA+B,MAAM,IAAI,yBAAyB,EAAE,EAC5F,2BAA2B,CAC5B,CAAA;QAJgB,aAAQ,GAAR,QAAQ,CAAQ;QAKjC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAA;IACxC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,WAAW;IAC/B;IAAnB,YAAmB,QAAgB,EAAE,OAAe;QAClD,KAAK,CAAC,0CAA0C,QAAQ,MAAM,OAAO,EAAE,EAAE,mBAAmB,CAAC,CAAA;QAD5E,aAAQ,GAAR,QAAQ,CAAQ;QAEjC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,WAAW;IAClC;IAAnB,YAAmB,QAAkE;QACnF,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACpG,KAAK,CAAC,qCAAqC,YAAY,EAAE,EAAE,sBAAsB,CAAC,CAAA;QAFjE,aAAQ,GAAR,QAAQ,CAA0D;QAGnF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAA;IACtC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,WAAW;IACd;IAApC,YAAY,OAAe,EAAS,YAAsB;QACxD,KAAK,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAA;QADJ,iBAAY,GAAZ,YAAY,CAAU;QAExD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IAC9B;IAAnB,YAAmB,QAAgB,EAAE,OAAe,EAAE,KAAe;QACnE,KAAK,CAAC,6BAA6B,QAAQ,MAAM,OAAO,EAAE,EAAE,2BAA2B,EAAE,KAAK,CAAC,CAAA;QAD9E,aAAQ,GAAR,QAAQ,CAAQ;QAEjC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF"}

package/dist/src/guard/confirmation.d.ts

@@ -0,0 +1,67 @@
+import type { ConfirmationResponse, Logger, PendingAction } from './types.js';
+export type ConfirmationCallback = (response: ConfirmationResponse) => void;
+export type ActionCreatedListener = (action: PendingAction) => void;
+export type ActionResolvedListener = (action: PendingAction, response: ConfirmationResponse) => void;
+export interface ConfirmationServiceOptions {
+    defaultTimeoutMs?: number;
+    logger?: Logger;
+}
+/** Largest delay `setTimeout` accepts; larger values fire after ~1ms with a TimeoutOverflowWarning. */
+export declare const MAX_TIMEOUT_MS: number;
+/**
+ * Manages human-in-the-loop confirmations for sensitive or irreversible actions.
+ *
+ * Actions are kept in memory with a configurable TTL.
+ * External interfaces (web UI, telegram bots, webhooks) approve or reject them.
+ * If no response arrives within the timeout window, the action automatically times out.
+ *
+ * Timers are `unref()`'d so a pending confirmation never keeps the process alive; call
+ * `dispose()` on shutdown to settle everything that is still pending.
+ */
+export declare class ConfirmationService {
+    private pending;
+    private defaultTimeoutMs;
+    private logger?;
+    private createdListeners;
+    private resolvedListeners;
+    private disposed;
+    constructor(opts?: ConfirmationServiceOptions);
+    setLogger(logger: Logger): void;
+    onActionCreated(listener: ActionCreatedListener): () => void;
+    onActionResolved(listener: ActionResolvedListener): () => void;
+    /**
+     * Create a pending action and wait for human confirmation, timeout, or abort.
+     * Never approves implicitly: timeout, abort and disposal all resolve as non-approved.
+     */
+    waitForResponse(action: Omit<PendingAction, 'id' | 'status' | 'createdAt' | 'expiresAt'>, timeoutMs?: number, abortSignal?: AbortSignal): Promise<ConfirmationResponse>;
+    /**
+     * Approve a pending action. If the action is bound to a session, the caller must present the
+     * same `sessionId`; otherwise the approval is refused and the action stays pending.
+     */
+    approve(actionId: string, reason?: string, sessionId?: string): boolean;
+    /**
+     * Reject a pending action. Same session binding rules as `approve()`.
+     */
+    reject(actionId: string, reason?: string, sessionId?: string): boolean;
+    /**
+     * List current pending actions, optionally restricted to one session.
+     */
+    getPendingActions(sessionId?: string): PendingAction[];
+    /**
+     * Get a specific pending action by ID.
+     */
+    getPendingAction(actionId: string): PendingAction | null;
+    /**
+     * Resolves expired items as `timeout`, invoking `onActionResolved` listeners.
+     */
+    clearExpired(): void;
+    /**
+     * Settles every pending action as rejected, clears timers and listeners.
+     * Further `waitForResponse()` calls resolve as rejected immediately.
+     */
+    dispose(): void;
+    private resolveAction;
+    private notifyCreated;
+    private notifyResolved;
+}
+//# sourceMappingURL=confirmation.d.ts.map

package/dist/src/guard/confirmation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmation.d.ts","sourceRoot":"","sources":["../../../src/guard/confirmation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE7E,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAAA;AAC3E,MAAM,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAA;AACnE,MAAM,MAAM,sBAAsB,GAAG,CACnC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,oBAAoB,KAC3B,IAAI,CAAA;AAET,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,uGAAuG;AACvG,eAAO,MAAM,cAAc,QAAc,CAAA;AAgBzC;;;;;;;;;GASG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,MAAM,CAAC,CAAQ;IACvB,OAAO,CAAC,gBAAgB,CAAwC;IAChE,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,IAAI,GAAE,0BAA+B;IAKjD,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B,eAAe,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAK5D,gBAAgB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAK9D;;;OAGG;IACG,eAAe,CACnB,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,CAAC,EACxE,SAAS,GAAE,MAA8B,EACzC,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,oBAAoB,CAAC;IAgEhC;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO;IAIvE;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO;IAItE;;OAEG;IACH,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE;IAMtD;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAOxD;;OAEG;IACH,YAAY,IAAI,IAAI;IASpB;;;OAGG;IACH,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,aAAa;IAmBrB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,cAAc;CASvB"}

package/dist/src/guard/confirmation.js

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto';
+/** Largest delay `setTimeout` accepts; larger values fire after ~1ms with a TimeoutOverflowWarning. */
+export const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+const DEFAULT_TIMEOUT_MS = 60_000;
+function normalizeTimeout(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return Math.min(fallback, MAX_TIMEOUT_MS);
+    }
+    return Math.min(Math.floor(value), MAX_TIMEOUT_MS);
+}
+/**
+ * Manages human-in-the-loop confirmations for sensitive or irreversible actions.
+ *
+ * Actions are kept in memory with a configurable TTL.
+ * External interfaces (web UI, telegram bots, webhooks) approve or reject them.
+ * If no response arrives within the timeout window, the action automatically times out.
+ *
+ * Timers are `unref()`'d so a pending confirmation never keeps the process alive; call
+ * `dispose()` on shutdown to settle everything that is still pending.
+ */
+export class ConfirmationService {
+    pending = new Map();
+    defaultTimeoutMs;
+    logger;
+    createdListeners = new Set();
+    resolvedListeners = new Set();
+    disposed = false;
+    constructor(opts = {}) {
+        this.defaultTimeoutMs = normalizeTimeout(opts.defaultTimeoutMs, DEFAULT_TIMEOUT_MS);
+        this.logger = opts.logger;
+    }
+    setLogger(logger) {
+        this.logger = logger;
+    }
+    onActionCreated(listener) {
+        this.createdListeners.add(listener);
+        return () => this.createdListeners.delete(listener);
+    }
+    onActionResolved(listener) {
+        this.resolvedListeners.add(listener);
+        return () => this.resolvedListeners.delete(listener);
+    }
+    /**
+     * Create a pending action and wait for human confirmation, timeout, or abort.
+     * Never approves implicitly: timeout, abort and disposal all resolve as non-approved.
+     */
+    async waitForResponse(action, timeoutMs = this.defaultTimeoutMs, abortSignal) {
+        if (this.disposed) {
+            return { status: 'rejected', reason: 'Confirmation service disposed' };
+        }
+        if (abortSignal?.aborted) {
+            return { status: 'rejected', reason: 'Aborted' };
+        }
+        const id = randomUUID();
+        const effectiveTimeout = normalizeTimeout(timeoutMs, this.defaultTimeoutMs);
+        const now = Date.now();
+        const expiresAt = now + effectiveTimeout;
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (response) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                abortSignal?.removeEventListener('abort', onAbort);
+                const item = this.pending.get(id);
+                this.pending.delete(id);
+                if (item) {
+                    const { callback: _cb, timer: _t, ...rest } = item;
+                    this.notifyResolved({ ...rest, status: response.status, reason: response.reason }, response);
+                }
+                resolve(response);
+            };
+            const onAbort = () => settle({ status: 'rejected', reason: 'Aborted' });
+            const timer = setTimeout(() => {
+                this.logger?.warn?.(`[ConfirmationService] Action ${id} timed out after ${effectiveTimeout}ms`);
+                settle({ status: 'timeout', reason: 'Confirmation timeout' });
+            }, effectiveTimeout);
+            timer.unref?.();
+            abortSignal?.addEventListener('abort', onAbort, { once: true });
+            const fullAction = {
+                ...action,
+                id,
+                createdAt: now,
+                expiresAt,
+                status: 'pending',
+            };
+            this.pending.set(id, { ...fullAction, callback: settle, timer });
+            this.logger?.info?.(`[ConfirmationService] Action created: ${id} (${action.action} on ${action.toolName}), expires in ${effectiveTimeout}ms`);
+            this.notifyCreated(fullAction);
+        });
+    }
+    /**
+     * Approve a pending action. If the action is bound to a session, the caller must present the
+     * same `sessionId`; otherwise the approval is refused and the action stays pending.
+     */
+    approve(actionId, reason, sessionId) {
+        return this.resolveAction(actionId, { status: 'approved', reason }, sessionId);
+    }
+    /**
+     * Reject a pending action. Same session binding rules as `approve()`.
+     */
+    reject(actionId, reason, sessionId) {
+        return this.resolveAction(actionId, { status: 'rejected', reason }, sessionId);
+    }
+    /**
+     * List current pending actions, optionally restricted to one session.
+     */
+    getPendingActions(sessionId) {
+        return Array.from(this.pending.values())
+            .filter((entry) => sessionId === undefined || entry.sessionId === sessionId)
+            .map(({ callback: _cb, timer: _t, ...action }) => action);
+    }
+    /**
+     * Get a specific pending action by ID.
+     */
+    getPendingAction(actionId) {
+        const entry = this.pending.get(actionId);
+        if (!entry)
+            return null;
+        const { callback: _cb, timer: _t, ...action } = entry;
+        return action;
+    }
+    /**
+     * Resolves expired items as `timeout`, invoking `onActionResolved` listeners.
+     */
+    clearExpired() {
+        const now = Date.now();
+        for (const item of [...this.pending.values()]) {
+            if (item.expiresAt <= now) {
+                item.callback({ status: 'timeout', reason: 'Confirmation expired' });
+            }
+        }
+    }
+    /**
+     * Settles every pending action as rejected, clears timers and listeners.
+     * Further `waitForResponse()` calls resolve as rejected immediately.
+     */
+    dispose() {
+        this.disposed = true;
+        for (const item of [...this.pending.values()]) {
+            item.callback({ status: 'rejected', reason: 'Confirmation service disposed' });
+        }
+        this.pending.clear();
+        this.createdListeners.clear();
+        this.resolvedListeners.clear();
+    }
+    resolveAction(actionId, response, sessionId) {
+        const entry = this.pending.get(actionId);
+        if (!entry)
+            return false;
+        if (entry.sessionId !== undefined && entry.sessionId !== sessionId) {
+            this.logger?.warn?.(`[ConfirmationService] Refused to ${response.status === 'approved' ? 'approve' : 'reject'} action ${actionId}: session mismatch`);
+            return false;
+        }
+        entry.callback(response);
+        return true;
+    }
+    notifyCreated(action) {
+        for (const listener of this.createdListeners) {
+            try {
+                listener(action);
+            }
+            catch (err) {
+                this.logger?.warn?.('[ConfirmationService] Error in actionCreated listener:', err);
+            }
+        }
+    }
+    notifyResolved(action, response) {
+        for (const listener of this.resolvedListeners) {
+            try {
+                listener(action, response);
+            }
+            catch (err) {
+                this.logger?.warn?.('[ConfirmationService] Error in actionResolved listener:', err);
+            }
+        }
+    }
+}
+//# sourceMappingURL=confirmation.js.map

package/dist/src/guard/confirmation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmation.js","sourceRoot":"","sources":["../../../src/guard/confirmation.ts"],"names":[],"mappings":"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"}

package/dist/src/guard/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Thrown when a tool call is refused by security policy and must not run:
+ * permission is `deny`, or `ask` without any way to obtain a confirmation (fail-closed).
+ */
+export declare class PolicyViolationError extends Error {
+    readonly toolName: string;
+    readonly code = "E_POLICY_VIOLATION";
+    constructor(toolName: string, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/guard/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/guard/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAI3B,QAAQ,EAAE,MAAM;IAHlC,QAAQ,CAAC,IAAI,wBAAuB;gBAGlB,QAAQ,EAAE,MAAM,EAChC,OAAO,EAAE,MAAM;CAKlB"}

package/dist/src/guard/errors.js

@@ -0,0 +1,14 @@
+/**
+ * Thrown when a tool call is refused by security policy and must not run:
+ * permission is `deny`, or `ask` without any way to obtain a confirmation (fail-closed).
+ */
+export class PolicyViolationError extends Error {
+    toolName;
+    code = 'E_POLICY_VIOLATION';
+    constructor(toolName, message) {
+        super(`Tool "${toolName}" blocked by policy: ${message}`);
+        this.toolName = toolName;
+        this.name = 'PolicyViolationError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/guard/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/guard/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAI3B;IAHT,IAAI,GAAG,oBAAoB,CAAA;IAEpC,YACkB,QAAgB,EAChC,OAAe;QAEf,KAAK,CAAC,SAAS,QAAQ,wBAAwB,OAAO,EAAE,CAAC,CAAA;QAHzC,aAAQ,GAAR,QAAQ,CAAQ;QAIhC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACpC,CAAC;CACF"}