@makaio/client-codex 1.0.0-dev-1779051654000

package/dist/definition.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Client definition for the OpenAI Codex CLI.
+ *
+ * Codex is a first-party agentic coding assistant binary (`codex`) that
+ * Makaio harnesses via the codex-app-server adapter. Capability annotations
+ * are derived from `codexCapabilityMap` in `@makaio/contracts` to keep
+ * capability taxonomy in a single canonical location.
+ * @packageDocumentation
+ */
+/**
+ * Static client definition for `@makaio/client-codex`.
+ *
+ * Declares the two native tools the `codex` binary exposes (`bash` and
+ * `patch`) and the recommended default approval policy for new harnesses
+ * targeting this client.
+ */
+export declare const clientDefinition: {
+    id: string;
+    name: string;
+    version: string;
+    description?: string | undefined;
+    binary?: {
+        name: string;
+        supportedVersions: string;
+    } | undefined;
+    nativeTools: {
+        name: string;
+        friendlyName: string;
+        description?: string | undefined;
+        category?: string | undefined;
+        capabilities: {
+            tag: string;
+            description?: string | undefined;
+        }[];
+    }[];
+    defaultApprovalPolicy: "always-ask" | "full-access" | "reject";
+    logSources?: {
+        id: string;
+        name: string;
+        description?: string | undefined;
+        glob?: string | undefined;
+    }[] | undefined;
+    defaultProviderId?: string | undefined;
+    runtimeCapabilities: {
+        supportsHooks: boolean;
+        supportsStatusline: boolean;
+        supportsSupervisorLaunch: boolean;
+        supportsManagedBinary: boolean;
+        hookEvents: {
+            name: string;
+            frameworkSubject?: string | undefined;
+        }[];
+    };
+    managedInstall?: {
+        type: "npm";
+        package: string;
+        version: string;
+    } | {
+        type: "signed-binary-bucket";
+        version: string;
+        config: {
+            baseUrl: string;
+            manifestPathTemplate: string;
+            manifestSignaturePathTemplate: string;
+            publicKeyUrl: string;
+            publicKeyFingerprint: string;
+            binaryPathTemplate: string;
+            platforms: Record<string, string>;
+        };
+    } | undefined;
+    versionCommand?: {
+        executable: string | {
+            default: string;
+            darwin?: string | undefined;
+            linux?: string | undefined;
+            win32?: string | undefined;
+        };
+        args: string[];
+    } | undefined;
+    postInstall?: {
+        kind: string;
+        payload?: Record<string, unknown> | undefined;
+    } | undefined;
+    configIsolation?: {
+        envVar: string;
+        defaultPath: string;
+        pathKind: "directory" | "file";
+    } | undefined;
+};
+//# sourceMappingURL=definition.d.ts.map

package/dist/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwD3B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { clientDefinition } from './definition.js';
+/** Codex client package descriptor for unified package discovery. */
+export { codexPackage } from './package.js';
+export { AbsolutePathSchema, CodexConfigHooksAddRequestSchema, CodexConfigHooksAddResponseSchema, CodexConfigHooksListRequestSchema, CodexConfigHooksListResponseSchema, CodexConfigHooksRemoveRequestSchema, CodexConfigHooksRemoveResponseSchema, CodexConfigSchemas, CodexHookEntrySchema, CodexNativeCommandHookSchema, CodexNativeHookMatcherGroupSchema, CodexNativeHooksFileSchema, CodexScopeHookRecordSchema, CodexScopeSchema, CodexWiringSchemas, } from './schemas/index.js';
+export type { CodexConfigHooksAddRequest, CodexConfigHooksAddResponse, CodexConfigHooksListRequest, CodexConfigHooksListResponse, CodexConfigHooksRemoveRequest, CodexConfigHooksRemoveResponse, CodexHookEntry, CodexNativeCommandHook, CodexNativeHookMatcherGroup, CodexNativeHooksFile, CodexScope, CodexScopeHookRecord, CodexWiringApplyRequest, CodexWiringListRequest, CodexWiringRemoveRequest, } from './schemas/index.js';
+export { CodexClientSessionService } from './runtime/codex-client-session-service.js';
+export { CodexClientSubjects } from './runtime/namespace.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,qEAAqE;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,kBAAkB,EAClB,gCAAgC,EAChC,iCAAiC,EACjC,iCAAiC,EACjC,kCAAkC,EAClC,mCAAmC,EACnC,oCAAoC,EACpC,kBAAkB,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,iCAAiC,EACjC,0BAA0B,EAC1B,0BAA0B,EAC1B,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,2BAA2B,EAC3B,4BAA4B,EAC5B,6BAA6B,EAC7B,8BAA8B,EAC9B,cAAc,EACd,sBAAsB,EACtB,2BAA2B,EAC3B,oBAAoB,EACpB,UAAU,EACV,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.mjs

