@boxxy/server 0.0.1 → 0.1.3

package/src/config/read-trusted-issuers.ts

@@ -0,0 +1,60 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+export type IssuersAnswer =
+  | { readonly kind: 'read'; readonly issuers: readonly unknown[] }
+  | { readonly kind: 'invalid'; readonly message: string };
+
+// The trust documents, one per file of each folder, as parsed JSON in name order. The adapter
+// checks their shape; this reads them only.
+export async function readTrustedIssuers(folders: readonly string[]): Promise<IssuersAnswer> {
+  const issuers: unknown[] = [];
+
+  for (const folder of folders) {
+    const files = await readFileNames(folder);
+
+    if (files === null) {
+      return { kind: 'invalid', message: `no trusted issuers folder at ${folder}` };
+    }
+
+    for (const name of files) {
+      const file = path.join(folder, name);
+
+      const text = await Bun.file(file).text();
+
+      const json = parseJSON(text);
+
+      if (json === undefined) {
+        return { kind: 'invalid', message: `the trust document at ${file} is not JSON` };
+      }
+
+      issuers.push(json);
+    }
+  }
+
+  return { kind: 'read', issuers };
+}
+
+// null: the folder does not exist
+async function readFileNames(folder: string): Promise<string[] | null> {
+  try {
+    const entries = await readdir(folder, { withFileTypes: true });
+
+    return entries
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name)
+      .toSorted((left, right) => left.localeCompare(right));
+  } catch {
+    return null;
+  }
+}
+
+function parseJSON(text: string): unknown {
+  try {
+    const value: unknown = JSON.parse(text);
+
+    return value;
+  } catch {
+    return undefined;
+  }
+}

package/src/config/server-config-schema.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+
+const name = z.string().min(1);
+
+const address = z.strictObject({
+  hostname: name,
+
+  // 0 asks the system for a free port
+  port: z.int().min(0).max(65_535),
+});
+
+const spawnSection = z.strictObject({
+  target: name,
+  repoPaths: z.record(z.string(), name),
+});
+
+const atcSection = z.strictObject({
+  // the atc daemon's oRPC route, such as `http://127.0.0.1:7777/rpc`
+  url: z.url(),
+
+  // by worker target: the folders the agent trusts, each with its subfolders
+  trustedFolders: z.record(z.string(), z.array(name)),
+
+  // the session that gets the hold notices; with none, no notice is sent
+  noticeSession: name.optional(),
+});
+
+const folders = z.array(name).min(1);
+
+// the folders of the trust documents, one file per issuer, and the audience the tokens name
+const trustedIssuersSection = z.strictObject({ folders, audience: name });
+
+const pepysSection = z.strictObject({
+  // the receive route of boxxy's source on pepys ingest
+  ingestUrl: z.url(),
+
+  // the oRPC route of the pepys query API
+  apiUrl: z.url(),
+  environment: name,
+});
+
+// The server's configuration file, as JSON, at the path in `BOXXY_CONFIG`. It holds no secret:
+// each token comes from the environment.
+export const serverConfigSchema = z.strictObject({
+  runner: name,
+  store: z.strictObject({ file: name }),
+
+  // a git checkout, or a plain folder with no `.git`
+  rules: z.strictObject({ folder: name }),
+  api: z.strictObject({
+    // the owner's private network: `/rpc`, `/mcp` and `/healthz`, with no token
+    listen: address,
+
+    // the broker's target: `/rpc` and `/mcp/session`, with the worker token on every request
+    workerListen: address,
+  }),
+  spawn: spawnSection,
+  atc: atcSection,
+
+  // with none, every session and hook call is refused
+  trustedIssuers: trustedIssuersSection.optional(),
+
+  // with none, no fact is sent, and the two reports answer PEPYS_NOT_CONFIGURED
+  pepys: pepysSection.optional(),
+
+  // GitHub's REST root, or the broker's; with none, the hook's link answers `retry`, and no
+  // pull request watch runs
+  github: z.strictObject({ baseUrl: z.url() }).optional(),
+});
+
+export type ServerConfig = z.infer<typeof serverConfigSchema>;

package/src/create-capacity-backoff.ts

@@ -0,0 +1,18 @@
+import type { CapacityBackoff, Instant, PoolName } from '@boxxy/model';
+
+// The runner's memory of the pools that a host refused for capacity. It lives in the process: a
+// restart forgets it, and the next refusal holds the pool again. A second hold keeps the later
+// end.
+export function createCapacityBackoff(): CapacityBackoff {
+  const until = new Map<PoolName, Instant>();
+
+  return {
+    hold: (pool, end) => {
+      const held = until.get(pool);
+      const later = held !== undefined && held > end ? held : end;
+
+      until.set(pool, later);
+    },
+    listHeld: (now) => [...until].filter(([, end]) => end > now).map(([pool]) => pool),
+  };
+}

