@phreshos/server 0.1.13 → 0.1.15

package/README.md

@@ -110,9 +110,12 @@ incarnation is ready. The Server SDK owns one deadline across readiness and the
 answer; absence or incarnation loss rejects without turning a boundary into a
 waiter.
 
-Server Program handles add `install()` and `fork()`. Their filesystem areas
-also expose `path()` and traversal-safe `resolve()`, because filesystem work is
-performed locally in the Server SDK after the Host supplies only the area root.
+Server Program handles add `install()` and `fork()`. `install()` is an async
+generator that opens immediately, yields ordered `stdout` and `stderr` command
+chunks, completes only after installation succeeds, and throws the owning
+System error when installation fails. Their filesystem areas also expose
+`path()` and traversal-safe `resolve()`, because filesystem work is performed
+locally in the Server SDK after the Host supplies only the area root.
 Object descriptions passed to `host.program.create()` therefore require an
 explicit absolute storage root as well as at least one declared Endpoint.
 
@@ -149,31 +152,23 @@ rejects instead of reconfiguring the existing Process.
 `host.service(key)` creates the exact opaque service handle. The
 handler exposes its authored `name`, `enabled()`, `waitReady()`, lifecycle
 subscriptions, and channel; it does not expose its Program or Endpoint as
-separate fields. Services are not a second public registry: inspect Programs
-and their Endpoint declarations. `program.server?.hasService()` identifies a
-declared Service capability, while `await program.server?.docs()` reads its
-installed policy and API documentation before the Endpoint starts.
+separate fields. Services are runtime bindings explicitly enabled by their
+providing Endpoints; creating the providing Process remains the Program's
+responsibility.
 
-Server-side Service handles can create their dedicated providing Process and
-wait for readiness without reproducing Program-specific launch rules:
+Readiness accepts an optional timeout directly:
 
 ```ts
-await serverService.createAndWaitReady()
-await clientService.createAndWaitReady({ minimize: true })
+await service.waitReady(10_000)
 ```
 
-Both readiness operations accept an optional timeout directly and expose an
-immutable timed view. A direct argument on the timed view takes precedence:
+Programs may provide one agent-independent operating document. Its availability
+is projected without loading it, and its content is read from the Program:
 
 ```ts
-await service.waitReady(10_000)
-await service.timeout(5_000).waitReady()
-await service.timeout(5_000).waitReady(10_000)
+if (program.hasAgent) console.log(await program.agent())
 ```
 
-The System owns the single deadline across Process creation, Endpoint startup,
-and Service readiness. The creation capability exists only in the Server SDK.
-
 `program.icon()` requests a guaranteed PNG `Blob` in `small`, `medium`, or
 `large` form without exposing the Program's source path or the system's private
 asset-hosting address. Omitting the size selects `medium`.
@@ -198,3 +193,17 @@ The system validates this through the same launch contract as
 `program.process.create()`. Setting startup does not create a Process immediately.
 `uninstall(false)` preserves the configuration but makes it inactive until the
 Program is installed again; removing everything deletes it.
+
+Installation and uninstallation expose any declared Server command output as
+ordered streams. Consuming the generator waits for the authoritative operation
+to finish:
+
+```ts
+for await (const chunk of program.install()) {
+  (chunk.stream === "stderr" ? process.stderr : process.stdout).write(chunk.text)
+}
+
+for await (const chunk of program.uninstall(true)) {
+  (chunk.stream === "stderr" ? process.stderr : process.stdout).write(chunk.text)
+}
+```

package/dist/domain.d.ts

@@ -1,4 +1,4 @@
-import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture, type AskCapture, type Cleanup, type ClientDeclaration, type Exit, type Launch, type Position, type ProgramPermission, type ProgramProcess as CoreProgramProcess, type ProgramArea as CoreProgramArea, type Size, type TrafficMessage, type Window as CoreWindow, type WindowState } from "@phreshos/core";
+import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture, type AskCapture, type Cleanup, type ClientDeclaration, type Exit, type Launch, type Position, type ProgramCommandChunk, type ProgramPermission, type ProgramProcess as CoreProgramProcess, type ProgramArea as CoreProgramArea, type Size, type TrafficMessage, type Window as CoreWindow, type WindowState } from "@phreshos/core";
 import Events from "./events.js";
 import { type ProgramStartup } from "./startup.js";
 import { type ClientServiceHandler, type ServerServiceHandler } from "./service.js";
