@ap3x/observe 0.1.0

package/dist/pipeline.d.ts

@@ -0,0 +1,21 @@
+import type { TraceContext, TraceEvent, TraceEventInput } from "./envelope";
+export interface TraceSink {
+    onEvent(event: TraceEvent): void;
+}
+export interface TracePipelineOptions {
+    sinks?: TraceSink[];
+    /** Test seam for timestamps; defaults to Date.now. */
+    now?: () => number;
+}
+/** Stamps ids/seq/ts onto emitter inputs and fans out to sinks. Sink errors never propagate. */
+export declare class TracePipeline {
+    #private;
+    constructor(options?: TracePipelineOptions);
+    get fallbackRoot(): TraceContext;
+    get dropped(): number;
+    /** Forget a finished trace's seq counter (footer written, run over). */
+    releaseTrace(traceId: string): void;
+    addSink(sink: TraceSink): () => void;
+    emit(input: TraceEventInput, ctx?: TraceContext): TraceEvent;
+}
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAK5E,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,gGAAgG;AAChG,qBAAa,aAAa;;gBAOZ,OAAO,CAAC,EAAE,oBAAoB;IAK1C,IAAI,YAAY,IAAI,YAAY,CAG/B;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,wEAAwE;IACxE,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAInC,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,IAAI;IAKpC,IAAI,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,YAAY,GAAG,UAAU;CA+B7D"}

package/dist/queued-sink.d.ts

@@ -0,0 +1,20 @@
+import type { TraceEvent } from "./envelope";
+import type { TraceSink } from "./pipeline";
+export interface QueuedSinkOptions {
+    /** Queue bound; overflow drops events and counts them. Default 1024. */
+    maxQueue?: number;
+}
+/**
+ * Decouples a sink from the loop (spec: observers can never block or slow a
+ * turn). Events enqueue synchronously and drain on the next macrotask; the
+ * queue is bounded — overflow drops and increments `dropped`.
+ */
+export declare class QueuedSink implements TraceSink {
+    #private;
+    constructor(inner: TraceSink, options?: QueuedSinkOptions);
+    get dropped(): number;
+    onEvent(event: TraceEvent): void;
+    /** Drain everything queued right now (shutdown, tests). */
+    flush(): void;
+}
+//# sourceMappingURL=queued-sink.d.ts.map

package/dist/queued-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queued-sink.d.ts","sourceRoot":"","sources":["../src/queued-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,UAAW,YAAW,SAAS;;gBAO9B,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,iBAAiB;IAKzD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAwBhC,2DAA2D;IAC3D,KAAK,IAAI,IAAI;CAGd"}

package/dist/taps/agent.d.ts

@@ -0,0 +1,17 @@
+import type { AgentEvent } from "@ap3x/agent-core";
+import type { TraceContext } from "../envelope";
+import type { TracePipeline } from "../pipeline";
+export interface AgentEventSource {
+    subscribe(listener: (event: AgentEvent) => void | Promise<void>): () => void;
+}
+export interface ObserveAgentOptions {
+    agent?: {
+        name?: string;
+        model?: string;
+    };
+    ctx?: TraceContext;
+    onDrop?: () => void;
+}
+/** Attaches a trace tap to anything with Agent-style subscribe(). Returns unsubscribe. */
+export declare function observeAgent(source: AgentEventSource, pipeline: TracePipeline, options?: ObserveAgentOptions): () => void;
+//# sourceMappingURL=agent.d.ts.map

package/dist/taps/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/taps/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAmB,MAAM,aAAa,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC;CAC9E;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AA8DD,0FAA0F;AAC1F,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,MAAM,IAAI,CAiBZ"}

package/dist/taps/swarm.d.ts

@@ -0,0 +1,12 @@
+import type { TracePipeline } from "../pipeline";
+/** Bridges swarm delegation events into a trace pipeline. Returns unsubscribe. */
+export declare function observeSwarms(pipeline: TracePipeline, options?: {
+    onDrop?: () => void;
+}): () => void;
+/**
+ * Automatic parent/child span nesting across delegations (P2 line item):
+ * every enterDelegation runs its child inside a child TraceContext, so child
+ * agent/tool events carry parentSpanId without any explicit ctx threading.
+ */
+export declare function enableDelegationSpans(): () => void;
+//# sourceMappingURL=swarm.d.ts.map

