@ekairos/openai-reactor 1.22.3 → 1.22.4-beta.development.0

package/README.md

@@ -1,49 +1,24 @@
 # @ekairos/openai-reactor
 
-OpenAI-oriented reactors for `@ekairos/thread`.
+Codex reactor for `@ekairos/events`.
+
+This package is Codex-only:
+- only `createCodexReactor` is exported,
+- no generic OpenAI model reactor is provided here.
 
 ## Exports
 
-- `createOpenAIReactor(options?)`  
-  Returns the AI SDK reactor (`streamText`) for Thread. Optional `options`
-  let you resolve per-turn `config` and map it into model/max-step settings.
 - `createCodexReactor(options)`  
-  Codex App Server reactor for direct Thread execution (no tool indirection).
-
-## AI SDK Reactor Example
-
-```ts
-import { createThread } from "@ekairos/thread";
-import { createOpenAIReactor } from "@ekairos/openai-reactor";
-
-const reactor = createOpenAIReactor({
-  resolveConfig: async ({ env }) => {
-    "use step";
-    return {
-      model: env.model ?? "openai/gpt-5.2",
-      maxModelSteps: 2,
-    };
-  },
-  selectModel: ({ config, baseModel }) => config.model ?? baseModel,
-  selectMaxModelSteps: ({ config, baseMaxModelSteps }) =>
-    typeof config.maxModelSteps === "number"
-      ? config.maxModelSteps
-      : baseMaxModelSteps,
-});
-
-const aiThread = createThread<any>("ai.thread")
-  .context((stored) => stored.content ?? {})
-  .narrative(() => "General purpose AI thread")
-  .actions(() => ({}))
-  .reactor(reactor)
-  .shouldContinue(() => false)
-  .build();
-```
+  Codex App Server reactor for direct Context execution (no tool indirection).
+- `mapCodexChunkType(providerChunkType)`  
+  Maps provider chunk types to canonical Context chunk types.
+- `defaultMapCodexChunk(providerChunk)`  
+  Default provider-chunk mapper used by the reactor.
 
 ## Codex Reactor Example
 
 ```ts
-import { createThread } from "@ekairos/thread";
+import { createContext } from "@ekairos/events";
 import { createCodexReactor } from "@ekairos/openai-reactor";
 
 const reactor = createCodexReactor({
@@ -52,7 +27,7 @@ const reactor = createCodexReactor({
     return {
       appServerUrl: env.appServerUrl,
       repoPath: env.repoPath,
-      threadId: env.threadId,
+      providerContextId: env.providerContextId,
       mode: "local",
     };
   },
@@ -60,7 +35,7 @@ const reactor = createCodexReactor({
     "use step";
     // call codex app server / stream
     return {
-      threadId: config.threadId ?? "thread_1",
+      providerContextId: config.providerContextId ?? "context_1",
       turnId: "turn_1",
       assistantText: "Done.",
       reasoningText: "",
@@ -70,15 +45,44 @@ const reactor = createCodexReactor({
   },
 });
 
-const codingThread = createThread<any>("code.agent")
+const codingContext = createContext<any>("code.agent")
   .context((stored) => stored.content ?? {})
-  .narrative(() => "Ekairos coding thread")
+  .narrative(() => "Ekairos coding context")
   .actions(() => ({}))
   .reactor(reactor)
   .shouldContinue(() => false)
   .build();
 ```
 
+## Provider stream -> Context mapping
+
+For each provider chunk you emit via `emitChunk(providerChunk)`, the reactor writes:
+
+- SSE chunk event: `data-chunk.emitted` with canonical `chunkType` (`chunk.text_delta`, `chunk.action_input_available`, etc.)
+- `codex-event` part metadata on the persisted output item:
+  - `streamTrace.totalChunks`
+  - `streamTrace.chunkTypes`
+  - `streamTrace.providerChunkTypes`
+  - `streamTrace.chunks[]` (configurable)
+
+Default behavior persists stream trace summary and mapped chunks in the final `codex-event`.
+
+Config options:
+
+- `includeStreamTraceInOutput` (default: `true`)
+- `includeRawProviderChunksInOutput` (default: `false`)
+- `maxPersistedStreamChunks` (default: `300`)
+- `onMappedChunk(chunk, params)` hook for custom telemetry pipelines
+
 ## Workflow Compatibility
 
 `resolveConfig` and `executeTurn` should be implemented as workflow-safe step functions when they perform I/O.
+
+## AI SDK generic reactor
+
+`createAiSdkReactor(...)` is provider-agnostic and lives in `@ekairos/events`.
+
+## TODO
+
+- Continuity across machines should be validated end-to-end with persisted session state.
+- Current continuity assumption in local tests is: keep the same `contextId` and reuse the same provider `providerContextId` between turns.

