@soederpop/luca 0.1.2 → 0.1.3

package/dist/agi/features/openai-codex.d.ts

@@ -0,0 +1,381 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+declare module '@soederpop/luca/feature' {
+    interface AvailableFeatures {
+        openaiCodex: typeof OpenAICodex;
+    }
+}
+export interface CodexItem {
+    id: string;
+    type: 'agent_message' | 'reasoning' | 'command_execution' | string;
+    text?: string;
+    command?: string;
+    aggregated_output?: string;
+    exit_code?: number | null;
+    status?: 'in_progress' | 'completed' | string;
+}
+export interface CodexItemEvent {
+    type: 'item.completed' | 'item.started';
+    item: CodexItem;
+}
+export interface CodexTurnEvent {
+    type: 'turn.completed' | 'turn.started';
+    usage?: {
+        input_tokens?: number;
+        cached_input_tokens?: number;
+        output_tokens?: number;
+    };
+}
+export interface CodexThreadEvent {
+    type: 'thread.started';
+    thread_id: string;
+}
+/** Normalized message emitted via session:message for downstream consumers. */
+export interface CodexMessageEvent {
+    type: 'message';
+    role: 'assistant' | 'system';
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: string;
+        [key: string]: any;
+    }>;
+}
+export interface CodexExecEvent {
+    type: 'exec';
+    command: string;
+    cwd?: string;
+    exit_code?: number | null;
+    stdout?: string;
+    stderr?: string;
+}
+export type CodexEvent = CodexItemEvent | CodexTurnEvent | CodexThreadEvent | {
+    type: string;
+    [key: string]: any;
+};
+export interface CodexSession {
+    id: string;
+    status: 'idle' | 'running' | 'completed' | 'error';
+    prompt: string;
+    result?: string;
+    error?: string;
+    turns: number;
+    messages: CodexMessageEvent[];
+    executions: CodexExecEvent[];
+    items: CodexItem[];
+    process?: any;
+    threadId?: string;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+    };
+}
+export declare const OpenAICodexStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    sessions: z.ZodRecord<z.ZodString, z.ZodAny>;
+    activeSessions: z.ZodArray<z.ZodString>;
+    codexAvailable: z.ZodBoolean;
+    codexVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const OpenAICodexOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    codexPath: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    sandbox: z.ZodOptional<z.ZodEnum<{
+        "read-only": "read-only";
+        "workspace-write": "workspace-write";
+        "danger-full-access": "danger-full-access";
+    }>>;
+    approvalMode: z.ZodOptional<z.ZodEnum<{
+        suggest: "suggest";
+        "auto-edit": "auto-edit";
+        "full-auto": "full-auto";
+    }>>;
+    projectDoc: z.ZodOptional<z.ZodString>;
+    noProjectDoc: z.ZodOptional<z.ZodBoolean>;
+    fullStdout: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const OpenAICodexEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    'session:start': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        prompt: z.ZodString;
+    }, z.core.$strip>], null>;
+    'session:event': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        event: z.ZodAny;
+    }, z.core.$strip>], null>;
+    'session:delta': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        text: z.ZodString;
+        role: z.ZodString;
+    }, z.core.$strip>], null>;
+    'session:message': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        message: z.ZodAny;
+    }, z.core.$strip>], null>;
+    'session:exec': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        exec: z.ZodAny;
+    }, z.core.$strip>], null>;
+    'session:exec-start': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        command: z.ZodString;
+    }, z.core.$strip>], null>;
+    'session:reasoning': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strip>], null>;
+    'session:result': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        result: z.ZodString;
+    }, z.core.$strip>], null>;
+    'session:error': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        error: z.ZodAny;
+        exitCode: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>], null>;
+    'session:abort': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+    }, z.core.$strip>], null>;
+    'session:parse-error': z.ZodTuple<[z.ZodObject<{
+        sessionId: z.ZodString;
+        line: z.ZodString;
+    }, z.core.$strip>], null>;
+}, z.core.$strip>;
+export type OpenAICodexState = z.infer<typeof OpenAICodexStateSchema>;
+export type OpenAICodexOptions = z.infer<typeof OpenAICodexOptionsSchema>;
+export interface CodexRunOptions {
+    model?: string;
+    cwd?: string;
+    sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access';
+    approvalMode?: 'suggest' | 'auto-edit' | 'full-auto';
+    projectDoc?: string;
+    noProjectDoc?: boolean;
+    fullStdout?: boolean;
+    images?: string[];
+    fullAuto?: boolean;
+    /** Resume a previous session by ID. */
+    resumeSessionId?: string;
+    /** Resume the most recent session. */
+    resumeLast?: boolean;
+    /** Skip all approvals and sandboxing. */
+    dangerouslyAutoApproveEverything?: boolean;
+    /** Additional CLI flags. */
+    extraArgs?: string[];
+}
+/**
+ * OpenAI Codex CLI wrapper feature. Spawns and manages Codex sessions
+ * as subprocesses, streaming structured JSON events back through the
+ * container's event system.
+ *
+ * Mirrors the ClaudeCode feature pattern: each call to `run()` spawns a
+ * `codex exec --json` process, parses NDJSON from stdout line-by-line,
+ * and emits typed events on the feature's event bus.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const codex = container.feature('openaiCodex')
+ *
+ * // Listen for events
+ * codex.on('session:message', ({ sessionId, message }) => console.log(message))
+ * codex.on('session:patch', ({ sessionId, patch }) => console.log('File changed:', patch.path))
+ *
+ * // Run a prompt
+ * const session = await codex.run('Fix the failing tests in src/')
+ * console.log(session.result)
+ * ```
+ */
+export declare class OpenAICodex extends Feature<OpenAICodexState, OpenAICodexOptions> {
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        sessions: z.ZodRecord<z.ZodString, z.ZodAny>;
+        activeSessions: z.ZodArray<z.ZodString>;
+        codexAvailable: z.ZodBoolean;
+        codexVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        codexPath: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodString>;
+        sandbox: z.ZodOptional<z.ZodEnum<{
+            "read-only": "read-only";
+            "workspace-write": "workspace-write";
+            "danger-full-access": "danger-full-access";
+        }>>;
+        approvalMode: z.ZodOptional<z.ZodEnum<{
+            suggest: "suggest";
+            "auto-edit": "auto-edit";
+            "full-auto": "full-auto";
+        }>>;
+        projectDoc: z.ZodOptional<z.ZodString>;
+        noProjectDoc: z.ZodOptional<z.ZodBoolean>;
+        fullStdout: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        'session:start': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            prompt: z.ZodString;
+        }, z.core.$strip>], null>;
+        'session:event': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            event: z.ZodAny;
+        }, z.core.$strip>], null>;
+        'session:delta': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            text: z.ZodString;
+            role: z.ZodString;
+        }, z.core.$strip>], null>;
+        'session:message': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            message: z.ZodAny;
+        }, z.core.$strip>], null>;
+        'session:exec': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            exec: z.ZodAny;
+        }, z.core.$strip>], null>;
+        'session:exec-start': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            command: z.ZodString;
+        }, z.core.$strip>], null>;
+        'session:reasoning': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            text: z.ZodString;
+        }, z.core.$strip>], null>;
+        'session:result': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            result: z.ZodString;
+        }, z.core.$strip>], null>;
+        'session:error': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            error: z.ZodAny;
+            exitCode: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>], null>;
+        'session:abort': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+        }, z.core.$strip>], null>;
+        'session:parse-error': z.ZodTuple<[z.ZodObject<{
+            sessionId: z.ZodString;
+            line: z.ZodString;
+        }, z.core.$strip>], null>;
+    }, z.core.$strip>;
+    static shortcut: "features.openaiCodex";
+    get initialState(): OpenAICodexState;
+    private _resolvedCodexPath;
+    /** @returns The path to the codex CLI binary, falling back to 'codex' on the PATH. */
+    get codexPath(): string;
+    /**
+     * Check if the Codex CLI is available and capture its version.
+     *
+     * @returns {Promise<boolean>} True if the codex binary was found and responded to --version
+     */
+    checkAvailability(): Promise<boolean>;
+    /**
+     * Build the argument array for a codex CLI invocation.
+     */
+    private buildArgs;
+    private createSessionId;
+    private updateSession;
+    /**
+     * Process a parsed JSON event from the Codex CLI stream.
+     *
+     * The codex CLI (codex exec --json) emits NDJSON with these event types:
+     *   thread.started   — { thread_id }
+     *   turn.started     — (no payload)
+     *   item.started     — { item: { id, type, ... } }
+     *   item.completed   — { item: { id, type, text?, command?, exit_code?, ... } }
+     *   turn.completed   — { usage: { input_tokens, output_tokens } }
+     *
+     * Item types within item.completed:
+     *   agent_message      — assistant text response
+     *   reasoning          — model thinking/reasoning
+     *   command_execution  — shell command with output
+     */
+    private handleEvent;
+    /**
+     * Run a prompt in a new Codex session. Spawns a subprocess,
+     * streams NDJSON events, and resolves when the session completes.
+     *
+     * @param {string} prompt - The natural language instruction for the Codex agent
+     * @param {CodexRunOptions} [options] - Optional overrides for model, cwd, sandbox policy, etc.
+     * @returns {Promise<CodexSession>} The completed session with result, messages, patches, and executions
+     *
+     * @example
+     * ```typescript
+     * const session = await codex.run('Fix the failing tests')
+     * console.log(session.result)
+     *
+     * const session = await codex.run('Refactor the auth module', {
+     *   model: 'o4-mini',
+     *   fullAuto: true,
+     *   cwd: '/path/to/project'
+     * })
+     * ```
+     */
+    run(prompt: string, options?: CodexRunOptions): Promise<CodexSession>;
+    /**
+     * Run a prompt without waiting for completion. Returns the session ID
+     * immediately so you can subscribe to events.
+     *
+     * @param {string} prompt - The natural language instruction for the Codex agent
+     * @param {CodexRunOptions} [options] - Optional overrides for model, cwd, sandbox policy, etc.
+     * @returns {string} The session ID, which can be used with getSession() or waitForSession()
+     *
+     * @example
+     * ```typescript
+     * const sessionId = codex.start('Build a REST API for users')
+     *
+     * codex.on('session:delta', ({ sessionId: sid, text }) => {
+     *   if (sid === sessionId) process.stdout.write(text)
+     * })
+     * ```
+     */
+    start(prompt: string, options?: CodexRunOptions): string;
+    private consumeStream;
+    /**
+     * Kill a running session's subprocess.
+     *
+     * @param {string} sessionId - The session ID to abort
+     * @returns {void}
+     */
+    abort(sessionId: string): void;
+    /**
+     * Retrieve the current state of a session by its ID.
+     *
+     * @param {string} sessionId - The session ID to look up
+     * @returns {CodexSession | undefined} The session object, or undefined if not found
+     */
+    getSession(sessionId: string): CodexSession | undefined;
+    /**
+     * Wait for a running session to complete or error. Resolves immediately
+     * if the session is already in a terminal state.
+     *
+     * @param {string} sessionId - The session ID to wait for
+     * @returns {Promise<CodexSession>} The completed or errored session
+     * @throws {Error} If the session ID is not found
+     */
+    waitForSession(sessionId: string): Promise<CodexSession>;
+    /**
+     * Enable the feature. Delegates to the base Feature enable() lifecycle.
+     *
+     * @param {object} [options] - Options to merge into the feature configuration
+     * @returns {Promise<this>} This instance, for chaining
+     */
+    enable(options?: any): Promise<this>;
+}
+export default OpenAICodex;
+//# sourceMappingURL=openai-codex.d.ts.map

