openclacky 1.5.22 → 1.5.24

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 (130) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +104 -0
  3. data/docs/secretary-prototype.md +286 -0
  4. data/lib/clacky/agent/cost_tracker.rb +55 -36
  5. data/lib/clacky/agent/hook_manager.rb +4 -1
  6. data/lib/clacky/agent/llm_caller.rb +46 -12
  7. data/lib/clacky/agent/memory_injector.rb +209 -0
  8. data/lib/clacky/agent/memory_updater.rb +16 -0
  9. data/lib/clacky/agent/session_serializer.rb +15 -11
  10. data/lib/clacky/agent/skill_manager.rb +30 -8
  11. data/lib/clacky/agent.rb +124 -17
  12. data/lib/clacky/agent_config.rb +7 -3
  13. data/lib/clacky/agent_profile.rb +33 -6
  14. data/lib/clacky/anthropic_stream_aggregator.rb +11 -1
  15. data/lib/clacky/bedrock_stream_aggregator.rb +11 -1
  16. data/lib/clacky/billing/platform_billing.rb +7 -0
  17. data/lib/clacky/cli.rb +4 -3
  18. data/lib/clacky/client.rb +30 -25
  19. data/lib/clacky/default_extensions/advisor/README.md +25 -0
  20. data/lib/clacky/default_extensions/advisor/README.zh.md +25 -0
  21. data/lib/clacky/default_extensions/advisor/ext.yml +1 -1
  22. data/lib/clacky/default_extensions/advisor/icon.svg +14 -0
  23. data/lib/clacky/default_extensions/advisor/panels/advisor/view.js +7 -1
  24. data/lib/clacky/default_extensions/coding/ext.yml +0 -1
  25. data/lib/clacky/default_extensions/computer-use/README.md +48 -0
  26. data/lib/clacky/default_extensions/computer-use/README.zh.md +48 -0
  27. data/lib/clacky/default_extensions/computer-use/ext.yml +1 -1
  28. data/lib/clacky/default_extensions/computer-use/icon.svg +16 -0
  29. data/lib/clacky/default_extensions/ext-studio/ext.yml +0 -1
  30. data/lib/clacky/default_extensions/general/ext.yml +0 -1
  31. data/lib/clacky/default_extensions/git/README.md +41 -0
  32. data/lib/clacky/default_extensions/git/README.zh.md +41 -0
  33. data/lib/clacky/default_extensions/git/ext.yml +1 -1
  34. data/lib/clacky/default_extensions/git/icon.svg +15 -0
  35. data/lib/clacky/default_extensions/git/panels/git/view.js +106 -27
  36. data/lib/clacky/default_extensions/meeting/README.md +46 -0
  37. data/lib/clacky/default_extensions/meeting/README.zh.md +47 -0
  38. data/lib/clacky/default_extensions/meeting/ext.yml +1 -1
  39. data/lib/clacky/default_extensions/meeting/icon.svg +13 -0
  40. data/lib/clacky/default_extensions/preview/README.md +29 -0
  41. data/lib/clacky/default_extensions/preview/README.zh.md +29 -0
  42. data/lib/clacky/default_extensions/preview/ext.yml +1 -1
  43. data/lib/clacky/default_extensions/preview/icon.svg +13 -0
  44. data/lib/clacky/default_extensions/secretary/README.md +69 -0
  45. data/lib/clacky/default_extensions/secretary/README.zh.md +69 -0
  46. data/lib/clacky/default_extensions/secretary/agents/secretary.md +41 -0
  47. data/lib/clacky/default_extensions/secretary/agents/worker.md +35 -0
  48. data/lib/clacky/default_extensions/secretary/api/handler.rb +8 -0
  49. data/lib/clacky/default_extensions/secretary/ext.yml +42 -0
  50. data/lib/clacky/default_extensions/secretary/icon.svg +17 -0
  51. data/lib/clacky/default_extensions/secretary/panels/work/view.js +344 -0
  52. data/lib/clacky/default_extensions/secretary/tools/delegate_work.rb +37 -0
  53. data/lib/clacky/default_extensions/secretary/tools/manage_work.rb +22 -0
  54. data/lib/clacky/default_extensions/secretary/tools/yield_work.rb +35 -0
  55. data/lib/clacky/default_extensions/time_machine/README.md +32 -0
  56. data/lib/clacky/default_extensions/time_machine/README.zh.md +32 -0
  57. data/lib/clacky/default_extensions/time_machine/ext.yml +1 -1
  58. data/lib/clacky/default_extensions/time_machine/icon.svg +14 -0
  59. data/lib/clacky/default_skills/channel-manager/SKILL.md +103 -13
  60. data/lib/clacky/default_skills/channel-manager/dingtalk_setup.rb +4 -2
  61. data/lib/clacky/default_skills/channel-manager/discord_setup.rb +9 -2
  62. data/lib/clacky/default_skills/channel-manager/weixin_setup.rb +10 -1
  63. data/lib/clacky/default_skills/cron-task-creator/SKILL.md +183 -206
  64. data/lib/clacky/default_skills/cron-task-creator/evals/evals.json +45 -0
  65. data/lib/clacky/default_skills/media-gen/SKILL.md +31 -14
  66. data/lib/clacky/default_skills/onboard/SKILL.md +5 -7
  67. data/lib/clacky/default_skills/persist-memory/SKILL.md +15 -1
  68. data/lib/clacky/extension/api_extension.rb +23 -2
  69. data/lib/clacky/extension/loader.rb +2 -0
  70. data/lib/clacky/extension/verifier.rb +2 -2
  71. data/lib/clacky/json_ui_controller.rb +14 -1
  72. data/lib/clacky/locales/en.rb +14 -0
  73. data/lib/clacky/locales/i18n.rb +25 -3
  74. data/lib/clacky/locales/zh.rb +14 -0
  75. data/lib/clacky/message_history.rb +15 -2
  76. data/lib/clacky/openai_responses_stream_aggregator.rb +11 -1
  77. data/lib/clacky/openai_stream_aggregator.rb +11 -1
  78. data/lib/clacky/prompts/base.md +1 -1
  79. data/lib/clacky/providers.rb +32 -17
  80. data/lib/clacky/server/backup_manager.rb +98 -2
  81. data/lib/clacky/server/browser_manager.rb +10 -5
  82. data/lib/clacky/server/channel/adapters/base.rb +18 -0
  83. data/lib/clacky/server/channel/adapters/feishu/message_parser.rb +1 -0
  84. data/lib/clacky/server/channel/adapters/telegram/adapter.rb +1 -0
  85. data/lib/clacky/server/channel/channel_config.rb +185 -48
  86. data/lib/clacky/server/channel/channel_manager.rb +247 -110
  87. data/lib/clacky/server/git_panel.rb +2 -1
  88. data/lib/clacky/server/http_server.rb +517 -175
  89. data/lib/clacky/server/preview.rb +26 -5
  90. data/lib/clacky/server/scheduler.rb +166 -85
  91. data/lib/clacky/server/web_ui_controller.rb +12 -0
  92. data/lib/clacky/session_manager.rb +4 -1
  93. data/lib/clacky/skill.rb +1 -1
  94. data/lib/clacky/tools/base.rb +7 -1
  95. data/lib/clacky/ui_interface.rb +5 -0
  96. data/lib/clacky/utils/file_processor.rb +23 -11
  97. data/lib/clacky/utils/model_pricing.rb +19 -0
  98. data/lib/clacky/version.rb +1 -1
  99. data/lib/clacky/web/app.css +621 -52
  100. data/lib/clacky/web/app.js +103 -9
  101. data/lib/clacky/web/components/code-editor.js +73 -4
  102. data/lib/clacky/web/components/custom-select.js +7 -18
  103. data/lib/clacky/web/components/hint-tip.js +172 -0
  104. data/lib/clacky/web/components/model-picker.js +1 -1
  105. data/lib/clacky/web/components/notify.js +37 -10
  106. data/lib/clacky/web/components/onboard.js +1 -1
  107. data/lib/clacky/web/components/sidebar.js +70 -0
  108. data/lib/clacky/web/features/backup/store.js +64 -27
  109. data/lib/clacky/web/features/backup/view.js +42 -11
  110. data/lib/clacky/web/features/channels/store.js +19 -4
  111. data/lib/clacky/web/features/channels/view.js +94 -33
  112. data/lib/clacky/web/features/extensions/view.js +15 -8
  113. data/lib/clacky/web/features/new-session/view.js +33 -22
  114. data/lib/clacky/web/features/profile/view.js +4 -4
  115. data/lib/clacky/web/features/tasks/store.js +5 -3
  116. data/lib/clacky/web/features/tasks/view.js +99 -26
  117. data/lib/clacky/web/features/trash/view.js +4 -4
  118. data/lib/clacky/web/features/workspace/view.js +193 -57
  119. data/lib/clacky/web/i18n.js +189 -17
  120. data/lib/clacky/web/index.html +165 -53
  121. data/lib/clacky/web/projects.js +15 -2
  122. data/lib/clacky/web/sessions.js +316 -86
  123. data/lib/clacky/web/settings.js +304 -75
  124. data/lib/clacky/web/utils.js +261 -0
  125. data/lib/clacky/web/ws-dispatcher.js +24 -3
  126. data/lib/clacky/web/ws.js +16 -4
  127. data/lib/clacky/work/service.rb +544 -0
  128. data/lib/clacky/work/store.rb +57 -0
  129. data/lib/clacky.rb +1 -0
  130. metadata +35 -1
