@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/computer.d.ts

@@ -0,0 +1,294 @@
+import * as Schema from "effect/Schema";
+import type { CapabilityContract, CapabilityDirectory } from "./capabilities.js";
+import { type AppFileRead, type AppFileWrite } from "./files.js";
+export declare const computerListingSchema: Schema.Struct<{
+    readonly path: Schema.String;
+    readonly entries: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly type: Schema.Literals<readonly ["file", "directory", "symlink"]>;
+        readonly size: Schema.Number;
+        readonly modifiedAt: Schema.Number;
+    }>>;
+    readonly nextOffset: Schema.NullOr<Schema.Number>;
+}>;
+export type ComputerListing = Schema.Schema.Type<typeof computerListingSchema>;
+export declare const computerList: CapabilityContract<{
+    list(input: {
+        path: string;
+        limit: number;
+        offset: number;
+    }): Promise<ComputerListing>;
+}>;
+export declare const computerRuntimeStateSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly state: Schema.Literals<readonly ["running", "sleeping", "starting"]>;
+}>, Schema.Struct<{
+    readonly state: Schema.Literal<"queued">;
+    readonly position: Schema.Number;
+}>]>;
+export type ComputerRuntimeState = Schema.Schema.Type<typeof computerRuntimeStateSchema>;
+export declare const computerInternetAccessSchema: Schema.Struct<{
+    readonly enabled: Schema.Boolean;
+    readonly effective: Schema.Boolean;
+    readonly blockedBy: Schema.NullOr<Schema.Literals<readonly ["team", "global"]>>;
+}>;
+export type ComputerInternetAccess = Schema.Schema.Type<typeof computerInternetAccessSchema>;
+export declare const computerInstrumentSnapshotSchema: Schema.Struct<{
+    readonly computerId: Schema.NonEmptyString;
+    readonly name: Schema.NonEmptyString;
+    readonly runtime: Schema.Union<readonly [Schema.Struct<{
+        readonly state: Schema.Literals<readonly ["running", "sleeping", "starting"]>;
+    }>, Schema.Struct<{
+        readonly state: Schema.Literal<"queued">;
+        readonly position: Schema.Number;
+    }>]>;
+    readonly backends: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.NonEmptyString;
+        readonly kind: Schema.Literals<readonly ["platform-container", "on-box-vm", "local"]>;
+        readonly status: Schema.Literals<readonly ["ready", "queued", "online", "offline"]>;
+        readonly queuePosition: Schema.NullOr<Schema.Number>;
+        readonly hostId: Schema.NullOr<Schema.String>;
+        readonly hostLabel: Schema.NullOr<Schema.String>;
+        readonly folderLabel: Schema.NullOr<Schema.String>;
+        readonly detachable: Schema.Boolean;
+    }>>;
+    readonly internet: Schema.Struct<{
+        readonly enabled: Schema.Boolean;
+        readonly effective: Schema.Boolean;
+        readonly blockedBy: Schema.NullOr<Schema.Literals<readonly ["team", "global"]>>;
+    }>;
+}>;
+export type ComputerInstrumentSnapshot = Schema.Schema.Type<typeof computerInstrumentSnapshotSchema>;
+export declare const computerInstrumentRead: CapabilityContract<{
+    read(): Promise<ComputerInstrumentSnapshot>;
+}>;
+export declare const computerInstrumentControl: CapabilityContract<{
+    start(): Promise<ComputerRuntimeState>;
+    setInternetAccess(enabled: boolean): Promise<ComputerInternetAccess>;
+    detachLocal(backendId: string): Promise<{
+        detached: boolean;
+    }>;
+}>;
+export declare function readComputerInstrument(capabilities: CapabilityDirectory): Promise<ComputerInstrumentSnapshot>;
+export declare function startInstrumentComputer(capabilities: CapabilityDirectory): Promise<ComputerRuntimeState>;
+export declare function setInstrumentInternetAccess(capabilities: CapabilityDirectory, enabled: boolean): Promise<ComputerInternetAccess>;
+export declare function detachInstrumentLocalBackend(capabilities: CapabilityDirectory, backendId: string): Promise<{
+    detached: boolean;
+}>;
+export declare const computerPortsSchema: Schema.Struct<{
+    readonly ports: Schema.$Array<Schema.Struct<{
+        readonly port: Schema.Number;
+        readonly previewUrl: Schema.NonEmptyString;
+        /** Host-selected display mode; this metadata does not grant preview access. */
+        readonly openMode: Schema.Literals<readonly ["inline", "external-only"]>;
+        readonly expiresAt: Schema.Number;
+    }>>;
+}>;
+export type ComputerPorts = Schema.Schema.Type<typeof computerPortsSchema>;
+export declare const computerPortsResultSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly ports: Schema.$Array<Schema.Struct<{
+        readonly port: Schema.Number;
+        readonly previewUrl: Schema.NonEmptyString;
+        /** Host-selected display mode; this metadata does not grant preview access. */
+        readonly openMode: Schema.Literals<readonly ["inline", "external-only"]>;
+        readonly expiresAt: Schema.Number;
+    }>>;
+}>, Schema.Struct<{
+    readonly error: Schema.Literal<"port_previews_not_configured">;
+}>]>;
+export type ComputerPortsResult = Schema.Schema.Type<typeof computerPortsResultSchema>;
+export type ComputerPortExposure = Readonly<{
+    port: number;
+    exposed: boolean;
+}>;
+export type ComputerPortRemoval = Readonly<{
+    port: number;
+    removed: boolean;
+}>;
+export declare const computerPortExposureSchema: Schema.Struct<{
+    readonly port: Schema.Number;
+    readonly exposed: Schema.Boolean;
+}>;
+export declare const computerPortRemovalSchema: Schema.Struct<{
+    readonly port: Schema.Number;
+    readonly removed: Schema.Boolean;
+}>;
+/** The selected Computer's admitted preview URLs and port mutations. */
+export declare const computerPorts: CapabilityContract<{
+    list(): Promise<ComputerPortsResult>;
+    expose(port: number): Promise<ComputerPortExposure>;
+    unexpose(port: number): Promise<ComputerPortRemoval>;
+}>;
+/** Decode exposed ports at the SDK boundary. */
+export declare function listComputerPorts(capabilities: CapabilityDirectory): Promise<ComputerPortsResult>;
+/** Expose one port on the selected Computer under its App admission. */
+export declare function exposeComputerPort(capabilities: CapabilityDirectory, port: number): Promise<ComputerPortExposure>;
+/** Remove one exposed port from the selected Computer. */
+export declare function unexposeComputerPort(capabilities: CapabilityDirectory, port: number): Promise<ComputerPortRemoval>;
+/**
+ * `synced`: the exact observation that recorded this exit also confirmed
+ * computerd's post-command pull landed. `pending`: that observation saw
+ * the pull fail, or gave up waiting for it. `unknown`: this exit was
+ * recorded with no pull evidence at all.
+ */
+export declare const computerProcessSyncSchema: Schema.Literals<readonly ["synced", "pending", "unknown"]>;
+/** A process owned by the selected Computer's durable process inventory. */
+export declare const computerProcessSchema: Schema.Struct<{
+    readonly port: Schema.NullOr<Schema.Number>;
+    readonly id: Schema.NonEmptyString;
+    readonly command: Schema.NonEmptyString;
+    readonly cwd: Schema.NullOr<Schema.String>;
+    readonly startedAt: Schema.Number;
+    readonly state: Schema.Literals<readonly ["running", "exited", "uncertain"]>;
+    readonly exitCode: Schema.NullOr<Schema.Number>;
+    readonly sync: Schema.Literals<readonly ["synced", "pending", "unknown"]>;
+    readonly endedAt: Schema.NullOr<Schema.Number>;
+}>;
+export declare const computerProcessesSchema: Schema.Struct<{
+    readonly processes: Schema.$Array<Schema.Struct<{
+        readonly port: Schema.NullOr<Schema.Number>;
+        readonly id: Schema.NonEmptyString;
+        readonly command: Schema.NonEmptyString;
+        readonly cwd: Schema.NullOr<Schema.String>;
+        readonly startedAt: Schema.Number;
+        readonly state: Schema.Literals<readonly ["running", "exited", "uncertain"]>;
+        readonly exitCode: Schema.NullOr<Schema.Number>;
+        readonly sync: Schema.Literals<readonly ["synced", "pending", "unknown"]>;
+        readonly endedAt: Schema.NullOr<Schema.Number>;
+    }>>;
+}>;
+export declare const computerProcessKillSchema: Schema.Struct<{
+    readonly process: Schema.Struct<{
+        readonly port: Schema.NullOr<Schema.Number>;
+        readonly id: Schema.NonEmptyString;
+        readonly command: Schema.NonEmptyString;
+        readonly cwd: Schema.NullOr<Schema.String>;
+        readonly startedAt: Schema.Number;
+        readonly state: Schema.Literals<readonly ["running", "exited", "uncertain"]>;
+        readonly exitCode: Schema.NullOr<Schema.Number>;
+        readonly sync: Schema.Literals<readonly ["synced", "pending", "unknown"]>;
+        readonly endedAt: Schema.NullOr<Schema.Number>;
+    }>;
+    readonly signalled: Schema.Boolean;
+}>;
+export type ComputerProcess = Schema.Schema.Type<typeof computerProcessSchema>;
+export type ComputerProcessSync = Schema.Schema.Type<typeof computerProcessSyncSchema>;
+export type ComputerProcesses = Schema.Schema.Type<typeof computerProcessesSchema>;
+/** Stable UI request identity is distinct from the host-only native scope. */
+export declare const computerProcessStartSchema: Schema.Struct<{
+    readonly requestId: Schema.NonEmptyString;
+    readonly command: Schema.NonEmptyString;
+    readonly cwd: Schema.optionalKey<Schema.String>;
+    readonly port: Schema.optionalKey<Schema.Number>;
+}>;
+export type ComputerProcessStart = Schema.Schema.Type<typeof computerProcessStartSchema>;
+/** Read the authoritative process inventory from the selected Computer. */
+export declare const computerProcesses: CapabilityContract<{
+    start(input: ComputerProcessStart): Promise<ComputerProcess>;
+    list(): Promise<ComputerProcesses>;
+    kill(id: string): Promise<Schema.Schema.Type<typeof computerProcessKillSchema>>;
+}>;
+/** Decode the Computer owner's process inventory at the App boundary. */
+export declare function listComputerProcesses(capabilities: CapabilityDirectory): Promise<ComputerProcesses>;
+/** Stop one process owned by the selected Computer. */
+export declare function killComputerProcess(capabilities: CapabilityDirectory, id: string): Promise<{
+    readonly process: {
+        readonly port: number | null;
+        readonly id: string;
+        readonly command: string;
+        readonly cwd: string | null;
+        readonly startedAt: number;
+        readonly state: "running" | "exited" | "uncertain";
+        readonly exitCode: number | null;
+        readonly sync: "unknown" | "pending" | "synced";
+        readonly endedAt: number | null;
+    };
+    readonly signalled: boolean;
+}>;
+export declare const computerReadFile: CapabilityContract<{
+    open(input: {
+        path: string;
+    }): Promise<AppFileRead>;
+}>;
+/** The caller receives native file bytes; HTTP details stay in the SDK adapter. */
+export declare function readComputerFile(capabilities: CapabilityDirectory, input: {
+    path: string;
+}, options: {
+    signal?: AbortSignal;
+}): Promise<File>;
+/** Decode listing data at the SDK boundary, before the App consumes it. */
+export declare function listComputerFiles(capabilities: CapabilityDirectory, input: {
+    path: string;
+    limit: number;
+    offset: number;
+}): Promise<ComputerListing>;
+export declare const computerWriteFile: CapabilityContract<{
+    open(input: {
+        path: string;
+    }): Promise<AppFileWrite>;
+    mkdir(input: {
+        path: string;
+    }): Promise<void>;
+    replace(input: ComputerFileReplacementInput): Promise<ComputerFileReplacementOutcome>;
+}>;
+export type ComputerFileReplacementInput = Readonly<{
+    path: string;
+    expectedContent: string;
+    content: string;
+}>;
+declare const computerFileReplacementOutcomeSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"replaced">;
+    readonly path: Schema.NonEmptyString;
+    readonly bytes: Schema.Number;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"conflict">;
+}>]>;
+export type ComputerFileReplacementOutcome = Schema.Schema.Type<typeof computerFileReplacementOutcomeSchema>;
+export declare function replaceComputerFileIfUnchanged(capabilities: CapabilityDirectory, input: ComputerFileReplacementInput, options: {
+    signal?: AbortSignal;
+}): Promise<Readonly<{
+    path: string;
+    bytes: number;
+}>>;
+export type ComputerTerminalSize = Readonly<{
+    cols: number;
+    rows: number;
+}>;
+/** Display facts supplied by the admitted Computer, separate from shell bytes. */
+export declare const computerTerminalInformationSchema: Schema.Struct<{
+    readonly computerName: Schema.NonEmptyString;
+    readonly teamName: Schema.NonEmptyString;
+    readonly modelDoor: Schema.NonEmptyString;
+    readonly uptimeSeconds: Schema.Number;
+    readonly version: Schema.NonEmptyString;
+}>;
+export type ComputerTerminalInformation = Schema.Schema.Type<typeof computerTerminalInformationSchema>;
+/** The host keeps the PTY socket and exposes only its two flow-controlled streams. */
+export type AppComputerTerminal = Disposable & {
+    information(): Promise<ComputerTerminalInformation>;
+    output(): Promise<ReadableStream<Uint8Array>>;
+    input(): Promise<WritableStream<Uint8Array>>;
+    resize(size: ComputerTerminalSize): Promise<void>;
+    close(): Promise<void>;
+};
+export type ComputerTerminal = Readonly<{
+    information: ComputerTerminalInformation;
+    output: ReadableStream<Uint8Array>;
+    input: WritableStream<Uint8Array>;
+    resize(size: ComputerTerminalSize): Promise<void>;
+    close(): Promise<void>;
+}>;
+export declare const computerTerminal: CapabilityContract<{
+    open(size: ComputerTerminalSize): Promise<AppComputerTerminal>;
+}>;
+/** Open one host-owned terminal and bind its lifetime to the mounted App. */
+export declare function openComputerTerminal(capabilities: CapabilityDirectory, size: ComputerTerminalSize, options?: {
+    signal?: AbortSignal;
+}): Promise<ComputerTerminal>;
+/** Native file stream crosses RPC; neither File subclass nor an editable URL crosses. */
+export declare function writeComputerFile(capabilities: CapabilityDirectory, input: {
+    path: string;
+    content: Blob;
+}, options: {
+    signal?: AbortSignal;
+}): Promise<void>;
+export {};

