Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
40.8 KB
Raw Blame
import type { FileReferenceV1 } from '@clerum/gfs-interaction-policy'
import type { FileReferenceResolution } from '../agent/fileReferenceResolver'
import { logger } from '../logger'
import { inspectImage, validateImage } from '../visualInput/imageValidation'
import { VisualInputError } from '../visualInput/policy'
import type { MemoryReservation } from '../visualInput/policy'
import type {
  InternalToolCallContext,
  InternalToolDefinition,
  InternalToolExecutionOptions,
  InternalToolResult,
} from '../workflow/types'
import { GfscHttpError } from './gfsClient'
import { GfsDownloadError } from './gfsContentDownload'
import type { GfsDownloadOptions, GfsDownloadResult } from './gfsContentDownload'
import { type GfsMetadataSnapshot, normalizeRid } from './gfsContentRead'
import {
  enterGfsDownloadTransfer,
  exitGfsDownloadTransfer,
  recordGfsDownloadAdmission,
  recordGfsDownloadTransfer,
} from './gfsDownloadMetrics'
import { GfsDownloadStore, GfsDownloadStoreError } from './gfsDownloadStore'
import { GFS_FILE_LIMITS } from './gfsFilePolicy'
import {
  GFS_LOCAL_PROCESSING_GUIDANCE,
  type GfsFileContent,
  type GfsReadOptions,
} from './gfsReadTypes'
import { gfsStoreSpaceGuidance } from './gfsSpaceGuidance'
import { decodeTextContent } from './textContent'

/**
 * Agent gfs READ tools (spec community.md §Operator surfaces, plan P3-S04).
 * clerum__gfs_list/read/stat/resolve let an agent browse and read the Global
 * File System through gfsc, using its dedicated aud=gfs-controller token. P3 is
 * READ-ONLY — write (clerum__gfs_write) lands in P4. Every result carries the
 * stable `gfsUri` so links survive rename/move.
 */

/**
 * Per-call bounds from the tool call that issues the request. `signal` cancels
 * the request and any 429 retry sleep; `deadlineMs` (epoch ms) is when the
 * calling tool's budget ends, so a retry never sleeps past it.
 */
export interface GfscCallOptions {
  signal?: AbortSignal
  deadlineMs?: number
}

/** The gfsc read surface, injected so the tools are unit-tested without gfsc. */
export interface GfscReadClient {
  accessible(args: { drive: string; cursor?: string }, call?: GfscCallOptions): Promise<unknown>
  list(
    args: { drive: string; resourceId: string; cursor?: string },
    call?: GfscCallOptions
  ): Promise<unknown>
  read(
    args: { drive: string; resourceId: string },
    options?: GfsReadOptions
  ): Promise<GfsFileContent>
  readMetadata?(
    args: { drive: string; resourceId: string },
    options: {
      signal?: AbortSignal
      timeoutMs?: number
      deadlineMs?: number
      expectedVersion?: number
    }
  ): Promise<GfsMetadataSnapshot>
  download?(
    args: { drive: string; resourceId: string },
    options: GfsDownloadOptions
  ): Promise<GfsDownloadResult>
  stat(args: { drive: string; resourceId: string }, call?: GfscCallOptions): Promise<unknown>
  resolve(args: { uri: string }, call?: GfscCallOptions): Promise<unknown>
}

/** Turns a tool call's execution context into the client's per-call bounds. */
function callOptions(context?: InternalToolCallContext): GfscCallOptions {
  return {
    signal: context?.signal,
    deadlineMs: context?.timeoutMs === undefined ? undefined : Date.now() + context.timeoutMs,
  }
}

function ok(content: unknown): InternalToolResult {
  return { success: true, content: typeof content === 'string' ? content : JSON.stringify(content) }
}
// Read failures get the same redaction floor as mutations (see mutationFail):
// only gfsc's HTTP status and a coarse public category may reach the model —
// never the response body, which could carry paths or server internals.
// A store space refusal keeps its fixed envelope as the first line and adds the
// fixed guidance for its code as a second line; gfsFilePreparation accepts that
// exact second line and nothing else. Every other store code, including
// `volume_unmeasurable`, is the bare envelope.
function fail(error: unknown): InternalToolResult {
  if (error instanceof VisualInputError) return { success: false, error: error.message }
  if (error instanceof GfsDownloadStoreError) {
    const guidance = gfsStoreSpaceGuidance(error.code)
    return {
      success: false,
      error: guidance === undefined ? error.message : `${error.message}\n${guidance}`,
    }
  }
  if (error instanceof GfsDownloadError) return { success: false, error: error.message }
  return redactedFail('GFS read failed', error)
}

function versionConflict(error: unknown): boolean {
  return (
    (error instanceof VisualInputError && error.code === 'version_conflict') ||
    (error instanceof GfsDownloadError && error.code === 'version_conflict')
  )
}

