@boxxy/pepys 0.0.1 → 0.1.4

package/src/test-utils/create-ingest-stand-in.ts

@@ -0,0 +1,56 @@
+import { isDeliveryAuthentic } from '@pepys/kit';
+import { boxxySource } from '../boxxy-source.ts';
+
+export interface IngestStandIn {
+  // the receive route of the boxxy source, for the sender's `fetch` option
+  readonly handleRequest: (request: Request) => Promise<Response>;
+
+  // the events of the stored facts, in arrival order, a copy counted once
+  readStored: () => Promise<readonly string[]>;
+}
+
+// Ingest's receive route in memory, with the kit's own signature check and batch read. The kit
+// exports no route handler of ingest, so the answers are written here: 401, the read's 400 or
+// 422, or the batch stored whole with a copy of an event dropped.
+export function createIngestStandIn(secret: string): IngestStandIn {
+  const path = boxxySource.live;
+
+  if (path?.kind !== 'receive') {
+    throw new Error('the boxxy source has no receive path');
+  }
+
+  const stored: string[] = [];
+
+  return {
+    handleRequest: async (request) => {
+      const buffer = await request.arrayBuffer();
+
+      const body = new Uint8Array(buffer);
+
+      if (!isDeliveryAuthentic(path.check, secret, request.headers, body)) {
+        return Response.json({ error: 'the signature does not match' }, { status: 401 });
+      }
+
+      const received = path.read(
+        { headers: request.headers, body },
+        { name: boxxySource.name, families: boxxySource.families },
+      );
+
+      if (received.kind === 'refused') {
+        return Response.json({ error: received.reason }, { status: received.status });
+      }
+
+      if (received.kind === 'ignored') {
+        return Response.json({ status: 'ignored' }, { status: 202 });
+      }
+
+      const events = received.batch.facts.map((pending) => pending.fact.id);
+
+      stored.push(...events.filter((event) => !stored.includes(event)));
+
+      return Response.json({ status: 'stored', stored: events.length });
+    },
+    readStored: () =>
+      Promise.resolve(stored.map((event) => event.replace(`event:${boxxySource.name}:`, ''))),
+  };
+}

package/src/test-utils/create-query-stand-in.ts

@@ -0,0 +1,51 @@
+import type { CostToLand } from '@boxxy/model';
+import { buildCostToLand } from '../queries/build-cost-to-land.ts';
+import { buildStageTime } from '../queries/build-stage-time.ts';
+import type { UncheckedQueryClient } from '../types.ts';
+
+export interface QueryStandIn {
+  readonly client: UncheckedQueryClient;
+
+  // the cost the query answers for the item's entity ID
+  setCost: (item: string, cost: CostToLand) => void;
+
+  // every later call fails as a refused connection does
+  takeDown: () => void;
+}
+
+// The two queries in memory. An item with no cost set answers what each query's builder gives for
+// an item with no row.
+export function createQueryStandIn(): QueryStandIn {
+  const costs = new Map<string, CostToLand>();
+
+  let isDown = false;
+
+  const answer = (value: () => unknown): Promise<unknown> =>
+    isDown ? Promise.reject(new Error('connect ECONNREFUSED')) : Promise.resolve(value());
+
+  return {
+    client: {
+      boxxy_cost_to_land: (input) =>
+        answer(
+          () =>
+            costs.get(input.item) ??
+            buildCostToLand({
+              item: input.item,
+              attempts: [],
+              bindings: [],
+              requests: [],
+              turns: [],
+              pullRequests: [],
+            }),
+        ),
+      boxxy_stage_time: (input) =>
+        answer(() => buildStageTime({ ...input, attempts: [], deliveries: [] })),
+    },
+    setCost: (item, cost) => {
+      costs.set(item, cost);
+    },
+    takeDown: () => {
+      isDown = true;
+    },
+  };
+}

package/src/test-utils/create-test-pepys.ts

