# Simulator Chat

> >

- **Type:** Skill
- **Install:** `agentstack add skill-corezoid-simulator-ai-plugin-simulator-chat`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [corezoid](https://agentstack.voostack.com/s/corezoid)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [corezoid](https://github.com/corezoid)
- **Source:** https://github.com/corezoid/simulator-ai-plugin/tree/main/plugins/simulator/skills/simulator-chat
- **Website:** https://simulator.company

## Install

```sh
agentstack add skill-corezoid-simulator-ai-plugin-simulator-chat
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> **Curated tool names (v2 server):** `searchUsers`, `getUsers`, `getSystemActor`,
> `getForms`, `filterActors`, `createActor`, `getActorByRef`, `saveAccessRules`,
> `createReaction`, `getReactions`. Call them by these exact names. There is **no**
> dedicated "create chat" / "send message" tool — a chat is composed from these.

# Simulator.Company Chat Specialist

In Simulator.Company a **chat is an actor of the `Events` system form**:

- `data.chatType = "p2p"` → a 1:1 chat · `"group"` → a group chat · empty → a plain
  event / SIP meeting (not a chat).
- **Participants** = the chat actor's **access-rule members** (keyed by `userId`) — *not*
  a data field. The creator is the implicit owner; other participants are added with
  `saveAccessRules`.
- **Messages** = **`comment` reactions** posted under the chat actor.

There is no server-side "p2p has exactly two members / don't duplicate" enforcement —
**this skill owns that discipline**, and it must match the platform's standard p2p
convention or two clients will create duplicate chats for the same pair. The
convention:

- **Deterministic `ref`** = `p2pConversation__` — both
  participants' raw workspace userIds **sorted ascending**, joined with `_`. This is the
  p2p dedup key; the UI finds/reuses a chat *only* by this ref.
- **`title`** = `:p2p:` — nicks ordered by the same ascending userId sort.
- **`data`** = `{ chatType:"p2p", startDate:, endDate:, scheduleMeeting:false }`.
- **Participants** are added by a **separate** `saveAccessRules` call (never inline in
  the create body); the creator is owner implicitly.

> Read `$CLAUDE_PLUGIN_ROOT/docs/entities/chats.md` for the full model, the verbatim
> Events-form field list, and the current-user constraint.

Reply to the user in **their own language**.

---

## Test case: "write a message to user N"

This is the canonical flow. Each step names the exact tool.

### 1 — Resolve user N

```
searchUsers(query="N")          # accId defaults to the active workspace
```

Take N's `userId` from the result (e.g. `4210`). If several match, ask the user which
one (or show name + email). `getUsers` lists everyone if you need to browse.

> `getSystemActor(objType="user", objId=)` returns N's system "twin" actor. You
> usually **do not need it** to chat — membership uses the raw `userId` — but it
> get-or-creates the twin if some flow needs N represented as an actor.

### 2 — Resolve the Events form id (per workspace)

```
getForms(formTypes="system")    # find the row whose title == "Events" → its id
```

The Events form id differs per workspace, so don't hardcode it. (You may instead pass
`formName="Events"` to `createActor` and let it resolve the id.)

### 3 — Build the canonical ref + title (reuse key)

The p2p dedup key needs **both** userIds. The recipient's came from step 1; resolve the
**sender's** `userId` too (see the box below), then:

```
ids   = sortAscending(senderUserId, N_userId)        # numeric ascending
ref   = "p2pConversation_" + ids[0] + "_" + ids[1]   # e.g. p2pConversation_4210_4310
title = nick(ids[0]) + ":p2p:" + nick(ids[1])        # e.g. olena:p2p:petro
```

> **Getting the sender's userId.** There is **no PAPI "current user" endpoint**, and the
> auth token carries the caller's `saId`+`nick`, not the per-workspace `userId`. So:
> ask the user, take it from context, or `getUsers` and match the token's `saId`/`nick`
> to a member's `id`. **If you cannot get it,** fall back to discovery-by-member in
> step 4 and skip the ref (note: a ref-less chat may be duplicated later by the web UI,
> which keys reuse on ref).

### 4 — Find an existing chat (reuse, don't duplicate)

Canonical — by the deterministic ref, exactly as the web UI does:

```
getActorByRef(formId=, ref=)     # found → reuse its id, skip to step 6
```

Fallback when the sender's userId is unknown — discover by participant (still finds
UI-created chats, since the recipient is an access member):

```
filterActors(formId=, q="chatType=p2p", members=":view")
```

### 5 — Create the p2p chat (only if none exists)

```
createActor(
  formName="Events",                       # or formId=
  title=,                           # ":p2p:"
  ref=,                               # p2pConversation__ — REQUIRED for UI reuse
  data={ "chatType": "p2p",
         "startDate": ,
         "endDate":   ,
         "scheduleMeeting": false })        # plain unix SECONDS on Events — not a calendar object
```

`startDate`/`endDate` are **required** by the Events form. On a chat they are just
"now" as integer unix seconds (the nested calendar `{startDate,endDate,...}` object used
elsewhere does **not** apply here).

Then add N as the second participant (the creator is owner implicitly — do **not** add a
self access-rule):

```
saveAccessRules(
  objType="actor", objId="",
  rules=[{ "action":"create",
           "data":{ "userId": ,
                    "privs":{ "view":true, "modify":true, "remove":true } } }])
```

`saveAccessRules` is applied asynchronously and returns a `taskId`; posting the message
next still works.

### 6 — Post the message (a `comment` reaction)

```
createReaction(type="comment", actorId="", description="")
```

That `comment` reaction under the chat actor **is** the chat message. To read the
conversation back: `getReactions(actorId="", view="flat", orderValue="ASC")`.

---

## Variations

- **Group chat.** Create with `data.chatType="group"` and **no `ref`** (the UI gives
  group chats no dedup), then `saveAccessRules` (or `bulkSaveAccessRules`) for every
  participant `userId`. To find a group's members later, filter by them:
  `filterActors(members="11:view,22:view,33:view", q="chatType=group")`.
- **Reply in a thread.** Pass `parentId=` to `createReaction` (see
  `simulator-reactions`).
- **Attach a file to a message.** Upload first (`uploadBase64` → `attachId`), then
  `createReaction(..., attachments=[{attachId:}])` — see `simulator-attachments`.
- **Post quietly (no notification).** `createReaction(..., notify=false)`.
- **Hand the message to the AI agent.** `createReaction(..., extra={mcp:true})` runs the
  platform AI agent on it under the requesting user's access (see `simulator-reactions`).

## Reuse & safety rules

- **Always look up (step 4) before creating (step 5).** Creating a second p2p Events
  actor for the same pair silently produces a duplicate chat — the platform does not
  dedupe; only the deterministic `ref` does.
- **Always set the canonical `ref` on create** (`p2pConversation__`) so the
  web UI reuses the same chat instead of making its own duplicate.
- **Participants are access rules, never `data` fields.** Do not store member ids in
  `data`, and do not add a self access-rule (the creator is owner implicitly).
- **Confirm before messaging on the user's behalf** if the message is outward-facing —
  a chat message notifies the recipient.
- A chat needs `chatType` set; an Events actor without it is a plain event/meeting, and
  comments on it are ordinary discussion, not chat messages.

---

## Relationship to the other skills

| Skill | Boundary |
|---|---|
| `simulator-reactions` | Generic comments/approvals/ratings on **any** actor (a chat message is a `comment` reaction — that skill covers the reaction mechanics). |
| `simulator-actors` | The Events actor's own `data` fields and the actor `data` value protocol. |
| `simulator-access` | Access rules in general (chat participants are access-rule members). |
| `simulator-attachments` | Files on a message/actor. |
| `simulator-init` | Login + workspace selection (needed before any of this). |

## Reference Documents

| Path | When to read |
|---|---|
| `$CLAUDE_PLUGIN_ROOT/docs/entities/chats.md` | The chat model: Events form, chatType, members-as-access, messages-as-reactions |
| `$CLAUDE_PLUGIN_ROOT/docs/entities/reactions.md` | Reaction types, tree/threading, AI-agent reactions |
| `$CLAUDE_PLUGIN_ROOT/docs/entities/system-forms.md` | The Events system form among the built-ins |

## Tips

- `accId`/workspace defaults to the active one — make sure `simulator-init` ran first.
- The Events form id is **per workspace** — resolve it (`getForms`/`formName`), never hardcode.
- On Events, `startDate`/`endDate` are plain unix **seconds**, both "now" for a chat.
- Canonical reuse = `getActorByRef(ref="p2pConversation__")` (matches the web UI); it needs both userIds — the sender's isn't in the token (`saId`/`nick` only, no PAPI /me), so derive it or fall back to `filterActors(members=…, q="chatType=p2p")`.
- A message is just `createReaction(type="comment", actorId=, description=...)`.

## Source & license

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

- **Author:** [corezoid](https://github.com/corezoid)
- **Source:** [corezoid/simulator-ai-plugin](https://github.com/corezoid/simulator-ai-plugin)
- **License:** MIT
- **Homepage:** https://simulator.company

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-corezoid-simulator-ai-plugin-simulator-chat
- Seller: https://agentstack.voostack.com/s/corezoid
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.