@sixb/core 0.1.1 → 0.1.3

package/src/storage/agents/types.ts

@@ -1,5 +1,6 @@
 import type { AgentMessage, AgentMessagePart, AgentMessageRole } from "../../agents/message"
 import type { Principal } from "../../auth"
+import type { SixbErrorCode, SixbFailure } from "../../errors/types"
 import type { JsonValue } from "../../json"
 
 // ── agent_threads — one conversation with an agent ──────────────────────────────────────────────
@@ -58,16 +59,27 @@ export type AgentExecutionStatus = "queued" | "running" | "succeeded" | "failed"
 
 export type AgentRunStatus = AgentExecutionStatus
 
+/** Error codes an agent execution can persist and expose through its public contract. */
+export const AGENT_RUN_FAILURE_CODES = [
+  "internal.unexpected",
+  "runtime.cancelled",
+  "agent.execution_failed",
+] as const satisfies readonly [SixbErrorCode, ...SixbErrorCode[]]
+
+export type AgentRunFailureCode = (typeof AGENT_RUN_FAILURE_CODES)[number]
+
 /**
- * Why a run ended — our own SDK-independent vocabulary (it mirrors the AI SDK unified finish
- * reasons), so reads are typed and exhaustive without core depending on `ai`. `other`/`unknown` are
- * catch-alls: a provider value we don't recognise still records *that* the run ended.
+ * Why a run ended — our own SDK-independent vocabulary. It includes the AI SDK's unified finish
+ * reasons plus platform-level endings such as `timeout`, so reads are typed and exhaustive without
+ * core depending on `ai`. `other`/`unknown` are catch-alls: an unrecognised provider value still
+ * records *that* the run ended.
  */
 export const AGENT_RUN_FINISH_REASONS = [
   "stop",
   "length",
   "content-filter",
   "tool-calls",
+  "timeout",
   "error",
   "other",
   "unknown",
@@ -90,14 +102,6 @@ export function coerceAgentRunFinishReason(
     : "unknown"
 }
 
-export interface AgentRunUsage {
-  readonly inputTokens?: number
-  readonly outputTokens?: number
-  readonly totalTokens?: number
-  readonly reasoningTokens?: number
-  readonly cachedInputTokens?: number
-}
-
 /** Stable, user-facing diagnostics emitted by the platform while executing a run. */
 export const AGENT_RUN_DIAGNOSTIC_CODES = [
   "output_file_limit_exceeded",
@@ -143,20 +147,20 @@ export interface AgentRunExecution {
 export interface AgentRunRecord {
   readonly id: string
   readonly projectId: string
+  readonly executionId: string
   readonly threadId: string
   readonly agentId: string
   readonly triggerMessageId: string
-  readonly requestedByPrincipal: Principal
-  readonly executionPrincipal?: Extract<Principal, { readonly type: "serviceAccount" }>
+  /** Durable group memberships snapshotted when the run was admitted. */
+  readonly requesterGroupIds: readonly string[]
   readonly status: AgentRunStatus
   readonly modelId?: string
   /** Why the run ended (our own SDK-independent enum). */
   readonly finishReason?: AgentRunFinishReason
-  readonly usage?: AgentRunUsage
   /** Platform diagnostics are transcript annotations, never agent-authored message content. */
   readonly diagnostics?: readonly AgentRunDiagnostic[]
-  /** Failure message when the run did not succeed. */
-  readonly error?: string
+  /** Portable failure snapshot when the run did not succeed. */
+  readonly error?: SixbFailure<AgentRunFailureCode>
   /** Execution attempts: `0` while queued, `1` on first start, incremented on redelivery. */
   readonly attempt: number
   readonly execution?: AgentRunExecution
@@ -168,17 +172,17 @@ export interface AgentRunRecord {
 export interface CreateAgentRunInput {
   readonly id: string
   readonly projectId: string
+  readonly executionId: string
   readonly threadId: string
   readonly agentId: string
   readonly triggerMessageId: string
-  readonly requestedByPrincipal: Principal
+  readonly requesterGroupIds: readonly string[]
   readonly createdAt?: Date
 }
 
 export interface StartAgentRunInput {
   readonly id: string
   readonly projectId: string
-  readonly executionPrincipal?: Extract<Principal, { readonly type: "serviceAccount" }>
   readonly modelId?: string
   readonly execution: AgentRunExecution
   readonly startedAt?: Date
@@ -188,7 +192,7 @@ export interface FinishQueuedAgentRunInput {
   readonly id: string
   readonly projectId: string
   readonly status: "failed" | "cancelled"
-  readonly error?: string
+  readonly error?: SixbFailure<AgentRunFailureCode>
   readonly completedAt?: Date
 }
 
@@ -214,7 +218,6 @@ export type FinishAgentRunInput =
       readonly status: "succeeded"
       readonly modelId?: string
       readonly finishReason?: AgentRunFinishReason
-      readonly usage?: AgentRunUsage
       readonly diagnostics?: readonly AgentRunDiagnostic[]
       readonly completedAt?: Date
     }
@@ -225,9 +228,8 @@ export type FinishAgentRunInput =
       readonly status: "failed" | "cancelled"
       readonly modelId?: string
       readonly finishReason?: AgentRunFinishReason
-      readonly usage?: AgentRunUsage
       readonly diagnostics?: readonly AgentRunDiagnostic[]
-      readonly error?: string
+      readonly error?: SixbFailure<AgentRunFailureCode>
       readonly completedAt?: Date
     }
 
@@ -287,9 +289,17 @@ export interface AppendAgentMessageInput extends AgentMessage {
   readonly completedAt?: Date
 }
 
+export interface DeleteAgentMessagesByRunInput {
+  readonly projectId: string
+  readonly threadId: string
+  readonly runId: string
+}
+
 export interface ListAgentMessagesInput {
   readonly projectId: string
   readonly threadId: string
+  /** Return only messages whose per-thread sequence is greater than this retained boundary. */
+  readonly afterSeq?: number
   readonly roles?: readonly AgentMessageRole[]
   readonly limit?: number
   readonly offset?: number
@@ -302,6 +312,55 @@ export interface ListAgentMessagesResult {
   readonly total: number
 }
 
+// ── agent_context_checkpoints — append-only model-context boundaries ──────────────────────────
+
+export type AgentContextCheckpointReason = "threshold" | "overflow"
+
+/**
+ * A durable summary boundary used only when projecting a thread into model context.
+ *
+ * Checkpoints never replace or mutate transcript messages. Normal thread reads remain authoritative
+ * and complete; the worker reads the latest checkpoint and only the retained message tail.
+ */
+export interface AgentContextCheckpointRecord {
+  readonly id: string
+  readonly projectId: string
+  readonly threadId: string
+  readonly createdByRunId: string
+  readonly previousCheckpointId?: string
+  readonly reason: AgentContextCheckpointReason
+  readonly summary: string
+  readonly summaryFormatVersion: 1
+  readonly summarizedThroughSeq: number
+  readonly observedHeadSeq: number
+  readonly estimatedInputTokensBefore: number
+  readonly estimatedInputTokensAfter: number
+  readonly summaryModelId: string
+  readonly createdAt: Date
+}
+
+export interface CreateAgentContextCheckpointInput {
+  readonly id: string
+  readonly projectId: string
+  readonly threadId: string
+  readonly createdByRunId: string
+  /** Compare-and-swap anchor. `null` means the thread must not have a prior checkpoint. */
+  readonly expectedPreviousCheckpointId: string | null
+  /** Compare-and-swap anchor for the complete transcript observed by the summarizer. */
+  readonly expectedHeadSeq: number
+  /** Current delivery token for `createdByRunId`; stale redeliveries must not write. */
+  readonly executionToken: string
+  readonly reason: AgentContextCheckpointReason
+  readonly summary: string
+  readonly summaryFormatVersion: 1
+  readonly summarizedThroughSeq: number
+  readonly observedHeadSeq: number
+  readonly estimatedInputTokensBefore: number
+  readonly estimatedInputTokensAfter: number
+  readonly summaryModelId: string
+  readonly createdAt?: Date
+}
+
 // ── Store ───────────────────────────────────────────────────────────────────────────────────────
 
 export interface AgentThreadStore {
@@ -337,12 +396,27 @@ export interface AgentRunStore {
 export interface AgentMessageStore {
   /** Insert a message (its `parts` are the canonical content) and bump thread stats. */
   append(input: AppendAgentMessageInput): Promise<AgentMessageRecord>
+  /** Delete every message produced by one run and repair the thread's message stats. */
+  deleteByRunId(input: DeleteAgentMessagesByRunInput): Promise<number>
   getById(params: { projectId: string; id: string }): Promise<AgentMessageRecord | null>
   list(input: ListAgentMessagesInput): Promise<ListAgentMessagesResult>
 }
 
+export interface AgentContextCheckpointStore {
+  /**
+   * Append one checkpoint after atomically validating run ownership and both transcript anchors.
+   * Repeating the same payload for the same creating run is idempotent.
+   */
+  create(input: CreateAgentContextCheckpointInput): Promise<AgentContextCheckpointRecord>
+  getLatest(input: {
+    readonly projectId: string
+    readonly threadId: string
+  }): Promise<AgentContextCheckpointRecord | null>
+}
+
 export interface AgentStorage {
   readonly threads: AgentThreadStore
   readonly runs: AgentRunStore
   readonly messages: AgentMessageStore
+  readonly checkpoints: AgentContextCheckpointStore
 }