@sixb/core 0.1.21 → 0.1.22

package/src/http/api-routes.ts

@@ -19,10 +19,21 @@ export interface SixbApiRoute {
   readonly accessToken: boolean
   /** The route is proxied by the agent API gateway (a strict subset of the accessToken routes). */
   readonly agentApi: boolean
+  /**
+   * What the route changes when the Agent calls it, for every `agentApi` route but a GET. The
+   * gateway holds `action` and `workflow` calls for the requester's approval when their mode asks.
+   */
+  readonly agentEffect?: AgentApiEffect
   /** The canonical handler may run under an explicitly selected shared session. */
   readonly sharedSession?: boolean
 }
 
+/**
+ * `read` changes nothing (a read sent as POST); `memory` writes the Agent's own notes; `file` stores
+ * a blob nothing points at yet; `model` costs what AI limits already bound.
+ */
+export type AgentApiEffect = "read" | "action" | "workflow" | "memory" | "file" | "model"
+
 export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
   {
     operationId: "getProjectInfo",
@@ -160,6 +171,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     path: "/api/objects/query",
     accessToken: true,
     agentApi: true,
+    agentEffect: "read",
     sharedSession: true,
   },
   {
@@ -168,6 +180,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     path: "/api/objects/query/links",
     accessToken: true,
     agentApi: true,
+    agentEffect: "read",
     sharedSession: true,
   },
   {
@@ -176,6 +189,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     path: "/api/objects/query/count",
     accessToken: true,
     agentApi: true,
+    agentEffect: "read",
     sharedSession: true,
   },
   {
@@ -184,6 +198,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     path: "/api/objects/query/exists",
     accessToken: true,
     agentApi: true,
+    agentEffect: "read",
     sharedSession: true,
   },
   {
@@ -192,6 +207,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     path: "/api/objects/query/facets",
     accessToken: true,
     agentApi: true,
+    agentEffect: "read",
     sharedSession: true,
   },
   {
@@ -202,6 +218,16 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     agentApi: true,
     sharedSession: true,
   },
+  // A read: POST only so the value, an email say, stays out of URLs and their logs.
+  {
+    operationId: "getObjectByUniqueProperty",
+    method: "POST",
+    path: "/api/objects/:objectTypeId/by/:propertyId",
+    accessToken: true,
+    agentApi: true,
+    agentEffect: "read",
+    sharedSession: true,
+  },
   // The four write routes. Bearer-capable because their execution facade enforces authorization
   // (`edit:object` / `append:telemetry`), which is exactly the precondition this table requires.
   // NOT agent-proxied: letting an agent turn write objects on its own is a separate decision, and
@@ -241,6 +267,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     path: "/api/telemetry/history",
     accessToken: true,
     agentApi: true,
+    agentEffect: "read",
     sharedSession: true,
   },
   {
@@ -301,6 +328,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     path: "/api/actions/:actionId",
     accessToken: true,
     agentApi: true,
+    agentEffect: "action",
     sharedSession: true,
   },
   {
@@ -309,6 +337,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     path: "/api/files",
     accessToken: true,
     agentApi: true,
+    agentEffect: "file",
   },
   {
     operationId: "listActionRuns",
@@ -359,6 +388,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     path: "/api/workflows/:workflowId/runs",
     accessToken: true,
     agentApi: true,
+    agentEffect: "workflow",
   },
   {
     operationId: "listWorkflowRuns",
@@ -430,6 +460,53 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: false,
   },
+  // A sub-agent's files are for people reading its conversation; its parent got them from
+  // `wait_agent`.
+  {
+    operationId: "getAgentChildFileContent",
+    method: "GET",
+    path: "/api/agent-threads/:threadId/child-files/content",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "headAgentChildFileContent",
+    method: "HEAD",
+    path: "/api/agent-threads/:threadId/child-files/content",
+    accessToken: true,
+    agentApi: false,
+  },
+  // The Agent reads and saves its memory with `sixb memory` in its sandbox. Its history and deleting
+  // a repo are for people, so they stay off the gateway.
+  {
+    operationId: "getAgentMemory",
+    method: "GET",
+    path: "/api/agent-memory/:repo",
+    accessToken: true,
+    agentApi: true,
+  },
+  {
+    operationId: "listAgentMemoryRevisions",
+    method: "GET",
+    path: "/api/agent-memory/:repo/revisions",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "saveAgentMemory",
+    method: "POST",
+    path: "/api/agent-memory/:repo/revisions",
+    accessToken: true,
+    agentApi: true,
+    agentEffect: "memory",
+  },
+  {
+    operationId: "deleteAgentMemory",
+    method: "DELETE",
+    path: "/api/agent-memory/:repo",
+    accessToken: true,
+    agentApi: false,
+  },
   // Artifacts are reachable with an access token, so the CLI and integrations can publish them. The
   // Agent publishes through its own tool, not the gateway.
   {
@@ -460,6 +537,34 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: false,
   },
