openclacky 1.5.22 → 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 (91) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +58 -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 +6 -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 +71 -23
  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/secretary/agents/secretary.md +41 -0
  34. data/lib/clacky/default_extensions/secretary/agents/worker.md +35 -0
  35. data/lib/clacky/default_extensions/secretary/api/handler.rb +8 -0
  36. data/lib/clacky/default_extensions/secretary/ext.yml +39 -0
  37. data/lib/clacky/default_extensions/secretary/panels/work/view.js +344 -0
  38. data/lib/clacky/default_extensions/secretary/tools/delegate_work.rb +37 -0
  39. data/lib/clacky/default_extensions/secretary/tools/manage_work.rb +22 -0
  40. data/lib/clacky/default_extensions/secretary/tools/yield_work.rb +35 -0
  41. data/lib/clacky/default_extensions/time_machine/README.md +32 -0
  42. data/lib/clacky/default_extensions/time_machine/README.zh.md +32 -0
  43. data/lib/clacky/default_extensions/time_machine/ext.yml +1 -1
  44. data/lib/clacky/default_extensions/time_machine/icon.svg +14 -0
  45. data/lib/clacky/default_skills/channel-manager/SKILL.md +79 -8
  46. data/lib/clacky/default_skills/channel-manager/discord_setup.rb +5 -1
  47. data/lib/clacky/default_skills/channel-manager/weixin_setup.rb +8 -1
  48. data/lib/clacky/default_skills/cron-task-creator/SKILL.md +183 -206
  49. data/lib/clacky/default_skills/cron-task-creator/evals/evals.json +45 -0
  50. data/lib/clacky/default_skills/media-gen/SKILL.md +17 -8
  51. data/lib/clacky/extension/api_extension.rb +10 -2
  52. data/lib/clacky/extension/loader.rb +2 -0
  53. data/lib/clacky/extension/verifier.rb +2 -2
  54. data/lib/clacky/locales/en.rb +14 -0
  55. data/lib/clacky/locales/zh.rb +14 -0
  56. data/lib/clacky/prompts/base.md +1 -1
  57. data/lib/clacky/providers.rb +25 -14
  58. data/lib/clacky/server/channel/adapters/base.rb +18 -0
  59. data/lib/clacky/server/channel/adapters/feishu/message_parser.rb +1 -0
  60. data/lib/clacky/server/channel/adapters/telegram/adapter.rb +1 -0
  61. data/lib/clacky/server/channel/channel_config.rb +185 -48
  62. data/lib/clacky/server/channel/channel_manager.rb +179 -66
  63. data/lib/clacky/server/git_panel.rb +2 -1
  64. data/lib/clacky/server/http_server.rb +385 -134
  65. data/lib/clacky/server/scheduler.rb +166 -85
  66. data/lib/clacky/session_manager.rb +4 -1
  67. data/lib/clacky/tools/base.rb +7 -1
  68. data/lib/clacky/utils/file_processor.rb +20 -10
  69. data/lib/clacky/version.rb +1 -1
  70. data/lib/clacky/web/app.css +401 -46
  71. data/lib/clacky/web/app.js +85 -3
  72. data/lib/clacky/web/components/code-editor.js +73 -4
  73. data/lib/clacky/web/components/model-picker.js +1 -1
  74. data/lib/clacky/web/components/notify.js +37 -10
  75. data/lib/clacky/web/components/onboard.js +1 -1
  76. data/lib/clacky/web/features/channels/store.js +19 -4
  77. data/lib/clacky/web/features/channels/view.js +87 -26
  78. data/lib/clacky/web/features/extensions/view.js +15 -8
  79. data/lib/clacky/web/features/new-session/view.js +23 -20
  80. data/lib/clacky/web/features/tasks/store.js +5 -3
  81. data/lib/clacky/web/features/tasks/view.js +98 -26
  82. data/lib/clacky/web/features/workspace/view.js +193 -57
  83. data/lib/clacky/web/i18n.js +128 -12
  84. data/lib/clacky/web/index.html +25 -10
  85. data/lib/clacky/web/sessions.js +82 -41
  86. data/lib/clacky/web/settings.js +215 -45
  87. data/lib/clacky/web/utils.js +217 -0
  88. data/lib/clacky/web/ws-dispatcher.js +7 -3
  89. data/lib/clacky/work/service.rb +542 -0
  90. data/lib/clacky/work/store.rb +57 -0
  91. metadata +30 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: dad8bbc900ca4c356fd5f6c90be1d3f17dd868cdfd1c5e20f11c2501d60e91a3
4
- data.tar.gz: 41419dccba92391c36388cb6faeb02d6ad3e1c30f23a8b843289e7fd8d9a5a51
3
+ metadata.gz: 5b5f420c625379fad464ab7f88912b46d3c8bfd17dbb14c58274ed0841d0039e
4
+ data.tar.gz: 6f8df699a2a7097348bba112445687429b17aa2617f1265ad83107a1aa7778fd
5
5
  SHA512:
