@agentic-kit/pi 0.15.1 → 0.17.0

package/esm/extensions/metered-model.js

@@ -0,0 +1,50 @@
+/**
+ * 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 { DEFAULT_PROVIDER_NAME, resolveMeteredGateway } from '@agentic-kit/metering';
+/** Shape a resolved gateway as pi's provider registration. */
+export function piProviderConfig(gateway) {
+    return {
+        name: gateway.displayName,
+        baseUrl: gateway.baseUrl,
+        api: gateway.api,
+        headers: gateway.headers,
+        apiKey: gateway.apiKey,
+        models: gateway.models.map((model) => ({ ...model }))
+    };
+}
+export function createMeteredModelExtension(options) {
+    const providerName = options.providerName ?? DEFAULT_PROVIDER_NAME;
+    const gateway = resolveMeteredGateway(options);
+    const config = piProviderConfig(gateway);
+    const modelId = options.selectModel === false ? undefined : (options.selectModel ?? options.models[0].id);
+    if (modelId !== undefined && !options.models.some((model) => model.id === modelId)) {
+        // Selecting an unregistered id silently leaves pi on an unmetered model,
+        // which is the one failure this lane exists to prevent.
+        throw new Error(`metered model: selectModel "${modelId}" is not one of the registered models`);
+    }
+    const extension = (pi) => {
+        pi.registerProvider(providerName, config);
+        if (modelId === undefined)
+            return;
+        // `pi.setModel` takes a resolved model, and the registry that resolves it
+        // lives on the context — which an extension only gets on an event.
+        // `session_start` is the first, and fires before the first turn.
+        pi.on('session_start', async (_event, ctx) => {
+            const model = ctx.modelRegistry.find(providerName, modelId);
+            if (!model)
+                throw new Error(`metered model: provider "${providerName}" has no model "${modelId}" after registration`);
+            const ok = await pi.setModel(model);
+            if (!ok)
+                throw new Error(`metered model: pi refused model "${providerName}/${modelId}" (no usable credentials for the gateway)`);
+        });
+    };
+    return { extension, config, gateway, providerName, selectedModel: modelId };
+}

package/esm/extensions/run-log.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The pi side of the run log: drain the neutral session mirror after anything
+ * that can append an entry. Every listed event is a point where pi has just
+ * written to the session, so the run log trails the session by at most one event.
+ */
+import { type RunEventRecord, type RunLogAppendStore, SessionMirror } from '@agentic-kit/run-log';
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+/**
+ * Events after which the session may have grown. `session_start` also covers
+ * resume (pi replays the file before the first event), so a resumed run
+ * re-appends its history and the store's idempotency discards the duplicates.
+ */
+export declare const MIRROR_EVENTS: readonly ["session_start", "session_compact", "session_tree", "session_shutdown", "input", "before_agent_start", "message_end", "tool_execution_end", "turn_end", "agent_end", "model_select", "thinking_level_select"];
+export type MirrorEvent = (typeof MIRROR_EVENTS)[number];
+export interface RunLogExtensionOptions {
+    /** The run this session belongs to. Local and cloud runs differ only here. */
+    runId: string;
+    store: RunLogAppendStore;
+    /** pi session format version the entries are produced under. */
+    transcriptVersion?: number;
+    events?: readonly MirrorEvent[];
+    /**
+     * Called when a drain fails. Without it the failure is rethrown into pi's
+     * event dispatch: a run log that silently stops recording is worse than a
+     * loud one, so losing entries is never the default.
+     */
+    onError?: (error: unknown) => void;
+}
+export interface RunLogExtension {
+    extension: ExtensionFactory;
+    /** Drain now — for a host that wants the log flushed before it exits. */
+    flush(): Promise<RunEventRecord[]>;
+    mirror: SessionMirror;
+}
+export declare function createRunLogExtension(options: RunLogExtensionOptions): RunLogExtension;

package/esm/extensions/run-log.js

