Plugin 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 a package's root PLUGIN.md.

JSON Schema: plugin-manifest.schema.json.

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

Top-level fields

Field	Type	Required	Description
id	string	no	Package ID: lowercase letters, digits and hyphens. Defaults to the name of the package directory; when written it must equal that name. framework is reserved. Example: "dice-check".
kind	"core" or "plugin"	no	Package kind. core marks a core plugin, which every session requests by default. Defaults to plugin. Default: "plugin".
version	string	no	Package version. Setup runtimes rerun for existing sessions when it changes. A package without a version counts as 0.0.0.
covel	string	no	Host version range this package supports. A host outside it does not install or load the package. Example: ">=0.0.45".
displayName	text	no	Player-facing name. Plain string; translations go in locale files.
description	text	yes	What the package does. Plain string; translations go in locale files.
tags	list of string	no	Catalogue tags the loader cannot work out, such as mode:dialogue or data:characters. The loader adds the ui:* and cost:* tags from the package's panels and runtimes and ignores written ones. role: tags are rejected; use contracts.
author	object	no	Who made the package. Shown on the package's cards before play, never during play.
license	string	no	License of the package: an SPDX identifier or a short name. Example: "MIT", "CC-BY-4.0".
homepage	string	no	Page of the package itself, such as its repository or documentation. https only. Example: "https://example.com/my-package".
provides	list of string or object	no	Versioned contracts this package provides that no runtime of it outputs, such as an extension or data contract. The contract of each runtime's io.output.contract is added by the loader; write it here only to mark the default provider.
requires	list of string	no	Contracts that must have an active provider. The resolver adds one when the package is active. A contract a runtime reads and that is not listed here is optional: the runtime uses it when a provider is active.
conflicts	list of string	no	Contracts whose other providers cannot be active together with this package. Plugin contracts only.
contracts	map of object	no	Public schema of each contract this package publishes or accepts, keyed by contract ID. A contract that a contributes.data namespace accepts needs no entry here: its schema is the one of that namespace.
entry	string	no	Package-relative path of the server entry module. It registers tools, actions, services, hooks and extensions. Defaults to ./server/index.js when that file exists.
permissions	object	no	Upper bounds of the package's own code. http lists the origins and methods the entry module of a community package may reach through covel.http, in addition to those its runtimes declare.
contributes	object	no	Package-level contributions. Every entry registration needs a declaration here, and every declaration needs an implementation.
runtime	object	no	The single inline runtime of this package; its prompt is the body of this file. Packages with several runtimes use runtimes/<id>/RUNTIME.md instead.

author

Field	Type	Required	Description
name	string	yes	Name of the person or team. Shown as written in every language. Example: "Jane Doe".
url	string	no	The author's own page. https only. Example: "https://example.com".
about	text	no	A short message from the author to players: who they are, what else they make, how to support them. Plain text.
links	list of object	no	Links the author wants players to see, such as a community, a support page or other work. At most 6.

author.links[]

Field	Type	Required	Description
label	text	yes	Text of the link. Example: "Discord".
url	string	yes	Address of the link. https only. The player sees the full address and confirms before it opens. Example: "https://example.com/community".

provides[]

Field	Type	Required	Description
contract	string	yes	Contract ID this package provides.
default	boolean	no	true marks the default provider. It steps aside when another provider of the contract is selected.

contracts.*

Field	Type	Required	Description
schema	string	yes	Package-relative path of the contract's JSON Schema.

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.

contributes

