@forgeax/engine-dsh 0.0.0-dev.8d955ade1c79

package/dist/embedded.mjs

@@ -0,0 +1,220 @@
+import { createServer } from 'http';
+import { Context } from '@forgeax/engine-plugin';
+import { randomUUID } from 'crypto';
+import { World, createWorldContext, Update } from '@forgeax/engine-ecs';
+
+// src/embedded.ts
+
+// src/protocol.ts
+var FEDERATION_PROTOCOL_VERSION = 1;
+var FEDERATION_ROUTE_PREFIX = "/forgeax-federation/v1";
+
+// src/index.ts
+var inject = ["webServer"];
+async function apply(ctx, config = {}) {
+  const identity = config.identity ?? `dsh-${randomUUID()}`;
+  const leases = /* @__PURE__ */ new Set();
+  let tick = 0;
+  let state = 0;
+  let embeddedContext;
+  let timer;
+  const disposers = [];
+  let disposed = false;
+  ctx.effect(
+    () => async () => {
+      if (disposed) return;
+      disposed = true;
+      for (const dispose of disposers.reverse()) dispose();
+      leases.clear();
+      if (timer !== void 0) clearInterval(timer);
+      await embeddedContext?.fiber.dispose();
+    },
+    "forgeax-federation: routes and embedded engine"
+  );
+  if (config.engineEndpoint === void 0) {
+    const world = new World();
+    embeddedContext = await createWorldContext(world);
+    world.addSystem(Update, {
+      name: "forgeax-federation-headless-tick",
+      queries: [],
+      fn: () => {
+        tick += 1;
+      }
+    }).unwrap();
+    timer = setInterval(() => {
+      const result = world.update(1 / 30);
+      if (!result.ok) ctx.logger.warn(result.error);
+    }, 1e3 / 30);
+  }
+  const status = () => ({
+    protocol: FEDERATION_PROTOCOL_VERSION,
+    identity,
+    ready: true,
+    realm: "dsh",
+    capabilities: ["lease", "community-probe", "engine-projection"],
+    leases: leases.size,
+    engine: config.engineEndpoint === void 0 ? { binding: "embedded", ready: true, frameId: tick, tick, state } : { binding: "external", endpoint: config.engineEndpoint, ready: true }
+  });
+  disposers.push(
+    ctx.webServer.register({
+      kind: "exact",
+      path: `${FEDERATION_ROUTE_PREFIX}/status`,
+      handler(_request, response) {
+        writeJson(response, 200, status());
+      }
+    }),
+    ctx.webServer.register({
+      kind: "exact",
+      path: `${FEDERATION_ROUTE_PREFIX}/activity`,
+      async handler(request, response) {
+        if (request.method !== "POST") {
+          writeJson(response, 405, { code: "federation-method-not-allowed" });
+          return;
+        }
+        const candidate = ctx.get("forgeaxIntelligenceCapability");
+        if (candidate === void 0 || typeof candidate.run !== "function") {
+          writeJson(response, 404, { code: "federation-intelligence-capability-missing" });
+          return;
+        }
+        const body = await readJsonBody(request);
+        if (typeof body !== "object" || body === null || typeof Reflect.get(body, "input") !== "string" || typeof Reflect.get(body, "sessionId") !== "string") {
+          writeJson(response, 400, { code: "federation-activity-invalid" });
+          return;
+        }
+        writeJson(
+          response,
+          200,
+          await candidate.run(Reflect.get(body, "input"), Reflect.get(body, "sessionId"))
+        );
+      }
+    }),
+    ctx.webServer.register({
+      kind: "exact",
+      path: `${FEDERATION_ROUTE_PREFIX}/lease`,
+      handler(request, response) {
+        if (request.method === "POST") {
+          const leaseId = randomUUID();
+          leases.add(leaseId);
+          writeJson(response, 201, { leaseId });
+          return;
+        }
+        if (request.method === "DELETE") {
+          const leaseId = new URL(request.url ?? "/", "http://localhost").searchParams.get(
+            "leaseId"
+          );
+          if (leaseId !== null) leases.delete(leaseId);
+          writeJson(response, 200, { released: leaseId !== null });
+          return;
+        }
+        writeJson(response, 405, { code: "federation-method-not-allowed" });
+      }
+    }),
+    ctx.webServer.register({
+      kind: "exact",
+      path: `${FEDERATION_ROUTE_PREFIX}/community`,
+      async handler(_request, response) {
+        const candidate = ctx.get("forgeaxFederationCapability");
+        if (candidate === void 0 || typeof candidate.inspect !== "function") {
+          writeJson(response, 404, { code: "federation-community-capability-missing" });
+          return;
+        }
+        writeJson(response, 200, await candidate.inspect());
+      }
+    }),
+    ctx.webServer.register({
+      kind: "exact",
+      path: `${FEDERATION_ROUTE_PREFIX}/engine/control`,
+      handler(request, response) {
+        if (request.method !== "POST" || config.engineEndpoint !== void 0) {
+          writeJson(response, 409, { code: "federation-engine-control-unavailable" });
+          return;
+        }
+        state = state === 0 ? 1 : 0;
+        writeJson(response, 200, status().engine);
+      }
+    })
+  );
+}
+async function readJsonBody(request) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.byteLength;
+    if (size > 65536) throw new Error("federation request exceeds 65536 bytes");
+    chunks.push(buffer);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function writeJson(response, status, value) {
+  response.writeHead(status, {
+    "cache-control": "no-store",
+    "content-type": "application/json; charset=utf-8"
+  });
+  response.end(JSON.stringify(value));
+}
+
+// src/embedded.ts
+var EmbeddedWebServer = class {
+  routes = /* @__PURE__ */ new Set();
+  register(route) {
+    this.routes.add(route);
+    return () => this.routes.delete(route);
+  }
+  match(pathname) {
+    return [...this.routes].find(
+      (route) => route.kind === "exact" ? pathname === route.path : pathname === route.path || pathname.startsWith(`${route.path}/`)
+    );
+  }
+};
+var routes = new EmbeddedWebServer();
+var server = createServer((request, response) => {
+  const pathname = new URL(request.url ?? "/", "http://localhost").pathname;
+  const route = routes.match(pathname);
+  if (route === void 0) {
+    response.writeHead(404);
+    response.end();
+    return;
+  }
+  Promise.resolve(route.handler(request, response)).catch(() => {
+    if (!response.headersSent) response.writeHead(500);
+    response.end();
+  });
+});
+await new Promise((resolve, reject) => {
+  server.once("error", reject);
+  server.listen(0, "127.0.0.1", () => resolve());
+});
+var context = new Context();
+var carrier = {
+  name: "embedded-webserver",
+  provide: "webServer",
+  apply(ctx) {
+    const provide = ctx.provide;
+    provide.call(ctx, "webServer", routes);
+  }
+};
+await context.plugin(carrier);
+await context.plugin({
+  name: "forgeax-federation",
+  inject,
+  apply
+});
+var address = server.address();
+process.stdout.write(`forgeax embedded: http://127.0.0.1:${address.port}
+`);
+var closing = false;
+var close = async () => {
+  if (closing) return;
+  closing = true;
+  await context.fiber.dispose();
+  await new Promise((resolve) => server.close(() => resolve()));
+};
+process.once("SIGTERM", () => {
+  void close().then(() => process.exit(0));
+});
+process.once("SIGINT", () => {
+  void close().then(() => process.exit(0));
+});
+//# sourceMappingURL=embedded.mjs.map
+//# sourceMappingURL=embedded.mjs.map

