wherever-dev 0.21.0 → 0.22.0

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 (111) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/dist/assistant-channels.d.ts +242 -0
  3. package/dist/assistant-channels.d.ts.map +1 -0
  4. package/dist/assistant-channels.js +270 -0
  5. package/dist/assistant-channels.js.map +1 -0
  6. package/dist/assistant-controller.d.ts +228 -0
  7. package/dist/assistant-controller.d.ts.map +1 -0
  8. package/dist/assistant-controller.js +314 -0
  9. package/dist/assistant-controller.js.map +1 -0
  10. package/dist/assistant-cron.d.ts +87 -0
  11. package/dist/assistant-cron.d.ts.map +1 -0
  12. package/dist/assistant-cron.js +352 -0
  13. package/dist/assistant-cron.js.map +1 -0
  14. package/dist/assistant-folder.d.ts +161 -0
  15. package/dist/assistant-folder.d.ts.map +1 -0
  16. package/dist/assistant-folder.js +333 -0
  17. package/dist/assistant-folder.js.map +1 -0
  18. package/dist/assistant-schedule.d.ts +236 -0
  19. package/dist/assistant-schedule.d.ts.map +1 -0
  20. package/dist/assistant-schedule.js +454 -0
  21. package/dist/assistant-schedule.js.map +1 -0
  22. package/dist/assistant-scheduler.d.ts +210 -0
  23. package/dist/assistant-scheduler.d.ts.map +1 -0
  24. package/dist/assistant-scheduler.js +472 -0
  25. package/dist/assistant-scheduler.js.map +1 -0
  26. package/dist/assistant-tool-text.d.ts +40 -0
  27. package/dist/assistant-tool-text.d.ts.map +1 -0
  28. package/dist/assistant-tool-text.js +102 -0
  29. package/dist/assistant-tool-text.js.map +1 -0
  30. package/dist/assistant-tools.d.ts +207 -0
  31. package/dist/assistant-tools.d.ts.map +1 -0
  32. package/dist/assistant-tools.js +390 -0
  33. package/dist/assistant-tools.js.map +1 -0
  34. package/dist/attach-file-tool.d.ts +20 -1
  35. package/dist/attach-file-tool.d.ts.map +1 -1
  36. package/dist/attach-file-tool.js +45 -3
  37. package/dist/attach-file-tool.js.map +1 -1
  38. package/dist/cli-requests.d.ts +90 -0
  39. package/dist/cli-requests.d.ts.map +1 -0
  40. package/dist/cli-requests.js +75 -0
  41. package/dist/cli-requests.js.map +1 -0
  42. package/dist/download-grants.d.ts +12 -0
  43. package/dist/download-grants.d.ts.map +1 -0
  44. package/dist/download-grants.js +76 -0
  45. package/dist/download-grants.js.map +1 -0
  46. package/dist/index.js +431 -20
  47. package/dist/index.js.map +1 -1
  48. package/dist/protocol.d.ts +43 -0
  49. package/dist/protocol.d.ts.map +1 -1
  50. package/dist/reply-routing.d.ts +106 -0
  51. package/dist/reply-routing.d.ts.map +1 -0
  52. package/dist/reply-routing.js +174 -0
  53. package/dist/reply-routing.js.map +1 -0
  54. package/dist/session-pool.d.ts +243 -4
  55. package/dist/session-pool.d.ts.map +1 -1
  56. package/dist/session-pool.js +464 -100
  57. package/dist/session-pool.js.map +1 -1
  58. package/dist/telegram-channel.d.ts +272 -0
  59. package/dist/telegram-channel.d.ts.map +1 -0
  60. package/dist/telegram-channel.js +701 -0
  61. package/dist/telegram-channel.js.map +1 -0
  62. package/dist/telegram-files.d.ts +101 -0
  63. package/dist/telegram-files.d.ts.map +1 -0
  64. package/dist/telegram-files.js +145 -0
  65. package/dist/telegram-files.js.map +1 -0
  66. package/dist/telegram-pairing.d.ts +119 -0
  67. package/dist/telegram-pairing.d.ts.map +1 -0
  68. package/dist/telegram-pairing.js +97 -0
  69. package/dist/telegram-pairing.js.map +1 -0
  70. package/dist/telegram-replies.d.ts +94 -0
  71. package/dist/telegram-replies.d.ts.map +1 -0
  72. package/dist/telegram-replies.js +329 -0
  73. package/dist/telegram-replies.js.map +1 -0
  74. package/dist/telegram-token.d.ts +55 -0
  75. package/dist/telegram-token.d.ts.map +1 -0
  76. package/dist/telegram-token.js +86 -0
  77. package/dist/telegram-token.js.map +1 -0
  78. package/dist/web-push.d.ts +167 -0
  79. package/dist/web-push.d.ts.map +1 -0
  80. package/dist/web-push.js +387 -0
  81. package/dist/web-push.js.map +1 -0
  82. package/package.json +1 -1
  83. package/public/_app/immutable/assets/0.BkzT3rFr.css +1 -0
  84. package/public/_app/immutable/chunks/CExVgK9Z.js +2 -0
  85. package/public/_app/immutable/chunks/CExVgK9Z.js.map +1 -0
  86. package/public/_app/immutable/chunks/CkOw6fRa.js +2 -0
  87. package/public/_app/immutable/chunks/{idnZrCTB.js.map → CkOw6fRa.js.map} +1 -1
  88. package/public/_app/immutable/chunks/DyHllYtq.js +2 -0
  89. package/public/_app/immutable/chunks/{DJMI34rR.js.map → DyHllYtq.js.map} +1 -1
  90. package/public/_app/immutable/entry/{app.CF_gzWKW.js → app.D3PEFbtP.js} +3 -3
  91. package/public/_app/immutable/entry/{app.CF_gzWKW.js.map → app.D3PEFbtP.js.map} +1 -1
  92. package/public/_app/immutable/entry/start.BR00Qps5.js +2 -0
  93. package/public/_app/immutable/entry/start.BR00Qps5.js.map +1 -0
  94. package/public/_app/immutable/nodes/{0.CIIhZFWl.js → 0.DG3L8hMN.js} +3 -3
  95. package/public/_app/immutable/nodes/{0.CIIhZFWl.js.map → 0.DG3L8hMN.js.map} +1 -1
  96. package/public/_app/immutable/nodes/{1.D4WVeMej.js → 1.BCpuoZxW.js} +2 -2
  97. package/public/_app/immutable/nodes/{1.D4WVeMej.js.map → 1.BCpuoZxW.js.map} +1 -1
  98. package/public/_app/immutable/nodes/2.D2auiZW1.js +122 -0
  99. package/public/_app/immutable/nodes/2.D2auiZW1.js.map +1 -0
  100. package/public/_app/version.json +1 -1
  101. package/public/index.html +11 -11
  102. package/public/service-worker.js +1 -1
  103. package/public/_app/immutable/assets/0.BKJ49K71.css +0 -1
  104. package/public/_app/immutable/chunks/CkzyFwPn.js +0 -2
  105. package/public/_app/immutable/chunks/CkzyFwPn.js.map +0 -1
  106. package/public/_app/immutable/chunks/DJMI34rR.js +0 -2
  107. package/public/_app/immutable/chunks/idnZrCTB.js +0 -2
  108. package/public/_app/immutable/entry/start.GpPJ13Gr.js +0 -2
  109. package/public/_app/immutable/entry/start.GpPJ13Gr.js.map +0 -1
  110. package/public/_app/immutable/nodes/2._KcrsFWH.js +0 -120
  111. package/public/_app/immutable/nodes/2._KcrsFWH.js.map +0 -1