+  {
+    operationId: "getArtifactState",
+    method: "GET",
+    path: "/api/artifacts/:artifactId/state",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "clearArtifactState",
+    method: "DELETE",
+    path: "/api/artifacts/:artifactId/state",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "setArtifactState",
+    method: "PUT",
+    path: "/api/artifacts/:artifactId/state/:key",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "deleteArtifactStateValue",
+    method: "DELETE",
+    path: "/api/artifacts/:artifactId/state/:key",
+    accessToken: true,
+    agentApi: false,
+  },
   {
     operationId: "publishArtifactVersion",
     method: "POST",
@@ -474,6 +579,13 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: false,
   },
+  {
+    operationId: "getArtifactQuery",
+    method: "GET",
+    path: "/api/artifacts/:artifactId/versions/:version/queries/:name",
+    accessToken: true,
+    agentApi: false,
+  },
   {
     operationId: "createArtifactFrame",
     method: "POST",
@@ -577,6 +689,59 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: false,
   },
+  {
+    operationId: "listUsers",
+    method: "GET",
+    path: "/api/users",
+    accessToken: true,
+    agentApi: true,
+  },
+  {
+    operationId: "getUser",
+    method: "GET",
+    path: "/api/users/:userId",
+    accessToken: true,
+    agentApi: true,
+  },
+  {
+    operationId: "listModels",
+    method: "GET",
+    path: "/api/models",
+    accessToken: true,
+    agentApi: true,
+  },
+  {
+    operationId: "generateText",
+    method: "POST",
+    path: "/api/models/language/generations",
+    accessToken: true,
+    agentApi: true,
+    agentEffect: "model",
+  },
+  {
+    operationId: "generateImages",
+    method: "POST",
+    path: "/api/models/image/generations",
+    accessToken: true,
+    agentApi: true,
+    agentEffect: "model",
+  },
+  {
+    operationId: "generateSpeech",
+    method: "POST",
+    path: "/api/models/audio/speech",
+    accessToken: true,
+    agentApi: true,
+    agentEffect: "model",
+  },
+  {
+    operationId: "transcribeAudio",
+    method: "POST",
+    path: "/api/models/audio/transcriptions",
+    accessToken: true,
+    agentApi: true,
+    agentEffect: "model",
+  },
   {
     operationId: "getAiAccountingOverview",
     method: "GET",
@@ -591,6 +756,27 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: false,
   },
+  {
+    operationId: "getAiModelCallFiles",
+    method: "GET",
+    path: "/api/ai/model-calls/:callId/files",
+    accessToken: true,
+    agentApi: true,
+  },
+  {
+    operationId: "getAiModelCallFileContent",
+    method: "GET",
+    path: "/api/ai/model-calls/:callId/files/content",
+    accessToken: true,
+    agentApi: true,
+  },
+  {
+    operationId: "headAiModelCallFileContent",
+    method: "HEAD",
+    path: "/api/ai/model-calls/:callId/files/content",
+    accessToken: true,
+    agentApi: false,
+  },
   {
     operationId: "listAiModelCallGroups",
     method: "GET",
@@ -642,12 +828,25 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
   },
 ]
 
