@picassohq/cli 0.0.0-stage → 1.0.1

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 (230) hide show
  1. package/agents/browser_agent.yaml +53 -0
  2. package/agents/code_reviewer.yaml +49 -0
  3. package/agents/codebase_investigator.yaml +70 -0
  4. package/agents/design_auditor.yaml +50 -0
  5. package/agents/devex_auditor.yaml +50 -0
  6. package/agents/doc_writer.yaml +54 -0
  7. package/agents/engineering_architect.yaml +51 -0
  8. package/agents/generalist.yaml +55 -0
  9. package/agents/migration_planner.yaml +51 -0
  10. package/agents/product_reviewer.yaml +48 -0
  11. package/agents/qa_operator.yaml +52 -0
  12. package/agents/release_engineer.yaml +50 -0
  13. package/agents/security_auditor.yaml +62 -0
  14. package/agents/test_writer.yaml +52 -0
  15. package/assets/first-light-lockup.png +0 -0
  16. package/assets/first-light-tagline.png +0 -0
  17. package/assets/house/README.md +26 -0
  18. package/assets/house/auraone-banner.png +0 -0
  19. package/assets/house/auraone-logo.png +0 -0
  20. package/assets/house/kiro-prism-banner.png +0 -0
  21. package/assets/house/kiro-prism-logo.png +0 -0
  22. package/assets/house/picasso-banner.png +0 -0
  23. package/assets/house/picasso-logo.png +0 -0
  24. package/assets/wordmark-app.png +0 -0
  25. package/assets/wordmark-tight.png +0 -0
  26. package/assets/wordmark.png +0 -0
  27. package/design/styles.css +1042 -0
  28. package/dist/build-info.json +37 -0
  29. package/dist/index.js +3028 -0
  30. package/goals/cli-hardening.yaml +40 -0
  31. package/goals/repo-maintenance.yaml +40 -0
  32. package/package.json +49 -4
  33. package/runtime/dsh/picasso-ecosystem.community.amendments.yml +24 -0
  34. package/runtime/dsh/picasso-ecosystem.community.json +185 -0
  35. package/runtime/dsh/picasso-ecosystem.community.patch.yml +40 -0
  36. package/runtime/dsh/picasso-ecosystem.cordis.patch.yml +143 -0
  37. package/runtime/dsh/picasso-isolation.patch.yml +25 -0
  38. package/runtime/dsh/picasso-providers.patch.yml +373 -0
  39. package/runtime/dsh/picasso-runtime.cordis.yml +738 -0
  40. package/runtime/dsh/picasso-sdk.patch.yml +204 -0
  41. package/runtime/engine-manifest.json +214 -0
  42. package/runtime/package.json +6 -0
  43. package/runtime/packages/picasso-cache-probe/cordis.patch.yml +5 -0
  44. package/runtime/packages/picasso-cache-probe/index.js +477 -0
  45. package/runtime/packages/picasso-cache-probe/package.json +38 -0
  46. package/runtime/packages/picasso-commands/cordis.patch.yml +4 -0
  47. package/runtime/packages/picasso-commands/fresh-review.js +573 -0
  48. package/runtime/packages/picasso-commands/index.js +497 -0
  49. package/runtime/packages/picasso-commands/package.json +28 -0
  50. package/runtime/packages/picasso-instructions/conflicts.js +115 -0
  51. package/runtime/packages/picasso-instructions/formats.js +145 -0
  52. package/runtime/packages/picasso-instructions/frontmatter.js +175 -0
  53. package/runtime/packages/picasso-instructions/glob.js +114 -0
  54. package/runtime/packages/picasso-instructions/globals.js +90 -0
  55. package/runtime/packages/picasso-instructions/imports.js +123 -0
  56. package/runtime/packages/picasso-instructions/index.js +326 -0
  57. package/runtime/packages/picasso-instructions/modes.js +64 -0
  58. package/runtime/packages/picasso-instructions/package.json +30 -0
  59. package/runtime/packages/picasso-instructions/parse.js +134 -0
  60. package/runtime/packages/picasso-instructions/report.js +161 -0
  61. package/runtime/packages/picasso-instructions/resolve.js +939 -0
  62. package/runtime/packages/picasso-instructions/scan.js +181 -0
  63. package/runtime/packages/picasso-instructions/settings.js +150 -0
  64. package/runtime/packages/picasso-instructions/skills.js +345 -0
  65. package/runtime/packages/picasso-lean-context/cordis.patch.yml +13 -0
  66. package/runtime/packages/picasso-lean-context/index.js +6049 -0
  67. package/runtime/packages/picasso-lean-context/package.json +26 -0
  68. package/runtime/packages/picasso-lean-context/timeline.js +417 -0
  69. package/runtime/packages/picasso-librarian/classify.js +146 -0
  70. package/runtime/packages/picasso-librarian/cordis.patch.yml +10 -0
  71. package/runtime/packages/picasso-librarian/index.js +878 -0
  72. package/runtime/packages/picasso-librarian/notes.js +159 -0
  73. package/runtime/packages/picasso-librarian/package.json +34 -0
  74. package/runtime/packages/picasso-librarian/state.js +478 -0
  75. package/runtime/packages/picasso-memory/index.js +1184 -0
  76. package/runtime/packages/picasso-memory/package.json +21 -0
  77. package/runtime/packages/picasso-model-router/connections.js +895 -0
  78. package/runtime/packages/picasso-model-router/cordis.patch.yml +17 -0
  79. package/runtime/packages/picasso-model-router/index.js +1081 -0
  80. package/runtime/packages/picasso-model-router/package.json +30 -0
  81. package/runtime/packages/picasso-options/cordis.patch.yml +4 -0
  82. package/runtime/packages/picasso-options/index.js +263 -0
  83. package/runtime/packages/picasso-options/package.json +28 -0
  84. package/runtime/packages/picasso-progress-reports/cordis.patch.yml +10 -0
  85. package/runtime/packages/picasso-progress-reports/index.js +267 -0
  86. package/runtime/packages/picasso-progress-reports/package.json +30 -0
  87. package/runtime/packages/picasso-progress-reports/report.js +235 -0
  88. package/runtime/packages/picasso-sdk-server/aside.js +128 -0
  89. package/runtime/packages/picasso-sdk-server/connections.js +38 -0
  90. package/runtime/packages/picasso-sdk-server/context-timeline.js +27 -0
  91. package/runtime/packages/picasso-sdk-server/egress-gate.js +520 -0
  92. package/runtime/packages/picasso-sdk-server/failure-policy.js +246 -0
  93. package/runtime/packages/picasso-sdk-server/file-input.js +169 -0
  94. package/runtime/packages/picasso-sdk-server/goal.js +131 -0
  95. package/runtime/packages/picasso-sdk-server/ignore-file.js +458 -0
  96. package/runtime/packages/picasso-sdk-server/ignore-plugin.js +12 -0
  97. package/runtime/packages/picasso-sdk-server/ignore-sandbox.js +122 -0
  98. package/runtime/packages/picasso-sdk-server/ignore-snapshot.js +131 -0
  99. package/runtime/packages/picasso-sdk-server/image-input.js +44 -0
  100. package/runtime/packages/picasso-sdk-server/index.js +886 -0
  101. package/runtime/packages/picasso-sdk-server/instructions.js +34 -0
  102. package/runtime/packages/picasso-sdk-server/jobs.js +113 -0
  103. package/runtime/packages/picasso-sdk-server/mcp-gate.js +51 -0
  104. package/runtime/packages/picasso-sdk-server/model-selection.js +162 -0
  105. package/runtime/packages/picasso-sdk-server/package.json +50 -0
  106. package/runtime/packages/picasso-sdk-server/picasso-records.js +50 -0
  107. package/runtime/packages/picasso-sdk-server/provider-reload.js +84 -0
  108. package/runtime/packages/picasso-sdk-server/queue.js +322 -0
  109. package/runtime/packages/picasso-sdk-server/requester.js +43 -0
  110. package/runtime/packages/picasso-sdk-server/rewind.js +108 -0
  111. package/runtime/packages/picasso-sdk-server/schedule.js +187 -0
  112. package/runtime/packages/picasso-sdk-server/session-grants.js +35 -0
  113. package/runtime/packages/picasso-sdk-server/session-state.js +118 -0
  114. package/runtime/packages/picasso-sdk-server/shell-paths.js +869 -0
  115. package/runtime/packages/picasso-sdk-server/stream-deltas.js +211 -0
  116. package/runtime/packages/picasso-sdk-server/team-tasks.js +451 -0
  117. package/runtime/packages/picasso-sdk-server/tool-output.js +128 -0
  118. package/runtime/packages/picasso-sdk-server/tools-list.js +51 -0
  119. package/runtime/packages/picasso-sdk-server/wave2-hooks.js +612 -0
  120. package/runtime/packages/picasso-sdk-server/workspace-archive.js +170 -0
  121. package/runtime/packages/picasso-sdk-server/workspace-restore.js +180 -0
  122. package/runtime/packages/picasso-web-search/backends.js +350 -0
  123. package/runtime/packages/picasso-web-search/config.js +121 -0
  124. package/runtime/packages/picasso-web-search/cordis.patch.yml +7 -0
  125. package/runtime/packages/picasso-web-search/failure.js +111 -0
  126. package/runtime/packages/picasso-web-search/format.js +35 -0
  127. package/runtime/packages/picasso-web-search/index.js +66 -0
  128. package/runtime/packages/picasso-web-search/package.json +38 -0
  129. package/runtime/packages/picasso-web-search/router.js +155 -0
  130. package/runtime/packages/picasso-x-reader/circle.js +324 -0
  131. package/runtime/packages/picasso-x-reader/command.js +169 -0
  132. package/runtime/packages/picasso-x-reader/cordis.patch.yml +8 -0
  133. package/runtime/packages/picasso-x-reader/index.js +170 -0
  134. package/runtime/packages/picasso-x-reader/package.json +39 -0
  135. package/runtime/packages/picasso-x-reader/read.js +370 -0
  136. package/runtime/packages/picasso-x-reader/rewrite.js +38 -0
  137. package/runtime/packages/picasso-x-reader/settings.js +131 -0
  138. package/runtime/packages/picasso-x-reader/urls.js +154 -0
  139. package/runtime/packages/picasso-x-reader/xmd.js +512 -0
  140. package/runtime/plugins/picasso-auth-bridge/index.js +380 -0
  141. package/runtime/plugins/picasso-auth-bridge/package.json +28 -0
  142. package/runtime/plugins/picasso-auto-approve/index.js +1003 -0
  143. package/runtime/plugins/picasso-auto-approve/package.json +28 -0
  144. package/runtime/plugins/picasso-browser/index.js +424 -0
  145. package/runtime/plugins/picasso-browser/package.json +28 -0
  146. package/runtime/plugins/picasso-checkpoints/evidence.js +210 -0
  147. package/runtime/plugins/picasso-checkpoints/index.js +885 -0
  148. package/runtime/plugins/picasso-checkpoints/package.json +29 -0
  149. package/runtime/plugins/picasso-commands/fresh-review.js +573 -0
  150. package/runtime/plugins/picasso-commands/index.js +497 -0
  151. package/runtime/plugins/picasso-commands/package.json +28 -0
  152. package/runtime/plugins/picasso-instructions/conflicts.js +115 -0
  153. package/runtime/plugins/picasso-instructions/formats.js +145 -0
  154. package/runtime/plugins/picasso-instructions/frontmatter.js +175 -0
  155. package/runtime/plugins/picasso-instructions/glob.js +114 -0
  156. package/runtime/plugins/picasso-instructions/globals.js +90 -0
  157. package/runtime/plugins/picasso-instructions/imports.js +123 -0
  158. package/runtime/plugins/picasso-instructions/index.js +326 -0
  159. package/runtime/plugins/picasso-instructions/modes.js +64 -0
  160. package/runtime/plugins/picasso-instructions/package.json +30 -0
  161. package/runtime/plugins/picasso-instructions/parse.js +134 -0
  162. package/runtime/plugins/picasso-instructions/report.js +161 -0
  163. package/runtime/plugins/picasso-instructions/resolve.js +939 -0
  164. package/runtime/plugins/picasso-instructions/scan.js +181 -0
  165. package/runtime/plugins/picasso-instructions/settings.js +150 -0
  166. package/runtime/plugins/picasso-instructions/skills.js +345 -0
  167. package/runtime/plugins/picasso-lean-context/index.js +6049 -0
  168. package/runtime/plugins/picasso-lean-context/package.json +26 -0
  169. package/runtime/plugins/picasso-lean-context/timeline.js +417 -0
  170. package/runtime/plugins/picasso-librarian/classify.js +146 -0
  171. package/runtime/plugins/picasso-librarian/index.js +878 -0
  172. package/runtime/plugins/picasso-librarian/notes.js +159 -0
  173. package/runtime/plugins/picasso-librarian/package.json +34 -0
  174. package/runtime/plugins/picasso-librarian/state.js +478 -0
  175. package/runtime/plugins/picasso-lifecycle-hooks/index.js +186 -0
  176. package/runtime/plugins/picasso-lifecycle-hooks/package.json +25 -0
  177. package/runtime/plugins/picasso-mail/inbox.js +207 -0
  178. package/runtime/plugins/picasso-mail/index.js +293 -0
  179. package/runtime/plugins/picasso-mail/package.json +22 -0
  180. package/runtime/plugins/picasso-memory/index.js +1184 -0
  181. package/runtime/plugins/picasso-memory/package.json +21 -0
  182. package/runtime/plugins/picasso-model-router/connections.js +895 -0
  183. package/runtime/plugins/picasso-model-router/index.js +1081 -0
  184. package/runtime/plugins/picasso-model-router/package.json +30 -0
  185. package/runtime/plugins/picasso-options/index.js +263 -0
  186. package/runtime/plugins/picasso-options/package.json +28 -0
  187. package/runtime/plugins/picasso-progress-reports/index.js +267 -0
  188. package/runtime/plugins/picasso-progress-reports/package.json +30 -0
  189. package/runtime/plugins/picasso-progress-reports/report.js +235 -0
  190. package/runtime/plugins/picasso-provider-models/index.js +436 -0
  191. package/runtime/plugins/picasso-provider-models/package.json +28 -0
  192. package/runtime/plugins/picasso-repo-index/index.js +1850 -0
  193. package/runtime/plugins/picasso-repo-index/package.json +28 -0
  194. package/runtime/plugins/picasso-schedule-pause/index.js +344 -0
  195. package/runtime/plugins/picasso-schedule-pause/package.json +28 -0
  196. package/runtime/plugins/picasso-session-lifecycle/index.js +796 -0
  197. package/runtime/plugins/picasso-session-lifecycle/package.json +28 -0
  198. package/runtime/plugins/picasso-trackers/index.js +895 -0
  199. package/runtime/plugins/picasso-trackers/package.json +28 -0
  200. package/runtime/plugins/picasso-web-search/backends.js +350 -0
  201. package/runtime/plugins/picasso-web-search/config.js +121 -0
  202. package/runtime/plugins/picasso-web-search/failure.js +111 -0
  203. package/runtime/plugins/picasso-web-search/format.js +35 -0
  204. package/runtime/plugins/picasso-web-search/index.js +66 -0
  205. package/runtime/plugins/picasso-web-search/package.json +38 -0
  206. package/runtime/plugins/picasso-web-search/router.js +155 -0
  207. package/runtime/plugins/picasso-x-reader/circle.js +324 -0
  208. package/runtime/plugins/picasso-x-reader/command.js +169 -0
  209. package/runtime/plugins/picasso-x-reader/index.js +170 -0
  210. package/runtime/plugins/picasso-x-reader/package.json +39 -0
  211. package/runtime/plugins/picasso-x-reader/read.js +370 -0
  212. package/runtime/plugins/picasso-x-reader/rewrite.js +38 -0
  213. package/runtime/plugins/picasso-x-reader/settings.js +131 -0
  214. package/runtime/plugins/picasso-x-reader/urls.js +154 -0
  215. package/runtime/plugins/picasso-x-reader/xmd.js +512 -0
  216. package/runtime/relay/attachment-text.mjs +737 -0
  217. package/runtime/relay/companion/companion.css +126 -0
  218. package/runtime/relay/companion/companion.js +648 -0
  219. package/runtime/relay/companion/icon.svg +5 -0
  220. package/runtime/relay/companion/index.html +25 -0
  221. package/runtime/relay/companion/manifest.json +13 -0
  222. package/runtime/relay/companion/sw.js +41 -0
  223. package/runtime/relay/main.mjs +37252 -0
  224. package/runtime/relay/model-listing.mjs +614 -0
  225. package/runtime/relay/versions-routes.mjs +1198 -0
  226. package/runtime/verify-plugins.mjs +205 -0
  227. package/runtime-lock/package-lock.json +10779 -0
  228. package/runtime-lock/package.json +7 -0
  229. package/scripts/install-runtime.mjs +400 -0
  230. package/README.md +0 -3
