@wix/pathgrade 0.29.0

package/dist/sdk/ask-bus/handler.js

@@ -0,0 +1,244 @@
+function isAskUserReaction(reaction) {
+    return 'whenAsked' in reaction;
+}
+function isTextReaction(reaction) {
+    return 'when' in reaction;
+}
+function toAskUserQuestion(q) {
+    return {
+        id: q.id,
+        header: q.header,
+        question: q.question,
+        isOther: q.isOther,
+        isSecret: q.isSecret,
+        options: q.options === null ? null : q.options.map((o) => ({ ...o })),
+    };
+}
+function testRegExp(rx, input) {
+    const previousLastIndex = rx.lastIndex;
+    try {
+        rx.lastIndex = 0;
+        return rx.test(input);
+    }
+    finally {
+        rx.lastIndex = previousLastIndex;
+    }
+}
+function matchesWhenAsked(reaction, question) {
+    if (reaction.whenAsked instanceof RegExp) {
+        return testRegExp(reaction.whenAsked, question.question);
+    }
+    return reaction.whenAsked(question);
+}
+function matchesTextReaction(reaction, question) {
+    if (!testRegExp(reaction.when, question.question))
+        return false;
+    return reaction.unless ? !testRegExp(reaction.unless, question.question) : true;
+}
+function normalizeAnswer(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === 'string')
+        return [raw];
+    return [...raw];
+}
+function callReactionAnswer(reaction, question) {
+    if (typeof reaction.answer === 'function') {
+        // Authoring-bug throws propagate intentionally.
+        const raw = reaction.answer(question);
+        return normalizeAnswer(raw);
+    }
+    return normalizeAnswer(reaction.answer);
+}
+function tryReactionsForQuestion(question, reactions, firedOnce, shadowedByQuestion) {
+    let primary;
+    for (let reactionIndex = 0; reactionIndex < reactions.length; reactionIndex++) {
+        const reaction = reactions[reactionIndex];
+        if (!isAskUserReaction(reaction))
+            continue;
+        if (reaction.once && firedOnce.has(reactionIndex))
+            continue;
+        if (!matchesWhenAsked(reaction, question))
+            continue;
+        const values = callReactionAnswer(reaction, question);
+        if (values === undefined)
+            continue;
+        if (!primary) {
+            primary = { reactionIndex, values };
+        }
+        else {
+            let set = shadowedByQuestion.get(question.id);
+            if (!set) {
+                set = new Set();
+                shadowedByQuestion.set(question.id, set);
+            }
+            set.add(reactionIndex);
+        }
+    }
+    return primary;
+}
+function tryLegacyTextReactionsForQuestion(question, reactions, firedOnce, shadowedByQuestion) {
+    let primary;
+    for (let reactionIndex = 0; reactionIndex < reactions.length; reactionIndex++) {
+        const reaction = reactions[reactionIndex];
+        if (!isTextReaction(reaction))
+            continue;
+        if (reaction.once && firedOnce.has(reactionIndex))
+            continue;
+        if (!matchesTextReaction(reaction, question))
+            continue;
+        if (!primary) {
+            primary = { reactionIndex, values: [reaction.reply] };
+        }
+        else {
+            let set = shadowedByQuestion.get(question.id);
+            if (!set) {
+                set = new Set();
+                shadowedByQuestion.set(question.id, set);
+            }
+            set.add(reactionIndex);
+        }
+    }
+    return primary;
+}
+function applyFallback(question, disposition) {
+    if (disposition === 'decline') {
+        return {
+            answer: { questionId: question.id, values: [], source: 'declined' },
+            unmatched: false,
+        };
+    }
+    if (disposition === 'first-option') {
+        if (question.isSecret) {
+            return {
+                answer: { questionId: question.id, values: [], source: 'declined' },
+                unmatched: true,
+            };
+        }
+        if (question.options && question.options.length > 0) {
+            return {
+                answer: {
+                    questionId: question.id,
+                    values: [question.options[0].label],
+                    source: 'fallback',
+                },
+                unmatched: false,
+            };
+        }
+        // No options — degrades to 'error'.
+        return {
+            answer: { questionId: question.id, values: [], source: 'declined' },
+            unmatched: true,
+        };
+    }
+    // 'error' — respond declined so the handle resolves; caller ends the turn.
+    return {
+        answer: { questionId: question.id, values: [], source: 'declined' },
+        unmatched: true,
+    };
+}
+export function createAskUserHandler(ctx) {
+    const previewByBatch = new Map();
+    let unmatchedError = null;
+    const buildPreviewEntries = (batch, firedReactionIndexes, shadowedIndexes, resolvedAnswersByReaction) => {
+        const entries = [];
+        for (let reactionIndex = 0; reactionIndex < ctx.reactions.length; reactionIndex++) {
+            const reaction = ctx.reactions[reactionIndex];
+            if (!isAskUserReaction(reaction))
+                continue;
+            const fired = firedReactionIndexes.has(reactionIndex);
+            const shadowed = shadowedIndexes.has(reactionIndex);
+            const whenAskedMatched = fired || shadowed
+                || batch.questions.some((q) => matchesWhenAsked(reaction, toAskUserQuestion(q)));
+            let status;
+            if (fired)
+                status = 'fired';
+            else if (shadowed)
+                status = 'shadowed';
+            else
+                status = 'no-match';
+            const entry = {
+                kind: 'ask_user',
+                reactionIndex,
+                whenAskedMatched,
+                fired,
+                status,
+            };
+            if (fired) {
+                const values = resolvedAnswersByReaction.get(reactionIndex);
+                if (values !== undefined)
+                    entry.resolvedAnswers = [...values];
+            }
+            entries.push(entry);
+        }
+        return entries;
+    };
+    const handler = (batch, respond) => {
+        const answers = [];
+        const firedReactionIndexes = new Set();
+        const shadowedByQuestion = new Map();
+        const resolvedAnswersByReaction = new Map();
+        const firedOnceThisBatch = new Set();
+        let anyUnmatched = false;
+        for (const rawQuestion of batch.questions) {
+            const question = toAskUserQuestion(rawQuestion);
+            const currentFired = new Set(ctx.firedOnce);
+            for (const idx of firedOnceThisBatch)
+                currentFired.add(idx);
+            const reactionHit = tryReactionsForQuestion(question, ctx.reactions, currentFired, shadowedByQuestion) ?? tryLegacyTextReactionsForQuestion(question, ctx.reactions, currentFired, shadowedByQuestion);
+            if (reactionHit) {
+                answers.push({
+                    questionId: question.id,
+                    values: reactionHit.values,
+                    source: 'reaction',
+                });
+                firedReactionIndexes.add(reactionHit.reactionIndex);
+                resolvedAnswersByReaction.set(reactionHit.reactionIndex, reactionHit.values);
+                const reaction = ctx.reactions[reactionHit.reactionIndex];
+                if (reaction.once) {
+                    firedOnceThisBatch.add(reactionHit.reactionIndex);
+                }
+                continue;
+            }
+            const fallback = applyFallback(question, ctx.onUnmatchedAskUser);
+            answers.push(fallback.answer);
+            if (fallback.unmatched)
+                anyUnmatched = true;
+        }
+        // Commit once-retirement after batch completes (global across conversation).
+        for (const idx of firedOnceThisBatch)
+            ctx.firedOnce.add(idx);
+        const shadowedIndexes = new Set();
+        for (const set of shadowedByQuestion.values()) {
+            for (const idx of set)
+                shadowedIndexes.add(idx);
+        }
+        previewByBatch.set(batch.batchId, buildPreviewEntries(batch, firedReactionIndexes, shadowedIndexes, resolvedAnswersByReaction));
+        if (batch.lifecycle === 'post-hoc') {
+            // Observability only — bus drops any respond() call at the wire.
+            return;
+        }
+        const resolution = { answers };
+        respond(resolution);
+        if (anyUnmatched && ctx.onUnmatchedAskUser === 'error') {
+            unmatchedError = {
+                batchId: batch.batchId,
+                turnNumber: batch.turnNumber,
+                questionTexts: batch.questions.map((q) => q.question),
+            };
+        }
+        else if (anyUnmatched && ctx.onUnmatchedAskUser === 'first-option') {
+            // 'first-option' falls through to 'error' when no options / isSecret.
+            unmatchedError = {
+                batchId: batch.batchId,
+                turnNumber: batch.turnNumber,
+                questionTexts: batch.questions.map((q) => q.question),
+            };
+        }
+    };
+    return {
+        handler,
+        previewByBatch,
+        getUnmatchedError: () => unmatchedError,
+    };
+}