package/dist/agi/features/openai-codex.d.ts.map

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

package/dist/agi/features/openapi.d.ts

@@ -0,0 +1,200 @@
+import { Feature } from '../feature.js';
+import { z } from 'zod';
+declare module '../../feature.js' {
+    interface AvailableFeatures {
+        openapi: typeof OpenAPI;
+    }
+}
+export declare const OpenAPIStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    loaded: z.ZodDefault<z.ZodBoolean>;
+    title: z.ZodDefault<z.ZodString>;
+    version: z.ZodDefault<z.ZodString>;
+    endpointCount: z.ZodDefault<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const OpenAPIOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const OpenAPIEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    loaded: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+export type OpenAPIOptions = z.infer<typeof OpenAPIOptionsSchema>;
+export type OpenAPIState = z.infer<typeof OpenAPIStateSchema>;
+export interface EndpointInfo {
+    /** Human-friendly camelCase name derived from operationId */
+    name: string;
+    /** Original operationId from the spec */
+    operationId: string;
+    /** HTTP method (get, post, put, delete, patch, etc.) */
+    method: string;
+    /** URL path template, e.g. /pets/{petId} */
+    path: string;
+    /** Summary from the spec */
+    summary: string;
+    /** Longer description from the spec */
+    description: string;
+    /** Tags for grouping */
+    tags: string[];
+    /** Parameter definitions from the spec */
+    parameters: OpenAPIParameter[];
+    /** Request body schema if present */
+    requestBody: any;
+    /** Response definitions keyed by status code */
+    responses: Record<string, any>;
+    /** Whether the endpoint is deprecated */
+    deprecated: boolean;
+}
+export interface OpenAPIParameter {
+    name: string;
+    in: 'query' | 'path' | 'header' | 'cookie';
+    description: string;
+    required: boolean;
+    schema: any;
+}
+export interface OpenAIFunctionDef {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, any>;
+        required: string[];
+    };
+}
+export interface OpenAIToolDef {
+    type: 'function';
+    function: OpenAIFunctionDef;
+}
+/**
+ * The OpenAPI feature loads an OpenAPI/Swagger spec from a URL and provides
+ * inspection and conversion utilities.
+ *
+ * Works in both browser and node environments since it uses fetch.
+ *
+ * @example
+ * ```typescript
+ * const api = container.feature('openapi', { url: 'https://petstore.swagger.io/v2' })
+ * await api.load()
+ *
+ * // Inspect all endpoints
+ * api.endpoints
+ *
+ * // Get a single endpoint by its friendly name
+ * api.endpoint('getPetById')
+ *
+ * // Convert to OpenAI tool definitions
+ * api.toTools()
+ *
+ * // Convert a single endpoint to a function definition
+ * api.toFunction('getPetById')
+ * ```
+ */
+export declare class OpenAPI extends Feature<OpenAPIState, OpenAPIOptions> {
+    static shortcut: "features.openapi";
+    static description: string;
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        loaded: z.ZodDefault<z.ZodBoolean>;
+        title: z.ZodDefault<z.ZodString>;
+        version: z.ZodDefault<z.ZodString>;
+        endpointCount: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        loaded: z.ZodTuple<[z.ZodAny], null>;
+    }, z.core.$strip>;
+    /** Raw parsed spec document */
+    private _spec;
+    /** Parsed endpoint map keyed by friendly name */
+    private _endpoints;
+    /** @returns Default state with loaded=false and empty metadata fields. */
+    get initialState(): OpenAPIState;
+    /** The base server URL derived from options, normalizing the openapi.json suffix */
+    get serverUrl(): string;
+    /** The URL that will be fetched for the spec document */
+    get specUrl(): string;
+    /** The raw spec object. Null before load() is called. */
+    get spec(): any;
+    /**
+     * Fetches and parses the OpenAPI spec from the configured URL.
+     * Populates `endpoints`, updates state with spec metadata.
+     *
+     * @returns {Promise<this>} This instance, for chaining
+     */
+    load(): Promise<this>;
+    /** All parsed endpoints as an array */
+    get endpoints(): EndpointInfo[];
+    /** All endpoint friendly names */
+    get endpointNames(): string[];
+    /** Map of endpoints grouped by tag */
+    get endpointsByTag(): Record<string, EndpointInfo[]>;
+    /**
+     * Get a single endpoint by its friendly name or operationId.
+     *
+     * @param {string} name - The friendly name or operationId to look up
+     * @returns {EndpointInfo | undefined} The endpoint info, or undefined if not found
+     */
+    endpoint(name: string): EndpointInfo | undefined;
+    /**
+     * Convert all endpoints into OpenAI-compatible tool definitions.
+     *
+     * @param {Function} [filter] - Optional predicate to select which endpoints to include
+     * @returns {OpenAIToolDef[]} Array of tool definitions ready for the OpenAI tools parameter
+     */
+    toTools(filter?: (ep: EndpointInfo) => boolean): OpenAIToolDef[];
+    /**
+     * Convert a single endpoint (by name) to an OpenAI-compatible tool definition.
+     *
+     * @param {string} name - The endpoint friendly name or operationId
+     * @returns {OpenAIToolDef | undefined} The tool definition, or undefined if not found
+     */
+    toTool(name: string): OpenAIToolDef | undefined;
+    /**
+     * Convert all endpoints into OpenAI-compatible function definitions.
+     *
+     * @param {Function} [filter] - Optional predicate to select which endpoints to include
+     * @returns {OpenAIFunctionDef[]} Array of function definitions
+     */
+    toFunctions(filter?: (ep: EndpointInfo) => boolean): OpenAIFunctionDef[];
+    /**
+     * Convert a single endpoint (by name) to an OpenAI function definition.
+     *
+     * @param {string} name - The endpoint friendly name or operationId
+     * @returns {OpenAIFunctionDef | undefined} The function definition, or undefined if not found
+     */
+    toFunction(name: string): OpenAIFunctionDef | undefined;
+    /**
+     * Return a compact JSON summary of all endpoints, useful for logging or REPL inspection.
+     *
+     * @returns {{ title: string, version: string, serverUrl: string, endpointCount: number, endpoints: object[] }} Serializable summary
+     */
+    toJSON(): {
+        title: string | undefined;
+        version: string | undefined;
+        serverUrl: string;
+        endpointCount: number;
+        endpoints: {
+            name: string;
+            method: string;
+            path: string;
+            summary: string;
+            tags: string[];
+            deprecated: boolean;
+        }[];
+    };
+}
+export default OpenAPI;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/agi/features/openapi.d.ts.map

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