package/dist/embedded.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocol.ts","../src/index.ts","../src/embedded.ts"],"names":[],"mappings":"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","file":"embedded.mjs","sourcesContent":["export const FEDERATION_PROTOCOL_VERSION = 1 as const;\nexport const FEDERATION_ROUTE_PREFIX = '/forgeax-federation/v1' as const;\n\nexport type FederationBinding = 'attach' | 'external' | 'embedded';\nexport type FederationOwnership = 'lease' | 'instance';\n\nexport interface FederationStatus {\n  readonly protocol: typeof FEDERATION_PROTOCOL_VERSION;\n  readonly identity: string;\n  readonly ready: true;\n  readonly realm: 'dsh';\n  readonly capabilities: readonly string[];\n  readonly leases: number;\n  readonly engine: EngineProjection;\n}\n\nexport type EngineProjection = EngineEndpointProjection | EmbeddedEngineProjection;\n\nexport interface EngineEndpointProjection {\n  readonly binding: 'external';\n  readonly endpoint: string;\n  readonly ready: true;\n}\n\nexport interface EmbeddedEngineProjection {\n  readonly binding: 'embedded';\n  readonly ready: true;\n  readonly frameId: number;\n  readonly tick: number;\n  readonly state: number;\n}\n\nexport interface FederationLease {\n  readonly leaseId: string;\n}\n\nexport interface FederationCommunityCapability {\n  readonly id: string;\n  readonly value: string;\n}\n\nexport interface FederationActivityResult {\n  readonly output: string;\n}\n\nexport interface EnginePreviewStatus {\n  readonly protocol: typeof FEDERATION_PROTOCOL_VERSION;\n  readonly kind: 'forgeax-engine-status';\n  readonly binding: 'external';\n  readonly ready: true;\n  readonly frameId: number;\n  readonly tick: number;\n  readonly state: number;\n}\n\nexport interface EnginePreviewPoll {\n  readonly protocol: typeof FEDERATION_PROTOCOL_VERSION;\n  readonly kind: 'forgeax-engine-poll';\n}\n\nexport interface EnginePreviewControl {\n  readonly protocol: typeof FEDERATION_PROTOCOL_VERSION;\n  readonly kind: 'forgeax-engine-control';\n  readonly action: 'toggle';\n}\n\nexport type EnginePreviewRequest = EnginePreviewPoll | EnginePreviewControl;\n\nexport function isEnginePreviewRequest(value: unknown): value is EnginePreviewRequest {\n  if (typeof value !== 'object' || value === null) return false;\n  const record = value as Record<string, unknown>;\n  if (record.protocol !== FEDERATION_PROTOCOL_VERSION) return false;\n  if (record.kind === 'forgeax-engine-poll') return true;\n  return record.kind === 'forgeax-engine-control' && record.action === 'toggle';\n}\n\nexport function isEnginePreviewStatus(value: unknown): value is EnginePreviewStatus {\n  if (typeof value !== 'object' || value === null) return false;\n  const record = value as Record<string, unknown>;\n  return (\n    record.protocol === FEDERATION_PROTOCOL_VERSION &&\n    record.kind === 'forgeax-engine-status' &&\n    record.binding === 'external' &&\n    record.ready === true &&\n    typeof record.frameId === 'number' &&\n    typeof record.tick === 'number' &&\n    typeof record.state === 'number'\n  );\n}\n\nexport function isFederationStatus(value: unknown): value is FederationStatus {\n  if (typeof value !== 'object' || value === null) return false;\n  const record = value as Record<string, unknown>;\n  return (\n    record.protocol === FEDERATION_PROTOCOL_VERSION &&\n    record.realm === 'dsh' &&\n    record.ready === true &&\n    typeof record.identity === 'string' &&\n    Array.isArray(record.capabilities) &&\n    record.capabilities.every((capability) => typeof capability === 'string') &&\n    Number.isInteger(record.leases) &&\n    (record.leases as number) >= 0 &&\n    isEngineProjection(record.engine)\n  );\n}\n\nfunction isEngineProjection(value: unknown): value is EngineProjection {\n  if (typeof value !== 'object' || value === null) return false;\n  const record = value as Record<string, unknown>;\n  if (record.ready !== true) return false;\n  if (record.binding === 'external') return typeof record.endpoint === 'string';\n  return (\n    record.binding === 'embedded' &&\n    typeof record.frameId === 'number' &&\n    typeof record.tick === 'number' &&\n    typeof record.state === 'number'\n  );\n}\n","import { randomUUID } from 'node:crypto';\nimport type { IncomingMessage, ServerResponse } from 'node:http';\n\nimport { createWorldContext, Update, World } from '@forgeax/engine-ecs';\nimport type { Context } from '@forgeax/engine-plugin';\n\nimport {\n  FEDERATION_PROTOCOL_VERSION,\n  FEDERATION_ROUTE_PREFIX,\n  type FederationActivityResult,\n  type FederationCommunityCapability,\n  type FederationStatus,\n} from './protocol';\n\ninterface WebRoute {\n  readonly kind: 'exact' | 'prefix';\n  readonly path: string;\n  readonly handler: (request: IncomingMessage, response: ServerResponse) => void | Promise<void>;\n}\n\ninterface WebServerService {\n  register(route: WebRoute): () => void;\n}\n\ninterface DshHostContext {\n  readonly webServer: WebServerService;\n  readonly logger: { warn(error: unknown): void };\n  effect(callback: () => void | (() => void | Promise<void>), label?: string): void;\n  get(name: string): unknown;\n}\n\ninterface CommunityProbeService {\n  inspect(): FederationCommunityCapability | Promise<FederationCommunityCapability>;\n}\n\ninterface IntelligenceCapabilityService {\n  run(\n    input: string,\n    sessionId: string,\n  ): FederationActivityResult | Promise<FederationActivityResult>;\n}\n\nexport interface Config {\n  readonly engineEndpoint?: string;\n  readonly identity?: string;\n}\n\nexport const inject = ['webServer'];\n\n/** DSH-native Host half. DSH's Loader mounts this ordinary plugin from the package patch. */\nexport async function apply(ctx: DshHostContext, config: Config = {}): Promise<void> {\n  const identity = config.identity ?? `dsh-${randomUUID()}`;\n  const leases = new Set<string>();\n  let tick = 0;\n  let state = 0;\n  let embeddedContext: Context | undefined;\n  let timer: ReturnType<typeof setInterval> | undefined;\n  const disposers: Array<() => void> = [];\n  let disposed = false;\n\n  ctx.effect(\n    () => async () => {\n      if (disposed) return;\n      disposed = true;\n      for (const dispose of disposers.reverse()) dispose();\n      leases.clear();\n      if (timer !== undefined) clearInterval(timer);\n      await embeddedContext?.fiber.dispose();\n    },\n    'forgeax-federation: routes and embedded engine',\n  );\n\n  if (config.engineEndpoint === undefined) {\n    const world = new World();\n    embeddedContext = await createWorldContext(world);\n    world\n      .addSystem(Update, {\n        name: 'forgeax-federation-headless-tick',\n        queries: [],\n        fn: () => {\n          tick += 1;\n        },\n      })\n      .unwrap();\n    timer = setInterval(() => {\n      const result = world.update(1 / 30);\n      if (!result.ok) ctx.logger.warn(result.error);\n    }, 1000 / 30);\n  }\n\n  const status = (): FederationStatus => ({\n    protocol: FEDERATION_PROTOCOL_VERSION,\n    identity,\n    ready: true,\n    realm: 'dsh',\n    capabilities: ['lease', 'community-probe', 'engine-projection'],\n    leases: leases.size,\n    engine:\n      config.engineEndpoint === undefined\n        ? { binding: 'embedded', ready: true, frameId: tick, tick, state }\n        : { binding: 'external', endpoint: config.engineEndpoint, ready: true },\n  });\n\n  disposers.push(\n    ctx.webServer.register({\n      kind: 'exact',\n      path: `${FEDERATION_ROUTE_PREFIX}/status`,\n      handler(_request, response) {\n        writeJson(response, 200, status());\n      },\n    }),\n    ctx.webServer.register({\n      kind: 'exact',\n      path: `${FEDERATION_ROUTE_PREFIX}/activity`,\n      async handler(request, response) {\n        if (request.method !== 'POST') {\n          writeJson(response, 405, { code: 'federation-method-not-allowed' });\n          return;\n        }\n        const candidate = ctx.get('forgeaxIntelligenceCapability') as\n          | IntelligenceCapabilityService\n          | undefined;\n        if (candidate === undefined || typeof candidate.run !== 'function') {\n          writeJson(response, 404, { code: 'federation-intelligence-capability-missing' });\n          return;\n        }\n        const body = await readJsonBody(request);\n        if (\n          typeof body !== 'object' ||\n          body === null ||\n          typeof Reflect.get(body, 'input') !== 'string' ||\n          typeof Reflect.get(body, 'sessionId') !== 'string'\n        ) {\n          writeJson(response, 400, { code: 'federation-activity-invalid' });\n          return;\n        }\n        writeJson(\n          response,\n          200,\n          await candidate.run(Reflect.get(body, 'input'), Reflect.get(body, 'sessionId')),\n        );\n      },\n    }),\n    ctx.webServer.register({\n      kind: 'exact',\n      path: `${FEDERATION_ROUTE_PREFIX}/lease`,\n      handler(request, response) {\n        if (request.method === 'POST') {\n          const leaseId = randomUUID();\n          leases.add(leaseId);\n          writeJson(response, 201, { leaseId });\n          return;\n        }\n        if (request.method === 'DELETE') {\n          const leaseId = new URL(request.url ?? '/', 'http://localhost').searchParams.get(\n            'leaseId',\n          );\n          if (leaseId !== null) leases.delete(leaseId);\n          writeJson(response, 200, { released: leaseId !== null });\n          return;\n        }\n        writeJson(response, 405, { code: 'federation-method-not-allowed' });\n      },\n    }),\n    ctx.webServer.register({\n      kind: 'exact',\n      path: `${FEDERATION_ROUTE_PREFIX}/community`,\n      async handler(_request, response) {\n        const candidate = ctx.get('forgeaxFederationCapability') as\n          | CommunityProbeService\n          | undefined;\n        if (candidate === undefined || typeof candidate.inspect !== 'function') {\n          writeJson(response, 404, { code: 'federation-community-capability-missing' });\n          return;\n        }\n        writeJson(response, 200, await candidate.inspect());\n      },\n    }),\n    ctx.webServer.register({\n      kind: 'exact',\n      path: `${FEDERATION_ROUTE_PREFIX}/engine/control`,\n      handler(request, response) {\n        if (request.method !== 'POST' || config.engineEndpoint !== undefined) {\n          writeJson(response, 409, { code: 'federation-engine-control-unavailable' });\n          return;\n        }\n        state = state === 0 ? 1 : 0;\n        writeJson(response, 200, status().engine);\n      },\n    }),\n  );\n}\n\nasync function readJsonBody(request: IncomingMessage): Promise<unknown> {\n  const chunks: Buffer[] = [];\n  let size = 0;\n  for await (const chunk of request) {\n    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);\n    size += buffer.byteLength;\n    if (size > 65_536) throw new Error('federation request exceeds 65536 bytes');\n    chunks.push(buffer);\n  }\n  return JSON.parse(Buffer.concat(chunks).toString('utf8')) as unknown;\n}\n\nfunction writeJson(response: ServerResponse, status: number, value: unknown): void {\n  response.writeHead(status, {\n    'cache-control': 'no-store',\n    'content-type': 'application/json; charset=utf-8',\n  });\n  response.end(JSON.stringify(value));\n}\n","import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';\nimport type { AddressInfo } from 'node:net';\n\nimport { Context, type Plugin } from '@forgeax/engine-plugin';\n\nimport { apply as federationApply, inject as federationInject } from './index';\n\ninterface Route {\n  readonly kind: 'exact' | 'prefix';\n  readonly path: string;\n  readonly handler: (request: IncomingMessage, response: ServerResponse) => void | Promise<void>;\n}\n\nclass EmbeddedWebServer {\n  private readonly routes = new Set<Route>();\n\n  register(route: Route): () => void {\n    this.routes.add(route);\n    return () => this.routes.delete(route);\n  }\n\n  match(pathname: string): Route | undefined {\n    return [...this.routes].find((route) =>\n      route.kind === 'exact'\n        ? pathname === route.path\n        : pathname === route.path || pathname.startsWith(`${route.path}/`),\n    );\n  }\n}\n\nconst routes = new EmbeddedWebServer();\nconst server = createServer((request, response) => {\n  const pathname = new URL(request.url ?? '/', 'http://localhost').pathname;\n  const route = routes.match(pathname);\n  if (route === undefined) {\n    response.writeHead(404);\n    response.end();\n    return;\n  }\n  Promise.resolve(route.handler(request, response)).catch(() => {\n    if (!response.headersSent) response.writeHead(500);\n    response.end();\n  });\n});\n\nawait new Promise<void>((resolve, reject) => {\n  server.once('error', reject);\n  server.listen(0, '127.0.0.1', () => resolve());\n});\n\nconst context = new Context();\nconst carrier: Plugin = {\n  name: 'embedded-webserver',\n  provide: 'webServer',\n  apply(ctx) {\n    const provide = ctx.provide as unknown as (name: string, value: unknown) => void;\n    provide.call(ctx, 'webServer', routes);\n  },\n};\nawait context.plugin(carrier);\nawait context.plugin({\n  name: 'forgeax-federation',\n  inject: federationInject,\n  apply: federationApply as unknown as Plugin['apply'],\n});\n\nconst address = server.address() as AddressInfo;\nprocess.stdout.write(`forgeax embedded: http://127.0.0.1:${address.port}\\n`);\n\nlet closing = false;\nconst close = async (): Promise<void> => {\n  if (closing) return;\n  closing = true;\n  await context.fiber.dispose();\n  await new Promise<void>((resolve) => server.close(() => resolve()));\n};\n\nprocess.once('SIGTERM', () => {\n  void close().then(() => process.exit(0));\n});\nprocess.once('SIGINT', () => {\n  void close().then(() => process.exit(0));\n});\n"]}

