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
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: a120f8d1189892876508f1c49309b7e4a21652c9293499211444b6e42770f649
4
- data.tar.gz: 2c02a199d26ae835426fa5ce8fb65665ac3c342aa7b717337c3e72470fd868f7
3
+ metadata.gz: 5b5f420c625379fad464ab7f88912b46d3c8bfd17dbb14c58274ed0841d0039e
4
+ data.tar.gz: 6f8df699a2a7097348bba112445687429b17aa2617f1265ad83107a1aa7778fd
5
5
  SHA512:
6
- metadata.gz: aed2dcb3fb47de8a9fc9b20cccbae1f45e70338b37a44e5edbea6ec54c8c3065a27976a2ea5cb2b34ac209cbc3d53c8b6866598deb1a78ff5194ecbef6c0d66e
7
- data.tar.gz: 948e67f2dc8f003e55daea5f8e4d790e5368ef58eec63489d317e8be4336e2e04a9db498bdb1e362005a66b502f930a1dd5c88e9da6607863d9dfc4b06986feb
6
+ metadata.gz: 462d32d168319ebc8d1366636ffe7cbcd5df1d748334180e12e688928f9abd72a8c7e8887ee8d3fb71c269a835fdd014a7bf8387fc6aeff5b2b98ca40833d217
7
+ data.tar.gz: e74fdb9dfdc042b922544f6eb80f0a7b6c029d25f6e5e15a841ee8277aa32830c5dcd733a049cc9225851689d18d66665e9301480ffb3c0875dc6e644b582484
data/CHANGELOG.md CHANGED
@@ -4,6 +4,125 @@ 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
+
65
+ ## [1.5.22] - 2026-10-30
66
+
67
+ ### Added
68
+ - Rebuild the Git changes panel with scoped review and lazy diffs
69
+ - Choose which unpushed commits to review and which base to compare against, from the committed scope pill
70
+ - Scroll each diff pane sideways on its own while the gutters stay pinned
71
+ - Open a per-file menu from the diff header
72
+ - Show file icons in the changes panel diff headers
73
+ - Toggle the file tree and expand all from the Git panel's single-row toolbar
74
+ - Add a git branch picker to the new session page
75
+ - Drag workspace files straight into the composer
76
+ - Recall sent messages with the arrow keys in the composer
77
+ - Zoom and pan image previews
78
+ - Open attachment cards in the file preview
79
+ - Add a chrome-style preview toolbar with zoom controls
80
+ - Redesign the scheduled tasks page
81
+ - Show when each scheduled task runs next
82
+ - Toggle the aside panel with Cmd/Ctrl+L, and show the shortcut in its tooltip
83
+ - Move the pending input queue above the session info bar
84
+ - Hide the chat column when showing the aside would leave it too narrow
85
+ - Keep the task summary visible until the unread session is opened
86
+ - Show vendor icons on the model cards in settings
87
+ - Reuse file-tree icons for attachment chips
88
+ - Add Office, PDF and text file icons
89
+ - Add Kimi K3.1 Pro and K3.1 Pro Highspeed, and default Kimi to K3.1 Pro
90
+
91
+ ### Improved
92
+ - Draw every icon-button hint through one shared tooltip that measures itself before it opens
93
+ - Group the diff toolbar buttons into one pill and soften the Git panel icons
94
+ - Translate tooltips in place when the language changes, including the composer and session info bar
95
+ - Tighten task card typography and give billing controls more breathing room
96
+ - Switch the theme in a single cross-fade instead of a flash
97
+ - Treat the theme accent and the recycle bin as one hover region
98
+ - Draw the slash command button as an icon
99
+ - Fade the leading edge of scrolling text
100
+ - Share one session list scan across concurrent callers
101
+ - Disable browser auto-translation on the web pages
102
+
103
+ ### Fixed
104
+ - Explain a missing working directory in the file tree
105
+ - Detect open-with apps for files without an extension
106
+ - Report a failure to open a file instead of returning a silent success
107
+ - Stop leaking the open-with template into the picker label
108
+ - End the `ask_user` countdown when switching to manual so the session waits for an answer
109
+ - Store web search API keys per provider so switching providers never reuses another provider's key
110
+ - Keep agent-resolved `ask_user` cards closed when replaying history
111
+ - Light the done dot only on `task_finished`
112
+ - Make the open project session highlight translucent so the drop frame shows through
113
+ - Keep the drop zone inside the chat column
114
+ - Add the missing workspace preview label
115
+ - Keep the Git panel scope pill on the first row of a narrow toolbar
116
+ - Hide the shared tooltip when its anchor is clicked
117
+ - Keep the preview address bar in sync with in-frame navigation
118
+ - Keep billing period buttons inside their own panel
119
+ - Lighten extension descriptions
120
+
121
+ ### More
122
+ - Rename DeepSeek Flash to `dsk-deepseek-v4.1-flash`, and refresh the Volcengine Ark lineup and pricing
123
+ - Bill the Claude series at 45% of list
124
+ - Unify the localStorage key naming
125
+
7
126
  ## [1.5.21] - 2026-10-22
8
127
 
9
128
  ### 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