@crow-agent/server 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @crow-agent/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local server that hosts durable Sessions and exposes the Agent Harness over a
+byte transport.
+
+A `Server` instance accepts connections, runs the hello handshake, and then
+routes service calls at two levels: calls aimed at the server itself, and calls
+aimed at one attached Session. Routing stays opaque — the server never decodes
+application payloads. It only checks that the `{ serverId, sessionId,
+attachmentId }` route on each request is live, then forwards the envelope.
+
+## What the host provides
+
+Everything session-shaped is application code. The server asks a `ServerHost`
+for three things:
+
+- `serverServices` — the connection-scoped service endpoint. Its
+  `attachClient()` hands each connection a narrow attachment-management
+  surface (`RoutedServerServiceAttachment`).
+- `resolveSession(sessionId, context)` — map an id to metadata, or throw
+  `SessionNotFoundError` / `SessionAmbiguousError`.
+- `openSession(metadata, context)` — acquire the worker-local Session and wrap
+  it in a `RoutedSessionHandle`. The handle's `attachClient()` returns a
+  presentation-scoped capability whose `invokeService()` forwards an opaque
+  service/member envelope at the chosen Session endpoint.
+
+Application-owned services (`SessionDirectory`, `SessionManagement`) project
+the private session catalog into replicated, presentation-safe state and create,
+remove, attach, and detach Sessions without leaking route ids into business
+results. Subscription snapshots and updates stay scoped to the attachment that
+requested them; attachment changes are published out of band once the router
+installs or clears the live route.
+
+## Attachments
+
+One Session can serve several presentation attachments at once. Repeating
+`attach` from a single connection is idempotent. Each successful attachment
+receives a server-generated `attachmentId` that only travels in routing
+control data. Stale or mismatched routes are rejected. When a connection drops,
+its pending responses fail, but its attachment is released only after admitted
+service calls settle — the host decides when zero presentation demand plus
+quiet worker-local Harness activity allow worker retirement. `server.close()`
+shuts every routed Session handle down, relinquishing worker and Session-writer
+ownership.
+
+## Example
+
+```ts
+import { randomUUID } from "node:crypto";
+import { MemorySessionRepo, type Context } from "@crow-agent/agent-core";
+import {
+  SessionAmbiguousError,
+  SessionNotFoundError,
+  type RoutedServerServiceHost,
+  type RoutedSessionHandle,
+  type ServerHost,
+  type Session,
+} from "@crow-agent/server";
+import { createUnixServer, getUnixSocketPath } from "@crow-agent/server/unix";
+
+const catalog = new MemorySessionRepo();
+
+async function lookupSession(sessionId: string, context: Context) {
+  const candidates = await catalog.list(undefined, context);
+  const match = candidates.filter((entry) => entry.id === sessionId);
+  if (match.length > 1) throw new SessionAmbiguousError();
+  const found = match[0];
+  if (found === undefined) throw new SessionNotFoundError(`Unknown session: ${sessionId}`);
+  return found;
+}
+
+async function launch(
+  serverServices: RoutedServerServiceHost,
+  openRoutedSession: (session: Session) => Promise<RoutedSessionHandle>,
+) {
+  const host: ServerHost = {
+    serverServices,
+    resolveSession: lookupSession,
+    openSession: async (metadata, context) => {
+      const session = await catalog.open(metadata, context);
+      return openRoutedSession(session);
+    },
+  };
+
+  const serverId = randomUUID();
+  const socketPath = getUnixSocketPath(serverId, "/run/user/1000/crow");
+  const server = createUnixServer(host, { serverId, path: socketPath });
+  await server.start();
+  return server;
+}
+```
+
+The launcher picks `serverId` as a logical identity — it is not a socket
+address. `getUnixSocketPath()` derives a filesystem path from a directory you
+choose; prefer a short private runtime directory. A long-lived launcher may
+reuse the same id and path when replacing the server process.
+
+`Server` composes transports through the `ServerListener` interface; peer
+authentication is application policy and is not provided by the Unix transport.
+The Unix submodule offers `createUnixListener()` and `createUnixServer()`.
+Low-level envelope validation, CBOR, and framing come from `@crow-agent/protocol`;
+Chord handles service-control parsing, error codes, snapshots and updates, and
+each subscription's replicated-state encoder.
+
+Server and worker lifecycle live outside the public Crow protocol. The
+replaceable application server turns connection attachments into private
+demand updates; the worker merges generation-tagged demand with authoritative
+Harness activity. The coordinator supplies stable routing and reports generic
+server-generation connection changes.

