@phreshos/server 0.1.21 → 0.1.23

package/README.md

@@ -136,6 +136,9 @@ A Program owns its scoped Process capability:
 const processes = await program.process.list()
 const process = await program.process.find("worker")
 const created = await program.process.create({ name: "worker" })
+for await (const event of program.process.run({ name: "temporary" }, { signal })) {
+  // started, output, exited
+}
 const shared = await program.process.findOrCreate({
   name: "shared-server",
   server: true,
@@ -143,6 +146,11 @@ const shared = await program.process.findOrCreate({
 })
 ```
 
+`run()` creates exactly one Process and yields its ordered `started`, `output`,
+and `exited` lifecycle. Aborting its signal, returning early, or losing the
+calling Server exits that Process; `create()` remains independent of the
+caller.
+
 `findOrCreate()` is atomic at the authoritative Core. Concurrent equivalent
 launches converge on one named Process; a different launch for that name
 rejects instead of reconfiguring the existing Process.
@@ -172,7 +180,7 @@ if (program.hasAgent) console.log(await program.agent())
 asset-hosting address. Omitting the size selects `medium`.
 
 Installed Programs may persist one ordinary Process launch for the next system
-startup. This capability exists only in the Server SDK:
+startup through the shared Program interface:
 
 ```ts
 await program.startup.enable({

package/dist/domain.d.ts

@@ -74,11 +74,26 @@ export interface ProgramProcess extends Omit<CoreProgramProcess, "list" | "first
     find(identityOrName: string): Promise<Process | null>;
     /** Creates one Process of this Program. */
     create(launch?: Launch): Promise<Process>;
+    /** Runs one Process for exactly as long as its lifecycle iterator remains open. */
+    run(launch?: Launch, options?: ProgramProcessRunOptions): AsyncGenerator<ProgramProcessRunEvent, void, void>;
     /** Finds the named Process or atomically creates it with the same resolved launch. */
     findOrCreate(launch: Launch & Readonly<{
         name: string;
     }>): Promise<Process>;
 }
+export type ProgramProcessRunEvent = Readonly<{
+    event: "started";
+    process: Process;
+}> | (Readonly<{
+    event: "output";
+}> & ProgramCommandChunk) | Readonly<{
+    event: "exited";
+    process: Process;
+    exit: Exit;
+}>;
+export type ProgramProcessRunOptions = Readonly<{
+    signal?: AbortSignal;
+}>;
 /** Server-visible Process handle. */
 export interface Process<Events extends object = {}> extends CoreProcess<Events> {
     /** Permanent handle to this Process's Server. */

package/dist/domain.js

@@ -134,6 +134,11 @@ class ProgramProcessHandle {
         const answer = await wire.request(["program-process-create", this.address, launch]);
         return process(answer[0]);
     }
+    async *run(launch = {}, options = {}) {
+        for await (const value of wire.stream(["run", this.address, launch], undefined, options.signal)) {
+            yield processRunEvent(value);
+        }
+    }
     async findOrCreate(launch) {
         const answer = await wire.request(["program-process-find-or-create", this.address, launch]);
         return process(answer[0]);
@@ -143,6 +148,21 @@ class ProgramProcessHandle {
         return answer[0];
     }
 }
+function processRunEvent(value) {
+    const event = value;
+    if (event?.event === "started" && event.process) {
+        return Object.freeze({ event: "started", process: process(event.process) });
+    }
+    if (event?.event === "output" && (event.stream === "stdout" || event.stream === "stderr") && typeof event.text === "string") {
+        return Object.freeze({ event: "output", stream: event.stream, text: event.text });
+    }
+    if (event?.event === "exited" && event.process) {
+        const code = typeof event.exit?.code === "number" ? event.exit.code : null;
+        const signal = typeof event.exit?.signal === "string" ? event.exit.signal : null;
+        return Object.freeze({ event: "exited", process: process(event.process), exit: exit(code, signal) });
+    }
+    throw new Error("The System returned an invalid Process run event");
+}
 /** Internal transport address for a Program handle created by this SDK. */
 export function programAddress(value) {
     if (!(value instanceof ProgramHandle))

package/dist/main.d.ts

@@ -1,9 +1,9 @@
-export { system, type System, type SystemProcess, type SystemProgram, type ClientDescription, type SystemProcessEvents, type SystemProcessExit, type SystemProgramEvents, type SystemProgramUninstall, type ProgramDescription, type ServerDescription } from "./system.js";
+export { system } from "./system.js";
 export { current, type Current, type CurrentClient } from "./current.js";
 export { type Answerer, type Channel, type ChannelCapture, type ChannelEvents, type ChannelMessage } from "./channel.js";
 export { type ProgramStartup } from "./startup.js";
 export { type Storage } from "./storage.js";
 export { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 export { ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
-export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess } from "./domain.js";
-export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ClientTraffic, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointTraffic, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, Position, ProgramEvents, ProgramPermission, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, ServerTraffic, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, ThemedValue, WritableAppearance, WindowEvents, WindowGeometry, WindowLayer, WindowState } from "@phreshos/core";
+export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess, type ProgramProcessRunEvent, type ProgramProcessRunOptions } from "./domain.js";
+export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ClientTraffic, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointTraffic, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, Position, ProgramEvents, ProgramPermission, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, ServerTraffic, System, SystemProcess, SystemProcessEntity, SystemProcessEntityEvents, SystemProgram, SystemProgramEntity, SystemProgramProcess, SystemProgramProcessEvents, SystemEndpointEntity, SystemServerEntity, SystemClientEntity, ClientDescription, SystemProcessEvents, SystemProcessExit, SystemProgramEvents, SystemProgramUninstall, ProgramDescription, ServerDescription, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, ThemedValue, WritableAppearance, WindowEvents, WindowGeometry, WindowLayer, WindowState } from "@phreshos/core";

package/dist/system.d.ts

@@ -1,133 +1,3 @@
-import type { Exit, Layer, Position, ServiceKey, Size, Subscribable, SystemUploads, WritableAppearance } from "@phreshos/core";
-import type { ClientServiceHandler, ServerServiceHandler } from "./service.js";
-import { type Client, type Process, type Program, type Server } from "./domain.js";
-import { type Storage } from "./storage.js";
-/** Resolved production description for a Program's Server. */
-type ServerDescriptionBase = Readonly<{
-    /** Absolute directory containing the production Server files. */
-    location: string;
-    /** Whether newly created Processes start this Server by default. */
-    start?: boolean;
-    /** Command used to install the Server's production dependencies. */
-    installCommand?: string;
-}>;
-export type ServerDescription = ServerDescriptionBase & (Readonly<{
-    /** Command used to start an isolated Server process. */
-    startCommand: string;
-    entryFile?: never;
-}> | Readonly<{
-    startCommand?: never;
-    /** JavaScript module loaded as a worker owned by the System. */
-    entryFile: string;
-}>);
-/** Resolved production description for a Program's Client and initial Window. */
-export type ClientDescription = Readonly<{
-    /** Absolute directory containing the production Client files. */
-    location: string;
-    /** Whether newly created Processes start this Client by default. */
-    start?: boolean;
-    /** Default Window title. */
-    title?: string;
-    /** Default Window size. */
-    size?: Size;
-    /** Default Window position. */
-    position?: Position;
-    /** Default Window layer. */
-    layer?: Layer;
-    /** Whether the Window starts minimized. */
-    minimize?: boolean;
-}>;
-type Description = Readonly<{
-    /** Stable identity assigned to the Program. */
-    identity: string;
-    /** Human-readable Program name. */
-    name?: string;
-    /** Declared Program version. */
-    version?: string;
-    /** Short human-readable Program description. */
-    description?: string;
-    /** Absolute validated PNG source used to derive the Program's hosted icon sizes. */
-    icon?: string;
-    /** Absolute Markdown file describing Program-specific operation to agents. */
-    agent?: string;
-    /** Absolute directory used for the Program's persistent storage. */
-    storage: string;
-}>;
-/** Complete runtime description used to create a Program. */
-export type ProgramDescription = Description & (Readonly<{
-    /** Required Server description when no Client is described. */
-    server: ServerDescription;
-    /** Optional Client description. */
-    client?: ClientDescription;
-}> | Readonly<{
-    /** Optional Server description. */
-    server?: ServerDescription;
-    /** Required Client description when no Server is described. */
-    client: ClientDescription;
-}>);
-/** An uninstall reported with the affected Program and removal scope. */
-export type SystemProgramUninstall = Readonly<{
-    /** Program that left the installed state. */
-    program: Program;
-    /** Whether all installed resources, including storage, were removed. */
-    everythingRemoved: boolean;
-}>;
-/** A Process exit reported with the Process that ended. */
-export type SystemProcessExit = Exit & Readonly<{
-    /** Process that ended. */
-    process: Process;
-}>;
-/** Authoritative lifecycle events visible to the Server system. */
-export type SystemProgramEvents = {
-    /** A Program entered the runtime registry. */
-    create: Program;
-    /** A Program left the runtime registry. */
-    forget: Program;
-    /** A Program entered the installed state. */
-    install: Program;
-    /** A Program left the installed state. */
-    uninstall: SystemProgramUninstall;
-};
-/** Authoritative Process lifecycle events visible to the Server system. */
-export type SystemProcessEvents = {
-    /** One Process Endpoint entered a new live incarnation. */
-    endpointStart: Server | Client;
-    /** One Process Endpoint incarnation ended. */
-    endpointStop: Server | Client;
-    /** A Process entered the runtime set. */
-    create: Process;
-    /** A Process left the runtime set. */
-    exit: SystemProcessExit;
-};
-/** Authoritative Program registry available to a Server endpoint. */
-export interface SystemProgram extends Subscribable<SystemProgramEvents, never> {
-    list(onlyInstalled?: boolean): Promise<Program[]>;
-    find(identity: string): Promise<Program | null>;
-    create(source: ProgramDescription | string): Promise<Program>;
-}
-/** Authoritative Process registry available to a Server endpoint. */
-export interface SystemProcess extends Subscribable<SystemProcessEvents, never> {
-    list(): Promise<Process[]>;
-    find(identity: string): Promise<Process | null>;
-}
-/** Authoritative system capabilities available to a Server endpoint. */
-export interface System {
-    /** Native operating-system home storage available to Server endpoints. */
-    readonly storage: Storage;
-    /** Complete unresolved Appearance authority owned by the System. */
-    readonly appearance: WritableAppearance;
-    readonly program: SystemProgram;
-    readonly process: SystemProcess;
-    /** Flat System-owned public uploads capability. */
-    readonly uploads: SystemUploads;
-    /** Returns a stable handle for one exact Service identity. */
-    service<ServiceEvents extends object = {}>(key: ServiceKey & {
-        endpoint: "server";
-    }): ServerServiceHandler<ServiceEvents>;
-    service<ServiceEvents extends object = {}>(key: ServiceKey & {
-        endpoint: "client";
-    }): ClientServiceHandler<ServiceEvents>;
-}
+import type { System } from "@phreshos/core";
 /** Authoritative system capabilities for the currently executing Server. */
 export declare const system: System;
-export {};

package/dist/system.js

@@ -1,5 +1,5 @@
 import Events from "./events.js";
-import { exit, lifecycleEndpoint, process, program } from "./domain.js";
+import { exit, lifecycleEndpoint, process, program, } from "./domain.js";
 import { uploads } from "./uploads.js";
 import ServerAppearance from "./appearance.js";
 import wire from "./wire.js";
@@ -11,6 +11,10 @@ class ServerSystem {
     program = new ServerSystemProgram();
     process = new ServerSystemProcess();
     uploads = uploads;
+    async forceCreateProgram(source) {
+        const answer = await wire.request(["host-program-force-create", source]);
+        return program(answer[0]);
+    }
     service(key) { return prepareService(key); }
 }
 class ServerSystemProgram extends Events {

package/dist/wire.d.ts

@@ -20,7 +20,7 @@ declare class Wire {
     request(values: unknown[], timeout?: number): Promise<unknown>;
     requestWithin(values: unknown[], deadline: Deadline): Promise<unknown>;
     /** Opens one long-running system operation and yields its ordered values. */
-    stream(values: unknown[], timeout?: number): AsyncIterableIterator<unknown>;
+    stream(values: unknown[], timeout?: number, signal?: AbortSignal): AsyncIterableIterator<unknown>;
     /** Resolves this endpoint's Process address only for operations that need it. */
     identity(): Promise<{
         process: string;

package/dist/wire.js

@@ -74,7 +74,7 @@ class Wire {
         });
     }
     /** Opens one long-running system operation and yields its ordered values. */
-    stream(values, timeout = defaultTimeout) {
+    stream(values, timeout = defaultTimeout, signal) {
         const wire = this;
         return (async function* () {
             const question = randomUUID();
@@ -90,6 +90,15 @@ class Wire {
                     state.wake = null;
                 }, timeout)
             };
+            const abort = () => {
+                state.failure = signal?.reason instanceof Error ? signal.reason : new Error("The operation was cancelled");
+                state.wake?.();
+                state.wake = null;
+            };
+            if (signal?.aborted)
+                abort();
+            else
+                signal?.addEventListener("abort", abort, { once: true });
             wire.send("boundary", "expect", question);
             wire.streams.set(question, state);
             wire.send("end-host", "stream", question, ...values);
@@ -107,6 +116,7 @@ class Wire {
                 }
             }
             finally {
+                signal?.removeEventListener("abort", abort);
                 clearTimeout(state.timer);
                 wire.streams.delete(question);
                 wire.send("boundary", "forget", question);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/server",
-    "version": "0.1.21",
+    "version": "0.1.23",
   "description": "The SDK used by a Program's server endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -47,13 +47,13 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.20"
+    "@phreshos/core": "^0.1.22"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-        "@phreshos/core": "^0.1.20",
+        "@phreshos/core": "^0.1.22",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }