@sixb/core 0.1.1 → 0.1.2

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/types.ts

@@ -1,5 +1,5 @@
 import type { LanguageModelV4, LanguageModelV4CallOptions } from "@ai-sdk/provider"
-import type { ConnectorAdapter, ConnectorClient, ConnectorDefinition } from "../connectors"
+import type { ConnectorRuntime } from "../connectors"
 import type { JsonPrimitive, JsonValue, ReadonlyJsonValue } from "../json"
 import type { Logger } from "../logging"
 import type { InferSchema } from "../ontology/inference"
@@ -74,9 +74,7 @@ export interface AgentToolRunContext<
   readonly input: TInput
   readonly signal: AbortSignal
   readonly run: AgentToolRunInfo
-  connector<TAdapter extends ConnectorAdapter>(
-    definition: ConnectorDefinition<string, TAdapter>
-  ): Promise<ConnectorClient<TAdapter>>
+  readonly connector: ConnectorRuntime
   readonly logger: Logger
 }
 

package/src/agents/validation.ts

@@ -6,7 +6,7 @@ import {
   type ValueType,
   validateSchemaValue,
 } from "../ontology"
-import type { GroupDefinition, SecurityRegistry } from "../security"
+import type { GroupDefinition, SecurityDefinitionCatalog } from "../security"
 import { AgentDefinitionError } from "./errors"
 import {
   AGENT_REASONING_LEVELS,
@@ -31,7 +31,7 @@ const AGENT_TOOL_PRIMITIVE_SCHEMAS = new Set([
   "fileRef",
 ])
 
-export const AGENT_RESERVED_TOOL_NAMES = ["bash"] as const
+export const AGENT_RESERVED_TOOL_NAMES = ["bash", "read"] as const
 
 export function assertNonEmpty(value: string, field: string): void {
   if (!value.trim()) {
@@ -232,7 +232,7 @@ export function groupIdsFromDefinitions(
 
 export function validateAgentGroupReferences(
   agents: readonly AgentDefinition[],
-  security: SecurityRegistry
+  security: SecurityDefinitionCatalog
 ): void {
   for (const agent of agents) {
     assertNoDuplicateGroupIds(agent.id, agent.groupIds)

package/src/auth/attribution.ts

@@ -0,0 +1,48 @@
+import { compareStrings } from "../json"
+import type { AuthStorage } from "../storage/auth"
+import type { Principal } from "./types"
+
+/**
+ * Resolve the durable group-membership snapshot used to attribute admitted work.
+ *
+ * Authorization contexts can carry a token-restricted subset of the principal's groups, so they
+ * are deliberately not accepted here. Accounting attribution comes from auth storage whenever it
+ * is configured. A system principal, or a runtime with no durable auth storage, has no groups.
+ */
+export async function snapshotRequesterGroupIds(input: {
+  readonly auth: AuthStorage | undefined
+  readonly projectId: string
+  readonly principal: Principal
+}): Promise<readonly string[]> {
+  if (input.principal.type === "system" || !input.auth) {
+    return []
+  }
+
+  const memberships =
+    input.principal.type === "user"
+      ? await input.auth.groupMemberships.listForUser({
+          projectId: input.projectId,
+          userId: input.principal.id,
+        })
+      : await input.auth.serviceAccountGroupMemberships.listForServiceAccount({
+          projectId: input.projectId,
+          serviceAccountId: input.principal.id,
+        })
+
+  return normalizeRequesterGroupIds(memberships.map((membership) => membership.groupId))
+}
+
+/** Validate and canonicalize an immutable requester-group snapshot at a storage boundary. */
+export function normalizeRequesterGroupIds(groupIds: readonly string[]): readonly string[] {
+  if (!Array.isArray(groupIds)) {
+    throw new TypeError("[Sixb] requesterGroupIds must be an array.")
+  }
+  const unique = new Set<string>()
+  for (const groupId of groupIds) {
+    if (typeof groupId !== "string" || groupId.trim().length === 0) {
+      throw new TypeError("[Sixb] requesterGroupIds entries must be nonblank.")
+    }
+    unique.add(groupId)
+  }
+  return [...unique].sort(compareStrings)
+}

package/src/auth/index.ts

@@ -9,6 +9,7 @@ export {
   parseAccessTokenValue,
   SERVICE_ACCOUNT_ACCESS_TOKEN_PREFIX,
 } from "./access-tokens"
+export { normalizeRequesterGroupIds, snapshotRequesterGroupIds } from "./attribution"
 export type { AuthSessionAudience, AuthSessionAudienceOptions } from "./audience"
 export {
   DEFAULT_AUTH_SESSION_AUDIENCE,

package/src/auth/runtime.ts

@@ -11,7 +11,7 @@ import {
   type MembershipPolicyScope,
   missingMembershipGroupIds,
   resolveMembershipPolicyScope,
-  type SecurityRegistry,
+  type SecurityDefinitionCatalog,
 } from "../security"
 import type { Storage } from "../storage"
 import {
@@ -120,14 +120,14 @@ const ACCESS_TOKEN_TOUCH_INTERVAL_MS = 60_000
 export interface AuthRuntimeOptions {
   readonly projectId: string
   readonly storage: Storage
-  readonly security: SecurityRegistry
+  readonly security: SecurityDefinitionCatalog
   readonly config?: SixbAuthConfig
 }
 
 export class AuthRuntime {
   private readonly projectId: string
   private readonly storage: Storage
-  private readonly security: SecurityRegistry
+  private readonly security: SecurityDefinitionCatalog
   private readonly config: ResolvedAuthConfig
   private readonly sessionCache: SessionCache | null
 
@@ -566,8 +566,8 @@ export class AuthRuntime {
   /**
    * Resolve the authenticated principal's authorization context for a request.
    *
-   * Grants resolve eagerly (`groups -> roles -> grants`, subtype-expanded), so
-   * the returned context supports synchronous set-lookup checks and `sixb.as()`.
+   * Grants resolve eagerly (`groups -> roles -> grants`, subtype-expanded), so the returned
+   * context supports synchronous checks when Core binds a request execution SDK.
    */
   async createAuthorizationContext(
     request: Request,

package/src/authorization/decision.ts

@@ -5,18 +5,17 @@
  * index. `can` (boolean) and `assertAuthorized` (throw) are the two ways to
  * consume a decision; every enforcement site goes through one of them.
  *
- * A missing authorization context means a privileged caller (raw `sixb`,
- * syncs, workers, tests) — everything is allowed. Scoped contexts are
- * default-deny: a request without a covering grant is denied.
- *
- * SECURITY — this makes "privileged" the silent default: any caller that
- * reaches a leaf without an authorization context bypasses all grant checks.
- * That is intended for internal callers, but it means HTTP routes serving
- * authenticated principals must go through the scoped runtime (`sixb.as(ctx)`),
- * never the raw runtime. See `RequestAuthState` in the server for the rule.
+ * Every protected leaf first resolves the opaque runtime capability. Missing, forged, or
+ * unregistered authority is denied; only an explicitly registered trusted or disabled execution
+ * is unrestricted.
  */
 
 import type { AuthSessionAudience } from "../auth/audience"
+import {
+  type ResolvedRuntimeAuthorization,
+  resolveRuntimeAuthorization,
+} from "../execution/authorization"
+import type { ExecutionContext, RuntimeAuthorization } from "../execution/types"
 import { AuthorizationError } from "./errors"
 import type { GrantKind } from "./grant-kinds"
 import type { AuthorizationContext, GrantIndex } from "./types"
@@ -34,6 +33,7 @@ export type AuthzRequest =
   | { readonly kind: "pipeline.run"; readonly pipelineId: string }
   | { readonly kind: "agent.run"; readonly agentId: string }
   | { readonly kind: "logs.observe" }
+  | { readonly kind: "connector.manage"; readonly connectorId: string }
   | { readonly kind: "object.query"; readonly touchedObjectTypeIds: readonly string[] }
 
 export interface AuthzDecision {
@@ -45,6 +45,7 @@ export interface AuthzDecision {
 }
 
 interface AuthorizedRuntime {
+  readonly runtimeAuthorization?: RuntimeAuthorization
   readonly authorization?: AuthorizationContext
 }
 
@@ -81,6 +82,8 @@ function atomsFor(request: AuthzRequest): readonly Atom[] {
       return [{ kind: "run:agent", id: request.agentId }]
     case "logs.observe":
       return [{ kind: "observe:logs", id: "logs" }]
+    case "connector.manage":
+      return [{ kind: "manage:connector", id: request.connectorId }]
     case "object.query":
       return request.touchedObjectTypeIds.map((id) => ({ kind: "view:object", id }))
   }
@@ -116,17 +119,33 @@ export function isAllowed(
 }
 
 export function assertAuthorized(runtime: AuthorizedRuntime, request: AuthzRequest): void {
-  const decision = evaluate(runtime.authorization, request)
+  const resolved = assertRuntimeAuthorizationBound(runtime)
+  const authorization = resolved.type === "principal" ? resolved.context : undefined
+  const decision = evaluate(authorization, request)
   if (decision.allowed) {
     return
   }
 
   throw new AuthorizationError(
     decision.missing[0] ?? request.kind,
-    deniedMessage(runtime.authorization, request)
+    deniedMessage(authorization, request)
   )
 }
 
+/** Resolve registered process-local authority before a protected leaf makes a decision. */
+export function assertRuntimeAuthorizationBound(
+  runtime: AuthorizedRuntime
+): Exclude<ResolvedRuntimeAuthorization, { readonly type: "denied" }> {
+  const resolved = resolveRuntimeAuthorization(runtime.runtimeAuthorization)
+  if (resolved.type === "denied") {
+    throw new AuthorizationError(
+      "runtime:unbound",
+      "[Sixb] Protected operations require a registered execution scope."
+    )
+  }
+  return resolved
+}
+
 /**
  * Assert a principal may write objects of this type.
  *
@@ -157,16 +176,56 @@ export function assertCanAppendTelemetry(runtime: AuthorizedRuntime, objectTypeI
   assertAuthorized(runtime, { kind: "telemetry.append", objectTypeId })
 }
 
+/** Assert a principal may manage lifecycle state for this connector definition. */
+export function assertCanManageConnector(runtime: AuthorizedRuntime, connectorId: string): void {
+  assertAuthorized(runtime, { kind: "connector.manage", connectorId })
+}
+
 /**
  * Fail closed for operations that have no grant semantics yet.
  *
  * One caller left — `listLinks`, whose rows reveal target types that no read grant covers. Object,
  * link, and telemetry writes moved to {@link assertCanEdit} / {@link assertCanAppendTelemetry}.
- * Keeps unsupported surfaces denied even if a scoped runtime context reaches a code path the scoped
- * SDK does not expose.
+ * Keeps unsupported surfaces denied even if a principal-bound runtime context reaches a code path
+ * the execution SDK does not expose.
  */
 export function assertPrivileged(runtime: AuthorizedRuntime, operation: string): void {
-  if (!runtime.authorization) {
+  const resolved = assertRuntimeAuthorizationBound(runtime)
+  if (resolved.type === "unrestricted") {
+    return
+  }
+
+  throw new AuthorizationError(
+    `privileged:${operation}`,
+    `[Sixb] Operation '${operation}' is not covered by scoped authorization grants.`
+  )
+}
+
+/**
+ * Assert access to process providers that trusted executions and genuine agent runs may use.
+ *
+ * Agent provenance alone is not authority: the registered capability must be bound to the exact
+ * same agent and run before this check succeeds.
+ */
+export function assertProviderAccess(
+  runtime: AuthorizedRuntime,
+  execution: ExecutionContext,
+  operation: string
+): void {
+  const resolved = assertRuntimeAuthorizationBound(runtime)
+  if (resolved.type === "unrestricted") {
+    return
+  }
+
+  const binding = resolved.executionBinding
+  const executor = execution.executor
+  if (
+    binding?.type === "agent" &&
+    executor.type === "agent" &&
+    binding.executionId === execution.id &&
+    binding.agentId === executor.agentId &&
+    binding.runId === executor.runId
+  ) {
     return
   }
 
@@ -204,6 +263,8 @@ function deniedMessage(
       return `[Sixb] Principal '${principalId}' is not allowed to run agent '${request.agentId}'.`
     case "logs.observe":
       return `[Sixb] Principal '${principalId}' is not allowed to observe project logs.`
+    case "connector.manage":
+      return `[Sixb] Principal '${principalId}' is not allowed to manage connector '${request.connectorId}'.`
     case "object.query": {
       // Name the first touched type the principal cannot view.
       const blocked = request.touchedObjectTypeIds.find(

package/src/authorization/grant-kinds.ts

@@ -22,6 +22,7 @@ export type GrantKind =
   | "run:pipeline"
   | "run:agent"
   | "observe:logs"
+  | "manage:connector"
 
 /** Registered id universes a grant kind ranges over, plus subtype expansion. */
 export interface GrantUniverse {
@@ -34,6 +35,7 @@ export interface GrantUniverse {
   readonly pipelineIds: ReadonlySet<string>
   readonly agentIds: ReadonlySet<string>
   readonly observableIds: ReadonlySet<string>
+  readonly connectorIds: ReadonlySet<string>
   readonly getSubTypes: (objectTypeId: string) => readonly string[]
 }
 
@@ -115,6 +117,11 @@ export const GRANT_KINDS: Record<GrantKind, GrantKindSpec> = {
     subject: "observability surface",
     fix: 'Use can.observe("logs").',
   },
+  "manage:connector": {
+    universeKey: "connectorIds",
+    subject: "connector",
+    fix: "Add it to 'connectors/' or pass it to createSixb({ connectors }).",
+  },
 }
 
 export const GRANT_KIND_KEYS = Object.keys(GRANT_KINDS) as readonly GrantKind[]
@@ -136,6 +143,8 @@ export function grantKindOf(grant: GrantDefinition): GrantKind {
       return `run:${grant.target}`
     case "observe":
       return "observe:logs"
+    case "manage":
+      return "manage:connector"
   }
 }
 

package/src/authorization/index.ts

@@ -4,7 +4,9 @@ export {
   assertAuthorized,
   assertCanAppendTelemetry,
   assertCanEdit,
+  assertCanManageConnector,
   assertPrivileged,
+  assertProviderAccess,
   evaluate,
   isAllowed,
 } from "./decision"

package/src/blob-storage/execution.ts

@@ -0,0 +1,78 @@
+import { assertProviderAccess } from "../authorization"
+import type { ExecutionContext } from "../execution"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type {
+  AbortBlobUploadInput,
+  BlobByteRange,
+  BlobInfo,
+  BlobStorage,
+  BlobUploadSession,
+  CompleteBlobUploadInput,
+  CreateBlobUploadInput,
+  FileRef,
+  PutBlobInput,
+  SignBlobUploadPartInput,
+  SignedBlobUploadPart,
+} from "./types"
+import { supportsDirectUpload, supportsRangeRead } from "./validation"
+
+/** Blob operations bound to one execution. Provider lifecycle is deliberately host-only. */
+export interface BlobsRuntime {
+  put(input: PutBlobInput): Promise<FileRef>
+  open(blobId: string): Promise<ReadableStream<Uint8Array>>
+  stat(blobId: string): Promise<BlobInfo | null>
+  openRange?(blobId: string, range: BlobByteRange): Promise<ReadableStream<Uint8Array>>
+  createUpload?(input: CreateBlobUploadInput): Promise<BlobUploadSession>
+  signUploadPart?(input: SignBlobUploadPartInput): Promise<SignedBlobUploadPart>
+  completeUpload?(input: CompleteBlobUploadInput): Promise<FileRef>
+  abortUpload?(input: AbortBlobUploadInput): Promise<void>
+}
+
+export function createBlobsRuntime(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  blobStorage: BlobStorage
+): BlobsRuntime {
+  const assertAccess = () => assertProviderAccess(runtime, execution, "blobs.access")
+  const executionBlobs: BlobsRuntime = {
+    put: (input) => {
+      assertAccess()
+      return blobStorage.put(input)
+    },
+    open: (blobId) => {
+      assertAccess()
+      return blobStorage.open(blobId)
+    },
+    stat: (blobId) => {
+      assertAccess()
+      return blobStorage.stat(blobId)
+    },
+  }
+
+  if (supportsRangeRead(blobStorage)) {
+    executionBlobs.openRange = (blobId, range) => {
+      assertAccess()
+      return blobStorage.openRange(blobId, range)
+    }
+  }
+  if (supportsDirectUpload(blobStorage)) {
+    executionBlobs.createUpload = (input) => {
+      assertAccess()
+      return blobStorage.createUpload(input)
+    }
+    executionBlobs.signUploadPart = (input) => {
+      assertAccess()
+      return blobStorage.signUploadPart(input)
+    }
+    executionBlobs.completeUpload = (input) => {
+      assertAccess()
+      return blobStorage.completeUpload(input)
+    }
+    executionBlobs.abortUpload = (input) => {
+      assertAccess()
+      return blobStorage.abortUpload(input)
+    }
+  }
+
+  return Object.freeze(executionBlobs)
+}