@@ -0,0 +1,4 @@
+import { _ as CodexNativeHooksFileSchema, a as CodexWiringSchemas, b as clientDefinition, c as CodexConfigHooksAddResponseSchema, d as CodexConfigHooksRemoveRequestSchema, f as CodexConfigHooksRemoveResponseSchema, g as CodexNativeHookMatcherGroupSchema, h as CodexNativeCommandHookSchema, l as CodexConfigHooksListRequestSchema, m as CodexHookEntrySchema, o as AbsolutePathSchema, p as CodexConfigSchemas, r as CodexClientSubjects, s as CodexConfigHooksAddRequestSchema, t as CodexClientSessionService, u as CodexConfigHooksListResponseSchema, v as CodexScopeHookRecordSchema, y as CodexScopeSchema } from "./codex-client-session-service-DD2LkxP1.mjs";
+import { t as codexPackage } from "./src-DkIyzWF3.mjs";
+
+export { AbsolutePathSchema, CodexClientSessionService, CodexClientSubjects, CodexConfigHooksAddRequestSchema, CodexConfigHooksAddResponseSchema, CodexConfigHooksListRequestSchema, CodexConfigHooksListResponseSchema, CodexConfigHooksRemoveRequestSchema, CodexConfigHooksRemoveResponseSchema, CodexConfigSchemas, CodexHookEntrySchema, CodexNativeCommandHookSchema, CodexNativeHookMatcherGroupSchema, CodexNativeHooksFileSchema, CodexScopeHookRecordSchema, CodexScopeSchema, CodexWiringSchemas, clientDefinition, codexPackage };

package/dist/package.d.ts

@@ -0,0 +1,18 @@
+import type { IMakaioBus } from '@makaio/framework/bus';
+/**
+ * MakaioNodeExtension<IMakaioBus> descriptor for the Codex client.
+ *
+ * Wraps the existing {@link clientDefinition} in the standard
+ * `MakaioNodeExtension<IMakaioBus>` shape so the runtime coordinator can discover and
+ * register this client through the unified client contribution surface.
+ */
+import type { MakaioNodeExtension } from '@makaio/framework/contracts';
+/**
+ * Package descriptor for the Codex client.
+ *
+ * Declares the OpenAI Codex CLI binary (`codex`) as a first-party agentic
+ * coding assistant client with hook and supervisor-launch support and a
+ * default `full-access` approval policy.
+ */
+export declare const codexPackage: MakaioNodeExtension<IMakaioBus>;
+//# sourceMappingURL=package.d.ts.map

package/dist/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../src/package.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,mBAAmB,CAAC,UAAU,CAKxD,CAAC"}

