@capsuleer/dice 1.0.1

package/README.md

@@ -0,0 +1,112 @@
+# @capsuleer/dice
+
+Dice roller and randomness module for Capsuleer agents. Roll dice in standard RPG notation, flip coins, and pick random items from lists — with every roll traced so you always know what fate decided.
+
+```bash
+capsuleer install dice
+```
+
+Genuinely useful. Suspiciously fun.
+
+---
+
+## API
+
+### Rolling dice
+
+```typescript
+// Standard RPG notation: NdX[+/-modifier]
+const attack = await dice.roll("1d20+5")
+// → { notation: "1d20+5", rolls: [14], modifier: 5, total: 19, min: 6, max: 25 }
+
+const damage = await dice.roll("2d6+3")
+// → { notation: "2d6+3", rolls: [4, 6], modifier: 3, total: 13, min: 5, max: 15 }
+
+// Just a d20
+const check = await dice.roll("d20")
+
+// Handful of d6s
+const fireball = await dice.roll("8d6")
+```
+
+### Simulations
+
+```typescript
+// Roll the same notation many times and get summary stats
+const sim = await dice.rollMany("2d6", 1000)
+// → {
+//     rolls: [...],          // all 1000 results
+//     totals: [7, 4, 11, ...],
+//     stats: { mean: 7.02, min: 2, max: 12 }
+//   }
+```
+
+Great for probability exploration — ask an agent "what's the average damage of 3d8+5 over 500 attacks?"
+
+### Coin flips
+
+```typescript
+// Single flip
+const flip = await dice.coin()
+// → { flips: 1, results: ["heads"], heads: 1, tails: 0 }
+
+// Many flips
+const trial = await dice.coin(100)
+// → { flips: 100, results: [...], heads: 53, tails: 47 }
+```
+
+### Random selection
+
+```typescript
+// Pick one random item
+const winner = await dice.pick(["Alice", "Bob", "Carol", "Dave"])
+// → ["Carol"]
+
+// Pick multiple (without replacement)
+const team = await dice.pick(["Alice", "Bob", "Carol", "Dave", "Eve"], 3)
+// → ["Eve", "Alice", "Carol"]
+```
+
+---
+
+## Observability
+
+```jsonl
+{ "ok": true, "op": "dice.roll", "data": { "notation": "2d6+3", "rolls": [4, 6], "modifier": 3, "total": 13, "min": 5, "max": 15 } }
+{ "ok": true, "op": "dice.rollMany", "data": { "notation": "2d6", "times": 1000, "stats": { "mean": 7.02, "min": 2, "max": 12 } } }
+{ "ok": true, "op": "dice.coin", "data": { "flips": 100, "heads": 53, "tails": 47 } }
+{ "ok": true, "op": "dice.pick", "data": { "from": 4, "count": 1, "result": ["Carol"] } }
+```
+
+---
+
+## Notation reference
+
+| Notation | Meaning |
+|---|---|
+| `d20` | One twenty-sided die |
+| `2d6` | Two six-sided dice, summed |
+| `1d20+5` | One d20 plus a +5 modifier |
+| `4d6-1` | Four d6s minus 1 |
+| `100d1` | Deeply philosophical |
+
+Limits: 1–1000 dice, 2–10000 sides, modifier is any integer.
+
+---
+
+## Policy
+
+```typescript
+const capsule = await Capsule({
+  policy: {
+    dice: {
+      roll: true,
+      rollMany: true,
+      coin: true,
+      pick: true,
+    }
+  }
+})
+```
+
+See the [policy docs](https://axon.arclabs.it/docs/capsuleer/policy) for the full rule syntax.

package/capsuleer.manifest.json

@@ -0,0 +1,224 @@
+{
+  "name": "dice",
+  "version": "1.0.1",
+  "description": "Dice roller and randomness module — roll dice in standard notation, flip coins, and pick random items",
+  "exports": [
+    {
+      "name": "roll",
+      "declaration": "declare function roll(notation: string): Promise<{ notation: string; rolls: Array<number>; modifier: number; total: number; min: number; max: number }>",
+      "schema": {
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "notation": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "notation"
+          ]
+        },
+        "returns": {
+          "type": "object",
+          "properties": {
+            "notation": {
+              "type": "string"
+            },
+            "rolls": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              }
+            },
+            "modifier": {
+              "type": "number"
+            },
+            "total": {
+              "type": "number"
+            },
+            "min": {
+              "type": "number"
+            },
+            "max": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "notation",
+            "rolls",
+            "modifier",
+            "total",
+            "min",
+            "max"
+          ]
+        }
+      }
+    },
+    {
+      "name": "rollMany",
+      "declaration": "declare function rollMany(notation: string, times: number): Promise<{ rolls: Array<{ notation: string; rolls: Array<number>; modifier: number; total: number; min: number; max: number }>; totals: Array<number>; stats: { mean: number; min: number; max: number } }>",
+      "schema": {
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "notation": {
+              "type": "string"
+            },
+            "times": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "notation",
+            "times"
+          ]
+        },
+        "returns": {
+          "type": "object",
+          "properties": {
+            "rolls": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "notation": {
+                    "type": "string"
+                  },
+                  "rolls": {
+                    "type": "array",
+                    "items": {
+                      "type": "number"
+                    }
+                  },
+                  "modifier": {
+                    "type": "number"
+                  },
+                  "total": {
+                    "type": "number"
+                  },
+                  "min": {
+                    "type": "number"
+                  },
+                  "max": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "notation",
+                  "rolls",
+                  "modifier",
+                  "total",
+                  "min",
+                  "max"
+                ]
+              }
+            },
+            "totals": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              }
+            },
+            "stats": {
+              "type": "object",
+              "properties": {
+                "mean": {
+                  "type": "number"
+                },
+                "min": {
+                  "type": "number"
+                },
+                "max": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "mean",
+                "min",
+                "max"
+              ]
+            }
+          },
+          "required": [
+            "rolls",
+            "totals",
+            "stats"
+          ]
+        }
+      }
+    },
+    {
+      "name": "coin",
+      "declaration": "declare function coin(flips: number): Promise<{ flips: number; results: Array<\"heads\" | \"tails\">; heads: number; tails: number }>",
+      "schema": {
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "flips": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "flips"
+          ]
+        },
+        "returns": {
+          "type": "object",
+          "properties": {
+            "flips": {
+              "type": "number"
+            },
+            "results": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "heads",
+                  "tails"
+                ]
+              }
+            },
+            "heads": {
+              "type": "number"
+            },
+            "tails": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "flips",
+            "results",
+            "heads",
+            "tails"
+          ]
+        }
+      }
+    },
+    {
+      "name": "pick",
+      "declaration": "declare function pick(items: Array<unknown>, count: number): Promise<Array<unknown>>",
+      "schema": {
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "items": {
+              "type": "array",
+              "items": {}
+            },
+            "count": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "items",
+            "count"
+          ]
+        },
+        "returns": {
+          "type": "array",
+          "items": {}
+        }
+      }
+    }
+  ]
+}

