notices

Post an event record that surfaces to the callers it is addressed to on the response of the tool call that posted it, or on their next tool call.

require("@builtin::modules.api.engine.notices") -- notices (also available as global 'notices')

The notices namespace: 10 functions.

globals/notices/post

notices.post(template: string, params: { [string]: any }?, opts: NoticeOpts?)

Post a notice. template is a fixed sentence used to collapse repeats; put varying values in params. A param holding a picture — an image value from mcp.image or a capture tool — is delivered as a picture beside the notice's line rather than as text. opts.severity defaults to "info"; opts.includeLocation attaches the emitting call site. opts.actionable says whether the callers a notice is addressed to are expected to act on it, rather than take it in as background; an agent's event receiver starts an idle agent's turn for an actionable notice and hands the rest to its context.

Parameters

• template string — Fixed sentence identifying the notice.
• params { [string]: any } (optional) — Optional table of named values rendered alongside the template; a picture in it arrives as a picture.
• opts NoticeOpts (optional) — Optional table: severity ("info" | "warn" | "error"), includeLocation (boolean), audience ("" | { string }?). Who sees the notice: "" addresses every caller; a list addresses those callers only, each entry an agent's name (as the agent toolbox's roster lists it) or a caller key <kind>:<id> such as "agent:". Defaults to the caller whose code is running, or every caller when none is. A notice reaches the agents on this engine: an entry naming no agent on this world's roster, an entry naming an agent the roster lists on another engine of the world, or an empty list, raises an error. actionable (boolean) states whether the callers it is addressed to are expected to act on it; omitted, a notice addressed to particular callers (the default audience included) is actionable, and one for every caller is background.

notices.post("wave complete", { wave = 3 })
notices.post("save slot corrupted, using defaults", { slot = id }, { severity = "warn" })
notices.post("bake finished", { shot = mcp.image("/source/tmp/bake.png") })
notices.post("boss defeated", nil, { audience = "*" })
notices.post("build ready for review", nil, { audience = { "terrain" }, actionable = true })

globals/notices/withdraw

notices.withdraw(template: string) -> number

Withdraw the notices this code posted under template that are still stored, whoever they are addressed to, because what they state has stopped being true: a caller that has not read one yet would be told something that no longer holds. A notice is keyed by its template and by the code that posted it, so a call reaches only notices posted from the same place. A later notices.post under the template queues again.

Parameters

• template string — The template the notices were posted under.

Returns number — How many emissions the withdrawn notices held.

notices.withdraw("save slot corrupted, using defaults")

modules/notices/post

post(template: string, params: { [string]: any }?, opts: NoticeOpts?)

Post a notice. template is a fixed sentence used to collapse repeats; put varying values in params. A param holding a picture — an image value from mcp.image or a capture tool — is delivered as a picture beside the notice's line rather than as text. opts.severity defaults to "info"; opts.includeLocation attaches the emitting call site. opts.actionable says whether the callers a notice is addressed to are expected to act on it, rather than take it in as background; an agent's event receiver starts an idle agent's turn for an actionable notice and hands the rest to its context.

Parameters

• template string — Fixed sentence identifying the notice.
• params { [string]: any }? (optional) — Optional table of named values rendered alongside the template; a picture in it arrives as a picture.
• opts NoticeOpts? (optional) — Optional table: severity ("info" | "warn" | "error"), includeLocation (boolean), audience ("" | { string }?). Who sees the notice: "" addresses every caller; a list addresses those callers only, each entry an agent's name (as the agent toolbox's roster lists it) or a caller key <kind>:<id> such as "agent:". Defaults to the caller whose code is running, or every caller when none is. A notice reaches the agents on this engine: an entry naming no agent on this world's roster, an entry naming an agent the roster lists on another engine of the world, or an empty list, raises an error. actionable (boolean) states whether the callers it is addressed to are expected to act on it; omitted, a notice addressed to particular callers (the default audience included) is actionable, and one for every caller is background.

notices.post("wave complete", { wave = 3 })
notices.post("save slot corrupted, using defaults", { slot = id }, { severity = "warn" })
notices.post("bake finished", { shot = mcp.image("/source/tmp/bake.png") })
notices.post("boss defeated", nil, { audience = "*" })
notices.post("build ready for review", nil, { audience = { "terrain" }, actionable = true })

modules/notices/withdraw

withdraw(template: string): number

Withdraw the notices this code posted under template that are still stored, whoever they are addressed to, because what they state has stopped being true: a caller that has not read one yet would be told something that no longer holds. A notice is keyed by its template and by the code that posted it, so a call reaches only notices posted from the same place. A later notices.post under the template queues again.

