Automation - Inktomi93/OrbWeaver GitHub Wiki

Automation is an event-driven rule engine. A rule triggers on a chat event or on a library change (a character, persona, world-info or asset update), checks a condition written as an expression, and runs its actions: it offers quick replies, nudges the narrator, draws a picture, moves a meter, or holds back until you approve. A rule can keep per-chat state that later rules read. A few rules watch your whole library instead, covered at the end. You add rules from a ready-made list or write your own, switch on the ones you want, and check later what they did.

Nothing here asks the model nicely and hopes. A rule either fires or the log tells you why it didn't, and what the model hands a rule is checked before it can land anywhere. How that works is on How a turn is built under "How automation rules run".

Add a rule to a chat

Rules are the host's. In a chat you host:

Open the room's This chat settings, then Host controls, then Rules.
Press Add a rule and pick one. Some are two rules that work as a pair, and the button says so ("Add 2 rules").
Set its options and press Add rule.
Flip the rule's switch, or both switches for a pair. A new rule is born switched off, so adding one never changes your chat until you turn it on.

Open a rule to find:

Test, a dry run. It shows whether the rule's condition would match and what each step would do. It runs nothing, and it shows in Recent activity as a test run.
Run now, in the rule's More actions menu. It fires the rule once, ignoring its condition and its rate cap. The rule has to be switched on. On a rule that costs a model call, the menu item says so.
Connections, for rules that ask for a reply or draw a picture. Give that one rule its own Chat or Image generation connection, or leave it alone to use yours.
Recent activity, covered below.

Edit, beside Test, opens the rule in the rule editor (below). Editing a rule you added from the list makes it a custom rule of your own. A saved roster carries the room's switched-on rules, and applying one adds them and switches them on. → Rooms and group chats

Write your own rule

Beside Add a rule is Custom rule, which opens the rule editor:

Rule name and Description.
When: the event the rule runs on. Only the events it can use are listed.
Condition (CEL): an expression that filters the matching events.
Include events caused by automation: off by default. When it's on, the depth cap still stops a chain of rules setting each other off forever.
Cooldown (seconds) and Maximum runs per hour.
Actions, which run in the order they're listed. Pick one under Action to add, fill in its fields, and add more the same way.

Edits save by themselves once the rule has a name and a finished action. A new rule starts switched off, like every other. An unfinished rule stays as a draft in this browser, listed under your rules, until you finish it or press Discard.

The same editor is under Settings, Automation, for library-wide rules. Those can't read the chat, chat variables or choices.

Times in a rule

A rule reads the clock in the timezone of the browser that last saved it. That covers now.hour and now.dayOfWeek in a condition, quiet hours on a rule from the list, and {{time}} and {{date}} in a rule's own text. The editor says which timezone the rule uses.

A rule saved before rules carried a timezone uses UTC until its next edit, and the editor says so.
A rule you add from the list, or one a saved roster switches on, takes your timezone when it's added.
If the server doesn't recognise your browser's timezone, the rule saves with UTC, and the editor says that too.
Cooldowns, rate limits and how long a card waits for you count real elapsed time, so the timezone never changes them.

What's in the list

The picker describes each rule in a sentence, and marks the ones that cost a model call each time they fire and the ones that ask before acting. Those sentences are the reference. The shape of the list:

For	Rules
Quick replies	Opener chips, Offer chips after a beat, Call a vote
Asking first	Welcome-back recap, Auto-add lore entries, Distill lore, Rumour mill, Prose audit
Steering the narrator	Periodic pacing nudge, Cutaways, Callbacks, Scene veil, React to lore activation, Story pacing analysis, Spotlight balance
Meters	The needle, Clock fires when full
Pictures and backgrounds	Illustrate the scene, Illustrate on lore reveal, Auto-set scene background
Notices	Async table nudge, for shared rooms
Your whole library	Living library, covered at the end

A game steers its own story, so the rules that study the story can't be added while a game is active: The needle, Distill lore, Rumour mill, Prose audit, Story pacing analysis and Spotlight balance. → RPG mode

Which model a rule uses