function fileReference(file: GfsFileContent, reason: string): InternalToolResult {
  return ok({
    resource: file.source,
    sizeBytes: file.bytes.byteLength,
    delivery: 'reference_only',
    reason,
  })
}

function isSvgText(text: string): boolean {
  let remaining = text.trimStart()
  // Scan each prefix once; do not use a repeated, backtracking XML regex on
  // untrusted file content. This is format recognition, never XML execution.
  for (;;) {
    const end = remaining.startsWith('<?')
      ? remaining.indexOf('?>', 2)
      : remaining.startsWith('<!--')
        ? remaining.indexOf('-->', 4)
        : -1
    if (end < 0) break
    const suffixLength = remaining.startsWith('<?') ? 2 : 3
    remaining = remaining.slice(end + suffixLength).trimStart()
  }
  return /^<svg[\s>/]/i.test(remaining) || /^<!DOCTYPE\s+svg[\s>]/i.test(remaining)
}
// Locally-authored argument-validation messages carry no server data and must
// reach the model verbatim so the agent can correct its call.
function invalidArgs(message: string): InternalToolResult {
  return { success: false, error: message }
}

function workspaceFileUsage(visualDelivery: 'included' | 'not_included', visualReason?: string) {
  return {
    pathSemantics: 'relative-to-caller-workspace',
    nextTool: 'shell_exec_when_local_processing_is_needed',
    visualDelivery,
    ...(visualReason === undefined ? {} : { visualReason }),
    approval: 'user-approval-required',
    writeOutputsTo: 'outputs/',
    processLocally: true,
    boundedOutputOnly: true,
    wholeFileToContextAllowed: false,
    processingInstructions: GFS_LOCAL_PROCESSING_GUIDANCE,
  }
}

function workspaceFileWithoutImage(receipt: GfsDownloadResult, reason: string): InternalToolResult {
  return ok({
    delivery: 'workspace_file',
    ...receipt,
    visualDelivery: 'not_included',
    visualReason: reason,
    usage: workspaceFileUsage('not_included', reason),
  })
}

async function projectManagedImage(
  receipt: GfsDownloadResult,
  downloadStore: GfsDownloadStore,
  callerIdentity: string,
  options: InternalToolExecutionOptions | undefined,
  knownBytes?: Buffer
): Promise<InternalToolResult> {
  let readReservation: MemoryReservation | undefined
  try {
    let bytes = knownBytes
    const prefix =
      bytes?.subarray(0, 16) ??
      (await downloadStore.readManagedFilePrefix(receipt.path, callerIdentity))
    const hasImageMagic =
      prefix.length >= 3 &&
      ((prefix[0] === 0x89 && prefix[1] === 0x50 && prefix[2] === 0x4e) ||
        (prefix[0] === 0xff && prefix[1] === 0xd8 && prefix[2] === 0xff))
    if (!hasImageMagic) return workspaceFileWithoutImage(receipt, 'not_image')
    const visualInput = options?.visualInput
    if (!visualInput)
      return workspaceFileWithoutImage(receipt, 'image_input_unavailable_in_this_execution')
    const capability = await visualInput.resolveCapability(options?.signal)
    if (options?.signal?.aborted) throw new VisualInputError('cancelled')
    if (capability.status !== 'supported')
      return workspaceFileWithoutImage(receipt, `model_image_input_${capability.status}`)
    const profile = capability.deliveryLimits
    if (!profile) return workspaceFileWithoutImage(receipt, 'provider_visual_profile_unavailable')
    if (
      (profile.maxImageBytes !== undefined && receipt.sizeBytes > profile.maxImageBytes) ||
      (profile.maxImageEncodedBytes !== undefined &&
        4 * Math.ceil(receipt.sizeBytes / 3) > profile.maxImageEncodedBytes)
    )
      return workspaceFileWithoutImage(receipt, 'provider_visual_limit_exceeded')
    if (bytes === undefined) {
      if (receipt.sizeBytes > visualInput.budget.remainingReadBytes)
        throw new VisualInputError('limit_exceeded')
      // Reserve before the physical read. Inline classification bytes already
      // carry their read reservation and are not charged twice.
      readReservation = visualInput.budget.reserve(receipt.sizeBytes)
      visualInput.budget.consumeRead(receipt.sizeBytes)
      bytes = await downloadStore.readManagedFile(receipt.path, callerIdentity)
    }
    if (options?.signal?.aborted) throw new VisualInputError('cancelled')
    const limits = {
      maxFileBytes: profile.maxImageBytes ?? GFS_FILE_LIMITS.maxFileBytes,
      maxDimension: profile.maxDimension,
      maxPixels: profile.maxPixels,
    }
    const image = inspectImage(bytes, limits)
    if (!image) return workspaceFileWithoutImage(receipt, 'not_image')
    if (
      (profile.maxDimension !== undefined &&
        (image.width > profile.maxDimension || image.height > profile.maxDimension)) ||
      (profile.maxPixels !== undefined && image.width * image.height > profile.maxPixels)
    )
      return workspaceFileWithoutImage(receipt, 'provider_visual_limit_exceeded')
    await validateImage(bytes, image, {
      signal: options?.signal,
      budget: visualInput.budget,
      limits,
    })
    if (options?.signal?.aborted) throw new VisualInputError('cancelled')
    const dataBase64 = visualInput.budget.encodeImage(bytes)
    return {
      success: true,
      content: JSON.stringify({
        delivery: 'workspace_file',
        ...receipt,
        visualDelivery: 'included',
        usage: workspaceFileUsage('included'),
      }),
      images: [{ ...image, source: receipt.source, sizeBytes: receipt.sizeBytes, dataBase64 }],
    }
  } catch (error) {
    if (error instanceof VisualInputError && error.code !== 'cancelled')
      return workspaceFileWithoutImage(
        receipt,
        error.code === 'limit_exceeded' ? 'local_visual_resources_exceeded' : error.code
      )
    throw error
  } finally {
    readReservation?.release()
  }
}

