@agentic-kit/pi 0.15.0 → 0.16.0

package/README.md

@@ -12,7 +12,19 @@
    <a href="https://www.npmjs.com/package/@agentic-kit/pi"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=agentic%2Fpi%2Fpackage.json"/></a>
 </p>
 
-The [pi coding agent](https://github.com/badlogic/pi-mono) adapter for **agentic-kit**: the Constructive typed database tools and the [`@agentic-kit/harness`](https://www.npmjs.com/package/@agentic-kit/harness) confirm gate, packaged as a pi extension any host can register — Constructive Desktop, the [`agent` CLI](https://www.npmjs.com/package/@agentic-kit/cli), or your own pi-based agent.
+The **one** [pi coding agent](https://github.com/badlogic/pi-mono) adapter for **agentic-kit**: the Constructive typed database tools, and everything that attaches a platform run to a pi session — the run gate, the run log, the metering gateway and usage reporting — for any host to register: Constructive Desktop, the [`agent` CLI](https://www.npmjs.com/package/@agentic-kit/cli), or your own pi-based agent.
+
+What a run *does* is harness-neutral and lives elsewhere; only its attachment to pi lives here.
+
+```
+neutral contracts                      this package                pi
+────────────────────────────────────   ─────────────────────────   ────────────────────
+@agentic-kit/harness  (gate, adapter)  tool_call ─► RunGate       pi.on('tool_call')
+@agentic-kit/metering (gateway, usage) MeteredGateway ─► provider  pi.registerProvider
+@agentic-kit/run-log  (append-only)    SessionMirror              pi's session manager
+```
+
+So a second, compatible harness is a *sibling adapter* — not a fork of the lanes.
 
 ```bash
 npm install @agentic-kit/pi
@@ -22,6 +34,8 @@ npm install @agentic-kit/pi
 
 - **16 typed db tools** — `provision_database`, `provision_blueprint`, `describe_schema`, `add_relation`, `delete_table`, `create_field` / `update_field` / `delete_field`, `add_policies`, `add_records`, `run_codegen`, and the template suite (`list` / `create` / `apply` / `update` / `delete`). Tool schemas are authored in [zod](https://zod.dev) and emitted as plain JSON Schema at pi's tool boundary.
 - **Confirm gate** — the harness's host-neutral gate wired to pi's `tool_call` events. Hosts with a rich confirm surface (Desktop) expose `confirmTool`/`notifyToolSkipped` on `ctx.ui`; everyone else gets pi's built-in `ui.confirm` dialog.
+- **Run lanes** — `composeRun` / `startRun` build a pi session with the run's lanes attached: `createRunLogExtension` mirrors pi's session entries into the run log under `transcriptFormat: 'pi'`, `createMeteredModelExtension` points pi at the Constructive gateway so usage cannot be under-reported, `createUsageReportExtension` self-reports usage when the host owns the provider keys, and `createGateExtension` suspends a gated tool call until a human answers.
+- **`piHarness`** — the `HarnessAdapter` face of the above: an `id`, the `transcriptFormat` its entries are written under, and `startRun`.
 - **Host injection** — credentials, backend endpoints, and data-plane tokens come from your host, not from the package:
 
 ```ts
@@ -88,7 +102,9 @@ For local development, the cold path and the warm pool depend on the backend's j
 
 ## Related
 
-- [`@agentic-kit/harness`](https://www.npmjs.com/package/@agentic-kit/harness) — host-neutral skills, gating, and blueprint core
+- [`@agentic-kit/harness`](https://www.npmjs.com/package/@agentic-kit/harness) — host-neutral skills, gating, blueprint core, and the `HarnessAdapter` contract
+- [`@agentic-kit/metering`](https://www.npmjs.com/package/@agentic-kit/metering) — the metered gateway and usage reporting
+- [`@agentic-kit/run-log`](https://www.npmjs.com/package/@agentic-kit/run-log) — the append-only run log
 - [`@agentic-kit/cli`](https://www.npmjs.com/package/@agentic-kit/cli) — `agent`, a local secure-by-default coding agent
 - [`agentic-kit`](https://www.npmjs.com/package/agentic-kit) — the umbrella package
 

package/embed/lanes.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Compose a run's lanes into the extension list pi loads.
+ *
+ * A run's placement — a developer's laptop, a long-running cloud job — is *only*
+ * a difference in these options: which store the log appends to, whether the
+ * model calls leave through the metered gateway or a local key, and where an
+ * approval question is asked. The composed session is otherwise identical, which
+ * is the whole point of the package.
+ */
+import type { MeteredIdentity } from '@agentic-kit/metering';
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+import { type GateExtension, type GateExtensionOptions } from '../extensions/gate';
+import { type MeteredModelExtension, type MeteredModelExtensionOptions } from '../extensions/metered-model';
+import { type RunLogExtension, type RunLogExtensionOptions } from '../extensions/run-log';
+import { type UsageReportExtension, type UsageReportExtensionOptions } from '../extensions/usage-report';
+/** Run log lane — `runId` comes from the run, not from here. */
+export type RunLogLane = Omit<RunLogExtensionOptions, 'runId'>;
+/**
+ * Metering lane. `gateway` is authoritative (the gateway meters what it proxies);
+ * `self-report` is the own-provider-key lane and is only as trustworthy as the
+ * agent reporting it. They are mutually exclusive on purpose: routing through the
+ * gateway *and* self-reporting would double-count the same tokens.
+ */
+export type MeteringLane = ({
+    mode: 'gateway';
+} & MeteredModelExtensionOptions) | ({
+    mode: 'self-report';
+} & UsageReportExtensionOptions);
+/** Approval lane — `runId` comes from the run. */
+export type GateLane = Omit<GateExtensionOptions, 'runId'>;
+export interface ComposeRunOptions {
+    runId: string;
+    log?: RunLogLane;
+    metering?: MeteringLane;
+    gate?: GateLane;
+    /**
+     * The host's own extensions — workspace tools, prompts, UI glue. Loaded after
+     * the lanes so a host tool call is already gated and already logged.
+     */
+    extensions?: readonly ExtensionFactory[];
+}
+export interface ComposedLanes {
+    log?: RunLogExtension;
+    meteredModel?: MeteredModelExtension;
+    usageReport?: UsageReportExtension;
+    gate?: GateExtension;
+}
+export interface ComposedRun {
+    runId: string;
+    /** In load order: log, metering, gate, then the host's own. */
+    extensions: ExtensionFactory[];
+    lanes: ComposedLanes;
+    /**
+     * Drain every lane that buffers, and throw the first failure. A host calls
+     * this before it exits; the extensions also flush themselves on
+     * `session_shutdown`, so this is for hosts that end a run without one.
+     */
+    flush(): Promise<void>;
+}
+export declare function composeRun(options: ComposeRunOptions): ComposedRun;
+/**
+ * The identity every metered lane needs. Exported so a host can build it once
+ * from its resolved project context and hand the same value to both lanes.
+ */
+export type { MeteredIdentity };

package/embed/lanes.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Compose a run's lanes into the extension list pi loads.
+ *
+ * A run's placement — a developer's laptop, a long-running cloud job — is *only*
+ * a difference in these options: which store the log appends to, whether the
+ * model calls leave through the metered gateway or a local key, and where an
+ * approval question is asked. The composed session is otherwise identical, which
+ * is the whole point of the package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeRun = composeRun;
+const gate_1 = require("../extensions/gate");
+const metered_model_1 = require("../extensions/metered-model");
+const run_log_1 = require("../extensions/run-log");
+const usage_report_1 = require("../extensions/usage-report");
+function composeRun(options) {
+    const lanes = {};
+    const extensions = [];
+    if (options.log) {
+        lanes.log = (0, run_log_1.createRunLogExtension)({ runId: options.runId, ...options.log });
+        extensions.push(lanes.log.extension);
+    }
+    const metering = options.metering;
+    if (metering?.mode === 'gateway') {
+        const { mode: _mode, ...meteredOptions } = metering;
+        lanes.meteredModel = (0, metered_model_1.createMeteredModelExtension)(meteredOptions);
+        extensions.push(lanes.meteredModel.extension);
+    }
+    else if (metering?.mode === 'self-report') {
+        const { mode: _mode, ...reportOptions } = metering;
+        lanes.usageReport = (0, usage_report_1.createUsageReportExtension)(reportOptions);
+        extensions.push(lanes.usageReport.extension);
+    }
+    if (options.gate) {
+        lanes.gate = (0, gate_1.createGateExtension)({ runId: options.runId, ...options.gate });
+        extensions.push(lanes.gate.extension);
+    }
+    if (options.extensions)
+        extensions.push(...options.extensions);
+    return {
+        runId: options.runId,
+        extensions,
+        lanes,
+        flush: async () => {
+            // Sequential, log first: a usage failure must not cost us the transcript.
+            if (lanes.log)
+                await lanes.log.flush();
+            if (lanes.usageReport)
+                await lanes.usageReport.flush();
+        }
+    };
+}

package/embed/session.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Start a pi session with a run's lanes attached.
+ *
+ * pi ships as ESM only, and every host already imports it dynamically (the
+ * desktop main process does this in `bootstrap`, before pi's storage paths are
+ * resolved). So the module is *injected* rather than imported here: this package
+ * stays CJS+ESM publishable, the host keeps control of when pi loads, and these
+ * paths are testable without a model, a network or a filesystem.
+ *
+ * pi takes extensions through a `ResourceLoader`, not through
+ * `createAgentSession`, so embedding means handing the composed factories to a
+ * loader — pi's default one, or the host's own (the desktop harness builds one
+ * that layers its skills, prompts and templates).
+ */
+import type { CreateAgentSessionOptions, CreateAgentSessionResult, ExtensionFactory, ResourceLoader } from '@earendil-works/pi-coding-agent';
+import { type ComposedRun, type ComposeRunOptions } from './lanes';
+export interface ResourceLoaderRequest {
+    /** The lane extensions, in load order. Give these to the loader. */
+    extensionFactories: ExtensionFactory[];
+    cwd: string;
+    agentDir: string;
+}
+export type CreateResourceLoader = (request: ResourceLoaderRequest) => ResourceLoader | Promise<ResourceLoader>;
+/** The slice of the pi module this package needs, so a host can inject it. */
+export interface PiModule {
+    createAgentSession: (options: CreateAgentSessionOptions) => Promise<CreateAgentSessionResult>;
+    DefaultResourceLoader: new (options: {
+        cwd: string;
+        agentDir: string;
+        extensionFactories?: ExtensionFactory[];
+    }) => ResourceLoader;
+    getAgentDir?: () => string;
+}
+export interface StartRunOptions extends ComposeRunOptions {
+    /** `await import('@earendil-works/pi-coding-agent')`. */
+    pi: PiModule;
+    cwd?: string;
+    /** pi's config/storage dir. Defaults to `pi.getAgentDir()` when available. */
+    agentDir?: string;
+    /** Passed through to pi, minus the ones this package owns. */
+    session?: Omit<CreateAgentSessionOptions, 'cwd' | 'agentDir' | 'resourceLoader'>;
+    /** Layer the lanes onto a host's own loader instead of pi's default. */
+    createResourceLoader?: CreateResourceLoader;
+}
+export interface EmbeddedRun {
+    run: ComposedRun;
+    session: CreateAgentSessionResult['session'];
+    extensionsResult: CreateAgentSessionResult['extensionsResult'];
+    modelFallbackMessage?: string;
+    resourceLoader: ResourceLoader;
+    /**
+     * Flush the lanes, then dispose the session. Flush first and let a failure
+     * propagate *after* disposal, so a delivery error is never traded for a leaked
+     * session — and never swallowed into a clean-looking shutdown.
+     */
+    close(): Promise<void>;
+}
+export declare function startRun(options: StartRunOptions): Promise<EmbeddedRun>;

package/embed/session.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Start a pi session with a run's lanes attached.
+ *
+ * pi ships as ESM only, and every host already imports it dynamically (the
+ * desktop main process does this in `bootstrap`, before pi's storage paths are
+ * resolved). So the module is *injected* rather than imported here: this package
+ * stays CJS+ESM publishable, the host keeps control of when pi loads, and these
+ * paths are testable without a model, a network or a filesystem.
+ *
+ * pi takes extensions through a `ResourceLoader`, not through
+ * `createAgentSession`, so embedding means handing the composed factories to a
+ * loader — pi's default one, or the host's own (the desktop harness builds one
+ * that layers its skills, prompts and templates).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startRun = startRun;
+const lanes_1 = require("./lanes");
+async function startRun(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const agentDir = options.agentDir ?? options.pi.getAgentDir?.();
+    if (agentDir === undefined) {
+        throw new Error('pi: agentDir is required when the injected pi module has no getAgentDir()');
+    }
+    const run = (0, lanes_1.composeRun)(options);
+    const resourceLoader = await (options.createResourceLoader ?? defaultResourceLoader(options.pi))({
+        extensionFactories: run.extensions,
+        cwd,
+        agentDir
+    });
+    const result = await options.pi.createAgentSession({ ...options.session, cwd, agentDir, resourceLoader });
+    // pi emits `session_start` from `bindExtensions`, which its own CLI modes call
+    // once their UI exists — `createAgentSession` never does. An embedder that
+    // skips it loads the extensions but never starts them: the metered lane never
+    // selects the gateway model, so a cloud run's calls leave on whatever provider
+    // key the process happens to hold, unmetered, and the log lane never binds on
+    // resume. So the embedding, not the host, fires it.
+    await result.session.bindExtensions({});
+    assertMeteredModelSelected(run, result.session);
+    return {
+        run,
+        session: result.session,
+        extensionsResult: result.extensionsResult,
+        ...(result.modelFallbackMessage === undefined ? {} : { modelFallbackMessage: result.modelFallbackMessage }),
+        resourceLoader,
+        close: async () => {
+            let failure;
+            try {
+                await run.flush();
+            }
+            catch (error) {
+                failure = error;
+            }
+            result.session.dispose();
+            if (failure !== undefined)
+                throw failure;
+        }
+    };
+}
+/**
+ * The metered lane's whole purpose is that usage cannot be under-reported, so a
+ * session that ended up on some other provider must fail the run rather than
+ * quietly bill nothing.
+ */
+function assertMeteredModelSelected(run, session) {
+    const lane = run.lanes.meteredModel;
+    if (!lane?.selectedModel)
+        return;
+    const model = session.model;
+    if (model?.provider === lane.providerName && model.id === lane.selectedModel)
+        return;
+    throw new Error(`pi: the metered lane selected "${lane.providerName}/${lane.selectedModel}" but the ` +
+        `session is on "${model ? `${model.provider}/${model.id}` : 'no model'}" — model calls would ` +
+        'leave outside the gateway and go unmetered');
+}
+const defaultResourceLoader = (pi) => async (request) => {
+    const loader = new pi.DefaultResourceLoader({
+        cwd: request.cwd,
+        agentDir: request.agentDir,
+        extensionFactories: request.extensionFactories
+    });
+    // pi's loader discovers nothing until it is reloaded once.
+    await loader.reload();
+    return loader;
+};

package/esm/embed/lanes.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Compose a run's lanes into the extension list pi loads.
+ *
+ * A run's placement — a developer's laptop, a long-running cloud job — is *only*
+ * a difference in these options: which store the log appends to, whether the
+ * model calls leave through the metered gateway or a local key, and where an
+ * approval question is asked. The composed session is otherwise identical, which
+ * is the whole point of the package.
+ */
+import type { MeteredIdentity } from '@agentic-kit/metering';
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+import { type GateExtension, type GateExtensionOptions } from '../extensions/gate';
+import { type MeteredModelExtension, type MeteredModelExtensionOptions } from '../extensions/metered-model';
+import { type RunLogExtension, type RunLogExtensionOptions } from '../extensions/run-log';
+import { type UsageReportExtension, type UsageReportExtensionOptions } from '../extensions/usage-report';
+/** Run log lane — `runId` comes from the run, not from here. */
+export type RunLogLane = Omit<RunLogExtensionOptions, 'runId'>;
+/**
+ * Metering lane. `gateway` is authoritative (the gateway meters what it proxies);
+ * `self-report` is the own-provider-key lane and is only as trustworthy as the
+ * agent reporting it. They are mutually exclusive on purpose: routing through the
+ * gateway *and* self-reporting would double-count the same tokens.
+ */
+export type MeteringLane = ({
+    mode: 'gateway';
+} & MeteredModelExtensionOptions) | ({
+    mode: 'self-report';
+} & UsageReportExtensionOptions);
+/** Approval lane — `runId` comes from the run. */
+export type GateLane = Omit<GateExtensionOptions, 'runId'>;
+export interface ComposeRunOptions {
+    runId: string;
+    log?: RunLogLane;
+    metering?: MeteringLane;
+    gate?: GateLane;
+    /**
+     * The host's own extensions — workspace tools, prompts, UI glue. Loaded after
+     * the lanes so a host tool call is already gated and already logged.
+     */
+    extensions?: readonly ExtensionFactory[];
+}
+export interface ComposedLanes {
+    log?: RunLogExtension;
+    meteredModel?: MeteredModelExtension;
+    usageReport?: UsageReportExtension;
+    gate?: GateExtension;
+}
+export interface ComposedRun {
+    runId: string;
+    /** In load order: log, metering, gate, then the host's own. */
+    extensions: ExtensionFactory[];
+    lanes: ComposedLanes;
+    /**
+     * Drain every lane that buffers, and throw the first failure. A host calls
+     * this before it exits; the extensions also flush themselves on
+     * `session_shutdown`, so this is for hosts that end a run without one.
+     */
+    flush(): Promise<void>;
+}
+export declare function composeRun(options: ComposeRunOptions): ComposedRun;
+/**
+ * The identity every metered lane needs. Exported so a host can build it once
+ * from its resolved project context and hand the same value to both lanes.
+ */
+export type { MeteredIdentity };

package/esm/embed/lanes.js

@@ -0,0 +1,50 @@
+/**
+ * Compose a run's lanes into the extension list pi loads.
+ *
+ * A run's placement — a developer's laptop, a long-running cloud job — is *only*
+ * a difference in these options: which store the log appends to, whether the
+ * model calls leave through the metered gateway or a local key, and where an
+ * approval question is asked. The composed session is otherwise identical, which
+ * is the whole point of the package.
+ */
+import { createGateExtension } from '../extensions/gate';
+import { createMeteredModelExtension } from '../extensions/metered-model';
+import { createRunLogExtension } from '../extensions/run-log';
+import { createUsageReportExtension } from '../extensions/usage-report';
+export function composeRun(options) {
+    const lanes = {};
+    const extensions = [];
+    if (options.log) {
+        lanes.log = createRunLogExtension({ runId: options.runId, ...options.log });
+        extensions.push(lanes.log.extension);
+    }
+    const metering = options.metering;
+    if (metering?.mode === 'gateway') {
+        const { mode: _mode, ...meteredOptions } = metering;
+        lanes.meteredModel = createMeteredModelExtension(meteredOptions);
+        extensions.push(lanes.meteredModel.extension);
+    }
+    else if (metering?.mode === 'self-report') {
+        const { mode: _mode, ...reportOptions } = metering;
+        lanes.usageReport = createUsageReportExtension(reportOptions);
+        extensions.push(lanes.usageReport.extension);
+    }
+    if (options.gate) {
+        lanes.gate = createGateExtension({ runId: options.runId, ...options.gate });
+        extensions.push(lanes.gate.extension);
+    }
+    if (options.extensions)
+        extensions.push(...options.extensions);
+    return {
+        runId: options.runId,
+        extensions,
+        lanes,
+        flush: async () => {
+            // Sequential, log first: a usage failure must not cost us the transcript.
+            if (lanes.log)
+                await lanes.log.flush();
+            if (lanes.usageReport)
+                await lanes.usageReport.flush();
+        }
+    };
+}

package/esm/embed/session.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Start a pi session with a run's lanes attached.
+ *
+ * pi ships as ESM only, and every host already imports it dynamically (the
+ * desktop main process does this in `bootstrap`, before pi's storage paths are
+ * resolved). So the module is *injected* rather than imported here: this package
+ * stays CJS+ESM publishable, the host keeps control of when pi loads, and these
+ * paths are testable without a model, a network or a filesystem.
+ *
+ * pi takes extensions through a `ResourceLoader`, not through
+ * `createAgentSession`, so embedding means handing the composed factories to a
+ * loader — pi's default one, or the host's own (the desktop harness builds one
+ * that layers its skills, prompts and templates).
+ */
+import type { CreateAgentSessionOptions, CreateAgentSessionResult, ExtensionFactory, ResourceLoader } from '@earendil-works/pi-coding-agent';
+import { type ComposedRun, type ComposeRunOptions } from './lanes';
+export interface ResourceLoaderRequest {
+    /** The lane extensions, in load order. Give these to the loader. */
+    extensionFactories: ExtensionFactory[];
+    cwd: string;
+    agentDir: string;
+}
+export type CreateResourceLoader = (request: ResourceLoaderRequest) => ResourceLoader | Promise<ResourceLoader>;
+/** The slice of the pi module this package needs, so a host can inject it. */
+export interface PiModule {
+    createAgentSession: (options: CreateAgentSessionOptions) => Promise<CreateAgentSessionResult>;
+    DefaultResourceLoader: new (options: {
+        cwd: string;
+        agentDir: string;
+        extensionFactories?: ExtensionFactory[];
+    }) => ResourceLoader;
+    getAgentDir?: () => string;
+}
+export interface StartRunOptions extends ComposeRunOptions {
+    /** `await import('@earendil-works/pi-coding-agent')`. */
+    pi: PiModule;
+    cwd?: string;
+    /** pi's config/storage dir. Defaults to `pi.getAgentDir()` when available. */
+    agentDir?: string;
+    /** Passed through to pi, minus the ones this package owns. */
+    session?: Omit<CreateAgentSessionOptions, 'cwd' | 'agentDir' | 'resourceLoader'>;
+    /** Layer the lanes onto a host's own loader instead of pi's default. */
+    createResourceLoader?: CreateResourceLoader;
+}
+export interface EmbeddedRun {
+    run: ComposedRun;
+    session: CreateAgentSessionResult['session'];
+    extensionsResult: CreateAgentSessionResult['extensionsResult'];
+    modelFallbackMessage?: string;
+    resourceLoader: ResourceLoader;
+    /**
+     * Flush the lanes, then dispose the session. Flush first and let a failure
+     * propagate *after* disposal, so a delivery error is never traded for a leaked
+     * session — and never swallowed into a clean-looking shutdown.
+     */
+    close(): Promise<void>;
+}
+export declare function startRun(options: StartRunOptions): Promise<EmbeddedRun>;

package/esm/embed/session.js

@@ -0,0 +1,82 @@
+/**
+ * Start a pi session with a run's lanes attached.
+ *
+ * pi ships as ESM only, and every host already imports it dynamically (the
+ * desktop main process does this in `bootstrap`, before pi's storage paths are
+ * resolved). So the module is *injected* rather than imported here: this package
+ * stays CJS+ESM publishable, the host keeps control of when pi loads, and these
+ * paths are testable without a model, a network or a filesystem.
+ *
+ * pi takes extensions through a `ResourceLoader`, not through
+ * `createAgentSession`, so embedding means handing the composed factories to a
+ * loader — pi's default one, or the host's own (the desktop harness builds one
+ * that layers its skills, prompts and templates).
+ */
+import { composeRun } from './lanes';
+export async function startRun(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const agentDir = options.agentDir ?? options.pi.getAgentDir?.();
+    if (agentDir === undefined) {
+        throw new Error('pi: agentDir is required when the injected pi module has no getAgentDir()');
+    }
+    const run = composeRun(options);
+    const resourceLoader = await (options.createResourceLoader ?? defaultResourceLoader(options.pi))({
+        extensionFactories: run.extensions,
+        cwd,
+        agentDir
+    });
+    const result = await options.pi.createAgentSession({ ...options.session, cwd, agentDir, resourceLoader });
+    // pi emits `session_start` from `bindExtensions`, which its own CLI modes call
+    // once their UI exists — `createAgentSession` never does. An embedder that
+    // skips it loads the extensions but never starts them: the metered lane never
+    // selects the gateway model, so a cloud run's calls leave on whatever provider
+    // key the process happens to hold, unmetered, and the log lane never binds on
+    // resume. So the embedding, not the host, fires it.
+    await result.session.bindExtensions({});
+    assertMeteredModelSelected(run, result.session);
+    return {
+        run,
+        session: result.session,
+        extensionsResult: result.extensionsResult,
+        ...(result.modelFallbackMessage === undefined ? {} : { modelFallbackMessage: result.modelFallbackMessage }),
+        resourceLoader,
+        close: async () => {
+            let failure;
+            try {
+                await run.flush();
+            }
+            catch (error) {
+                failure = error;
+            }
+            result.session.dispose();
+            if (failure !== undefined)
+                throw failure;
+        }
+    };
+}
+/**
+ * The metered lane's whole purpose is that usage cannot be under-reported, so a
+ * session that ended up on some other provider must fail the run rather than
+ * quietly bill nothing.
+ */
+function assertMeteredModelSelected(run, session) {
+    const lane = run.lanes.meteredModel;
+    if (!lane?.selectedModel)
+        return;
+    const model = session.model;
+    if (model?.provider === lane.providerName && model.id === lane.selectedModel)
+        return;
+    throw new Error(`pi: the metered lane selected "${lane.providerName}/${lane.selectedModel}" but the ` +
+        `session is on "${model ? `${model.provider}/${model.id}` : 'no model'}" — model calls would ` +
+        'leave outside the gateway and go unmetered');
+}
+const defaultResourceLoader = (pi) => async (request) => {
+    const loader = new pi.DefaultResourceLoader({
+        cwd: request.cwd,
+        agentDir: request.agentDir,
+        extensionFactories: request.extensionFactories
+    });
+    // pi's loader discovers nothing until it is reloaded once.
+    await loader.reload();
+    return loader;
+};

package/esm/extensions/gate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The pi side of the run gate: map pi's `tool_call` event onto the neutral
+ * `RunGate` and turn its outcome into pi's block shape.
+ *
+ * pi's `tool_call` handler can await, so an `ask` verdict simply suspends the
+ * tool until the approval channel resolves. That is the whole mechanism for
+ * "approve a cloud agent's `rm -rf` from a browser tab" — and it is all the
+ * harness-specific code the gate needs; the policy, the approval rendezvous and
+ * the audit record live in `@agentic-kit/harness`.
+ */
+import { type ApprovalRequest, type RunGate, type RunGateOptions, type RunGatePolicy } from '@agentic-kit/harness';
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+export type GateExtensionOptions = RunGateOptions;
+export interface GateExtension {
+    extension: ExtensionFactory;
+    policy: RunGatePolicy;
+    /** Requests currently waiting on a human. */
+    pending: ReadonlyMap<string, ApprovalRequest>;
+    gate: RunGate;
+}
+export declare function createGateExtension(options: GateExtensionOptions): GateExtension;

package/esm/extensions/gate.js

@@ -0,0 +1,27 @@
+/**
+ * The pi side of the run gate: map pi's `tool_call` event onto the neutral
+ * `RunGate` and turn its outcome into pi's block shape.
+ *
+ * pi's `tool_call` handler can await, so an `ask` verdict simply suspends the
+ * tool until the approval channel resolves. That is the whole mechanism for
+ * "approve a cloud agent's `rm -rf` from a browser tab" — and it is all the
+ * harness-specific code the gate needs; the policy, the approval rendezvous and
+ * the audit record live in `@agentic-kit/harness`.
+ */
+import { createRunGate } from '@agentic-kit/harness';
+export function createGateExtension(options) {
+    const gate = createRunGate(options);
+    const extension = (pi) => {
+        pi.on('tool_call', async (event) => {
+            const outcome = await gate.decide({
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                input: (event.input ?? {})
+            });
+            if (outcome.allowed)
+                return {};
+            return { block: true, ...(outcome.reason === undefined ? {} : { reason: outcome.reason }) };
+        });
+    };
+    return { extension, policy: gate.policy, pending: gate.pending, gate };
+}

package/esm/extensions/metered-model.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The pi side of the metering lane: register the resolved gateway as a pi
+ * provider, optionally as the session's model.
+ *
+ * Every model call then leaves the process through `agentic-server`, which is the
+ * billing authority, so usage cannot be under-reported by the agent. The
+ * endpoint itself is resolved by `@agentic-kit/metering`; only the registration
+ * shape below is pi's. The self-reporting lane (own provider keys) is
+ * `./usage-report`.
+ */
+import { type MeteredGateway, type MeteredGatewayOptions } from '@agentic-kit/metering';
+import type { ExtensionFactory, ProviderConfig } from '@earendil-works/pi-coding-agent';
+export interface MeteredModelExtensionOptions extends MeteredGatewayOptions {
+    /**
+     * Model id to select once registered. Defaults to the first model; pass `false`
+     * to leave the host's model choice alone.
+     */
+    selectModel?: string | false;
+}
+export interface MeteredModelExtension {
+    extension: ExtensionFactory;
+    /** The config handed to pi — asserted in tests, useful for host logging. */
+    config: ProviderConfig;
+    /** The neutral endpoint the config was built from. */
+    gateway: MeteredGateway;
+    providerName: string;
+    /** Model id pi selects on session start, if any. */
+    selectedModel: string | undefined;
+}
+/** Shape a resolved gateway as pi's provider registration. */
+export declare function piProviderConfig(gateway: MeteredGateway): ProviderConfig;
+export declare function createMeteredModelExtension(options: MeteredModelExtensionOptions): MeteredModelExtension;