@@ -7,253 +7,230 @@ disable-model-invocation: false
7
7
  user-invocable: true
8
8
  ---
9
9
 
10
- # Cron Task Creator
11
-
12
- A skill for creating, managing, and running scheduled automated tasks in Clacky.
13
-
14
- ## Architecture Overview
15
-
16
- ```
17
- Storage:
18
- ~/.clacky/tasks/<name>.md # Task prompt file (self-contained AI instruction)
19
- ~/.clacky/schedules.yml # All scheduled plans (YAML list)
20
- ~/.clacky/logger/clacky-*.log # Execution logs (daily rotation)
21
-
22
- API Base: http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}
23
-
24
- Cron-Tasks API (unified — manages task file + schedule together):
25
- GET /api/cron-tasks → list all cron tasks with schedule info
26
- POST /api/cron-tasks → create task + schedule {name, content, cron, enabled?}
27
- PATCH /api/cron-tasks/:name → update {content?, cron?, enabled?}
28
- DELETE /api/cron-tasks/:name → delete task file + schedule
29
- POST /api/cron-tasks/:name/run → execute immediately (creates a new session)
30
- ```
31
-
32
- ## Cron Expression Quick Reference
33
-
34
- | Expression | Meaning |
35
- |-----------------|---------------------------|
36
- | `0 9 * * 1-5` | Weekdays at 09:00 |
37
- | `0 9 * * *` | Every day at 09:00 |
38
- | `0 */2 * * *` | Every 2 hours |
39
- | `*/30 * * * *` | Every 30 minutes |
40
- | `0 19 * * *` | Every day at 19:00 |
41
- | `0 8 * * 1` | Every Monday at 08:00 |
42
- | `0 0 1 * *` | First day of every month |
43
-
44
- Field order: `minute hour day-of-month month day-of-week`
45
10
 
