Runtime manifest

Generated by pnpm schemas:generate from the Zod schemas in packages/shared/src/schemas/. Do not edit by hand; change the schema's .describe() text instead.

Frontmatter of runtimes/<id>/RUNTIME.md, and the inline runtime of a root PLUGIN.md.

JSON Schema: runtime-manifest.schema.json.

In the path headings below, [] is a list item and .* is a map value.

Top-level fields

Field	Type	Required	Description
description	text	no	What the runtime does. Plain string; translations go in locale files.
schedule	object	no	When and in what order the runtime runs.
io	object	no	What the runtime reads and produces.
agent	object	no	Settings of an agent runtime, the kind of a runtime without a function block: it drives model tool calls from the prompt body.
function	object	no	Makes this a function runtime, which runs a JavaScript handler instead of a model. function: {} takes every default. Not allowed with agent.
guard	string	no	Path of the guard module. It runs before the runtime and can skip it.
effects	object	no	Declared read and write sets, used to detect parallel hazards.
permissions	object	no	Declared permission upper bounds.

schedule

Field	Type	Required	Description
stage	"setup" or "pre-turn" or "narrative" or "post-turn" or "audit"	no	Stage the runtime runs in. Required for an auto trigger, the default. Order: setup, pre-turn, narrative, post-turn, audit.
every	integer	no	auto only: run on the logical turns that are a multiple of this number. Defaults to 1, every turn.
trigger	object	no	When the runtime is activated. Leave it out for an auto runtime without options.
needs	list of string or object	no	Upstream runtimes or contracts that must succeed first. Sets order and gates this runtime.
after	list of string or object	no	Upstream runtimes or contracts that run first. Sets order only; it does not gate and does not activate a provider.
detached	boolean or object	no	true lets the turn finish before this runtime does: it runs afterwards as a durable background job. Only on stage post-turn or audit. An object sets the job's options and also makes it detached. Defaults to false: the turn waits.
background	boolean	no	true runs a manual or event activation as a durable background job: the caller gets a job ID at once. Defaults to false: the caller waits for the result.
subagentOnly	boolean	no	true makes this agent runtime a sub-agent provider: the scheduler never runs it, and another runtime runs it with ctx.agents.run or the delegate tool. It implies trigger: manual and allows no stage, needs, after, background, io.output.recordAs, guard or io.visibility: story. Defaults to false.

schedule.trigger

Field	Type	Required	Description
type	"auto" or "manual" or "event"	no	auto runs in its stage every turn, or every schedule.every-th turn. manual runs on an explicit RPC call. event runs when topic is emitted. Defaults to auto.
topic	string	no	Event topic to subscribe to. Required for event.
maxTriggerCount	integer	no	Maximum number of triggers in one session.
cooldownTurns	integer	no	Minimum number of turns between two triggers.
startTurn	integer	no	First logical turn at which the runtime may trigger. When unset, it triggers as soon as its stage opens.

schedule.needs[] (form 1 of 2)

Field	Type	Required	Description
runtime	string	yes	Runtime ID in this package: <pluginId>/<runtimeId>, or the package ID for a single runtime.
scope	"turn" or "session"	no	turn gates on the same execution. session gates on the persistent setup snapshot and is valid only on stage setup.

schedule.needs[] (form 2 of 2)

Field	Type	Required	Description
contract	string	yes	Contract ID. List it in the package's requires when a provider must be active; otherwise the runtime uses it when one is.
cardinality	"one" or "all"	no	one takes a single provider; all takes every provider. Defaults to one.
scope	"turn" or "session"	no	turn gates on the same execution. session gates on the persistent setup snapshot and is valid only on stage setup.

schedule.after[] (form 1 of 2)

Field	Type	Required	Description
runtime	string	yes	Runtime ID in this package: <pluginId>/<runtimeId>, or the package ID for a single runtime.

schedule.after[] (form 2 of 2)