package/dist/index.js CHANGED
@@ -5,6 +5,17 @@ import { connect as netConnect } from 'node:net';
5
5
  import { WebSocketServer, WebSocket } from 'ws';
6
6
  import { SessionPool, RELOADING_REFUSAL, getWhereverConfig, getWhereverCertsDir, getWhereverStateDir, detectRemoteRepo, normalizePath, invalidateFolderExistence } from './session-pool.js';
7
7
  import { readDrafts, addDraft, deleteDraft, validateDraftInput } from './drafts.js';
8
+ import { startAssistantFolder } from './assistant-folder.js';
9
+ import { AssistantController } from './assistant-controller.js';
10
+ import { AssistantScheduler } from './assistant-scheduler.js';
11
+ import { assistantNotActiveError, setTimezone, WEB_TIMEZONE_SOURCE, } from './assistant-tools.js';
12
+ import { ChannelDispatcher } from './assistant-channels.js';
13
+ import { WebPushChannel, resolveVapidSubject, validateSubscription } from './web-push.js';
14
+ import { TelegramChannel } from './telegram-channel.js';
15
+ import { normalizeUserId } from './telegram-pairing.js';
16
+ import { resolveTelegramToken, takeTelegramTokenEnv } from './telegram-token.js';
17
+ import { DEFAULT_GRACE_MS } from './assistant-schedule.js';
18
+ import { createCliRequestRouter, assistantInfoChangedFrame } from './cli-requests.js';
8
19
  import { readStarredSet, setSessionStarred, validateStarInput, forgetStar } from './session-stars.js';
9
20
  import { piSdkInfo } from './pi-sdk.js';
10
21
  import { searchConversations } from './conversation-search.js';
@@ -12,6 +23,8 @@ import { matchRemoteRepoRule, resolveRemoteCandidates } from './remote-candidate
12
23
  import { RestoreJobRegistry } from './restore-jobs.js';
13
24
  import { INITIAL_HISTORY_LIMIT, HISTORY_PAGE_SIZE } from './protocol.js';
14
25
  import { gateUploadFolder, gateUploadWrite, uploadMaxBytes, uploadTooLarge } from './upload-gate.js';
26
+ import { readAttachGrants } from './download-grants.js';
27
+ import { DEFAULT_DOWNLOAD_MAX_BYTES } from './attach-file-tool.js';
15
28
  import { UploadStaging, UPLOAD_CAPABILITY, isValidUploadId, parseChunkFrame, CHUNK_FRAME_KIND } from './upload-staging.js';
16
29
  import fs from 'node:fs';
17
30
  import path from 'node:path';
@@ -193,13 +206,18 @@ function getUploadStaging() {
193
206
  return uploadStaging;
194
207
  }
