@tealbrick/deliver

Deliver sandbox files to chat recipients using a provider chosen during setup. Node 24+, native Eve 0.55.0 tool adapter. Host-independent byte delivery API.

First-time setup

After installing this package in your Eve project, run:

npx tealbrick-deliver setup

1. Select R2, AWS S3, custom S3-compatible storage (including self-hosted MinIO), Vercel Blob, or a directory already served by your web server.
2. Enter provider-specific endpoint/bucket/region and masked credentials.
3. Select signed or public access where supported; explicitly accept public links.
4. Optionally verify a disposable upload/download/delete before saving.

Creates .tealbrick/deliver.json, owner-only .tealbrick/deliver.credentials.json, and agent/tools/deliver.ts. Adds /.tealbrick/ to the project's .gitignore before saving. Existing settings/tools are never overwritten. Config stores environment variable names, not credentials. Local credential-file permissions are checked. Windows hosts must additionally restrict access using their account ACLs.

Deploy settings separately from source. Supply referenced credentials as runtime secrets, or explicitly provision the protected credentials file. Do not put secrets in the agent mount, image, browser, sandbox or chat. Runtime working directory must contain .tealbrick/, or pass absolute paths to configuredDeliverTool.

npx tealbrick-deliver check

check creates a disposable object, fetches its recipient-facing URL, compares the bytes and deletes it. Failure is explicit. A failed cleanup returns only the object key for operator reconciliation. This checks the host's network reachability; mobile/desktop/Telegram acceptance must also be tested from those clients. No buckets or web servers are provisioned by setup.

Providers

| Provider | Required target and credentials | Delivery | |---|---|---| | R2 | HTTPS S3 endpoint, bucket, key ID and secret; region auto | Signed (default), or configured public base URL | | AWS S3 | Bucket, region, key ID and secret | Signed (default), or configured public base URL | | S3-compatible / MinIO | HTTPS endpoint, bucket, region, addressing style, key pair | Signed or public base URL | | Vercel Blob | Public-store token | Public URL | | Served directory | Absolute operator-owned directory and HTTPS serving URL | Public URL |

Provider selection is explicit. BLOB_READ_WRITE_TOKEN, DELIVER_DIR and other legacy variables do not silently select a provider. Custom endpoints require HTTPS; self-hosted services can terminate TLS through a reverse proxy. Private tailnet hosts are reachable only to recipients on that network.

Signed URLs default to 24 hours; configure 60 seconds through seven days. An object can outlive its link. This package does not renew links or run a retention job. Configure bucket lifecycle separately. R2 signed URLs use the S3 endpoint, not a custom domain. Public URLs require an already configured public bucket/domain. No bucket ACL changes are made. Temporary S3 credentials may expire before the requested link lifetime; direct config supports sessionTokenEnv.

Eve tool

Setup creates this mount:

import {configuredDeliverTool} from '@tealbrick/deliver/eve';
export default configuredDeliverTool();

The agent calls deliver({path:'/workspace/report.pdf',filename:'report.pdf'}). Only the current Eve sandbox is read. Mount this capability only on authorized agents; the host owns session authorization. No local host-file read tool is exposed.

Result: {url, objectKey, filename, contentType, byteSize, sha256, access, expiresAt?, note}. The chat client can display/open the URL. Native Telegram attachment uploads and stable Teal Brick link renewal are future channel/gateway work, not implemented by this package. Signed links are bearer capabilities; no Portal cookie is needed. Treat them as sensitive when logging or forwarding.

Programmatic use

import {createDeliver,validateDeliveryConfig} from '@tealbrick/deliver';
const config=validateDeliveryConfig({
  version:1,provider:'r2',endpoint:'https://ACCOUNT.r2.cloudflarestorage.com',
  bucket:'my-deliveries',region:'auto',forcePathStyle:true,
  accessKeyIdEnv:'TEALBRICK_DELIVER_ACCESS_KEY_ID',
  secretAccessKeyEnv:'TEALBRICK_DELIVER_SECRET_ACCESS_KEY',
  access:'signed',expiresIn:86400,
});
const deliver=createDeliver(config);
const result=await deliver({data:new Uint8Array([1,2,3]),filename:'export.bin'});

Defaults: 100 MiB per file, 30-second timeout (configurable up to 120 seconds). The Eve sandbox API returns the whole file before the size check; this is not a streaming upload implementation. Cancellation bounds waits; ambiguous failures report the generated object key so an operator can reconcile whether an upload exists. Do not blindly retry them. Unique delivery keys prevent overwrite; setup cleanup only addresses its own generated key.

Unknown formats, HTML and SVG use download MIME rather than active web content. Serve directory files as downloads with X-Content-Type-Options: nosniff in your web server. The directory and parents must be operator-owned, outside the sandbox; symlinked child directories are rejected. Files must be readable by your web server.

This package is the file-delivery adapter, not Knowledge document ingestion. Tests use temporary directories, injected SDK transports and local credentials. Fresh tarball Eve discovery/build is distinct from live provider/client validation.