const driveResourceParams = {
  type: 'object',
  required: ['drive', 'resourceId'],
  properties: {
    drive: { type: 'string', description: 'gfs drive name (e.g. "main").' },
    resourceId: {
      type: 'string',
      description:
        'The resourceId returned by GFS discovery (32-hex rid or UUID). A filename, path, or UUID embedded in a filename is not the resourceId. For a human path, find the accessible folder and list its children first.',
    },
  },
} as const

const DOWNLOAD_RESOURCE_ID_PATTERN =
  '^(?:[0-9a-fA-F]{32}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$'
const DOWNLOAD_RESOURCE_ID = new RegExp(DOWNLOAD_RESOURCE_ID_PATTERN)
const downloadDriveResourceParams = {
  ...driveResourceParams,
  properties: {
    ...driveResourceParams.properties,
    resourceId: {
      ...driveResourceParams.properties.resourceId,
      pattern: DOWNLOAD_RESOURCE_ID_PATTERN,
    },
  },
} as const

function downloadTargetError(args: Record<string, unknown>): string | null {
  if (typeof args.drive !== 'string' || args.drive.length === 0)
    return 'drive must be the non-empty GFS drive name returned by discovery.'
  if (typeof args.resourceId !== 'string' || !DOWNLOAD_RESOURCE_ID.test(args.resourceId))
    return 'resourceId must be the observed 32-hex or dashed UUID from clerum__gfs_accessible/clerum__gfs_list; filenames, paths, and gfs:// URIs are not resource IDs.'
  return null
}

/**
 * #666 — the version a file reference of the turn's message pins, and the
 * version gfsc reported instead when the reference was stale.
 */
export interface ReferencedFilePin {
  version: number
  currentVersion?: number
  /** Producer-classified payload size; retained without filename inference. */
  byteLength?: FileReferenceV1['byteLength']
  /** Producer byte classification: text, image, or binary. */
  reader?: FileReferenceV1['reader']
  /** Producer-declared visual candidacy, not a provider-capability claim. */
  modelImageInput?: FileReferenceV1['modelImageInput']
}

/** Pins keyed by `${drive}/${rid}`, with the rid normalized as gfsc names it. */
export type ReferencedFilePins = ReadonlyMap<string, ReferencedFilePin>

function referencedFileKey(drive: unknown, resourceId: unknown): string | null {
  const rid = normalizeRid(resourceId)
  return typeof drive === 'string' && rid ? `${drive}/${rid}` : null
}

/** The pins of every GFS reference the message carried, whatever its availability. */
export function referencedFilePins(
  resolutions: readonly FileReferenceResolution[] | undefined
): ReferencedFilePins {
  const pins = new Map<string, ReferencedFilePin>()
  for (const { availability, reference, resolvedVersion } of resolutions ?? []) {
    const source = reference.source
    if (source.kind !== 'gfs') continue
    const key = referencedFileKey(source.drive, source.resourceId)
    if (!key) throw new Error('A resolved GFS file reference must carry a 32-hex resourceId')
    pins.set(key, {
      version: source.version,
      byteLength: reference.byteLength,
      reader: reference.reader,
      modelImageInput: reference.modelImageInput,
      ...(availability === 'stale' && resolvedVersion !== undefined
        ? { currentVersion: resolvedVersion }
        : {}),
    })
  }
  return pins
}

function pinnedVersionMessage(pin: ReferencedFilePin): string {
  const base = `This file is referenced in the current message at version ${pin.version}. Omit expectedVersion or pass ${pin.version}`
  return pin.currentVersion === undefined
    ? `${base}.`
    : `${base}, or pass its current_version ${pin.currentVersion} to read the current file.`
}