195
208
  /**
196
- * Validate a requested download path against the allowed roots and return the
197
- * safe absolute path to stream, or null if it escapes / does not exist / is not
198
- * a regular file. This is the security-critical guard: it realpath-resolves the
199
- * target BEFORE the containment check so neither `..` traversal nor an in-tree
200
- * symlink can point outside an allowed root.
209
+ * Validate a requested download path against the allowed roots and the session's
210
+ * attach grants, and return the safe absolute path to stream, or null if it
211
+ * escapes / does not exist / is not a regular file. This is the security-critical
212
+ * guard: it realpath-resolves the target BEFORE the containment check so neither
213
+ * `..` traversal nor an in-tree symlink can point outside an allowed root.
214
+ *
215
+ * `grants` are the files the agent explicitly offered with `attach_file` (see
216
+ * download-grants.ts). They are matched EXACTLY on real path, never as roots, so
217
+ * attaching one file outside the roots does not open its directory. Loaded lazily:
218
+ * the transcript is only scanned when the root check has already failed.
201
219
  */
202
- function resolveSafeDownloadPath(requested, cwd, roots) {
220
+ async function resolveSafeDownloadPath(requested, cwd, roots, grants) {
203
221
  if (!requested)
204
222
  return null;
205
223
  let candidate = expandTilde(requested);
@@ -236,9 +254,22 @@ function resolveSafeDownloadPath(requested, cwd, roots) {
236
254
  return true;
237
255
  return real.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
238
256
  });
239
- if (!withinRoot)
240
- return null;
241
- return real;
257
+ if (withinRoot)
258
+ return real;
259
+ if (grants) {
260
+ for (const granted of await grants()) {
261
+ let grantedReal;
262
+ try {
263
+ grantedReal = fs.realpathSync(path.resolve(granted));
264
+ }
265
+ catch {
266
+ continue;
267
+ }
268
+ if (grantedReal === real)
269
+ return real;
270
+ }
271
+ }
272
+ return null;
242
273
  }