package/dist/sdk/ask-bus/parsers.d.ts

@@ -0,0 +1,9 @@
+import type { AskBatch } from './types.js';
+import type { ToolRequestUserInputParams } from '../../agents/codex-app-server/protocol/index.js';
+/**
+ * Parse Codex `ToolRequestUserInputParams` (the `item/tool/requestUserInput`
+ * server-request params) into a normalized `AskBatch` with
+ * `lifecycle: 'live'`. Used by the Codex `app-server` driver (slice #6) and by
+ * the adapter-layer parity test (slice #9).
+ */
+export declare function buildAskBatchFromCodexRequestUserInput(params: ToolRequestUserInputParams, turnNumber: number): AskBatch;

package/dist/sdk/ask-bus/parsers.js

@@ -0,0 +1,30 @@
+/**
+ * Parse Codex `ToolRequestUserInputParams` (the `item/tool/requestUserInput`
+ * server-request params) into a normalized `AskBatch` with
+ * `lifecycle: 'live'`. Used by the Codex `app-server` driver (slice #6) and by
+ * the adapter-layer parity test (slice #9).
+ */
+export function buildAskBatchFromCodexRequestUserInput(params, turnNumber) {
+    const questions = params.questions.map((q) => ({
+        id: q.id,
+        ...(q.header ? { header: q.header } : {}),
+        question: q.question,
+        options: q.options === null
+            ? null
+            : q.options.map((o) => ({
+                label: o.label,
+                ...(o.description ? { description: o.description } : {}),
+            })),
+        isOther: q.isOther,
+        isSecret: q.isSecret,
+    }));
+    return {
+        batchId: params.itemId,
+        turnNumber,
+        source: 'codex-app-server',
+        lifecycle: 'live',
+        sourceTool: 'request_user_input',
+        toolUseId: params.itemId,
+        questions,
+    };
+}