/**
 * #666 — stat, resolve and list report the live resource, which can be newer
 * than the version a referenced file is pinned to for clerum__gfs_read.
 */
const LIVE_RESOURCE_NOTE =
  'Reports the live resource; a file referenced in the current message is read at its listed version, or at its current_version once the reference is stale.'

export interface GfsReadToolOptions {
  /** Files the turn's message referenced; an empty map when there is no message. */
  referencedFiles: ReferencedFilePins
  /** Host-owned durable store; task registries receive a caller-bound handle. */
  downloadStore?: GfsDownloadStore
  /** Trusted identity derived by the Host, never tool arguments. */
  callerIdentity?: string
  /** Caller workspace root derived by the Host, never tool arguments. */
  callerWorkspacePath?: string
  /** Trusted task lifetime identity; never accepted from model arguments. */
  retentionOwnerId?: string
}

/** The five read tools, bound to a gfsc client. */
export function buildGfsReadTools(
  client: GfscReadClient,
  {
    referencedFiles,
    downloadStore,
    callerIdentity,
    callerWorkspacePath,
    retentionOwnerId,
  }: GfsReadToolOptions
): InternalToolDefinition[] {
  const canDownload = Boolean(
    downloadStore && client.download && callerIdentity && callerWorkspacePath && retentionOwnerId
  )
  const transferToWorkspace = async (
    target: { drive: string; resourceId: string },
    expectedVersion: number | undefined,
    context?: InternalToolExecutionOptions
  ): Promise<GfsDownloadResult> => {
    if (
      !downloadStore ||
      !client.download ||
      !callerIdentity ||
      !callerWorkspacePath ||
      !retentionOwnerId
    )
      throw new GfsDownloadStoreError('workspace_unavailable')
    const transferStartedAt = Date.now()
    enterGfsDownloadTransfer()
    try {
      const receipt = await client.download(target, {
        store: downloadStore,
        callerIdentity,
        callerWorkspacePath,
        retentionOwnerId,
        ...callOptions(context),
        timeoutMs: context?.timeoutMs,
        ...(expectedVersion === undefined ? {} : { expectedVersion }),
      })
      recordGfsDownloadTransfer('success', (Date.now() - transferStartedAt) / 1000)
      return receipt
    } catch (error) {
      recordGfsDownloadTransfer('failure', (Date.now() - transferStartedAt) / 1000)
      throw error
    } finally {
      exitGfsDownloadTransfer()
    }
  }
  const downloadToWorkspace = async (
    target: { drive: string; resourceId: string },
    expectedVersion: number | undefined,
    context?: InternalToolExecutionOptions
  ): Promise<InternalToolResult> => {
    const receipt = await transferToWorkspace(target, expectedVersion, context)
    return ok({
      delivery: 'workspace_file',
      ...receipt,
      usage: workspaceFileUsage('not_included'),
    })
  }
  const tools: InternalToolDefinition[] = [
    {
      name: 'clerum__gfs_accessible',
      description:
        'List directly accessible GFS resources, including effective permissions and stable gfsUri links. A directory with coversDescendants grants access to its children; discover those children with clerum__gfs_list before reading or downloading a named file.',
      parameters: {
        type: 'object',
        required: ['drive'],
        properties: {
          drive: { type: 'string', description: 'gfs drive name (e.g. "main").' },
          cursor: { type: 'string', description: 'Opaque pagination cursor.' },
        },
      },
      execute: async (
        args: Record<string, unknown>,
        _outputDir: string,
        context?: InternalToolCallContext
      ): Promise<InternalToolResult> => {
        try {
          return ok(
            await client.accessible(
              args as { drive: string; cursor?: string },
              callOptions(context)
            )
          )
        } catch (err) {
          return fail(err)
        }
      },
    },
    {
      name: 'clerum__gfs_list',
      description: `List the children of a gfs directory. Returns entries with their gfsUri. ${LIVE_RESOURCE_NOTE}`,
      parameters: {
        type: 'object',
        required: ['drive', 'resourceId'],
        properties: {
          ...driveResourceParams.properties,
          cursor: { type: 'string', description: 'Opaque pagination cursor.' },
        },
      },
      execute: async (
        args: Record<string, unknown>,
        _outputDir: string,
        context?: InternalToolCallContext
      ): Promise<InternalToolResult> => {
        try {
          return ok(
            await client.list(
              args as { drive: string; resourceId: string; cursor?: string },
              callOptions(context)
            )
          )
        } catch (err) {
          return fail(err)
        }
      },
    },
    {
      name: 'clerum__gfs_read',
      description:
        'Read a GFS file by drive + resourceId. Returns bounded UTF-8 text inline; larger admitted sources are delivered as governed workspace files, and a valid JPEG/PNG may additionally become visual input after its workspace receipt is preserved. ' +
        'The Host reads a referenced_file from the turn context at the version the reference names; pass expectedVersion only to read the current_version of a stale reference. If the file changed since it was referenced, the result has availability "stale" and no content.',
      parameters: {
        ...driveResourceParams,
        properties: {
          ...driveResourceParams.properties,
          expectedVersion: {
            type: 'integer',
            minimum: 0,
            description:
              'Read only this version of the file. For a referenced_file, only its version or, when stale, its current_version is accepted.',
          },
        },
      },
      execute: async (
        args: Record<string, unknown>,
        _outputDir: string,
        options?: InternalToolExecutionOptions
      ): Promise<InternalToolResult> => {
        const { expectedVersion: requestedVersion, ...target } = args
        if (requestedVersion !== undefined && !isValidIfMatch(requestedVersion))
          return invalidArgs('expectedVersion must be a non-negative integer.')
        // #666 — a file the message referenced is read at the referenced
        // version, or at the current version gfsc reported for a stale one.
        const key = referencedFileKey(target.drive, target.resourceId)
        const pin = key === null ? undefined : referencedFiles.get(key)
        let expectedVersion = requestedVersion
        if (pin) {
          if (requestedVersion === undefined) expectedVersion = pin.version
          else if (requestedVersion !== pin.version && requestedVersion !== pin.currentVersion)
            return invalidArgs(pinnedVersionMessage(pin))
        }
        let file: GfsFileContent | undefined
        let snapshot: GfsMetadataSnapshot | undefined
        try {
          if (client.readMetadata) {
            const metadata = await client.readMetadata(
              target as { drive: string; resourceId: string },
              {
                ...callOptions(options),
                timeoutMs: options?.timeoutMs,
                ...(expectedVersion === undefined ? {} : { expectedVersion }),
              }
            )
            snapshot = metadata
            if (metadata.size > GFS_FILE_LIMITS.inlineTextBytes) {
              if (canDownload) {
                recordGfsDownloadAdmission('workspace_attempt')
                const receipt = await transferToWorkspace(
                  target as { drive: string; resourceId: string },
                  metadata.source.version,
                  options
                )
                return await projectManagedImage(receipt, downloadStore!, callerIdentity!, options)
              } else {
                recordGfsDownloadAdmission('workspace_unavailable')
                expectedVersion ??= metadata.source.version
                return ok({
                  availability: 'workspace_delivery_unavailable',
                  resource: metadata.source,
                  sizeBytes: metadata.size,
                  inlineTextBytes: GFS_FILE_LIMITS.inlineTextBytes,
                  reason: 'workspace_delivery_is_required_for_this_file_size',
                })
              }
            }
          }
          recordGfsDownloadAdmission('inline_attempt')
          if (expectedVersion === undefined && snapshot?.source.version !== undefined)
            expectedVersion = snapshot.source.version
          file = await client.read(target as { drive: string; resourceId: string }, {
            ...callOptions(options),
            timeoutMs: options?.timeoutMs,
            budget: options?.readBudget ?? options?.visualInput?.budget,
            ...(snapshot === undefined ? {} : { metadataSnapshot: snapshot }),
            ...((snapshot?.source.version ?? expectedVersion) === undefined
              ? {}
              : { expectedVersion: snapshot?.source.version ?? expectedVersion }),
          })
          if (options?.signal?.aborted) throw new VisualInputError('cancelled')
          const image = inspectImage(file.bytes, { maxFileBytes: GFS_FILE_LIMITS.maxFileBytes })
          if (image) {
            if (canDownload) {
              recordGfsDownloadAdmission('workspace_attempt')
              const receipt = await transferToWorkspace(
                target as { drive: string; resourceId: string },
                file.source.version,
                options
              )
              return await projectManagedImage(
                receipt,
                downloadStore!,
                callerIdentity!,
                options,
                file.bytes
              )
            }
            const visualInput = options?.visualInput
            if (!visualInput)
              return fileReference(file, 'image_input_unavailable_in_this_execution')
            const capability = await visualInput.resolveCapability(options?.signal)
            if (options?.signal?.aborted) throw new VisualInputError('cancelled')
            if (capability.status !== 'supported')
              return fileReference(file, `model_image_input_${capability.status}`)
            const profile = capability.deliveryLimits
            if (!profile) return fileReference(file, 'provider_visual_profile_unavailable')
            if (
              profile.maxImageEncodedBytes !== undefined &&
              4 * Math.ceil(file.bytes.byteLength / 3) > profile.maxImageEncodedBytes
            )
              return fileReference(file, 'provider_visual_limit_exceeded')
            await validateImage(file.bytes, image, {
              signal: options?.signal,
              budget: visualInput.budget,
              limits: {
                maxFileBytes: profile.maxImageBytes ?? GFS_FILE_LIMITS.maxFileBytes,
                maxDimension: profile.maxDimension,
                maxPixels: profile.maxPixels,
              },
            })
            if (options?.signal?.aborted) throw new VisualInputError('cancelled')
            const dataBase64 = visualInput.budget.encodeImage(file.bytes)
            return {
              success: true,
              content: JSON.stringify({
                resource: file.source,
                mimeType: image.mimeType,
                width: image.width,
                height: image.height,
                sizeBytes: file.bytes.byteLength,
                delivery: 'image_input',
              }),
              images: [
                { ...image, source: file.source, sizeBytes: file.bytes.byteLength, dataBase64 },
              ],
            }
          }
          // Inline text is bounded by the generic GFS policy; larger sources were
          // routed to the workspace before this in-memory read.
          const text = decodeTextContent(file.bytes)
          if (text === null || isSvgText(text)) {
            if (canDownload) {
              recordGfsDownloadAdmission('workspace_attempt')
              return await downloadToWorkspace(
                target as { drive: string; resourceId: string },
                file.source.version,
                options
              )
            }
            return fileReference(
              file,
              text === null ? 'unsupported_binary_format' : 'svg_visual_input_not_supported'
            )
          }
          return ok(text)
        } catch (err) {
          if (
            snapshot === undefined &&
            err instanceof VisualInputError &&
            err.code === 'limit_exceeded'
          )
            recordGfsDownloadAdmission('limit_exceeded')
          // #666 — with an expected version, a version conflict is an answer about
          // the reference, not a read failure.
          if (expectedVersion !== undefined && versionConflict(err))
            return ok({
              availability: 'stale',
              drive: target.drive,
              resourceId: target.resourceId,
              expectedVersion,
            })
          return fail(err)
        } finally {
          file?.reservation.release()
        }
      },
    },
    {
      name: 'clerum__gfs_stat',
      description: `Stat a gfs resource (name, kind, version, bytes, gfsUri). ${LIVE_RESOURCE_NOTE}`,
      parameters: driveResourceParams,
      execute: async (
        args: Record<string, unknown>,
        _outputDir: string,
        context?: InternalToolCallContext
      ): Promise<InternalToolResult> => {
        try {
          return ok(
            await client.stat(args as { drive: string; resourceId: string }, callOptions(context))
          )
        } catch (err) {
          return fail(err)
        }
      },
    },
    {
      name: 'clerum__gfs_resolve',
      description: `Resolve a gfs:// URI to its current resource + canonical path. ${LIVE_RESOURCE_NOTE}`,
      parameters: {
        type: 'object',
        required: ['uri'],
        properties: { uri: { type: 'string', description: 'A gfs:// URI.' } },
      },
      execute: async (
        args: Record<string, unknown>,
        _outputDir: string,
        context?: InternalToolCallContext
      ): Promise<InternalToolResult> => {
        try {
          return ok(await client.resolve(args as { uri: string }, callOptions(context)))
        } catch (err) {
          return fail(err)
        }
      },
    },
  ]
  if (canDownload) {
    tools.push({
      name: 'clerum__gfs_download',
      description:
        'Download a GFS file to this caller workspace without putting its contents in model context. Returns source metadata, SHA-256, exact size, version, expiry, and a relative workspace path for approved local processing.',
      parameters: {
        ...downloadDriveResourceParams,
        properties: {
          ...downloadDriveResourceParams.properties,
          expectedVersion: {
            type: 'integer',
            minimum: 0,
            description: 'Download only this version of the file.',
          },
        },
      },
      execute: async (args, _outputDir, options): Promise<InternalToolResult> => {
        const inputError = downloadTargetError(args)
        if (inputError) return invalidArgs(inputError)
        const { expectedVersion: requestedVersion, ...target } = args
        if (requestedVersion !== undefined && !isValidIfMatch(requestedVersion))
          return invalidArgs('expectedVersion must be a non-negative integer.')
        const key = referencedFileKey(target.drive, target.resourceId)
        const pin = key === null ? undefined : referencedFiles.get(key)
        let expectedVersion = requestedVersion
        if (pin) {
          if (requestedVersion === undefined) expectedVersion = pin.version
          else if (requestedVersion !== pin.version && requestedVersion !== pin.currentVersion)
            return invalidArgs(pinnedVersionMessage(pin))
        }
        try {
          return await downloadToWorkspace(
            target as { drive: string; resourceId: string },
            expectedVersion as number | undefined,
            options
          )
        } catch (error) {
          // Traces omit tool arguments; retain only public target identifiers
          // and a bounded failure category, never GFSC bodies or raw errors.
          const drive =
            typeof target.drive === 'string' &&
            target.drive.length > 0 &&
            target.drive.length <= 64 &&
            !/[^a-z0-9_-]/.test(target.drive)
              ? target.drive
              : undefined
          const resourceId = normalizeRid(target.resourceId)
          const status =
            error instanceof GfscHttpError
              ? error.status
              : error instanceof Error
                ? Number(/^gfsc (\d{3}):/.exec(error.message)?.[1])
                : Number.NaN
          logger.warn(
            {
              component: 'GfsDownload',
              ...(drive === undefined ? {} : { drive }),
              ...(resourceId?.length === 32 ? { resourceId } : {}),
              ...(Number.isInteger(status) && status >= 100 && status <= 599
                ? { httpStatus: status }
                : {}),
              errorClass:
                error instanceof GfscHttpError
                  ? 'GfscHttpError'
                  : error instanceof GfsDownloadError
                    ? 'GfsDownloadError'
                    : error instanceof GfsDownloadStoreError
                      ? 'GfsDownloadStoreError'
                      : error instanceof VisualInputError
                        ? 'VisualInputError'
                        : error instanceof Error
                          ? 'Error'
                          : 'unknown',
            },
            'GFS workspace download failed'
          )
          if (expectedVersion !== undefined && versionConflict(error))
            return ok({ availability: 'stale', ...target, expectedVersion })
          return fail(error)
        }
      },
    })
  }
  return tools
}

