@wix/pathgrade 0.29.0

package/dist/sdk/judge-tool-runner.js

@@ -0,0 +1,51 @@
+import { runJudgeSession, } from './judge-tool-session.js';
+export async function runJudgeWithTools(scorer, ctx, llm, opts = {}) {
+    const startedAt = Date.now();
+    const retries = getRetryCount(scorer.retry);
+    let last;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        last = await runJudgeSession({ scorer, ctx, llm }, {
+            maxRounds: opts.maxRounds,
+            toolTimeoutMs: opts.toolTimeoutMs,
+            toolExecutor: opts.toolExecutor,
+        });
+        if (last.code !== 'llm_refused' && last.code !== 'invalid_score')
+            break;
+    }
+    return {
+        entry: toEntry(scorer, last),
+        rounds: last.rounds,
+        toolCalls: last.toolCalls,
+        tokenUsage: last.tokenUsage,
+        wallTimeMs: Date.now() - startedAt,
+    };
+}
+function getRetryCount(retry) {
+    if (retry === true)
+        return 1;
+    if (typeof retry === 'number' && Number.isFinite(retry)) {
+        return Math.max(0, Math.floor(retry));
+    }
+    return 0;
+}
+function toEntry(scorer, outcome) {
+    if (outcome.code === null) {
+        return {
+            name: scorer.name,
+            type: 'judge',
+            score: outcome.score,
+            weight: scorer.weight,
+            details: outcome.details,
+            status: 'ok',
+        };
+    }
+    return {
+        name: scorer.name,
+        type: 'judge',
+        score: 0,
+        weight: scorer.weight,
+        details: outcome.details,
+        status: 'error',
+        errorCode: outcome.code,
+    };
+}

package/dist/sdk/judge-tool-session.d.ts

@@ -0,0 +1,47 @@
+import type { ToolCapableLLMPort } from '../utils/llm-types.js';
+import type { JudgeScorer, ScorerContext, TokenUsage } from './types.js';
+import type { LogEntry } from '../types.js';
+import { type RegisteredTool } from './judge-tools.js';
+export type JudgeErrorCode = 'llm_refused' | 'max_rounds' | 'invalid_score' | 'tool_error_unrecoverable' | 'provider_not_supported';
+export interface JudgeToolCallRecord {
+    name: string;
+    input: unknown;
+    ok: boolean;
+    bytes: number;
+    errorMessage?: string;
+}
+export type ToolExecutor = (name: string, input: Record<string, unknown>, ctx: ScorerContext) => Promise<string>;
+export interface JudgeSessionInput {
+    scorer: JudgeScorer;
+    ctx: ScorerContext;
+    llm: ToolCapableLLMPort;
+}
+export interface JudgeSessionOptions {
+    /** Overrides scorer.maxRounds. */
+    maxRounds?: number;
+    /** Per-tool-call timeout (ms). Default 10_000. */
+    toolTimeoutMs?: number;
+    /** Override tool execution dispatch; used by tests and future MCP-backed registries. */
+    toolExecutor?: ToolExecutor;
+    /** Override the tool registry; defaults to DEFAULT_TOOL_REGISTRY. */
+    registry?: ReadonlyMap<string, RegisteredTool>;
+    /** Push `judge_tool_call` entries into `ctx.log` as they happen. Default `true`. When `false`, entries are only returned in `SessionOutcome.logEntries`. */
+    emitLogs?: boolean;
+}
+export type SessionOutcome = {
+    code: null;
+    score: number;
+    details: string;
+    rounds: number;
+    toolCalls: JudgeToolCallRecord[];
+    tokenUsage: TokenUsage;
+    logEntries: LogEntry[];
+} | {
+    code: JudgeErrorCode;
+    details: string;
+    rounds: number;
+    toolCalls: JudgeToolCallRecord[];
+    tokenUsage: TokenUsage;
+    logEntries: LogEntry[];
+};
+export declare function runJudgeSession(input: JudgeSessionInput, options?: JudgeSessionOptions): Promise<SessionOutcome>;

package/dist/sdk/judge-tool-session.js