A rule that makes a character or narrator reply runs on the room host's Chat model. The reply is an ordinary one, steered by the rule's instruction.
The quiet steps run on the host's Utility model: the analyst behind Story pacing analysis, The needle and the other "study the story" rules, writing a picture's prompt, choosing a background, and captioning a portrait for Living library. Without a Utility model those steps can't run, and the rule's Recent activity is where it shows. The analyst needs a Utility model that can return structured output, and portrait captioning needs one that accepts images. → Connect a model
Pictures are drawn by your Image generation model.

In a shared room the host pays for all of it, including rules that fire because a friend posted. → Share with friends

Cards: approve before the AI acts

A rule marked Asks before acting changes nothing by itself. It raises a card in the chat, and only the host sees it. Press Do it to go ahead or dismiss it to say no. When several are waiting, you see the newest with a "+N pending" count.

Lore cards write into the world book you chose when you added the rule, and that book has to be attached to the chat. Auto-add lore entries also has a Before writing option if you'd rather it write without asking.
Prose audit shows Show the change on its card, with the exact words it would fix. If you accept, the fix lands as a new swipe and the original stays as a swipe. If you swipe or edit that reply before accepting, the fix is refused. It audits Only when I ask by default: right after a reply that bothered you, press Run now and it checks the newest reply. No card means it found nothing to fix.
Welcome-back recap offers a recap when you open a room after being away.

Cards aren't saved. An unanswered one expires after about half an hour, and a server restart or a dropped connection clears it. The rule raises a fresh card the next time it fires.

Quick-reply chips

Chips are one-tap suggestions in the chat. Everyone in the room sees them, not just the host. A chip either sends its text as your own line, or drops it into your message box so you can edit it first. Opener chips do the second.

Call a vote never fires by itself. The host runs it with Run now, and each person's pick goes in as their own line. Chips are temporary: reloading the page clears them until the rule raises them again.

Story meters

The needle and Clock fires when full each put a small widget in the room for everyone, once the rule has run.

The needle is a "Story tension" dial. When the score reaches the level you set, the room's background changes to one of yours that fits. It only ever picks from backgrounds you already have, so with none, nothing happens. The analyst's notes stay private. The room sees only the score.
Clock fires when full fills one step per reply. When it's full, the narrator works something into the story, or you get a notification (your choice), and the clock resets.

See what rules did

Open a rule's Recent activity to see what it did, with the reason: Fired, Condition not met, Rate-capped, Action errored, No authority, and a few more. Condition not met is only recorded after a rule's first run, so an empty log can just mean its condition hasn't held yet. A card a rule raised shows up only once you accept it. Start here when a rule seems quiet.
The Activity tab in the room's panel (host only) shows what every rule did, newest first. Cards you accepted carry a Confirmed badge.
A rule that errors repeatedly in a row switches itself off and sends you a notice. Its row shows a Turned off badge and explains why. Open Recent activity, fix the cause, such as a missing Utility model, then switch it back on. A Can't run badge means its saved actions cannot be read; remove that rule and add it again instead.
Notices, such as a clock set to notify you or Async table nudge pinging members who are waiting, arrive in your notifications.

Library-wide rules and the rate limit

Open Settings, then Automation. These rules belong to your account; you do not need server-admin access. Library-wide rules watch your own library with no chat open. Living library is the one on the list: when a character's card changes, it paints a fresh portrait. It works from the card's avatar, so a card without one can't be painted, and the rule's Recent activity shows the error.

Rate limit is where you set Runs per hour for all your library-wide rules together. It doesn't cover chat rules. Those have fixed limits: every rule has an hourly limit, and each room has a ceiling across its rules. A rule that hits a limit isn't broken; its Recent activity says Rate-capped. Chat rules that cost a model call also have an Offer to run it when rate-capped switch, on by default. Library-wide rules never raise that offer.

Limits

Rules are the host's. A rule acts only while the person who added it is still the host. After a hand-off, the previous host's rules stop acting, and Recent activity shows No authority.
Cards and chips live only while the room is open, and aren't saved.
Library-wide rules don't update live. Their Last ran line refreshes the next time you look.

Next steps: RPG mode for the game-side meters, Rooms and group chats for rosters, and Connect a model for the Utility model.