46
- ---
47
-
48
- ## Operations
11
+ # Cron Task Creator
49
12
 
50
- ### 1. LIST — Show all tasks
13
+ Create and manage scheduled tasks through the existing cron-task API. This skill
14
+ supports both ordinary tasks and secretary work; they share plan management but
15
+ have different execution and result destinations.
16
+
17
+ ## Determine the task type
18
+
19
+ For an **existing plan**, GET its saved metadata first. Its saved target determines
20
+ its type, regardless of which conversation is currently managing it:
21
+
22
+ | Saved plan | Execution | Result/history |
23
+ |---|---|---|
24
+ | No target (including older plans) | Ordinary agent session | Tasks run history and execution session |
25
+ | target.type = secretary_work | Work card and worker session | Owning secretary conversation and work card |
26
+
27
+ Do not convert an old ordinary task to secretary work because it is opened from a
28
+ secretary conversation. PATCH preserves the target. Do not recreate a plan just
29
+ to edit it. Moving an existing plan to another execution type or owner is not a
30
+ PATCH capability; explain this if the user requests it and establish the intended
31
+ replacement before creating/deleting anything.
32
+
33
+ For a **new plan**:
34
+
35
+ - In an ordinary conversation, create an ordinary task as before.
36
+ - In a known secretary conversation, create secretary work by default, unless the
37
+ user explicitly requests an independent ordinary task.
38
+ - CLACKY_SESSION_ID exists for ordinary sessions too; its presence alone does not
39
+ identify a secretary. Use the current agent role, not the task title (e.g.
40
+ "morning report"), to choose the default.
41
+ - Secretary workers currently support read/research work. Do not silently send a
42
+ task requiring writes, shell execution, email sending or booking to a worker
43
+ that cannot perform it. Explain the mismatch and clarify the intended execution
44
+ or report-only scope. Ordinary tasks retain their existing tools/permissions.
45
+
46
+ Both types use server-local cron time. Only ask for missing requirements; do not
47
+ introduce an extra confirmation when the user's intent is already clear.
48
+
49
+ ## API and storage
50
+
51
+ Base URL: `http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}`.
52
+ Use the server's configured authentication if required; do not print credentials.
53
+
54
+ | Operation | Endpoint |
55
+ |---|---|
56
+ | List plans | GET /api/cron-tasks |
57
+ | Create | POST /api/cron-tasks |
58
+ | Edit or enable/disable | PATCH /api/cron-tasks/:name |
59
+ | Delete | DELETE /api/cron-tasks/:name |
60
+ | Run once now | POST /api/cron-tasks/:name/run |
61
+ | Ordinary run history | GET /api/cron-runs?task=:name |
62
+ | Secretary work history | GET /api/ext/secretary/work?session_id=:owner |
63
+
64
+ Prompts are stored in `~/.clacky/tasks/<name>.md`; plans are stored in
65
+ `~/.clacky/schedules.yml`. Use the API for changes rather than editing these files.
66
+ GET returns name, title, content, cron, enabled, next_run, last_run and optional target.
67
+ `name` is a stable ASCII identifier; `title` is the human-readable label. Names are
68
+ global, not per conversation. Always inspect the response and handle errors before
69
+ reporting success.
70
+
71
+ ## 1. List and select
51
72
 
52
73
  ```bash
53
- curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks
74
+ curl -s "http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks"
54
75
  ```
55
76
 