package/dist/sdk/ask-bus/projection.d.ts

@@ -0,0 +1,26 @@
+import type { ToolEvent } from '../../tool-events.js';
+import type { AskAnswerSource, AskBatchSnapshot } from './types.js';
+export interface AskUserToolEventQuestionArgument {
+    readonly id: string;
+    readonly header?: string;
+    readonly question: string;
+    readonly isOther: boolean;
+    readonly isSecret: boolean;
+    readonly options: ReadonlyArray<{
+        readonly label: string;
+        readonly description?: string;
+    }> | null;
+    readonly answer?: {
+        readonly values: readonly string[];
+        readonly source: AskAnswerSource;
+    };
+}
+export interface AskUserToolEventArguments {
+    readonly batchId: string;
+    readonly questions: readonly AskUserToolEventQuestionArgument[];
+}
+export type AskUserToolEvent = Omit<ToolEvent, 'action' | 'arguments'> & {
+    readonly action: 'ask_user';
+    readonly arguments: AskUserToolEventArguments;
+};
+export declare function toAskUserToolEvent(snapshot: AskBatchSnapshot): AskUserToolEvent;

package/dist/sdk/ask-bus/projection.js

@@ -0,0 +1,45 @@
+import { buildSummary } from '../../tool-events.js';
+function providerFromSource(source) {
+    if (source === 'codex-app-server')
+        return 'codex';
+    return source;
+}
+export function toAskUserToolEvent(snapshot) {
+    const answersById = new Map();
+    if (snapshot.resolution) {
+        for (const a of snapshot.resolution.answers) {
+            answersById.set(a.questionId, { values: a.values, source: a.source });
+        }
+    }
+    const questions = snapshot.questions.map((q) => {
+        const answer = answersById.get(q.id);
+        return {
+            id: q.id,
+            ...(q.header ? { header: q.header } : {}),
+            question: q.question,
+            isOther: q.isOther,
+            isSecret: q.isSecret,
+            options: q.options === null
+                ? null
+                : q.options.map((o) => ({
+                    label: o.label,
+                    ...(o.description ? { description: o.description } : {}),
+                })),
+            ...(answer ? { answer: { values: [...answer.values], source: answer.source } } : {}),
+        };
+    });
+    const args = {
+        batchId: snapshot.batchId,
+        questions,
+    };
+    return {
+        action: 'ask_user',
+        provider: providerFromSource(snapshot.source),
+        providerToolName: snapshot.sourceTool,
+        turnNumber: snapshot.turnNumber,
+        arguments: args,
+        summary: buildSummary('ask_user', snapshot.sourceTool, args),
+        confidence: 'high',
+        rawSnippet: '',
+    };
+}

