openclacky 1.5.21 → 1.5.23

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 (110) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +119 -0
  3. data/docs/secretary-prototype.md +286 -0
  4. data/lib/clacky/agent/session_serializer.rb +15 -11
  5. data/lib/clacky/agent.rb +58 -15
  6. data/lib/clacky/agent_config.rb +3 -1
  7. data/lib/clacky/agent_profile.rb +33 -6
  8. data/lib/clacky/billing/platform_billing.rb +9 -0
  9. data/lib/clacky/default_extensions/advisor/README.md +25 -0
  10. data/lib/clacky/default_extensions/advisor/README.zh.md +25 -0
  11. data/lib/clacky/default_extensions/advisor/ext.yml +1 -1
  12. data/lib/clacky/default_extensions/advisor/icon.svg +14 -0
  13. data/lib/clacky/default_extensions/coding/ext.yml +0 -1
  14. data/lib/clacky/default_extensions/computer-use/README.md +48 -0
  15. data/lib/clacky/default_extensions/computer-use/README.zh.md +48 -0
  16. data/lib/clacky/default_extensions/computer-use/ext.yml +1 -1
  17. data/lib/clacky/default_extensions/computer-use/icon.svg +16 -0
  18. data/lib/clacky/default_extensions/ext-studio/ext.yml +0 -1
  19. data/lib/clacky/default_extensions/general/ext.yml +0 -1
  20. data/lib/clacky/default_extensions/git/README.md +41 -0
  21. data/lib/clacky/default_extensions/git/README.zh.md +41 -0
  22. data/lib/clacky/default_extensions/git/ext.yml +1 -1
  23. data/lib/clacky/default_extensions/git/icon.svg +15 -0
  24. data/lib/clacky/default_extensions/git/panels/git/view.js +1960 -399
  25. data/lib/clacky/default_extensions/meeting/README.md +46 -0
  26. data/lib/clacky/default_extensions/meeting/README.zh.md +47 -0
  27. data/lib/clacky/default_extensions/meeting/ext.yml +1 -1
  28. data/lib/clacky/default_extensions/meeting/icon.svg +13 -0
  29. data/lib/clacky/default_extensions/preview/README.md +29 -0
  30. data/lib/clacky/default_extensions/preview/README.zh.md +29 -0
  31. data/lib/clacky/default_extensions/preview/ext.yml +1 -1
  32. data/lib/clacky/default_extensions/preview/icon.svg +13 -0
  33. data/lib/clacky/default_extensions/preview/panels/preview/view.js +199 -34
  34. data/lib/clacky/default_extensions/secretary/agents/secretary.md +41 -0
  35. data/lib/clacky/default_extensions/secretary/agents/worker.md +35 -0
  36. data/lib/clacky/default_extensions/secretary/api/handler.rb +8 -0
  37. data/lib/clacky/default_extensions/secretary/ext.yml +39 -0
  38. data/lib/clacky/default_extensions/secretary/panels/work/view.js +344 -0
  39. data/lib/clacky/default_extensions/secretary/tools/delegate_work.rb +37 -0
  40. data/lib/clacky/default_extensions/secretary/tools/manage_work.rb +22 -0
  41. data/lib/clacky/default_extensions/secretary/tools/yield_work.rb +35 -0
  42. data/lib/clacky/default_extensions/time_machine/README.md +32 -0
  43. data/lib/clacky/default_extensions/time_machine/README.zh.md +32 -0
  44. data/lib/clacky/default_extensions/time_machine/ext.yml +1 -1
  45. data/lib/clacky/default_extensions/time_machine/icon.svg +14 -0
  46. data/lib/clacky/default_skills/channel-manager/SKILL.md +79 -8
  47. data/lib/clacky/default_skills/channel-manager/discord_setup.rb +5 -1
  48. data/lib/clacky/default_skills/channel-manager/weixin_setup.rb +8 -1
  49. data/lib/clacky/default_skills/cron-task-creator/SKILL.md +183 -206
  50. data/lib/clacky/default_skills/cron-task-creator/evals/evals.json +45 -0
  51. data/lib/clacky/default_skills/media-gen/SKILL.md +17 -8
  52. data/lib/clacky/extension/api_extension.rb +10 -2
  53. data/lib/clacky/extension/loader.rb +2 -0
  54. data/lib/clacky/extension/verifier.rb +2 -2
  55. data/lib/clacky/locales/en.rb +14 -0
  56. data/lib/clacky/locales/zh.rb +14 -0
  57. data/lib/clacky/prompts/base.md +1 -1
  58. data/lib/clacky/providers.rb +68 -31
  59. data/lib/clacky/search_config.rb +33 -11
  60. data/lib/clacky/server/channel/adapters/base.rb +18 -0
  61. data/lib/clacky/server/channel/adapters/feishu/message_parser.rb +1 -0
  62. data/lib/clacky/server/channel/adapters/telegram/adapter.rb +1 -0
  63. data/lib/clacky/server/channel/channel_config.rb +185 -48
  64. data/lib/clacky/server/channel/channel_manager.rb +179 -66
  65. data/lib/clacky/server/git_panel.rb +362 -35
  66. data/lib/clacky/server/http_server.rb +530 -181
  67. data/lib/clacky/server/preview.rb +118 -17
  68. data/lib/clacky/server/scheduler.rb +211 -51
  69. data/lib/clacky/server/web_ui_controller.rb +35 -27
  70. data/lib/clacky/session_manager.rb +56 -6
  71. data/lib/clacky/tools/base.rb +7 -1
  72. data/lib/clacky/utils/file_processor.rb +20 -10
  73. data/lib/clacky/utils/mac_app_detector.rb +8 -7
  74. data/lib/clacky/utils/model_pricing.rb +60 -2
  75. data/lib/clacky/utils/windows_app_detector.rb +3 -1
  76. data/lib/clacky/version.rb +1 -1
  77. data/lib/clacky/web/app.css +1114 -205
  78. data/lib/clacky/web/app.js +143 -8
  79. data/lib/clacky/web/auth.js +1 -1
  80. data/lib/clacky/web/components/code-editor.js +73 -4
  81. data/lib/clacky/web/components/composer.js +107 -8
  82. data/lib/clacky/web/components/image-zoom.js +165 -0
  83. data/lib/clacky/web/components/model-picker.js +7 -5
  84. data/lib/clacky/web/components/notify.js +39 -12
  85. data/lib/clacky/web/components/onboard.js +1 -1
  86. data/lib/clacky/web/core/aside.js +60 -3
  87. data/lib/clacky/web/features/billing/view.js +2 -2
  88. data/lib/clacky/web/features/channels/store.js +19 -4
  89. data/lib/clacky/web/features/channels/view.js +92 -28
  90. data/lib/clacky/web/features/extensions/view.js +17 -10
  91. data/lib/clacky/web/features/new-session/store.js +79 -2
  92. data/lib/clacky/web/features/new-session/view.js +516 -75
  93. data/lib/clacky/web/features/skills/store.js +1 -1
  94. data/lib/clacky/web/features/tasks/store.js +5 -3
  95. data/lib/clacky/web/features/tasks/view.js +249 -66
  96. data/lib/clacky/web/features/workspace/store.js +13 -6
  97. data/lib/clacky/web/features/workspace/view.js +340 -214
  98. data/lib/clacky/web/i18n.js +366 -68
  99. data/lib/clacky/web/index.html +196 -165
  100. data/lib/clacky/web/projects.js +37 -4
  101. data/lib/clacky/web/sessions.js +263 -146
  102. data/lib/clacky/web/settings.js +241 -53
  103. data/lib/clacky/web/skills.js +2 -2
  104. data/lib/clacky/web/theme.js +17 -2
  105. data/lib/clacky/web/utils.js +234 -2
  106. data/lib/clacky/web/weixin-qr.html +2 -1
  107. data/lib/clacky/web/ws-dispatcher.js +14 -31
  108. data/lib/clacky/work/service.rb +542 -0
  109. data/lib/clacky/work/store.rb +57 -0
  110. metadata +31 -1
