@forgeax/engine-dsh 0.1.2

package/dist/engine-host.mjs

@@ -0,0 +1,384 @@
+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 isFederationCommunityCapability(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return typeof record.id === "string" && typeof record.value === "string";
+}
+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;
+  let releaseAttempt;
+  return {
+    connection: connection(normalized, "attach", "lease", status),
+    async dispose() {
+      if (disposed) return;
+      if (releaseAttempt !== void 0) return releaseAttempt;
+      const attempt = releaseLease(normalized, leaseId).then(
+        () => {
+          disposed = true;
+        },
+        (cause) => {
+          releaseAttempt = void 0;
+          throw cause;
+        }
+      );
+      releaseAttempt = attempt;
+      return attempt;
+    }
+  };
+}
+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 }
+        );
+      }
+      let value;
+      try {
+        value = await response.json();
+      } catch (cause) {
+        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, reason: "invalid-json" },
+          cause
+        );
+      }
+      if (!isFederationCommunityCapability(value)) {
+        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, received: value }
+        );
+      }
+      return value;
+    },
+    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) {
+  try {
+    const response = await fetch(
+      `${endpoint}${FEDERATION_ROUTE_PREFIX}/lease?leaseId=${encodeURIComponent(leaseId)}`,
+      { method: "DELETE" }
+    );
+    if (!response.ok) {
+      throw leaseReleaseError(endpoint, { status: response.status });
+    }
+  } catch (cause) {
+    if (cause instanceof DshRealmError) throw cause;
+    throw leaseReleaseError(endpoint, { reason: "transport" }, cause);
+  }
+}
+function leaseReleaseError(endpoint, detail, cause) {
+  return new DshRealmError(
+    "dsh-lease-failed",
+    "the attached bridge lease to release",
+    "Keep the ConnectedRealm and retry disposal after the target can accept the release.",
+    { endpoint, ...detail },
+    cause
+  );
+}
+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

