simulator-attachments

name

simulator-attachments

description

Simulator.Company files & attachments specialist. Use when the user wants to upload a file, attach a document/image to an actor or comment, list/rename/detach workspace files. Activate when the user says "upload a file", "attach this document", "add an attachment", "rename the file", "detach the file", "list workspace files", "завантаж файл", "прикріпи файл/документ", "відкріпи вкладення", "загрузи файл", "прикрепи документ". For setting an actor's picture/avatar use the `uploadActorPicture` engine tool; for comments that carry files use `simulator-reactions`.

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="<base64 string>",          # prefer RAW base64; a data:<mime>;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": "<actor or reaction UUID>" }
])
removeAttachments(accId="ws_xxx", items=[
  { "attachId": 5521, "actorId": "<actor or reaction UUID>" }
])   # 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="<actor UUID>", 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="<base64>")   → attachId 5521
# 2. link it to the actor
addAttachments(items=[{ "attachId": 5521, "actorId": "<actor UUID>" }])
# (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:<mime>;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.