/** The gfsc write surface (P4) — read + write. */
export interface GfscWriteClient extends GfscReadClient {
  write(
    args: {
      drive: string
      resourceId: string
      content: string
      ifMatch: number
    },
    call?: GfscCallOptions
  ): Promise<unknown>
  createFile(
    args: {
      drive: string
      parentResourceId: string
      name: string
      content: string
    },
    call?: GfscCallOptions
  ): Promise<unknown>
  createFolder(
    args: { drive: string; parentResourceId: string; name: string },
    call?: GfscCallOptions
  ): Promise<unknown>
  rename(
    args: {
      drive: string
      resourceId: string
      newName: string
      ifMatch: number
    },
    call?: GfscCallOptions
  ): Promise<unknown>
  copy(
    args: {
      drive: string
      sourceResourceId: string
      destinationParentId: string
      newName?: string
      ifMatch: number
    },
    call?: GfscCallOptions
  ): Promise<unknown>
}

// Preserve only GFSC's HTTP status and a coarse public category. The server
// keeps the detailed correlated evidence; paths, blob keys, SQL details and
// response bodies must not cross into the model-visible tool result. Keeping
// 403 distinguishable is required for immediate-revocation and isolation
// journeys, while still making every failure safe to display.
function redactedFail(label: string, error: unknown): InternalToolResult {
  const message = error instanceof Error ? error.message : String(error)
  const match = /\bgfsc\s+(\d{3})\b/i.exec(message)
  if (!match) return { success: false, error: label }
  const status = Number(match[1])
  const category =
    status === 400
      ? 'invalid_request'
      : status === 401
        ? 'unauthenticated'
        : status === 403
          ? 'forbidden'
          : status === 404
            ? 'not_found'
            : status === 409
              ? 'conflict'
              : status === 412
                ? 'precondition_failed'
                : status === 413
                  ? 'limit_exceeded'
                  : status === 429
                    ? 'rate_limited'
                    : status >= 500
                      ? 'unavailable'
                      : 'failed'
  // The retry hint comes from the typed error's parsed Retry-After header, an
  // integer, never from the response body.
  const hint =
    error instanceof GfscHttpError && error.status === 429 && error.retryAfterSeconds !== undefined
      ? `, retry after ${error.retryAfterSeconds}s`
      : ''
  return { success: false, error: `${label} (gfsc ${status}: ${category}${hint})` }
}

