@sixb/core 0.1.21 → 0.1.22

package/src/agents/fork.ts

@@ -0,0 +1,158 @@
+import { createRuntimeArtifactAccessRule } from "../artifacts/execution"
+import { createArtifactId } from "../artifacts/ids"
+import type { Principal } from "../auth"
+import type { SixbDependencies } from "../runtime/sixb"
+import type { SixbRuntimeContext } from "../runtime/types"
+import { AgentStorageError, type AgentThreadRecord } from "../storage/agents"
+import { ArtifactStorageError } from "../storage/artifacts/errors"
+import type { ArtifactStorage, CopyArtifactInput } from "../storage/artifacts/types"
+import type { Storage } from "../storage/types"
+import { AgentRequestError } from "./errors"
+import { createAgentThreadId, createAgentThreadSandboxName } from "./ids"
+import { normalizeSandboxBinding } from "./sandbox"
+
+/**
+ * Copy a thread of the caller's, or one shared with them, into a new thread the caller owns alone.
+ *
+ * The caller has already checked that `source` is visible. A workspace binding is checked again
+ * against the project's current sandbox definition, and the fork gets a sandbox of its own.
+ */
+export async function forkAgentThread(
+  runtime: SixbRuntimeContext,
+  input: {
+    readonly source: AgentThreadRecord
+    readonly ownerPrincipal: Principal
+    readonly sandbox?: SixbDependencies["sandbox"]
+  }
+): Promise<AgentThreadRecord> {
+  const storage = runtime.storage.agents
+  if (!storage) {
+    throw new AgentRequestError("storage_unavailable", "[Sixb] Agent storage is not configured.")
+  }
+
+  const { source, sandbox } = input
+  if (source.sandboxParams !== undefined && !sandbox?.supportsPersistence) {
+    throw new AgentRequestError(
+      "sandbox_not_configured",
+      "[Sixb] Thread sandboxes require a provider with persistence support."
+    )
+  }
+
+  const id = createAgentThreadId()
+  const sandboxParams =
+    source.sandboxParams === undefined
+      ? undefined
+      : normalizeSandboxBinding(sandbox?.definition, source.sandboxParams, runtime.ontology)
+
+  try {
+    // One transaction: a fork that fails leaves no copy behind, and none copied is missing.
+    return await runtime.storage.transaction(async (tx) => {
+      const threads = tx.agents?.threads
+      if (!threads) {
+        throw new AgentRequestError(
+          "storage_unavailable",
+          "[Sixb] Agent storage is not configured."
+        )
+      }
+
+      const artifactCopies = await copySharedArtifacts(runtime, tx, {
+        sourceThreadId: source.id,
+        forkId: id,
+        owner: input.ownerPrincipal,
+      })
+
+      return threads.fork({
+        projectId: runtime.projectId,
+        sourceThreadId: source.id,
+        id,
+        ownerPrincipal: input.ownerPrincipal,
+        ...(source.title === undefined ? {} : { title: source.title }),
+        ...(sandboxParams === undefined
+          ? {}
+          : {
+              sandboxParams,
+              sandboxName: createAgentThreadSandboxName(runtime.projectId, id),
+            }),
+        ...(Object.keys(artifactCopies).length === 0 ? {} : { artifactCopies }),
+      })
+    })
+  } catch (error) {
+    if (error instanceof AgentStorageError && error.code === "thread_not_found") {
+      throw new AgentRequestError(
+        "thread_not_found",
+        `[Sixb] Agent thread '${source.id}' not found.`
+      )
+    }
+
+    throw error
+  }
+}
+
+/**
+ * The fork's own copies of the artifacts the source shares that the caller reads, by the artifact
+ * access rule: every one for a signed-in session, only its own for an access token. Each copy has
+ * every version under its number, so a copied card or an `@N` address still resolves; it reuses
+ * the files, which blob storage keeps by content, is owned by whoever forks, and is shared in the
+ * fork alone. A copy keeps its addresses: one naming another artifact still names the original.
+ * Returns each source id with its copy's.
+ */
+async function copySharedArtifacts(
+  runtime: SixbRuntimeContext,
+  tx: Storage,
+  input: {
+    readonly sourceThreadId: string
+    readonly forkId: string
+    readonly owner: Principal
+  }
+): Promise<Record<string, string>> {
+  const { projectId } = runtime
+  const artifacts = tx.artifacts
+  if (!artifacts) {
+    const shared = await runtime.storage.artifacts?.list({
+      projectId,
+      threadId: input.sourceThreadId,
+      limit: 1,
+    })
+    if (shared && shared.total > 0) {
+      throw new AgentRequestError(
+        "storage_unavailable",
+        "[Sixb] Forking a conversation that shares artifacts needs artifacts and Agent threads in one storage."
+      )
+    }
+    return {}
+  }
+
+  const access = createRuntimeArtifactAccessRule(runtime, tx)
+  const copies: Record<string, string> = {}
+  const { artifacts: shared } = await artifacts.list({ projectId, threadId: input.sourceThreadId })
+  for (const artifact of shared) {
+    if ((await access.accessTo(artifact)) === "none") continue
+
+    copies[artifact.id] = await createCopy(artifacts, {
+      projectId,
+      sourceId: artifact.id,
+      owner: input.owner,
+      threadId: input.forkId,
+    })
+  }
+  return copies
+}
+
+/** A copy of the artifact under a fresh id. */
+async function createCopy(
+  artifacts: ArtifactStorage,
+  input: Omit<CopyArtifactInput, "id">
+): Promise<string> {
+  for (let attempt = 1; ; attempt += 1) {
+    const id = createArtifactId()
+    try {
+      await artifacts.copy({ ...input, id })
+      return id
+    } catch (error) {
+      const collided = error instanceof ArtifactStorageError && error.code === "artifact_exists"
+      if (!collided || attempt === COPY_ATTEMPTS) throw error
+    }
+  }
+}
+
+const COPY_ATTEMPTS = 3

