@phreshos/server 0.1.12 → 0.1.14

package/README.md

@@ -149,10 +149,22 @@ 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.
+
+Readiness accepts an optional timeout directly:
+
+```ts
+await service.waitReady(10_000)
+```
+
+Programs may provide one agent-independent operating document. Its availability
+is projected without loading it, and its content is read from the Program:
+
+```ts
+if (program.hasAgent) console.log(await program.agent())
+```
 
 `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

package/dist/domain.d.ts

@@ -1,6 +1,7 @@
 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 Events from "./events.js";
 import { type ProgramStartup } from "./startup.js";
+import { type ClientServiceHandler, type ServerServiceHandler } from "./service.js";
 export interface HandleAddress {
     identity: string;
     reference: string;
@@ -15,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;
@@ -31,6 +31,7 @@ export interface ProgramRecord {
     name: string;
     version: string | null;
     description: string | null;
+    hasAgent: boolean;
     server: EndpointDeclarationRecord | null;
     client: ClientDeclarationRecord | null;
 }
@@ -104,6 +105,8 @@ export interface Endpoint<Events extends object = {}> extends CoreEndpoint<Event
 export interface Server<Events extends object = {}> extends CoreServer<Events> {
     /** Returns the Process that owns this Server. */
     process(): Promise<Process>;
+    /** Returns the Service currently exposed by this Server Endpoint. */
+    service<ServiceEvents extends object = {}>(): Promise<ServerServiceHandler<ServiceEvents> | null>;
 }
 /** Server-visible Client handle. */
 export interface Client<Events extends object = {}> extends CoreClient<Events> {
@@ -111,6 +114,8 @@ export interface Client<Events extends object = {}> extends CoreClient<Events> {
     readonly window: Window;
     /** Returns the Process that owns this Client. */
     process(): Promise<Process>;
+    /** Returns the Service currently exposed by this Client Endpoint. */
+    service<ServiceEvents extends object = {}>(): Promise<ClientServiceHandler<ServiceEvents> | null>;
 }
 /** Server-visible Client-owned Window capability. */
 export type Window = CoreWindow;

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

@@ -1,4 +1,5 @@
-import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ClientServiceHandler, ServerServiceHandler, ServiceKey, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
+import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ServiceKey, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
+import type { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 import { type Client, type Process, type Program, type Server } from "./domain.js";
 /** Resolved production description for a Program's Server. */
 export type ServerDescription = Readonly<{
@@ -6,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. */
@@ -19,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. */
@@ -43,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,6 +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, ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
+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/main.js

@@ -2,5 +2,6 @@ export { host } from "./host.js";
 export { current } from "./current.js";
 export {} from "./channel.js";
 export {} from "./startup.js";
-export { ClientServiceHandler, ServerServiceHandler, ServiceHandler } from "@phreshos/core";
+export { ClientServiceHandler, ServerServiceHandler } from "./service.js";
+export { ServiceHandler } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/service.d.ts

@@ -1,5 +1,13 @@
-import { type ClientServiceHandler, type ServerServiceHandler, type ServiceHandler, type ServiceKey } from "@phreshos/core";
+import { ClientServiceHandler as CoreClientServiceHandler, ServerServiceHandler as CoreServerServiceHandler, type ServiceHandler, type ServiceKey } from "@phreshos/core";
 import type { HandleAddress } from "./domain.js";
+/** Server-SDK handle for a Service provided by a Server Endpoint. */
+export declare class ServerServiceHandler<Events extends object = {}> extends CoreServerServiceHandler<Events> {
+    protected constructor();
+}
+/** Server-SDK handle for a Service provided by a Client Endpoint. */
+export declare class ClientServiceHandler<Events extends object = {}> extends CoreClientServiceHandler<Events> {
+    protected constructor();
+}
 export declare function prepareService<EventsMap extends object = {}>(key: ServiceKey & {
     endpoint: "server";
 }): ServerServiceHandler<EventsMap>;

package/dist/service.js

@@ -5,8 +5,14 @@ import Events from "./events.js";
 import HandleRegistry from "./handle-registry.js";
 import wire from "./wire.js";
 const handles = new HandleRegistry();
-const ServerServiceBase = CoreServerServiceHandler;
-const ClientServiceBase = CoreClientServiceHandler;
+/** Server-SDK handle for a Service provided by a Server Endpoint. */
+export class ServerServiceHandler extends CoreServerServiceHandler {
+    constructor() { super(); }
+}
+/** Server-SDK handle for a Service provided by a Client Endpoint. */
+export class ClientServiceHandler extends CoreClientServiceHandler {
+    constructor() { super(); }
+}
 class ServerChannelHandle extends Events {
     key;
     constructor(key) {
@@ -45,7 +51,7 @@ class ClientChannelHandle extends Events {
         super(...serviceEvents(key, "channel"));
     }
 }
-class ServerHandler extends ServerServiceBase {
+class ServerHandler extends ServerServiceHandler {
     key;
     name;
     channel;
@@ -64,7 +70,7 @@ class ServerHandler extends ServerServiceBase {
         await wire.request(["service-wait-ready", this.key, timeout], timeout);
     }
 }
-class ClientHandler extends ClientServiceBase {
+class ClientHandler extends ClientServiceHandler {
     key;
     name;
     channel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/server",
-  "version": "0.1.12",
+  "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"
   }