package/dist/engine-host.d.ts

@@ -0,0 +1,43 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+import { type Result } from '@forgeax/engine-types';
+import { type FederationActivityResult, type FederationBinding, type FederationCommunityCapability, type FederationOwnership, type FederationStatus } from './protocol';
+declare module '@forgeax/engine-plugin' {
+    interface EngineContextServices {
+        dshRealm: DshRealmConnection;
+    }
+}
+export type DshRealmErrorCode = 'dsh-target-unavailable' | 'dsh-target-incompatible' | 'dsh-launch-failed' | 'dsh-handshake-timeout' | 'dsh-lease-failed' | 'dsh-community-failed';
+export declare class DshRealmError extends Error {
+    readonly code: DshRealmErrorCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: Readonly<Record<string, unknown>>;
+    constructor(code: DshRealmErrorCode, expected: string, hint: string, detail: Readonly<Record<string, unknown>>, cause?: unknown);
+}
+export interface DshRealmPluginOptions {
+    /** Attach to an already-running compatible DSH realm. Never closes that realm. */
+    readonly endpoint?: string;
+    /** Explicit DSH executable. Omit to discover `dsh` on PATH. */
+    readonly executable?: string;
+    readonly profile?: string;
+    readonly home?: string;
+    readonly cwd?: string;
+    readonly handshakeTimeoutMs?: number;
+    readonly allowEmbedded?: boolean;
+}
+export interface DshRealmConnection {
+    readonly endpoint: string;
+    readonly binding: FederationBinding;
+    readonly ownership: FederationOwnership;
+    readonly status: FederationStatus;
+    community(): Promise<FederationCommunityCapability>;
+    activity(input: string, sessionId: string, signal?: AbortSignal): Promise<FederationActivityResult>;
+}
+export interface ConnectedRealm {
+    readonly connection: DshRealmConnection;
+    dispose(): Promise<void>;
+}
+/** Engine-side Realm Host Plugin. It publishes no service until handshake and lease acquisition succeed. */
+export declare function dshRealmPlugin(options?: DshRealmPluginOptions): Plugin;
+export declare function connectDshRealm(options?: DshRealmPluginOptions): Promise<Result<ConnectedRealm, DshRealmError>>;
+//# sourceMappingURL=engine-host.d.ts.map