package/dist/public-api.d.ts

@@ -0,0 +1,5 @@
+export { INTERNAL_SERVER_ERROR_MESSAGE, ServerDrainingError, ServerError, SessionAmbiguousError, SessionNotAttachedError, SessionNotFoundError, WrongServerError, } from "./server-errors.ts";
+export type { ServerListener } from "./server-listener.ts";
+export { Server } from "./session-server.ts";
+export type { MaybePromise, RoutedServerPresentation, RoutedServerServiceAttachment, RoutedServerServiceHost, RoutedSessionAttachment, RoutedSessionHandle, ServerHost, ServerOptions, } from "./server-types.ts";
+//# sourceMappingURL=public-api.d.ts.map

package/dist/public-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api.d.ts","sourceRoot":"","sources":["../src/public-api.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,6BAA6B,EAC7B,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,YAAY,EACX,YAAY,EACZ,wBAAwB,EACxB,6BAA6B,EAC7B,uBAAuB,EACvB,uBAAuB,EACvB,mBAAmB,EACnB,UAAU,EACV,aAAa,GACb,MAAM,mBAAmB,CAAC"}

package/dist/public-api.js

@@ -0,0 +1,3 @@
+export { INTERNAL_SERVER_ERROR_MESSAGE, ServerDrainingError, ServerError, SessionAmbiguousError, SessionNotAttachedError, SessionNotFoundError, WrongServerError, } from "./server-errors.js";
+export { Server } from "./session-server.js";
+//# sourceMappingURL=public-api.js.map

package/dist/public-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api.js","sourceRoot":"","sources":["../src/public-api.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,6BAA6B,EAC7B,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,GAChB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC","sourcesContent":["export {\n\tINTERNAL_SERVER_ERROR_MESSAGE,\n\tServerDrainingError,\n\tServerError,\n\tSessionAmbiguousError,\n\tSessionNotAttachedError,\n\tSessionNotFoundError,\n\tWrongServerError,\n} from \"./server-errors.ts\";\nexport type { ServerListener } from \"./server-listener.ts\";\nexport { Server } from \"./session-server.ts\";\nexport type {\n\tMaybePromise,\n\tRoutedServerPresentation,\n\tRoutedServerServiceAttachment,\n\tRoutedServerServiceHost,\n\tRoutedSessionAttachment,\n\tRoutedSessionHandle,\n\tServerHost,\n\tServerOptions,\n} from \"./server-types.ts\";\n"]}

package/dist/server-connection.d.ts

@@ -0,0 +1,32 @@
+import type { ServiceStateEncoder } from "@crow-agent/chord";
+import type { ClientMessageDecoder, RpcTarget } from "@crow-agent/protocol";
+import type { MaybePromise, RoutedServerServiceAttachment } from "./server-types.ts";
+/** An established byte connection authorized by its transport. */
+export type ByteConnection = {
+    readonly closed: boolean;
+    send(chunk: Uint8Array): Promise<void>;
+    close(finalChunk?: Uint8Array): MaybePromise<void>;
+};
+export type ByteConnectionHandler = {
+    onData(chunk: Uint8Array): void;
+    onClose(): void;
+    onError(error: Error): void;
+};
+export type ByteConnectionAcceptor = (connection: ByteConnection) => ByteConnectionHandler;
+export type ConnectionStage = "awaitingHello" | "handshaking" | "ready" | "closing" | "closed";
+export type ConnectionState = {
+    connection: ByteConnection;
+    decoder: ClientMessageDecoder;
+    serviceStateEncoders: Map<string, ServiceStateEncoder>;
+    stage: ConnectionStage;
+    disconnected: boolean;
+    handshake?: Promise<void>;
+    handshakeTimeout: NodeJS.Timeout;
+    serverServices?: RoutedServerServiceAttachment;
+    activeRequests: Map<string, {
+        controller: AbortController;
+        target: RpcTarget;
+    }>;
+};
+export declare function isTerminalConnection(state: ConnectionState): boolean;
+//# sourceMappingURL=server-connection.d.ts.map