@@ -34,12 +34,41 @@ Configure IM platform channels for openclacky.
34
34
  | `channel status` | status |
35
35
  | `channel enable feishu/wecom/weixin/discord/telegram/dingtalk/qq` | enable |
36
36
  | `channel disable feishu/wecom/weixin/discord/telegram/dingtalk/qq` | disable |
37
+ | `channel remove`, `channel delete` | remove |
37
38
  | `channel reconfigure` | reconfigure |
38
39
  | `channel doctor` | doctor |
39
40
  | `send <message> to weixin/feishu/wecom/discord/telegram/dingtalk/qq` | send |
40
41
 
41
42
  ---
42
43
 
44
+ ## Multiple instances per platform
45
+
46
+ Every platform can be connected more than once (for example a personal and a work
47
+ Feishu app, or two WeChat accounts). Each instance carries:
48
+
49
+ - `id` — stable routing identifier. The first instance is always `default`.
50
+ - `name` — display name shown in the Web UI (e.g. "Company Feishu").
51
+
52
+ Rules:
53
+
54
+ 1. Before adding an instance, ask the user for a display name (`ask_user`).
55
+ 2. Derive `instance_id` from that name as a short ASCII slug (`work`, `personal`,
56
+ `team-2`). It must match `[A-Za-z0-9][A-Za-z0-9_-]{0,39}` and must not collide
57
+ with an existing id from `GET /api/channels` → `channels[].instances[].id`.
58
+ 3. Pass BOTH fields in the same `POST /api/channels/<platform>` body that saves
59
+ the credentials:
60
+ ```json
61
+ {"instance_id":"work","name":"Company Feishu","app_id":"...","app_secret":"..."}
62
+ ```
63
+ 4. Never omit `instance_id` when adding: without it the server updates the
64
+ **default** instance and overwrites its credentials.
65
+ 5. When reconfiguring an existing instance, keep its `instance_id`; never create
66
+ a new one for the same bot.
67
+ 6. All setup flows below work unchanged for the first instance; add the two
68
+ fields above only when the user asked for an additional instance.
69
+
70
+ ---
71
+
43
72
  ## `status`