package/index.ts

@@ -0,0 +1,117 @@
+import { defineModule } from "@capsuleer/core"
+
+type RollResult = {
+    notation: string
+    rolls: number[]
+    modifier: number
+    total: number
+    min: number
+    max: number
+}
+
+type CoinResult = {
+    flips: number
+    results: Array<"heads" | "tails">
+    heads: number
+    tails: number
+}
+
+// Parse standard dice notation: NdX[+/-M]
+// Examples: "2d6", "1d20+5", "4d6-1", "d20"
+function parseNotation(notation: string): { count: number; sides: number; modifier: number } {
+    const match = notation.trim().toLowerCase().match(/^(\d*)d(\d+)([+-]\d+)?$/)
+    if (!match) throw new Error(`Invalid dice notation: "${notation}". Expected format: NdX, NdX+M, or NdX-M (e.g. 2d6, 1d20+3, d8-1)`)
+    const count = match[1] === "" ? 1 : parseInt(match[1], 10)
+    const sides = parseInt(match[2], 10)
+    const modifier = match[3] ? parseInt(match[3], 10) : 0
+    if (count < 1 || count > 1000) throw new Error(`Dice count must be between 1 and 1000, got ${count}`)
+    if (sides < 2 || sides > 10000) throw new Error(`Dice sides must be between 2 and 10000, got ${sides}`)
+    return { count, sides, modifier }
+}
+
+function rollDie(sides: number): number {
+    return Math.floor(Math.random() * sides) + 1
+}
+
+const dice = {
+    async roll(notation: string): Promise<RollResult> {
+        try {
+            const { count, sides, modifier } = parseNotation(notation)
+            const rolls = Array.from({ length: count }, () => rollDie(sides))
+            const total = rolls.reduce((a, b) => a + b, 0) + modifier
+            const result: RollResult = {
+                notation,
+                rolls,
+                modifier,
+                total,
+                min: count + modifier,
+                max: count * sides + modifier,
+            }
+            console.log(JSON.stringify({ ok: true, op: "dice.roll", data: result }))
+            return result
+        } catch (err: any) {
+            console.log(JSON.stringify({ ok: false, op: "dice.roll", data: { notation }, error: err.message }))
+            throw err
+        }
+    },
+
+    async rollMany(notation: string, times: number): Promise<{ rolls: RollResult[]; totals: number[]; stats: { mean: number; min: number; max: number } }> {
+        try {
+            if (times < 1 || times > 10000) throw new Error(`times must be between 1 and 10000, got ${times}`)
+            const { count, sides, modifier } = parseNotation(notation)
+            const rolls: RollResult[] = Array.from({ length: times }, () => {
+                const r = Array.from({ length: count }, () => rollDie(sides))
+                const total = r.reduce((a, b) => a + b, 0) + modifier
+                return { notation, rolls: r, modifier, total, min: count + modifier, max: count * sides + modifier }
+            })
+            const totals = rolls.map(r => r.total)
+            const mean = totals.reduce((a, b) => a + b, 0) / totals.length
+            const result = {
+                rolls,
+                totals,
+                stats: { mean, min: Math.min(...totals), max: Math.max(...totals) },
+            }
+            console.log(JSON.stringify({ ok: true, op: "dice.rollMany", data: { notation, times, stats: result.stats } }))
+            return result
+        } catch (err: any) {
+            console.log(JSON.stringify({ ok: false, op: "dice.rollMany", data: { notation, times }, error: err.message }))
+            throw err
+        }
+    },
+
+    async coin(flips = 1): Promise<CoinResult> {
+        try {
+            if (flips < 1 || flips > 10000) throw new Error(`flips must be between 1 and 10000, got ${flips}`)
+            const results: Array<"heads" | "tails"> = Array.from({ length: flips }, () =>
+                Math.random() < 0.5 ? "heads" : "tails"
+            )
+            const heads = results.filter(r => r === "heads").length
+            const result: CoinResult = { flips, results, heads, tails: flips - heads }
+            console.log(JSON.stringify({ ok: true, op: "dice.coin", data: { flips, heads, tails: result.tails } }))
+            return result
+        } catch (err: any) {
+            console.log(JSON.stringify({ ok: false, op: "dice.coin", data: { flips }, error: err.message }))
+            throw err
+        }
+    },
+
+    async pick(items: unknown[], count = 1): Promise<unknown[]> {
+        try {
+            if (count < 1 || count > items.length) throw new Error(`count must be between 1 and ${items.length}, got ${count}`)
+            const shuffled = [...items].sort(() => Math.random() - 0.5)
+            const result = shuffled.slice(0, count)
+            console.log(JSON.stringify({ ok: true, op: "dice.pick", data: { from: items.length, count, result } }))
+            return result
+        } catch (err: any) {
+            console.log(JSON.stringify({ ok: false, op: "dice.pick", data: { count }, error: err.message }))
+            throw err
+        }
+    },
+}
+
+export default defineModule({
+    name: "dice",
+    version: "1.0.0",
+    description: "Dice roller and randomness module — roll dice in standard notation, flip coins, and pick random items",
+    api: dice,
+})

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@capsuleer/dice",
+  "version": "1.0.1",
+  "description": "Dice roller and randomness module for capsuleer — standard dice notation, coin flips, and random selection",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "keywords": [
+    "capsuleer",
+    "dice",
+    "random",
+    "rpg"
+  ],
+  "author": "cody",
+  "license": "MIT",
+  "dependencies": {
+    "@capsuleer/core": "latest"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}