56
- Display each task: name, cron schedule, enabled status, content preview.
57
-
58
- If no tasks exist, inform the user and offer to create one or show templates.
77
+ For "all my scheduled tasks", show both types. For "this secretary's plans",
78
+ filter target.owner_session_id to the actual current CLACKY_SESSION_ID. When the
79
+ user names an existing plan, resolve it from the list, including ordinary plans.
80
+ If names/titles are ambiguous, clarify before mutating. Do not select another
81
+ secretary's similarly named plan by accident; an explicit request to manage a
82
+ particular existing plan may refer to a different conversation.
59
83
 
60
- **Key tip**: Remind the user that the Clacky WebUI Task Panel (sidebar → Tasks) also shows all tasks and supports direct management.
84
+ Display the plan's `title` when present, falling back to `name`, together with time,
85
+ enabled state, next run and result destination. Include ordinary last_run status when
86
+ available; do not interpret a secretary plan's empty cron last_run as "never executed".
87
+ Use its work history below. The existing WebUI Tasks panel remains the global
88
+ management surface; the secretary Work panel shows that conversation's plans and work.
61
89
 
62
- ---
63
-
64
- ### 2. CREATE — New task
90
+ ## 2. Create
65
91
 
66
- **Step 1: Gather required info** (only ask for what's missing)
67
- - What should the task DO? (goal, behavior, output format)
68
- - How often should it run? (or is it manual-only without a schedule?)
69
- - Any specific parameters? (URLs, file paths, output location, language)
92
+ Gather the objective, frequency, sources and required output. Write a self-contained
93
+ prompt: each execution starts a fresh session. Include needed paths/URLs, report
94
+ scope, language and output requirements. Secretary workers receive recent work
95
+ summaries, but do not automatically have mailbox/calendar access or the full
96
+ conversation. Do not promise unavailable sources or actions.
70
97
 
71
- **Step 2: Generate task name**
72
- - Rule: only `[a-z0-9_-]`, lowercase, no spaces
73
- - Examples: `daily_report`, `price_monitor`, `weekly_summary`
98
+ Choose a distinct lowercase `name` using `[a-z0-9_-]` — it becomes the task file
99
+ name and API path. Also set a short `title` in the user's language; this is what the
100
+ Tasks panel and cron sessions display. Check existing names first. Do not use POST
101
+ to overwrite a plan; use PATCH when editing the intended plan.
74
102
 
75
- **Step 3: Write the task prompt**
103
+ Ordinary task payload (the existing format remains valid):
76
104
 
77
- The prompt must be:
78
- - **Self-contained**: the agent running it has zero prior context — include everything needed
79
- - **Written as direct instructions** to an AI agent (imperative, not conversational)
80
- - **Detailed**: include URLs, file paths, output format, language, expected output location
81
-
82
- Good task prompt example:
105
+ ```json
106
+ {
107
+ "name": "daily_file_summary",
108
+ "title": "Daily file summary",
109
+ "content": "Read the specified project notes and write the requested daily summary to the agreed output path. Include the actual paths and acceptance criteria here.",
110
+ "cron": "0 9 * * *",
111
+ "enabled": true
112
+ }
83
113
  ```
84
- You are a price monitoring assistant. Complete the following task:
85
-
86
- ## Goal
87
- Check the current BTC price on CoinGecko, compare with yesterday's price, and log an alert if the change exceeds 5%.
88
114
 
89
- ## Steps
90
- 1. Fetch https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd&include_24hr_change=true
91
- 2. Parse the JSON response to get current price and 24h change
92
- 3. If |change| > 5%, write an alert to ~/price_alerts/alert_YYYY-MM-DD.txt
93
- 4. Print the current price and change percentage
115
+ For secretary work, use the same payload fields and add:
94
116
 
95
- Execute immediately.
117
+ ```json
118
+ {
119
+ "name": "morning_report",
120
+ "title": "Morning report",
121
+ "content": "Summarize current work progress, completed items, blockers and decisions needed. Report in the user's requested language through the secretary.",
122
+ "cron": "0 9 * * *",
123
+ "enabled": true,
124
+ "owner_session_id": "<actual current CLACKY_SESSION_ID>"
125
+ }
96
126
  ```
97
127
 
98
- **Step 4: Create via API**
128
+ Read the actual session ID from the terminal environment; never submit the
129
+ placeholder or guess an ID. The API validates that the owner is a secretary.
130
+ Omit owner_session_id for ordinary tasks. Do not send a raw target hash.
131
+ For secretary notifications, use the existing X-Lang header (zh/en) when the
132
+ user's language is known.
99
133
 
100
- ```bash
101
- curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks \
102
- -H "Content-Type: application/json" \
103
- -d '{
104
- "name": "task_name",
105
- "content": "task prompt content...",
106
- "cron": "0 9 * * *",
107
- "enabled": true
108
- }'
109
- ```
110
-
111
- **Step 5: Confirm creation**
112
-
113
- ```
114
- ✅ Task created successfully!
115
-
116
- 📋 Task name: daily_standup
117
- ⏰ Schedule: Weekdays at 09:00 (cron: 0 9 * * 1-5)
118
-
119
- View and manage this task in the Clacky WebUI → Tasks panel. Click ▶ Run to execute immediately.
120
- ```
134
+ Serialize the selected payload into a temporary JSON file, preserving literal
135
+ user text. Then POST it with `Content-Type: application/json` and
136
+ `--data-binary @<payload-file>`; do not interpolate user content into shell code.
137
+ The API requires a cron expression, even for a plan initially disabled.
121
138
 
122
- ---
139
+ After success, confirm the time and destination:
123
140
 
124
- ### 3. EDIT — Modify an existing task
141
+ - Ordinary: the task runs in an independent session; results are available in
142
+ Tasks / the execution session (plus any output explicitly requested).
143
+ - Secretary: each occurrence creates work and reports back to its owning
144
+ secretary conversation. The Work panel shows progress.
125
145
 
126
- **Step 1**: Identify the task (if unclear, LIST first and ask)
146
+ Do not tell users that an ordinary task will report to the current conversation.
127
147
 
128
- **Step 2**: Show current state via LIST or ask user to confirm
148
+ ## 3. Edit
129
149
 
130
- **Step 3**: Update via API
150
+ Read the selected plan, retain its type and owner, and PATCH only requested fields:
131
151
 
132
- ```bash
133
- # Update content only
134
- curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name \
135
- -H "Content-Type: application/json" \
136
- -d '{"content": "new prompt content..."}'
137
-
138
- # Update cron schedule only
139
- curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name \
140
- -H "Content-Type: application/json" \
141
- -d '{"cron": "0 8 * * 1-5"}'
142
-
143
- # Update both
144
- curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name \
145
- -H "Content-Type: application/json" \
146
- -d '{"content": "...", "cron": "0 8 * * 1-5"}'
152
+ ```json
153
+ {"cron": "0 18 * * *"}
147
154
  ```
148
155
 
149
- **Step 4**: Confirm changes
150
-
151
- ```
152
- ✅ Task updated!
153
- 📋 daily_standup
154
- Schedule: 0 9 * * 1-5 → 0 8 * * 1-5 (now weekdays at 08:00)
156
+ ```json
157
+ {"content": "Updated self-contained instructions"}
155
158
  ```
156
159
 
157
- ---
160
+ The supported fields are title, content, cron and enabled. Omitted fields remain
161
+ intact; an empty title clears it and falls back to name. Neither owner_session_id
162
+ nor target is editable through this endpoint. Report the actual changed fields
163
+ after success. Editing an ordinary task from a secretary conversation leaves it
164
+ ordinary; editing secretary work from another conversation leaves its result
165
+ destination unchanged.
158
166
 
159
- ### 4. ENABLE / DISABLE — Toggle a task
167
+ ## 4. Enable or disable
160
168
 
161
- ```bash
162
- # Disable
163
- curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name \
164
- -H "Content-Type: application/json" \
165
- -d '{"enabled": false}'
166
-
167
- # Enable
168
- curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name \
169
- -H "Content-Type: application/json" \
170
- -d '{"enabled": true}'
171
- ```
169
+ PATCH `{"enabled": false}` to pause future occurrences, or
170
+ `{"enabled": true}` to enable them. Re-enabling starts from the next future slot;
171
+ it does not backfill the disabled period.
172
172
 
173
- Confirm:
174
- ```
175
- ✅ daily_standup has been disabled.
176
- To re-enable: say "enable daily_standup"
177
- ```
178
-
179
- ---
180
-
181
- ### 5. DELETE — Remove a task
182
-
183
- Always confirm before deleting (unless the user has explicitly said to delete):
184
-
185
- ```
186
- ⚠️ Are you sure you want to delete daily_standup? This cannot be undone.
187
- ```
188
-
189
- ```bash
190
- curl -s -X DELETE http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name
191
- ```
192
-
193
- ---
194
-
195
- ### 6. HISTORY — View run history
196
-
197
- Read the daily log files directly:
198
-
199
- ```bash
200
- grep "task_name" ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log | tail -20
201
- ```
202
-
203
- Or search across recent days:
204
- ```bash
205
- grep -h "task_name" ~/.clacky/logger/clacky-*.log | tail -30
206
- ```
173
+ For both types, disabling a plan does not interrupt an execution already created.
174
+ For secretary work, if the user also wants an existing work item paused/cancelled,
175
+ handle that separately through the owning secretary's work-management path.
176
+ manage_work manages work cards, not cron plans.
177
+
178
+ ## 5. Delete
207
179
 
208
- Display format:
209
- ```
210
- 📊 Run History: ai_news_x_daily
180
+ DELETE the selected plan by its exact name. An explicit deletion request already
181
+ authorizes deletion; clarify only if the intended plan is ambiguous. Explain that
182
+ removing the plan stops future occurrences, not existing executions or their
183
+ history. Do not cancel a work card merely because its plan was deleted.
211
184
 
212
- Mar 10 19:00 ❌ Failed — JSON::ParserError: unexpected end of input
213
- Mar 09 19:00 ✅ Success — took 1m 42s
214
- Mar 08 19:00 ✅ Success — took 2m 10s
215
- ```
185
+ ## 6. History and results
216
186
 
217
- ---
187
+ Use the saved type, not the current conversation, to choose the history source:
218
188
 
219
- ### 7. RUN NOW — Execute immediately
189
+ - Ordinary: GET /api/cron-runs with task set to the plan's name. Show statuses and
190
+ link/reference the returned execution session. Logs under ~/.clacky/logger/
191
+ can help diagnose failures if run metadata is insufficient.
192
+ - Secretary: GET /api/ext/secretary/work with session_id set to the saved
193
+ target.owner_session_id. Select cards whose schedule_name equals the plan name.
194
+ Show scheduled_at, status and progress; use the card's session_id for execution
195
+ details. Results return to the saved owner. Do not use cron-run history as the
196
+ source of completion status for these plans.
220
197
 
221
- ```bash
222
- curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/cron-tasks/task_name/run
223
- ```
198
+ Missing records are not evidence of success or failure. Describe what is known.
224
199
 
225
- This creates a new session. Tell the user:
226
- ```
227
- ▶️ Task started in a new session.
228
- View it in the Clacky WebUI → Sessions panel.
229
- ```
200
+ ## 7. Run now
230
201
 
231
- ---
202
+ POST /api/cron-tasks/:name/run for either type. This does not change the recurrence.
232
203
 
233
- ### 8. TEMPLATES — Browse common task templates
204
+ - Ordinary: the API prepares an execution session. Open the returned session in
205
+ the existing UI to start/view the pending run. Do not claim completion from 202.
206
+ - Secretary: the API queues a work card and returns its worker session. The result
207
+ will return to the saved secretary owner, even if requested from another chat.
208
+ If 409 reports an unfinished previous work or unavailable owner, explain the
209
+ blocker; do not bypass it by creating an ordinary task or a duplicate plan.
234
210
 
235
- When user says "what templates are there" or "what can I automate":
211
+ ## Timing and templates
236
212
 
237
- ```
238
- 📚 Common Task Templates — pick one to get started:
239
-
240
- 1. 📰 AI News Digest — Daily fetch of AI news from X/RSS, generate Markdown report
241
- 2. 💰 Price Monitor — Check crypto/stock prices on a schedule, log alerts on anomalies
242
- 3. 📊 Weekly Work Summary — Every Monday, summarize last week's work into a report
243
- 4. 🌤 Weather Reminder — Fetch weather every morning and save to file
244
- 5. 🔍 Competitor Monitor — Periodically scrape competitor sites for changes
245
- 6. 📝 Journal Prompt — Evening reminder to journal with daily reflection questions
246
- 7. 🔗 Link Health Check — Periodically verify specified URLs are accessible
247
- 8. 📂 File Backup — Regularly back up a specified directory to another location
248
-
249
- Tell me which one interests you, or describe your own use case!
250
- ```
213
+ The server checks schedules roughly once per minute and must be running/resumed.
214
+ Cron does not wake a paused sandbox. Tracked missed occurrences collapse to the
215
+ latest one. Older plans without a stored cursor begin tracking when first loaded;
216
+ do not promise recovery of a pre-upgrade backlog.
251
217
 
252
- ---
218
+ For secretary plans, only one unfinished work item per plan is allowed. A waiting,
219
+ paused, failed or decision-needed item blocks the next occurrence until resolved
220
+ or cancelled. Ordinary plans retain their existing execution behavior; do not
221
+ apply this worker restriction to them.
253
222
 
254
- ## Important Notes
223
+ | Expression | Meaning in server-local time |
224
+ |---|---|
225
+ | 0 9 * * 1-5 | Weekdays at 09:00 |
226
+ | 0 9 * * * | Daily at 09:00 |
227
+ | 0 20 * * * | Daily at 20:00 |
228
+ | 0 */2 * * * | Every two hours |
229
+ | */30 * * * * | Every 30 minutes |
230
+ | 0 9 1 * * | First day of each month at 09:00 |
255
231
 
256
- - Task names: only `[a-z0-9_-]`, no spaces, no uppercase
257
- - Task prompt files must be **self-contained** — the executing agent has no prior memory
258
- - Clacky server must be running for cron to trigger automatically (checked every minute)
259
- - The WebUI Task Panel is the preferred interface for managing tasks — always remind the user to check it after changes
232
+ Offer templates appropriate to the selected execution type. Research digests,
233
+ work-progress reports and competitor monitoring can fit secretary workers.
234
+ File-writing reports, backups and shell-based checks use ordinary task capabilities
235
+ and permissions. Include actual inputs and output requirements before creating a
236
+ template-derived task; a template is not proof that a data source is connected.
@@ -33,6 +33,51 @@
33
33
  "显示了变更前后的对比",
34
34
  "任务文件内容未被修改"
35
35
  ]
36
+ },
37
+ {
38
+ "id": 4,
39
+ "prompt": "当前是普通会话。帮我每天早上9点生成一份早报,在独立执行会话里查看。",
40
+ "expected_output": "使用原有 cron API 创建普通任务,不因早报名称而添加秘书归属。",
41
+ "assertions": [
42
+ "POST 不包含 owner_session_id",
43
+ "使用 cron 0 9 * * *",
44
+ "说明独立执行会话的结果位置,不承诺回到当前对话"
45
+ ]
46
+ },
47
+ {
48
+ "id": 5,
49
+ "prompt": "当前是秘书会话,CLACKY_SESSION_ID 是有效秘书会话。每天晚上8点汇总我的工作进展,并在这里告诉我。",
50
+ "expected_output": "通过同一个 cron skill/API 创建有秘书归属的计划。",
51
+ "assertions": [
52
+ "从环境读取实际 CLACKY_SESSION_ID 作为 owner_session_id",
53
+ "使用 cron 0 20 * * *",
54
+ "不调用 manage_work 创建计划",
55
+ "说明结果回到归属秘书会话",
56
+ "不要求 timezone 参数"
57
+ ]
58
+ },
59
+ {
60
+ "id": 6,
61
+ "prompt": "当前是秘书会话。把旧任务 daily_file_summary 改到每天18点。GET 显示该计划没有 target。",
62
+ "expected_output": "只 PATCH cron,保留普通任务执行方式。",
63
+ "assertions": [
64
+ "使用 PATCH 而非删除重建",
65
+ "只修改 cron 为 0 18 * * *",
66
+ "不添加 owner_session_id 或改变执行类型",
67
+ "不修改任务内容"
68
+ ]
69
+ },
70
+ {
71
+ "id": 7,
72
+ "prompt": "当前是普通会话。查看 morning_report 的结果并立刻运行一次。GET 显示该计划 target.type 为 secretary_work,归属会话为 secretary_a。",
73
+ "expected_output": "依据保存的秘书目标选择工作历史和运行结果目的地。",
74
+ "assertions": [
75
+ "通过归属会话的 work API 并按 schedule_name 查询工作记录",
76
+ "调用原 cron run API",
77
+ "说明结果仍回到 secretary_a,不回到当前会话",
78
+ "不将缺少 cron last_run 当作没有执行过",
79
+ "409 时不绕过限制创建普通任务"
80
+ ]
36
81
  }
