temp-files

What this skill does

# Temp-Files — Workroom file relay

This skill lets one agent drop temporary files, directories, or whole-site
snapshots to another agent without polluting the long-term backup namespace
and without an external file host.

| Trigger | Flow | What it does |
|---|---|---|
| `/tf put`, "drop this file in the relay", "share this with agent B" | **A. Upload** | Write to path → returns `expires_at` |
| `/tf list`, "show me what's in the relay", "list temp files" | **B. List** | One-level `ls`: files + subdirs |
| `/tf get`, "pull X down", "download X" | **C. Download** | File straight through / dir as zip |
| `/tf rm`, "delete X from the relay" | **D. Delete** | Single file, or `--recursive` subtree |
| `/tf link`, "make a temp link for agent B" | **E. Short link** | Mint a `tf_xxxx` internal short link |

Every command hits the same service (`sc-agent-backup.internal`) and
authenticates with the container's built-in `CONTAINER_JWT`. Identity and
path are derived from the JWT:
**`user_id = JWT.userInfoID`, `agent_scope = JWT.containerId`** (defaults to
`default`). You cannot reach, see, or delete relay files belonging to another
user or another agent.

## Difference vs. the `backup` skill (must read)

| Dimension | `backup` skill | `temp-files` skill (this one) |
|---|---|---|
| Purpose | Long-term agent state | Short-term handoff, collaboration relay |
| Addressing | Server-generated `backup_id` | Caller-supplied path |
| Model | Immutable `tar.gz` bundle | Path-based filesystem, overwritable |
| Quota | 5 bundles / user, hard cap | Byte quota + per-file size limit |
| TTL | None | **Default 7 days, sliding on access/overwrite, hard cap 60 days** |
| Cross-agent | Restore the whole bundle | Per-file / per-directory + short link |

**Never mix the two.** "Restore an entire agent state" → use `backup`.
"Hand off one artifact so the other agent can carry on" → use this skill.

## Operational rules

### Rule 1 — Do not use the relay as a file host

Default file TTL is 7 days. Even with overwrite/download sliding renewal,
the hard cap is 60 days. Anything that needs to stick around goes through
`backup` or `volume-backup`.

### Rule 2 — Path whitelist

The server only accepts segments matching `[A-Za-z0-9._\- ]`. It rejects
`..`, absolute paths, empty segments, and control characters. Just pass a
relative path:

- `skills/my-skill/SKILL.md`  ✅
- `sites/staging/index.html`  ✅
- `../escape.txt`  ❌ → 400 bad_path
- `/abs/oops.md` gets its leading slash stripped — better not to send it

### Rule 3 — Short links are "agent-to-agent inside", not public sharing

The first-pass short link follows a **capability URL model**:

- Whoever holds `tf_xxxxxxxx` can fetch it (the code itself is the credential — 64 bits of entropy)
- But still requires the **6PN internal network** + a **valid `CONTAINER_JWT`** (for audit)
- A browser or bare `curl` has no token, so it gets 401 — that's expected, not a bug
- Cross-user agents *can* fetch, because that is exactly the Workroom handoff use case

Correct flow:

1. Agent A calls `/tf put` to upload
2. Agent A calls `/tf link` and receives `tf_xxxxxxxx`
3. Agent A sends the short link to agent B over Workroom
4. Agent B (inside Fly, with its own `CONTAINER_JWT`, possibly under a different
   user) calls `tf fetch tf_xxxxxxxx` to retrieve it

**Do not** hand `http://sc-agent-backup.internal:8080/t/<code>` to an end user
to open in a browser — it isn't publicly reachable. If/when public sharing
ships, wait for the phase-B public resolver.

**Cleanup rule**: once the receiver confirms they have the file, the sender
should immediately `tf unlink <code>` to revoke the short link and stop the
token from lingering. Sensitive content *must* be unlinked — don't rely on
TTL as a backstop.

### Rule 4 — Stop on failure, do not silently retry

If any `tf.py` subcommand exits non-zero, **stop immediately and return the
stderr verbatim to the user**. Do not "let me try again for you."

## Install path

The skill installs into `/data/workspace/skills/temp-files/`. Every command
runs from the agent's working directory:

```bash
python3 skills/temp-files/scripts/tf.py <subcommand> ...
```

## Command reference

Environment for every command:
- `CONTAINER_JWT` — injected by ai-agent, required
- `TEMP_STORAGE_URL` — optional, defaults to `http://sc-agent-backup.internal:8080`

Global output switches (place before the subcommand):
- `--verbose`: emit full payload / error meta (for debugging)
- `--json`: stable JSON envelope, same keys on success and failure
  - success: `{ok: true, error: "", message: "ok", detail: "", data: {...}}`
    - `data` defaults to the command's compact view (minimum useful field set)
    - with `--verbose`, `data` becomes the server's raw payload (all fields)
  - failure: `{ok: false, error: "<code>", message: "...", detail: "...", exit_code: N}`
    - `error` is the server's error code (e.g. `bad_path` / `not_found` / `quota_exceeded`) or `usage_error` / `http_error`
    - with `--verbose`, includes a `meta` sub-structure (HTTP status / server's original message+detail)
- default (no switches): compact output, the smallest useful set of fields (readable by humans and agents alike)

Note: `tf list` and `tf links` without `--json` print a human-friendly table;
with `--json` they go through the envelope and `data` carries the full
`entries`/`links` array.

### Recommended defaults (quick reference)

| Flag | Recommended | Why |
|---|---|---|
| `link --ttl-seconds` | `3600` (1 hour) | Long enough for the receiver to fetch once, short enough not to linger |
| `put --ttl-days` | `7` (default) | Covers a typical review cycle |
| `fetch --extract` | **always pass it** | Auto-unpack, one less step, zip-slip defence built in |
| `get` on a directory | must pass `--zip` | Server has no plain-directory download mode |
| `unlink` after handoff | call as soon as the receiver confirms | Short code = credential; sensitive content must be revoked |

### A. Upload / overwrite

```bash
python3 skills/temp-files/scripts/tf.py put <local-file> <remote-path> \
    [--ttl-days N]
```

Example:

```bash
python3 skills/temp-files/scripts/tf.py put ./SKILL.md skills/demo/SKILL.md
# → {"path": "...", "size_bytes": ..., "expires_at": ...}
```

Same-name uploads overwrite; the response returns a fresh `expires_at`.

### B. List

```bash
python3 skills/temp-files/scripts/tf.py list [--prefix PATH]
```

No `--prefix` lists the root; `--prefix sites/` lists one level under that.

### C. Download

```bash
# Single file
python3 skills/temp-files/scripts/tf.py get <remote-path> <local-dest>

# Whole directory as a zip
python3 skills/temp-files/scripts/tf.py get <remote-dir> <local-dest.zip> --zip
```

A successful download slides the TTL forward by 7 days.

### D. Delete

```bash
# Single file / empty directory
python3 skills/temp-files/scripts/tf.py rm <remote-path>

# Non-empty directory
python3 skills/temp-files/scripts/tf.py rm <remote-dir> --recursive
```

### E. Short links

```bash
python3 skills/temp-files/scripts/tf.py link <remote-path> \
    [--zip] [--ttl-seconds 3600]
# → {"code": "tf_xxxxxxxx", "url": "http://.../t/tf_xxxxxxxx", ...}

# List currently active short links
python3 skills/temp-files/scripts/tf.py links

# Revoke
python3 skills/temp-files/scripts/tf.py unlink <code>
```

Short link TTL defaults to 1 hour and caps at 7 days (independent of the
file's own TTL).

### F. Pull data via a short link (what the receiving agent runs)

```bash
# Download + auto-unpack (strongly recommended)
python3 skills/temp-files/scripts/tf.py fetch <code> <local-dest> --extract

# Or specify the extract directory
python3 skills/temp-files/scripts/tf.py fetch <code> ./pack.zip --extract ./out

# Without --extract: download only, no unpack
python3 skills/temp-files/scripts/tf.py fetch <code> <local-dest>
```

Any caller with a valid `CONTAINER_JWT` can fetch (cross-user is fine).

**Zip auto-detect**: when the server returns `Content-Type: application/zip`