@@ -0,0 +1,228 @@
+import { isDeliveryAuthentic } from '@pepys/kit';
+import type { DeliveryCheck, FactEnvelope } from '@pepys/kit';
+import { createTestStore } from '@pepys/testing';
+import { z } from 'zod';
+import { boxxySource } from '../boxxy-source.ts';
+import { buildBoxxyPlugin } from '../build-boxxy-plugin.ts';
+import { buildCostToLandQuery } from '../queries/build-cost-to-land-query.ts';
+import { buildStageTimeQuery } from '../queries/build-stage-time-query.ts';
+import type { DeliveryReads, ForeignReads } from '../queries/types.ts';
+import { isOutgoingFact } from '../sink/is-outgoing-fact.ts';
+import type { UncheckedQueryClient } from '../types.ts';
+import { buildForeignStandIn } from './build-foreign-stand-in.ts';
+import { toEntityID } from './to-entity-id.ts';
+
+export interface TestPepysOptions {
+  // the value of `PEPYS_BOXXY_SIGNING_SECRET`, which the fact batch route checks
+  readonly boxxySecret: string;
+
+  // the value of `PEPYS_GITHUB_WEBHOOK_SECRET`, which the webhook route checks
+  readonly webhookSecret: string;
+}
+
+// One model request of an agent session, with the proven sender of its record.
+export interface TelemetryRequest {
+  readonly id: string;
+
+  // the atc session ID that the agent copies onto its records
+  readonly session: string;
+  readonly origin: { readonly issuer: string; readonly subject: string };
+  readonly model: string;
+  readonly costUSD: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+
+  // ISO 8601
+  readonly at: string;
+}
+
+export interface TestPepys extends AsyncDisposable {
+  // ingest's two routes that boxxy's journey reaches: the boxxy fact batch route and the GitHub
+  // webhook route; any other path answers 404
+  readonly handleRequest: (request: Request) => Promise<Response>;
+
+  // the two queries of the boxxy plug-in, as the pepys API answers them
+  readonly client: UncheckedQueryClient;
+
+  // the rows that the telemetry route would write for these records
+  readonly writeTelemetry: (requests: readonly TelemetryRequest[]) => Promise<void>;
+}
+
+const webhookRoute = '/webhook/github';
+
+const webhookCheck: DeliveryCheck = {
+  kind: 'hmac-sha256',
+  header: 'x-hub-signature-256',
+  secretEnv: 'PEPYS_GITHUB_WEBHOOK_SECRET',
+};
+
+// GitHub's `pull_request` event, as far as the merge time goes
+const pullRequestEventSchema = z.object({
+  action: z.string(),
+  pull_request: z.object({ id: z.number().int(), merged_at: z.string().nullable() }),
+});
+
+// The boxxy plug-in on the kit's test store, behind the kit's own signature check and batch read.
+// The GitHub and telemetry plug-ins are stand-ins: the webhook writes the pull request row, and
+// the delivery read knows merges only, no release and no deploy.
+export async function createTestPepys(options: TestPepysOptions): Promise<TestPepys> {
+  const standIn = buildForeignStandIn();
+
+  const merges = new Map<string, string | null>();
+
+  const foreign: ForeignReads = { ...standIn.foreign, delivery: buildDeliveryReads(merges) };
+  const plugin = buildBoxxyPlugin(foreign);
+
+  const store = await createTestStore({ plugins: [plugin, ...standIn.plugins] });
+
+  const costQuery = buildCostToLandQuery(foreign);
+  const stageQuery = buildStageTimeQuery(foreign.delivery);
+  const path = boxxySource.live;
+
+  if (path?.kind !== 'receive') {
+    throw new Error('the boxxy source has no receive path');
+  }
+
+  const stored = new Set<string>();
+
+  const receiveFacts = async (request: Request): Promise<Response> => {
+    const buffer = await request.arrayBuffer();
+
+    const body = new Uint8Array(buffer);
+
+    if (!isDeliveryAuthentic(path.check, options.boxxySecret, request.headers, body)) {
+      return Response.json({ error: 'the signature does not match' }, { status: 401 });
+    }
+
+    const received = path.read(
+      { headers: request.headers, body },
+      { name: boxxySource.name, families: boxxySource.families },
+    );
+
+    if (received.kind === 'refused') {
+      return Response.json({ error: received.reason }, { status: received.status });
+    }
+
+    if (received.kind === 'ignored') {
+      return Response.json({ status: 'ignored' }, { status: 202 });
+    }
+
+    const facts = received.batch.facts
+      .filter((pending) => !stored.has(pending.fact.id))
+      .map((pending) => toOutgoingFact(pending.fact))
+      .filter((fact) => isOutgoingFact(fact));
+
+    await store.apply(boxxySource, facts);
+
+    for (const pending of received.batch.facts) {
+      stored.add(pending.fact.id);
+    }
+
+    return Response.json({ status: 'stored', stored: received.batch.facts.length });
+  };
+
+  const receiveWebhook = async (request: Request): Promise<Response> => {
+    const buffer = await request.arrayBuffer();
+
+    const body = new Uint8Array(buffer);
+
+    if (!isDeliveryAuthentic(webhookCheck, options.webhookSecret, request.headers, body)) {
+      return Response.json({ error: 'the signature does not match' }, { status: 401 });
+    }
+
+    const raw: unknown = JSON.parse(new TextDecoder().decode(body));
+    const event = pullRequestEventSchema.safeParse(raw);
+
+    if (request.headers.get('x-github-event') !== 'pull_request' || !event.success) {
+      return Response.json({ status: 'ignored' }, { status: 202 });
+    }
+
+    const id = `github:pull_request:${event.data.pull_request.id}`;
+
+    merges.set(id, event.data.pull_request.merged_at);
+
+    await store.writeRows(standIn.consumers.githubPullRequest, 'github_pull_request', [
+      { id: toEntityID(id), merged_at: event.data.pull_request.merged_at },
+    ]);
+
+    return Response.json({ status: 'stored', stored: 1 });
+  };
+
+  return {
+    handleRequest: (request) => {
+      const route = new URL(request.url).pathname;
+
+      if (route === path.route) {
+        return receiveFacts(request);
+      }
+
+      return route === webhookRoute
+        ? receiveWebhook(request)
+        : Promise.resolve(Response.json({ error: 'no such route' }, { status: 404 }));
+    },
+    client: {
+      boxxy_cost_to_land: (input) => store.query(costQuery, input),
+      boxxy_stage_time: (input) => store.query(stageQuery, input),
+    },
+    writeTelemetry: (requests) =>
+      store.writeRows(
+        standIn.consumers.telemetryModelRequest,
+        'telemetry_model_request',
+        requests.map((request) => ({
+          id: toEntityID(`telemetry:model_request:${request.id}`),
+          session_id: toEntityID(`telemetry:session:${request.session}`),
+          origin_issuer: request.origin.issuer,
+          origin_subject: request.origin.subject,
+          product: 'claude_code',
+          model: request.model,
+          cost_basis: 'reported',
+          cost_usd: request.costUSD,
+          input_tokens: request.inputTokens,
+          cache_read_tokens: 0,
+          cache_creation_tokens: 0,
+          output_tokens: request.outputTokens,
+          at: request.at,
+        })),
+      ),
+    [Symbol.asyncDispose]: () => store[Symbol.asyncDispose](),
+  };
+}
+
+// The merge of each pull request that an attempt of the item produced, read through the
+// `produced` links as the GitHub plug-in's delivery module reads it.
+function buildDeliveryReads(merges: ReadonlyMap<string, string | null>): DeliveryReads {
+  return {
+    consumers: [],
+    readDeliveries: async (db, input) => {
+      const produced = await db
+        .selectFrom('link_effective as produced')
+        .innerJoin('boxxy_attempt as attempt', 'attempt.id', 'produced.from_id')
+        .where('produced.type', '=', 'produced')
+        .where('attempt.item_id', '=', input.item)
+        .select('produced.to_id as id')
+        .distinct()
+        .orderBy('produced.to_id')
+        .execute();
+
+      return produced.map((row) => ({
+        pullRequest: row.id,
+        mergedAt: merges.get(row.id) ?? null,
+        release: null,
+        deploy: null,
+      }));
+    },
+  };
+}
+
+// The fact of a batch that ingest built the envelope from; the event is the envelope's ID less
+// the source's prefix.
+function toOutgoingFact(fact: FactEnvelope<unknown>) {
+  return {
+    type: fact.type,
+    event: fact.id.replace(`event:${boxxySource.name}:`, ''),
+    entity: fact.entity,
+    ...(fact.actor === undefined ? {} : { actor: fact.actor }),
+    at: fact.at,
+    payload: fact.payload,
+  };
+}

