e2e 0.15.2 → 0.17.0

package/dist/internal/urls.js

@@ -1,7 +1,7 @@
 /** URL normalization and origin policy helpers. */
 import { ConfigurationError } from './errors.js';
 import { testPattern } from './regexp.js';
-import { toTextPattern } from './text.js';
+import { toTextPattern, withIgnoreCase } from './text.js';
 /**
  * Parses and normalizes the app base URL. Rejects userinfo, query, and
  * fragment. WHATWG parsing handles IDNA ASCII hosts, dot segments, and
@@ -94,12 +94,16 @@ export function isLoopbackHost(hostname) {
 export function isImplicitTestHost(hostname) {
     return isLoopbackHost(hostname) || hostname.endsWith('.test');
 }
-const FORBIDDEN_PROTOCOLS = new Set(['file:', 'data:', 'javascript:']);
+const NAVIGABLE_PROTOCOLS = new Set(['http:', 'https:']);
+/** The one non-http(s) page navigation opens: empty, with no local or inline content. */
+const BLANK_PAGE = 'about:blank';
 /**
- * Resolves a navigation URL against the base and refuses the schemes no test
- * may open. Returns the absolute URL string. Any http(s) origin is admitted:
- * a click can reach one just as well, so a gate on typed navigation alone
- * would guard nothing.
+ * Resolves a navigation URL against the base and refuses every scheme but
+ * http(s), except the exact `about:blank`. Returns the absolute URL string.
+ * Any http(s) origin is admitted: a click can reach one just as well, so a
+ * gate on typed navigation alone would guard nothing. The rule is an
+ * allowlist because a browser wraps and nests schemes (`view-source:file:`,
+ * `blob:`, `filesystem:`), and a list of forbidden ones misses the wrapper.
  */
 export function resolveNavigationUrl(input, base) {
     let url;
@@ -114,7 +118,7 @@ export function resolveNavigationUrl(input, base) {
         }
         throw new ConfigurationError('POLICY_DENIED', `malformed URL: ${input}`);
     }