@@ -0,0 +1,213 @@
+import * as fs from 'fs/promises';
+import { DEFAULT_TOOL_REGISTRY } from './judge-tools.js';
+import { buildToolUseJudgePrompt } from './judge-prompt-builder.js';
+import { getErrorMessage } from './scorer-utils.js';
+const DEFAULT_MAX_ROUNDS = 10;
+const DEFAULT_TOOL_TIMEOUT_MS = 10_000;
+export async function runJudgeSession(input, options = {}) {
+    const { scorer, ctx, llm } = input;
+    const tokenUsage = { inputTokens: 0, outputTokens: 0 };
+    const toolCalls = [];
+    const logEntries = [];
+    const emitLogs = options.emitLogs ?? true;
+    if (typeof llm.callWithTools !== 'function') {
+        return makeOutcome(tokenUsage, toolCalls, logEntries, 0, {
+            code: 'provider_not_supported',
+            details: 'The active LLM provider does not support tool-use judges (no callWithTools). Set ANTHROPIC_API_KEY to use the Anthropic HTTP provider, or remove `tools` from this judge.',
+        });
+    }
+    try {
+        await fs.access(ctx.workspace);
+    }
+    catch {
+        return makeOutcome(tokenUsage, toolCalls, logEntries, 0, {
+            code: 'tool_error_unrecoverable',
+            details: `Workspace does not exist: ${ctx.workspace}`,
+        });
+    }
+    const registry = options.registry ?? DEFAULT_TOOL_REGISTRY;
+    const allowed = new Set(scorer.tools ?? []);
+    const toolSchemas = (scorer.tools ?? []).map((n) => registry.get(n).schema);
+    const maxRounds = options.maxRounds ?? scorer.maxRounds ?? DEFAULT_MAX_ROUNDS;
+    const toolTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
+    const { system, user } = buildToolUseJudgePrompt(scorer, ctx);
+    const messages = [
+        { role: 'user', content: user },
+    ];
+    let rounds = 0;
+    while (rounds < maxRounds) {
+        rounds++;
+        let response;
+        try {
+            response = await llm.callWithTools(messages, {
+                system,
+                tools: toolSchemas,
+                model: scorer.model,
+                cacheControl: scorer.cacheControl,
+            });
+        }
+        catch (err) {
+            return makeOutcome(tokenUsage, toolCalls, logEntries, rounds, {
+                code: 'tool_error_unrecoverable',
+                details: getErrorMessage(err),
+            });
+        }
+        tokenUsage.inputTokens += response.inputTokens ?? 0;
+        tokenUsage.outputTokens += response.outputTokens ?? 0;
+        if (response.kind === 'final') {
+            if (!response.text.trim()) {
+                return makeOutcome(tokenUsage, toolCalls, logEntries, rounds, {
+                    code: 'llm_refused',
+                    details: 'LLM returned empty response with no tool calls',
+                });
+            }
+            const parsed = parseFinalScore(response.text);
+            if (!parsed.ok) {
+                return makeOutcome(tokenUsage, toolCalls, logEntries, rounds, {
+                    code: 'invalid_score',
+                    details: parsed.message,
+                });
+            }
+            return makeOutcome(tokenUsage, toolCalls, logEntries, rounds, {
+                code: null,
+                score: parsed.score,
+                details: parsed.details,
+            });
+        }
+        const outside = response.blocks.find((b) => !allowed.has(b.name));
+        if (outside) {
+            return makeOutcome(tokenUsage, toolCalls, logEntries, rounds, {
+                code: 'tool_error_unrecoverable',
+                details: `LLM requested tool not in allowlist: ${outside.name}`,
+            });
+        }
+        messages.push({
+            role: 'assistant',
+            content: [
+                ...(response.text ? [{ type: 'text', text: response.text }] : []),
+                ...response.blocks,
+            ],
+        });
+        const results = await Promise.allSettled(response.blocks.map(async (block) => {
+            try {
+                const output = await withTimeout(executeTool(block, ctx, registry, options.toolExecutor), toolTimeoutMs);
+                const bytes = Buffer.byteLength(output, 'utf8');
+                const record = {
+                    name: block.name,
+                    input: block.input,
+                    ok: true,
+                    bytes,
+                };
+                toolCalls.push(record);
+                recordToolCallLog(ctx, scorer, record, logEntries, emitLogs);
+                return toolResultBlock(block.id, output, false);
+            }
+            catch (err) {
+                const msg = getErrorMessage(err);
+                const record = {
+                    name: block.name,
+                    input: block.input,
+                    ok: false,
+                    bytes: 0,
+                    errorMessage: msg,
+                };
+                toolCalls.push(record);
+                recordToolCallLog(ctx, scorer, record, logEntries, emitLogs);
+                return toolResultBlock(block.id, msg, true);
+            }
+        }));
+        const userBlocks = results.map((r, i) => {
+            if (r.status === 'fulfilled')
+                return r.value;
+            return toolResultBlock(response.blocks[i].id, getErrorMessage(r.reason), true);
+        });
+        messages.push({ role: 'user', content: userBlocks });
+    }
+    return makeOutcome(tokenUsage, toolCalls, logEntries, rounds, {
+        code: 'max_rounds',
+        details: `Tool-use loop exhausted after ${rounds} rounds — consider increasing maxRounds (current: ${maxRounds}).`,
+    });
+}
+function makeOutcome(tokenUsage, toolCalls, logEntries, rounds, outcome) {
+    if (outcome.code === null) {
+        return {
+            code: null,
+            score: outcome.score,
+            details: outcome.details,
+            rounds,
+            toolCalls,
+            tokenUsage,
+            logEntries,
+        };
+    }
+    return {
+        code: outcome.code,
+        details: outcome.details,
+        rounds,
+        toolCalls,
+        tokenUsage,
+        logEntries,
+    };
+}
+async function executeTool(block, ctx, registry, override) {
+    if (override) {
+        return override(block.name, block.input, ctx);
+    }
+    const tool = registry.get(block.name);
+    if (!tool)
+        throw new Error(`Unknown tool: ${block.name}`);
+    return tool.run(block.input, ctx);
+}
+function toolResultBlock(id, content, isError) {
+    return { type: 'tool_result', tool_use_id: id, content, is_error: isError };
+}
+function recordToolCallLog(ctx, scorer, record, logEntries, emitLogs) {
+    const entry = {
+        type: 'judge_tool_call',
+        timestamp: new Date().toISOString(),
+        judge_tool_call: {
+            name: record.name,
+            input: record.input,
+            ok: record.ok,
+            bytes: record.bytes,
+            errorMessage: record.errorMessage,
+            judge_name: scorer.name,
+        },
+    };
+    logEntries.push(entry);
+    if (emitLogs)
+        ctx.log.push(entry);
+}
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Tool call timed out after ${ms}ms`)), ms);
+        promise.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+    });
+}
+function parseFinalScore(text) {
+    const cleaned = text.replace(/```(?:json)?\s*/g, '').replace(/```/g, '').trim();
+    const jsonMatch = cleaned.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+        return { ok: false, message: `No JSON object found in final response: ${text.slice(0, 200)}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonMatch[0]);
+    }
+    catch (err) {
+        return { ok: false, message: `JSON parse failed: ${getErrorMessage(err)}` };
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return { ok: false, message: 'Final JSON is not an object' };
+    }
+    const obj = parsed;
+    const rawScore = obj.score;
+    const numScore = typeof rawScore === 'number' ? rawScore : parseFloat(String(rawScore));
+    if (!Number.isFinite(numScore) || numScore < 0 || numScore > 1) {
+        return { ok: false, message: `Score out of range or not a number: ${String(rawScore)}` };
+    }
+    const details = typeof obj.details === 'string'
+        ? obj.details
+        : typeof obj.reasoning === 'string' ? obj.reasoning : '';
+    return { ok: true, score: numScore, details };
+}

