Skip to the content.

Script Rules

core/agent-graph/script binds a rule script to a graph node. A rule reads the state it declares, returns the state it declares, and does nothing else: it does not speak (only a model node streams text), it does not open a session, and it cannot suspend.

It is not a built-in node kind — a script engine is a dependency choice, so the host registers it where it opens the graph:

built, err := nodes.Open(ctx, rt, "graphs/game.yaml", config.File("graphs/game.yaml"),
    nodes.WithRuntimeKinds(func(rt nodes.Runtime) ([]graph.NodeKind, error) {
        kind, err := script.New(
            script.WithRuntime(rt),                 // what a tool call dispatches through
            script.WithBackends(starlark.New()),    // config.backend resolves here
        )
        if err != nil {
            return nil, err
        }
        return []graph.NodeKind{kind}, nil
    }),
)

New fails at construction when no backend is registered, a backend is nil, or two share a name — a wiring mistake a host should hear about once, not per turn. The default source is a FileSource rooted at the process working directory; script.WithSource replaces it for embedded or generated rules.

That is the whole reason it can be bounded, tested and replayed. It is also what makes it not the script runtime this repository removed: there is no board, no channel and no publish — the graph's state already is the board.

Configuration

- id: tally
  kind: script
  timeout: 2s # the engine bounds one invocation
  config:
    backend: starlark # resolved against the host's backend table
    path: rules/vote_tally.star # handed to the source
    reads: [game, public_log] # projected into the script
    writes: [game, public_log] # the only keys it may return
    allow: [tool:werewolf_game_event] # empty means it can call nothing
    max_output_bytes: 65536 # over the cap fails, never truncates
    budget:
      max_steps: 200000 # reproducible: same source, same state, same steps
      memory_mib: 64 # only a backend that declares it may be asked
    version: pinned # pinned | latest

A configuration states what it needs, and construction fails when the backend cannot honour it:

configuration requires
budget.max_steps Capabilities.Terminating
budget.memory_mib Capabilities.MemoryBounded
allow Capabilities.Tools, and a runtime to dispatch through

That is deliberate: a document must never run with less than it asked for.

The script

def run(state):
    game = state["game"]          # only the keys in config.reads
    votes = {}
    for vote in game["votes"]:
        votes[vote] = votes.get(vote, 0) + 1
    return {"game": game, "votes": votes}   # only the keys in config.writes

Transcripts are a view, not a list

state["history"] behaves like a list of {"role", "text"} dicts — len(), t[i] (negative indices included), t[a:b] and for message in t all work — but it is answered lazily:

question cost
len(t) / t.count O(1)
t.last / t.first one dict
t[i], t[-2:] the messages asked for
for message in t every message, which is what asking for them means
str(t) every message, because that is what printing asks

The point is the shape a rule usually has: "how many turns have we had" and "what did they just say" cost nothing, and a 5,000-message transcript is the same price as an empty one. A rule that wants the whole history as text pays for it, once, when it asks.

A message reads the way it always did, and it is one value rather than a dict plus a hashtable:

message = state["history"][-1]
message["role"]        # "narrator"
message["text"]        # the line
message.role           # the same, as an attribute
message.get("text")    # dict-shaped access, with a default
"role" in message      # True
str(message)           # {"role": "narrator", "text": "..."}

It is read-only and unhashable: message["role"] = ... fails, and a message is not a key. Two messages compare equal when they carry the same role and text.

The view is read-only: t.pop(), t.append(...) and t[0] = ... are errors. A rule computes new state and returns it; it does not edit the transcript it was given.

Tools

def run(state):
    tool("werewolf_game_event", {"event_type": "night_resolve", "phase": "dawn"})
    return {"phase": "dawn"}

tool returns {"ok": True, "text": ...} and refuses anything allow does not name. The call goes through the runtime's ordinary path — the same middleware chain, policy checks and catalog view a tool node uses — and each call is recorded with its argument hash, so a replay answers from the record instead of running the tool again.

A failed tool aborts the script. Starlark has no exception to catch, and a rule that cannot complete its action should fail the step rather than guess.

Versions and replay

Every invocation records script.run (source reference and version) and every call records script.tool, both of them durably with the step.

Budgets and non-goals

Backends

backend deterministic terminating memory bound isolated tools cost
starlark ✓ language ✓ language ✗ ✗ ✓ ~6 µs per rule

A backend is a language: Compile(ctx, Script) (Program, error) and Run(ctx, Program, state, budget, host). To add one:

  1. implement script.Backend, declaring only what you can promise;
  2. run scripttest.Run(t, scripttest.Fixture{...}) — the same contract cases every backend runs, so a second language is verified rather than re-derived;
  3. keep Host as the only way out: tool policy, recording and replay live in the node, so no backend can get them wrong.

Errors

failure class
bad config, missing source, compile error Validation
a script that fails while running Aborted
a budget that runs out BudgetExceeded
a write the config does not declare, or the wrong kind Validation
a tool outside allow Forbidden