package/dist/server-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-connection.d.ts","sourceRoot":"","sources":["../src/server-connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EACX,oBAAoB,EACpB,SAAS,EACT,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EACX,YAAY,EACZ,6BAA6B,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG;IAC5B,QAAQ,CAAC,MAAM,EACd,OAAO,CAAC;IACT,IAAI,CACH,KAAK,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,KAAK,CACJ,UAAU,CAAC,EAAE,UAAU,GACrB,YAAY,CAAC,IAAI,CAAC,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC,MAAM,CACL,KAAK,EAAE,UAAU,GACf,IAAI,CAAC;IACR,OAAO,IAAI,IAAI,CAAC;IAChB,OAAO,CACN,KAAK,EAAE,KAAK,GACV,IAAI,CAAC;CACR,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,CACpC,UAAU,EAAE,cAAc,KACtB,qBAAqB,CAAC;AAE3B,MAAM,MAAM,eAAe,GACxB,eAAe,GACf,aAAa,GACb,OAAO,GACP,SAAS,GACT,QAAQ,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG;IAC7B,UAAU,EACT,cAAc,CAAC;IAChB,OAAO,EACN,oBAAoB,CAAC;IACtB,oBAAoB,EACnB,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAClC,KAAK,EAAE,eAAe,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EACT,OAAO,CAAC,IAAI,CAAC,CAAC;IACf,gBAAgB,EACf,MAAM,CAAC,OAAO,CAAC;IAChB,cAAc,CAAC,EACd,6BAA6B,CAAC;IAC/B,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE;QAC3B,UAAU,EAAE,eAAe,CAAC;QAC5B,MAAM,EAAE,SAAS,CAAC;KAClB,CAAC,CAAC;CACH,CAAC;AAEF,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,eAAe,GACpB,OAAO,CAGT"}

package/dist/server-connection.js

@@ -0,0 +1,5 @@
+export function isTerminalConnection(state) {
+    const { disconnected, stage } = state;
+    return disconnected || stage === "closing" || stage === "closed";
+}
+//# sourceMappingURL=server-connection.js.map

package/dist/server-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-connection.js","sourceRoot":"","sources":["../src/server-connection.ts"],"names":[],"mappings":"AAiEA,MAAM,UAAU,oBAAoB,CACnC,KAAsB;IAEtB,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IACtC,OAAO,YAAY,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,QAAQ,CAAC;AAClE,CAAC","sourcesContent":["import type { ServiceStateEncoder } from \"@crow-agent/chord\";\nimport type {\n\tClientMessageDecoder,\n\tRpcTarget,\n} from \"@crow-agent/protocol\";\n\nimport type {\n\tMaybePromise,\n\tRoutedServerServiceAttachment,\n} from \"./server-types.ts\";\n\n/** An established byte connection authorized by its transport. */\nexport type ByteConnection = {\n\treadonly closed:\n\t\tboolean;\n\tsend(\n\t\tchunk: Uint8Array,\n\t): Promise<void>;\n\tclose(\n\t\tfinalChunk?: Uint8Array,\n\t): MaybePromise<void>;\n};\n\nexport type ByteConnectionHandler = {\n\tonData(\n\t\tchunk: Uint8Array,\n\t): void;\n\tonClose(): void;\n\tonError(\n\t\terror: Error,\n\t): void;\n};\n\nexport type ByteConnectionAcceptor = (\n\tconnection: ByteConnection,\n) => ByteConnectionHandler;\n\nexport type ConnectionStage =\n\t| \"awaitingHello\"\n\t| \"handshaking\"\n\t| \"ready\"\n\t| \"closing\"\n\t| \"closed\";\n\nexport type ConnectionState = {\n\tconnection:\n\t\tByteConnection;\n\tdecoder:\n\t\tClientMessageDecoder;\n\tserviceStateEncoders:\n\t\tMap<string, ServiceStateEncoder>;\n\tstage: ConnectionStage;\n\tdisconnected: boolean;\n\thandshake?:\n\t\tPromise<void>;\n\thandshakeTimeout:\n\t\tNodeJS.Timeout;\n\tserverServices?:\n\t\tRoutedServerServiceAttachment;\n\tactiveRequests: Map<string, {\n\t\tcontroller: AbortController;\n\t\ttarget: RpcTarget;\n\t}>;\n};\n\nexport function isTerminalConnection(\n\tstate: ConnectionState,\n): boolean {\n\tconst { disconnected, stage } = state;\n\treturn disconnected || stage === \"closing\" || stage === \"closed\";\n}\n"]}