package/src/test-utils/to-entity-id.ts

@@ -0,0 +1,14 @@
+import { buildEntityID, parseEntityID } from '@pepys/kit';
+import type { EntityID } from '@pepys/kit';
+
+// A row that a test writes takes its entity ID columns as the kit's entity ID type.
+export function toEntityID(text: string): EntityID {
+  const parsed = parseEntityID(text);
+  const built = parsed.ok ? buildEntityID(parsed.value) : parsed;
+
+  if (!built.ok) {
+    throw new Error(`${text} is no entity ID: ${built.failure.reason}`);
+  }
+
+  return built.value;
+}

package/src/test-utils/to-scope-fact.ts

@@ -0,0 +1,92 @@
+import type { OutgoingFact } from '@pepys/kit';
+import { z } from 'zod';
+import type { boxxySource } from '../boxxy-source.ts';
+import type { WorkFact } from '../work/types.ts';
+
+const base = { id: z.string(), entity: z.string(), at: z.string() };
+const ofAttempt = { attempt: z.string() };
+const callerSchema = z.object({ issuer: z.string(), subject: z.string() }).nullable();
+
+const filedPayload = z.object({
+  kind: z.string(),
+  repo: z.string(),
+  title: z.string(),
+  fields: z.object({ designMode: z.unknown().optional() }),
+});
+
+const editedPayload = z.object({
+  title: z.unknown().optional(),
+  kind: z.unknown().optional(),
+  fields: z.unknown().optional(),
+});
+
+const closedPayload = z.object({ reason: z.string() });
+
+const claimedPayload = z.object({
+  ...ofAttempt,
+  phase: z.string(),
+  number: z.number(),
+  round: z.number(),
+  mode: z.string(),
+  pool: z.string(),
+  recipeHash: z.string(),
+  rulesVersion: z.string(),
+});
+
+const sessionPayload = z.object({ ...ofAttempt, atcSession: z.string(), caller: callerSchema });
+
+const boundPayload = z.object({
+  ...ofAttempt,
+  atcSession: z.string(),
+  agentSession: z.string(),
+  product: z.string(),
+});
+
+const settledPayload = z.object({
+  ...ofAttempt,
+  state: z.string(),
+  outcome: z.string(),
+  failure: z.string().nullable(),
+  asleep: z.boolean(),
+});
+
+const linkedPayload = z.object({ ...ofAttempt, pullRequestId: z.string() });
+
+const sessionTypes = z.enum([
+  'boxxy.attempt.started',
+  'boxxy.attempt.reconciled',
+  'boxxy.attempt.resumed',
+]);
+
+const markPayload = z.object(ofAttempt);
+
+const markTypes = z.enum([
+  'boxxy.attempt.slept',
+  'boxxy.attempt.woken',
+  'boxxy.attempt.closed_out',
+]);
+
+const scopeFactSchema: z.ZodType<WorkFact> = z.discriminatedUnion('type', [
+  z.object({ ...base, type: z.literal('boxxy.item.filed'), payload: filedPayload }),
+  z.object({ ...base, type: z.literal('boxxy.item.edited'), payload: editedPayload }),
+  z.object({ ...base, type: z.literal('boxxy.item.closed'), payload: closedPayload }),
+  z.object({ ...base, type: z.literal('boxxy.attempt.claimed'), payload: claimedPayload }),
+  z.object({ ...base, type: sessionTypes, payload: sessionPayload }),
+  z.object({ ...base, type: z.literal('boxxy.attempt.session_bound'), payload: boundPayload }),
+  z.object({ ...base, type: markTypes, payload: markPayload }),
+  z.object({ ...base, type: z.literal('boxxy.attempt.settled'), payload: settledPayload }),
+  z.object({ ...base, type: z.literal('boxxy.pull_request.linked'), payload: linkedPayload }),
+]);
+
+// One fact of a batch as the consumer reads it from its scope, with the fact ID that ingest gives
+// it. The payload is read the way the glue's decoder reads it, so a field the fold needs and the
+// model lacks fails.
+export function toScopeFact(fact: OutgoingFact<typeof boxxySource>): WorkFact {
+  return scopeFactSchema.parse({
+    id: `event:boxxy:${fact.event}`,
+    type: fact.type,
+    entity: fact.entity,
+    at: fact.at,
+    payload: fact.payload,
+  });
+}

