@sixb/core 0.1.21 → 0.1.22

package/src/agents/thread-access.ts

@@ -0,0 +1,137 @@
+import { type Principal, principalsEqual, SYSTEM_PRINCIPAL, type UserPrincipal } from "../auth"
+import { isRuntimeAllowed } from "../authorization"
+import type { resolveRuntimeAuthorizationForProject } from "../execution/authorization"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { AgentStorage, AgentThreadRecord } from "../storage/agents"
+import { AgentRequestError } from "./errors"
+
+/** How the caller takes part in a conversation: its owner, or a user its owner added. */
+export type AgentThreadAccess = "owner" | "participant"
+
+/** A user the thread's owner added, who reads the conversation and talks in it. */
+export interface AgentThreadParticipant {
+  readonly principal: UserPrincipal
+  readonly addedAt: Date
+  readonly addedBy: Principal
+}
+
+/** A thread as the runtime returns it: the stored record with the users taking part in it. */
+export interface AgentThreadView extends AgentThreadRecord {
+  readonly participants: readonly AgentThreadParticipant[]
+}
+
+/** A thread the caller can read, and how it takes part in it. */
+export interface ReadableAgentThread {
+  readonly thread: AgentThreadView
+  readonly access: AgentThreadAccess
+}
+
+type RuntimeAuthority = ReturnType<typeof resolveRuntimeAuthorizationForProject>
+
+/**
+ * The one rule for who reads a conversation through `sixb.agent`.
+ *
+ * The caller needs `can.run(agent)`, then must own the thread or take part in it. Code without a
+ * caller (authorization disabled, or system code) reads every thread as its owner. A shared link,
+ * a delegated execution or a denied caller reads none. An observer reads every thread through
+ * `sixb.agent.observed` instead, without ever being its owner or a participant.
+ *
+ * A sub-agent's thread is read exactly when its conversation is, with the caller's access there:
+ * whoever stops reading the conversation stops reading its children with it.
+ */
+export interface AgentThreadAccessRule {
+  /** Who acts: the signed-in principal, or the system principal for code without a caller. */
+  readonly caller: Principal
+  /** The thread and how the caller takes part in it; `null` when it cannot read it. */
+  read(threadId: string): Promise<ReadableAgentThread | null>
+}
+
+export function createAgentThreadAccessRule(
+  runtime: SixbRuntimeContext,
+  authority: RuntimeAuthority,
+  /** Where threads are read, the project's storage when omitted: a transaction's decides in it. */
+  agents?: AgentStorage
+): AgentThreadAccessRule {
+  const caller = authority.type === "principal" ? authority.context.principal : SYSTEM_PRINCIPAL
+  const blocked = authority.type === "denied" || authority.type === "delegated"
+
+  const accessIn = (thread: AgentThreadView): AgentThreadAccess | null => {
+    if (blocked || !isRuntimeAllowed(runtime, { kind: "agent.run" })) return null
+    if (authority.type !== "principal") return "owner"
+    if (principalsEqual(caller, thread.ownerPrincipal)) return "owner"
+
+    return thread.participants.some((participant) => principalsEqual(participant.principal, caller))
+      ? "participant"
+      : null
+  }
+
+  const read = async (threadId: string): Promise<ReadableAgentThread | null> => {
+    if (blocked) return null
+
+    const storage = agents ?? runtime.storage.agents
+    const getById = (id: string) => storage?.threads.getById({ projectId: runtime.projectId, id })
+    const stored = await getById(threadId)
+    if (!stored) return null
+
+    // One level only: a child's parent is always a conversation, as storage admits no other.
+    const conversation = stored.parent ? await getById(stored.parent.threadId) : stored
+    if (conversation?.kind !== "conversation") return null
+
+    const [thread, readThrough = thread] = await agentThreadViews(
+      runtime,
+      conversation === stored ? [stored] : [stored, conversation],
+      storage
+    )
+    const access = readThrough ? accessIn(readThrough) : null
+    return thread && access ? { thread, access } : null
+  }
+
+  return { caller, read }
+}
+
+/** Refuse what only a conversation takes: a message, a fork, a participant, a mode, a sandbox. */
+export function assertConversationThread(thread: Pick<AgentThreadRecord, "id" | "kind">): void {
+  if (thread.kind === "conversation") return
+  throw new AgentRequestError(
+    "thread_not_conversation",
+    `[Sixb] Agent thread '${thread.id}' is a sub-agent's: it is read through its conversation and takes no change of its own.`
+  )
+}
+
+/**
+ * The conversation a thread belongs to: the thread itself, or a sub-agent's parent. What a child
+ * publishes, and the thread its sandbox names, are its conversation's.
+ */
+export function conversationThreadId(thread: Pick<AgentThreadRecord, "id" | "parent">): string {
+  return thread.parent?.threadId ?? thread.id
+}
+
+/** Stored threads as the runtime returns them, with their participants and no execution tokens. */
+export async function agentThreadViews(
+  runtime: SixbRuntimeContext,
+  threads: readonly AgentThreadRecord[],
+  agents: AgentStorage | undefined = runtime.storage.agents
+): Promise<readonly AgentThreadView[]> {
+  const participants =
+    threads.length === 0
+      ? []
+      : ((await agents?.threads.listParticipants({
+          projectId: runtime.projectId,
+          threadIds: threads.map((thread) => thread.id),
+        })) ?? [])
+
+  return threads.map((thread) => ({
+    ...publicThread(thread),
+    participants: participants
+      .filter((participant) => participant.threadId === thread.id)
+      .map(({ principal, addedAt, addedBy }) => ({ principal, addedAt, addedBy })),
+  }))
+}
+
+/** Execution ownership tokens never leave the storage/worker boundary. */
+function publicThread(thread: AgentThreadRecord): AgentThreadRecord {
+  if (!thread.sandboxState) return thread
+
+  const { name, status, initialized } = thread.sandboxState
+  return { ...thread, sandboxState: { name, status, initialized } }
+}