6
- metadata.gz: 1cfb5f474c526ce2e5ae71b3685d6a710c0da51f68b06d5cf1ae54c4983454dbed9046654b98d02d64968755331eeeaf95058e53f9a861c63797096aa4b2f834
7
- data.tar.gz: 4230f8c558a10c71dc4a32a88963151885f22962e8edb8f7c221b908a08ab6d30afc6ae7e33574792100c476a943a0619ba1ac59c0c48a69caaf70f2aef4ff8a
6
+ metadata.gz: 462d32d168319ebc8d1366636ffe7cbcd5df1d748334180e12e688928f9abd72a8c7e8887ee8d3fb71c269a835fdd014a7bf8387fc6aeff5b2b98ca40833d217
7
+ data.tar.gz: e74fdb9dfdc042b922544f6eb80f0a7b6c029d25f6e5e15a841ee8277aa32830c5dcd733a049cc9225851689d18d66665e9301480ffb3c0875dc6e644b582484
data/CHANGELOG.md CHANGED
@@ -4,6 +4,64 @@ All notable changes to this project will be documented in this file.
4
4
 
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
 
7
+ ## [1.5.23] - 2026-11-06
8
+
9
+ ### Added
10
+ - Add durable delegated work and a secretary extension
11
+ - Run multiple instances of the same IM channel platform
12
+ - Show linked local media inline in the Web UI
13
+ - Open Markdown images in the lightbox
14
+ - Add file actions to the image lightbox toolbar
15
+ - Add an open-with submenu to file context menus
16
+ - Sync scrolling between the Markdown editor and preview
17
+ - Persist composer text drafts across reloads, stored per session
18
+ - Offer starter examples when no scheduled task exists
19
+ - Show a readable title for scheduled tasks instead of the ASCII name
20
+ - Name the session in desktop notifications
21
+ - Give builtin extensions icons and full detail pages
22
+ - Refresh the OpenClacky image and video model lineup
23
+ - Advertise OpenClacky AI Keys above the secondary models
24
+ - Explain the Recommended provider badge on hover
25
+ - Mention media capabilities on the onboarding key card
26
+ - Infer no-vision for custom models from known model names
27
+ - Explain the last-turn scope in the Git panel on hover
28
+
29
+ ### Improved
30
+ - Improve worker conversations, report context and debug exports
31
+ - Order scheduled tasks by enabled state, then newest first
32
+ - Make the secondary-model rows readable at a glance
33
+ - Restyle the provider promo and sharpen its copy
34
+ - Explain broken images in the workspace preview
35
+ - Tighten the Git changes toolbar and left-align the tool row when it wraps
36
+ - Unify session info bar tooltips and move the session file id to the end of the bar
37
+ - Tint destructive row menu items red only on hover
38
+
39
+ ### Fixed
40
+ - Show the pane scrollbar on hover in the split diff view
41
+ - Keep the open-with submenu attached to its parent menu
42
+ - Title attachment-only turns with file names in the time machine
43
+ - Close the Git panel file menu on revert and refresh
44
+ - Show the untracked-files hint when checkout is blocked by untracked files
45
+ - Force English git output so checkout errors are recognised
46
+ - Drop a pushed commit pick on Git panel refresh
47
+ - Refetch the commit list on Git panel refresh, and stop the empty list from saying it twice
48
+ - Raise the scope menu and finder above the mobile aside overlay
49
+ - Drop the sub-model when the session's model card is gone
50
+ - Refresh the new-session model list every time the panel opens
51
+ - Resync the modal API-key link with the selected provider
52
+ - Exit address mode in the directory picker after entering the current path
53
+ - Skip sidebar transitions while restoring layout on load
54
+ - Keep the real path when opening file:// links in preview
55
+ - Refresh open file tabs after edits
56
+ - Reveal the file tree when the last file tab closes
57
+ - Start housekeeping phase cards collapsed
58
+ - Keep token usage detail fields always visible
59
+ - Show the collapse tooltip to the left of the button
60
+ - Drop tooltips from the open-with split button
61
+
62
+ ### More
63
+ - Rename the MCP panel to connectors in Chinese
64
+
7
65
  ## [1.5.22] - 2026-10-30
8
66
 
9
67
  ### Added