package/src/types.ts

@@ -0,0 +1,14 @@
+import type { PluginClient } from '@pepys/kit';
+import type { buildBoxxyPlugin } from './build-boxxy-plugin.ts';
+
+// The typed client of the plug-in's two queries on the pepys API's RPC route.
+export type BoxxyQueryClient = PluginClient<ReturnType<typeof buildBoxxyPlugin>>;
+
+// The same client as the reader takes it. Its types hold only when pepys runs this package's
+// version, so the reader parses each answer. Any `BoxxyQueryClient` fits, and so does the pepys
+// API's deployment client of a deployment that holds the plug-in.
+export type UncheckedQueryClient = {
+  readonly [Query in keyof BoxxyQueryClient]: (
+    input: Parameters<BoxxyQueryClient[Query]>[0],
+  ) => Promise<unknown>;
+};

package/src/wire-fact-schemas.ts

@@ -0,0 +1,41 @@
+import { workFactSchemas } from '@boxxy/model';
+import type { FactType } from '@boxxy/model';
+import { z } from 'zod';
+
+// The sink adds the store version to every payload, and no model schema holds it, so the wire
+// schema of a type is the model's schema plus that one field. These are the `types` of the fact
+// family.
+const storeVersion = { storeVersion: z.number().int().positive() };
+
+export const wireFactSchemas = {
+  'boxxy.item.filed': workFactSchemas['boxxy.item.filed'].extend(storeVersion),
+  'boxxy.item.noted': workFactSchemas['boxxy.item.noted'].extend(storeVersion),
+  'boxxy.item.edited': workFactSchemas['boxxy.item.edited'].extend(storeVersion),
+  'boxxy.item.closed': workFactSchemas['boxxy.item.closed'].extend(storeVersion),
+  'boxxy.relation.added': workFactSchemas['boxxy.relation.added'].extend(storeVersion),
+  'boxxy.relation.removed': workFactSchemas['boxxy.relation.removed'].extend(storeVersion),
+  'boxxy.lever.recorded': workFactSchemas['boxxy.lever.recorded'].extend(storeVersion),
+  'boxxy.attempt.claimed': workFactSchemas['boxxy.attempt.claimed'].extend(storeVersion),
+  'boxxy.decision.recorded': workFactSchemas['boxxy.decision.recorded'].extend(storeVersion),
+  'boxxy.attempt.started': workFactSchemas['boxxy.attempt.started'].extend(storeVersion),
+  'boxxy.attempt.spawn_unanswered':
+    workFactSchemas['boxxy.attempt.spawn_unanswered'].extend(storeVersion),
+  'boxxy.attempt.reconciled': workFactSchemas['boxxy.attempt.reconciled'].extend(storeVersion),
+  'boxxy.attempt.session_bound':
+    workFactSchemas['boxxy.attempt.session_bound'].extend(storeVersion),
+  'boxxy.attempt.slept': workFactSchemas['boxxy.attempt.slept'].extend(storeVersion),
+  'boxxy.attempt.wake_requested':
+    workFactSchemas['boxxy.attempt.wake_requested'].extend(storeVersion),
+  'boxxy.attempt.woken': workFactSchemas['boxxy.attempt.woken'].extend(storeVersion),
+  'boxxy.attempt.resumed': workFactSchemas['boxxy.attempt.resumed'].extend(storeVersion),
+  'boxxy.attempt.closed_out': workFactSchemas['boxxy.attempt.closed_out'].extend(storeVersion),
+  'boxxy.attempt.timed_out': workFactSchemas['boxxy.attempt.timed_out'].extend(storeVersion),
+  'boxxy.attempt.turn_ended': workFactSchemas['boxxy.attempt.turn_ended'].extend(storeVersion),
+  'boxxy.attempt.settled': workFactSchemas['boxxy.attempt.settled'].extend(storeVersion),
+  'boxxy.proposal.recorded': workFactSchemas['boxxy.proposal.recorded'].extend(storeVersion),
+  'boxxy.evidence.recorded': workFactSchemas['boxxy.evidence.recorded'].extend(storeVersion),
+  'boxxy.pull_request.linked': workFactSchemas['boxxy.pull_request.linked'].extend(storeVersion),
+  'boxxy.commit.linked': workFactSchemas['boxxy.commit.linked'].extend(storeVersion),
+  'boxxy.pull_request.merged': workFactSchemas['boxxy.pull_request.merged'].extend(storeVersion),
+  'boxxy.pull_request.closed': workFactSchemas['boxxy.pull_request.closed'].extend(storeVersion),
+} satisfies Readonly<Record<FactType, z.ZodObject>>;