package/dist/sdk/ask-bus/types.d.ts

@@ -0,0 +1,69 @@
+export type AskSource = 'claude' | 'codex-app-server' | 'cursor';
+/**
+ * Lifecycle of a question batch — determines whether answers flow back and when.
+ *
+ * - 'live'     — mid-turn, synchronous. Driver MUST await resolution before
+ *                proceeding (Codex app-server ToolRequestUserInput).
+ * - 'post-hoc' — the agent already moved past this question by the time
+ *                pathgrade saw it. Observable but unresolvable (Claude denial;
+ *                Cursor v1). Codex exec simply doesn't emit; no dedicated tag.
+ */
+export type AskLifecycle = 'live' | 'post-hoc';
+export interface AskOption {
+    readonly label: string;
+    readonly description?: string;
+}
+export interface AskQuestion {
+    readonly id: string;
+    readonly header?: string;
+    readonly question: string;
+    readonly options: readonly AskOption[] | null;
+    readonly isOther: boolean;
+    readonly isSecret: boolean;
+}
+export interface AskBatch {
+    readonly batchId: string;
+    readonly turnNumber: number;
+    readonly source: AskSource;
+    readonly lifecycle: AskLifecycle;
+    readonly sourceTool: string;
+    readonly toolUseId?: string;
+    readonly questions: readonly AskQuestion[];
+}
+export type AskAnswerSource = 'reaction' | 'fallback' | 'declined';
+export interface AskAnswer {
+    readonly questionId: string;
+    readonly values: readonly string[];
+    readonly source: AskAnswerSource;
+}
+export interface AskResolution {
+    readonly answers: readonly AskAnswer[];
+}
+export interface AskAnswerSnapshot {
+    readonly questionId: string;
+    /** isSecret answers with source='reaction' or 'fallback' appear here as ['<redacted>']. */
+    readonly values: readonly string[];
+    readonly source: AskAnswerSource;
+}
+export interface AskResolutionSnapshot {
+    readonly answers: readonly AskAnswerSnapshot[];
+}
+export interface AskBatchSnapshot extends AskBatch {
+    readonly resolution: AskResolutionSnapshot | null;
+}
+export type AskHandler = (batch: AskBatch, respond: (resolution: AskResolution) => void) => void;
+export type Unsubscribe = () => void;
+export interface AskHandle {
+    readonly batchId: string;
+    /**
+     * Resolves to the resolution the first subscriber provided, or null for
+     * post-hoc batches. Always resolves — never pending forever.
+     * Timeout-bounded for 'live' lifecycle.
+     */
+    readonly resolution: Promise<AskResolution | null>;
+}
+export interface AskBus {
+    emit(batch: AskBatch): AskHandle;
+    onAsk(handler: AskHandler): Unsubscribe;
+    snapshot(turnNumber?: number): readonly AskBatchSnapshot[];
+}

package/dist/sdk/ask-bus/types.js

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

package/dist/sdk/chat.d.ts

