@xoxoai/checkmate 0.4.0

package/dist/tools/registry.js

@@ -0,0 +1,46 @@
+import { getToolName } from './types';
+export class ToolRegistry {
+    runtimeConfig;
+    tools = [];
+    toolsByName = new Map();
+    constructor(runtimeConfig) {
+        this.runtimeConfig = runtimeConfig;
+    }
+    register(tool) {
+        const tools = Array.isArray(tool) ? tool : [tool];
+        for (const registeredTool of tools) {
+            const toolName = getToolName(registeredTool);
+            if (this.toolsByName.has(toolName)) {
+                throw new Error(`Duplicate tool registration for '${toolName}'`);
+            }
+            this.tools.push(registeredTool);
+            this.toolsByName.set(toolName, registeredTool);
+        }
+    }
+    getRuntimeConfig() {
+        return this.runtimeConfig;
+    }
+    resolve(toolName) {
+        return this.toolsByName.get(toolName);
+    }
+    async getTools() {
+        const allowedNames = this.runtimeConfig.getAllowedFunctionNames();
+        const definitions = this.tools.map((tool) => this.toOpenAiTool(tool));
+        if (allowedNames.length === 0) {
+            return definitions;
+        }
+        return definitions.filter((tool) => allowedNames.includes(tool.function.name));
+    }
+    toOpenAiTool(tool) {
+        return {
+            type: 'function',
+            function: {
+                name: tool.definition.name,
+                description: tool.definition.description,
+                parameters: tool.definition.parameters,
+                strict: tool.definition.strict,
+            },
+        };
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,WAAW,EAAE,MAAM,SAAS,CAAA;AAShD,MAAM,OAAO,YAAY;IAIK;IAHZ,KAAK,GAAgB,EAAE,CAAA;IACvB,WAAW,GAAG,IAAI,GAAG,EAAqB,CAAA;IAE3D,YAA6B,aAA4B;QAA5B,kBAAa,GAAb,aAAa,CAAe;IAAG,CAAC;IAE7D,QAAQ,CAAC,IAA6B;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAEjD,KAAK,MAAM,cAAc,IAAI,KAAK,EAAE,CAAC;YACpC,MAAM,QAAQ,GAAG,WAAW,CAAC,cAAc,CAAC,CAAA;YAC5C,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACpC,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,GAAG,CAAC,CAAA;YACjE,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;YAC/B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAA;QAC/C,CAAC;IACF,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAA;IAC1B,CAAC;IAED,OAAO,CAAC,QAAgB;QACvB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IACtC,CAAC;IAED,KAAK,CAAC,QAAQ;QACb,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC,uBAAuB,EAAE,CAAA;QACjE,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAA;QAErE,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO,WAAW,CAAA;QACnB,CAAC;QAED,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;IAC/E,CAAC;IAEO,YAAY,CAAC,IAAe;QACnC,OAAO;YACN,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE;gBACT,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI;gBAC1B,WAAW,EAAE,IAAI,CAAC,UAAU,CAAC,WAAW;gBACxC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,UAAU;gBACtC,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,MAAM;aAC9B;SACD,CAAA;IACF,CAAC;CACD"}

package/dist/tools/salesforce/login-tool.d.ts

@@ -0,0 +1,7 @@
+import { BrowserToolRuntime } from '../browser/tool';
+import { AgentTool } from '../types';
+export declare const SalesforceLoginTool: {
+    readonly TOOL_LOGIN_TO_SALESFORCE_ORG: "login_to_salesforce_org";
+};
+export declare function createSalesforceTools(browserRuntime: BrowserToolRuntime): AgentTool[];
+//# sourceMappingURL=login-tool.d.ts.map

package/dist/tools/salesforce/login-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login-tool.d.ts","sourceRoot":"","sources":["../../../src/tools/salesforce/login-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEpD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAIpC,eAAO,MAAM,mBAAmB;;CAEtB,CAAA;AAEV,wBAAgB,qBAAqB,CAAC,cAAc,EAAE,kBAAkB,GAAG,SAAS,EAAE,CAoBrF"}

package/dist/tools/salesforce/login-tool.js

@@ -0,0 +1,25 @@
+import { z } from 'zod/v4';
+import { defineAgentTool } from '../define-agent-tool';
+import { SalesforceAuthenticator } from '../../integrations/salesforce/authenticator';
+import { SalesforceCliHandler } from '../../integrations/salesforce/cli-handler';
+export const SalesforceLoginTool = {
+    TOOL_LOGIN_TO_SALESFORCE_ORG: 'login_to_salesforce_org',
+};
+export function createSalesforceTools(browserRuntime) {
+    return [
+        defineAgentTool({
+            name: SalesforceLoginTool.TOOL_LOGIN_TO_SALESFORCE_ORG,
+            description: 'Login to a Salesforce org in a browser. Do not use if Salesforce org is opened and logged in. You do not need to specify credentials, the tool will handle it for you.',
+            schema: z
+                .object({
+                goal: z.string().describe('The goal or purpose of logging into the Salesforce org'),
+            })
+                .strict(),
+            handler: async (_args, context) => {
+                const frontDoorUrl = await new SalesforceAuthenticator(new SalesforceCliHandler()).ready.then((authenticator) => authenticator.getFrontDoorUrl());
+                return browserRuntime.navigateToUrl(frontDoorUrl, context.step);
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=login-tool.js.map

package/dist/tools/salesforce/login-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login-tool.js","sourceRoot":"","sources":["../../../src/tools/salesforce/login-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE1B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,6CAA6C,CAAA;AACrF,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAEhF,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAClC,4BAA4B,EAAE,yBAAyB;CAC9C,CAAA;AAEV,MAAM,UAAU,qBAAqB,CAAC,cAAkC;IACvE,OAAO;QACN,eAAe,CAAC;YACf,IAAI,EAAE,mBAAmB,CAAC,4BAA4B;YACtD,WAAW,EACV,wKAAwK;YACzK,MAAM,EAAE,CAAC;iBACP,MAAM,CAAC;gBACP,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;aACnF,CAAC;iBACD,MAAM,EAAE;YACV,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;gBACjC,MAAM,YAAY,GAAG,MAAM,IAAI,uBAAuB,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAC5F,CAAC,aAAa,EAAE,EAAE,CAAC,aAAa,CAAC,eAAe,EAAE,CAClD,CAAA;gBAED,OAAO,cAAc,CAAC,aAAa,CAAC,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;YAChE,CAAC;SACD,CAAC;KACF,CAAA;AACF,CAAC"}

package/dist/tools/step/result-tool.d.ts

@@ -0,0 +1,7 @@
+import { AgentTool } from '../types';
+export declare const StepResultTool: {
+    readonly TOOL_FAIL_TEST_STEP: "fail_test_step";
+    readonly TOOL_PASS_TEST_STEP: "pass_test_step";
+};
+export declare function createStepResultTools(): AgentTool[];
+//# sourceMappingURL=result-tool.d.ts.map

package/dist/tools/step/result-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-tool.d.ts","sourceRoot":"","sources":["../../../src/tools/step/result-tool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEpC,eAAO,MAAM,cAAc;;;CAGjB,CAAA;AAQV,wBAAgB,qBAAqB,IAAI,SAAS,EAAE,CAmBnD"}

package/dist/tools/step/result-tool.js

@@ -0,0 +1,32 @@
+import { z } from 'zod/v4';
+import { defineAgentTool } from '../define-agent-tool';
+export const StepResultTool = {
+    TOOL_FAIL_TEST_STEP: 'fail_test_step',
+    TOOL_PASS_TEST_STEP: 'pass_test_step',
+};
+const stepResultSchema = z
+    .object({
+    actualResult: z.string().describe('The actual result of the test step'),
+})
+    .strict();
+export function createStepResultTools() {
+    return [
+        defineAgentTool({
+            name: StepResultTool.TOOL_FAIL_TEST_STEP,
+            description: 'Fail the test step with the actual result',
+            schema: stepResultSchema,
+            handler: ({ actualResult }, context) => {
+                context.resolveStepResult({ passed: false, actual: actualResult });
+            },
+        }),
+        defineAgentTool({
+            name: StepResultTool.TOOL_PASS_TEST_STEP,
+            description: 'Pass the test step with the actual result',
+            schema: stepResultSchema,
+            handler: ({ actualResult }, context) => {
+                context.resolveStepResult({ passed: true, actual: actualResult });
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=result-tool.js.map

package/dist/tools/step/result-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-tool.js","sourceRoot":"","sources":["../../../src/tools/step/result-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAGtD,MAAM,CAAC,MAAM,cAAc,GAAG;IAC7B,mBAAmB,EAAE,gBAAgB;IACrC,mBAAmB,EAAE,gBAAgB;CAC5B,CAAA;AAEV,MAAM,gBAAgB,GAAG,CAAC;KACxB,MAAM,CAAC;IACP,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;CACvE,CAAC;KACD,MAAM,EAAE,CAAA;AAEV,MAAM,UAAU,qBAAqB;IACpC,OAAO;QACN,eAAe,CAAC;YACf,IAAI,EAAE,cAAc,CAAC,mBAAmB;YACxC,WAAW,EAAE,2CAA2C;YACxD,MAAM,EAAE,gBAAgB;YACxB,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,EAAE;gBACtC,OAAO,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAA;YACnE,CAAC;SACD,CAAC;QACF,eAAe,CAAC;YACf,IAAI,EAAE,cAAc,CAAC,mBAAmB;YACxC,WAAW,EAAE,2CAA2C;YACxD,MAAM,EAAE,gBAAgB;YACxB,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,EAAE;gBACtC,OAAO,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAA;YAClE,CAAC;SACD,CAAC;KACF,CAAA;AACF,CAAC"}

package/dist/tools/tool-contract.d.ts

@@ -0,0 +1,3 @@
+export type { AgentTool, AgentToolContext, AgentToolDefinition, AgentToolResponse, AgentToolResult, ToolCall, } from './types';
+export { getToolName } from './types';
+//# sourceMappingURL=tool-contract.d.ts.map

package/dist/tools/tool-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-contract.d.ts","sourceRoot":"","sources":["../../src/tools/tool-contract.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,SAAS,EACT,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,QAAQ,GACR,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA"}

package/dist/tools/tool-contract.js

@@ -0,0 +1,2 @@
+export { getToolName } from './types';
+//# sourceMappingURL=tool-contract.js.map

package/dist/tools/tool-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-contract.js","sourceRoot":"","sources":["../../src/tools/tool-contract.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA"}

package/dist/tools/types.d.ts

@@ -0,0 +1,139 @@
+import { ResolveStepResult, Step } from '../runtime/types';
+/**
+ * Normalized tool call emitted by the model.
+ *
+ * @example
+ * ```ts
+ * const call: ToolCall = {
+ *   name: 'browser_click_or_hover',
+ *   arguments: { ref: 'e123', hover: false },
+ * }
+ * ```
+ */
+export type ToolCall = {
+    /**
+     * Tool name requested by the model.
+     */
+    name: string;
+    /**
+     * Parsed tool arguments.
+     */
+    arguments?: unknown;
+};
+/**
+ * Serializable tool definition used by Checkmate.
+ *
+ * @example
+ * ```ts
+ * const definition: AgentToolDefinition = {
+ *   name: 'check_api_health',
+ *   description: 'Check whether the API is healthy',
+ *   parameters: { type: 'object', properties: { url: { type: 'string' } } },
+ *   strict: true,
+ * }
+ * ```
+ */
+export type AgentToolDefinition = {
+    /**
+     * Stable tool name.
+     */
+    name: string;
+    /**
+     * Short tool description shown to the model.
+     */
+    description: string;
+    /**
+     * JSON schema for the tool parameters.
+     */
+    parameters: Record<string, unknown>;
+    /**
+     * Whether the tool arguments should be validated strictly.
+     */
+    strict: boolean;
+};
+/**
+ * Structured tool response returned to the model.
+ *
+ * @example
+ * ```ts
+ * const response: AgentToolResponse = {
+ *   response: 'Clicked the Submit button.',
+ *   status: 'success',
+ * }
+ * ```
+ */
+export type AgentToolResponse = {
+    /**
+     * Human-readable result returned to the model.
+     */
+    response: string;
+    /**
+     * Optional fresh snapshot to append after tool execution.
+     */
+    snapshot?: string | null;
+    /**
+     * Outcome status used in tool execution summaries.
+     */
+    status?: 'success' | 'error';
+};
+/**
+ * Any valid value a tool can return.
+ *
+ * Tools may return a structured response, a plain string, or nothing.
+ *
+ * @example
+ * ```ts
+ * const result: AgentToolResult = {
+ *   response: 'API health is good',
+ *   status: 'success',
+ * }
+ * ```
+ */
+export type AgentToolResult = AgentToolResponse | string | void;
+/**
+ * Context passed to every tool execution.
+ *
+ * @example
+ * ```ts
+ * const handler = async (_args: unknown, context: AgentToolContext) => {
+ *   context.resolveStepResult({ passed: true, actual: context.step.expect })
+ * }
+ * ```
+ */
+export type AgentToolContext = {
+    /**
+     * Step currently being executed.
+     */
+    step: Step;
+    /**
+     * Callback used to finish the step.
+     */
+    resolveStepResult: ResolveStepResult;
+};
+/**
+ * Tool contract used by the runner loop.
+ *
+ * Most users should create tools with `defineTool()` instead of building this object manually.
+ *
+ * @example
+ * ```ts
+ * const tool: AgentTool = defineTool({
+ *   name: 'check_api_health',
+ *   description: 'Check whether the API is healthy',
+ *   schema: z.object({ url: z.string() }).strict(),
+ *   handler: async ({ url }) => `API health is good for ${url}`,
+ * })
+ * ```
+ */
+export type AgentTool = {
+    /**
+     * Tool definition exposed to the model.
+     */
+    definition: AgentToolDefinition;
+    /**
+     * Tool implementation.
+     */
+    execute: (args: unknown, context: AgentToolContext) => Promise<AgentToolResult> | AgentToolResult;
+};
+export declare function getToolName(tool: AgentTool): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAE1D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG;IACtB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEnC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAA;CACf,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC/B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAExB;;OAEG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAAA;AAE/D;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B;;OAEG;IACH,IAAI,EAAE,IAAI,CAAA;IAEV;;OAEG;IACH,iBAAiB,EAAE,iBAAiB,CAAA;CACpC,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG;IACvB;;OAEG;IACH,UAAU,EAAE,mBAAmB,CAAA;IAE/B;;OAEG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAA;CACjG,CAAA;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEnD"}

package/dist/tools/types.js

@@ -0,0 +1,4 @@
+export function getToolName(tool) {
+    return tool.definition.name;
+}
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAwJA,MAAM,UAAU,WAAW,CAAC,IAAe;IAC1C,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAA;AAC5B,CAAC"}

package/docs/EXTENSIONS.md

@@ -0,0 +1,233 @@
+# **_checkmate_** extensions
+
+This guide is about how to adapt **_checkmate_** to your own domain.
+
+Use it when you want to:
+
+- add a new tool
+- add a new extension
+- compose your own runner
+- build on top of `web()` or `salesforce()`
+
+## Core Idea
+
+`@xoxoai/checkmate/core` stays generic.
+
+The runner owns:
+
+- the model loop
+- retries
+- pass/fail resolution
+- tool dispatch
+
+Extensions add domain-specific behavior such as:
+
+- tools
+- system instructions
+- initial step context
+- post-tool context
+- shared capabilities for other extensions
+- teardown logic
+
+That is how `web()` and `salesforce()` work, and it is the same model you use for your own extensions.
+
+## Tool vs Extension
+
+Use `defineTool()` when you need one new action the model can call.
+
+Use `defineExtension()` when you need to bundle tools with runtime behavior such as instructions, setup, or extra context.
+
+Use `createRunner()` when you want to compose your own runtime from built-in and custom extensions.
+
+## Your First Tool
+
+A tool is the smallest unit of behavior.
+
+```typescript
+import { defineTool } from '@xoxoai/checkmate/core'
+import { z } from 'zod/v4'
+
+export const apiHealthTool = defineTool({
+	name: 'check_api_health',
+	description: 'Check whether the API is healthy',
+	schema: z.object({ url: z.string().url() }).strict(),
+	handler: async ({ url }) => {
+		return {
+			response: `API health is good for ${url}`,
+			status: 'success',
+		}
+	},
+})
+```
+
+Good tools are:
+
+- single-purpose
+- concrete
+- easy to describe in one sentence
+- safe to call multiple times
+
+## Your First Extension
+
+An extension can be as small as a name, one tool, and one instruction.
+
+```typescript
+import { createRunner, defineExtension } from '@xoxoai/checkmate/core'
+import { web } from '@xoxoai/checkmate/playwright'
+import { apiHealthTool } from './api-health-tool'
+
+export const apiHealth = defineExtension({
+	name: 'api-health',
+	tools: [apiHealthTool],
+	instructions: ['Use check_api_health before relying on API-driven UI state.'],
+})
+
+const ai = createRunner({
+	extensions: [web({ page }), apiHealth],
+})
+```
+
+This already gives you a reusable building block that can be shared across projects.
+
+## Extension Hooks
+
+Extensions can do more than register tools.
+
+`defineExtension()` supports these hooks:
+
+- `tools`: register one or more tools
+- `instructions`: append system-level guidance for the model
+- `setup(api)`: register capabilities, tools, hooks, or teardown logic
+- `buildInitialMessages(context)`: add step-specific context before the first model call
+- `handleToolResponses(context)`: append fresh context after tools run
+- `teardown()`: clean up extension-owned resources
+
+Example:
+
+```typescript
+import { defineExtension } from '@xoxoai/checkmate/core'
+
+export const releaseGuard = defineExtension({
+	name: 'release-guard',
+	instructions: ['Prefer visible release labels over inferred version numbers.'],
+	buildInitialMessages: async ({ step }) => [
+		{
+			role: 'user',
+			content: `Current release check target: ${step.expect}`,
+		},
+	],
+})
+```
+
+## Setup API
+
+Inside `setup(api)`, you can compose richer behavior.
+
+Available methods:
+
+- `addTool()`
+- `addInstruction()`
+- `addInitialMessages()`
+- `addToolResponsesHook()`
+- `setCapability()`
+- `getCapability()`
+- `onTeardown()`
+
+This is the main escape hatch for advanced integrations.
+
+## Capabilities and Composition
+
+Capabilities let one extension publish something another extension can use without hard-coding the relationship into the core runner.
+
+That is how the Salesforce extension builds on the web extension.
+
+Example:
+
+```typescript
+import { defineExtension } from '@xoxoai/checkmate/core'
+import { Page } from '@playwright/test'
+import { PlaywrightCapability } from '@xoxoai/checkmate/playwright'
+
+export const auditTrail = defineExtension({
+	name: 'audit-trail',
+	setup(api) {
+		const page = api.getCapability<Page>(PlaywrightCapability.PAGE)
+
+		api.addInstruction(`Current page starts at: ${page.url()}`)
+	},
+})
+```
+
+Prefer capabilities when one extension depends on another extension's runtime objects.
+
+## Extending Built-In Extensions
+
+Built-in extensions are composable too.
+
+You do not need to rewrite `web()` or `salesforce()` to adapt them.
+
+```typescript
+import { web } from '@xoxoai/checkmate/playwright'
+
+const companyWeb = web({ page }).extend({
+	instructions: ['Prefer visible labels over generated ids.'],
+})
+```
+
+You can also add tools or hooks on top of the built-in extension:
+
+```typescript
+const companyWeb = web({ page }).extend({
+	tools: [apiHealthTool],
+	instructions: ['Check API health before asserting UI state.'],
+})
+```
+
+This is usually better than cloning the built-in extension from scratch.
+
+## Building a Custom Runner
+
+Once you have extensions, create a runner helper that matches your domain.
+
+```typescript
+import { createRunner } from '@xoxoai/checkmate/core'
+import { Page } from '@playwright/test'
+import { web } from '@xoxoai/checkmate/playwright'
+import { salesforce } from '@xoxoai/checkmate/salesforce'
+import { apiHealth } from './api-health-extension'
+
+export function createAcmeRunner(page: Page) {
+	return createRunner({
+		extensions: [web({ page }), salesforce(), apiHealth],
+	})
+}
+```
+
+This keeps test code simple while letting your runtime evolve in one place.
+
+## Design Guidelines
+
+Keep extensions readable and honest.
+
+- Keep tools focused on one action.
+- Keep domain behavior out of the core runner.
+- Prefer extension composition over copying built-ins.
+- Prefer capabilities over direct imports between unrelated extensions.
+- Keep instructions concrete and short.
+- Add initial or post-tool context only when the model truly needs it.
+- Return clear tool responses that help the model decide the next step.
+
+## Recommended Progression
+
+Most teams should build in this order:
+
+1. Start with `@xoxoai/checkmate/playwright`.
+2. Add one custom tool with `defineTool()`.
+3. Group related tools into an extension with `defineExtension()`.
+4. Compose a project-specific runner with `createRunner()`.
+5. Extend built-ins only when you need custom runtime behavior.
+
+## See Also
+
+- [GUIDE](./GUIDE.md)
+- [README](../README.md)