Field	Type	Required	Description
contract	string	yes	Contract ID. This runtime runs after the contract's active providers; it never activates a provider.
cardinality	"one" or "all"	no	one takes a single provider; all takes every provider. Defaults to one.

schedule.detached

Field	Type	Required	Description
settle	boolean	no	true makes the next player action wait until this runtime's job has finished, for at most maxSettleWaitMs. Defaults to false.
maxSettleWaitMs	integer	no	Longest time in ms the next action waits for the job, at most 120000. Requires settle: true.
maxQueueMs	integer	no	Longest time in ms the job may wait in the queue.
maxExecutionMs	integer	no	Longest time in ms the job may run.

io

Field	Type	Required	Description
inputs	map of object	no	Typed input bindings keyed by local name. An agent reads them at runtime-inputs.<name>.value.
selfData	list of object	no	Own plugin data inlined into the agent prompt.
payloadSchema	string	no	Schema that validates the activation payload.
output	object	no	What the runtime produces.
visibility	"story" or "system"	no	Output kind the kernel dispatches on: story for the main narrative provider, system for every other runtime. Defaults to system.
concealed	boolean	no	true for a runtime that handles hidden content. Its prompt, model reply, tool arguments, results and output are removed from traces, live streams and API results, and text it returns is not written to the conversation. Not allowed with visibility: story.

io.inputs.*

Field	Type	Required	Description
from	object	yes	Producer of the value: a runtime in this package, a contract, or a kernel input. A kernel input takes no other field.
scope	"turn" or "committed"	no	turn reads the same execution's upstream result. committed reads the latest committed export and needs recordAs. Defaults to turn.
select	string	no	JSON Pointer applied to the upstream value. Declaring select with scope: committed is rejected; committed inputs read the complete export. Example: "/narrativeOutput".
required	boolean	no	true stops this runtime when the upstream value is missing or failed. Defaults to true. A story runtime (io.visibility: story) must set it to false for contract inputs.
accepts	string	no	Schema the bound value must satisfy: a local path or contract:<contractId>. It adds to the public contract check.
recordAs	string	no	Export key to read from the producer. Required with scope: committed.

io.inputs.*.from (form 1 of 3)

Field	Type	Required	Description
runtime	string	yes	Runtime ID in this package: <pluginId>/<runtimeId>, or the package ID for a single runtime.

io.inputs.*.from (form 2 of 3)

Field	Type	Required	Description
contract	string	yes	Contract ID. List it in the package's requires when a provider must be active; otherwise the runtime uses it when one is.
cardinality	"one" or "all"	no	one takes a single provider; all takes every provider. Defaults to one.

io.inputs.*.from (form 3 of 3)

Field	Type	Required	Description
kernel	"turn-digest@1" or "operations@1"	yes	Kernel input: the turn digest or staged operations from completed upstream runs.

io.selfData[]

Field	Type	Required	Description
namespace	string	yes	Own data namespace to inline. Data of other plugins cannot be read.
as	string	yes	Tag that wraps the injected block in the prompt. Example: "<existing-affinity>".
format	"summary" or "full" or "ids-only"	no	summary lists key, update time and truncated JSON. ids-only lists keys. full lists complete JSON. Defaults to summary. Default: "summary".
maxEntries	integer	no	Maximum number of entries injected. Above it, half are the oldest and half the most recently updated. Defaults to 50. Default: 50.

io.output

Field	Type	Required	Description
contract	string	no	Contract this runtime's output publishes. The package provides it; provides needs no entry for it.
schema	string	no	Private schema that validates the runtime's output.
recordAs	string	no	Export key under which the output is persisted for later executions. Requires schema.

agent

