@longtable/provider-codex 0.1.9 → 0.1.11

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import type { ProviderCapabilities, QuestionRecord } from "@longtable/core";
 import type { CheckpointSignal, ResearcherProfile, ResolvedCheckpointPolicy, RuntimeGuidance } from "@longtable/checkpoints";
 import type { NumberedCheckpointSpec, ParsedCheckpointSelection, SetupPersistedOutput } from "@longtable/setup";
 export interface CodexCheckpointContext {
@@ -27,12 +28,23 @@ export interface CodexRuntimeBridge {
     profile: ResearcherProfile;
     runtimeDefaults: CodexRuntimeDefaults;
 }
+export interface CodexRenderedQuestionRecord {
+    questionId: string;
+    checkpointKey: string;
+    spec: NumberedCheckpointSpec;
+    prompt: string;
+}
+export declare const CODEX_PROVIDER_CAPABILITIES: ProviderCapabilities;
+export declare function getCodexProviderCapabilities(): ProviderCapabilities;
 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 questionRecordToNumberedCheckpointSpec(record: QuestionRecord): NumberedCheckpointSpec;
+export declare function renderQuestionRecordPrompt(record: QuestionRecord): CodexRenderedQuestionRecord;
 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 "./skills.js";
 export * from "./wrapper.js";

package/dist/index.js

@@ -1,6 +1,24 @@
 import { resolveCheckpointPolicy } from "@longtable/checkpoints";
 import { resolveRuntimeGuidance } from "@longtable/checkpoints";
 import { buildNumberedCheckpointPrompt, parseNumberedCheckpointResponse } from "@longtable/setup";
+export const CODEX_PROVIDER_CAPABILITIES = {
+    provider: "codex",
+    nativeStructuredQuestions: false,
+    generatedSkills: "stable",
+    promptAliases: "unavailable",
+    nativeParallelSubagents: "session_dependent",
+    sequentialFallback: true,
+    mcpTransport: "planned",
+    notes: [
+        "Codex generated skills are the preferred native surface.",
+        "Installed prompt files are not guaranteed to become slash commands in current Codex builds.",
+        "Native parallel subagents may exist in an interactive session, but the npm CLI must not require them.",
+        "Sequential panel fallback is the stable provider-neutral path."
+    ]
+};
+export function getCodexProviderCapabilities() {
+    return CODEX_PROVIDER_CAPABILITIES;
+}
 export function normalizeResearcherProfile(profile) {
     return {
         field: profile.field,
@@ -47,6 +65,41 @@ export function renderCheckpointPrompt(spec, guidance) {
     sections.push(buildNumberedCheckpointPrompt(spec));
     return sections.join("\n\n");
 }
+export function questionRecordToNumberedCheckpointSpec(record) {
+    const options = [
+        ...record.prompt.options.map((option) => ({
+            value: option.value,
+            label: option.description ? `${option.label} — ${option.description}` : option.label
+        })),
+        ...(record.prompt.allowOther
+            ? [{
+                    value: "other",
+                    label: record.prompt.otherLabel ?? "Other"
+                }]
+            : [])
+    ];
+    return {
+        title: record.prompt.title,
+        instructions: [
+            record.prompt.question,
+            ...record.prompt.rationale.map((entry) => `Why now: ${entry}`),
+            `Question id: ${record.id}`,
+            `Checkpoint: ${record.prompt.checkpointKey ?? "manual"}`,
+            `Required: ${record.prompt.required ? "yes" : "no"}`
+        ].join("\n"),
+        options,
+        allowRationale: true
+    };
+}
+export function renderQuestionRecordPrompt(record) {
+    const spec = questionRecordToNumberedCheckpointSpec(record);
+    return {
+        questionId: record.id,
+        checkpointKey: record.prompt.checkpointKey ?? "manual",
+        spec,
+        prompt: buildNumberedCheckpointPrompt(spec)
+    };
+}
 export function parseCheckpointResponse(spec, input) {
     return parseNumberedCheckpointResponse(spec, input);
 }
@@ -102,4 +155,5 @@ export function createCodexRuntimeBridge(setup) {
     };
 }
 export * from "./config.js";
+export * from "./skills.js";
 export * from "./wrapper.js";

package/dist/skills.d.ts

@@ -0,0 +1,16 @@
+import type { RoleDefinition } from "@longtable/core";
+export interface CodexSkillSpec {
+    name: string;
+    description: string;
+    body: string[];
+}
+export interface InstalledCodexSkill {
+    name: string;
+    path: string;
+    description: string;
+}
+export declare function resolveCodexSkillsDir(customDir?: string): string;
+export declare function buildCodexSkillSpecs(roles: RoleDefinition[]): CodexSkillSpec[];
+export declare function installCodexSkills(roles: RoleDefinition[], customDir?: string): Promise<InstalledCodexSkill[]>;
+export declare function removeCodexSkills(roles: RoleDefinition[], customDir?: string): Promise<string[]>;
+export declare function listInstalledCodexSkills(roles: RoleDefinition[], customDir?: string): Promise<InstalledCodexSkill[]>;

package/dist/skills.js

@@ -0,0 +1,214 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export function resolveCodexSkillsDir(customDir) {
+    return customDir ? resolve(customDir) : join(homedir(), ".codex", "skills");
+}
+function skillNameForRole(role) {
+    return `longtable-${role.key.replaceAll("_", "-")}`;
+}
+function yamlString(value) {
+    return JSON.stringify(value);
+}
+function renderSkillFile(spec) {
+    return [
+        "---",
+        `name: ${spec.name}`,
+        `description: ${yamlString(spec.description)}`,
+        "---",
+        "",
+        `# ${spec.name}`,
+        "",
+        ...spec.body
+    ].join("\n");
+}
+function baseSkillSpecs() {
+    return [
+        {
+            name: "longtable",
+            description: "Use for LongTable research conversations, lt explore/review/panel requests, researcher checkpoints, and role routing.",
+            body: [
+                "## Purpose",
+                "",
+                "Act as the LongTable adapter inside Codex. LongTable is a researcher-centered workspace, not a replacement for the researcher.",
+                "",
+                "## Natural Invocation",
+                "",
+                "Use this skill when the user says things like:",
+                "",
+                "- `longtable: help me narrow this project`",
+                "- `lt explore: ...`",
+                "- `lt review: ...`",
+                "- `lt panel: ...`",
+                "- `use the LongTable methods critic on this design`",
+                "",
+                "## Routing Rules",
+                "",
+                "- `lt explore` keeps the problem open and asks clarifying or tension questions before recommending closure.",
+                "- `lt review` starts with the strongest weakness, objection, or missing evidence.",
+                "- `lt panel` creates a visible multi-role review with synthesis, role opinions, conflict summary, and a decision prompt.",
+                "- Natural references to methods, measurement, theory, reviewer, editor, ethics, venue, or voice should foreground the matching LongTable role.",
+                "- When research responsibility is about to shift, surface a Researcher Checkpoint before closure.",
+                "- When changing LongTable product language, README positioning, or checkpoint policy, surface a Meta-Decision Checkpoint first.",
+                "",
+                "## Panel And Team Behavior",
+                "",
+                "- If the user asks for a panel, team, disagreement, or multiple perspectives, treat that as permission to coordinate multiple LongTable roles.",
+                "- Use provider-native subagents only when the current Codex runtime makes them available and the user's request clearly calls for multi-agent work.",
+                "- If native subagents are unavailable, use LongTable's sequential panel fallback and make the fallback explicit in the technical record.",
+                "- Do not expose hidden reasoning, tool logs, or private chain-of-thought. Expose a structured deliberation record instead.",
+                "",
+                "## Project State",
+                "",
+                "- Treat `.longtable/` state as the source of truth when present.",
+                "- Read `CURRENT.md` when available before giving project-specific advice.",
+                "- If a Researcher Checkpoint is needed, ask a concise question with meaningful options and wait for the researcher.",
+                "- If a checkpoint allows `other`, make `other` visible instead of hiding it in state.",
+                "- Treat provider-native question UI as transport; LongTable state records are the source of truth.",
+                "- When the `longtable` CLI is available in a workspace, use `longtable question --print --provider codex --prompt \"...\"` to create and render a canonical checkpoint before proceeding.",
+                "- If `CURRENT.md` shows a pending required checkpoint, do not proceed until `longtable decide --question <id> --answer <value>` records the researcher's choice.",
+                "- Preserve open tensions and authorship instead of forcing closure.",
+                "- Label unsupported external claims as inference or estimate."
+            ]
+        },
+        {
+            name: "longtable-panel",
+            description: "Use when LongTable should run a panel or team-style review with visible role disagreement.",
+            body: [
+                "## Purpose",
+                "",
+                "Run a LongTable panel-style review in Codex.",
+                "",
+                "## When To Use",
+                "",
+                "- The user says `lt panel`.",
+                "- The user asks for disagreement, multiple perspectives, a team review, or pre-commit challenge.",
+                "- The work touches several research risks at once, such as theory, methods, measurement, venue fit, ethics, or authorship.",
+                "",
+                "## Output Contract",
+                "",
+                "Return:",
+                "",
+                "1. LongTable synthesis",
+                "2. Panel opinions by role",
+                "3. Conflict summary",
+                "4. Decision prompt for the researcher",
+                "5. Technical record: roles consulted, execution surface, fallback/native mode, and source/file references used",
+                "",
+                "## Rules",
+                "",
+                "- Do not collapse disagreement too early.",
+                "- Use a Researcher Checkpoint before treating a high-stakes research decision as settled.",
+                "- If the CLI is available, prefer `longtable question --print --provider codex --prompt \"...\"` for canonical numbered checkpoint rendering.",
+                "- Use `longtable panel --print --prompt \"...\"` only as an optional canonical prompt aid, not as the user's primary interface."
+            ]
+        },
+        {
+            name: "longtable-explore",
+            description: "Use for early LongTable research exploration, problem framing, and question narrowing.",
+            body: [
+                "## Purpose",
+                "",
+                "Help the researcher keep the problem open long enough to find a defensible research question.",
+                "",
+                "## Rules",
+                "",
+                "- Ask at least two clarifying or tension questions before recommending a direction.",
+                "- Surface scope boundaries, candidate constructs, and hidden assumptions.",
+                "- Keep unresolved tensions visible.",
+                "- Avoid generic search advice unless the user asks for evidence discovery."
+            ]
+        },
+        {
+            name: "longtable-review",
+            description: "Use for LongTable critical review of a claim, paragraph, study design, manuscript section, or plan.",
+            body: [
+                "## Purpose",
+                "",
+                "Review a research object without smoothing over weaknesses.",
+                "",
+                "## Rules",
+                "",
+                "- Start with the most important weakness, objection, or missing evidence.",
+                "- Separate sourced facts, interpretation, and speculation.",
+                "- Preserve the researcher's own language where possible.",
+                "- Ask a checkpoint question before treating a high-stakes decision as settled."
+            ]
+        }
+    ];
+}
+function roleSkillSpec(role) {
+    const label = role.label;
+    return {
+        name: skillNameForRole(role),
+        description: `Use the LongTable ${label} role: ${role.shortDescription}`,
+        body: [
+            "## Purpose",
+            "",
+            `Foreground the LongTable ${label} role.`,
+            "",
+            "## Natural Triggers",
+            "",
+            role.synonyms.map((synonym) => `- ${synonym}`).join("\n"),
+            "",
+            "## Role Focus",
+            "",
+            role.shortDescription,
+            "",
+            "## Rules",
+            "",
+            `- Disclose: \`LongTable consulted: ${label}\`.`,
+            "- Keep the role grounded in the user's research object and project state.",
+            "- Do not invent a separate role definition; this skill is an adapter generated from the LongTable role registry.",
+            "- If evidence is needed, ask whether the researcher wants scholarly search or citation verification.",
+            "- If the role's judgment would change the project direction, ask a Researcher Checkpoint before closure."
+        ]
+    };
+}
+export function buildCodexSkillSpecs(roles) {
+    return [...baseSkillSpecs(), ...roles.map(roleSkillSpec)];
+}
+export async function installCodexSkills(roles, customDir) {
+    const skillsDir = resolveCodexSkillsDir(customDir);
+    await mkdir(skillsDir, { recursive: true });
+    const installed = [];
+    for (const spec of buildCodexSkillSpecs(roles)) {
+        const skillDir = join(skillsDir, spec.name);
+        await mkdir(skillDir, { recursive: true });
+        const path = join(skillDir, "SKILL.md");
+        await writeFile(path, renderSkillFile(spec), "utf8");
+        installed.push({
+            name: spec.name,
+            path,
+            description: spec.description
+        });
+    }
+    return installed;
+}
+export async function removeCodexSkills(roles, customDir) {
+    const skillsDir = resolveCodexSkillsDir(customDir);
+    const removed = [];
+    for (const spec of buildCodexSkillSpecs(roles)) {
+        const skillDir = join(skillsDir, spec.name);
+        if (existsSync(skillDir)) {
+            await rm(skillDir, { recursive: true, force: true });
+            removed.push(skillDir);
+        }
+    }
+    return removed;
+}
+export async function listInstalledCodexSkills(roles, customDir) {
+    const skillsDir = resolveCodexSkillsDir(customDir);
+    if (!existsSync(skillsDir)) {
+        return [];
+    }
+    const entries = new Set(await readdir(skillsDir));
+    return buildCodexSkillSpecs(roles)
+        .filter((spec) => entries.has(spec.name) && existsSync(join(skillsDir, spec.name, "SKILL.md")))
+        .map((spec) => ({
+        name: spec.name,
+        path: join(skillsDir, spec.name, "SKILL.md"),
+        description: spec.description
+    }));
+}

package/dist/wrapper.d.ts

@@ -1,3 +1,4 @@
+import { classifyCheckpointTrigger } from "@longtable/checkpoints";
 import type { InteractionMode, ResearchStage, RuntimeGuidance } from "@longtable/core";
 export interface CodexThinWrapperOptions {
     prompt: string;
@@ -9,6 +10,8 @@ export interface CodexThinWrapperOptions {
 export interface CodexWrappedPrompt {
     mode: InteractionMode;
     researchStage: ResearchStage;
+    checkpointKey: string;
+    checkpointTrigger: ReturnType<typeof classifyCheckpointTrigger>;
     guidance: RuntimeGuidance;
     wrappedPrompt: string;
     setupLoaded: boolean;

package/dist/wrapper.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { cwd } from "node:process";
-import { resolveCheckpointPolicy, resolveRuntimeGuidance } from "@longtable/checkpoints";
+import { classifyCheckpointTrigger, resolveCheckpointPolicy, resolveRuntimeGuidance } from "@longtable/checkpoints";
 import { loadSetupOutput, resolveDefaultSetupPath } from "@longtable/setup";
 import { normalizeResearcherProfile, renderRuntimeGuidance } from "./index.js";
 function defaultProfile() {
@@ -32,20 +32,6 @@ function defaultStage(mode) {
             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)) {
@@ -67,27 +53,26 @@ function readPromptFromStdin() {
 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,
+    const fallbackMode = defaultMode(setup ?? undefined);
+    const trigger = classifyCheckpointTrigger(prompt, {
+        preferredMode: options.mode,
+        fallbackMode,
+        researchStage: options.researchStage ?? (options.mode ? defaultStage(options.mode) : undefined),
         unresolvedTensions: setup?.initialState.openTensions ?? [],
         studyContract: setup?.initialState.studyContract
-    };
-    const policy = resolveCheckpointPolicy(profile, signal);
-    const guidance = resolveRuntimeGuidance(profile, signal, policy);
-    const sections = [renderRuntimeGuidance(guidance)];
+    });
+    const policy = resolveCheckpointPolicy(profile, trigger.signal);
+    const guidance = resolveRuntimeGuidance(profile, trigger.signal, policy);
+    const triggerLines = [
+        "LongTable checkpoint trigger",
+        `- checkpoint: ${trigger.signal.checkpointKey}`,
+        `- trigger family: ${trigger.family}`,
+        `- confidence: ${trigger.confidence}`,
+        `- status: ${trigger.requiresQuestionBeforeClosure ? "question required before closure" : "advisory guidance"}`,
+        `- rationale: ${trigger.rationale.join(" ")}`
+    ];
+    const sections = [triggerLines.join("\n"), renderRuntimeGuidance(guidance)];
     const instructionLines = [
         "LongTable ordering rules",
         guidance.minimumQuestions > 0 || guidance.mustAskBeforeClosure
@@ -104,8 +89,10 @@ export async function buildCodexThinWrappedPrompt(options) {
     sections.push(instructionLines.join("\n"));
     sections.push(["User prompt", prompt].join("\n"));
     return {
-        mode,
-        researchStage,
+        mode: trigger.signal.mode,
+        researchStage: trigger.signal.researchStage,
+        checkpointKey: trigger.signal.checkpointKey,
+        checkpointTrigger: trigger,
         guidance,
         wrappedPrompt: sections.join("\n\n"),
         setupLoaded: Boolean(setup)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtable/provider-codex",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "private": false,
   "description": "Codex adapter surface for LongTable",
   "type": "module",
@@ -15,9 +15,9 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@longtable/checkpoints": "0.1.9",
-    "@longtable/core": "0.1.9",
-    "@longtable/setup": "0.1.9"
+    "@longtable/checkpoints": "0.1.11",
+    "@longtable/core": "0.1.11",
+    "@longtable/setup": "0.1.11"
   },
   "devDependencies": {
     "@types/node": "^22.10.1",
@@ -42,5 +42,11 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   }
 }