44
73
 
45
74
  Call the server API:
@@ -61,6 +90,10 @@ Response shape (example):
61
90
 
62
91
  Display the result:
63
92
 
93
+ When a platform has multiple instances, `channels[].instances` lists each one
94
+ with `id`, `name`, `enabled`, `running` and `has_config`. Report one row per
95
+ instance, e.g. `feishu (default)` and `feishu (work)`.
96
+
64
97
  ```
65
98
  Channel Status
66
99
  ─────────────────────────────────────────────────────
@@ -147,7 +180,7 @@ en: "✅ Feishu channel configured! You can now chat with the assistant via Feis
147
180
 
148
181
  #### Step 3 — Optional: install Feishu CLI
149
182
 
150
- Reach here after the channel is configured (Step 2 succeeded). Read `app_id` and `app_secret` from `~/.clacky/channels.yml` (under `channels.feishu`) for the install commands below.
183
+ Reach here after the channel is configured (Step 2 succeeded). Read `app_id` and `app_secret` from `~/.clacky/channels.yml` (under `channels.feishu`; it is now a **list** of instances — use the entry whose `id` matches the instance you just configured, otherwise the first entry) for the install commands below.
151
184
 
152
185
  Call `ask_user`:
153
186
 
@@ -222,6 +255,8 @@ On success: "✅ WeCom channel configured. WeCom client → Contacts → Smart B
222
255
 
223
256
  Weixin uses a QR code login — no app_id/app_secret needed. The token from the QR scan is saved directly in `channels.yml`.
224
257
 
258
+ For a second or later WeChat account, ask the user for a display name first, derive an `instance_id`, and pass both to the save step: `weixin_setup.rb --qrcode-id "$QRCODE_ID" --instance-id "personal" --name "Personal WeChat"`. Without `--instance-id` the token overwrites the `default` instance.
259
+
225
260
  #### Step 1 — Fetch QR code
226
261
 
227
262
  Run the script in `--fetch-qr` mode to get the QR URL without blocking:
@@ -271,6 +306,8 @@ As soon as the QR page has been presented to the user — whether you opened it
271
306
  ruby "SKILL_DIR/weixin_setup.rb" --qrcode-id "$QRCODE_ID"
272
307
  ```
273
308
 
309
+ For an additional account, append `--instance-id "<id>" --name "<display name>"` so the new token does not overwrite the existing WeChat instance.
310
+
274
311
  Where `$QRCODE_ID` is the `qrcode_id` from Step 2's JSON output.