@@ -0,0 +1,57 @@
+/**
+ * The pi side of the run log: drain the neutral session mirror after anything
+ * that can append an entry. Every listed event is a point where pi has just
+ * written to the session, so the run log trails the session by at most one event.
+ */
+import { PI_TRANSCRIPT_FORMAT, SessionMirror } from '@agentic-kit/run-log';
+/**
+ * Events after which the session may have grown. `session_start` also covers
+ * resume (pi replays the file before the first event), so a resumed run
+ * re-appends its history and the store's idempotency discards the duplicates.
+ */
+export const MIRROR_EVENTS = [
+    'session_start',
+    'session_compact',
+    'session_tree',
+    'session_shutdown',
+    'input',
+    'before_agent_start',
+    'message_end',
+    'tool_execution_end',
+    'turn_end',
+    'agent_end',
+    'model_select',
+    'thinking_level_select'
+];
+export function createRunLogExtension(options) {
+    const mirror = new SessionMirror({
+        runId: options.runId,
+        store: options.store,
+        transcriptFormat: PI_TRANSCRIPT_FORMAT,
+        ...(options.transcriptVersion === undefined ? {} : { transcriptVersion: options.transcriptVersion })
+    });
+    const events = options.events ?? MIRROR_EVENTS;
+    const drain = async () => {
+        try {
+            return await mirror.drain();
+        }
+        catch (error) {
+            if (!options.onError)
+                throw error;
+            options.onError(error);
+            return [];
+        }
+    };
+    const extension = (pi) => {
+        for (const event of events) {
+            // Each overload of `on` is typed for its own handler; the handler here
+            // ignores the event and only reads the context, so one cast at the
+            // registration boundary keeps the loop.
+            pi.on(event, async (_event, ctx) => {
+                mirror.bind(ctx.sessionManager);
+                await drain();
+            });
+        }
+    };
+    return { extension, flush: drain, mirror };
+}

package/esm/extensions/usage-report.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The pi side of the self-reporting lane: report each assistant message's usage
+ * to the gateway.
+ *
+ * This is the local / own-provider-key lane. The agent's own numbers are the only
+ * source, so a report is *self-reported* — good for reconciliation and for usage
+ * visibility on a developer's own key, not tamper-proof billing. When the run
+ * must be billed authoritatively, route the model calls through the gateway with
+ * `./metered-model` instead; the gateway then meters itself and this extension is
+ * unnecessary.
+ *
+ * Everything but the two event hooks below is `@agentic-kit/metering`.
+ */
+import { type MeteredIdentity, type UsageReport, UsageReporter } from '@agentic-kit/metering';
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+export interface UsageReportExtensionOptions {
+    identity: MeteredIdentity;
+    /** Gateway root. Required unless a custom `sink` is supplied. */
+    gatewayUrl?: string;
+    /** Delivery override — e.g. an in-process sink, or a queue. */
+    sink?: (report: UsageReport) => Promise<void>;
+    fetch?: typeof globalThis.fetch;
+    /** `operation` column value; defaults to `agent/chat`. */
+    operation?: string;
+    /** Report failures here instead of having `flush()` rethrow them. */
+    onError?: (error: unknown, report: UsageReport) => void;
+}
+export interface UsageReportExtension {
+    extension: ExtensionFactory;
+    /** Drain the queue and rethrow the first delivery failure. */
+    flush(): Promise<void>;
+    reporter: UsageReporter;
+}
+export declare function createUsageReportExtension(options: UsageReportExtensionOptions): UsageReportExtension;

package/esm/extensions/usage-report.js

