@fungi.computer/shed 0.9.1 → 0.10.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/backend/runs.ts CHANGED
@@ -11,8 +11,11 @@ import {
11
11
  maximumProcessRecords,
12
12
  processStartInputSchema,
13
13
  processListOutputSchema,
14
+ processKillOutputSchema,
15
+ type processIdInputSchema,
14
16
  type ComputerProcess,
15
17
  } from "@fungi.computer/computer-contract";
18
+ import type { ShedProcessRecord } from "./observation.js";
16
19
  import {
17
20
  runCommandInputSchema,
18
21
  runCommandResultSchema,
@@ -23,13 +26,20 @@ const processInputSchema = processStartInputSchema.omit({
23
26
  requestId: true,
24
27
  requestScope: true,
25
28
  });
29
+ /**
30
+ * The caller's replay key when the host supplies none, as for an external key
31
+ * over MCP or HTTP. A host-attested key always wins.
32
+ */
33
+ export const shedRequestIdSchema = processStartInputSchema.shape.requestId;
26
34
  export const shedRunInputSchema = processInputSchema
27
35
  .omit({ port: true })
28
36
  .extend({
29
37
  gitAccess: resolvedGitAccessSchema.optional(),
38
+ requestId: shedRequestIdSchema.optional(),
30
39
  });
31
40
  export const shedStartInputSchema = processInputSchema.extend({
32
41
  gitAccess: resolvedGitAccessSchema.optional(),
42
+ requestId: shedRequestIdSchema.optional(),
33
43
  });
34
44
  export type ShedStartInput = z.output<typeof shedStartInputSchema>;
35
45
  export type ShedRunInput = z.output<typeof shedRunInputSchema>;
@@ -46,9 +56,17 @@ export type ShedComputer = Readonly<{
46
56
  command: string;
47
57
  cwd?: string | undefined;
48
58
  port?: number | undefined;
59
+ requestId?: string | undefined;
49
60
  }): Promise<z.core.util.JSONType>;
50
61
  processes(input: Record<string, never>): Promise<z.core.util.JSONType>;
51
62
  }>;
63
+ /** Restart also signals the process it replaces. */
64
+ type ShedRestartComputer = ShedComputer &
65
+ Readonly<{
66
+ processKill(
67
+ input: z.output<typeof processIdInputSchema>,
68
+ ): Promise<z.core.util.JSONType>;
69
+ }>;
52
70
 
53
71
  const bindingNotGranted = z.object({
54
72
  code: z.literal("binding_not_granted"),
@@ -77,7 +95,20 @@ const rowSchema = z.strictObject({
77
95
  exitCode: z.number().int().nullable(),
78
96
  logPath: z.string(),
79
97
  gitAccess: z.string().nullable(),
98
+ /**
99
+ * The declared port: 0 when the process declared none, null for a row written
100
+ * before ports were recorded, which cannot be restarted.
101
+ */
102
+ port: z.number().int().nonnegative().nullable(),
103
+ /** The process this one restarted, when it is a restart. */
104
+ parentId: z.string().nullable(),
105
+ /**
106
+ * When Shed signalled this process to stop for its caller, null for a row
107
+ * written before stops were recorded and for a process nobody stopped.
108
+ */
109
+ stoppedAt: z.number().int().nullable(),
80
110
  });
111
+ type Mode = "start" | "run" | "restart";
81
112
  export const shedRunCommandInputSchema = runCommandInputSchema.extend({
82
113
  gitAccess: resolvedGitAccessSchema.optional(),
83
114
  });
@@ -122,7 +153,7 @@ export async function runShedCommand(
122
153
  });
123
154
  }
124
155
 