package/dist/sdk/judge-tools.d.ts

@@ -0,0 +1,29 @@
+import type { ToolEvent } from '../tool-events.js';
+import type { ToolSchema } from '../utils/llm-types.js';
+import type { CodeJudgeToolName, ScorerContext } from './types.js';
+export interface RegisteredTool {
+    schema: ToolSchema;
+    run: (input: Record<string, unknown>, ctx: ScorerContext) => Promise<string>;
+}
+export interface JudgeToolContext {
+    workspace: string;
+}
+/**
+ * Resolve a workspace-relative path, rejecting if the resolved path escapes
+ * the workspace (including via symlinks).
+ *
+ * Real-paths the parent directory and appends the basename. We don't realpath
+ * the full path because fs.realpath throws ENOENT on missing targets; a naive
+ * fallback to path.resolve would not traverse symlinks and could be tricked by
+ * a ..-walk against non-existent paths outside the workspace.
+ *
+ * The lexical fallback for missing-parent paths is unreachable under the tool
+ * allowlist (all tools either require an existing target or use resolveInWorkspace
+ * on a parent that already exists). Kept for defense in depth.
+ */
+export declare function resolveInWorkspace(workspace: string, relPath: string): Promise<string>;
+export declare function readFile(ctx: JudgeToolContext, relPath: string): Promise<string>;
+export declare function listDir(ctx: JudgeToolContext, relPath: string): Promise<string[]>;
+export declare function grep(ctx: JudgeToolContext, pattern: string, relPath?: string): Promise<string>;
+export declare function getToolEvents(events: readonly ToolEvent[], actionFilter?: string): Promise<string>;
+export declare const DEFAULT_TOOL_REGISTRY: ReadonlyMap<CodeJudgeToolName, RegisteredTool>;

