@sixb/core 0.1.20 → 0.1.22

package/src/execution/unique-lookup.ts

@@ -0,0 +1,55 @@
+import type { OntologyRegistry } from "../ontology"
+import { OntologyValidationError } from "../ontology/errors"
+import type { ObjectType, ValueType } from "../ontology/types"
+import { uniqueValueKey, uniqueValueKind } from "../ontology/unique-values"
+import { normalizeSchemaValue, validateSchemaValue } from "../ontology/validation"
+
+/**
+ * The key a lookup by a unique property compares: the caller's value, validated and normalized as
+ * a write would store it, so a `Date` finds the object a write gave the same date.
+ */
+export function uniqueLookupKey(
+  ontology: OntologyRegistry,
+  input: { readonly objectTypeId: string; readonly propertyId: string; readonly value: unknown }
+): string {
+  return uniqueLookupKeyOf(
+    ontology.resolveObjectType(input.objectTypeId),
+    input.propertyId,
+    input.value,
+    ontology.getValueTypesById()
+  )
+}
+
+/** {@link uniqueLookupKey} against an already resolved object type. */
+export function uniqueLookupKeyOf(
+  objectType: ObjectType,
+  propertyId: string,
+  value: unknown,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): string {
+  const path = `${objectType.id}.${propertyId}`
+
+  const property = objectType.properties.find((candidate) => candidate.id === propertyId)
+  const kind = property?.unique ? uniqueValueKind(property.schema, valueTypesById) : undefined
+  if (!property || !kind) {
+    throw new OntologyValidationError(
+      `[Sixb] Cannot look up '${path}' by value: getBy needs a property declared with unique: true.`
+    )
+  }
+
+  if (value === null || value === undefined) {
+    throw new OntologyValidationError(
+      `[Sixb] Cannot look up '${path}' by ${String(value)}: no object holds a null or missing value.`
+    )
+  }
+
+  validateSchemaValue(property.schema, value, path, valueTypesById)
+  const key = uniqueValueKey(
+    kind,
+    normalizeSchemaValue(property.schema, value, path, valueTypesById)
+  )
+  if (key === null) {
+    throw new OntologyValidationError(`[Sixb] Cannot look up '${path}' by this value.`)
+  }
+  return key
+}

package/src/execution/visible-objects.ts

@@ -0,0 +1,26 @@
+import { type ObjectBatchKey, objectBatchKey } from "../storage"
+import type { AuthorizedObjectReader } from "./authorized-object-reader"
+
+export interface ObjectKey {
+  readonly objectTypeId: string
+  readonly primaryId: string
+}
+
+/**
+ * The objects among these that a reader sees now, by {@link objectBatchKey}: read through the
+ * reader in one call, so its conditions decide. Each object type must be viewable by the reader.
+ */
+export async function visibleObjects(
+  reader: AuthorizedObjectReader,
+  objects: readonly ObjectKey[]
+): Promise<ReadonlySet<ObjectBatchKey>> {
+  const items = new Map<ObjectBatchKey, ObjectKey>()
+  for (const { objectTypeId, primaryId } of objects) {
+    items.set(objectBatchKey(objectTypeId, primaryId), { objectTypeId, primaryId })
+  }
+
+  if (items.size === 0) return new Set()
+
+  const rows = await reader.getByPrimaryIdBatch({ items: [...items.values()] })
+  return new Set(rows.keys())
+}

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,153 @@ 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.
+  {
+    operationId: "listArtifacts",
+    method: "GET",
+    path: "/api/artifacts",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "createArtifact",
+    method: "POST",
+    path: "/api/artifacts",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "getArtifact",
+    method: "GET",
+    path: "/api/artifacts/:artifactId",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "deleteArtifact",
+    method: "DELETE",
+    path: "/api/artifacts/:artifactId",
+    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",
+    path: "/api/artifacts/:artifactId/versions",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "getArtifactVersion",
+    method: "GET",
+    path: "/api/artifacts/:artifactId/versions/:version",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "getArtifactQuery",
+    method: "GET",
+    path: "/api/artifacts/:artifactId/versions/:version/queries/:name",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "createArtifactFrame",
+    method: "POST",
+    path: "/api/artifacts/:artifactId/versions/:version/frame",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "getArtifactFileContent",
+    method: "GET",
+    path: "/api/artifacts/:artifactId/versions/:version/content",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "headArtifactFileContent",
+    method: "HEAD",
+    path: "/api/artifacts/:artifactId/versions/:version/content",
+    accessToken: true,
+    agentApi: false,
+  },
   {
     operationId: "searchObjects",
     method: "GET",
@@ -452,6 +629,119 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     accessToken: true,
     agentApi: false,
   },
+  // A browser records its own activity, signed in or through a shared link. Access tokens never
+  // do: a script is not a visit.
+  {
+    operationId: "getActivityCaptureConfig",
+    method: "GET",
+    path: "/api/activity/capture-config",
+    accessToken: false,
+    agentApi: false,
+    sharedSession: true,
+  },
+  {
+    operationId: "captureActivity",
+    method: "POST",
+    path: "/api/activity/events",
+    accessToken: false,
+    agentApi: false,
+    sharedSession: true,
+  },
+  {
+    operationId: "listActivityVisits",
+    method: "GET",
+    path: "/api/activity/visits",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "listActivityUsers",
+    method: "GET",
+    path: "/api/activity/users",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "getActivitySummary",
+    method: "GET",
+    path: "/api/activity/summary",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "getActivityCalendar",
+    method: "GET",
+    path: "/api/activity/calendar",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "getActivityVisitTimeline",
+    method: "GET",
+    path: "/api/activity/visits/:visitId/timeline",
+    accessToken: true,
+    agentApi: false,
+  },
+  {
+    operationId: "listActivityConnections",
+    method: "GET",
+    path: "/api/activity/connections",
+    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",
@@ -466,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",
@@ -517,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)