275
312
 
276
313
  Run this command with `timeout: 60`. If it doesn't succeed, **retry up to 3 times with the same `$QRCODE_ID`** — the QR code stays valid for 5 minutes. Only stop retrying if:
@@ -455,22 +492,55 @@ curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/
455
492
 
456
493
  If the platform has no credentials (404 or error), redirect to `setup`.
457
494
 
495
+ When the platform has multiple instances, add `"instance_id":"<id>"` to the body
496
+ to enable just that instance.
497
+
458
498
  Say: "✅ `<platform>` channel enabled."
459
499
 
460
500
  ---
461
501
 
462
502
  ## `disable`
463
503
 
464
- Call the server API to disable the platform:
504
+ Call the server API to turn the platform off without touching its credentials:
505
+
506
+ ```bash
507
+ curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/enabled \
508
+ -H "Content-Type: application/json" \
509
+ -d '{"enabled": false}'
510
+ ```
511
+
512
+ This disables the first instance. To disable one specific instance, add its id:
465
513
 
466
514
  ```bash
467
- curl -s -X DELETE http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>
515
+ curl -s -X PATCH http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/enabled \
516
+ -H "Content-Type: application/json" \
517
+ -d '{"enabled": false, "instance_id": "<instance_id>"}'
468
518
  ```
469
519
 
520
+ To disable every instance, read `GET /api/channels` and send the PATCH above for
521
+ each instance id. Never use `DELETE` to turn a bot off — it removes the credentials.
522
+
470
523
  Say: "❌ `<platform>` channel disabled."
471
524
 
472
525
  ---
473
526
 
527
+ ## `remove`
528
+
529
+ Delete one instance and its credentials for good. Always confirm the target with
530
+ the user first, then call:
531
+
532
+ ```bash
533
+ curl -s -X DELETE http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/instances/<instance_id>
534
+ ```
535
+
536
+ The bot stops immediately and the entry is removed from `channels.yml`. Deleting the
537
+ last instance removes the platform entirely. If the user only wants to pause it,
538
+ use `disable` instead.
539
+
540
+ Say: "🗑️ `<platform>` instance `<name>` removed."
541
+
542
+ ---
543
+
474
544
  ### DingTalk setup
475
545
 
476
546
  #### Step 1 — Get QR code
@@ -512,7 +582,7 @@ ruby "SKILL_DIR/dingtalk_setup.rb" --poll "<device_code>"
512
582
  Check each item, report ✅ / ❌ with remediation:
513
583
 
514
584
  1. **Config file** — does `~/.clacky/channels.yml` exist and is it readable?
515
- 2. **Required keys** — for each enabled platform:
585
+ 2. **Required keys** — for each enabled platform instance (every `channels.<platform>` entry is a list of instances):
516
586
  - Feishu: `app_id`, `app_secret` present and non-empty
517
587
  - WeCom: `bot_id`, `secret` present and non-empty
518
588
  - Weixin: `token` present and non-empty in `channels.yml`
@@ -523,8 +593,8 @@ Check each item, report ✅ / ❌ with remediation:
523
593
  4. **Weixin token** (if enabled) — call `GET /api/channels` and check `has_token: true` for the weixin entry.
524
594
  5. **Telegram credentials** (if enabled) — call `getMe` against the Bot API:
525
595
  ```bash
526
- BOT_TOKEN=$(ruby -ryaml -e 'puts (YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"]["bot_token"] rescue "")')
527
- BASE_URL=$(ruby -ryaml -e 'puts (YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"]["base_url"] || "https://api.telegram.org" rescue "https://api.telegram.org")')
596
+ BOT_TOKEN=$(ruby -ryaml -e 'c=YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"] rescue nil; c=[c] if c.is_a?(Hash); i=(c||[]).first; puts(i ? i["bot_token"].to_s : "")')
597
+ BASE_URL=$(ruby -ryaml -e 'c=YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"] rescue nil; c=[c] if c.is_a?(Hash); i=(c||[]).first; puts(i && i["base_url"] ? i["base_url"] : "https://api.telegram.org")')
528
598
  curl -s "$BASE_URL/bot$BOT_TOKEN/getMe" | grep -q '"ok":true' && echo "✅ Telegram OK" || echo "❌ Telegram credentials rejected by getMe"
529
599
  ```
