@getbourdon/participants 0.2.3 → 0.2.4

package/dist/base.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Bourdon participant base — the Protocol → TS interface, errors, and the
+ * AgentStore / HealthStatus types. Faithful port of `participants/base.py`.
+ *
+ * The L5 dataclass model (AgentInfo/Entity/Session/VisibilityPolicy/L5Manifest),
+ * the `toDict` omission rules, and the visibility helpers all live in
+ * `@getbourdon/l5` and are reused verbatim — only THAT output shape is the parity
+ * contract. This module owns the participant CONTRACT surface around them.
+ *
+ * Contract semantics (enforced by every reader, asserted by the conformance
+ * fixtures, never by trust):
+ *   1. visibility filter BEFORE emission (`filterForFederation`) — private wins.
+ *   2. deterministic / idempotent `exportL5` — same store → identical `toDict`.
+ *   3. `healthCheck` NEVER throws — catch-all → degraded/blocked.
+ *   4. every native string through `@getbourdon/redaction` before it enters L5.
+ */
+import type { L5ManifestModel, SessionModel } from "@getbourdon/l5";
+/** Tied to Bourdon spec v0.1 — same literals as the Python oracle. */
+export declare const CONTRACT_VERSION = "0.1";
+export declare const SPEC_VERSION = "0.1";
+/** Base class for participant errors. */
+export declare class ParticipantError extends Error {
+    constructor(message?: string);
+}
+/** Raised by `discover()` when the native store cannot be found or read.
+ * Non-fatal: L6 skips this agent rather than aborting the whole export. */
+export declare class ParticipantDiscoveryError extends ParticipantError {
+}
+/** Raised by `exportL5()` / `exportSessions()` when an export fails mid-op
+ * (the store WAS present — distinct from a discovery miss). */
+export declare class ParticipantExportError extends ParticipantError {
+}
+/** Raised when the native store's version is outside the supported range.
+ * Subtype of discovery error (a version mismatch is a discovery-time miss). */
+export declare class ParticipantVersionMismatchError extends ParticipantDiscoveryError {
+}
+/** Metadata describing the native agent store. Returned by `discover()`. */
+export interface AgentStore {
+    path: string;
+    version: string;
+    metadata: Record<string, unknown>;
+}
+/** Returned by `healthCheck()`. Consumed by the `bourdon doctor` CLI. */
+export interface HealthStatus {
+    status: "ok" | "degraded" | "blocked";
+    reason?: string;
+    details: Record<string, unknown>;
+    /** A human-runnable command to remedy a non-ok status. */
+    proposedFix?: string;
+}
+/**
+ * Structural interface every participant must satisfy (the Python
+ * `@runtime_checkable Protocol`). Duck-typed at registration: a class is a
+ * participant iff it has `agentId` + `agentType` + `exportL5` + `healthCheck`.
+ *
+ * Optional members (`displayName`, a `defaultNativePath` static) are documented
+ * here as in the Python Protocol; discovery + the setup wizard fall back to
+ * sensible defaults when absent.
+ */
+export interface BourdonParticipant {
+    agentId: string;
+    agentType: string;
+    nativePath: string;
+    /** Human-friendly label (e.g. "GitHub Copilot"). Optional. */
+    displayName?: string;
+    /** Quarantined-class marker (Python `QUARANTINED_CLASS`). When true, the CLI
+     * requires `--i-understand-the-risk` to register the agent trusted, and its
+     * exports are staged for operator review rather than written to the live
+     * store (spec D6: quarantine follows the content, not the invoker). Absent =
+     * a normal, non-quarantined participant. Read by `bourdon agent add/set-tier`
+     * (cli/src/commands/federation.ts). */
+    quarantinedClass?: boolean;
+    /** Confirm the native store exists; return metadata. Throws
+     * {@link ParticipantDiscoveryError} when missing/unreadable. */
+    discover(): AgentStore;
+    /** Build the L5 manifest from native memory, applying the visibility filter
+     * BEFORE return. Deterministic — same store yields the same manifest. */
+    exportL5(since?: Date): L5ManifestModel;
+    /** Export recent sessions in normalized schema. */
+    exportSessions(since?: Date, limit?: number): SessionModel[];
+    /** Return ok / degraded / blocked with a reason. MUST NOT throw. */
+    healthCheck(): HealthStatus;
+}
+/**
+ * Tiny structural guard mirroring Python's `_PARTICIPANT_MARKER_ATTRS`
+ * duck-type: a value is a participant iff it carries the four marker members.
+ */
+export declare function isParticipant(obj: unknown): obj is BourdonParticipant;
+/**
+ * Environment variable holding the deployment's own project-name recognition
+ * vocabulary, as a comma-separated list (e.g.
+ * `BOURDON_PROJECT_HINTS="Acme Portal,Widget API,internal-tools"`).
+ */
+export declare const PROJECT_HINTS_ENV = "BOURDON_PROJECT_HINTS";
+/**
+ * Project-name hints used to tag sessions with a project focus.
+ *
+ * Bourdon ships **no** project roster of its own — the `defaults` a reader
+ * passes are limited to product-neutral names (this product, plus the agent
+ * surfaces it federates). A deployment that wants its own projects recognized
+ * sets {@link PROJECT_HINTS_ENV}; those entries are appended to `defaults`.
+ *
+ * Matching downstream is case-insensitive substring matching, so entries are
+ * de-duplicated case-insensitively here while preserving first-seen order and
+ * the original casing (which is what gets emitted as the project name).
+ *
+ * Mirrors Python `participants.base.load_project_hints`.
+ */
+export declare function loadProjectHints(defaults?: readonly string[]): readonly string[];