package/dist/server-errors.d.ts

@@ -0,0 +1,31 @@
+import type { RemoteServiceErrorCode } from "@crow-agent/chord";
+type ServerOperationErrorCode = RemoteServiceErrorCode | "wrong_server" | "session_not_found" | "session_ambiguous" | "session_not_attached" | "server_draining";
+export declare const INTERNAL_SERVER_ERROR_MESSAGE = "Internal server error";
+/** A host or lifecycle failure that may safely cross the protocol boundary. */
+export declare class ServerError extends Error {
+    name: string;
+    readonly code: ServerOperationErrorCode;
+    constructor(code: ServerOperationErrorCode, message: string);
+}
+export declare class WrongServerError extends ServerError {
+    name: string;
+    constructor();
+}
+export declare class SessionNotFoundError extends ServerError {
+    name: string;
+    constructor(message?: string);
+}
+export declare class SessionAmbiguousError extends ServerError {
+    name: string;
+    constructor();
+}
+export declare class SessionNotAttachedError extends ServerError {
+    name: string;
+    constructor();
+}
+export declare class ServerDrainingError extends ServerError {
+    name: string;
+    constructor();
+}
+export {};
+//# sourceMappingURL=server-errors.d.ts.map

package/dist/server-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-errors.d.ts","sourceRoot":"","sources":["../src/server-errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,KAAK,wBAAwB,GAAG,sBAAsB,GACnD,cAAc,GACd,mBAAmB,GACnB,mBAAmB,GACnB,sBAAsB,GACtB,iBAAiB,CAAC;AAErB,eAAO,MAAM,6BAA6B,0BAA0B,CAAC;AAErE,+EAA+E;AAC/E,qBAAa,WACZ,SAAQ,KAAK;IACJ,IAAI,SAAiB;IAC9B,QAAQ,CAAC,IAAI,EACZ,wBAAwB,CAAC;IAE1B,YACC,IAAI,EAAE,wBAAwB,EAC9B,OAAO,EAAE,MAAM,EAIf;CACD;AAED,qBAAa,gBACZ,SAAQ,WAAW;IACV,IAAI,SAAsB;IAEnC,cAKC;CACD;AAED,qBAAa,oBACZ,SAAQ,WAAW;IACV,IAAI,SAA0B;IAEvC,YACC,OAAO,SAA0B,EAMjC;CACD;AAED,qBAAa,qBACZ,SAAQ,WAAW;IACV,IAAI,SAA2B;IAExC,cAKC;CACD;AAED,qBAAa,uBACZ,SAAQ,WAAW;IACV,IAAI,SAA6B;IAE1C,cAKC;CACD;AAED,qBAAa,mBACZ,SAAQ,WAAW;IACV,IAAI,SAAyB;IAEtC,cAKC;CACD"}

package/dist/server-errors.js

