briyah 1.2.3 → 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/model_prices.json

@@ -10214,6 +10214,37 @@
         },
         "supports_output_config": true
     },
+    "claude-fable-5": {
+        "cache_creation_input_token_cost": 1.25e-05,
+        "cache_creation_input_token_cost_above_1hr": 2e-05,
+        "cache_read_input_token_cost": 1e-06,
+        "input_cost_per_token": 1e-05,
+        "litellm_provider": "anthropic",
+        "max_input_tokens": 1000000,
+        "max_output_tokens": 128000,
+        "max_tokens": 128000,
+        "mode": "chat",
+        "output_cost_per_token": 5e-05,
+        "search_context_cost_per_query": {
+            "search_context_size_high": 0.01,
+            "search_context_size_low": 0.01,
+            "search_context_size_medium": 0.01
+        },
+        "supports_adaptive_thinking": true,
+        "supports_assistant_prefill": false,
+        "supports_computer_use": true,
+        "supports_function_calling": true,
+        "supports_pdf_input": true,
+        "supports_prompt_caching": true,
+        "supports_reasoning": true,
+        "supports_response_schema": true,
+        "supports_tool_choice": true,
+        "supports_vision": true,
+        "supports_xhigh_reasoning_effort": true,
+        "supports_max_reasoning_effort": true,
+        "supports_native_structured_output": true,
+        "supports_output_config": true
+    },
     "claude-opus-4-8": {
         "cache_creation_input_token_cost": 6.25e-06,
         "cache_creation_input_token_cost_above_1hr": 1e-05,

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"
   },
   {
@@ -12,30 +14,48 @@
     "description": "",
     "service": "Anthropic",
     "model": "claude-haiku-4-5",
+    "small_model": "claude-haiku-4-5",
+    "moderator_service": "Anthropic",
+    "moderator_model": "claude-haiku-4-5",
     "cost": "80"
   },
   {
-    "name": "Claude Opus 4.7",
+    "name": "Claude Opus 4.8",
     "description": "Overkill for storytelling",
     "service": "Anthropic",
-    "model": "claude-opus-4-7",
+    "model": "claude-opus-4-8",
     "small_model": "claude-haiku-4-5",
+    "moderator_service": "Anthropic",
+    "moderator_model": "claude-haiku-4-5",
     "cost": "1500"
   },
   {
-    "name": "Grok 4.20",
+    "name": "Claude Fable 5",
+    "description": "Way overkill for storytelling",
+    "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.3",
     "description": "",
     "service": "Grok",
-    "model": "grok-4.20-0309-reasoning",
-    "small_model": "grok-4.20-beta-0309-non-reasoning",
+    "model": "grok-4.3",
+    "moderator_service": "Grok",
+    "moderator_model": "grok-4.3",
     "cost": "300"
   },
   {
-    "name": "Mock",
-    "description": "Mock LLM for testing (no real API calls)",
-    "service": "Mock",
-    "model": "mock-fast-v1",
-    "cost": "0"
+    "name": "DeepSeek v4",
+    "description": "",
+    "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

@@ -1,9 +1,10 @@
 [
   {
-    "name": "Claude Sonnet 4.5",
+    "name": "Claude Sonnet 4.6",
     "description": "Best storyteller, bar none",
     "service": "Anthropic",
-    "model": "claude-sonnet-4-5",
+    "model": "claude-sonnet-4-6",
+    "small_model": "claude-haiku-4-5",
     "cost": "300"
   },
   {
@@ -11,15 +12,25 @@
     "description": "",
     "service": "Anthropic",
     "model": "claude-haiku-4-5",
+    "small_model": "claude-haiku-4-5",
     "cost": "80"
   },
   {
-    "name": "Claude Opus 4.6",
+    "name": "Claude Opus 4.8",
     "description": "Overkill for storytelling",
     "service": "Anthropic",
-    "model": "claude-opus-4-6",
+    "model": "claude-opus-4-8",
+    "small_model": "claude-haiku-4-5",
     "cost": "1500"
   },
+  {
+    "name": "Claude Fable 5",
+    "description": "Way overkill for storytelling",
+    "service": "Anthropic",
+    "model": "claude-fable-5",
+    "small_model": "claude-haiku-4-5",
+    "cost": "3000"
+  },
   {
     "name": "Qwen",
     "description": "",
@@ -35,11 +46,18 @@
     "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"
+  },
+  {
+    "name": "DeepSeek v4",
+    "description": "",
+    "service": "DeepSeek",
+    "model": "deepseek-v4-pro",
+    "small_model": "deepseek-v4-flash",
+    "cost": "3"
   }
-
 ]

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."
+}