package/dist/runtime/client-settings.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Codex client settings I/O.
+ *
+ * Provides filesystem read/write operations for Codex `hooks.json`
+ * configuration files. Handles both global and project-scoped config files
+ * with atomic writes and per-path write serialization to prevent concurrent
+ * modification.
+ * @packageDocumentation
+ */
+import type { CodexScope, CodexConfigHooksListResponse, CodexConfigHooksAddResponse, CodexConfigHooksRemoveResponse } from '../schemas/config.js';
+/**
+ * Optional path override injected during testing.
+ * When provided, {@link CodexClientSettings} uses these paths instead of
+ * calling {@link resolveCodexSettingsPaths}.
+ */
+export interface CodexClientSettingsPathsOverride {
+    /**
+     * Absolute path to the global `hooks.json` file.
+     */
+    readonly globalHooks: string;
+    /**
+     * Absolute path to the project-scoped `hooks.json` file, or `null`.
+     */
+    readonly projectHooks: string | null;
+}
+/**
+ * Path resolution options for {@link CodexClientSettings}.
+ */
+export interface CodexClientSettingsOptions {
+    /** Optional managed Codex config root used for global-scope hooks. */
+    readonly configDir?: string;
+    /** Optional exact path override used by tests. */
+    readonly pathsOverride?: CodexClientSettingsPathsOverride;
+}
+/**
+ * Handles reading and writing Codex `hooks.json` configuration files.
+ *
+ * This is a plain composed component — not a `BaseService` — intended to be
+ * instantiated inside `CodexClientSessionService` or a similar host.
+ *
+ * ## Atomic writes
+ * All writes go through a temp-file + `fs.rename()` sequence so that readers
+ * never see a partially written file.
+ *
+ * ## Write serialization
+ * A module-scoped per-path mutex ensures that concurrent callers modifying
+ * the same file are serialized rather than racing, even across instances.
+ */
+export declare class CodexClientSettings {
+    /**
+     * Optional path override used in tests. When `undefined`, paths are
+     * resolved dynamically via {@link resolveCodexSettingsPaths}.
+     */
+    private readonly pathsOverride;
+    /** Optional managed Codex config root for global-scope hooks. */
+    private readonly configDir;
+    /**
+     * Creates a new `CodexClientSettings` instance.
+     * @param options - Optional path override or config-root options. Passing
+     *   `{ globalHooks, projectHooks }` remains supported for existing tests.
+     */
+    constructor(options?: CodexClientSettingsPathsOverride | CodexClientSettingsOptions);
+    /**
+     * List the effective hook configuration for a project directory.
+     *
+     * Reads both the global and (when available) project-scoped config files,
+     * concatenates their hooks into an effective list, and returns the per-scope
+     * breakdown alongside it.
+     * @param req - Request options. `projectDir` is the optional absolute path to
+     *   the project root (when omitted only the global scope is read).
+     *   `eventName` is an optional event name filter; when omitted all hooks are
+     *   returned.
+     * @returns Effective merged hook list and per-scope breakdown.
+     */
+    listHooks(req: {
+        projectDir?: string;
+        eventName?: string;
+    }): Promise<CodexConfigHooksListResponse>;
+    /**
+     * Add a new hook entry to the specified config scope.
+     *
+     * The operation is idempotent: if a hook with the same `event`, `command`,
+     * and `matcher` already exists in the target file, the file is left
+     * unchanged and `{ added: false }` is returned.
+     * @param req - Hook entry and targeting options. `scope` selects the config
+     *   file; `projectDir` is required when `scope` is `'project'`. `event`,
+     *   `command`, and optional `matcher` / `timeout` form the hook entry.
+     * @returns `{ added: true }` when the hook was appended, `{ added: false }`
+     *   when an identical hook already exists.
+     */
+    addHook(req: {
+        projectDir?: string;
+        scope: CodexScope;
+        event: string;
+        matcher?: string;
+        command: string;
+        timeout?: number;
+    }): Promise<CodexConfigHooksAddResponse>;
+    /**
+     * Remove hook entries from the specified config scope.
+     *
+     * Removes all hooks where `entry.event === req.event` and
+     * `entry.command.includes(req.match.commandContains)`.
+     * @param req - Removal criteria and targeting options. `scope` selects the
+     *   config file; `projectDir` is required when `scope` is `'project'`.
+     *   `event` is the event name to match. `match.commandContains` is the
+     *   command substring filter — any hook whose command contains this string
+     *   is removed.
+     * @returns `{ removed: n }` where `n` is the count of removed hooks.
+     */
+    removeHook(req: {
+        projectDir?: string;
+        scope: CodexScope;
+        event: string;
+        match: {
+            commandContains: string;
+        };
+    }): Promise<CodexConfigHooksRemoveResponse>;
+    /**
+     * Resolve config file path for a given scope.
+     *
+     * For `'project'` scope, `projectDir` must be provided. For `'global'`
+     * scope, `projectDir` is ignored.
+     * @param scope - Target config scope.
+     * @param projectDir - Optional absolute path to the project root.
+     * @returns Absolute path to the `hooks.json` file for the given scope.
+     * @throws When `scope === 'project'` and `projectDir` is absent.
+     */
+    private resolvePathForScope;
+    /**
+     * Resolve settings paths, applying the optional test override when present.
+     * @param projectDir - Optional project root passed through to
+     *   {@link resolveCodexSettingsPaths} when no override is active.
+     * @returns Resolved settings paths.
+     */
+    private resolvePaths;
+    private isWritable;
+    private readHooksFile;
+    private readHooksDocument;
+    /**
+     * Flatten a native Codex hooks document into the public command-hook view.
+     * @param document - Native Codex hooks document.
+     * @returns Flat command-hook entries ordered by event, matcher group, then
+     *   handler order.
+     */
+    private flattenHooksFile;
+    private modifyHooksFile;
+}
+//# sourceMappingURL=client-settings.d.ts.map

package/dist/runtime/client-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-settings.d.ts","sourceRoot":"","sources":["../../src/runtime/client-settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAEV,UAAU,EAGV,4BAA4B,EAC5B,2BAA2B,EAC3B,8BAA8B,EAC/B,MAAM,sBAAsB,CAAC;AAiB9B;;;;GAIG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,gCAAgC,CAAC;CAC3D;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAmB;IAC9B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+C;IAC7E,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAE/C;;;;OAIG;IACH,YAAmB,OAAO,CAAC,EAAE,gCAAgC,GAAG,0BAA0B,EAQzF;IAMD;;;;;;;;;;;OAWG;IACU,SAAS,CAAC,GAAG,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,4BAA4B,CAAC,CA+B9G;IAED;;;;;;;;;;;OAWG;IACU,OAAO,CAAC,GAAG,EAAE;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,UAAU,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAsDvC;IAED;;;;;;;;;;;OAWG;IACU,UAAU,CAAC,GAAG,EAAE;QAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,UAAU,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE;YAAE,eAAe,EAAE,MAAM,CAAA;SAAE,CAAC;KACpC,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAqC1C;IAMD;;;;;;;;;OASG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;YAmBN,UAAU;YAmCV,aAAa;YAeb,iBAAiB;IAmB/B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;YAoCV,eAAe;CAsB9B"}

