ekairos 1.22.4-beta.development.0 → 1.22.4-beta.feature-thread-unify.0

package/README.md

@@ -1,22 +1,123 @@
 # ekairos
 
-Convenience package that re-exports the main Ekairos surfaces.
+Unified entrypoint for Ekairos core libraries.
 
-## Main entrypoints
+`ekairos` re-exports:
 
-- `ekairos` -> `@ekairos/events` + `@ekairos/domain`
-- `ekairos/context` -> context runtime/builder surface
-- `ekairos/dataset`
-- `ekairos/domain`
+- `@ekairos/domain`
+- `@ekairos/thread`
 
-## Example
+Use this package when you want one dependency and a clean DX surface for app teams.
+
+## What You Build With It
+
+Ekairos is for domain-native AI applications:
+
+- model your business as domains,
+- run durable AI threads on top of those domains,
+- keep state, traces, and workflow execution aligned.
+
+## Installation
+
+```bash
+pnpm add ekairos
+```
+
+## Minimal App Bootstrap
+
+```ts
+import "server-only";
+import { configureRuntime } from "ekairos/runtime";
+import { getOrgAdminDb } from "@/lib/admin-org-db";
+import appDomain from "@/lib/domain";
+
+export const runtimeConfig = configureRuntime({
+  runtime: async (env: { orgId: string }) => {
+    const db = await getOrgAdminDb(env.orgId, appDomain);
+    return { db };
+  },
+  domain: { domain: appDomain },
+});
+```
+
+The runtime bootstrap is single-source:
+
+- no per-thread runtime bootstrap,
+- no duplicated store wiring in app code,
+- no extra SDK wrapper required.
+
+Thread builds its store from the runtime-resolved db.
+
+## Define a Thread
 
 ```ts
-import { createContext } from "ekairos/context";
+import { createThread } from "ekairos";
+import { tool } from "ai";
+import { z } from "zod";
 
-const demoContext = createContext("demo")
-  .context((stored) => stored.content ?? {})
-  .narrative(() => "Demo context")
-  .actions(() => ({}))
+const demoThread = createThread<{ orgId: string; sessionId: string }>("demo")
+  .context(async (stored, env) => ({ ...(stored.content ?? {}), ...env }))
+  .narrative(() => "You are a reliable assistant.")
+  .actions(() => ({
+    ping: tool({
+      description: "Return pong",
+      inputSchema: z.object({ text: z.string().optional() }),
+      execute: async ({ text }) => ({ pong: text ?? "ok" }),
+    }),
+  }))
+  .model("openai/gpt-5.2")
   .build();
 ```
+
+## Preconfigured Coding Thread (`thread/codex`)
+
+If your app uses Codex App Server:
+
+```ts
+import { createCodexThreadBuilder } from "ekairos/thread";
+
+const codingBuilder = createCodexThreadBuilder({
+  key: "code.agent",
+  context: async (stored, env) => ({ ...(stored.content ?? {}), ...env }),
+  executeCodex: async ({ input, env }) => {
+    // call app server and return normalized output
+    return {
+      threadId: "t_1",
+      turnId: "turn_1",
+      assistantText: "completed",
+      reasoningText: "",
+      diff: "",
+      toolParts: [],
+    };
+  },
+});
+```
+
+## Workflow Integration
+
+Ekairos threads are designed to run inside Workflow DevKit:
+
+- thread logic stays declarative,
+- side effects run in workflow-safe steps,
+- streams are resumable via workflow run streams.
+
+Important boundary:
+
+- workflow wrapper owns `"use workflow"`,
+- thread engine stays workflow-compatible but does not declare `"use workflow"` internally.
+
+## Package Surface
+
+- `ekairos` -> root re-exports (`domain` + `thread` APIs)
+- `ekairos/domain` -> domain constructors and types
+- `ekairos/thread` -> thread runtime and builders
+- `ekairos/dataset` -> dataset tools (separate package support)
+
+## DX Principles
+
+- Keep startup config short.
+- Keep thread definitions easy to read.
+- Keep runtime explicit and deterministic.
+- Keep domain as source of truth.
+
+This package is optimized for fast onboarding without sacrificing production durability.

