@sixb/core 0.1.1 → 0.1.3

package/src/agents/types.ts

@@ -1,5 +1,6 @@
 import type { LanguageModelV4, LanguageModelV4CallOptions } from "@ai-sdk/provider"
-import type { ConnectorAdapter, ConnectorClient, ConnectorDefinition } from "../connectors"
+import type { BlobBody, FileRef } from "../blob-storage"
+import type { ConnectorRuntime } from "../connectors"
 import type { JsonPrimitive, JsonValue, ReadonlyJsonValue } from "../json"
 import type { Logger } from "../logging"
 import type { InferSchema } from "../ontology/inference"
@@ -67,21 +68,64 @@ export interface AgentToolRunInfo {
   readonly threadId?: string
 }
 
+/** Input accepted by the run-scoped artifact publisher exposed to agent tools. */
+export interface AgentToolArtifactPutInput {
+  readonly body: BlobBody
+  readonly fileName: string
+  readonly mediaType?: string
+}
+
+/** A durable artifact and its path inside the current run sandbox. */
+export interface AgentToolArtifact {
+  readonly fileRef: FileRef
+  readonly sandboxPath: string
+}
+
+/** The narrow artifact-writing surface available to an agent tool call. */
+export interface AgentToolArtifacts {
+  put(input: AgentToolArtifactPutInput): Promise<AgentToolArtifact>
+}
+
+export type AgentToolTextContent = {
+  readonly type: "text"
+  readonly text: string
+}
+
+export type AgentToolFileContent = {
+  readonly type: "file"
+  readonly fileRef: FileRef
+}
+
+/** Durable model-facing content returned by a file-aware tool. */
+export type AgentToolContent = AgentToolTextContent | AgentToolFileContent
+
+/**
+ * A file-aware tool result. The tag distinguishes this envelope from an ordinary JSON result while
+ * keeping the whole value safe to persist in the durable tool-call trace.
+ */
+export type AgentToolResult = {
+  readonly kind: "agentToolResult"
+  readonly content: readonly AgentToolContent[]
+}
+
 /** The narrow, run-scoped surface passed to an agent tool handler. */
 export interface AgentToolRunContext<
   TInput extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>,
 > {
   readonly input: TInput
+  readonly toolCallId: string
   readonly signal: AbortSignal
   readonly run: AgentToolRunInfo
-  connector<TAdapter extends ConnectorAdapter>(
-    definition: ConnectorDefinition<string, TAdapter>
-  ): Promise<ConnectorClient<TAdapter>>
+  readonly connector: ConnectorRuntime
   readonly logger: Logger
+  readonly artifacts: AgentToolArtifacts
 }
 
 /** Agent tool handlers may return only values safe to persist in agent messages. */
-export type AgentToolHandlerResult = ReadonlyJsonValue | Promise<ReadonlyJsonValue>
+export type AgentToolHandlerResult =
+  | ReadonlyJsonValue
+  | AgentToolResult
+  | Promise<ReadonlyJsonValue | AgentToolResult>
 
 export type AgentToolHandler<TInput extends Readonly<Record<string, unknown>>> = (
   context: AgentToolRunContext<TInput>

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", "view_file"] 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)
+}