function mutationFail(error: unknown): InternalToolResult {
  return redactedFail('GFS mutation failed', error)
}

function isValidIfMatch(value: unknown): value is number {
  return Number.isSafeInteger(value) && (value as number) >= 0
}

/**
 * Agent gfs WRITE tool (plan P4-S04). clerum__gfs_write replaces a file and
 * REQUIRES If-Match (the resource version) — agent writes are writer-routed
 * conditional writes (P4-S01); the mutation is audited server-side. Destructive
 * bits (delete) stay default-denied for agents.
 */
export function buildGfsWriteTools(client: GfscWriteClient): InternalToolDefinition[] {
  return [
    {
      name: 'clerum__gfs_write',
      description:
        'Conditionally replace the complete content of an existing gfs file. Requires If-Match (the current version).',
      parameters: {
        type: 'object',
        required: ['drive', 'resourceId', 'content', 'ifMatch'],
        properties: {
          drive: { type: 'string', description: 'gfs drive name.' },
          resourceId: { type: 'string', description: 'Resource id (32-hex rid).' },
          content: { type: 'string', description: 'New file content.' },
          ifMatch: { type: 'number', description: 'The resource version being replaced.' },
        },
      },
      execute: async (
        args: Record<string, unknown>,
        _outputDir: string,
        context?: InternalToolCallContext
      ): Promise<InternalToolResult> => {
        if (!isValidIfMatch(args.ifMatch)) {
          return invalidArgs('clerum__gfs_write requires a non-negative safe-integer If-Match')
        }
        try {
          return ok(
            await client.write(
              args as { drive: string; resourceId: string; content: string; ifMatch: number },
              callOptions(context)
            )
          )
        } catch (err) {
          return mutationFail(err)
        }
      },
    },
    {
      name: 'clerum__gfs_create_file',
      description: 'Create one file under an existing gfs folder.',
      parameters: {
        type: 'object',
        required: ['drive', 'parentResourceId', 'name', 'content'],
        properties: {
          drive: { type: 'string', description: 'gfs drive name.' },
          parentResourceId: { type: 'string', description: 'Destination folder resource id.' },
          name: {
            type: 'string',
            description:
              'New file name including its file extension, e.g. "report.txt" or "notes.md". Always match the content format.',
          },
          content: { type: 'string', description: 'Initial file content.' },
        },
      },
      execute: async (
        args: Record<string, unknown>,
        _outputDir: string,
        context?: InternalToolCallContext
      ): Promise<InternalToolResult> => {
        try {
          return ok(
            await client.createFile(
              args as { drive: string; parentResourceId: string; name: string; content: string },
              callOptions(context)
            )
          )
        } catch (err) {
          return mutationFail(err)
        }
      },
    },
    {
      name: 'clerum__gfs_create_folder',
      description: 'Create one folder under an existing gfs folder.',
      parameters: {
        type: 'object',
        required: ['drive', 'parentResourceId', 'name'],
        properties: {
          drive: { type: 'string', description: 'gfs drive name.' },
          parentResourceId: { type: 'string', description: 'Destination folder resource id.' },
          name: { type: 'string', description: 'New folder name.' },
        },
      },
      execute: async (
        args: Record<string, unknown>,
        _outputDir: string,
        context?: InternalToolCallContext
      ): Promise<InternalToolResult> => {
        try {
          return ok(
            await client.createFolder(
              args as { drive: string; parentResourceId: string; name: string },
              callOptions(context)
            )
          )
        } catch (err) {
          return mutationFail(err)
        }
      },
    },
    {
      name: 'clerum__gfs_rename',
      description:
        'Rename one gfs resource without moving it. Requires If-Match (the current resource version).',
      parameters: {
        type: 'object',
        required: ['drive', 'resourceId', 'newName', 'ifMatch'],
        properties: {
          drive: { type: 'string', description: 'gfs drive name.' },
          resourceId: { type: 'string', description: 'Resource id to rename.' },
          newName: { type: 'string', description: 'New file or folder name.' },
          ifMatch: { type: 'number', description: 'The observed resource version.' },
        },
      },
      execute: async (
        args: Record<string, unknown>,
        _outputDir: string,
        context?: InternalToolCallContext
      ): Promise<InternalToolResult> => {
        if (!isValidIfMatch(args.ifMatch)) {
          return invalidArgs('clerum__gfs_rename requires a non-negative safe-integer If-Match')
        }
        try {
          return ok(
            await client.rename(
              args as { drive: string; resourceId: string; newName: string; ifMatch: number },
              callOptions(context)
            )
          )
        } catch (err) {
          return mutationFail(err)
        }
      },
    },
  ]
}

