@dotrino/terminal-agent 0.42.0 → 0.43.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.
package/README.md CHANGED
@@ -122,6 +122,19 @@ Sin `--id`, es la consola en la que corre la orden: el agente pone su id en
122
122
  Para que un agente de IA la mantenga al día, el paquete trae un skill de Claude Code en
123
123
  `skills/dotrino-terminal-note/`: se copia a `~/.claude/skills/`.
124
124
 
125
+ ## Imágenes desde otro aparato
126
+
127
+ Desde el teléfono o el navegador se puede adjuntar una imagen a la consola: viaja por la sesión
128
+ (cifrada, en trozos con acuse), el agente la guarda en `uploads/` dentro de la carpeta del perfil
129
+ y contesta la ruta, que es lo que el aparato escribe en la consola. Así se le enseña una foto o
130
+ una captura a lo que corre dentro.
131
+
132
+ - Solo PNG, JPEG, GIF y WebP, y qué es lo dicen los primeros bytes del archivo, no quien lo manda.
133
+ - El nombre lo pone el agente (`img-<fecha>-<hora>-<azar>.<ext>`); la carpeta es solo del usuario.
134
+ - Tope de 12 MB por imagen (el aparato la reduce antes de mandarla). Se borran solas a los 7 días.
135
+
136
+ Protocolo: `{ type:'file', up, seq, data, last? }` → `{ type:'filed', up, seq, path? }` (`uploads.js`).
137
+
125
138
  ## Clave de la máquina (opcional)
126
139
 
127
140
  Por defecto, cualquier aparato de tu cuenta con permiso abre consolas en esta máquina. Si
