@sixb/core 0.1.20 → 0.1.21

package/src/storage/agents/types.ts

@@ -1,7 +1,6 @@
 import type { AgentMessage, AgentMessagePart, AgentMessageRole } from "../../agents/message"
 import type { AgentReasoning } from "../../agents/types"
 import type { Principal } from "../../auth"
-import type { FileRef } from "../../blob-storage"
 import type { SixbErrorCode, SixbFailure } from "../../errors/types"
 import type { JsonValue } from "../../json"
 import type { LanguageModelRef } from "../../models"
@@ -157,15 +156,7 @@ export function coerceAgentRunFinishReason(
 }
 
 /** Stable, user-facing diagnostics emitted by the platform while executing a run. */
-export const AGENT_RUN_DIAGNOSTIC_CODES = [
-  "output_file_limit_exceeded",
-  "output_file_too_large",
-  "output_budget_exhausted",
-  "output_collection_failed",
-  "output_file_changed",
-  "output_storage_failed",
-  "step_limit_reached",
-] as const
+export const AGENT_RUN_DIAGNOSTIC_CODES = ["step_limit_reached"] as const
 
 /**
  * Closed on purpose, and the wire is closed with it.
@@ -181,10 +172,8 @@ export type AgentRunDiagnosticSeverity = "warning" | "error"
 export interface AgentRunDiagnostic {
   readonly code: AgentRunDiagnosticCode
   readonly severity: AgentRunDiagnosticSeverity
-  /** `output` for published files, `run` for the turn as a whole. */
-  readonly scope: "output" | "run"
-  /** Relative path inside the run's published output directory, when one file is involved. */
-  readonly path?: string
+  /** What the diagnostic is about: the turn as a whole. */
+  readonly scope: "run"
   /** Sanitized, stable copy suitable for display to an end user. */
   readonly message: string
 }
