@phreshos/server 0.1.13 → 0.1.14

package/README.md

@@ -149,31 +149,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`.

package/dist/domain.d.ts

@@ -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;
 }

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,6 +60,12 @@ 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];
@@ -78,16 +85,14 @@ class ProgramHandle extends ProgramBase {
         await wire.request(["forget", this.address]);
     }
 }
-function declaration(address, endpoint, record) {
+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 +100,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/server",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "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.12",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }