@jinn-network/client 0.1.2 → 0.1.3-canary.2d6b2676

package/dist/erc8004/validation.d.ts

@@ -0,0 +1,145 @@
+/**
+ * ValidationRegistryClient — typed wrapper for the ERC-8004 ValidationRegistry
+ * contract.
+ *
+ * Phase 1b challenge mechanism. Per
+ * `docs/superpowers/specs/2026-04-27-erc-8004-entity-model-design.md` §4.4,
+ * Jinn challenges are anchored on the deployed `0x8004…` ValidationRegistry
+ * keyed by `(validatorAddress, agentId, requestHash)` where
+ * `requestHash = manifest.evidenceHash` — the same 32-byte hash JinnRouter
+ * already commits in `claimDelivery`. No new contracts are deployed; this
+ * client wraps the existing UUPS proxy.
+ *
+ * Wire shape (from /tmp/erc8004-ref/ValidationRegistryUpgradeable.sol):
+ *   - validationRequest(validator, agentId, requestURI, requestHash) — only
+ *     the agent owner / approved / operator can submit; reverts on duplicate
+ *     `requestHash`.
+ *   - validationResponse(requestHash, response, responseURI, responseHash, tag)
+ *     — only the validator named in the request may respond; `response` is a
+ *     0..100 score.
+ *   - getValidationStatus(requestHash) returns
+ *     (validator, agentId, response, responseHash, tag, lastUpdate). The
+ *     contract reverts on unknown `requestHash`.
+ *   - getAgentValidations(agentId) → bytes32[]
+ *   - getValidatorRequests(validator) → bytes32[]
+ *
+ * This module is intentionally **not wired into the daemon, evaluator, or CLI**.
+ * The UX of the challenge mechanism (who calls `requestValidation`, when, with
+ * what UI, with what validator-selection model) is a separate Phase 1b spec.
+ * This file ships the typed client; downstream beads consume it.
+ */
+import { type Address, type Hex, type PublicClient, type WalletClient } from 'viem';
+import { VALIDATION_REGISTRY_ABI } from './abis.js';
+import { VALIDATION_REGISTRY_ADDRESSES, getValidationRegistryAddress } from './addresses.js';
+export { VALIDATION_REGISTRY_ABI, VALIDATION_REGISTRY_ADDRESSES, getValidationRegistryAddress, };
+export type ValidationStatus = 'REQUESTED' | 'RESPONDED';
+export interface ValidationRecord {
+    /** Same 32-byte hash committed by JinnRouter as `evidenceHash`. */
+    requestHash: Hex;
+    validatorAddress: Address;
+    agentId: bigint;
+    /**
+     * The `requestURI` provided at request time. NOTE: the deployed contract
+     * does not persist `requestURI` in storage — it appears only in the
+     * `ValidationRequest` event. This field is therefore left as an empty
+     * string when read back via `getStatus`; callers that need the URI must
+     * recover it from the indexed event log. Documented here so call sites
+     * don't accidentally rely on a value that round-trips through storage.
+     */
+    requestURI: string;
+    status: ValidationStatus;
+    /** uint8 0..100. Present only when `status === 'RESPONDED'`. */
+    response?: number;
+    /** Same caveat as requestURI: only present in events, not in storage. */
+    responseURI?: string;
+    responseHash?: Hex;
+    tag?: string;
+}
+export interface ValidationRegistryConfig {
+    validationRegistryAddress: Address;
+    /** Required for every read path. */
+    publicClient: PublicClient;
+    /** Required for write paths (`requestValidation`, `submitResponse`). */
+    walletClient?: WalletClient;
+}
+export declare class ValidationRegistryClient {
+    private readonly publicClient;
+    private readonly walletClient;
+    private readonly contractAddress;
+    constructor(config: ValidationRegistryConfig);
+    /**
+     * Submit a challenge — `validationRequest(validator, agentId, requestURI, requestHash)`.
+     *
+     * `requestHash` MUST equal `manifest.evidenceHash` (the same 32-byte hash
+     * JinnRouter committed in `claimDelivery`); see DR §4.4. The contract
+     * enforces uniqueness on `requestHash`, so duplicate calls revert.
+     *
+     * **Validator selection is open** at the contract level: any address may
+     * be passed as `validatorAddress`, and any caller authorised by the agent
+     * NFT (owner / approved / operator-for-all) may submit a request. Whether
+     * Jinn imposes an additional gating layer (whitelist, stake, randomized
+     * pool) is **deferred to a follow-up Phase 1b spec** and not enforced
+     * here.
+     *
+     * The agent-NFT permission check inside the contract means the caller's
+     * EOA / Safe must be authorised on `agentId` via `IdentityRegistry`
+     * (owner, getApproved, or isApprovedForAll). Callers should ensure this
+     * upstream — e.g. the operator submits requests against their own
+     * agentId.
+     *
+     * Returns the transaction hash. Caller is responsible for waiting on the
+     * receipt if they need confirmation semantics (kept off this path so the
+     * client is reusable from both EOA-direct and Safe-wrapped contexts —
+     * higher layers add the appropriate retry/confirm helper).
+     */
+    requestValidation(args: {
+        validatorAddress: Address;
+        agentId: bigint;
+        requestURI: string;
+        requestHash: Hex;
+    }): Promise<Hex>;
+    /**
+     * Submit a response — `validationResponse(requestHash, response, responseURI,
+     * responseHash, tag)`.
+     *
+     * Validators only. The contract checks `msg.sender === validatorAddress`
+     * and `response <= 100`. Callers must use the wallet that was named as
+     * `validatorAddress` in the matching `requestValidation` call.
+     */
+    submitResponse(args: {
+        requestHash: Hex;
+        /** uint8 0..100 score. */
+        response: number;
+        responseURI: string;
+        responseHash: Hex;
+        tag: string;
+    }): Promise<Hex>;
+    /**
+     * Fetch the current validation status for a given `requestHash`.
+     *
+     * Returns `null` if no request has been recorded for that hash. The
+     * deployed contract reverts (`"unknown"`) on unknown hashes; we catch and
+     * map that to `null` so callers can treat "not found" as a value rather
+     * than an exception.
+     *
+     * `requestURI` and `responseURI` are not persisted in contract storage —
+     * they appear only in the `ValidationRequest` / `ValidationResponse`
+     * events. The returned record therefore leaves `requestURI` empty and
+     * omits `responseURI`; callers that need them must read the indexed
+     * events.
+     */
+    getStatus(requestHash: Hex): Promise<ValidationRecord | null>;
+    /**
+     * All `requestHash` values ever filed against `agentId`. Order is
+     * insertion order from contract storage (per
+     * `_agentValidations[agentId]`).
+     */
+    getAgentValidations(agentId: bigint): Promise<Hex[]>;
+    /**
+     * All `requestHash` values ever assigned to `validatorAddress`. Order is
+     * insertion order from contract storage (per
+     * `_validatorRequests[validator]`).
+     */
+    getValidatorRequests(validatorAddress: Address): Promise<Hex[]>;
+    private requireWallet;
+}

package/dist/erc8004/validation.js

@@ -0,0 +1,219 @@
+/**
+ * ValidationRegistryClient — typed wrapper for the ERC-8004 ValidationRegistry
+ * contract.
+ *
+ * Phase 1b challenge mechanism. Per
+ * `docs/superpowers/specs/2026-04-27-erc-8004-entity-model-design.md` §4.4,
+ * Jinn challenges are anchored on the deployed `0x8004…` ValidationRegistry
+ * keyed by `(validatorAddress, agentId, requestHash)` where
+ * `requestHash = manifest.evidenceHash` — the same 32-byte hash JinnRouter
+ * already commits in `claimDelivery`. No new contracts are deployed; this
+ * client wraps the existing UUPS proxy.
+ *
+ * Wire shape (from /tmp/erc8004-ref/ValidationRegistryUpgradeable.sol):
+ *   - validationRequest(validator, agentId, requestURI, requestHash) — only
+ *     the agent owner / approved / operator can submit; reverts on duplicate
+ *     `requestHash`.
+ *   - validationResponse(requestHash, response, responseURI, responseHash, tag)
+ *     — only the validator named in the request may respond; `response` is a
+ *     0..100 score.
+ *   - getValidationStatus(requestHash) returns
+ *     (validator, agentId, response, responseHash, tag, lastUpdate). The
+ *     contract reverts on unknown `requestHash`.
+ *   - getAgentValidations(agentId) → bytes32[]
+ *   - getValidatorRequests(validator) → bytes32[]
+ *
+ * This module is intentionally **not wired into the daemon, evaluator, or CLI**.
+ * The UX of the challenge mechanism (who calls `requestValidation`, when, with
+ * what UI, with what validator-selection model) is a separate Phase 1b spec.
+ * This file ships the typed client; downstream beads consume it.
+ */
+import { VALIDATION_REGISTRY_ABI } from './abis.js';
+import { VALIDATION_REGISTRY_ADDRESSES, getValidationRegistryAddress, } from './addresses.js';
+// Re-exports so callers that imported these from the validation module
+// continue to work without touching `./abis.js` / `./addresses.js`.
+export { VALIDATION_REGISTRY_ABI, VALIDATION_REGISTRY_ADDRESSES, getValidationRegistryAddress, };
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+const ZERO_BYTES32 = '0x0000000000000000000000000000000000000000000000000000000000000000';
+// ── Client ───────────────────────────────────────────────────────────────────
+export class ValidationRegistryClient {
+    publicClient;
+    walletClient;
+    contractAddress;
+    constructor(config) {
+        this.publicClient = config.publicClient;
+        this.walletClient = config.walletClient;
+        this.contractAddress = config.validationRegistryAddress;
+    }
+    // ── Write methods ──────────────────────────────────────────────────────────
+    /**
+     * Submit a challenge — `validationRequest(validator, agentId, requestURI, requestHash)`.
+     *
+     * `requestHash` MUST equal `manifest.evidenceHash` (the same 32-byte hash
+     * JinnRouter committed in `claimDelivery`); see DR §4.4. The contract
+     * enforces uniqueness on `requestHash`, so duplicate calls revert.
+     *
+     * **Validator selection is open** at the contract level: any address may
+     * be passed as `validatorAddress`, and any caller authorised by the agent
+     * NFT (owner / approved / operator-for-all) may submit a request. Whether
+     * Jinn imposes an additional gating layer (whitelist, stake, randomized
+     * pool) is **deferred to a follow-up Phase 1b spec** and not enforced
+     * here.
+     *
+     * The agent-NFT permission check inside the contract means the caller's
+     * EOA / Safe must be authorised on `agentId` via `IdentityRegistry`
+     * (owner, getApproved, or isApprovedForAll). Callers should ensure this
+     * upstream — e.g. the operator submits requests against their own
+     * agentId.
+     *
+     * Returns the transaction hash. Caller is responsible for waiting on the
+     * receipt if they need confirmation semantics (kept off this path so the
+     * client is reusable from both EOA-direct and Safe-wrapped contexts —
+     * higher layers add the appropriate retry/confirm helper).
+     */
+    async requestValidation(args) {
+        const wallet = this.requireWallet('requestValidation');
+        const account = wallet.account;
+        if (!account) {
+            throw new Error('[ValidationRegistryClient] walletClient has no account');
+        }
+        return wallet.writeContract({
+            address: this.contractAddress,
+            abi: VALIDATION_REGISTRY_ABI,
+            functionName: 'validationRequest',
+            args: [args.validatorAddress, args.agentId, args.requestURI, args.requestHash],
+            account,
+            chain: wallet.chain ?? null,
+        });
+    }
+    /**
+     * Submit a response — `validationResponse(requestHash, response, responseURI,
+     * responseHash, tag)`.
+     *
+     * Validators only. The contract checks `msg.sender === validatorAddress`
+     * and `response <= 100`. Callers must use the wallet that was named as
+     * `validatorAddress` in the matching `requestValidation` call.
+     */
+    async submitResponse(args) {
+        if (!Number.isInteger(args.response) || args.response < 0 || args.response > 100) {
+            throw new Error(`[ValidationRegistryClient] response must be an integer in [0, 100]; got ${args.response}`);
+        }
+        const wallet = this.requireWallet('submitResponse');
+        const account = wallet.account;
+        if (!account) {
+            throw new Error('[ValidationRegistryClient] walletClient has no account');
+        }
+        return wallet.writeContract({
+            address: this.contractAddress,
+            abi: VALIDATION_REGISTRY_ABI,
+            functionName: 'validationResponse',
+            args: [
+                args.requestHash,
+                args.response,
+                args.responseURI,
+                args.responseHash,
+                args.tag,
+            ],
+            account,
+            chain: wallet.chain ?? null,
+        });
+    }
+    // ── Read methods ───────────────────────────────────────────────────────────
+    /**
+     * Fetch the current validation status for a given `requestHash`.
+     *
+     * Returns `null` if no request has been recorded for that hash. The
+     * deployed contract reverts (`"unknown"`) on unknown hashes; we catch and
+     * map that to `null` so callers can treat "not found" as a value rather
+     * than an exception.
+     *
+     * `requestURI` and `responseURI` are not persisted in contract storage —
+     * they appear only in the `ValidationRequest` / `ValidationResponse`
+     * events. The returned record therefore leaves `requestURI` empty and
+     * omits `responseURI`; callers that need them must read the indexed
+     * events.
+     */
+    async getStatus(requestHash) {
+        let raw;
+        try {
+            raw = (await this.publicClient.readContract({
+                address: this.contractAddress,
+                abi: VALIDATION_REGISTRY_ABI,
+                functionName: 'getValidationStatus',
+                args: [requestHash],
+            }));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes('unknown'))
+                return null;
+            throw err;
+        }
+        const [validatorAddress, agentId, response, responseHash, tag /*, lastUpdate */] = raw;
+        if (validatorAddress === ZERO_ADDRESS)
+            return null;
+        // Contract initialises responseHash=0 / tag="" until the validator
+        // responds; a non-zero responseHash OR a non-empty tag both indicate
+        // a response has landed (the validator may legitimately submit
+        // responseHash=0 with a non-empty tag, or vice versa). The
+        // `lastUpdate` block-timestamp also moves on response, but we treat
+        // the storage fields as the authoritative signal.
+        const hasResponded = responseHash !== ZERO_BYTES32 || tag !== '';
+        if (!hasResponded) {
+            return {
+                requestHash,
+                validatorAddress,
+                agentId,
+                requestURI: '',
+                status: 'REQUESTED',
+            };
+        }
+        return {
+            requestHash,
+            validatorAddress,
+            agentId,
+            requestURI: '',
+            status: 'RESPONDED',
+            response,
+            responseHash,
+            tag,
+        };
+    }
+    /**
+     * All `requestHash` values ever filed against `agentId`. Order is
+     * insertion order from contract storage (per
+     * `_agentValidations[agentId]`).
+     */
+    async getAgentValidations(agentId) {
+        const result = (await this.publicClient.readContract({
+            address: this.contractAddress,
+            abi: VALIDATION_REGISTRY_ABI,
+            functionName: 'getAgentValidations',
+            args: [agentId],
+        }));
+        return [...result];
+    }
+    /**
+     * All `requestHash` values ever assigned to `validatorAddress`. Order is
+     * insertion order from contract storage (per
+     * `_validatorRequests[validator]`).
+     */
+    async getValidatorRequests(validatorAddress) {
+        const result = (await this.publicClient.readContract({
+            address: this.contractAddress,
+            abi: VALIDATION_REGISTRY_ABI,
+            functionName: 'getValidatorRequests',
+            args: [validatorAddress],
+        }));
+        return [...result];
+    }
+    // ── Internal ───────────────────────────────────────────────────────────────
+    requireWallet(method) {
+        if (!this.walletClient) {
+            throw new Error(`[ValidationRegistryClient] ${method} requires a walletClient; ` +
+                `pass one via ValidationRegistryConfig.walletClient.`);
+        }
+        return this.walletClient;
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/erc8004/validation.js.map

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

package/dist/errors/persisted-bootstrap-error.d.ts

@@ -0,0 +1,4 @@
+import type { ErrorEnvelope } from './envelope.js';
+export declare function persistBootstrapError(envelope: ErrorEnvelope, earningDir: string): void;
+export declare function readBootstrapError(earningDir: string): ErrorEnvelope | null;
+export declare function clearBootstrapError(earningDir: string): void;

package/dist/errors/persisted-bootstrap-error.js

@@ -0,0 +1,50 @@
+/**
+ * Persist a fatal bootstrap error to disk so the panel can surface it to the
+ * operator after the daemon process has exited.
+ *
+ * The structured error envelope produced by `emitEnvelope` is written to
+ * `<earningDir>/bootstrap-error.json` *before* `process.exit(50)` runs. On
+ * the next `jinn run`, `/v1/bootstrap` reads this file and includes it in
+ * the response so the SPA can render an error state on the active phase
+ * instead of staying frozen on the last persisted bootstrap step.
+ *
+ * Cleared at the start of each bootstrap attempt — if the operator fixes
+ * the underlying issue and the daemon proceeds past the failed step, the
+ * error file disappears and the panel returns to a clean state.
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const FILE_NAME = 'bootstrap-error.json';
+export function persistBootstrapError(envelope, earningDir) {
+    try {
+        mkdirSync(earningDir, { recursive: true, mode: 0o700 });
+        writeFileSync(join(earningDir, FILE_NAME), JSON.stringify(envelope, null, 2) + '\n', { mode: 0o600 });
+    }
+    catch {
+        // Best-effort. A failure here doesn't change the existing exit-with-50
+        // contract — we just lose the panel breadcrumb.
+    }
+}
+export function readBootstrapError(earningDir) {
+    const path = join(earningDir, FILE_NAME);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function clearBootstrapError(earningDir) {
+    const path = join(earningDir, FILE_NAME);
+    if (!existsSync(path))
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Best-effort.
+    }
+}
+//# sourceMappingURL=persisted-bootstrap-error.js.map

package/dist/errors/persisted-bootstrap-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persisted-bootstrap-error.js","sourceRoot":"","sources":["../../src/errors/persisted-bootstrap-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,MAAM,SAAS,GAAG,sBAAsB,CAAC;AAEzC,MAAM,UAAU,qBAAqB,CAAC,QAAuB,EAAE,UAAkB;IAC/E,IAAI,CAAC;QACH,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACxD,aAAa,CACX,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,EAC3B,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EACxC,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,gDAAgD;IAClD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IACzC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAkB,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IACzC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO;IAC9B,IAAI,CAAC;QACH,UAAU,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;AACH,CAAC"}

package/dist/events/emitter.d.ts

@@ -0,0 +1,12 @@
+import { EventRingBuffer } from './ring-buffer.js';
+import type { StructuredEventKind } from './types.js';
+export declare function getEventBuffer(): EventRingBuffer;
+export interface EmitInput {
+    kind: StructuredEventKind;
+    message: string;
+    requestId?: string;
+    txHash?: string;
+    errorCode?: string;
+    details?: Record<string, unknown>;
+}
+export declare function emitStructured(input: EmitInput): void;

package/dist/events/emitter.js

@@ -0,0 +1,23 @@
+/**
+ * Global structured-event emitter for the daemon.
+ *
+ * Singleton ring buffer + a thin `emitStructured` helper. The /v1/events SSE
+ * endpoint subscribes to this buffer; the daemon's lifecycle/error sites push
+ * into it. See docs/superpowers/specs/2026-05-01-operator-local-app-design.md.
+ */
+import { randomUUID } from 'node:crypto';
+import { EventRingBuffer } from './ring-buffer.js';
+const RING = new EventRingBuffer(1000);
+export function getEventBuffer() {
+    return RING;
+}
+export function emitStructured(input) {
+    const event = {
+        schemaVersion: 1,
+        id: randomUUID(),
+        ts: new Date().toISOString(),
+        ...input,
+    };
+    RING.push(event);
+}
+//# sourceMappingURL=emitter.js.map

package/dist/events/emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../../src/events/emitter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGnD,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;AAEvC,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC;AACd,CAAC;AAWD,MAAM,UAAU,cAAc,CAAC,KAAgB;IAC7C,MAAM,KAAK,GAAoB;QAC7B,aAAa,EAAE,CAAC;QAChB,EAAE,EAAE,UAAU,EAAE;QAChB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,GAAG,KAAK;KACT,CAAC;IACF,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC"}

package/dist/events/ring-buffer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bounded in-memory ring buffer of structured daemon events with subscribe/snapshot.
+ *
+ * - `push` records an event and notifies subscribers; subscriber errors are isolated.
+ * - `snapshot` returns a defensive copy filtered by kinds/sinceId/limit.
+ * - Default capacity 1000; trim is amortized O(1) at expected event rates.
+ */
+import type { StructuredEvent, StructuredEventKind } from './types.js';
+export interface EventFilter {
+    kinds?: StructuredEventKind[];
+    sinceId?: string;
+    limit?: number;
+}
+export type EventSubscriber = (event: StructuredEvent) => void;
+export declare class EventRingBuffer {
+    private capacity;
+    private buffer;
+    private subscribers;
+    constructor(capacity?: number);
+    push(event: StructuredEvent): void;
+    snapshot(filter?: EventFilter): StructuredEvent[];
+    subscribe(sub: EventSubscriber): () => void;
+    /** Drop all buffered events; subscribers are retained. Intended for test isolation. */
+    clear(): void;
+}

package/dist/events/ring-buffer.js

@@ -0,0 +1,46 @@
+export class EventRingBuffer {
+    capacity;
+    buffer = [];
+    subscribers = new Set();
+    constructor(capacity = 1000) {
+        this.capacity = capacity;
+    }
+    push(event) {
+        this.buffer.push(event);
+        if (this.buffer.length > this.capacity) {
+            this.buffer = this.buffer.slice(-this.capacity);
+        }
+        for (const sub of this.subscribers) {
+            try {
+                sub(event);
+            }
+            catch (err) {
+                // never let subscriber errors propagate, but leave a breadcrumb
+                console.error('[events] subscriber threw:', err instanceof Error ? err.message : err);
+            }
+        }
+    }
+    snapshot(filter = {}) {
+        let out = this.buffer;
+        if (filter.sinceId) {
+            const idx = out.findIndex((e) => e.id === filter.sinceId);
+            out = idx >= 0 ? out.slice(idx + 1) : out;
+        }
+        if (filter.kinds && filter.kinds.length > 0) {
+            const allowed = new Set(filter.kinds);
+            out = out.filter((e) => allowed.has(e.kind));
+        }
+        if (filter.limit !== undefined)
+            out = out.slice(-filter.limit);
+        return [...out];
+    }
+    subscribe(sub) {
+        this.subscribers.add(sub);
+        return () => this.subscribers.delete(sub);
+    }
+    /** Drop all buffered events; subscribers are retained. Intended for test isolation. */
+    clear() {
+        this.buffer = [];
+    }
+}
+//# sourceMappingURL=ring-buffer.js.map

package/dist/events/ring-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-buffer.js","sourceRoot":"","sources":["../../src/events/ring-buffer.ts"],"names":[],"mappings":"AAiBA,MAAM,OAAO,eAAe;IAIN;IAHZ,MAAM,GAAsB,EAAE,CAAC;IAC/B,WAAW,GAAG,IAAI,GAAG,EAAmB,CAAC;IAEjD,YAAoB,WAAmB,IAAI;QAAvB,aAAQ,GAAR,QAAQ,CAAe;IAAG,CAAC;IAE/C,IAAI,CAAC,KAAsB;QACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YACvC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAClD,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACnC,IAAI,CAAC;gBACH,GAAG,CAAC,KAAK,CAAC,CAAC;YACb,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,gEAAgE;gBAChE,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACxF,CAAC;QACH,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,SAAsB,EAAE;QAC/B,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;QACtB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC;YAC1D,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC5C,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtC,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;YAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/D,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;IAClB,CAAC;IAED,SAAS,CAAC,GAAoB;QAC5B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5C,CAAC;IAED,uFAAuF;IACvF,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;IACnB,CAAC;CACF"}

package/dist/events/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Structured event types for the operator-facing local app.
+ *
+ * Events are produced by the daemon (intent state transitions, errors, lifecycle
+ * markers) and consumed by /v1/events SSE + /v1/events/recent JSON endpoints
+ * served to the operator SPA. See docs/superpowers/specs/2026-05-01-operator-local-app-design.md.
+ */
+import { z } from 'zod';
+export declare const StructuredEventKindSchema: z.ZodEnum<["intent", "reward", "fleet", "system", "error", "log"]>;
+export type StructuredEventKind = z.infer<typeof StructuredEventKindSchema>;
+export declare const StructuredEventSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    ts: z.ZodString;
+    kind: z.ZodEnum<["intent", "reward", "fleet", "system", "error", "log"]>;
+    message: z.ZodString;
+    requestId: z.ZodOptional<z.ZodString>;
+    txHash: z.ZodOptional<z.ZodString>;
+    errorCode: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    id: string;
+    kind: "error" | "reward" | "fleet" | "intent" | "system" | "log";
+    schemaVersion: 1;
+    ts: string;
+    details?: Record<string, unknown> | undefined;
+    requestId?: string | undefined;
+    txHash?: string | undefined;
+    errorCode?: string | undefined;
+}, {
+    message: string;
+    id: string;
+    kind: "error" | "reward" | "fleet" | "intent" | "system" | "log";
+    schemaVersion: 1;
+    ts: string;
+    details?: Record<string, unknown> | undefined;
+    requestId?: string | undefined;
+    txHash?: string | undefined;
+    errorCode?: string | undefined;
+}>;
+export type StructuredEvent = z.infer<typeof StructuredEventSchema>;

package/dist/events/types.js

@@ -0,0 +1,28 @@
+/**
+ * Structured event types for the operator-facing local app.
+ *
+ * Events are produced by the daemon (intent state transitions, errors, lifecycle
+ * markers) and consumed by /v1/events SSE + /v1/events/recent JSON endpoints
+ * served to the operator SPA. See docs/superpowers/specs/2026-05-01-operator-local-app-design.md.
+ */
+import { z } from 'zod';
+export const StructuredEventKindSchema = z.enum([
+    'intent',
+    'reward',
+    'fleet',
+    'system',
+    'error',
+    'log',
+]);
+export const StructuredEventSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string(),
+    ts: z.string(),
+    kind: StructuredEventKindSchema,
+    message: z.string(),
+    requestId: z.string().optional(),
+    txHash: z.string().optional(),
+    errorCode: z.string().optional(),
+    details: z.record(z.unknown()).optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/events/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/events/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC9C,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,OAAO;IACP,KAAK;CACN,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,aAAa,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,yBAAyB;IAC/B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC"}