@longtable/provider-codex 0.1.9

package/README.md

@@ -0,0 +1,50 @@
+# @longtable/provider-codex
+
+Codex-specific adapter logic for LongTable.
+
+This package implements numbered checkpoint interaction and thin runtime-guidance injection rather than depending on a provider-native question widget.
+
+## Role
+
+This package provides the Codex adapter used by `@longtable/cli`.
+
+It is publishable as a library package, but the primary researcher-facing command surface is `longtable`, not a standalone wrapper executable.
+
+### Local build and test
+
+From the workspace root:
+
+```bash
+npm install
+npm run typecheck
+npm run build
+```
+
+Then test the adapter directly:
+
+```bash
+node packages/longtable-provider-codex/dist/wrapper-cli.js \
+  --print \
+  --mode explore \
+  --prompt "I want exploration, not a conclusion yet."
+```
+
+```bash
+node packages/longtable-provider-codex/dist/wrapper-cli.js \
+  --exec \
+  --json \
+  --mode review \
+  --prompt "Review this claim critically."
+```
+
+If the wrapped behavior changes, update this README in the same commit.
+
+The wrapper reads the managed setup artifact when available and prepends a short runtime-guidance block so Codex receives:
+
+- mode
+- minimum question requirements
+- closure disposition
+- narrative-trace preservation rules
+- human commitment stakes when relevant
+
+For the recommended setup path, pair this package with `@longtable/setup`.

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+import type { SetupPersistedOutput } from "@longtable/setup";
+import { createCodexRuntimeBridge } from "./index.js";
+export interface CodexConfigFragment {
+    setupPath: string;
+    provider: "codex";
+    checkpointProtocol: "numbered";
+    defaultInteractionMode: SetupPersistedOutput["defaultInteractionMode"];
+    profileSummary: {
+        field: string;
+        careerStage: string;
+        experienceLevel: string;
+        currentProjectType: string;
+    };
+    runtimeGuidance: ReturnType<typeof createCodexRuntimeBridge>["runtimeDefaults"];
+}
+export declare function createCodexConfigFragment(setup: SetupPersistedOutput, setupPath: string): CodexConfigFragment;
+export declare function renderCodexConfigToml(setup: SetupPersistedOutput, setupPath: string): string;

package/dist/config.js

