@sixb/core 0.1.20 → 0.1.21

package/src/activity/timeline.ts

@@ -0,0 +1,424 @@
+import type { ActionObjectSubject } from "../actions"
+import { unreadableActionRunTypes } from "../actions/run-authorization"
+import { AuthorizationError, canViewActionRun, canViewWorkflowRun } from "../authorization"
+import { resolveExecutionCosts } from "../runtime/ai-cost"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { ActionRunStatus } from "../storage/action-runs"
+import { ACTIVITY_MAX_VISIT_MS, ACTIVITY_MIN_IDLE_TIMEOUT_MS } from "../storage/activity/policy"
+import type { ActivityVisit, StoredActivityVisitPage } from "../storage/activity/types"
+import type { AgentRunStatus, ConversationAgentRunRecord } from "../storage/agents"
+import type { AiCostSummary } from "../storage/ai-cost"
+import type { ExecutionRecord } from "../storage/executions"
+import { objectBatchKey } from "../storage/objects/keys"
+import type { ShareGrantRecord } from "../storage/share-grants"
+import type { WorkflowRunStatus } from "../storage/workflow-runs"
+import { type ActivityConnection, readActivityConnection } from "./connection"
+import type { ActivityVisitView } from "./shares"
+
+/**
+ * At most this many page views and interactions together, and as many recorded executions, make a
+ * visit's timeline.
+ */
+export const ACTIVITY_TIMELINE_LIMIT = 200
+
+/**
+ * How far around its activity a visit claims its session's executions. A click right after a
+ * return reaches the server before the activity that opens the visit, and the last action before
+ * leaving may come after the last activity sent. Half the shortest idle timeout keeps the visits of
+ * one session from claiming the same execution.
+ */
+const SESSION_GRACE_MS = ACTIVITY_MIN_IDLE_TIMEOUT_MS / 2
+
+export interface ActivityPageEntry {
+  readonly kind: "page"
+  readonly at: Date
+  readonly sequence: number
+  readonly route: string
+}
+
+/** An interaction the app marked, on the page it happened on. */
+export interface ActivityInteractionEntry {
+  readonly kind: "interaction"
+  readonly at: Date
+  readonly sequence: number
+  readonly name: string
+  readonly route: string
+}
+
+export interface ActivityActionEntry {
+  readonly kind: "action"
+  readonly at: Date
+  readonly executionId: string
+  readonly actionId: string
+  readonly runId: string
+  /** `incomplete` when no outcome is recorded: the run is in flight, or was interrupted. */
+  readonly status: ActionRunStatus | "incomplete"
+  /** Whether the viewer may read the run itself, as Observability › Runs shows it. */
+  readonly runVisible: boolean
+  /** The object it applied to, only when the viewer can read that object. */
+  readonly object?: { readonly objectTypeId: string; readonly primaryId: string }
+}
+
+export interface ActivityWorkflowEntry {
+  readonly kind: "workflow"
+  readonly at: Date
+  readonly executionId: string
+  readonly workflowId: string
+  readonly runId: string
+  readonly status: WorkflowRunStatus | "incomplete"
+  /** Whether the viewer may read the run itself, as Observability › Runs shows it. */
+  readonly runVisible: boolean
+}
+
+/** A conversation's run: its metadata only, never its title or messages. */
+export interface ActivityAgentEntry {
+  readonly kind: "agent"
+  readonly at: Date
+  readonly executionId: string
+  readonly runId: string
+  readonly threadId: string
+  readonly status: AgentRunStatus
+  /** Messages in the thread now, every run's. */
+  readonly messages: number
+  /** The run's model calls with those of its subagents and tools; absent without any. */
+  readonly cost?: AiCostSummary
+}
+
+export type ActivityTimelineEntry =
+  | ActivityPageEntry
+  | ActivityInteractionEntry
+  | ActivityActionEntry
+  | ActivityWorkflowEntry
+  | ActivityAgentEntry
+
+export interface ActivityVisitTimeline {
+  readonly visit: ActivityVisitView
+  /** Absent once the session is gone, or without an auth or share store. */
+  readonly connection?: ActivityConnection
+  /**
+   * By time. Page views and interactions come in their sequence, and before executions at the same
+   * instant.
+   */
+  readonly entries: readonly ActivityTimelineEntry[]
+  /**
+   * More than {@link ACTIVITY_TIMELINE_LIMIT} page views and interactions, or recorded executions.
+   * The timeline then stops at the last page view or interaction, or the last root execution, it
+   * could keep.
+   */
+  readonly truncated: boolean
+}
+
+/**
+ * A visit's timeline: its page views and interactions, and what its session started while it
+ * lasted. One bounded read per source, each batched over the visit; see `README.md`.
+ */
+export async function composeActivityTimeline(
+  runtime: SixbRuntimeContext,
+  input: {
+    readonly page: StoredActivityVisitPage
+    /** The visit, named by its link's share. */
+    readonly visit: ActivityVisitView
+    /** That link's grant, read with the name. */
+    readonly grant?: ShareGrantRecord
+  },
+  now: Date
+): Promise<ActivityVisitTimeline> {
+  const { page, visit } = input
+  const { storage, projectId } = runtime
+
+  const [ledger, connection] = await Promise.all([
+    storage.executions.listBySession({
+      projectId,
+      session: { type: visit.actor.type, id: page.sessionId },
+      ...sessionWindow(visit),
+      limit: ACTIVITY_TIMELINE_LIMIT,
+    }),
+    readActivityConnection(runtime, page, input.grant, now),
+  ])
+  const executions = ledger.executions
+
+  const ofKind = (kind: "action" | "workflow") =>
+    executions.flatMap((execution) =>
+      execution.executor.type === "primitive" && execution.executor.kind === kind
+        ? [execution.id]
+        : []
+    )
+  const agentRunIds = executions.flatMap((execution) =>
+    execution.executor.type === "agent" ? [execution.executor.runId] : []
+  )
+
+  // Only what an Agent ran can count toward a conversation's cost.
+  const byId = new Map(executions.map((execution) => [execution.id, execution]))
+  const withAgent = executions.filter((execution) =>
+    lineage(execution, byId).some((ancestor) => ancestor.executor.type === "agent")
+  )
+
+  const [actionRuns, workflowRuns, agentRuns, costs] = await Promise.all([
+    storage.actionRuns?.getByExecutionIds({ projectId, executionIds: ofKind("action") }) ?? [],
+    storage.workflowRuns?.getByExecutionIds({ projectId, executionIds: ofKind("workflow") }) ?? [],
+    storage.agents?.runs.getByIds({ projectId, ids: agentRunIds }) ?? [],
+    resolveExecutionCosts({
+      storage: storage.aiCosts,
+      projectId,
+      executionIds: withAgent.map((execution) => execution.id),
+    }),
+  ])
+
+  // A subagent's cost goes to the conversation above it. A Workflow's Agent steps have none.
+  const conversations = new Map(
+    agentRuns.flatMap((run) =>
+      run.kind === "conversation" ? [[run.executionId, run] as const] : []
+    )
+  )
+  const subjects = actionRuns.flatMap((run) => (run.subject.kind === "object" ? [run.subject] : []))
+
+  const [threads, readable, unreadableRunTypes] = await Promise.all([
+    storage.agents?.threads.getByIds({
+      projectId,
+      ids: [...conversations.values()].map((run) => run.threadId),
+    }) ?? [],
+    readableObjects(runtime, subjects),
+    subjects.length > 0 ? unreadableActionRunTypes(runtime.objectReader) : new Set<string>(),
+  ])
+
+  const actionRunByExecution = new Map(actionRuns.map((run) => [run.executionId, run]))
+  const workflowRunByExecution = new Map(workflowRuns.map((run) => [run.executionId, run]))
+  const messagesByThread = new Map(threads.map((thread) => [thread.id, thread.messageCount]))
+  const costByAgent = rollUpCosts(byId, conversations, withAgent, costs)
+
+  const executionEntries = executions.flatMap((execution): ActivityTimelineEntry[] => {
+    const at = new Date(execution.createdAt)
+    const executor = execution.executor
+    const authority = execution.authorizationRef
+
+    if (executor.type === "primitive" && authority.type === "trustedPrimitive") {
+      if (executor.kind === "action") {
+        const run = actionRunByExecution.get(execution.id)
+        const subject = run?.subject.kind === "object" ? run.subject : undefined
+        const object =
+          subject && readable.has(objectBatchKey(subject.objectTypeId, subject.primaryId))
+            ? { objectTypeId: subject.objectTypeId, primaryId: subject.primaryId }
+            : undefined
+
+        // As the runs page decides: the action and its subject's type, and the type's markings.
+        const runVisible =
+          run !== undefined &&
+          canViewActionRun(runtime.authorization, run) &&
+          (subject === undefined || !unreadableRunTypes.has(subject.objectTypeId))
+
+        return [
+          {
+            kind: "action",
+            at,
+            executionId: execution.id,
+            actionId: authority.primitive.id,
+            runId: executor.runId,
+            status: run?.status ?? "incomplete",
+            runVisible,
+            ...(object === undefined ? {} : { object }),
+          },
+        ]
+      }
+
+      if (executor.kind === "workflow") {
+        const run = workflowRunByExecution.get(execution.id)
+        return [
+          {
+            kind: "workflow",
+            at,
+            executionId: execution.id,
+            workflowId: authority.primitive.id,
+            runId: executor.runId,
+            status: run?.status ?? "incomplete",
+            runVisible: run !== undefined && canViewWorkflowRun(runtime.authorization, run),
+          },
+        ]
+      }
+    }
+
+    const conversation = conversations.get(execution.id)
+    if (conversation) {
+      const cost = costByAgent.get(execution.id)
+      return [
+        {
+          kind: "agent",
+          at,
+          executionId: execution.id,
+          runId: conversation.id,
+          threadId: conversation.threadId,
+          status: conversation.status,
+          messages: messagesByThread.get(conversation.threadId) ?? 0,
+          ...(cost === undefined ? {} : { cost }),
+        },
+      ]
+    }
+
+    return []
+  })
+
+  // Recorded entries come first at an equal instant, in their sequence: the sort is stable.
+  const recorded = [
+    ...page.pageViews.map(
+      (pageView): ActivityPageEntry => ({
+        kind: "page",
+        at: new Date(pageView.receivedAt),
+        sequence: pageView.sequence,
+        route: pageView.route,
+      })
+    ),
+    ...page.interactions.map(
+      (interaction): ActivityInteractionEntry => ({
+        kind: "interaction",
+        at: new Date(interaction.receivedAt),
+        sequence: interaction.sequence,
+        name: interaction.name,
+        route: interaction.route,
+      })
+    ),
+  ].sort((left, right) => left.sequence - right.sequence)
+
+  // Past the last page view, interaction or root kept, a source left rows out: the timeline stops
+  // there.
+  const cutoffs = [
+    page.hasMore ? recorded.at(-1)?.at : undefined,
+    ledger.truncated
+      ? executions.filter((execution) => execution.source.type !== "execution").at(-1)?.createdAt
+      : undefined,
+  ].flatMap((at) => (at === undefined ? [] : [at.getTime()]))
+  const cutoff = cutoffs.length > 0 ? Math.min(...cutoffs) : Number.POSITIVE_INFINITY
+
+  const entries = [...recorded, ...executionEntries]
+    .filter((entry) => entry.at.getTime() <= cutoff)
+    .sort((left, right) => left.at.getTime() - right.at.getTime())
+
+  return {
+    visit,
+    ...(connection === undefined ? {} : { connection }),
+    entries,
+    truncated: page.hasMore || ledger.truncated,
+  }
+}
+
+/**
+ * Roots created in `[start - grace, last activity + grace)`, cut where the session's next visit
+ * may start once this one is a day old.
+ */
+function sessionWindow(visit: ActivityVisit): { readonly from: Date; readonly to: Date } {
+  const startedAt = visit.startedAt.getTime()
+  return {
+    from: new Date(startedAt - SESSION_GRACE_MS),
+    to: new Date(
+      Math.min(
+        visit.lastSeenAt.getTime() + SESSION_GRACE_MS,
+        startedAt + ACTIVITY_MAX_VISIT_MS - SESSION_GRACE_MS
+      )
+    ),
+  }
+}
+
+/** An execution, then its parent and the parent's, as far as the visit's executions go. */
+function lineage(
+  execution: ExecutionRecord,
+  byId: ReadonlyMap<string, ExecutionRecord>
+): readonly ExecutionRecord[] {
+  const chain: ExecutionRecord[] = []
+  let current: ExecutionRecord | undefined = execution
+
+  while (current) {
+    chain.push(current)
+    current = current.source.type === "execution" ? byId.get(current.source.executionId) : undefined
+  }
+  return chain
+}
+
+/** Each conversation's cost: its own calls and those of everything below it, each counted once. */
+function rollUpCosts(
+  byId: ReadonlyMap<string, ExecutionRecord>,
+  conversations: ReadonlyMap<string, ConversationAgentRunRecord>,
+  withAgent: readonly ExecutionRecord[],
+  costs: readonly (AiCostSummary | undefined)[]
+): ReadonlyMap<string, AiCostSummary> {
+  const grouped = new Map<string, AiCostSummary[]>()
+
+  withAgent.forEach((execution, index) => {
+    const cost = costs[index]
+    const owner = lineage(execution, byId).find((ancestor) => conversations.has(ancestor.id))
+    if (!cost || !owner) {
+      return
+    }
+
+    const summaries = grouped.get(owner.id) ?? []
+    summaries.push(cost)
+    grouped.set(owner.id, summaries)
+  })
+
+  return new Map(
+    [...grouped].flatMap(([owner, summaries]) => {
+      const total = addCosts(summaries)
+      return total ? [[owner, total] as const] : []
+    })
+  )
+}
+
+function addCosts(summaries: readonly AiCostSummary[]): AiCostSummary | undefined {
+  const amounts = new Map<string, bigint>()
+  let ratedCallCount = 0
+  let unpriceableCallCount = 0
+  let unvaluedCallCount = 0
+
+  for (const summary of summaries) {
+    for (const money of summary.amounts) {
+      amounts.set(money.currency, (amounts.get(money.currency) ?? 0n) + BigInt(money.amountNanos))
+    }
+    ratedCallCount += summary.ratedCallCount
+    unpriceableCallCount += summary.unpriceableCallCount
+    unvaluedCallCount += summary.unvaluedCallCount
+  }
+
+  if (ratedCallCount + unpriceableCallCount + unvaluedCallCount === 0) {
+    return undefined
+  }
+
+  return {
+    amounts: [...amounts]
+      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+      .map(([currency, amount]) => ({ currency, amountNanos: amount.toString() })),
+    ratedCallCount,
+    unpriceableCallCount,
+    unvaluedCallCount,
+  }
+}
+
+/**
+ * The action subjects the viewer can read, through its own object reader: object type grants,
+ * markings and existence alike. One batch per object type, as a type the viewer cannot see fails
+ * its whole batch.
+ */
+async function readableObjects(
+  runtime: SixbRuntimeContext,
+  subjects: readonly ActionObjectSubject[]
+): Promise<ReadonlySet<string>> {
+  const byType = new Map<string, Map<string, ActionObjectSubject>>()
+  for (const subject of subjects) {
+    const items = byType.get(subject.objectTypeId) ?? new Map()
+    items.set(subject.primaryId, subject)
+    byType.set(subject.objectTypeId, items)
+  }
+
+  const readable = new Set<string>()
+  await Promise.all(
+    [...byType.values()].map(async (items) => {
+      try {
+        const rows = await runtime.objectReader.getByPrimaryIdBatch({ items: [...items.values()] })
+        for (const key of rows.keys()) {
+          readable.add(key)
+        }
+      } catch (error) {
+        if (!(error instanceof AuthorizationError)) {
+          throw error
+        }
+      }
+    })
+  )
+  return readable
+}