37
82
  ]
38
83
  }
@@ -159,7 +159,7 @@ Common `error_type` values: `not_configured`, `auth_required`, `network_error`,
159
159
 
160
160
  ## Step 3 — Show the image
161
161
 
162
- `Read` does NOT show the image to the user — it only feeds it into your own context. To make the user actually see it, write a markdown tag in your reply:
162
+ `Read` does NOT show the image to the user — it only feeds it into your own context. To make the user actually see it, write exactly one markdown tag in your reply and nothing else for that file:
163
163
 
164
164
  ```markdown
165
165
  ![](file:///abs/path/from/response.png)
@@ -190,10 +190,19 @@ When the user gives a vague request like "给我配张图", ask one clarifying q
190
190
  - The user wants a **diagram / chart** with specific data — use a charting library (matplotlib, mermaid, etc.) instead; image gen is for illustrations, not data viz
191
191
  - The user asks for **screenshots** of real software — use the browser tool
192
192
 
193
- ## Generating video (Veo)
193
+ ## Generating video (Gemini Omni / Veo)
194
194
 
195
195
  The same `/api/media/` namespace serves video generation. The user must
196
- configure a `type=video` model in settings (recommended: `or-veo-3-1`).
196
+ configure a `type=video` model in settings (recommended: `or-gemini-omni-flash`).
197
+
198
+ | Model | Duration | Notes |
199
+ |------------------------|----------|-------|
200
+ | `or-gemini-omni-flash` | 3–15 s | Default. Newest, ~$0.07/s at 720p. |
201
+ | `or-veo-3-1` | 4–8 s | Best cinematic quality, ~$0.40/s. |
202
+ | `or-veo-3-1-fast` | 4–8 s | ~$0.10/s. |
203
+ | `or-veo-3-1-lite` | 4–8 s | Cheapest, ~$0.05/s. |
204
+
205
+ Out-of-range durations are clamped by the gateway, not rejected.
197
206
 
198
207
  ### Endpoint
199
208
 
@@ -231,7 +240,7 @@ curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/media/vid
231
240
  |--------------------|----------|---------------------------------|-------|
232
241
  | `prompt` | yes | string | Same prompt-craft tips as images apply. |
233
242
  | `aspect_ratio` | no | `landscape` / `portrait` | Defaults to `landscape` (16:9). |
234
- | `duration_seconds` | no | 4–8 | Defaults to 8. |
243
+ | `duration_seconds` | no | 3–15 (Omni) / 4–8 (Veo) | Defaults to 8. |
235
244
  | `image` | no | `{ "b64_json": "...", "mime_type": "image/png" }` | Optional first frame for image-to-video. |
236
245
  | `output_dir` | no | absolute path | The exact directory the file is written to — nothing is appended. Use the directory the user asked for; otherwise `$(pwd)/assets/generated` as shown in the example. |
237
246
  | `session_id` | yes | string | Current Clacky session ID. Always pass the rendered value shown in the request example. |
@@ -251,9 +260,17 @@ curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/media/vid
251
260
  }
252
261
  ```