125
- function claimKey(actor: HostActor, method: "start" | "run", key: string) {
156
+ function claimKey(actor: HostActor, method: Mode, key: string) {
126
157
  return JSON.stringify([actor, method, key]);
127
158
  }
128
159
  const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
@@ -146,8 +177,26 @@ export function createShedRuns(sql: ShedSql) {
146
177
  // disposable, so it is dropped, never read, copied or migrated.
147
178
  sql.exec("DROP TABLE IF EXISTS shed_process_claims");
148
179
  sql.exec(
149
- "CREATE TABLE IF NOT EXISTS shed_native_process_claims (requestKey TEXT PRIMARY KEY, computerId TEXT NOT NULL, command TEXT NOT NULL, cwd TEXT, processId TEXT, phase TEXT NOT NULL, startedAt INTEGER, exitCode INTEGER, logPath TEXT NOT NULL, gitAccess TEXT)",
180
+ "CREATE TABLE IF NOT EXISTS shed_native_process_claims (requestKey TEXT PRIMARY KEY, computerId TEXT NOT NULL, command TEXT NOT NULL, cwd TEXT, processId TEXT, phase TEXT NOT NULL, startedAt INTEGER, exitCode INTEGER, logPath TEXT NOT NULL, gitAccess TEXT, port INTEGER, parentId TEXT, stoppedAt INTEGER)",
181
+ );
182
+ // Rows written before ports and restarts were recorded keep their data: the
183
+ // columns are added in place, never reset, and stay null on those rows.
184
+ const columns = new Set(
185
+ z
186
+ .array(z.object({ name: z.string() }))
187
+ .parse(
188
+ sql.exec("PRAGMA table_info(shed_native_process_claims)").toArray(),
189
+ )
190
+ .map((column) => column.name),
150
191
  );
192
+ if (!columns.has("port"))
193
+ sql.exec("ALTER TABLE shed_native_process_claims ADD COLUMN port INTEGER");
194
+ if (!columns.has("parentId"))
195
+ sql.exec("ALTER TABLE shed_native_process_claims ADD COLUMN parentId TEXT");
196
+ if (!columns.has("stoppedAt"))
197
+ sql.exec(
198
+ "ALTER TABLE shed_native_process_claims ADD COLUMN stoppedAt INTEGER",
199
+ );
151
200
  sql.exec(
152
201
  "CREATE TABLE IF NOT EXISTS shed_retired_claim_keys (requestKey TEXT PRIMARY KEY)",
153
202
  );
@@ -165,11 +214,7 @@ export function createShedRuns(sql: ShedSql) {
165
214
  .toArray().length !== 0
166
215
  );
167
216
  }
168
- function scopeRows(
169
- actor: HostActor,
170
- mode: "start" | "run",
171
- computerId: string,
172
- ) {
217
+ function scopeRows(actor: HostActor, mode: Mode, computerId: string) {
173
218
  return z
174
219
  .array(rowSchema)
175
220
  .parse(
@@ -183,7 +228,7 @@ export function createShedRuns(sql: ShedSql) {
183
228
  .toArray(),
184
229
  );
185
230
  }
186
- function retire(requestKey: string, actor: HostActor, mode: "start" | "run") {
231
+ function retire(requestKey: string, actor: HostActor, mode: Mode) {
187
232
  // Record rejection first, so an interruption cannot turn a retired key into a new start.
188
233
  sql.exec(
189
234
  "INSERT OR IGNORE INTO shed_retired_claim_keys (requestKey) VALUES (?)",
@@ -204,7 +249,7 @@ export function createShedRuns(sql: ShedSql) {
204
249
  }
205
250
  function trimScope(
206
251
  actor: HostActor,
207
- mode: "start" | "run",
252
+ mode: Mode,
208
253
  computerId: string,
209
254
  current: string,
210
255
  ) {
@@ -224,7 +269,7 @@ export function createShedRuns(sql: ShedSql) {
224
269
  }
225
270
  async function refreshScope(
226
271
  actor: HostActor,
227
- mode: "start" | "run",
272
+ mode: Mode,
228
273
  computerId: string,
229
274
  computer: ShedComputer,
230
275
  ) {
@@ -274,17 +319,19 @@ export function createShedRuns(sql: ShedSql) {
274
319
  prior: z.output<typeof rowSchema>,
275
320
  input: ShedRunInput,
276
321
  computerId: string,
322
+ parentId: string | null,
277
323
  ) {
278
324
  if (
279
325
  prior.computerId !== computerId ||
280
326
  prior.command !== input.command ||
281
327
  prior.cwd !== (input.cwd ?? null) ||
328
+ prior.parentId !== parentId ||
282
329
  prior.gitAccess !==
283
330
  (input.gitAccess === undefined ? null : JSON.stringify(input.gitAccess))
284
331
  )
285
332
  throw new AppMethodRefusal(
286
333
  "conflict",
287
- "Run identity conflicts with its original command, Git scope or Computer",
334
+ "Run identity conflicts with its original command, Git scope, Computer or restarted process",
288
335
  );
289
336
  }
290
337
  async function claim(
@@ -293,9 +340,11 @@ export function createShedRuns(sql: ShedSql) {
293
340
  rawKey: string,
294
341
  actor: HostActor,
295
342
  computer: ShedComputer,
296
- mode: "start" | "run",
343
+ mode: Mode,
344
+ parentId: string | null = null,
345
+ nativeRequestId?: string,
297
346
  ) {
298
- if (actor.kind !== "member")
347
+ if (actor.kind === "agent")
299
348
  return shedComputerRefusalSchema.parse({ error: "not_granted" });
300
349
  const requestKey = claimKey(actor, mode, rawKey);
301
350
  if (retired(requestKey))
@@ -317,10 +366,16 @@ export function createShedRuns(sql: ShedSql) {
317
366
  };
318
367
  if (input.cwd !== undefined) processInput.cwd = input.cwd;
319
368
  if (input.port !== undefined) processInput.port = input.port;
320
- return { start: processInputSchema.parse(processInput), logPath };
369
+ // The host's own key reaches the binding first; the caller's request id
370
+ // goes along only when the host attested none, as for an external key.
371
+ const start: z.output<typeof processInputSchema> & {
372
+ requestId?: string;
373
+ } = processInputSchema.parse(processInput);
374
+ if (nativeRequestId !== undefined) start.requestId = nativeRequestId;
375
+ return { start, logPath };
321
376
  }
322
377
  async function dispatch(
323
- start: z.output<typeof processInputSchema>,
378
+ start: z.output<typeof processInputSchema> & { requestId?: string },
324
379
  logPath: string,
325
380
  ) {
326
381
  starting.set(requestKey, input.port ?? null);
@@ -346,7 +401,7 @@ export function createShedRuns(sql: ShedSql) {
346
401
  const gitAccess =
347
402
  input.gitAccess === undefined ? null : JSON.stringify(input.gitAccess);
348
403
  async function resume(prior: z.output<typeof rowSchema>) {
349
- verify(prior, input, computerId);
404
+ verify(prior, input, computerId, parentId);
350
405
  if (prior.phase === "starting") {
351
406
  const activePort = starting.get(requestKey);
352
407
  if (activePort !== undefined) {
@@ -358,7 +413,7 @@ export function createShedRuns(sql: ShedSql) {
358
413
  return pending(5000);
359
414
  }
360
415
  // The host binding retains this call's native idempotency key across retries.
361
- if (mode === "start") {
416
+ if (mode !== "run") {
362
417
  const prepared = prepare();
363
418
  return dispatch(prepared.start, prior.logPath);
364
419
  }
@@ -385,30 +440,94 @@ export function createShedRuns(sql: ShedSql) {
385
440
  if (prior) return resume(prior);
386
441
  const { start, logPath } = prepare();
387
442
  sql.exec(
388
- "INSERT INTO shed_native_process_claims (requestKey,computerId,command,cwd,phase,logPath,gitAccess) VALUES (?,?,?,?,'starting',?,?)",
443
+ "INSERT INTO shed_native_process_claims (requestKey,computerId,command,cwd,phase,logPath,gitAccess,port,parentId) VALUES (?,?,?,?,'starting',?,?,?,?)",
389
444
  requestKey,
390
445
  computerId,
391
446
  input.command,
392
447
  input.cwd ?? null,
393
448
  logPath,
394
449
  gitAccess,
450
+ input.port ?? 0,
451
+ parentId,
395
452
  );
396
453
  return dispatch(start, logPath);
397
454
  }
455
+ function recordOf(row: z.output<typeof rowSchema>): ShedProcessRecord {
456
+ return {
457
+ parentId: row.parentId,
458
+ stoppedAt: row.stoppedAt,
459
+ logPath: row.logPath,
460
+ };
461
+ }
462
+ /** The caller's own latest record of one process; agents never own one. */
463
+ function ownedRow(processId: string, computerId: string, actor: HostActor) {
464
+ if (actor.kind === "agent") return null;
465
+ const row = sql
466
+ .exec(
467
+ "SELECT * FROM shed_native_process_claims WHERE processId=? AND computerId=? AND json_extract(requestKey,'$[0]')=? ORDER BY rowid DESC LIMIT 1",
468
+ processId,
469
+ computerId,
470
+ JSON.stringify(actor),
471
+ )
472
+ .toArray()[0];
473
+ return row === undefined ? null : rowSchema.parse(row);
474
+ }
475
+ /** Notes that the Computer accepted a stop signal for this caller's process. */
476
+ function recordStop(processId: string, computerId: string, actor: HostActor) {
477
+ const row = ownedRow(processId, computerId, actor);
478
+ if (row === null) return;
479
+ sql.exec(
480
+ "UPDATE shed_native_process_claims SET stoppedAt=COALESCE(stoppedAt,?) WHERE requestKey=?",
481
+ Date.now(),
482
+ row.requestKey,
483
+ );
484
+ }
398
485
  return {
399
486
  owns(processId: string, computerId: string, actor: HostActor) {
400
- if (actor.kind !== "member") return false;
401
- return (
402
- sql
403
- .exec(
404
- "SELECT requestKey FROM shed_native_process_claims WHERE processId=? AND computerId=? AND json_extract(requestKey,'$[0]')=?",
405
- processId,
406
- computerId,
407
- JSON.stringify(actor),
487
+ return ownedRow(processId, computerId, actor) !== null;
488
+ },
489
+ /** The processes this caller started on the Computer, by process id. */
490
+ ownedRecords(
491
+ computerId: string,
492
+ actor: HostActor,
493
+ ): ReadonlyMap<string, ShedProcessRecord> {
494
+ if (actor.kind === "agent") return new Map();
495
+ return new Map(
496
+ z
497
+ .array(rowSchema)
498
+ .parse(
499
+ sql
500
+ .exec(
501
+ "SELECT * FROM shed_native_process_claims WHERE processId IS NOT NULL AND computerId=? AND json_extract(requestKey,'$[0]')=? ORDER BY rowid ASC",
502
+ computerId,
503
+ JSON.stringify(actor),
504
+ )
505
+ .toArray(),
408
506
  )
409
- .toArray().length !== 0
507
+ .flatMap((row) =>
508
+ row.processId === null ? [] : [[row.processId, recordOf(row)]],
509
+ ),
410
510
  );
411
511
  },
512
+ /** What Shed recorded of a process this caller started, or null. */
513
+ recordById(
514
+ processId: string,
515
+ computerId: string,
516
+ actor: HostActor,
517
+ ): ShedProcessRecord | null {
518
+ const row = ownedRow(processId, computerId, actor);
519
+ return row === null ? null : recordOf(row);
520
+ },
521
+ recordStop,
522
+ /** A log named by the process this caller started, not by the call key. */
523
+ logPathById(
524
+ processId: string,
525
+ computerId: string,
526
+ actor: HostActor,
527
+ ): { path: string } | { error: "not_found" } {
528
+ const row = ownedRow(processId, computerId, actor);
529
+ return row === null ? { error: "not_found" } : { path: row.logPath };
530
+ },
412
531
  logPath(
413
532
  rawKey: string,
414
533
  computerId: string,
@@ -430,8 +549,78 @@ export function createShedRuns(sql: ShedSql) {
430
549
  requestKey: string,
431
550
  actor: HostActor,
432
551
  computer: ShedComputer,
552
+ nativeRequestId?: string,
553
+ ) {
554
+ return claim(
555
+ input,
556
+ computerId,
557
+ requestKey,
558
+ actor,
559
+ computer,
560
+ "start",
561
+ null,
562
+ nativeRequestId,
563
+ );
564
+ },
565
+ /**
566
+ * Stop one of this caller's processes and start its recorded command, cwd
567
+ * and port as a new process linked by `parentId`. The request id replays
568
+ * the new process; the replaced one is signalled only before that claim.
569
+ */
570
+ async restart(
571
+ processId: z.output<typeof processIdInputSchema>["id"],
572
+ computerId: string,
573
+ requestKey: string,
574
+ actor: HostActor,
575
+ computer: ShedRestartComputer,
576
+ nativeRequestId?: string,
433
577
  ) {
434
- return claim(input, computerId, requestKey, actor, computer, "start");
578
+ if (actor.kind === "agent")
579
+ return shedComputerRefusalSchema.parse({ error: "not_granted" });
580
+ const parent = ownedRow(processId, computerId, actor);
581
+ if (parent === null || retired(claimKey(actor, "restart", requestKey)))
582
+ return shedComputerRefusalSchema.parse({ error: "not_found" });
583
+ // No recorded port (an older row) or a Git scope cannot be replayed faithfully.
584
+ if (parent.port === null || parent.gitAccess !== null)
585
+ return shedComputerRefusalSchema.parse({ error: "invalid" });
586
+ if (read(claimKey(actor, "restart", requestKey)) === null) {
587
+ const inventory = await computerCall(() => computer.processes({}));
588
+ const refused = shedComputerRefusalSchema.safeParse(inventory);
589
+ if (refused.success) return refused.data;
590
+ const current = processListOutputSchema
591
+ .parse(inventory)
592
+ .processes.find((item) => item.id === processId);
593
+ if (current?.state === "uncertain")
594
+ return shedComputerRefusalSchema.parse({ error: "unavailable" });
595
+ if (current?.state === "running") {
596
+ const reply = await computerCall(() =>
597
+ computer.processKill({ id: processId }),
598
+ );
599
+ const denied = shedComputerRefusalSchema.safeParse(reply);
600
+ if (denied.success) return denied.data;
601
+ // The new process may need the old one's port: wait for its exit.
602
+ const stopped = processKillOutputSchema.parse(reply);
603
+ if (stopped.signalled) recordStop(processId, computerId, actor);
604
+ if (stopped.process.state !== "exited")
605
+ return stopped.signalled
606
+ ? pending(1000)
607
+ : shedComputerRefusalSchema.parse({ error: "unavailable" });
608
+ }
609
+ }
610
+ const input: ShedStartInput = { command: parent.command };
611
+ if (parent.cwd !== null) input.cwd = parent.cwd;
612
+ if (parent.port !== 0) input.port = parent.port;
613
+ const result = await claim(
614
+ input,
615
+ computerId,
616
+ requestKey,
617
+ actor,
618
+ computer,
619
+ "restart",
620
+ processId,
621
+ nativeRequestId,
622
+ );
623
+ return "process" in result ? { ...result, parentId: processId } : result;
435
624
  },
436
625
  async run(
437
626
  input: ShedRunInput,
@@ -439,14 +628,15 @@ export function createShedRuns(sql: ShedSql) {
439
628
  requestKey: string,
440
629
  actor: HostActor,
441
630
  computer: ShedComputer,
631
+ nativeRequestId?: string,
442
632
  ) {
443
- if (actor.kind !== "member")
633
+ if (actor.kind === "agent")
444
634
  return shedComputerRefusalSchema.parse({ error: "not_granted" });
445
635
  if (retired(claimKey(actor, "run", requestKey)))
446
636
  return shedComputerRefusalSchema.parse({ error: "not_found" });
447
637
  const prior = read(claimKey(actor, "run", requestKey));
448
638
  if (prior) {
449
- verify(prior, input, computerId);
639
+ verify(prior, input, computerId, null);
450
640
  if (prior.phase === "exited")
451
641
  return completion(prior.exitCode, prior.logPath);
452
642
  }
@@ -457,6 +647,8 @@ export function createShedRuns(sql: ShedSql) {
457
647
  actor,
458
648
  computer,
459
649
  "run",
650
+ null,
651
+ nativeRequestId,
460
652
  );
461
653
  if ("kind" in result) return result;
462
654
  if ("error" in result) return result;