dsh-agy-cli 0.0.0-stage → 0.12.1

package/lib/agy/limiter.js

@@ -0,0 +1,111 @@
+export class AgyQueueError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'AgyQueueError';
+    }
+}
+function validateInteger(name, value, minimum, maximum) {
+    if (!Number.isInteger(value) || value < minimum || value > maximum) {
+        throw new RangeError(`${name} must be an integer between ${minimum} and ${maximum}`);
+    }
+    return value;
+}
+/** FIFO limiter for AGY child processes, with bounded queue and cancellation. */
+export class AgyConcurrencyLimiter {
+    maxConcurrent;
+    maxQueue;
+    queueTimeoutMs;
+    active = 0;
+    queue = [];
+    constructor(options) {
+        this.maxConcurrent = validateInteger('maxConcurrent', options.maxConcurrent, 1, 64);
+        this.maxQueue = validateInteger('maxQueue', options.maxQueue, 0, 256);
+        this.queueTimeoutMs = validateInteger('queueTimeoutMs', options.queueTimeoutMs, 0, 3_600_000);
+    }
+    getStats() {
+        return {
+            active: this.active,
+            queued: this.queue.length,
+            maxConcurrent: this.maxConcurrent,
+            maxQueue: this.maxQueue,
+            queueTimeoutMs: this.queueTimeoutMs,
+        };
+    }
+    acquire(signal) {
+        if (signal?.aborted) {
+            return Promise.reject(new AgyQueueError('AGY request aborted while waiting for a process slot', 'ABORTED'));
+        }
+        if (this.active < this.maxConcurrent) {
+            this.active += 1;
+            return Promise.resolve(this.createRelease());
+        }
+        if (this.queue.length >= this.maxQueue) {
+            return Promise.reject(new AgyQueueError('AGY process queue is full', 'QUEUE_FULL'));
+        }
+        return new Promise((resolve, reject) => {
+            const entry = {
+                resolve,
+                reject,
+                signal,
+                onAbort: () => this.rejectEntry(entry, new AgyQueueError('AGY request aborted while waiting for a process slot', 'ABORTED')),
+                timer: undefined,
+                settled: false,
+            };
+            if (this.queueTimeoutMs > 0) {
+                entry.timer = setTimeout(() => this.rejectEntry(entry, new AgyQueueError('AGY request exceeded the process queue timeout', 'QUEUE_TIMEOUT')), this.queueTimeoutMs);
+            }
+            signal?.addEventListener('abort', entry.onAbort, { once: true });
+            this.queue.push(entry);
+            this.drain();
+        });
+    }
+    createRelease() {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.active -= 1;
+            this.drain();
+        };
+    }
+    rejectEntry(entry, error) {
+        if (entry.settled)
+            return;
+        const index = this.queue.indexOf(entry);
+        if (index >= 0)
+            this.queue.splice(index, 1);
+        entry.settled = true;
+        if (entry.timer !== undefined)
+            clearTimeout(entry.timer);
+        entry.signal?.removeEventListener('abort', entry.onAbort);
+        entry.reject(error);
+    }
+    resolveEntry(entry) {
+        if (entry.settled)
+            return;
+        entry.settled = true;
+        if (entry.timer !== undefined)
+            clearTimeout(entry.timer);
+        entry.signal?.removeEventListener('abort', entry.onAbort);
+        this.active += 1;
+        entry.resolve(this.createRelease());
+    }
+    drain() {
+        while (this.active < this.maxConcurrent && this.queue.length > 0) {
+            const entry = this.queue.shift();
+            if (entry === undefined)
+                return;
+            if (entry.settled)
+                continue;
+            if (entry.signal?.aborted) {
+                this.rejectEntry(entry, new AgyQueueError('AGY request aborted while waiting for a process slot', 'ABORTED'));
+                continue;
+            }
+            this.resolveEntry(entry);
+        }
+    }
+}
+//# sourceMappingURL=limiter.js.map

package/lib/agy/log.d.ts

