@agent-arc-status/emitter 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Fisher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @agent-arc-status/emitter
+
+A batteries-included **producer** for the [Agent Arc Status
+Protocol](https://github.com/joethefisher/agent-arc-status). It wraps the reference
+`CadenceController` and makes correct emission the default:
+
+- **`started` first, terminal last** — `run(fn)` emits `started` on entry and `done` on success or
+  terminal `blocked` on throw, so every stream it produces is `validateSequence`-clean.
+- **Automatic silence backstop** — a timer independent of the work loop (§5.2) fires a `heartbeat`
+  when the silence window would otherwise elapse.
+- **Best-effort transport** — a failed send goes to `onError`; status reporting never crashes the work.
+- **Zero runtime dependencies** — Node stdlib only.
+
+```ts
+import { ArcEmitter, httpTransport } from "@agent-arc-status/emitter";
+
+const arc = new ArcEmitter({
+  title: "nightly: refresh customer health scores",
+  arcKind: "batch",
+  transport: httpTransport({ url: process.env.ARC_STATUS_URL!, secret: process.env.ARC_STATUS_SECRET }),
+});
+
+await arc.run(async (arc) => {
+  await arc.milestone("ingested 12k account records", { step: 1, total: 4 });
+  // ... work ...
+  await arc.milestone("scored and persisted", { step: 4, total: 4 });
+});
+// -> started, milestone, milestone, done  (all validated, heartbeats auto-filled)
+```
+
+## API
+
+- `new ArcEmitter(config)` — `{ title, transport, arcId?, arcKind?, cadence?, heartbeatActivity?,
+  tickIntervalMs?, onError? }`.
+- `start()`, `milestone(title, opts?)`, `heartbeat(title?, opts?)`, `blocked(title, opts?)`,
+  `done(title?, opts?)`, `isTerminal()`, `run(fn)`.
+- Transports: `httpTransport({ url, secret?, headers?, fetch? })` (webhook binding §8.1, optional
+  HMAC-SHA256) and `stdoutTransport({ write? })` (JSON Lines, §8.3). Implement `Transport` for others.
+
+Everything is injectable (`cadence.now`, `timer`, `transport`, `fetch`) for deterministic tests.

package/dist/ArcEmitter.d.ts

@@ -0,0 +1,60 @@
+import { type ArcStatusEvent, type CadenceConfig } from "@agent-arc-status/reference";
+import type { Transport } from "./transport.js";
+/** Minimal timer surface, injectable for deterministic tests. */
+export interface TimerLike {
+    setInterval(callback: () => void, ms: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+export interface ArcEmitterConfig {
+    /** The arc's objective; becomes the `started` title. */
+    title: string;
+    /** Where validated events are sent. */
+    transport: Transport;
+    /** Stable arc id. Default: a fresh UUID. */
+    arcId?: string;
+    arcKind?: string;
+    /** Emitter's protocol_version. Default: the reference `PROTOCOL_VERSION`. */
+    protocolVersion?: string;
+    /** Cadence floor/window and injectable clock (shared with the emitter). */
+    cadence?: CadenceConfig;
+    /** Supplies the auto-heartbeat title. Default: "still working". */
+    heartbeatActivity?: () => string;
+    /** How often the backstop timer polls the cadence controller. Default 30s. */
+    tickIntervalMs?: number;
+    /** Injectable timer. Default: global setInterval/clearInterval (unref'd). */
+    timer?: TimerLike;
+    /** Called on a transport failure or an invalid event; never rethrows. */
+    onError?: (error: unknown, event?: ArcStatusEvent) => void;
+}
+export interface EmitOptions {
+    body?: string;
+    step?: number;
+    total?: number;
+    eta_minutes?: number;
+}
+/**
+ * A batteries-included producer. It wraps the reference `CadenceController`
+ * (which stays pure and timer-free — the emitter owns the interval), guarantees
+ * a `started` leads the arc and a terminal ends it, and fires heartbeats from a
+ * timer independent of the work loop (§5.2). Transport failures are swallowed
+ * into `onError` so status reporting never crashes the workload.
+ */
+export declare class ArcEmitter {
+    #private;
+    readonly arcId: string;
+    constructor(config: ArcEmitterConfig);
+    /** Begin the arc and start the backstop timer. */
+    start(): Promise<void>;
+    milestone(title: string, opts?: EmitOptions): Promise<void>;
+    heartbeat(title?: string, opts?: EmitOptions): Promise<void>;
+    blocked(title: string, opts?: EmitOptions): Promise<void>;
+    done(title?: string, opts?: EmitOptions): Promise<void>;
+    isTerminal(): boolean;
+    /**
+     * Run `fn` as the arc: guarantees `started` first, `done` on success or
+     * terminal `blocked` on throw, and timer cleanup — so every produced stream is
+     * sequence-valid regardless of how `fn` exits.
+     */
+    run<T>(fn: (arc: ArcEmitter) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=ArcEmitter.d.ts.map

package/dist/ArcEmitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArcEmitter.d.ts","sourceRoot":"","sources":["../src/ArcEmitter.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,cAAc,EAEnB,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACxB,WAAW,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACvD,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,SAAS,EAAE,SAAS,CAAC;IACrB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,mEAAmE;IACnE,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC;IACjC,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;CAC5D;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD;;;;;;GAMG;AACH,qBAAa,UAAU;;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBASX,MAAM,EAAE,gBAAgB;IAQpC,kDAAkD;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBtB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D,SAAS,CAAC,KAAK,SAAkB,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7D,IAAI,CAAC,KAAK,SAAc,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMtE,UAAU,IAAI,OAAO;IAIrB;;;;OAIG;IACG,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CA+E9D"}

package/dist/ArcEmitter.js

@@ -0,0 +1,163 @@
+import { randomUUID } from "node:crypto";
+import { CadenceController, PROTOCOL_VERSION, validate, } from "@agent-arc-status/reference";
+const defaultTimer = {
+    setInterval: (callback, ms) => setInterval(callback, ms),
+    clearInterval: (handle) => clearInterval(handle),
+};
+/**
+ * A batteries-included producer. It wraps the reference `CadenceController`
+ * (which stays pure and timer-free — the emitter owns the interval), guarantees
+ * a `started` leads the arc and a terminal ends it, and fires heartbeats from a
+ * timer independent of the work loop (§5.2). Transport failures are swallowed
+ * into `onError` so status reporting never crashes the workload.
+ */
+export class ArcEmitter {
+    arcId;
+    #config;
+    #controller;
+    #now;
+    #timer;
+    #handle = null;
+    #startedSent = false;
+    #terminal = false;
+    constructor(config) {
+        this.#config = config;
+        this.arcId = config.arcId ?? randomUUID();
+        this.#controller = new CadenceController(config.cadence);
+        this.#now = config.cadence?.now ?? (() => Date.now());
+        this.#timer = config.timer ?? defaultTimer;
+    }
+    /** Begin the arc and start the backstop timer. */
+    async start() {
+        const started = this.#controller.begin({
+            arc_id: this.arcId,
+            title: this.#config.title,
+            arc_kind: this.#config.arcKind,
+            protocol_version: this.#config.protocolVersion ?? PROTOCOL_VERSION,
+        });
+        if (started) {
+            this.#startedSent = true;
+            await this.#send(started);
+        }
+        this.#handle = this.#timer.setInterval(() => {
+            void this.#onTick();
+        }, this.#config.tickIntervalMs ?? 30_000);
+        this.#handle.unref?.();
+    }
+    async milestone(title, opts = {}) {
+        await this.#ensureStarted();
+        await this.#emit("milestone", title, opts);
+    }
+    async heartbeat(title = "still working", opts = {}) {
+        await this.#ensureStarted();
+        await this.#emit("heartbeat", title, opts);
+    }
+    async blocked(title, opts = {}) {
+        await this.#ensureStarted();
+        await this.#emit("blocked", title, opts);
+    }
+    async done(title = "completed", opts = {}) {
+        await this.#ensureStarted();
+        await this.#emit("done", title, opts);
+        this.#stop();
+    }
+    isTerminal() {
+        return this.#terminal;
+    }
+    /**
+     * Run `fn` as the arc: guarantees `started` first, `done` on success or
+     * terminal `blocked` on throw, and timer cleanup — so every produced stream is
+     * sequence-valid regardless of how `fn` exits.
+     */
+    async run(fn) {
+        await this.start();
+        try {
+            const result = await fn(this);
+            if (!this.#terminal)
+                await this.done("completed");
+            return result;
+        }
+        catch (error) {
+            if (!this.#terminal) {
+                await this.blocked(`failed: ${errorMessage(error)}`, { body: errorBody(error) });
+            }
+            throw error;
+        }
+        finally {
+            this.#stop();
+            if (this.#config.transport.close)
+                await this.#config.transport.close();
+        }
+    }
+    async #onTick() {
+        if (this.#terminal)
+            return;
+        const event = this.#controller.tick(this.#config.heartbeatActivity?.());
+        if (event) {
+            if (event.phase === "started")
+                this.#startedSent = true;
+            await this.#send(event);
+        }
+    }
+    async #ensureStarted() {
+        if (this.#startedSent || this.#terminal)
+            return;
+        const event = this.#build("started", this.#config.title);
+        this.#startedSent = true;
+        await this.#send(event);
+        this.#controller.onEmit(event);
+    }
+    async #emit(phase, title, opts) {
+        const event = this.#build(phase, title, opts);
+        if (phase === "done")
+            this.#terminal = true;
+        await this.#send(event);
+        this.#controller.onEmit(event);
+    }
+    #build(phase, title, opts = {}) {
+        const event = {
+            arc_id: this.arcId,
+            phase,
+            title,
+            sent_at: new Date(this.#now()).toISOString(),
+            protocol_version: this.#config.protocolVersion ?? PROTOCOL_VERSION,
+        };
+        if (this.#config.arcKind !== undefined)
+            event.arc_kind = this.#config.arcKind;
+        if (opts.body !== undefined)
+            event.body = opts.body;
+        if (opts.step !== undefined)
+            event.step = opts.step;
+        if (opts.total !== undefined)
+            event.total = opts.total;
+        if (opts.eta_minutes !== undefined)
+            event.eta_minutes = opts.eta_minutes;
+        return event;
+    }
+    async #send(event) {
+        const result = validate(event);
+        if (!result.ok) {
+            this.#config.onError?.(new Error(`invalid arc.status event: ${JSON.stringify(result.issues)}`), event);
+            return;
+        }
+        try {
+            await this.#config.transport.send(event);
+        }
+        catch (error) {
+            this.#config.onError?.(error, event);
+        }
+    }
+    #stop() {
+        if (this.#handle !== null) {
+            this.#timer.clearInterval(this.#handle);
+            this.#handle = null;
+        }
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function errorBody(error) {
+    return error instanceof Error && error.stack ? error.stack : undefined;
+}
+//# sourceMappingURL=ArcEmitter.js.map

package/dist/ArcEmitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArcEmitter.js","sourceRoot":"","sources":["../src/ArcEmitter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @agent-arc-status/emitter — a batteries-included producer for the Agent Arc
+ * Status Protocol. Wraps the reference cadence controller, owns the backstop
+ * timer, and guarantees started-first / terminal-on-exit emission.
+ */
+export { ArcEmitter, type ArcEmitterConfig, type EmitOptions, type TimerLike, } from "./ArcEmitter.js";
+export { type Transport } from "./transport.js";
+export { httpTransport, type HttpTransportOptions } from "./transports/http.js";
+export { stdoutTransport, type StdoutTransportOptions } from "./transports/stdout.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,UAAU,EACV,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @agent-arc-status/emitter — a batteries-included producer for the Agent Arc
+ * Status Protocol. Wraps the reference cadence controller, owns the backstop
+ * timer, and guarantees started-first / terminal-on-exit emission.
+ */
+export { ArcEmitter, } from "./ArcEmitter.js";
+export { httpTransport } from "./transports/http.js";
+export { stdoutTransport } from "./transports/stdout.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,UAAU,GAIX,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,aAAa,EAA6B,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,eAAe,EAA+B,MAAM,wBAAwB,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,13 @@
+import type { ArcStatusEvent } from "@agent-arc-status/reference";
+/**
+ * A destination for validated arc.status events. Implementations own the wire
+ * (HTTP, stdout, a queue). `send` MAY reject on network failure; the emitter
+ * routes such rejections to its `onError` so status reporting never crashes the
+ * workload.
+ */
+export interface Transport {
+    send(event: ArcStatusEvent): Promise<void>;
+    /** Optional cleanup, awaited when an emitter's `run()` finishes. */
+    close?(): Promise<void>;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,oEAAoE;IACpE,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/dist/transport.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":""}

package/dist/transports/http.d.ts

@@ -0,0 +1,19 @@
+import type { Transport } from "../transport.js";
+export interface HttpTransportOptions {
+    /** Webhook endpoint that receives `arc.status` events. */
+    url: string;
+    /** If set, sign the body with HMAC-SHA256 (spec §8.1 / §9.1). */
+    secret?: string;
+    /** Extra headers merged onto every request. */
+    headers?: Record<string, string>;
+    /** Injectable fetch for testing. Default: global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * HTTP webhook transport implementing the reference binding (spec §8.1):
+ * `POST` with `X-Webhook-Event-Type: arc.status`, a per-delivery id, a
+ * timestamp, and an optional HMAC-SHA256 signature. Rejects on non-2xx so the
+ * emitter can route the failure to `onError`.
+ */
+export declare function httpTransport(options: HttpTransportOptions): Transport;
+//# sourceMappingURL=http.d.ts.map

package/dist/transports/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAsBtE"}

package/dist/transports/http.js

@@ -0,0 +1,31 @@
+import { createHmac, randomUUID } from "node:crypto";
+/**
+ * HTTP webhook transport implementing the reference binding (spec §8.1):
+ * `POST` with `X-Webhook-Event-Type: arc.status`, a per-delivery id, a
+ * timestamp, and an optional HMAC-SHA256 signature. Rejects on non-2xx so the
+ * emitter can route the failure to `onError`.
+ */
+export function httpTransport(options) {
+    const doFetch = options.fetch ?? fetch;
+    return {
+        async send(event) {
+            const body = JSON.stringify(event);
+            const headers = {
+                "Content-Type": "application/json",
+                "X-Webhook-Event-Type": "arc.status",
+                "X-Webhook-Delivery-Id": randomUUID(),
+                "X-Webhook-Timestamp": new Date().toISOString(),
+                ...options.headers,
+            };
+            if (options.secret !== undefined) {
+                const signature = createHmac("sha256", options.secret).update(body).digest("hex");
+                headers["X-Webhook-Signature"] = `sha256=${signature}`;
+            }
+            const response = await doFetch(options.url, { method: "POST", headers, body });
+            if (!response.ok) {
+                throw new Error(`arc.status transport: HTTP ${response.status}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/transports/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAerD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;IACvC,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,KAAqB;YAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,OAAO,GAA2B;gBACtC,cAAc,EAAE,kBAAkB;gBAClC,sBAAsB,EAAE,YAAY;gBACpC,uBAAuB,EAAE,UAAU,EAAE;gBACrC,qBAAqB,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBAC/C,GAAG,OAAO,CAAC,OAAO;aACnB,CAAC;YACF,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBACjC,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAClF,OAAO,CAAC,qBAAqB,CAAC,GAAG,UAAU,SAAS,EAAE,CAAC;YACzD,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/E,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YACnE,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/transports/stdout.d.ts

@@ -0,0 +1,8 @@
+import type { Transport } from "../transport.js";
+export interface StdoutTransportOptions {
+    /** Sink for each JSON line. Default: `process.stdout.write`. */
+    write?: (line: string) => void;
+}
+/** A JSON Lines transport (spec §8.3): one event per line to stdout. */
+export declare function stdoutTransport(options?: StdoutTransportOptions): Transport;
+//# sourceMappingURL=stdout.d.ts.map

package/dist/transports/stdout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdout.d.ts","sourceRoot":"","sources":["../../src/transports/stdout.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,SAAS,CAO/E"}

package/dist/transports/stdout.js

@@ -0,0 +1,10 @@
+/** A JSON Lines transport (spec §8.3): one event per line to stdout. */
+export function stdoutTransport(options = {}) {
+    const write = options.write ?? ((line) => void process.stdout.write(line));
+    return {
+        async send(event) {
+            write(JSON.stringify(event) + "\n");
+        },
+    };
+}
+//# sourceMappingURL=stdout.js.map

package/dist/transports/stdout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdout.js","sourceRoot":"","sources":["../../src/transports/stdout.ts"],"names":[],"mappings":"AAQA,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACnF,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,KAAqB;YAC9B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@agent-arc-status/emitter",
+  "version": "0.3.0",
+  "description": "Batteries-included producer for the Agent Arc Status Protocol: guarantees started-first, done/blocked-on-exit, and an automatic silence backstop. Zero runtime dependencies.",
+  "license": "MIT",
+  "author": "Joe Fisher",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joethefisher/agent-arc-status.git",
+    "directory": "packages/emitter"
+  },
+  "homepage": "https://github.com/joethefisher/agent-arc-status#readme",
+  "bugs": "https://github.com/joethefisher/agent-arc-status/issues",
+  "keywords": [
+    "agent",
+    "agents",
+    "ai",
+    "llm",
+    "observability",
+    "progress",
+    "arc-status"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@agent-arc-status/reference": "^0.3.0"
+  }
+}