@spec attach(Codex.Thread.Options.t(), Codex.Files.Attachment.t()) ::
  Codex.Thread.Options.t()

Attaches an Attachment to the supplied ThreadOptions.

@spec cleanup!() :: :ok | {:error, term()}

Deprecated alias retained for backwards compatibility.

@spec force_cleanup() :: :ok | {:error, term()}

Removes staged files that are not marked as persistent.

@spec list_staged() :: [Codex.Files.Attachment.t()]

Lists staged attachments currently cached.

@spec list_staged_result() :: {:ok, [Codex.Files.Attachment.t()]} | {:error, term()}

Lists staged attachments with explicit success/error tuples.

@spec metrics() :: map() | {:error, term()}

Returns high-level staging metrics including counts and total bytes.

@spec reset!() :: :ok | {:error, term()}

Resets the staging directory and manifest.

@spec stage(
  Path.t(),
  keyword()
) :: {:ok, Codex.Files.Attachment.t()} | {:error, term()}

Stages a file for future attachment invocation.

Options:

• :name - override the attachment name (defaults to the basename of path)
• :persist - keep file around indefinitely (default: false)
• :ttl_ms - custom time-to-live for ephemeral attachments. Accepts :infinity or a non-negative integer in milliseconds. Defaults to Application.get_env/3 lookups of :attachment_ttl_ms and falls back to 24 hours.

@spec staging_dir() :: Path.t()

Returns the staging directory path.