253
262
 
254
- The `video` field is an absolute path on disk. Show it to the user with a
255
- markdown link or an HTML5 `<video>` tag pointing at the `file://` path; embed
256
- it in documents with a path relative to the document.
263
+ The `video` field is an absolute path on disk. To let the user watch it, write
264
+ exactly one markdown tag in your reply and nothing else for that file:
265
+
266
+ ```markdown
267
+ ![clip.mp4](file:///abs/path/from/response.mp4)
268
+ ```
269
+
270
+ The Web UI turns this into an inline player on its own — do NOT also write an
271
+ HTML `<video>` tag or a second plain `[link]`, or the clip shows up twice. If
272
+ you're embedding it in a document, convert the path to one relative to that
273
+ document.
257
274
 
258
275
  ### Response (failure)
259
276
 
@@ -262,10 +279,10 @@ Same shape and `error_type` values as image generation, but with `"video": null`
262
279
 
263
280
  ### Continuous / long video (last-frame chaining)
264
281
 
265
- A single Veo call maxes out at 8 seconds, and separate calls are visually
282
+ A single call maxes out at 15 seconds (Omni) or 8 seconds (Veo), and separate calls are visually
266
283
  **unrelated** (the character, lighting and framing jump between clips). To make
267
284
  several clips flow as one continuous shot, chain them: take the **last frame**