package/dist/codex.reactor.d.ts

@@ -0,0 +1,101 @@
+import { type ContextSkillPackage, type ContextItem, type ContextReactor, type ContextReactorParams, type ContextStreamChunkType } from "@ekairos/events";
+import type { ContextEnvironment } from "@ekairos/events/runtime";
+import { type AnyRecord } from "./shared.js";
+export type CodexConfig = {
+    appServerUrl: string;
+    repoPath: string;
+    providerContextId?: string;
+    mode?: "local" | "remote" | "sandbox";
+    model?: string;
+    approvalPolicy?: string;
+    sandboxPolicy?: Record<string, unknown>;
+};
+export type CodexTurnResult = {
+    providerContextId: string;
+    turnId: string;
+    assistantText: string;
+    reasoningText?: string;
+    diff?: string;
+    toolParts?: unknown[];
+    metadata?: Record<string, unknown>;
+    usage?: Record<string, unknown>;
+};
+export type CodexExecuteTurnArgs<Context, Config extends CodexConfig = CodexConfig, Env extends ContextEnvironment = ContextEnvironment> = {
+    env: Env;
+    context: AnyRecord;
+    triggerEvent: ContextItem;
+    contextId: string;
+    eventId: string;
+    executionId: string;
+    stepId: string;
+    iteration: number;
+    instruction: string;
+    config: Config;
+    skills: ContextSkillPackage[];
+    writable?: WritableStream<unknown>;
+    silent: boolean;
+    emitChunk: (providerChunk: unknown) => Promise<void>;
+};
+export type CodexChunkMappingResult = {
+    chunkType: ContextStreamChunkType;
+    providerChunkType?: string;
+    actionRef?: string;
+    data?: unknown;
+    raw?: unknown;
+    skip?: boolean;
+};
+export type CodexMappedChunk = {
+    at: string;
+    sequence: number;
+    chunkType: ContextStreamChunkType;
+    providerChunkType?: string;
+    actionRef?: string;
+    data?: unknown;
+    raw?: unknown;
+};
+export type CodexStreamTrace = {
+    totalChunks: number;
+    chunkTypes: Record<string, number>;
+    providerChunkTypes: Record<string, number>;
+    chunks?: CodexMappedChunk[];
+};
+export type CreateCodexReactorOptions<Context, Config extends CodexConfig = CodexConfig, Env extends ContextEnvironment = ContextEnvironment> = {
+    toolName?: string;
+    includeReasoningPart?: boolean;
+    buildInstruction?: (params: {
+        env: Env;
+        context: AnyRecord;
+        triggerEvent: ContextItem;
+    }) => string | Promise<string>;
+    resolveConfig: (params: {
+        env: Env;
+        context: AnyRecord;
+        triggerEvent: ContextItem;
+        contextId: string;
+        eventId: string;
+        executionId: string;
+        stepId: string;
+        iteration: number;
+    }) => Promise<Config>;
+    executeTurn: (args: CodexExecuteTurnArgs<Context, Config, Env>) => Promise<CodexTurnResult>;
+    mapChunk?: (providerChunk: unknown) => CodexChunkMappingResult | null;
+    includeStreamTraceInOutput?: boolean;
+    includeRawProviderChunksInOutput?: boolean;
+    maxPersistedStreamChunks?: number;
+    onMappedChunk?: (chunk: CodexMappedChunk, params: ContextReactorParams<Context, Env>) => Promise<void> | void;
+};
+export declare function mapCodexChunkType(providerChunkType: string): ContextStreamChunkType;
+export declare function mapCodexAppServerNotification(providerChunk: unknown): CodexChunkMappingResult | null;
+export declare function defaultMapCodexChunk(providerChunk: unknown): CodexChunkMappingResult;
+/**
+ * Codex App Server reactor for @ekairos/events.
+ *
+ * This maps one Context loop iteration to one Codex turn and returns a persisted
+ * assistant event compatible with the Context engine.
+ *
+ * Workflow compatibility:
+ * - `resolveConfig` and `executeTurn` should be implemented with `"use step"`
+ *   wrappers when they perform I/O.
+ */
+export declare function createCodexReactor<Context, Config extends CodexConfig = CodexConfig, Env extends ContextEnvironment = ContextEnvironment>(options: CreateCodexReactorOptions<Context, Config, Env>): ContextReactor<Context, Env>;
+//# sourceMappingURL=codex.reactor.d.ts.map

package/dist/codex.reactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.reactor.d.ts","sourceRoot":"","sources":["../src/codex.reactor.ts"],"names":[],"mappings":"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"}