@fungi.computer/shed 0.0.1 → 0.2.0

package/README.md

@@ -78,11 +78,11 @@ Agents call Shed through Oyster's MCP endpoint, or at
 `POST $OYSTER_URL/apps/shed/methods/<name>` with a key; see
 [Git, keys and MCP](https://github.com/fungi-computer/oyster#git-keys-and-mcp).
 
-| Method                                    | What it does                                                                                          |
-| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `runCommand({command, cwd?, timeoutMs?})` | Runs a shell command for up to 45 seconds and returns its exit status and output (64 KiB per stream). |
-| `listProcesses({})`                       | Lists up to 64 processes on the Computer. Starts nothing.                                             |
-| `listPorts({})`                           | Lists up to 64 forwarded ports. Starts nothing.                                                       |
+| Method                                    | What it does                                                                                                                                                                                                                                                                   |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `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`. |
+| `listProcesses({})`                       | Lists up to 64 processes on the Computer. Starts nothing.                                                                                                                                                                                                                      |
+| `listPorts({})`                           | Lists up to 64 forwarded ports. Starts nothing.                                                                                                                                                                                                                                |
 
 Workflows (see [Trellis](https://github.com/fungi-computer/trellis)) use a
 second set for longer work:
@@ -121,3 +121,15 @@ agent tools are in [backend/methods.ts](backend/methods.ts), and
 ## License
 
 MIT. See [LICENSE](LICENSE).
+
+## Local film replay
+
+`TerminalPanel` optionally accepts `onTerminalReady(handle)` after Ghostty and
+its font metrics are ready. The typed `TerminalFilmHandle` exposes `write`,
+`reset` and `resize` with Ghostty's ordinary signatures, plus
+`await handle.paint()` to finish drawing the current buffer to the canvas before
+capturing it. The handle follows theme/width renderer replacements and throws
+after unmount. Production callers omit the callback; terminal sessions and input
+stay owned by Shed. Replay callers should reset, resize, write their frame, then
+await `paint()`; a native write callback alone is not a canvas completion
+signal.

package/backend/methods.ts

@@ -1,3 +1,4 @@
+import { resultRows } from "@fungi.computer/agar/method-presentation";
 import { processesGill } from "./gills.js";
 import {
   processPageInputSchema,
@@ -6,9 +7,10 @@ import {
 } from "./process-page.js";
 import * as z from "zod";
 import { Base64 } from "effect/encoding";
-import { computerPortInputSchema } from "@fungi.computer/computer/operations";
+import { computerPortInputSchema } from "@fungi.computer/computer-contract";
 import {
   runShedCommand,
+  computerCall,
   shedRunCommandInputSchema,
   shedRunInputSchema,
   shedStartInputSchema,
@@ -30,7 +32,7 @@ import {
   computerProcessSchema,
   processIdInputSchema,
   processKillOutputSchema,
-} from "@fungi.computer/computer/operations";
+} from "@fungi.computer/computer-contract";
 const empty = z.strictObject({});
 const command = runCommandInputSchema;
 const refusal = shedComputerRefusalSchema;
@@ -41,19 +43,19 @@ const commandReply = runCommandResultSchema;
 export type ShedMethodContext = Readonly<{
   runs?: ShedRuns;
   env: Readonly<{
-    COMPUTER?: Partial<ShedComputer> &
+    COMPUTER: ShedComputer &
       Readonly<{
-        ports?(input: Record<string, never>): Promise<WhistleJsonValue>;
-        preview?(input: { port: number }): Promise<z.core.util.JSONType>;
-        processKill?(
+        ports(input: Record<string, never>): Promise<WhistleJsonValue>;
+        preview(input: { port: number }): Promise<z.core.util.JSONType>;
+        processKill(
           input: z.output<typeof processIdInputSchema>,
         ): Promise<z.core.util.JSONType>;
-        read?(input: {
+        read(input: {
           path: string;
           byteOffset: number;
           byteLength: number;
         }): Promise<z.core.util.JSONType>;
-        exec?(input: z.output<typeof command>): Promise<WhistleJsonValue>;
+        exec(input: z.output<typeof command>): Promise<WhistleJsonValue>;
       }>;
   }>;
 }>;
@@ -68,6 +70,23 @@ const bytes = z.strictObject({
   encoding: z.literal("base64"),
   truncated: z.boolean(),
 });
+/** The script's command lines, without blanks and comments. */
+const commandLines = (command: string) =>
+  command
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith("#"));
+/**
+ * A script reads by its last command: a script usually opens with setup
+ * (`set -eu`, `cd`) and ends with what it is for, such as a push.
+ */
+const lastCommand = (command: string) =>
+  commandLines(command).at(-1)?.slice(0, 80) ?? "a command";
+const scriptLength = (command: string) => {
+  const lines = commandLines(command).length;
+  return lines > 1 ? [`${String(lines)} commands`] : [];
+};
+
 export const appBackend = defineAppBackend<ShedMethodContext>({
   gills: [processesGill],
   methods: {
@@ -79,7 +98,7 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
       input: computerPortInputSchema,
       output: preview,
       handler: async (input, context: ShedMethodContext, caller) => {
-        if (!caller.computerId || !context.env.COMPUTER?.preview)
+        if (!caller.computerId)
           throw new Error("Computer preview access is not granted");
         // Project the issued URL; preview-row presentation policy stays with the host.
         return z
@@ -102,7 +121,7 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
         z.strictObject({ error: z.enum(["not_found", "ambiguous"]) }),
       ]),
       handler: async (input, context: ShedMethodContext, caller) => {
-        if (!caller.computerId || !context.env.COMPUTER?.read || !context.runs)
+        if (!caller.computerId || !context.runs)
           throw new Error("Computer file access is not granted");
         const log = context.runs.logPath(
           input.run,
@@ -133,7 +152,7 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
       description:
         "Start one process on the pinned Computer and return its process and log path without waiting for exit.",
       effect: "write",
-      requires: ["computer.execute", "computer.writeFile"],
+      requires: ["computer.execute"],
       pending: true,
       input: shedStartInputSchema,
       output: z.union([
@@ -146,29 +165,19 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
       ]),
       handler: (input, context: ShedMethodContext, caller) => {
         const computer = context.env.COMPUTER;
-        if (
-          !caller.computerId ||
-          !computer?.processStart ||
-          !computer.processes ||
-          !context.runs
-        )
+        if (!caller.computerId || !context.runs)
           throw new Error("Computer access is not granted");
         if (!caller.idempotencyKey)
           throw new Error(
             "A host idempotency key is required to start a process",
           );
-        const { processStart, processes, workflowGitPass, write } = computer;
+        const { processStart, processes } = computer;
         return context.runs.start(
           input,
           caller.computerId,
           caller.idempotencyKey,
           caller.actor,
-          {
-            processStart,
-            processes,
-            workflowGitPass,
-            write,
-          },
+          { processStart, processes },
         );
       },
     }),
@@ -179,20 +188,22 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
       input: processIdInputSchema,
       output: z.union([processKillOutputSchema, refusal]),
       handler: async (input, context: ShedMethodContext, caller) => {
-        if (!caller.computerId || !context.env.COMPUTER?.processKill)
+        if (!caller.computerId)
           throw new Error("Computer access is not granted");
         if (!context.runs?.owns(input.id, caller.computerId, caller.actor))
           return refusal.parse({ error: "not_found" });
         return z
           .union([processKillOutputSchema, refusal])
-          .parse(await context.env.COMPUTER.processKill(input));
+          .parse(
+            await computerCall(() => context.env.COMPUTER.processKill(input)),
+          );
       },
     }),
     run: defineAppMethod({
       description:
         "Run one command on the pinned Computer, retaining a log and polling until it exits.",
       effect: "write",
-      requires: ["computer.execute", "computer.writeFile"],
+      requires: ["computer.execute"],
       pending: true,
       input: shedRunInputSchema,
       output: z.union([
@@ -202,16 +213,34 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
         }),
         refusal,
       ]),
+      present: {
+        rows: resultRows,
+        verb: "ran",
+        row: ({ input, output }) =>
+          "error" in output
+            ? {
+                id: "refused",
+                title: "Shed could not run the command",
+                detail: output.error,
+                tone: "error",
+              }
+            : {
+                id: output.logPath,
+                title: `Shed ran ${lastCommand(input.command)}`,
+                detail: [
+                  output.exitCode === 0
+                    ? "Finished"
+                    : `Exited with code ${String(output.exitCode)}`,
+                  ...scriptLength(input.command),
+                ].join(" · "),
+                tone: output.exitCode === 0 ? "settled" : "error",
+              },
+      },
       handler: (input, context: ShedMethodContext, caller) => {
         const computer = context.env.COMPUTER;
-        if (
-          !caller.computerId ||
-          !computer?.processStart ||
-          !computer.processes ||
-          !context.runs
-        )
+        if (!caller.computerId || !context.runs)
           throw new Error("Computer access is not granted");
-        const { processStart, processes, workflowGitPass, write } = computer;
+        const { processStart, processes } = computer;
         if (!caller.idempotencyKey)
           throw new Error("A host idempotency key is required to start a run");
         return context.runs.run(
@@ -219,7 +248,7 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
           caller.computerId,
           caller.idempotencyKey,
           caller.actor,
-          { processStart, processes, workflowGitPass, write },
+          { processStart, processes },
         );
       },
     }),
@@ -232,9 +261,11 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
       input: empty,
       output: portsReply,
       handler: async (input, context, caller) =>
-        caller.computerId === null || !context.env.COMPUTER?.ports
+        caller.computerId === null
           ? refusal.parse({ error: "not_granted" })
-          : portsReply.parse(await context.env.COMPUTER.ports(input)),
+          : portsReply.parse(
+              await computerCall(() => context.env.COMPUTER.ports(input)),
+            ),
     }),
     listProcesses: defineAppMethod({
       description:
@@ -244,7 +275,7 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
       input: processPageInputSchema,
       output: processesReply,
       handler: async (input, context, caller) => {
-        if (caller.computerId === null || !context.env.COMPUTER?.processes)
+        if (caller.computerId === null)
           return refusal.parse({ error: "not_granted" });
         if (
           input.after !== undefined &&
@@ -252,7 +283,7 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
         )
           return refusal.parse({ error: "invalid" });
         const inventory = processesReply.parse(
-          await context.env.COMPUTER.processes({}),
+          await computerCall(() => context.env.COMPUTER.processes({})),
         );
         return "error" in inventory
           ? inventory
@@ -261,17 +292,17 @@ export const appBackend = defineAppBackend<ShedMethodContext>({
     }),
     runCommand: defineAppMethod({
       description:
-        "Execute a shell command on the attached Computer, with an optional absolute cwd and a timeout up to 45 seconds. A Workflow step's admitted gitAccess reaches the command as $FUNGI_GIT_REMOTE with command-local Git credentials. The host mints request identity, owns the per-attachment execution budget and attribution. Each output stream is bounded to the Computer’s 64 KiB byte slice, with up to two extra UTF-8 bytes from a replacement character, and may be truncated.",
+        "Run a shell command on the attached Computer. Use cwd to choose an absolute working directory. The timeout is at most 45 seconds. In a Workflow Git step, use $FUNGI_GIT_REMOTE for the repository. Returns stdout, stderr, exitCode and a truncation flag for each stream, or an error code if the command cannot return output. A nonzero exitCode indicates failure or cancellation. Output may be truncated.",
       effect: "write",
-      requires: ["computer.execute", "computer.writeFile"],
+      requires: ["computer.execute"],
       input: shedRunCommandInputSchema,
       output: commandReply,
       handler: async (input, context, caller) => {
         const computer = context.env.COMPUTER;
-        if (caller.computerId === null || !computer?.exec)
+        if (caller.computerId === null)
           return refusal.parse({ error: "not_granted" });
-        const { exec, workflowGitPass, write } = computer;
-        return runShedCommand(input, { exec, workflowGitPass, write });
+        const { exec } = computer;
+        return runShedCommand(input, { exec });
       },
     }),
   },

package/backend/process-page.ts

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import { processListOutputSchema } from "@fungi.computer/computer/operations";
+import { processListOutputSchema } from "@fungi.computer/computer-contract";
 
 const process = processListOutputSchema.shape.processes.element;
 const processCursorSchema = z.strictObject({