@@ -0,0 +1,286 @@
1
+ # Secretary prototype
2
+
3
+ This version uses ordinary sessions: one secretary conversation owns a set of
4
+ background worker sessions. No extra daemon, database or extension installation
5
+ is required. The built-in `secretary` extension supplies the two profiles, three
6
+ model tools, API and Work panel. The server supplies persistence and coordination.
7
+
8
+ ## Try it
9
+
10
+ Restart the server from this checkout (`bundle exec ruby bin/openclacky server`),
11
+ refresh the Web UI, and create a **生活秘书 / Secretary** session. Open its
12
+ **工作事项** side panel.
13
+
14
+ 1. Say: “帮我查一下杭州适合带父母去的景点,整理一份建议,交给工作助手做。”
15
+ 2. While it works, continue chatting with the secretary. The worker has a separate
16
+ session, and the secretary receives its result when available.
17
+ 3. Try: “准备一条约张三下周吃饭的邀请,优先周四。先给我草稿,我来发送。”
18
+ 4. When the work requests your input, tell the secretary “我发出去了,请等待回复”,
19
+ then relay “张三说只有周五有空”. The panel’s discussion button inserts a work
20
+ session reference into the normal composer; it does not submit automatically.
21
+ 5. Change requirements, pause, cancel or resume by talking to the secretary.
22
+ Completed/cancelled items require new delegation.
23
+ 6. Restart while waiting. The card and wait survive. A run interrupted while
24
+ executing becomes “需要处理”; it is not blindly replayed.
25
+
26
+ ## Scope
27
+
28
+ - Workers use their profile's normal tools and existing permission checks. Work
29
+ coordination does not impose a separate read-only allowlist. The built-in worker
30
+ can create files; additional integrations depend on its configured tools.
31
+ - Automatic incoming association requires an exact `reply_to`, channel and chat
32
+ match. Telegram and Feishu normalize reply references. No heuristic matching
33
+ or autonomous outbound messaging is included. Other replies can be relayed
34
+ manually through the secretary conversation; never invent a sent message ID.
35
+ - `check_at` accepts future ISO8601 timestamps including an explicit UTC offset.
36
+ A deadline wakes the worker to assess next steps; it does not authorize sending.
37
+ - This is a single-server local store. Do not run two servers against the same
38
+ sessions directory. CLI conversations do not host the coordinator.
39
+ - The default background capacity leaves one slot available when the configured
40
+ maximum is greater than one. A maximum of one cannot provide simultaneous
41
+ foreground/background execution.
42
+
43
+ ## Persistence and execution
44
+
45
+ `<sessions_dir>/work/state.json` contains cards, per-card result outboxes, and
46
+ threaded incoming events. Writes are mutex-protected atomic replacements with
47
+ mode 0600. Cards and result notifications are saved together. Active work and
48
+ pending notifications protect their associated sessions from automatic cleanup.
49
+ Explicit deletion of sessions is not a work cancellation API: cancel work first.
50
+
51
+ The coordinator runs once per second. It delivers pending secretary notifications
52
+ before dispatching queued workers. Only one execution per session is admitted.
53
+ Waiting uses no worker thread. A generation check rejects tools from an execution
54
+ whose requirements changed, was cancelled or already yielded. `yield_work` stops
55
+ execution even if the model returned additional tool calls in the same batch.
56
+
57
+ Notifications carry an event ID. The secretary history is persisted before outbox
58
+ acknowledgement; a replay checks history for that ID. This guarantees durable
59
+ receipt within retained history, not exactly-once model reasoning or external
60
+ side effects. External side effects still require tool-specific retry/idempotency handling.
61
+
62
+ The host captures recent verbatim user messages (with original message IDs) at
63
+ delegation and injects current card summaries into secretary turns. It does not
64
+ copy the entire parent conversation. Older necessary context must be supplied
65
+ explicitly; external replies are labelled separately from owner instructions.
66
+
67
+ ## Extension API
68
+
69
+ Server-attached tools access `agent.work_service`; API handlers access
70
+ `work_service`. The service implements delegation, management and yielding without
71
+ requiring extensions to access the HTTP server's private execution methods.
72
+
73
+ - Secretary: `delegate_work`, `manage_work` (list/get/update/reply/pause/resume/cancel).
74
+ - Worker: `yield_work` (completed/needs_input/waiting_event).
75
+ - UI: read-only `GET /api/ext/secretary/work?session_id=...`. All changes go
76
+ through the secretary's tools in the main conversation.
77
+
78
+ ## Presentation boundary
79
+
80
+ WorkService submits both worker tasks and secretary wakeups through the shared
81
+ `run_session_task` entry point. It does not call `Agent#run`, access agent UI,
82
+ render messages, or rewrite old history for presentation. `display_message` names
83
+ worker input/turns; the prompt contains the full work data.
84
+
85
+ Work reports are ordinary session inputs: `display_message` becomes `display_text`
86
+ for friendly live display and history replay. Full work data stays in the actual message content. No new hidden-turn API or rollback semantics are needed.
87
+
88
+ The panel owns English/Chinese strings and responds to the host language event.
89
+ Server-generated messages use Ruby i18n and the locale captured at delegation;
90
+ stored history, user text and worker results retain their original language.
91
+
92
+ The coordinator emits transient `ext.work.changed` invalidations scoped to the
93
+ owner session. The extension subscribes through `Clacky.ext`, fetches the durable
94
+ card snapshot, and shares it between the existing `session.aside` and
95
+ `session.composer` slots. Mount and reconnect also refresh. The composer slot
96
+ shows ongoing/waiting/decision counts while the normal session remains idle and
97
+ available for conversation. No extra global WS message flags or host rendering
98
+ branches are added. Panel actions use the existing Composer session-reference
99
+ API and preserve drafts. Historical prototype notifications are left untouched;
100
+ there is no string-based history repair.
101
+
102
+ ## Recurring secretary work
103
+
104
+ The existing cron-task-creator skill and cron-task API own all plan management.
105
+ The secretary supplies owner_session_id from CLACKY_SESSION_ID, a friendly title,
106
+ a self-contained content prompt, cron when creating
107
+ through POST /api/cron-tasks. The API validates the owner and saves an execution
108
+ target. Existing GET/PATCH/DELETE/RUN routes manage the same plan; PATCH preserves
109
+ its target. The global API remains the user's management surface; the skill selects
110
+ plans by target.owner_session_id before changing them. Duplicate creates cannot
111
+ overwrite a secretary plan; use PATCH or a distinct name. manage_work remains
112
+ limited to individual work cards; there are no schedule-management tool actions.
113
+
114
+ For example, ask the secretary to prepare a morning report at 09:00 and an evening
115
+ report at 20:00 in server-local time. Specify sources and report scope; the prototype
116
+ has no automatic mailbox/calendar access. Each occurrence creates a fresh worker
117
+ session and durable work card; results return through the ordinary outbox and
118
+ friendly display_text path. Workers receive the plan instruction, occurrence time
119
+ and up to 50 recent work summaries. The work aside shows plans and their next due
120
+ time; changes are discussed in the existing conversation. Existing cron-task
121
+ management APIs also list/manage these plans; Run Now follows the work-card path.
122
+
123
+ Plans and prompts reuse schedules.yml and tasks/*.md. Next occurrence timestamps
124
+ are saved atomically. A restored process or resumed sandbox catches up only the
125
+ latest missed occurrence. A secretary occurrence is deduplicated by plan ID and
126
+ scheduled UTC instant in the work store, including when the plan cursor failed to
127
+ save after card creation. One unfinished card per plan is allowed: queued, running,
128
+ waiting, paused, failed and decision-needed work blocks the next occurrence until
129
+ resolved or cancelled. Pausing/deleting a plan does not cancel existing cards;
130
+ re-enabling or changing its timing starts from the next future occurrence.
131
+
132
+ Schedules use server-local time. Legacy plans without a cursor
133
+ begin tracking at the first scheduler tick (no invented pre-upgrade backlog).
134
+ Existing cron DOM/DOW AND semantics are retained. Receipt-based crash deduplication
135
+ is provided by secretary work cards; ordinary cron sessions keep their existing
136
+ execution path and do not gain an exactly-once execution guarantee.
137
+
138
+ No external wakeup service is introduced. Cron cannot execute while the sandbox is
139
+ paused; once something resumes it, due scanning continues. Existing yield_work
140
+ and check_at behavior is unchanged. Email subscriptions and cloud lifecycle APIs
141
+ remain outside this change.
142
+
143
+ ## Custom secretary profiles
144
+
145
+ Use the existing user-agent directory and agent picker. No separate identity
146
+ store or management page is required. For example, create
147
+ `~/.clacky/agents/my-secretary/profile.yml`:
148
+
149
+ ```yaml
150
+ name: my-secretary
151
+ title: My secretary
152
+ title_zh: 我的秘书
153
+ base_agent: secretary
154
+ ```
155
+
156
+ In the same directory, write `system_prompt.md` with the user's responsibilities,
157
+ preferences and output expectations. The loader composes the secretary extension's
158
+ shared rules followed by this file. Existing base rules, global `SOUL.md` and
159
+ `USER.md` continue to load normally. The profile uses the secretary's declared
160
+ tool set and Work panel. `base_agent` can reference any agent contributed by an
161
+ enabled extension (for example `coding` or a third-party agent), not just
162
+ `secretary`. Only one direct reference is supported: no chains, user-only bases
163
+ or arbitrary cross-container tool merging. Base disabled-skill restrictions are
164
+ retained; custom profiles may disable additional skills. Skills scoped to the
165
+ base agent and panels attached to it also remain available. Extensions can use
166
+ `agent.agent_profile.based_on?(id)` to recognize customized profiles.
167
+
168
+ Restart the service after upgrading, then refresh the WebUI. The custom agent
169
+ appears in the existing new-conversation picker. Conversations retain the custom
170
+ profile name and keep work isolated by owner session. Scheduled work can belong
171
+ to these conversations too; workers use the configured work_agent profile.
172
+
173
+ Prompt edits follow ordinary profile behavior: new/restored agent instances load
174
+ current files. Already loaded instances are not hot-updated. This feature adds no
175
+ prompt snapshots, identity-specific memory, new session fields or outbound tools.
176
+
177
+ ## Choosing a worker
178
+
179
+ An agent opts into delegation with `work_agent: <profile-id>` in its extension
180
+ agent declaration or user `profile.yml`. The built-in secretary sets
181
+ `work_agent: secretary-worker`. Custom `base_agent` profiles inherit this setting;
182
+ an explicit value overrides it and an empty string disables delegation.
183
+ The target must be an available profile. Its normal built-in and declared
184
+ extension tools load without an additional work-specific allowlist.
185
+
186
+ Third-party tools can call `agent.work_service.delegate`, `manage`, and
187
+ `yield_work`. A worker must report its outcome through `yield_work` (or its own
188
+ tool calling that service method). The service commits the outcome and returns
189
+ `end_turn: true`. Any tool can return this generic flag to finish the current turn
190
+ after recording its result; remaining tool calls in the batch are settled without
191
+ execution. The flag does not itself schedule a wakeup or pause a work card.
192
+ Work sessions retain revision/cancellation checks regardless of profile name.
193
+
194
+ ## Handoffs, session status and alerts
195
+
196
+ `yield_work` uses `needs_input` for a question to the main agent and
197
+ `waiting_event` for an external reply or timed checkpoint. The main agent answers
198
+ from existing information/authorization when possible; otherwise it asks the user
199
+ and relays the answer. Legacy `needs_user` / `waiting_reply` calls and stored
200
+ `waiting_user` / `waiting_reply` cards remain readable and normalize to the new names.
201
+
202
+ Ending a tool turn does not imply awaiting an answer. `completed` and
203
+ `waiting_event` leave the worker session idle; `needs_input` leaves it
204
+ awaiting_feedback. The work card retains the durable outcome/wait state.
205
+ Worker turns do not alert the user directly. Delegation and reply/update handoffs
206
+ return `notify_user: false` to suppress completion alerts and done markers; an
207
+ explicit user question in the same owner turn takes precedence. Main-agent reports
208
+ retain normal notification behavior. The composer shows background work and task
209
+ titles without pretending the main agent is still executing.
210
+
211
+ User interruption pauses the work card. `manage_work resume` requeues paused or
212
+ failed work in its existing worker session, retaining history and progress; no
213
+ new delegation is created. It accepts optional additional instructions and the
214
+ usual expected_revision check. Repeating resume on queued/running work is a no-op.
215
+ Completed work accepts `reply`/`update` to refine the result in the same session;
216
+ completion means there is no work pending, not that the user has accepted it.
217
+ `resume` remains for interrupted work. Cancelled work cannot be restarted by feedback.
218
+
219
+ Users can also speak directly in a worker conversation. These inputs use the
220
+ ordinary session input queue, attachment/reference processing and queue/steer
221
+ setting. Pending messages are shown by the existing queue UI and reconnect snapshot;
222
+ Work does not keep a second chat queue in its cards. The existing on_start and
223
+ on_complete hooks establish and clean up revision protection for direct turns.
224
+ Direct conversation preserves the work's business status, result and wait condition.
225
+ A normal successful reply creates no work report. New deliverables, blockers and
226
+ external waits still use `yield_work`; background executions must yield.
227
+
228
+ The worker profile defines how to answer user-initiated conversation and when to
229
+ yield an outcome. Users may provide feedback directly; worker requests for missing
230
+ information, decisions or authorization still go to the main agent via needs_input.
231
+ The worker does not call ask_user or directly ask the user to unblock the work.
232
+ Direct chat uses the existing conversation history; the core injects no extra
233
+ worker conversation instructions or work-card snapshot. Ordinary answers render
234
+ as assistant messages. Ending a tool turn does not pause explicit queued user messages; awaiting
235
+ user input and interruptions still pause the queue.
236
+
237
+ ## Debug downloads
238
+
239
+ Session downloads retain the existing top-level session, archive chunks and log.
240
+ When the session owns work, the ZIP additionally contains `work/cards.json`,
241
+ `work/events.json` (matched events only), `work/manifest.json`, and the associated
242
+ worker session files under `work/sessions/<session-id>/`. The manifest preserves
243
+ existing work/session identifiers and marks unavailable worker files as missing.
244
+ Downloading a worker includes its own card but does not expand to its owner's
245
+ conversation or sibling workers. Session files are the latest persisted versions;
246
+ the work snapshot and session files are not an atomic snapshot of a running system.
247
+
248
+ ## Work identity and report references
249
+
250
+ A work card's `id` is its worker session ID; no separate work identifier is
251
+ allocated. Updates and resume keep this identity. `owner_session_id` identifies
252
+ the receiving conversation, and outbox event IDs still identify individual
253
+ notifications for deduplication. No legacy work-ID migration is provided.
254
+
255
+ Work reports reuse the existing session reference payload (`type`, `session_id`,
256
+ `name`) on their visible input message. `reference_contexts` is passed through
257
+ the server execution entry point and saved as `display_references`; the same
258
+ reference renders live and on history replay. Session badges link through the
259
+ existing `#session/<id>` route. `display_text` remains the friendly notification
260
+ body; full results are the prompt, while referenced sessions/quotes produce their
261
+ model context in the server before input delivery. Existing history fields are unchanged;
262
+ old ordinary sessions retain their reference badges and hidden context on replay.
263
+
264
+ The Ruby input parameter remains `reference_contexts`. Existing string entries
265
+ are still injected as model-only text. Structured reference entries additionally
266
+ render as badges using the existing `display_references` history field. The
267
+ browser request/event field remains `references`; no separate Ruby display
268
+ parameter is required.
269
+
270
+ Reference lookup stays in the HTTP server, which already owns the session store.
271
+ It adds a model-only `context` value to each resolved reference in the existing
272
+ `reference_contexts` argument. Agent consumes that text and strips `context` from
273
+ UI/history reference metadata; it does not look up sessions or require a server
274
+ SessionManager injection. Legacy text-only contexts and saved queued inputs remain
275
+ supported.
276
+
277
+ Work reports contain the work title/ID, event time, revision and outcome.
278
+ Manual stops are identified as user actions, distinct from worker reports and
279
+ execution failures. Historical feedback, original instructions and generic
280
+ next-step instructions are not replayed. Existing work tools and the worker session
281
+ reference provide details on demand.
282
+ Outbox event IDs remain in the work store, not in model-visible content or session
283
+ message IDs. Delivery uses pending/delivered state without scanning session history.
284
+ A crash after session persistence but before acknowledgement can repeat a report.
285
+ When capturing verbatim user context, host submissions carrying `display_text`
286
+ are excluded so generated reports are not treated as user authorization.
@@ -20,7 +20,13 @@ module Clacky
20
20
  @archived_at = session_data[:archived_at]
21
21
  @history = MessageHistory.new(session_data[:messages] || [])
22
22
  @input_queue = (session_data[:pending_inputs] || []).map do |entry|
23
- entry.reject { |key, _| key == :steer_target }.merge(delivery: "queue")
23
+ options = (entry[:options] || {}).dup
24
+ # Old queued inputs stored both the references and their generated text.
25
+ legacy_references = options.delete(:references_display)
26
+ unless Array(legacy_references).empty?
27
+ options[:reference_contexts] = Array(legacy_references) + Array(options[:reference_contexts])
28
+ end
29
+ entry.reject { |key, _| key == :steer_target }.merge(delivery: "queue", options: options)
24
30
  end
25
31
  @accepting_steering = false
26
32
  @todos = session_data[:todos] || [] # Restore todos from session
@@ -136,17 +142,15 @@ module Clacky
136
142
  model_entry = @config.find_model_by_name_and_url(saved_model_name, saved_base_url)
137
143
  if model_entry && model_entry["id"]
138
144
  switch_model_by_id(model_entry["id"])
139
- end
140
- end
141
145
 
142
- # Re-apply the per-session sub-model pin (if any). Done AFTER
143
- # switch_model_by_id so the overlay isn't cleared by the card switch
144
- # invariant. Validation happens at write-time (the WebUI/API enforces
145
- # the name belongs to the card's provider) — at restore-time we trust
146
- # what we previously wrote.
147
- saved_sub_model = session_data.dig(:config, :sub_model)
148
- if saved_sub_model && !saved_sub_model.to_s.empty?
149
- set_session_sub_model(saved_sub_model)
146
+ # The sub-model pin belongs to the saved card's provider, so it is
147
+ # only re-applied when that card was found; on the fallback card it
148
+ # would pair a foreign model name with the wrong credentials.
149
+ saved_sub_model = session_data.dig(:config, :sub_model)
150
+ if saved_sub_model && !saved_sub_model.to_s.empty?
151
+ set_session_sub_model(saved_sub_model)
152
+ end
153
+ end
150
154
  end
151
155
 
152
156
  # Rebuild and refresh the system prompt so any newly installed skills
data/lib/clacky/agent.rb CHANGED
@@ -51,6 +51,8 @@ module Clacky
51
51
  :status, :error, :updated_at, :source, :config,
52
52
  :latest_latency, # Hash of latency metrics from the most recent LLM call (see Client#send_messages_with_tools)
53
53
  :reasoning_effort
54
+ attr_accessor :work_service
55
+ attr_reader :tool_registry
54
56
  attr_accessor :pinned
55
57
  attr_accessor :channel_info
56
58
  attr_accessor :project_id
@@ -520,7 +522,7 @@ module Clacky
520
522
  @name = new_name.to_s.strip
521
523
  end
522
524
 
523
- def run(user_input, files: nil, reference_contexts: nil, display_text: nil, created_at: nil, references_display: nil)
525
+ def run(user_input, files: nil, reference_contexts: nil, display_text: nil, created_at: nil)
524
526
  # Initialized here (not mid-body) because run's rescue/ensure are
525
527
  # method-level and must be able to reference them on any exit path.
526
528
  result = nil
@@ -556,7 +558,11 @@ module Clacky
556
558
  @cancel_flag = CancelFlag.new
557
559
 
558
560
  # Start new task for Time Machine
559
- task_id = start_new_task(title: display_text.to_s.empty? ? user_input.to_s : display_text.to_s)
561
+ task_title = display_text.to_s.empty? ? user_input.to_s : display_text.to_s
562
+ if task_title.strip.empty?
563
+ task_title = display_files_for(files).map { |f| f[:name] }.join(", ")
564
+ end
565
+ task_id = start_new_task(title: task_title)
560
566
  run_context = { session_id: @session_id, run_id: task_id.to_s,
561
567
  source: @source.to_s, input_created_at: created_at,
562
568
  observed_at: Time.now.utc.iso8601(6), status: "running" }
@@ -622,7 +628,7 @@ module Clacky
622
628
 
623
629
  append_user_input(user_input, files: files, reference_contexts: reference_contexts,
624
630
  display_text: display_text, created_at: created_at,
625
- references_display: references_display, task_id: task_id)
631
+ task_id: task_id)
626
632
  @total_tasks += 1
627
633
  run_turn_started = true
628
634
 
@@ -641,8 +647,14 @@ module Clacky
641
647
  return result = hook_result[:result]
642
648
  end
643
649
 
650
+ work_context = @work_service&.turn_context(self)
651
+ @history.append(role: "user", content: work_context, system_injected: true, task_id: task_id) if work_context
652
+
644
653
  # Track if ask_user was called
645
654
  awaiting_user_feedback = false
655
+ # A tool handed control back; distinct from finishing a normal reply.
656
+ yielded = false
657
+ notify_user = true
646
658
  # Heuristic sibling of the above: the reply merely ended with a question
647
659
  # mark. Kept separate because it must never reach build_result — the
648
660
  # session status it feeds shows a "waiting" badge to the user, and a
@@ -657,6 +669,7 @@ module Clacky
657
669
  @hooks.trigger(:on_iteration, @iterations)
658
670
 
659
671
  consume_steering_inputs
672
+ @work_service&.guard!(self) if Thread.current[:clacky_work]
660
673
 
661
674
  # Think: LLM reasoning with tool support
662
675
  response = think
@@ -794,9 +807,10 @@ module Clacky
794
807
  # Act: Execute tool calls
795
808
  action_result = act(response[:tool_calls], assistant_message: response.delete(:history_message))
796
809
 
797
- # Check if ask_user was called
798
- if action_result[:awaiting_feedback]
799
- awaiting_user_feedback = true
810
+ notify_user = false if action_result[:notify_user] == false
811
+ if action_result[:awaiting_feedback] || action_result[:end_turn]
812
+ awaiting_user_feedback = !!action_result[:awaiting_feedback]
813
+ yielded = !!action_result[:end_turn]
800
814
  observe(response, action_result[:tool_results])
801
815
  flush_pending_injections
802
816
  break
@@ -834,13 +848,14 @@ module Clacky
834
848
  @input_mutex.synchronize { @accepting_steering = false }
835
849
  notify_input_queue
836
850
  result = build_result(awaiting_user_feedback: awaiting_user_feedback)
851
+ result[:notify_user] = false if !notify_user && !awaiting_user_feedback
837
852
  result[:queue_paused] = true if awaiting_user_feedback || task_interrupted
838
853
  run_context[:reason] = "tool_denied" if task_interrupted
839
854
 
840
855
  # Run skill evolution hooks after main loop completes
841
856
  # Skip if task was interrupted by user (denied tool) or awaiting user feedback
842
857
  # Only for main agent (not subagents) to avoid recursive evolution
843
- unless @is_subagent || task_interrupted || awaiting_user_feedback || turn_unfinished
858
+ unless @is_subagent || task_interrupted || yielded || awaiting_user_feedback || turn_unfinished
844
859
  run_skill_evolution_hooks
845
860
  end
846
861
 
@@ -851,7 +866,7 @@ module Clacky
851
866
  # and only then [OK] Task Complete is printed. No cleanup dance,
852
867
  # no cross-method progress handle holding.
853
868
  # Skip on interrupt / feedback / subagent (self-guarded inside too).
854
- unless @is_subagent || task_interrupted || awaiting_user_feedback || turn_unfinished
869
+ unless @is_subagent || task_interrupted || yielded || awaiting_user_feedback || turn_unfinished
855
870
  run_memory_update_subagent
856
871
  end
857
872
 
@@ -876,7 +891,7 @@ module Clacky
876
891
  # in this same thread. Skipped for subagents and interrupts.
877
892
  # An explicit request for user feedback pauses the goal as well as the
878
893
  # queue. Mere question punctuation still leaves the goal judge in charge.
879
- unless @is_subagent || task_interrupted || awaiting_user_feedback
894
+ unless @is_subagent || task_interrupted || yielded || awaiting_user_feedback
880
895
  continuation = maybe_continue_goal(result)
881
896
  return continuation if continuation
882
897
  end
@@ -959,9 +974,16 @@ module Clacky
959
974
  context.merge(status: status, observed_at: Time.now.utc.iso8601(6)))
960
975
  end
961
976
 
977
+ # Resolved context is model-only; retain only reference metadata for UI/replay.
978
+ private def display_references(contexts)
979
+ Array(contexts).select { |ref| ref.is_a?(Hash) }.map do |ref|
980
+ ref.reject { |key, _| key.to_s == "context" }
981
+ end
982
+ end
983
+
962
984
  # Shared by initial input and steering; only the execution thread writes history.
963
985
  private def append_user_input(user_input, files: nil, reference_contexts: nil,
964
- display_text: nil, created_at: nil, references_display: nil,
986
+ display_text: nil, created_at: nil,
965
987
  task_id: @current_task_id)
966
988
  # Resolve lightweight metadata first, then commit the accepted user turn
967
989
  # before any attachment parser/OCR/sidecar work can block or fail. Session
@@ -980,7 +1002,7 @@ module Clacky
980
1002
  display_text: display_text,
981
1003
  skill_command: skill_command[:found] ? skill_command[:skill_name] : nil,
982
1004
  skill_command_display: skill_command_display,
983
- display_references: Array(references_display).empty? ? nil : references_display
1005
+ display_references: display_references(reference_contexts)
984
1006
  }
985
1007
  if staged
986
1008
  @history.append(message_metadata.merge(
@@ -1178,7 +1200,8 @@ module Clacky
1178
1200
  # Inject referenced past chats (the @mention "send as reference" behavior)
1179
1201
  # as a system_injected message — same mechanism as file references: the LLM
1180
1202
  # sees the context, but replay_history skips it and no user bubble renders.
1181
- Array(reference_contexts).each do |ctx|
1203
+ Array(reference_contexts).each do |reference|
1204
+ ctx = reference.is_a?(Hash) ? (reference[:context] || reference["context"]) : reference
1182
1205
  next if ctx.to_s.strip.empty?
1183
1206
  @history.append({ role: "user", content: ctx, system_injected: true, task_id: task_id })
1184
1207
  end
@@ -1320,7 +1343,8 @@ module Clacky
1320
1343
  source = options.delete(:source) || :web
1321
1344
  notify_input_queue
1322
1345
  @ui.show_user_message(options[:display_text] || entry[:content], created_at: options[:created_at],
1323
- files: options[:files] || [], source: source, steering: true) if @ui&.respond_to?(:show_user_message)
1346
+ files: options[:files] || [], source: source, steering: true,
1347
+ **(!Array(options[:reference_contexts]).any? { |ref| ref.is_a?(Hash) } ? {} : { references: display_references(options[:reference_contexts]) })) if @ui&.respond_to?(:show_user_message)
1324
1348
  run(entry[:content], **options)
1325
1349
  end
1326
1350
 
@@ -1362,7 +1386,8 @@ module Clacky
1362
1386
  end
1363
1387
  committed += 1
1364
1388
  @ui&.show_user_message(options[:display_text] || entry[:content],
1365
- created_at: options[:created_at], files: options[:files] || [], source: source, steering: true) if @ui&.respond_to?(:show_user_message)
1389
+ created_at: options[:created_at], files: options[:files] || [], source: source, steering: true,
1390
+ **(!Array(options[:reference_contexts]).any? { |ref| ref.is_a?(Hash) } ? {} : { references: display_references(options[:reference_contexts]) })) if @ui&.respond_to?(:show_user_message)
1366
1391
  end
1367
1392
  notify_input_queue unless entries.empty?
1368
1393
  !entries.empty?
@@ -1589,6 +1614,8 @@ module Clacky
1589
1614
  feedback = nil
1590
1615
  results = []
1591
1616
  awaiting_feedback = false
1617
+ end_turn = false
1618
+ notify_user = true
1592
1619
 
1593
1620
  tool_calls.each_with_index do |call, index|
1594
1621
  # Resolve tool name: handle case-insensitive and common alias mismatches
@@ -1607,6 +1634,8 @@ module Clacky
1607
1634
  # Tool truly not found — let the rescue below handle it with a clear message
1608
1635
  end
1609
1636
 
1637
+ @work_service&.guard!(self)
1638
+
1610
1639
  # Hook: before_tool_use
1611
1640
  hook_result = @hooks.trigger(:before_tool_use, call)
1612
1641
  if hook_result[:action] == :deny
@@ -1747,6 +1776,8 @@ module Clacky
1747
1776
  result = tool.execute(**args)
1748
1777
  end
1749
1778
 
1779
+ notify_user = false if result.is_a?(Hash) && result[:notify_user] == false
1780
+
1750
1781
  # Hook: after_tool_use
1751
1782
  @hooks.trigger(:after_tool_use, call, result)
1752
1783
 
@@ -1807,6 +1838,16 @@ module Clacky
1807
1838
  end
1808
1839
 
1809
1840
  results << build_success_result(call, result)
1841
+ # Tools may end this turn after committing their result (e.g. a durable wait).
1842
+ if result.is_a?(Hash) && result[:end_turn] == true
1843
+ end_turn = true
1844
+ awaiting_feedback = result[:awaiting_feedback] == true
1845
+ # Settle every call in this batch, but execute nothing after yielding.
1846
+ tool_calls.drop(index + 1).each do |remaining|
1847
+ results << build_denied_result(remaining, "Turn ended; remaining calls were not executed", true)
1848
+ end
1849
+ break
1850
+ end
1810
1851
  rescue StandardError => e
1811
1852
  # Log complete error information to debug_logs for troubleshooting
1812
1853
  @debug_logs << {
@@ -1831,7 +1872,9 @@ module Clacky
1831
1872
  denied: denied,
1832
1873
  feedback: feedback,
1833
1874
  tool_results: results,
1834
- awaiting_feedback: awaiting_feedback
1875
+ awaiting_feedback: awaiting_feedback,
1876
+ end_turn: end_turn,
1877
+ notify_user: notify_user
1835
1878
  }
1836
1879
  end
1837
1880
 
@@ -1255,8 +1255,10 @@ module Clacky
1255
1255
  m = @models.find { |mm| mm["id"] == @current_model_id }
1256
1256
  return m if m
1257
1257
  # id no longer exists (model was deleted). Fall through to other
1258
- # resolution strategies below, and clear the stale id.
1258
+ # resolution strategies below, and clear the stale id. The sub-model
1259
+ # pin belonged to the deleted card's provider, so it goes too.
1259
1260
  @current_model_id = nil
1261
+ @session_model_overlay = nil
1260
1262
  end
1261
1263
 
1262
1264
  default_model = find_model_by_type("default")