@scp-dev/broker 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @scp-dev/broker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The SCP local broker: one daemon per user per machine, serving JSON-RPC on a unix socket, with its client and the bridge to an account hub.
+
+```sh
+npm install @scp-dev/broker
+```
+
+## Usage
+
+```ts
+import { RelayClient, relayDir, startBroker } from "@scp-dev/broker"
+
+const broker = await startBroker({ dir: relayDir() })
+
+const orch = await RelayClient.connect(broker.socket)
+await orch.hello({ claim: { handle: "orch", harness: "claude-code" } })
+const parser = await RelayClient.connect(broker.socket)
+await parser.hello({ claim: { handle: "parser", harness: "codex" } })
+
+await orch.request("send", { to: "parser", body: "Also cover the empty-input case." })
+const { messages } = await parser.request<{ messages: { body: { text: string } }[] }>("inbox", { wait_s: 5 })
+```
+
+Clients that should start the daemon on demand use `connectBroker(dir, start)`.
+
+## Provides
+
+- `startBroker`: the daemon, with a single-instance lock, the policy file and an idle exit.
+- `RelayClient` and `connectBroker`: the socket client every CLI verb, hook and MCP tool uses.
+- The bridge to an account hub, opened only when configured.
+- The judge gate at configured boundaries.
+- Path helpers for `~/.local/state/scp` and `~/.config/scp`.
+
+Implements [Transport and framing](https://scp.dev/spec#5-transport-and-framing), [Federation](https://scp.dev/spec#14-federation-and-cross-account) and the [wire methods](https://scp.dev/spec#appendix-a-wire-methods-local-broker). See the [root README](https://github.com/scphq/scp#readme).
+
+## License
+
+[Apache-2.0](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,422 @@
+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';
+
+interface Hello {
+    claim?: Claim;
+    resume?: string;
+    /** the human inbox me/; `tty` says whether a terminal is attached, and is recorded on what it sends */
+    human?: boolean;
+    tty?: boolean;
+    /** a hook's connection: it claims like an agent but never counts as connected, and posts only event and status */
+    transient?: boolean;
+    /** 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 */
+    observe?: boolean;
+    /** an observer's process lineage: when it lands on an endpoint, the observer gets that endpoint's view and may narrow */
+    lineage?: string[];
+    /** an observer's lineage up to its nearest harness process: when it lands on an agent endpoint, the connection acts as it with lineage auth */
+    self?: string[];
+    /** a spawn-env grant from a shell with no name: the hello binds only to the endpoint that spent it, or one below it */
+    grant?: string;
+    cwd?: string;
+}
+interface BrokerInfo {
+    socket: string;
+    dir: string;
+    pid: number;
+    policy: {
+        file: string;
+        state: "open" | "loaded" | "error";
+        error?: string;
+    };
+}
+interface HelloResult {
+    endpoint: EndpointView | null;
+    token?: string;
+    /** the broker checked the hello's grant against the endpoint it bound */
+    grant_bound?: boolean;
+    /** a hook's subagent claim the broker honoured, and whether it made the endpoint */
+    subagent?: true;
+    created?: true;
+    capabilities: string[];
+    preamble: string;
+    broker: BrokerInfo;
+}
+interface GrantParams {
+    name?: string;
+    labels?: Record<string, string>;
+    title?: string;
+    under?: string;
+    scope?: ScopePreset;
+    in?: string[];
+    out?: string[];
+    allow?: string[];
+    groups?: string[];
+    ttl_s?: number;
+    /** a full process key: a claim from that process's tree with no grant of its own takes this grant (`swarm spawn` binds its own) */
+    bind_process?: string;
+    /** `swarm spawn`'s, which waits on the harness it runs: the spawner's stop may wait for that worker */
+    spawn?: boolean;
+    /** `swarm spawn --no-push`'s: the spawner's stop never waits on that worker, whose messages and handback stay ordinary unread ones */
+    no_push?: boolean;
+    /** with peek on, the spawn's prompt: kept scrubbed as the worker's first peek turn once it joins */
+    prompt?: string;
+}
+interface GroupParams {
+    action: "create" | "add" | "remove" | "rules" | "ls" | "show" | "drop" | "pin" | "unpin";
+    name?: string;
+    endpoint?: string;
+    in?: string[];
+    out?: string[];
+    rules?: string[];
+}
+/** one NDJSON JSON-RPC connection to the local broker */
+declare class RelayClient {
+    private nextId;
+    private readonly pending;
+    private readonly reader;
+    private readonly writer;
+    private socket;
+    private closedError;
+    private listeners;
+    static connect(path: string): Promise<RelayClient>;
+    onNotification(fn: (method: string, params: unknown) => void): void;
+    request<T = unknown>(method: string, params?: object): Promise<T>;
+    hello(hello: Hello): Promise<HelloResult>;
+    rules(endpoint?: string): Promise<ScopeView>;
+    rulesSet(params: {
+        endpoint?: string;
+        in?: string[];
+        out?: string[];
+        scope?: ScopePreset;
+        allow?: string[];
+    }): Promise<ScopeView>;
+    rulesWiden(params: {
+        endpoint: string;
+        in?: string[];
+        out?: string[];
+    }): Promise<ScopeChange>;
+    rulesLift(params: {
+        endpoint: string;
+        cap: string;
+    }): Promise<ScopeView>;
+    /** a `krt_` grant for a spawn: `env` holds SCP_GRANT, which is a secret */
+    grant(params: GrantParams): Promise<{
+        token: string;
+        env: Record<string, string>;
+        steer?: {
+            key: string;
+            parent: string;
+        };
+    }>;
+    /**
+     * the harness a spawn ran with `grant` exited: its endpoint goes done and offline, or a grant no one spent is revoked, and the spawner gets
+     * `output` back in the handback message, unless the harness never `started`
+     */
+    spawnExit(params: {
+        grant: string;
+        code: number;
+        output?: string;
+        stderr?: string;
+        unapplied?: string[];
+        exits?: number[];
+        started?: boolean;
+    }): Promise<{
+        joined: boolean;
+        name: string | null;
+        endpoint: EndpointView | null;
+        handback?: string | null;
+    }>;
+    /**
+     * a spawned worker that exited: its harness session id, the transcript its hooks named with it and its spawner's unread messages to it;
+     * with `take` and a session they are marked read, for a resume to carry them
+     */
+    spawnSteers(params: {
+        grant: string;
+        take?: boolean;
+    }): Promise<{
+        session: string | null;
+        steers: Envelope[];
+        transcript?: string | null;
+    }>;
+    /**
+     * at a stop: the spawned workers' unread messages, held for the hook to print, waiting up to `wait_s` while workers still run, none came,
+     * pushes are left and no prompt moved the `prompts` mark inject handed out; with `wait_s` above 0 and other workers still running, the
+     * broker gathers more of their results into the same push for up to ${LIMITS.pushGraceS} s, which may run past `wait_s`
+     */
+    stopWait(waitS?: number, prompts?: number): Promise<StopWaitResult>;
+    group(params: GroupParams): Promise<unknown>;
+    admin(params: {
+        action: "grant" | "revoke" | "ls";
+        subject?: string;
+        tree?: string;
+        group?: string;
+    }): Promise<unknown>;
+    peers(): Promise<PeerView[]>;
+    why(from: string, to: string): Promise<WhyResult>;
+    close(): void;
+    private flush;
+    private onData;
+    private dispatchLines;
+    private fail;
+    private onClose;
+}
+declare class BrokerUnavailable extends Error {
+}
+/**
+ * A connection to the broker for `dir`. With `start`, a missing broker is started (detached)
+ * and the connection retried for up to `timeoutMs`. A socket whose directory is a link, someone
+ * else's, or writable by others is refused before anything is sent: in /tmp anyone could make it first.
+ */
+declare function connectBroker(dir: string, start?: () => void, timeoutMs?: number): Promise<RelayClient>;
+
+interface BridgeConfig {
+    /** the hub's https origin, from the caller; the socket is <origin>/v1/relay/ws */
+    url: string;
+    /** the account's bearer credential for the hub, opaque to the broker; null keeps the bridge down and says why in status() */
+    token: string | null;
+    /** why there is no credential, for status() */
+    tokenError?: string | undefined;
+    /** reads the credential again before each reconnect, so an expired or replaced one is picked up */
+    credentials?: (() => Promise<string | null>) | undefined;
+    machine: string;
+    /** which local endpoints are mirrored to the hub (default ["*"]) */
+    mirror?: Selector[] | undefined;
+    /** drop cwd, status notes and activity summaries from what is mirrored */
+    redact?: boolean | undefined;
+    /** let messages marked private leave this machine */
+    privateOk?: boolean | undefined;
+    /** a WebSocket constructor (tests) */
+    webSocket?: WebSocketWithHeaders | undefined;
+    /** reconnect backoff bounds (default 1 s to 60 s) */
+    backoff?: {
+        minMs: number;
+        maxMs: number;
+    } | undefined;
+    /** how long a forward cut off by a dropped connection waits for the next one (default 30 s) */
+    forwardWaitMs?: number | undefined;
+    /** the wait before a failed inject is tried again, doubling for each later try (default 1 s) */
+    injectBackoffMs?: number | undefined;
+}
+interface BridgeStatus {
+    enabled: true;
+    machine: string;
+    url: string;
+    connected: boolean;
+    last_error: string | null;
+    since: string;
+}
+interface Bridge {
+    /** a send whose recipients are all on other machines, on behalf of the local endpoint `from` */
+    forward(from: string, params: SendParams, origin?: {
+        tty?: boolean;
+    }): Promise<SendResult>;
+    /** a local endpoint was claimed, let go or changed its status: mirrored as a delta */
+    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's activity, posted to the hub */
+    activity(endpoint: string, row: ActivityRow): void;
+    /** the endpoints of other accounts this account's contacts let it reach */
+    contacts(): Promise<XListed[]>;
+    status(): BridgeStatus;
+    stop(): Promise<void>;
+}
+/** a WebSocket constructor that takes request headers, as Bun's and Node's do */
+type WebSocketWithHeaders = new (url: string, options: {
+    headers: Record<string, string>;
+}) => WebSocket;
+/** `<origin>/v1/relay/ws` with ws or wss */
+declare function relaySocketUrl(origin: string): string;
+
+declare class BrokerRunning extends Error {
+}
+
+/** the longest request line the broker reads, in bytes */
+declare const MAX_LINE: number;
+
+type Run = (cmd: string[]) => {
+    exitCode: number | null;
+    stdout: string | Buffer;
+};
+/** macOS's LocalHostName (read only), or undefined when it is unset */
+declare function localHostName(run?: Run): string | undefined;
+/** this machine's name: on macOS its LocalHostName, which a network change does not rename as it can the hostname; else the hostname */
+declare function systemHostname(platform?: string, local?: () => string | undefined, fallback?: () => string): string;
+/** systemHostname, read once per process */
+declare function thisHostname(): string;
+/** the lowercased first label of `name` (default this machine's): agents' machine label, and what `machine:` matches */
+declare function shortHostname(name?: string): string;
+/** `$SCP_DIR`, else `$XDG_STATE_HOME/scp`, else ~/.local/state/scp */
+declare function relayDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * `~/.config/scp/policy.json` of the account the broker runs as, from the user database rather
+ * than HOME or XDG_CONFIG_HOME, so the process that happens to start the broker cannot pick its policy
+ */
+declare function policyPath(): string;
+/** the account's home directory from the user database, falling back to HOME where that is unavailable */
+declare function accountHome(): string;
+/** a private directory: created 0700, and refused when it is a link or someone else's */
+declare function privateDir(path: string): string;
+/**
+ * The broker's socket: inside the relay dir, unless that path is too long for a unix socket
+ * (deep temp HOMEs), then a per-user, per-dir private directory under /tmp.
+ */
+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;
+}
+
+interface BrokerOptions {
+    dir: string;
+    /** the policy file; missing means open */
+    policyPath?: string | undefined;
+    /** the user part of addresses */
+    user?: string | undefined;
+    /** exit after this long with no connection and nothing waiting (default 30 min); 0 never */
+    idleMs?: number | undefined;
+    now?: (() => number) | undefined;
+    /** extra roots attachments may point into, besides the sender's cwd */
+    roots?: string[] | undefined;
+    /** bytes queued for one connection before fleet events to it are dropped and replies end it (default 4 MiB) */
+    outboundCapBytes?: number | undefined;
+    /** requests one connection may have in flight (default 32) */
+    maxPending?: number | undefined;
+    /** how long a request line may stay unfinished (default 30 s) */
+    partialLineMs?: number | undefined;
+    /** where the broker reports its own failures (default stderr) */
+    log?: ((line: string) => void) | undefined;
+    /** this host's machine name on the hub (default the bridge's), and for `machine:` selectors (default the short hostname) */
+    machine?: string | undefined;
+    /** the link to the hub; without it the broker never opens a network connection */
+    bridge?: BridgeConfig | 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) */
+    env?: Record<string, string | undefined> | undefined;
+    /** the judge model client for a policy's `judge.model` (default the provider's HTTP API) */
+    judgeClient?: JudgeClientFactory | undefined;
+}
+interface Broker {
+    socket: string;
+    core: FederatedCore;
+    bridge: Bridge | null;
+    judge: JudgeGate;
+    policyFile: string;
+    stopped: Promise<void>;
+    stop(): Promise<void>;
+}
+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 };