Field	Type	Required	Description
tools	list of string	no	Names of tools the entry registers with registerTool.
actions	list of string	no	Names of RPC actions the entry registers with registerRpc.
commands	list of object	no	Player slash commands. Each action must be listed in actions.
actionKinds	list of object	no	Action kinds players may submit besides the base kinds. Pure declaration: the server checks each action against its roles, text rule and fields schema. The wire kind is <pluginId>/<name>.
services	list of string or object	no	Services the entry registers with registerService: a contract ID, or { contract, access, modelFacing } for one that changes its plugin's data (access: write) or that agents may import as a tool (modelFacing: true).
extensions	list of string or object	no	Extensions the entry provides with provideExtension: <point>/<id>, or an object for one that sets more, such as a UI slot provider.
hooks	list of "SessionStart" or "TurnStart" or "PreCompaction" or "PostCompaction" or "PreSchedule" or "PreRuntime" or "PostContextAssembly" or "PreStep" or "PreLLMCall" or "PostLLMResponse" or "PostRuntime" or "PreToolUse" or "PostToolUse" or "PreStateCommit" or "PostStateCommit" or "TurnStop" or "SessionEnd" or object	no	Lifecycle hooks the entry registers: an event name, or { event, enforce } for a phase other than normal.
wires	list of string	no	IDs of provider wires the entry registers.
forms	list of string	no	IDs of forms the entry registers.
events	list of object	no	Domain events the package's runtimes may emit with the builtin emit-event tool.
settings	list of object	no	Player-configurable settings. A world can preset them with pluginSettings.
datasets	map of object	no	Typed plugin-data datasets the package owns; the name is the plugin-data namespace.
data	map of object	no	Own plugin data namespaces, keyed by namespace.
ui	object	no	Package-relative paths of declarative UI specs, by placement.
worldProjections	map of object	no	Pure projections from world data into own namespaces, keyed by projection ID.
prompt	list of object	no	Static prompt segments. The host registers them.

contributes.commands[]

Field	Type	Required	Description
name	string	yes	Command name in lowercase kebab-case, without the leading slash.
aliases	list of string	no	Other names that invoke the same command.
description	text	yes	What the command does. Shown to the player.
arguments	list of object	no	Positional arguments, in order. Names must be unique.
action	string	yes	RPC action the command invokes. It must be listed in contributes.actions.
context	list of "session" or "active-runtimes" or "models"	no	Host context scopes passed to the action.

contributes.commands[].arguments[]

Field	Type	Required	Description
name	string	yes	Argument name in lowercase kebab-case.
type	"string" or "integer" or "number" or "boolean"	no	Value type of the argument. Defaults to string.
description	text	no	What the argument means. Shown to the player.
required	boolean	no	true when the player must supply the argument.
variadic	boolean	no	true collects all remaining words. Only the last argument can be variadic.
choices	list of string	no	Allowed values of the argument.

contributes.actionKinds[]

Field	Type	Required	Description
name	string	yes	Kind name, unique in the package and not a base kind. The wire kind is <pluginId>/<name>.
roles	list of "player" or "host" or "spectator"	no	Seat roles that may submit this kind. Defaults to [player].
text	"required" or "optional" or "none"	no	Whether the action carries text: required, optional (default) or none.
actor	boolean	no	Whether the action is taken as a character. Defaults to true: the seat's current character unless the action names another bound one.
schema	string	no	Package-relative path of the JSON Schema the action's fields must match. Without it the kind takes no fields.
display	object	yes	How the composer shows the kind.

contributes.actionKinds[].display

Field	Type	Required	Description
label	text	yes	Name of the kind, for the composer and for the model-facing rendering of the action.
icon	string	no	Icon name for the composer.
placeholder	text	no	Placeholder text for the composer.

contributes.services[]

Field	Type	Required	Description
contract	string	yes	The contract ID the service is registered under.
access	"read" or "write"	no	write lets the service change its own plugin's data for the caller: its writes commit with the caller's work. read (the default) only reads. The registration must say the same.
modelFacing	boolean	no	true lets agents import the service as a tool with agent.tools.services. The registration must say the same and give a description and an input that exports JSON Schema.

contributes.extensions[]

Field	Type	Required	Description
point	string	yes	Extension point this entry provides. Example: "prompt.segment@1".
id	string	yes	ID of this extension within the package.
order	integer	no	Sort order among providers of the same point. Lower values come first. Defaults to 0.
slot	string	no	UI slot providers only: the kernel UI slot this entry fills.
watch	list of string	no	UI slot providers only: own data namespaces whose changes refresh the slot.
preview	list of string	no	UI slot providers only: event topics whose in-turn preview refreshes the slot.

contributes.hooks[]

