@sixb/core 0.1.1 → 0.1.3

package/src/agents/request.ts

@@ -1,19 +1,28 @@
+import { randomUUID } from "node:crypto"
 import type { Principal } from "../auth"
 import { SYSTEM_PRINCIPAL } from "../auth"
+import { snapshotRequesterGroupIds } from "../auth/attribution"
 import { assertAuthorized } from "../authorization"
 import type { FileRef } from "../blob-storage"
+import { createAgentExecutionRecord } from "../execution/agent"
+import { ensureExecutionRecord, executionRecordInputFromRuntime } from "../execution/durable"
+import type { ExecutionContext } from "../execution/types"
 import type { SixbRuntimeContext } from "../runtime/types"
+import type { SecurityDefinitionCatalog } from "../security"
 import {
   type AgentRunRecord,
   type AgentStorage,
   AgentStorageError,
   type AgentThreadRecord,
 } from "../storage/agents"
+import type { CreateExecutionInput } from "../storage/executions"
+import { ensureAgentExecutionIdentity, resolveAgentExecutionAuthorization } from "./authority"
 import type { AgentContextEntryInput } from "./context"
 import { resolveAgentContextParts } from "./context-resolution"
 import { dispatchQueuedAgentRuns } from "./dispatch"
 import { AgentRequestError } from "./errors"
 import { createAgentMessageId, createAgentRunId, createAgentThreadId } from "./ids"