@@ -0,0 +1,186 @@
1
+ // @picasso/lifecycle-hooks — config-driven user hooks for dsh lifecycle
2
+ // events (dsh 0.2.1-rc.5): session create, turn start, turn end.
3
+ //
4
+ // config: {
5
+ // hooks: {
6
+ // onSessionCreate: ["/abs/path/cmd", "arg1"],
7
+ // onTurnStart: ["npm", "run", "turn-start"],
8
+ // onTurnEnd: ["/abs/path/cmd"]
9
+ // },
10
+ // timeoutMs: 15000 // per-hook ceiling (default 15000)
11
+ // }
12
+ //
13
+ // Each value is an argv array — NEVER a shell string: the command spawns via
14
+ // child_process.execFile with no shell, so quoting/metacharacters are data,
15
+ // not syntax. Executables are validated at mount: absolute paths must exist;
16
+ // bare names must resolve on PATH. A hook whose executable is missing is
17
+ // dropped with a warning, not mounted.
18
+ //
19
+ // Sources, merged file-first then config.hooks overrides:
20
+ // config.file / PICASSO_LIFECYCLE_HOOKS_FILE — a JSON file with the same
21
+ // hooks map ({ "onTurnEnd": ["cmd","arg"], ... }), for hosts that mount the
22
+ // plugin without patch config.
23
+ //
24
+ // Event surfaces: `session/created` (session create) and `session/event`
25
+ // (`turn/start` / `turn/end` in the durable log). Hooks run fail-open off the
26
+ // hot path — a hook failure never breaks a turn — with the event context in
27
+ // env: PICASSO_HOOK_EVENT (session-create|turn-start|turn-end),
28
+ // PICASSO_SESSION_ID, PICASSO_TURN_ID (empty on session create).
29
+ import { execFile } from 'node:child_process';
30
+ import { existsSync, readFileSync } from 'node:fs';
31
+ import { delimiter } from 'node:path';
32
+
33
+ export const name = 'picasso-lifecycle-hooks';
34
+ export const dshTarget = '0.2.2-rc.3';
35
+ export const ENV_FILE = 'PICASSO_LIFECYCLE_HOOKS_FILE';
36
+ export const HOOK_EVENTS = /** @type {const} */ ({
37
+ onSessionCreate: 'session-create',
38
+ onTurnStart: 'turn-start',
39
+ onTurnEnd: 'turn-end',
40
+ });
41
+ export const DEFAULT_TIMEOUT_MS = 15000;
42
+ const MAX_ARGV = 64;
43
+
44
+ const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
45
+
46
+ /** Parse one hooks map into event→argv rows. Throws on malformed input — a bad hooks config is a misconfiguration. */
47
+ export function parseHooksMap(map, label = 'hooks') {
48
+ if (map === undefined || map === null) return {};
49
+ if (!isRecord(map)) throw new Error(`${name}: ${label} must be an object mapping event names to argv arrays`);
50
+ const parsed = {};
51
+ for (const [event, argv] of Object.entries(map)) {
52
+ if (!(event in HOOK_EVENTS)) throw new Error(`${name}: ${label}.${event} is not a lifecycle event (expected one of ${Object.keys(HOOK_EVENTS).join(', ')})`);
53
+ if (!Array.isArray(argv) || argv.length === 0 || argv.length > MAX_ARGV) {
54
+ throw new Error(`${name}: ${label}.${event} must be an argv array of 1-${MAX_ARGV} strings (never a shell string)`);
55
+ }
56
+ for (const [index, part] of argv.entries()) {
57
+ if (typeof part !== 'string' || part.length === 0) throw new Error(`${name}: ${label}.${event}[${index}] must be a non-empty string`);
58
+ if (part.includes('\0')) throw new Error(`${name}: ${label}.${event}[${index}] contains a NUL byte`);
59
+ }
60
+ parsed[event] = [...argv];
61
+ }
62
+ return parsed;
63
+ }
64
+
65
+ /** Read a JSON hooks file leniently: a missing/unreadable file is no hooks; a malformed document throws. */
66
+ export function readHooksFile(file) {
67
+ if (typeof file !== 'string' || file === '') return {};
68
+ let text;
69
+ try {
70
+ text = readFileSync(file, 'utf8');
71
+ } catch (error) {
72
+ if (error?.code === 'ENOENT') return {};
73
+ throw error;
74
+ }
75
+ let parsed;
76
+ try {
77
+ parsed = JSON.parse(text);
78
+ } catch (error) {
79
+ throw new Error(`${name}: ${file} is not valid JSON: ${error.message}`);
80
+ }
81
+ return parseHooksMap(isRecord(parsed) && 'hooks' in parsed ? parsed.hooks : parsed, file);
82
+ }
83
+
84
+ /** Where a hook's executable resolves: absolute/explicit-relative path must exist; a bare name must land on PATH. */
85
+ export function resolveExecutable(command, env = process.env) {
86
+ if (command.includes('/')) return existsSync(command) ? command : undefined;
87
+ for (const dir of (env.PATH ?? '').split(delimiter).filter(Boolean)) {
88
+ const candidate = `${dir}/${command}`;
89
+ if (existsSync(candidate)) return candidate;
90
+ }
91
+ return undefined;
92
+ }
93
+
94
+ /**
95
+ * Merge sources and keep only hooks whose executable resolves. Returns
96
+ * `{hooks, dropped}` — dropped names (with reasons) so apply() can warn once
97
+ * and tests can assert the drop without a logger.
98
+ */
99
+ export function prepareHooks(maps, env = process.env) {
100
+ const merged = {};
101
+ for (const map of maps) Object.assign(merged, map);
102
+ const hooks = {};
103
+ const dropped = [];
104
+ for (const [event, argv] of Object.entries(merged)) {
105
+ const resolved = resolveExecutable(argv[0], env);
106
+ if (resolved === undefined) {
107
+ dropped.push({ event, command: argv[0], reason: `executable not found: ${argv[0]}` });
108
+ continue;
109
+ }
110
+ hooks[event] = { argv: [resolved, ...argv.slice(1)] };
111
+ }
112
+ return { hooks, dropped };
113
+ }
114
+
115
+ /** The env a hook sees: the ambient env plus the event identity. */
116
+ export function hookEnv(event, { sessionId, turnId }, env = process.env) {
117
+ return {
118
+ ...env,
119
+ PICASSO_HOOK_EVENT: HOOK_EVENTS[event],
120
+ PICASSO_SESSION_ID: sessionId ?? '',
121
+ PICASSO_TURN_ID: turnId ?? '',
122
+ };
123
+ }
124
+
125
+ /** The execFile invocation for one hook fire — argv array, no shell, bounded. */
126
+ export function hookInvocation(hook, event, context, timeoutMs = DEFAULT_TIMEOUT_MS, env = process.env) {
127
+ const [command, ...args] = hook.argv;
128
+ return {
129
+ command,
130
+ args,
131
+ options: {
132
+ env: hookEnv(event, context, env),
133
+ timeout: timeoutMs,
134
+ maxBuffer: 256 * 1024,
135
+ windowsHide: true,
136
+ },
137
+ };
138
+ }
139
+
140
+ export function apply(ctx, config = {}, deps = {}) {
141
+ const run = deps.execFile ?? execFile;
142
+ const log = typeof ctx.logger?.warn === 'function' ? (line) => ctx.logger.warn(line) : (line) => console.warn(line);
143
+ const timeoutMs = Number.isFinite(config.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
144
+ let fileHooks;
145
+ try {
146
+ fileHooks = readHooksFile(config.file ?? process.env[ENV_FILE]);
147
+ } catch (error) {
148
+ log(`[picasso-lifecycle-hooks] ${error.message}`);
149
+ fileHooks = {};
150
+ }
151
+ const configHooks = parseHooksMap(config.hooks ?? {}, 'config.hooks');
152
+ const { hooks, dropped } = prepareHooks([fileHooks, configHooks]);
153
+ for (const drop of dropped) log(`[picasso-lifecycle-hooks] ${drop.event} hook skipped — ${drop.reason}`);
154
+ const events = Object.keys(hooks);
155
+ if (events.length === 0) return; // default OFF: no hooks configured or all dropped
156
+
157
+ const fire = (event, context) => {
158
+ const spec = hookInvocation(hooks[event], event, context, timeoutMs);
159
+ run(spec.command, spec.args, spec.options, () => undefined); // fail-open, off the hot path
160
+ };
161
+
162
+ const disposers = [];
163
+ if (hooks.onSessionCreate) {
164
+ disposers.push(
165
+ ctx.on('session/created', (session) => {
166
+ fire('onSessionCreate', { sessionId: session?.header?.id ?? session?.id, turnId: '' });
167
+ }),
168
+ );
169
+ }
170
+ if (hooks.onTurnStart || hooks.onTurnEnd) {
171
+ disposers.push(
172
+ ctx.on('session/event', (session, event) => {
173
+ const turn = event?.data?.turn;
174
+ const context = {
175
+ sessionId: session?.header?.id ?? session?.id,
176
+ turnId: typeof turn === 'string' ? turn : turn?.id,
177
+ };
178
+ if (event?.type === 'turn/start' && hooks.onTurnStart) fire('onTurnStart', context);
179
+ else if (event?.type === 'turn/end' && hooks.onTurnEnd) fire('onTurnEnd', context);
180
+ }),
181
+ );
182
+ }
183
+ return () => {
184
+ for (const dispose of disposers) dispose?.();
185
+ };
186
+ }
@@ -0,0 +1,25 @@
1
+ {
2
+ "name": "@picasso/lifecycle-hooks",
3
+ "version": "0.1.0",
4
+ "private": true,
5
+ "description": "dsh cordis plugin: runs user-configured commands (argv arrays via child_process.execFile, never shell strings) on lifecycle events — onSessionCreate, onTurnStart, onTurnEnd. Executables are validated at mount; hooks run fail-open off the hot path.",
6
+ "type": "module",
7
+ "main": "index.js",
8
+ "exports": {
9
+ ".": "./index.js",
10
+ "./cordis.patch.yml": "./cordis.patch.yml",
11
+ "./package.json": "./package.json"
12
+ },
13
+ "dshTarget": "0.2.2-rc.3",
14
+ "dsh": {
15
+ "bundle": {
16
+ "patch": "./cordis.patch.yml"
17
+ }
18
+ },
19
+ "files": [
20
+ "index.js",
21
+ "cordis.patch.yml",
22
+ "README.md"
23
+ ],
24
+ "license": "UNLICENSED"
25
+ }
@@ -0,0 +1,207 @@
1
+ // `picassoInbox/*` — inbox control the Host Remote API lacks, for the Mac relay (the CLI/TUI has the same two
2
+ // operations on `@picasso/sdk-server` `session/queue` mode `interrupt` and `session/queue/update` `move`):
3
+ //
4
+ // picassoInbox/interrupt {sessionId, requestId?, content?, itemId?} -> {accepted, requestId, interrupted}
5
+ // Stop the running step and run this message as the very next turn. The queued turns are lifted out of the
6
+ // `next-turn` inbox without being canceled, the turn is stopped through the session controller's own `cancel`
7
+ // (the user's stop: `agent.cancel({kind:'user'}, {keepInbox: true})`, subagent refusals included), the message
8
+ // is admitted through `commands.prompt` (attachments, rpcId dedup and every dsh refusal included) and the lifted
9
+ // turns go back behind it, ids and order intact. While the aborted turn unwinds dsh latches the wake, so the
10
+ // message starts the moment the turn converges; on an idle session it simply jumps the queue.
11
+ // `itemId` sends a message that is still pending instead (a steer waiting behind a long tool call: "interrupt
12
+ // and send"): it leaves the inbox canceled and its stored content is admitted when `content` is omitted.
13
+ // picassoInbox/move {sessionId, itemId, index} -> {accepted}
14
+ // Reorder one queued turn to `index` (clamped) with a single inbox splice: no remove-and-requeue, so the
15
+ // message keeps its id, content and attachments.
16
+ // picassoInbox/resume {sessionId} -> {accepted, started}
17
+ // Run the queue a Stop left behind. The user's stop keeps the `next-turn` inbox (`keepInbox`) but nothing wakes
18
+ // the idle agent until another message arrives, so the queue sits paused. This wakes the driver the way a new
19
+ // message would, without adding one: the oldest queued turn runs next and the rest follow in order. `started`
20
+ // is false when there was nothing to run or a turn is already running (it drains the queue itself).
21
+ //
22
+ // Both splice without discarding (`agent/inbox/discarded` is never emitted for a message that comes straight back:
23
+ // a goal round or a question reply that is only moved must not read as withdrawn).
24
+ import { randomUUID } from 'node:crypto';
25
+
26
+ export const INBOX_SERVICE_KEY = 'picassoInbox';
27
+ const REMOTE_METHOD_DESCRIPTOR = '@deepseek-ai/dsh-typert-protocol/remote-methods';
28
+ const REMOTE_METHODS = ['interrupt', 'move', 'resume'];
29
+
30
+ const nonempty = (value) => (typeof value === 'string' && value.length > 0 ? value : undefined);
31
+
32
+ /** A dsh RemoteError, identified structurally by the gateway, so the code reaches the client on the 422 channel. */
33
+ export class InboxError extends Error {
34
+ constructor(code, message, details = {}) {
35
+ super(message);
36
+ this.name = 'RemoteError';
37
+ this.code = code;
38
+ this.details = details;
39
+ this.isDSHRemoteError = true;
40
+ }
41
+ }
42
+
43
+ /** A non-discarding splice (dsh's claim uses the same mutation); the public splice is the fallback. */
44
+ export function spliceKeeping(inbox, target, start, deleteCount, inserted) {
45
+ if (typeof inbox.mutate === 'function') return inbox.mutate(target, start, deleteCount, inserted, false);
46
+ return inbox.splice(target, start, deleteCount, inserted);
47
+ }
48
+
49
+ /** Move one pending `next-turn` message to `index` (clamped) in one splice; false when it is not pending. */
50
+ export function moveQueued(agent, itemId, index) {
51
+ const inbox = agent.inbox;
52
+ const list = inbox.nextTurn;
53
+ const from = list.findIndex((message) => String(message.id) === String(itemId));
54
+ if (from < 0) return false;
55
+ const to = Math.max(0, Math.min(list.length - 1, Math.trunc(Number(index))));
56
+ if (!Number.isFinite(to) || to === from) return true;
57
+ const low = Math.min(from, to);
58
+ const span = list.slice(low, Math.max(from, to) + 1);
59
+ const moved = span.splice(from - low, 1)[0];
60
+ span.splice(to - low, 0, moved);
61
+ spliceKeeping(inbox, 'next-turn', low, span.length, span);
62
+ return true;
63
+ }
64
+
65
+ /** Put lifted queued turns back: behind whatever was admitted, or where they were when nothing was. */
66
+ function restoreParked(agent, parked) {
67
+ if (parked.length === 0) return;
68
+ const inbox = agent.inbox;
69
+ if (agent.status === 'idle' && inbox.nextTurn.length === 0) spliceKeeping(inbox, 'next-turn', 0, 0, parked);
70
+ else spliceKeeping(inbox, 'next-turn', inbox.nextTurn.length, 0, parked);
71
+ }
72
+
73
+ const notPending = (itemId) =>
74
+ new InboxError('session/queue-item-not-found', 'The message is no longer pending: the turn already took it in.', { itemId });
75
+
76
+ /** Takes one pending message out of either inbox list (a canceled removal); throws when it is no longer pending. */
77
+ function takePending(agent, itemId) {
78
+ const inbox = agent.inbox;
79
+ for (const target of ['next-step', 'next-turn']) {
80
+ const list = target === 'next-step' ? inbox.nextStep : inbox.nextTurn;
81
+ const index = list.findIndex((message) => String(message.id) === itemId);
82
+ if (index < 0) continue;
83
+ const message = list[index];
84
+ if (typeof inbox.remove === 'function') inbox.remove(message.id);
85
+ else inbox.splice(target, index, 1, []);
86
+ return { message, target, index };
87
+ }
88
+ throw notPending(itemId);
89
+ }
90
+
91
+ /** Puts a taken message back where it waited (the interrupt that took it was refused). */
92
+ function restoreTaken(agent, taken) {
93
+ const list = taken.target === 'next-step' ? agent.inbox.nextStep : agent.inbox.nextTurn;
94
+ if (list.some((message) => String(message.id) === String(taken.message.id))) return;
95
+ spliceKeeping(agent.inbox, taken.target, Math.min(taken.index, list.length), 0, [taken.message]);
96
+ }
97
+
98
+ export class InboxService {
99
+ /**
100
+ * @param options.agentFor - the live agent for a session id (`ctx.agents.get`); undefined when cold.
101
+ * @param options.commands - lazy `SessionCommandController` accessor (`ctx.sessionController.commands`).
102
+ */
103
+ constructor(options) {
104
+ this.agentFor = options.agentFor;
105
+ this.commands = options.commands;
106
+ this.mint = options.mint ?? randomUUID;
107
+ this.typertRemote = Object.freeze({ service: this, serviceKey: INBOX_SERVICE_KEY, namespace: INBOX_SERVICE_KEY });
108
+ }
109
+
110
+ /**
111
+ * `itemId` (optional) names a message still pending in the inbox — a steer waiting in `next-step` behind a long
112
+ * tool call, or a queued turn — that should go now instead: it is taken out of the inbox (a canceled removal, so no
113
+ * client shows it as delivered) in the same synchronous section as the cancel, and its stored content (text and
114
+ * attachments) is what is sent when `content` is omitted. Already claimed by the turn: `session/queue-item-not-found`.
115
+ */
116
+ async interrupt(sessionId, requestId, content, itemId, signal) {
117
+ signal?.throwIfAborted?.();
118
+ const id = nonempty(sessionId);
119
+ if (id === undefined) throw new InboxError('gateway/bad-request', 'sessionId must be a non-empty string.');
120
+ const pendingId = nonempty(itemId);
121
+ if (content !== undefined || pendingId === undefined) {
122
+ if (!Array.isArray(content) || content.length === 0) throw new InboxError('gateway/bad-request', 'interrupt content must be a non-empty content array.');
123
+ }
124
+ const commands = this.commands();
125
+ if (commands === undefined || typeof commands.prompt !== 'function') throw new InboxError('inbox/unavailable', 'The session controller is not mounted.');
126
+ const rid = nonempty(requestId) ?? this.mint();
127
+ const agent = this.agentFor(id);
128
+ if (agent === undefined) {
129
+ // Cold: nothing runs and nothing is queued in memory — an ordinary prompt.
130
+ if (pendingId !== undefined && content === undefined) throw notPending(pendingId);
131
+ await commands.prompt({ requestId: rid, sessionId: id, mode: 'queue', content }, { kind: 'user', rpcId: rid });
132
+ return { accepted: true, requestId: rid, interrupted: false };
133
+ }
134
+ const taken = pendingId === undefined ? undefined : takePending(agent, pendingId);
135
+ const body = content ?? taken.message.content;
136
+ const waiting = agent.inbox.nextTurn.length;
137
+ const parked = waiting > 0 ? spliceKeeping(agent.inbox, 'next-turn', 0, waiting, []) : [];
138
+ const running = agent.status === 'running';
139
+ let admitted = false;
140
+ try {
141
+ if (running) commands.cancel({ sessionId: id });
142
+ await commands.prompt({ requestId: rid, sessionId: id, mode: 'queue', content: body }, { kind: 'user', rpcId: rid });
143
+ admitted = true;
144
+ } finally {
145
+ restoreParked(agent, parked);
146
+ // A refused admission must not lose the message that was taken out: it goes back where it waited.
147
+ if (!admitted && taken !== undefined) restoreTaken(agent, taken);
148
+ }
149
+ return { accepted: true, requestId: rid, interrupted: running };
150
+ }
151
+
152
+ move(sessionId, itemId, index, signal) {
153
+ signal?.throwIfAborted?.();
154
+ const id = nonempty(sessionId);
155
+ if (id === undefined) throw new InboxError('gateway/bad-request', 'sessionId must be a non-empty string.');
156
+ if (!Number.isSafeInteger(index)) throw new InboxError('gateway/bad-request', 'a move needs an integer index.');
157
+ const agent = this.agentFor(id);
158
+ if (agent === undefined || !moveQueued(agent, itemId, index)) {
159
+ throw new InboxError('session/queue-item-not-found', 'queued item is no longer pending', { itemId });
160
+ }
161
+ return { accepted: true };
162
+ }
163
+
164
+ resume(sessionId, signal) {
165
+ signal?.throwIfAborted?.();
166
+ const id = nonempty(sessionId);
167
+ if (id === undefined) throw new InboxError('gateway/bad-request', 'sessionId must be a non-empty string.');
168
+ const agent = this.agentFor(id);
169
+ if (agent === undefined || agent.inbox.nextTurn.length === 0 || agent.status === 'running') return { accepted: true, started: false };
170
+ if (typeof agent.wakeDriver === 'function') {
171
+ // dsh's own wake (what a followup does after inserting): idle → one driver that claims the head turn.
172
+ agent.wakeDriver();
173
+ return { accepted: true, started: true };
174
+ }
175
+ if (typeof agent.followup !== 'function') throw new InboxError('inbox/unavailable', 'This engine cannot resume a paused queue.');
176
+ // Public fallback: the head goes back in through `followup` (the same message: id, content, attachments), which
177
+ // wakes the agent; the rest go back behind it.
178
+ const parked = spliceKeeping(agent.inbox, 'next-turn', 0, agent.inbox.nextTurn.length, []);
179
+ try {
180
+ agent.followup(parked[0]);
181
+ } finally {
182
+ restoreParked(agent, parked.slice(1));
183
+ }
184
+ return { accepted: true, started: true };
185
+ }
186
+ }
187
+
188
+ Object.defineProperty(InboxService.prototype, REMOTE_METHOD_DESCRIPTOR, {
189
+ configurable: true,
190
+ value: Object.freeze({ version: 1, methods: Object.freeze(REMOTE_METHODS.map((method) => Object.freeze({ method, invocation: Object.freeze({ kind: 'direct' }) }))) }),
191
+ });
192
+
193
+ /** Provides `picassoInbox` beside `mail` (called from the mail plugin's `apply`). */
194
+ export function applyInbox(ctx) {
195
+ const service = new InboxService({
196
+ agentFor: (id) => {
197
+ try {
198
+ return ctx.get('agents')?.get?.(id);
199
+ } catch {
200
+ return undefined;
201
+ }
202
+ },
203
+ commands: () => ctx.get('sessionController')?.commands,
204
+ });
205
+ ctx.provide(INBOX_SERVICE_KEY, service);
206
+ return service;
207
+ }