/** Recursive copy is advertised only when both read and write scopes exist. */
export function buildGfsCopyTools(client: GfscWriteClient): InternalToolDefinition[] {
  return [
    {
      name: 'clerum__gfs_copy',
      description:
        'Copy one gfs file or folder tree into a destination folder. The original remains at the source; Copy never deletes it. Requires the observed source-root If-Match; file content remains server-side.',
      parameters: {
        type: 'object',
        required: ['drive', 'sourceResourceId', 'destinationParentId', 'ifMatch'],
        properties: {
          drive: { type: 'string', description: 'gfs drive name.' },
          sourceResourceId: { type: 'string', description: 'Source file or folder resource id.' },
          destinationParentId: { type: 'string', description: 'Destination folder resource id.' },
          newName: { type: 'string', description: 'Optional explicit name for the copied root.' },
          ifMatch: { type: 'number', description: 'The observed source-root version.' },
        },
      },
      execute: async (
        args: Record<string, unknown>,
        _outputDir: string,
        context?: InternalToolCallContext
      ): Promise<InternalToolResult> => {
        if (!isValidIfMatch(args.ifMatch)) {
          return invalidArgs('clerum__gfs_copy requires a non-negative safe-integer If-Match')
        }
        try {
          return ok(
            await client.copy(
              args as {
                drive: string
                sourceResourceId: string
                destinationParentId: string
                newName?: string
                ifMatch: number
              },
              callOptions(context)
            )
          )
        } catch (err) {
          return mutationFail(err)
        }
      },
    },
  ]
}