@aitne-sh/aitne 0.1.9 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (218) hide show
  1. package/README.md +41 -11
  2. package/agent-assets/agent-profiles/background-task.md +53 -0
  3. package/agent-assets/agent-profiles/conversational.md +1 -0
  4. package/agent-assets/agent-profiles/routine-fetch-window.md +14 -75
  5. package/agent-assets/agent-profiles/routine.md +1 -1
  6. package/agent-assets/agents/{hourly-check → activity-scan}/agent.md +22 -17
  7. package/agent-assets/agents/monthly-review/agent.md +6 -5
  8. package/agent-assets/docs/concepts/agent-day.md +6 -7
  9. package/agent-assets/docs/concepts/auth-health.md +23 -20
  10. package/agent-assets/docs/concepts/backends-and-tiers.md +13 -9
  11. package/agent-assets/docs/concepts/costs-and-quotas.md +14 -12
  12. package/agent-assets/docs/concepts/delegated-mode.md +18 -17
  13. package/agent-assets/docs/concepts/memory-model.md +16 -9
  14. package/agent-assets/docs/concepts/observations.md +24 -20
  15. package/agent-assets/docs/concepts/process-keys.md +10 -9
  16. package/agent-assets/docs/concepts/routines.md +34 -31
  17. package/agent-assets/docs/concepts/safety-and-execution.md +11 -7
  18. package/agent-assets/docs/concepts/safety-model.md +39 -25
  19. package/agent-assets/docs/concepts/skills.md +12 -10
  20. package/agent-assets/docs/features/integrations/browser-history.md +23 -18
  21. package/agent-assets/docs/features/integrations/calendar.md +28 -17
  22. package/agent-assets/docs/features/integrations/git.md +13 -11
  23. package/agent-assets/docs/features/integrations/github.md +22 -14
  24. package/agent-assets/docs/features/integrations/mail.md +25 -22
  25. package/agent-assets/docs/features/integrations/notion.md +35 -11
  26. package/agent-assets/docs/features/integrations/obsidian.md +8 -8
  27. package/agent-assets/docs/features/lifestyle/git.md +27 -23
  28. package/agent-assets/docs/features/lifestyle/reading.md +20 -11
  29. package/agent-assets/docs/features/lifestyle/receipts.md +11 -10
  30. package/agent-assets/docs/features/lifestyle/travel-bookings.md +4 -3
  31. package/agent-assets/docs/features/memory-files/agent-journal.md +53 -26
  32. package/agent-assets/docs/features/memory-files/agent-lessons.md +178 -0
  33. package/agent-assets/docs/features/memory-files/projects.md +11 -8
  34. package/agent-assets/docs/features/memory-files/roadmap.md +17 -14
  35. package/agent-assets/docs/features/memory-files/schedule.md +6 -3
  36. package/agent-assets/docs/features/memory-files/today.md +10 -7
  37. package/agent-assets/docs/features/memory-files/user-profile.md +14 -9
  38. package/agent-assets/docs/features/messaging/bang-commands.md +21 -6
  39. package/agent-assets/docs/features/messaging/overview.md +17 -14
  40. package/agent-assets/docs/features/messaging/telegram.md +10 -9
  41. package/agent-assets/docs/features/operations/activity-and-conversations.md +6 -5
  42. package/agent-assets/docs/features/operations/approvals.md +6 -5
  43. package/agent-assets/docs/features/operations/browser-tasks.md +184 -0
  44. package/agent-assets/docs/features/operations/cost-tracking.md +11 -1
  45. package/agent-assets/docs/features/operations/managed-chromium.md +4 -2
  46. package/agent-assets/docs/features/operations/notifications.md +11 -1
  47. package/agent-assets/docs/features/operations/quiet-hours.md +41 -11
  48. package/agent-assets/docs/features/operations/schedule-approaching.md +2 -2
  49. package/agent-assets/docs/features/routines/activity-scan.md +220 -0
  50. package/agent-assets/docs/features/routines/custom-routines.md +82 -134
  51. package/agent-assets/docs/features/routines/evening-review.md +23 -13
  52. package/agent-assets/docs/features/routines/morning-routine.md +7 -5
  53. package/agent-assets/docs/features/routines/weekly-review.md +24 -3
  54. package/agent-assets/docs/features/wiki/commands.md +4 -4
  55. package/agent-assets/docs/features/wiki/cost-and-approval.md +4 -3
  56. package/agent-assets/docs/features/wiki/dashboard.md +7 -6
  57. package/agent-assets/docs/features/wiki/overview.md +3 -3
  58. package/agent-assets/docs/features/wiki/search.md +5 -5
  59. package/agent-assets/docs/features/wiki/workspaces.md +2 -2
  60. package/agent-assets/docs/getting-started/01-what-is-this.md +3 -3
  61. package/agent-assets/docs/getting-started/02-first-steps.md +5 -3
  62. package/agent-assets/docs/getting-started/04-first-day.md +27 -30
  63. package/agent-assets/docs/glossary.md +8 -8
  64. package/agent-assets/docs/guides/add-a-custom-routine.md +122 -68
  65. package/agent-assets/docs/guides/budget-and-cost-for-wiki.md +2 -2
  66. package/agent-assets/docs/guides/connect-a-new-mail-account.md +4 -2
  67. package/agent-assets/docs/guides/explore-with-trace-and-connect.md +5 -4
  68. package/agent-assets/docs/guides/install-and-run.md +2 -2
  69. package/agent-assets/docs/guides/maintain-wiki-health.md +2 -2
  70. package/agent-assets/docs/guides/pause-the-agent.md +27 -21
  71. package/agent-assets/docs/guides/reinstall-cleanly.md +2 -0
  72. package/agent-assets/docs/guides/setup-wizard.md +12 -6
  73. package/agent-assets/docs/guides/use-an-existing-obsidian-vault.md +6 -6
  74. package/agent-assets/docs/reference/api.md +26 -5
  75. package/agent-assets/docs/reference/cli-commands.md +3 -3
  76. package/agent-assets/docs/reference/config.md +51 -24
  77. package/agent-assets/docs/reference/disallowed-tools.md +6 -4
  78. package/agent-assets/docs/reference/keyboard-shortcuts.md +2 -2
  79. package/agent-assets/docs/reference/knowledge-layout.md +25 -12
  80. package/agent-assets/docs/reference/process-keys.md +9 -9
  81. package/agent-assets/docs/reference/skills.md +10 -6
  82. package/agent-assets/docs/troubleshooting/auth-failed.md +9 -8
  83. package/agent-assets/docs/troubleshooting/dashboard-shows-degraded.md +16 -9
  84. package/agent-assets/docs/troubleshooting/messaging-not-pairing.md +2 -2
  85. package/agent-assets/docs/troubleshooting/morning-routine-didnt-run.md +32 -16
  86. package/agent-assets/docs/troubleshooting/observation-not-detected.md +26 -24
  87. package/agent-assets/docs/troubleshooting/quota-exhausted.md +7 -6
  88. package/agent-assets/docs/troubleshooting/wiki-write-failed.md +3 -3
  89. package/agent-assets/skills/agent-actions/SKILL.md +23 -39
  90. package/agent-assets/skills/agent-create/SKILL.md +26 -6
  91. package/agent-assets/skills/attach/SKILL.md +8 -27
  92. package/agent-assets/skills/background-task/SKILL.md +184 -0
  93. package/agent-assets/skills/background-task-reply/SKILL.md +100 -0
  94. package/agent-assets/skills/browser-history/SKILL.md +60 -29
  95. package/agent-assets/skills/browser-history-respond/SKILL.md +6 -1
  96. package/agent-assets/skills/browser-task/SKILL.md +33 -31
  97. package/agent-assets/skills/context/SKILL.md +26 -34
  98. package/agent-assets/skills/context/curation.json +12 -12
  99. package/agent-assets/skills/context/references/api.md +22 -20
  100. package/agent-assets/skills/context/references/required-frontmatter.md +10 -9
  101. package/agent-assets/skills/context/references/snapshot-files.md +16 -15
  102. package/agent-assets/skills/context/seeds/file-responsibilities.seed.json +5 -5
  103. package/agent-assets/skills/context/seeds/frontmatter-requirements.seed.json +3 -3
  104. package/agent-assets/skills/docs-search/SKILL.md +19 -31
  105. package/agent-assets/skills/external-services/SKILL.delegated.claude.md +8 -95
  106. package/agent-assets/skills/external-services/SKILL.delegated.codex.md +8 -94
  107. package/agent-assets/skills/external-services/SKILL.delegated.gemini.md +8 -94
  108. package/agent-assets/skills/external-services/SKILL.native.claude.md +15 -9
  109. package/agent-assets/skills/external-services/SKILL.native.codex.md +11 -5
  110. package/agent-assets/skills/external-services/SKILL.native.gemini.md +11 -5
  111. package/agent-assets/skills/external-services/references/exec-errors.md +32 -0
  112. package/agent-assets/skills/external-services/references/skills-crud.md +5 -5
  113. package/agent-assets/skills/gmail-lifestyle/SKILL.md +3 -2
  114. package/agent-assets/skills/gmail-lifestyle/references/receipts-api.md +4 -0
  115. package/agent-assets/skills/gmail-lifestyle/references/travel-bookings-api.md +9 -0
  116. package/agent-assets/skills/mail/SKILL.delegated.claude.md +13 -25
  117. package/agent-assets/skills/mail/SKILL.delegated.codex.md +3 -2
  118. package/agent-assets/skills/mail/SKILL.delegated.gemini.md +3 -2
  119. package/agent-assets/skills/mail/SKILL.md +12 -20
  120. package/agent-assets/skills/mail/SKILL.native.claude.md +24 -16
  121. package/agent-assets/skills/mail/SKILL.native.codex.md +16 -9
  122. package/agent-assets/skills/mail/SKILL.native.gemini.md +12 -6
  123. package/agent-assets/skills/mail/references/api.md +6 -1
  124. package/agent-assets/skills/mail/references/examples.md +2 -1
  125. package/agent-assets/skills/managed-tasks/SKILL.md +44 -77
  126. package/agent-assets/skills/managed-tasks/references/errors.md +25 -14
  127. package/agent-assets/skills/managed-tasks/references/output-path.md +33 -17
  128. package/agent-assets/skills/managed-tasks/references/recurrence-rule.md +26 -16
  129. package/agent-assets/skills/management-policy/SKILL.md +36 -28
  130. package/agent-assets/skills/management-policy/curation.json +1 -1
  131. package/agent-assets/skills/management-policy/references/policy-workflow.md +30 -18
  132. package/agent-assets/skills/notify/SKILL.md +16 -13
  133. package/agent-assets/skills/notify/references/priority.md +42 -26
  134. package/agent-assets/skills/notion/SKILL.delegated.claude.md +1 -1
  135. package/agent-assets/skills/notion/SKILL.delegated.codex.md +1 -1
  136. package/agent-assets/skills/notion/SKILL.delegated.gemini.md +1 -1
  137. package/agent-assets/skills/notion/SKILL.md +18 -18
  138. package/agent-assets/skills/notion/SKILL.native.claude.md +4 -4
  139. package/agent-assets/skills/notion/SKILL.native.codex.md +3 -3
  140. package/agent-assets/skills/notion/SKILL.native.gemini.md +3 -3
  141. package/agent-assets/skills/observations/SKILL.md +9 -24
  142. package/agent-assets/skills/observations/references/fetch-fallback.md +22 -0
  143. package/agent-assets/skills/project-doc/SKILL.md +9 -6
  144. package/agent-assets/skills/project-doc/curation.json +3 -3
  145. package/agent-assets/skills/project-doc/seeds/project-shape.seed.json +2 -2
  146. package/agent-assets/skills/project-doc/seeds/slug-grammar.seed.json +3 -3
  147. package/agent-assets/skills/reading/SKILL.md +8 -42
  148. package/agent-assets/skills/reading/references/reading-taste.md +5 -5
  149. package/agent-assets/skills/roadmap/SKILL.md +3 -19
  150. package/agent-assets/skills/roadmap/references/api.md +23 -8
  151. package/agent-assets/skills/roadmap/references/horizon-tags.md +11 -0
  152. package/agent-assets/skills/roadmap/references/migration.md +8 -6
  153. package/agent-assets/skills/roadmap/references/retention.md +18 -0
  154. package/agent-assets/skills/schedule/SKILL.md +20 -28
  155. package/agent-assets/skills/schedule/references/importance.md +23 -0
  156. package/agent-assets/skills/schedule/references/recurrence-rule.md +26 -16
  157. package/agent-assets/skills/scheduled-managed-task/SKILL.md +46 -46
  158. package/agent-assets/skills/today/SKILL.md +38 -81
  159. package/agent-assets/skills/today/references/agent-plan-lifecycle.md +9 -4
  160. package/agent-assets/skills/today/references/agent-plan-revision.md +28 -0
  161. package/agent-assets/skills/today/references/today-skeleton.md +66 -0
  162. package/agent-assets/skills/today/seeds/agent-notes-flavors.seed.json +1 -1
  163. package/agent-assets/skills/today/seeds/section-shape.seed.json +6 -6
  164. package/agent-assets/skills/user-interview/SKILL.md +15 -90
  165. package/agent-assets/skills/user-interview/references/op-briefing.md +1 -1
  166. package/agent-assets/skills/user-interview/references/op-dm-handler.md +88 -0
  167. package/agent-assets/skills/user-interview/references/op-morning.md +2 -2
  168. package/agent-assets/skills/user-interview/references/sweep-and-fallback.md +1 -1
  169. package/agent-assets/skills/user-profile/SKILL.md +16 -26
  170. package/agent-assets/skills/user-profile/curation.json +3 -3
  171. package/agent-assets/skills/user-profile/references/character-preferences.md +3 -3
  172. package/agent-assets/skills/wiki/wiki-ask/SKILL.md +1 -1
  173. package/agent-assets/skills/wiki/wiki-compile/SKILL.md +5 -4
  174. package/agent-assets/skills/wiki/wiki-connect/SKILL.md +32 -5
  175. package/agent-assets/skills/wiki/wiki-ingest/SKILL.md +6 -50
  176. package/agent-assets/skills/wiki/wiki-ingest/references/curl-errors.md +58 -0
  177. package/agent-assets/skills/wiki/wiki-lint/SKILL.md +20 -14
  178. package/agent-assets/skills/wiki/wiki-trace/SKILL.md +10 -5
  179. package/agent-assets/skills/wiki/wiki-vault-rules/SKILL.md +2 -0
  180. package/agent-assets/system-prompts/routine-research-cluster-update.md +71 -0
  181. package/agent-assets/task-flows/_partials/feedback-capture.md +30 -0
  182. package/agent-assets/task-flows/_partials/notion-acquire.notion.md +47 -21
  183. package/agent-assets/task-flows/background_task.md +81 -0
  184. package/agent-assets/task-flows/git.local_ahead.stale.md +1 -1
  185. package/agent-assets/task-flows/git.push.detected.md +1 -1
  186. package/agent-assets/task-flows/git.tag.created.md +1 -1
  187. package/agent-assets/task-flows/github.assigned.md +1 -1
  188. package/agent-assets/task-flows/github.pull_request.review_requested.md +2 -2
  189. package/agent-assets/task-flows/github.security_alert.md +1 -1
  190. package/agent-assets/task-flows/message.received.dm.md +11 -3
  191. package/agent-assets/task-flows/message.received.dm_first.md +8 -2
  192. package/agent-assets/task-flows/{routine.hourly_check.md → routine.activity_scan.md} +31 -23
  193. package/agent-assets/task-flows/{routine.hourly_check.triage.md → routine.activity_scan.triage.md} +3 -3
  194. package/agent-assets/task-flows/routine.evening_review.md +80 -0
  195. package/agent-assets/task-flows/routine.monthly_review.md +81 -8
  196. package/agent-assets/task-flows/routine.research_cluster_update.md +33 -19
  197. package/agent-assets/task-flows/routine.roadmap_refresh.md +2 -2
  198. package/agent-assets/task-flows/routine.today_refresh.md +1 -1
  199. package/agent-assets/task-flows/routine.weekly_review.md +124 -4
  200. package/agent-assets/task-flows/schedule.approaching.md +2 -2
  201. package/agent-assets/task-flows/scheduled.dm.md +77 -1
  202. package/agent-assets/task-flows/scheduled.task.md +7 -1
  203. package/agent-assets/task-flows/wiki.trace.md +1 -1
  204. package/agent-assets/templates/_manifest.json +2 -2
  205. package/agent-assets/templates/knowledge/dossiers/_index.md +1 -1
  206. package/agent-assets/templates/knowledge/dossiers/{hourly.md → activity-scan.md} +1 -1
  207. package/agent-assets/templates/policies/journal-format.md +1 -1
  208. package/agent-assets/templates/policies/mcp.md +1 -1
  209. package/agent-assets/templates/policies/routines/_index.md +1 -1
  210. package/agent-assets/templates/policies/routines/{hourly.md → activity-scan.md} +5 -5
  211. package/bin/aitne.mjs +45 -11
  212. package/package.json +6 -5
  213. package/scripts/commands/doctor.mjs +11 -2
  214. package/scripts/lib/process-identity.d.mts +46 -0
  215. package/scripts/lib/process-identity.mjs +193 -0
  216. package/scripts/lib/read-api-token.mjs +1 -1
  217. package/scripts/start.mjs +14 -4
  218. package/agent-assets/docs/features/routines/hourly-check.md +0 -205