package/src/handlers/api.ts

@@ -0,0 +1,23 @@
+import { contract } from '@boxxy/contract';
+import { ORPCError, implement } from '@orpc/server';
+import { match } from 'ts-pattern';
+import { authorizeCall } from '../auth/authorize-call.ts';
+import type { ProvenCall, RequestContext } from '../types.ts';
+
+// The contract with the root middleware on every procedure, so each handler built from it runs
+// after the access check. A handler of a session or hook procedure gets the proven call.
+export const api = implement(contract)
+  .$context<RequestContext>()
+  .use(async (options) => {
+    const authorization = await authorizeCall(options.context, options.path);
+
+    const call = match(authorization)
+      .with({ kind: 'refused' }, (refused) => {
+        throw new ORPCError(refused.code);
+      })
+      .with({ kind: 'owner' }, (): ProvenCall | null => null)
+      .with({ kind: 'session' }, (session) => session.call)
+      .exhaustive();
+
+    return options.next({ context: { call } });
+  });

package/src/handlers/attempt-handlers.ts

@@ -0,0 +1,244 @@
+import {
+  bindAttemptSession,
+  closeOutAttempt,
+  linkPullRequest,
+  pickCallAttempt,
+} from '@boxxy/dispatch';
+import type { CallRef } from '@boxxy/dispatch';
+import type {
+  AttemptRow,
+  EvidenceKind,
+  ItemKindName,
+  LoadedRules,
+  StoreChange,
+} from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import type { ProvenCall, ServerDeps } from '../types.ts';
+import { api } from './api.ts';
+import { toWireJSON } from './to-wire-json.ts';
+
+const noAttempt = { kind: 'refused', reason: 'no-attempt' } as const;
+
+// The procedures of a session and its hooks. Each takes its session and caller from the root
+// middleware's proven call, never from the request; the request names only the attempt.
+export const attemptHandlers = {
+  current: api.attempt.current.handler(async (options) => {
+    const context = options.context;
+
+    if (context.call === null) {
+      return noAttempt;
+    }
+
+    const call = context.call;
+
+    const latest = await context.deps.store.read((tx) => tx.findAttemptBySession(call.session));
+
+    if (latest === null) {
+      return noAttempt;
+    }
+
+    const picked = pickCallAttempt(latest, { ...call, attempt: latest.id });
+
+    if (picked.kind === 'refused') {
+      return picked;
+    }
+
+    return readCurrent(context.deps, picked.attempt);
+  }),
+  closeOut: api.attempt.closeOut.handler((options) => {
+    const input = options.input;
+    const deps = options.context.deps;
+    const call = buildCallRef(options.context.call, input.session.attempt);
+
+    if (call === null) {
+      return noAttempt;
+    }
+
+    return closeOutAttempt({
+      store: deps.store,
+      call,
+      body: input.closeOut,
+      rules: deps.rulesState().rules,
+      now: deps.clock.now(),
+      newId: deps.newId,
+    });
+  }),
+  evidence: api.attempt.evidence.handler((options) => {
+    const input = options.input;
+    const context = options.context;
+    const call = buildCallRef(context.call, input.session.attempt);
+
+    if (call === null) {
+      return noAttempt;
+    }
+
+    return writeEvidence(context.deps, call, {
+      kind: input.kind,
+      ref: input.ref,
+      observed: input.observed ?? null,
+    });
+  }),
+  bindSession: api.attempt.bindSession.handler(async (options) => {
+    const input = options.input;
+    const context = options.context;
+    const call = buildCallRef(context.call, input.session.attempt);
+    const agentSession = brandSchemas.agentSessionId.safeParse(input.session.agentSession);
+
+    if (call === null || !agentSession.success) {
+      return { kind: 'no-attempt' } as const;
+    }
+
+    const answer = await bindAttemptSession({
+      store: context.deps.store,
+      call,
+      agentSession: agentSession.data,
+      missingSkills: input.missingSkills ?? [],
+      now: context.deps.clock.now(),
+      newId: context.deps.newId,
+    });
+
+    if (answer.kind !== 'fault') {
+      return answer;
+    }
+
+    context.deps.log.warn('an agent session is bound to another attempt', {
+      attempt: answer.attempt,
+      holder: answer.holder,
+    });
+
+    return { kind: 'fault', fault: answer.fault, holder: answer.holder } as const;
+  }),
+  recordPullRequest: api.attempt.recordPullRequest.handler((options) => {
+    const input = options.input;
+    const deps = options.context.deps;
+    const call = buildCallRef(options.context.call, input.session.attempt);
+
+    if (call === null) {
+      return noAttempt;
+    }
+
+    if (deps.forge === null) {
+      return { kind: 'retry' } as const;
+    }
+
+    return linkPullRequest({
+      store: deps.store,
+      forge: deps.forge,
+      rules: deps.rulesState().rules,
+      call,
+      url: input.url,
+      now: deps.clock.now(),
+      newId: deps.newId,
+    });
+  }),
+};
+
+async function readCurrent(deps: ServerDeps, attempt: AttemptRow) {
+  const rules = deps.rulesState().rules;
+  const now = deps.clock.now();
+
+  const [item, notes] = await deps.store.read((tx) =>
+    Promise.all([tx.readItem(attempt.item, now, rules), tx.listItemNotes(attempt.item)]),
+  );
+
+  const phase = rules.phases.get(attempt.phase);
+
+  if (item === null || phase === undefined) {
+    return noAttempt;
+  }
+
+  return {
+    kind: 'attempt' as const,
+    attempt,
+    item,
+    input: toWireJSON(attempt.input),
+    closeOut: {
+      phase: attempt.phase,
+      schema: toWireJSON(phase.closeOut.jsonSchema),
+      outcomes: [...phase.outcomes],
+    },
+    skills: { pin: rules.skills, names: collectSkillNames(rules, item.kind, attempt) },
+    notes: notes.map((note) => ({ seq: note.seq, text: note.text, at: note.at })),
+  };
+}
+
+function collectSkillNames(rules: LoadedRules, kind: ItemKindName, attempt: AttemptRow): string[] {
+  const recipes = rules.kinds.get(kind)?.recipes ?? {};
+
+  const name =
+    (attempt.mode === 'attended' ? recipes[`${attempt.phase}/attended`] : undefined) ??
+    recipes[attempt.phase];
+
+  return name === undefined ? [] : [...(rules.recipes.get(name)?.recipe.skills ?? [])];
+}
+
+// an attempt ID that no store holds, so `pickCallAttempt` answers `not-current`
+const missingAttemptId = '00000000-0000-7000-8000-000000000000';
+
+// The attempt ID from the request, with the session and the caller that the middleware proved.
+// A string that is no attempt ID names no attempt of the session.
+function buildCallRef(proven: ProvenCall | null, attempt: string): CallRef | null {
+  const parsed = brandSchemas.attemptId.safeParse(attempt);
+
+  if (proven === null) {
+    return null;
+  }
+
+  return {
+    attempt: parsed.success ? parsed.data : brandSchemas.attemptId.parse(missingAttemptId),
+    session: proven.session,
+    caller: proven.caller,
+  };
+}
+
+interface EvidenceDraft {
+  readonly kind: Exclude<EvidenceKind, 'pull_request' | 'commit'>;
+  readonly ref: string;
+  readonly observed: string | null;
+}
+
+// Writes under the attempt's lease, so the evidence of a settled attempt is refused.
+function writeEvidence(deps: ServerDeps, call: CallRef, draft: EvidenceDraft) {
+  return deps.store.exclusive(async (tx) => {
+    const latest = await tx.findAttemptBySession(call.session);
+
+    const picked = pickCallAttempt(latest, call);
+
+    if (picked.kind === 'refused') {
+      return picked;
+    }
+
+    const attempt = picked.attempt;
+    const factId = brandSchemas.factId.parse(deps.newId());
+    const at = deps.clock.now();
+
+    const result = await tx.applyChange({
+      at,
+      under: buildUnder(attempt),
+      writes: [
+        {
+          op: 'insert',
+          table: 'evidence',
+          row: { factId, attempt: attempt.id, ...draft, source: 'agent', at },
+        },
+      ],
+      facts: [
+        {
+          id: factId,
+          type: 'boxxy.evidence.recorded',
+          entity: `boxxy:item:${attempt.item}`,
+          actor: `boxxy:attempt:${attempt.id}`,
+          payload: { attempt: attempt.id, ...draft },
+        },
+      ],
+    });
+
+    return result.kind === 'applied'
+      ? ({ kind: 'recorded', factId } as const)
+      : ({ kind: 'refused', reason: 'not-current' } as const);
+  });
+}
+
+function buildUnder(attempt: AttemptRow): NonNullable<StoreChange['under']> {
+  return { item: attempt.item, phase: attempt.phase, gen: attempt.leaseGen };
+}

package/src/handlers/build-owner-fact.ts

@@ -0,0 +1,20 @@
+import type { ItemId, NewFact, WorkFacts } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import type { ServerDeps } from '../types.ts';
+
+// A fact of the owner's path. Its entity is the item it names (the entity rule of the fact
+// catalog).
+export function buildOwnerFact<Type extends keyof WorkFacts>(
+  deps: ServerDeps,
+  item: ItemId,
+  type: Type,
+  payload: WorkFacts[Type],
+): NewFact<Type> {
+  return {
+    id: brandSchemas.factId.parse(deps.newId()),
+    type,
+    entity: `boxxy:item:${item}`,
+    actor: 'boxxy:owner:local',
+    payload,
+  };
+}