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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +119 -0
- data/docs/secretary-prototype.md +286 -0
- data/lib/clacky/agent/session_serializer.rb +15 -11
- data/lib/clacky/agent.rb +58 -15
- data/lib/clacky/agent_config.rb +3 -1
- data/lib/clacky/agent_profile.rb +33 -6
- data/lib/clacky/billing/platform_billing.rb +9 -0
- data/lib/clacky/default_extensions/advisor/README.md +25 -0
- data/lib/clacky/default_extensions/advisor/README.zh.md +25 -0
- data/lib/clacky/default_extensions/advisor/ext.yml +1 -1
- data/lib/clacky/default_extensions/advisor/icon.svg +14 -0
- data/lib/clacky/default_extensions/coding/ext.yml +0 -1
- data/lib/clacky/default_extensions/computer-use/README.md +48 -0
- data/lib/clacky/default_extensions/computer-use/README.zh.md +48 -0
- data/lib/clacky/default_extensions/computer-use/ext.yml +1 -1
- data/lib/clacky/default_extensions/computer-use/icon.svg +16 -0
- data/lib/clacky/default_extensions/ext-studio/ext.yml +0 -1
- data/lib/clacky/default_extensions/general/ext.yml +0 -1
- data/lib/clacky/default_extensions/git/README.md +41 -0
- data/lib/clacky/default_extensions/git/README.zh.md +41 -0
- data/lib/clacky/default_extensions/git/ext.yml +1 -1
- data/lib/clacky/default_extensions/git/icon.svg +15 -0
- data/lib/clacky/default_extensions/git/panels/git/view.js +1960 -399
- data/lib/clacky/default_extensions/meeting/README.md +46 -0
- data/lib/clacky/default_extensions/meeting/README.zh.md +47 -0
- data/lib/clacky/default_extensions/meeting/ext.yml +1 -1
- data/lib/clacky/default_extensions/meeting/icon.svg +13 -0
- data/lib/clacky/default_extensions/preview/README.md +29 -0
- data/lib/clacky/default_extensions/preview/README.zh.md +29 -0
- data/lib/clacky/default_extensions/preview/ext.yml +1 -1
- data/lib/clacky/default_extensions/preview/icon.svg +13 -0
- data/lib/clacky/default_extensions/preview/panels/preview/view.js +199 -34
- data/lib/clacky/default_extensions/secretary/agents/secretary.md +41 -0
- data/lib/clacky/default_extensions/secretary/agents/worker.md +35 -0
- data/lib/clacky/default_extensions/secretary/api/handler.rb +8 -0
- data/lib/clacky/default_extensions/secretary/ext.yml +39 -0
- data/lib/clacky/default_extensions/secretary/panels/work/view.js +344 -0
- data/lib/clacky/default_extensions/secretary/tools/delegate_work.rb +37 -0
- data/lib/clacky/default_extensions/secretary/tools/manage_work.rb +22 -0
- data/lib/clacky/default_extensions/secretary/tools/yield_work.rb +35 -0
- data/lib/clacky/default_extensions/time_machine/README.md +32 -0
- data/lib/clacky/default_extensions/time_machine/README.zh.md +32 -0
- data/lib/clacky/default_extensions/time_machine/ext.yml +1 -1
- data/lib/clacky/default_extensions/time_machine/icon.svg +14 -0
- data/lib/clacky/default_skills/channel-manager/SKILL.md +79 -8
- data/lib/clacky/default_skills/channel-manager/discord_setup.rb +5 -1
- data/lib/clacky/default_skills/channel-manager/weixin_setup.rb +8 -1
- data/lib/clacky/default_skills/cron-task-creator/SKILL.md +183 -206
- data/lib/clacky/default_skills/cron-task-creator/evals/evals.json +45 -0
- data/lib/clacky/default_skills/media-gen/SKILL.md +17 -8
- data/lib/clacky/extension/api_extension.rb +10 -2
- data/lib/clacky/extension/loader.rb +2 -0
- data/lib/clacky/extension/verifier.rb +2 -2
- data/lib/clacky/locales/en.rb +14 -0
- data/lib/clacky/locales/zh.rb +14 -0
- data/lib/clacky/prompts/base.md +1 -1
- data/lib/clacky/providers.rb +68 -31
- data/lib/clacky/search_config.rb +33 -11
- data/lib/clacky/server/channel/adapters/base.rb +18 -0
- data/lib/clacky/server/channel/adapters/feishu/message_parser.rb +1 -0
- data/lib/clacky/server/channel/adapters/telegram/adapter.rb +1 -0
- data/lib/clacky/server/channel/channel_config.rb +185 -48
- data/lib/clacky/server/channel/channel_manager.rb +179 -66
- data/lib/clacky/server/git_panel.rb +362 -35
- data/lib/clacky/server/http_server.rb +530 -181
- data/lib/clacky/server/preview.rb +118 -17
- data/lib/clacky/server/scheduler.rb +211 -51
- data/lib/clacky/server/web_ui_controller.rb +35 -27
- data/lib/clacky/session_manager.rb +56 -6
- data/lib/clacky/tools/base.rb +7 -1
- data/lib/clacky/utils/file_processor.rb +20 -10
- data/lib/clacky/utils/mac_app_detector.rb +8 -7
- data/lib/clacky/utils/model_pricing.rb +60 -2
- data/lib/clacky/utils/windows_app_detector.rb +3 -1
- data/lib/clacky/version.rb +1 -1
- data/lib/clacky/web/app.css +1114 -205
- data/lib/clacky/web/app.js +143 -8
- data/lib/clacky/web/auth.js +1 -1
- data/lib/clacky/web/components/code-editor.js +73 -4
- data/lib/clacky/web/components/composer.js +107 -8
- data/lib/clacky/web/components/image-zoom.js +165 -0
- data/lib/clacky/web/components/model-picker.js +7 -5
- data/lib/clacky/web/components/notify.js +39 -12
- data/lib/clacky/web/components/onboard.js +1 -1
- data/lib/clacky/web/core/aside.js +60 -3
- data/lib/clacky/web/features/billing/view.js +2 -2
- data/lib/clacky/web/features/channels/store.js +19 -4
- data/lib/clacky/web/features/channels/view.js +92 -28
- data/lib/clacky/web/features/extensions/view.js +17 -10
- data/lib/clacky/web/features/new-session/store.js +79 -2
- data/lib/clacky/web/features/new-session/view.js +516 -75
- data/lib/clacky/web/features/skills/store.js +1 -1
- data/lib/clacky/web/features/tasks/store.js +5 -3
- data/lib/clacky/web/features/tasks/view.js +249 -66
- data/lib/clacky/web/features/workspace/store.js +13 -6
- data/lib/clacky/web/features/workspace/view.js +340 -214
- data/lib/clacky/web/i18n.js +366 -68
- data/lib/clacky/web/index.html +196 -165
- data/lib/clacky/web/projects.js +37 -4
- data/lib/clacky/web/sessions.js +263 -146
- data/lib/clacky/web/settings.js +241 -53
- data/lib/clacky/web/skills.js +2 -2
- data/lib/clacky/web/theme.js +17 -2
- data/lib/clacky/web/utils.js +234 -2
- data/lib/clacky/web/weixin-qr.html +2 -1
- data/lib/clacky/web/ws-dispatcher.js +14 -31
- data/lib/clacky/work/service.rb +542 -0
- data/lib/clacky/work/store.rb +57 -0
- 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
|
|
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
|
|
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 '
|
|
527
|
-
BASE_URL=$(ruby -ryaml -e '
|
|
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
|
|
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 =
|
|
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
|
-
|
|
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
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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
|
-
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
103
|
+
Ordinary task payload (the existing format remains valid):
|
|
76
104
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
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
|
-
|
|
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
|
-
|
|
146
|
+
Do not tell users that an ordinary task will report to the current conversation.
|
|
127
147
|
|
|
128
|
-
|
|
148
|
+
## 3. Edit
|
|
129
149
|
|
|
130
|
-
|
|
150
|
+
Read the selected plan, retain its type and owner, and PATCH only requested fields:
|
|
131
151
|
|
|
132
|
-
```
|
|
133
|
-
|
|
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
|
-
|
|
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
|
-
|
|
167
|
+
## 4. Enable or disable
|
|
160
168
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
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
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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
|
-
|
|
209
|
-
|
|
210
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
211
|
+
## Timing and templates
|
|
236
212
|
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
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
|
-
|
|
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
|
-
|
|
257
|
-
-
|
|
258
|
-
-
|
|
259
|
-
|
|
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.
|