Field	Type	Required	Description
model	string	no	Model slot the agent uses. Defaults to story with io.visibility: story, otherwise plugin. Example: "utility".
toolChoice	"required" or object	no	required makes the model call a tool on every step. { name } makes it call that one tool. Without it, the model chooses.
reasoning	boolean	no	false turns model reasoning off for this runtime. Defaults to true: the model's own reasoning setting applies.
history	object	no	Bounds the agent's prompt history. When omitted, the runtime sees the shared session history.
tools	object	no	Tools the agent's model may call.
advertiseEvents	boolean	no	true lists the session's event directory in the prompt so the model knows which topics it may emit.
finishWith	string	no	Tool that ends the run: the run completes after a successful call to it, and fails if it ends without one. The model must call a tool on every step (toolChoice: required) unless toolChoice says otherwise. Not with completion, which is the long form for several tools or explicit completion.
completion	object	no	How the agent run ends. For one completing tool, finishWith is shorter.
loop	object	no	Time, retry and step limits of the agent loop, and its profile.

agent.toolChoice

Field	Type	Required	Description
name	string	yes	Name of the tool to force.

agent.history

Field	Type	Required	Description
includeSummaries	boolean	no	Include persisted summaries alongside the bounded history window. Defaults to false.
maxTurns	integer	yes	Number of most recent turns kept in the agent's prompt history. 0 sends no history.

agent.tools

Field	Type	Required	Description
builtin	list of string	no	Names of builtin tools the runtime may call.
plugin	list of string	no	Names of this package's own tools the runtime may call. Each must be listed in contributes.tools. The runtime of a single-runtime package gets every contributed tool when this is omitted.
defer	true or list of string	no	Deferred tool loading. true defers the whole whitelist; a list defers only those names.
services	list of string or object	no	Services the agent imports as tools. Each names a contract; the one active provider that offers it to models answers the call. Without one the tool is left out for the run. A write service's tool stages the provider's writes, which commit with this runtime's work; it is left out of a run that cannot change data there.
datasets	list of string or object	no	Datasets of this package the agent reads and writes through generated tools (<dataset>-get, -list, -upsert, -update). A name gives every tool the dataset offers; { dataset, tools } gives some of them.

agent.tools.services[]

Field	Type	Required	Description
contract	string	yes	The contract ID of the model-facing service to import.
as	string	no	The tool name the model sees. Defaults to the contract without its version, dots as dashes (inventory.items@1 → inventory-items).

agent.tools.datasets[]

Field	Type	Required	Description
dataset	string	yes	A dataset of this package (contributes.datasets).
tools	list of "get" or "list" or "upsert" or "update"	yes	The dataset tools this agent gets; each must be one the dataset offers.

agent.completion

Field	Type	Required	Description
require	"explicit" or "tool-use"	no	explicit needs a completing tool or runtime-done. tool-use needs a successful tool named in afterTools, or any successful business tool when afterTools is empty. Failed calls and runtime-done do not count.
afterTools	list of string	no	The runtime completes after a successful call to one of these tools.

agent.loop

Field	Type	Required	Description
maxSteps	integer	no	Maximum number of tool-call steps. Use 1 or 2 for a runtime that calls one tool and stops.
timeoutMs	integer	no	Time limit of the runtime in ms. The time a streamed model call spends writing does not count. Defaults to 120000; 240000 with io.visibility: story.
callTimeoutMs	integer	no	Time limit of one model call that is not streamed, in ms. Defaults to 60000; 120000 with io.visibility: story.
firstTokenTimeoutMs	integer	no	Time limit for the first streamed token in ms, the same for every attempt. Without it an attempt waits at most 120000, and no longer than leaves room in timeoutMs for the retries still allowed.
idleTimeoutMs	integer	no	Longest silence of a streamed model call that has started to write, in ms. A model that keeps writing is not cut off. Defaults to 120000.
maxRetries	integer	no	Retries on a transient model failure; 0 disables retry. Defaults to 3; 1 with io.visibility: story.
loopDetection	integer	no	Number of repeated tool calls that counts as a loop. Defaults to 3; 0 disables detection.
maxRecursionDepth	integer	no	Maximum depth of nested ctx.recursiveCall(). Defaults to 10.
profile	"story" or "actor" or "system"	no	Loop profile the other loop behaviour keys override. story streams to the player, reads interjections and keeps a cut reply; actor and system do neither, and actor answers without tools where system fails. Defaults to story with io.visibility: story, otherwise system.
stream	boolean	no	Show the model's text to the player as it streams. Needs io.visibility: story. Defaults to the profile's value: true for story.
steering	boolean	no	Merge the player's interjections into the transcript before each step and after a prose finish. Needs io.visibility: story. Defaults to the profile's value: true for story.
truncation	"accept" or "reject"	no	accept keeps a reply cut at the output limit; reject fails it. accept needs streaming. Defaults to accept for story, otherwise reject.
fallback	"answer-without-tools" or "fail"	no	What a repeated tool loop does: answer-without-tools takes the tools away and asks for the answer; fail stops the runtime. Defaults to fail for system, otherwise answer-without-tools.
corrections	object	no	Independent correction budgets for one agent loop run; 0 disables that correction.
finalizer	object	no	The final answer step, with tools off.