@@ -0,0 +1,41 @@
+export const INTERNAL_SERVER_ERROR_MESSAGE = "Internal server error";
+/** A host or lifecycle failure that may safely cross the protocol boundary. */
+export class ServerError extends Error {
+    name = "ServerError";
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export class WrongServerError extends ServerError {
+    name = "WrongServerError";
+    constructor() {
+        super("wrong_server", "Request was addressed to another server");
+    }
+}
+export class SessionNotFoundError extends ServerError {
+    name = "SessionNotFoundError";
+    constructor(message = "Session was not found") {
+        super("session_not_found", message);
+    }
+}
+export class SessionAmbiguousError extends ServerError {
+    name = "SessionAmbiguousError";
+    constructor() {
+        super("session_ambiguous", "Session ID matches more than one session");
+    }
+}
+export class SessionNotAttachedError extends ServerError {
+    name = "SessionNotAttachedError";
+    constructor() {
+        super("session_not_attached", "Session is not attached to this client");
+    }
+}
+export class ServerDrainingError extends ServerError {
+    name = "ServerDrainingError";
+    constructor() {
+        super("server_draining", "Server is draining");
+    }
+}
+//# sourceMappingURL=server-errors.js.map

package/dist/server-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-errors.js","sourceRoot":"","sources":["../src/server-errors.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,6BAA6B,GAAG,uBAAuB,CAAC;AAErE,+EAA+E;AAC/E,MAAM,OAAO,WACZ,SAAQ,KAAK;IACJ,IAAI,GAAG,aAAa,CAAC;IACrB,IAAI,CACa;IAE1B,YACC,IAA8B,EAC9B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD;AAED,MAAM,OAAO,gBACZ,SAAQ,WAAW;IACV,IAAI,GAAG,kBAAkB,CAAC;IAEnC;QACC,KAAK,CACJ,cAAc,EACd,yCAAyC,CACzC,CAAC;IACH,CAAC;CACD;AAED,MAAM,OAAO,oBACZ,SAAQ,WAAW;IACV,IAAI,GAAG,sBAAsB,CAAC;IAEvC,YACC,OAAO,GAAG,uBAAuB;QAEjC,KAAK,CACJ,mBAAmB,EACnB,OAAO,CACP,CAAC;IACH,CAAC;CACD;AAED,MAAM,OAAO,qBACZ,SAAQ,WAAW;IACV,IAAI,GAAG,uBAAuB,CAAC;IAExC;QACC,KAAK,CACJ,mBAAmB,EACnB,0CAA0C,CAC1C,CAAC;IACH,CAAC;CACD;AAED,MAAM,OAAO,uBACZ,SAAQ,WAAW;IACV,IAAI,GAAG,yBAAyB,CAAC;IAE1C;QACC,KAAK,CACJ,sBAAsB,EACtB,wCAAwC,CACxC,CAAC;IACH,CAAC;CACD;AAED,MAAM,OAAO,mBACZ,SAAQ,WAAW;IACV,IAAI,GAAG,qBAAqB,CAAC;IAEtC;QACC,KAAK,CACJ,iBAAiB,EACjB,oBAAoB,CACpB,CAAC;IACH,CAAC;CACD","sourcesContent":["import type { RemoteServiceErrorCode } from \"@crow-agent/chord\";\n\ntype ServerOperationErrorCode = RemoteServiceErrorCode\n\t| \"wrong_server\"\n\t| \"session_not_found\"\n\t| \"session_ambiguous\"\n\t| \"session_not_attached\"\n\t| \"server_draining\";\n\nexport const INTERNAL_SERVER_ERROR_MESSAGE = \"Internal server error\";\n\n/** A host or lifecycle failure that may safely cross the protocol boundary. */\nexport class ServerError\n\textends Error {\n\toverride name = \"ServerError\";\n\treadonly code:\n\t\tServerOperationErrorCode;\n\n\tconstructor(\n\t\tcode: ServerOperationErrorCode,\n\t\tmessage: string,\n\t) {\n\t\tsuper(message);\n\t\tthis.code = code;\n\t}\n}\n\nexport class WrongServerError\n\textends ServerError {\n\toverride name = \"WrongServerError\";\n\n\tconstructor() {\n\t\tsuper(\n\t\t\t\"wrong_server\",\n\t\t\t\"Request was addressed to another server\",\n\t\t);\n\t}\n}\n\nexport class SessionNotFoundError\n\textends ServerError {\n\toverride name = \"SessionNotFoundError\";\n\n\tconstructor(\n\t\tmessage = \"Session was not found\",\n\t) {\n\t\tsuper(\n\t\t\t\"session_not_found\",\n\t\t\tmessage,\n\t\t);\n\t}\n}\n\nexport class SessionAmbiguousError\n\textends ServerError {\n\toverride name = \"SessionAmbiguousError\";\n\n\tconstructor() {\n\t\tsuper(\n\t\t\t\"session_ambiguous\",\n\t\t\t\"Session ID matches more than one session\",\n\t\t);\n\t}\n}\n\nexport class SessionNotAttachedError\n\textends ServerError {\n\toverride name = \"SessionNotAttachedError\";\n\n\tconstructor() {\n\t\tsuper(\n\t\t\t\"session_not_attached\",\n\t\t\t\"Session is not attached to this client\",\n\t\t);\n\t}\n}\n\nexport class ServerDrainingError\n\textends ServerError {\n\toverride name = \"ServerDrainingError\";\n\n\tconstructor() {\n\t\tsuper(\n\t\t\t\"server_draining\",\n\t\t\t\"Server is draining\",\n\t\t);\n\t}\n}\n"]}

