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

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;
@@ -160,6 +160,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 —

package/dist/harness.js

@@ -888,6 +888,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
@@ -1435,6 +1437,8 @@ export class Harness {
         // 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;
         const projection = await SessionProjection.attach({ id, store, events }, preloadedLog);
         const interrupted = await store.getState(INTERRUPTION_STATE_KEY) !== null;
         if (!interrupted) {
@@ -1448,7 +1452,7 @@ export class Harness {
             ownMachine: opts.machine !== undefined,
             ...(opts.mcpServers !== undefined ? { mcpServers: opts.mcpServers } : {}),
         }, params);
-        const core = await Session.open(scope, { capabilities, preloadedLog });
+        const core = await Session.open(scope, { capabilities, preloadedLog, resumed });
         const agent = opts.agent ??
             this.options.agent ??
             (await this.buildDefaultAgent(opts.appendSystemPrompt, opts.maxStepsPerTurn));

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/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.5",
   "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.5"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.84.1"