@sixb/core 0.1.21 → 0.1.22

package/src/storage/artifacts/types.ts

@@ -28,7 +28,10 @@ export interface ArtifactFile {
   readonly file: FileRef
 }
 
-/** Where a version was published from. Provenance only: reading never depends on it. */
+/**
+ * Where a version was published from: an Agent turn in a thread. Publishing one shares the artifact
+ * in that thread.
+ */
 export interface ArtifactOrigin {
   readonly threadId: string
   readonly runId: string
@@ -72,6 +75,11 @@ export interface PublishArtifactVersionInput {
   /** Must be the artifact's kind. */
   readonly kind: ArtifactKind
   readonly version: ArtifactVersionInput
+  /**
+   * The version this one was made from. When the latest version is another, the publish fails
+   * with `artifact_moved` rather than replace changes it never saw.
+   */
+  readonly baseVersion?: number
 }
 
 export interface PublishedArtifactVersion {
@@ -87,8 +95,8 @@ export interface GetArtifactInput {
 export interface ListArtifactsInput {
   readonly projectId: string
   readonly owner?: Principal
-  /** Only artifacts with a version published from this thread. */
-  readonly originThreadId?: string
+  /** Only artifacts shared in this thread. */
+  readonly threadId?: string
   /** Only artifacts of this kind. */
   readonly kind?: ArtifactKind
   readonly limit?: number
@@ -125,6 +133,19 @@ export interface DeleteArtifactInput {
   readonly id: string
 }
 
+export interface CopyArtifactInput {
+  readonly projectId: string
+  /** The artifact copied. */
+  readonly sourceId: string
+  /** The copy's id. */
+  readonly id: string
+  /** Owns the copy. */
+  readonly owner: Principal
+  /** The thread the copy is shared in, as long as it lasts: a fork's. */
+  readonly threadId: string
+  readonly copiedAt?: Date
+}
+
 export interface ListReferencingVersionsInput {
   readonly projectId: string
   /** The artifact the versions refer to. */
@@ -170,16 +191,49 @@ export interface DeleteArtifactVersionsByOriginInput {
   readonly runId: string
 }
 
+/** Whose values, kept by which artifact: a page keeps its own for each reader. */
+export interface ArtifactStateScope {
+  readonly projectId: string
+  readonly artifactId: string
+  readonly principal: Principal
+}
+
+export interface ArtifactStateKeyInput extends ArtifactStateScope {
+  readonly key: string
+}
+
+export interface SetArtifactStateInput extends ArtifactStateKeyInput {
+  /** JSON text, stored as written. */
+  readonly value: string
+  readonly updatedAt: Date
+}
+
+/** One value a page keeps for a reader. */
+export interface ArtifactStateEntry {
+  readonly key: string
+  /** JSON text. */
+  readonly value: string
+  /** The value's UTF-8 bytes, which the reader's limits count. */
+  readonly sizeBytes: number
+  readonly updatedAt: Date
+}
+
 /**
  * Persistence only: who may read or publish, and what a version may contain, are decided in Core
  * before a call reaches storage.
  */
 export interface ArtifactStorage {
-  /** Creates the artifact with its first version. Throws `artifact_exists` when the id is taken. */
+  /**
+   * Creates the artifact with its first version, shared in its origin's thread. Throws
+   * `artifact_exists` when the id is taken.
+   */
   create(input: CreateArtifactInput): Promise<PublishedArtifactVersion>
   /**
-   * Stores the next version and makes it the latest. Throws `artifact_not_found` or
-   * `artifact_kind_mismatch`. A version number is never reused, even after its version is deleted.
+   * Stores the next version and makes it the latest, sharing the artifact in its origin's thread.
+   * Throws `artifact_not_found`, `artifact_kind_mismatch`, or `artifact_moved` with the latest version and its author when
+   * `baseVersion` is not the latest, checked in the same transaction as the write, so of two
+   * publishes from one base only the first is stored. A version number is never reused, even
+   * after its version is deleted.
    */
   publish(input: PublishArtifactVersionInput): Promise<PublishedArtifactVersion>
   get(input: GetArtifactInput): Promise<ArtifactRecord | null>
@@ -188,6 +242,18 @@ export interface ArtifactStorage {
   getVersion(input: GetArtifactVersionInput): Promise<ArtifactVersionRecord | null>
   /** Newest first. */
   listVersions(input: ListArtifactVersionsInput): Promise<ListArtifactVersionsResult>
+  /**
+   * The threads the artifact is shared in, by id: each one a version it keeps was published from,
+   * and the one it was copied for.
+   */
+  listThreadIds(input: GetArtifactInput): Promise<string[]>
+  /**
+   * Copies an artifact with every version under its number, each without its origin, as a new
+   * artifact shared in `threadId` for as long as it lasts: a fork's copy, whose `@N` addresses
+   * still resolve. The files are reused, not copied. Throws `artifact_not_found` without the
+   * source and `artifact_exists` when the id is taken.
+   */
+  copy(input: CopyArtifactInput): Promise<ArtifactRecord>
   /**
    * The latest version of each artifact whose latest version has an address to this artifact, so
    * a new version can tell which artifacts it breaks. Ordered by artifact id.
@@ -199,11 +265,29 @@ export interface ArtifactStorage {
   findFrameGrant(input: FindArtifactFrameGrantInput): Promise<ArtifactFrameGrantRecord | null>
   /** Deletes up to `limit` grants that expired before `expiredBefore`, and returns the count. */
   deleteExpiredFrameGrants(input: DeleteExpiredArtifactFrameGrantsInput): Promise<number>
-  /** Deletes the artifact, every version, and its frame grants. `false` when it does not exist. */
+  /** A value a page keeps for a reader, or null when it keeps none under the key. */
+  getState(input: ArtifactStateKeyInput): Promise<ArtifactStateEntry | null>
+  /**
+   * Keeps a value under its key, replacing one there. Throws `artifact_not_found`, or
+   * `artifact_state_full` when the value, or the reader's keys or bytes with it, would pass
+   * `ARTIFACT_STATE_LIMITS`, checked in the same transaction as the write.
+   */
+  setState(input: SetArtifactStateInput): Promise<void>
+  /** `false` when there was no value under the key. */
+  deleteState(input: ArtifactStateKeyInput): Promise<boolean>
+  /** Every value a page keeps for a reader, by key. */
+  listState(input: ArtifactStateScope): Promise<ArtifactStateEntry[]>
+  /** Deletes every value a page keeps for a reader, and returns how many. */
+  clearState(input: ArtifactStateScope): Promise<number>
+  /**
+   * Deletes the artifact, every version, its frame grants, and what it keeps for its readers.
+   * `false` when it does not exist.
+   */
   delete(input: DeleteArtifactInput): Promise<boolean>
   /**
    * Deletes the versions a run published and returns how many. An artifact left without versions
-   * is deleted; one that lost its latest version points at its newest remaining one.
+   * is deleted; one that lost its latest version points at its newest remaining one. One left
+   * without a version from the run's thread is no longer shared there, unless it was copied for it.
    */
   deleteVersionsByOrigin(input: DeleteArtifactVersionsByOriginInput): Promise<number>
 }

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

@@ -11,6 +11,7 @@ import type {
   InvitationRecord,
   SessionRecord,
   SuspendUserAndRevokeSessionsInput,
+  UpdateAuthUserResult,
   UserIdentityRecord,
   UserRecord,
 } from "../types"
@@ -241,6 +242,7 @@ export class InMemoryAuthStorage implements AuthStorage {
       consumedAt: completedAt,
     })
 
+    const previousUser = existingUser ? cloneRecord(existingUser) : null
     let user = existingUser
     if (!user) {
       user = {
@@ -283,6 +285,7 @@ export class InMemoryAuthStorage implements AuthStorage {
       session: cloneRecord(session),
       invitation: invitation.invitation ? cloneRecord(invitation.invitation) : undefined,
       groupMemberships: memberships.map(cloneRecord),
+      previousUser,
     }
   }
 
@@ -366,6 +369,7 @@ export class InMemoryAuthStorage implements AuthStorage {
 
     this.consumeOidcAttempt(input, completedAt, projectId)
 
+    const previousUser = user ? cloneRecord(user) : null
     if (!user) {
       user = {
         id: newUserId ?? assertNonEmpty(input.newUserId, "User id"),
@@ -378,6 +382,8 @@ export class InMemoryAuthStorage implements AuthStorage {
         updatedAt: completedAt,
       }
       this.state.users.set(userKey(projectId, user.id), cloneRecord(user))
+    } else {
+      user = this.refreshProviderProfile(user, input, completedAt)
     }
 
     const invitation = this.acceptInvitationAndApplyGroups({
@@ -428,12 +434,13 @@ export class InMemoryAuthStorage implements AuthStorage {
       identity: cloneRecord(nextIdentity),
       invitation: invitation.invitation ? cloneRecord(invitation.invitation) : undefined,
       groupMemberships: memberships.map(cloneRecord),
+      previousUser,
     }
   }
 
   async suspendUserAndRevokeSessions(
     input: SuspendUserAndRevokeSessionsInput
-  ): Promise<UserRecord> {
+  ): Promise<UpdateAuthUserResult> {
     const key = userKey(input.projectId, input.userId)
     const existing = this.state.users.get(key)
 
@@ -452,7 +459,25 @@ export class InMemoryAuthStorage implements AuthStorage {
     this.state.users.set(key, cloneRecord(next))
     revokeActiveSessionsForUser(this.state, input.projectId, input.userId, input.suspendedAt)
 
-    return cloneRecord(next)
+    return { user: cloneRecord(next), previousUser: cloneRecord(existing) }
+  }
+
+  // The identity provider owns the name and picture it sends: every sign-in overwrites them, and
+  // one it leaves out keeps the stored value.
+  private refreshProviderProfile(
+    user: UserRecord,
+    input: CompleteOidcSignInInput,
+    updatedAt: Date
+  ): UserRecord {
+    const displayName = input.displayName ?? user.displayName
+    const avatarUrl = input.avatarUrl ?? user.avatarUrl
+    if (displayName === user.displayName && avatarUrl === user.avatarUrl) {
+      return user
+    }
+
+    const next: UserRecord = { ...user, displayName, avatarUrl, updatedAt: cloneDate(updatedAt) }
+    this.state.users.set(userKey(user.projectId, user.id), cloneRecord(next))
+    return next
   }
 
   private acceptInvitationAndApplyGroups(input: {

package/src/storage/auth/in-memory/users.ts

@@ -6,6 +6,7 @@ import type {
   ListAuthUsersInput,
   ListAuthUsersResult,
   UpdateAuthUserProfileInput,
+  UpdateAuthUserResult,
   UpdateAuthUserStatusInput,
   UserRecord,
 } from "../types"
@@ -69,6 +70,16 @@ export class InMemoryAuthUserStore implements AuthUserStore {
     return cloneOptionalRecord(record)
   }
 
+  async getByIds(params: {
+    readonly projectId: string
+    readonly ids: readonly string[]
+  }): Promise<readonly UserRecord[]> {
+    return [...new Set(params.ids)].flatMap((id) => {
+      const record = this.state.users.get(userKey(params.projectId, id))
+      return record ? [cloneRecord(record)] : []
+    })
+  }
+
   async getByEmail(params: {
     readonly projectId: string
     readonly email: string
@@ -76,7 +87,7 @@ export class InMemoryAuthUserStore implements AuthUserStore {
     return cloneOptionalRecord(getUserByEmail(this.state, params.projectId, params.email))
   }
 
-  async updateProfile(input: UpdateAuthUserProfileInput): Promise<UserRecord> {
+  async updateProfile(input: UpdateAuthUserProfileInput): Promise<UpdateAuthUserResult> {
     const key = userKey(input.projectId, input.id)
     const existing = this.state.users.get(key)
 
@@ -87,17 +98,23 @@ export class InMemoryAuthUserStore implements AuthUserStore {
       )
     }
 
+    const displayName = profileValue(input.displayName, existing.displayName)
+    const avatarUrl = profileValue(input.avatarUrl, existing.avatarUrl)
+    if (displayName === existing.displayName && avatarUrl === existing.avatarUrl) {
+      return { user: cloneRecord(existing), previousUser: cloneRecord(existing) }
+    }
+
     const next: UserRecord = {
       ...existing,
-      displayName: input.displayName,
-      avatarUrl: input.avatarUrl,
+      displayName,
+      avatarUrl,
       updatedAt: dateOrNow(input.updatedAt),
     }
     this.state.users.set(key, cloneRecord(next))
-    return cloneRecord(next)
+    return { user: cloneRecord(next), previousUser: cloneRecord(existing) }
   }
 
-  async updateStatus(input: UpdateAuthUserStatusInput): Promise<UserRecord> {
+  async updateStatus(input: UpdateAuthUserStatusInput): Promise<UpdateAuthUserResult> {
     const key = userKey(input.projectId, input.id)
     const existing = this.state.users.get(key)
 
@@ -114,7 +131,7 @@ export class InMemoryAuthUserStore implements AuthUserStore {
       updatedAt: dateOrNow(input.updatedAt),
     }
     this.state.users.set(key, cloneRecord(next))
-    return cloneRecord(next)
+    return { user: cloneRecord(next), previousUser: cloneRecord(existing) }
   }
 
   async list(input: ListAuthUsersInput): Promise<ListAuthUsersResult> {
@@ -123,10 +140,12 @@ export class InMemoryAuthUserStore implements AuthUserStore {
     }
 
     const statuses = input.statuses ? new Set(input.statuses) : null
+    const search = input.search?.toLowerCase()
     const order = input.order ?? "desc"
     const rows = [...this.state.users.values()]
       .filter((user) => user.projectId === input.projectId)
       .filter((user) => (statuses ? statuses.has(user.status) : true))
+      .filter((user) => (search === undefined ? true : userMatches(user, search)))
       .sort((a, b) => compareByCreatedAt(a, b, order))
 
     const page = paginate(rows, input)
@@ -137,3 +156,18 @@ export class InMemoryAuthUserStore implements AuthUserStore {
     }
   }
 }
+
+// Omitted keeps the current value, and `null` clears it.
+function profileValue(
+  value: string | null | undefined,
+  current: string | undefined
+): string | undefined {
+  return value === undefined ? current : (value ?? undefined)
+}
+
+function userMatches(user: UserRecord, search: string): boolean {
+  return (
+    (user.displayName?.toLowerCase().includes(search) ?? false) ||
+    user.email.toLowerCase().includes(search)
+  )
+}

package/src/storage/auth/index.ts

@@ -57,6 +57,7 @@ export type {
   SuspendUserAndRevokeSessionsInput,
   UpdateAuthServiceAccountInput,
   UpdateAuthUserProfileInput,
+  UpdateAuthUserResult,
   UpdateAuthUserStatusInput,
   UpsertAuthGroupMembershipInput,
   UpsertAuthServiceAccountGroupMembershipInput,

package/src/storage/auth/types.ts

@@ -190,14 +190,21 @@ export interface CreateAuthUserInput {
   readonly updatedAt?: Date
 }
 
+/** Omitted fields stay unchanged, and `null` clears one. */
 export interface UpdateAuthUserProfileInput {
   readonly projectId: string
   readonly id: string
-  readonly displayName?: string
-  readonly avatarUrl?: string
+  readonly displayName?: string | null
+  readonly avatarUrl?: string | null
   readonly updatedAt?: Date
 }
 
+/** A change to one user, with the user as the change found them, read in the same atomic step. */
+export interface UpdateAuthUserResult {
+  readonly user: UserRecord
+  readonly previousUser: UserRecord
+}
+
 export interface UpdateAuthUserStatusInput {
   readonly projectId: string
   readonly id: string
@@ -208,6 +215,12 @@ export interface UpdateAuthUserStatusInput {
 export interface ListAuthUsersInput {
   readonly projectId: string
   readonly statuses?: readonly UserStatus[]
+  /**
+   * Keep users whose display name or email contains this text, ignoring case. Matched literally:
+   * `%` and `_` are plain characters. `total` and `hasMore` count only the matches. SQLite ignores
+   * case for ASCII letters only.
+   */
+  readonly search?: string
   readonly limit?: number
   readonly offset?: number
   readonly order?: "asc" | "desc"
@@ -423,8 +436,11 @@ export interface CompleteDeviceAuthorizationInput {
   readonly projectId: string
   readonly id: string
   readonly deviceCodeHash: string
-  /** The bearer session to start for the approving user. */
-  readonly session: CreateAuthSessionInput & { readonly bearer: BearerSessionState }
+  /**
+   * The session to start for the approving user: a bearer session for a native client, or a
+   * cookie session for a browser that asked to be approved from another one.
+   */
+  readonly session: CreateAuthSessionInput
   readonly completedAt: Date
 }
 
@@ -457,6 +473,10 @@ export interface CompleteOidcSignInInput {
    * links the user who has this email, or claims this email's invitation for a new user.
    */
   readonly email: string
+  /**
+   * The name and picture the provider sends. Every sign-in sets them on the user, and one left out
+   * keeps the stored value. `updatedAt` moves only when one of them changes.
+   */
   readonly displayName?: string
   readonly avatarUrl?: string
   readonly claims?: Readonly<Record<string, unknown>>
@@ -478,6 +498,11 @@ export interface CompleteSignInResult {
   readonly identity?: UserIdentityRecord
   readonly invitation?: InvitationRecord
   readonly groupMemberships: readonly GroupMembershipRecord[]
+  /**
+   * The user as this sign-in found them, before it changed their profile, or `null` when this
+   * sign-in created them.
+   */
+  readonly previousUser: UserRecord | null
 }
 
 export interface SuspendUserAndRevokeSessionsInput {
@@ -489,12 +514,21 @@ export interface SuspendUserAndRevokeSessionsInput {
 export interface AuthUserStore {
   create(input: CreateAuthUserInput): Promise<UserRecord>
   getById(params: { readonly projectId: string; readonly id: string }): Promise<UserRecord | null>
+  /** The users of the project with these ids, in any order. Ids no user has are skipped. */
+  getByIds(params: {
+    readonly projectId: string
+    readonly ids: readonly string[]
+  }): Promise<readonly UserRecord[]>
   getByEmail(params: {
     readonly projectId: string
     readonly email: string
   }): Promise<UserRecord | null>
-  updateProfile(input: UpdateAuthUserProfileInput): Promise<UserRecord>
-  updateStatus(input: UpdateAuthUserStatusInput): Promise<UserRecord>
+  /**
+   * Update only the provided fields; omitted fields must remain unchanged atomically. When no
+   * value changes, nothing is written, so `updatedAt` stays as it was.
+   */
+  updateProfile(input: UpdateAuthUserProfileInput): Promise<UpdateAuthUserResult>
+  updateStatus(input: UpdateAuthUserStatusInput): Promise<UpdateAuthUserResult>
   list(input: ListAuthUsersInput): Promise<ListAuthUsersResult>
 }
 
@@ -763,5 +797,7 @@ export interface AuthStorage {
   completeDeviceAuthorization(
     input: CompleteDeviceAuthorizationInput
   ): Promise<CompleteDeviceAuthorizationResult>
-  suspendUserAndRevokeSessions(input: SuspendUserAndRevokeSessionsInput): Promise<UserRecord>
+  suspendUserAndRevokeSessions(
+    input: SuspendUserAndRevokeSessionsInput
+  ): Promise<UpdateAuthUserResult>
 }

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

@@ -4,8 +4,10 @@ import { ExecutionStorageError } from "./errors"
 import { compareExecutionCreation } from "./provider"
 import type {
   CreateExecutionInput,
+  ExecutionDescendant,
   ExecutionRecord,
   ExecutionStorage,
+  ListExecutionDescendantsInput,
   ListSessionExecutionsInput,
   SessionExecutions,
 } from "./types"
@@ -116,6 +118,36 @@ export class InMemoryExecutionStorage implements ExecutionStorage {
       }
     })
   }
+
+  async listDescendants(
+    input: ListExecutionDescendantsInput
+  ): Promise<readonly ExecutionDescendant[]> {
+    return this.runRootOperation(() => {
+      const rows = [...this.rows.values()].filter((row) => row.projectId === input.projectId)
+      const seen = new Set(input.executionIds)
+      const found: ExecutionRecord[] = []
+
+      let parents = new Set(input.executionIds)
+      while (parents.size > 0) {
+        const level = rows.filter(
+          (row) =>
+            row.source.type === "execution" &&
+            parents.has(row.source.executionId) &&
+            !seen.has(row.id)
+        )
+
+        for (const row of level) seen.add(row.id)
+        found.push(...level)
+        parents = new Set(level.map((row) => row.id))
+      }
+
+      return found
+        .flatMap((row) =>
+          row.source.type === "execution" ? [{ id: row.id, parentId: row.source.executionId }] : []
+        )
+        .sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0))
+    })
+  }
 }
 
 function isFromSession(

package/src/storage/executions/index.ts

@@ -11,9 +11,11 @@ export type {
   CreateExecutionInput,
   DurableExecutionExecutor,
   DurableExecutionSource,
+  ExecutionDescendant,
   ExecutionRecord,
   ExecutionSessionRef,
   ExecutionStorage,
+  ListExecutionDescendantsInput,
   ListSessionExecutionsInput,
   SessionExecutions,
 } from "./types"

package/src/storage/executions/types.ts

@@ -72,6 +72,17 @@ export interface SessionExecutions {
   readonly truncated: boolean
 }
 
+export interface ListExecutionDescendantsInput {
+  readonly projectId: string
+  readonly executionIds: readonly string[]
+}
+
+/** An execution below the ones asked about, and the execution that caused it. */
+export interface ExecutionDescendant {
+  readonly id: string
+  readonly parentId: string
+}
+
 /** Immutable execution ledger. Records can be created and read, never updated or deleted. */
 export interface ExecutionStorage {
   create(input: CreateExecutionInput): Promise<ExecutionRecord>
@@ -81,4 +92,10 @@ export interface ExecutionStorage {
   }): Promise<ExecutionRecord | null>
   /** What one session started: its roots in a window, and what they caused through `source`. */
   listBySession(input: ListSessionExecutionsInput): Promise<SessionExecutions>
+  /**
+   * Everything these executions caused through `source`, at any depth, each once and without the
+   * executions asked about, ordered by id. Unbounded, as a sum over the tree needs all of it, so
+   * each is only its id and its parent's.
+   */
+  listDescendants(input: ListExecutionDescendantsInput): Promise<readonly ExecutionDescendant[]>
 }