Parameters

• template string — The template the notices were posted under.

notices.withdraw("save slot corrupted, using defaults")

tools/notices/drain

notices.drain() -> Drained?

Return your unread notices as the formatted delivery block — the same text that would otherwise be attached to your next tool result. What this returns is marked read for you, so read it; nothing is removed for other callers, and keys you muted with suppress are passed over. Returns nil when you have nothing unread. For a caller that pulls its own context; if you read notices off your tool results, you do not need this. Overflow content is written to /source/tmp/notices/ and named in the block. Pictures the notices carry come back in noticeImages, in the order the block names them, and reach the caller as pictures.

Returns Drained?

tools/notices/list

notices.list() -> NoticesList

Show the notices addressed to you and the keys you muted. pending holds the stored notices your audience admits, read or unread, less the keys you muted; a notice stays stored until every caller it names has read it, or it ages out. Each pending row carries its id (one key can hold several rows), key, template, severity, origin, count, source, params (each key with the distinct values it took), location, and when it first and last fired. A warning or error raised again with the params of one already delivered is a repeat: earlier counts the emissions delivered before it, and heldUntilMs names when a held repeat is delivered, carrying every repeat raised meanwhile. suppressed holds your own muted keys, each with the number of times it fired at you while muted. Marks nothing read. Use a key from here with suppress.

Returns NoticesList

tools/notices/suppress

notices.suppress(key: string) -> { suppressed: string }

Mute a notice key you have acknowledged, for you alone. It keeps counting (visible in your list) but never renders on your tool calls or your drain again this session; every other caller keeps receiving it. Available to the operating agent; a loaded world component cannot mute its own notices.

Parameters

• key string

Returns { suppressed: string }

"user:atlas:texture rebuilt"

tools/notices/unsuppress

notices.unsuppress(key: string) -> { unsuppressed: string }

Un-mute a notice key you suppressed, so it renders on your tool calls again. Reverses your own suppress only. Available to the operating agent.

Parameters

• key string

Returns { unsuppressed: string }

"user:atlas:texture rebuilt"

typed/builtin//modules/api/engine/notices/notices/post

notices.post(template: string, params: { [string]: any }?, opts: NoticeOpts?)

Post a notice. template is a fixed sentence used to collapse repeats; put varying values in params. A param holding a picture — an image value from mcp.image or a capture tool — is delivered as a picture beside the notice's line rather than as text. opts.severity defaults to "info"; opts.includeLocation attaches the emitting call site. opts.actionable says whether the callers a notice is addressed to are expected to act on it, rather than take it in as background; an agent's event receiver starts an idle agent's turn for an actionable notice and hands the rest to its context.

Parameters

• template string — Fixed sentence identifying the notice.
• params { [string]: any } (optional) — Optional table of named values rendered alongside the template; a picture in it arrives as a picture.
• opts NoticeOpts (optional) — Optional table: severity ("info" | "warn" | "error"), includeLocation (boolean), audience ("" | { string }?). Who sees the notice: "" addresses every caller; a list addresses those callers only, each entry an agent's name (as the agent toolbox's roster lists it) or a caller key <kind>:<id> such as "agent:". Defaults to the caller whose code is running, or every caller when none is. A notice reaches the agents on this engine: an entry naming no agent on this world's roster, an entry naming an agent the roster lists on another engine of the world, or an empty list, raises an error. actionable (boolean) states whether the callers it is addressed to are expected to act on it; omitted, a notice addressed to particular callers (the default audience included) is actionable, and one for every caller is background.

notices.post("wave complete", { wave = 3 })
notices.post("save slot corrupted, using defaults", { slot = id }, { severity = "warn" })
notices.post("bake finished", { shot = mcp.image("/source/tmp/bake.png") })
notices.post("boss defeated", nil, { audience = "*" })
notices.post("build ready for review", nil, { audience = { "terrain" }, actionable = true })

typed/builtin//modules/api/engine/notices/notices/withdraw

notices.withdraw(template: string) -> number

Withdraw the notices this code posted under template that are still stored, whoever they are addressed to, because what they state has stopped being true: a caller that has not read one yet would be told something that no longer holds. A notice is keyed by its template and by the code that posted it, so a call reaches only notices posted from the same place. A later notices.post under the template queues again.

Parameters

• template string — The template the notices were posted under.

Returns number — How many emissions the withdrawn notices held.

notices.withdraw("save slot corrupted, using defaults")