@sixb/core 0.1.20 → 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
@@ -80,22 +93,22 @@ export type AgentToolRunInfo =
       readonly stepId: string
     }
 
-/** Input accepted by the run-scoped artifact publisher exposed to agent tools. */
-export interface AgentToolArtifactPutInput {
+/** Input accepted by the run-scoped file publisher exposed to agent tools. */
+export interface AgentToolFilePutInput {
   readonly body: BlobBody
   readonly fileName: string
   readonly mediaType?: string
 }
 
-/** A durable artifact and its path inside the current run sandbox. */
-export interface AgentToolArtifact {
+/** A file a tool stored durably, and the path of its copy inside the current run sandbox. */
+export interface AgentToolFile {
   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>
+/** The narrow file-writing surface available to an agent tool call. */
+export interface AgentToolFiles {
+  put(input: AgentToolFilePutInput): Promise<AgentToolFile>
 }
 
 /**
@@ -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. */
@@ -159,19 +173,19 @@ export interface AgentToolRunContext<
   readonly run: AgentToolRunInfo
   readonly sixb: AgentToolRuntimeFacade
   readonly logger: Logger
-  readonly artifacts: AgentToolArtifacts
+  readonly files: AgentToolFiles
   readonly attachments: AgentToolAttachments
 }
 
 /** 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,10 @@ export const AGENT_RESERVED_TOOL_NAMES = [
   "view_file",
   "spawn_agent",
   "wait_agent",
+  "message_agent",
+  "ask_parent",
+  "publish_artifact",
+  "publish_artifact_version",
 ] as const
 
 export function isAgentToolDefinition(value: unknown): value is AgentToolDefinition {

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.`
+    )
+  }
+}

package/src/artifacts/address.ts

@@ -0,0 +1,132 @@
+import { isArtifactId } from "./ids"
+
+/**
+ * An address to an artifact, or to a part of one:
+ *
+ * ```text
+ * artifact:<id>[@<version>][/<file>][#<part>]
+ * ```
+ *
+ * Without a version it follows the latest one. What a part names depends on the target's kind: a
+ * sheet (`Summary`), a range of one (`Summary!A1:D12`), a chart (`chart=revenue`), a document's
+ * section by its slug (`methodology`), or a slide (`4`).
+ */
+export interface ArtifactAddress {
+  readonly artifactId: string
+  readonly version?: number
+  /** A file inside the artifact, by its path. */
+  readonly path?: string
+  readonly part?: string
+}
+
+const SCHEME = "artifact:"
+
+/** Whether a URL is written in the `artifact:` scheme, well formed or not. */
+export function isArtifactAddress(value: string): boolean {
+  return value.trim().toLowerCase().startsWith(SCHEME)
+}
+
+/** Reads an address; `null` when it is not a well-formed `artifact:` address. */
+export function parseArtifactAddress(value: string): ArtifactAddress | null {
+  const text = value.trim()
+  if (!isArtifactAddress(text)) return null
+  const hashAt = text.indexOf("#")
+  const head = text.slice(SCHEME.length, hashAt === -1 ? undefined : hashAt)
+  const part = hashAt === -1 ? undefined : decode(text.slice(hashAt + 1))
+  const slashAt = head.indexOf("/")
+  const target = slashAt === -1 ? head : head.slice(0, slashAt)
+  const path = slashAt === -1 ? undefined : decodePath(head.slice(slashAt + 1))
+  const [artifactId = "", version, ...rest] = target.split("@")
+  if (!isArtifactId(artifactId) || rest.length > 0) return null
+  if (version !== undefined && !/^[1-9]\d{0,8}$/.test(version)) return null
+  if (path === null || part === null || part === "") return null
+  return {
+    artifactId,
+    ...(version === undefined ? {} : { version: Number(version) }),
+    ...(path === undefined ? {} : { path }),
+    ...(part === undefined ? {} : { part }),
+  }
+}
+
+/**
+ * Writes an address so it survives inside Markdown: spaces and the characters that end a link
+ * are escaped, and the rest of a part stays readable (`Q3%20numbers!A1:D12`).
+ */
+export function formatArtifactAddress(address: ArtifactAddress): string {
+  const escaped = (text: string) =>
+    encodeURI(text).replace(
+      /[#()[\]<>]/g,
+      (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`
+    )
+  return [
+    SCHEME,
+    address.artifactId,
+    address.version === undefined ? "" : `@${address.version}`,
+    address.path === undefined ? "" : `/${address.path.split("/").map(escaped).join("/")}`,
+    address.part === undefined ? "" : `#${escaped(address.part)}`,
+  ].join("")
+}
+
+/** A rectangle of cells, zero-based, where row 0 is the header row (`A1`). */
+export interface CellRange {
+  readonly top: number
+  readonly left: number
+  readonly bottom: number
+  readonly right: number
+}
+
+/** What a part names in a sheet: a sheet, a range of one, or a chart. */
+export type SheetPart =
+  | { readonly type: "sheet"; readonly sheet: string; readonly range?: CellRange }
+  | { readonly type: "chart"; readonly chart: string }
+
+/** Reads a sheet part: `chart=revenue`, `Summary`, or `Summary!A1:D12`. */
+export function parseSheetPart(part: string): SheetPart | null {
+  if (part.startsWith("chart=")) {
+    const chart = part.slice("chart=".length)
+    return chart ? { type: "chart", chart } : null
+  }
+  const bangAt = part.lastIndexOf("!")
+  if (bangAt === -1) return { type: "sheet", sheet: part }
+  const sheet = part.slice(0, bangAt)
+  const range = parseCellRange(part.slice(bangAt + 1))
+  return sheet && range ? { type: "sheet", sheet, range } : null
+}
+
+/** Reads `B2` or `A1:D12`, in either corner order. */
+export function parseCellRange(text: string): CellRange | null {
+  const corners = text.split(":")
+  if (corners.length > 2) return null
+  const cells = corners.map(parseCell)
+  const [start, end = start] = cells
+  if (!start || !end) return null
+  return {
+    top: Math.min(start.row, end.row),
+    left: Math.min(start.column, end.column),
+    bottom: Math.max(start.row, end.row),
+    right: Math.max(start.column, end.column),
+  }
+}
+
+function parseCell(text: string): { readonly row: number; readonly column: number } | null {
+  const match = /^([A-Za-z]{1,3})([1-9]\d{0,6})$/.exec(text.trim())
+  if (!match?.[1] || !match[2]) return null
+  let column = 0
+  for (const letter of match[1].toUpperCase()) column = column * 26 + letter.charCodeAt(0) - 64
+  return { row: Number(match[2]) - 1, column: column - 1 }
+}
+
+function decode(text: string): string | null {
+  try {
+    return decodeURIComponent(text)
+  } catch {
+    return null
+  }
+}
+
+/** A relative file path: no empty, `.`, or `..` segment. */
+function decodePath(text: string): string | null {
+  const segments = text.split("/").map(decode)
+  if (segments.some((segment) => !segment || segment === "." || segment === "..")) return null
+  return segments.join("/")
+}