Simulator Attachments

> Curated tool names (v2 server): uploadBase64, getAttachments, getActorAttachments, > addAttachments, updateAttachment, removeAttachments. Plus the engine tools > uploadActorPicture / uploadActorPictureBulk for actor avatars. Call them by these exact names.

Simulator.Company Files & Attachments Specialist

A file is uploaded once into the workspace and becomes an attachment record (with an attachId). You then link that record to actors or reactions. Listing, renaming and unlinking operate on the record.

> Relationship to the other skills > - simulator-reactions — a comment can carry files via its attachments:[{attachId}]. > - simulator-actors — uploadActorPicture sets an actor's avatar (an engine tool, not here).

The flow: upload → attachId → link

1. Upload the bytes → get the attachment record (attachId, stored fileName).
2. Link the attachId to an actor/reaction (or pass it in a reaction's attachments).
3. Manage it later (rename, list, unlink).

Workspace context

uploadBase64, getAttachments, addAttachments, removeAttachments take an accId (workspace id) — it defaults to the configured workspace if omitted. updateAttachment is addressed by attachId only.

---

Upload a file

uploadBase64(
  accId="ws_xxx",                  # optional — defaults to the configured workspace
  file="",          # prefer RAW base64; a data:;base64, prefix is also stripped server-side
  originalName="report.pdf",       # sets the type + title
  ttl=0)                           # seconds; 0 = permanent
# → returns the attachment record incl. attachId + fileName

> Prefer raw base64. A data: URI prefix is accepted and stripped server-side, but raw base64 > is the safe default. Multipart uploads are not a curated tool — use uploadActorPicture for > actor images, or uploadBase64 for everything else.

Link / unlink files

addAttachments(accId="ws_xxx", items=[
  { "attachId": 5521, "actorId": "" }
])
removeAttachments(accId="ws_xxx", items=[
  { "attachId": 5521, "actorId": "" }
])   # unlinks; does NOT delete the stored file

List & rename

getAttachments(accId="ws_xxx", limit=50, orderBy="created_at", orderValue="DESC")  # all files in the workspace
getActorAttachments(actorId="", limit=100)                             # only files linked to one actor
updateAttachment(attachId=5521, title="Q3 report.pdf")

> Use getActorAttachments when you want a single actor's files; getAttachments lists the > whole workspace. getActorAttachments is addressed by actorId (no accId).

End-to-end: attach a PDF to an actor

# 1. upload
uploadBase64(originalName="contract.pdf", file="")   → attachId 5521
# 2. link it to the actor
addAttachments(items=[{ "attachId": 5521, "actorId": "" }])
# (or attach to a comment instead — see simulator-reactions: createReaction(..., attachments=[{attachId:5521}]))

---

Reference Documents

| Path | When to read | |---|---| | $CLAUDE_PLUGIN_ROOT/docs/entities/attachments.md | Attachment model, statuses, storage, virus-scan flow | | $CLAUDE_PLUGIN_ROOT/docs/entities/reactions.md | Attaching files to comments |

Tips

• Upload first to get an attachId, then addAttachments (or a reaction's attachments).
• removeAttachments only unlinks — it does not delete the stored bytes.
• uploadBase64 prefers raw base64; a data:;base64, prefix is stripped server-side.
• For an actor's avatar/picture use uploadActorPicture (handles URL / local path / base64, auto-rasterises SVG).
• addAttachments/removeAttachments items need BOTH attachId and actorId per entry.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: corezoid
• Source: corezoid/simulator-ai-plugin
• License: MIT
• Homepage: https://simulator.company

Install and usage instructions live in the source repository linked above.