| name | notification-manual |
| description | Notification filesystem and standalone notification tool router for LingTai. Read this when using notification(action='manual'|'check'|'dismiss_channel'| 'dismiss_event'|'dismiss_ref'), interpreting `.notification/<channel>.json`, or deciding between producer-specific handling and safe mirror dismissal. Routes channel/sync mechanics and dismissal safety into nested references; large-result compaction remains owned by summarize-manual.
|
| version | 0.4.0 |
| tags | ["lingtai","notifications","channels","dismiss","manual","force","stale","nudge"] |
| last_changed_at | 2026-07-19T00:00:00Z |
| related_files | ["src/lingtai/tools/notification/__init__.py","src/lingtai/tools/notification/schema.py","src/lingtai/intrinsic_skills/notification-manual/reference/channel-model/SKILL.md","src/lingtai/intrinsic_skills/notification-manual/reference/dismissal-safety/SKILL.md"] |
| maintenance | Tracks the routed source/resources it summarizes; update when the underlying capability or its sub-references change.
|
Notification Manual — Router
LingTai notifications are a filesystem protocol: producers publish allowlisted
.notification/<channel>.json surfaces, and the kernel exposes their current
model-visible state. The always-available notification tool is the sole
agent-callable home for reading and clearing those surfaces. system has no
notification or dismiss alias; it still owns summarize because context hygiene
is not a notification operation.
Quick start
| Action | Use |
|---|
notification(action='manual') | Return this installed router body. Strictly read-only: it neither reads nor changes notification state. |
notification(action='check') | Request the live notification payload. The handler returns a placeholder and the kernel stamps _meta.agent_meta.notifications.attention plus _meta.agent_meta.guidance.transient onto the result. |
notification(action='dismiss_channel', channel=...) | Clear one dismissible channel mirror whole. |
notification(action='dismiss_event', event_id=..., channel='system') | Remove one matching system event; channel defaults to system. |
notification(action='dismiss_ref', ref_id=..., channel='system') | Remove matching system events by producer reference; channel defaults to system. |
There is no aggregate dismiss action. After handling a notification, use the
narrowest correct producer-specific or atomic dismiss action and end the turn;
do not voluntarily call check again merely to confirm the clear.
Installed manual retrieval
notification(action='manual') reads only:
<agent>/.library/intrinsic/capabilities/notification-manual/SKILL.md
Success returns exactly status, notification_manual, and manual_path. A
missing installed file returns status: degraded, an empty
notification_manual, the same fixed manual_path, and an actionable error
naming an initializer or capability-install problem. It never falls back to a
source checkout and never touches .notification/, the Notification Store,
producer state, delivery fingerprints, or acknowledgement state.
Nested reference catalog
- name: notification-manual-channel-model
location: reference/channel-model/SKILL.md
description: |
Nested notification-manual reference for the filesystem channel protocol,
allowlist, envelopes and instructions, nudge routing, kernel sync, voluntary
check behavior, and producer canonical-state versus mirror boundaries. Read
this when interpreting or producing notification payloads.
- name: notification-manual-dismissal-safety
location: reference/dismissal-safety/SKILL.md
description: |
Nested notification-manual reference for atomic dismissal, producer-specific
verbs, stale-version and force rules, protected channels, post-molt
acknowledgement, and legacy large_tool_result reminder escape hatches. Read
this before clearing notification state or diagnosing a refusal.
Routing table
| Need / keywords | Read |
|---|
Channel names; .notification/*.json; allowlist; mcp. channels; envelope fields; instructions; nudge/update checks; _meta.agent_meta.notifications.attention; voluntary check; producer state versus mirror | reference/channel-model/SKILL.md |
Which dismiss action; producer-specific handling; guarded/stale mirror; force; protected goal; post-molt reason; legacy large_tool_result event | reference/dismissal-safety/SKILL.md |
Tool-result ranking, digest quality, system(action='summarize'), recovery by tool_call_id, summarize versus molt | ../system-manual/reference/summarize-manual/SKILL.md |
| Active goal source-of-truth and cancellation/completion | ../system-manual/reference/goal-manual/SKILL.md |
| Runtime/kernel update nudges | ../system-manual/reference/runtime-update-checks/SKILL.md |
Safety boundaries to keep resident
check is the notification-state read; manual is documentation retrieval
only. Neither writes notification state.- Generic dismiss clears a notification mirror, never producer-owned canonical
state. Prefer the producer's own verb when one exists.
force=true is for knowingly clearing a stale or guarded mirror. It does not
override protected source-of-truth channels and never mutates producer state.- Large tool results are ranked under
_meta.agent_meta.agent_state.current_tool_result_chars, not emitted as new
notifications. Follow ../system-manual/reference/summarize-manual/SKILL.md;
do not invent a second summarization procedure here.
Why the boundary is split this way
The filesystem protocol lets in-process and external producers publish one
current surface without sharing a queue; atomic action names make the clearing
target explicit; producer guards keep a mirror clear from being mistaken for
handling source-of-truth state.