+import { publishAgentRunActivity } from "./streams"
 import type { AgentDefinition } from "./types"
 
 export interface RequestAgentRunInput {
@@ -31,7 +40,7 @@ export interface RequestAgentRunInput {
   readonly title?: string
   /** Explicit id for the trigger (user) message. Defaults to a generated id. */
   readonly messageId?: string
-  /** Owner principal for a newly created thread. Defaults to the system principal until auth lands. */
+  /** Caller principal for privileged integrations; scoped runtimes use their authorization principal. */
   readonly principal?: Principal
 }
 
@@ -54,6 +63,8 @@ export interface RequestAgentRunResult {
  */
 export async function requestAgentRun(
   runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  security: SecurityDefinitionCatalog,
   agent: AgentDefinition,
   input: RequestAgentRunInput
 ): Promise<RequestAgentRunResult> {
@@ -65,8 +76,9 @@ export async function requestAgentRun(
 
   const agents = requireAgentStorage(runtime)
   const projectId = runtime.projectId
-  const principal = input.principal ?? SYSTEM_PRINCIPAL
-
+  // A scoped runtime is authoritative for caller identity. `input.principal` remains available to
+  // privileged server integrations that have already authenticated their request.
+  const principal = runtime.authorization?.principal ?? input.principal ?? SYSTEM_PRINCIPAL
   const { thread, createdThread } = await resolveThread(agents, {
     projectId,
     agentId: agent.id,
@@ -84,6 +96,20 @@ export async function requestAgentRun(
   }
 
   const runId = createAgentRunId()
+  const durableExecution = await prepareDurableAgentExecution(
+    runtime,
+    execution,
+    security,
+    agent,
+    runId
+  )
+  const requesterGroupIds = durableExecution.requestedBy
+    ? await snapshotRequesterGroupIds({
+        auth: runtime.storage.auth,
+        projectId,
+        principal: durableExecution.requestedBy,
+      })
+    : []
   const triggerMessageId = input.messageId ?? createAgentMessageId()
   let run: AgentRunRecord
   try {
@@ -95,6 +121,7 @@ export async function requestAgentRun(
           "[Sixb] Agent storage is not configured."
         )
       }
+      await tx.executions.create(durableExecution)
       await agents.messages.append({
         id: triggerMessageId,
         projectId,
@@ -111,10 +138,11 @@ export async function requestAgentRun(
       return agents.runs.create({
         id: runId,
         projectId,
+        executionId: durableExecution.id,
         threadId: thread.id,
         agentId: agent.id,
         triggerMessageId,
-        requestedByPrincipal: principal,
+        requesterGroupIds,
       })
     })
   } catch (error) {
@@ -124,17 +152,129 @@ export async function requestAgentRun(
     throw error
   }
 
-  // The queued run is also the durable dispatch intent. Publication is best-effort here; an agent
-  // worker scans queued runs and retries with the same deterministic queue job id.
-  let jobId: string | undefined
+  await publishRunActivity(runtime, run)
+  const jobId = await dispatchAgentRun(runtime, agents, runId)
+
+  return {
+    run,
+    ...(jobId ? { jobId } : {}),
+    createdThread,
+  }
+}
+
+/** Retry a failed turn as a new child execution while reusing its immutable trigger message. */
+export async function retryAgentRun(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  security: SecurityDefinitionCatalog,
+  agent: AgentDefinition,
+  failedRun: AgentRunRecord
+): Promise<RequestAgentRunResult> {
+  assertAuthorized(runtime, { kind: "agent.run", agentId: agent.id })
+  if (failedRun.agentId !== agent.id) {
+    throw new AgentRequestError(
+      "agent_not_found",
+      `[Sixb] Agent run '${failedRun.id}' does not belong to agent '${agent.id}'.`
+    )
+  }
+  if (failedRun.status !== "failed") {
+    throw new AgentRequestError(
+      "run_not_retryable",
+      `[Sixb] Only failed Agent runs can be retried.`
+    )
+  }
+
+  const agents = requireAgentStorage(runtime)
+  const runId = createAgentRunId()
+  const durableExecution = await prepareDurableAgentExecution(
+    runtime,
+    execution,
+    security,
+    agent,
+    runId
+  )
+  const requesterGroupIds = durableExecution.requestedBy
+    ? await snapshotRequesterGroupIds({
+        auth: runtime.storage.auth,
+        projectId: runtime.projectId,
+        principal: durableExecution.requestedBy,
+      })
+    : []
+  const run = await runtime.storage.transaction(async (tx) => {
+    const agents = tx.agents
+    if (!agents) {
+      throw new AgentRequestError("storage_unavailable", "[Sixb] Agent storage is not configured.")
+    }
+    await agents.messages.deleteByRunId({
+      projectId: runtime.projectId,
+      threadId: failedRun.threadId,
+      runId: failedRun.id,
+    })
+    await tx.executions.create(durableExecution)
+    return agents.runs.create({
+      id: runId,
+      projectId: runtime.projectId,
+      executionId: durableExecution.id,
+      threadId: failedRun.threadId,
+      agentId: agent.id,
+      triggerMessageId: failedRun.triggerMessageId,
+      requesterGroupIds,
+    })
+  })
+  await publishRunActivity(runtime, run)
+  const jobId = await dispatchAgentRun(runtime, agents, runId)
+  return { run, ...(jobId ? { jobId } : {}), createdThread: false }
+}
+
+async function prepareDurableAgentExecution(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  security: SecurityDefinitionCatalog,
+  agent: AgentDefinition,
+  runId: string
+): Promise<CreateExecutionInput> {
+  const identity = await ensureAgentExecutionIdentity({
+    auth: runtime.storage.auth,
+    projectId: runtime.projectId,
+    agent,
+  })
+  const resolved = await resolveAgentExecutionAuthorization({
+    auth: runtime.storage.auth,
+    projectId: runtime.projectId,
+    agentId: agent.id,
+    authorizationRef: { type: "principal", principal: identity.principal },
+    security,
+  })
+  const parent = await ensureExecutionRecord(
+    runtime.storage.executions,
+    executionRecordInputFromRuntime({
+      execution,
+      runtimeAuthorization: runtime.runtimeAuthorization,
+    })
+  )
+  return createAgentExecutionRecord({
+    id: `exec_${randomUUID()}`,
+    parent,
+    agentId: agent.id,
+    runId,
+    principal: resolved.identity.principal,
+  })
+}
+
+async function dispatchAgentRun(
+  runtime: SixbRuntimeContext,
+  agents: AgentStorage,
+  runId: string
+): Promise<string | undefined> {
+  // The queued run is the durable dispatch intent. Publication is best-effort; workers reconcile
+  // it with the same deterministic queue job id if the queue is temporarily unavailable.
   try {
     const dispatch = await dispatchQueuedAgentRuns({
-      projectId,
+      projectId: runtime.projectId,
       storage: agents,
       queue: runtime.queues.agents,
       runIds: [runId],
     })
-    jobId = dispatch.dispatched[0]?.jobId
     const failure = dispatch.failures[0]
     if (failure) {
       console.error(
@@ -142,14 +282,19 @@ export async function requestAgentRun(
         failure.error
       )
     }
+    return dispatch.dispatched[0]?.jobId
   } catch (error) {
     console.error(`[Sixb] Could not dispatch queued agent run '${runId}'; retrying later.`, error)
+    return undefined
   }
+}
 
-  return {
-    run,
-    ...(jobId ? { jobId } : {}),
-    createdThread,
+/** Activity delivery is observational: durable run admission remains successful if the feed is down. */
+async function publishRunActivity(runtime: SixbRuntimeContext, run: AgentRunRecord): Promise<void> {
+  try {
+    await publishAgentRunActivity(runtime.broker, run)
+  } catch (error) {
+    console.error(`[Sixb] Agent run '${run.id}' activity stream publish failed:`, error)
   }
 }
 

package/src/agents/streams.ts

@@ -1,6 +1,12 @@
 import type { Broker, BrokerStreamDefinition } from "../broker"
-import type { JsonValue } from "../json"
-import type { AgentRunRecord } from "../storage/agents/types"
+import { parseSixbFailure } from "../errors/internal"
+import type { SixbFailure } from "../errors/types"
+import { isJsonValue, isPlainRecord, type JsonValue } from "../json"
+import {
+  AGENT_RUN_FAILURE_CODES,
+  type AgentRunFailureCode,
+  type AgentRunRecord,
+} from "../storage/agents/types"
 
 export const AGENT_RUN_STREAM_SCHEMA_VERSION = 1 as const
 export const DEFAULT_AGENT_RUN_STREAM_RETENTION = {
@@ -8,6 +14,86 @@ export const DEFAULT_AGENT_RUN_STREAM_RETENTION = {
   maxRecords: 5_000,
 } as const
 
+export const AGENT_ACTIVITY_STREAM_SCHEMA_VERSION = 1 as const
+export const AGENT_ACTIVITY_STREAM_ID = "agents.activity" as const
+export const DEFAULT_AGENT_ACTIVITY_STREAM_RETENTION = {
+  maxAgeMs: 24 * 60 * 60 * 1000, // 24 hours
+  maxRecords: 10_000,
+} as const
+
+export interface AgentRunActivityEvent {
+  readonly schemaVersion: typeof AGENT_ACTIVITY_STREAM_SCHEMA_VERSION
+  readonly type: "agent.run.activity"
+  readonly projectId: string
+  readonly runId: string
+  readonly threadId: string
+  readonly agentId: string
+  readonly status: AgentRunRecord["status"]
+  readonly attempt: number
+  readonly occurredAt: string
+}
+
+export function agentActivityStreamDefinition(): BrokerStreamDefinition {
+  return {
+    id: AGENT_ACTIVITY_STREAM_ID,
+    retention: DEFAULT_AGENT_ACTIVITY_STREAM_RETENTION,
+  }
+}
+
+export function agentRunActivityEvent(
+  run: AgentRunRecord,
+  occurredAt: Date = new Date()
+): AgentRunActivityEvent {
+  return {
+    schemaVersion: AGENT_ACTIVITY_STREAM_SCHEMA_VERSION,
+    type: "agent.run.activity",
+    projectId: run.projectId,
+    runId: run.id,
+    threadId: run.threadId,
+    agentId: run.agentId,
+    status: run.status,
+    attempt: run.attempt,
+    occurredAt: occurredAt.toISOString(),
+  }
+}
+
+export function isAgentRunActivityEvent(value: unknown): value is AgentRunActivityEvent {
+  return (
+    isPlainRecord(value) &&
+    value.schemaVersion === AGENT_ACTIVITY_STREAM_SCHEMA_VERSION &&
+    value.type === "agent.run.activity" &&
+    typeof value.projectId === "string" &&
+    typeof value.runId === "string" &&
+    typeof value.threadId === "string" &&
+    typeof value.agentId === "string" &&
+    isAgentRunStatus(value.status) &&
+    typeof value.attempt === "number" &&
+    Number.isFinite(value.attempt) &&
+    typeof value.occurredAt === "string"
+  )
+}
+
+export async function publishAgentRunActivity(broker: Broker, run: AgentRunRecord): Promise<void> {
+  const event = agentRunActivityEvent(run)
+  await broker.ensureStream({
+    projectId: run.projectId,
+    stream: agentActivityStreamDefinition(),
+  })
+  await broker.append({
+    projectId: run.projectId,
+    streamId: AGENT_ACTIVITY_STREAM_ID,
+    records: [
+      {
+        name: event.type,
+        key: event.threadId,
+        // The event is composed only of validated JSON primitives.
+        payload: event as unknown as JsonValue,
+        idempotencyKey: `${event.runId}:${event.attempt}:${event.status}`,
+      },
+    ],
+  })
+}
+
 export type AgentRunStreamId = `agents.runs.${string}`
 
 export function agentRunStreamId(runId: string): AgentRunStreamId {
@@ -100,6 +186,9 @@ export async function subscribeAgentRunCancel(
   )
 }
 
+/** Exact portable failure exposed by a terminal Agent run stream event. */
+export type AgentRunFailure = SixbFailure<AgentRunFailureCode>
+
 export type AgentRunStreamEvent =
   | (AgentRunStreamEventBase & {
       readonly type: "agent.run.started"
@@ -118,7 +207,7 @@ export type AgentRunStreamEvent =
       readonly type: "agent.run.finished"
       readonly status: "succeeded" | "failed" | "cancelled"
       readonly finishReason?: string
-      readonly error?: string
+      readonly error?: AgentRunFailure
     })
 
 export type AgentRunFinishedEvent = Extract<AgentRunStreamEvent, { type: "agent.run.finished" }>
@@ -154,6 +243,63 @@ export function agentRunFinishedEvent(
   }
 }
 
+/** Validate an Agent stream payload using the same contract its producers use. */
+export function isAgentRunStreamEvent(value: unknown): value is AgentRunStreamEvent {
+  if (
+    !isPlainRecord(value) ||
+    value.schemaVersion !== AGENT_RUN_STREAM_SCHEMA_VERSION ||
+    typeof value.projectId !== "string" ||
+    typeof value.runId !== "string" ||
+    typeof value.threadId !== "string" ||
+    typeof value.agentId !== "string" ||
+    typeof value.attempt !== "number" ||
+    !Number.isFinite(value.attempt) ||
+    typeof value.occurredAt !== "string" ||
+    typeof value.type !== "string"
+  ) {
+    return false
+  }
+
+  switch (value.type) {
+    case "agent.run.started":
+      return value.modelId === undefined || typeof value.modelId === "string"
+    case "agent.ui.chunk":
+      return (
+        Number.isInteger(value.chunkIndex) &&
+        Object.hasOwn(value, "chunk") &&
+        isJsonValue(value.chunk)
+      )
+    case "agent.message.finalized":
+      return typeof value.messageId === "string"
+    case "agent.run.finished":
+      return (
+        isTerminalAgentRunStatus(value.status) &&
+        (value.finishReason === undefined || typeof value.finishReason === "string") &&
+        (value.error === undefined || isAgentRunFailure(value.error))
+      )
+    default:
+      return false
+  }
+}
+
+function isTerminalAgentRunStatus(value: unknown): value is "succeeded" | "failed" | "cancelled" {
+  return value === "succeeded" || value === "failed" || value === "cancelled"
+}
+
+function isAgentRunStatus(value: unknown): value is AgentRunRecord["status"] {
+  return value === "queued" || value === "running" || isTerminalAgentRunStatus(value)
+}
+
+function isAgentRunFailure(value: unknown): value is AgentRunFailure {
+  if (!isPlainRecord(value)) return false
+  try {
+    parseSixbFailure(value, AGENT_RUN_FAILURE_CODES)
+    return true
+  } catch {
+    return false
+  }
+}
+
 /** Single owner of the idempotency-key vocabulary for agent run stream records. */
 export function agentRunStreamIdempotencyKey(event: AgentRunStreamEvent): string {
   switch (event.type) {
@@ -191,4 +337,5 @@ export async function publishAgentRunFinished(broker: Broker, run: AgentRunRecor
       },
     ],
   })
+  await publishAgentRunActivity(broker, run)
 }

package/src/agents/thread-context-projection.ts

@@ -0,0 +1,93 @@
+import type { AgentContextCheckpointRecord, AgentMessageRecord } from "../storage/agents/types"
+import type { AgentMessage } from "./message"
+
+/** A model-only message. Persisted tail messages carry `id`; the synthetic summary does not. */
+export interface AgentThreadModelContextMessage extends AgentMessage {
+  readonly id?: string
+}
+
+export interface ProjectAgentThreadModelContextInput {
+  readonly checkpoint: AgentContextCheckpointRecord | null
+  /** Complete retained tail, ordered by ascending per-thread sequence. */
+  readonly messages: readonly AgentMessageRecord[]
+}
+
+/**
+ * Build the bounded, model-only view of a durable thread.
+ *
+ * The function is deliberately pure: storage chooses the latest checkpoint and reads its retained
+ * tail; this function validates that projection and prepends one synthetic user-role summary.
+ */
+export function projectAgentThreadModelContext(
+  input: ProjectAgentThreadModelContextInput
+): readonly AgentThreadModelContextMessage[] {
+  const { checkpoint, messages } = input
+  if (!checkpoint) return messages
+
+  assertConsistentCheckpointProjection(checkpoint, messages)
+  return [
+    {
+      role: "user",
+      parts: [{ type: "text", text: serializeThreadSummary(checkpoint.summary) }],
+    },
+    ...messages,
+  ]
+}
+
+function assertConsistentCheckpointProjection(
+  checkpoint: AgentContextCheckpointRecord,
+  messages: readonly AgentMessageRecord[]
+): void {
+  if (checkpoint.summaryFormatVersion !== 1 || checkpoint.summary.trim().length === 0) {
+    throw projectionError(checkpoint, "has an invalid summary")
+  }
+  if (checkpoint.summarizedThroughSeq >= checkpoint.observedHeadSeq) {
+    throw projectionError(checkpoint, "does not retain its observed head")
+  }
+  if (messages.length === 0) {
+    throw projectionError(checkpoint, "has no retained messages")
+  }
+
+  let expectedSeq = checkpoint.summarizedThroughSeq + 1
+  for (const message of messages) {
+    if (message.projectId !== checkpoint.projectId || message.threadId !== checkpoint.threadId) {
+      throw projectionError(checkpoint, "contains a message from another thread")
+    }
+    if (message.seq !== expectedSeq) {
+      throw projectionError(checkpoint, `has a sequence gap before message '${message.id}'`)
+    }
+    expectedSeq += 1
+  }
+
+  if (messages[0]?.role !== "user") {
+    throw projectionError(checkpoint, "does not begin at a user turn boundary")
+  }
+  if ((messages.at(-1)?.seq ?? 0) < checkpoint.observedHeadSeq) {
+    throw projectionError(checkpoint, "ends before the checkpoint's observed head")
+  }
+}
+
+function serializeThreadSummary(summary: string): string {
+  return [
+    "The earlier conversation was compacted into this continuation summary.",
+    "",
+    "<sixb_thread_summary>",
+    escapeXml(summary),
+    "</sixb_thread_summary>",
+  ].join("\n")
+}
+
+function projectionError(checkpoint: AgentContextCheckpointRecord, detail: string): Error {
+  return new Error(
+    `[Sixb] Agent context checkpoint '${checkpoint.id}' for thread '${checkpoint.threadId}' ${detail}.`
+  )
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;")
+}

package/src/agents/tool-definition.ts

@@ -1,5 +1,11 @@
-import { cloneJsonValue, getInvalidJsonValueReason } from "../json"
+import {
+  cloneJsonValue,
+  getInvalidJsonValueReason,
+  type JsonValue,
+  type ReadonlyJsonValue,
+} from "../json"
 import { AgentDefinitionError, AgentToolResultValidationError } from "./errors"
+import { getInvalidAgentToolResultReason } from "./tool-result"
 import type {
   AgentToolDefinition,
   AgentToolHandler,
@@ -41,8 +47,12 @@ export function createAgentToolDefinition<
     input,
     handler: async (context) => {
       const result = await definition.handler(context)
+      let snapshot: JsonValue
       try {
-        return cloneJsonValue(result, "result")
+        // AgentToolResult is intentionally expressed with FileRef instead of a duplicate JSON-only
+        // shape. Runtime validation below proves that the complete envelope crosses the same JSON
+        // boundary as legacy results.
+        snapshot = cloneJsonValue(result as ReadonlyJsonValue, "result")
       } catch (cause) {
         throw new AgentToolResultValidationError(
           definition.name,
@@ -50,6 +60,11 @@ export function createAgentToolDefinition<
           { cause }
         )
       }
+      const richResultReason = getInvalidAgentToolResultReason(snapshot)
+      if (richResultReason) {
+        throw new AgentToolResultValidationError(definition.name, richResultReason)
+      }
+      return snapshot
     },
   }
 

package/src/agents/tool-result.ts

@@ -0,0 +1,61 @@
+import { isFileRef } from "../blob-storage/validation"
+import { isPlainRecord } from "../json"
+import type { AgentToolResult } from "./types"
+
+/** Narrow a durable JSON tool output to Sixb's file-aware result envelope. */
+export function isAgentToolResult(value: unknown): value is AgentToolResult {
+  return (
+    isPlainRecord(value) &&
+    value.kind === "agentToolResult" &&
+    getInvalidAgentToolResultReason(value) === undefined
+  )
+}
+
+/** Return a precise path when a tagged result does not satisfy the public rich-result contract. */
+export function getInvalidAgentToolResultReason(value: unknown): string | undefined {
+  if (!isPlainRecord(value) || value.kind !== "agentToolResult") {
+    return undefined
+  }
+
+  if (!Array.isArray(value.content)) {
+    return "result.content must be an array"
+  }
+  const unsupportedKey = Object.keys(value).find((key) => key !== "kind" && key !== "content")
+  if (unsupportedKey) {
+    return `result.${unsupportedKey} is not supported`
+  }
+  if (value.content.length === 0) {
+    return "result.content must contain at least one content part"
+  }
+
+  for (let index = 0; index < value.content.length; index += 1) {
+    const part = value.content[index]
+    const path = `result.content[${index}]`
+    if (!isPlainRecord(part)) {
+      return `${path} must be a text or file content part`
+    }
+    if (part.type === "text") {
+      if (typeof part.text !== "string") {
+        return `${path}.text must be a string`
+      }
+      const unsupportedKey = Object.keys(part).find((key) => key !== "type" && key !== "text")
+      if (unsupportedKey) {
+        return `${path}.${unsupportedKey} is not supported`
+      }
+      continue
+    }
+    if (part.type === "file") {
+      if (!isFileRef(part.fileRef)) {
+        return `${path}.fileRef must be a valid FileRef`
+      }
+      const unsupportedKey = Object.keys(part).find((key) => key !== "type" && key !== "fileRef")
+      if (unsupportedKey) {
+        return `${path}.${unsupportedKey} is not supported`
+      }
+      continue
+    }
+    return `${path}.type must be 'text' or 'file'`
+  }
+
+  return undefined
+}