briyah 1.2.4 → 1.2.5

package/README.md

@@ -5,7 +5,8 @@ Briyah is an SDK for AI agents, multi-agent rooms, and interactive stories. It w
 What's in the package:
 
 - **Agents.** AI agents with a system prompt, persistent conversation history, attached documents, and per-call cost and token tracking. Histories can be summarized/compacted or cleared.
-- **Rooms.** Multi-agent conversations with a shared goal. Agents exchange messages at different visibility levels (speak, whisper, think, shout), draft and approve shared artifacts, and a moderator can route turns.
+- **Rooms.** Multi-agent conversations with a shared goal. Agents exchange messages at different visibility levels (speak, whisper, think, shout), publish shared artifacts, run tools, commission each other for parallel research, and a moderator can route turns.
+- **Tools.** User-defined functions agents can call from a room. A tool is a named async JavaScript function body with declared parameters that returns a JSON value; `helpers.fetch` is available for HTTP requests. Tools are granted per agent, and an agent may chain several tool calls privately before responding. Tool code runs in-process on the server with a timeout — only define tools you trust.
 - **Stories.** Text-based interactive fiction with a narrator, AI-played characters, and a human player. Stories progress through chapters and can introduce new characters mid-game. Story events (state updates, character suggestions, chapter transitions, errors) are delivered through an emitter the host app subscribes to.
 - **Text processing.** One-shot `processText` for non-conversational use, with cost and token counts on the result.
 - **File attachments.** Attach documents to agents as context. Supported file types vary by LLM provider.
@@ -227,6 +228,13 @@ const room = await appService.createRoom(name, goal, agentIds);
 const rooms = await appService.listRooms();
 await appService.sendRoomMessage(roomId, content, sender, action?);
 
+// Tool Management
+const tools = await appService.listTools();
+const tool = await appService.createTool({ name, description, parameters, code, timeoutMs? });
+await appService.updateTool(name, tool);
+await appService.deleteTool(name);
+const result = await appService.testTool(name, args);  // { ok: true, result } | { ok: false, error }
+
 // Story Management
 const story = await appService.createStory(name, idea, userCharacterDesc, otherCharactersDesc, storyModel?);
 await appService.progressStory(storyId);
@@ -477,6 +485,46 @@ emitter.on('update', (newBalance: number) => {
 });
 ```
 
+### Example 8: Giving Agents Tools
+
+Tools let a room agent fetch or compute data mid-conversation. Define the tool once, grant it to specific agents, and the agent invokes it on its own (via the EXECUTE room action) when a conversation calls for it. The result is returned privately to the calling agent, which may chain several calls before speaking.
+
+```typescript
+const app = briyah.getAppService('user-123');
+
+// 1. Define a tool. `code` is the body of an async function receiving
+//    (args, helpers) and returning a JSON-serializable value.
+await app.createTool({
+    name: 'weather_lookup',
+    description: 'Gets the current temperature for a city',
+    parameters: [
+        { name: 'city', type: 'string', description: 'City name', required: true }
+    ],
+    code: `
+        const res = await helpers.fetch('https://wttr.in/' + encodeURIComponent(args.city) + '?format=j1');
+        const data = await res.json();
+        return { tempC: data.current_condition[0].temp_C };
+    `,
+    timeoutMs: 15000  // optional; default 30s, max 120s
+});
+
+// 2. Test it before any agent uses it
+const test = await app.testTool('weather_lookup', { city: 'Paris' });
+if (!test.ok) throw new Error(test.error);
+
+// 3. Grant it to an agent (grants are enforced server-side)
+const researcher = app.createAgent('Anthropic', 'Researcher', 'Researcher',
+    'A researcher who uses tools for exact answers', 'claude-haiku-4-5');
+researcher.toolNames = ['weather_lookup'];
+researcher.save();
+
+// 4. In a room, the agent calls the tool on its own when a question needs it.
+//    Other agents wait while it researches; a log-only 'tool' message records
+//    each call (visible when fetching messages with includeThoughts=true).
+```
+
+Agents can also delegate: an agent may respond with a `commission` action naming other agents, each of which researches independently (using its own tools) and replies with a `deliver`. The commissioner receives all deliverables at once and responds before the conversation continues. No SDK calls are needed for this — it is driven by the agents themselves.
+
 ## Data Storage
 
 Briyah stores data in the following structure:
@@ -489,13 +537,14 @@ Briyah stores data in the following structure:
 │   └── published-agents.json    # Published agent mappings
 └── user/
     └── {userId}/                # Per-user data
+        ├── agents/              # Agent configs and histories (one JSON per agent)
+        ├── rooms/               # Room metadata, message logs, artifacts (one folder per room)
+        ├── stories/             # Story state
+        ├── tools/               # User-defined tools (one JSON per tool)
         ├── prompts/             # User-specific prompts
         ├── upload/              # User file attachments
-        └── userconfig/          # User configuration files
-            ├── agents.json      # User's agents
-            ├── rooms.json       # User's rooms
-            ├── stories.json     # User's stories
-            └── balance.json     # User's balance
+        ├── transactions/        # Transaction records
+        └── userconfig/          # User preferences and balance
 ```
 
 ## Multi-Instance Support