@@ -0,0 +1,39 @@
+import { createCodexRuntimeBridge } from "./index.js";
+export function createCodexConfigFragment(setup, setupPath) {
+    const bridge = createCodexRuntimeBridge(setup);
+    return {
+        setupPath,
+        provider: "codex",
+        checkpointProtocol: bridge.checkpointProtocol,
+        defaultInteractionMode: bridge.defaultInteractionMode,
+        profileSummary: {
+            field: bridge.profile.field,
+            careerStage: bridge.profile.careerStage,
+            experienceLevel: bridge.profile.experienceLevel,
+            currentProjectType: bridge.profile.currentProjectType
+        },
+        runtimeGuidance: bridge.runtimeDefaults
+    };
+}
+export function renderCodexConfigToml(setup, setupPath) {
+    const fragment = createCodexConfigFragment(setup, setupPath);
+    return [
+        "[longtable]",
+        `provider = "${fragment.provider}"`,
+        `setup_path = "${fragment.setupPath}"`,
+        `checkpoint_protocol = "${fragment.checkpointProtocol}"`,
+        `default_interaction_mode = "${fragment.defaultInteractionMode}"`,
+        "",
+        "[longtable.profile]",
+        `field = "${fragment.profileSummary.field}"`,
+        `career_stage = "${fragment.profileSummary.careerStage}"`,
+        `experience_level = "${fragment.profileSummary.experienceLevel}"`,
+        `current_project_type = "${fragment.profileSummary.currentProjectType}"`,
+        "",
+        "[longtable.runtime_guidance]",
+        `ask_at_least_two_questions_in_explore = ${fragment.runtimeGuidance.askAtLeastTwoQuestionsInExplore}`,
+        `preserve_narrative_trace_in_draft = ${fragment.runtimeGuidance.preserveNarrativeTraceInDraft}`,
+        `require_why_may_be_wrong_in_review = ${fragment.runtimeGuidance.requireWhyMayBeWrongInReview}`,
+        `question_bias_compensation = "${fragment.runtimeGuidance.questionBiasCompensation}"`
+    ].join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import type { CheckpointSignal, ResearcherProfile, ResolvedCheckpointPolicy, RuntimeGuidance } from "@longtable/checkpoints";
+import type { NumberedCheckpointSpec, ParsedCheckpointSelection, SetupPersistedOutput } from "@longtable/setup";
+export interface CodexCheckpointContext {
+    profile: ResearcherProfile;
+    signal: CheckpointSignal;
+    spec: NumberedCheckpointSpec;
+}
+export interface CodexCheckpointResult {
+    policy: ResolvedCheckpointPolicy;
+    guidance: RuntimeGuidance;
+    prompt: string;
+    selection?: ParsedCheckpointSelection;
+    accepted: boolean;
+    reprompt?: string;
+}
+export interface CodexRuntimeDefaults {
+    askAtLeastTwoQuestionsInExplore: boolean;
+    preserveNarrativeTraceInDraft: boolean;
+    requireWhyMayBeWrongInReview: boolean;
+    questionBiasCompensation: "strong";
+}
+export interface CodexRuntimeBridge {
+    provider: "codex";
+    checkpointProtocol: "numbered";
+    supportsStructuredQuestions: false;
+    defaultInteractionMode: SetupPersistedOutput["defaultInteractionMode"];
+    profile: ResearcherProfile;
+    runtimeDefaults: CodexRuntimeDefaults;
+}
+export declare function normalizeResearcherProfile(profile: SetupPersistedOutput["profileSeed"]): ResearcherProfile;
+export declare function renderRuntimeGuidance(guidance: RuntimeGuidance): string;
+export declare function renderCheckpointPrompt(spec: NumberedCheckpointSpec, guidance?: RuntimeGuidance): string;
+export declare function parseCheckpointResponse(spec: NumberedCheckpointSpec, input: string): ParsedCheckpointSelection | null;
+export declare function buildReprompt(spec: NumberedCheckpointSpec, guidance?: RuntimeGuidance): string;
+export declare function runBlockingCheckpoint(context: CodexCheckpointContext, input?: string): CodexCheckpointResult;
+export declare function createCodexRuntimeBridge(setup: SetupPersistedOutput): CodexRuntimeBridge;
+export * from "./config.js";
+export * from "./wrapper.js";

package/dist/index.js

@@ -0,0 +1,105 @@
+import { resolveCheckpointPolicy } from "@longtable/checkpoints";
+import { resolveRuntimeGuidance } from "@longtable/checkpoints";
+import { buildNumberedCheckpointPrompt, parseNumberedCheckpointResponse } from "@longtable/setup";
+export function normalizeResearcherProfile(profile) {
+    return {
+        field: profile.field,
+        careerStage: profile.careerStage,
+        experienceLevel: profile.experienceLevel,
+        preferredCheckpointIntensity: profile.preferredCheckpointIntensity,
+        currentProjectType: profile.currentProjectType ?? "unspecified research task",
+        ...(profile.humanAuthorshipSignal ? { humanAuthorshipSignal: profile.humanAuthorshipSignal } : {}),
+        ...(profile.aiAutonomyPreference ? { aiAutonomyPreference: profile.aiAutonomyPreference } : {})
+    };
+}
+export function renderRuntimeGuidance(guidance) {
+    const lines = [
+        "LongTable runtime guidance",
+        `- mode: ${guidance.mode}`,
+        `- closure: ${guidance.closureDisposition}`,
+        `- minimum questions before closure: ${guidance.minimumQuestions}`,
+        `- question types: ${guidance.questionTypes.length > 0 ? guidance.questionTypes.join(", ") : "none"}`,
+        `- questions first: ${guidance.preferQuestionsFirst ? "yes" : "no"}`,
+        `- preserve narrative trace: ${guidance.preserveNarrativeTrace ? "yes" : "no"}`
+    ];
+    if (guidance.includeWhyMayBeWrong) {
+        lines.push("- include: why this may be wrong");
+    }
+    if (guidance.includeOpenTensions) {
+        lines.push("- include: open tensions");
+    }
+    if (guidance.surfaceHumanCommitment) {
+        lines.push("- include: why this requires explicit human commitment");
+    }
+    if (guidance.mandatoryQuestions.length > 0) {
+        lines.push("- ask first:");
+        for (const question of guidance.mandatoryQuestions) {
+            lines.push(`  - ${question}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function renderCheckpointPrompt(spec, guidance) {
+    const sections = [];
+    if (guidance) {
+        sections.push(renderRuntimeGuidance(guidance));
+    }
+    sections.push(buildNumberedCheckpointPrompt(spec));
+    return sections.join("\n\n");
+}
+export function parseCheckpointResponse(spec, input) {
+    return parseNumberedCheckpointResponse(spec, input);
+}
+export function buildReprompt(spec, guidance) {
+    return [
+        "Your response could not be parsed.",
+        renderCheckpointPrompt(spec, guidance)
+    ].join("\n\n");
+}
+export function runBlockingCheckpoint(context, input) {
+    const policy = resolveCheckpointPolicy(context.profile, context.signal);
+    const guidance = resolveRuntimeGuidance(context.profile, context.signal, policy);
+    const prompt = renderCheckpointPrompt(context.spec, guidance);
+    if (!policy.blocking) {
+        return {
+            policy,
+            guidance,
+            prompt,
+            accepted: false
+        };
+    }
+    const selection = input ? parseCheckpointResponse(context.spec, input) : null;
+    if (!selection) {
+        return {
+            policy,
+            guidance,
+            prompt,
+            accepted: false,
+            reprompt: buildReprompt(context.spec, guidance)
+        };
+    }
+    return {
+        policy,
+        guidance,
+        prompt,
+        selection,
+        accepted: true
+    };
+}
+export function createCodexRuntimeBridge(setup) {
+    return {
+        provider: "codex",
+        checkpointProtocol: "numbered",
+        supportsStructuredQuestions: false,
+        defaultInteractionMode: setup.defaultInteractionMode,
+        profile: normalizeResearcherProfile(setup.profileSeed),
+        runtimeDefaults: {
+            askAtLeastTwoQuestionsInExplore: true,
+            preserveNarrativeTraceInDraft: true,
+            requireWhyMayBeWrongInReview: true,
+            questionBiasCompensation: "strong"
+        }
+    };
+}
+export * from "./config.js";
+export * from "./wrapper.js";

package/dist/wrapper-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/wrapper-cli.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { cwd, exit } from "node:process";
+import { buildCodexThinWrappedPrompt, runCodexThinWrapper } from "./wrapper.js";
+const VALID_MODES = new Set([
+    "explore",
+    "review",
+    "critique",
+    "draft",
+    "commit",
+    "submit"
+]);
+const VALID_STAGES = new Set([
+    "problem_framing",
+    "theory_selection",
+    "method_design",
+    "measurement_design",
+    "analysis_planning",
+    "writing",
+    "submission"
+]);
+function usage() {
+    return [
+        "Usage:",
+        "  longtable-codex-wrapper --print --prompt \"...\" [--mode explore] [--stage problem_framing]",
+        "  longtable-codex-wrapper --exec --prompt \"...\" [--mode review] [--json]",
+        "",
+        "Options:",
+        "  --prompt <text>       Prompt to wrap before sending to Codex",
+        "  --mode <mode>         explore|review|critique|draft|commit|submit",
+        "  --stage <stage>       problem_framing|theory_selection|method_design|measurement_design|analysis_planning|writing|submission",
+        "  --setup <path>        Override managed setup path",
+        "  --cwd <path>          Working directory to pass to codex exec",
+        "  --print               Print the wrapped prompt only",
+        "  --exec                Run codex exec with the wrapped prompt",
+        "  --json                When used with --exec, request JSONL events from Codex",
+        "  --help                Show this message"
+    ].join("\n");
+}
+function parseArgs(argv) {
+    const parsed = {
+        workingDirectory: cwd(),
+        json: false,
+        print: false,
+        exec: false
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        switch (token) {
+            case "--prompt":
+                parsed.prompt = argv[index + 1];
+                index += 1;
+                break;
+            case "--mode":
+                if (!VALID_MODES.has(argv[index + 1])) {
+                    throw new Error(`Invalid mode: ${argv[index + 1]}`);
+                }
+                parsed.mode = argv[index + 1];
+                index += 1;
+                break;
+            case "--stage":
+                if (!VALID_STAGES.has(argv[index + 1])) {
+                    throw new Error(`Invalid stage: ${argv[index + 1]}`);
+                }
+                parsed.stage = argv[index + 1];
+                index += 1;
+                break;
+            case "--setup":
+                parsed.setupPath = argv[index + 1];
+                index += 1;
+                break;
+            case "--cwd":
+                parsed.workingDirectory = argv[index + 1];
+                index += 1;
+                break;
+            case "--json":
+                parsed.json = true;
+                break;
+            case "--print":
+                parsed.print = true;
+                break;
+            case "--exec":
+                parsed.exec = true;
+                break;
+            case "--help":
+                console.log(usage());
+                exit(0);
+            default:
+                throw new Error(`Unknown argument: ${token}`);
+        }
+    }
+    if (!parsed.print && !parsed.exec) {
+        parsed.print = true;
+    }
+    return parsed;
+}
+function resolvePrompt(prompt) {
+    if (prompt && prompt.trim()) {
+        return prompt.trim();
+    }
+    if (!process.stdin.isTTY) {
+        return readFileSync(0, "utf8").trim();
+    }
+    return "";
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const prompt = resolvePrompt(args.prompt);
+    if (!prompt) {
+        throw new Error("A prompt is required. Pass --prompt or pipe text on stdin.");
+    }
+    if (args.print) {
+        const wrapped = await buildCodexThinWrappedPrompt({
+            prompt,
+            mode: args.mode,
+            researchStage: args.stage,
+            setupPath: args.setupPath,
+            workingDirectory: args.workingDirectory
+        });
+        console.log(wrapped.wrappedPrompt);
+        return;
+    }
+    const exitCode = await runCodexThinWrapper({
+        prompt,
+        mode: args.mode,
+        researchStage: args.stage,
+        setupPath: args.setupPath,
+        workingDirectory: args.workingDirectory,
+        json: args.json
+    });
+    exit(exitCode);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error("");
+    console.error(usage());
+    exit(1);
+});

package/dist/wrapper.d.ts

@@ -0,0 +1,20 @@
+import type { InteractionMode, ResearchStage, RuntimeGuidance } from "@longtable/core";
+export interface CodexThinWrapperOptions {
+    prompt: string;
+    mode?: InteractionMode;
+    researchStage?: ResearchStage;
+    workingDirectory?: string;
+    setupPath?: string;
+}
+export interface CodexWrappedPrompt {
+    mode: InteractionMode;
+    researchStage: ResearchStage;
+    guidance: RuntimeGuidance;
+    wrappedPrompt: string;
+    setupLoaded: boolean;
+}
+export declare function buildCodexThinWrappedPrompt(options: CodexThinWrapperOptions): Promise<CodexWrappedPrompt>;
+export interface CodexThinWrapperExecOptions extends CodexThinWrapperOptions {
+    json?: boolean;
+}
+export declare function runCodexThinWrapper(options: CodexThinWrapperExecOptions): Promise<number>;

package/dist/wrapper.js

@@ -0,0 +1,141 @@
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { cwd } from "node:process";
+import { resolveCheckpointPolicy, resolveRuntimeGuidance } from "@longtable/checkpoints";
+import { loadSetupOutput, resolveDefaultSetupPath } from "@longtable/setup";
+import { normalizeResearcherProfile, renderRuntimeGuidance } from "./index.js";
+function defaultProfile() {
+    return {
+        field: "unknown",
+        careerStage: "unknown",
+        experienceLevel: "intermediate",
+        preferredCheckpointIntensity: "balanced",
+        currentProjectType: "unspecified research task"
+    };
+}
+function defaultMode(setup) {
+    return setup?.defaultInteractionMode ?? "explore";
+}
+function defaultStage(mode) {
+    switch (mode) {
+        case "draft":
+            return "writing";
+        case "commit":
+            return "theory_selection";
+        case "submit":
+            return "submission";
+        case "review":
+        case "critique":
+            return "analysis_planning";
+        case "explore":
+        default:
+            return "problem_framing";
+    }
+}
+function defaultCheckpointLevel(mode) {
+    switch (mode) {
+        case "submit":
+            return "adaptive_required";
+        case "commit":
+            return "recommended";
+        case "review":
+        case "critique":
+        case "draft":
+        case "explore":
+        default:
+            return "recommended";
+    }
+}
+async function loadManagedSetup(customPath) {
+    const target = resolveDefaultSetupPath(customPath).path;
+    if (!existsSync(target)) {
+        return null;
+    }
+    try {
+        return await loadSetupOutput(customPath);
+    }
+    catch {
+        return null;
+    }
+}
+function readPromptFromStdin() {
+    if (process.stdin.isTTY) {
+        return "";
+    }
+    return readFileSync(0, "utf8").trim();
+}
+export async function buildCodexThinWrappedPrompt(options) {
+    const setup = await loadManagedSetup(options.setupPath);
+    const profile = setup ? normalizeResearcherProfile(setup.profileSeed) : defaultProfile();
+    const mode = options.mode ?? defaultMode(setup ?? undefined);
+    const researchStage = options.researchStage ?? defaultStage(mode);
+    const prompt = options.prompt.trim();
+    const signal = {
+        checkpointKey: "runtime_guidance",
+        baseLevel: defaultCheckpointLevel(mode),
+        mode,
+        artifactStakes: mode === "submit"
+            ? "external_submission"
+            : mode === "commit"
+                ? "study_protocol"
+                : mode === "draft"
+                    ? "internal_draft"
+                    : "private_note",
+        researchStage,
+        unresolvedTensions: setup?.initialState.openTensions ?? [],
+        studyContract: setup?.initialState.studyContract
+    };
+    const policy = resolveCheckpointPolicy(profile, signal);
+    const guidance = resolveRuntimeGuidance(profile, signal, policy);
+    const sections = [renderRuntimeGuidance(guidance)];
+    const instructionLines = [
+        "LongTable ordering rules",
+        guidance.minimumQuestions > 0 || guidance.mustAskBeforeClosure
+            ? "- surface the mandatory questions before any recommendation or closure"
+            : "- keep the response aligned to the stated mode",
+        guidance.includeWhyMayBeWrong ? "- include why this may be wrong before synthesis" : undefined,
+        guidance.includeOpenTensions ? "- keep unresolved tensions visible" : undefined,
+        guidance.preserveNarrativeTrace ? "- preserve narrative trace and avoid generic fluency" : undefined,
+        guidance.surfaceHumanCommitment ? "- make the human commitment stakes explicit before closing" : undefined,
+        profile.humanAuthorshipSignal
+            ? `- preserve this human authorship signal: ${profile.humanAuthorshipSignal}`
+            : undefined
+    ].filter(Boolean);
+    sections.push(instructionLines.join("\n"));
+    sections.push(["User prompt", prompt].join("\n"));
+    return {
+        mode,
+        researchStage,
+        guidance,
+        wrappedPrompt: sections.join("\n\n"),
+        setupLoaded: Boolean(setup)
+    };
+}
+export async function runCodexThinWrapper(options) {
+    const prompt = options.prompt.trim() || readPromptFromStdin();
+    if (!prompt) {
+        throw new Error("A prompt is required. Pass --prompt or pipe text on stdin.");
+    }
+    const wrapped = await buildCodexThinWrappedPrompt({
+        ...options,
+        prompt
+    });
+    const args = [
+        "exec",
+        "--color",
+        "never",
+        "-s",
+        "read-only",
+        "-C",
+        options.workingDirectory ?? cwd(),
+        "--skip-git-repo-check"
+    ];
+    if (options.json) {
+        args.push("--json");
+    }
+    args.push(wrapped.wrappedPrompt);
+    const result = spawnSync("codex", args, {
+        stdio: "inherit"
+    });
+    return result.status ?? 1;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@longtable/provider-codex",
+  "version": "0.1.9",
+  "private": false,
+  "description": "Codex adapter surface for LongTable",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@longtable/checkpoints": "0.1.9",
+    "@longtable/core": "0.1.9",
+    "@longtable/setup": "0.1.9"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "longtable",
+    "research",
+    "codex",
+    "wrapper",
+    "checkpoints"
+  ],
+  "author": "Hosung You",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HosungYou/LongTable.git"
+  },
+  "homepage": "https://github.com/HosungYou/LongTable#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}