package/src/agents/ids.ts

@@ -24,12 +24,19 @@ export function createAgentRunId(): string {
 
 /** One stable child identity per parent-selected spawn key. */
 export function createSubagentRunId(parentRunId: string, spawnKey: string): string {
-  const digest = createHash("sha256")
-    .update(parentRunId)
-    .update("\0")
-    .update(spawnKey)
-    .digest("hex")
-  return `agt_run_child_${digest}`
+  return `agt_run_child_${spawnDigest(parentRunId, spawnKey)}`
+}
+
+/**
+ * The thread a child works in, named after the turn that spawned it and its key. It shares its
+ * first run's digest: migration `subagent-threads` names the threads of earlier children so.
+ */
+export function createSubagentThreadId(spawningRunId: string, spawnKey: string): string {
+  return `agt_thr_child_${spawnDigest(spawningRunId, spawnKey)}`
+}
+
+function spawnDigest(runId: string, spawnKey: string): string {
+  return createHash("sha256").update(runId).update("\0").update(spawnKey).digest("hex")
 }
 
 /** Stable execution identity paired with a deterministic child run. */
@@ -46,6 +53,11 @@ export function agentContextCheckpointId(runId: string): string {
   return `agt_ctx_${runId}`
 }
 
+/** A checkpoint copied into a fork; the source's checkpoint keeps its run-derived id. */
+export function createCopiedAgentContextCheckpointId(): string {
+  return `agt_ctx_copy_${randomUUID()}`
+}
+
 /** A queue delivery's fencing token for writes to an `agent_runs` record. */
 export function createAgentRunExecutionToken(): string {
   return `agt_exec_${randomUUID()}`

package/src/agents/index.ts

@@ -16,9 +16,34 @@ export {
   AGENT_API_GATEWAY_PREFIX,
   AGENT_API_ROUTES,
   createAgentApiGatewayCapability,
+  findAgentApiRoute,
   isAllowedAgentApiRequest,
   isValidAgentApiGatewayCapability,
 } from "./api-gateway"
+export type { AgentApprovalResume } from "./approval-continuation"
+export { resumeDecidedAgentTurn } from "./approval-continuation"
+export { getAgentApprovalExecutor } from "./approval-executor"
+export type {
+  AgentApprovalCallerRun,
+  AgentApprovalHold,
+  AgentChildApprovalAwaiting,
+} from "./approvals"
+export {
+  AGENT_APPROVAL_EXECUTION_LEASE_MS,
+  agentApprovalCallers,
+  agentRunApprovalMode,
+  announceAgentApprovals,
+  approvalCallSummary,
+  hasActiveChildren,
+  holdAgentApprovalCall,
+  isAwaitingApprovalRun,
+  isPausedSubagentRun,
+  listChildApprovalsAwaiting,
+  listTurnApprovals,
+  stopAgentTurn,
+  turnPausesOnHeldCalls,
+  turnResumeReadiness,
+} from "./approvals"
 export type { AgentExecutionAuthorization, AgentExecutionIdentity } from "./authority"
 export {
   agentServiceAccountId,
@@ -26,8 +51,11 @@ export {
   resolveAgentExecutionAuthorization,
   resolveAgentPropertyClearance,
   resolveInheritedAgentExecutionAuthorization,
+  userCanRunAgent,
 } from "./authority"
 export { defineAgentTool } from "./builders"
+export type { AgentChildQuestion } from "./child-question"
+export { deferredChildQuestion, isAwaitingAnswerRun } from "./child-question"
 export type {
   AgentContextEntryInput,
   AgentContextInput,
@@ -88,11 +116,16 @@ export {
   createAgentThreadSandboxName,
   createSubagentExecutionId,
   createSubagentRunId,
+  createSubagentThreadId,
 } from "./ids"
 export {
   AGENT_MESSAGE_CONTENT_VERSION,
+  type AgentApprovalCaller,
+  type AgentApprovalCallSummary,
+  type AgentApprovalOutcomePart,
   type AgentContinuationPart,
   type AgentFilePart,
+  type AgentMailPart,
   type AgentMessage,
   type AgentMessagePart,
   type AgentMessagePartType,
@@ -106,6 +139,7 @@ export {
 } from "./message"
 export type {
   ModelLoopResult,
+  PausableModelLoopResult,
   PrepareModelStepInput,
   PrepareModelStepResult,
   RunModelLoopInput,
@@ -119,6 +153,13 @@ export {
   requestAgentRun,
   retryAgentRun,
 } from "./request"
+export type {
+  AgentRunExecutionScope,
+  AgentRunScopeAuthority,
+  AgentRunScopeErrorCode,
+  AgentRunScopeHost,
+} from "./run-scope"
+export { AgentRunScopeError, resolveAgentRunExecutionScope } from "./run-scope"
 export type {
   AgentDefinitions,
   AgentDefinitionsInput,
@@ -128,11 +169,13 @@ export type {
 } from "./skills"
 export type {
   AgentCompactionFailureCode,
+  AgentMail,
   AgentRunControlStreamId,
   AgentRunFailure,
   AgentRunFinishedEvent,
   AgentRunStreamEvent,
   AgentRunStreamId,
+  ReceivedAgentMail,
 } from "./streams/protocol"
 export {
   AGENT_COMPACTION_FAILURE_CODES,
@@ -141,15 +184,24 @@ export {
   agentRunControlStreamDefinition,
   agentRunControlStreamId,
   agentRunFinishedEvent,
+  agentRunInboxStreamId,
   agentRunStreamDefinition,
   agentRunStreamId,
   agentRunStreamIdempotencyKey,
+  agentThreadInboxStreamId,
   DEFAULT_AGENT_RUN_STREAM_RETENTION,
   isAgentRunStreamEvent,
+  isKnownAgentMailKind,
+  publishAgentMail,
   publishAgentRunCancel,
   publishAgentRunFinished,
+  readAgentMail,
+  subscribeAgentInbox,
+  subscribeAgentMail,
   subscribeAgentRunCancel,
 } from "./streams/protocol"
+export { listSubagentThreadRuns } from "./subagent-runs"
+export { assertConversationThread, conversationThreadId } from "./thread-access"
 export type {
   AgentThreadModelContextMessage,
   ProjectAgentThreadModelContextInput,
@@ -159,8 +211,10 @@ export type { AgentToolCatalog } from "./tool-catalog"
 export { isAgentToolResult } from "./tool-result"
 export type {
   AgentDescriptor,
+  AgentMemoryReference,
   AgentReasoning,
   AgentReference,
+  AgentThreadsReference,
   AgentToolAttachments,
   AgentToolContent,
   AgentToolDefinition,
@@ -182,6 +236,7 @@ export type {
   AgentUsageReference,
   InferAgentToolInput,
   InferAgentToolInputSchema,
+  InferAgentToolOutput,
 } from "./types"
 export { AGENT_REASONING_LEVELS } from "./types"
 export {

package/src/agents/memory-execution.ts

@@ -0,0 +1,186 @@
+import { type Principal, SYSTEM_PRINCIPAL } from "../auth"
+import { isRuntimeAllowed } from "../authorization"
+import { resolveRuntimeAuthorizationForProject } from "../execution/authorization"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type {
+  AgentMemoryChange,
+  AgentMemoryFile,
+  AgentMemoryStore,
+  ListAgentMemoryRevisionsResult,
+} from "../storage/agents"
+import { AgentMemoryError } from "./errors"
+import {
+  type AgentMemoryLinkWarning,
+  type AgentMemoryRepoName,
+  agentMemoryRepoId,
+  applyAgentMemoryChanges,
+  findBrokenAgentMemoryLinks,
+} from "./memory"
+
+/** A memory repo as the caller sees it. */
+export interface AgentMemoryRepoView {
+  readonly repo: AgentMemoryRepoName
+  /** 0 before the first save. */
+  readonly revision: number
+  /** Ordered by path. */
+  readonly files: readonly AgentMemoryFile[]
+}
+
+export interface SaveAgentMemoryRuntimeInput {
+  /** The revision the changes were made against. */
+  readonly baseRevision: number
+  /** What was learned, as the revision's entry in the repo's history. */
+  readonly message: string
+  /** `contents: null` deletes the file. */
+  readonly changes: readonly AgentMemoryChange[]
+  /** The conversation the save came from, `/agents/<threadId>`. */
+  readonly source?: string
+}
+
+export type SaveAgentMemoryRuntimeResult =
+  | {
+      readonly saved: true
+      readonly revision: number
+      /** Links in the saved repo that point at no file. */
+      readonly warnings: readonly AgentMemoryLinkWarning[]
+    }
+  | {
+      readonly saved: false
+      /** The repo's latest revision. */
+      readonly revision: number
+      /** Files in `changes` that another save changed after `baseRevision`, as they are now. */
+      readonly conflicts: readonly AgentMemoryChange[]
+    }
+
+/**
+ * The Agent's memory: `user` is the caller's own; `project` is built up by everyone who can run the
+ * Agent, who all read and save it, and deleted only with `can.manage(agent.memory)`.
+ */
+export interface AgentMemoryRuntime {
+  /**
+   * With `asOf`, the repo at the latest revision saved by then; with `revision`, as that revision
+   * left it.
+   */
+  get(
+    repo: AgentMemoryRepoName,
+    options?: { readonly asOf?: Date; readonly revision?: number }
+  ): Promise<AgentMemoryRepoView>
+  save(
+    repo: AgentMemoryRepoName,
+    input: SaveAgentMemoryRuntimeInput
+  ): Promise<SaveAgentMemoryRuntimeResult>
+  /** Newest first. */
+  listRevisions(
+    repo: AgentMemoryRepoName,
+    input?: { readonly limit?: number; readonly offset?: number }
+  ): Promise<ListAgentMemoryRevisionsResult>
+  /** Deletes the repo with its history. */
+  delete(repo: AgentMemoryRepoName): Promise<void>
+}
+
+const SOURCE_PATTERN = /^\/agents\/[A-Za-z0-9_-]{1,128}$/
+
+export function createAgentMemoryRuntime(runtime: SixbRuntimeContext): AgentMemoryRuntime {
+  const authority = resolveRuntimeAuthorizationForProject(runtime)
+  // Shared-link sessions and unresolved authority reach no memory.
+  const caller: Principal | null =
+    authority.type === "principal"
+      ? authority.context.principal
+      : authority.type === "unrestricted"
+        ? SYSTEM_PRINCIPAL
+        : null
+
+  const requireStorage = (): AgentMemoryStore => {
+    const storage = runtime.storage.agents?.memory
+    if (!storage) {
+      throw new AgentMemoryError(
+        "storage_unavailable",
+        "[Sixb] Agent memory needs storage that supports the Agent."
+      )
+    }
+    return storage
+  }
+
+  const canManageProject = () => isRuntimeAllowed(runtime, { kind: "agentMemory.manage" })
+
+  /** The repo's storage id, once the caller may read and save it. */
+  const usable = (repo: AgentMemoryRepoName): string => {
+    if (
+      repo === "project" &&
+      !isRuntimeAllowed(runtime, { kind: "agent.run" }) &&
+      !canManageProject()
+    ) {
+      throw new AgentMemoryError(
+        "not_allowed",
+        "[Sixb] The project's Agent memory needs can.run(agent) or can.manage(agent.memory)."
+      )
+    }
+    return agentMemoryRepoId(repo, caller)
+  }
+
+  /** The repo's storage id, once the caller may delete it with its history. */
+  const deletable = (repo: AgentMemoryRepoName): string => {
+    const repoId = usable(repo)
+    if (repo === "project" && !canManageProject()) {
+      throw new AgentMemoryError(
+        "not_allowed",
+        "[Sixb] Deleting the project's Agent memory needs can.manage(agent.memory)."
+      )
+    }
+    return repoId
+  }
+
+  return {
+    async get(repo, options = {}) {
+      const repoId = usable(repo)
+      const { revision, files } = await requireStorage().get({
+        projectId: runtime.projectId,
+        repoId,
+        ...(options.asOf === undefined ? {} : { asOf: options.asOf }),
+        ...(options.revision === undefined ? {} : { revision: options.revision }),
+      })
+      return { repo, revision, files }
+    },
+
+    async save(repo, input) {
+      const repoId = usable(repo)
+      if (!Number.isSafeInteger(input.baseRevision) || input.baseRevision < 0) {
+        throw new AgentMemoryError(
+          "invalid_save",
+          "[Sixb] Agent memory base revision must be the revision the changes were made against."
+        )
+      }
+      if (input.source !== undefined && !SOURCE_PATTERN.test(input.source)) {
+        throw new AgentMemoryError(
+          "invalid_save",
+          "[Sixb] Agent memory source must be a conversation link, '/agents/<threadId>'."
+        )
+      }
+      const storage = requireStorage()
+      const current = await storage.get({ projectId: runtime.projectId, repoId })
+      const files = applyAgentMemoryChanges(current.files, input.message, input.changes)
+      const result = await storage.save({
+        projectId: runtime.projectId,
+        repoId,
+        baseRevision: input.baseRevision,
+        message: input.message.trim(),
+        author: caller ?? SYSTEM_PRINCIPAL,
+        ...(input.source === undefined ? {} : { source: input.source }),
+        changes: input.changes,
+      })
+      return result.saved ? { ...result, warnings: findBrokenAgentMemoryLinks(files) } : result
+    },
+
+    async listRevisions(repo, input = {}) {
+      return requireStorage().listRevisions({
+        projectId: runtime.projectId,
+        repoId: usable(repo),
+        ...input,
+      })
+    },
+
+    async delete(repo) {
+      await requireStorage().delete({ projectId: runtime.projectId, repoId: deletable(repo) })
+    },
+  }
+}

package/src/agents/memory.ts

@@ -0,0 +1,178 @@
+/**
+ * Agent memory repos: a folder of linked Markdown files with `MEMORY.md` as the entry point, in the
+ * Agent Memory Repo format. These rules decide what a save may contain before it reaches storage.
+ */
+
+import type { Principal } from "../auth"
+import type { AgentMemoryChange, AgentMemoryFile } from "../storage/agents"
+import { AgentMemoryError } from "./errors"
+
+/** The two repos a conversation reaches: its user's own, and the one the project shares. */
+export type AgentMemoryRepoName = "user" | "project"
+
+export const AGENT_MEMORY_REPO_NAMES: readonly AgentMemoryRepoName[] = ["user", "project"]
+
+/** The file every repo starts from, and the one rendered into every conversation's prompt. */
+export const AGENT_MEMORY_ENTRY = "MEMORY.md"
+
+export const AGENT_MEMORY_LIMITS = {
+  /** `MEMORY.md` is part of every prompt. */
+  entryBytes: 16 * 1024,
+  fileBytes: 256 * 1024,
+  repoBytes: 4 * 1024 * 1024,
+  pathLength: 256,
+  messageLength: 500,
+} as const
+
+/** A link to a path that is not in the repo, found in one of its Markdown files. */
+export interface AgentMemoryLinkWarning {
+  /** The file the link is in. */
+  readonly path: string
+  readonly link: string
+}
+
+const encoder = new TextEncoder()
+
+/**
+ * The storage id of a repo: `user:<userId>` or `project`. A caller with no user of its own keeps
+ * its memory as `system:<id>`: a project without auth, or app code running as the system, which
+ * then reads a repo no signed-in user's conversation does.
+ */
+export function agentMemoryRepoId(repo: AgentMemoryRepoName, owner: Principal | null): string {
+  if (repo === "project") return "project"
+  if (!owner || owner.type === "serviceAccount") {
+    throw new AgentMemoryError(
+      "not_allowed",
+      "[Sixb] Agent memory of its own belongs to a signed-in user."
+    )
+  }
+  return `${owner.type}:${owner.id}`
+}
+
+export function parseAgentMemoryRepoName(value: string): AgentMemoryRepoName {
+  if (value === "user" || value === "project") return value
+  throw new AgentMemoryError(
+    "invalid_repo",
+    `[Sixb] Agent memory repo '${value}' does not exist. Use 'user' or 'project'.`
+  )
+}
+
+/** Why a path cannot hold a memory file, or `null` when it can. */
+export function agentMemoryPathProblem(path: string): string | null {
+  if (path.length === 0) return "is empty"
+  if (path.length > AGENT_MEMORY_LIMITS.pathLength) {
+    return `is longer than ${AGENT_MEMORY_LIMITS.pathLength} characters`
+  }
+  if (/[\u0000-\u001f\u007f\\]/.test(path)) return "contains a backslash or a control character"
+  if (path.startsWith("/")) return "is absolute; paths start at the repo root"
+  const segments = path.split("/")
+  if (segments.some((segment) => segment.length === 0)) return "has an empty segment"
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    return "has a '.' or '..' segment"
+  }
+  if (segments.some((segment) => segment.startsWith("."))) return "names a dotfile"
+  if (path.endsWith(".theirs")) return "is a conflict copy; merge it into its file and delete it"
+  return null
+}
+
+/**
+ * Apply `changes` to the repo's current files and check the result, so a save is rejected with
+ * an error the Agent can act on. Returns the repo as the save leaves it.
+ */
+export function applyAgentMemoryChanges(
+  current: readonly AgentMemoryFile[],
+  message: string,
+  changes: readonly AgentMemoryChange[]
+): AgentMemoryFile[] {
+  const fail = (detail: string): never => {
+    throw new AgentMemoryError("invalid_save", `[Sixb] Agent memory ${detail}`)
+  }
+
+  if (message.trim().length === 0) fail("save needs a message saying what was learned.")
+  if (message.length > AGENT_MEMORY_LIMITS.messageLength) {
+    fail(`save message is longer than ${AGENT_MEMORY_LIMITS.messageLength} characters.`)
+  }
+  if (changes.length === 0) fail("save changes no file.")
+
+  const files = new Map(current.map((file) => [file.path, file.contents]))
+  const seen = new Set<string>()
+  for (const change of changes) {
+    const problem = agentMemoryPathProblem(change.path)
+    if (problem) fail(`path '${change.path}' ${problem}.`)
+    if (seen.has(change.path)) fail(`save changes '${change.path}' more than once.`)
+    seen.add(change.path)
+
+    if (change.contents === null) {
+      files.delete(change.path)
+      continue
+    }
+    if (change.contents.includes("\u0000")) fail(`file '${change.path}' is not text.`)
+    const bytes = encoder.encode(change.contents).byteLength
+    if (change.path === AGENT_MEMORY_ENTRY && bytes > AGENT_MEMORY_LIMITS.entryBytes) {
+      fail(
+        `${AGENT_MEMORY_ENTRY} is over ${kilobytes(AGENT_MEMORY_LIMITS.entryBytes)}, and it is part of every prompt. Move entries into topic files and link them.`
+      )
+    }
+    if (bytes > AGENT_MEMORY_LIMITS.fileBytes) {
+      fail(`file '${change.path}' is over ${kilobytes(AGENT_MEMORY_LIMITS.fileBytes)}.`)
+    }
+    files.set(change.path, change.contents)
+  }
+
+  if (!files.has(AGENT_MEMORY_ENTRY)) {
+    fail(`repo must keep its ${AGENT_MEMORY_ENTRY}.`)
+  }
+  let total = 0
+  for (const contents of files.values()) total += encoder.encode(contents).byteLength
+  if (total > AGENT_MEMORY_LIMITS.repoBytes) {
+    fail(
+      `repo would be over ${kilobytes(AGENT_MEMORY_LIMITS.repoBytes)}. Remove entries that are cheap to look up again.`
+    )
+  }
+
+  return [...files].map(([path, contents]) => ({ path, contents }))
+}
+
+/**
+ * Links in the repo's Markdown files that point at no file. A `[[target]]` names a path from the
+ * repo root, with `.md` left out and any other extension kept.
+ */
+export function findBrokenAgentMemoryLinks(
+  files: readonly AgentMemoryFile[]
+): AgentMemoryLinkWarning[] {
+  const paths = new Set(files.map((file) => file.path))
+  const warnings: AgentMemoryLinkWarning[] = []
+  for (const file of files) {
+    if (!file.path.endsWith(".md")) continue
+    for (const link of agentMemoryLinks(file.contents)) {
+      if (!paths.has(agentMemoryLinkPath(link))) warnings.push({ path: file.path, link })
+    }
+  }
+  return warnings.sort((left, right) =>
+    left.path === right.path ? compare(left.link, right.link) : compare(left.path, right.path)
+  )
+}
+
+/** The distinct `[[link]]` targets in a Markdown file, in the order they first appear. */
+export function agentMemoryLinks(contents: string): string[] {
+  const links = new Set<string>()
+  for (const match of contents.matchAll(/\[\[([^[\]\n]+)\]\]/g)) {
+    const link = match[1]?.trim()
+    if (link) links.add(link)
+  }
+  return [...links]
+}
+
+/** The file a link names: `.md` is added unless its last segment already has an extension. */
+export function agentMemoryLinkPath(link: string): string {
+  const name = link.slice(link.lastIndexOf("/") + 1)
+  return name.includes(".") ? link : `${link}.md`
+}
+
+function kilobytes(bytes: number): string {
+  return bytes >= 1024 * 1024 ? `${bytes / (1024 * 1024)} MB` : `${bytes / 1024} KB`
+}
+
+function compare(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0
+}