package/dist/agent.d.ts

@@ -1,2 +1,2 @@
-export * from '@ekairos/events';
+export * from '@ekairos/thread';
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.js

@@ -14,6 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// Re-export agent functionality from @ekairos/events
-__exportStar(require("@ekairos/events"), exports);
+// Re-export agent functionality from @ekairos/thread
+__exportStar(require("@ekairos/thread"), exports);
 //# sourceMappingURL=agent.js.map

package/dist/dataset.d.ts

@@ -1,2 +1,17 @@
-export * from "@ekairos/dataset";
+import { type InstantAdminDatabase } from "@instantdb/admin";
+import { datasetDomain, DatasetService } from "@ekairos/dataset";
+import type { SchemaOf } from "@ekairos/domain";
+export type DatasetDb = InstantAdminDatabase<SchemaOf<typeof datasetDomain>>;
+export type DatasetsOptions = {
+    db?: DatasetDb;
+    appId?: string;
+    adminToken?: string;
+    schema?: unknown;
+};
+export type DatasetsClient = {
+    db: DatasetDb;
+    domain: typeof datasetDomain;
+    service: DatasetService;
+};
+export declare function datasets(options?: DatasetsOptions): DatasetsClient;
 //# sourceMappingURL=dataset.d.ts.map

package/dist/dataset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,MAAM,MAAM,SAAS,GAAG,oBAAoB,CAAC,QAAQ,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC;AAE7E,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,EAAE,OAAO,aAAa,CAAC;IAC7B,OAAO,EAAE,cAAc,CAAC;CACzB,CAAC;AAeF,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,CAgCtE"}

package/dist/dataset.js

@@ -1,18 +1,41 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("@ekairos/dataset"), exports);
+exports.datasets = datasets;
+const admin_1 = require("@instantdb/admin");
+const dataset_1 = require("@ekairos/dataset");
+function resolveAppId(options) {
+    return (options.appId ??
+        process.env.INSTANT_APP_ID ??
+        process.env.NEXT_PUBLIC_INSTANT_APP_ID ??
+        "");
+}
+function resolveAdminToken(options) {
+    return options.adminToken ?? process.env.INSTANT_APP_ADMIN_TOKEN ?? "";
+}
+function datasets(options = {}) {
+    if (options.db) {
+        return {
+            db: options.db,
+            domain: dataset_1.datasetDomain,
+            service: new dataset_1.DatasetService(options.db),
+        };
+    }
+    const appId = resolveAppId(options);
+    const adminToken = resolveAdminToken(options);
+    if (!appId || !adminToken) {
+        throw new Error("datasets() requires Instant credentials. Provide { db } or { appId, adminToken }.");
+    }
+    const schema = options.schema ??
+        (typeof dataset_1.datasetDomain.toInstantSchema === "function"
+            ? dataset_1.datasetDomain.toInstantSchema()
+            : typeof dataset_1.datasetDomain.schema === "function"
+                ? dataset_1.datasetDomain.schema()
+                : undefined);
+    const db = (0, admin_1.init)({ appId, adminToken, ...(schema ? { schema } : {}) });
+    return {
+        db,
+        domain: dataset_1.datasetDomain,
+        service: new dataset_1.DatasetService(db),
+    };
+}
 //# sourceMappingURL=dataset.js.map

package/dist/dataset.js.map