Field	Type	Required	Description
event	"SessionStart" or "TurnStart" or "PreCompaction" or "PostCompaction" or "PreSchedule" or "PreRuntime" or "PostContextAssembly" or "PreStep" or "PreLLMCall" or "PostLLMResponse" or "PostRuntime" or "PreToolUse" or "PostToolUse" or "PreStateCommit" or "PostStateCommit" or "TurnStop" or "SessionEnd"	yes	Lifecycle event the hook handles.
enforce	"pre" or "normal" or "post"	no	Phase the hook runs in. Defaults to normal.

contributes.events[]

Field	Type	Required	Description
topic	string	yes	Event topic in dot-separated kebab-case. Example: "scene.set".
schema	string	yes	Package-relative path of the JSON Schema that validates the event payload.
description	text	yes	What the event means. Given to runtimes that may emit it.
advertise	boolean	no	true advertises the event to runtimes that emit events. Defaults to true. Default: true.

contributes.settings[]

Field	Type	Required	Description
key	string	yes	Setting key. Runtimes read it from ctx.userSettings.
type	"text" or "textarea" or "number" or "integer" or "toggle" or "select" or "slider" or "slot"	yes	Control type. select needs options; slot lets the player pick a model slot.
default	any	no	Value used when neither the player nor the world sets one.
label	text	yes	Label shown in the settings panel.
description	text	no	Help text shown with the control.
min	number	no	Minimum for numeric controls.
max	number	no	Maximum for numeric controls.
step	number	no	Step for numeric controls.
options	list of object	no	Choices of a select control.

contributes.settings[].options[]

Field	Type	Required	Description
value	string	yes	Stored value of the option.
label	text	yes	Label shown for the option.

contributes.datasets.*

Field	Type	Required	Description
schema	string	yes	Package-relative JSON Schema that every record of the dataset must satisfy.
key	string	no	Top-level record field whose string value is the record's key. Omit when callers choose keys.
ops	list of "set" or "merge" or "inc" or "append" or "insert" or "remove" or "upsertItem" or "delete"	no	Operation kinds allowed on this dataset. Defaults to every kind.
tools	list of "get" or "list" or "upsert" or "update"	no	Dataset tools an agent may select with agent.tools.datasets. Defaults to get and list, upsert when ops allow set, and update when ops allow any other operation.
description	string	no	What the dataset holds, in English. Agents read it in the description of each dataset tool.

contributes.data.*

Field	Type	Required	Description
schema	string	yes	Package-relative path of the JSON Schema that validates each record.
description	string	no	What the namespace stores. Read by world authors and tools.
version	integer	no	Schema version of the namespace. Defaults to 1; raise it when the record shape changes. Default: 1.
accepts	list of string	no	Data contracts whose world data this namespace accepts.
authoring	object	no	What a world author needs to supply this content. Authoring tools and the world generator read it.
search	object	no	Makes the records of this namespace part of memory search (memory-search) while the plugin is active in the session.

contributes.data.*.authoring

Field	Type	Required	Description
title	text	yes	Author-facing name of this content. Plain string; translations go in locale files. Example: "Starting quests".
summary	text	no	One player-facing sentence about this content. Shown where a player chooses what a generated world includes. Plain string; translations go in locale files.
hint	string	no	How to write good records: what to include, limits, and links to other content. Read by authors and by generators.
example	string	no	Package-relative path of a JSON file with a valid example of the source value. It is validated against the namespace schema.
source	object	no	The world data source an author declares to supply this content.
characterField	string	no	The content is written inside the world's character records instead of a file of its own: each character may carry one record under this field. The character's id keys the record, and the character's name, type, description and fields are not repeated in it. Not together with source. Example: "blueprint".
references	list of object	no	Values in each record that name something of the world. pnpm validate:world reports a value that names nothing, or the wrong kind of thing, before a session starts.
generate	"offer" or "default"	no	Lets the in-app world generator produce this content from hint and example alone. offer lists it as a choice; default also selects it. It needs an example, and a characterField or a public, non-media source keyed by id.

contributes.data.*.authoring.source