243
274
  function serveStaticFile(reqPath, res) {
244
275
  let filePath = path.join(staticDir, reqPath === '/' ? 'index.html' : reqPath);
@@ -770,7 +801,12 @@ function parseArgs() {
770
801
  // `token` above; nothing reads these variables again.
771
802
  delete process.env.WHEREVER_TOKEN;
772
803
  delete process.env.PI_REMOTE_TOKEN;
773
- return { port, host, socket, token, tokenSource, idleTimeout, sslKey, sslCert, noSsl, httpLocalhostFallbackPort, debug };
804
+ // The assistant's Telegram bot token variables, for the same reason (ADR 0007,
805
+ // ADR 0018): captured and scrubbed here ALWAYS, before anything is spawned.
806
+ // The token FILE is only read later, and only while the assistant is active
807
+ // and Telegram is enabled (telegram-token.ts).
808
+ const telegramTokenEnv = takeTelegramTokenEnv();
809
+ return { port, host, socket, token, tokenSource, idleTimeout, sslKey, sslCert, noSsl, httpLocalhostFallbackPort, debug, telegramTokenEnv };
774
810
  }
775
811
  /** Loopback-only binds are the safe default; everything else is reachable by others. */
776
812
  function isLoopbackHost(host) {
@@ -879,13 +915,69 @@ function sendThenTerminate(ws, msg, flushTimeoutMs = 1_000) {
879
915
  kill();
880
916
  }
881
917
  }
918
+ /**
919
+ * The scheduler's grace window from `assistantScheduleGraceMinutes`: a finite
920
+ * number >= 0, else the default (1 h) with a warning.
921
+ */
922
+ function scheduleGraceMs(minutes) {
923
+ if (minutes === undefined)
924
+ return DEFAULT_GRACE_MS;
925
+ if (typeof minutes === 'number' && Number.isFinite(minutes) && minutes >= 0)
926
+ return minutes * 60_000;
927
+ console.warn(`[wherever] ignoring assistantScheduleGraceMinutes=${JSON.stringify(minutes)} (not a number >= 0); using 60`);
928
+ return DEFAULT_GRACE_MS;
929
+ }
882
930
  async function main() {
883
- const { port, host, socket, token, tokenSource, idleTimeout, sslKey, sslCert, noSsl, httpLocalhostFallbackPort, debug } = parseArgs();
931
+ const { port, host, socket, token, tokenSource, idleTimeout, sslKey, sslCert, noSsl, httpLocalhostFallbackPort, debug, telegramTokenEnv } = parseArgs();
884
932
  debugEnabled = debug;
885
933
  console.log(`[wherever] pi SDK ${piSdkInfo.version}: ` +
886
934
  (piSdkInfo.tier === 'bundled' ? `bundled (${piSdkInfo.why})` : `${piSdkInfo.tier}, from ${piSdkInfo.root} (${piSdkInfo.why})`));
887
935
  const sessionPool = new SessionPool(idleTimeout, { getStarred: readStarredSet });
888
936
  await sessionPool.initialize();
937
+ // The assistant folder (opt-in via `assistantFolder`, see assistant-folder.ts):
938
+ // resolved, created, locked and seeded ONCE here, so a config change takes
939
+ // effect on restart only. The status is a start-time snapshot served by
940
+ // /config. The lock is released on shutdown and, as a backstop, on any exit.
941
+ const assistant = startAssistantFolder(getWhereverConfig());
942
+ sessionPool.setAssistantFolder(assistant.status.active ? (assistant.status.folder ?? undefined) : undefined);
943
+ // The assistant tools (assistant-tools.ts) in every server session, and the
944
+ // timezone line in the assistant folder: registered while `assistantFolder`
945
+ // is CONFIGURED. The backend is the scheduler, set below once it has started;
946
+ // until then, and for a server refused by the folder lock, every tool answers
947
+ // the lock-state error. Unset = no hooks, so sessions are exactly as before.
948
+ let assistantBackend = null;
949
+ // `assistant_notify`'s backend (the channel dispatcher + the scheduler's job
950
+ // mapping), set below once the channels have started. The tool itself is
951
+ // registered ONLY while the assistant is active (a refused server's sessions
952
+ // do not see it), see AssistantSessionHooks.notify.
953
+ let notifyBackend = null;
954
+ // The same hooks also answer the CLI bridge's tool-twin ops (cli-requests.ts).
955
+ let assistantHooks;
956
+ if (assistant.status.configured && assistant.status.folder) {
957
+ assistantHooks = {
958
+ folder: assistant.status.folder,
959
+ access: () => assistantBackend
960
+ ? { ok: true, backend: assistantBackend }
961
+ : { ok: false, error: assistantNotActiveError(assistant.status.lock) },
962
+ ...(assistant.status.active
963
+ ? {
964
+ notify: () => notifyBackend
965
+ ? { ok: true, backend: notifyBackend }
966
+ : { ok: false, error: 'the assistant channels are still starting; try again in a moment' },
967
+ }
968
+ : {}),
969
+ };
970
+ sessionPool.setAssistantSessionHooks(assistantHooks);
971
+ }
972
+ const currentTimezone = () => {
973
+ try {
974
+ return assistantBackend ? assistantBackend.getUserTimezone() : null;
975
+ }
976
+ catch {
977
+ return null;
978
+ }
979
+ };
980
+ process.on('exit', () => assistant.release());
889
981
  // Abandoned partial uploads (untouched for 24 h) are collected at startup and
890
982
  // then hourly. A no-op when the staging dir was never created. The startup
891
983
  // pass is awaited (one readdir) so it is done before the first upload arrives.
@@ -900,6 +992,190 @@ async function main() {
900
992
  const uploadGcTimer = setInterval(runUploadGc, 60 * 60 * 1000);
901
993
  uploadGcTimer.unref?.();
902
994
  const clients = new Map();
995
+ /** The assistant's channel dispatcher, set once the channels start (below; only while active). */
996
+ let channelDispatcher = null;
997
+ // The assistant controller (assistant-controller.ts): which session is the
998
+ // current assistant session, and its reset. Built, and the pool's
999
+ // session-created callback registered, ONLY while the assistant is active, so
1000
+ // with `assistantFolder` unset (or refused) session creation, `session_new`
1001
+ // and idle teardown are exactly as before.
1002
+ const assistantController = assistant.status.active && assistant.status.folder
1003
+ ? new AssistantController({
1004
+ pool: sessionPool,
1005
+ folder: assistant.status.folder,
1006
+ stateDir: getWhereverStateDir(),
1007
+ onChange: (pointer) => {
1008
+ const update = { type: 'assistant_status', ...pointer, timezone: currentTimezone() };
1009
+ for (const c of clients.values()) {
1010
+ if (!c.isCliBridge)
1011
+ sendWS(c.ws, update);
1012
+ }
1013
+ },
1014
+ // Messages a reset or an aborted settle dropped: reported to the
1015
+ // channels they came from (the dispatcher exists by then; before it
1016
+ // does, nothing has been sent from a channel, so nothing is lost).
1017
+ onDropped: (dropped) => channelDispatcher?.reportDropped(dropped),
1018
+ })
1019
+ : null;
1020
+ if (assistantController) {
1021
+ sessionPool.onSessionCreated = (sessionFile, cwd) => assistantController.handleSessionCreated(sessionFile, cwd);
1022
+ }
1023
+ // The assistant scheduler (assistant-scheduler.ts, ADR 0015): fires the jobs in
1024
+ // `<assistantFolder>/schedule.json`. Built and started ONLY while the
1025
+ // assistant is active (configured AND this server holds the folder lock), so
1026
+ // with `assistantFolder` unset or refused there is no timer and nothing is
1027
+ // written to the state dir.
1028
+ const assistantScheduler = assistantController && assistant.status.folder
1029
+ ? new AssistantScheduler({
1030
+ folder: assistant.status.folder,
1031
+ stateDir: getWhereverStateDir(),
1032
+ pool: sessionPool,
1033
+ controller: assistantController,
1034
+ graceMs: scheduleGraceMs(getWhereverConfig().assistantScheduleGraceMinutes),
1035
+ // Every change of the user's timezone (the web's report, or
1036
+ // `assistant_set_timezone`) goes through the scheduler's setter, which
1037
+ // calls this: CLI bridges get `assistant_info_changed`, dashboards an
1038
+ // `assistant_status` carrying the new zone.
1039
+ onTimezoneChange: () => {
1040
+ pushAssistantInfoChanged();
1041
+ broadcastAssistantStatus();
1042
+ },
1043
+ })
1044
+ : null;
1045
+ await assistantScheduler?.start();
1046
+ assistantBackend = assistantScheduler;
1047
+ // The assistant's CHANNELS (assistant-channels.ts): built and started ONLY
1048
+ // while the assistant is active, like the scheduler. Web Push (web-push.ts,
1049
+ // ADR 0017) is on unless `assistantWebPush.enabled` is false; it writes
1050
+ // nothing until a device subscribes (the VAPID keys are made on first use).
1051
+ const webPushChannel = assistantController && getWhereverConfig().assistantWebPush?.enabled !== false
1052
+ ? new WebPushChannel({
1053
+ stateDir: getWhereverStateDir(),
1054
+ subject: resolveVapidSubject({
1055
+ subject: getWhereverConfig().assistantWebPush?.subject,
1056
+ publicUrl: getWhereverConfig().publicUrl,
1057
+ }),
1058
+ })
1059
+ : null;
1060
+ // Telegram (telegram-channel.ts): only while the assistant is active (two
1061
+ // servers must never poll one bot; the folder lock decides) AND
1062
+ // `assistantTelegram.enabled` is true. Otherwise the token file is not even
1063
+ // read and nothing is logged. A token that cannot be resolved DISABLES
1064
+ // Telegram with a loud error and the server carries on (ADR 0018).
1065
+ const telegramConfig = getWhereverConfig().assistantTelegram;
1066
+ const telegramEnabled = !!assistantController && telegramConfig?.enabled === true;
1067
+ let telegramChannel = null;
1068
+ let telegramDisabledError = null;
1069
+ if (telegramEnabled) {
1070
+ const resolved = resolveTelegramToken({
1071
+ env: telegramTokenEnv,
1072
+ configToken: telegramConfig?.token,
1073
+ readFile: (p) => fs.readFileSync(p, 'utf8'),
1074
+ });
1075
+ for (const w of resolved.warnings)
1076
+ console.warn(`[wherever] telegram: ${w}`);
1077
+ const configuredUserId = normalizeUserId(telegramConfig?.userId);
1078
+ if (telegramConfig?.userId !== undefined && !configuredUserId) {
1079
+ console.warn(`[wherever] telegram: ignoring assistantTelegram.userId=${JSON.stringify(telegramConfig.userId)} (not a numeric Telegram user id); pairing by code instead`);
1080
+ }
1081
+ if (!resolved.ok) {
1082
+ telegramDisabledError = resolved.error;
1083
+ console.error(`[wherever] ERROR: Telegram is DISABLED: ${resolved.error}. The server keeps running without it.`);
1084
+ }
1085
+ else {
1086
+ console.log(`[wherever] telegram: bot token from ${resolved.source}`);
1087
+ telegramChannel = new TelegramChannel({
1088
+ token: resolved.token,
1089
+ stateDir: getWhereverStateDir(),
1090
+ configuredUserId,
1091
+ apiBaseUrl: typeof telegramConfig?.apiBaseUrl === 'string' && telegramConfig.apiBaseUrl.trim() ? telegramConfig.apiBaseUrl.trim() : undefined,
1092
+ // A notification links to the target session when the public URL is set.
1093
+ publicUrl: getWhereverConfig().publicUrl,
1094
+ // A file from Telegram lands where a web upload into the assistant
1095
+ // session does (`uploads.type`), under the same size limit.
1096
+ uploadDir: () => resolveUploadDir(getWhereverConfig(), assistant.status.folder ?? undefined),
1097
+ maxUploadBytes: () => uploadMaxBytes(getWhereverConfig()),
1098
+ });
1099
+ }
1100
+ }
1101
+ const assistantChannels = [
1102
+ ...(webPushChannel ? [webPushChannel] : []),
1103
+ ...(telegramChannel ? [telegramChannel] : []),
1104
+ ];
1105
+ channelDispatcher = assistantController
1106
+ ? new ChannelDispatcher({ controller: assistantController, pool: sessionPool, channels: assistantChannels })
1107
+ : null;
1108
+ await channelDispatcher?.start();
1109
+ if (channelDispatcher && assistantScheduler) {
1110
+ const scheduler = assistantScheduler;
1111
+ const dispatcher = channelDispatcher;
1112
+ notifyBackend = {
1113
+ notify: (n) => dispatcher.notify(n),
1114
+ jobOrigin: (jobId) => {
1115
+ const job = scheduler.store.read().valid.find((v) => v.job.id === jobId)?.job;
1116
+ return job ? { originSessionId: job.originSessionId, originCwd: job.originCwd } : null;
1117
+ },
1118
+ jobForSession: (sessionFile) => scheduler.jobForSession(sessionFile),
1119
+ };
1120
+ }
1121
+ /** The Web Push part of the assistant status (only while active). */
1122
+ const webPushStatus = () => ({
1123
+ enabled: !!webPushChannel,
1124
+ publicKey: webPushChannel?.existingPublicKey() ?? null,
1125
+ subscriptions: webPushChannel?.subscriptions().length ?? 0,
1126
+ });
1127
+ /**
1128
+ * The Telegram part of the assistant status (only while active): `enabled`
1129
+ * (`assistantTelegram.enabled`), and the channel's state: `disabled` (not
1130
+ * enabled, or no usable token: `error`), `starting`, `unpaired` (+ the
1131
+ * one-time `code`), `paired` (+ `user`) or `error` (the token was rejected).
1132
+ */
1133
+ const telegramStatus = () => telegramChannel
1134
+ ? { enabled: true, ...telegramChannel.status() }
1135
+ : telegramEnabled
1136
+ ? { enabled: true, state: 'disabled', error: telegramDisabledError ?? 'Telegram could not start' }
1137
+ : { enabled: false, state: 'disabled' };
1138
+ /** Re-send the live assistant status (pointer + timezone) to every dashboard. */
1139
+ const broadcastAssistantStatus = () => {
1140
+ if (!assistantController)
1141
+ return;
1142
+ const update = { type: 'assistant_status', ...assistantController.status(), timezone: currentTimezone() };
1143
+ for (const c of clients.values()) {
1144
+ if (!c.isCliBridge)
1145
+ sendWS(c.ws, update);
1146
+ }
1147
+ };
1148
+ /**
1149
+ * A web client's timezone report (`client_timezone`, sent on connect): made the
1150
+ * user's current timezone when it differs, only while the assistant is active.
1151
+ * Otherwise ignored, so nothing is written. An unknown zone is logged and ignored.
1152
+ */
1153
+ const onClientTimezone = (timezone) => {
1154
+ if (!assistantBackend || typeof timezone !== 'string' || !timezone.trim())
1155
+ return;
1156
+ const r = setTimezone(assistantBackend, { timezone }, WEB_TIMEZONE_SOURCE);
1157
+ if (!r.ok)
1158
+ console.warn(`[wherever] assistant: ignoring the web's timezone report: ${r.error}`);
1159
+ };
1160
+ // The CLI bridge's request/response path (ADR 0016, cli-requests.ts). Built
1161
+ // whether or not the assistant is active: `assistant_info` is how a terminal pi
1162
+ // learns it is NOT, and that answer is what keeps its tool twins inactive.
1163
+ const currentAssistantInfo = () => ({
1164
+ assistantFolder: assistantController ? assistant.status.folder : null,
1165
+ timezone: assistantController ? currentTimezone() : null,
1166
+ });
1167
+ const cliRequests = createCliRequestRouter({ assistantInfo: currentAssistantInfo, assistantHooks: () => assistantHooks });
1168
+ // Push the current assistant info to every connected CLI bridge, which updates
1169
+ // its cached `assistant_info`. The folder takes effect on restart only, so the
1170
+ // one runtime change is the user's timezone: the scheduler's
1171
+ // `onTimezoneChange` calls this.
1172
+ const pushAssistantInfoChanged = () => {
1173
+ const frame = assistantInfoChangedFrame(currentAssistantInfo());
1174
+ for (const c of clients.values()) {
1175
+ if (c.isCliBridge)
1176
+ sendWS(c.ws, frame);
1177
+ }
1178
+ };
903
1179
  // expandTilde so `~/certs/...` works from a systemd `Environment=` line or an
904
1180
  // EnvironmentFile, neither of which is shell-expanded. Without it the read
905
1181
  // below fails and (before the explicit-TLS check further down) the server
@@ -1243,7 +1519,7 @@ async function main() {
1243
1519
  sessionPool.onEvent = broadcastAgentEvent;
1244
1520
  const requestHandler = async (req, res) => {
1245
1521
  res.setHeader('Access-Control-Allow-Origin', '*');
1246
- res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
1522
+ res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
1247
1523
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
1248
1524
  if (req.method === 'OPTIONS') {
1249
1525
  res.writeHead(200);
@@ -1265,7 +1541,12 @@ async function main() {
1265
1541
  pathname.startsWith('/check-remote-repo') ||
1266
1542
  pathname.startsWith('/remote-candidates') ||
1267
1543
  pathname.startsWith('/autocomplete-path') ||
1268
- pathname.startsWith('/session/');
1544
+ pathname.startsWith('/session/') ||
1545
+ // Only while Web Push runs (assistant active): otherwise
1546
+ // /push/* is an unknown route, exactly as before.
1547
+ (!!webPushChannel && pathname.startsWith('/push/')) ||
1548
+ // Likewise only while the Telegram channel runs.
1549
+ (!!telegramChannel && pathname.startsWith('/telegram/'));
1269
1550
  if (isApiRequest && !authenticate(req, token)) {
1270
1551
  sendJSON(res, 401, { error: 'Unauthorized' });
1271
1552
  return;
@@ -1407,6 +1688,68 @@ async function main() {
1407
1688
  }
1408
1689
  return;
1409
1690
  }
1691
+ // --- Web Push subscriptions (web-push.ts, ADR 0017) ----------------------
1692
+ // Token-gated via isApiRequest, and only while Web Push runs (assistant
1693
+ // active): otherwise these fall through to the static handler like any
1694
+ // unknown route. `GET .../vapid-public-key` generates the keypair on first use.
1695
+ if (webPushChannel && pathname.startsWith('/push/')) {
1696
+ try {
1697
+ if (pathname === '/push/vapid-public-key' && req.method === 'GET') {
1698
+ sendJSON(res, 200, { publicKey: webPushChannel.publicKey() });
1699
+ return;
1700
+ }
1701
+ if (pathname === '/push/subscription' && req.method === 'GET') {
1702
+ const endpoint = url.searchParams.get('endpoint') || '';
1703
+ sendJSON(res, 200, { subscribed: !!endpoint && webPushChannel.isSubscribed(endpoint) });
1704
+ return;
1705
+ }
1706
+ if (pathname === '/push/subscription' && (req.method === 'POST' || req.method === 'DELETE')) {
1707
+ let parsed;
1708
+ try {
1709
+ parsed = JSON.parse((await readBody(req)) || '{}');
1710
+ }
1711
+ catch {
1712
+ sendJSON(res, 400, { error: 'Invalid request' });
1713
+ return;
1714
+ }
1715
+ if (req.method === 'POST') {
1716
+ const v = validateSubscription(parsed?.subscription ?? parsed);
1717
+ if (!v.ok) {
1718
+ sendJSON(res, 400, { error: v.error });
1719
+ return;
1720
+ }
1721
+ const subscriptions = await webPushChannel.subscribe(v.subscription);
1722
+ sendJSON(res, 200, { subscribed: true, subscriptions });
1723
+ return;
1724
+ }
1725
+ const endpoint = typeof parsed?.endpoint === 'string' ? parsed.endpoint : '';
1726
+ if (!endpoint) {
1727
+ sendJSON(res, 400, { error: 'Missing "endpoint"' });
1728
+ return;
1729
+ }
1730
+ const removed = await webPushChannel.unsubscribe(endpoint);
1731
+ sendJSON(res, 200, { subscribed: false, removed });
1732
+ return;
1733
+ }
1734
+ }
1735
+ catch (err) {
1736
+ sendJSON(res, 500, { error: err.message || 'Web Push failed' });
1737
+ return;
1738
+ }
1739
+ }
1740
+ // --- Telegram re-pair (telegram-channel.ts) -------------------------------
1741
+ // Token-gated via isApiRequest, and only while the Telegram channel runs:
1742
+ // otherwise an unknown route. Forgets the stored pairing and issues a new
1743
+ // one-time code; refused (409) while the user id comes from the config.
1744
+ if (telegramChannel && pathname === '/telegram/repair' && req.method === 'POST') {
1745
+ const r = telegramChannel.repair();
1746
+ if (!r.ok) {
1747
+ sendJSON(res, 409, { error: r.error, telegram: telegramStatus() });
1748
+ return;
1749
+ }
1750
+ sendJSON(res, 200, { ok: true, telegram: telegramStatus() });
1751
+ return;
1752
+ }
1410
1753
  if (pathname === '/config' && req.method === 'GET') {
1411
1754
  const config = getWhereverConfig();
1412
1755
  let searchFolder = config.searchFolder;
@@ -1437,6 +1780,19 @@ async function main() {
1437
1780
  searchFolder: searchFolder || null,
1438
1781
  searchCreateRemote: !!config.searchCreateRemote,
1439
1782
  searchDefaultModel,
1783
+ // Start-time snapshot (see startAssistantFolder): configured / folder /
1784
+ // active / lock. Later assistant tasks add fields to this object.
1785
+ // Plus, while active, the controller's pointer (currentSessionId /
1786
+ // currentSessionFile), which is live, not a start-time snapshot.
1787
+ // While active, also the user's current timezone (live).
1788
+ // While active, also the Web Push state (enabled, the VAPID public key
1789
+ // once generated, how many devices are subscribed; whether THIS device
1790
+ // is, the web asks `GET /push/subscription`).
1791
+ // While active, also the Telegram state (telegramStatus above; the
1792
+ // one-time pairing code is in it while unpaired, behind the token gate).
1793
+ assistant: assistantController
1794
+ ? { ...assistant.status, ...assistantController.status(), timezone: currentTimezone(), webPush: webPushStatus(), telegram: telegramStatus() }
1795
+ : assistant.status,
1440
1796
  appearance: {
1441
1797
  label,
1442
1798
  accent,
@@ -1978,10 +2334,12 @@ async function main() {
1978
2334
  sendJSON(res, 400, { error: 'Missing sessionId or path' });
1979
2335
  return;
1980
2336
  }
1981
- const tracked = sessionPool.getSession(qSessionId);
1982
- const cwd = tracked?.cwd;
2337
+ // Live OR on-disk: a session the server has not loaded still has a cwd
2338
+ // (its roots) and a transcript (its attach grants).
2339
+ const located = await sessionPool.locateSession(qSessionId);
2340
+ const cwd = located?.cwd;
1983
2341
  const roots = resolveDownloadRoots(config, cwd);
1984
- const safePath = resolveSafeDownloadPath(qPath, cwd, roots);
2342
+ const safePath = await resolveSafeDownloadPath(qPath, cwd, roots, located ? () => readAttachGrants(located.sessionFile) : undefined);
1985
2343
  if (!safePath) {
1986
2344
  // 404 (not 403) so we do not leak whether a path outside the allowed
1987
2345
  // roots exists: escape and not-found are indistinguishable to the client.
@@ -1996,7 +2354,7 @@ async function main() {
1996
2354
  sendJSON(res, 404, { error: 'File not found' });
1997
2355
  return;
1998
2356
  }
1999
- const maxBytes = config.downloads?.maxBytes ?? 100 * 1024 * 1024;
2357
+ const maxBytes = config.downloads?.maxBytes ?? DEFAULT_DOWNLOAD_MAX_BYTES;
2000
2358
  if (stat.size > maxBytes) {
2001
2359
  sendJSON(res, 413, { error: `File too large (${stat.size} > ${maxBytes} bytes)` });
2002
2360
  return;
@@ -2296,7 +2654,7 @@ async function main() {
2296
2654
  return;
2297
2655
  }
2298
2656
  try {
2299
- await handleWSMessage(msg, client, sessionPool, clients, broadcastToSession, broadcastSessionsUpdated);
2657
+ await handleWSMessage(msg, client, sessionPool, clients, broadcastToSession, broadcastSessionsUpdated, assistantController, cliRequests, onClientTimezone);
2300
2658
  }
2301
2659
  catch (err) {
2302
2660
  console.error('WS message processing error:', err);
@@ -2460,7 +2818,10 @@ This encrypts all network traffic securely and enables safe, private remote acce
2460
2818
  for (const c of clients.values()) {
2461
2819
  c.ws.close();
2462
2820
  }
2821
+ assistantScheduler?.stop();
2822
+ await channelDispatcher?.stop();
2463
2823
  await sessionPool.disposeAll();
2824
+ assistant.release();
2464
2825
  server.close();
2465
2826
  process.exit(0);
2466
2827
  };
@@ -2795,12 +3156,41 @@ function sendQueueSnapshot(client, sessionFile, sessionId, pool) {
2795
3156
  return;
2796
3157
  sendWS(client.ws, { type: 'queue_update', sessionId, steering });
2797
3158
  }
2798
- async function handleWSMessage(msg, client, pool, clients, broadcast, onSessionsUpdated) {
3159
+ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessionsUpdated, assistantController = null, cliRequests = null, onClientTimezone = () => { }) {
2799
3160
  switch (msg.type) {
3161
+ case 'client_timezone':
3162
+ // The web's timezone report on connect (see onClientTimezone in main).
3163
+ onClientTimezone(msg.timezone);
3164
+ break;
3165
+ case 'assistant_open':
3166
+ case 'assistant_reset': {
3167
+ // The Assistant entry point and its Reset action. The asker gets the
3168
+ // session to open and loads it through the normal session_load, so every
3169
+ // load-time decision (read-only, folder conflict, cold build) applies.
3170
+ if (!assistantController) {
3171
+ sendWS(client.ws, { type: 'session_error', error: 'The assistant is not active on this server (set assistantFolder in the config).' });
3172
+ return;
3173
+ }
3174
+ try {
3175
+ const cur = msg.type === 'assistant_reset' ? await assistantController.reset() : await assistantController.ensureCurrent();
3176
+ sendWS(client.ws, { type: 'assistant_current', sessionFile: cur.sessionFile, sessionId: cur.sessionId, cwd: cur.cwd });
3177
+ onSessionsUpdated();
3178
+ }
3179
+ catch (err) {
3180
+ sendWS(client.ws, { type: 'session_error', error: `Assistant: ${err.message}` });
3181
+ }
3182
+ return;
3183
+ }
2800
3184
  case 'cli_register': {
2801
3185
  client.isCliBridge = true;
2802
3186
  client.sessionId = msg.sessionFile;
2803
- const result = await pool.registerCliSession(msg.sessionFile, msg.cwd, msg.model || '', client.ws, msg.isStreaming === true);
3187
+ // `isNew` fires the pool's session-created callback (a fresh terminal pi in
3188
+ // assistantFolder moves the assistant pointer); `capabilities` is stored on
3189
+ // the entry. Older extensions send neither (ADR 0016).
3190
+ const result = await pool.registerCliSession(msg.sessionFile, msg.cwd, msg.model || '', client.ws, msg.isStreaming === true, {
3191
+ isNew: msg.isNew === true,
3192
+ capabilities: Array.isArray(msg.capabilities) ? msg.capabilities : [],
3193
+ });
2804
3194
  if (result.error) {
2805
3195
  sendWS(client.ws, { type: 'session_error', error: result.error });
2806
3196
  }
@@ -2877,6 +3267,27 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
2877
3267
  pool.handleCliEvent(client.sessionId, msg.event);
2878
3268
  break;
2879
3269
  }
3270
+ case 'cli_request': {
3271
+ // ADR 0016. The caller is the session THIS connection registered, never a
3272
+ // field of the request, so whatever an op stamps as origin is server-side.
3273
+ // Answered to the asker only. A request with no id cannot be answered.
3274
+ if (!cliRequests)
3275
+ return;
3276
+ // The tool-twin ops also need the session's id and cwd (the origin they
3277
+ // stamp), read from the pool's entry for it.
3278
+ const tracked = client.isCliBridge && client.sessionId ? pool.getSession(client.sessionId) : null;
3279
+ const caller = client.isCliBridge && client.sessionId
3280
+ ? {
3281
+ sessionFile: tracked?.sessionFile ?? client.sessionId,
3282
+ sessionId: tracked?.sessionId ?? null,
3283
+ ...(tracked ? { cwd: tracked.cwd } : {}),
3284
+ }
3285
+ : null;
3286
+ const response = await cliRequests.handle(msg, caller);
3287
+ if (response)
3288
+ sendWS(client.ws, response);
3289
+ break;
3290
+ }
2880
3291
  case 'connect':
2881
3292
  break;
2882
3293
  case 'ping':