package/dist/computer.js

@@ -0,0 +1,319 @@
+import { defineCapability } from "./capabilities.js";
+import { rpcDataSchema, rpcHandleSchema, rpcMethod, rpcVoid, } from "./internal/rpc-contract.js";
+import * as z from "zod";
+import * as Schema from "effect/Schema";
+import { readAppFile, writeAppFile, } from "./files.js";
+import { reportCatchFailure } from "./failure.js";
+import { AppError } from "./errors.js";
+export const computerListingSchema = Schema.Struct({
+    path: Schema.String,
+    entries: Schema.Array(Schema.Struct({
+        name: Schema.String,
+        type: Schema.Literals(["file", "directory", "symlink"]),
+        size: Schema.Number,
+        modifiedAt: Schema.Number,
+    })),
+    nextOffset: Schema.NullOr(Schema.Number),
+});
+export const computerList = defineCapability("computer.list", 1, rpcHandleSchema({
+    list: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(computerListingSchema)(value)))),
+}));
+export const computerRuntimeStateSchema = Schema.Union([
+    Schema.Struct({
+        state: Schema.Literals(["running", "sleeping", "starting"]),
+    }),
+    Schema.Struct({
+        state: Schema.Literal("queued"),
+        position: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThan(0))),
+    }),
+]);
+export const computerInternetAccessSchema = Schema.Struct({
+    enabled: Schema.Boolean,
+    effective: Schema.Boolean,
+    blockedBy: Schema.NullOr(Schema.Literals(["team", "global"])),
+});
+export const computerInstrumentSnapshotSchema = Schema.Struct({
+    computerId: Schema.NonEmptyString,
+    name: Schema.NonEmptyString,
+    runtime: computerRuntimeStateSchema,
+    backends: Schema.Array(Schema.Struct({
+        id: Schema.NonEmptyString,
+        kind: Schema.Literals(["platform-container", "on-box-vm", "local"]),
+        status: Schema.Literals(["ready", "queued", "online", "offline"]),
+        queuePosition: Schema.NullOr(Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThan(0)))),
+        hostId: Schema.NullOr(Schema.String),
+        hostLabel: Schema.NullOr(Schema.String),
+        folderLabel: Schema.NullOr(Schema.String),
+        detachable: Schema.Boolean,
+    })),
+    internet: computerInternetAccessSchema,
+});
+export const computerInstrumentRead = defineCapability("computer.instrument.read", 1, rpcHandleSchema({
+    read: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(computerInstrumentSnapshotSchema)(value)))),
+}));
+export const computerInstrumentControl = defineCapability("computer.instrument.control", 1, rpcHandleSchema({
+    start: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(computerRuntimeStateSchema)(value)))),
+    setInternetAccess: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(computerInternetAccessSchema)(value)))),
+    detachLocal: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(Schema.Struct({ detached: Schema.Boolean }))(value)))),
+}));
+export async function readComputerInstrument(capabilities) {
+    return Schema.decodeUnknownSync(computerInstrumentSnapshotSchema)(await capabilities.require(computerInstrumentRead).read());
+}
+export async function startInstrumentComputer(capabilities) {
+    return Schema.decodeUnknownSync(computerRuntimeStateSchema)(await capabilities.require(computerInstrumentControl).start());
+}
+export async function setInstrumentInternetAccess(capabilities, enabled) {
+    return Schema.decodeUnknownSync(computerInternetAccessSchema)(await capabilities
+        .require(computerInstrumentControl)
+        .setInternetAccess(enabled));
+}
+export async function detachInstrumentLocalBackend(capabilities, backendId) {
+    return Schema.decodeUnknownSync(Schema.Struct({ detached: Schema.Boolean }))(await capabilities
+        .require(computerInstrumentControl)
+        .detachLocal(backendId));
+}
+export const computerPortsSchema = Schema.Struct({
+    ports: Schema.Array(Schema.Struct({
+        port: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isBetween({ minimum: 1, maximum: 65_535 }))),
+        previewUrl: Schema.NonEmptyString,
+        /** Host-selected display mode; this metadata does not grant preview access. */
+        openMode: Schema.Literals(["inline", "external-only"]),
+        expiresAt: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThan(0))),
+    })).pipe(Schema.check(Schema.isMaxLength(64))),
+});
+export const computerPortsResultSchema = Schema.Union([
+    computerPortsSchema,
+    Schema.Struct({ error: Schema.Literal("port_previews_not_configured") }),
+]);
+export const computerPortExposureSchema = Schema.Struct({
+    port: Schema.Number.annotate({
+        message: "Use a port from 1 to 65535.",
+    }).check(Schema.isInt({ message: "Use a port from 1 to 65535." }), Schema.isBetween({ minimum: 1, maximum: 65_535 }, { message: "Use a port from 1 to 65535." })),
+    exposed: Schema.Boolean,
+});
+export const computerPortRemovalSchema = Schema.Struct({
+    port: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isBetween({ minimum: 1, maximum: 65_535 }))),
+    removed: Schema.Boolean,
+});
+/** The selected Computer's admitted preview URLs and port mutations. */
+export const computerPorts = defineCapability("computer.ports", 2, rpcHandleSchema({
+    list: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(computerPortsResultSchema)(value)))),
+    expose: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(computerPortExposureSchema)(value)))),
+    unexpose: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(computerPortRemovalSchema)(value)))),
+}));
+/** Decode exposed ports at the SDK boundary. */
+export async function listComputerPorts(capabilities) {
+    const result = Schema.decodeUnknownSync(computerPortsResultSchema)(await capabilities.require(computerPorts).list());
+    if ("error" in result)
+        return result;
+    for (const { previewUrl, expiresAt } of result.ports) {
+        const url = new URL(previewUrl);
+        if (url.protocol !== "https:" ||
+            url.username ||
+            url.password ||
+            expiresAt <= Date.now())
+            throw new Error("Computer preview URL is invalid");
+    }
+    return result;
+}
+/** Expose one port on the selected Computer under its App admission. */
+export async function exposeComputerPort(capabilities, port) {
+    return Schema.decodeUnknownSync(computerPortExposureSchema)(await capabilities.require(computerPorts).expose(port));
+}
+/** Remove one exposed port from the selected Computer. */
+export async function unexposeComputerPort(capabilities, port) {
+    return Schema.decodeUnknownSync(computerPortRemovalSchema)(await capabilities.require(computerPorts).unexpose(port));
+}
+/**
+ * `synced`: the exact observation that recorded this exit also confirmed
+ * computerd's post-command pull landed. `pending`: that observation saw
+ * the pull fail, or gave up waiting for it. `unknown`: this exit was
+ * recorded with no pull evidence at all.
+ */
+export const computerProcessSyncSchema = Schema.Literals([
+    "synced",
+    "pending",
+    "unknown",
+]);
+/** A process owned by the selected Computer's durable process inventory. */
+export const computerProcessSchema = Schema.Struct({
+    port: Schema.NullOr(computerPortExposureSchema.fields.port),
+    id: Schema.NonEmptyString,
+    command: Schema.NonEmptyString,
+    cwd: Schema.NullOr(Schema.String),
+    startedAt: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+    state: Schema.Literals(["running", "exited", "uncertain"]),
+    exitCode: Schema.NullOr(Schema.Number.pipe(Schema.check(Schema.isInt()))),
+    sync: computerProcessSyncSchema,
+    endedAt: Schema.NullOr(Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThanOrEqualTo(0)))),
+});
+export const computerProcessesSchema = Schema.Struct({
+    processes: Schema.Array(computerProcessSchema),
+});
+export const computerProcessKillSchema = Schema.Struct({
+    process: computerProcessSchema,
+    signalled: Schema.Boolean,
+});
+/** Stable UI request identity is distinct from the host-only native scope. */
+export const computerProcessStartSchema = Schema.Struct({
+    requestId: Schema.NonEmptyString.pipe(Schema.check(Schema.isMaxLength(256))),
+    command: Schema.NonEmptyString.pipe(Schema.check(Schema.isMaxLength(16 * 1024))),
+    cwd: Schema.optionalKey(Schema.String),
+    port: Schema.optionalKey(computerPortExposureSchema.fields.port),
+});
+/** Read the authoritative process inventory from the selected Computer. */
+export const computerProcesses = defineCapability("computer.processes", 1, rpcHandleSchema({
+    start: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(computerProcessSchema)(value)))),
+    list: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(computerProcessesSchema)(value)))),
+    kill: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(computerProcessKillSchema)(value)))),
+}));
+/** Decode the Computer owner's process inventory at the App boundary. */
+export async function listComputerProcesses(capabilities) {
+    return Schema.decodeUnknownSync(computerProcessesSchema)(await capabilities.require(computerProcesses).list());
+}
+/** Stop one process owned by the selected Computer. */
+export async function killComputerProcess(capabilities, id) {
+    return Schema.decodeUnknownSync(computerProcessKillSchema)(await capabilities.require(computerProcesses).kill(id));
+}
+export const computerReadFile = defineCapability("computer.readFile", 1, rpcHandleSchema({
+    open: rpcMethod(rpcHandleSchema({
+        response: rpcMethod(z.instanceof(Response)),
+        close: rpcVoid,
+    })),
+}));
+/** The caller receives native file bytes; HTTP details stay in the SDK adapter. */
+export async function readComputerFile(capabilities, input, options) {
+    return await readAppFile(await capabilities.require(computerReadFile).open(input), { ...options, name: input.path.split("/").at(-1) ?? "file" });
+}
+/** Decode listing data at the SDK boundary, before the App consumes it. */
+export async function listComputerFiles(capabilities, input) {
+    return Schema.decodeUnknownSync(computerListingSchema)(await capabilities.require(computerList).list(input));
+}
+export const computerWriteFile = defineCapability("computer.writeFile", 3, rpcHandleSchema({
+    open: rpcMethod(rpcHandleSchema({ write: rpcVoid, close: rpcVoid })),
+    mkdir: rpcVoid,
+    replace: rpcMethod(rpcDataSchema(z
+        .unknown()
+        .transform((value) => Schema.decodeUnknownSync(computerFileReplacementOutcomeSchema)(value)))),
+}));
+const computerFileReplacementOutcomeSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("replaced"),
+        path: Schema.NonEmptyString,
+        bytes: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+    }),
+    Schema.Struct({ kind: Schema.Literal("conflict") }),
+]);
+export async function replaceComputerFileIfUnchanged(capabilities, input, options) {
+    options.signal?.throwIfAborted();
+    const result = await capabilities.require(computerWriteFile).replace(input);
+    if (result.kind === "conflict")
+        throw new AppError("Computer file changed since it was opened", {
+            code: "CONFLICT",
+            retryable: false,
+        });
+    return { path: result.path, bytes: result.bytes };
+}
+/** Display facts supplied by the admitted Computer, separate from shell bytes. */
+export const computerTerminalInformationSchema = Schema.Struct({
+    computerName: Schema.NonEmptyString.pipe(Schema.check(Schema.isMaxLength(256))),
+    teamName: Schema.NonEmptyString.pipe(Schema.check(Schema.isMaxLength(256))),
+    modelDoor: Schema.NonEmptyString.pipe(Schema.check(Schema.isMaxLength(256))),
+    uptimeSeconds: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+    version: Schema.NonEmptyString.pipe(Schema.check(Schema.isMaxLength(64))),
+});
+export const computerTerminal = defineCapability("computer.terminal", 2, rpcHandleSchema({
+    open: rpcMethod(rpcHandleSchema({
+        information: rpcMethod(rpcDataSchema(z
+            .unknown()
+            .transform((value) => Schema.decodeUnknownSync(computerTerminalInformationSchema)(value)))),
+        output: rpcMethod(z.instanceof(ReadableStream).transform((stream) => stream.pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                controller.enqueue(z.instanceof(Uint8Array).parse(chunk));
+            },
+        })))),
+        input: rpcMethod(z.instanceof(WritableStream)),
+        resize: rpcVoid,
+        close: rpcVoid,
+    })),
+}));
+/** Open one host-owned terminal and bind its lifetime to the mounted App. */
+export async function openComputerTerminal(capabilities, size, options = {}) {
+    options.signal?.throwIfAborted();
+    const terminal = await capabilities.require(computerTerminal).open(size);
+    let closing;
+    const close = () => {
+        if (closing !== undefined)
+            return closing;
+        options.signal?.removeEventListener("abort", abort);
+        closing = Promise.resolve().then(async () => {
+            try {
+                await terminal.close();
+            }
+            finally {
+                terminal[Symbol.dispose]();
+            }
+        });
+        return closing;
+    };
+    const abort = () => {
+        void close().catch((cause) => {
+            reportCatchFailure("computer.terminal.abort-close", cause);
+        });
+    };
+    options.signal?.addEventListener("abort", abort, { once: true });
+    try {
+        const [output, input, information] = await Promise.all([
+            terminal.output(),
+            terminal.input(),
+            terminal.information(),
+        ]);
+        options.signal?.throwIfAborted();
+        const outputStream = output;
+        const inputStream = input;
+        return {
+            information: Schema.decodeUnknownSync(computerTerminalInformationSchema)(information),
+            output: outputStream,
+            input: inputStream,
+            resize: async (nextSize) => {
+                options.signal?.throwIfAborted();
+                if (closing !== undefined)
+                    throw new Error("Computer terminal is closed");
+                await terminal.resize(nextSize);
+            },
+            close,
+        };
+    }
+    catch (error) {
+        await close().catch((cause) => {
+            reportCatchFailure("computer.terminal.open-cleanup", cause);
+        });
+        throw error;
+    }
+}
+/** Native file stream crosses RPC; neither File subclass nor an editable URL crosses. */
+export async function writeComputerFile(capabilities, input, options) {
+    await writeAppFile(await capabilities.require(computerWriteFile).open({ path: input.path }), input.content, options);
+}

package/dist/connect.d.ts

@@ -0,0 +1,11 @@
+import type { AppRoot } from "./root.js";
+/** Options for connecting this iframe page to its authenticated host. */
+export type ConnectAppOptions = {
+    /** The origin the host handshake message must come from; the connection
+     * is refused when it comes from anywhere else. */
+    readonly expectedHostOrigin: string;
+    /** Cancels a pending connection attempt. */
+    readonly signal?: AbortSignal;
+};
+/** Connects this iframe page to its authenticated host. */
+export declare function connectApp(options: ConnectAppOptions): Promise<AppRoot>;