package/dist/server-listener.d.ts

@@ -0,0 +1,8 @@
+import type { ByteConnectionAcceptor } from "./server-connection.ts";
+/** Provides established byte connections once transport authentication completes. */
+export type ServerListener = {
+    /** Begins listening and hands authorized connections to accept. */
+    start(accept: ByteConnectionAcceptor): Promise<void>;
+    close(): Promise<void>;
+};
+//# sourceMappingURL=server-listener.d.ts.map

package/dist/server-listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-listener.d.ts","sourceRoot":"","sources":["../src/server-listener.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,sBAAsB,EACtB,MAAM,wBAAwB,CAAC;AAEhC,qFAAqF;AACrF,MAAM,MAAM,cAAc,GAAG;IAC5B,mEAAmE;IACnE,KAAK,CACJ,MAAM,EAAE,sBAAsB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB,CAAC"}

package/dist/server-listener.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server-listener.js.map

package/dist/server-listener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-listener.js","sourceRoot":"","sources":["../src/server-listener.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n\tByteConnectionAcceptor,\n} from \"./server-connection.ts\";\n\n/** Provides established byte connections once transport authentication completes. */\nexport type ServerListener = {\n\t/** Begins listening and hands authorized connections to accept. */\n\tstart(\n\t\taccept: ByteConnectionAcceptor,\n\t): Promise<void>;\n\tclose(): Promise<void>;\n};\n"]}

package/dist/server-types.d.ts

@@ -0,0 +1,52 @@
+import type { JsonValue, ServiceCall, ServiceProviderUpdate } from "@crow-agent/chord";
+import type { Context, SessionMetadata } from "@crow-agent/agent-core";
+import type { ServerListener } from "./server-listener.ts";
+export type ServerOptions = {
+    listeners: readonly ServerListener[];
+    /** Long-lived logical identity for this server, set by the launcher or profile. */
+    serverId: string;
+    maxFrameLength?: number;
+    handshakeTimeoutMs?: number;
+    onConnectionCountChanged?: (count: number) => void;
+    onError?: (error: Error) => void;
+};
+export type MaybePromise<T> = T | Promise<T>;
+/** Publishes one service update for a subscription owned by the calling attachment. */
+type ServicePublisher = (subscriptionId: string, update: ServiceProviderUpdate, context: Context) => MaybePromise<void>;
+/** The live capability one presentation connection holds for a hosted Session. */
+export type RoutedSessionAttachment = {
+    /** Forwards one opaque service operation to the attached Session endpoint. */
+    invokeService: (call: ServiceCall, publish: ServicePublisher, context: Context) => Promise<JsonValue | undefined>;
+    release: (context: Context) => MaybePromise<void>;
+};
+/** Routing capabilities a presentation exposes to server service implementations. */
+export type RoutedServerPresentation = {
+    attachSession: (sessionId: string, context: Context) => Promise<void>;
+    detachSession: (context: Context) => Promise<void>;
+    /** Drops routed attachments and handles before durable metadata is deleted. */
+    prepareSessionRemoval: (sessionId: string, context: Context) => Promise<void>;
+};
+/** The server-scoped service endpoint for one connection. */
+export type RoutedServerServiceAttachment = {
+    invokeService: (call: ServiceCall, publish: ServicePublisher, context: Context) => Promise<JsonValue | undefined>;
+    release: (context: Context) => MaybePromise<void>;
+};
+export type RoutedServerServiceHost = {
+    attachClient: (presentation: RoutedServerPresentation, context: Context) => MaybePromise<RoutedServerServiceAttachment>;
+};
+/** Handle that acquires presentation-scoped capabilities for a Session. */
+export type RoutedSessionHandle = {
+    attachClient: (context: Context) => MaybePromise<RoutedSessionAttachment>;
+    /** Settles with an error on unexpected termination, or undefined after a clean close. */
+    readonly terminated?: Promise<Error | undefined>;
+    close: (context: Context) => Promise<void>;
+};
+/** Application hooks for server-wide management and Session routing. */
+export type ServerHost<TMetadata extends SessionMetadata = SessionMetadata> = {
+    readonly serverServices: RoutedServerServiceHost;
+    /** Resolves one durable Session ID, or throws a bounded routing error. */
+    resolveSession: (sessionId: string, context: Context) => Promise<TMetadata>;
+    openSession: (metadata: TMetadata, context: Context) => Promise<RoutedSessionHandle>;
+};
+export {};
+//# sourceMappingURL=server-types.d.ts.map