@@ -251,8 +240,7 @@ export interface SubagentRunSpec {
 
 /** Durable child output returned to its parent by `wait_agent`. */
 export interface SubagentRunResult {
-  readonly text?: string
-  readonly files?: readonly FileRef[]
+  readonly text: string
 }
 
 export interface SubagentRunRecord extends AgentRunRecordBase {
@@ -480,6 +468,11 @@ export interface AgentThreadStore {
   transitionSandbox(input: TransitionAgentThreadSandboxInput): Promise<AgentThreadSandboxState>
   create(input: CreateAgentThreadInput): Promise<AgentThreadRecord>
   getById(params: { projectId: string; id: string }): Promise<AgentThreadRecord | null>
+  /** The threads found, in first-occurrence input order; a missing one is omitted. */
+  getByIds(params: {
+    readonly projectId: string
+    readonly ids: readonly string[]
+  }): Promise<readonly AgentThreadRecord[]>
   list(input: ListAgentThreadsInput): Promise<ListAgentThreadsResult>
 }
 

package/src/storage/artifacts/errors.ts

@@ -0,0 +1,16 @@
+export type ArtifactStorageErrorCode =
+  | "artifact_exists"
+  | "artifact_not_found"
+  | "artifact_kind_mismatch"
+
+/** Error for artifact-storage invariants. Callers branch on `code` rather than message text. */
+export class ArtifactStorageError extends Error {
+  readonly name = "ArtifactStorageError"
+
+  constructor(
+    readonly code: ArtifactStorageErrorCode,
+    message: string
+  ) {
+    super(message)
+  }
+}

package/src/storage/artifacts/in-memory.ts

@@ -0,0 +1,240 @@
+import { principalsEqual } from "../../auth"
+import { paginate } from "../pagination"
+import { artifactStorageErrors } from "./record"
+import type {
+  ArtifactFrameGrantRecord,
+  ArtifactRecord,
+  ArtifactStorage,
+  ArtifactVersionInput,
+  ArtifactVersionRecord,
+  CreateArtifactInput,
+  DeleteArtifactInput,
+  DeleteArtifactVersionsByOriginInput,
+  DeleteExpiredArtifactFrameGrantsInput,
+  FindArtifactFrameGrantInput,
+  GetArtifactInput,
+  GetArtifactVersionInput,
+  ListArtifactsInput,
+  ListArtifactsResult,
+  ListArtifactVersionsInput,
+  ListArtifactVersionsResult,
+  ListReferencingVersionsInput,
+  PublishArtifactVersionInput,
+  PublishedArtifactVersion,
+} from "./types"
+
+interface StoredArtifact {
+  readonly record: ArtifactRecord
+  /** Oldest first. */
+  readonly versions: readonly ArtifactVersionRecord[]
+  /** The number the next version gets; it only grows, so a deleted number is never reused. */
+  readonly nextVersion: number
+}
+
+interface InMemoryArtifactSnapshot {
+  readonly artifacts: ReadonlyMap<string, StoredArtifact>
+  readonly frameGrants: ReadonlyMap<string, ArtifactFrameGrantRecord>
+}
+
+export class InMemoryArtifactStorage implements ArtifactStorage {
+  private artifacts = new Map<string, StoredArtifact>()
+  private frameGrants = new Map<string, ArtifactFrameGrantRecord>()
+
+  async create(input: CreateArtifactInput): Promise<PublishedArtifactVersion> {
+    const key = artifactKey(input.projectId, input.id)
+    if (this.artifacts.has(key)) throw artifactStorageErrors.exists(input.id)
+    const version = versionRecord(input.projectId, input.id, 1, input.version)
+    const record: ArtifactRecord = {
+      projectId: input.projectId,
+      id: input.id,
+      kind: input.kind,
+      title: version.title,
+      owner: { ...input.owner },
+      latestVersion: 1,
+      createdAt: new Date(version.createdAt),
+      updatedAt: new Date(version.createdAt),
+    }
+    this.artifacts.set(key, { record, versions: [version], nextVersion: 2 })
+    return published(record, version)
+  }
+
+  async publish(input: PublishArtifactVersionInput): Promise<PublishedArtifactVersion> {
+    const key = artifactKey(input.projectId, input.artifactId)
+    const stored = this.artifacts.get(key)
+    if (!stored) throw artifactStorageErrors.notFound(input.artifactId)
+    if (stored.record.kind !== input.kind) {
+      throw artifactStorageErrors.kindMismatch(input.artifactId, stored.record.kind, input.kind)
+    }
+    const version = versionRecord(
+      input.projectId,
+      input.artifactId,
+      stored.nextVersion,
+      input.version
+    )
+    const record: ArtifactRecord = {
+      ...stored.record,
+      title: version.title,
+      latestVersion: version.version,
+      updatedAt: new Date(version.createdAt),
+    }
+    this.artifacts.set(key, {
+      record,
+      versions: [...stored.versions, version],
+      nextVersion: stored.nextVersion + 1,
+    })
+    return published(record, version)
+  }
+
+  async get(input: GetArtifactInput): Promise<ArtifactRecord | null> {
+    const stored = this.artifacts.get(artifactKey(input.projectId, input.id))
+    return stored ? structuredClone(stored.record) : null
+  }
+
+  async list(input: ListArtifactsInput): Promise<ListArtifactsResult> {
+    const matching = [...this.artifacts.values()]
+      .filter(
+        ({ record, versions }) =>
+          record.projectId === input.projectId &&
+          (!input.owner || principalsEqual(record.owner, input.owner)) &&
+          (input.kind === undefined || record.kind === input.kind) &&
+          (input.originThreadId === undefined ||
+            versions.some((version) => version.origin?.threadId === input.originThreadId))
+      )
+      .map(({ record }) => record)
+      .sort(
+        (left, right) =>
+          right.updatedAt.getTime() - left.updatedAt.getTime() || left.id.localeCompare(right.id)
+      )
+    const { page, hasMore, total } = paginate(matching, input)
+    return { artifacts: structuredClone(page), hasMore, total }
+  }
+
+  async getVersion(input: GetArtifactVersionInput): Promise<ArtifactVersionRecord | null> {
+    const stored = this.artifacts.get(artifactKey(input.projectId, input.artifactId))
+    const version = stored?.versions.find((candidate) => candidate.version === input.version)
+    return version ? structuredClone(version) : null
+  }
+
+  async listVersions(input: ListArtifactVersionsInput): Promise<ListArtifactVersionsResult> {
+    const stored = this.artifacts.get(artifactKey(input.projectId, input.artifactId))
+    const newestFirst = [...(stored?.versions ?? [])].reverse()
+    const { page, hasMore, total } = paginate(newestFirst, input)
+    return { versions: structuredClone(page), hasMore, total }
+  }
+
+  async listReferencingVersions(
+    input: ListReferencingVersionsInput
+  ): Promise<ArtifactVersionRecord[]> {
+    const prefix = `artifact:${input.artifactId}`
+    const referencing: ArtifactVersionRecord[] = []
+    for (const stored of this.artifacts.values()) {
+      if (stored.record.projectId !== input.projectId) continue
+      const latest = stored.versions.find(
+        (candidate) => candidate.version === stored.record.latestVersion
+      )
+      if (latest?.references.some((reference) => refersTo(reference.address, prefix))) {
+        referencing.push(structuredClone(latest))
+      }
+    }
+    // Code-unit order, as SQLite compares text.
+    return referencing.sort((left, right) => (left.artifactId < right.artifactId ? -1 : 1))
+  }
+
+  async createFrameGrant(record: ArtifactFrameGrantRecord): Promise<void> {
+    if (!this.artifacts.has(artifactKey(record.projectId, record.artifactId))) {
+      throw artifactStorageErrors.notFound(record.artifactId)
+    }
+    this.frameGrants.set(artifactKey(record.projectId, record.tokenHash), structuredClone(record))
+  }
+
+  async findFrameGrant(
+    input: FindArtifactFrameGrantInput
+  ): Promise<ArtifactFrameGrantRecord | null> {
+    const grant = this.frameGrants.get(artifactKey(input.projectId, input.tokenHash))
+    return grant ? structuredClone(grant) : null
+  }
+
+  async deleteExpiredFrameGrants(input: DeleteExpiredArtifactFrameGrantsInput): Promise<number> {
+    let deleted = 0
+    for (const [key, grant] of this.frameGrants) {
+      if (deleted >= input.limit) break
+      if (grant.projectId !== input.projectId || grant.expiresAt >= input.expiredBefore) continue
+      this.frameGrants.delete(key)
+      deleted += 1
+    }
+    return deleted
+  }
+
+  async delete(input: DeleteArtifactInput): Promise<boolean> {
+    return this.deleteArtifact(artifactKey(input.projectId, input.id))
+  }
+
+  async deleteVersionsByOrigin(input: DeleteArtifactVersionsByOriginInput): Promise<number> {
+    let deleted = 0
+    for (const [key, stored] of this.artifacts) {
+      if (stored.record.projectId !== input.projectId) continue
+      const remaining = stored.versions.filter((version) => version.origin?.runId !== input.runId)
+      if (remaining.length === stored.versions.length) continue
+      deleted += stored.versions.length - remaining.length
+      const latest = remaining.at(-1)
+      if (!latest) {
+        this.deleteArtifact(key)
+        continue
+      }
+      this.artifacts.set(key, {
+        ...stored,
+        record: {
+          ...stored.record,
+          title: latest.title,
+          latestVersion: latest.version,
+          updatedAt: new Date(latest.createdAt),
+        },
+        versions: remaining,
+      })
+    }
+    return deleted
+  }
+
+  snapshot(): InMemoryArtifactSnapshot {
+    return structuredClone({ artifacts: this.artifacts, frameGrants: this.frameGrants })
+  }
+
+  restore(snapshot: InMemoryArtifactSnapshot): void {
+    const restored = structuredClone(snapshot)
+    this.artifacts = new Map(restored.artifacts)
+    this.frameGrants = new Map(restored.frameGrants)
+  }
+
+  /** Deletes an artifact with its frame grants, as the SQL providers' cascade does. */
+  private deleteArtifact(key: string): boolean {
+    for (const [grantKey, grant] of this.frameGrants) {
+      if (artifactKey(grant.projectId, grant.artifactId) === key) this.frameGrants.delete(grantKey)
+    }
+    return this.artifacts.delete(key)
+  }
+}
+
+function versionRecord(
+  projectId: string,
+  artifactId: string,
+  version: number,
+  input: ArtifactVersionInput
+): ArtifactVersionRecord {
+  return structuredClone({ ...input, projectId, artifactId, version })
+}
+
+function published(
+  record: ArtifactRecord,
+  version: ArtifactVersionRecord
+): PublishedArtifactVersion {
+  return structuredClone({ artifact: record, version })
+}
+
+function artifactKey(projectId: string, id: string): string {
+  return `${projectId}\0${id}`
+}
+
+/** Whether an address names the artifact `artifact:<id>` is, at any version, file, or part. */
+function refersTo(address: string, prefix: string): boolean {
+  return address.startsWith(prefix) && /^(?:$|[@/#])/.test(address.slice(prefix.length))
+}

package/src/storage/artifacts/index.ts

@@ -0,0 +1,30 @@
+export type { ArtifactStorageErrorCode } from "./errors"
+export { ArtifactStorageError } from "./errors"
+export { InMemoryArtifactStorage } from "./in-memory"
+export type {
+  ArtifactFile,
+  ArtifactFrameGrantRecord,
+  ArtifactFrameTarget,
+  ArtifactKind,
+  ArtifactOrigin,
+  ArtifactOutline,
+  ArtifactRecord,
+  ArtifactReference,
+  ArtifactStorage,
+  ArtifactVersionInput,
+  ArtifactVersionRecord,
+  CreateArtifactInput,
+  DeleteArtifactInput,
+  DeleteArtifactVersionsByOriginInput,
+  DeleteExpiredArtifactFrameGrantsInput,
+  FindArtifactFrameGrantInput,
+  GetArtifactInput,
+  GetArtifactVersionInput,
+  ListArtifactsInput,
+  ListArtifactsResult,
+  ListArtifactVersionsInput,
+  ListArtifactVersionsResult,
+  ListReferencingVersionsInput,
+  PublishArtifactVersionInput,
+  PublishedArtifactVersion,
+} from "./types"

package/src/storage/artifacts/record.ts

@@ -0,0 +1,200 @@
+import { isArtifactKind } from "../../artifacts/kinds"
+import type { ArtifactOutline } from "../../artifacts/outline"
+import type { ArtifactReference } from "../../artifacts/references"
+import type { Principal } from "../../auth"
+import { isFileRef } from "../../blob-storage"
+import { ArtifactStorageError } from "./errors"
+import type {
+  ArtifactFile,
+  ArtifactFrameGrantRecord,
+  ArtifactFrameTarget,
+  ArtifactKind,
+  ArtifactRecord,
+  ArtifactVersionRecord,
+} from "./types"
+
+// Rows arrive from providers with camelCase keys. JSON columns may arrive parsed (jsonb) or as text
+// (SQLite), and timestamps as `Date` or ISO text. A row that does not read back as a valid record
+// fails closed rather than rendering something the store never held.
+
+type Row = { readonly [column: string]: unknown }
+
+export function parseArtifactRow(row: Row): ArtifactRecord {
+  const id = text(row.id, "id", "artifact")
+  const where = `artifact '${id}'`
+  const kind = row.kind
+  if (!isArtifactKind(kind)) throw corrupt(where, "kind is not an artifact kind")
+  return {
+    projectId: text(row.projectId, "projectId", where),
+    id,
+    kind,
+    title: text(row.title, "title", where),
+    owner: principal(row.ownerPrincipalType, row.ownerPrincipalId, "owner", where),
+    latestVersion: positiveInteger(row.latestVersion, "latestVersion", where),
+    createdAt: date(row.createdAt, "createdAt", where),
+    updatedAt: date(row.updatedAt, "updatedAt", where),
+  }
+}
+
+export function parseArtifactVersionRow(row: Row): ArtifactVersionRecord {
+  const artifactId = text(row.artifactId, "artifactId", "artifact version")
+  const version = positiveInteger(row.version, "version", `artifact '${artifactId}'`)
+  const where = `artifact '${artifactId}' version ${version}`
+  const originThreadId = row.originThreadId
+  const originRunId = row.originRunId
+  if ((originThreadId == null) !== (originRunId == null)) {
+    throw corrupt(where, "origin needs both a thread and a run")
+  }
+  return {
+    projectId: text(row.projectId, "projectId", where),
+    artifactId,
+    version,
+    title: text(row.title, "title", where),
+    entry: text(row.entry, "entry", where),
+    files: files(json(row.files, "files", where), where),
+    outline: outline(json(row.outline, "outline", where), where),
+    references: references(json(row.refs, "refs", where), where),
+    author: principal(row.authorPrincipalType, row.authorPrincipalId, "author", where),
+    ...(originThreadId == null
+      ? {}
+      : {
+          origin: {
+            threadId: text(originThreadId, "originThreadId", where),
+            runId: text(originRunId, "originRunId", where),
+          },
+        }),
+    createdAt: date(row.createdAt, "createdAt", where),
+  }
+}
+
+/** Targets are checked one by one: they decide what a frame may show from other artifacts. */
+export function parseArtifactFrameGrantRow(row: Row): ArtifactFrameGrantRecord {
+  const artifactId = text(row.artifactId, "artifactId", "artifact frame grant")
+  const where = `frame grant for artifact '${artifactId}'`
+  return {
+    projectId: text(row.projectId, "projectId", where),
+    tokenHash: text(row.tokenHash, "tokenHash", where),
+    artifactId,
+    version: positiveInteger(row.version, "version", where),
+    targets: frameTargets(json(row.targets, "targets", where), where),
+    createdAt: date(row.createdAt, "createdAt", where),
+    expiresAt: date(row.expiresAt, "expiresAt", where),
+  }
+}
+
+/** The errors every provider raises, with one wording. */
+export const artifactStorageErrors = {
+  exists: (id: string) =>
+    new ArtifactStorageError("artifact_exists", `[Sixb] Artifact '${id}' already exists.`),
+  notFound: (id: string) =>
+    new ArtifactStorageError("artifact_not_found", `[Sixb] Artifact '${id}' was not found.`),
+  kindMismatch: (id: string, kind: ArtifactKind, requested: ArtifactKind) =>
+    new ArtifactStorageError(
+      "artifact_kind_mismatch",
+      `[Sixb] Artifact '${id}' is a ${kind}; it cannot take a ${requested} version.`
+    ),
+}
+
+function files(value: unknown, where: string): ArtifactFile[] {
+  if (!Array.isArray(value)) throw corrupt(where, "files is not a list")
+  return value.map((entry) => {
+    if (!isObject(entry) || typeof entry.path !== "string" || !isFileRef(entry.file)) {
+      throw corrupt(where, "a file entry is not a path and a file reference")
+    }
+    return { path: entry.path, file: entry.file }
+  })
+}
+
+function outline(value: unknown, where: string): ArtifactOutline {
+  if (!isObject(value) || !isArtifactKind(value.kind)) {
+    throw corrupt(where, "outline does not name an artifact kind")
+  }
+  return value as unknown as ArtifactOutline
+}
+
+function references(value: unknown, where: string): ArtifactReference[] {
+  if (!Array.isArray(value)) throw corrupt(where, "references is not a list")
+  return value.map((entry) => {
+    if (
+      !isObject(entry) ||
+      typeof entry.address !== "string" ||
+      (entry.as !== "embed" && entry.as !== "link") ||
+      typeof entry.at !== "string" ||
+      !Number.isSafeInteger(entry.resolvedVersion) ||
+      (entry.resolvedVersion as number) < 1
+    ) {
+      throw corrupt(where, "a reference is not an address, a verb, a place, and a version")
+    }
+    return {
+      address: entry.address,
+      as: entry.as,
+      at: entry.at,
+      resolvedVersion: entry.resolvedVersion as number,
+    }
+  })
+}
+
+function frameTargets(value: unknown, where: string): ArtifactFrameTarget[] {
+  if (!Array.isArray(value)) throw corrupt(where, "targets is not a list")
+  return value.map((entry) => {
+    if (
+      !isObject(entry) ||
+      typeof entry.address !== "string" ||
+      typeof entry.artifactId !== "string" ||
+      !Number.isSafeInteger(entry.version) ||
+      (entry.version as number) < 1
+    ) {
+      throw corrupt(where, "a target is not an address, an artifact, and a version")
+    }
+    return {
+      address: entry.address,
+      artifactId: entry.artifactId,
+      version: entry.version as number,
+    }
+  })
+}
+
+const PRINCIPAL_TYPES: ReadonlySet<string> = new Set(["user", "serviceAccount", "system"])
+
+function principal(type: unknown, id: unknown, column: string, where: string): Principal {
+  if (typeof type !== "string" || !PRINCIPAL_TYPES.has(type)) {
+    throw corrupt(where, `${column} is not a principal`)
+  }
+  return { type: type as Principal["type"], id: text(id, column, where) }
+}
+
+function json(value: unknown, column: string, where: string): unknown {
+  if (typeof value !== "string") return value
+  try {
+    return JSON.parse(value)
+  } catch {
+    throw corrupt(where, `${column} is not JSON`)
+  }
+}
+
+function text(value: unknown, column: string, where: string): string {
+  if (typeof value !== "string" || value.length === 0) throw corrupt(where, `${column} is not text`)
+  return value
+}
+
+function positiveInteger(value: unknown, column: string, where: string): number {
+  const number = typeof value === "bigint" ? Number(value) : value
+  if (typeof number !== "number" || !Number.isSafeInteger(number) || number < 1) {
+    throw corrupt(where, `${column} is not a positive integer`)
+  }
+  return number
+}
+
+function date(value: unknown, column: string, where: string): Date {
+  const parsed = value instanceof Date || typeof value === "string" ? new Date(value) : null
+  if (!parsed || !Number.isFinite(parsed.getTime())) throw corrupt(where, `${column} is not a date`)
+  return parsed
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function corrupt(where: string, reason: string): Error {
+  return new Error(`[Sixb] Stored ${where} is invalid: ${reason}.`)
+}