@@ -1 +1 @@
-{"version":3,"file":"dataset.js","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,mDAAiC"}
+{"version":3,"file":"dataset.js","sourceRoot":"","sources":["../src/dataset.ts"],"names":[],"mappings":";;AAgCA,4BAgCC;AAhED,4CAAmE;AACnE,8CAAiE;AAkBjE,SAAS,YAAY,CAAC,OAAwB;IAC5C,OAAO,CACL,OAAO,CAAC,KAAK;QACb,OAAO,CAAC,GAAG,CAAC,cAAc;QAC1B,OAAO,CAAC,GAAG,CAAC,0BAA0B;QACtC,EAAE,CACH,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAwB;IACjD,OAAO,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,EAAE,CAAC;AACzE,CAAC;AAED,SAAgB,QAAQ,CAAC,UAA2B,EAAE;IACpD,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC;QACf,OAAO;YACL,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,MAAM,EAAE,uBAAa;YACrB,OAAO,EAAE,IAAI,wBAAc,CAAC,OAAO,CAAC,EAAE,CAAC;SACxC,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAE9C,IAAI,CAAC,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,mFAAmF,CACpF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GACV,OAAO,CAAC,MAAM;QACd,CAAC,OAAQ,uBAAqB,CAAC,eAAe,KAAK,UAAU;YAC3D,CAAC,CAAE,uBAAqB,CAAC,eAAe,EAAE;YAC1C,CAAC,CAAC,OAAQ,uBAAqB,CAAC,MAAM,KAAK,UAAU;gBACnD,CAAC,CAAE,uBAAqB,CAAC,MAAM,EAAE;gBACjC,CAAC,CAAC,SAAS,CAAC,CAAC;IACnB,MAAM,EAAE,GAAG,IAAA,YAAI,EAAC,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAc,CAAC;IAEnF,OAAO;QACL,EAAE;QACF,MAAM,EAAE,uBAAa;QACrB,OAAO,EAAE,IAAI,wBAAc,CAAC,EAAE,CAAC;KAChC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export * from '@ekairos/events';
+export * from '@ekairos/thread';
 export * from '@ekairos/domain';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// Re-export principal de context/events
-__exportStar(require("@ekairos/events"), exports);
+// Re-export todo de thread (el paquete principal)
+__exportStar(require("@ekairos/thread"), exports);
 // Re-export domain utilities
 __exportStar(require("@ekairos/domain"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wCAAwC;AACxC,kDAAgC;AAEhC,6BAA6B;AAC7B,kDAAgC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAkD;AAClD,kDAAgC;AAEhC,6BAA6B;AAC7B,kDAAgC"}

package/dist/thread.d.ts

@@ -0,0 +1,2 @@
+export * from "@ekairos/thread";
+//# sourceMappingURL=thread.d.ts.map

package/dist/thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../src/thread.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/{context.js → thread.js}

@@ -14,5 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("@ekairos/events"), exports);
-//# sourceMappingURL=context.js.map
+__exportStar(require("@ekairos/thread"), exports);
+//# sourceMappingURL=thread.js.map

package/dist/thread.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread.js","sourceRoot":"","sources":["../src/thread.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAgC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ekairos",
-  "version": "1.22.4-beta.development.0",
+  "version": "1.22.4-beta.feature-thread-unify.0",
   "description": "Ekairos - AI Stories and Workflows Runtime",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -34,11 +34,11 @@
       "require": "./dist/dataset.js",
       "default": "./dist/dataset.js"
     },
-    "./context": {
-      "types": "./dist/context.d.ts",
-      "import": "./dist/context.js",
-      "require": "./dist/context.js",
-      "default": "./dist/context.js"
+    "./thread": {
+      "types": "./dist/thread.d.ts",
+      "import": "./dist/thread.js",
+      "require": "./dist/thread.js",
+      "default": "./dist/thread.js"
     },
     "./domain": {
       "types": "./dist/domain.d.ts",
@@ -73,10 +73,10 @@
   },
   "dependencies": {
     "@ekairos/dataset": "^1.21.85-beta.0",
-    "@ekairos/domain": "^1.22.4-beta.development.0",
-    "@ekairos/events": "^1.22.4-beta.development.0",
+    "@ekairos/domain": "^1.22.4-beta.feature-thread-unify.0",
+    "@ekairos/thread": "^1.22.4-beta.feature-thread-unify.0",
     "@instantdb/admin": "0.22.126",
-    "ekairos-cli": "^1.22.4-beta.development.0"
+    "ekairos-cli": "^1.22.4-beta.feature-thread-unify.0"
   },
   "devDependencies": {
     "@ekairos/tsconfig": "workspace:*",

package/dist/context.d.ts

@@ -1,2 +0,0 @@
-export * from "@ekairos/events";
-//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/context.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAgC"}