package/dist/server-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-types.d.ts","sourceRoot":"","sources":["../src/server-types.ts"],"names":[],"mappings":"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"}

package/dist/server-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server-types.js.map

package/dist/server-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-types.js","sourceRoot":"","sources":["../src/server-types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n\tJsonValue,\n\tServiceCall,\n\tServiceProviderUpdate,\n} from \"@crow-agent/chord\";\nimport type {\n\tContext,\n\tSessionMetadata,\n} from \"@crow-agent/agent-core\";\nimport type {\n\tServerListener,\n} from \"./server-listener.ts\";\n\nexport type ServerOptions = {\n\tlisteners:\n\t\treadonly ServerListener[];\n\t/** Long-lived logical identity for this server, set by the launcher or profile. */\n\tserverId: string;\n\tmaxFrameLength?: number;\n\thandshakeTimeoutMs?:\n\t\tnumber;\n\tonConnectionCountChanged?: (\n\t\tcount: number,\n\t) => void;\n\tonError?: (\n\t\terror: Error,\n\t) => void;\n};\n\nexport type MaybePromise<T> =\n\tT | Promise<T>;\n\n/** Publishes one service update for a subscription owned by the calling attachment. */\ntype ServicePublisher = (\n\tsubscriptionId: string,\n\tupdate: ServiceProviderUpdate,\n\tcontext: Context,\n) => MaybePromise<void>;\n\n/** The live capability one presentation connection holds for a hosted Session. */\nexport type RoutedSessionAttachment = {\n\t/** Forwards one opaque service operation to the attached Session endpoint. */\n\tinvokeService: (\n\t\tcall: ServiceCall,\n\t\tpublish: ServicePublisher,\n\t\tcontext: Context,\n\t) => Promise<JsonValue | undefined>;\n\trelease: (\n\t\tcontext: Context,\n\t) => MaybePromise<void>;\n};\n\n/** Routing capabilities a presentation exposes to server service implementations. */\nexport type RoutedServerPresentation = {\n\tattachSession: (\n\t\tsessionId: string,\n\t\tcontext: Context,\n\t) => Promise<void>;\n\tdetachSession: (\n\t\tcontext: Context,\n\t) => Promise<void>;\n\t/** Drops routed attachments and handles before durable metadata is deleted. */\n\tprepareSessionRemoval: (\n\t\tsessionId: string,\n\t\tcontext: Context,\n\t) => Promise<void>;\n};\n\n/** The server-scoped service endpoint for one connection. */\nexport type RoutedServerServiceAttachment = {\n\tinvokeService: (\n\t\tcall: ServiceCall,\n\t\tpublish: ServicePublisher,\n\t\tcontext: Context,\n\t) => Promise<JsonValue | undefined>;\n\trelease: (\n\t\tcontext: Context,\n\t) => MaybePromise<void>;\n};\n\nexport type RoutedServerServiceHost = {\n\tattachClient: (\n\t\tpresentation: RoutedServerPresentation,\n\t\tcontext: Context,\n\t) => MaybePromise<RoutedServerServiceAttachment>;\n};\n\n/** Handle that acquires presentation-scoped capabilities for a Session. */\nexport type RoutedSessionHandle = {\n\tattachClient: (\n\t\tcontext: Context,\n\t) => MaybePromise<RoutedSessionAttachment>;\n\t/** Settles with an error on unexpected termination, or undefined after a clean close. */\n\treadonly terminated?:\n\t\tPromise<Error | undefined>;\n\tclose: (\n\t\tcontext: Context,\n\t) => Promise<void>;\n};\n\n/** Application hooks for server-wide management and Session routing. */\nexport type ServerHost<TMetadata extends SessionMetadata = SessionMetadata> = {\n\treadonly serverServices:\n\t\tRoutedServerServiceHost;\n\t/** Resolves one durable Session ID, or throws a bounded routing error. */\n\tresolveSession: (\n\t\tsessionId: string,\n\t\tcontext: Context,\n\t) => Promise<TMetadata>;\n\topenSession: (\n\t\tmetadata: TMetadata,\n\t\tcontext: Context,\n\t) => Promise<RoutedSessionHandle>;\n};\n"]}

