Skip to content

Commit da86a83

Browse files
authored
Merge pull request #2019 from lidge-jun/codex/split-wp1-types
refactor(types): extract value clusters into types/tools and types/wire leaves
2 parents 4edf795 + 3ddae40 commit da86a83

4 files changed

Lines changed: 338 additions & 211 deletions

File tree

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# WP1 — types.ts value-leaf extraction (stacked PR 1 of the split program)
2+
3+
Unit: devlog/_plan/260818_megafile_split_program. Risk basis: 000_risk_assessment.md.
4+
Branch: codex/split-wp1-types on dev @ b04cd26e7 (post FastWire B0/B1 merge).
5+
Class: C2 (mechanical move, shared-runtime file, full-suite gate).
6+
7+
## Loop spec
8+
9+
- Archetype: pure-move refactor, zero behavior change.
10+
- Trigger: split program WP1, lowest-risk opener.
11+
- Goal: src/types.ts stops carrying runtime value code; values live in leaves;
12+
every existing import keeps working via re-export.
13+
- Non-goals: NO type-cluster split yet (OcxConfig/OcxProviderConfig stay),
14+
NO consumer retargeting to leaf paths, NO behavior or signature change.
15+
- Verifier: bun run typecheck && bun run test (full — shared runtime file).
16+
- Stop: both green + core-lab-boundary green; PR opened against dev.
17+
- Memory artifact: this doc + ledger attests.
18+
19+
## Scope (IN)
20+
21+
Extract the two VALUE clusters from src/types.ts (1867 lines) into leaves:
22+
23+
1. src/types/tools.ts — lines ~236-292:
24+
namespacedToolName, toolChoiceAliases, toolAllowedByChoice,
25+
resolveToolChoiceWireName, modelInList, OcxToolChoice (type),
26+
isAllowedToolChoice, toolChoiceToolPredicate.
27+
Needs `import type { OcxTool } from "../types"` — type-only, erased at
28+
runtime, so the types.ts -> tools.ts re-export is NOT a runtime cycle.
29+
2. src/types/wire.ts — lines ~1760-1839:
30+
UPSTREAM_HTTP_VERSION_VALUES, UpstreamHttpVersion,
31+
REASONING_SUMMARY_DELIVERY_VALUES, ReasoningSummaryDelivery,
32+
CodexAccountMode, OPENAI_PROVIDER_TIER_VERSION,
33+
MODEL_ADAPTER_OVERRIDE_ALLOWED, ANTHROPIC_WIRE_MODELS (internal),
34+
anthropicWireModelsForProvider (internal), captureWireAdapterHardPins,
35+
isWirePinnedModel, pinnedWireAdapter. Self-contained, no imports.
36+
37+
src/types.ts keeps every current export via `export ... from "./types/..."`;
38+
type-only names re-exported with `export type`.
39+
40+
## Scope (OUT)
41+
42+
- All interface/type clusters stay in types.ts this PR.
43+
- No import-path changes anywhere else in src/ or tests/.
44+
- No lab imports anywhere new (types is on the protected graph as a value
45+
import from responses/core.ts: modelInList, namespacedToolName).
46+
47+
## File change map
48+
49+
- ADD src/types/tools.ts (~60 lines incl. docs)
50+
- ADD src/types/wire.ts (~85 lines incl. docs)
51+
- EDIT src/types.ts: delete moved bodies, add two re-export blocks at the
52+
same positions; net -120 lines.
53+
54+
## Accept criteria
55+
56+
1. bun run typecheck exit 0.
57+
2. bun run test full suite: same pass count as base (13k+), 0 fail.
58+
3. tests/core-lab-boundary.test.ts green (covers the new static edges
59+
types.ts -> types/tools.ts, types/wire.ts on the protected walk).
60+
4. rg confirms no consumer file changed: git diff --stat touches exactly 3
61+
files.
62+
5. Value identity preserved: MODEL_ADAPTER_OVERRIDE_ALLOWED still a single
63+
ReadonlySet instance (only one declaration site, re-export not re-create).
64+
65+
Activation grounding: criterion 3's scenario is the existing boundary test
66+
run; criterion 5's scenario is the full suite (service-tier tests compare
67+
set membership through both import paths).
68+
69+
## Verifier reality (PLAN-VERIFIER-REAL-01)
70+
71+
- bun run typecheck: exists in package.json, reads src/ via tsconfig
72+
include ["src"] — observes both new files. To be run in C.
73+
- bun run test: tests/ suite imports ../src/types in 400 files — observes
74+
the barrel; core-lab-boundary walks the import graph from the three
75+
protected roots which reach types.ts — observes the new edges.
76+
77+
## Stacked-PR plan (DEV-STACK-01)
78+
79+
PR 1 (this): value leaves + barrel. Target: dev.
80+
PR 2 (next cycle): type-cluster split (request/config/provider/accounts)
81+
stacked on PR 1's head branch.
82+
Later cycles per 000_risk_assessment.md order (config leaves, registry, ...).
83+
84+
## Audit amendments (A-phase, 2 auditors: grok-4.6 NEAR-PASS / gpt-5.6-sol FAIL->fixed)
85+
86+
1. CYCLE FIX (sol blocker): OcxTool (lines 211-232) moves INTO types/tools.ts.
87+
tools.ts imports NOTHING from ../types — dependency is strictly one-way
88+
(types.ts -> types/tools.ts). types.ts re-exports OcxTool as a type.
89+
2. RECIPE FIX (grok finding 7): `export type { X } from` does not BIND X in
90+
the barrel. types.ts still uses OcxTool (line 106), OcxToolChoice (299),
91+
UpstreamHttpVersion (1455), CodexAccountMode (1470),
92+
ReasoningSummaryDelivery (1574) — so the barrel adds a local
93+
`import type { OcxTool, OcxToolChoice } from "./types/tools"` and
94+
`import type { UpstreamHttpVersion, ReasoningSummaryDelivery,
95+
CodexAccountMode } from "./types/wire"` next to the Kiro import.
96+
3. OcxToolChoice + its guards travel with tools.ts (they are one cluster).
97+
4. Extensionless specifiers only (lab walker resolves `${base}.ts`).
98+
5. AC4 corrected: scope proof = `git diff --stat <base>..HEAD -- src tests`
99+
showing exactly 3 src files; devlog/plan files are committed separately.
100+
6. AC5 proof corrected: identity is preserved by ESM re-export semantics
101+
(single declaration site); drop the false 'both import paths' claim.
102+
7. Protected-roots note corrected: PROTECTED has 4 files; only
103+
responses/core.ts puts types.ts on the runtime graph (core.ts:63).
104+