package/consoles.js CHANGED
@@ -102,6 +102,9 @@ class Console {
102
102
  // hizo; solo a ella se le sigue la pantalla (redimensionar la ventana, girar el teléfono).
103
103
  // Volver a conectarse o que otra pantalla se vaya no cambia el tamaño.
104
104
  this.holder = null
105
+ // Quién lo tenía cuando se fue (su aparato o su ventana): si ESA pantalla vuelve por una
106
+ // conexión nueva sin que otra lo haya tomado, sigue siendo la suya (`resume`).
107
+ this.lastHolder = null
105
108
  this.exited = false
106
109
  this.screen = new Terminal({ cols, rows, scrollback: SCROLLBACK, allowProposedApi: true })
107
110
  this.serializer = new SerializeAddon()
@@ -262,14 +265,34 @@ class Console {
262
265
  this.viewers.delete(viewer)
263
266
  // Irse no cambia el tamaño ni se lo pasa a otra pantalla: se queda como está hasta que
264
267
  // alguien abra la consola, se cambie a ella, pulse ⤢ o teclee.
265
- if (this.holder === viewer) this.holder = null
268
+ if (this.holder === viewer) { this.holder = null; this.lastHolder = screenOf(viewer) }
266
269
  this._meta()
267
270
  }
268
271
 
272
+ /**
273
+ * `viewer` VUELVE por una conexión nueva (`attach` con `keep`). No toma el tamaño; pero si el
274
+ * tamaño era de ESA MISMA pantalla, lo sigue teniendo y se le sigue. Sin esto, tras un corte
275
+ * de red el teléfono que lo puso dejaba de contar: abría el teclado y la consola se quedaba
276
+ * con las filas de antes, las últimas por detrás del teclado, hasta que tecleaba.
277
+ * Vale tanto si su conexión vieja ya se soltó (`lastHolder`) como si sigue enganchada sin
278
+ * saberse muerta (`holder` es otra sesión de la misma pantalla).
279
+ */
280
+ resume (viewer) {
281
+ if (!this.viewers.has(viewer)) return
282
+ const mine = screenOf(viewer)
283
+ if (!mine) return
284
+ const had = this.holder ? screenOf(this.holder) : this.lastHolder
285
+ if (this.holder === viewer || had !== mine) return
286
+ this.holder = viewer
287
+ if (viewer.size && (viewer.size.cols !== this.cols || viewer.size.rows !== this.rows)) this.resize(viewer.size.cols, viewer.size.rows)
288
+ else this._meta()
289
+ }
290
+
269
291
  /** `viewer` toma el tamaño AHORA: abrió la consola, se cambió a ella, pulsó ⤢ o tecleó. */
270
292
  take (viewer) {
271
293
  if (!this.viewers.has(viewer)) return
272
294
  this.holder = viewer
295
+ this.lastHolder = null
273
296
  if (viewer.size) this.resize(viewer.size.cols, viewer.size.rows)
274
297
  else this._meta()
275
298
  }
@@ -312,6 +335,12 @@ export function isTyped (data) { return String(data).replace(REPORTS, '') !== ''
312
335
 
313
336
 
314
337
  /** Las consolas de este agente. */
338
+ /** Qué PANTALLA es un mirón, más allá de su conexión: el aparato, o la ventana con su etiqueta. Null si no se sabe. */
339
+ function screenOf (v) {
340
+ if (v.origin === 'remote') return v.device ? `remote:${v.device}` : null
341
+ return v.tag ? `local:${v.tag}` : null
342
+ }
343
+
315
344
  export class ConsoleHub {
316
345
  /**
317
346
  * @param {{ spawn:(opts:{cols:number,rows:number,cwd:string|null,id:string})=>any }} opts
package/index.js CHANGED
@@ -18,11 +18,15 @@
18
18
  * { type:'note', id?, text?, task? } (de qué va una consola: `text` es la nota de
19
19
  * la persona y `task` la tarea que pone el programa; sin `id`, la enganchada;
20
20
  * sin ninguno de los dos, solo lee; contesta con `noted`) ·
21
- * { type:'unlock', code } (la clave de la máquina, si tiene: access.js)
21
+ * { type:'unlock', code } (la clave de la máquina, si tiene: access.js) ·
22
+ * { type:'file', up, seq, data, last? } (una imagen, en trozos base64 y en
23
+ * orden; cada trozo se acusa con `filed`, y el último trae la `path` donde
24
+ * quedó en esta máquina: uploads.js)
22
25
  * agente → cliente: { type:'consoles', list } · { type:'attached', id, fresh } ·
23
26
  * { type:'replay', id, data, last } · { type:'out', data } ·
24
27
  * { type:'exit', code, closedBy? } · { type:'fail', code, message, retryMs? } ·
25
- * { type:'unlocked' } · { type:'noted', console }
28
+ * { type:'unlocked' } · { type:'noted', console } ·
29
+ * { type:'filed', up, seq, path? }
26
30
  *
27
31
  * Con clave puesta, una sesión remota que no la ha escrito recibe `fail` con `code:'locked'`
28
32
  * a todo lo que pida; tras `unlock` vale para esa conexión. `bad-code` y `wait` traen
@@ -38,6 +42,7 @@ import { ConsoleHub, REPLAY_CHUNK, isTyped } from './consoles.js'
38
42
  import { listenLocal } from './local.js'
39
43
  import { makeGate } from './access.js'
40
44
  import { makeFar } from './far.js'
45
+ import { makeUploads } from './uploads.js'
41
46
 
42
47
  const require = createRequire(import.meta.url)
43
48
 
@@ -96,11 +101,14 @@ export function makeHub (pty, opts = {}) {
96
101
  *
97
102
  * @param {object} session
98
103
  * @param {ConsoleHub} hub
99
- * @param {{ origin?: 'local'|'remote', gate?: ReturnType<typeof makeGate> }} [opts] `gate`: la
100
- * clave de la máquina (access.js). Solo se le pide a las sesiones remotas.
104
+ * @param {{ origin?: 'local'|'remote', gate?: ReturnType<typeof makeGate>, uploadsDir?: string }} [opts]
105
+ * `gate`: la clave de la máquina (access.js). Solo se le pide a las sesiones remotas.
106
+ * `uploadsDir`: dónde se guardan las imágenes que manda esta sesión (uploads.js). Sin ella,
107
+ * mandar una imagen falla con `no-uploads`.
101
108
  */
102
- export function serveSession (session, hub, { origin = 'remote', gate = null } = {}) {
109
+ export function serveSession (session, hub, { origin = 'remote', gate = null, uploadsDir = null } = {}) {
103
110
  let current = null
111
+ const uploads = uploadsDir ? makeUploads(uploadsDir) : null
104
112
  let size = { cols: 80, rows: 24 }
105
113
  const viewer = {
106
114
  origin,
@@ -141,7 +149,8 @@ export function serveSession (session, hub, { origin = 'remote', gate = null } =
141
149
  // aparato» sin nadie mirando, y nadie la elegía como libre).
142
150
  if (current !== c) { c.detach(viewer); return }
143
151
  // Volver a engancharse tras una reconexión (`keep`) no es abrir ni cambiarse: no toca el tamaño.
144
- if (!keep) c.take(viewer)
152
+ // Pero si el tamaño era de esta misma pantalla, lo sigue siendo (y se le sigue el teclado, el giro).
153
+ if (!keep) c.take(viewer); else c.resume(viewer)
145
154
  // La pantalla va en trozos: el proxio corta los mensajes a 1 MB.
146
155
  for (let i = 0; i < snapshot.length || i === 0; i += REPLAY_CHUNK) {
147
156
  await session.send({ type: 'replay', id: c.id, data: snapshot.slice(i, i + REPLAY_CHUNK), last: i + REPLAY_CHUNK >= snapshot.length })
@@ -220,13 +229,22 @@ export function serveSession (session, hub, { origin = 'remote', gate = null } =
220
229
  session.send({ type: 'noted', console: c.info() })
221
230
  return
222
231
  }
232
+ // Una imagen para lo que corre en la consola: se guarda aquí y se contesta dónde quedó.
233
+ if (msg.type === 'file') {
234
+ if (!uploads) return fail('no-uploads', 'this agent has nowhere to keep images')
235
+ try { session.send({ type: 'filed', ...uploads.take(msg) }) } catch (e) {
236
+ if (!e.code) console.error('[terminal-agent] could not keep an image:', e.message)
237
+ fail(e.code || 'file-failed', e.message)
238
+ }
239
+ return
240
+ }
223
241
  // El orden del panel: es de la máquina, así que lo ve igual cualquier pantalla.
224
242
  if (msg.type === 'move') {
225
243
  if (!hub.move(String(msg.id), msg.before == null ? null : String(msg.before))) return fail('no-console', 'that console no longer exists')
226
244
  session.send({ type: 'consoles', list: hub.list() })
227
245
  }
228
246
  })
229
- session.on('close', release)
247
+ session.on('close', () => { release(); uploads?.drop() })
230
248
  }
231
249
 
232
250
  /**
@@ -236,7 +254,7 @@ export function serveSession (session, hub, { origin = 'remote', gate = null } =
236
254
  * otras máquinas hay, y una orden suelta para una de ellas.
237
255
  * Exportada para las pruebas.
238
256
  */
239
- export function serveLocal (session, hub, far) {
257
+ export function serveLocal (session, hub, far, { uploadsDir = null } = {}) {
240
258
  const h = { message: [], close: [] }
241
259
  const inner = { device: null, send: (p) => session.send(p), on (ev, cb) { h[ev]?.push(cb); return this } }
242
260
  const failed = (e) => session.send({ type: 'fail', code: e.code || 'far-error', message: e.message })
@@ -248,7 +266,7 @@ export function serveLocal (session, hub, far) {
248
266
  if (!mode) {
249
267
  if (msg.type === 'via') { mode = 'far'; far.via(inner, msg.machine).catch(failed); return }
250
268
  mode = 'hub'
251
- serveSession(inner, hub, { origin: 'local' })
269
+ serveSession(inner, hub, { origin: 'local', uploadsDir })
252
270
  }
253
271
  for (const cb of h.message) { try { cb(msg) } catch (_) {} }
254
272
  })
@@ -290,7 +308,8 @@ export async function startAgent (opts = {}) {
290
308
  })
291
309
  // Las consolas de las otras máquinas de la cuenta, para las ventanas de esta (far.js).
292
310
  const far = makeFar({ dir, loadLink: () => loadLink(dir), kind: LABEL })
293
- const local = await listenLocal({ dir, serve: (session) => serveLocal(session, hub, far) })
311
+ const uploadsDir = path.join(dir, 'uploads')
312
+ const local = await listenLocal({ dir, serve: (session) => serveLocal(session, hub, far, { uploadsDir }) })
294
313
  let stopped = false
295
314
  const startRemote = () => startRemoteAgent({
296
315
  label: LABEL,
@@ -298,7 +317,7 @@ export async function startAgent (opts = {}) {
298
317
  proxyUrl: opts.proxyUrl,
299
318
  quiet: opts.quiet,
300
319
  onRevoked: () => { hub.killAll(); opts.onRevoked?.() },
301
- onSession: (session) => serveSession(session, hub, { origin: 'remote', gate })
320
+ onSession: (session) => serveSession(session, hub, { origin: 'remote', gate, uploadsDir })
302
321
  })
303
322
  let watcher = null
304
323
  if (loadLink(dir)) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dotrino/terminal-agent",
3
- "version": "0.42.0",
3
+ "version": "0.43.0",
4
4
  "description": "Dotrino Terminal: las ventanas de esta máquina (dotrino-terminal) y su agente, que deja abrir esas mismas consolas desde los otros aparatos de tu cuenta, cifrado punto a punto.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -22,6 +22,7 @@
22
22
  "service.js",
23
23
  "title.js",
24
24
  "update.js",
25
+ "uploads.js",
25
26
  "bin",
26
27
  "skills"
27
28
  ],
package/uploads.js ADDED
@@ -0,0 +1,91 @@
1
+ /**
2
+ * uploads.js — una imagen que manda un aparato de la cuenta se guarda en ESTA máquina.
3
+ *
4
+ * Para qué: desde el teléfono no hay otra forma de enseñarle una foto o una captura a lo que
5
+ * corre en la consola. El aparato la manda por la sesión (cifrada, como todo lo demás), aquí
6
+ * se guarda en un archivo y se le contesta la RUTA, que es lo que se escribe en la consola.
7
+ *
8
+ * Solo imágenes, y qué es lo decide el contenido (sus primeros bytes), no lo que diga quien la
9
+ * manda: el nombre y la extensión los pone el agente. Quien llega hasta aquí ya tiene una shell
10
+ * en la máquina, así que esto no le da nada que no tuviera; aun así no elige ni el nombre ni la
11
+ * carpeta.
12
+ *
13
+ * Llega en trozos (`file`), en orden y con acuse por trozo (`filed`): el proxio corta los
14
+ * mensajes a 1 MB y el acuse hace que el que manda no vaya más rápido de lo que se recibe.
15
+ */
16
+ import fs from 'node:fs'
17
+ import path from 'node:path'
18
+ import crypto from 'node:crypto'
19
+
20
+ /** Lo más que pesa una imagen. El aparato la reduce antes de mandarla; esto es el tope. */
21
+ export const UPLOAD_MAX = 12 * 1024 * 1024
22
+ /** Lo más que pesa un trozo, ya en base64. */
23
+ export const UPLOAD_CHUNK_MAX = 256 * 1024
24
+ /** Lo que se guarda una imagen: después se borra sola. */
25
+ export const UPLOAD_KEEP_MS = 7 * 24 * 60 * 60 * 1000
26
+
27
+ const fail = (code, message) => Object.assign(new Error(message), { code })
28
+
29
+ /** La extensión de una imagen por sus primeros bytes, o null si no es una de las admitidas. */
30
+ export function imageExt (buf) {
31
+ if (buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'png'
32
+ if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'jpg'
33
+ if (buf.length >= 6 && (buf.subarray(0, 6).toString('latin1') === 'GIF87a' || buf.subarray(0, 6).toString('latin1') === 'GIF89a')) return 'gif'
34
+ if (buf.length >= 12 && buf.subarray(0, 4).toString('latin1') === 'RIFF' && buf.subarray(8, 12).toString('latin1') === 'WEBP') return 'webp'
35
+ return null
36
+ }
37
+
38
+ /** Borra las imágenes que ya cumplieron su tiempo. Un fallo aquí se dice y no para nada más. */
39
+ export function pruneUploads (dir, now = Date.now()) {
40
+ let names
41
+ try { names = fs.readdirSync(dir) } catch (e) { if (e.code === 'ENOENT') return; throw e }
42
+ for (const name of names) {
43
+ if (!/^img-.*\.(png|jpg|gif|webp)$/.test(name)) continue
44
+ const file = path.join(dir, name)
45
+ try { if (now - fs.statSync(file).mtimeMs > UPLOAD_KEEP_MS) fs.rmSync(file) } catch (e) {
46
+ console.error('[terminal-agent] could not remove an old image', file, '-', e.message)
47
+ }
48
+ }
49
+ }
50
+
51
+ const stamp = (d) => {
52
+ const p = (n) => String(n).padStart(2, '0')
53
+ return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
54
+ }
55
+
56
+ /**
57
+ * Lo que recibe UNA sesión. Una imagen a la vez: empezar otra descarta la que iba a medias.
58
+ *
59
+ * @param {string} dir la carpeta donde se guardan (se crea, solo para el usuario).
60
+ * @returns {{ take: (msg: { up: string, seq: number, data: string, last?: boolean }) => { up: string, seq: number, path?: string }, drop: () => void }}
61
+ */
62
+ export function makeUploads (dir) {
63
+ /** @type {{ up: string, next: number, size: number, parts: Buffer[] } | null} */
64
+ let cur = null
65
+ return {
66
+ take (msg) {
67
+ const up = typeof msg.up === 'string' ? msg.up.slice(0, 64) : ''
68
+ const seq = msg.seq
69
+ if (!up || !Number.isInteger(seq) || seq < 0 || typeof msg.data !== 'string') throw fail('bad-file', 'file: needs `up`, `seq` and `data`')
70
+ if (msg.data.length > UPLOAD_CHUNK_MAX) { cur = null; throw fail('too-big', 'file: that piece is too big') }
71
+ if (seq === 0) cur = { up, next: 0, size: 0, parts: [] }
72
+ if (!cur || cur.up !== up || cur.next !== seq) { cur = null; throw fail('bad-file', 'file: a piece came out of order') }
73
+ const part = Buffer.from(msg.data, 'base64')
74
+ cur.size += part.length
75
+ if (cur.size > UPLOAD_MAX) { cur = null; throw fail('too-big', `file: the image is over ${UPLOAD_MAX / 1024 / 1024} MB`) }
76
+ cur.parts.push(part)
77
+ cur.next++
78
+ if (!msg.last) return { up, seq }
79
+ const whole = Buffer.concat(cur.parts)
80
+ cur = null
81
+ const ext = imageExt(whole)
82
+ if (!ext) throw fail('not-image', 'file: that is not a PNG, JPEG, GIF or WebP image')
83
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
84
+ pruneUploads(dir)
85
+ const file = path.join(dir, `img-${stamp(new Date())}-${crypto.randomBytes(3).toString('hex')}.${ext}`)
86
+ fs.writeFileSync(file, whole, { mode: 0o600, flag: 'wx' })
87
+ return { up, seq, path: file }
88
+ },
89
+ drop () { cur = null }
90
+ }
91
+ }