package/dist/runtime/codex-client-session-service.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Codex client session normalization service.
+ *
+ * Subscribes to raw Codex hook events on `client:codex.hook.received` and
+ * emits the corresponding normalized `client.session.*` observations via
+ * {@link normalizeCodexHook}.
+ *
+ * Also handles config management requests on `client:codex.config.hooks.*`
+ * subjects. Before constructing settings I/O, the service resolves the active
+ * config directory via `client.resolveBinary` and uses that as the global
+ * Codex config root, falling back to native `~/.codex` paths when no resolver
+ * or global binary is available. Wiring requests use the same settings path
+ * resolution. The service also handles the blocking `client:codex.config.prime`
+ * lifecycle hook and the `client:codex.sessionConfig.setup` delegation subject
+ * for per-session config directory initialization.
+ *
+ * Unknown or not-yet-modeled event names are silently dropped — they stay
+ * raw-only inside the `client:codex.*` namespace and are never forwarded to
+ * the global `client.*` namespace.
+ *
+ * ## Adapter-managed session gate
+ *
+ * When both the native-hook ingress and the adapter-derived path are active for
+ * the same Codex process, `client.session.started` would otherwise be emitted
+ * twice.  The service listens to `client.runtime.started` events: when an event
+ * arrives with `clientId === CLIENT_ID`, `source.layer === 'adapter'`, and a
+ * non-empty `adapterSessionId`, that session ID is recorded as adapter-managed.
+ * Any subsequent normalized hook for the same `adapterSessionId` is then
+ * silently dropped — the adapter path already owns the canonical emission.
+ * Sessions whose `adapterSessionId` is absent or not yet registered emit as
+ * before (fail-open).  Events from other clients (e.g. `'claude-code'`,
+ * `'gemini'`) are ignored unconditionally — their adapter sessions must not
+ * suppress Codex hook emissions.
+ *
+ * The managed-session set is bounded at {@link MANAGED_SESSION_CAP} entries to
+ * prevent unbounded growth in long-lived processes.  When the cap is reached,
+ * the oldest recorded session ID is evicted before inserting the new one
+ * (FIFO).
+ * @packageDocumentation
+ */
+import type { IMakaioBus } from '@makaio/framework/bus';
+import { BaseService } from '@makaio/framework/service-base';
+import { CodexClientSettings } from './client-settings.js';
+/**
+ * Maximum number of adapter-managed session IDs retained in
+ * {@link CodexClientSessionService.managedAdapterSessionIds}.
+ *
+ * Concurrent active Codex sessions are typically single-digit, so this
+ * cap is a safety net against unbounded growth in long-lived processes.  When
+ * the cap is reached, the oldest recorded ID is evicted (FIFO) before the new
+ * one is inserted.
+ */
+export declare const MANAGED_SESSION_CAP = 10000;
+/**
+ * Service that normalizes raw Codex hook events into global
+ * `client.session.*` observed-semantics events and handles Codex config
+ * management requests on `client:codex.config.hooks.*`.
+ *
+ * Lifecycle:
+ * 1. `init()` — subscribes to `client:codex.hook.received`, subscribes to
+ *    `client.runtime.started` for the adapter-managed session gate, and
+ *    registers request handlers for `config.hooks.list`, `config.hooks.add`,
+ *    `config.hooks.remove`, `config.prime`, `wiring.list`, `wiring.apply`,
+ *    `wiring.remove`, and `sessionConfig.setup`.
+ * 2. On each incoming raw event, calls {@link normalizeCodexHook}.
+ * 3. Emits the normalized subject when the event is recognized; silently
+ *    ignores unknown events.  Normalized `client.session.*` events are
+ *    suppressed when the `adapterSessionId` is already in the adapter-managed
+ *    set.
+ * 4. `destroy()` — unsubscribes all handlers automatically via `BaseService`.
+ */
+export declare class CodexClientSessionService extends BaseService {
+    /** Optional injected settings I/O delegate for tests. */
+    private readonly settingsOverride;
+    /** Cached active config-dir resolution; reset when the active Codex version changes. */
+    private cachedConfigDir;
+    /**
+     * Set of `adapterSessionId` values known to be owned by an adapter-managed
+     * Codex runtime.  Populated by {@link handleRuntimeStarted} when a
+     * `client.runtime.started` event arrives with `clientId === CLIENT_ID` and
+     * `source.layer === 'adapter'`.
+     *
+     * Bounded at {@link MANAGED_SESSION_CAP} entries — the oldest ID is evicted
+     * (FIFO) when the cap is reached.
+     *
+     * Used by {@link handleHookReceived} to gate duplicate `client.session.*`
+     * emissions for sessions that the adapter path already covers.
+     */
+    private readonly managedAdapterSessionIds;
+    /**
+     * Creates a new Codex client session service.
+     * @param bus - Bus instance used for subscribing and emitting events
+     * @param settings - Optional {@link CodexClientSettings} instance for tests
+     *   that need exact filesystem paths. Production callers should omit it so
+     *   the service can resolve the active managed config dir via the bus.
+     */
+    constructor(bus?: IMakaioBus, settings?: CodexClientSettings);
+    /**
+     * Register the raw hook ingress handler, config management request handlers,
+     * wiring management request handlers, the config-prime lifecycle handler,
+     * and the session config setup handler on the bus.
+     *
+     * Also subscribes to `client.runtime.started` to track adapter-managed
+     * sessions for the {@link handleHookReceived} suppression gate.
+     */
+    protected onInit(): void;
+    /**
+     * Clear the adapter-managed session ID set on teardown.
+     */
+    protected onDestroy(): void;
+    private createSettings;
+    /**
+     * Return the cached config directory promise, resolving it on first access.
+     *
+     * Missing binary resolution is a graceful fallback so config reads/writes can
+     * still target native Codex config paths in framework-only or global-only
+     * setups.
+     * @returns Absolute managed config dir, or `undefined` to use native paths.
+     */
+    private resolveConfigDir;
+    private doResolveConfigDir;
+    /**
+     * Record a runtime as adapter-managed when the evidence source is an adapter.
+     *
+     * Called for every `client.runtime.started` event.  Only events whose
+     * `clientId` equals `'codex'`, whose `source.layer` is `'adapter'`, and
+     * that carry a non-empty `adapterSessionId` update the managed-sessions gate.
+     * Events from other clients (e.g. `'claude-code'`, `'gemini'`) are ignored
+     * unconditionally — their adapter sessions must not suppress Codex hook
+     * emissions.  Non-adapter sources (e.g. `'supervisor'`, `'statusline'`) are
+     * also ignored to prevent accidental suppression of native hook paths.
+     *
+     * When the set reaches {@link MANAGED_SESSION_CAP}, the oldest entry is
+     * evicted before the new ID is inserted.
+     * @param payload - `client.runtime.started` payload
+     */
+    private handleRuntimeStarted;
+    private handleHookReceived;
+    /**
+     * Determine whether a normalized native hook belongs to an adapter-managed
+     * session whose global observed-semantics events are already emitted by the
+     * adapter layer.
+     * @param adapterSessionId - Adapter/session identifier from the normalized hook
+     * @returns True when the native hook should remain raw-only
+     */
+    private isAdapterManagedSession;
+}
+//# sourceMappingURL=codex-client-session-service.d.ts.map