‎src/types.ts‎

Lines changed: 23 additions & 211 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
import type { KiroOAuthMetadata } from "./oauth/types";
2+
import type { OcxTool, OcxToolChoice } from "./types/tools";
3+
import type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode } from "./types/wire";
24

35
/** Exact provider/credential namespace for process-local reasoning replay. */
46
export interface OcxReasoningReplayIdentity {
@@ -214,137 +216,17 @@ export interface OcxProviderOpaqueToolCallMetadata {
214216

215217
export type OcxAssistantContentPart = OcxTextContent | OcxThinkingContent | OcxToolCall;
216218

217-
export interface OcxTool {
218-
name: string;
219-
description: string;
220-
parameters: Record<string, unknown>;
221-
strict?: boolean;
222-
/** MCP namespace (e.g. "mcp__context7") for tools flattened out of a Responses "namespace" tool. */
223-
namespace?: string;
224-
/** Freeform/custom tool (e.g. apply_patch): the model's call must be relayed as a custom_tool_call. */
225-
freeform?: boolean;
226-
/** Client-executed tool discovery (tool_search): the model's call must be relayed as a tool_search_call. */
227-
toolSearch?: boolean;
228-
/** Tool definition restored from a prior tool_search output; transports may prioritize it when catalogs are bounded. */
229-
loadedFromToolSearch?: boolean;
230-
/** Cursor-only synthetic exact-match edit tool; never inferred from the wire name. */
231-
cursorStructuredEdit?: true;
232-
/** Synthetic web_search tool: the model's call is executed by the gpt-5.4-mini sidecar, not relayed to Codex. */
233-
webSearch?: boolean;
234-
/** Synthetic image_gen tool: the model's call is executed by the xAI image bridge sidecar, not relayed to Codex. */
235-
imageGeneration?: boolean;
236-
/** Synthetic video_gen tool: executed by the xAI video bridge sidecar. */
237-
videoGeneration?: boolean;
238-
}
239-
240-
/**
241-
* Wire name a chat model sees for a tool. Namespaced (MCP) tools are flattened to
242-
* "<namespace>__<name>" so they survive the chat-completions function-tool format;
243-
* the proxy maps this back to {namespace, name} on the return trip (Codex routes MCP
244-
* calls by an explicit `namespace` field, not by parsing the name).
245-
*/
246-
export function namespacedToolName(namespace: string | undefined, name: string): string {
247-
return namespace ? `${namespace}__${name}` : name;
248-
}
249-
250-
export function toolChoiceAliases(tool: Pick<OcxTool, "namespace" | "name">): string[] {
251-
const wireName = namespacedToolName(tool.namespace, tool.name);
252-
return tool.namespace ? [wireName, `${tool.namespace}.${tool.name}`] : [wireName];
253-
}
254-
255-
function sameToolIdentity(
256-
left: Pick<OcxTool, "namespace" | "name">,
257-
right: Pick<OcxTool, "namespace" | "name">,
258-
): boolean {
259-
return left.namespace === right.namespace && left.name === right.name;
260-
}
261-
262-
/**
263-
* All tools that could be selected by one client-facing name. Bare logical names are included
264-
* here because they are a compatibility selector for namespaced tools, while wire and dotted
265-
* aliases come from `toolChoiceAliases`. A selector with more than one candidate is invalid.
266-
*/
267-
export function toolChoiceCandidates(
268-
tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
269-
name: string,
270-
): Pick<OcxTool, "namespace" | "name">[] {
271-
if (!tools) return [];
272-
const candidates: Pick<OcxTool, "namespace" | "name">[] = [];
273-
for (const tool of tools) {
274-
if (tool.name !== name && !toolChoiceAliases(tool).includes(name)) continue;
275-
if (!candidates.some(candidate => sameToolIdentity(candidate, tool))) candidates.push(tool);
276-
}
277-
return candidates;
278-
}
279-
280-
/**
281-
* Newer Codex clients can select a tool nested in a namespace by its bare name. Resolve that
282-
* shorthand only when the request contains one tool with the logical name, so an ambiguous name
283-
* cannot authorize a tool from an unintended namespace.
284-
*/
285-
export function toolAllowedByChoice(
286-
tool: Pick<OcxTool, "namespace" | "name">,
287-
allowedTools: ReadonlySet<string>,
288-
tools?: readonly Pick<OcxTool, "namespace" | "name">[],
289-
): boolean {
290-
if (!tools) return toolChoiceAliases(tool).some(name => allowedTools.has(name));
291-
for (const name of [...toolChoiceAliases(tool), tool.name]) {
292-
if (!allowedTools.has(name)) continue;
293-
const candidates = toolChoiceCandidates(tools, name);
294-
if (candidates.length === 1 && sameToolIdentity(candidates[0], tool)) return true;
295-
}
296-
return false;
297-
}
298-
299-
export function resolveToolChoiceWireName(tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined, name: string): string {
300-
const candidates = toolChoiceCandidates(tools, name);
301-
if (candidates.length === 1) {
302-
const match = candidates[0];
303-
return namespacedToolName(match.namespace, match.name);
304-
}
305-
// Keep unknown/ambiguous names unchanged for callers that only serialize a selector. The
306-
// catalog-aware predicate rejects them, and parseRequest rejects ambiguous request selectors.
307-
return name;
308-
}
309-
310-
/**
311-
* Whether `modelId` is in a per-provider classification list (e.g. `noVisionModels`). Matches the full
312-
* id, OR — for Ollama-style ids — the family before the ":size" tag, so a `gpt-oss` entry covers
313-
* `gpt-oss:120b`/`gpt-oss:20b`. Colon-less ids (e.g. `grok-build-0.1`) still match exactly only.
314-
*/
315-
export function modelInList(list: string[] | undefined, modelId: string): boolean {
316-
if (!list || list.length === 0) return false;
317-
if (list.includes(modelId)) return true;
318-
const colon = modelId.indexOf(":");
319-
return colon > 0 && list.includes(modelId.slice(0, colon));
320-
}
321-
322-
export type OcxToolChoice =
323-
| "auto"
324-
| "none"
325-
| "required"
326-
| { name: string }
327-
| { allowedTools: string[]; mode: "auto" | "required" };
328-
329-
export function isAllowedToolChoice(value: OcxToolChoice | undefined): value is { allowedTools: string[]; mode: "auto" | "required" } {
330-
return typeof value === "object" && value !== null && "allowedTools" in value;
331-
}
332-
333-
/** Compile the request's tool-choice policy into a reusable advertisement/restoration predicate. */
334-
export function toolChoiceToolPredicate(
335-
choice: OcxToolChoice | undefined,
336-
tools?: readonly Pick<OcxTool, "namespace" | "name">[],
337-
): (tool: Pick<OcxTool, "namespace" | "name">) => boolean {
338-
if (!choice || choice === "auto" || choice === "required") return () => true;
339-
if (choice === "none") return () => false;
340-
if (isAllowedToolChoice(choice)) {
341-
const allowed = new Set(choice.allowedTools);
342-
return tool => toolAllowedByChoice(tool, allowed, tools);
343-
}
344-
if (!tools) return tool => toolChoiceAliases(tool).includes(choice.name);
345-
const candidates = toolChoiceCandidates(tools, choice.name);
346-
return tool => candidates.length === 1 && sameToolIdentity(candidates[0], tool);
347-
}
219+
export type { OcxTool, OcxToolChoice } from "./types/tools";
220+
export {
221+
namespacedToolName,
222+
toolChoiceAliases,
223+
toolChoiceCandidates,
224+
toolAllowedByChoice,
225+
resolveToolChoiceWireName,
226+
modelInList,
227+
isAllowedToolChoice,
228+
toolChoiceToolPredicate,
229+
} from "./types/tools";
348230

349231
export interface OcxRequestOptions {
350232
maxOutputTokens?: number;
@@ -1825,86 +1707,16 @@ export interface OcxProviderConfig {
18251707
nativeLocalExec?: "off" | "codex-sandbox" | "on";
18261708
}
18271709

1828-
/**
1829-
* Accepted values for the per-provider upstream HTTP-version pin (#1668). Shared by the
1830-
* zod load schema, the management write boundary (POST/PATCH), and the fetch runtime, so
1831-
* a value that one boundary accepts can never be rejected by another.
1832-
*/
1833-
export const UPSTREAM_HTTP_VERSION_VALUES = [
1834-
"auto",
1835-
"http1.1",
1836-
"h1",
1837-
"http2",
1838-
"h2",
1839-
] as const;
1840-
1841-
export type UpstreamHttpVersion = (typeof UPSTREAM_HTTP_VERSION_VALUES)[number];
1842-
1843-
export const REASONING_SUMMARY_DELIVERY_VALUES = [
1844-
"sequential",
1845-
"sequential_cutoff",
1846-
"concurrent",
1847-
"concurrent_cutoff",
1848-
] as const;
1849-
1850-
export type ReasoningSummaryDelivery = typeof REASONING_SUMMARY_DELIVERY_VALUES[number];
1851-
1852-
/** Trusted runtime ownership for Codex-account credentials. Never persisted per provider. */
1853-
export type CodexAccountMode = "direct" | "pool";
1854-
1855-
export const OPENAI_PROVIDER_TIER_VERSION = 2 as const;
1856-
1857-
/**
1858-
* Wires that a per-model `modelAdapters` override may select.
1859-
*
1860-
* Deliberately narrow: provider-specific adapters (cursor, kiro, google, ...) carry
1861-
* their own credential and base-URL semantics, so exposing them here would widen the
1862-
* auth boundary rather than pick a wire. Widening this set needs a per-adapter
1863-
* credential threat model first (#404).
1864-
*/
1865-
export const MODEL_ADAPTER_OVERRIDE_ALLOWED: ReadonlySet<string> = new Set([
1866-
"openai-chat",
1867-
"openai-responses",
1868-
]);
1869-
1870-
/**
1871-
* Providers whose listed model ids must be driven over the Anthropic wire even when
1872-
* the provider's configured adapter says otherwise — the upstream only speaks
1873-
* Anthropic for these models.
1874-
*/
1875-
const ANTHROPIC_WIRE_MODELS: Record<string, ReadonlySet<string>> = {
1876-
"opencode-go": new Set(["minimax-m2.5", "minimax-m2.7", "minimax-m3"]),
1877-
};
1878-
1879-
function anthropicWireModelsForProvider(providerName: string): ReadonlySet<string> | undefined {
1880-
return Object.hasOwn(ANTHROPIC_WIRE_MODELS, providerName)
1881-
? ANTHROPIC_WIRE_MODELS[providerName]
1882-
: undefined;
1883-
}
1884-
1885-
/** Detached provider-local hard-pin table for pure wire-policy resolution. */
1886-
export function captureWireAdapterHardPins(providerName: string): Readonly<Record<string, string>> {
1887-
const models = anthropicWireModelsForProvider(providerName);
1888-
if (!models) return Object.freeze({});
1889-
return Object.freeze(Object.fromEntries([...models].map(modelId => [modelId, "anthropic"])));
1890-
}
1891-
1892-
/**
1893-
* True when the upstream speaks exactly one wire for this model, so a configured
1894-
* override must not apply.
1895-
*
1896-
* Deliberately independent of the provider's current adapter: the wire resolver runs
1897-
* more than once per request, and a check phrased as "pin differs from the current
1898-
* adapter" would pass on the first pass and then let the override win on the second.
1899-
*/
1900-
export function isWirePinnedModel(providerName: string, modelId: string): boolean {
1901-
return anthropicWireModelsForProvider(providerName)?.has(modelId) ?? false;
1902-
}
1903-
1904-
/** The wire a pinned model must use, or undefined when the model is not pinned. */
1905-
export function pinnedWireAdapter(providerName: string, modelId: string): string | undefined {
1906-
return isWirePinnedModel(providerName, modelId) ? "anthropic" : undefined;
1907-
}
1710+
export type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode } from "./types/wire";
1711+
export {
1712+
UPSTREAM_HTTP_VERSION_VALUES,
1713+
REASONING_SUMMARY_DELIVERY_VALUES,
1714+
OPENAI_PROVIDER_TIER_VERSION,
1715+
MODEL_ADAPTER_OVERRIDE_ALLOWED,
1716+
captureWireAdapterHardPins,
1717+
isWirePinnedModel,
1718+
pinnedWireAdapter,
1719+
} from "./types/wire";
19081720

19091721
export interface CodexAccount {
19101722
id: string;

0 commit comments

Comments
 (0)