package/dist/engine-host.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocol.ts","../src/engine-host.ts"],"names":[],"mappings":"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","file":"engine-host.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 function isFederationCommunityCapability(\n  value: unknown,\n): value is FederationCommunityCapability {\n  if (typeof value !== 'object' || value === null) return false;\n  const record = value as Record<string, unknown>;\n  return typeof record.id === 'string' && typeof record.value === '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 { type ChildProcessWithoutNullStreams, spawn } from 'node:child_process';\nimport { access } from 'node:fs/promises';\nimport { delimiter, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nimport type { Plugin } from '@forgeax/engine-plugin';\nimport { err, ok, type Result } from '@forgeax/engine-types';\n\nimport {\n  FEDERATION_PROTOCOL_VERSION,\n  FEDERATION_ROUTE_PREFIX,\n  type FederationActivityResult,\n  type FederationBinding,\n  type FederationCommunityCapability,\n  type FederationLease,\n  type FederationOwnership,\n  type FederationStatus,\n  isFederationCommunityCapability,\n  isFederationStatus,\n} from './protocol';\n\ndeclare module '@forgeax/engine-plugin' {\n  interface EngineContextServices {\n    dshRealm: DshRealmConnection;\n  }\n}\n\nexport type DshRealmErrorCode =\n  | 'dsh-target-unavailable'\n  | 'dsh-target-incompatible'\n  | 'dsh-launch-failed'\n  | 'dsh-handshake-timeout'\n  | 'dsh-lease-failed'\n  | 'dsh-community-failed';\n\nexport class DshRealmError extends Error {\n  readonly code: DshRealmErrorCode;\n  readonly expected: string;\n  readonly hint: string;\n  readonly detail: Readonly<Record<string, unknown>>;\n\n  constructor(\n    code: DshRealmErrorCode,\n    expected: string,\n    hint: string,\n    detail: Readonly<Record<string, unknown>>,\n    cause?: unknown,\n  ) {\n    super(`${code}: ${expected}`, cause === undefined ? undefined : { cause });\n    this.name = 'DshRealmError';\n    this.code = code;\n    this.expected = expected;\n    this.hint = hint;\n    this.detail = detail;\n  }\n}\n\nexport interface DshRealmPluginOptions {\n  /** Attach to an already-running compatible DSH realm. Never closes that realm. */\n  readonly endpoint?: string;\n  /** Explicit DSH executable. Omit to discover `dsh` on PATH. */\n  readonly executable?: string;\n  readonly profile?: string;\n  readonly home?: string;\n  readonly cwd?: string;\n  readonly handshakeTimeoutMs?: number;\n  readonly allowEmbedded?: boolean;\n}\n\nexport interface DshRealmConnection {\n  readonly endpoint: string;\n  readonly binding: FederationBinding;\n  readonly ownership: FederationOwnership;\n  readonly status: FederationStatus;\n  community(): Promise<FederationCommunityCapability>;\n  activity(\n    input: string,\n    sessionId: string,\n    signal?: AbortSignal,\n  ): Promise<FederationActivityResult>;\n}\n\nexport interface ConnectedRealm {\n  readonly connection: DshRealmConnection;\n  dispose(): Promise<void>;\n}\n\n/** Engine-side Realm Host Plugin. It publishes no service until handshake and lease acquisition succeed. */\nexport function dshRealmPlugin(options: DshRealmPluginOptions = {}): Plugin {\n  return {\n    name: 'dsh-realm',\n    provide: 'dshRealm',\n    async apply(ctx) {\n      const result = await connectDshRealm(options);\n      if (!result.ok) throw result.error;\n      const connected = result.value;\n      ctx.effect(() => () => connected.dispose(), 'dsh-realm: binding ownership');\n      ctx.provide('dshRealm', connected.connection);\n    },\n  };\n}\n\nexport async function connectDshRealm(\n  options: DshRealmPluginOptions = {},\n): Promise<Result<ConnectedRealm, DshRealmError>> {\n  try {\n    return ok(await resolveDshRealm(options));\n  } catch (cause) {\n    if (cause instanceof DshRealmError) return err(cause);\n    return err(\n      new DshRealmError(\n        'dsh-launch-failed',\n        'the DSH realm binding to initialize',\n        'Inspect the selected endpoint, executable, profile, and process diagnostics.',\n        { binding: options.endpoint === undefined ? 'launch' : 'attach' },\n        cause,\n      ),\n    );\n  }\n}\n\nasync function resolveDshRealm(options: DshRealmPluginOptions): Promise<ConnectedRealm> {\n  const timeoutMs = options.handshakeTimeoutMs ?? 10_000;\n  if (options.endpoint !== undefined) {\n    return attach(options.endpoint, timeoutMs);\n  }\n\n  const executable =\n    options.executable === undefined ? await discoverOnPath('dsh') : options.executable;\n  if (executable !== undefined) {\n    return launchExternal(executable, options, timeoutMs);\n  }\n  if (options.allowEmbedded === false) {\n    throw new DshRealmError(\n      'dsh-target-unavailable',\n      'a compatible explicit endpoint or local dsh executable',\n      'Install DeepSeek Harness, pass executable/endpoint, or allow the packaged minimum fallback.',\n      { binding: 'external' },\n    );\n  }\n  return launchEmbedded(timeoutMs);\n}\n\nasync function attach(endpoint: string, timeoutMs: number): Promise<ConnectedRealm> {\n  const normalized = normalizeEndpoint(endpoint);\n  const status = await waitForStatus(normalized, timeoutMs, 'attach');\n  const leaseId = await acquireLease(normalized);\n  let disposed = false;\n  let releaseAttempt: Promise<void> | undefined;\n  return {\n    connection: connection(normalized, 'attach', 'lease', status),\n    async dispose() {\n      if (disposed) return;\n      if (releaseAttempt !== undefined) return releaseAttempt;\n      const attempt = releaseLease(normalized, leaseId).then(\n        () => {\n          disposed = true;\n        },\n        (cause) => {\n          releaseAttempt = undefined;\n          throw cause;\n        },\n      );\n      releaseAttempt = attempt;\n      return attempt;\n    },\n  };\n}\n\nasync function launchExternal(\n  executable: string,\n  options: DshRealmPluginOptions,\n  timeoutMs: number,\n): Promise<ConnectedRealm> {\n  const args = ['--profile', options.profile ?? 'web', '--host', '127.0.0.1', '--port', '0'];\n  const child = spawn(executable, args, {\n    cwd: options.cwd,\n    env: {\n      ...process.env,\n      ...(options.home === undefined ? {} : { DSH_HOME: options.home }),\n    },\n  });\n  return finishLaunch(child, 'external', timeoutMs, executable);\n}\n\nasync function launchEmbedded(timeoutMs: number): Promise<ConnectedRealm> {\n  const entry = fileURLToPath(new URL('./embedded.mjs', import.meta.url));\n  const child = spawn(process.execPath, [entry], { env: process.env });\n  return finishLaunch(child, 'embedded', timeoutMs, entry);\n}\n\nasync function finishLaunch(\n  child: ChildProcessWithoutNullStreams,\n  binding: Exclude<FederationBinding, 'attach'>,\n  timeoutMs: number,\n  target: string,\n): Promise<ConnectedRealm> {\n  try {\n    const endpoint = await readLaunchEndpoint(child, timeoutMs, target);\n    const status = await waitForStatus(endpoint, timeoutMs, binding);\n    const leaseId = await acquireLease(endpoint);\n    let disposed = false;\n    return {\n      connection: connection(endpoint, binding, 'instance', status),\n      async dispose() {\n        if (disposed) return;\n        disposed = true;\n        await releaseLease(endpoint, leaseId).catch(() => undefined);\n        await stopChild(child);\n      },\n    };\n  } catch (error) {\n    await stopChild(child);\n    throw error;\n  }\n}\n\nfunction connection(\n  endpoint: string,\n  binding: FederationBinding,\n  ownership: FederationOwnership,\n  status: FederationStatus,\n): DshRealmConnection {\n  return {\n    endpoint,\n    binding,\n    ownership,\n    status,\n    async community() {\n      const response = await fetch(`${endpoint}${FEDERATION_ROUTE_PREFIX}/community`);\n      if (!response.ok) {\n        throw new DshRealmError(\n          'dsh-community-failed',\n          'the DSH-native community capability to answer through the bridge',\n          'Install and enable a DSH plugin that provides forgeaxFederationCapability.',\n          { endpoint, status: response.status },\n        );\n      }\n      let value: unknown;\n      try {\n        value = await response.json();\n      } catch (cause) {\n        throw new DshRealmError(\n          'dsh-community-failed',\n          'the DSH-native community capability to answer through the bridge',\n          'Install and enable a DSH plugin that provides forgeaxFederationCapability.',\n          { endpoint, reason: 'invalid-json' },\n          cause,\n        );\n      }\n      if (!isFederationCommunityCapability(value)) {\n        throw new DshRealmError(\n          'dsh-community-failed',\n          'the DSH-native community capability to answer through the bridge',\n          'Install and enable a DSH plugin that provides forgeaxFederationCapability.',\n          { endpoint, received: value },\n        );\n      }\n      return value;\n    },\n    async activity(input, sessionId, signal) {\n      const response = await fetch(`${endpoint}${FEDERATION_ROUTE_PREFIX}/activity`, {\n        method: 'POST',\n        headers: { 'content-type': 'application/json' },\n        body: JSON.stringify({ input, sessionId }),\n        ...(signal === undefined ? {} : { signal }),\n      });\n      if (!response.ok) {\n        throw new DshRealmError(\n          'dsh-community-failed',\n          'a DSH-native intelligence capability to answer through the bridge',\n          'Install and enable a DSH plugin that provides forgeaxIntelligenceCapability.',\n          { endpoint, status: response.status },\n        );\n      }\n      const value = (await response.json()) as Partial<FederationActivityResult>;\n      if (typeof value.output !== 'string') {\n        throw new DshRealmError(\n          'dsh-community-failed',\n          'the DSH intelligence bridge to return text output',\n          'Use a capability plugin compatible with federation protocol 1.',\n          { endpoint, received: value },\n        );\n      }\n      return { output: value.output };\n    },\n  };\n}\n\nasync function waitForStatus(\n  endpoint: string,\n  timeoutMs: number,\n  binding: FederationBinding,\n): Promise<FederationStatus> {\n  const deadline = Date.now() + timeoutMs;\n  let last: unknown;\n  while (Date.now() < deadline) {\n    try {\n      const response = await fetch(`${endpoint}${FEDERATION_ROUTE_PREFIX}/status`);\n      if (response.ok) {\n        const value: unknown = await response.json();\n        if (!isFederationStatus(value) || value.protocol !== FEDERATION_PROTOCOL_VERSION) {\n          throw new DshRealmError(\n            'dsh-target-incompatible',\n            `DSH federation protocol ${FEDERATION_PROTOCOL_VERSION}`,\n            'Use a connector version that matches this Engine package.',\n            { binding, endpoint, received: value },\n          );\n        }\n        return value;\n      }\n      last = response.status;\n    } catch (error) {\n      if (error instanceof DshRealmError) throw error;\n      last = error;\n    }\n    await new Promise((resolve) => setTimeout(resolve, 50));\n  }\n  throw new DshRealmError(\n    'dsh-handshake-timeout',\n    `a ready federation endpoint within ${timeoutMs}ms`,\n    'Install @forgeax/engine-dsh into the selected DSH profile and inspect its native Loader diagnostics.',\n    { binding, endpoint, last },\n  );\n}\n\nasync function acquireLease(endpoint: string): Promise<string> {\n  const response = await fetch(`${endpoint}${FEDERATION_ROUTE_PREFIX}/lease`, { method: 'POST' });\n  if (!response.ok) {\n    throw new DshRealmError(\n      'dsh-lease-failed',\n      'a lease-scoped bridge activation',\n      'The target must support lease acquisition and release before attach is safe.',\n      { endpoint, status: response.status },\n    );\n  }\n  const lease = (await response.json()) as Partial<FederationLease>;\n  if (typeof lease.leaseId !== 'string') {\n    throw new DshRealmError(\n      'dsh-lease-failed',\n      'a string leaseId',\n      'Update the target connector to the matching protocol version.',\n      { endpoint, received: lease },\n    );\n  }\n  return lease.leaseId;\n}\n\nasync function releaseLease(endpoint: string, leaseId: string): Promise<void> {\n  try {\n    const response = await fetch(\n      `${endpoint}${FEDERATION_ROUTE_PREFIX}/lease?leaseId=${encodeURIComponent(leaseId)}`,\n      { method: 'DELETE' },\n    );\n    if (!response.ok) {\n      throw leaseReleaseError(endpoint, { status: response.status });\n    }\n  } catch (cause) {\n    if (cause instanceof DshRealmError) throw cause;\n    throw leaseReleaseError(endpoint, { reason: 'transport' }, cause);\n  }\n}\n\nfunction leaseReleaseError(\n  endpoint: string,\n  detail: Readonly<Record<string, unknown>>,\n  cause?: unknown,\n): DshRealmError {\n  return new DshRealmError(\n    'dsh-lease-failed',\n    'the attached bridge lease to release',\n    'Keep the ConnectedRealm and retry disposal after the target can accept the release.',\n    { endpoint, ...detail },\n    cause,\n  );\n}\n\nfunction readLaunchEndpoint(\n  child: ChildProcessWithoutNullStreams,\n  timeoutMs: number,\n  target: string,\n): Promise<string> {\n  return new Promise((resolve, reject) => {\n    let output = '';\n    const timer = setTimeout(() => {\n      cleanup();\n      reject(\n        new DshRealmError(\n          'dsh-launch-failed',\n          'the launched realm to print its loopback URL',\n          'Inspect the native DSH startup and Loader diagnostics.',\n          { target, output },\n        ),\n      );\n    }, timeoutMs);\n    const onData = (chunk: Buffer): void => {\n      output += chunk.toString('utf8');\n      const matched = output.match(/(?:dsh web|forgeax embedded):\\s+(http:\\/\\/127\\.0\\.0\\.1:\\d+)/);\n      if (matched?.[1] === undefined) return;\n      cleanup();\n      resolve(matched[1]);\n    };\n    const onExit = (code: number | null): void => {\n      cleanup();\n      reject(\n        new DshRealmError(\n          'dsh-launch-failed',\n          'the launched realm to remain alive through readiness',\n          'Inspect the native process output and profile composition.',\n          { target, code, output },\n        ),\n      );\n    };\n    const onError = (cause: Error): void => {\n      cleanup();\n      reject(\n        new DshRealmError(\n          'dsh-launch-failed',\n          'the selected DSH executable to start',\n          'Pass an executable file that can launch the selected native DSH profile.',\n          { target, output },\n          cause,\n        ),\n      );\n    };\n    const cleanup = (): void => {\n      clearTimeout(timer);\n      child.stdout.off('data', onData);\n      child.stderr.off('data', onData);\n      child.off('exit', onExit);\n      child.off('error', onError);\n    };\n    child.stdout.on('data', onData);\n    child.stderr.on('data', onData);\n    child.once('exit', onExit);\n    child.once('error', onError);\n  });\n}\n\nasync function stopChild(child: ChildProcessWithoutNullStreams): Promise<void> {\n  if (child.exitCode !== null || child.signalCode !== null) return;\n  const exited = new Promise<void>((resolve) => child.once('exit', () => resolve()));\n  child.kill('SIGTERM');\n  const graceful = await Promise.race([\n    exited.then(() => true),\n    new Promise<false>((resolve) => setTimeout(() => resolve(false), 2_000)),\n  ]);\n  if (!graceful && child.exitCode === null) {\n    child.kill('SIGKILL');\n    await exited;\n  }\n}\n\nasync function discoverOnPath(name: string): Promise<string | undefined> {\n  const paths = process.env.PATH?.split(delimiter) ?? [];\n  for (const directory of paths) {\n    const candidate = join(directory, name);\n    try {\n      await access(candidate);\n      return candidate;\n    } catch {\n      // Keep scanning deterministic PATH order.\n    }\n  }\n  return undefined;\n}\n\nfunction normalizeEndpoint(endpoint: string): string {\n  return endpoint.endsWith('/') ? endpoint.slice(0, -1) : endpoint;\n}\n"]}

package/dist/engine-preview.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+export interface EnginePreviewPluginOptions {
+    readonly window?: Window;
+    readonly initialState?: number;
+    readonly control?: (state: number) => number | Promise<number>;
+}
+/**
+ * Engine-native half of the DSH Web preview bridge. The effect owns one ECS
+ * counter system and one postMessage listener; neither exists while disabled.
+ */
+export declare function enginePreviewPlugin(options?: EnginePreviewPluginOptions): Plugin;
+//# sourceMappingURL=engine-preview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine-preview.d.ts","sourceRoot":"","sources":["../src/engine-preview.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAQrD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,CAyDpF"}

package/dist/engine-preview.mjs

@@ -0,0 +1,70 @@
+import { Update } from '@forgeax/engine-ecs';
+
+// src/engine-preview.ts
+
+// src/protocol.ts
+var FEDERATION_PROTOCOL_VERSION = 1;
+function isEnginePreviewRequest(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  if (record.protocol !== FEDERATION_PROTOCOL_VERSION) return false;
+  if (record.kind === "forgeax-engine-poll") return true;
+  return record.kind === "forgeax-engine-control" && record.action === "toggle";
+}
+
+// src/engine-preview.ts
+function enginePreviewPlugin(options = {}) {
+  return {
+    name: "dsh-engine-preview",
+    inject: ["world"],
+    apply(ctx) {
+      const targetWindow = options.window ?? globalThis.window;
+      let tick = 0;
+      let state = options.initialState ?? 0;
+      const systemName = "dsh-engine-preview-tick";
+      ctx.effect(() => {
+        ctx.world.addSystem(Update, {
+          name: systemName,
+          queries: [],
+          fn: () => {
+            tick += 1;
+          }
+        }).unwrap();
+        const respond = (event, value) => {
+          if (event.source === null) return;
+          const origin = event.origin === "null" ? "*" : event.origin;
+          event.source.postMessage(value, { targetOrigin: origin });
+        };
+        const snapshot = () => ({
+          protocol: FEDERATION_PROTOCOL_VERSION,
+          kind: "forgeax-engine-status",
+          binding: "external",
+          ready: true,
+          frameId: tick,
+          tick,
+          state
+        });
+        const onMessage = (event) => {
+          if (!isEnginePreviewRequest(event.data)) return;
+          if (event.data.kind === "forgeax-engine-poll") {
+            respond(event, snapshot());
+            return;
+          }
+          Promise.resolve(options.control?.(state) ?? (state === 0 ? 1 : 0)).then((next) => {
+            state = next;
+            respond(event, snapshot());
+          }).catch(() => void 0);
+        };
+        targetWindow.addEventListener("message", onMessage);
+        return () => {
+          targetWindow.removeEventListener("message", onMessage);
+          ctx.world.removeSystem(Update, systemName).unwrap();
+        };
+      }, "dsh-engine-preview: tick and message bridge");
+    }
+  };
+}
+
+export { enginePreviewPlugin };
+//# sourceMappingURL=engine-preview.mjs.map
+//# sourceMappingURL=engine-preview.mjs.map

package/dist/engine-preview.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocol.ts","../src/engine-preview.ts"],"names":[],"mappings":"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","file":"engine-preview.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 function isFederationCommunityCapability(\n  value: unknown,\n): value is FederationCommunityCapability {\n  if (typeof value !== 'object' || value === null) return false;\n  const record = value as Record<string, unknown>;\n  return typeof record.id === 'string' && typeof record.value === '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 { Update } from '@forgeax/engine-ecs';\nimport type { Plugin } from '@forgeax/engine-plugin';\n\nimport {\n  type EnginePreviewStatus,\n  FEDERATION_PROTOCOL_VERSION,\n  isEnginePreviewRequest,\n} from './protocol';\n\nexport interface EnginePreviewPluginOptions {\n  readonly window?: Window;\n  readonly initialState?: number;\n  readonly control?: (state: number) => number | Promise<number>;\n}\n\n/**\n * Engine-native half of the DSH Web preview bridge. The effect owns one ECS\n * counter system and one postMessage listener; neither exists while disabled.\n */\nexport function enginePreviewPlugin(options: EnginePreviewPluginOptions = {}): Plugin {\n  return {\n    name: 'dsh-engine-preview',\n    inject: ['world'],\n    apply(ctx) {\n      const targetWindow = options.window ?? globalThis.window;\n      let tick = 0;\n      let state = options.initialState ?? 0;\n      const systemName = 'dsh-engine-preview-tick';\n\n      ctx.effect(() => {\n        ctx.world\n          .addSystem(Update, {\n            name: systemName,\n            queries: [],\n            fn: () => {\n              tick += 1;\n            },\n          })\n          .unwrap();\n\n        const respond = (event: MessageEvent, value: EnginePreviewStatus): void => {\n          if (event.source === null) return;\n          const origin = event.origin === 'null' ? '*' : event.origin;\n          (event.source as WindowProxy).postMessage(value, { targetOrigin: origin });\n        };\n        const snapshot = (): EnginePreviewStatus => ({\n          protocol: FEDERATION_PROTOCOL_VERSION,\n          kind: 'forgeax-engine-status',\n          binding: 'external',\n          ready: true,\n          frameId: tick,\n          tick,\n          state,\n        });\n        const onMessage = (event: MessageEvent): void => {\n          if (!isEnginePreviewRequest(event.data)) return;\n          if (event.data.kind === 'forgeax-engine-poll') {\n            respond(event, snapshot());\n            return;\n          }\n          Promise.resolve(options.control?.(state) ?? (state === 0 ? 1 : 0))\n            .then((next) => {\n              state = next;\n              respond(event, snapshot());\n            })\n            .catch(() => undefined);\n        };\n        targetWindow.addEventListener('message', onMessage);\n\n        return () => {\n          targetWindow.removeEventListener('message', onMessage);\n          ctx.world.removeSystem(Update, systemName).unwrap();\n        };\n      }, 'dsh-engine-preview: tick and message bridge');\n    },\n  };\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+interface WebRoute {
+    readonly kind: 'exact' | 'prefix';
+    readonly path: string;
+    readonly handler: (request: IncomingMessage, response: ServerResponse) => void | Promise<void>;
+}
+interface WebServerService {
+    register(route: WebRoute): () => void;
+}
+interface DshHostContext {
+    readonly webServer: WebServerService;
+    readonly logger: {
+        warn(error: unknown): void;
+    };
+    effect(callback: () => void | (() => void | Promise<void>), label?: string): void;
+    get(name: string): unknown;
+}
+export interface Config {
+    readonly engineEndpoint?: string;
+    readonly identity?: string;
+}
+export declare const inject: string[];
+/** DSH-native Host half. DSH's Loader mounts this ordinary plugin from the package patch. */
+export declare function apply(ctx: DshHostContext, config?: Config): Promise<void>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAajE,UAAU,QAAQ;IAChB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChG;AAED,UAAU,gBAAgB;IACxB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAC;CACvC;AAED,UAAU,cAAc;IACtB,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE;QAAE,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC;IAChD,MAAM,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClF,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AA+BD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,MAAM,UAAgB,CAAC;AAEpC,6FAA6F;AAC7F,wBAAsB,KAAK,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,GAAE,MAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAyJnF"}