package/data/common/config/image_models.json

@@ -1,141 +1,204 @@
 [
-  {
-    "name": "FLUX.1 Kontext (edit)",
-    "description": "Image-to-image editing; maintains character consistency",
-    "type": "image-to-image",
-    "service": "FalAI",
-    "model": "fal-ai/flux-pro/kontext/multi",
-    "centsPerImage": 4,
-    "imageProperties": {
-      "aspect_ratio": "1:1",
-      "safety_tolerance": "2",
-      "num_images": 1,
-      "output_format": "png"
-    }
-  },
   {
     "name": "FLUX.1 Kontext",
-    "description": "",
-    "type": "text-to-image",
-    "service": "FalAI",
-    "model": "fal-ai/flux-pro/kontext/text-to-image",
-    "centsPerImage": 4,
-    "imageProperties": {
-      "aspect_ratio": "1:1",
-      "safety_tolerance": "2",
-      "num_images": 1,
-      "output_format": "png"
+    "description": "Maintains character consistency across scenes",
+    "generation": {
+      "service": "FalAI",
+      "model": "fal-ai/flux-pro/kontext/text-to-image",
+      "centsPerImage": 4,
+      "imageProperties": {
+        "aspect_ratio": "1:1",
+        "safety_tolerance": "2",
+        "num_images": 1,
+        "output_format": "png"
+      }
+    },
+    "editing": {
+      "service": "FalAI",
+      "model": "fal-ai/flux-pro/kontext/multi",
+      "centsPerImage": 4,
+      "imageProperties": {
+        "aspect_ratio": "1:1",
+        "safety_tolerance": "2",
+        "num_images": 1,
+        "output_format": "png"
+      }
     }
   },
   {
     "name": "GPT Image 1.5",
     "description": "High quality; consistent characters across scenes",
-    "type": "text-to-image",
-    "service": "OpenAI",
-    "model": "gpt-image-1.5",
-    "centsPerImage": 21,
-    "imageProperties": {
-      "size": "1024x1024",
-      "quality": "auto",
-      "moderation": "low"
-    }
-  },
-  {
-    "name": "GPT Image 1.5 (edit)",
-    "description": "High quality image editing with reference images",
-    "type": "image-to-image",
-    "service": "OpenAI",
-    "model": "gpt-image-1.5",
-    "centsPerImage": 21,
-    "imageProperties": {
-      "size": "1024x1024"
+    "generation": {
+      "service": "OpenAI",
+      "model": "gpt-image-1.5",
+      "centsPerImage": 21,
+      "imageProperties": {
+        "size": "1024x1024",
+        "quality": "auto",
+        "moderation": "low"
+      }
+    },
+    "editing": {
+      "service": "OpenAI",
+      "model": "gpt-image-1.5",
+      "centsPerImage": 21,
+      "imageProperties": {
+        "size": "1024x1024"
+      }
     }
   },
   {
     "name": "GPT Image 1 Mini",
     "description": "Mediocre quality; some character consistency",
-    "type": "text-to-image",
-    "service": "OpenAI",
-    "model": "gpt-image-1-mini",
-    "centsPerImage": 10,
-    "imageProperties": {
-      "size": "1024x1024",
-      "quality": "auto",
-      "moderation": "low"
+    "generation": {
+      "service": "OpenAI",
+      "model": "gpt-image-1-mini",
+      "centsPerImage": 10,
+      "imageProperties": {
+        "size": "1024x1024",
+        "quality": "auto",
+        "moderation": "low"
+      }
+    },
+    "editing": {
+      "service": "OpenAI",
+      "model": "gpt-image-1-mini",
+      "centsPerImage": 10,
+      "imageProperties": {
+        "size": "1024x1024"
+      }
     }
   },
   {
     "name": "FLUX.2 MAX",
     "description": "Cheap",
-    "type": "text-to-image",
-    "service": "TogetherAI",
-    "model": "black-forest-labs/FLUX.2-max",
-    "centsPerImage": 4,
-    "imageProperties": {
-      "width": 1024,
-      "height": 1024,
-      "disable_safety_checker": false,
-      "response_format": "base64"
+    "generation": {
+      "service": "TogetherAI",
+      "model": "black-forest-labs/FLUX.2-max",
+      "centsPerImage": 4,
+      "imageProperties": {
+        "width": 1024,
+        "height": 1024,
+        "disable_safety_checker": false,
+        "response_format": "base64"
+      }
+    },
+    "editing": {
+      "service": "TogetherAI",
+      "model": "black-forest-labs/FLUX.2-max",
+      "centsPerImage": 4,
+      "imageProperties": {
+        "width": 1024,
+        "height": 1024,
+        "disable_safety_checker": false,
+        "response_format": "base64"
+      }
     }
   },
   {
     "name": "Stable Diffusion 3",
     "description": "Laughably poor quality",
-    "type": "text-to-image",
-    "service": "TogetherAI",
-    "model": "stabilityai/stable-diffusion-3-medium",
-    "centsPerImage": 4,
-    "imageProperties": {
-      "width": 1024,
-      "height": 1024,
-      "disable_safety_checker": false,
-      "response_format": "base64"
+    "generation": {
+      "service": "TogetherAI",
+      "model": "stabilityai/stable-diffusion-3-medium",
+      "centsPerImage": 4,
+      "imageProperties": {
+        "width": 1024,
+        "height": 1024,
+        "disable_safety_checker": false,
+        "response_format": "base64"
+      }
+    },
+    "editing": {
+      "service": "FalAI",
+      "model": "fal-ai/flux-pro/kontext/multi",
+      "centsPerImage": 4,
+      "imageProperties": {
+        "aspect_ratio": "1:1",
+        "safety_tolerance": "2",
+        "num_images": 1,
+        "output_format": "png"
+      }
     }
   },
   {
     "name": "Google Imagen 4",
     "description": "No character consistency",
-    "type": "text-to-image",
-    "service": "GoogleAI",
-    "model": "imagen-4.0-generate-001",
-    "centsPerImage": 4,
-    "imageProperties": {
-      "numberOfImages": 1,
-      "aspectRatio": "1:1"
+    "generation": {
+      "service": "GoogleAI",
+      "model": "imagen-4.0-generate-001",
+      "centsPerImage": 4,
+      "imageProperties": {
+        "numberOfImages": 1,
+        "aspectRatio": "1:1"
+      }
+    },
+    "editing": {
+      "service": "FalAI",
+      "model": "fal-ai/flux-pro/kontext/multi",
+      "centsPerImage": 4,
+      "imageProperties": {
+        "aspect_ratio": "1:1",
+        "safety_tolerance": "2",
+        "num_images": 1,
+        "output_format": "png"
+      }
     }
   },
   {
     "name": "Nano Banana Pro",
     "description": "",
-    "type": "text-to-image",
-    "service": "FalAI",
-    "model": "fal-ai/nano-banana-pro",
-    "centsPerImage": 15,
-    "imageProperties": {
-      "image_size": { "width": 1024, "height": 1024 },
-      "safety_tolerance": "2",
-      "num_images": 1,
-      "output_format": "png"
+    "generation": {
+      "service": "FalAI",
+      "model": "fal-ai/nano-banana-pro",
+      "centsPerImage": 15,
+      "imageProperties": {
+        "image_size": { "width": 1024, "height": 1024 },
+        "safety_tolerance": "2",
+        "num_images": 1,
+        "output_format": "png"
+      }
+    },
+    "editing": {
+      "service": "FalAI",
+      "model": "fal-ai/nano-banana-pro",
+      "centsPerImage": 15,
+      "imageProperties": {
+        "image_size": { "width": 1024, "height": 1024 },
+        "safety_tolerance": "2",
+        "num_images": 1,
+        "output_format": "png"
+      }
     }
   },
   {
     "name": "Nano Banana",
     "description": "",
-    "type": "text-to-image",
-    "service": "FalAI",
-    "model": "fal-ai/nano-banana",
-    "centsPerImage": 4,
-    "imageProperties": {
-      "image_size": { "width": 1024, "height": 1024 },
-      "safety_tolerance": "2",
-      "num_images": 1,
-      "output_format": "png"
+    "generation": {
+      "service": "FalAI",
+      "model": "fal-ai/nano-banana",
+      "centsPerImage": 4,
+      "imageProperties": {
+        "image_size": { "width": 1024, "height": 1024 },
+        "safety_tolerance": "2",
+        "num_images": 1,
+        "output_format": "png"
+      }
+    },
+    "editing": {
+      "service": "FalAI",
+      "model": "fal-ai/nano-banana",
+      "centsPerImage": 4,
+      "imageProperties": {
+        "image_size": { "width": 1024, "height": 1024 },
+        "safety_tolerance": "2",
+        "num_images": 1,
+        "output_format": "png"
+      }
     }
   },
   {
     "name": "No images",
-    "description": "Disable image generation (no real API calls)",
-    "service": "",
-    "model": ""
+    "description": "Disable image generation (no real API calls)"
   }
 ]

package/data/common/config/markup

@@ -1 +1 @@
-12.990938720000031
+13.132693000000032

package/data/common/config/story_models.json

@@ -5,6 +5,8 @@
     "service": "Anthropic",
     "model": "claude-sonnet-4-6",
     "small_model": "claude-haiku-4-5",
+    "moderator_service": "Anthropic",
+    "moderator_model": "claude-haiku-4-5",
     "cost": "300"
   },
   {
@@ -13,6 +15,8 @@
     "service": "Anthropic",
     "model": "claude-haiku-4-5",
     "small_model": "claude-haiku-4-5",
+    "moderator_service": "Anthropic",
+    "moderator_model": "claude-haiku-4-5",
     "cost": "80"
   },
   {
@@ -21,6 +25,8 @@
     "service": "Anthropic",
     "model": "claude-opus-4-8",
     "small_model": "claude-haiku-4-5",
+    "moderator_service": "Anthropic",
+    "moderator_model": "claude-haiku-4-5",
     "cost": "1500"
   },
   {
@@ -29,13 +35,17 @@
     "service": "Anthropic",
     "model": "claude-fable-5",
     "small_model": "claude-haiku-4-5",
+    "moderator_service": "Anthropic",
+    "moderator_model": "claude-haiku-4-5",
     "cost": "3000"
   },
   {
-    "name": "Grok 4.20",
+    "name": "Grok 4.3",
     "description": "",
     "service": "Grok",
-    "model": "grok-4.20-0309-reasoning",
+    "model": "grok-4.3",
+    "moderator_service": "Grok",
+    "moderator_model": "grok-4.3",
     "cost": "300"
   },
   {
@@ -44,6 +54,8 @@
     "service": "DeepSeek",
     "model": "deepseek-v4-pro",
     "small_model": "deepseek-v4-flash",
+    "moderator_service": "DeepSeek",
+    "moderator_model": "deepseek-v4-flash",
     "cost": "3"
   }
-]
+]

package/data/common/config/story_models_full.json

@@ -46,10 +46,10 @@
     "cost": "60"
   },
   {
-    "name": "Grok 4.20",
+    "name": "Grok 4.3",
     "description": "",
     "service": "Grok",
-    "model": "grok-4.20-0309-reasoning",
+    "model": "grok-4.3",
     "cost": "300"
   },
   {

package/data/common/prompts/character/create_user_character.prompt

@@ -22,23 +22,15 @@ Create a detailed character profile that includes:
 
 2. **Backstory**: A rich history that explains how they became who they are today. Include key life events, relationships, and experiences that shaped them.
 
-3. **Personality**: Core traits, temperament, values, beliefs, and how they typically interact with others. What makes them unique?
+3. **Special Abilities**: Any special abilities or powers that differentiate them from other characters in the story.
 
-4. **Motivations**: What drives them? What are their goals, desires, fears, and needs?
+4. **Strengths**: Skills, talents, positive qualities, and what they excel at.
 
-5. **Special Abilities**: Any special abilities or powers that differentiate them from other characters in the story.
-
-6. **Strengths**: Skills, talents, positive qualities, and what they excel at.
-
-7. **Weaknesses**: Flaws, vulnerabilities, limitations, and areas where they struggle.
-
-8. **Relationships**: How they relate to other characters in the story (if applicable based on the scenario).
+5. **Relationships**: How they relate to other characters in the story (if applicable based on the scenario).
 
 **Important Guidelines:**
 - Make the character interesting, complex, and memorable
 - Ensure the character fits naturally within the story's setting and tone
-- Give the character internal conflicts and contradictions that make them feel human
-- Consider how the character's background influences their current behavior
 - Make sure the profile is consistent with the description provided above
 - Leave room for the player to make choices and shape the character's development
 
@@ -68,4 +60,3 @@ Example format:
   }
 }
 ```
-Note: Do NOT use double-quotes anywhere in the description, character_profile, or inventory; use single-quotes instead.

package/data/common/prompts/character/introduce_character.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "name": "introduce_character_response",
+  "description": "Response schema for creating a brief profile for a character introduced mid-story",
+  "type": "object",
+  "properties": {
+    "description": {
+      "type": "string",
+      "description": "A brief 1-2 sentence description containing only immediately observable physical characteristics"
+    },
+    "character_profile": {
+      "type": "string",
+      "description": "A short markdown-formatted character profile covering the character's role in the story, what they realistically know, and a brief personality description"
+    }
+  },
+  "required": ["description", "character_profile"],
+  "additionalProperties": false
+}

package/data/common/prompts/character/introduce_character.mock

@@ -0,0 +1,4 @@
+{
+  "description": "A friendly newcomer with an unassuming appearance",
+  "character_profile": "**Name:** New Character\n\n**Role in the Story:** A local who has just crossed paths with the main characters.\n\n**What They Know:** Only what they have personally seen in their daily routine; they know nothing of the party's secrets.\n\n**Personality:** Curious and talkative, with a plainspoken manner."
+}

package/data/common/prompts/character/introduce_character.prompt

@@ -0,0 +1,58 @@
+# Introduce New Character
+You are creating a brief character profile for {{agentName}}, a character who has just been introduced into an ongoing story.
+
+## Recent Story Events
+{{#if formattedHistory}}
+{{#each formattedHistory}}
+{{this}}
+{{/each}}
+{{else}}
+Refer to the conversation history above for recent events.
+{{/if}}
+
+## Plot Plan (narrator's eyes only — do not reveal to others)
+{{plotPlan}}
+
+## Other Characters in the Story (name and visible description)
+{{#if otherCharacters}}
+{{#each otherCharacters}}
+- **{{name}}**: {{description}}
+{{/each}}
+{{else}}
+(No other characters yet.)
+{{/if}}
+
+## Your task
+Create a SHORT and SIMPLE character profile for {{agentName}}. This is a quick introduction, not a full character study. The profile must cover only:
+
+1. **Name**: The character's name ({{agentName}})
+
+2. **Role in the Story**: Where this character fits into the story. How are they connected to the setting, the other characters, and the events in the plot plan?
+
+3. **What They Know**: What this character would *realistically* know about the story so far. Only include events they could plausibly have witnessed, been told about, or learned through their position in the story world.
+**NOTE:** Do *not* mention information the character should *not* know about. For example, don't say 'Jessica doesn't know about the envelope under the seat'. That just gives it away to the new character.
+
+4. **What They Have Experienced**: This character knows nothing about the events of the story other than what you reveal to them here. So, give them details about the most recent interaction or dialog that led to them being introduced into the story.
+
+5. **Who They Are With**: Using the recent story events, work out which other characters {{agentName}} is currently in contact with (in the same scene / interacting with them). For each such character, describe their *visible, observable appearance* drawn from the "Other Characters in the Story" list above — what {{agentName}} can plainly see. {{agentName}} perceives these people by their appearance, NOT by name or backstory: only refer to a character by name if {{agentName}} would realistically already know it (e.g. they were introduced by name in the recent events). Otherwise describe them observably (for example, 'a woman in her early 30s with olive skin and an athletic build'). Do not include any character who is not present with {{agentName}}, and do not reveal hidden details, names, or backstory the character couldn't observe.
+
+6. **Personality**: A brief description of their temperament, manner, and how they speak.
+
+**Important Guidelines:**
+- Stay consistent with how the character has already appeared in the story events above
+- If the plot plan assigns this character a specific role or secret, include only what THIS character would know about it
+- Do *not* say 'He has no knowledge of...' and proceed to list all the things in the story the character shouldn't know.
+- Use your judgment about how detailed this character profile should be given their role in the story
+
+## Response format
+Return a JSON object with these fields:
+- `description`: A brief 1-2 sentence observable description of the character (physical appearance only). Stay consistent with any description already given in the story; otherwise invent something plausible.
+- `character_profile`: The short markdown-formatted character profile covering the sections above.
+
+Example format:
+```json
+{
+  "description": "A stocky man in his 50s with a weathered face, gray stubble, and a dockworker's rough hands.",
+  "character_profile": "**Name:** {{agentName}}\n\n**Role in the Story:** [Where they fit]\n\n**What They Know:** [Realistic knowledge of story events]\n\n**What They Have Experienced:** [The interaction that brought them in]\n\n**Who They Are With:** [Observable appearance of the characters present with them, named only if they'd know the name]\n\n**Personality:** [Brief temperament and speech style]"
+}
+```

package/data/common/prompts/character/perceive.prompt

@@ -22,6 +22,9 @@ Use your character profile to:
 {{visibleArtifacts}}
 ```
 
+## Your Inventory and Condition
+If a "Your private context (known only to you)" section is included with the current situation, it lists what your character is currently carrying, wearing, or possessing, along with any physical or mental conditions (wounded, exhausted, etc.). Stay consistent with it: only use or reference items you actually have, and let your conditions shape what your character can realistically do.
+
 ## How to Respond
 
 You should respond with a string of text that indicates what your character says or does.

package/data/common/prompts/character/progress_character.json

@@ -4,19 +4,23 @@
   "description": "Response schema for updating a character profile as the story progresses",
   "type": "object",
   "properties": {
+    "no_changes": {
+      "type": "boolean",
+      "description": "Set true when this character was NOT significantly affected by recent events. When true, omit description, character_profile, and inventory entirely - the existing profile is left unchanged."
+    },
     "description": {
       "type": "string",
-      "description": "A brief 1-2 sentence description containing only immediately observable physical characteristics"
+      "description": "A brief 1-2 sentence description containing only immediately observable physical characteristics. Omit when no_changes is true."
     },
     "character_profile": {
       "type": "string",
-      "description": "An updated markdown-formatted character profile reflecting growth and changes from recent story events"
+      "description": "An updated markdown-formatted character profile reflecting growth and changes from recent story events. Omit when no_changes is true."
     },
     "inventory": {
       "type": "string",
-      "description": "An updated concise markdown inventory reflecting items gained, lost, consumed, equipped, or any new/resolved conditions since the last chapter. Use '## Items' and (optionally) '## Conditions' sections. Omit this field if the character was just introduced or had no inventory artifact yet."
+      "description": "An updated concise markdown inventory reflecting items gained, lost, consumed, equipped, or any new/resolved conditions since the last chapter. Use '## Items' and (optionally) '## Conditions' sections. Omit this field if the character was just introduced, had no inventory artifact yet, or no_changes is true."
     }
   },
-  "required": ["character_profile"],
+  "required": ["no_changes"],
   "additionalProperties": false
 }

package/data/common/prompts/character/progress_character.mock

@@ -1,4 +1,5 @@
 {
+  "no_changes": false,
   "character_profile": "## Background\n\nThe character has grown through recent events and interactions.\n\n## Personality\n\n- More confident after recent experiences\n- Developing deeper relationships\n\n## Motivations\n\n- Seeking to understand the unfolding situation\n- Working toward personal goals",
   "description": "A character who has evolved through the story"
 }