-// Enforce the subset invariant at module load: a gateway-proxied route must also be a bearer route,
-// or the gateway would expose a surface the access-token boundary does not recognize.
-for (const route of SIXB_API_ROUTES) {
-  if (route.agentApi && !route.accessToken) {
-    throw new Error(
-      `[Sixb] agent API route '${route.method} ${route.path}' must also be an access-token route.`
-    )
+/**
+ * The table's invariants, enforced at module load. A gateway-proxied route must also be a bearer
+ * route, or the gateway would expose a surface the access-token boundary does not recognize. A
+ * gateway-proxied route that can change state names what it changes, so a route added later cannot
+ * skip the approval gate by accident.
+ */
+export function assertSixbApiRoutes(routes: readonly SixbApiRoute[]): void {
+  for (const route of routes) {
+    if (route.agentApi && !route.accessToken) {
+      throw new Error(
+        `[Sixb] agent API route '${route.method} ${route.path}' must also be an access-token route.`
+      )
+    }
+    if (route.agentApi && route.method !== "GET" && route.agentEffect === undefined) {
+      throw new Error(
+        `[Sixb] agent API route '${route.method} ${route.path}' must declare its agentEffect.`
+      )
+    }
   }
 }
+
+assertSixbApiRoutes(SIXB_API_ROUTES)

package/src/index.ts

@@ -3,6 +3,7 @@
 export type {
   ArraySchema,
   ComplexSchema,
+  CurrentUserRef,
   DirectLinkResult,
   DirectLinkTarget,
   EnumSchema,
@@ -49,6 +50,7 @@ export type {
   ValueTypeRefSchema,
 } from "./ontology"
 export {
+  currentUser,
   defineInterface,
   defineObjectType,
   defineOntology,
@@ -302,6 +304,16 @@ export type {
   TelemetryEvent,
   TelemetryEventOrigin,
   TelemetryEventSource,
+  UserEvent,
+  UserEventSelectorBuilder,
+  UserEventSelectorContext,
+  UserEventSelectorEvent,
+  UserEventSelectorOperation,
+  UserInvitedEvent,
+  UserJoinedEvent,
+  UserProfileUpdatedEvent,
+  UserReactivatedEvent,
+  UserSuspendedEvent,
   WorkflowEvent,
   WorkflowRunFinishedEvent,
   WorkflowRunNodeFinishedEvent,
@@ -397,9 +409,12 @@ export type {
   MembershipCapabilities,
   MembershipOperationCapabilities,
   Principal,
+  ProfileField,
   SixbAuthConfig,
+  UserPrincipal,
 } from "./auth"
 export { principalsEqual, SYSTEM_PRINCIPAL } from "./auth"
+export type { UserIdentityRecord } from "./storage/auth"
 
 // ── Authorization ──────────────────────────────────────────
 
@@ -427,6 +442,11 @@ export type {
   UpdateAiUsageLimitPolicyInput,
 } from "./ai-usage"
 
+// ── Member directory ──────────────────────────────────────
+
+export type { UserStatus } from "./storage"
+export type { ListUsersInput, UserProfile, UsersPage, UsersRuntime } from "./users"
+
 // ── Security Definitions ───────────────────────────────────
 
 export type {
@@ -449,10 +469,11 @@ export type {
   MarkingDefinition,
   MembershipOperation,
   MembershipPolicyDefinition,
+  ModelsRunGrant,
+  ObjectViewGrantBuilder,
   ObserveGrant,
   ObserveGrantTarget,
   ProjectReference,
-  ProjectSurfaceReference,
   RedactionReason,
   Redactions,
   RegisteredSecurityDefinitions,
@@ -462,6 +483,7 @@ export type {
   SecurityDefinitionCatalog,
   Selection,
   ShareGrant,
+  UsersViewGrant,
   ViewGrant,
   ViewGrantTarget,
 } from "./security"
@@ -611,6 +633,7 @@ export type {
   ObjectQueryPage,
   ObjectQueryPredicate,
   ObjectQueryPredicateComparison,
+  ObjectQueryPredicateConstant,
   ObjectQueryPredicateContains,
   ObjectQueryPredicateExists,
   ObjectQueryPredicateGroup,
@@ -895,24 +918,70 @@ export type {
   ActivityVisitTimeline,
   ActivityWorkflowEntry,
 } from "./activity/timeline"
+export type { AgentApprovalModeSource, ResolvedAgentApprovalMode } from "./agents/approvals"
+export type { AgentChildQuestion } from "./agents/child-question"
+export type {
+  AgentChildAwaiting,
+  AgentChildEndReason,
+  AgentChildRunView,
+  AgentChildView,
+} from "./agents/children"
+export type { AgentMemoryErrorCode } from "./agents/errors"
+export { AgentMemoryError } from "./agents/errors"
 export type {
+  AgentApprovalDecision,
+  AgentApprovalsRuntime,
+  AgentChildListResult,
+  AgentPreferences,
+  AgentPreferencesRuntime,
   AgentRunListResult,
   AgentRunsRuntime,
   AgentRuntime,
   AgentRunView,
+  AgentThreadParticipantsRuntime,
   AgentThreadsRuntime,
+  ConversationAgentRunView,
+  DecideExecutionAgentApprovalInput,
   ExecutionAgentRunResult,
+  ListAgentChildrenInput,
+  ListAgentThreadViewsResult,
+  ListExecutionAgentApprovalsInput,
+  ListExecutionAgentThreadsInput,
+  ObservedAgentThreadsRuntime,
+  SubagentRunView,
 } from "./agents/execution"
+export type { AgentMemoryLinkWarning, AgentMemoryRepoName } from "./agents/memory"
+export type {
+  AgentMemoryRepoView,
+  AgentMemoryRuntime,
+  SaveAgentMemoryRuntimeInput,
+  SaveAgentMemoryRuntimeResult,
+} from "./agents/memory-execution"
+export type { AgentThreadParticipantInput } from "./agents/participants"
+export type { AgentThreadParticipant, AgentThreadView } from "./agents/thread-access"
+export type { ArtifactAccess } from "./artifacts/access"
 export type { ArtifactRequestErrorCode } from "./artifacts/errors"
 export { ArtifactRequestError } from "./artifacts/errors"
 export type {
   ArtifactContentInput,
+  ArtifactQueryInput,
+  ArtifactStateRuntime,
+  ArtifactStateValue,
   ArtifactsRuntime,
   ListArtifactsRuntimeInput,
+  PublishArtifactRuntimeInput,
 } from "./artifacts/execution"
 export type { ArtifactKind } from "./artifacts/kinds"
 export type { ArtifactOutline } from "./artifacts/outline"
 export type { PublishedArtifact } from "./artifacts/publish/publish"
+export type {
+  ArtifactFacetsQueryResult,
+  ArtifactObjectsQueryResult,
+  ArtifactQueryProperty,
+  ArtifactQueryPropertyType,
+  ArtifactQueryResult,
+  ArtifactQuerySchema,
+} from "./artifacts/queries"
 export type { ArtifactReference } from "./artifacts/references"
 export type { ArtifactWarning } from "./artifacts/warnings"
 export type { CreateFileDownloadUrlOptions, FileDownloadUrl } from "./blob-storage/download-urls"
@@ -951,7 +1020,7 @@ export type {
 export type {
   LanguageModel,
   LanguageModelDefinition,
-  LanguageModelRateCard,
+  ModelRateCard,
   ProviderData,
 } from "./models"
 export type {
@@ -1011,6 +1080,8 @@ export type {
   TelemetryHistoryInput,
   TelemetryPropertyToken,
   TwinObject,
+  UniquePropertyToken,
+  UniquePropertyValue,
 } from "./runtime"
 export {
   ConnectorError,
@@ -1030,6 +1101,11 @@ export type {
   ActionRunFailure,
   ActionRunFailureCode,
   ActionRunPhase,
+  AgentApprovalCall,
+  AgentApprovalMode,
+  AgentApprovalOutcome,
+  AgentApprovalRecord,
+  AgentApprovalStatus,
   AgentRunFailureCode,
   AiCostSummary,
   PipelineRunFailureCode,
@@ -1050,6 +1126,7 @@ export type {
   ActivityVisit,
   ActivityVisitsPage,
 } from "./storage/activity/types"
+export type { ArtifactLatestVersion } from "./storage/artifacts/errors"
 export type { VectorIndexingFailureCode } from "./storage/ontology/vector-indexing"
 export type { SyncRunsRuntime, SyncsRuntime } from "./syncs/execution"
 export type {
@@ -1068,6 +1145,9 @@ export type {
 // ── Agents ──────────────────────────────────────────────────
 
 export type {
+  AgentApprovalCaller,
+  AgentApprovalCallSummary,
+  AgentApprovalOutcomePart,
   AgentContextEntryInput,
   AgentContextInput,
   AgentContextOrigin,
@@ -1079,6 +1159,8 @@ export type {
   AgentFileDataProjection,
   AgentFileDataResolverInput,
   AgentFilePart,
+  AgentMailPart,
+  AgentMemoryReference,
   AgentMessage,
   AgentMessagePart,
   AgentMessagePartType,
@@ -1093,6 +1175,7 @@ export type {
   AgentSkillDefinition,
   AgentStepStartPart,
   AgentTextPart,
+  AgentThreadsReference,
   AgentToolAttachments,
   AgentToolCallPart,
   AgentToolCallState,
@@ -1118,6 +1201,7 @@ export type {
   AgentUsageReference,
   InferAgentToolInput,
   InferAgentToolInputSchema,
+  InferAgentToolOutput,
   RequestAgentRunInput,
   RequestAgentRunResult,
 } from "./agents"
@@ -1145,6 +1229,8 @@ export type {
 export type { ParamOptions } from "./shared/params/builders"
 export type { InferParams, ParamConfig, ParamsConfig } from "./shared/params/types"
 export type {
+  AgentThreadKind,
+  AgentThreadParent,
   AgentThreadRecord,
   AgentThreadSandboxParams,
   AgentThreadSandboxState,
@@ -1174,6 +1260,9 @@ export type {
   LanguageModelCatalog,
   LanguageModelEntry,
   LanguageModelRef,
+  LanguageModelTier,
+  LanguageModelTierProbabilities,
+  LanguageModelTiers,
   ModelCallCost,
   ModelCatalog,
   ModelCatalogInput,
@@ -1197,6 +1286,7 @@ export type {
   RerankingModelResult,
   RerankingResult,
 } from "./models"
+export type { ModelCallFiles, ModelCallsRuntime } from "./models/calls"
 export type {
   InferLanguageModelOutput,
   LanguageModelGenerateInput,
@@ -1220,6 +1310,8 @@ export type {
 } from "./actions/descriptor"
 export type {
   AudioModelsRuntime,
+  AudioSpeakInput,
+  AudioSpeakResult,
   AudioTranscribeInput,
   AudioTranscribeResult,
   TranscriptionOutput,
@@ -1240,6 +1332,11 @@ export type {
   ProbabilityQuestion,
   ScoreQuestion,
 } from "./models/decision/types"
+export type {
+  ImageGenerateInput,
+  ImageGenerateResult,
+  ImageModelsRuntime,
+} from "./models/image/types"
 export type {
   ForeignKeyDescriptor,
   LinkProjectionDefinition,

package/src/materialization/errors.ts

@@ -43,6 +43,43 @@ export class MaterializationObjectNotFoundError extends MaterializationValidatio
   }
 }
 
+/**
+ * A unique property value that another object of the type already holds.
+ *
+ * The message names only the type and the property, so a caller learns that the value is taken
+ * and nothing more. The holder and the claimant are kept for messages that may name them.
+ */
+export class UniqueValueViolationError extends MaterializationValidationError {
+  override readonly name = "UniqueValueViolationError"
+
+  constructor(
+    readonly objectTypeId: string,
+    readonly propertyId: string,
+    readonly holderPrimaryId: string,
+    readonly claimantPrimaryId: string
+  ) {
+    super(`Another '${objectTypeId}' object already has this '${propertyId}'.`)
+  }
+}
+
+/**
+ * A write to a unique property whose stored values were never built, or were built with other
+ * keys: `sixb db migrate` prepares them. Writes stay refused until then, rather than accept a
+ * value they cannot check.
+ */
+export class UniquePropertyNotPreparedError extends Error {
+  readonly name = "UniquePropertyNotPreparedError"
+
+  constructor(
+    readonly objectTypeId: string,
+    readonly propertyId: string
+  ) {
+    super(
+      `[Sixb] Unique property '${objectTypeId}.${propertyId}' is not prepared. Run \`sixb db migrate\`.`
+    )
+  }
+}
+
 /**
  * Abort reason for an explicit, terminal cancellation of a materialization.
  *

package/src/materialization/event-envelopes.ts

@@ -9,6 +9,14 @@ import type {
 } from "./events"
 import type { OntologyMaterializationPropertyChangeMap } from "./model"
 
+/** The partition key of an object's events, which the log can be read by. */
+export function objectPartitionKey(object: {
+  readonly objectTypeId: string
+  readonly primaryId: string
+}): string {
+  return `${object.objectTypeId}:${object.primaryId}`
+}
+
 /** Where an event sits in its commit: its id and its ordinal. */
 export interface OntologyMaterializationEventSequence {
   readonly id: string
@@ -46,7 +54,7 @@ export function materializationEvent(
         ...context,
         type: draft.type,
         topic: "objects",
-        partitionKey: `${draft.payload.objectTypeId}:${draft.payload.primaryId}`,
+        partitionKey: objectPartitionKey(draft.payload),
         payload: {
           ...draft.payload,
           propertyChanges: createdPropertyChanges(draft.payload.properties),
@@ -57,7 +65,7 @@ export function materializationEvent(
         ...context,
         type: draft.type,
         topic: "objects",
-        partitionKey: `${draft.payload.objectTypeId}:${draft.payload.primaryId}`,
+        partitionKey: objectPartitionKey(draft.payload),
         payload: draft.payload,
       }
     case "object.deleted":
@@ -65,7 +73,7 @@ export function materializationEvent(
         ...context,
         type: draft.type,
         topic: "objects",
-        partitionKey: `${draft.payload.objectTypeId}:${draft.payload.primaryId}`,
+        partitionKey: objectPartitionKey(draft.payload),
         payload: draft.payload,
       }
     case "link.created":

package/src/materialization/index.ts

@@ -16,6 +16,7 @@ export {
   MaterializationConflictError,
   MaterializationObjectNotFoundError,
   MaterializationValidationError,
+  UniqueValueViolationError,
 } from "./errors"
 export type { OntologyMaterializationEventSequence } from "./event-envelopes"
 export { eventAttribution, materializationEvent } from "./event-envelopes"