@fungi.computer/shed 0.9.0 → 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/README.md +41 -16
- package/backend/methods.ts +175 -37
- package/backend/observation.ts +67 -0
- package/backend/process-page.ts +25 -3
- package/backend/runs.ts +222 -30
- package/backend/test/key-processes.node.test.ts +586 -0
- package/backend/test/methods.test.ts +24 -4
- package/backend/test/observation.node.test.ts +421 -0
- package/backend/test/runs.node.test.ts +16 -6
- package/dist/assets/{index-DT5cobOX.js → index-DqaFSc_Z.js} +1 -1
- package/dist/index.html +1 -1
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -10,7 +10,22 @@ Shed is one of the starter Apps of
|
|
|
10
10
|
on your own Cloudflare account. On Oyster, the Computer is a Linux workspace in
|
|
11
11
|
a Cloudflare Container; Shed runs commands there, not on your laptop.
|
|
12
12
|
|
|
13
|
-
##
|
|
13
|
+
## Quick start
|
|
14
|
+
|
|
15
|
+
In a Fungi monorepo checkout with dependencies installed, run the component
|
|
16
|
+
workbench from the root:
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
pnpm workbench:prepare
|
|
20
|
+
pnpm exec ladle serve --port 61983
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Open <http://localhost:61983/?story=shed--workspace&mode=preview&theme=light>.
|
|
24
|
+
This is Shed's real UI with local fixture data (a local Computer fixture; typed
|
|
25
|
+
input echoes and no commands run), not a live Oyster. To run Shed on a real
|
|
26
|
+
Oyster, see [Get it](#get-it).
|
|
27
|
+
|
|
28
|
+
## Common tasks
|
|
14
29
|
|
|
15
30
|
- Type commands at an instant light prompt (`ls`, `rg TODO`, `jq . package.json`
|
|
16
31
|
and the like). A command that needs a real Linux process, such as `npm`,
|
|
@@ -28,7 +43,9 @@ stops and do not come back when it starts. Closing Shed does not stop a process.
|
|
|
28
43
|
|
|
29
44
|
<img alt="Shed on a phone in the light theme: the light shell prompt in /workspace with the footer controls below" src="docs/media/terminal-phone.png" width="300">
|
|
30
45
|
|
|
31
|
-
##
|
|
46
|
+
## Reference
|
|
47
|
+
|
|
48
|
+
### Get it
|
|
32
49
|
|
|
33
50
|
Shed installs with the other starter Apps. On a deployed Oyster (see the
|
|
34
51
|
[Oyster quick start](https://github.com/fungi-computer/oyster#deploy-to-cloudflare)),
|
|
@@ -51,7 +68,7 @@ registrable site from the owner sign-in. Without it, **Ports** still exposes and
|
|
|
51
68
|
removes ports and says that previews are off. Reopen old preview links from the
|
|
52
69
|
Ports tray.
|
|
53
70
|
|
|
54
|
-
|
|
71
|
+
### Change it
|
|
55
72
|
|
|
56
73
|
Every installed App is also a template you can fork on your own Oyster. Fork
|
|
57
74
|
Shed into a Bonsai repository and clone it with ordinary `git`:
|
|
@@ -74,7 +91,7 @@ your forks with `--repositories <base URL>` and `--ref <branch or tag>`. The
|
|
|
74
91
|
installer reads all seven starter Apps from that base, so fork them under one
|
|
75
92
|
account.
|
|
76
93
|
|
|
77
|
-
|
|
94
|
+
### Agent tools
|
|
78
95
|
|
|
79
96
|
Agents call Shed through Oyster's MCP endpoint, or at
|
|
80
97
|
`POST $OYSTER_URL/apps/shed/methods/<name>` with a key; see
|
|
@@ -83,25 +100,33 @@ Agents call Shed through Oyster's MCP endpoint, or at
|
|
|
83
100
|
| Method | What it does |
|
|
84
101
|
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
85
102
|
| `runCommand({command, cwd?, timeoutMs?})` | Runs a shell command for up to 45 seconds. Returns `stdout`, `stderr`, `exitCode`, `stdoutTruncated` and `stderrTruncated` (64 KiB per stream), or `{ error: code }`. A budget refusal also supplies `kind` and `retryAfterMs`. Workflow Git commands use `$FUNGI_GIT_REMOTE`. |
|
|
86
|
-
| `listProcesses({})` | Lists up to 64 processes on the Computer. Starts nothing.
|
|
103
|
+
| `listProcesses({})` | Lists up to 64 processes on the Computer. Each row says `controllable`: true when you started it, so `stop`, `restart` and `logs` by id accept it. Each row also carries `run`, the same run `observe` returns, with no log position. Starts nothing. |
|
|
87
104
|
| `listPorts({})` | Lists up to 64 forwarded ports. Starts nothing. |
|
|
88
105
|
|
|
89
|
-
Workflows (see [Trellis](https://github.com/fungi-computer/trellis))
|
|
90
|
-
second set for longer
|
|
106
|
+
Workflows (see [Trellis](https://github.com/fungi-computer/trellis)) and an
|
|
107
|
+
outside server holding a key scoped to one Computer use a second set for longer
|
|
108
|
+
work:
|
|
109
|
+
|
|
110
|
+
| Method | What it does |
|
|
111
|
+
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
112
|
+
| `run({command, cwd, requestId?})` | Starts one process, logs its output under `/workspace/.fungi/runs/`, and waits until it exits. A retry reuses the same process. |
|
|
113
|
+
| `start({command, cwd?, port?, requestId?})` | Starts a process without waiting for it. The same `requestId` with the same input returns the same process; changed input is a `conflict`. A Workflow's own key wins over `requestId`. |
|
|
114
|
+
| `observe({id, cursor?})` | Reads one process as a run: `state`, `reason`, times, `outputs` and `cost`, which is always `null` because nothing is metered. A process you stopped reads `cancelled`; one the Computer ended by sleeping reads `failed` with reason `computer_slept`; one the Computer cannot check reads `unknown`. For a process you started it also returns `log: { cursor, size, eof }`: send the `cursor` back to move up to 128 KiB along the log until `eof`, and read the bytes with `logs`. |
|
|
115
|
+
| `stop({id})` | Stops a process you started. Another caller's process, such as one started in the Shed window, answers `not_found`. |
|
|
116
|
+
| `logs({id, offset, length})` | Reads up to 128 KiB of the log of a process you started. `logs({run, ...})` still names a log by the call key. |
|
|
117
|
+
| `restart({id, requestId})` | Stops a process you started and starts its command, directory and port again as a new process whose `parentId` is the old one. It answers pending until the old process has exited; retry with the same `requestId`. A process started before Shed recorded ports cannot be restarted: start it again. |
|
|
118
|
+
| `expose({port})` | Returns a preview URL for a port that is already exposed. |
|
|
91
119
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
| `start` / `stop` | Start a process without waiting for it, or stop one. |
|
|
96
|
-
| `logs({run, offset, length})` | Reads up to 128 KiB of a run's log. |
|
|
97
|
-
| `expose({port})` | Returns a preview URL for a port that is already exposed. |
|
|
120
|
+
A key calls these over MCP with no host idempotency key, so it names its own
|
|
121
|
+
`requestId`. Revoking the key refuses its next `stop`, `restart` and `logs`
|
|
122
|
+
call. Processes it started keep running until the owner stops them.
|
|
98
123
|
|
|
99
124
|
A workflow step can be given push or read access to one repository. Its command
|
|
100
125
|
then finds a credential-free remote in `$FUNGI_GIT_REMOTE`, for example
|
|
101
126
|
`git push "$FUNGI_GIT_REMOTE" HEAD:refs/heads/main`. Arguments never choose the
|
|
102
127
|
Computer; the host does.
|
|
103
128
|
|
|
104
|
-
|
|
129
|
+
### Build and check
|
|
105
130
|
|
|
106
131
|
Shed is a React App built with Vite. Its terminal renders with Ghostty and its
|
|
107
132
|
controls come from [Caps](https://github.com/fungi-computer/caps).
|
|
@@ -120,11 +145,11 @@ prompt, [src/terminal-panel.tsx](src/terminal-panel.tsx) the full terminal, and
|
|
|
120
145
|
agent tools are in [backend/methods.ts](backend/methods.ts), and
|
|
121
146
|
[package.json](package.json) declares the permissions the App asks for.
|
|
122
147
|
|
|
123
|
-
|
|
148
|
+
### License
|
|
124
149
|
|
|
125
150
|
MIT. See [LICENSE](LICENSE).
|
|
126
151
|
|
|
127
|
-
|
|
152
|
+
### Local film replay
|
|
128
153
|
|
|
129
154
|
`TerminalPanel` optionally accepts `onTerminalReady(handle)` after Ghostty and
|
|
130
155
|
its font metrics are ready. The typed `TerminalFilmHandle` exposes `write`,
|
package/backend/methods.ts
CHANGED
|
@@ -3,8 +3,11 @@ import { processesGill } from "./gills.js";
|
|
|
3
3
|
import {
|
|
4
4
|
processPageInputSchema,
|
|
5
5
|
processPageSchema,
|
|
6
|
+
processInventorySchema,
|
|
6
7
|
pageProcesses,
|
|
7
8
|
} from "./process-page.js";
|
|
9
|
+
import { observeProcess } from "./observation.js";
|
|
10
|
+
import { runObservationSchema } from "@fungi.computer/agar/run-observation";
|
|
8
11
|
import * as z from "zod";
|
|
9
12
|
import { Base64 } from "effect/encoding";
|
|
10
13
|
import { computerPortInputSchema } from "@fungi.computer/computer-contract";
|
|
@@ -13,6 +16,7 @@ import {
|
|
|
13
16
|
computerCall,
|
|
14
17
|
shedRunCommandInputSchema,
|
|
15
18
|
shedRunInputSchema,
|
|
19
|
+
shedRequestIdSchema,
|
|
16
20
|
shedStartInputSchema,
|
|
17
21
|
type ShedComputer,
|
|
18
22
|
type ShedRuns,
|
|
@@ -38,6 +42,7 @@ const command = runCommandInputSchema;
|
|
|
38
42
|
const refusal = shedComputerRefusalSchema;
|
|
39
43
|
const portsReply = z.union([computerPortsOutputSchema, refusal]);
|
|
40
44
|
const processesReply = z.union([processPageSchema, refusal]);
|
|
45
|
+
const inventoryReply = z.union([processInventorySchema, refusal]);
|
|
41
46
|
const commandReply = runCommandResultSchema;
|
|
42
47
|
/** Only scoped inventory and execution bindings enter this runtime-neutral definition. */
|
|
43
48
|
export type ShedMethodContext = Readonly<{
|
|
@@ -69,6 +74,13 @@ const bytes = z.strictObject({
|
|
|
69
74
|
encoding: z.literal("base64"),
|
|
70
75
|
truncated: z.boolean(),
|
|
71
76
|
});
|
|
77
|
+
/**
|
|
78
|
+
* The Computer binding takes its replay key from the host when the host
|
|
79
|
+
* attested one. Only a caller the host attested none for, such as a key over
|
|
80
|
+
* MCP, sends its own request id along.
|
|
81
|
+
*/
|
|
82
|
+
const nativeRequestId = (hostKey: string | undefined, requestKey: string) =>
|
|
83
|
+
hostKey === undefined ? requestKey : undefined;
|
|
72
84
|
/** The script's command lines, without blanks and comments. */
|
|
73
85
|
const commandLines = (command: string) =>
|
|
74
86
|
command
|
|
@@ -86,6 +98,28 @@ const scriptLength = (command: string) => {
|
|
|
86
98
|
return lines > 1 ? [`${String(lines)} commands`] : [];
|
|
87
99
|
};
|
|
88
100
|
|
|
101
|
+
const maximumLogWindow = 131072;
|
|
102
|
+
/** One bounded read of a log, checked against what was asked for. */
|
|
103
|
+
async function readLogWindow(
|
|
104
|
+
computer: ShedMethodContext["env"]["COMPUTER"],
|
|
105
|
+
path: string,
|
|
106
|
+
offset: number,
|
|
107
|
+
length: number,
|
|
108
|
+
) {
|
|
109
|
+
const reply = bytes.parse(
|
|
110
|
+
await computer.read({ path, byteOffset: offset, byteLength: length }),
|
|
111
|
+
);
|
|
112
|
+
const decoded = Base64.decode(reply.content);
|
|
113
|
+
if (
|
|
114
|
+
reply.path !== path ||
|
|
115
|
+
reply.byteOffset !== offset ||
|
|
116
|
+
decoded._tag === "Failure" ||
|
|
117
|
+
decoded.success.byteLength > length
|
|
118
|
+
)
|
|
119
|
+
throw new Error("Invalid Computer log reply");
|
|
120
|
+
return { reply, byteLength: decoded.success.byteLength };
|
|
121
|
+
}
|
|
122
|
+
|
|
89
123
|
export const appBackend = defineAppBackend<ShedMethodContext>({
|
|
90
124
|
gills: [processesGill],
|
|
91
125
|
methods: {
|
|
@@ -107,44 +141,95 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
|
|
|
107
141
|
}),
|
|
108
142
|
logs: defineAppMethod({
|
|
109
143
|
description:
|
|
110
|
-
"Read up to 128 KiB from a
|
|
144
|
+
"Read up to 128 KiB from a log, identified by the process id this caller started or by its host call key; offsets and lengths are bytes.",
|
|
111
145
|
effect: "read",
|
|
112
146
|
requires: ["computer.readFile"],
|
|
113
|
-
input: z
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
147
|
+
input: z
|
|
148
|
+
.strictObject({
|
|
149
|
+
run: z.string().min(1).max(128).optional(),
|
|
150
|
+
id: processIdInputSchema.shape.id.optional(),
|
|
151
|
+
offset: z.number().int().nonnegative().default(0),
|
|
152
|
+
length: z.number().int().min(1).max(131072).default(131072),
|
|
153
|
+
})
|
|
154
|
+
.check(
|
|
155
|
+
z.refine(
|
|
156
|
+
(input) => (input.run === undefined) !== (input.id === undefined),
|
|
157
|
+
"Name the log by run or by id, not both",
|
|
158
|
+
),
|
|
159
|
+
),
|
|
118
160
|
output: z.union([
|
|
119
|
-
bytes.extend({
|
|
161
|
+
bytes.extend({
|
|
162
|
+
run: z.string().optional(),
|
|
163
|
+
id: processIdInputSchema.shape.id.optional(),
|
|
164
|
+
}),
|
|
120
165
|
z.strictObject({ error: z.enum(["not_found", "ambiguous"]) }),
|
|
121
166
|
]),
|
|
122
167
|
handler: async (input, context: ShedMethodContext, caller) => {
|
|
123
168
|
if (!caller.computerId || !context.runs)
|
|
124
169
|
throw new Error("Computer file access is not granted");
|
|
125
|
-
const log =
|
|
126
|
-
input.
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
170
|
+
const log =
|
|
171
|
+
input.id !== undefined
|
|
172
|
+
? context.runs.logPathById(
|
|
173
|
+
input.id,
|
|
174
|
+
caller.computerId,
|
|
175
|
+
caller.actor,
|
|
176
|
+
)
|
|
177
|
+
: input.run === undefined
|
|
178
|
+
? ({ error: "not_found" } as const)
|
|
179
|
+
: context.runs.logPath(
|
|
180
|
+
input.run,
|
|
181
|
+
caller.computerId,
|
|
182
|
+
caller.actor,
|
|
183
|
+
);
|
|
130
184
|
if ("error" in log) return log;
|
|
131
|
-
const
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
byteLength: input.length,
|
|
137
|
-
}),
|
|
185
|
+
const { reply } = await readLogWindow(
|
|
186
|
+
context.env.COMPUTER,
|
|
187
|
+
log.path,
|
|
188
|
+
input.offset,
|
|
189
|
+
input.length,
|
|
138
190
|
);
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
reply
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
191
|
+
return input.id === undefined
|
|
192
|
+
? { ...reply, run: input.run }
|
|
193
|
+
: { ...reply, id: input.id };
|
|
194
|
+
},
|
|
195
|
+
}),
|
|
196
|
+
observe: defineAppMethod({
|
|
197
|
+
description:
|
|
198
|
+
"Read one process on the attached Computer as a run: its state, why, times, outputs and, for a process this caller started, a log position. Pass the returned log cursor back to advance up to 128 KiB along the log until eof, and read the bytes with logs. Cost is null: no process is metered. Starts nothing.",
|
|
199
|
+
effect: "read",
|
|
200
|
+
requires: ["computer.execute", "computer.readFile"],
|
|
201
|
+
input: z.strictObject({
|
|
202
|
+
id: processIdInputSchema.shape.id,
|
|
203
|
+
cursor: z.number().int().nonnegative().default(0),
|
|
204
|
+
}),
|
|
205
|
+
output: z.union([runObservationSchema, refusal]),
|
|
206
|
+
handler: async (input, context: ShedMethodContext, caller) => {
|
|
207
|
+
if (caller.computerId === null)
|
|
208
|
+
return refusal.parse({ error: "not_granted" });
|
|
209
|
+
const inventory = inventoryReply.parse(
|
|
210
|
+
await computerCall(() => context.env.COMPUTER.processes({})),
|
|
211
|
+
);
|
|
212
|
+
if ("error" in inventory) return inventory;
|
|
213
|
+
const process = inventory.processes.find(
|
|
214
|
+
(item) => item.id === input.id,
|
|
215
|
+
);
|
|
216
|
+
if (process === undefined) return refusal.parse({ error: "not_found" });
|
|
217
|
+
const record =
|
|
218
|
+
context.runs?.recordById(input.id, caller.computerId, caller.actor) ??
|
|
219
|
+
null;
|
|
220
|
+
if (record === null) return observeProcess(process, null, null);
|
|
221
|
+
const { reply, byteLength } = await readLogWindow(
|
|
222
|
+
context.env.COMPUTER,
|
|
223
|
+
record.logPath,
|
|
224
|
+
input.cursor,
|
|
225
|
+
maximumLogWindow,
|
|
226
|
+
);
|
|
227
|
+
const cursor = input.cursor + byteLength;
|
|
228
|
+
return observeProcess(process, record, {
|
|
229
|
+
cursor,
|
|
230
|
+
size: cursor,
|
|
231
|
+
eof: !reply.truncated,
|
|
232
|
+
});
|
|
148
233
|
},
|
|
149
234
|
}),
|
|
150
235
|
start: defineAppMethod({
|
|
@@ -166,17 +251,57 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
|
|
|
166
251
|
const computer = context.env.COMPUTER;
|
|
167
252
|
if (!caller.computerId || !context.runs)
|
|
168
253
|
throw new Error("Computer access is not granted");
|
|
169
|
-
|
|
254
|
+
const requestKey = caller.idempotencyKey ?? input.requestId;
|
|
255
|
+
if (!requestKey)
|
|
170
256
|
throw new Error(
|
|
171
|
-
"A host idempotency key is required to start a process",
|
|
257
|
+
"A request id or host idempotency key is required to start a process",
|
|
172
258
|
);
|
|
173
259
|
const { processStart, processes } = computer;
|
|
174
260
|
return context.runs.start(
|
|
175
261
|
input,
|
|
176
262
|
caller.computerId,
|
|
177
|
-
|
|
263
|
+
requestKey,
|
|
178
264
|
caller.actor,
|
|
179
265
|
{ processStart, processes },
|
|
266
|
+
nativeRequestId(caller.idempotencyKey, requestKey),
|
|
267
|
+
);
|
|
268
|
+
},
|
|
269
|
+
}),
|
|
270
|
+
restart: defineAppMethod({
|
|
271
|
+
description:
|
|
272
|
+
"Stop a process this caller started and start its recorded command, directory and port again as a new process linked to it by parentId. Send the same requestId to retry.",
|
|
273
|
+
effect: "write",
|
|
274
|
+
requires: ["computer.execute"],
|
|
275
|
+
pending: true,
|
|
276
|
+
input: processIdInputSchema.extend({
|
|
277
|
+
requestId: shedRequestIdSchema.optional(),
|
|
278
|
+
}),
|
|
279
|
+
output: z.union([
|
|
280
|
+
z.strictObject({
|
|
281
|
+
process: computerProcessSchema,
|
|
282
|
+
logPath: z.string(),
|
|
283
|
+
port: computerPortInputSchema.shape.port.optional(),
|
|
284
|
+
parentId: processIdInputSchema.shape.id,
|
|
285
|
+
}),
|
|
286
|
+
refusal,
|
|
287
|
+
]),
|
|
288
|
+
handler: (input, context: ShedMethodContext, caller) => {
|
|
289
|
+
const computer = context.env.COMPUTER;
|
|
290
|
+
if (!caller.computerId || !context.runs)
|
|
291
|
+
throw new Error("Computer access is not granted");
|
|
292
|
+
const requestKey = caller.idempotencyKey ?? input.requestId;
|
|
293
|
+
if (!requestKey)
|
|
294
|
+
throw new Error(
|
|
295
|
+
"A request id or host idempotency key is required to restart a process",
|
|
296
|
+
);
|
|
297
|
+
const { processStart, processes, processKill } = computer;
|
|
298
|
+
return context.runs.restart(
|
|
299
|
+
input.id,
|
|
300
|
+
caller.computerId,
|
|
301
|
+
requestKey,
|
|
302
|
+
caller.actor,
|
|
303
|
+
{ processStart, processes, processKill },
|
|
304
|
+
nativeRequestId(caller.idempotencyKey, requestKey),
|
|
180
305
|
);
|
|
181
306
|
},
|
|
182
307
|
}),
|
|
@@ -191,11 +316,14 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
|
|
|
191
316
|
throw new Error("Computer access is not granted");
|
|
192
317
|
if (!context.runs?.owns(input.id, caller.computerId, caller.actor))
|
|
193
318
|
return refusal.parse({ error: "not_found" });
|
|
194
|
-
|
|
319
|
+
const reply = z
|
|
195
320
|
.union([processKillOutputSchema, refusal])
|
|
196
321
|
.parse(
|
|
197
322
|
await computerCall(() => context.env.COMPUTER.processKill(input)),
|
|
198
323
|
);
|
|
324
|
+
if ("signalled" in reply && reply.signalled)
|
|
325
|
+
context.runs.recordStop(input.id, caller.computerId, caller.actor);
|
|
326
|
+
return reply;
|
|
199
327
|
},
|
|
200
328
|
}),
|
|
201
329
|
run: defineAppMethod({
|
|
@@ -240,14 +368,18 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
|
|
|
240
368
|
if (!caller.computerId || !context.runs)
|
|
241
369
|
throw new Error("Computer access is not granted");
|
|
242
370
|
const { processStart, processes } = computer;
|
|
243
|
-
|
|
244
|
-
|
|
371
|
+
const requestKey = caller.idempotencyKey ?? input.requestId;
|
|
372
|
+
if (!requestKey)
|
|
373
|
+
throw new Error(
|
|
374
|
+
"A request id or host idempotency key is required to start a run",
|
|
375
|
+
);
|
|
245
376
|
return context.runs.run(
|
|
246
377
|
input,
|
|
247
378
|
caller.computerId,
|
|
248
|
-
|
|
379
|
+
requestKey,
|
|
249
380
|
caller.actor,
|
|
250
381
|
{ processStart, processes },
|
|
382
|
+
nativeRequestId(caller.idempotencyKey, requestKey),
|
|
251
383
|
);
|
|
252
384
|
},
|
|
253
385
|
}),
|
|
@@ -281,12 +413,18 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
|
|
|
281
413
|
input.after.computerId !== caller.computerId
|
|
282
414
|
)
|
|
283
415
|
return refusal.parse({ error: "invalid" });
|
|
284
|
-
const inventory =
|
|
416
|
+
const inventory = inventoryReply.parse(
|
|
285
417
|
await computerCall(() => context.env.COMPUTER.processes({})),
|
|
286
418
|
);
|
|
287
419
|
return "error" in inventory
|
|
288
420
|
? inventory
|
|
289
|
-
: pageProcesses(
|
|
421
|
+
: pageProcesses(
|
|
422
|
+
inventory,
|
|
423
|
+
input,
|
|
424
|
+
caller.computerId,
|
|
425
|
+
context.runs?.ownedRecords(caller.computerId, caller.actor) ??
|
|
426
|
+
new Map(),
|
|
427
|
+
);
|
|
290
428
|
},
|
|
291
429
|
}),
|
|
292
430
|
runCommand: defineAppMethod({
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import {
|
|
2
|
+
runObservationSchema,
|
|
3
|
+
type RunObservation,
|
|
4
|
+
} from "@fungi.computer/agar/run-observation";
|
|
5
|
+
import type { ComputerProcess } from "@fungi.computer/computer-contract";
|
|
6
|
+
|
|
7
|
+
/** What Shed's own process record adds to the Computer's. */
|
|
8
|
+
export type ShedProcessRecord = Readonly<{
|
|
9
|
+
/** The process this one restarted. */
|
|
10
|
+
parentId: string | null;
|
|
11
|
+
/** When Shed signalled this process to stop at its caller's request. */
|
|
12
|
+
stoppedAt: number | null;
|
|
13
|
+
logPath: string;
|
|
14
|
+
}>;
|
|
15
|
+
|
|
16
|
+
type Standing = Pick<RunObservation, "state" | "reason">;
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* The Computer's record decides what happened; Shed's adds only that its caller
|
|
20
|
+
* stopped the process, which is a fact the Computer cannot know. A caller's
|
|
21
|
+
* stop wins over how the process then exited.
|
|
22
|
+
*/
|
|
23
|
+
function standing(
|
|
24
|
+
process: ComputerProcess,
|
|
25
|
+
record: ShedProcessRecord | null,
|
|
26
|
+
): Standing {
|
|
27
|
+
const stopped = (record?.stoppedAt ?? null) !== null;
|
|
28
|
+
if (process.state === "uncertain")
|
|
29
|
+
return { state: "unknown", reason: "computer_unreachable" };
|
|
30
|
+
if (process.state === "running")
|
|
31
|
+
return stopped
|
|
32
|
+
? { state: "running", reason: "stopping" }
|
|
33
|
+
: { state: "running" };
|
|
34
|
+
if (stopped) return { state: "cancelled", reason: "stopped" };
|
|
35
|
+
if (process.endedReason === "idle-sleep")
|
|
36
|
+
return { state: "failed", reason: "computer_slept" };
|
|
37
|
+
if (process.exitCode === null)
|
|
38
|
+
return { state: "unknown", reason: "exit_unobserved" };
|
|
39
|
+
return process.exitCode === 0
|
|
40
|
+
? { state: "completed" }
|
|
41
|
+
: { state: "failed", reason: "nonzero_exit" };
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* A read view of one Computer process as a run. Nothing here is stored: the
|
|
46
|
+
* Computer's inventory and Shed's call record are the sources, and cost stays
|
|
47
|
+
* null because no owner meters a process.
|
|
48
|
+
*/
|
|
49
|
+
export function observeProcess(
|
|
50
|
+
process: ComputerProcess,
|
|
51
|
+
record: ShedProcessRecord | null,
|
|
52
|
+
log: RunObservation["log"],
|
|
53
|
+
): RunObservation {
|
|
54
|
+
const observation: RunObservation = {
|
|
55
|
+
source: "shed.process",
|
|
56
|
+
id: process.id,
|
|
57
|
+
...standing(process, record),
|
|
58
|
+
requestedAt: process.startedAt,
|
|
59
|
+
startedAt: process.startedAt,
|
|
60
|
+
log,
|
|
61
|
+
outputs: record === null ? [] : [{ kind: "log", ref: record.logPath }],
|
|
62
|
+
cost: null,
|
|
63
|
+
};
|
|
64
|
+
if (record?.parentId) observation.parentId = record.parentId;
|
|
65
|
+
if (process.endedAt !== null) observation.endedAt = process.endedAt;
|
|
66
|
+
return runObservationSchema.parse(observation);
|
|
67
|
+
}
|
package/backend/process-page.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import * as z from "zod";
|
|
2
2
|
import { processListOutputSchema } from "@fungi.computer/computer-contract";
|
|
3
|
+
import { runObservationSchema } from "@fungi.computer/agar/run-observation";
|
|
4
|
+
import { observeProcess, type ShedProcessRecord } from "./observation.js";
|
|
3
5
|
|
|
4
6
|
const process = processListOutputSchema.shape.processes.element;
|
|
5
7
|
const processCursorSchema = z.strictObject({
|
|
@@ -11,18 +13,31 @@ export const processPageInputSchema = z.strictObject({
|
|
|
11
13
|
limit: z.number().int().min(1).max(64).default(64),
|
|
12
14
|
after: processCursorSchema.optional(),
|
|
13
15
|
});
|
|
16
|
+
const inventoryProcess = process.extend({ command: z.string().max(16384) });
|
|
17
|
+
/** What the Computer reports, before Shed marks what this caller may control. */
|
|
18
|
+
export const processInventorySchema = processListOutputSchema.extend({
|
|
19
|
+
processes: z.array(inventoryProcess).max(64),
|
|
20
|
+
});
|
|
14
21
|
export const processPageSchema = processListOutputSchema.extend({
|
|
15
22
|
processes: z
|
|
16
|
-
.array(
|
|
23
|
+
.array(
|
|
24
|
+
inventoryProcess.extend({
|
|
25
|
+
/** Whether this caller started the process, so `stop` and `restart` accept it. */
|
|
26
|
+
controllable: z.boolean(),
|
|
27
|
+
/** The same process as a run; read its log through `observe`. */
|
|
28
|
+
run: runObservationSchema,
|
|
29
|
+
}),
|
|
30
|
+
)
|
|
17
31
|
.max(64),
|
|
18
32
|
next: processCursorSchema.optional(),
|
|
19
33
|
});
|
|
20
34
|
|
|
21
35
|
/** Keyset pages preserve the Computer inventory's newest-first ordering. */
|
|
22
36
|
export function pageProcesses(
|
|
23
|
-
inventory: z.output<typeof
|
|
37
|
+
inventory: z.output<typeof processInventorySchema>,
|
|
24
38
|
input: z.output<typeof processPageInputSchema>,
|
|
25
39
|
computerId: string,
|
|
40
|
+
controlled: ReadonlyMap<string, ShedProcessRecord>,
|
|
26
41
|
): z.output<typeof processPageSchema> {
|
|
27
42
|
const after = input.after;
|
|
28
43
|
const remaining =
|
|
@@ -33,7 +48,14 @@ export function pageProcesses(
|
|
|
33
48
|
item.startedAt < after.startedAt ||
|
|
34
49
|
(item.startedAt === after.startedAt && item.id < after.id),
|
|
35
50
|
);
|
|
36
|
-
const processes = remaining.slice(0, input.limit)
|
|
51
|
+
const processes = remaining.slice(0, input.limit).map((item) => {
|
|
52
|
+
const record = controlled.get(item.id) ?? null;
|
|
53
|
+
return {
|
|
54
|
+
...item,
|
|
55
|
+
controllable: record !== null,
|
|
56
|
+
run: observeProcess(item, record, null),
|
|
57
|
+
};
|
|
58
|
+
});
|
|
37
59
|
const last = processes.at(-1);
|
|
38
60
|
return remaining.length > input.limit && last !== undefined
|
|
39
61
|
? {
|