Package Exports

@intent-driven/runtime-local

Readme

@intent-driven/runtime-local

Standalone Fold-runtime для локального quickstart'а. Принимает ontology.js (сгенерированный idf full-bootstrap), поднимает HTTP-сервер с эндпоинтами, которые ожидает @intent-driven/mcp-server для подключения к Claude Desktop / Cursor / Zed.

Статус: v0.3 — stateful Φ через @intent-driven/engine. Поддерживает /api/health, /api/typemap, /api/agent/:domain/schema (discovery), /api/state/current, /api/agent/:domain/world (fold снимок). agent/exec + approvals lifecycle — в следующих релизах (см. roadmap fold-15min).

Зачем

До этого пакета чтобы поднять Fold-runtime локально нужно было git clone idf + npm install + npm run server в host-репе. Это блокер коробочности: пользователь не должен знать про host. После этого пакета:

idf serve --ontology ./ontology.js   # планируется в @intent-driven/cli
# или программно:
import { createRuntime } from '@intent-driven/runtime-local';
const runtime = createRuntime({
  ontology: require('./ontology.js'),
  seed: require('./seed.json'),  // опц. — массив эффектов
});
await runtime.start();

Установка

npm install @intent-driven/runtime-local

Peer-зависимость: @intent-driven/core@>=0.49.0 (через @intent-driven/engine).

API

`createRuntime(opts)`

Создаёт runtime-инстанс. Не стартует сервер — для этого вызови .start().

Опция	Тип	Default	Описание
`ontology`	object	required	IDF ontology — `{ entities, intents, roles, projections, ... }`.
`seed`	array	`[]`	Pre-confirmed эффекты для начального состояния Φ. Каждый — `{id, intent_id, alpha, target, context, value?, status: 'confirmed', created_at}`. Primitive `value` (строки/числа) нормализуются в JSON-encoded автоматически.
`port`	number	`3001`	Порт. `0` = random (для тестов).
`host`	string	`'127.0.0.1'`	Bind-адрес.

Возвращает { app, ontology, domain, engine, persistence, start(), stop() }. engine — instance @intent-driven/engine, для прямого использования (e.g., тесты).

`runtime.start()` → `Promise<{url, port, host}>`

Поднимает Express-сервер. Загружает seed в persistence перед listen. Возвращает actual URL/port (полезно при port: 0).

`runtime.stop()` → `Promise<void>`

Закрывает сервер.

Эндпоинты

Метод	Путь	Назначение
`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 не совпадает.
`GET`	`/api/state/current`	Folded world snapshot — `{domain, world: {products: [...], orders: [...]}}`.
`GET`	`/api/agent/:domain/world`	Тот же world, что и `/api/state/current`. Этот endpoint вызывает `@intent-driven/mcp-server` для resource-чтения. 503 при mismatch domain.
`POST`	`/api/agent/:domain/exec/:intentId`	Ingest intent через `engine.submit`. Generic builder для add/replace/remove. Возвращает `200 {status:'confirmed', effect}` или `409 {status:'rejected', error:'invariant_violation', reason, cascaded}`. `400` для read-intents, `404` для unknown intent, `503` для wrong domain.

POST /api/agent/:domain/exec/:intentId

Тело запроса: { params: { ... } }.

buildEffect() строит effect по generic-семантике (идентично host'овскому genericBuildEffects):

alpha=add → context = {...params, id: params.id || uuid}, value = null
alpha=replace target=Entity.field → context = {id: params.id}, value = JSON.stringify(params[field])
alpha=replace target=Entity → context = {...params}, value = null
alpha=remove → context = {id: params.id || params['<entity>Id']}, value = null
alpha=read → 400 (читай через GET /api/state/current)

Лежит на engine.submit, поэтому invariants всех 6 kinds автоматически проверяются (role-capability / referential / transition / cardinality / aggregate / expression).

A1.3 (следующий PR): intents с lifecycle.requiresApproval сейчас confirm'ятся напрямую. После добавления lifecycleAugmenter они будут создавать ApprovalRequest вместо ingest'а оригинального effect'а.

Roadmap (следующие PR)

v0.5: GET /api/approvals/pending + POST /api/approvals/:id/approve|reject + ApprovalRequest auto-injection (lifecycleAugmenter)
v0.6: GET /api/state/at?t=ISO + /api/state/diff?from=&to= — time-travel
v0.7: SSE-стрим /api/approvals/stream для idf approvals --watch

JSPM