-    if (FORBIDDEN_PROTOCOLS.has(url.protocol)) {
+    if (!NAVIGABLE_PROTOCOLS.has(url.protocol) && url.href !== BLANK_PAGE) {
         throw new ConfigurationError('POLICY_DENIED', `forbidden URL scheme: ${url.protocol}`);
     }
     return { url: url.href };
@@ -160,9 +164,11 @@ export function sameSite(url, site) {
  * Relative expected strings resolve against the base URL; string comparison is
  * exact after WHATWG serialization; regexps test the complete serialized URL.
  * Anything else is `INVALID_ARGUMENT`, the `toTextPattern` rule.
+ * `ignoreCase` is Playwright's: `true` compares a string case-insensitively
+ * and adds the `i` flag to a regexp, `false` removes it.
  */
-export function urlMatches(current, expected, baseHref) {
-    const pattern = toTextPattern(expected);
+export function urlMatches(current, expected, baseHref, ignoreCase) {
+    const pattern = withIgnoreCase(toTextPattern(expected), ignoreCase);
     if (pattern.kind === 'regexp') {
         return testPattern(pattern.source, pattern.flags, serializeForComparison(current));
     }
@@ -173,7 +179,10 @@ export function urlMatches(current, expected, baseHref) {
     catch {
         return false;
     }
-    return serializeForComparison(current) === expectedUrl.href;
+    const actual = serializeForComparison(current);
+    return ignoreCase === true
+        ? actual.toLowerCase() === expectedUrl.href.toLowerCase()
+        : actual === expectedUrl.href;
 }
 function serializeForComparison(url) {
     try {
@@ -183,4 +192,3 @@ function serializeForComparison(url) {
         return url;
     }
 }
-//# sourceMappingURL=urls.js.map

package/dist/internal/vcs.d.ts

@@ -18,4 +18,3 @@ export interface VcsInfo {
  * answers, else from the CI variables GitHub Actions sets, else undefined.
  */
 export declare function detectVcs(projectRoot: string, env: NodeJS.ProcessEnv): Promise<VcsInfo | undefined>;
-//# sourceMappingURL=vcs.d.ts.map

package/dist/internal/vcs.js

@@ -29,4 +29,3 @@ export async function detectVcs(projectRoot, env) {
     const ciBranch = env['GITHUB_HEAD_REF'] || env['GITHUB_REF_NAME'];
     return { commit: ciCommit, ...(ciBranch === undefined || ciBranch === '' ? {} : { branch: ciBranch }) };
 }
-//# sourceMappingURL=vcs.js.map

package/dist/internal/zip.d.ts

@@ -29,4 +29,3 @@ export declare function zipEntry(name: string, data: Uint8Array, like?: Pick<Zip
 /** Serializes entries into one archive. */
 export declare function writeZip(entries: readonly ZipEntry[]): Buffer;
 export {};
-//# sourceMappingURL=zip.d.ts.map

package/dist/internal/zip.js

@@ -180,4 +180,3 @@ function dosStamp(date) {
         dosDate: ((year - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate(),
     };
 }
-//# sourceMappingURL=zip.js.map

package/dist/locator/engine.d.ts

@@ -18,6 +18,11 @@ export declare function attributeOf(node: SemanticNode, name: string): string |
  * empty or absent.
  */
 export declare function denySecureRead(nodes: readonly SemanticNode[], label: string): void;
+/**
+ * What a frame the engine reports missing means to a resolve: `wait` treats
+ * it like a node that is not there yet, `empty` answers zero matches.
+ */
+type MissingFrame = 'wait' | 'empty';
 interface LocatorEngineOptions {
     readonly session: TargetSession;
     /** The running phase's signal and deadline, read per operation. */
@@ -95,8 +100,13 @@ export declare class LocatorEngine {
     /** Reads every current match at once, for `allTextContents`: a missing frame reads as no matches. */
     readAllNow(expression: LocatorExpression): Promise<readonly SemanticNode[]>;
     private readEvery;
-    /** Reads one node for polling surfaces; returns null while zero matches. */
-    tryRead(expression: LocatorExpression, deadline: Deadline): Promise<{
+    /**
+     * Reads one node for polling surfaces; returns null while zero matches.
+     * A poll that waits for absence passes `missingFrame: 'empty'`: nothing
+     * under a frame that is not in the document is attached, so the sample is
+     * zero matches rather than a wait for the frame.
+     */
+    tryRead(expression: LocatorExpression, deadline: Deadline, missingFrame?: MissingFrame): Promise<{
         node: SemanticNode | null;
         count: number;
     }>;
@@ -150,4 +160,3 @@ export declare function locatorDetails(expression: LocatorExpression, waitedMs?:
 /** Translates an engine error into the runner-owned public taxonomy. */
 export declare function translateLocatorError(cause: unknown, expression?: LocatorExpression): E2EError;
 export {};
-//# sourceMappingURL=engine.d.ts.map

package/dist/locator/engine.js

@@ -213,9 +213,14 @@ export class LocatorEngine {
             }
         }
     }
-    /** Reads one node for polling surfaces; returns null while zero matches. */
-    async tryRead(expression, deadline) {
-        return this.readOne(expression, deadline, 'wait');
+    /**
+     * Reads one node for polling surfaces; returns null while zero matches.
+     * A poll that waits for absence passes `missingFrame: 'empty'`: nothing
+     * under a frame that is not in the document is attached, so the sample is
+     * zero matches rather than a wait for the frame.
+     */
+    async tryRead(expression, deadline, missingFrame = 'wait') {
+        return this.readOne(expression, deadline, missingFrame);
     }
     /**
      * Reads the one current match at once, for `isVisible` and `isHidden`:
@@ -378,4 +383,3 @@ export function translateLocatorError(cause, expression) {
     const suffix = expression === undefined ? '' : `: ${describeExpression(expression)}`;
     return translateEngineError(cause, suffix);
 }
-//# sourceMappingURL=engine.js.map

package/dist/locator/expression.d.ts

@@ -28,4 +28,3 @@ export declare function indexExpression(source: LocatorExpression, index: number
 export declare function expressionHints(expression: LocatorExpression): Pick<ErrorDetails, 'role' | 'name' | 'testId'>;
 /** Renders an expression for diagnostics. */
 export declare function describeExpression(expression: LocatorExpression): string;
-//# sourceMappingURL=expression.d.ts.map

package/dist/locator/expression.js

@@ -140,4 +140,3 @@ export function describeExpression(expression) {
             return `frameLocator(${JSON.stringify(expression.selector)}) >> ${describeExpression(expression.source)}`;
     }
 }
-//# sourceMappingURL=expression.js.map

package/dist/locator/screen.d.ts

@@ -32,4 +32,3 @@ export declare function createScreen(context: ScreenContext): Screen;
 export declare function createScopedScreen(context: ScreenContext, wrap: (expression: LocatorExpression) => LocatorExpression): Screen;
 /** Creates a public locator from a raw expression (a contributed fixture's platform selector). */
 export declare function createLocator(context: ScreenContext, expression: LocatorExpression): Locator;
-//# sourceMappingURL=screen.d.ts.map

package/dist/locator/screen.js

@@ -55,6 +55,27 @@ const TEXT_OPTION_KEYS = ['exact', 'visible'];
 const ROLE_FILTER_KEYS = [...TEXT_OPTION_KEYS, 'checked', 'disabled', 'selected', 'expanded', 'pressed', 'level'];
 /** The keys of `RoleOptions`: the accessible name and the filters. */
 const ROLE_OPTION_KEYS = ['name', ...ROLE_FILTER_KEYS];
+/** The states `locator.waitFor` waits for, Playwright's four. */
+const WAIT_FOR_STATES = ['attached', 'detached', 'visible', 'hidden'];
+/** The states absence satisfies: a frame missing from the document reads as zero matches for them. */
+const ABSENCE_STATES = new Set(['detached', 'hidden']);
+/**
+ * Whether the one match, or its absence, is in `state`: `attached` is any
+ * match, `detached` none, `visible` a match that is not hidden, and `hidden`
+ * a hidden match or none.
+ */
+function inWaitForState(node, state) {
+    switch (state) {
+        case 'attached':
+            return node !== null;
+        case 'detached':
+            return node === null;
+        case 'visible':
+            return isNodeVisible(node);
+        case 'hidden':
+            return !isNodeVisible(node);
+    }
+}
 class ScreenImpl {
     context;
     scope;
@@ -361,7 +382,11 @@ class LocatorImpl extends ScreenImpl {
         return nodes.map((node) => normalizeText(node.text ?? ''));
     }
     async waitFor(options) {
-        const state = options?.state ?? 'visible';
+        rejectUnknownOptions('waitFor', options, ['state', 'timeout']);
+        const state = options?.state === undefined ? 'visible' : options.state;
+        if (!WAIT_FOR_STATES.includes(state)) {
+            throw new TestError('INVALID_ARGUMENT', `waitFor state must be one of ${WAIT_FOR_STATES.join(', ')}, got ${JSON.stringify(state)}`);
+        }
         await this.context.steps.run('locator', 'locator.waitFor', `${this.label} → ${state}`, async () => {
             const { engine } = this.context;
             const deadline = engine.deadline(options?.timeout);
@@ -371,9 +396,8 @@ class LocatorImpl extends ScreenImpl {
                 signal: engine.signal,
                 negated: false,
                 evaluate: async () => {
-                    const { node } = await engine.tryRead(this.expression, deadline);
-                    const visible = isNodeVisible(node);
-                    return state === 'visible' ? visible : !visible;
+                    const { node } = await engine.tryRead(this.expression, deadline, ABSENCE_STATES.has(state) ? 'empty' : 'wait');
+                    return inWaitForState(node, state);
                 },
                 onTimeout: () => new TestError('LOCATOR_NOT_FOUND', `locator did not become ${state}: ${this.label}`, {
                     details: locatorDetails(this.expression, Date.now() - startedMs),
@@ -482,4 +506,3 @@ function requireModifiers(value, api) {
     }
     return modifiers.length === 0 ? {} : { modifiers };
 }
-//# sourceMappingURL=screen.js.map

package/dist/mcp/catalog.d.ts

@@ -12,6 +12,7 @@
  */
 import type { ToolSet } from 'ai';
 import type { StepExecutorContext } from '../agent/executor.ts';
+import { type NodeRedaction } from '../agent/observation.ts';
 import type { ScreenPresenter } from '../agent/screen-update.ts';
 import type { LocatorExpression, SemanticNode, TargetSession } from '../engine/surface.ts';
 import type { LocatorEngine } from '../locator/engine.ts';
@@ -24,6 +25,8 @@ export interface SessionCatalog {
     readonly tools: ToolSet;
     /** The tools that change nothing on the app. */
     readonly readOnly: ReadonlySet<string>;
+    /** The project's own tools among them. */
+    readonly project: ReadonlySet<string>;
 }
 export interface CatalogOptions {
     readonly context: StepExecutorContext;
@@ -33,10 +36,12 @@ export interface CatalogOptions {
     /** The agent's project tools (`agents.<name>.tools`), served beside the built-in ones. */
     readonly tools: Readonly<Record<string, AgentTool>>;
     /** The attempt's secret ledger: what `locate` shows of a node passes through it, as `observe` does. */
-    readonly redact: (text: string) => string;
+    readonly redaction: NodeRedaction;
     /** The session's recorder, when the engine records video. */
     readonly recorder: SessionRecorder | undefined;
     readonly warn: (message: string) => void;
+    /** Told the cause of every grammar action that failed into a result. */
+    readonly onActionFailed?: ((cause: unknown) => void) | undefined;
 }
 /** Builds the session's catalog from the step context and the target. */
 export declare function createSessionCatalog(options: CatalogOptions): SessionCatalog;
@@ -56,5 +61,4 @@ export interface LocateQuery {
 /** Builds the expression and the matching `screen.*` call from the tool arguments. */
 export declare function locateQuery(args: LocateArgs): LocateQuery;
 /** Renders a locate result: the count, the verdict a test would get, and the nodes, each through the attempt's redactor. */
-export declare function describeLocate(query: LocateQuery, count: number, nodes: readonly SemanticNode[], redact: (text: string) => string): string;
-//# sourceMappingURL=catalog.d.ts.map
+export declare function describeLocate(query: LocateQuery, count: number, nodes: readonly SemanticNode[], redaction: NodeRedaction): string;

package/dist/mcp/catalog.js

@@ -12,7 +12,7 @@
  */
 import { z } from 'zod';
 import { projectTools } from '../agent/default-agent.js';
-import { projectTree } from '../agent/observation.js';
+import { projectTree, redactNode } from '../agent/observation.js';
 import { GRAMMAR_TOOL_NAMES } from '../agent/action-names.js';
 import { createGrammarTools } from '../agent/primitives.js';
 import { ConfigurationError } from '../internal/errors.js';
@@ -29,12 +29,12 @@ export function createSessionCatalog(options) {
     const { context, screen } = options;
     // The grammar's own observe reports a diff for the model loop; the
     // session's shows the whole screen, so it replaces the grammar's.
-    const { observe: _diffObserve, ...verbs } = createGrammarTools(context, { screen });
+    const { observe: _diffObserve, ...verbs } = createGrammarTools(context, { screen, onActionFailed: options.onActionFailed });
     const recording = options.recorder === undefined ? {} : recordingTools(options.recorder);
     const builtIn = {
         observe: fullObserveTool(context, screen),
         ...verbs,
-        locate: locateTool(options.locator, options.session, options.redact),
+        locate: locateTool(options.locator, options.session, options.redaction),
         ...recording,
     };
     const defined = options.tools;
@@ -49,7 +49,7 @@ export function createSessionCatalog(options) {
         if (defined[name]?.annotations.mutates === false)
             readOnly.add(name);
     }
-    return { tools: { ...builtIn, ...project }, readOnly };
+    return { tools: { ...builtIn, ...project }, readOnly, project: new Set(Object.keys(project)) };
 }
 /**
  * The session's `observe`: the whole screen, every time. Action results
@@ -65,7 +65,7 @@ function fullObserveTool(context, screen) {
     };
 }
 /** The session's `locate`: a semantic locator tried against the live screen, with the verdict a test would get. */
-function locateTool(locator, session, redact) {
+function locateTool(locator, session, redaction) {
     return {
         description: 'Try a semantic locator against the live screen before writing it into a test: screen.getByRole(role, name), getByText, getByLabel, getByPlaceholder, or getByTestId. Returns how many nodes match and which, plus the test code to use. Exactly one of role, text, label, placeholder, or testId; name narrows a role query. Matching is exact unless exact is false.',
         inputSchema: z.object({
@@ -84,7 +84,7 @@ function locateTool(locator, session, redact) {
             for (const ref of refs.slice(0, MAX_LOCATE_NODES)) {
                 read.push(await session.read(ref, locator.operation()));
             }
-            return describeLocate(query, refs.length, read, redact);
+            return describeLocate(query, refs.length, read, redaction);
         },
     };
 }
@@ -115,7 +115,7 @@ export function locateQuery(args) {
     return { expression: textQuery('placeholder', placeholder, { exact }, undefined), code: `screen.getByPlaceholder(${JSON.stringify(placeholder)}${options})` };
 }
 /** Renders a locate result: the count, the verdict a test would get, and the nodes, each through the attempt's redactor. */
-export function describeLocate(query, count, nodes, redact) {
+export function describeLocate(query, count, nodes, redaction) {
     const lines = [`${count === 1 ? '1 node matches' : `${count} nodes match`} ${describeExpression(query.expression)}.`];
     if (count === 1)
         lines.push(`Use: ${query.code}`);
@@ -124,7 +124,7 @@ export function describeLocate(query, count, nodes, redact) {
     else
         lines.push(`A test action on ${query.code} would fail with LOCATOR_AMBIGUOUS. Narrow it with a name, getByRole(role, name), .filter({ hasText }), .first(), or .nth(i), or scope it under a container.`);
     for (const node of nodes)
-        lines.push(`- ${describeNode(projectTree(node, redact))}`);
+        lines.push(`- ${describeNode(projectTree(redactNode(node, redaction)))}`);
     if (count > nodes.length)
         lines.push(`- and ${count - nodes.length} more`);
     return lines.join('\n');
@@ -149,4 +149,3 @@ function describeNode(node) {
         parts.push(`[${states.join(', ')}]`);
     return parts.join(' ');
 }
-//# sourceMappingURL=catalog.js.map

package/dist/mcp/config.d.ts

@@ -20,4 +20,3 @@ export declare function locateProjectConfig(options: ProjectOptions): string;
  * config. The project root is the config's directory.
  */
 export declare function loadProjectConfig(configPath: string, env: NodeJS.ProcessEnv): Promise<LoadedConfig>;
-//# sourceMappingURL=config.d.ts.map

package/dist/mcp/config.js

@@ -21,4 +21,3 @@ export async function loadProjectConfig(configPath, env) {
     const raw = await loadConfigModule(configPath, { graph: true });
     return { ...resolveConfig(raw, { projectRoot: path.dirname(configPath), configPath, env }), configPath };
 }
-//# sourceMappingURL=config.js.map

package/dist/mcp/recording.d.ts

@@ -74,4 +74,3 @@ export declare class SessionRecorder {
 export declare function describeRecording(recording: FinishedRecording): string;
 /** The session's `start_recording` and `stop_recording` tools. */
 export declare function recordingTools(recorder: SessionRecorder): ToolSet;
-//# sourceMappingURL=recording.d.ts.map

package/dist/mcp/recording.js

@@ -152,4 +152,3 @@ export function recordingTools(recorder) {
         },
     };
 }
-//# sourceMappingURL=recording.js.map

package/dist/mcp/server.d.ts

@@ -7,6 +7,12 @@
  * it the process's and a test hands it pipes.
  */
 import type { Readable, Writable } from 'node:stream';
+import type { McpSessionSummary } from './usage.ts';
+/** The client as it named itself in `initialize`. */
+export interface McpClient {
+    readonly name: string;
+    readonly version: string;
+}
 export interface ServeOptions {
     readonly cwd: string;
     /** The config every session loads unless `open_session` names one. */
@@ -25,7 +31,8 @@ export interface ServeOptions {
     readonly log: (line: string) => void;
     /** Ends the server from outside: a process signal. */
     readonly signal?: AbortSignal | undefined;
+    /** Told once per `open_session`, when its session closes or its open fails, with the client that asked; undefined before `initialize`. */
+    readonly onSessionEnd?: ((summary: McpSessionSummary, client: McpClient | undefined) => void) | undefined;
 }
 /** Serves until the client disconnects or `signal` aborts; resolves with the exit code. */
 export declare function serveMcp(options: ServeOptions): Promise<number>;
-//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.js

@@ -6,8 +6,8 @@
  * config the server started next to. Streams are injected, so the CLI hands
  * it the process's and a test hands it pipes.
  */
-import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { readGuide, skillTopics } from '../cli/skill.js';
 import { ConfigurationError, errorMessage } from '../internal/errors.js';
 import { loadProjectConfig, locateProjectConfig } from './config.js';
@@ -34,16 +34,20 @@ export async function serveMcp(options) {
         maxSessions: options.maxSessions,
         defaultTarget: options.target,
         log,
+        onSessionEnd: (summary) => {
+            const client = server.server.getClientVersion();
+            options.onSessionEnd?.(summary, client === undefined ? undefined : { name: client.name, version: client.version });
+        },
     });
     for (const spec of host.toolSpecs()) {
         server.registerTool(spec.name, {
             description: spec.description,
             inputSchema: spec.inputSchema,
             annotations: { readOnlyHint: spec.readOnly, openWorldHint: false },
-        }, async (args, extra) => {
+        }, async (args, ctx) => {
             // A failure is a result the agent can react to, never a protocol error.
             try {
-                return await spec.call(args, { signal: extra.signal });
+                return await spec.call(args, { signal: ctx.mcpReq.signal });
             }
             catch (cause) {
                 return errorResult(cause);
@@ -100,4 +104,3 @@ function registerGuide(server) {
         return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text }] };
     });
 }
-//# sourceMappingURL=server.js.map

package/dist/mcp/session.d.ts

@@ -12,6 +12,7 @@
  * restart and the client's tool list never changes.
  */
 import type { LoadedConfig } from './config.ts';
+import { type McpSessionSummary, type SessionEndedBy } from './usage.ts';
 import { type McpToolCallExtra, type McpToolResult, type McpToolSpec } from './tools.ts';
 /** How many sessions `e2e mcp --max-sessions` allows at once, each a browser or a device. */
 export declare const SESSION_BOUNDS: {
@@ -39,6 +40,8 @@ export interface SessionHostOptions {
     readonly ttlMs?: number | undefined;
     /** How many sessions may be open at once, from `--max-sessions`; default `SESSION_BOUNDS.default`. */
     readonly maxSessions?: number | undefined;
+    /** Told once per `open_session`, when its session closes or its open fails. */
+    readonly onSessionEnd?: ((summary: McpSessionSummary) => void) | undefined;
 }
 /** Owns the live sessions, up to the server's limit, and the fixed MCP tools that drive them. */
 export declare class SessionHost {
@@ -60,7 +63,7 @@ export declare class SessionHost {
      */
     open(options: OpenSessionOptions, signal?: AbortSignal): Promise<string>;
     /** Closes one session, the only one when `session` is omitted, and returns what happened; a session already closing returns that close. */
-    close(reason: string, session?: string): Promise<string>;
+    close(reason: string, session?: string, endedBy?: SessionEndedBy): Promise<string>;
     /** Closes every session, for a server that is shutting down; undefined when none was open. */
     closeAll(reason: string): Promise<string | undefined>;
     private teardown;
@@ -101,4 +104,3 @@ export declare class SessionHost {
     private callSpec;
     private closeSpec;
 }
-//# sourceMappingURL=session.d.ts.map

package/dist/mcp/session.js

@@ -12,11 +12,11 @@
  * restart and the client's tool list never changes.
  */
 import { z } from 'zod';
-import { loadAiSdk } from '../agent/ai-sdk.js';
+import { loadAiSdkIfInstalled } from '../agent/ai-sdk.js';
 import { openInteractiveStep } from '../agent/interactive-step.js';
 import { ScreenPresenter } from '../agent/screen-update.js';
 import { secretHandle } from '../secrets.js';
-import { ConfigurationError, errorMessage, InfrastructureError } from '../internal/errors.js';
+import { classifyError, ConfigurationError, errorMessage, InfrastructureError } from '../internal/errors.js';
 import { LocatorEngine } from '../locator/engine.js';
 import { allocateAppPorts } from '../run/app-ports.js';
 import { SharedAppProcesses } from '../run/process-pool.js';
@@ -26,6 +26,7 @@ import { openStandaloneAttempt } from '../run/standalone.js';
 import { createSessionCatalog, isGrammarVerb } from './catalog.js';
 import { describeRecording, SessionRecorder } from './recording.js';
 import { SessionRegistry } from './sessions.js';
+import { SessionUsage } from './usage.js';
 import { actionResult, catalogLine, defineMcpTool, describeToolDetail, errorResult, invokeTool, redactResult, textResult } from './tools.js';
 /** How long one session may live, whatever happens. */
 const SESSION_TTL_MS = 4 * 60 * 60 * 1000;
@@ -64,21 +65,25 @@ export class SessionHost {
      * it, or disconnects, aborts the open and what it started.
      */
     open(options, signal) {
-        return this.sessions.admit((id) => this.openSession(id, options, signal));
+        const usage = new SessionUsage(this.sessions.liveCount, this.options.headed);
+        return this.sessions.admit((id) => this.openSession(id, options, usage, signal)).catch((cause) => {
+            this.options.onSessionEnd?.(usage.openFailed(classifyError(cause).code));
+            throw cause;
+        });
     }
     /** Closes one session, the only one when `session` is omitted, and returns what happened; a session already closing returns that close. */
-    async close(reason, session) {
+    async close(reason, session, endedBy = 'agent') {
         if (session === undefined && !this.sessions.hasLive)
             return 'No session is open.';
-        return this.sessions.close(session, reason, (live) => this.teardown(live, reason));
+        return this.sessions.close(session, reason, (live) => this.teardown(live, reason, endedBy));
     }
     /** Closes every session, for a server that is shutting down; undefined when none was open. */
     async closeAll(reason) {
         this.shutdown.abort();
-        const summaries = await this.sessions.closeAll(reason, (live) => this.teardown(live, reason));
+        const summaries = await this.sessions.closeAll(reason, (live) => this.teardown(live, reason, 'server'));
         return summaries.length === 0 ? undefined : summaries.join('\n');
     }
-    async teardown(live, reason) {
+    async teardown(live, reason, endedBy) {
         if (live.idleTimer !== undefined)
             clearTimeout(live.idleTimer);
         const { value, cleanupErrors } = await this.closeAttempt(live.attempt, live.abort, async () => {
@@ -86,7 +91,7 @@ export class SessionHost {
             const outcome = await live.step.done;
             // The recorder runs this after a start or stop still in flight, even one the step's deadline abandoned.
             return { outcome, saved: await this.saveRecording(live) };
-        });
+        }).finally(() => this.options.onSessionEnd?.(live.usage.closed(endedBy)));
         const lines = [`Session ${live.id} closed (${reason}); ${live.actions} tool calls ran.`];
         if (value.saved !== undefined)
             lines.push(value.saved);
@@ -124,16 +129,31 @@ export class SessionHost {
     call(session, name, args, extra) {
         const live = this.sessions.resolve(session);
         const tool = live.catalog.tools[name];
-        if (tool === undefined)
-            throw this.unknownTool(live, name);
+        live.usage.called(name, live.catalog.project.has(name));
+        if (tool === undefined) {
+            const error = this.unknownTool(live, name);
+            live.usage.failed(error.code);
+            throw error;
+        }
         const redact = live.attempt.agentRuntime.redact;
-        return this.run(live, () => invokeTool(name, tool, args, extra)).then((result) => redactResult(isGrammarVerb(name) ? actionResult(name, result) : result, redact), (cause) => redactResult(errorResult(cause), redact));
+        return this.run(live, () => invokeTool(name, tool, args, extra)).then((result) => {
+            if (!isGrammarVerb(name)) {
+                // A grammar action's failure was counted with its code as it happened; a project tool's result carries none.
+                if (result.isError === true)
+                    live.usage.failed(undefined);
+                return redactResult(result, redact);
+            }
+            return redactResult(actionResult(name, result), redact);
+        }, (cause) => {
+            live.usage.failed(classifyError(cause).code);
+            return redactResult(errorResult(cause), redact);
+        });
     }
-    async openSession(id, options, request) {
-        // The catalog reads the tools' schemas through the AI SDK, synchronously
-        // and on every render, so the optional SDK is loaded once here: a project
-        // without it learns so before an attempt opens a browser.
-        await loadAiSdk();
+    async openSession(id, options, usage, request) {
+        // The catalog renders synchronously, so the optional SDK is loaded once
+        // here when installed. Without it the catalog reads the tools' Standard
+        // Schemas, and only a model-backed call needs the package.
+        await loadAiSdkIfInstalled();
         // The config is claimed before it evaluates: its top-level code resolves
         // secrets against the registry an open session installed, which only
         // knows that session's config.
@@ -143,6 +163,7 @@ export class SessionHost {
         // A session is its own run: a URL declared with port 0 gets a port here.
         const config = await allocateAppPorts(loaded);
         const target = this.resolveTarget(config, options.target);
+        usage.resolved(target.platform, target.engine);
         this.sessions.claimEngine(id, target.name, target.engine);
         const ttlMs = this.options.ttlMs ?? SESSION_TTL_MS;
         const abort = new AbortController();
@@ -186,7 +207,7 @@ export class SessionHost {
                 screen,
                 session: attempt.session,
                 tools: config.agent.tools,
-                redact: attempt.agentRuntime.redact,
+                redaction: { redact: attempt.agentRuntime.redact, redactCut: attempt.agentRuntime.redactCut },
                 recorder,
                 locator: new LocatorEngine({
                     session: attempt.session,
@@ -197,6 +218,7 @@ export class SessionHost {
                     assertionTimeout: config.assertionTimeout,
                 }),
                 warn: (message) => this.options.log('warning', message),
+                onActionFailed: (cause) => usage.failed(classifyError(cause).code),
             });
             const live = {
                 id,
@@ -210,6 +232,7 @@ export class SessionHost {
                 abort,
                 idleTimer: undefined,
                 actions: 0,
+                usage,
             };
             const text = this.openingText(live, config, await this.firstScreen(live));
             // A first screen that came back despite the cancel must not become a live session nobody asked for.
@@ -218,7 +241,7 @@ export class SessionHost {
             opening.removeEventListener('abort', cancel);
             this.sessions.activate(live);
             // A step that ends on its own (the TTL, a hard stop) ends the session.
-            void step.done.then((outcome) => this.endOnItsOwn(live, outcome.error === undefined ? 'the session step concluded' : errorMessage(outcome.error)));
+            void step.done.then((outcome) => this.endOnItsOwn(live, outcome.error === undefined ? 'the session step concluded' : errorMessage(outcome.error), 'step'));
             this.touch(live);
             return text;
         }
@@ -231,11 +254,11 @@ export class SessionHost {
         }
     }
     /** Closes a live session that ended without a close_session: its step concluded, or it sat idle. */
-    endOnItsOwn(live, why) {
+    endOnItsOwn(live, why, endedBy) {
         if (!this.sessions.isLive(live.id))
             return;
         this.options.log('warning', `session ${live.id} ended: ${why}`);
-        this.close(why, live.id).catch((cause) => this.options.log('error', `closing session ${live.id} failed: ${errorMessage(cause)}`));
+        this.close(why, live.id, endedBy).catch((cause) => this.options.log('error', `closing session ${live.id} failed: ${errorMessage(cause)}`));
     }
     /** A recorder writing to `<output>/videos/<session>/`, when the engine records video. */
     recorder(id, config, attempt) {
@@ -345,7 +368,7 @@ export class SessionHost {
         if (live.idleTimer !== undefined)
             clearTimeout(live.idleTimer);
         const idleMs = this.options.idleMs ?? SESSION_IDLE_MS;
-        live.idleTimer = setTimeout(() => this.endOnItsOwn(live, `idle for ${Math.round(idleMs / 60_000)} minutes`), idleMs);
+        live.idleTimer = setTimeout(() => this.endOnItsOwn(live, `idle for ${Math.round(idleMs / 60_000)} minutes`, 'idle'), idleMs);
         live.idleTimer.unref();
     }
     /** Runs one tool body inside the live session's step. */
@@ -404,4 +427,3 @@ export class SessionHost {
         });
     }
 }
-//# sourceMappingURL=session.js.map

package/dist/mcp/sessions.d.ts

@@ -25,6 +25,8 @@ export declare class SessionRegistry<S extends NamedSession> {
     constructor(limit: number);
     /** Whether any session is live. */
     get hasLive(): boolean;
+    /** How many sessions are live. */
+    get liveCount(): number;
     /**
      * Admits a session and runs `open` for it under a fresh id. A session whose
      * open fails leaves once `open` has settled, after the host tore down what
@@ -63,4 +65,3 @@ export declare class SessionRegistry<S extends NamedSession> {
     /** Keeps why a session ended, forgetting the oldest beyond `ENDED_KEPT`. */
     private remember;
 }
-//# sourceMappingURL=sessions.d.ts.map