| name | notification-manual-channel-model |
| description | Nested notification-manual reference for LingTai's notification filesystem channel protocol, allowlist, payload envelopes and instructions, nudge routing, kernel sync, voluntary check behavior, and canonical producer state versus notification mirrors. Read after notification-manual when interpreting, producing, or debugging notification payloads; skip for dismissal policy.
|
| version | 0.1.0 |
| tags | ["lingtai","notifications","channels","protocol","sync","nudge"] |
| last_changed_at | 2026-07-19T00:00:00Z |
| related_files | ["src/lingtai/intrinsic_skills/notification-manual/SKILL.md","src/lingtai/tools/notification/schema.py","src/lingtai/kernel/notification_store/__init__.py"] |
| maintenance | Tracks the notification channel-model/protocol topic it documents; update when that integration changes.
|
Notification Channel Model
Files and allowlist
A channel is the filename stem in .notification/<channel>.json:
.notification/email.json becomes _meta.agent_meta.notifications.attention.email;.notification/system.json becomes _meta.agent_meta.notifications.attention.system;.notification/mcp.telegram.json becomes
_meta.agent_meta.notifications.attention["mcp.telegram"];.notification/goal.json becomes _meta.agent_meta.notifications.attention.goal.
The kernel accepts built-in channels including email, system, soul,
nudge, post-molt, tool_loop_guard, bash, btw, cron, molt, and
goal; MCP bridge channels use the mcp. prefix. Unknown JSON filenames are
ignored by collection, and kernel publish/dismiss helpers reject names outside
the allowlist. This prevents arbitrary workdir files from entering the
model-visible notification lane.
nudge is the formal channel for mechanical, throttled checks. Runtime update
checks publish data.nudges[] entries with kind: kernel_version; the sole
normal install/update route is https://lingtai.ai/install.sh. Let Shell execute
its concise --help, then update --help, without reading or pasting the script
source. The installer owns exact-tag migration navigation; real update, mutation,
configuration writes, and refresh require explicit human/config-owner authority.
The bundled runtime-update-checks reference is limited to local read-only
diagnosis and refresh mechanics. Source-freshness checks may publish
kind: source_drift, but that handling stays local and never enters
release-migration routing. This manual owns only the generic channel protocol.
Envelope and producer instructions
Producer helpers write the current channel surface as a standard envelope:
{
"header": "1 system notification",
"icon": "🔔",
"priority": "normal",
"published_at": "2026-06-10T00:00:00Z",
"instructions": "Optional agent-facing handling guidance.",
"data": {"events": []}
}
instructions is an optional field inside one channel payload, not a channel
name. It tells the agent how that producer expects the event to be handled or
cleared. Producers own that directive because only they know whether the file is
a disposable output, a mirror over canonical state, a coalesced event summary,
or protected source of truth.
External producers that can write the workdir may publish the same envelope to
an allowlisted mcp.<server>.json path. They must use atomic sibling-temp
replacement so readers never observe a partial JSON file.
Voluntary check and model-visible delivery
notification(action='check') returns a dict placeholder. The turn-loop
post-hook stamps the canonical live payload onto that same result under
_meta.agent_meta.notifications.attention and
_meta.agent_meta.guidance.transient. The handler does not
assemble a second bare channel representation and does not write notification
state.
When notifications arrive while an agent is IDLE or ASLEEP, the kernel can
synthesize the same notification(action='check') tool-call/result shape and
wake the agent. During ACTIVE work, the post-hook moves the single live payload
to a suitable dict-shaped tool result only when required by first appearance,
material change, or a deliberate check. Delivery fingerprints and the live
holder belong to kernel synchronization, not to the notification tool's
manual action.
After handling the payload, clear it through the producer-specific action or the
narrowest safe notification dismiss action and end the turn. Do not call check
again only to confirm dismissal; sparse synchronization will expose a material
change when needed.
Canonical producer state versus mirror
A generic channel clear changes only the .notification/<channel>.json surface.
It does not mark an email read, change a goal, consume an MCP source queue, or
mutate any other producer-owned state. A producer whose notification is a mirror
over canonical state must register a generic-dismiss guard and teach the
producer-specific verb in instructions.
This separation is deliberate: the filesystem protocol gives the kernel one
current high-attention surface, while canonical state remains under the
producer's own schema and lifecycle. Read ../dismissal-safety/SKILL.md before
clearing guarded, stale, protected, or event-granular state.
Footprint
The protocol footprint is .notification/<channel>.json plus kernel-owned
notification metadata such as legacy acknowledgement state. Inspect it read-only
before diagnosing a producer. Never delete the directory or bulk-remove files —
that bypasses the guards and stale checks that only the producer verb or an
atomic notification action honor.