@@ -0,0 +1,53 @@
+/**
+ * The pi side of the self-reporting lane: report each assistant message's usage
+ * to the gateway.
+ *
+ * This is the local / own-provider-key lane. The agent's own numbers are the only
+ * source, so a report is *self-reported* — good for reconciliation and for usage
+ * visibility on a developer's own key, not tamper-proof billing. When the run
+ * must be billed authoritatively, route the model calls through the gateway with
+ * `./metered-model` instead; the gateway then meters itself and this extension is
+ * unnecessary.
+ *
+ * Everything but the two event hooks below is `@agentic-kit/metering`.
+ */
+import { httpUsageSink, isAssistantMessage, toUsageReport, UsageReporter } from '@agentic-kit/metering';
+export function createUsageReportExtension(options) {
+    const sink = options.sink ??
+        httpUsageSink({
+            gatewayUrl: requireGatewayUrl(options),
+            identity: options.identity,
+            ...(options.fetch ? { fetch: options.fetch } : {})
+        });
+    const reporter = new UsageReporter({ sink, ...(options.onError ? { onError: options.onError } : {}) });
+    // pi can emit `message_end` more than once for the same response (a rewritten
+    // message, a replayed entry on resume), and each emission would otherwise bill
+    // again. `responseId` is the provider's identity for the response, so it is
+    // what dedupes; messages without one are reported as-is.
+    const seen = new Set();
+    const extension = (pi) => {
+        pi.on('message_end', (event) => {
+            const message = event.message;
+            if (!isAssistantMessage(message))
+                return;
+            const responseId = message.responseId;
+            if (typeof responseId === 'string' && responseId.length > 0) {
+                if (seen.has(responseId))
+                    return;
+                seen.add(responseId);
+            }
+            const report = toUsageReport(message, options.operation === undefined ? {} : { operation: options.operation });
+            if (report)
+                reporter.enqueue(report);
+        });
+        pi.on('session_shutdown', async () => {
+            await reporter.flush();
+        });
+    };
+    return { extension, flush: () => reporter.flush(), reporter };
+}
+function requireGatewayUrl(options) {
+    if (!options.gatewayUrl)
+        throw new Error('usage report: gatewayUrl is required unless a custom sink is provided');
+    return options.gatewayUrl;
+}

package/esm/harness.d.ts

@@ -0,0 +1,16 @@
+/**
+ * pi as a `HarnessAdapter`.
+ *
+ * The adapter is thin by design: everything a run actually does — gating, run
+ * log, metering — already lives behind neutral contracts, so all that is left
+ * here is pi's identity, the transcript it writes, and its way of attaching
+ * extensions (a resource loader). A second harness implements the same three
+ * things against its own plugin surface, and hosts keep calling `startRun`.
+ */
+import type { HarnessAdapter, HarnessRun } from '@agentic-kit/harness';
+import { type EmbeddedRun, type StartRunOptions } from './embed/session';
+export declare const PI_HARNESS_ID = "pi";
+export interface PiHarnessRun extends EmbeddedRun, HarnessRun {
+    readonly runId: string;
+}
+export declare const piHarness: HarnessAdapter<StartRunOptions, PiHarnessRun>;

package/esm/harness.js

@@ -0,0 +1,24 @@
+/**
+ * pi as a `HarnessAdapter`.
+ *
+ * The adapter is thin by design: everything a run actually does — gating, run
+ * log, metering — already lives behind neutral contracts, so all that is left
+ * here is pi's identity, the transcript it writes, and its way of attaching
+ * extensions (a resource loader). A second harness implements the same three
+ * things against its own plugin surface, and hosts keep calling `startRun`.
+ */
+import { PI_TRANSCRIPT_FORMAT } from '@agentic-kit/run-log';
+import { startRun } from './embed/session';
+export const PI_HARNESS_ID = 'pi';
+export const piHarness = {
+    id: PI_HARNESS_ID,
+    transcriptFormat: PI_TRANSCRIPT_FORMAT,
+    async startRun(options) {
+        const embedded = await startRun(options);
+        return {
+            ...embedded,
+            runId: embedded.run.runId,
+            flush: () => embedded.run.flush()
+        };
+    }
+};

package/esm/index.d.ts

@@ -5,6 +5,13 @@ export declare const dbTools: ExtensionFactory;
 export declare function createDbTools(host: PiToolsHost): ExtensionFactory;
 export { type ConfirmGate, type ConfirmGateDeps, type ConfirmGateOptions, createConfirmGate, } from './confirm-gate';
 export { CONTEXT_ENV_KEYS, CONTEXT_ENV_PREFIX, type ContextEnvKey, type ContextSource, deriveSubdomainEndpoint, fromEnvFile, fromEnvironment, type ModulesClient, type ProjectContext, type ProjectContextFailureCode, resolveDataToken, resolveProjectContext, } from './context';