@@ -0,0 +1,29 @@
+import type { AgentTurnResult, CommandResult, LogEntry } from '../types.js';
+import type { ChatSession, Message } from './types.js';
+import type { VerboseEmitter } from '../reporters/verbose-emitter.js';
+export interface ChatSessionDeps {
+    /** Mutable reference to the trial's messages array */
+    messages: Message[];
+    /** Mutable reference to the trial's log array */
+    log: LogEntry[];
+    /** Run a command in the trial workspace */
+    exec: (cmd: string) => Promise<CommandResult>;
+    /** Send a reply to the agent with per-turn timeout handling */
+    sendTurn: (message: string) => Promise<AgentTurnResult>;
+    /** Verbose event sink (no-op when disabled) */
+    verbose?: VerboseEmitter;
+}
+export declare class ChatSessionImpl implements ChatSession {
+    private _turn;
+    private _done;
+    private _lastMessage;
+    private deps;
+    constructor(firstTurnResult: AgentTurnResult, deps: ChatSessionDeps);
+    get turn(): number;
+    get done(): boolean;
+    get lastMessage(): string;
+    get messages(): Message[];
+    reply(message: string): Promise<void>;
+    hasFile(pattern: string): Promise<boolean>;
+    end(): void;
+}

package/dist/sdk/chat.js

@@ -0,0 +1,93 @@
+import { buildModelAgentResultLogEntry } from './agent-result-log.js';
+import { getVisibleAssistantMessage } from './visible-turn.js';
+export class ChatSessionImpl {
+    _turn;
+    _done = false;
+    _lastMessage;
+    deps;
+    constructor(firstTurnResult, deps) {
+        this._turn = 1;
+        this._lastMessage = getVisibleAssistantMessage(firstTurnResult);
+        this.deps = deps;
+    }
+    get turn() {
+        return this._turn;
+    }
+    get done() {
+        return this._done;
+    }
+    get lastMessage() {
+        return this._lastMessage;
+    }
+    get messages() {
+        return this.deps.messages;
+    }
+    async reply(message) {
+        if (this._done) {
+            throw new Error('Cannot reply() on a done ChatSession');
+        }
+        const timestamp = () => new Date().toISOString();
+        const turnNumber = this._turn + 1;
+        this.deps.messages.push({ role: 'user', content: message });
+        this.deps.log.push({
+            type: 'user_reply',
+            timestamp: timestamp(),
+            instruction: message,
+            turn_number: turnNumber,
+        });
+        this.deps.verbose?.turnStart({
+            turn: turnNumber,
+            kind: 'user_reply',
+            message: message,
+        });
+        let turnResult;
+        const turnStart = Date.now();
+        try {
+            turnResult = await this.deps.sendTurn(message);
+        }
+        catch (err) {
+            this._done = true;
+            throw err;
+        }
+        const response = getVisibleAssistantMessage(turnResult);
+        const durationMs = Date.now() - turnStart;
+        this.deps.log.push(buildModelAgentResultLogEntry({
+            timestamp: timestamp(),
+            turnNumber,
+            durationMs,
+            turnResult,
+            assistantMessage: response,
+        }));
+        for (const toolEvent of turnResult.toolEvents) {
+            this.deps.log.push({
+                type: 'tool_event',
+                timestamp: timestamp(),
+                tool_event: toolEvent,
+            });
+            this.deps.verbose?.toolEvent({
+                action: toolEvent.action,
+                summary: toolEvent.summary,
+            });
+        }
+        this.deps.messages.push({ role: 'agent', content: response });
+        this.deps.verbose?.turnEnd({
+            turn: turnNumber,
+            durationMs,
+            outputLines: response.split('\n').length,
+            messagePreview: response,
+        });
+        if (turnResult.exitCode !== 0) {
+            this._done = true;
+            throw new Error(`Agent exited with code ${turnResult.exitCode}`);
+        }
+        this._turn = turnNumber;
+        this._lastMessage = response;
+    }
+    async hasFile(pattern) {
+        const result = await this.deps.exec(`ls -d ${pattern} 2>/dev/null`);
+        return result.stdout.trim().length > 0;
+    }
+    end() {
+        this._done = true;
+    }
+}

package/dist/sdk/conversation-window.d.ts

@@ -0,0 +1,14 @@
+import type { LLMPort } from '../utils/llm-types.js';
+import type { Message } from './types.js';
+export interface ConversationWindowOptions {
+    /** Number of recent messages (not turn pairs) to keep verbatim. Default: 4 */
+    windowSize?: number;
+    /** Model to use for summarization. Default: 'claude-haiku-4-5-20251001' */
+    model?: string;
+    /** LLM port for summarization calls. */
+    llm?: LLMPort;
+}
+export interface ConversationWindow {
+    getHistory(messages: Message[]): Promise<string>;
+}
+export declare function createConversationWindow(opts?: ConversationWindowOptions): ConversationWindow;