agent.loop.corrections

Field	Type	Required	Description
toolUse	integer	no	Corrections for missing required tool use or explicit completion. Defaults to 1.
review	integer	no	Corrections after a PostLLMResponse rejection. Defaults to 2.
loopPerturbation	integer	no	Perturbations before the repeated-tool fallback. Defaults to 1.
outputRepair	integer	no	Requests with tools off to repair invalid output. Defaults to 1.

agent.loop.finalizer

Field	Type	Required	Description
maxSteps	boolean	no	At the step limit or when the request no longer fits the model's context, ask once for the answer with tools off. false makes these stops always fail. Defaults to true.
deadlineReserveMs	integer	no	Stop starting steps this many ms before the time limit and ask for the answer with tools off, when prose can complete the runtime. At most half of timeoutMs is used; smaller than timeoutMs. Defaults to 0, off.

function

Field	Type	Required	Description
handler	string	no	Path of the handler module, relative to this manifest. The module default-exports the handler function. Defaults to ./handler.js next to the manifest when that file exists.
model	string	no	Model slot the handler's gateway calls route through. Declared so a detached job's credential readiness check judges the same slot the call resolves. Example: "memory".
timeoutMs	integer	no	Time limit of the handler in ms.
tools	object	no	Tools the handler may call through ctx.tools.call.

function.tools

Field	Type	Required	Description
builtin	list of string	no	Names of builtin tools the runtime may call.
plugin	list of string	no	Names of this package's own tools the runtime may call. Each must be listed in contributes.tools. The runtime of a single-runtime package gets every contributed tool when this is omitted.
defer	true or list of string	no	Deferred tool loading. true defers the whole whitelist; a list defers only those names.

effects

Field	Type	Required	Description
reads	list of "state:*" or "narrative:*" or "characters:*" or "assets:*" or "media:*" or "lorebook:*" or "ui:*" or "interaction:*" or "unknown:*" or string	no	Resources the runtime reads, such as narrative:* or plugin-data:self:<namespace>. Entries must be unique.
writes	list of "state:*" or "narrative:*" or "characters:*" or "assets:*" or "media:*" or "lorebook:*" or "ui:*" or "interaction:*" or "unknown:*" or string	no	Resources the runtime writes, such as state:* or event:<topic>. Entries must be unique.
parallelSafe	boolean	no	true states that the runtime is safe to run in parallel with its stage siblings.

permissions

Field	Type	Required	Description
http	list of object	no	Upper bound of the HTTP origins and methods the runtime may use.

permissions.http[]

Field	Type	Required	Description
origin	string	yes	HTTPS origin the runtime may call, without path, query or credentials. Example: "https://api.example.com".
methods	list of "GET" or "POST" or "PUT" or "PATCH" or "DELETE" or "HEAD"	no	HTTP methods allowed for the origin. Entries must be unique.