+export { type ComposedLanes, type ComposedRun, composeRun, type ComposeRunOptions, type GateLane, type MeteringLane, type RunLogLane, } from './embed/lanes';
+export { type CreateResourceLoader, type EmbeddedRun, type PiModule, type ResourceLoaderRequest, startRun, type StartRunOptions, } from './embed/session';
+export { createGateExtension, type GateExtension, type GateExtensionOptions, } from './extensions/gate';
+export { createMeteredModelExtension, type MeteredModelExtension, type MeteredModelExtensionOptions, piProviderConfig, } from './extensions/metered-model';
+export { createRunLogExtension, MIRROR_EVENTS, type MirrorEvent, type RunLogExtension, type RunLogExtensionOptions, } from './extensions/run-log';
+export { createUsageReportExtension, type UsageReportExtension, type UsageReportExtensionOptions, } from './extensions/usage-report';
+export { PI_HARNESS_ID, piHarness, type PiHarnessRun } from './harness';
 export { type ActiveDataToken, configureHost, type DataAuthBroker, getHost, type HostAccount, type HostBackendConfig, type HostProvisionOverlay, type PiToolsHost, type PreviewToken, } from './host';
 export { loadProvisionManifest, parseProvisionManifest, PROVISION_MANIFEST_FILE, type ProvisionManifest, } from './provision-database/manifest';
 export { allModulePresets, DEFAULT_PROVISION_PRESET, getModulePreset, type ModulePreset, type ProvisionModule, } from './provision-database/presets';

package/esm/index.js

@@ -46,6 +46,13 @@ export function createDbTools(host) {
 }
 export { createConfirmGate, } from './confirm-gate';
 export { CONTEXT_ENV_KEYS, CONTEXT_ENV_PREFIX, deriveSubdomainEndpoint, fromEnvFile, fromEnvironment, resolveDataToken, resolveProjectContext, } from './context';
+export { composeRun, } from './embed/lanes';
+export { startRun, } from './embed/session';
+export { createGateExtension, } from './extensions/gate';
+export { createMeteredModelExtension, piProviderConfig, } from './extensions/metered-model';
+export { createRunLogExtension, MIRROR_EVENTS, } from './extensions/run-log';
+export { createUsageReportExtension, } from './extensions/usage-report';
+export { PI_HARNESS_ID, piHarness } from './harness';
 export { configureHost, getHost, } from './host';
 export { loadProvisionManifest, parseProvisionManifest, PROVISION_MANIFEST_FILE, } from './provision-database/manifest';
 export { allModulePresets, DEFAULT_PROVISION_PRESET, getModulePreset, } from './provision-database/presets';