268
- of clip N and feed it as the `image` (first frame) of clip N+1. Veo's
285
+ of clip N and feed it as the `image` (first frame) of clip N+1. The model's
269
286
  image-to-video then continues from exactly where the previous clip ended, so
270
287
  the seam is smooth.
271
288
 
@@ -320,9 +337,9 @@ Rules & caveats:
320
337
  slower re-encode (and may letterbox). Use the same `aspect_ratio` everywhere.
321
338
  - **Cost adds up linearly** — N segments ≈ N × single-clip price. Confirm the
322
339
  number of segments and total length with the user before starting.
323
- - For >30s or a true single-take >8s with no seam at all, this client-side
324
- chaining is the practical option today; Veo's native server-side `extend`
325
- (148s) is not wired into this endpoint yet.
340
+ - For >30s or a true single-take longer than one clip with no seam at all,
341
+ this client-side chaining is the practical option today; the native
342
+ server-side `extend` (Veo / Omni) is not wired into this endpoint yet.
326
343
 
327
344
  ### Seedance — multimodal video
328
345
 
@@ -571,10 +588,10 @@ The `audio` field is an absolute path on disk. Output is mono 16-bit PCM at
571
588
  24 kHz wrapped in a standard WAV container — playable by any browser, OS
572
589
  player, or `<audio>` tag without conversion.
573
590
 
574
- To let the user hear it, write a markdown link in your reply:
591
+ To let the user hear it, write exactly one markdown tag in your reply:
575
592
 
576
593
  ```markdown
577
- [🔊 听一下](file:///abs/path/from/response.wav)
594
+ ![response.wav](file:///abs/path/from/response.wav)
578
595
  ```
579
596
 
580
597
  For embedding in HTML documents, use:
@@ -493,7 +493,6 @@ Use the `read` tool. Expect YAML frontmatter:
493
493
  ---
494
494
  topic: <topic>
495
495
  description: <one-line>
496
- updated_at: YYYY-MM-DD
497
496
  ---
498
497
 
499
498
  <body in Markdown>
@@ -506,7 +505,7 @@ If parsing fails, continue — frontmatter is advisory.
506
505
  2–4 short sentences. Quote the topic + most concrete facts. Don't dump the file.
507
506
 
508
507
  Example (en):
509
- > This memory is about **Ruby style preferences** (updated 2026-04-10):
508
+ > This memory is about **Ruby style preferences**:
510
509
  > you prefer inline `private def` over a standalone `private` keyword,
511
510
  > and frozen string literals on all new files.
512
511
 
@@ -538,17 +537,16 @@ zh:
538
537
 
539
538
  ### C.6a. "Leave it"
540
539
 
541
- Bump `updated_at` to today, write back. Tell the user you've confirmed it's current.
540
+ Run `touch <path>` with the terminal tool instead of rewriting the file. Tell the user you've confirmed it's current.
542
541
 
543
542
  ### C.6b. "Update"
544
543
 
545
544
  Ask ONE follow-up (free text) for what changed. Then:
546
545
 
547
546
  1. Merge into the body. Rewrite in place for stale facts; append for net-new.
548
- 2. Update `updated_at` to today.
549
- 3. Keep under **300 words** — distill, don't accumulate.
550
- 4. Write back with the same frontmatter keys.
551
- 5. Show a short diff-style summary.
547
+ 2. Keep under **300 words** — distill, don't accumulate.
548
+ 3. Write back with the same `topic` / `description` keys. Drop any legacy `updated_at` key.
549
+ 4. Show a short diff-style summary.
552
550
 
553
551
  ### C.6c. "Delete"
554
552