package/dist/sdk/conversation-window.js

@@ -0,0 +1,38 @@
+export function createConversationWindow(opts = {}) {
+    const windowSize = opts.windowSize ?? 4;
+    const model = opts.model ?? 'claude-haiku-4-5-20251001';
+    const llm = opts.llm;
+    let cachedSummary = null;
+    let summarizedUpTo = 0; // number of messages already summarized
+    return {
+        async getHistory(messages) {
+            // If all messages fit within the window, return them verbatim
+            if (messages.length <= windowSize) {
+                return formatMessages(messages);
+            }
+            // No LLM — can't summarize, return all messages verbatim
+            if (!llm) {
+                return formatMessages(messages);
+            }
+            // Split: older messages get summarized, recent messages stay verbatim
+            const cutoff = messages.length - windowSize;
+            const olderMessages = messages.slice(0, cutoff);
+            const recentMessages = messages.slice(cutoff);
+            // Only re-summarize if there are new messages beyond what we've already summarized
+            if (cutoff > summarizedUpTo || cachedSummary === null) {
+                const toSummarize = cachedSummary
+                    ? `Previous summary: ${cachedSummary}\n\nNew messages:\n${formatMessages(messages.slice(summarizedUpTo, cutoff))}`
+                    : formatMessages(olderMessages);
+                const response = await llm.call(`Summarize this conversation concisely in one paragraph, preserving key facts and decisions:\n\n${toSummarize}`, { model });
+                cachedSummary = response.text.trim();
+                summarizedUpTo = cutoff;
+            }
+            return `## Earlier Context (Summary)\n${cachedSummary}\n\n## Recent Conversation\n${formatMessages(recentMessages)}`;
+        },
+    };
+}
+function formatMessages(messages) {
+    return messages
+        .map(m => `${m.role === 'user' ? 'User' : 'Agent'}: ${m.content}`)
+        .join('\n\n');
+}

package/dist/sdk/converse.d.ts

@@ -0,0 +1,42 @@
+import type { AgentTurnResult, LogEntry } from '../types.js';
+import type { AgentName, AgentTransport, ConversationResult, ConverseOptions, EvalResult, Scorer, Message } from './types.js';
+import type { VerboseEmitter } from '../reporters/verbose-emitter.js';
+import type { AskBus } from './ask-bus/types.js';
+export interface ConversationDeps {
+    /** Send a message to the agent, returns response string. Throws on failure. */
+    sendTurn: (message: string) => Promise<string | AgentTurnResult>;
+    /** Check file existence in workspace */
+    hasFile: (pattern: string) => Promise<boolean>;
+    /** Workspace path */
+    workspace: string;
+    /** Mutable messages array — runner appends user/agent entries */
+    messages: Message[];
+    /** Mutable log array */
+    log: LogEntry[];
+    /** Generate persona reply when no reaction matches */
+    personaReply?: () => Promise<string>;
+    /** Run step scorers */
+    runStepScorers?: (scorers: Scorer[]) => Promise<EvalResult>;
+    /** Verbose event sink (no-op when disabled) */
+    verbose?: VerboseEmitter;
+    /** Per-conversation ask-user bus. When omitted, ask_user reactions never fire. */
+    askBus?: AskBus;
+    /**
+     * Resolved agent name. Surfaced for transport-aware preflight checks.
+     */
+    agentName?: AgentName;
+    /**
+     * Resolved transport (codex only). When `'exec'`, a preflight guard fails
+     * fast at conversation start if any `AskUserReaction` is present without
+     * `allowUnreachableReactions: true`.
+     */
+    transport?: AgentTransport;
+    /**
+     * Per-turn timeout in seconds. Used to format the agent-timeout error
+     * message thrown after `pushModelAgentMessage` records the partial turn.
+     * Optional for callers that supply their own thrown errors via `sendTurn`.
+     */
+    agentTimeoutSec?: number;
+}
+export declare function runConversation(opts: ConverseOptions, deps: ConversationDeps): Promise<ConversationResult>;
+export { previewReactions } from './reaction-preview.js';