package/dist/taps/swarm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swarm.d.ts","sourceRoot":"","sources":["../../src/taps/swarm.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,kFAAkF;AAClF,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GAChC,MAAM,IAAI,CAmBZ;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,IAAI,CAGlD"}

package/dist/trace-file.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Read-side of the JSONL trace format written by TraceWriter. Pure functions —
+ * no filesystem access — so the CLI, tests, and future analyzers share one
+ * parser. Tolerant by design: a crashed run has no footer, and a torn write
+ * may leave malformed lines; both are counted, never thrown.
+ */
+import type { TraceEvent } from "./envelope";
+export interface TraceHeader {
+    type: "trace";
+    version: number;
+    traceId: string;
+    startedAt: number;
+}
+export interface TraceFooter {
+    type: "trace_end";
+    traceId: string;
+    dropped: number;
+    outcome?: string;
+    endedAt: number;
+}
+export interface ParsedTrace {
+    header?: TraceHeader;
+    events: TraceEvent[];
+    footer?: TraceFooter;
+    malformedLines: number;
+}
+export declare function parseTraceFile(content: string): ParsedTrace;
+export interface ToolStats {
+    calls: number;
+    failures: number;
+}
+export interface TraceSummary {
+    traceId: string;
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    outcome?: string;
+    dropped: number;
+    events: number;
+    malformedLines: number;
+    turns: number;
+    usage: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        costTotal?: number;
+    };
+    toolCalls: number;
+    toolFailures: number;
+    tools: Record<string, ToolStats>;
+    hookRuns: number;
+    hookErrors: number;
+    agents: string[];
+}
+/** Cost, turns, tool-failure rates, duration — the first optimization-ready dataset. */
+export declare function summarizeTrace(parsed: ParsedTrace): TraceSummary;
+//# sourceMappingURL=trace-file.d.ts.map

package/dist/trace-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-file.d.ts","sourceRoot":"","sources":["../src/trace-file.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAwB3D;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QACL,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CA0DhE"}

package/dist/trace-writer.d.ts

@@ -0,0 +1,17 @@
+import type { TraceEvent } from "./envelope";
+import type { TraceSink } from "./pipeline";
+export interface TraceWriterOptions {
+    dir?: string;
+    now?: () => number;
+}
+/** One JSONL file per trace under ~/.ap3x/traces/. Never throws into the pipeline. */
+export declare class TraceWriter implements TraceSink {
+    #private;
+    constructor(options?: TraceWriterOptions);
+    /** Aggregate dropped-event count across all traces. */
+    get dropped(): number;
+    onEvent(event: TraceEvent): void;
+    close(traceId: string, outcome?: "ok" | "error" | "aborted"): void;
+    closeAll(outcome?: "ok" | "error" | "aborted"): void;
+}
+//# sourceMappingURL=trace-writer.d.ts.map

package/dist/trace-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-writer.d.ts","sourceRoot":"","sources":["../src/trace-writer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AASD,sFAAsF;AAEtF,qBAAa,WAAY,YAAW,SAAS;;gBAS/B,OAAO,CAAC,EAAE,kBAAkB;IAKxC,uDAAuD;IACvD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAkBhC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI;IAiBlE,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI;CAgDrD"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@ap3x/observe",
+  "version": "0.1.0",
+  "description": "Observability seams and a hook engine for agents and swarms",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AP3X-Dev/AP3X.git",
+    "directory": "packages/observe"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean --tsconfig tsconfig.build.json && tsc -p tsconfig.build.json",
+    "prepublishOnly": "node ../../scripts/publish-gate.mjs",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ap3x/agent-core": "0.1.0",
+    "@ap3x/ai": "0.1.0",
+    "@ap3x/swarms": "0.1.0"
+  }
+}