@scp-dev/broker 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import * as _scp_dev_core from '@scp-dev/core';
-import { ScopePreset, Claim, EndpointView, ScopeView, ScopeChange, Envelope, StopWaitResult, PeerView, WhyResult, SendParams, SendResult, ActivityRow, XListed, Selector, Sql, JudgeModelConfig, JudgeClient, JudgePolicy, Verdict } from '@scp-dev/core';
-import { FederatedCore } from '@scp-dev/hub';
+import { ScopePreset, Claim, EndpointView, ScopeView, ScopeChange, Envelope, StopWaitResult, PeerView, WhyResult, SendParams, SendResult, ActivityRow, XListed, Selector } from '@scp-dev/core';
+import { JudgeGate as JudgeGate$1, JudgeGateOptions, FederatedCore, Deliver, JudgeClientFactory } from '@scp-dev/hub';
+export { Deliver } from '@scp-dev/hub';
 
 interface Hello {
     claim?: Claim;
@@ -10,6 +10,11 @@ interface Hello {
     tty?: boolean;
     /** a hook's connection: it claims like an agent but never counts as connected, and posts only event and status */
     transient?: boolean;
+    /** with `transient`: the session joins the relay on demand, taking `handle` when given, and links itself under the agent `under` */
+    join?: {
+        handle?: string;
+        under?: string;
+    };
     /** a one-shot command: the broker announces no presence change when it connects or goes */
     brief?: boolean;
     /** no identity: list, status, watch, log and policy only */
@@ -172,6 +177,16 @@ declare class BrokerUnavailable extends Error {
  */
 declare function connectBroker(dir: string, start?: () => void, timeoutMs?: number): Promise<RelayClient>;
 
+/** what the broker gives the bridge: waking local waiters, telling local watchers, the local policy's state */
+interface BridgeHooks {
+    /** a local endpoint got a message */
+    wake(endpoint: string): void;
+    /** a fleet event for local watchers only; never forwarded back */
+    fleet(event: Record<string, unknown>): void;
+    /** loads the local policy; a reason when it is unusable */
+    policyError(): string | null;
+    log?(line: string): void;
+}
 interface BridgeConfig {
     /** the hub's https origin, from the caller; the socket is <origin>/v1/relay/ws */
     url: string;
@@ -217,6 +232,8 @@ interface Bridge {
     changed(endpoint: string): void;
     /** rules, caps, groups or a title changed, which can touch several endpoints: every mirrored endpoint is sent again */
     resync(): void;
+    /** a local endpoint took another handle: the hub renames its mirror in place, keeping what queued for it */
+    renamed(endpoint: string, was: string): void;
     /** a local endpoint's activity, posted to the hub */
     activity(endpoint: string, row: ActivityRow): void;
     /** the endpoints of other accounts this account's contacts let it reach */
@@ -268,116 +285,9 @@ declare function privateDir(path: string): string;
  */
 declare function socketPath(dir: string): string;
 
-type JudgeClientFactory = (model: JudgeModelConfig, key: () => Promise<string>) => JudgeClient;
-type Origin = {
-    tty?: boolean;
-    unverified?: boolean;
-};
-/** sends as `from` through the same path an unjudged send takes, waking recipients */
-type Deliver = (from: string, params: SendParams, origin: Origin) => Promise<SendResult>;
-interface JudgeGateOptions {
-    sql: Sql;
-    core: FederatedCore;
-    now: () => number;
-    /** where key_env is read */
-    env: Record<string, string | undefined>;
-    client?: JudgeClientFactory | undefined;
-    log: (line: string) => void;
-    /** an endpoint got a notice */
-    wake: (endpoint: string) => void;
-}
-interface HoldRow {
-    id: string;
-    from_ep: string;
-    params: string;
-    origin: string;
-    verdict: string;
-    created_at: number;
-    expires_at: number;
-    state: "held" | "releasing" | "released" | "refused" | "expired";
-    by: string | null;
-    resolved_at: number | null;
-}
-/** a hold as the human's review lists it: never the body */
-interface HoldView {
-    id: string;
-    from: string;
-    to: string[];
-    state: HoldRow["state"];
-    created_at: string;
-    expires_at: string;
-    categories: string[];
-    reason: string;
-    boundary: string;
-    source: Verdict["source"];
-    bytes: number;
-    by: string | null;
-    resolved_at: string | null;
-}
-/**
- * the broker's local judge (policy `judge`): shadow judges after delivery and only audits; enforce judges before delivery and passes,
- * redacts, refuses or holds. Holds wait in `judge_holds` for the human at a terminal; their body is purged once resolved or expired
- */
-declare class JudgeGate {
-    private readonly o;
-    readonly stats: _scp_dev_core.JudgeStats;
-    private policy;
-    private version;
-    private client;
-    private readonly cache;
-    private readonly shadows;
-    /** judged sends in the last hour per budget: `ep:<id>`, `tree:<root id>` and `*` for the whole broker */
-    private readonly spent;
-    constructor(o: JudgeGateOptions);
-    /** the policy's judge section; a model client only when its key is readable, else the prefilter alone */
-    configure(policy: JudgePolicy | undefined): void;
-    private keyReader;
-    /** resolves once every shadow judgement started so far finished */
-    settled(): Promise<void>;
-    /** a send or ask through the judge; an unjudged one goes straight to `deliver` */
-    send(from: string, params: SendParams, origin: Origin, deliver: Deliver): Promise<SendResult>;
-    /** an earlier judged send or waiting hold under the send's client_id: the same message is answered as before, another one refused as core refuses it */
-    private seen;
-    private remember;
-    /**
-     * a judged send counts before any model call against its sender's, its lineage tree's and the whole broker's budget, since refused and
-     * held sends never reach the send's own limits, and a new handle or a helper process must not bring a fresh budget
-     */
-    private spend;
-    /** how many budgets are tracked (idle ones are evicted by the sweep) */
-    budgetKeys(): number;
-    /** the held messages, newest first, without bodies */
-    holds(state?: string): HoldView[];
-    /** one hold with its body and the judge's redactions while it waits */
-    show(id: string): HoldView & {
-        body?: string;
-        redactions?: {
-            quote?: string;
-            kind: string;
-        }[];
-    };
-    /** delivers a held message as its sender, as stored or redacted: scope, policy and limits are checked again by the send itself */
-    release(id: string, options: {
-        redacted?: boolean;
-        by: string;
-    }, deliver: Deliver): Promise<SendResult>;
-    /** refuses a held message: it is never delivered, and its sender hears the human's reason */
-    refuse(id: string, reason: string, by: string): HoldView;
-    /** expires holds past their message TTL (body purged, sender told) and drops resolved ones past the audit window */
-    sweep(): void;
-    private expire;
-    /** the recipients by the boundary their message crosses; throws as send does for a target the sender cannot reach */
-    private boundaries;
-    private judge;
-    private shadow;
-    private hold;
-    private detail;
-    private storedDetail;
-    /** marks a hold resolved and purges its body and the judge's quotes of it */
-    private resolve;
-    private tell;
-    private row;
-    private view;
+/** the hub's judge gate reading `key_file` keys from disk */
+declare class JudgeGate extends JudgeGate$1 {
+    constructor(options: JudgeGateOptions);
 }
 
 interface BrokerOptions {
@@ -405,6 +315,8 @@ interface BrokerOptions {
     bridge?: BridgeConfig | undefined;
     /** reads the bridge configuration again for bridge_relink; one that appeared or names another hub or machine restarts the broker */
     bridgeConfig?: (() => Promise<BridgeConfig | undefined>) | undefined;
+    /** experimental: another link to other machines in place of the hub's, started only when `bridge` is unset */
+    link?: LinkFactory | undefined;
     /** how often presence that decays without a request (a hook-only endpoint) is checked for changes (default 60 s) */
     presenceEveryMs?: number | undefined;
     /** where a judge model's key_env is read (default the broker's environment) */
@@ -412,6 +324,13 @@ interface BrokerOptions {
     /** the judge model client for a policy's `judge.model` (default the provider's HTTP API) */
     judgeClient?: JudgeClientFactory | undefined;
 }
+/** what a link gets from the broker: its core, the remote hooks a bridge gets, and a send as a local endpoint or a mirrored one through the judge */
+interface LinkContext {
+    core: FederatedCore;
+    hooks: BridgeHooks;
+    send: Deliver;
+}
+type LinkFactory = (context: LinkContext) => Bridge;
 interface Broker {
     socket: string;
     core: FederatedCore;
@@ -423,4 +342,16 @@ interface Broker {
 }
 declare function startBroker(options: BrokerOptions): Promise<Broker>;
 
-export { type Bridge, type BridgeConfig, type BridgeStatus, type Broker, type BrokerInfo, type BrokerOptions, BrokerRunning, BrokerUnavailable, type GrantParams, type GroupParams, type Hello, type HelloResult, MAX_LINE, RelayClient, accountHome, connectBroker, localHostName, policyPath, privateDir, relayDir, relaySocketUrl, shortHostname, socketPath, startBroker, systemHostname, thisHostname };
+/**
+ * What the broker last decided about a harness session, by its session key: whether it joined or left, and the handle it goes by. Hooks and
+ * the MCP shim read it before they claim, so a session that never joined (manual join mode) or left stays off the relay without a broker
+ * round trip, and a renamed session claims its own name. The broker writes it; the endpoint rows stay the source of truth.
+ */
+interface SessionMarker {
+    joined: boolean;
+    handle?: string;
+}
+declare function readSessionMarker(dir: string, session: string): SessionMarker | undefined;
+declare function writeSessionMarker(dir: string, session: string, marker: SessionMarker): void;
+
+export { type Bridge, type BridgeConfig, type BridgeHooks, type BridgeStatus, type Broker, type BrokerInfo, type BrokerOptions, BrokerRunning, BrokerUnavailable, type GrantParams, type GroupParams, type Hello, type HelloResult, type LinkContext, type LinkFactory, MAX_LINE, RelayClient, type SessionMarker, accountHome, connectBroker, localHostName, policyPath, privateDir, readSessionMarker, relayDir, relaySocketUrl, shortHostname, socketPath, startBroker, systemHostname, thisHostname, writeSessionMarker };