package/dist/runtime/codex-client-session-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-client-session-service.d.ts","sourceRoot":"","sources":["../../src/runtime/codex-client-session-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAU3D;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,yBAA0B,SAAQ,WAAW;IACxD,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkC;IACnE,wFAAwF;IACxF,OAAO,CAAC,eAAe,CAA0C;IAEjE;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAqB;IAE9D;;;;;;OAMG;IACH,YAAmB,GAAG,GAAE,UAAsB,EAAE,QAAQ,CAAC,EAAE,mBAAmB,EAG7E;IAED;;;;;;;OAOG;IACH,UAAmB,MAAM,IAAI,IAAI,CA+DhC;IAED;;OAEG;IACH,UAAmB,SAAS,IAAI,IAAI,CAGnC;YAMa,cAAc;IAQ5B;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;YA0BV,kBAAkB;IAgBhC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,oBAAoB;YA0Bd,kBAAkB;IAgChC;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;CAGhC"}

package/dist/runtime/config-prime-handler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Codex config-prime handler.
+ *
+ * Handles the `client:codex.config.prime` delegation subject fired by the
+ * framework at three lifecycle phases: `managed-install`, `profile-create`,
+ * and `session-create`.
+ *
+ * The handler ensures that `check_for_update_on_startup = false` is present
+ * in the Codex `config.toml` file inside the target directory so that managed
+ * Codex processes never attempt to auto-update during a Makaio-controlled
+ * session. All other existing config keys are preserved; the key is replaced
+ * when it already exists with any value, and appended when absent.
+ *
+ * Writes are atomic (tmp-file + rename) to prevent readers from observing a
+ * partially written file. The operation is idempotent: when the file already
+ * contains the correct value the write is skipped entirely.
+ * @packageDocumentation
+ */
+import type { ClientConfigPrimeRequest, ClientConfigPrimeResponse } from '@makaio/framework/contracts/client';
+/**
+ * Prime the Codex `config.toml` in the target config directory.
+ *
+ * Ensures that `check_for_update_on_startup = false` is set, preserving all
+ * other existing key-value pairs. Existing occurrences of the key (with any
+ * value) are replaced; the key is appended when absent. Empty lines are
+ * stripped to keep the file compact.
+ *
+ * The write is atomic via a temporary file + `fs.rename()` to prevent readers
+ * from observing a partially written file. The operation is idempotent: when
+ * the file already contains the correct value the disk is not touched.
+ * @param payload - Config prime request containing `clientId`, `configDir`,
+ *   and `phase`. Additional optional fields (`binaryVersion`, `adapterName`,
+ *   `projectDir`) are accepted but not used by the Codex prime handler.
+ * @returns `{ primed: true }` on success.
+ */
+export declare function handleCodexConfigPrime(payload: ClientConfigPrimeRequest): Promise<ClientConfigPrimeResponse>;
+//# sourceMappingURL=config-prime-handler.d.ts.map

package/dist/runtime/config-prime-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-prime-handler.d.ts","sourceRoot":"","sources":["../../src/runtime/config-prime-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAMpG;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAmClH"}