Field	Type	Required	Description
path	string	yes	Conventional path of the source inside a world package. The path sets how it is read: a .yaml or .yml file, a .json file, or a media directory (a path without an extension) whose index this namespace receives. <dir>/*.<ext> names every such file of a directory, each one a source, read in file-name order. It may not name a path the kernel or the package itself owns: world.yaml, WORLD.md, data/world.data.yaml, data/dimensions.yaml, data/lorebook.yaml, characters/characters.json, media/gallery.json, media/portraits.json, media/scenes.json or media/gallery/, nor an edition of one. Example: "data/quests.yaml", "data/rules/*.yaml".
key	string	no	Field that gives each record a stable key. Defaults to id, and to filename for a media directory.
localeArrayKeys	list of string	no	Additional stable identity fields for nested object lists in locale overlays, after the source key and id. Translations retain these keys when lists are reordered.
visibility	"public" or "hidden"	no	hidden for content the player must not see before the plugin reveals it. Defaults to public.
lorebook	boolean	no	true also projects each record into the lorebook (+lorebook).

contributes.data.*.authoring.references[]

Field	Type	Required	Description
path	string	yes	Where the referring values are in each record: field names joined by ., with [] after a field that holds a list. **. before a field name finds that field at any depth below. Example: "attributes[].id", "when.**.dimension".
to	"character-attribute" or "world-dimension"	yes	What each value must name. character-attribute is the id of a top-level attribute of the world's characterSchema; world-dimension is the ID of a dimension the world declares.
type	"string" or "number" or "boolean" or "enum" or "array" or "object" or "map"	no	Value type the named attribute must have. Only with to: character-attribute.
within	list of string	no	Fields beside the referring value that must lie inside what it names. For character-attribute, number fields inside the attribute's min and max; for world-dimension, a path into the dimension's value (a.b, or a list of keys) that its schema allows.
values	list of string	no	Sibling paths holding candidate values of a world dimension. Uses the same path syntax as path; in[] checks each list member, while equals checks the whole value. Checked against the schema at the single within path, or the root when absent. Only with to: world-dimension; at most one within field when set.

contributes.data.*.search

Field	Type	Required	Description
text	string	yes	Field of a record's value that holds the text to search. A record without a string there is not searched.

contributes.ui

Field	Type	Required	Description
view	list of string	no	Paths of UI specs for full-column views the player can switch to.
right	list of string	no	Paths of UI specs for right-panel tabs.
message	list of string	no	Paths of UI specs rendered inside the message stream.
segment	list of string	no	Paths of display-only templates for committed story paragraphs, matched by segment kind or speaker.

contributes.worldProjections.*

Field	Type	Required	Description
from	string	yes	Schema URI of the world data source to project. Only sources with exactly this schema are projected.
handler	string	yes	Package-relative path of the pure projection handler module.
outputs	map of object	yes	Destinations keyed by output ID. At least one is required.

contributes.worldProjections.*.outputs.*

Field	Type	Required	Description
namespace	string	yes	Own data namespace that receives the projected records.
key	string	yes	Field of each projected record used as its stable key.

contributes.prompt[]

Field	Type	Required	Description
id	string	yes	ID of the segment within the package.
content	string	yes	Text of the segment.
position	"system" or "pre-history" or "post-history" or object	yes	Where the segment goes: system, pre-history, post-history, or { depth } for a position relative to the message history.
role	"system" or "user" or "assistant"	no	Message role of the segment. Defaults to system.

contributes.prompt[].position

Field	Type	Required	Description
depth	integer	yes	Message depth at which the segment is inserted.

runtime

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.

runtime.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.

runtime.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.

runtime.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.

runtime.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.

runtime.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.

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.

runtime.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.

runtime.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.

runtime.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.

runtime.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.

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.

runtime.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.

runtime.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.

runtime.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.

runtime.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.

runtime.agent.toolChoice

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

runtime.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.

runtime.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.

runtime.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).

runtime.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.

runtime.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.

runtime.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.

runtime.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.

runtime.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.

runtime.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.

runtime.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.

runtime.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.

runtime.permissions

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

runtime.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.