package/dist/session-routing.d.ts

@@ -0,0 +1,42 @@
+import type { JsonValue, ServiceCall, ServiceProviderUpdate } from "@crow-agent/chord";
+import { type Context, type SessionMetadata } from "@crow-agent/agent-core";
+import type { RpcTarget, SessionTarget } from "@crow-agent/protocol";
+import type { ServerHost } from "./server-types.ts";
+type RouterOptions<TMetadata extends SessionMetadata> = {
+    host: ServerHost<TMetadata>;
+    isClosing: () => boolean;
+    reportError: (error: unknown) => void;
+    serverId: string;
+    publishAttachment(client: object, attachment: SessionTarget | undefined, context: Context): Promise<void>;
+};
+type UpdatePublisher = (subscriptionId: string, update: ServiceProviderUpdate, context: Context) => Promise<void>;
+export declare class SessionRouter<TMetadata extends SessionMetadata = SessionMetadata> {
+    #private;
+    constructor(options: RouterOptions<TMetadata>);
+    executeServiceCall(call: ServiceCall, target: RpcTarget, client: object, publish: UpdatePublisher, context: Context): Promise<JsonValue | undefined>;
+    attachClient(client: object, sessionId: string, context: Context): Promise<void>;
+    detachClient(client: object, context: Context): Promise<void>;
+    removeSession(sessionId: string, context: Context): Promise<void>;
+    disconnect(client: object, context: Context): Promise<void>;
+    close(context: Context): Promise<void>;
+    private shutdown;
+    private draining;
+    private clientGone;
+    private enqueueForClient;
+    private attachNow;
+    private leaseLink;
+    private linkStale;
+    private beginServiceCall;
+    private trackCall;
+    private requireLink;
+    private unlink;
+    private teardownLink;
+    private releaseLease;
+    private forgetLink;
+    private openHosted;
+    private createHosted;
+    private closeDrainedHandle;
+    private dropHosted;
+}
+export {};
+//# sourceMappingURL=session-routing.d.ts.map

package/dist/session-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-routing.d.ts","sourceRoot":"","sources":["../src/session-routing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,SAAS,EACT,WAAW,EACX,qBAAqB,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEN,KAAK,OAAO,EACZ,KAAK,eAAe,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAKrE,OAAO,KAAK,EAGX,UAAU,EACV,MAAM,mBAAmB,CAAC;AAoB3B,KAAK,aAAa,CAAC,SAAS,SAAS,eAAe,IAAI;IACvD,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAC5B,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,WAAW,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,aAAa,GAAG,SAAS,EACrC,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC,CAAC;CACjB,CAAC;AAEF,KAAK,eAAe,GAAG,CACtB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,OAAO,KACZ,OAAO,CAAC,IAAI,CAAC,CAAC;AAOnB,qBAAa,aAAa,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe;;IAS7E,YAAY,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,EAE5C;IAEK,kBAAkB,CACvB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAKhC;IAED,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAG/E;IAED,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5D;IAEK,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAetE;IAEK,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhE;IAED,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrC;YAWa,QAAQ;IA4BtB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,gBAAgB;YAeV,SAAS;YAqBT,SAAS;IAcvB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,gBAAgB;IAsBxB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,MAAM;YAKA,YAAY;YAeZ,YAAY;YAKZ,UAAU;YAOV,UAAU;YAcV,YAAY;YAoBZ,kBAAkB;IAYhC,OAAO,CAAC,UAAU;CAUlB"}