dsh-agy-cli 0.0.0-stage → 0.12.1

package/lib/agy/parser.js

@@ -0,0 +1,492 @@
+export const DEFAULT_MAX_LINE_LENGTH = 1_048_576;
+export class AgyParserError extends Error {
+    code;
+    lineNumber;
+    rawLine;
+    constructor(message, code, lineNumber, rawLine, options) {
+        super(message, options);
+        this.code = code;
+        this.lineNumber = lineNumber;
+        this.rawLine = rawLine;
+        this.name = 'AgyParserError';
+    }
+}
+const AGY_TOOL_EVENT_KINDS = [
+    'event-tool-call',
+    'event-tool-result',
+    'step-type-tool',
+    'explicit-tool-name',
+];
+/**
+ * Stable AGY orchestration recipients used to carry a DSH-owned tool call.
+ * Keep this exact-name allowlist narrow; arbitrary recipients remain rejected.
+ */
+const DSH_CARRIER_RECIPIENTS = ['dsh', 'dsh-session', 'dsh-runner'];
+export function isDshCarrierRecipient(value) {
+    return DSH_CARRIER_RECIPIENTS.includes(value);
+}
+export function isAgyToolEventKind(value) {
+    return typeof value === 'string'
+        && AGY_TOOL_EVENT_KINDS.includes(value);
+}
+export function emptyAgyEventCategoryCounts() {
+    return {
+        init: 0,
+        step_update: 0,
+        checkpoint: 0,
+        agent_response: 0,
+        result: 0,
+        tool: 0,
+        permission: 0,
+        error: 0,
+        unknown: 0,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function diagnosticLine(value) {
+    return value.length <= 4_096 ? value : `${value.slice(0, 4_096)}…`;
+}
+/** Parse one complete NDJSON line and require only the stable event envelope. */
+export function parseAgyJsonLine(rawLine, lineNumber = 1, maxLineLength = DEFAULT_MAX_LINE_LENGTH) {
+    // The instance-configured limit travels with the call: an AgyStreamParser
+    // constructed with a larger maxLineLength must not be silently clamped back
+    // to the module default by this second gate.
+    if (rawLine.length > maxLineLength) {
+        throw new AgyParserError(`AGY event line ${lineNumber} exceeds the maximum length`, 'LINE_TOO_LONG', lineNumber, diagnosticLine(rawLine));
+    }
+    let value;
+    try {
+        value = JSON.parse(rawLine);
+    }
+    catch (error) {
+        throw new AgyParserError(`Invalid AGY JSON at line ${lineNumber}`, 'INVALID_JSON_LINE', lineNumber, diagnosticLine(rawLine), { cause: error });
+    }
+    if (!isRecord(value) || typeof value.event !== 'string' || value.event.length === 0) {
+        throw new AgyParserError(`AGY event at line ${lineNumber} must be an object with a non-empty event field`, 'INVALID_EVENT', lineNumber, diagnosticLine(rawLine));
+    }
+    return value;
+}
+/** Incremental parser for arbitrary stdout chunks, including CRLF streams. */
+export class AgyStreamParser {
+    buffer = '';
+    lineNumber = 0;
+    maxLineLength;
+    constructor(options = {}) {
+        this.maxLineLength = options.maxLineLength ?? DEFAULT_MAX_LINE_LENGTH;
+        if (!Number.isSafeInteger(this.maxLineLength) || this.maxLineLength < 1) {
+            throw new RangeError('maxLineLength must be a positive safe integer');
+        }
+    }
+    push(chunk) {
+        this.buffer += chunk;
+        if (this.buffer.length > this.maxLineLength && !this.buffer.includes('\n')) {
+            this.lineNumber += 1;
+            const rawLine = diagnosticLine(this.buffer);
+            this.buffer = '';
+            throw new AgyParserError(`AGY event line ${this.lineNumber} exceeds the maximum length`, 'LINE_TOO_LONG', this.lineNumber, rawLine);
+        }
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() ?? '';
+        return lines.flatMap(line => this.parseLine(line.replace(/\r$/, '')));
+    }
+    end() {
+        if (this.buffer.length === 0)
+            return [];
+        const line = this.buffer.replace(/\r$/, '');
+        this.buffer = '';
+        return this.parseLine(line);
+    }
+    parseLine(line) {
+        this.lineNumber += 1;
+        if (line.length > this.maxLineLength) {
+            throw new AgyParserError(`AGY event line ${this.lineNumber} exceeds the maximum length`, 'LINE_TOO_LONG', this.lineNumber, diagnosticLine(line));
+        }
+        if (line.trim().length === 0)
+            return [];
+        return [parseAgyJsonLine(line, this.lineNumber, this.maxLineLength)];
+    }
+}
+/** Parse an async sequence of stdout chunks without buffering the full stream. */
+export async function* parseAgyChunks(chunks) {
+    const parser = new AgyStreamParser();
+    for await (const chunk of chunks) {
+        yield* parser.push(chunk);
+    }
+    yield* parser.end();
+}
+function nestedRecord(event, key) {
+    const value = event[key];
+    return isRecord(value) ? value : undefined;
+}
+function normalizedKey(key) {
+    return key.toLowerCase().replace(/[-_]/g, '');
+}
+const STRUCTURAL_KEY_NAMES = new Map([
+    ['event', 'event'],
+    ['init', 'init'],
+    ['stepupdate', 'step_update'],
+    ['checkpoint', 'checkpoint'],
+    ['agentresponse', 'agent_response'],
+    ['result', 'result'],
+    ['toolcall', 'tool_call'],
+    ['toolresult', 'tool_result'],
+    ['permissionrequest', 'permission_request'],
+    ['errormessage', 'error_message'],
+    ['error', 'error'],
+    ['steptype', 'step_type'],
+    ['toolname', 'tool_name'],
+    ['toolinput', 'tool_input'],
+    ['state', 'state'],
+    ['name', 'name'],
+    ['recipient', 'recipient'],
+    ['message', 'message'],
+    ['arguments', 'arguments'],
+    ['parameters', 'parameters'],
+    ['input', 'input'],
+    ['args', 'args'],
+]);
+function structuralKeys(value) {
+    if (!isRecord(value))
+        return [];
+    const keys = new Set();
+    for (const key of Object.keys(value)) {
+        const canonical = STRUCTURAL_KEY_NAMES.get(normalizedKey(key));
+        if (canonical !== undefined)
+            keys.add(canonical);
+    }
+    return [...keys].sort();
+}
+function valueForKey(value, key) {
+    if (!isRecord(value))
+        return undefined;
+    const target = normalizedKey(key);
+    for (const [candidate, child] of Object.entries(value)) {
+        if (normalizedKey(candidate) === target)
+            return child;
+    }
+    return undefined;
+}
+function decodeRecord(value) {
+    if (isRecord(value))
+        return value;
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('{') || !trimmed.endsWith('}'))
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Extract the AGY conversation identity emitted by an init event. */
+export function conversationIdOf(event) {
+    if (event.event !== 'init')
+        return undefined;
+    if (typeof event.conversation_id === 'string' && event.conversation_id.length > 0) {
+        return event.conversation_id;
+    }
+    const init = nestedRecord(event, 'init');
+    return typeof init?.conversation_id === 'string' && init.conversation_id.length > 0
+        ? init.conversation_id
+        : undefined;
+}
+function stepUpdateOf(event) {
+    return event.event === 'step_update' ? nestedRecord(event, 'step_update') : undefined;
+}
+/** Return AGY's step type without constraining future event payloads. */
+export function stepTypeOf(event) {
+    const update = stepUpdateOf(event);
+    return typeof update?.step_type === 'string' ? update.step_type : undefined;
+}
+/** Extract an explicit AGY tool name from a step update, when present. */
+export function toolNameOf(event) {
+    const update = stepUpdateOf(event);
+    if (typeof update?.tool_name === 'string')
+        return update.tool_name;
+    if (typeof event.tool_name === 'string')
+        return event.tool_name;
+    for (const key of ['tool_call', 'tool_result']) {
+        const nested = nestedRecord(event, key);
+        if (typeof nested?.tool_name === 'string')
+            return nested.tool_name;
+    }
+    return undefined;
+}
+function decodeNestedString(value) {
+    let current = value.trim();
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        if (!(current.startsWith('"') && current.endsWith('"')))
+            break;
+        try {
+            const decoded = JSON.parse(current);
+            if (typeof decoded !== 'string')
+                break;
+            current = decoded.trim();
+        }
+        catch {
+            break;
+        }
+    }
+    return current;
+}
+function findEncodedFieldCandidates(value, field, candidates = [], depth = 0) {
+    if (depth > 8 || value === null || typeof value !== 'object')
+        return candidates;
+    if (Array.isArray(value)) {
+        for (const child of value)
+            findEncodedFieldCandidates(child, field, candidates, depth + 1);
+        return candidates;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (normalizedKey(key) === normalizedKey(field) && typeof child === 'string') {
+            candidates.push(decodeNestedString(child));
+        }
+        findEncodedFieldCandidates(child, field, candidates, depth + 1);
+    }
+    return candidates;
+}
+/**
+ * Return one unambiguous encoded field. AGY may wrap tool arguments in several
+ * layers; equal duplicates are harmless, but conflicting values must not be
+ * resolved by whichever branch happens to be visited first.
+ */
+function findEncodedField(value, field) {
+    const candidates = [...new Set(findEncodedFieldCandidates(value, field))];
+    return candidates.length === 1 ? candidates[0] : undefined;
+}
+function hasField(value, field, depth = 0) {
+    if (depth > 8 || value === null || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return value.some(child => hasField(child, field, depth + 1));
+    const target = normalizedKey(field);
+    for (const [key, child] of Object.entries(value)) {
+        if (normalizedKey(key) === target)
+            return true;
+        if (hasField(child, field, depth + 1))
+            return true;
+    }
+    return false;
+}
+/** Extract the narrowly-scoped AGY send_message carrier used by DSH-owned mode. */
+export function sendMessageOf(event) {
+    if (toolNameOf(event) !== 'send_message')
+        return undefined;
+    const recipient = findEncodedField(event, 'recipient');
+    const message = findEncodedField(event, 'message');
+    if (recipient === undefined || message === undefined)
+        return undefined;
+    return { recipient, message };
+}
+function stepNameOf(event) {
+    const update = stepUpdateOf(event);
+    return typeof update?.name === 'string' ? update.name : undefined;
+}
+/** Classify only explicit AGY tool lifecycle signals. */
+export function toolEventKindOf(event) {
+    if (event.event === 'tool_call')
+        return 'event-tool-call';
+    if (event.event === 'tool_result')
+        return 'event-tool-result';
+    if (stepTypeOf(event) === 'tool')
+        return 'step-type-tool';
+    if (toolNameOf(event) !== undefined)
+        return 'explicit-tool-name';
+    return undefined;
+}
+/** Recognize internal AGY tool lifecycle events without mapping them to DSH tools. */
+export function isToolEvent(event) {
+    return toolEventKindOf(event) !== undefined;
+}
+/** Classify a tool event's carrier shape without retaining any payload values. */
+export function toolEventDiagnosticOf(event, activeConversationId) {
+    const kind = toolEventKindOf(event);
+    if (kind === undefined)
+        return undefined;
+    const step = stepUpdateOf(event);
+    const stepType = stepTypeOf(event);
+    const toolName = toolNameOf(event);
+    const isSendMessage = toolName === 'send_message';
+    const hasRecipient = isSendMessage && hasField(event, 'recipient');
+    const hasMessage = isSendMessage && hasField(event, 'message');
+    const recipient = isSendMessage ? findEncodedField(event, 'recipient') : undefined;
+    const message = isSendMessage ? findEncodedField(event, 'message') : undefined;
+    let carrierShape = 'not-send-message';
+    if (isSendMessage) {
+        if (!hasRecipient)
+            carrierShape = 'missing-recipient';
+        else if (!hasMessage)
+            carrierShape = 'missing-message';
+        else if (recipient === undefined)
+            carrierShape = 'unreadable-recipient';
+        else if (message === undefined)
+            carrierShape = 'unreadable-message';
+        else
+            carrierShape = 'complete';
+    }
+    const recipientClass = !isSendMessage
+        ? 'not-applicable'
+        : recipient === undefined
+            ? 'missing'
+            : recipient === 'default_api'
+                ? 'default-api'
+                : isDshCarrierRecipient(recipient)
+                    ? 'dsh-recipient'
+                    : activeConversationId !== undefined && recipient === activeConversationId
+                        ? 'self-conversation'
+                        : activeConversationId !== undefined
+                            ? 'other-conversation'
+                            : 'other';
+    const toolInput = decodeRecord(valueForKey(step, 'tool_input'))
+        ?? decodeRecord(valueForKey(event, 'tool_input'))
+        ?? decodeRecord(valueForKey(event, 'arguments'))
+        ?? decodeRecord(valueForKey(event, 'input'));
+    return {
+        eventName: event.event,
+        kind,
+        ...(stepType === undefined ? {} : { stepType }),
+        ...(toolName === undefined ? {} : { toolName }),
+        carrierShape,
+        recipientClass,
+        topLevelKeys: structuralKeys(event),
+        stepKeys: structuralKeys(step),
+        toolInputKeys: structuralKeys(toolInput),
+    };
+}
+/** Recognize permission checkpoints that cannot be answered by a headless Provider. */
+export function isPermissionEvent(event) {
+    const stepType = stepTypeOf(event);
+    return event.event === 'permission_request'
+        || event.event === 'ask_permission'
+        || stepType === 'permission'
+        || stepType === 'permission_request'
+        || stepType === 'ask_permission'
+        || toolNameOf(event) === 'ask_permission'
+        || stepNameOf(event) === 'ask_permission';
+}
+/**
+ * Classify only stable event categories; unknown event names remain forward-compatible.
+ *
+ * A step_update carries its own step_type, so a nested `agent_response` update is
+ * counted as `agent_response` rather than being swallowed by the outer `step_update`
+ * case. Counts must reflect what the model actually emitted: reading `agent_response`
+ * as `step_update` made telemetry report zero streamed text on every turn, even
+ * though AGY streams text deltas natively.
+ */
+export function eventCategoryOf(event) {
+    if (isPermissionEvent(event))
+        return 'permission';
+    if (isToolEvent(event))
+        return 'tool';
+    switch (event.event) {
+        case 'init':
+            return 'init';
+        case 'step_update': {
+            if (stepTypeOf(event) === 'agent_response')
+                return 'agent_response';
+            return 'step_update';
+        }
+        case 'checkpoint':
+            return 'checkpoint';
+        case 'agent_response':
+            return 'agent_response';
+        case 'result':
+            return 'result';
+        case 'error':
+        case 'error_message':
+            return 'error';
+        default:
+            return 'unknown';
+    }
+}
+/**
+ * Bounded JSON of AGY's own `result` frame.
+ *
+ * `status: "ERROR"` is the only signal the adapter gets on the long-context
+ * failures this provider sees, and AGY omits `error` on those frames, so the
+ * `response` text and the remaining keys are the sole surviving diagnosis.
+ * Keys that carry bulk are truncated rather than dropped: a missing key and a
+ * truncated key look identical in telemetry and would be indistinguishable from
+ * "AGY said nothing".
+ */
+export function finalResultRawOf(event) {
+    if (event.event !== 'result')
+        return undefined;
+    const result = isRecord(event.result) ? event.result : undefined;
+    if (result === undefined)
+        return '{}';
+    const bounded = {};
+    for (const [key, value] of Object.entries(result)) {
+        if (typeof value === 'string')
+            bounded[key] = value.length > 512 ? `${value.slice(0, 512)}…(${value.length} chars)` : value;
+        else if (isRecord(value))
+            bounded[key] = '<object>';
+        else
+            bounded[key] = value;
+    }
+    return JSON.stringify(bounded).slice(0, 1_024);
+}
+/** Extract bounded classification detail from AGY error events without exposing the payload. */
+export function errorDetailOf(event) {
+    if (event.event !== 'error' && event.event !== 'error_message')
+        return undefined;
+    const values = [];
+    const direct = event[event.event];
+    if (typeof direct === 'string' && direct.trim().length > 0)
+        values.push(direct.trim());
+    const containers = [event];
+    if (isRecord(direct))
+        containers.push(direct);
+    const error = nestedRecord(event, 'error');
+    if (error !== undefined)
+        containers.push(error);
+    const errorMessage = nestedRecord(event, 'error_message');
+    if (errorMessage !== undefined)
+        containers.push(errorMessage);
+    for (const container of containers) {
+        for (const key of ['code', 'type', 'message', 'detail', 'reason', 'text', 'error']) {
+            const value = container[key];
+            if (typeof value === 'string' && value.trim().length > 0)
+                values.push(value.trim());
+        }
+    }
+    const unique = [...new Set(values)];
+    return unique.length === 0 ? undefined : unique.join(' ').slice(0, 2_048);
+}
+/** Extract a text delta from the observed AGY step_update envelope. */
+export function textDeltaOf(event) {
+    if (event.event !== 'step_update')
+        return undefined;
+    const update = nestedRecord(event, 'step_update');
+    return typeof update?.text_delta === 'string' ? update.text_delta : undefined;
+}
+/** Extract the final response text from a result event. */
+export function responseOf(event) {
+    if (event.event !== 'result')
+        return undefined;
+    const result = nestedRecord(event, 'result');
+    return typeof result?.response === 'string' ? result.response : undefined;
+}
+/** Extract the final AGY result status without constraining future statuses. */
+export function statusOf(event) {
+    if (event.event !== 'result')
+        return undefined;
+    const result = nestedRecord(event, 'result');
+    return typeof result?.status === 'string' ? result.status : undefined;
+}
+/** Extract usage as an opaque object; AGY may add fields across versions. */
+export function usageOf(event) {
+    const container = event.event === 'result'
+        ? nestedRecord(event, 'result')
+        : event.event === 'step_update'
+            ? nestedRecord(event, 'step_update')
+            : undefined;
+    return nestedRecord(container ?? {}, 'usage');
+}
+//# sourceMappingURL=parser.js.map

package/lib/agy/persistent-transport.d.ts

@@ -0,0 +1,101 @@
+import { type AgyReasoningEffort } from './process.js';
+export type PersistentTransportErrorCode = 'ABORTED' | 'DISPOSED' | 'EVENT_HANDLER_FAILED' | 'FRAME_TOO_LARGE' | 'PROTOCOL_ERROR' | 'TIMEOUT' | 'WORKER_BUSY' | 'WORKER_CRASHED' | 'WORKER_ERROR' | 'WORKER_LIMIT' | 'WORKER_START_FAILED' | 'WORKER_STOPPED' | 'OUTPUT_LIMIT' | 'CONVERSATION_MISMATCH';
+export declare class PersistentTransportError extends Error {
+    readonly code: PersistentTransportErrorCode;
+    constructor(message: string, code: PersistentTransportErrorCode, options?: ErrorOptions);
+}
+export type PersistentWorkerState = 'starting' | 'idle' | 'busy' | 'stopping' | 'stopped';
+export interface PersistentRequestFrame {
+    readonly kind: 'request';
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly text: string;
+}
+export interface PersistentShutdownFrame {
+    readonly kind: 'shutdown';
+}
+export type PersistentOutgoingFrame = PersistentRequestFrame | PersistentShutdownFrame;
+export interface PersistentIncomingFrame {
+    readonly kind: 'init' | 'step_update' | 'result';
+    readonly conversationId?: string;
+    readonly raw?: unknown;
+}
+export interface PersistentTransportRequest {
+    readonly sessionId: string;
+    readonly text: string;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    /** Inactivity budget re-armed on every received frame; omitted uses timeoutMs. */
+    readonly idleTimeoutMs?: number;
+    readonly maxOutputBytes?: number;
+    readonly onEvent?: (payload: unknown) => void;
+    /**
+     * Route for a *newly spawned* worker. AGY takes --agent/--model/--effort at
+     * process start, so a worker cannot answer a turn for a different model than
+     * the one it was launched with. These values therefore also key the worker
+     * pool: a request whose route differs from the live worker's gets its own
+     * process instead of silently answering with the wrong model.
+     */
+    readonly agent?: string;
+    readonly model?: string;
+    readonly reasoningEffort?: AgyReasoningEffort;
+    /**
+     * Existing AGY conversation this worker must continue. A freshly spawned
+     * worker is launched with `--conversation <id>`; if AGY answers with a
+     * different conversation_id the request fails with CONVERSATION_MISMATCH
+     * before any delta is emitted, so the caller can fall back to full history
+     * instead of silently answering without context.
+     */
+    readonly conversation?: string;
+    /** Extra argv appended after the route args (mode, slash-command switches). */
+    readonly extraArgs?: readonly string[];
+}
+export interface PersistentTransportResult {
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly events: readonly unknown[];
+    readonly durationMs: number;
+    readonly firstEventMs?: number;
+}
+export interface ExperimentalAgyTransportOptions {
+    readonly executable: string;
+    readonly args?: readonly string[];
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly maxWorkers?: number;
+    readonly maxFrameBytes?: number;
+    readonly maxOutputBytes?: number;
+    readonly maxStderrBytes?: number;
+    readonly idleTtlMs?: number;
+    readonly readyTimeoutMs?: number;
+    readonly shutdownTimeoutMs?: number;
+    readonly defaultRequestTimeoutMs?: number;
+}
+export interface PersistentTransportStats {
+    readonly totalWorkers: number;
+    readonly startingWorkers: number;
+    readonly idleWorkers: number;
+    readonly busyWorkers: number;
+    readonly stoppingWorkers: number;
+    readonly maxWorkers: number;
+    readonly disposed: boolean;
+}
+/** Encode one bounded NDJSON frame, including its trailing newline. */
+export declare function encodePersistentFrame(frame: PersistentOutgoingFrame, maxFrameBytes: number): string;
+/** Parse and validate the small protocol envelope; payload remains opaque. */
+export declare function parsePersistentFrame(line: string): PersistentIncomingFrame;
+/**
+ * Worker-per-route persistent transport. One AGY process per (session, route);
+ * the worker holds a single active turn and is keyed by the route because AGY
+ * fixes --agent/--model/--effort at process start.
+ */
+export declare class ExperimentalAgyTransport {
+    private readonly options;
+    private readonly workers;
+    private disposed;
+    constructor(options: ExperimentalAgyTransportOptions);
+    request(input: PersistentTransportRequest): Promise<PersistentTransportResult>;
+    dispose(): Promise<void>;
+    getStats(): PersistentTransportStats;
+}
+//# sourceMappingURL=persistent-transport.d.ts.map