package/dist/runtime/hook-normalizer.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure normalizer for Codex CLI hook events.
+ *
+ * Maps the Codex-native hook event names emitted on
+ * `client:codex.hook.received` to their corresponding
+ * `client.session.*` observed-semantics subjects.
+ *
+ * **Mapping table** (Codex event → global subject):
+ *
+ * | Codex event name         | Global subject                          |
+ * |--------------------------|------------------------------------------|
+ * | `SessionStart`           | `client.session.started`                |
+ * | `UserPromptSubmit`       | `client.session.userPrompt.submitted`   |
+ * | `Stop`                   | `client.session.turn.completed`         |
+ * | `PreToolUse`             | `client.session.tool.pre`               |
+ * | `PostToolUse`            | `client.session.tool.post`              |
+ *
+ * All other event names are returned as `null` — they are kept raw only and
+ * are never emitted into the global `client.*` namespace.
+ *
+ * **Source notes:** The Codex CLI hook event names above reflect the OpenAI
+ * Codex CLI hook system as documented at the time of authoring. If the binary
+ * changes its hook names, update {@link CODEX_EVENT_MAP} accordingly.
+ * @packageDocumentation
+ */
+import { ClientSubjects } from '@makaio/framework/clients';
+import type { ClientSessionStarted, ClientSessionUserPromptSubmitted, ClientSessionTurnCompleted, ClientSessionToolPre, ClientSessionToolPost } from '@makaio/framework/contracts/client';
+import type { RawClientHookPayload } from './schemas.js';
+/**
+ * Union of all normalized subject definitions the Codex normalizer can emit.
+ *
+ * Used as the return type of {@link normalizeCodexHook} to keep downstream
+ * consumers type-safe without wide `SubjectDefinition` casts.
+ */
+export type CodexNormalizedSubject = typeof ClientSubjects.session.started | typeof ClientSubjects.session.userPrompt.submitted | typeof ClientSubjects.session.turn.completed | typeof ClientSubjects.session.tool.pre | typeof ClientSubjects.session.tool.post;
+/**
+ * Union of all normalized payload types the Codex normalizer can produce.
+ *
+ * Mirrors the `client.session.*` schema union so callers do not need to
+ * import individual payload types from `@makaio/contracts`.
+ */
+export type CodexNormalizedPayload = ClientSessionStarted | ClientSessionUserPromptSubmitted | ClientSessionTurnCompleted | ClientSessionToolPre | ClientSessionToolPost;
+/**
+ * Discriminated union of normalized Codex hook event results.
+ *
+ * Each variant pairs a specific `client.session.*` subject with its
+ * corresponding strongly-typed payload.  The caller switches on `subject`
+ * to obtain a narrowed payload type and call `bus.emit` without casts.
+ *
+ * When the event name is unknown, {@link normalizeCodexHook} returns `null`
+ * to signal that the event must stay raw-only.
+ */
+export type CodexNormalizedEvent = {
+    readonly subject: typeof ClientSubjects.session.started;
+    readonly payload: ClientSessionStarted;
+} | {
+    readonly subject: typeof ClientSubjects.session.userPrompt.submitted;
+    readonly payload: ClientSessionUserPromptSubmitted;
+} | {
+    readonly subject: typeof ClientSubjects.session.turn.completed;
+    readonly payload: ClientSessionTurnCompleted;
+} | {
+    readonly subject: typeof ClientSubjects.session.tool.pre;
+    readonly payload: ClientSessionToolPre;
+} | {
+    readonly subject: typeof ClientSubjects.session.tool.post;
+    readonly payload: ClientSessionToolPost;
+};
+/**
+ * Normalize a raw Codex hook payload into a `client.session.*` event.
+ *
+ * Returns `null` for unknown or not-yet-modeled event names so the caller
+ * skips global emission and keeps the event raw-only in `client:codex.*`.
+ * @param raw - Raw hook payload delivered on `client:codex.hook.received`
+ * @returns Normalized event with subject and typed payload, or `null` when
+ *   the event name is unknown
+ */
+export declare function normalizeCodexHook(raw: RawClientHookPayload): CodexNormalizedEvent | null;
+//# sourceMappingURL=hook-normalizer.d.ts.map

package/dist/runtime/hook-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-normalizer.d.ts","sourceRoot":"","sources":["../../src/runtime/hook-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,cAAc,EAAsB,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EACV,oBAAoB,EACpB,gCAAgC,EAChC,0BAA0B,EAC1B,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAC9B,OAAO,cAAc,CAAC,OAAO,CAAC,OAAO,GACrC,OAAO,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,GAClD,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,GAC5C,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,GACtC,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAC9B,oBAAoB,GACpB,gCAAgC,GAChC,0BAA0B,GAC1B,oBAAoB,GACpB,qBAAqB,CAAC;AAE1B;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GACnG;IACE,QAAQ,CAAC,OAAO,EAAE,OAAO,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC;IACrE,QAAQ,CAAC,OAAO,EAAE,gCAAgC,CAAC;CACpD,GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,0BAA0B,CAAA;CAAE,GAChH;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GACpG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAqE3G;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,oBAAoB,GAAG,oBAAoB,GAAG,IAAI,CAkDzF"}