tigris-agent-kit

The full skill.

Original instructions from the publisher’s SKILL.md

# Tigris Agent Kit

High-level storage workflows for AI agents on Tigris. Composes `@tigrisdata/storage` and `@tigrisdata/iam` primitives into four building blocks: **forks**, **workspaces**, **checkpoints**, and **coordination**.

## Prerequisites

**Before doing anything else**, ensure the Tigris CLI is installed:

```bash
tigris help || npm install -g @tigrisdata/cli
```

If you need to install it, tell the user: "I'm installing the Tigris CLI (`@tigrisdata/cli`) so we can work with Tigris object storage."

Then install the agent-kit package:

```bash
npm install @tigrisdata/agent-kit
```

## Configuration

All functions accept an optional `config` parameter. When omitted, the SDK reads from environment variables:

```bash
TIGRIS_STORAGE_ACCESS_KEY_ID=tid_...
TIGRIS_STORAGE_SECRET_ACCESS_KEY=tsec_...
```

Pass config explicitly when needed:

```typescript
const config = {
  accessKeyId: 'tid_...',
  secretAccessKey: 'tsec_...',
};
```

All functions return a `TigrisResponse<T>` — a discriminated union of `{ data: T }` or `{ error: Error }`. Always check `error` first.

## Quick Reference

| Building Block | Purpose | Functions |
|---|---|---|
| **Forks** | N isolated copies of a shared dataset | `createForks`, `teardownForks` |
| **Workspaces** | Dedicated per-agent bucket with TTL | `createWorkspace`, `teardownWorkspace` |
| **Checkpoints** | Snapshot bucket state, restore as fork | `checkpoint`, `restore`, `listCheckpoints` |
| **Coordination** | Event-driven pipelines via webhooks | `setupCoordination`, `teardownCoordination` |

## When to Use Which

| Scenario | Use |
|---|---|
| Spin up N agents that each need their own copy of a dataset | **Forks** |
| Give one agent a scratch bucket that auto-cleans after a day | **Workspace** |
| Save agent state mid-run so you can branch from it later | **Checkpoint** + **Restore** |
| Trigger downstream agent when an upstream agent writes a result | **Coordination** |

## Forks — Parallel Agent Copies

Each fork is an independent bucket with isolated storage. Copy-on-write — instant at any size, zero data duplication. The base bucket must have snapshots enabled.

```typescript
import { createForks, teardownForks } from '@tigrisdata/agent-kit';

const { data: forkSet, error } = await createForks('my-dataset', 3, {
  prefix: 'experiment-run-42',
  credentials: { role: 'Editor' },
});
if (error) throw error;

for (const fork of forkSet.forks) {
  // fork.bucket — the bucket name
  // fork.credentials?.accessKeyId / secretAccessKey — scoped per fork
}

// Revokes credentials and deletes all fork buckets
await teardownForks(forkSet);
```

Detailed options, lifecycle, and patterns: read `./resources/forks.md`.

## Workspaces — Per-Agent Buckets

Provision a dedicated bucket for one agent. Optional TTL auto-expires objects; optional scoped credentials enforce least privilege.

```typescript
import { createWorkspace, teardownWorkspace } from '@tigrisdata/agent-kit';

const { data: workspace } = await createWorkspace('agent-workspace-abc', {
  ttl: { days: 1 },
  enableSnapshots: true,
  credentials: { role: 'Editor' },
});

// Use workspace.bucket and workspace.credentials with @tigrisdata/storage

await teardownWorkspace(workspace);
```

Detailed options, TTL behavior, and patterns: read `./resources/workspaces.md`.

## Checkpoints — Snapshot and Restore

Capture bucket state at a point in time; restore creates a copy-on-write fork from that snapshot. Original is untouched.

```typescript
import { checkpoint, restore, listCheckpoints } from '@tigrisdata/agent-kit';

const { data: ckpt } = await checkpoint('training-data', { name: 'epoch-50' });

const { data: list } = await listCheckpoints('training-data');

const { data: restored } = await restore(
  'training-data',
  ckpt.snapshotId,
  { forkName: 'training-data-retry' },
);
// restored.bucket — independent fork at that point in time
```

Detailed options and rollback patterns: read `./resources/checkpoints.md`.

## Coordination — Event-Driven Pipelines

Wire bucket notifications so writes fire webhooks instead of requiring polling. Use it to chain agents: agent A writes a result, Tigris fires a webhook, agent B starts.

```typescript
import { setupCoordination, teardownCoordination } from '@tigrisdata/agent-kit';

await setupCoordination('pipeline-bucket', {
  webhookUrl: 'https://my-service.com/webhook',
  filter: 'WHERE `key` REGEXP "^results/"',
  auth: { token: 'my-webhook-secret' },
});

await teardownCoordination('pipeline-bucket');
```

Filter syntax, webhook auth, and pipeline patterns: read `./resources/coordination.md`.

## API Reference

### Forks

| Function | Description |
|---|---|
| `createForks(baseBucket, count, options?)` | Snapshot + fork N times + scoped credentials |
| `teardownForks(forkSet, options?)` | Revoke credentials + delete forks |

### Workspaces

| Function | Description |
|---|---|
| `createWorkspace(name, options?)` | Create bucket + TTL + scoped credentials |
| `teardownWorkspace(workspace, options?)` | Revoke credentials + delete bucket |

### Checkpoints

| Function | Description |
|---|---|
| `checkpoint(bucket, options?)` | Snapshot a bucket, returns snapshot ID |
| `restore(bucket, snapshotId, options?)` | Fork from a snapshot |
| `listCheckpoints(bucket, options?)` | List all snapshots for a bucket |

### Coordination

| Function | Description |
|---|---|
| `setupCoordination(bucket, options)` | Configure bucket notifications |
| `teardownCoordination(bucket, options?)` | Clear bucket notifications |

## Critical Rules

**Always:** Check `result.error` before `result.data` | Call the corresponding `teardown*` to revoke credentials and delete buckets — agents leak buckets fast | Enable snapshots on the base bucket before calling `createForks` or `checkpoint` | Use scoped per-fork/per-workspace credentials so one agent's compromise doesn't expose others

**Never:** Reuse a single shared access key across agents — defeats the point of scoped credentials | Skip teardown on long-running services — orphaned buckets accumulate billing | Assume `restore` mutates the original bucket — it creates a new fork

## Common Mistakes

| Mistake | Fix |
|---|---|
| `createForks` fails with "snapshots not enabled" | Recreate base bucket with `enableSnapshot: true` |
| Forks not cleaned up after agent run | Always pair `createForks` with `teardownForks` in a `finally` block |
| Webhook never fires | Check `filter` syntax — must be a valid SQL `WHERE` clause against `key`, `event`, etc. |
| Workspace TTL doesn't delete bucket | TTL expires *objects*, not the bucket itself. Call `teardownWorkspace` to delete the bucket |
| Restored bucket is empty | Verify `snapshotId` exists with `listCheckpoints` before calling `restore` |

## Related Skills

- **tigris-snapshots-forking** — Lower-level snapshot and fork primitives in `@tigrisdata/storage`
- **tigris-bucket-management** — Bucket creation, regions, snapshot configuration
- **tigris-security-access-control** — IAM, scoped keys, key rotation
- **file-storage** — Core `@tigrisdata/storage` SDK for reading/writing within fork or workspace buckets

## Official Documentation

- Package: https://www.npmjs.com/package/@tigrisdata/agent-kit
- Source: https://github.com/tigrisdata/storage/tree/main/packages/agent-kit