package/src/agents/index.ts

@@ -1,4 +1,9 @@
 export type { PropertyClearance } from "../objects/property-clearance"
+export {
+  captureSandboxEnv,
+  sandboxCredentialIssue,
+  staticSandboxRecipe,
+} from "../sandboxes/configuration"
 export type {
   AgentFileDataProjection,
   AgentFileDataResolverInput,
@@ -156,14 +161,14 @@ export type {
   AgentDescriptor,
   AgentReasoning,
   AgentReference,
-  AgentToolArtifact,
-  AgentToolArtifactPutInput,
-  AgentToolArtifacts,
   AgentToolAttachments,
   AgentToolContent,
   AgentToolDefinition,
   AgentToolDescriptionBuilder,
+  AgentToolFile,
   AgentToolFileContent,
+  AgentToolFilePutInput,
+  AgentToolFiles,
   AgentToolHandler,
   AgentToolHandlerResult,
   AgentToolInputBuilder,

package/src/agents/request.ts

@@ -253,6 +253,11 @@ export async function retryAgentRun(
       threadId: failedRun.threadId,
       runId: failedRun.id,
     })
+    // What the failed turn published goes with what it said, so the retry starts clean.
+    await tx.artifacts?.deleteVersionsByOrigin({
+      projectId: runtime.projectId,
+      runId: failedRun.id,
+    })
     await tx.executions.create(durableExecution)
     return agents.runs.create({
       id: runId,

package/src/agents/skills.ts

@@ -50,6 +50,12 @@ export function createAgentSkillCatalog(
   const skills = Object.freeze([...(definitions ?? [])])
   const skillsByName = new Map<string, AgentSkillDefinition>()
   for (const skill of skills) {
+    // As discovery refuses them: the worker adds its built-in skills under this prefix.
+    if (skill.name.startsWith("sixb-")) {
+      throw new RuntimeError(
+        `[Sixb] Agent Skill name '${skill.name}' uses the reserved 'sixb-' prefix.`
+      )
+    }
     if (skillsByName.has(skill.name)) {
       throw new RuntimeError(`[Sixb] Duplicate Agent Skill name: ${skill.name}`)
     }

package/src/agents/types.ts

@@ -80,22 +80,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>
 }
 
 /**
@@ -159,7 +159,7 @@ export interface AgentToolRunContext<
   readonly run: AgentToolRunInfo
   readonly sixb: AgentToolRuntimeFacade
   readonly logger: Logger
-  readonly artifacts: AgentToolArtifacts
+  readonly files: AgentToolFiles
   readonly attachments: AgentToolAttachments
 }
 

package/src/agents/validation.ts

@@ -13,6 +13,8 @@ export const AGENT_RESERVED_TOOL_NAMES = [
   "view_file",
   "spawn_agent",
   "wait_agent",
+  "publish_artifact",
+  "publish_artifact_version",
 ] as const
 
 export function isAgentToolDefinition(value: unknown): value is AgentToolDefinition {

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("/")
+}