package/dist/sdk/judge-tools.js

@@ -0,0 +1,283 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+const READ_FILE_MAX_BYTES = 200 * 1024;
+const GREP_MAX_MATCHES = 50;
+const GREP_MAX_LINE_LEN = 300;
+const GREP_MAX_FILES = 5_000;
+const GREP_MAX_BYTES = 10 * 1024 * 1024;
+const GREP_EXCLUDED_DIRS = new Set(['node_modules']);
+/**
+ * Resolve a workspace-relative path, rejecting if the resolved path escapes
+ * the workspace (including via symlinks).
+ *
+ * Real-paths the parent directory and appends the basename. We don't realpath
+ * the full path because fs.realpath throws ENOENT on missing targets; a naive
+ * fallback to path.resolve would not traverse symlinks and could be tricked by
+ * a ..-walk against non-existent paths outside the workspace.
+ *
+ * The lexical fallback for missing-parent paths is unreachable under the tool
+ * allowlist (all tools either require an existing target or use resolveInWorkspace
+ * on a parent that already exists). Kept for defense in depth.
+ */
+export async function resolveInWorkspace(workspace, relPath) {
+    if (path.isAbsolute(relPath)) {
+        throw new Error(`Path "${relPath}" is outside workspace (absolute paths not allowed)`);
+    }
+    const workspaceReal = await fs.realpath(workspace);
+    const joined = path.resolve(workspaceReal, relPath);
+    const parent = path.dirname(joined);
+    const basename = path.basename(joined);
+    let parentReal;
+    try {
+        parentReal = await fs.realpath(parent);
+    }
+    catch {
+        const norm = path.resolve(workspaceReal, relPath);
+        if (!isInside(workspaceReal, norm)) {
+            throw new Error(`Path "${relPath}" is outside workspace`);
+        }
+        return norm;
+    }
+    const resolved = path.join(parentReal, basename);
+    if (!isInside(workspaceReal, resolved)) {
+        throw new Error(`Path "${relPath}" is outside workspace`);
+    }
+    return resolved;
+}
+function isInside(root, candidate) {
+    const rel = path.relative(root, candidate);
+    if (rel === '')
+        return true;
+    if (rel.startsWith('..'))
+        return false;
+    if (path.isAbsolute(rel))
+        return false;
+    return true;
+}
+/**
+ * Final-containment check for traversal. Realpaths the full target (it must
+ * exist) and rejects if it is not inside the workspace realpath. Used by grep
+ * to refuse following symlinks out of the workspace.
+ */
+async function checkFinalContainment(workspace, absolutePath) {
+    try {
+        const real = await fs.realpath(absolutePath);
+        const workspaceReal = await fs.realpath(workspace);
+        return isInside(workspaceReal, real);
+    }
+    catch {
+        return false;
+    }
+}
+export async function readFile(ctx, relPath) {
+    const resolved = await resolveInWorkspace(ctx.workspace, relPath);
+    let content;
+    try {
+        content = await fs.readFile(resolved, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new Error(`File not found: ${relPath}`);
+        }
+        throw err;
+    }
+    if (Buffer.byteLength(content, 'utf8') > READ_FILE_MAX_BYTES) {
+        const head = content.slice(0, READ_FILE_MAX_BYTES);
+        return `${head}\n[truncated at 200KB]`;
+    }
+    return content;
+}
+export async function listDir(ctx, relPath) {
+    const resolved = await resolveInWorkspace(ctx.workspace, relPath);
+    let entries;
+    try {
+        entries = await fs.readdir(resolved, { withFileTypes: true });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT') {
+            throw new Error(`Directory not found: ${relPath}`);
+        }
+        if (code === 'ENOTDIR') {
+            throw new Error(`Not a directory: ${relPath}`);
+        }
+        throw err;
+    }
+    return entries.map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+}
+export async function grep(ctx, pattern, relPath) {
+    const rootRel = relPath ?? '.';
+    const root = await resolveInWorkspace(ctx.workspace, rootRel);
+    const workspaceReal = await fs.realpath(ctx.workspace);
+    const regex = new RegExp(pattern);
+    const matches = [];
+    let filesVisited = 0;
+    let bytesRead = 0;
+    let boundedOut = false;
+    function collectMatches(filePath, content) {
+        const displayPath = path.relative(workspaceReal, filePath);
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (matches.length >= GREP_MAX_MATCHES)
+                break;
+            if (!regex.test(lines[i]))
+                continue;
+            let text = lines[i];
+            if (text.length > GREP_MAX_LINE_LEN) {
+                text = `${text.slice(0, GREP_MAX_LINE_LEN)}[truncated]`;
+            }
+            matches.push(`${displayPath}:${i + 1}:${text}`);
+        }
+    }
+    async function scanFile(full) {
+        filesVisited++;
+        if (filesVisited > GREP_MAX_FILES) {
+            boundedOut = true;
+            return;
+        }
+        let content;
+        try {
+            content = await fs.readFile(full, 'utf8');
+        }
+        catch {
+            return;
+        }
+        bytesRead += Buffer.byteLength(content, 'utf8');
+        if (bytesRead > GREP_MAX_BYTES) {
+            boundedOut = true;
+            return;
+        }
+        collectMatches(full, content);
+    }
+    async function walk(dir) {
+        if (matches.length >= GREP_MAX_MATCHES || boundedOut)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (matches.length >= GREP_MAX_MATCHES || boundedOut)
+                return;
+            if (entry.name.startsWith('.'))
+                continue;
+            if (entry.isDirectory() && GREP_EXCLUDED_DIRS.has(entry.name))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (!(await checkFinalContainment(workspaceReal, full)))
+                continue;
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                await scanFile(full);
+            }
+        }
+    }
+    let rootStat;
+    try {
+        rootStat = await fs.stat(root);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            throw new Error(`Directory not found: ${rootRel}`);
+        throw err;
+    }
+    if (rootStat.isFile()) {
+        await scanFile(root);
+    }
+    else {
+        await walk(root);
+    }
+    const out = matches.join('\n');
+    if (matches.length >= GREP_MAX_MATCHES) {
+        return `${out}\n[truncated at ${GREP_MAX_MATCHES} matches]`;
+    }
+    if (boundedOut) {
+        return `${out}\n[traversal truncated: exceeded ${GREP_MAX_FILES} files or ${GREP_MAX_BYTES / (1024 * 1024)}MB]`;
+    }
+    return out;
+}
+export async function getToolEvents(events, actionFilter) {
+    const filtered = actionFilter
+        ? events.filter((e) => e.action.includes(actionFilter))
+        : events;
+    return JSON.stringify(filtered);
+}
+export const DEFAULT_TOOL_REGISTRY = new Map([
+    ['readFile', {
+            schema: {
+                name: 'readFile',
+                description: 'Read the contents of a file inside the workspace. Content is truncated at 200KB.',
+                input_schema: {
+                    type: 'object',
+                    properties: { path: { type: 'string', description: 'Workspace-relative path' } },
+                    required: ['path'],
+                },
+            },
+            async run(input, ctx) {
+                const p = input.path;
+                if (typeof p !== 'string' || !p)
+                    throw new Error('readFile: missing or invalid "path" argument');
+                return readFile({ workspace: ctx.workspace }, p);
+            },
+        }],
+    ['listDir', {
+            schema: {
+                name: 'listDir',
+                description: 'List entries in a directory (one level). Directory names get a trailing "/".',
+                input_schema: {
+                    type: 'object',
+                    properties: { path: { type: 'string' } },
+                    required: ['path'],
+                },
+            },
+            async run(input, ctx) {
+                const p = input.path;
+                if (typeof p !== 'string' || !p)
+                    throw new Error('listDir: missing or invalid "path" argument');
+                const entries = await listDir({ workspace: ctx.workspace }, p);
+                return entries.join('\n');
+            },
+        }],
+    ['grep', {
+            schema: {
+                name: 'grep',
+                description: 'Search a regex pattern through workspace files. Returns path:line:text matches, capped at 50. Dotfiles and node_modules excluded.',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        pattern: { type: 'string', description: 'Regex pattern (anchored with ^/$ for full line)' },
+                        path: { type: 'string', description: 'Optional sub-path to scope the search' },
+                    },
+                    required: ['pattern'],
+                },
+            },
+            async run(input, ctx) {
+                const pattern = input.pattern;
+                if (typeof pattern !== 'string' || !pattern) {
+                    throw new Error('grep: missing or invalid "pattern" argument');
+                }
+                const scope = typeof input.path === 'string' && input.path ? input.path : undefined;
+                return grep({ workspace: ctx.workspace }, pattern, scope);
+            },
+        }],
+    ['getToolEvents', {
+            schema: {
+                name: 'getToolEvents',
+                description: 'Retrieve the agent session tool events as JSON. Optional actionFilter substring-matches against event.action.',
+                input_schema: {
+                    type: 'object',
+                    properties: { actionFilter: { type: 'string' } },
+                },
+            },
+            async run(input, ctx) {
+                const filter = typeof input.actionFilter === 'string' ? input.actionFilter : undefined;
+                return getToolEvents(ctx.toolEvents, filter);
+            },
+        }],
+]);