package/dist/engine-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-host.d.ts","sourceRoot":"","sources":["../src/engine-host.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,6BAA6B,EAElC,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EAEtB,MAAM,YAAY,CAAC;AAEpB,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,qBAAqB;QAC7B,QAAQ,EAAE,kBAAkB,CAAC;KAC9B;CACF;AAED,MAAM,MAAM,iBAAiB,GACzB,wBAAwB,GACxB,yBAAyB,GACzB,mBAAmB,GACnB,uBAAuB,GACvB,kBAAkB,GAClB,sBAAsB,CAAC;AAE3B,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;gBAGjD,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,KAAK,CAAC,EAAE,OAAO;CASlB;AAED,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,SAAS,IAAI,OAAO,CAAC,6BAA6B,CAAC,CAAC;IACpD,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,4GAA4G;AAC5G,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAY1E;AAED,wBAAsB,eAAe,CACnC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC,CAehD"}

package/dist/engine-host.mjs

@@ -0,0 +1,331 @@
+import { spawn } from 'child_process';
+import { access } from 'fs/promises';
+import { delimiter, join } from 'path';
+import { fileURLToPath } from 'url';
+import { ok, err } from '@forgeax/engine-types';
+
+// src/engine-host.ts
+
+// src/protocol.ts
+var FEDERATION_PROTOCOL_VERSION = 1;
+var FEDERATION_ROUTE_PREFIX = "/forgeax-federation/v1";
+function isFederationStatus(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return record.protocol === FEDERATION_PROTOCOL_VERSION && record.realm === "dsh" && record.ready === true && typeof record.identity === "string" && Array.isArray(record.capabilities) && record.capabilities.every((capability) => typeof capability === "string") && Number.isInteger(record.leases) && record.leases >= 0 && isEngineProjection(record.engine);
+}
+function isEngineProjection(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  if (record.ready !== true) return false;
+  if (record.binding === "external") return typeof record.endpoint === "string";
+  return record.binding === "embedded" && typeof record.frameId === "number" && typeof record.tick === "number" && typeof record.state === "number";
+}
+
+// src/engine-host.ts
+var DshRealmError = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(code, expected, hint, detail, cause) {
+    super(`${code}: ${expected}`, cause === void 0 ? void 0 : { cause });
+    this.name = "DshRealmError";
+    this.code = code;
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = detail;
+  }
+};
+function dshRealmPlugin(options = {}) {
+  return {
+    name: "dsh-realm",
+    provide: "dshRealm",
+    async apply(ctx) {
+      const result = await connectDshRealm(options);
+      if (!result.ok) throw result.error;
+      const connected = result.value;
+      ctx.effect(() => () => connected.dispose(), "dsh-realm: binding ownership");
+      ctx.provide("dshRealm", connected.connection);
+    }
+  };
+}
+async function connectDshRealm(options = {}) {
+  try {
+    return ok(await resolveDshRealm(options));
+  } catch (cause) {
+    if (cause instanceof DshRealmError) return err(cause);
+    return err(
+      new DshRealmError(
+        "dsh-launch-failed",
+        "the DSH realm binding to initialize",
+        "Inspect the selected endpoint, executable, profile, and process diagnostics.",
+        { binding: options.endpoint === void 0 ? "launch" : "attach" },
+        cause
+      )
+    );
+  }
+}
+async function resolveDshRealm(options) {
+  const timeoutMs = options.handshakeTimeoutMs ?? 1e4;
+  if (options.endpoint !== void 0) {
+    return attach(options.endpoint, timeoutMs);
+  }
+  const executable = options.executable === void 0 ? await discoverOnPath("dsh") : options.executable;
+  if (executable !== void 0) {
+    return launchExternal(executable, options, timeoutMs);
+  }
+  if (options.allowEmbedded === false) {
+    throw new DshRealmError(
+      "dsh-target-unavailable",
+      "a compatible explicit endpoint or local dsh executable",
+      "Install DeepSeek Harness, pass executable/endpoint, or allow the packaged minimum fallback.",
+      { binding: "external" }
+    );
+  }
+  return launchEmbedded(timeoutMs);
+}
+async function attach(endpoint, timeoutMs) {
+  const normalized = normalizeEndpoint(endpoint);
+  const status = await waitForStatus(normalized, timeoutMs, "attach");
+  const leaseId = await acquireLease(normalized);
+  let disposed = false;
+  return {
+    connection: connection(normalized, "attach", "lease", status),
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      await releaseLease(normalized, leaseId);
+    }
+  };
+}
+async function launchExternal(executable, options, timeoutMs) {
+  const args = ["--profile", options.profile ?? "web", "--host", "127.0.0.1", "--port", "0"];
+  const child = spawn(executable, args, {
+    cwd: options.cwd,
+    env: {
+      ...process.env,
+      ...options.home === void 0 ? {} : { DSH_HOME: options.home }
+    }
+  });
+  return finishLaunch(child, "external", timeoutMs, executable);
+}
+async function launchEmbedded(timeoutMs) {
+  const entry = fileURLToPath(new URL("./embedded.mjs", import.meta.url));
+  const child = spawn(process.execPath, [entry], { env: process.env });
+  return finishLaunch(child, "embedded", timeoutMs, entry);
+}
+async function finishLaunch(child, binding, timeoutMs, target) {
+  try {
+    const endpoint = await readLaunchEndpoint(child, timeoutMs, target);
+    const status = await waitForStatus(endpoint, timeoutMs, binding);
+    const leaseId = await acquireLease(endpoint);
+    let disposed = false;
+    return {
+      connection: connection(endpoint, binding, "instance", status),
+      async dispose() {
+        if (disposed) return;
+        disposed = true;
+        await releaseLease(endpoint, leaseId).catch(() => void 0);
+        await stopChild(child);
+      }
+    };
+  } catch (error) {
+    await stopChild(child);
+    throw error;
+  }
+}
+function connection(endpoint, binding, ownership, status) {
+  return {
+    endpoint,
+    binding,
+    ownership,
+    status,
+    async community() {
+      const response = await fetch(`${endpoint}${FEDERATION_ROUTE_PREFIX}/community`);
+      if (!response.ok) {
+        throw new DshRealmError(
+          "dsh-community-failed",
+          "the DSH-native community capability to answer through the bridge",
+          "Install and enable a DSH plugin that provides forgeaxFederationCapability.",
+          { endpoint, status: response.status }
+        );
+      }
+      return await response.json();
+    },
+    async activity(input, sessionId, signal) {
+      const response = await fetch(`${endpoint}${FEDERATION_ROUTE_PREFIX}/activity`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ input, sessionId }),
+        ...signal === void 0 ? {} : { signal }
+      });
+      if (!response.ok) {
+        throw new DshRealmError(
+          "dsh-community-failed",
+          "a DSH-native intelligence capability to answer through the bridge",
+          "Install and enable a DSH plugin that provides forgeaxIntelligenceCapability.",
+          { endpoint, status: response.status }
+        );
+      }
+      const value = await response.json();
+      if (typeof value.output !== "string") {
+        throw new DshRealmError(
+          "dsh-community-failed",
+          "the DSH intelligence bridge to return text output",
+          "Use a capability plugin compatible with federation protocol 1.",
+          { endpoint, received: value }
+        );
+      }
+      return { output: value.output };
+    }
+  };
+}
+async function waitForStatus(endpoint, timeoutMs, binding) {
+  const deadline = Date.now() + timeoutMs;
+  let last;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(`${endpoint}${FEDERATION_ROUTE_PREFIX}/status`);
+      if (response.ok) {
+        const value = await response.json();
+        if (!isFederationStatus(value) || value.protocol !== FEDERATION_PROTOCOL_VERSION) {
+          throw new DshRealmError(
+            "dsh-target-incompatible",
+            `DSH federation protocol ${FEDERATION_PROTOCOL_VERSION}`,
+            "Use a connector version that matches this Engine package.",
+            { binding, endpoint, received: value }
+          );
+        }
+        return value;
+      }
+      last = response.status;
+    } catch (error) {
+      if (error instanceof DshRealmError) throw error;
+      last = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw new DshRealmError(
+    "dsh-handshake-timeout",
+    `a ready federation endpoint within ${timeoutMs}ms`,
+    "Install @forgeax/engine-dsh into the selected DSH profile and inspect its native Loader diagnostics.",
+    { binding, endpoint, last }
+  );
+}
+async function acquireLease(endpoint) {
+  const response = await fetch(`${endpoint}${FEDERATION_ROUTE_PREFIX}/lease`, { method: "POST" });
+  if (!response.ok) {
+    throw new DshRealmError(
+      "dsh-lease-failed",
+      "a lease-scoped bridge activation",
+      "The target must support lease acquisition and release before attach is safe.",
+      { endpoint, status: response.status }
+    );
+  }
+  const lease = await response.json();
+  if (typeof lease.leaseId !== "string") {
+    throw new DshRealmError(
+      "dsh-lease-failed",
+      "a string leaseId",
+      "Update the target connector to the matching protocol version.",
+      { endpoint, received: lease }
+    );
+  }
+  return lease.leaseId;
+}
+async function releaseLease(endpoint, leaseId) {
+  await fetch(
+    `${endpoint}${FEDERATION_ROUTE_PREFIX}/lease?leaseId=${encodeURIComponent(leaseId)}`,
+    { method: "DELETE" }
+  );
+}
+function readLaunchEndpoint(child, timeoutMs, target) {
+  return new Promise((resolve, reject) => {
+    let output = "";
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(
+        new DshRealmError(
+          "dsh-launch-failed",
+          "the launched realm to print its loopback URL",
+          "Inspect the native DSH startup and Loader diagnostics.",
+          { target, output }
+        )
+      );
+    }, timeoutMs);
+    const onData = (chunk) => {
+      output += chunk.toString("utf8");
+      const matched = output.match(/(?:dsh web|forgeax embedded):\s+(http:\/\/127\.0\.0\.1:\d+)/);
+      if (matched?.[1] === void 0) return;
+      cleanup();
+      resolve(matched[1]);
+    };
+    const onExit = (code) => {
+      cleanup();
+      reject(
+        new DshRealmError(
+          "dsh-launch-failed",
+          "the launched realm to remain alive through readiness",
+          "Inspect the native process output and profile composition.",
+          { target, code, output }
+        )
+      );
+    };
+    const onError = (cause) => {
+      cleanup();
+      reject(
+        new DshRealmError(
+          "dsh-launch-failed",
+          "the selected DSH executable to start",
+          "Pass an executable file that can launch the selected native DSH profile.",
+          { target, output },
+          cause
+        )
+      );
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      child.stdout.off("data", onData);
+      child.stderr.off("data", onData);
+      child.off("exit", onExit);
+      child.off("error", onError);
+    };
+    child.stdout.on("data", onData);
+    child.stderr.on("data", onData);
+    child.once("exit", onExit);
+    child.once("error", onError);
+  });
+}
+async function stopChild(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  const exited = new Promise((resolve) => child.once("exit", () => resolve()));
+  child.kill("SIGTERM");
+  const graceful = await Promise.race([
+    exited.then(() => true),
+    new Promise((resolve) => setTimeout(() => resolve(false), 2e3))
+  ]);
+  if (!graceful && child.exitCode === null) {
+    child.kill("SIGKILL");
+    await exited;
+  }
+}
+async function discoverOnPath(name) {
+  const paths = process.env.PATH?.split(delimiter) ?? [];
+  for (const directory of paths) {
+    const candidate = join(directory, name);
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  return void 0;
+}
+function normalizeEndpoint(endpoint) {
+  return endpoint.endsWith("/") ? endpoint.slice(0, -1) : endpoint;
+}
+
+export { DshRealmError, connectDshRealm, dshRealmPlugin };
+//# sourceMappingURL=engine-host.mjs.map
+//# sourceMappingURL=engine-host.mjs.map