package/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/extensions/gate.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGateExtension = createGateExtension;
+const harness_1 = require("@agentic-kit/harness");
+function createGateExtension(options) {
+    const gate = (0, harness_1.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/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;

package/extensions/metered-model.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.piProviderConfig = piProviderConfig;
+exports.createMeteredModelExtension = createMeteredModelExtension;
+const metering_1 = require("@agentic-kit/metering");
+/** Shape a resolved gateway as pi's provider registration. */
+function piProviderConfig(gateway) {
+    return {
+        name: gateway.displayName,
+        baseUrl: gateway.baseUrl,
+        api: gateway.api,
+        headers: gateway.headers,
+        apiKey: gateway.apiKey,
+        models: gateway.models.map((model) => ({ ...model }))
+    };
+}
+function createMeteredModelExtension(options) {
+    const providerName = options.providerName ?? metering_1.DEFAULT_PROVIDER_NAME;
+    const gateway = (0, metering_1.resolveMeteredGateway)(options);
+    const config = piProviderConfig(gateway);
+    const modelId = options.selectModel === false ? undefined : (options.selectModel ?? options.models[0].id);
+    if (modelId !== undefined && !options.models.some((model) => model.id === modelId)) {
+        // Selecting an unregistered id silently leaves pi on an unmetered model,
+        // which is the one failure this lane exists to prevent.
+        throw new Error(`metered model: selectModel "${modelId}" is not one of the registered models`);
+    }
+    const extension = (pi) => {
+        pi.registerProvider(providerName, config);
+        if (modelId === undefined)
+            return;
+        // `pi.setModel` takes a resolved model, and the registry that resolves it
+        // lives on the context — which an extension only gets on an event.
+        // `session_start` is the first, and fires before the first turn.
+        pi.on('session_start', async (_event, ctx) => {
+            const model = ctx.modelRegistry.find(providerName, modelId);
+            if (!model)
+                throw new Error(`metered model: provider "${providerName}" has no model "${modelId}" after registration`);
+            const ok = await pi.setModel(model);
+            if (!ok)
+                throw new Error(`metered model: pi refused model "${providerName}/${modelId}" (no usable credentials for the gateway)`);
+        });
+    };
+    return { extension, config, gateway, providerName, selectedModel: modelId };
+}

package/extensions/run-log.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The pi side of the run log: drain the neutral session mirror after anything
+ * that can append an entry. Every listed event is a point where pi has just
+ * written to the session, so the run log trails the session by at most one event.
+ */
+import { type RunEventRecord, type RunLogAppendStore, SessionMirror } from '@agentic-kit/run-log';
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+/**
+ * Events after which the session may have grown. `session_start` also covers
+ * resume (pi replays the file before the first event), so a resumed run
+ * re-appends its history and the store's idempotency discards the duplicates.
+ */
+export declare const MIRROR_EVENTS: readonly ["session_start", "session_compact", "session_tree", "session_shutdown", "input", "before_agent_start", "message_end", "tool_execution_end", "turn_end", "agent_end", "model_select", "thinking_level_select"];
+export type MirrorEvent = (typeof MIRROR_EVENTS)[number];
+export interface RunLogExtensionOptions {
+    /** The run this session belongs to. Local and cloud runs differ only here. */
+    runId: string;
+    store: RunLogAppendStore;
+    /** pi session format version the entries are produced under. */
+    transcriptVersion?: number;
+    events?: readonly MirrorEvent[];
+    /**
+     * Called when a drain fails. Without it the failure is rethrown into pi's
+     * event dispatch: a run log that silently stops recording is worse than a
+     * loud one, so losing entries is never the default.
+     */
+    onError?: (error: unknown) => void;
+}
+export interface RunLogExtension {
+    extension: ExtensionFactory;
+    /** Drain now — for a host that wants the log flushed before it exits. */
+    flush(): Promise<RunEventRecord[]>;
+    mirror: SessionMirror;
+}
+export declare function createRunLogExtension(options: RunLogExtensionOptions): RunLogExtension;

package/extensions/run-log.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * The pi side of the run log: drain the neutral session mirror after anything
+ * that can append an entry. Every listed event is a point where pi has just
+ * written to the session, so the run log trails the session by at most one event.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIRROR_EVENTS = void 0;
+exports.createRunLogExtension = createRunLogExtension;
+const run_log_1 = require("@agentic-kit/run-log");
+/**
+ * Events after which the session may have grown. `session_start` also covers
+ * resume (pi replays the file before the first event), so a resumed run
+ * re-appends its history and the store's idempotency discards the duplicates.
+ */
+exports.MIRROR_EVENTS = [
+    'session_start',
+    'session_compact',
+    'session_tree',
+    'session_shutdown',
+    'input',
+    'before_agent_start',
+    'message_end',
+    'tool_execution_end',
+    'turn_end',
+    'agent_end',
+    'model_select',
+    'thinking_level_select'
+];
+function createRunLogExtension(options) {
+    const mirror = new run_log_1.SessionMirror({
+        runId: options.runId,
+        store: options.store,
+        transcriptFormat: run_log_1.PI_TRANSCRIPT_FORMAT,
+        ...(options.transcriptVersion === undefined ? {} : { transcriptVersion: options.transcriptVersion })
+    });
+    const events = options.events ?? exports.MIRROR_EVENTS;
+    const drain = async () => {
+        try {
+            return await mirror.drain();
+        }
+        catch (error) {
+            if (!options.onError)
+                throw error;
+            options.onError(error);
+            return [];
+        }
+    };
+    const extension = (pi) => {
+        for (const event of events) {
+            // Each overload of `on` is typed for its own handler; the handler here
+            // ignores the event and only reads the context, so one cast at the
+            // registration boundary keeps the loop.
+            pi.on(event, async (_event, ctx) => {
+                mirror.bind(ctx.sessionManager);
+                await drain();
+            });
+        }
+    };
+    return { extension, flush: drain, mirror };
+}

package/extensions/usage-report.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The pi side of the self-reporting lane: report each assistant message's usage
+ * to the gateway.
+ *
+ * This is the local / own-provider-key lane. The agent's own numbers are the only
+ * source, so a report is *self-reported* — good for reconciliation and for usage
+ * visibility on a developer's own key, not tamper-proof billing. When the run
+ * must be billed authoritatively, route the model calls through the gateway with
+ * `./metered-model` instead; the gateway then meters itself and this extension is
+ * unnecessary.
+ *
+ * Everything but the two event hooks below is `@agentic-kit/metering`.
+ */
+import { type MeteredIdentity, type UsageReport, UsageReporter } from '@agentic-kit/metering';
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+export interface UsageReportExtensionOptions {
+    identity: MeteredIdentity;
+    /** Gateway root. Required unless a custom `sink` is supplied. */
+    gatewayUrl?: string;
+    /** Delivery override — e.g. an in-process sink, or a queue. */
+    sink?: (report: UsageReport) => Promise<void>;
+    fetch?: typeof globalThis.fetch;
+    /** `operation` column value; defaults to `agent/chat`. */
+    operation?: string;
+    /** Report failures here instead of having `flush()` rethrow them. */
+    onError?: (error: unknown, report: UsageReport) => void;
+}
+export interface UsageReportExtension {
+    extension: ExtensionFactory;
+    /** Drain the queue and rethrow the first delivery failure. */
+    flush(): Promise<void>;
+    reporter: UsageReporter;
+}
+export declare function createUsageReportExtension(options: UsageReportExtensionOptions): UsageReportExtension;

package/extensions/usage-report.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * The pi side of the self-reporting lane: report each assistant message's usage
+ * to the gateway.
+ *
+ * This is the local / own-provider-key lane. The agent's own numbers are the only
+ * source, so a report is *self-reported* — good for reconciliation and for usage
+ * visibility on a developer's own key, not tamper-proof billing. When the run
+ * must be billed authoritatively, route the model calls through the gateway with
+ * `./metered-model` instead; the gateway then meters itself and this extension is
+ * unnecessary.
+ *
+ * Everything but the two event hooks below is `@agentic-kit/metering`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUsageReportExtension = createUsageReportExtension;
+const metering_1 = require("@agentic-kit/metering");
+function createUsageReportExtension(options) {
+    const sink = options.sink ??
+        (0, metering_1.httpUsageSink)({
+            gatewayUrl: requireGatewayUrl(options),
+            identity: options.identity,
+            ...(options.fetch ? { fetch: options.fetch } : {})
+        });
+    const reporter = new metering_1.UsageReporter({ sink, ...(options.onError ? { onError: options.onError } : {}) });
+    // pi can emit `message_end` more than once for the same response (a rewritten
+    // message, a replayed entry on resume), and each emission would otherwise bill
+    // again. `responseId` is the provider's identity for the response, so it is
+    // what dedupes; messages without one are reported as-is.
+    const seen = new Set();
+    const extension = (pi) => {
+        pi.on('message_end', (event) => {
+            const message = event.message;
+            if (!(0, metering_1.isAssistantMessage)(message))
+                return;
+            const responseId = message.responseId;
+            if (typeof responseId === 'string' && responseId.length > 0) {
+                if (seen.has(responseId))
+                    return;
+                seen.add(responseId);
+            }
+            const report = (0, metering_1.toUsageReport)(message, options.operation === undefined ? {} : { operation: options.operation });
+            if (report)
+                reporter.enqueue(report);
+        });
+        pi.on('session_shutdown', async () => {
+            await reporter.flush();
+        });
+    };
+    return { extension, flush: () => reporter.flush(), reporter };
+}
+function requireGatewayUrl(options) {
+    if (!options.gatewayUrl)
+        throw new Error('usage report: gatewayUrl is required unless a custom sink is provided');
+    return options.gatewayUrl;
+}

package/harness.d.ts

@@ -0,0 +1,16 @@
+/**
+ * pi as a `HarnessAdapter`.
+ *
+ * The adapter is thin by design: everything a run actually does — gating, run
+ * log, metering — already lives behind neutral contracts, so all that is left
+ * here is pi's identity, the transcript it writes, and its way of attaching
+ * extensions (a resource loader). A second harness implements the same three
+ * things against its own plugin surface, and hosts keep calling `startRun`.
+ */
+import type { HarnessAdapter, HarnessRun } from '@agentic-kit/harness';
+import { type EmbeddedRun, type StartRunOptions } from './embed/session';
+export declare const PI_HARNESS_ID = "pi";
+export interface PiHarnessRun extends EmbeddedRun, HarnessRun {
+    readonly runId: string;
+}
+export declare const piHarness: HarnessAdapter<StartRunOptions, PiHarnessRun>;