package/src/work/boxxy-work-consumer.ts

@@ -0,0 +1,95 @@
+import { defineConsumer, defineTable } from '@pepys/kit';
+import { workFamily } from '../boxxy-source.ts';
+import { attemptOf, produced, ranIn } from './constants.ts';
+
+// One scope per item: a fact on the stream marks its item dirty, and the entry file gets every
+// fact of the item and returns every row and link the item owns.
+export const boxxyWorkConsumer = defineConsumer({
+  name: 'boxxy_work',
+  entry: new URL('../consumers/apply-scope.ts', import.meta.url),
+  input: { mode: 'scope', scopeKind: 'boxxy:item', streams: [workFamily.stream] },
+  tables: {
+    boxxy_item: defineTable({
+      columns: {
+        id: { kind: 'entityID' },
+        kind: { kind: 'text' },
+        repo: { kind: 'text' },
+        title: { kind: 'text' },
+        design_mode: { kind: 'text', nullable: true },
+        filed_at: { kind: 'timestamp' },
+        closed_at: { kind: 'timestamp', nullable: true },
+        close_reason: { kind: 'text', nullable: true },
+        updated_at: { kind: 'timestamp' },
+      },
+      primaryKey: ['id'],
+      indexes: [],
+    }),
+    boxxy_attempt: defineTable({
+      columns: {
+        id: { kind: 'entityID' },
+        item_id: { kind: 'entityID' },
+        phase: { kind: 'text' },
+        number: { kind: 'integer' },
+        round: { kind: 'integer' },
+        mode: { kind: 'text' },
+        pool: { kind: 'text' },
+        recipe_hash: { kind: 'text' },
+        rules_version: { kind: 'text' },
+        atc_session: { kind: 'text', nullable: true },
+        state: { kind: 'text' },
+        outcome: { kind: 'text', nullable: true },
+        failure: { kind: 'text', nullable: true },
+        claimed_at: { kind: 'timestamp' },
+        started_at: { kind: 'timestamp', nullable: true },
+        closed_out_at: { kind: 'timestamp', nullable: true },
+        ended_at: { kind: 'timestamp', nullable: true },
+
+        // the stretches of sleep, `{ from, to }` with `to` null while asleep: the entry file does
+        // no date arithmetic, so the queries add them up
+        sleeps: { kind: 'json' },
+        updated_at: { kind: 'timestamp' },
+      },
+      primaryKey: ['id'],
+      indexes: [{ columns: ['item_id'] }],
+    }),
+
+    // The join table of the cost query: one row per attempt and telemetry session. `key` `atc`
+    // holds the atc session, and `agent` the agent's own session, which matches only a telemetry
+    // row that carried no atc session ID.
+    boxxy_attempt_session: defineTable({
+      columns: {
+        attempt_id: { kind: 'entityID' },
+        session_id: { kind: 'entityID' },
+        key: { kind: 'text' },
+        product: { kind: 'text', nullable: true },
+        caller_issuer: { kind: 'text', nullable: true },
+        caller_subject: { kind: 'text', nullable: true },
+        bound_at: { kind: 'timestamp' },
+      },
+      primaryKey: ['attempt_id', 'session_id'],
+      indexes: [{ columns: ['session_id'] }],
+    }),
+  },
+  entityViews: [
+    {
+      table: 'boxxy_item',
+      kind: 'boxxy:item',
+      id: 'id',
+      title: 'title',
+      url: null,
+      actor: null,
+      updatedAt: 'updated_at',
+    },
+    {
+      table: 'boxxy_attempt',
+      kind: 'boxxy:attempt',
+      id: 'id',
+      title: 'phase',
+      url: null,
+      actor: null,
+      updatedAt: 'updated_at',
+    },
+  ],
+  reads: [],
+  links: [ranIn, produced, attemptOf],
+});

package/src/work/constants.ts

@@ -0,0 +1,25 @@
+import { defineLinkType } from '@pepys/kit';
+
+// `boxxy:attempt:<attempt ID>` to `telemetry:session:<atc or agent session ID>`
+export const ranIn = defineLinkType({
+  name: 'ran_in',
+  from: ['boxxy:attempt'],
+  to: ['telemetry:session'],
+  hub: false,
+});
+
+// `boxxy:attempt:<attempt ID>` to `github:pull_request:<GitHub's own ID of the pull request>`
+export const produced = defineLinkType({
+  name: 'produced',
+  from: ['boxxy:attempt'],
+  to: ['github:pull_request'],
+  hub: false,
+});
+
+// `boxxy:attempt:<attempt ID>` to `boxxy:item:<item ID>`
+export const attemptOf = defineLinkType({
+  name: 'attempt_of',
+  from: ['boxxy:attempt'],
+  to: ['boxxy:item'],
+  hub: false,
+});