operon-agents 0.1.0-alpha.4 → 0.1.0-alpha.6

package/README.md

@@ -16,3 +16,40 @@ import { TransportMCPServer } from "operon-agents/mcp";
 import { bashTool, readTool } from "operon-agents/tools";
 import { OTelTracingProcessor } from "operon-agents/tracing";
 ```
+
+## Tracing
+
+Every session drives a `TracingProcessor` registered on the harness scope as `T.Tracing`: one
+trace per run (a prompt and everything it triggers), spans for agents, turns, model generations,
+tool calls and sub-agents, the session id on every span as `gen_ai.conversation.id`. By default
+spans are metadata only. Pass `content: "delta"` to also record the system prompt, the messages
+the model was asked to answer, its output, tool arguments and results — enough to replay a
+conversation in a trace viewer. Local Jaeger:
+
+```sh
+docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:2.9.0
+```
+
+```ts
+import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { OTelTracingProcessor } from "operon-agents/tracing";
+import { T } from "operon-agents/core";
+
+const provider = new NodeTracerProvider({
+  resource: resourceFromAttributes({ "service.name": "my-agent" }),
+  spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter({ url: "http://localhost:4318/v1/traces" }))],
+});
+const tracing = new OTelTracingProcessor({ tracer: provider.getTracer("my-agent"), tracerProvider: provider, content: "delta", shutdownProvider: true });
+
+const harness = await createLocalHarness({
+  model,
+  harness: (scope) => scope.register(T.Tracing, tracing),
+});
+```
+
+`content: "full"` repeats the entire context on every generation (trace size grows with steps ×
+context); `contentMaxChars` caps each attribute; `redact: true` masks tokens, emails and keys
+before export when the collector is not on the same machine.
+

package/dist/harness.d.ts

@@ -11,7 +11,7 @@
  * low-level "assemble it yourself / stateless server" path, import from
  * `operon-agents/core` instead.
  */
-import { type AgentEvent, type EventPublicationMode, type AgentEventListener, type AgentInput, SessionProjection, type SessionSnapshot, type SnapshotOptions, type DirectoryEntry, type ProjectionObservation, type ProjectionListener, type ApprovalRequest, type ApprovalResponse, type Capability, type InterruptAnswer, type ChatModel, ListenerSink, type PermissionManagerOptions, type PermissionMode, type PendingRunInterrupt, type QuestionRequest, type QuestionResult, type Responder, type RunHandle, type RunResult, type SessionStore, type SessionHandle, type SessionSummary, type ListSessionsFilter, type OpenSessionOptions, type DeleteSessionOptions, type ThinkingLevel, type Tool, type ExternalOriginMetadataValue, type SteerChannel, type SteerOrigin, Agent, Runner, Session, McpOAuthService, type HookDef, type McpServerConfig, type PluginManager, type ApprovalRequestOptions, type Machine, type MachineFactory, type ResolvedAgentProfile, type SubagentProvider, Scope } from "operon-agents-core";
+import { type AgentEvent, type EventPublicationMode, type TelemetryService, type AgentEventListener, type AgentInput, SessionProjection, type SessionSnapshot, type SnapshotOptions, type DirectoryEntry, type ProjectionObservation, type ProjectionListener, type ApprovalRequest, type ApprovalResponse, type Capability, type InterruptAnswer, type ChatModel, ListenerSink, type PermissionManagerOptions, type PermissionMode, type PendingRunInterrupt, type QuestionRequest, type QuestionResult, type Responder, type RunHandle, type RunResult, type SessionStore, type SessionHandle, type SessionSummary, type ListSessionsFilter, type OpenSessionOptions, type DeleteSessionOptions, type ThinkingLevel, type Tool, type ExternalOriginMetadataValue, type SteerChannel, type SteerOrigin, Agent, Runner, Session, McpOAuthService, type HookDef, type McpServerConfig, type PluginManager, type ApprovalRequestOptions, type Machine, type MachineFactory, type ResolvedAgentProfile, type SubagentProvider, Scope } from "operon-agents-core";
 import { HarnessExtensionManager, ServiceRegistry, type ExtensionDefinition, type ServiceOptions } from "./extensions/index.ts";
 import { type CommandResult } from "operon-agents-core";
 export type ApprovalHandler = (request: ApprovalRequest, options?: ApprovalRequestOptions) => Promise<ApprovalResponse> | ApprovalResponse;
@@ -19,6 +19,11 @@ export type QuestionHandler = (request: QuestionRequest, options?: {
     readonly signal?: AbortSignal;
 }) => Promise<QuestionResult> | QuestionResult;
 export type HarnessSessionState = "idle" | "running" | "interrupted" | "closed";
+/** Test-only (exported via `operon-agents/internal`): shrink the close deadlines. */
+export declare function setHarnessCloseTimeoutsForTest(ms: {
+    runSettle?: number;
+    scopeDispose?: number;
+}): void;
 export type DeliveryMode = "auto" | "steer" | "follow_up";
 export interface DeliveryOptions {
     readonly source: string;
@@ -160,6 +165,12 @@ export interface HarnessOptions<TContext = unknown> {
     /** Event durability policy. Defaults to `immediate` for low-latency local applications.
      *  Managed servers override each opened session to `committed`. */
     readonly eventPublication?: EventPublicationMode;
+    /**
+     * Product telemetry (docs/telemetry.md). Process-lifetime: create ONE service, attach the
+     * appenders once, pass the same instance to every harness. Absent = nothing is counted.
+     * The harness never shuts it down; the product does, before exit.
+     */
+    readonly telemetry?: TelemetryService;
     /**
      * Extra subagent profiles merged into the builtin `coder`/`explore`/`plan` fleet. The SOURCE is
      * the composition root's concern — disk (`loadAgentProfiles`) locally, external on a server —
@@ -396,17 +407,27 @@ export declare class HarnessSession<TContext = unknown> {
     private readonly responder;
     private readonly onClosed;
     private runContext;
-    private currentRun;
     /** Barrier gate (docs/architecture.md §5.5): while set, no NEW run starts on this
      *  session — prompt/resume park at it, promptStream starts lazily behind it. The in-flight
      *  run is never touched. */
     private runGate;
-    /** Resolves when the latest run settles — the "arrived at the boundary" signal a barrier
-     *  coordinator awaits. Undefined while idle. */
-    private runSettled;
-    private readonly runSettles;
+    /**
+     * Every run this facade has begun and not yet seen settle, by its controller. More than one
+     * entry means runs are queued behind the core's run lock (`prompt` while a turn is in flight):
+     * "busy" is this set being non-empty, `cancel()` aborts ALL of them, and the barrier's
+     * quiescence is ALL of them settling — tracking only the last-begun run would abort the
+     * queued one and leave the running one untouched.
+     */
+    private readonly runs;
     private lastRunInterrupted;
-    private closed;
+    /** open → closing (runs being drained, resources going down) → closed. Never goes back. */
+    private lifecycle;
+    /** The one close in flight (or finished): every `close()` call returns THIS promise. */
+    private closing;
+    /** Resolves the moment close() begins — what wakes a caller parked at the barrier gate so it
+     *  can fail with the closed error instead of hanging on a gate nobody will release. */
+    private notifyClosing;
+    private readonly closingNotified;
     private deliveryCounter;
     /** A wake is already scheduled on the microtask queue; more enqueues fold into it. */
     private wakeScheduled;
@@ -429,11 +450,19 @@ export declare class HarnessSession<TContext = unknown> {
      * Start a turn to consume queued follow-ups, once the current synchronous work is done.
      *
      * Deferred to a microtask for two reasons: several enqueues in one stack fold into a single
-     * wake, and a settle that lands in a finishing run's own stack sees `currentRun` already
+     * wake, and a settle that lands in a finishing run's own stack sees its run already
      * cleared. Re-checked at fire time because either can change in between — and re-checked
      * again after every run, since the queue may have filled during one whose drain had passed.
      */
     private scheduleIdleWake;
+    /** Not open: closing or closed. Every run entry point refuses from here on. */
+    private get closed();
+    /**
+     * Park at the barrier gate until released — or until this session starts closing, in which
+     * case fail with the closed error rather than wait on a gate no coordinator will release.
+     * Re-checked in a loop: a new hold can land between a release and this task resuming.
+     */
+    private parkAtGate;
     /** Run options every run on this session carries — currently the session's turn cap. */
     private get runOverrides();
     /** Current runtime-only application context supplied to Agent callbacks. */
@@ -446,6 +475,10 @@ export declare class HarnessSession<TContext = unknown> {
     setContext(context: TContext | undefined): void;
     private beginRun;
     private endRun;
+    /** A run is in flight or queued behind the core's run lock. */
+    private hasActiveRuns;
+    /** Settles when every run begun so far has settled (trivially, when idle). */
+    private allRunsSettled;
     /**
      * Barrier support (docs/architecture.md §5.5): refuse NEW runs until released and
      * report when this session reaches its run boundary. Installing the gate is synchronous — a
@@ -532,7 +565,7 @@ export declare class HarnessSession<TContext = unknown> {
      * active run — use `prompt` instead in that case.
      */
     followUp(input: string): string | null;
-    /** Abort the current run. */
+    /** Abort every run this session has accepted: the one in flight AND any queued behind it. */
     cancel(): void;
     /** Subscribe to this session's event stream. Returns an unsubscribe fn. */
     onEvent(listener: AgentEventListener): () => void;
@@ -615,8 +648,18 @@ export declare class HarnessSession<TContext = unknown> {
     listMcpTools(...args: Parameters<Session["listMcpTools"]>): ReturnType<Session["listMcpTools"]>;
     listMcpServers(...args: Parameters<Session["listMcpServers"]>): ReturnType<Session["listMcpServers"]>;
     reconnectMcpServer(...args: Parameters<Session["reconnectMcpServer"]>): ReturnType<Session["reconnectMcpServer"]>;
-    /** Close the session and release its resources. */
+    /**
+     * Close the session and release its resources. Order: stop accepting runs, abort the ones
+     * accepted (in flight and queued) and wait for them to settle — their tools' finally blocks,
+     * their journal writes — then detach the projection and take the core down. Every call
+     * returns the SAME promise, so nobody returns while the teardown is still running.
+     *
+     * The wait for runs is bounded (`CLOSE_RUN_WAIT_MS`, 5s): a run that ignores its abort signal
+     * is logged and left behind, and the teardown continues — the deadline caps the wait for
+     * runs, not the whole close (flushes and disposes carry their own deadlines).
+     */
     close(): Promise<void>;
+    private runClose;
 }
 /** Manages a fleet of in-process sessions over a shared engine config. */
 export declare class Harness<TContext = unknown> {
@@ -625,6 +668,11 @@ export declare class Harness<TContext = unknown> {
     /** Concrete tools the default profile's tool NAMES resolve against (keyed by schema name). */
     private readonly toolPalette;
     private readonly activeSessions;
+    /** Opens in flight by session id (`resumeSession`): concurrent callers share ONE open — the
+     *  whole of it, reconcile and failure cleanup included — instead of each building an instance. */
+    private readonly opening;
+    /** The one close in flight (or finished): every `close()` call returns THIS promise. */
+    private closing;
     /** The harness-tier scope: every process-lived object, and the parent of every workspace scope. */
     readonly scope: Scope<"harness">;
     /** Workspace scopes by key, reference-counted by the sessions open under them. */
@@ -686,6 +734,19 @@ export declare class Harness<TContext = unknown> {
     private buildDefaultAgent;
     get sessions(): ReadonlyMap<string, HarnessSession<TContext>>;
     createSession(opts?: CreateSessionOptions<TContext>): Promise<HarnessSession<TContext>>;
+    /**
+     * Register an open in flight under its id for as long as it runs. Every path that builds a
+     * session goes through here — create, resume, fork — so a `resumeSession` for an id that is
+     * being created joins that open instead of building a twin over the same store, and
+     * `closeSession` / `harness.close()` wait for it instead of closing its scope under it.
+     */
+    private trackOpen;
+    /**
+     * The open session with this id, or reopen it from the store. Concurrent calls for one id share
+     * a single open (`opening`): the second caller waits for the first's — reconcile included — and
+     * receives the same instance, never a second one that a close would then unregister. An
+     * instance that is closing is not handed out: the reopen waits for its close to finish first.
+     */
     resumeSession(id: string, opts?: ResumeSessionOptions<TContext>): Promise<HarnessSession<TContext>>;
     /** Fork an existing session into a new one (copies its log + state) and open it. */
     forkSession(sourceId: string, opts?: ForkSessionOptions<TContext>): Promise<HarnessSession<TContext>>;
@@ -697,7 +758,8 @@ export declare class Harness<TContext = unknown> {
     inspectSession(id: string, options?: OpenSessionOptions): Promise<SessionHandle | undefined>;
     /** Read one catalog row without the O(N) `listSessions()` scan. */
     getSessionSummary(id: string): Promise<SessionSummary | undefined>;
-    /** Close one open session by id (no-op if it isn't open). */
+    /** Close one open session by id (no-op if it isn't open). An open in flight for this id is
+     *  waited for and then closed, so a close/delete never races a half-built session. */
     closeSession(id: string): Promise<void>;
     /**
      * Delete a session after releasing any open in-process handle. Soft by default — the durable
@@ -714,6 +776,9 @@ export declare class Harness<TContext = unknown> {
      * registrations, then the defaults.
      */
     close(): Promise<void>;
+    private runClose;
+    /** Every path that opens a session starts here: a closing harness opens nothing new. */
+    private assertAcceptingSessions;
     /**
      * Replace by-value extensions with new versions, as one coordinated act — the by-value twin of
      * `harness.extensions.reload()` (docs/architecture.md §5.5). Every session holding
@@ -773,6 +838,12 @@ export declare class Harness<TContext = unknown> {
      */
     private extensionHost;
     private openFromStore;
+    /**
+     * Undo a failed `openFromStore`, newest artifact first. Every step runs even if an earlier one
+     * throws (a cleanup failure is logged, never allowed to mask the open's own error), and the
+     * workspace hold this open took is always returned.
+     */
+    private rollbackOpen;
     /**
      * The workspace scope for `key`, composed on first use — the host's `workspace` hook, then
      * every registered extension's `workspace` half — and ref-counted by the sessions under it.
@@ -780,6 +851,8 @@ export declare class Harness<TContext = unknown> {
     private acquireWorkspace;
     /** Drop one session's hold; the last one out closes the workspace scope. */
     private releaseWorkspace;
+    /** Close options for a scope the harness tears down itself: per-service deadline, failures logged. */
+    private scopeCloseOptions;
     /**
      * A handle to a workspace-tier extension service in ONE workspace — how a host reaches a
      * `workspace` half's instance (`harness.services.handle` only answers for the harness tier).

package/dist/harness.js

@@ -19,6 +19,19 @@ import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { assertOneSharedHalf, extensionsCapability, ExtensionRuntime, HarnessExtensionManager, ServiceRegistry, stageDefinition } from "./extensions/index.js";
 import { createExtensionCommandRegistry } from "operon-agents-core";
+/** How long `HarnessSession.close()` waits for aborted runs to settle before continuing teardown. */
+let CLOSE_RUN_WAIT_MS = 5_000;
+/** Per-service dispose deadline when the harness tears a scope down itself — a workspace whose
+ *  last session left, a session scope a failed open rolls back, the harness scope on close.
+ *  Mirrors the core session's own close deadline: one hung MCP shutdown must not hang close(). */
+let SCOPE_DISPOSE_TIMEOUT_MS = 5_000;
+/** Test-only (exported via `operon-agents/internal`): shrink the close deadlines. */
+export function setHarnessCloseTimeoutsForTest(ms) {
+    if (ms.runSettle !== undefined)
+        CLOSE_RUN_WAIT_MS = ms.runSettle;
+    if (ms.scopeDispose !== undefined)
+        SCOPE_DISPOSE_TIMEOUT_MS = ms.scopeDispose;
+}
 /** Rendezvous budget for `replaceExtension` when the caller names none. */
 const DEFAULT_REPLACE_TIMEOUT_MS = 30_000;
 /** Session-store key holding the per-session extension params map (see `createSession({ params })`). */
@@ -153,17 +166,29 @@ export class HarnessSession {
     responder;
     onClosed;
     runContext;
-    currentRun;
     /** Barrier gate (docs/architecture.md §5.5): while set, no NEW run starts on this
      *  session — prompt/resume park at it, promptStream starts lazily behind it. The in-flight
      *  run is never touched. */
     runGate;
-    /** Resolves when the latest run settles — the "arrived at the boundary" signal a barrier
-     *  coordinator awaits. Undefined while idle. */
-    runSettled;
-    runSettles = new Map();
+    /**
+     * Every run this facade has begun and not yet seen settle, by its controller. More than one
+     * entry means runs are queued behind the core's run lock (`prompt` while a turn is in flight):
+     * "busy" is this set being non-empty, `cancel()` aborts ALL of them, and the barrier's
+     * quiescence is ALL of them settling — tracking only the last-begun run would abort the
+     * queued one and leave the running one untouched.
+     */
+    runs = new Map();
     lastRunInterrupted = false;
-    closed = false;
+    /** open → closing (runs being drained, resources going down) → closed. Never goes back. */
+    lifecycle = "open";
+    /** The one close in flight (or finished): every `close()` call returns THIS promise. */
+    closing;
+    /** Resolves the moment close() begins — what wakes a caller parked at the barrier gate so it
+     *  can fail with the closed error instead of hanging on a gate nobody will release. */
+    notifyClosing;
+    closingNotified = new Promise((resolve) => {
+        this.notifyClosing = resolve;
+    });
     deliveryCounter = 0;
     /** A wake is already scheduled on the microtask queue; more enqueues fold into it. */
     wakeScheduled = false;
@@ -193,7 +218,7 @@ export class HarnessSession {
      * Start a turn to consume queued follow-ups, once the current synchronous work is done.
      *
      * Deferred to a microtask for two reasons: several enqueues in one stack fold into a single
-     * wake, and a settle that lands in a finishing run's own stack sees `currentRun` already
+     * wake, and a settle that lands in a finishing run's own stack sees its run already
      * cleared. Re-checked at fire time because either can change in between — and re-checked
      * again after every run, since the queue may have filled during one whose drain had passed.
      */
@@ -211,7 +236,7 @@ export class HarnessSession {
                 return;
             // A run in flight drains at its own turn boundary; an interrupted one must be resumed,
             // not talked over.
-            if (this.currentRun !== undefined)
+            if (this.hasActiveRuns())
                 return;
             // Either channel counts. A "steering" item is an interruption of work in flight, but with
             // nothing in flight there is nothing to interrupt — it is simply the next input, and the
@@ -223,6 +248,22 @@ export class HarnessSession {
             void this.runPrompt([]).catch(() => undefined);
         });
     }
+    /** Not open: closing or closed. Every run entry point refuses from here on. */
+    get closed() {
+        return this.lifecycle !== "open";
+    }
+    /**
+     * Park at the barrier gate until released — or until this session starts closing, in which
+     * case fail with the closed error rather than wait on a gate no coordinator will release.
+     * Re-checked in a loop: a new hold can land between a release and this task resuming.
+     */
+    async parkAtGate() {
+        while (this.runGate !== undefined) {
+            await Promise.race([this.runGate.released, this.closingNotified]);
+            if (this.closed)
+                throw new Error(`session "${this.id}" is closed`);
+        }
+    }
     /** Run options every run on this session carries — currently the session's turn cap. */
     get runOverrides() {
         return this.maxTurns !== undefined ? { maxTurns: this.maxTurns } : {};
@@ -235,7 +276,7 @@ export class HarnessSession {
         return {
             state: this.closed
                 ? "closed"
-                : this.currentRun !== undefined
+                : this.hasActiveRuns()
                     ? "running"
                     : this.lastRunInterrupted
                         ? "interrupted"
@@ -258,16 +299,23 @@ export class HarnessSession {
     }
     // ── Run driving (the methods core Session does not have) ──
     beginRun(controller) {
-        this.currentRun = controller;
-        this.runSettled = new Promise((resolve) => {
-            this.runSettles.set(controller, resolve);
+        let resolve;
+        const settled = new Promise((r) => {
+            resolve = r;
         });
+        this.runs.set(controller, { settled, resolve });
     }
     endRun(controller) {
-        if (this.currentRun === controller)
-            this.currentRun = undefined;
-        this.runSettles.get(controller)?.();
-        this.runSettles.delete(controller);
+        this.runs.get(controller)?.resolve();
+        this.runs.delete(controller);
+    }
+    /** A run is in flight or queued behind the core's run lock. */
+    hasActiveRuns() {
+        return this.runs.size > 0;
+    }
+    /** Settles when every run begun so far has settled (trivially, when idle). */
+    allRunsSettled() {
+        return Promise.all([...this.runs.values()].map((run) => run.settled)).then(() => undefined);
     }
     /**
      * Barrier support (docs/architecture.md §5.5): refuse NEW runs until released and
@@ -284,7 +332,7 @@ export class HarnessSession {
         });
         const gate = { released, release: releaseGate };
         this.runGate = gate;
-        const quiescent = this.currentRun !== undefined ? (this.runSettled ?? Promise.resolve()) : Promise.resolve();
+        const quiescent = this.allRunsSettled();
         return {
             quiescent,
             release: () => {
@@ -303,10 +351,11 @@ export class HarnessSession {
     async runPrompt(input, inputOrigin) {
         if (this.closed)
             throw new Error(`session "${this.id}" is closed`);
-        // Barrier gate: park (never fail) until released. A loop, not an if — a new hold can land
-        // between the release and this task resuming.
-        while (this.runGate !== undefined)
-            await this.runGate.released;
+        // Barrier gate: park until released (a hold is "wait", not "fail") — unless the session
+        // closes meanwhile, which is the one thing that turns the wait into a failure. Ungated, the
+        // run is registered SYNCHRONOUSLY: a cancel() or close() on the next line must find it.
+        if (this.runGate !== undefined)
+            await this.parkAtGate();
         const controller = new AbortController();
         this.beginRun(controller);
         try {
@@ -330,7 +379,7 @@ export class HarnessSession {
         finally {
             this.endRun(controller);
             // A follow-up can land after this run's last drain but before it settles — that enqueue
-            // saw `currentRun` set and stood down, so the run itself has to look once on the way out.
+            // saw an active run and stood down, so the run itself has to look once on the way out.
             this.scheduleIdleWake();
         }
     }
@@ -343,7 +392,7 @@ export class HarnessSession {
         if (this.closed || this.lastRunInterrupted)
             return false;
         // A run in flight drains its own queues, so handing the message to the frame is enough.
-        if (this.currentRun !== undefined)
+        if (this.hasActiveRuns())
             return this.core.steerTo(address, content, origin);
         // Idle: only the root frame can be woken. A subagent whose frame has ended is not a teammate
         // waiting for mail — it is a finished delegation, and only the parent that delegated it can
@@ -375,7 +424,7 @@ export class HarnessSession {
     async deliver(input, options) {
         if (this.closed)
             throw new Error(`session "${this.id}" is closed`);
-        if (this.lastRunInterrupted && this.currentRun === undefined) {
+        if (this.lastRunInterrupted && !this.hasActiveRuns()) {
             throw new Error(`session "${this.id}" is interrupted; resume it before delivering new work`);
         }
         if (!options.source.trim())
@@ -438,7 +487,7 @@ export class HarnessSession {
         const channel = origin.kind === "external"
             ? origin.channel ?? "steering"
             : origin.kind === "user_follow_up" ? "follow_up" : "steering";
-        if (this.currentRun !== undefined) {
+        if (this.hasActiveRuns()) {
             const receipt = this.core.steer.steer(input, origin);
             return {
                 deliveryId,
@@ -491,11 +540,13 @@ export class HarnessSession {
      * copy see a "stale interruption state" error; re-fetching the persisted state clears it.
      */
     async resume(answers) {
+        if (this.closed)
+            throw new Error(`session "${this.id}" is closed`);
         // Barrier gate first (a coordinator holding the barrier should not be resumed against —
-        // the call parks here until release rather than failing).
-        while (this.runGate !== undefined)
-            await this.runGate.released;
-        if (this.currentRun !== undefined)
+        // the call parks here until release rather than failing; closing meanwhile does fail it).
+        if (this.runGate !== undefined)
+            await this.parkAtGate();
+        if (this.hasActiveRuns())
             throw new Error(`session "${this.id}" already has an active run`);
         const controller = new AbortController();
         // Set this BEFORE the first await (past the gate). A host returning 202 from resume can
@@ -535,6 +586,8 @@ export class HarnessSession {
     }
     /** Streaming variant: iterate events, await `.completed` for the result. */
     promptStream(input) {
+        if (this.closed)
+            throw new Error(`session "${this.id}" is closed`);
         const controller = new AbortController();
         // Ungated: start synchronously, byte-identical to the pre-barrier behavior. Gated: the
         // handle returns immediately but the underlying run starts only after release (lazy start —
@@ -544,8 +597,7 @@ export class HarnessSession {
             this.beginRun(controller);
         const start = (async () => {
             if (gated) {
-                while (this.runGate !== undefined)
-                    await this.runGate.released;
+                await this.parkAtGate();
                 this.beginRun(controller);
             }
             return this.runner.runStream(this.agent, input, {
@@ -571,6 +623,9 @@ export class HarnessSession {
         })
             .finally(() => {
             this.endRun(controller);
+            // Same as runPrompt's exit: input queued after this run's last drain (a background
+            // notification landing at agent.ended) needs a wake, or it sits until the next prompt.
+            this.scheduleIdleWake();
         });
         // Guard the floating promise so iterate-only callers don't trip an unhandled rejection
         // (mirrors runStream's own internal guard); awaiters still receive a real rejection.
@@ -619,13 +674,14 @@ export class HarnessSession {
      * active run — use `prompt` instead in that case.
      */
     followUp(input) {
-        if (this.currentRun === undefined)
+        if (!this.hasActiveRuns())
             return null;
         return this.core.steer.followUp(input).steerId;
     }
-    /** Abort the current run. */
+    /** Abort every run this session has accepted: the one in flight AND any queued behind it. */
     cancel() {
-        this.currentRun?.abort();
+        for (const controller of [...this.runs.keys()])
+            controller.abort();
     }
     /** Subscribe to this session's event stream. Returns an unsubscribe fn. */
     onEvent(listener) {
@@ -833,15 +889,50 @@ export class HarnessSession {
     reconnectMcpServer(...args) {
         return this.core.reconnectMcpServer(...args);
     }
-    /** Close the session and release its resources. */
-    async close() {
-        if (this.closed)
-            return;
-        this.closed = true;
-        this.cancel();
-        this.projection.detach();
-        await this.core.close();
-        await this.onClosed(this.id);
+    /**
+     * Close the session and release its resources. Order: stop accepting runs, abort the ones
+     * accepted (in flight and queued) and wait for them to settle — their tools' finally blocks,
+     * their journal writes — then detach the projection and take the core down. Every call
+     * returns the SAME promise, so nobody returns while the teardown is still running.
+     *
+     * The wait for runs is bounded (`CLOSE_RUN_WAIT_MS`, 5s): a run that ignores its abort signal
+     * is logged and left behind, and the teardown continues — the deadline caps the wait for
+     * runs, not the whole close (flushes and disposes carry their own deadlines).
+     */
+    close() {
+        if (this.closing !== undefined)
+            return this.closing;
+        this.lifecycle = "closing";
+        this.notifyClosing();
+        this.closing = this.runClose();
+        return this.closing;
+    }
+    async runClose() {
+        try {
+            const settled = this.allRunsSettled();
+            this.cancel();
+            let timer;
+            const timedOut = await Promise.race([
+                settled.then(() => false),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(true), CLOSE_RUN_WAIT_MS);
+                }),
+            ]);
+            clearTimeout(timer);
+            if (timedOut) {
+                this.core.logger.log("warn", "session close: runs still settling after the deadline; continuing teardown", {
+                    sessionId: this.id,
+                    runs: this.runs.size,
+                    deadlineMs: CLOSE_RUN_WAIT_MS,
+                });
+            }
+            this.projection.detach();
+            await this.core.close();
+            await this.onClosed(this.id);
+        }
+        finally {
+            this.lifecycle = "closed";
+        }
     }
 }
 /** Manages a fleet of in-process sessions over a shared engine config. */
@@ -851,6 +942,11 @@ export class Harness {
     /** Concrete tools the default profile's tool NAMES resolve against (keyed by schema name). */
     toolPalette;
     activeSessions = new Map();
+    /** Opens in flight by session id (`resumeSession`): concurrent callers share ONE open — the
+     *  whole of it, reconcile and failure cleanup included — instead of each building an instance. */
+    opening = new Map();
+    /** The one close in flight (or finished): every `close()` call returns THIS promise. */
+    closing;
     /** The harness-tier scope: every process-lived object, and the parent of every workspace scope. */
     scope;
     /** Workspace scopes by key, reference-counted by the sessions open under them. */
@@ -888,6 +984,8 @@ export class Harness {
         this.scope.provide(T.SessionRepository, () => new MemorySessionRepository());
         if (options.eventPublication !== undefined)
             this.scope.register(T.EventPublication, options.eventPublication);
+        if (options.telemetry !== undefined)
+            this.scope.register(T.Telemetry, options.telemetry, { owned: false });
         const agentTools = options.tools ?? [...filesystemTools(), askUserQuestionTool];
         this.toolPalette = Object.fromEntries(agentTools.map((tool) => [tool.schema.name, tool]));
         // The Agent/Workflow tools only appear when the run has subagents to spawn. Default the fleet
@@ -1068,36 +1166,91 @@ export class Harness {
         return this.activeSessions;
     }
     async createSession(opts = {}) {
+        this.assertAcceptingSessions();
         const workDir = opts.workDir ?? this.options.workDir ?? process.cwd();
         const handle = await (await this.repository()).create({ id: opts.id, workDir, ownerKey: opts.ownerKey, title: opts.title });
-        return this.openFromStore(handle.id, handle.workDir, handle.store, opts);
+        return this.trackOpen(handle.id, () => this.openFromStore(handle.id, handle.workDir, handle.store, opts));
+    }
+    /**
+     * Register an open in flight under its id for as long as it runs. Every path that builds a
+     * session goes through here — create, resume, fork — so a `resumeSession` for an id that is
+     * being created joins that open instead of building a twin over the same store, and
+     * `closeSession` / `harness.close()` wait for it instead of closing its scope under it.
+     */
+    trackOpen(id, open) {
+        const promise = open().finally(() => {
+            if (this.opening.get(id) === promise)
+                this.opening.delete(id);
+        });
+        this.opening.set(id, promise);
+        return promise;
     }
-    async resumeSession(id, opts = {}) {
+    /**
+     * The open session with this id, or reopen it from the store. Concurrent calls for one id share
+     * a single open (`opening`): the second caller waits for the first's — reconcile included — and
+     * receives the same instance, never a second one that a close would then unregister. An
+     * instance that is closing is not handed out: the reopen waits for its close to finish first.
+     */
+    resumeSession(id, opts = {}) {
+        // Not async (the in-flight/active fast paths return existing promises), so refuse by rejecting.
+        if (this.closing !== undefined)
+            return Promise.reject(new Error("harness is closed"));
+        const inflight = this.opening.get(id);
+        if (inflight !== undefined) {
+            return hasOwnContext(opts)
+                ? inflight.then((session) => {
+                    session.setContext(opts.context);
+                    return session;
+                })
+                : inflight;
+        }
         const existing = this.activeSessions.get(id);
-        if (existing) {
+        if (existing !== undefined && existing.status.state !== "closed") {
             if (hasOwnContext(opts))
                 existing.setContext(opts.context);
-            return existing;
+            return Promise.resolve(existing);
         }
-        const handle = await (await this.repository()).open(id);
-        if (handle === undefined)
-            throw new SessionRepositoryNotFoundError(id);
-        const session = await this.openFromStore(handle.id, handle.workDir, handle.store, opts);
-        // Reopening: orphaned background subagents (running from a dead process) → lost.
-        await session.reconcileSubagents();
-        return session;
+        return this.trackOpen(id, async () => {
+            // `existing` here is one that is closing: wait for that close (its registration and
+            // workspace hold go with it) rather than open a twin beside it.
+            if (existing !== undefined)
+                await existing.close();
+            const handle = await (await this.repository()).open(id);
+            if (handle === undefined)
+                throw new SessionRepositoryNotFoundError(id);
+            const session = await this.openFromStore(handle.id, handle.workDir, handle.store, opts);
+            // Reopening: orphaned background subagents (running from a dead process) → lost. A failure
+            // here is an open failure: the session is torn down, not left registered and unreturned.
+            try {
+                await session.reconcileSubagents();
+            }
+            catch (error) {
+                await session.close();
+                throw error;
+            }
+            return session;
+        });
     }
     /** Fork an existing session into a new one (copies its log + state) and open it. */
     async forkSession(sourceId, opts = {}) {
+        this.assertAcceptingSessions();
         const handle = await (await this.repository()).fork(sourceId, {
             ...(opts.id !== undefined ? { id: opts.id } : {}),
             ...(opts.ownerKey !== undefined ? { ownerKey: opts.ownerKey } : {}),
             ...(opts.title !== undefined ? { title: opts.title } : {}),
         });
-        const session = await this.openFromStore(handle.id, handle.workDir, handle.store, opts);
-        // A fork copies the subagent ledger; its background "running" rows have no live task → lost.
-        await session.reconcileSubagents();
-        return session;
+        return this.trackOpen(handle.id, async () => {
+            const session = await this.openFromStore(handle.id, handle.workDir, handle.store, opts);
+            // A fork copies the subagent ledger; its background "running" rows have no live task → lost.
+            try {
+                await session.reconcileSubagents();
+            }
+            catch (error) {
+                await session.close();
+                throw error;
+            }
+            return session;
+        });
     }
     /** The currently-open session with this id, or undefined (does not reopen — use resumeSession). */
     getSession(id) {
@@ -1113,8 +1266,15 @@ export class Harness {
     async getSessionSummary(id) {
         return (await this.repository()).get(id);
     }
-    /** Close one open session by id (no-op if it isn't open). */
+    /** Close one open session by id (no-op if it isn't open). An open in flight for this id is
+     *  waited for and then closed, so a close/delete never races a half-built session. */
     async closeSession(id) {
+        const inflight = this.opening.get(id);
+        if (inflight !== undefined) {
+            const session = await inflight.catch(() => undefined);
+            await session?.close();
+            return;
+        }
         await this.activeSessions.get(id)?.close();
     }
     /**
@@ -1138,12 +1298,27 @@ export class Harness {
      * drained, then its dispose hook — default the instance's close()), then the host's own
      * registrations, then the defaults.
      */
-    async close() {
+    close() {
+        if (this.closing !== undefined)
+            return this.closing;
+        this.closing = this.runClose();
+        return this.closing;
+    }
+    async runClose() {
+        // Opens in flight finish (or fail) first: closing the scope tree under a half-built session
+        // would tear its scope out from under `Session.open`. New opens are refused from here on
+        // (`assertAcceptingSessions`), so the set only shrinks.
+        await Promise.allSettled([...this.opening.values()]);
         for (const session of [...this.activeSessions.values()])
             await session.close();
         await this.sharedReady.catch(() => undefined);
         this.createdServices.length = 0;
-        await this.scope.close();
+        await this.scope.close(this.scopeCloseOptions());
+    }
+    /** Every path that opens a session starts here: a closing harness opens nothing new. */
+    assertAcceptingSessions() {
+        if (this.closing !== undefined)
+            throw new Error("harness is closed");
     }
     /**
      * Replace by-value extensions with new versions, as one coordinated act — the by-value twin of
@@ -1399,86 +1574,126 @@ export class Harness {
         // The workspace scope (one per key, shared) and under it the session scope: what the harness
         // decides for this session goes in here; Session.open provides the defaults for the rest,
         // and from then on the session owns the scope.
+        // From here the open is a transaction: the session is registered as active only once every
+        // step has succeeded, and any failure tears down exactly what was built — projection, the
+        // session scope (via the core when it got that far), the workspace hold — before rethrowing.
+        // Half-open leftovers are what kept a workspace alive after its last real session closed.
         const workspace = await this.acquireWorkspace(workspaceKey, workDir);
         let scope;
+        let projection;
+        let core;
         try {
             scope = workspace.child("session");
+            scope.register(T.SessionId, id);
+            scope.register(T.StoreBackend, store, { owned: false }); // the repository owns the store's lifetime
+            const events = new ListenerSink();
+            scope.register(T.Events, events);
+            const responder = new MutableResponder();
+            scope.register(T.Responder, responder);
+            // Machine: this call's override → the harness-level factory (resolved by Session.open) →
+            // a LocalMachine at the session's own workDir. The session only OPERATES a caller-supplied
+            // machine; the default one is its own.
+            if (opts.machine !== undefined) {
+                if (typeof opts.machine === "function")
+                    scope.register(T.SessionMachineFactory, opts.machine);
+                else
+                    scope.register(T.Machine, opts.machine, { owned: false });
+            }
+            else if (!workspace.has(T.WorkspaceMachineFactory) && !this.scope.has(T.MachineFactory)) {
+                scope.provide(T.Machine, () => new LocalMachine(workDir));
+            }
+            scope.register(T.PermissionOptions, opts.permission ?? this.options.permission ?? { mode: "yolo" });
+            if (opts.eventPublication !== undefined)
+                scope.register(T.SessionEventPublication, opts.eventPublication);
+            // ONE open-time log read, shared: the projection seeds from it, and Session.open
+            // receives it as `preloadedLog` so its capability restore + context pre-build fold the
+            // same records — same IO, and the same `Message` objects (no second parsed copy).
+            // Attach still happens BEFORE Session.open: no events flow yet, so the seed cannot
+            // race the subscription, and anything capabilities emit during open is already folded.
+            let preloadedLog = await readLog(store);
+            // A fresh session has an empty log; anything else is a reopen. Telemetry is the only reader.
+            const resumed = preloadedLog.length > 0;
+            projection = await SessionProjection.attach({ id, store, events }, preloadedLog);
+            const interrupted = await store.getState(INTERRUPTION_STATE_KEY) !== null;
+            if (!interrupted) {
+                const recoveryRecords = await closeOrphanedProjectionFrames(id, store, projection);
+                if (recoveryRecords.length > 0)
+                    preloadedLog = [...preloadedLog, ...recoveryRecords];
+            }
+            const capabilities = await this.resolveCapabilities(scope, {
+                sessionId: id,
+                workDir,
+                ownMachine: opts.machine !== undefined,
+                ...(opts.mcpServers !== undefined ? { mcpServers: opts.mcpServers } : {}),
+            }, params);
+            core = await Session.open(scope, { capabilities, preloadedLog, resumed });
+            const agent = opts.agent ??
+                this.options.agent ??
+                (await this.buildDefaultAgent(opts.appendSystemPrompt, opts.maxStepsPerTurn));
+            const session = new HarnessSession({
+                core,
+                // The two caps land in different places: maxStepsPerTurn is an Agent property
+                // (the Runner reads the agent's value first), maxTurns is a per-run option.
+                agent,
+                runner: this.runner,
+                events,
+                responder,
+                projection,
+                workDir,
+                context: this.contextFor(opts),
+                ...(opts.maxTurns ?? this.options.maxTurns) !== undefined
+                    ? { maxTurns: opts.maxTurns ?? this.options.maxTurns }
+                    : {},
+                interrupted,
+                onClosed: async (sid) => {
+                    // Only THIS instance's registration goes — a later open under the same id (a resume
+                    // that waited for this close) must keep its own. The workspace hold is this
+                    // instance's regardless and is always returned.
+                    if (this.activeSessions.get(sid) === session)
+                        this.activeSessions.delete(sid);
+                    await this.releaseWorkspace(workspaceKey);
+                },
+            });
+            this.activeSessions.set(id, session);
+            // Born gated: a session appearing while a reshape barrier holds (createSession,
+            // resumeSession and openSession all land here) must not start runs mid-swap. Its
+            // quiescent is trivially settled — it has no run — so it never delays the rendezvous.
+            if (this.activeBarrier !== undefined)
+                this.activeBarrier.holds.set(id, session.holdAtBoundary());
+            return session;
         }
         catch (error) {
-            await this.releaseWorkspace(workspaceKey);
+            await this.rollbackOpen(id, workspaceKey, { projection, core, scope }, error);
             throw error;
         }
-        scope.register(T.SessionId, id);
-        scope.register(T.StoreBackend, store, { owned: false }); // the repository owns the store's lifetime
-        const events = new ListenerSink();
-        scope.register(T.Events, events);
-        const responder = new MutableResponder();
-        scope.register(T.Responder, responder);
-        // Machine: this call's override → the harness-level factory (resolved by Session.open) →
-        // a LocalMachine at the session's own workDir. The session only OPERATES a caller-supplied
-        // machine; the default one is its own.
-        if (opts.machine !== undefined) {
-            if (typeof opts.machine === "function")
-                scope.register(T.SessionMachineFactory, opts.machine);
-            else
-                scope.register(T.Machine, opts.machine, { owned: false });
-        }
-        else if (!workspace.has(T.WorkspaceMachineFactory) && !this.scope.has(T.MachineFactory)) {
-            scope.provide(T.Machine, () => new LocalMachine(workDir));
-        }
-        scope.register(T.PermissionOptions, opts.permission ?? this.options.permission ?? { mode: "yolo" });
-        if (opts.eventPublication !== undefined)
-            scope.register(T.SessionEventPublication, opts.eventPublication);
-        // ONE open-time log read, shared: the projection seeds from it, and Session.open
-        // receives it as `preloadedLog` so its capability restore + context pre-build fold the
-        // same records — same IO, and the same `Message` objects (no second parsed copy).
-        // Attach still happens BEFORE Session.open: no events flow yet, so the seed cannot
-        // race the subscription, and anything capabilities emit during open is already folded.
-        let preloadedLog = await readLog(store);
-        const projection = await SessionProjection.attach({ id, store, events }, preloadedLog);
-        const interrupted = await store.getState(INTERRUPTION_STATE_KEY) !== null;
-        if (!interrupted) {
-            const recoveryRecords = await closeOrphanedProjectionFrames(id, store, projection);
-            if (recoveryRecords.length > 0)
-                preloadedLog = [...preloadedLog, ...recoveryRecords];
-        }
-        const capabilities = await this.resolveCapabilities(scope, {
-            sessionId: id,
-            workDir,
-            ownMachine: opts.machine !== undefined,
-            ...(opts.mcpServers !== undefined ? { mcpServers: opts.mcpServers } : {}),
-        }, params);
-        const core = await Session.open(scope, { capabilities, preloadedLog });
-        const agent = opts.agent ??
-            this.options.agent ??
-            (await this.buildDefaultAgent(opts.appendSystemPrompt, opts.maxStepsPerTurn));
-        const session = new HarnessSession({
-            core,
-            // The two caps land in different places: maxStepsPerTurn is an Agent property
-            // (the Runner reads the agent's value first), maxTurns is a per-run option.
-            agent,
-            runner: this.runner,
-            events,
-            responder,
-            projection,
-            workDir,
-            context: this.contextFor(opts),
-            ...(opts.maxTurns ?? this.options.maxTurns) !== undefined
-                ? { maxTurns: opts.maxTurns ?? this.options.maxTurns }
-                : {},
-            interrupted,
-            onClosed: async (sid) => {
-                this.activeSessions.delete(sid);
-                await this.releaseWorkspace(workspaceKey);
-            },
-        });
-        this.activeSessions.set(id, session);
-        // Born gated: a session appearing while a reshape barrier holds (createSession,
-        // resumeSession and openSession all land here) must not start runs mid-swap. Its
-        // quiescent is trivially settled — it has no run — so it never delays the rendezvous.
-        if (this.activeBarrier !== undefined)
-            this.activeBarrier.holds.set(id, session.holdAtBoundary());
-        return session;
+    }
+    /**
+     * Undo a failed `openFromStore`, newest artifact first. Every step runs even if an earlier one
+     * throws (a cleanup failure is logged, never allowed to mask the open's own error), and the
+     * workspace hold this open took is always returned.
+     */
+    async rollbackOpen(id, workspaceKey, built, cause) {
+        const logger = this.scope.get(T.Logger);
+        const attempt = async (step, run) => {
+            try {
+                await run();
+            }
+            catch (error) {
+                logger?.log("warn", `session open rollback: ${step} failed`, {
+                    sessionId: id,
+                    step,
+                    error: error instanceof Error ? error.message : String(error),
+                    cause: cause instanceof Error ? cause.message : String(cause),
+                });
+            }
+        };
+        await attempt("detach projection", () => built.projection?.detach());
+        // The core owns the scope once it opened; before that the scope is ours to close.
+        if (built.core !== undefined)
+            await attempt("close core", () => built.core.close());
+        else if (built.scope !== undefined)
+            await attempt("close scope", () => built.scope.close(this.scopeCloseOptions(id)));
+        await attempt("release workspace", () => this.releaseWorkspace(workspaceKey));
     }
     /**
      * The workspace scope for `key`, composed on first use — the host's `workspace` hook, then
@@ -1516,7 +1731,21 @@ export class Harness {
         if (entry.refs > 0)
             return;
         this.workspaces.delete(key);
-        await entry.scope.close();
+        await entry.scope.close(this.scopeCloseOptions(undefined, key));
+    }
+    /** Close options for a scope the harness tears down itself: per-service deadline, failures logged. */
+    scopeCloseOptions(sessionId, workspaceKey) {
+        return {
+            disposeTimeoutMs: SCOPE_DISPOSE_TIMEOUT_MS,
+            onDisposeError: (name, error) => {
+                this.scope.get(T.Logger)?.log("warn", `service "${name}" dispose failed/timed out`, {
+                    service: name,
+                    ...(sessionId !== undefined ? { sessionId } : {}),
+                    ...(workspaceKey !== undefined ? { workspaceKey } : {}),
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            },
+        };
     }
     /**
      * A handle to a workspace-tier extension service in ONE workspace — how a host reaches a

package/dist/index.d.ts

@@ -22,4 +22,5 @@ export * as mcp from "operon-agents-core/mcp";
 export * as protocol from "operon-agents-core/protocol";
 export * as tools from "operon-agents-core/tools";
 export * as tracing from "operon-agents-core/tracing";
+export * as telemetry from "./telemetry.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -27,4 +27,5 @@ export * as mcp from "operon-agents-core/mcp";
 export * as protocol from "operon-agents-core/protocol";
 export * as tools from "operon-agents-core/tools";
 export * as tracing from "operon-agents-core/tracing";
+export * as telemetry from "./telemetry.js";
 //# sourceMappingURL=index.js.map

package/dist/internal.d.ts

@@ -6,4 +6,5 @@
  * No stability guarantees — prefer the main `operon-agents` surface.
  */
 export * from "operon-agents-core/internal";
+export { setHarnessCloseTimeoutsForTest } from "./harness.ts";
 //# sourceMappingURL=internal.d.ts.map

package/dist/internal.js

@@ -6,4 +6,5 @@
  * No stability guarantees — prefer the main `operon-agents` surface.
  */
 export * from "operon-agents-core/internal";
+export { setHarnessCloseTimeoutsForTest } from "./harness.js";
 //# sourceMappingURL=internal.js.map

package/dist/local.js

@@ -56,11 +56,13 @@ export async function localHarnessOptions(options) {
             await workspace?.(scope, ctx);
             // Skills follow the workspace's EXECUTION machine, not the host's disk: the catalog the
             // model sees must be the one whose scripts its Bash can reach. A remote workspace
-            // registers its machine above and the scan runs through it. A machine FACTORY (one
+            // registers its machine above and the scan runs through it; absent that, the harness's
+            // default (`T.MachineFactory`, read through the parent chain) is what sessions here will
+            // execute on — the same precedence `Session.open` resolves. A machine FACTORY (one
             // machine per session) has no single filesystem to scan — no shared registry then; each
             // session scans through its own `T.Machine` (`defaultCapabilities` without `T.SkillRegistry`).
             if (!scope.hasLocal(T.SkillRegistry)) {
-                const workspaceMachine = scope.get(T.WorkspaceMachineFactory) ?? new LocalMachine(ctx.workDir);
+                const workspaceMachine = scope.get(T.WorkspaceMachineFactory) ?? scope.get(T.MachineFactory) ?? new LocalMachine(ctx.workDir);
                 if (typeof workspaceMachine !== "function") {
                     const registry = new SkillRegistry();
                     await loadSkillRoots(workspaceMachine, registry, {

package/dist/telemetry-posthog.d.ts

@@ -0,0 +1,88 @@
+/**
+ * PostHogAppender — the framework's default telemetry sink (docs/telemetry.md §7).
+ *
+ * Two ways in, one path after:
+ *
+ *   (a) `{ apiKey, host, getDistinctId }` — the appender builds a `posthog-node` client. For
+ *       products without their own analytics plumbing. `getDistinctId` is REQUIRED here and is a
+ *       callback, not a value: sign-in / sign-out change it mid-process. Returning `undefined`
+ *       DROPS the event — the framework never substitutes an id of its own.
+ *
+ *   (b) `{ client }` — the product injects anything with a `capture()`; identity, consent and
+ *       buffering stay wherever the product already keeps them (operon desktop wraps its
+ *       consent-gated main-process sink this way, so there is exactly one PostHog channel).
+ *
+ * Per event: redact → drop non-primitives (types forbid them; a cast can still sneak one in) →
+ * enrich with app/framework identity → capture. Batching, retry and backoff are the client's.
+ */
+import { type TelemetryAppender, type TelemetryEvent, type TelemetryPrimitive } from "operon-agents-core/telemetry";
+/** The minimum a sink has to look like. `posthog-node`'s `PostHog` satisfies it as-is. */
+export interface PostHogClientLike {
+    capture(message: {
+        readonly distinctId?: string;
+        readonly event: string;
+        readonly properties: Record<string, TelemetryPrimitive>;
+        readonly timestamp?: Date;
+    }): void;
+    flush?(): Promise<void> | void;
+    shutdown?(timeoutMs?: number): Promise<void> | void;
+}
+export interface PostHogAppIdentity {
+    /** Product name stamped on every event as `app_name` (e.g. `operon`). */
+    readonly name: string;
+    /** Product version stamped as `app_version`. */
+    readonly version?: string;
+}
+interface PostHogAppenderBaseOptions {
+    readonly app: PostHogAppIdentity;
+    /** Who the event is about. Required in mode (a); optional in mode (b) where the client decides. */
+    readonly getDistinctId?: () => string | undefined;
+    /** Extra properties stamped on every event (a channel tag, say). Same red lines apply. */
+    readonly commonProperties?: Readonly<Record<string, TelemetryPrimitive>>;
+    /** Where dropped-event and client errors go. Default: `console.warn`, once per reason. */
+    readonly warn?: (message: string) => void;
+}
+/** Mode (a): the appender owns a `posthog-node` client. */
+export interface PostHogAppenderClientOptions extends PostHogAppenderBaseOptions {
+    readonly apiKey: string;
+    /** PostHog ingestion host, e.g. `https://us.i.posthog.com`. */
+    readonly host: string;
+    readonly getDistinctId: () => string | undefined;
+    /** Client batching knobs; passed through. */
+    readonly flushAt?: number;
+    readonly flushIntervalMs?: number;
+    /** Test seam: build the client from resolved options instead of `new PostHog(...)`. */
+    readonly createClient?: (apiKey: string, options: {
+        host: string;
+        flushAt?: number;
+        flushInterval?: number;
+    }) => PostHogClientLike;
+}
+/** Mode (b): the product injects the sink. */
+export interface PostHogAppenderInjectedOptions extends PostHogAppenderBaseOptions {
+    readonly client: PostHogClientLike;
+}
+export type PostHogAppenderOptions = PostHogAppenderClientOptions | PostHogAppenderInjectedOptions;
+export declare class PostHogAppender implements TelemetryAppender {
+    private client;
+    private readonly ready;
+    private readonly getDistinctId;
+    private readonly requireDistinctId;
+    private readonly common;
+    private readonly warn;
+    private readonly warned;
+    /** Events that arrived before the lazy client resolved (mode (a) only). Bounded. */
+    private pending;
+    private closed;
+    private droppedCount;
+    constructor(options: PostHogAppenderOptions);
+    /** Events dropped for lack of a distinct id, a closed appender, or a failed client. */
+    get dropped(): number;
+    track(event: TelemetryEvent): void;
+    private send;
+    private warnOnce;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=telemetry-posthog.d.ts.map

package/dist/telemetry-posthog.js

@@ -0,0 +1,142 @@
+/**
+ * PostHogAppender — the framework's default telemetry sink (docs/telemetry.md §7).
+ *
+ * Two ways in, one path after:
+ *
+ *   (a) `{ apiKey, host, getDistinctId }` — the appender builds a `posthog-node` client. For
+ *       products without their own analytics plumbing. `getDistinctId` is REQUIRED here and is a
+ *       callback, not a value: sign-in / sign-out change it mid-process. Returning `undefined`
+ *       DROPS the event — the framework never substitutes an id of its own.
+ *
+ *   (b) `{ client }` — the product injects anything with a `capture()`; identity, consent and
+ *       buffering stay wherever the product already keeps them (operon desktop wraps its
+ *       consent-gated main-process sink this way, so there is exactly one PostHog channel).
+ *
+ * Per event: redact → drop non-primitives (types forbid them; a cast can still sneak one in) →
+ * enrich with app/framework identity → capture. Batching, retry and backoff are the client's.
+ */
+import { createRequire } from "node:module";
+import { redactTelemetryProperties } from "operon-agents-core/telemetry";
+const SHUTDOWN_TIMEOUT_MS = 5_000;
+function frameworkVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require("../package.json");
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function isInjected(options) {
+    return "client" in options;
+}
+async function createNodeClient(apiKey, options) {
+    // Loaded lazily so a product in mode (b) never pays for the module, and so the import lives
+    // in one place if the client ever changes.
+    const mod = await import("posthog-node");
+    return new mod.PostHog(apiKey, { host: options.host, flushAt: options.flushAt, flushInterval: options.flushInterval, disableGeoip: true });
+}
+export class PostHogAppender {
+    client;
+    ready;
+    getDistinctId;
+    requireDistinctId;
+    common;
+    warn;
+    warned = new Set();
+    /** Events that arrived before the lazy client resolved (mode (a) only). Bounded. */
+    pending = [];
+    closed = false;
+    droppedCount = 0;
+    constructor(options) {
+        this.getDistinctId = options.getDistinctId;
+        this.requireDistinctId = !isInjected(options);
+        this.common = Object.freeze({
+            app_name: options.app.name,
+            app_version: options.app.version ?? null,
+            framework_version: frameworkVersion(),
+            platform: process.platform,
+            ...(options.commonProperties ?? {}),
+        });
+        this.warn = options.warn ?? ((message) => console.warn(`[telemetry/posthog] ${message}`));
+        if (isInjected(options)) {
+            this.client = options.client;
+            this.ready = Promise.resolve();
+        }
+        else {
+            const create = options.createClient;
+            const resolved = { host: options.host, flushAt: options.flushAt, flushInterval: options.flushIntervalMs };
+            this.ready = (create === undefined ? createNodeClient(options.apiKey, resolved) : Promise.resolve(create(options.apiKey, resolved)))
+                .then((client) => {
+                this.client = client;
+                const queued = this.pending;
+                this.pending = [];
+                for (const event of queued)
+                    this.send(event);
+            })
+                .catch((error) => {
+                this.warnOnce("client-init", `client failed to initialise; events will be dropped: ${String(error)}`);
+                this.pending = [];
+            });
+        }
+    }
+    /** Events dropped for lack of a distinct id, a closed appender, or a failed client. */
+    get dropped() {
+        return this.droppedCount;
+    }
+    track(event) {
+        if (this.closed) {
+            this.droppedCount += 1;
+            return;
+        }
+        if (this.client === undefined) {
+            if (this.pending.length >= 200) {
+                this.droppedCount += 1;
+                return;
+            }
+            this.pending.push(event);
+            return;
+        }
+        this.send(event);
+    }
+    send(event) {
+        const client = this.client;
+        if (client === undefined)
+            return;
+        const distinctId = this.getDistinctId?.();
+        if (this.requireDistinctId && distinctId === undefined) {
+            this.droppedCount += 1;
+            this.warnOnce("no-distinct-id", "getDistinctId() returned undefined; event dropped (the framework never mints an id)");
+            return;
+        }
+        const properties = { ...this.common, ...redactTelemetryProperties(event.properties) };
+        try {
+            client.capture({
+                ...(distinctId === undefined ? {} : { distinctId }),
+                event: event.name,
+                properties,
+                timestamp: new Date(event.timestamp),
+            });
+        }
+        catch (error) {
+            this.warnOnce("capture", `client.capture threw: ${String(error)}`);
+        }
+    }
+    warnOnce(key, message) {
+        if (this.warned.has(key))
+            return;
+        this.warned.add(key);
+        this.warn(message);
+    }
+    async flush() {
+        await this.ready;
+        await Promise.resolve(this.client?.flush?.());
+    }
+    async shutdown() {
+        await this.ready;
+        this.closed = true;
+        await Promise.resolve(this.client?.shutdown?.(SHUTDOWN_TIMEOUT_MS));
+    }
+}
+//# sourceMappingURL=telemetry-posthog.js.map

package/dist/telemetry.d.ts

@@ -0,0 +1,4 @@
+export * from "operon-agents-core/telemetry";
+export { PostHogAppender } from "./telemetry-posthog.ts";
+export type { PostHogAppenderOptions, PostHogAppenderClientOptions, PostHogAppenderInjectedOptions, PostHogClientLike, PostHogAppIdentity } from "./telemetry-posthog.ts";
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.js

@@ -0,0 +1,3 @@
+export * from "operon-agents-core/telemetry";
+export { PostHogAppender } from "./telemetry-posthog.js";
+//# sourceMappingURL=telemetry.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "operon-agents",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.6",
   "description": "Public SDK entrypoint for building agents.",
   "type": "module",
   "engines": {
@@ -58,6 +58,10 @@
       "types": "./dist/tracing.d.ts",
       "import": "./dist/tracing.js"
     },
+    "./telemetry": {
+      "types": "./dist/telemetry.d.ts",
+      "import": "./dist/telemetry.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -66,8 +70,9 @@
     "README.md"
   ],
   "dependencies": {
+    "posthog-node": "^5.51.6",
     "zod": "^4.4.3",
-    "operon-agents-core": "0.1.0-alpha.4"
+    "operon-agents-core": "0.1.0-alpha.6"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.84.1"