@intent-driven/runtime-local 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ignat Dubovsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @intent-driven/runtime-local
+
+Standalone Fold-runtime для локального quickstart'а. Принимает ontology.js (сгенерированный `idf full-bootstrap`), поднимает HTTP-сервер с эндпоинтами, которые ожидает `@intent-driven/mcp-server` для подключения к Claude Desktop / Cursor / Zed.
+
+> **Статус:** v0.1 — skeleton. Поддерживает `/api/health`, `/api/typemap`, `/api/agent/:domain/schema` (discovery). Полный agent/exec, approvals lifecycle, /api/state/* — в следующих релизах (см. roadmap fold-15min).
+
+## Зачем
+
+До этого пакета чтобы поднять Fold-runtime локально нужно было `git clone idf` + `npm install` + `npm run server` в host-репе. Это блокер коробочности: пользователь не должен знать про host. После этого пакета:
+
+```bash
+idf serve --ontology ./ontology.js   # планируется в @intent-driven/cli
+# или программно:
+import { createRuntime } from '@intent-driven/runtime-local';
+const runtime = createRuntime({ ontology: require('./ontology.js') });
+await runtime.start();
+```
+
+## Установка
+
+```bash
+npm install @intent-driven/runtime-local
+```
+
+Peer-зависимость: `@intent-driven/core@>=0.49.0` (нужен для будущих релизов с validator/fold; в v0.1 не требуется в runtime, но указан как peer для forward-compat).
+
+## API
+
+### `createRuntime(opts)`
+
+Создаёт runtime-инстанс. Не стартует сервер — для этого вызови `.start()`.
+
+| Опция | Тип | Default | Описание |
+|---|---|---|---|
+| `ontology` | object | **required** | IDF ontology — `{ entities, intents, roles, projections, ... }`. |
+| `port` | number | `3001` | Порт. `0` = random (для тестов). |
+| `host` | string | `'127.0.0.1'` | Bind-адрес. |
+
+Возвращает `{ app, ontology, domain, start(), stop() }`.
+
+### `runtime.start()` → `Promise<{url, port, host}>`
+
+Поднимает Express-сервер. Возвращает actual URL/port (полезно при `port: 0`).
+
+### `runtime.stop()` → `Promise<void>`
+
+Закрывает сервер.
+
+## Эндпоинты (v0.1)
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| `GET` | `/api/health` | Liveness check для `idf doctor` и MCP-server. Возвращает `{status, domain, runtime, version}`. |
+| `GET` | `/api/typemap` | Сводка ontology: entities/intents/roles names. |
+| `GET` | `/api/agent/:domain/schema` | Full ontology snapshot для MCP discovery. 503 если domain не совпадает с зарегистрированным. |
+
+## Roadmap (следующие PR)
+
+- v0.2: in-memory Φ-store + `GET /api/state/at` + `GET /api/state/diff`
+- v0.3: `POST /api/agent/:domain/exec/:intentId` — ingest с invariant validation, ApprovalRequest auto-injection через `lifecycleAugmenter`
+- v0.4: `GET /api/approvals/pending` + `POST /api/approvals/:id/approve|reject` + timer-driven expiry
+- v0.5: SSE-стрим `/api/approvals/stream` для `idf approvals --watch`
+
+## Лицензия
+
+MIT. © Ignat Dubovsky.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@intent-driven/runtime-local",
+  "version": "0.2.0",
+  "description": "Standalone Fold-runtime для local quickstart: stateful Φ + agent/exec + approvals + state — то, что делает host idf/server, но как npm-пакет",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^4.21.2"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.0",
+    "@intent-driven/core": "0.116.0"
+  },
+  "peerDependencies": {
+    "@intent-driven/core": ">=0.49.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Игнат Дубовский <dubovskyy.im@gmail.com>",
+  "homepage": "https://github.com/DubovskiyIM/idf-sdk/tree/main/packages/runtime-local",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DubovskiyIM/idf-sdk.git",
+    "directory": "packages/runtime-local"
+  },
+  "bugs": {
+    "url": "https://github.com/DubovskiyIM/idf-sdk/issues"
+  },
+  "keywords": [
+    "intent-driven",
+    "idf",
+    "runtime",
+    "local",
+    "fold",
+    "phi",
+    "approval",
+    "agent",
+    "quickstart"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/createRuntime.js

@@ -0,0 +1,99 @@
+import express from "express";
+import cors from "cors";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const PKG_VERSION = (() => {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+export function createRuntime(opts = {}) {
+  const { ontology, port = 3001, host = "127.0.0.1" } = opts;
+
+  if (!ontology || typeof ontology !== "object") {
+    throw new Error("createRuntime: ontology is required");
+  }
+
+  const domain = ontology.name || "default";
+
+  const app = express();
+  app.use(cors());
+  app.use(express.json({ limit: "10mb" }));
+
+  app.get("/api/health", (_req, res) => {
+    res.json({
+      status: "ok",
+      domain,
+      runtime: "@intent-driven/runtime-local",
+      version: PKG_VERSION,
+    });
+  });
+
+  app.get("/api/typemap", (_req, res) => {
+    res.json({
+      domain,
+      entities: Object.keys(ontology.entities || {}),
+      intents: Object.keys(ontology.intents || {}),
+      roles: Object.keys(ontology.roles || {}),
+    });
+  });
+
+  app.get("/api/agent/:domain/schema", (req, res) => {
+    if (req.params.domain !== domain) {
+      return res.status(503).json({
+        error: "ontology_unavailable",
+        domain: req.params.domain,
+        message: `Ontology for '${req.params.domain}' is not registered. Runtime serves '${domain}'.`,
+      });
+    }
+    res.json({
+      domain,
+      entities: ontology.entities || {},
+      intents: ontology.intents || {},
+      roles: ontology.roles || {},
+    });
+  });
+
+  let server = null;
+
+  return {
+    app,
+    ontology,
+    domain,
+
+    async start() {
+      if (server) {
+        throw new Error("runtime already started");
+      }
+      return await new Promise((resolve, reject) => {
+        const s = app.listen(port, host, () => {
+          server = s;
+          const addr = s.address();
+          const actualPort = typeof addr === "object" && addr ? addr.port : port;
+          resolve({
+            url: `http://${host}:${actualPort}`,
+            port: actualPort,
+            host,
+          });
+        });
+        s.once("error", reject);
+      });
+    },
+
+    async stop() {
+      if (!server) return;
+      const s = server;
+      server = null;
+      await new Promise((resolve, reject) => {
+        s.close((err) => (err ? reject(err) : resolve()));
+      });
+    },
+  };
+}

package/src/index.js

@@ -0,0 +1 @@
+export { createRuntime } from "./createRuntime.js";