@@ -0,0 +1,220 @@
1
+ ---
2
+ schema_version: 1
3
+ slug: features/routines/activity-scan
4
+ title: Activity Scan
5
+ id: activity-scan
6
+ aliases:
7
+ - hourly
8
+ - observation consumer
9
+ - activity scan gate
10
+ category: features
11
+ summary: |
12
+ A medium-tier routine that fires every interval (default: every 2
13
+ hours) during active hours,
14
+ drains the pending observations queue, and decides whether the
15
+ accumulated change pattern warrants surfacing. Runs through a
16
+ four-layer gate that keeps quiet days quiet.
17
+ section: routines
18
+ tags:
19
+ - routines
20
+ - autonomous
21
+ - observations
22
+ - polling
23
+ - activity-scan
24
+ status: stable
25
+ ui_anchors:
26
+ - /agents/activity-scan
27
+ - /settings/hours
28
+ - /activity?tab=system
29
+ ask_examples:
30
+ - What does the activity scan do?
31
+ - When does it run?
32
+ - How does the activity scan decide whether to escalate?
33
+ - What is the harvest pre-pass?
34
+ - How do I tune the gate's freshness window?
35
+ locale: en-US
36
+ created: 2026-04-25
37
+ updated: 2026-06-10
38
+ keywords:
39
+ - hourly
40
+ - observations
41
+ - polling
42
+ - activity scan
43
+ - gate
44
+ - layer 1
45
+ - layer 2
46
+ - layer 3
47
+ - harvestForGate
48
+ - decideStage
49
+ - pre-pass
50
+ related:
51
+ - concepts/observations
52
+ - concepts/routines
53
+ - concepts/delegated-mode
54
+ - features/integrations/browser-history
55
+ process_keys:
56
+ - routine.activity_scan
57
+ - routine.activity_scan.triage
58
+ - routine.fetch_window
59
+ config_keys:
60
+ - activityScanEnabled
61
+ - activityScanIntervalMinutes
62
+ - activityScanActiveStartHour
63
+ - activityScanActiveEndHour
64
+ - activityScanMinObservations
65
+ - activityScanStage2Enabled
66
+ - activityScanHeartbeatHours
67
+ - activityScanLowSignalPendingCeiling
68
+ - activityScanPrePassFreshnessMinutes
69
+ ---
70
+
71
+ # Activity Scan
72
+
73
+ A medium-tier routine that drains the observations queue every interval
74
+ during active hours and decides whether the accumulated change
75
+ pattern warrants notifying you or appending to `state/today.md`. The
76
+ "decide" step is a four-layer gate designed to keep quiet days quiet
77
+ without missing the moment when something piles up.
78
+
79
+ ## When It Runs
80
+
81
+ Every **interval minutes** (default 120 — every 2 hours), inside the configured active
82
+ window. Cadence, window, and the enable switch live on the
83
+ activity-scan **agent** — edit them at `/agents/activity-scan`
84
+ (Definition tab → Cadence card; Enable/Disable toggles the routine).
85
+ The legacy `activityScan*` config keys are deprecated fallbacks (see
86
+ [Configuration](#configuration)). The trigger:
87
+
88
+ - **Skips** when the morning routine has not yet run today
89
+ (recoverable — the dispatcher enqueues a `queueMorningRoutineWake`
90
+ self-recovery and the activity scan resumes after the morning
91
+ routine succeeds).
92
+ - **Skips** when another activity scan is in flight (atomic flag).
93
+ - **Skips** when accumulated signal is below the agent's **min
94
+ observations** threshold and the heartbeat window
95
+ (`activityScanHeartbeatHours`) hasn't elapsed.
96
+
97
+ Every tick writes one `agent_actions` row with
98
+ `action_type = 'activity_scan.gate'` so the gate's decisions are
99
+ auditable from `aitne audit` and the dashboard activity feed.
100
+
101
+ ## The Four-Layer Gate
102
+
103
+ The gate replaced the pre-Phase-9 "30-minute rate-limit" gate. It
104
+ runs on every cron tick; only Layer 4 actually spawns a medium-tier
105
+ agent session.
106
+
107
+ ### Layer 1 — Harvest pre-pass
108
+
109
+ `ActivityScanCoordinator.harvestForGate` spawns a lite-tier
110
+ `routine.fetch_window` session for each delegated / native
111
+ integration whose `runtime_state.pre_pass_last_run:<key>` is older
112
+ than `activityScanPrePassFreshnessMinutes`. The pre-pass fetches the
113
+ integration's scan window (mail / calendar / Notion) and POSTs the
114
+ results to `/api/observations`, so the rest of the gate sees a
115
+ populated queue instead of stale data.
116
+
117
+ Telemetry: `agent_actions.detail.harvest_ran` /
118
+ `harvest_integrations` / `harvest_failed_integrations`.
119
+
120
+ ### Layer 2 — Signal compute
121
+
122
+ `computeActivityScanSignals` reads the observation table mode-blind —
123
+ it filters by source-prefix sets derived from
124
+ `INTEGRATION_DESCRIPTORS`, never by `actor`. Signal categories
125
+ include unread-mail / event-change / repo-change / browser-history
126
+ clusters; each category produces a (count, last-seen, summary)
127
+ tuple. The pre-pass freshness gate from Layer 1 is what guarantees
128
+ those counts reflect "now", not "an hour ago".
129
+
130
+ ### Layer 3 — Decide stage
131
+
132
+ `decideStage` is a pure function over the signal snapshot plus the
133
+ per-tick config (heartbeat status, `activityScanStage2Enabled`,
134
+ `activityScanLowSignalPendingCeiling`). It returns one of three stages
135
+ — `stage0_silent`, `stage2`, or `stage3`:
136
+
137
+ | Stage | What happens |
138
+ |---|---|
139
+ | `stage0_silent` | No agent session. Consume the pending observations and append a single best-effort line to `state/today.md`'s `## Agent Log`. This is the verdict for both "no signals" and "low signal under the ceiling". |
140
+ | `stage2` | Only reachable when `activityScanStage2Enabled = true` (default `false`, so low-signal ticks fall through to `stage3`). Runs a lite-tier `routine.activity_scan.triage` call whose strict JSON output decides `log_only` (→ silent path) vs. `escalate` (→ `stage3`). |
141
+ | `stage3` | Spawn the full medium-tier `routine.activity_scan` session — the visible agent run. Reached directly on high-novelty signals (VIP mail, calendar conflict, overdue agent plan, approaching schedule) or as the cautious default when Stage 2 is off. |
142
+
143
+ When a Layer 1 pre-pass fails (`harvest.failed`), the gate
144
+ short-circuits to a cautious `stage3` with reason
145
+ `cautious_escalate_prepass_failure` and tags the audit row
146
+ `agent_actions.detail.cautious_escalate = true` — a failed fetch
147
+ should never silently swallow a tick's worth of signals.
148
+
149
+ ### Layer 4 — Dispatch
150
+
151
+ When Layer 3 returns `stage0_silent` (or Stage 2 returns
152
+ `log_only`), the daemon runs `runSilentActivityScanPath` — a
153
+ daemon-direct write, no agent. When it returns `stage3` (or Stage 2
154
+ returns `escalate`), `enqueueStage3ActivityScan` puts a
155
+ `routine.activity_scan` event on the bus, which becomes the visible
156
+ agent session.
157
+
158
+ ## What It Outputs
159
+
160
+ - A best-effort line in `state/today.md`'s `## Agent Log` — even the
161
+ silent path appends one (skipped only if `today.md` is missing or
162
+ the write lock is held; the observations are still consumed either
163
+ way).
164
+ - Notifications when warranted (only on a `stage3` agent session).
165
+ - An audit row on every tick:
166
+ `agent_actions.action_type = 'activity_scan.gate'`, carrying the
167
+ harvest + signal + stage detail.
168
+
169
+ ## Configuration
170
+
171
+ The cadence, active window, min-observations threshold, and on/off
172
+ switch are owned by the activity-scan agent: edit them at
173
+ `/agents/activity-scan` (Definition tab → Cadence card;
174
+ Enable/Disable for the switch). The matching `activityScan*` config
175
+ keys below are **deprecated fallbacks** — still accepted by
176
+ `PATCH /api/config` but no longer surfaced in the dashboard; values
177
+ resolve agent override → legacy config key → built-in default.
178
+
179
+ | Setting | Default | Layer | Notes |
180
+ |---|---|---|---|
181
+ | Enable/Disable (`/agents/activity-scan`) | enabled | trigger | Master switch — the agent's `enabled` flag. Legacy key `activityScanEnabled` (deprecated fallback). |
182
+ | Interval minutes | `120` | trigger | Cron cadence. Cadence card. Legacy key `activityScanIntervalMinutes` (deprecated fallback). |
183
+ | Active start hour | `4` | trigger | Active window start. Cadence card. Legacy key `activityScanActiveStartHour` (deprecated fallback). |
184
+ | Active end hour | `24` | trigger | End-exclusive; `24` ≡ midnight. Cadence card. Legacy key `activityScanActiveEndHour` (deprecated fallback). |
185
+ | Min observations | `1` | trigger | Minimum pending observations before a non-silent stage dispatches; below this the tick records a `below_threshold` skip. Cadence card. Legacy key `activityScanMinObservations` (deprecated fallback). |
186
+ | `activityScanPrePassFreshnessMinutes` | `30` | Layer 1 | Range `0`–`480`. Skip a per-integration fetch if its pre-pass ran more recently; `0` fetches every tick, `480` is cost-minimal. |
187
+ | `activityScanStage2Enabled` | `false` | Layer 3 | Adds the lite-tier triage call; while `false`, low-signal ticks route straight to `stage3`. |
188
+ | `activityScanHeartbeatHours` | `4` | Layer 3 | Range `1`–`48`. Force a non-silent stage at least this often, even on a quiet day. |
189
+ | `activityScanLowSignalPendingCeiling` | `0` | Layer 3 | Range `0`–`20`. At or below this pending count, a low-signal tick stays silent. `0` keeps the cautious default (any pending observation escalates). |
190
+
191
+ (The agent was named "Hourly Check" until v0.1.11 — old `hourlyCheck*`
192
+ config keys and the `/api/agents/hourly-check` URL are still accepted
193
+ for one deprecation window. `hourlyCheckGateMode` was removed in
194
+ HOURLY_CHECK_GATE_REDESIGN_PLAN
195
+ Phase 4 — the gate has a single execution path now.)
196
+
197
+ ## When Something Goes Wrong
198
+
199
+ - **Skipped because the morning routine hasn't run.** The
200
+ dispatcher's `morningRoutineRanToday` gate keys on
201
+ `agent_actions.result = 'success'`. The skip reason is
202
+ `morning_routine_pending_for_today` and triggers a
203
+ `queueMorningRoutineWake` self-recovery. See
204
+ [Morning Routine Didn't Run](../../troubleshooting/morning-routine-didnt-run.md).
205
+ - **Stage 3 never fires on a quiet day.** Expected.
206
+ `activityScanHeartbeatHours` forces a tick occasionally so silence
207
+ doesn't last indefinitely.
208
+ - **Pre-pass keeps failing for one integration.** Read
209
+ `agent_actions.detail.harvest_failed_integrations`; the failing
210
+ integration name is recorded. Usually an auth issue — check
211
+ `/health.integrationModes` and the integration's settings page.
212
+
213
+ ## Related
214
+
215
+ - [Observations](../../concepts/observations.md) — what populates the
216
+ queue Layer 2 reads.
217
+ - [Delegated Mode](../../concepts/delegated-mode.md) — the
218
+ delegated / native integrations that participate in Layer 1's
219
+ harvest.
220
+ - [Routines](../../concepts/routines.md)
@@ -1,175 +1,123 @@
1
1
  ---
2
2
  schema_version: 1
3
3
  slug: features/routines/custom-routines
4
- title: Custom Routines
4
+ title: Custom Routines (Retired)
5
5
  id: custom-routines
6
6
  aliases:
7
7
  - custom routine
8
8
  - cron routine
9
9
  - user routine
10
+ - migrated_to_agent
10
11
  category: features
11
12
  summary: |
12
- Beyond the built-in morning / evening / weekly / hourly routines,
13
- the operator can define custom routines that fire on any cron
14
- schedule. Each routine is a Markdown file under
15
- policies/routines/custom/, runs under the tier the operator picks,
16
- and is bounded by the same safety layers as the built-ins.
13
+ Custom routines — cron-driven Markdown files under
14
+ policies/routines/custom/ are retired. User Agents replaced them.
15
+ At the first daemon start after the upgrade, each valid custom
16
+ routine was converted once into a user Agent with the same cron,
17
+ tier, budget, and enabled state; the source file is kept but marked
18
+ inert. Recurring work now lives on /agents.
17
19
  section: routines
18
20
  tags:
19
21
  - routines
22
+ - agents
20
23
  - autonomous
21
24
  - scheduler
22
- - core
23
25
  - advanced
24
- status: stable
26
+ status: deprecated
25
27
  ask_examples:
26
- - How do I add a custom routine?
27
- - What can a custom routine do?
28
- - Can I disable a custom routine?
29
- - Which tier does a custom routine run under?
28
+ - What happened to my custom routines?
29
+ - Where did my custom routine go?
30
+ - What does migrated_to_agent mean?
31
+ - How do I create a recurring task now?
30
32
  locale: en-US
31
33
  created: 2026-04-25
32
- updated: 2026-05-28
34
+ updated: 2026-06-10
33
35
  keywords:
34
36
  - custom routine
35
37
  - routine.custom.<slug>
36
- - user-defined routine
37
- - scheduled task
38
- - recurring schedule
39
- - cron routine
38
+ - migrated_to_agent
39
+ - user agent
40
+ - recurring agent
41
+ - migration
40
42
  related:
41
43
  - guides/add-a-custom-routine
42
44
  - concepts/routines
43
- - features/memory-files/schedule
44
45
  prerequisites:
45
46
  - concepts/routines
46
47
  process_keys:
47
48
  - routine.custom.<slug>
48
49
  context_files:
49
50
  - policies/routines/custom/<slug>.md
51
+ - policies/agents/<slug>/agent.md
50
52
  api_endpoints:
51
- - PUT /api/context/*
52
- - POST /api/recurring-schedules
53
+ - POST /api/agents
53
54
  ui_anchors:
54
- - /settings/routines
55
- - /connections/routines
55
+ - /agents
56
56
  ---
57
57
 
58
- # Custom Routines
58
+ # Custom Routines (Retired)
59
59
 
60
60
  ## In One Sentence
61
61
 
62
- Operator-defined routines fire on any cron schedule, run under the
63
- tier the operator picks (`lite` / `medium` / `high`), and are bounded
64
- by the same safety layers as the built-ins.
65
-
66
- ## What It Does
67
-
68
- - Runs a vault-file-defined check list on a cron schedule.
69
- - Resolves the backend at fire time from the chosen tier (no concrete
70
- model picker tier resolution mirrors the built-in routines).
71
- - Logs its run to Activity exactly like a built-in routine.
72
-
73
- ## When It Runs
74
-
75
- The cron expression in the routine's vault file
76
- `policies/routines/custom/<slug>.md` drives the cadence. The scheduler
77
- wires one `node-cron` job per enabled routine at startup and fires a
78
- `routine.custom.<slug>` event on each tick.
79
-
80
- It is a **standard 5-field cron expression** (`min hour day-of-month
81
- month day-of-week`); for example `0 11 * * 2` is every Tuesday at
82
- 11:00 local time, in your configured timezone.
83
-
84
- ## How Changes Are Picked Up
85
-
86
- There is **no filesystem watcher**. The scheduler reloads only when a
87
- write goes through the context API — a `PUT` / `PATCH` / `DELETE`
88
- under `policies/routines/custom/` triggers an automatic re-diff of the
89
- registered jobs against what is on disk, so edits made through the
90
- dashboard, the API, or the agent take effect without a daemon restart.
91
-
92
- A raw file edit that bypasses the API (for example, opening the `.md`
93
- in an external editor) is *not* picked up until the next API write to
94
- that directory or a daemon restart. Prefer editing through **Settings
95
- Routines** or the context API.
96
-
97
- ## What It Outputs
98
-
99
- - Whatever the check list produces — a context-file write, a
100
- notification, or a no-op.
101
-
102
- ## Where in the Dashboard
103
-
104
- - **Settings Routines** (`/settings/routines`) is the operator
105
- surface for adding, editing, and disabling. `/connections/routines`
106
- is an equivalent page that opens the same surface.
107
-
108
- ## Configuration
109
-
110
- Each custom routine is a Markdown file under
111
- `~/.personal-agent/context/policies/routines/custom/<slug>.md` whose
112
- frontmatter carries:
113
-
114
- | Field | Type | Notes |
115
- |---|---|---|
116
- | `type` | `rule` | Always `rule` for custom routines. |
117
- | `slug` | string | Kebab-case; matches the file stem and the ProcessKey suffix. |
118
- | `cron` | string | Standard 5-field cron expression (e.g. `0 11 * * 2`). |
119
- | `process_key` | `routine.custom.<slug>` | Must match the slug. |
120
- | `enabled` | boolean (`true` / `false`) | Disable without deleting by setting `false`. |
121
- | `backend_tier` | `lite` \| `medium` \| `high` | Drives BackendRouter tier resolution. Legacy `light` (→ `medium`) and `heavy` (→ `high`) are still accepted for files written before the rename. |
122
- | `max_budget_usd` | number | Per-execute USD cap; must be a positive number (e.g. `0.05`). |
123
-
124
- Every field above is required; the body must contain a `## Checks`
125
- section — a routine that is missing any of them is rejected at write
126
- time with a validation error.
127
-
128
- The `## Checks` section is the list the agent runs through on each
129
- fire. To change a routine, write through the context API (the
130
- dashboard, the API, or the agent), which triggers an automatic reload
131
- as described above — no daemon restart is needed.
132
-
133
- ### Example
134
-
135
- A `tuesday-standup-prep` routine at
136
- `policies/routines/custom/tuesday-standup-prep.md`:
137
-
138
- ```markdown
139
- ---
140
- type: rule
141
- slug: tuesday-standup-prep
142
- cron: "0 11 * * 2"
143
- process_key: routine.custom.tuesday-standup-prep
144
- enabled: true
145
- backend_tier: medium
146
- max_budget_usd: 0.10
147
- ---
148
-
149
- ## Checks
150
-
151
- - Summarize commits I pushed since last Tuesday.
152
- - List any calendar events for the rest of the week that mention
153
- "standup" or "review".
154
- - If there is anything noteworthy, DM me a short prep note.
155
- ```
156
-
157
- This fires every Tuesday at 11:00 (your configured timezone), runs
158
- under the `medium` tier (Sonnet on the Claude backend), and stops
159
- spending once the run reaches $0.10.
160
-
161
- > **Distinct from `recurring_schedules`.** The `recurring_schedules`
162
- > table powers DM-style scheduled tasks (`agent.task` /
163
- > `agent.dm_task`) — e.g. "remind me at 9am every weekday". Those
164
- > use a structured `RecurrenceRule` (frequency + time + dayOf*) and
165
- > are managed via `POST /api/recurring-schedules`. They are not the
166
- > same surface as `routine.custom.<slug>`.
167
-
168
- ## When Something Goes Wrong
169
-
170
- - A cron expression that resolves to "never": the routine appears in
171
- the list but never fires. The dashboard shows next-fire as N/A.
62
+ Custom routines (`policies/routines/custom/<slug>.md` files fired as
63
+ `routine.custom.<slug>`) no longer run **user Agents replaced
64
+ them**, and every valid routine was converted automatically, exactly
65
+ once, at the first daemon start after the upgrade.
66
+
67
+ ## What Changed
68
+
69
+ - The custom-routine scheduler was removed. Files under
70
+ `policies/routines/custom/` are no longer read by any scheduler, and
71
+ no `routine.custom.<slug>` events fire. (Historical Activity rows
72
+ tagged with those keys remain and still resolve to this page.)
73
+ - Recurring work you define is now an **Agent**: a
74
+ `policies/agents/<slug>/agent.md` file that appears on the
75
+ **Agents** page (`/agents`) with its schedule, an enable toggle, run
76
+ metrics, execution history, and a **Run now** button — surfaces
77
+ custom routines never had. See
78
+ [Create a Recurring Agent](../../guides/add-a-custom-routine.md).
79
+
80
+ ## The One-Time Migration
81
+
82
+ At the first daemon start after the upgrade — and only once, guarded
83
+ by a persisted flag — every file under `policies/routines/custom/` is
84
+ examined:
85
+
86
+ - A **valid routine becomes a user Agent** at
87
+ `policies/agents/<slug>/agent.md` carrying over:
88
+ - the same **cron expression** (pinned to your configured timezone),
89
+ - the same **model tier** (`backend_tier` the Agent's tier),
90
+ - the same **per-run budget** (`max_budget_usd`),
91
+ - the same **enabled state** — a disabled routine migrates disabled.
92
+
93
+ The routine's body (its `## Checks` section) becomes the Agent's
94
+ **task prompt** verbatim, and the Agent's description records where
95
+ it came from (`Migrated from custom routine "<slug>".`).
96
+ - The **source file is never deleted.** It is rewritten in place with
97
+ `enabled: false` and a `migrated_to_agent: <slug>` marker in its
98
+ frontmatter, so it is visibly inert while your content is preserved.
99
+
100
+ ### Collisions and invalid files
101
+
102
+ - **Slug collision** — if an Agent (built-in or user) already exists
103
+ under the routine's slug, the migration falls back to
104
+ `custom-<slug>`. If that also collides, the routine is skipped with
105
+ a warning and the file is left untouched.
106
+ - **Invalid files** a routine with broken frontmatter or missing
107
+ required fields is left untouched and logged; it is not migrated.
108
+ (Such files never fired under the old scheduler either.)
109
+
110
+ ## After the Migration
111
+
112
+ - Find your migrated routines on **`/agents`** — each one's
113
+ description says which custom routine it came from.
114
+ - Edit the schedule, tier, limits, or prompt there (or directly in the
115
+ `agent.md` file; the daemon picks up changes without a restart).
116
+ - The inert files under `policies/routines/custom/` can stay as a
117
+ reference or be deleted whenever you like they have no effect
118
+ either way.
172
119
 
173
120
  ## Related
174
121
 
175
- - [Add a Custom Routine](../../guides/add-a-custom-routine.md)
122
+ - [Create a Recurring Agent](../../guides/add-a-custom-routine.md)
123
+ - [Routines](../../concepts/routines.md)
@@ -27,7 +27,7 @@ ask_examples:
27
27
  - How do I disable the evening review?
28
28
  locale: en-US
29
29
  created: 2026-04-25
30
- updated: 2026-05-28
30
+ updated: 2026-06-10
31
31
  keywords:
32
32
  - evening review
33
33
  - retro
@@ -39,7 +39,7 @@ related:
39
39
  - features/memory-files/agent-journal
40
40
  - features/memory-files/today
41
41
  - features/routines/morning-routine
42
- - features/routines/custom-routines
42
+ - guides/add-a-custom-routine
43
43
  process_keys:
44
44
  - routine.evening_review
45
45
  context_files:
@@ -48,9 +48,10 @@ context_files:
48
48
  - journal/agent.md
49
49
  - identity/profile.md
50
50
  - policies/routines/evening.md
51
+ - policies/agent-lessons.md
51
52
  ui_anchors:
52
- - /connections/journal
53
- - /settings/routines
53
+ - /knowledge?tab=context-files
54
+ - /agents/evening-review
54
55
  ---
55
56
 
56
57
  # Evening Review
@@ -64,7 +65,7 @@ your identity files.
64
65
 
65
66
  ## What It Does
66
67
 
67
- The routine runs three internal bookkeeping steps. These are quiet by
68
+ The routine runs several internal bookkeeping steps. These are quiet by
68
69
  design — they prepare state that **tomorrow's morning routine depends on**
69
70
  rather than producing a chatty end-of-day report.
70
71
 
@@ -80,6 +81,11 @@ rather than producing a chatty end-of-day report.
80
81
  3. **Process profile signals.** Reads the day's Raw Signals from your
81
82
  profile and routes each into `character`, Learned Context, or a
82
83
  detailed identity file under `identity/`, then prunes stale entries.
84
+ 4. **Consolidate feedback signals into lessons.** When feedback learning is
85
+ on (default) and signals are pending, folds the day's unconsumed feedback
86
+ into the scoped lesson stores (`policies/agent-lessons.md` for agent-scope
87
+ lessons; identity files for owner directives), then marks them consumed.
88
+ Skipped entirely when no signals pend.
83
89
 
84
90
  ## When It Runs / How It Is Triggered
85
91
 
@@ -94,6 +100,8 @@ run is skipped while the agent is paused (`!stop`) or setup is incomplete.
94
100
  - Roadmap edits in `plans/roadmap.md` when a plan was promoted or fired.
95
101
  - A `journal/agent.md` line **only** when a roadmap review date fired or a
96
102
  validation error needs recording.
103
+ - Lesson edits in `policies/agent-lessons.md` when feedback signals were
104
+ pending and consolidated.
97
105
 
98
106
  The built-in steps emit **no user-facing DM by default** — there is no
99
107
  "today wraps up here" message. (The one exception: any check you add to
@@ -102,19 +110,21 @@ including steps that call `POST /api/notify`.)
102
110
 
103
111
  ## Where in the Dashboard
104
112
 
105
- - **ConnectionsJournal** (`/connections/journal`) shows `journal/agent.md`
106
- entries when the roadmap step logged one.
107
- - **SettingsRoutines** (`/settings/routines`) is where you manage the
108
- evening rulebook.
113
+ - **KnowledgeContext Files** (`/knowledge?tab=context-files`) shows
114
+ `journal/agent.md` entries when the roadmap step logged one.
115
+ - **AgentsEvening Review** (`/agents/evening-review`) is where you
116
+ manage the evening rulebook (Rulebook tab) and enable or disable the
117
+ routine.
109
118
 
110
119
  ## Configuration
111
120
 
112
121
  The fire time and tier are fixed in code, but the routine is not a black box:
113
122
  - **Add your own evening checks.** Append `### <label>` entries to
114
- `policies/routines/evening.md` (via the dashboard, or the
115
- [custom routines guide](../../guides/add-a-custom-routine.md)). They run
116
- alongside the built-in steps using the same journaling conventions and
117
- may notify you explicitly.
123
+ `policies/routines/evening.md` (via the dashboard or the context
124
+ API). They run alongside the built-in steps using the same
125
+ journaling conventions and may notify you explicitly. For a
126
+ standalone recurring job on its own schedule, create a
127
+ [recurring Agent](../../guides/add-a-custom-routine.md) instead.
118
128
  - **Verify it stays healthy.** `aitne verify evening-review-slimdown`
119
129
  checks that recent `routine.evening_review` sessions ran inside their
120
130
  seeded token envelope (read-only; `--days N` widens the window).
@@ -26,7 +26,7 @@ ask_examples:
26
26
  - What model does morning routine use?
27
27
  locale: en-US
28
28
  created: 2026-04-25
29
- updated: 2026-05-28
29
+ updated: 2026-06-10
30
30
  keywords:
31
31
  - morning
32
32
  - day plan
@@ -42,7 +42,7 @@ related:
42
42
  prerequisites:
43
43
  - concepts/agent-day
44
44
  ui_anchors:
45
- - /settings/routines
45
+ - /agents/morning-routine
46
46
  - /settings/models
47
47
  - /schedule
48
48
  - /activity
@@ -91,7 +91,7 @@ Within Stage A, the work proceeds in this order:
91
91
  2. Pull today's calendar events from any connected calendar integration.
92
92
  3. Scan recent unread mail and surface the few that need owner attention.
93
93
  4. Walk the roadmap for items whose **Preparation Timeline** rows fire today.
94
- 5. Consume any pending observations the hourly check has already queued.
94
+ 5. Consume any pending observations the activity scan has already queued.
95
95
  6. Write the rebuilt `state/today.md`.
96
96
  7. Log a single status line to the dashboard activity feed.
97
97
 
@@ -109,8 +109,9 @@ the daemon injects a `<roadmap_skeleton>` block carrying the pre-aggregated
109
109
  Annual Goals / Quarterly Focus / Preparation Timeline facts so Stage A
110
110
  can populate the wizard's placeholder roadmap on medium tier instead of
111
111
  paying for a one-shot high-tier session. (The dedicated
112
- `routine.morning_routine_initial` process key was retired in Phase 4, and
113
- Phase 7 2026-05-16 removed its high-tier seed entirely.)
112
+ `routine.morning_routine_initial` process key along with its high-tier
113
+ seed — was retired in Phase 7, 2026-05-16; the first-run branch now flows
114
+ through the parent `routine.morning_routine` envelope.)
114
115
 
115
116
  ## What It Outputs
116
117
 
@@ -125,6 +126,7 @@ Phase 7 — 2026-05-16 — removed its high-tier seed entirely.)
125
126
  - **Schedule view** — the column for today is rebuilt against the new schedule file.
126
127
  - **Activity feed** — a `routine.morning_routine` row appears at the run timestamp.
127
128
  - **Settings → Models** — the routine's backend, model, max-turns, and budget cap are configured here.
129
+ - **Agents → Morning Routine** (`/agents/morning-routine`) — the agent's Rulebook tab edits the morning rulebook (`policies/routines/morning.md`) plus the daily-journal Format and Export rules.
128
130
 
129
131
  ## Configuration
130
132