package/src/agents/tool-definition.ts

@@ -10,6 +10,7 @@ import type {
   AgentToolDefinition,
   AgentToolHandler,
   AgentToolInputSchema,
+  AgentToolResult,
   InferAgentToolInputSchema,
 } from "./types"
 import {
@@ -25,12 +26,13 @@ const normalizedAgentTools = new WeakSet<AgentToolDefinition>()
 export function createAgentToolDefinition<
   const TName extends string,
   const TInput extends AgentToolInputSchema,
+  TOutput extends ReadonlyJsonValue | AgentToolResult = ReadonlyJsonValue | AgentToolResult,
 >(definition: {
   readonly name: TName
   readonly description: string
   readonly input: TInput
-  readonly handler: AgentToolHandler<InferAgentToolInputSchema<TInput>>
-}): AgentToolDefinition<TName, TInput> {
+  readonly handler: AgentToolHandler<InferAgentToolInputSchema<TInput>, TOutput>
+}): AgentToolDefinition<TName, TInput, TOutput> {
   assertValidAgentToolName(definition.name)
   assertValidAgentToolDescription(definition.name, definition.description)
   if (typeof definition.handler !== "function") {
@@ -40,7 +42,7 @@ export function createAgentToolDefinition<
   }
 
   const input = validateAndSnapshotAgentToolInput(definition.name, definition.input)
-  const tool: AgentToolDefinition<TName, TInput> = {
+  const tool: AgentToolDefinition<TName, TInput, TOutput> = {
     kind: "agentTool",
     name: definition.name,
     description: definition.description,

package/src/agents/types.ts

@@ -8,6 +8,7 @@ import type { ModelsRuntime } from "../models/generation-types"
 import type { InferSchema } from "../ontology/inference"
 import type { Schema } from "../ontology/types"
 import type { ObjectReader } from "../runtime/types"
+import type { UsersRuntime } from "../users"
 
 export type {
   AgentContextEntryInput,
@@ -20,6 +21,8 @@ export type {
 export interface AgentReference {
   readonly kind: "agent"
   readonly usage: AgentUsageReference
+  readonly threads: AgentThreadsReference
+  readonly memory: AgentMemoryReference
 }
 
 /** Project-wide AI accounting and limit capability, independent of permission to run the Agent. */
@@ -27,6 +30,16 @@ export interface AgentUsageReference {
   readonly kind: "aiUsage"
 }
 
+/** Every user's conversations with the Agent, as `can.observe(agent.threads)` reads them. */
+export interface AgentThreadsReference {
+  readonly kind: "agentThreads"
+}
+
+/** The project's shared Agent memory, which every conversation reads. */
+export interface AgentMemoryReference {
+  readonly kind: "agentMemory"
+}
+
 /** Public metadata for the project's conversational Agent. */
 export interface AgentDescriptor {
   readonly name: string
@@ -147,6 +160,7 @@ export interface AgentToolRuntimeFacade extends ObjectReader {
   readonly actions: ActionsRuntime
   readonly models: ModelsRuntime
   readonly connector: ConnectorRuntime
+  readonly users: UsersRuntime
 }
 
 /** The narrow, run-scoped surface passed to an agent tool handler. */
@@ -164,14 +178,14 @@ export interface AgentToolRunContext<
 }
 
 /** Agent tool handlers may return only values safe to persist in agent messages. */
-export type AgentToolHandlerResult =
-  | ReadonlyJsonValue
-  | AgentToolResult
-  | Promise<ReadonlyJsonValue | AgentToolResult>
+export type AgentToolHandlerResult<
+  TOutput extends ReadonlyJsonValue | AgentToolResult = ReadonlyJsonValue | AgentToolResult,
+> = TOutput | Promise<TOutput>
 
-export type AgentToolHandler<TInput extends Readonly<Record<string, unknown>>> = (
-  context: AgentToolRunContext<TInput>
-) => AgentToolHandlerResult
+export type AgentToolHandler<
+  TInput extends Readonly<Record<string, unknown>>,
+  TOutput extends ReadonlyJsonValue | AgentToolResult = ReadonlyJsonValue | AgentToolResult,
+> = (context: AgentToolRunContext<TInput>) => AgentToolHandlerResult<TOutput>
 
 /**
  * Runtime definitions are stored heterogeneously. Keep variance erasure at this
@@ -181,16 +195,20 @@ type StoredAgentToolHandler<TInput extends Readonly<Record<string, unknown>>> =
   bivarianceHack(context: AgentToolRunContext<TInput>): JsonValue | Promise<JsonValue>
 }["bivarianceHack"]
 
+declare const agentToolOutputValueType: unique symbol
+
 /** A reusable, inert model tool definition selected explicitly by an agent. */
 export interface AgentToolDefinition<
   TName extends string = string,
   TInput extends AgentToolInputSchema = AgentToolInputSchema,
+  TOutput extends ReadonlyJsonValue | AgentToolResult = ReadonlyJsonValue | AgentToolResult,
 > {
   readonly kind: "agentTool"
   readonly name: TName
   readonly description: string
   readonly input: TInput
   readonly handler: StoredAgentToolHandler<InferAgentToolInputSchema<TInput>>
+  readonly [agentToolOutputValueType]?: TOutput
 }
 
 /** Infer the input received by a tool definition's handler. */
@@ -198,10 +216,17 @@ export type InferAgentToolInput<TTool extends AgentToolDefinition> = InferAgentT
   TTool["input"]
 >
 
+/**
+ * Infer the output a chat receives from a tool: its handler's return value, saved on the message
+ * and streamed live as is. A file-aware tool's output is its `AgentToolResult` envelope.
+ */
+export type InferAgentToolOutput<TTool extends AgentToolDefinition> =
+  TTool extends AgentToolDefinition<string, AgentToolInputSchema, infer TOutput> ? TOutput : never
+
 export interface AgentToolRunBuilder<TName extends string, TInput extends AgentToolInputSchema> {
-  run(
-    handler: AgentToolHandler<InferAgentToolInputSchema<TInput>>
-  ): AgentToolDefinition<TName, TInput>
+  run<TOutput extends ReadonlyJsonValue | AgentToolResult>(
+    handler: AgentToolHandler<InferAgentToolInputSchema<TInput>, TOutput>
+  ): AgentToolDefinition<TName, TInput, TOutput>
 }
 
 export interface AgentToolInputBuilder<TName extends string> {

package/src/agents/validation.ts

@@ -13,6 +13,8 @@ export const AGENT_RESERVED_TOOL_NAMES = [
   "view_file",
   "spawn_agent",
   "wait_agent",
+  "message_agent",
+  "ask_parent",
   "publish_artifact",
   "publish_artifact_version",
 ] as const

package/src/artifacts/access.ts

@@ -0,0 +1,125 @@
+import { type Principal, principalsEqual } from "../auth"
+import type { ArtifactRecord, ArtifactStorage } from "../storage/artifacts/types"
+import { ArtifactRequestError } from "./errors"
+
+/**
+ * What the caller may do with an artifact.
+ *
+ * - `owner`: everything, deleting it included.
+ * - `update`: read every version and publish the next one, as the owner or a participant of a
+ *   conversation that shares it.
+ * - `read`: read every version, as someone who observes a conversation that shares it.
+ * - `none`: nothing; the artifact exists but is not shared with the caller.
+ */
+export type ArtifactAccess = "owner" | "update" | "read" | "none"
+
+/** How the caller reads a conversation: talking in it, only observing it, or not at all. */
+export type ConversationAccess = "update" | "read" | null
+
+/**
+ * The one rule for who reaches an artifact.
+ *
+ * Its owner reaches it, and code without a caller reaches every artifact. Anyone else reaches an
+ * artifact shared in a conversation they read: one the Agent published a version in, or a fork
+ * of it copied. Whoever owns or takes part in that conversation may update the artifact; an
+ * observer of it only reads. The artifact is shared whole, at every version, whatever published
+ * each one. Only a signed-in session reaches what is shared: an access token, or a principal
+ * without a credential, reaches only its own artifacts.
+ *
+ * A rule reads how the caller reads each conversation once, so it lives for one operation.
+ */
+export interface ArtifactAccessRule {
+  accessTo(artifact: ArtifactRecord): Promise<ArtifactAccess>
+  /**
+   * What the caller may do when publishing the artifact's next version from a conversation, or
+   * outside any without `threadId`. Its owner publishes from anywhere, and a version published in
+   * a conversation shares the artifact there: that is how sharing starts. Anyone else publishes
+   * from a conversation only when it already shares the artifact, with the access they have there,
+   * so a version never shares someone else's artifact in another conversation.
+   */
+  publishAccess(artifact: ArtifactRecord, threadId?: string): Promise<ArtifactAccess>
+  /** How the caller reads the artifacts a conversation shares. */
+  conversation(threadId: string): Promise<ConversationAccess>
+}
+
+export function createArtifactAccessRule(input: {
+  readonly storage: ArtifactStorage
+  readonly projectId: string
+  /** `system` for code without a caller, `null` for a caller that reaches no artifact. */
+  readonly caller: Principal | "system" | null
+  /** `false` unless the caller signed in with a session: anything else reaches only its own. */
+  readonly sharing: boolean
+  /** How the caller reads a conversation, by the thread-access rule. */
+  readonly conversation: (threadId: string) => Promise<ConversationAccess>
+}): ArtifactAccessRule {
+  const { caller } = input
+  const conversations = new Map<string, Promise<ConversationAccess>>()
+
+  const conversation = (threadId: string): Promise<ConversationAccess> => {
+    if (caller === null || !input.sharing) return Promise.resolve(null)
+
+    let reads = conversations.get(threadId)
+    if (!reads) {
+      reads = input.conversation(threadId)
+      conversations.set(threadId, reads)
+    }
+    return reads
+  }
+
+  /** `owner` or `none` when the answer needs no conversation; `undefined` when it does. */
+  const ownAccess = (artifact: ArtifactRecord): ArtifactAccess | undefined => {
+    if (caller === null) return "none"
+    if (caller === "system" || principalsEqual(caller, artifact.owner)) return "owner"
+    return input.sharing ? undefined : "none"
+  }
+
+  const threadIdsOf = (artifact: ArtifactRecord) =>
+    input.storage.listThreadIds({ projectId: input.projectId, id: artifact.id })
+
+  const accessTo = async (artifact: ArtifactRecord): Promise<ArtifactAccess> => {
+    const own = ownAccess(artifact)
+    if (own) return own
+
+    let access: ArtifactAccess = "none"
+    for (const threadId of await threadIdsOf(artifact)) {
+      const reads = await conversation(threadId)
+      if (reads === "update") return "update"
+      if (reads === "read") access = "read"
+    }
+    return access
+  }
+
+  const publishAccess = async (
+    artifact: ArtifactRecord,
+    threadId?: string
+  ): Promise<ArtifactAccess> => {
+    if (threadId === undefined) return accessTo(artifact)
+
+    const own = ownAccess(artifact)
+    if (own) return own
+
+    if (!(await threadIdsOf(artifact)).includes(threadId)) return "none"
+
+    const reads = await conversation(threadId)
+    return reads === null ? "none" : reads
+  }
+
+  return { accessTo, publishAccess, conversation }
+}
+
+/** Refuses an artifact the caller may not update: `not_shared`, or `read_only` for an observer. */
+export function assertUpdatable(artifactId: string, access: ArtifactAccess): void {
+  if (access === "none") {
+    throw new ArtifactRequestError(
+      "not_shared",
+      `[Sixb] Artifact '${artifactId}' is not shared in a conversation you read.`
+    )
+  }
+
+  if (access === "read") {
+    throw new ArtifactRequestError(
+      "read_only",
+      `[Sixb] You read artifact '${artifactId}' as an observer: you cannot change it or keep page data in it.`
+    )
+  }
+}