530
600
  6. **WeCom credentials** (if enabled) — search today's log:
@@ -567,6 +637,7 @@ Proactively send a message to a user via an IM channel adapter.
567
637
  Extract two things from the user's instruction:
568
638
  - **platform** — one of `weixin`, `feishu`, `wecom`, `discord`, `telegram`, `dingtalk`, `qq`
569
639
  - **message** — the text content to send
640
+ - **instance** (optional) — when the platform has multiple instances, ask which `name`/`id` to use and pass `instance_id` in both API calls below
570
641
 
571
642
  If the platform cannot be inferred, ask the user to clarify.
572
643
 
@@ -577,7 +648,7 @@ If the user specified a `user_id`, use it directly.
577
648
  Otherwise, list known users first:
578
649
 
579
650
  ```bash
580
- curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/users
651
+ curl -s "http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/users?instance_id=<instance_id>"
581
652
  ```
582
653
 
583
654
  - If the list is **empty**: tell the user "No known users for `<platform>`. The target user must send at least one message to the bot before proactive messaging is possible." Stop here.
@@ -589,7 +660,7 @@ curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platfor
589
660
  ```bash
590
661
  curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/<platform>/send \
591
662
  -H "Content-Type: application/json" \
592
- -d '{"message": "<message>", "user_id": "<user_id>"}'
663
+ -d '{"message": "<message>", "user_id": "<user_id>", "instance_id": "<instance_id>"}'
593
664
  ```
594
665
 
595
666
  **Response handling:**
@@ -86,7 +86,11 @@ def saved_bot_token
86
86
  yml_path = File.expand_path("~/.clacky/channels.yml")
87
87
  return nil unless File.exist?(yml_path)
88
88
  data = YAML.safe_load(File.read(yml_path), permitted_classes: [Symbol], aliases: true) rescue nil
89
- data&.dig("channels", "discord", "bot_token") || data&.dig(:channels, :discord, :bot_token)
89
+ channels = data.is_a?(Hash) ? (data["channels"] || data[:channels]) : nil
90
+ entries = channels.is_a?(Hash) ? (channels["discord"] || channels[:discord]) : nil
91
+ entries = [entries] if entries.is_a?(Hash)
92
+ first = Array(entries).find { |inst| inst.is_a?(Hash) }
93
+ first && (first["bot_token"] || first[:bot_token])
90
94
  end
91
95
 
92
96
  def save_to_server(bot_token:)
@@ -44,6 +44,10 @@ end
44
44
  FETCH_QR_MODE = ARGV.include?("--fetch-qr")
45
45
  QRCODE_ID_IDX = ARGV.index("--qrcode-id")
46
46
  GIVEN_QRCODE_ID = QRCODE_ID_IDX ? ARGV[QRCODE_ID_IDX + 1] : nil
47
+ INSTANCE_ID_IDX = ARGV.index("--instance-id")
48
+ GIVEN_INSTANCE_ID = INSTANCE_ID_IDX ? ARGV[INSTANCE_ID_IDX + 1].to_s.strip : ""
49
+ NAME_IDX = ARGV.index("--name")
50
+ GIVEN_NAME = NAME_IDX ? ARGV[NAME_IDX + 1].to_s.strip : ""
47
51
 
48
52
  # ---------------------------------------------------------------------------
49
53
  # Logging (suppress in --fetch-qr mode so stdout is clean JSON)
@@ -145,7 +149,10 @@ end
145
149
 
146
150
  def save_to_server(token:, base_url:)
147
151
  uri = URI("#{CLACKY_SERVER_URL}/api/channels/weixin")
148
- body = JSON.generate({ token: token, base_url: base_url })
152
+ body = { token: token, base_url: base_url }
153
+ body[:instance_id] = GIVEN_INSTANCE_ID unless GIVEN_INSTANCE_ID.empty?
154
+ body[:name] = GIVEN_NAME unless GIVEN_NAME.empty?
155
+ body = JSON.generate(body)
149
156
 
150
157
  http = Net::HTTP.new(uri.host, uri.port)
151
158
  http.read_timeout = 15
@@ -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.