@meistrari/agent-core 0.2.0-experimental.5 → 0.2.0-experimental.6

package/README.md

@@ -122,6 +122,13 @@ stale managed instruction file.
 `resolveInferenceModel`, `pluginsEnabled`, and `browserAuth` (a per-run Browser Use
 credential socket for ChatGPT authentication; off by default).
 
+API-key and Bedrock logins stay in the app-server's memory (`cli_auth_credentials_store="ephemeral"`),
+so no `auth.json` under `CODEX_HOME` holds the key for the agent's tools to read. An API-key login
+may name `baseUrl`, the root of another OpenAI Responses API (a gateway, or a loopback proxy that
+holds the real credential and gets a placeholder): Codex then reaches it as a model provider of its
+own, named by `modelProvider` (`api-key-endpoint` by default, never a built-in id), with the key as
+its bearer. `codex-api-key-endpoint.cli.spec.ts` pins that contract against the real CLI.
+
 `AgentRun.notify` and `AgentRun.compactContext` are optional on the interface; the Claude and
 Codex runs implement both. `sendPrompt` accepts `submissionOrder`, defaulting to `in-order`.
 
@@ -134,7 +141,8 @@ product instructions/tools, and supervisor integration tests. CI type-checks and
 with Remy's Bun 1.3.10 / Claude SDK 0.3.284 and agent-api's Claude SDK 0.3.257 pins.
 
 `bun run test` runs the portable suites. `bun run test:cli` runs the `*.cli.spec.ts` suites
-against the real bundled Claude Code CLI and a fake Messages API. CI runs them on Linux; the
+against the real bundled Claude Code CLI and a fake Messages API, and the Codex endpoint spec
+against the pinned Codex CLI (through `bunx`, or `CODEX_EXECUTABLE`) and a fake Responses API. CI runs them on Linux; the
 process lifecycle spec reads `/proc`, so it fails on macOS. Claude Code rejects its
 bypass-permissions mode as root, so run them as a regular user.
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@meistrari/agent-core",
     "type": "module",
-    "version": "0.2.0-experimental.5",
+    "version": "0.2.0-experimental.6",
     "packageManager": "bun@1.3.12",
     "description": "Shared contracts and runtime modules for Tela coding-agent sandboxes: agent protocol, supervisor wire protocol, resident supervisor, worker runtime client, and Claude/Codex harness adapters.",
     "license": "UNLICENSED",

package/src/agents/codex/codex-auth.ts

@@ -44,9 +44,23 @@ export interface CodexBedrockAuthProvider {
     getCredentials: (input?: CodexAuthTokenRequest) => Promise<CodexBedrockCredentials>
 }
 
+/**
+ * An API key login, kept in the app-server's memory only. Without `baseUrl` it reaches the API of the model
+ * provider `modelProvider` names (OpenAI's by default). With `baseUrl`, the root of another OpenAI Responses
+ * API (`https://gateway.example/v1`, or a loopback proxy that holds the real credential), Codex reaches it as
+ * a model provider of its own, named by `modelProvider` (`api-key-endpoint` by default) and given the key as
+ * its bearer.
+ */
+export interface CodexApiKeyAuthentication {
+    kind: 'api-key'
+    provider: CodexApiKeyAuthProvider
+    modelProvider?: string
+    baseUrl?: string
+}
+
 export type CodexAuthentication
     = | { kind: 'chatgpt', provider: CodexAuthProvider }
