@scp-dev/broker 0.1.2 → 0.1.4

package/src/server.ts

@@ -26,11 +26,12 @@ import {
   stripControl,
 } from "@scp-dev/core"
 import { FederatedCore } from "@scp-dev/hub"
-import { type Bridge, type BridgeConfig, remoteSend, startBridge } from "./bridge"
+import { type Bridge, type BridgeConfig, type BridgeHooks, remoteSend, startBridge } from "./bridge"
 import { type Deliver, type JudgeClientFactory, JudgeGate } from "./judge-gate"
 import { releaseBrokerLock, takeBrokerLock } from "./lock"
 import { encodeLine, LineReader, LineWriter, MAX_LINE } from "./ndjson"
 import { accountHome, accountHomeVerified, policyPath as defaultPolicyPath, privateDir, shortHostname, socketPath } from "./paths"
+import { writeSessionMarker } from "./sessions"
 import { Conn } from "./socket"
 import { type Database, openDatabase } from "./sqlite"
 
@@ -59,6 +60,8 @@ export 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) */
@@ -67,6 +70,15 @@ export interface BrokerOptions {
   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 */
+export interface LinkContext {
+  core: FederatedCore
+  hooks: BridgeHooks
+  send: Deliver
+}
+
+export type LinkFactory = (context: LinkContext) => Bridge
+
 export interface Broker {
   socket: string
   core: FederatedCore
@@ -87,6 +99,8 @@ interface Connection {
   tty?: boolean
   /** the connection holds the human inbox */
   human?: boolean
+  /** a human hello bound to the agent of this shell's lineage said a terminal was attached: the human at that agent's shell */
+  terminal?: boolean
   /**
    * the lineage endpoint of an observer, or of a hello bound to it: the connection sees and acts with that endpoint's view,
    * never widening unless `own`, and never counts as connected
@@ -134,7 +148,7 @@ const CHANGES_SCOPE = new Set(["rules_set", "rules_widen", "rules_lift", "group"
 const ASK_RECHECK_MS = 1000
 /** how often a waiting stop rechecks its workers, since a worker's exit or lapse wakes no one */
 const STOP_RECHECK_MS = 1000
-const TRANSIENT_METHODS = new Set(["event", "status", "whoami", "inject", "injected", "peek_turn", "stop_wait", "prompted"])
+const TRANSIENT_METHODS = new Set(["event", "status", "whoami", "inject", "injected", "peek_turn", "stop_wait", "prompted", "title_infer"])
 const GRANT_UNBOUND = `a spawn-env grant binds only a new harness process: run the harness with it, or name the child (${CLI_NAME} spawn-env --name / --as)`
 
 /** the workers' messages and handbacks a stop's push would show, and those of theirs left unread past it */
@@ -260,6 +274,7 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
   const known = new Map<string, Presence>()
   for (const view of localViews()) known.set(view.id, view.presence)
   const presenceTimer = setInterval(() => {
+    core.endExited()
     const live = new Set<string>()
     for (const view of localViews()) {
       live.add(view.id)
@@ -267,21 +282,17 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     }
     for (const id of known.keys()) if (!live.has(id)) known.delete(id)
   }, options.presenceEveryMs ?? PRESENCE_MS)
-  if (options.bridge) {
-    bridge = startBridge({
-      ...options.bridge,
-      core,
-      onRemote: {
-        wake,
-        fleet: notifyFleet,
-        policyError: () => {
-          loadPolicy()
-          return policyError
-        },
-        log,
-      },
-    })
+  const remoteHooks: BridgeHooks = {
+    wake,
+    fleet: notifyFleet,
+    policyError: () => {
+      loadPolicy()
+      return policyError
+    },
+    log,
   }
+  if (options.bridge) bridge = startBridge({ ...options.bridge, core, onRemote: remoteHooks })
+  else if (options.link) bridge = options.link({ core, hooks: remoteHooks, send: (from, params, origin) => judge.send(from, params, origin, deliver) })
 
   /** links the bridge again with the credential on disk; a configuration this broker cannot take without a restart stops it */
   async function relink(): Promise<object> {
@@ -383,6 +394,22 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
     bridge?.changed(view.id)
   }
 
+  /** after a join, rename or leave: the session's marker, the fleet and the hub's mirror learn it; `was` is the handle before */
+  function membership(view: EndpointView, session: string | null, joined: boolean, was?: string) {
+    const handle = view.address.slice(view.address.lastIndexOf("/") + 1)
+    if (session && !session.startsWith("sub:")) {
+      try {
+        writeSessionMarker(dir, session, { joined, handle })
+      } catch (error) {
+        log(`relay broker: the session marker was not written: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+    known.set(view.id, view.presence)
+    notifyFleet({ type: "presence", endpoint: view.address, presence: view.presence, harness: view.harness, labels: view.labels })
+    if (was !== undefined && was !== handle) bridge?.renamed(view.id, was)
+    else bridge?.changed(view.id)
+  }
+
   function notifyFleet(event: Record<string, unknown>) {
     const at = new Date((options.now ?? Date.now)()).toISOString()
     let line: Uint8Array | undefined
@@ -677,13 +704,27 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
         if (params.human === true || params.observe === true || params.resume !== undefined) {
           throw new RelayError("invalid_params", "a hook connection claims an agent endpoint: transient does not go with human, observe or resume")
         }
-        const before = new Map(core.list({ all: true }).map((view) => [view.id, view.presence]))
-        const { endpoint, subagent, created } = core.claim((params.claim ?? {}) as Claim, { transient: true })
+        const join = params.join
+        if (join !== undefined && (typeof join !== "object" || join === null || Array.isArray(join)))
+          throw new RelayError("invalid_params", "join is {handle?, under?}")
+        const under = (join as { under?: unknown } | undefined)?.under
+        const before = new Map(core.list({ all: true }).map((view) => [view.id, view]))
+        const { endpoint, subagent, created } =
+          join === undefined
+            ? core.claim((params.claim ?? {}) as Claim, { transient: true })
+            : {
+                endpoint: core.joinSession((params.claim ?? {}) as Claim, (join as { handle?: unknown }).handle, under),
+                subagent: undefined,
+                created: undefined,
+              }
         s.data.endpoint = endpoint.id
         s.data.transient = true
         const key = (params.claim as Claim | undefined)?.process
         if (typeof key === "string") s.data.process = key
-        if ((before.get(endpoint.id) ?? "offline") !== endpoint.presence) presenceChanged(endpoint)
+        const was = before.get(endpoint.id)?.address
+        if (join !== undefined) membership(endpoint, core.sessionOf(endpoint.id), true, was?.slice(was.lastIndexOf("/") + 1))
+        if (under !== undefined && before.get(endpoint.id)?.parent !== endpoint.parent) bridge?.resync()
+        else if ((before.get(endpoint.id)?.presence ?? "offline") !== endpoint.presence) presenceChanged(endpoint)
         return {
           endpoint,
           ...(subagent ? { subagent, ...(created ? { created } : {}) } : {}),
@@ -715,7 +756,10 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
       const claim = params.claim as Claim | undefined
       if (params.human === true && params.resume === undefined && params.lineage !== undefined) {
         const placed = core.placeLineage(params.lineage)
-        if (placed) return bindLineage(s, placed, params)
+        if (placed) {
+          s.data.terminal = params.tty === true
+          return bindLineage(s, placed, params)
+        }
       } else if (params.human !== true && params.resume === undefined && claim?.process === undefined && typeof claim?.handle === "string") {
         const placed = claim.lineage === undefined ? null : core.placeLineage(claim.lineage, claim.handle)
         if (placed && (claim.grant === undefined || core.grantBinds(claim.grant, placed))) {
@@ -822,6 +866,37 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
         bridge?.changed(me)
         return view
       }
+      case "title_infer": {
+        const changed = core.inferTitle(me, params, hookOf(s))
+        if (changed) bridge?.changed(me)
+        return { changed }
+      }
+      case "rename": {
+        const renamed = core.rename(actorOf(s), { ...(params.endpoint !== undefined ? { endpoint: params.endpoint } : {}), handle: params.handle })
+        membership(renamed.endpoint, renamed.session, true, renamed.from)
+        return renamed.endpoint
+      }
+      case "adopt": {
+        const actor = actorOf(s)
+        const adopted = core.adopt(
+          actor,
+          { endpoint: params.endpoint, ...(params.parent !== undefined ? { parent: params.parent } : {}) },
+          { tty: actor.kind === "endpoint" && s.data.terminal === true },
+        )
+        bridge?.resync()
+        return adopted
+      }
+      case "unlink": {
+        const unlinked = core.unlink(actorOf(s), params.endpoint !== undefined ? { endpoint: params.endpoint } : {})
+        bridge?.resync()
+        return unlinked
+      }
+      case "leave": {
+        const left = core.leaveSession(actorOf(s), params.endpoint !== undefined ? { endpoint: params.endpoint } : {})
+        for (const c of connections) if (c.data.endpoint === left.endpoint.id && !c.data.transient && !c.data.lineage && c !== s) c.end()
+        membership(left.endpoint, left.session, false)
+        return left.endpoint
+      }
       case "status": {
         core.status(me, params.state, params.note)
         const view = core.whoami(me)
@@ -837,14 +912,25 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
         if ((known.get(me) ?? "offline") !== after.presence) presenceChanged(after)
         return row
       }
-      case "inject":
-        return core.inject(me, {
+      case "inject": {
+        const waitMs = waitSeconds(params.wait_s)
+        const options = {
           stop: params.stop === true,
           count: params.count === true,
           holdUnread: params.hold_unread === true,
           directives: params.directives === true,
+          wake: waitMs > 0 && params.stop !== true && params.count !== true,
           ...hookOf(s),
-        })
+        }
+        const deadline = Date.now() + (options.wake ? waitMs : 0)
+        let result = core.inject(me, options)
+        while (!result.offered.length && !s.data.closed && Date.now() < deadline) {
+          await waitFor(me, deadline - Date.now(), s)
+          if (closing) throw new RelayError("unauthorized", "the relay broker is stopping")
+          result = core.inject(me, options)
+        }
+        return result
+      }
       case "stop_wait": {
         const waitMs = waitSeconds(params.wait_s)
         const deadline = Date.now() + waitMs
@@ -863,7 +949,8 @@ export async function startBroker(options: BrokerOptions): Promise<Broker> {
       case "prompted": {
         const prompted = core.prompted(me, hookOf(s))
         if (prompted) wake(me)
-        return { prompted }
+        const tldr = prompted && typeof params.tldr_every === "number" && core.tldrDue(me, params.tldr_every)
+        return { prompted, ...(tldr ? { tldr } : {}) }
       }
       case "injected":
         return {

package/src/sessions.ts

@@ -0,0 +1,39 @@
+import { createHash, randomUUID } from "node:crypto"
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+/**
+ * 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.
+ */
+export interface SessionMarker {
+  joined: boolean
+  handle?: string
+}
+
+function markerPath(dir: string, session: string): string {
+  return join(dir, "sessions", `${createHash("sha256").update(session).digest("hex").slice(0, 32)}.json`)
+}
+
+export function readSessionMarker(dir: string, session: string): SessionMarker | undefined {
+  try {
+    const value = JSON.parse(readFileSync(markerPath(dir, session), "utf8")) as Partial<SessionMarker>
+    if (typeof value?.joined !== "boolean") return undefined
+    return { joined: value.joined, ...(typeof value.handle === "string" ? { handle: value.handle } : {}) }
+  } catch {
+    return undefined
+  }
+}
+
+export function writeSessionMarker(dir: string, session: string, marker: SessionMarker): void {
+  const path = markerPath(dir, session)
+  mkdirSync(join(dir, "sessions"), { recursive: true, mode: 0o700 })
+  const temp = `${path}.${randomUUID()}.tmp`
+  try {
+    writeFileSync(temp, JSON.stringify(marker), { mode: 0o600 })
+    renameSync(temp, path)
+  } finally {
+    rmSync(temp, { force: true })
+  }
+}

package/src/testing.ts

@@ -7,6 +7,8 @@ export interface FakeToken {
   tokenId: string
   /** the account handle the token acts as */
   user: string
+  /** the org member the token belongs to; none is the personal account's owner */
+  actor?: string
 }
 
 export interface FakeHubServer {
@@ -88,7 +90,14 @@ export function startFakeHubServer(options: {
     if (!token) return null
     return {
       account: token.user,
-      grant: { tokenId: token.tokenId, userId: `usr_${token.user}`, actorId: null, expiresAt: Date.now() + 3_600_000, scoped: false, role: null },
+      grant: {
+        tokenId: token.tokenId,
+        userId: `usr_${token.user}`,
+        actorId: token.actor ?? null,
+        expiresAt: Date.now() + 3_600_000,
+        scoped: false,
+        role: token.actor ? "member" : null,
+      },
     }
   }