package/dist/base.js

@@ -0,0 +1,88 @@
+/**
+ * Bourdon participant base — the Protocol → TS interface, errors, and the
+ * AgentStore / HealthStatus types. Faithful port of `participants/base.py`.
+ *
+ * The L5 dataclass model (AgentInfo/Entity/Session/VisibilityPolicy/L5Manifest),
+ * the `toDict` omission rules, and the visibility helpers all live in
+ * `@getbourdon/l5` and are reused verbatim — only THAT output shape is the parity
+ * contract. This module owns the participant CONTRACT surface around them.
+ *
+ * Contract semantics (enforced by every reader, asserted by the conformance
+ * fixtures, never by trust):
+ *   1. visibility filter BEFORE emission (`filterForFederation`) — private wins.
+ *   2. deterministic / idempotent `exportL5` — same store → identical `toDict`.
+ *   3. `healthCheck` NEVER throws — catch-all → degraded/blocked.
+ *   4. every native string through `@getbourdon/redaction` before it enters L5.
+ */
+/** Tied to Bourdon spec v0.1 — same literals as the Python oracle. */
+export const CONTRACT_VERSION = "0.1";
+export const SPEC_VERSION = "0.1";
+// -- Errors -------------------------------------------------------------------
+/** Base class for participant errors. */
+export class ParticipantError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** Raised by `discover()` when the native store cannot be found or read.
+ * Non-fatal: L6 skips this agent rather than aborting the whole export. */
+export class ParticipantDiscoveryError extends ParticipantError {
+}
+/** Raised by `exportL5()` / `exportSessions()` when an export fails mid-op
+ * (the store WAS present — distinct from a discovery miss). */
+export class ParticipantExportError extends ParticipantError {
+}
+/** Raised when the native store's version is outside the supported range.
+ * Subtype of discovery error (a version mismatch is a discovery-time miss). */
+export class ParticipantVersionMismatchError extends ParticipantDiscoveryError {
+}
+/**
+ * Tiny structural guard mirroring Python's `_PARTICIPANT_MARKER_ATTRS`
+ * duck-type: a value is a participant iff it carries the four marker members.
+ */
+export function isParticipant(obj) {
+    if (obj === null || typeof obj !== "object")
+        return false;
+    const o = obj;
+    return (typeof o["agentId"] === "string" &&
+        typeof o["agentType"] === "string" &&
+        typeof o["exportL5"] === "function" &&
+        typeof o["healthCheck"] === "function");
+}
+/**
+ * Environment variable holding the deployment's own project-name recognition
+ * vocabulary, as a comma-separated list (e.g.
+ * `BOURDON_PROJECT_HINTS="Acme Portal,Widget API,internal-tools"`).
+ */
+export const PROJECT_HINTS_ENV = "BOURDON_PROJECT_HINTS";
+/**
+ * Project-name hints used to tag sessions with a project focus.
+ *
+ * Bourdon ships **no** project roster of its own — the `defaults` a reader
+ * passes are limited to product-neutral names (this product, plus the agent
+ * surfaces it federates). A deployment that wants its own projects recognized
+ * sets {@link PROJECT_HINTS_ENV}; those entries are appended to `defaults`.
+ *
+ * Matching downstream is case-insensitive substring matching, so entries are
+ * de-duplicated case-insensitively here while preserving first-seen order and
+ * the original casing (which is what gets emitted as the project name).
+ *
+ * Mirrors Python `participants.base.load_project_hints`.
+ */
+export function loadProjectHints(defaults = []) {
+    const hints = [];
+    const seen = new Set();
+    const raw = process.env[PROJECT_HINTS_ENV] ?? "";
+    for (const candidate of [...defaults, ...raw.split(",")]) {
+        const name = candidate.trim();
+        if (!name)
+            continue;
+        const key = name.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        hints.push(name);
+    }
+    return hints;
+}