@@ -16,7 +16,6 @@ export interface ProgramArea extends CoreProgramArea {
 /** Client-safe Program data transported by the authoritative host. */
 export interface EndpointDeclarationRecord {
     start: boolean;
-    hasService: boolean;
 }
 export interface ClientDeclarationRecord extends EndpointDeclarationRecord {
     title: string | null;
@@ -32,6 +31,7 @@ export interface ProgramRecord {
     name: string;
     version: string | null;
     description: string | null;
+    hasAgent: boolean;
     server: EndpointDeclarationRecord | null;
     client: ClientDeclarationRecord | null;
 }
@@ -63,8 +63,8 @@ export interface Program<Events extends object = {}> extends Omit<CoreProgram<Ev
     readonly permission: ProgramPermission;
     /** Operations and lifecycle observation for this Program's Processes. */
     readonly process: ProgramProcess;
-    /** Installs this Program and returns the same handle. */
-    install(): Promise<this>;
+    /** Installs this Program while yielding its command output in order. */
+    install(): AsyncGenerator<ProgramCommandChunk, void, void>;
     /** Creates a new runtime Program with the supplied stable identity. */
     fork(identity: string): Promise<Program>;
 }

package/dist/domain.js

@@ -43,11 +43,12 @@ class ProgramHandle extends ProgramBase {
     get name() { return this.record.name; }
     get version() { return this.record.version; }
     get description() { return this.record.description; }
+    get hasAgent() { return this.record.hasAgent; }
     get server() {
-        return this.record.server ? declaration(this.address, "server", this.record.server) : null;
+        return this.record.server ? declaration(this.record.server) : null;
     }
     get client() {
-        return this.record.client ? clientDeclaration(this.address, this.record.client) : null;
+        return this.record.client ? clientDeclaration(this.record.client) : null;
     }
     get address() { return { identity: this.identity, reference: this.reference }; }
     update(record) {
@@ -59,35 +60,49 @@ class ProgramHandle extends ProgramBase {
         const answer = await wire.request(["icon", this.address, size]);
         return new Blob([Uint8Array.from(answer[0])], { type: "image/png" });
     }
+    async agent() {
+        if (!this.hasAgent)
+            return null;
+        const answer = await wire.request(["program-agent", this.address]);
+        return answer[0];
+    }
     async installed() {
         const answer = await wire.request(["installed", this.address]);
         return answer[0];
     }
-    async install() {
-        await wire.request(["install", this.address]);
-        return this;
+    async *install() {
+        for await (const value of wire.stream(["install", this.address])) {
+            yield programCommandChunk(value);
+        }
     }
     async fork(identity) {
         const answer = await wire.request(["fork", this.address, identity]);
         return program(answer[0]);
     }
-    async uninstall(everything = false) {
-        await wire.request(["uninstall", this.address, everything]);
+    async *uninstall(everything = false) {
+        for await (const value of wire.stream(["uninstall", this.address, everything])) {
+            yield programCommandChunk(value);
+        }
     }
     async forget() {
         await wire.request(["forget", this.address]);
     }
 }
-function declaration(address, endpoint, record) {
+function programCommandChunk(value) {
+    const chunk = value;
+    if (!chunk || (chunk.stream !== "stdout" && chunk.stream !== "stderr") || typeof chunk.text !== "string") {
+        throw new Error("The host returned an invalid Program command chunk");
+    }
+    return Object.freeze({ stream: chunk.stream, text: chunk.text });
+}
+function declaration(record) {
     return Object.freeze({
-        start: record.start,
-        hasService: () => record.hasService,
-        docs: () => endpointDocs(address, endpoint, record.hasService)
+        start: record.start
     });
 }
-function clientDeclaration(address, record) {
+function clientDeclaration(record) {
     return Object.freeze({
-        ...declaration(address, "client", record),
+        ...declaration(record),
         title: record.title,
         size: record.size,
         position: record.position,
@@ -95,12 +110,6 @@ function clientDeclaration(address, record) {
         minimize: record.minimize
     });
 }
-async function endpointDocs(address, endpoint, declared) {
-    if (!declared)
-        return null;
-    const answer = await wire.request(["endpoint-docs", address, endpoint]);
-    return answer[0];
-}
 class ProgramProcessHandle {
     address;
     constructor(address, reference) {

package/dist/host.d.ts

@@ -7,8 +7,6 @@ export type ServerDescription = Readonly<{
     location: string;
     /** Whether newly created Processes start this Server by default. */
     start?: boolean;
-    /** Absolute Markdown file documenting the Service this Server may expose. */
-    serviceDocs?: string;
     /** Command used to install the Server's production dependencies. */
     installCommand?: string;
     /** Command used to start the Server from its production directory. */
@@ -20,8 +18,6 @@ export type ClientDescription = Readonly<{
     location: string;
     /** Whether newly created Processes start this Client by default. */
     start?: boolean;
-    /** Absolute Markdown file documenting the Service this Client may expose. */
-    serviceDocs?: string;
     /** Default Window title. */
     title?: string;
     /** Default Window size. */
@@ -44,6 +40,8 @@ type Description = Readonly<{
     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;
 }>;

package/dist/main.d.ts

@@ -2,7 +2,7 @@ export { host, type Host, type HostProcess, type HostProgram, type ClientDescrip
 export { current, type Current, type CurrentClient } from "./current.js";
 export { type Answerer, type Channel } from "./channel.js";
 export { type ProgramStartup } from "./startup.js";
-export { ClientServiceHandler, ServerServiceHandler, type TimedClientServiceHandler, type TimedServerServiceHandler } from "./service.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 ProgramArea, type ProgramProcess } from "./domain.js";
 export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ChannelCapture, ChannelEvents, ChannelMessage, 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, ServedFile, ServerTraffic, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Theme, ThemeEvents, ThemeProperties, WallpaperLaunch, FileWallpaper, DesktopWallpaper, WritableTheme, WindowEvents, WindowGeometry, WindowLayer, WindowState } from "@phreshos/core";

package/dist/service.d.ts

@@ -1,31 +1,13 @@
-import { ClientServiceHandler as CoreClientServiceHandler, ServerServiceHandler as CoreServerServiceHandler, type LaunchClient, type ServiceHandler, type ServiceKey, type Timeoutable } from "@phreshos/core";
+import { ClientServiceHandler as CoreClientServiceHandler, ServerServiceHandler as CoreServerServiceHandler, type ServiceHandler, type ServiceKey } from "@phreshos/core";
 import type { HandleAddress } from "./domain.js";
-/** Timed view of a Server Endpoint Service available through the Server SDK. */
-export interface TimedServerServiceHandler {
-    waitReady(timeout?: number): Promise<void>;
-    createAndWaitReady(timeout?: number): Promise<void>;
-}
-/** Timed view of a Client Endpoint Service available through the Server SDK. */
-export interface TimedClientServiceHandler {
-    waitReady(timeout?: number): Promise<void>;
-    createAndWaitReady(client?: LaunchClient, timeout?: number): Promise<void>;
-}
 /** Server-SDK handle for a Service provided by a Server Endpoint. */
 export declare class ServerServiceHandler<Events extends object = {}> extends CoreServerServiceHandler<Events> {
     protected constructor();
 }
-export interface ServerServiceHandler<Events extends object = {}> extends Timeoutable<TimedServerServiceHandler> {
-    createAndWaitReady(timeout?: number): Promise<void>;
-    timeout(milliseconds: number): TimedServerServiceHandler;
-}
 /** Server-SDK handle for a Service provided by a Client Endpoint. */
 export declare class ClientServiceHandler<Events extends object = {}> extends CoreClientServiceHandler<Events> {
     protected constructor();
 }
-export interface ClientServiceHandler<Events extends object = {}> extends Timeoutable<TimedClientServiceHandler> {
-    createAndWaitReady(client?: LaunchClient, timeout?: number): Promise<void>;
-    timeout(milliseconds: number): TimedClientServiceHandler;
-}
 export declare function prepareService<EventsMap extends object = {}>(key: ServiceKey & {
     endpoint: "server";
 }): ServerServiceHandler<EventsMap>;

package/dist/service.js

@@ -69,15 +69,6 @@ class ServerHandler extends ServerServiceHandler {
     async waitReady(timeout) {
         await wire.request(["service-wait-ready", this.key, timeout], timeout);
     }
-    async createAndWaitReady(timeout) {
-        await wire.request(["service-create-and-wait-ready", this.key, undefined, timeout], timeout);
-    }
-    timeout(milliseconds) {
-        return Object.freeze({
-            waitReady: (timeout) => this.waitReady(timeout ?? milliseconds),
-            createAndWaitReady: (timeout) => this.createAndWaitReady(timeout ?? milliseconds)
-        });
-    }
 }
 class ClientHandler extends ClientServiceHandler {
     key;
@@ -97,17 +88,6 @@ class ClientHandler extends ClientServiceHandler {
     async waitReady(timeout) {
         await wire.request(["service-wait-ready", this.key, timeout], timeout);
     }
-    async createAndWaitReady(client, timeout) {
-        await wire.request(["service-create-and-wait-ready", this.key, client, timeout], timeout);
-    }
-    timeout(milliseconds) {
-        return Object.freeze({
-            waitReady: (timeout) => this.waitReady(timeout ?? milliseconds),
-            createAndWaitReady: (client, timeout) => {
-                return this.createAndWaitReady(client, timeout ?? milliseconds);
-            }
-        });
-    }
 }
 export function prepareService(key) {
     if (!isServiceKey(key))

package/dist/wire.d.ts

@@ -7,6 +7,7 @@ type TrafficKind = "publish" | "ask" | "answer";
 /** The server endpoint's sole IPC adapter. */
 declare class Wire {
     private readonly pending;
+    private readonly streams;
     private readonly subscribers;
     private readonly every;
     private readonly answerers;
@@ -17,6 +18,8 @@ declare class Wire {
     send(route: string, ...values: unknown[]): void;
     request(values: unknown[], timeout?: number): Promise<unknown>;
     requestWithin(values: unknown[], deadline: Deadline): Promise<unknown>;
+    /** Opens one long-running host operation and yields its ordered values. */
+    stream(values: unknown[], timeout?: number): AsyncIterableIterator<unknown>;
     /** Resolves this endpoint's Process address only for operations that need it. */
     identity(): Promise<{
         process: string;
@@ -40,6 +43,7 @@ declare class Wire {
     private releaseWaiting;
     private forgetIncoming;
     private settle;
+    private receiveStream;
 }
 declare const _default: Wire;
 export default _default;

package/dist/wire.js

@@ -5,6 +5,7 @@ import { deserialize, serialize } from "./messagepack.js";
 /** The server endpoint's sole IPC adapter. */
 class Wire {
     pending = new Map();
+    streams = new Map();
     subscribers = new Map();
     every = new Map();
     answerers = new Map();
@@ -35,6 +36,10 @@ class Wire {
                 }
                 return;
             }
+            if (values[0] === "stream" && typeof values[1] === "string" && typeof values[2] === "string") {
+                this.receiveStream(values[1], values[2], values[3]);
+                return;
+            }
             if (values[0] === "answer" && typeof values[1] === "string") {
                 this.settle(values[1], values.at(-1));
                 return;
@@ -66,6 +71,46 @@ class Wire {
             this.send("end-host", "wait", question, ...values);
         });
     }
+    /** Opens one long-running host operation and yields its ordered values. */
+    stream(values, timeout = defaultTimeout) {
+        const wire = this;
+        return (async function* () {
+            const question = randomUUID();
+            const state = {
+                queue: [],
+                opened: false,
+                ended: false,
+                failure: null,
+                wake: null,
+                timer: setTimeout(() => {
+                    state.failure = new Error(`Answer timeout ${timeout}ms`);
+                    state.wake?.();
+                    state.wake = null;
+                }, timeout)
+            };
+            wire.send("boundary", "expect", question);
+            wire.streams.set(question, state);
+            wire.send("end-host", "stream", question, ...values);
+            try {
+                while (true) {
+                    if (state.queue.length) {
+                        yield state.queue.shift();
+                        continue;
+                    }
+                    if (state.failure)
+                        throw state.failure;
+                    if (state.ended)
+                        return;
+                    await new Promise(resolve => { state.wake = resolve; });
+                }
+            }
+            finally {
+                clearTimeout(state.timer);
+                wire.streams.delete(question);
+                wire.send("boundary", "forget", question);
+            }
+        })();
+    }
     /** Resolves this endpoint's Process address only for operations that need it. */
     identity() {
         if (!this.identityPromise) {
@@ -255,7 +300,44 @@ class Wire {
         else
             pending.reject(new Error("The boundary returned an invalid outcome"));
     }
+    receiveStream(question, operation, value) {
+        const stream = this.streams.get(question);
+        if (!stream || stream.ended || stream.failure)
+            return;
+        if (operation === "open") {
+            if (stream.opened)
+                return;
+            stream.opened = true;
+            clearTimeout(stream.timer);
+        }
+        else if (!stream.opened) {
+            stream.failure = new Error("The boundary produced a stream value before opening the stream");
+        }
+        else if (operation === "data") {
+            if (stream.queue.length >= maximumStreamQueue) {
+                stream.failure = new Error(`Host stream queue exceeded its capacity of ${maximumStreamQueue}`);
+            }
+            else {
+                stream.queue.push(value);
+            }
+        }
+        else if (operation === "answer") {
+            const outcome = value;
+            if (outcome?.success === true)
+                stream.ended = true;
+            else if (outcome?.success === false && typeof outcome.error === "string")
+                stream.failure = new Error(outcome.error);
+            else
+                stream.failure = new Error("The boundary returned an invalid stream outcome");
+        }
+        else {
+            stream.failure = new Error(`The boundary returned an invalid stream operation "${operation}"`);
+        }
+        stream.wake?.();
+        stream.wake = null;
+    }
 }
+const maximumStreamQueue = 256;
 function failed(error) {
     return {
         success: false,

package/package.json

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