-        | { kind: 'api-key', provider: CodexApiKeyAuthProvider, modelProvider?: string }
+        | CodexApiKeyAuthentication
         | { kind: 'amazon-bedrock', region: string, provider: CodexBedrockAuthProvider }
 /** Expiry scheduling hint only; this neither authenticates nor verifies a JWT signature. */
 export function codexAuthTokensExpireSoon(tokens: CodexAuthTokens): boolean {

package/src/agents/codex/codex-provider.ts

@@ -5,7 +5,7 @@ import type { AgentRun } from '../agent-run'
 import type { AgentTool } from '../agent-tool'
 import type { InstructionComposer } from '../instructions'
 import type { SessionContextComposer } from '../session-context'
-import type { CodexAuthentication, CodexAuthProvider, CodexAuthTokens, CodexBedrockCredentials } from './codex-auth'
+import type { CodexApiKeyAuthentication, CodexAuthentication, CodexAuthProvider, CodexAuthTokens, CodexBedrockCredentials } from './codex-auth'
 import type { CodexEventMapperState, CodexNotification } from './codex-event-mapper'
 import type { CodexJsonRpcMessage, CodexServerRequest } from './codex-json-rpc-client'
 import type { ClientRequestResponsesByMethod } from './codex-protocol'
@@ -13,7 +13,7 @@ import { realpath } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { codexModelIdSchema } from '../../protocol'
 import { serializeAgentError } from '../agent-error-serializer'
-import { AgentProviderMetadataError, AgentProviderProtocolError, AgentProviderRuntimeError } from '../agent-runtime-error'
+import { AgentProviderMetadataError, AgentProviderProtocolError, AgentProviderRuntimeError, AgentRuntimeValidationError } from '../agent-runtime-error'
 import { sessionConfiguredEvent } from '../agent-session-events'
 import { selectAgentTools, toolByName } from '../agent-tool'
 import { emptyInstructionComposer } from '../instructions'
@@ -33,6 +33,15 @@ import { CodexRunAuth, CodexRunAuthClosedError } from './codex-run-auth'
 import { catalogRepositorySkillRoots, workspaceSkillRoots } from './codex-skill-roots'
 import { runCodexDynamicTool, toCodexDynamicTools } from './codex-tool-mapper'
 
+/** The model provider an API key endpoint gets when `modelProvider` names none. */
+const API_KEY_ENDPOINT_PROVIDER = 'api-key-endpoint'
+/** Codex's own provider ids: an endpoint defined under one of these would not be the one Codex uses. */
+const BUILT_IN_MODEL_PROVIDERS = new Set(['openai', 'amazon-bedrock', 'ollama', 'lmstudio', 'oss'])
+/** A bare TOML key, so the id is safe inside the dotted `-c model_providers.<id>.…` overrides. */
+const MODEL_PROVIDER_ID = /^[\w-]+$/
+/** Where plain http keeps the key on the machine. */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]'])
+
 export interface CodexStartupStageFact {
     event: 'sandbox.startup-stage'
     stage: 'codex-initialize' | 'auth-acquisition-login' | 'thread-start' | 'thread-resume'
@@ -103,6 +112,8 @@ export class CodexProvider implements AgentProvider<'codex'> {
     private readonly executable: string
     private readonly environment: Record<string, string | undefined>
     private readonly auth: CodexAuthentication
+    /** The validated endpoint of an API key login that names one. */
+    private readonly apiKeyEndpoint: string | undefined
     private readonly onStartupStage: ((fact: CodexStartupStageFact) => void) | undefined
     private readonly instructions: InstructionComposer
     private readonly sessionContext: SessionContextComposer | undefined
@@ -115,6 +126,7 @@ export class CodexProvider implements AgentProvider<'codex'> {
 
     private constructor(config: CodexProviderConfig) {
         this.auth = normalizeCodexAuthentication(config.auth)
+        this.apiKeyEndpoint = this.auth.kind === 'api-key' ? apiKeyEndpoint(this.auth) : undefined
         this.tools = config.tools ?? []
         this.executable = config.executable ?? 'codex'
         this.environment = config.environment ?? {}
@@ -422,7 +434,11 @@ export class CodexProvider implements AgentProvider<'codex'> {
     }
 
     private modelProvider(): string | undefined {
-        return this.auth.kind === 'amazon-bedrock' ? 'amazon-bedrock' : this.auth.kind === 'api-key' ? this.auth.modelProvider : undefined
+        if (this.auth.kind === 'amazon-bedrock')
+            return 'amazon-bedrock'
+        if (this.auth.kind === 'api-key')
+            return this.auth.modelProvider ?? (this.apiKeyEndpoint === undefined ? undefined : API_KEY_ENDPOINT_PROVIDER)
+        return undefined
     }
 
     private async openConnection(input: {
@@ -450,6 +466,7 @@ export class CodexProvider implements AgentProvider<'codex'> {
                     ...(this.auth.kind === 'amazon-bedrock'
                         ? ['cli_auth_credentials_store="ephemeral"', 'model_provider="amazon-bedrock"', `model_providers.amazon-bedrock.aws.region=${JSON.stringify(this.auth.region)}`, 'model_providers.amazon-bedrock.aws.wire_api="responses"']
                         : []),
+                    ...(this.auth.kind === 'api-key' ? apiKeyConfigOverrides(this.auth.modelProvider, this.apiKeyEndpoint) : []),
                     ...(this.pluginsEnabled === undefined ? [] : [`features.plugins=${this.pluginsEnabled}`]),
                 ],
                 onMessage: (message) => {
@@ -895,6 +912,62 @@ function normalizeCodexAuthentication(auth: CodexAuthProvider | CodexAuthenticat
     return 'kind' in auth ? auth : { kind: 'chatgpt', provider: auth }
 }
 
+/**
+ * The endpoint as Codex is given it, or none: an http(s) URL with no credentials, query or fragment (not even
+ * an empty `?` or `#`), plain http only on loopback, where the key never crosses the network. Without a
+ * trailing slash, so Codex appends `/responses` to the path it names.
+ */
+function apiKeyEndpoint(auth: CodexApiKeyAuthentication): string | undefined {
+    const invalid = (message: string) => new AgentRuntimeValidationError({
+        code: 'agents.codex-api-key-endpoint-invalid',
+        message,
+        publicMessage: 'The Codex API key endpoint is misconfigured.',
+        details: { modelProvider: auth.modelProvider },
+    })
+    // Without an endpoint the provider id only selects a provider configured elsewhere, as it always has.
+    if (auth.baseUrl === undefined)
+        return undefined
+    if (auth.modelProvider !== undefined && !MODEL_PROVIDER_ID.test(auth.modelProvider))
+        throw invalid('Codex model provider ids are letters, digits, underscores and hyphens.')
+    let url: URL
+    try {
+        url = new URL(auth.baseUrl)
+    }
+    catch {
+        throw invalid('The Codex API key endpoint is not a URL.')
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        throw invalid('The Codex API key endpoint must be an http or https URL.')
+    if (url.protocol === 'http:' && !LOOPBACK_HOSTS.has(url.hostname))
+        throw invalid('The Codex API key endpoint sends the key as its bearer: plain http is accepted on loopback only.')
+    if (url.username || url.password || /[?#]/u.test(auth.baseUrl))
+        throw invalid('The Codex API key endpoint carries no credentials, query or fragment; the key travels as the bearer.')
+    if (BUILT_IN_MODEL_PROVIDERS.has(auth.modelProvider ?? API_KEY_ENDPOINT_PROVIDER))
+        throw invalid('An API key endpoint needs a model provider id of its own, not one of Codex\'s built-in providers.')
+    return `${url.origin}${url.pathname.replace(/\/+$/u, '')}`
+}
+
+/**
+ * An API key login is always kept in memory, never written to `auth.json` under CODEX_HOME, where the agent's
+ * own tools could read it. With an endpoint, Codex reaches it through a Responses provider of its own that
+ * authenticates with that login.
+ */
+function apiKeyConfigOverrides(modelProvider: string | undefined, endpoint: string | undefined): string[] {
+    const ephemeral = ['cli_auth_credentials_store="ephemeral"']
+    if (endpoint === undefined)
+        return ephemeral
+    const id = modelProvider ?? API_KEY_ENDPOINT_PROVIDER
+    const provider = `model_providers.${id}`
+    return [
+        ...ephemeral,
+        `model_provider=${JSON.stringify(id)}`,
+        `${provider}.name=${JSON.stringify(id)}`,
+        `${provider}.base_url=${JSON.stringify(endpoint)}`,
+        `${provider}.wire_api="responses"`,
+        `${provider}.requires_openai_auth=true`,
+    ]
+}
+
 async function requireSelectedRepositoryInstructionSource(input: {
     instructionBridgePath: string
     instructionSources?: readonly string[]

package/src/provenance.gen.ts

@@ -1,6 +1,6 @@
 // Generated by scripts/write-provenance.ts. Do not edit by hand.
 export const generatedProvenance = {
-    version: "0.2.0-experimental.5",
-    sha: "eea347fec63bc912885e3201e6463cfcfead865b",
-    buildTime: "2026-09-29T19:55:41.637Z",
+    version: "0.2.0-experimental.6",
+    sha: "1b8f8c0c8cc698990c1b0ed9e03c417216bc0316",
+    buildTime: "2026-10-02T20:59:57.760Z",
 } as const