package/dist/sdk/managed-session.d.ts

@@ -0,0 +1,50 @@
+import type { AgentTurnResult, LogEntry } from '../types.js';
+import type { Workspace } from '../providers/workspace.js';
+import type { AgentName, AgentTransport, Message } from './types.js';
+import type { LLMPort } from '../utils/llm-types.js';
+import type { AskBus } from './ask-bus/types.js';
+export interface ManagedSessionDeps {
+    ws: Workspace;
+    agentName: AgentName;
+    timeoutSec: number;
+    messages: Message[];
+    log: LogEntry[];
+    model?: string;
+    conversationWindow?: import('./types.js').ConversationWindowConfig | false;
+    llm?: LLMPort;
+    /**
+     * Per-conversation ceiling (ms) for live `ask_user` resolution. Threaded
+     * into `createAskBus` at session construction.
+     */
+    askUserTimeoutMs?: number;
+    /**
+     * Pre-constructed bus. When provided, the managed session uses it and does
+     * not create its own. Test/advanced paths can plug in a custom bus; normal
+     * callers should omit this and rely on default construction.
+     */
+    askBus?: AskBus;
+    /**
+     * Resolved Codex transport. When omitted, runtime-policy planning and
+     * driver capabilities fall back to the default (`exec` semantics).
+     */
+    transport?: AgentTransport;
+}
+export interface ManagedSession {
+    /** Full lifecycle: log start/result, push messages, check exit code. */
+    send(message: string): Promise<string>;
+    /** Raw turn execution — returns AgentTurnResult. Caller handles logging. */
+    executeTurn(message: string): Promise<AgentTurnResult>;
+    /** Remaining ms before the session-level deadline. */
+    remainingMs(): number;
+    /** Per-conversation ask-user bus. */
+    readonly askBus: AskBus;
+    /**
+     * Tear down the underlying agent session (close transport, kill subprocess,
+     * release stdio). Optional so that existing mocks and legacy drivers
+     * without teardown work unchanged. Idempotent; safe to call before any
+     * turn has run; a no-op for agents whose sessions do not implement
+     * {@link AgentSession.dispose}.
+     */
+    dispose?(): Promise<void>;
+}
+export declare function createManagedSession(deps: ManagedSessionDeps): ManagedSession;