@@ -0,0 +1,214 @@
+import { type AgyProcessDiagnostic, type AgyReasoningEffort, type ProcessResult, type ProcessTermination } from './process.js';
+import { type AgyToolEventDiagnostic, type AgyEventCategoryCounts, type AgyToolEventKind } from './parser.js';
+import type { ToolPolicy } from '../provider/config.js';
+import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+import { type ModelDiscoveryErrorCode } from '../provider/error-codes.js';
+import type { ModelDiscoverySource } from './models.js';
+import type { ToolProtocolArgumentIssue, ToolProtocolCompatibility } from '../provider/tool-protocol.js';
+export type AgyModelDiscoveryLogSource = 'static' | ModelDiscoverySource;
+export type AgyPermissionPreset = 'read-only' | 'workspace-write' | 'danger-full-access';
+export type AgySandboxMode = AgyPermissionPreset;
+export type AgyApprovalPolicy = 'ask' | 'never';
+export type AgyBridgeOutcome = 'text-only' | 'mcp-tools' | 'dsh-pending' | 'dsh-message' | 'dsh-tool-call' | 'agy-owned' | 'context-rejected' | 'schema-rejected' | 'protocol-rejected' | 'agy-internal-tool' | 'permission-required' | 'failed';
+export type AgyRequestMode = 'full' | 'bootstrap' | 'delta' | 'full-fallback';
+export type AgyDispatchKind = 'cold' | 'persistent';
+export type AgyUsageSource = 'step' | 'result-fallback';
+export type AgyCarrierValidation = 'recipient-rejected' | 'valid-message' | 'valid-tool-call' | 'invalid-envelope' | 'unknown-tool' | 'arguments-invalid' | 'response-limit';
+/** Safe, fixed labels for a rejected DSH-owned final response. */
+export type AgyProtocolFailureDetail = 'not-json' | 'envelope' | 'message-shape' | 'tool-call-shape' | 'response-limit' | 'validation' | 'unknown';
+export type AgyProtocolArgumentIssue = ToolProtocolArgumentIssue;
+/** Safe shape labels; the response body is intentionally never logged. */
+export type AgyProtocolResponseShape = 'empty' | 'object-like' | 'array-like' | 'fenced' | 'plain-text' | 'non-string';
+export type AgyLogEvent = 'agy.request.started' | 'agy.request.completed' | 'agy.request.failed';
+export interface AgyLogRecord {
+    event: AgyLogEvent;
+    requestId: string;
+    provider: string;
+    model: string;
+    agent: string;
+    toolPolicy: ToolPolicy;
+    toolSchemaCount: number;
+    toolCallCount: number;
+    bridgeOutcome: AgyBridgeOutcome;
+    permissionPreset?: AgyPermissionPreset;
+    sandboxMode?: AgySandboxMode;
+    approvalPolicy?: AgyApprovalPolicy;
+    reasoningEffort?: AgyReasoningEffort;
+    purpose?: 'compaction' | 'session-title';
+    modelDiscoverySource?: AgyModelDiscoveryLogSource;
+    modelDiscoveryWarningCode?: ModelDiscoveryErrorCode;
+    attempt: number;
+    processAttemptCount?: number;
+    retryMaxRetries?: number;
+    inputFrameBytes?: number;
+    inputFrameLimitBytes?: number;
+    promptBytes?: number;
+    promptLimitBytes?: number;
+    toolResultCount?: number;
+    largestToolResultBytes?: number;
+    truncatedToolResultCount?: number;
+    historyCompacted?: boolean;
+    omittedMessageCount?: number;
+    toolEventKind?: AgyToolEventKind;
+    toolEventStreamIndex?: number;
+    toolEventDiagnostic?: AgyToolEventDiagnostic;
+    /** True when the wrapper was intentionally aborted after a validated carrier was captured. */
+    carrierAbortExpected?: boolean;
+    carrierValidation?: AgyCarrierValidation;
+    protocolRepairAttempts?: number;
+    protocolRepairReason?: 'not-json' | 'arguments-invalid' | 'internal-tool-event';
+    protocolFailureDetail?: AgyProtocolFailureDetail;
+    protocolResponseShape?: AgyProtocolResponseShape;
+    protocolResponseBytes?: number;
+    protocolToolName?: string;
+    protocolArgumentIssue?: AgyProtocolArgumentIssue;
+    protocolMissingRequiredKeys?: readonly string[];
+    protocolReceivedArgumentKeys?: readonly string[];
+    protocolCompatibilityApplied?: ToolProtocolCompatibility;
+    eventCount: number;
+    toolEventCount: number;
+    permissionEventCount: number;
+    eventCategoryCounts: Readonly<AgyEventCategoryCounts>;
+    /**
+     * Which AGY process served the attempt: `persistent` reuses a warm worker for
+     * this DSH session, `cold` spawned a fresh AGY process. The two paths differ by
+     * AGY's whole startup cost (process spawn, auth, MCP handshake), so every
+     * latency field below is meaningless without this marker.
+     */
+    dispatch?: AgyDispatchKind;
+    /** Milliseconds from process start to the first parsed AGY event. */
+    firstEventMs?: number;
+    /** Milliseconds from process start to the first streamed text delta. */
+    firstTextMs?: number;
+    finalStatus?: string;
+    /**
+     * Raw JSON of AGY's own `result` frame, bounded to the fields that explain a
+     * non-SUCCESS ending. `status: "ERROR"` alone carries no diagnosis, and AGY
+     * omits `error` on the long-context failures this adapter sees, so the whole
+     * frame is the only place its explanation can live.
+     */
+    finalResultRaw?: string;
+    sessionId?: string;
+    conversationId?: string;
+    durationMs?: number;
+    exitCode?: number | null;
+    termination?: ProcessTermination;
+    queueWaitMs?: number;
+    usage?: TokenUsage;
+    /** Current physical-turn usage selected from the latest step event. */
+    usageSource?: AgyUsageSource;
+    /** AGY result usage is conversation-cumulative and is telemetry only. */
+    cumulativeUsage?: TokenUsage;
+    cacheHit?: boolean;
+    cacheTokenShare?: number;
+    requestMode?: AgyRequestMode;
+    conversationReused?: boolean;
+    /**
+     * A persistent worker came up with a different conversation than the stored
+     * binding, so the binding was dropped and the turn resent from full history.
+     */
+    conversationMismatch?: boolean;
+    /**
+     * AGY closed the turn with `status: ERROR` after text had already streamed.
+     * The partial text was delivered and the failure was kept as a reasoning
+     * annotation instead of being thrown away with the whole turn.
+     */
+    partialAnswerDelivered?: boolean;
+    stablePrefixBytes?: number;
+    stablePrefixHash?: string;
+    toolSchemaHash?: string;
+    /** Session/conversation identifiers are represented only by one-way fingerprints. */
+    sessionFingerprint?: string;
+    conversationFingerprint?: string;
+    processDiagnostic?: AgyProcessDiagnostic;
+    errorCode?: string;
+}
+export type AgyLogger = (record: Readonly<AgyLogRecord>) => void;
+/**
+ * Temporary test-observability sink. The caller must pass an already
+ * sanitized record; this file is intentionally outside the DSH session store
+ * because that store currently drops Error.cause and nested diagnostics.
+ */
+export declare const AGY_DIAGNOSTIC_LOG_PATH: string;
+export declare function appendAgyDiagnosticRecord(record: Readonly<AgyLogRecord>): void;
+/** Mutable request counters kept separate from the public log shape. */
+export interface AgyTelemetry {
+    readonly requestId: string;
+    readonly provider: string;
+    readonly model: string;
+    readonly agent: string;
+    readonly toolPolicy: ToolPolicy;
+    readonly toolSchemaCount: number;
+    toolCallCount: number;
+    bridgeOutcome: AgyBridgeOutcome;
+    permissionPreset?: AgyPermissionPreset;
+    sandboxMode?: AgySandboxMode;
+    approvalPolicy?: AgyApprovalPolicy;
+    readonly reasoningEffort?: AgyReasoningEffort;
+    readonly purpose?: 'compaction' | 'session-title';
+    readonly modelDiscoverySource?: AgyModelDiscoveryLogSource;
+    readonly modelDiscoveryWarningCode?: ModelDiscoveryErrorCode;
+    readonly sessionId: string | undefined;
+    readonly startedAt: number;
+    durationMs: number | undefined;
+    attempt: number;
+    processAttemptCount: number;
+    retryMaxRetries: number;
+    inputFrameBytes: number | undefined;
+    inputFrameLimitBytes: number | undefined;
+    promptBytes: number | undefined;
+    promptLimitBytes: number | undefined;
+    toolResultCount: number | undefined;
+    largestToolResultBytes: number | undefined;
+    truncatedToolResultCount: number | undefined;
+    historyCompacted: boolean;
+    omittedMessageCount: number;
+    toolEventKind: AgyToolEventKind | undefined;
+    toolEventStreamIndex: number | undefined;
+    toolEventDiagnostic: AgyToolEventDiagnostic | undefined;
+    carrierAbortExpected: boolean;
+    carrierValidation: AgyCarrierValidation | undefined;
+    protocolRepairAttempts: number;
+    protocolRepairReason: 'not-json' | 'arguments-invalid' | 'internal-tool-event' | undefined;
+    protocolFailureDetail: AgyProtocolFailureDetail | undefined;
+    protocolResponseShape: AgyProtocolResponseShape | undefined;
+    protocolResponseBytes: number | undefined;
+    protocolToolName: string | undefined;
+    protocolArgumentIssue: AgyProtocolArgumentIssue | undefined;
+    protocolMissingRequiredKeys: readonly string[] | undefined;
+    protocolReceivedArgumentKeys: readonly string[] | undefined;
+    protocolCompatibilityApplied: ToolProtocolCompatibility | undefined;
+    eventCount: number;
+    toolEventCount: number;
+    permissionEventCount: number;
+    eventCategoryCounts: AgyEventCategoryCounts;
+    dispatch: AgyDispatchKind | undefined;
+    firstEventMs: number | undefined;
+    firstTextMs: number | undefined;
+    finalStatus: string | undefined;
+    finalResultRaw: string | undefined;
+    conversationId: string | undefined;
+    queueWaitMs: number | undefined;
+    process: ProcessResult | undefined;
+    usage: TokenUsage | undefined;
+    usageSource: AgyUsageSource | undefined;
+    cumulativeUsage: TokenUsage | undefined;
+    cacheHit: boolean | undefined;
+    cacheTokenShare: number | undefined;
+    requestMode: AgyRequestMode | undefined;
+    conversationReused: boolean | undefined;
+    /** A persistent worker could not continue the stored conversation; binding dropped, resent from full history. */
+    conversationMismatch: boolean | undefined;
+    /** A failed AGY turn still delivered the text it had already streamed. */
+    partialAnswerDelivered: boolean | undefined;
+    stablePrefixBytes: number | undefined;
+    stablePrefixHash: string | undefined;
+    toolSchemaHash: string | undefined;
+    processDiagnostic: AgyProcessDiagnostic | undefined;
+}
+/** Build a whitelist-only record; prompt, stderr, env and executable are absent by design. */
+export declare function buildAgyLogRecord(telemetry: AgyTelemetry, event: AgyLogEvent, errorCode?: string): AgyLogRecord;
+/** Apply a final whitelist-only safety pass before the host logger receives metadata. */
+export declare function sanitizeAgyLogRecord(record: AgyLogRecord): AgyLogRecord;
+export declare function emitAgyLog(logger: AgyLogger | undefined, record: AgyLogRecord): void;
+//# sourceMappingURL=log.d.ts.map