@longtable/mcp 0.1.32 → 0.1.34

package/README.md

@@ -15,7 +15,7 @@ longtable-state
 Run:
 
 ```bash
-npx -y @longtable/mcp@0.1.32
+npx -y @longtable/mcp@0.1.34
 ```
 
 Self-test:

package/dist/first-research-shape.d.ts

@@ -0,0 +1,25 @@
+import type { QuestionOption } from "@longtable/core";
+export interface FirstResearchShape {
+    handle: string;
+    currentGoal: string;
+    currentBlocker?: string;
+    researchObject?: string;
+    gapRisk?: string;
+    protectedDecision?: string;
+    openQuestions: string[];
+    nextAction: string;
+    confidence: "low" | "medium" | "high";
+    sourceHookId?: string;
+    confirmedAt?: string;
+}
+export interface FirstResearchShapeQuestionSpec {
+    prompt: string;
+    title: string;
+    question: string;
+    checkpointKey: string;
+    options: QuestionOption[];
+    displayReason: string;
+}
+export declare function buildFirstResearchShapeQuestion(shape: FirstResearchShape): FirstResearchShapeQuestionSpec;
+export declare function firstResearchShapeAnswerConfirms(answer: string): boolean;
+export declare function firstResearchShapeAnswerStatus(answer: string): "confirmed" | "active" | "deferred";

package/dist/first-research-shape.js

@@ -0,0 +1,111 @@
+function questionTitle(shape) {
+    if (shape.protectedDecision) {
+        return "Protected Research Decision";
+    }
+    if (shape.currentBlocker) {
+        return "Main Unresolved Issue";
+    }
+    return "Emerging Research Direction";
+}
+function questionText(shape) {
+    if (shape.protectedDecision) {
+        return "Before LongTable moves forward, what protected research decision should stay explicit?";
+    }
+    if (shape.currentBlocker) {
+        return "What should LongTable do with the main unresolved issue in this emerging study?";
+    }
+    if (shape.openQuestions.length > 0) {
+        return "What should LongTable keep explicit as the next research move?";
+    }
+    return "How should LongTable carry this emerging study forward?";
+}
+function displayReason(shape) {
+    if (shape.protectedDecision) {
+        return `The interview surfaced a protected decision: ${shape.protectedDecision}. LongTable should not let it settle silently.`;
+    }
+    if (shape.currentBlocker) {
+        return `The main blocker is still open: ${shape.currentBlocker}. The next move should make that uncertainty explicit.`;
+    }
+    if (shape.openQuestions.length > 0) {
+        return `The interview surfaced open research questions. Choose the next move that keeps the most important one visible.`;
+    }
+    return "LongTable has enough context to propose a provisional research direction, but the next research move should still be explicit.";
+}
+function recommendedValue(shape) {
+    if (shape.protectedDecision) {
+        return "protect_decision";
+    }
+    if (shape.confidence === "high" && !shape.currentBlocker) {
+        return "stabilize_shape";
+    }
+    if (shape.currentBlocker || shape.confidence === "low") {
+        return "gather_context";
+    }
+    return "stabilize_shape";
+}
+function baseOptions(shape) {
+    const recommended = recommendedValue(shape);
+    const options = [];
+    if (shape.protectedDecision) {
+        options.push({
+            value: "protect_decision",
+            label: "Keep the protected decision open",
+            description: `Treat this as the guarded judgment while the broader direction stays provisional: ${shape.protectedDecision}`,
+            recommended: recommended === "protect_decision"
+        });
+    }
+    options.push({
+        value: "stabilize_shape",
+        label: "Use this as the provisional direction",
+        description: "Carry this research shape forward as the current working direction.",
+        recommended: recommended === "stabilize_shape"
+    }, {
+        value: "gather_context",
+        label: "Gather one more concrete case",
+        description: "Ask for one more scene, source, dataset, or example before stabilizing it.",
+        recommended: recommended === "gather_context"
+    }, {
+        value: "revise_shape",
+        label: "Revise the emerging shape",
+        description: "Change the handle, blocker, or next action before LongTable treats it as usable."
+    });
+    if (!shape.protectedDecision) {
+        options.push({
+            value: "keep_open",
+            label: "Keep the study open longer",
+            description: "Do not stabilize this direction yet."
+        });
+    }
+    return options;
+}
+export function buildFirstResearchShapeQuestion(shape) {
+    const summaryLines = [
+        "LongTable has enough context to propose a provisional research direction.",
+        `Handle: ${shape.handle}`,
+        `Goal: ${shape.currentGoal}`,
+        shape.currentBlocker ? `Blocker: ${shape.currentBlocker}` : undefined,
+        shape.protectedDecision ? `Protected decision: ${shape.protectedDecision}` : undefined,
+        shape.openQuestions.length > 0 ? `Open question: ${shape.openQuestions[0]}` : undefined,
+        `Next action: ${shape.nextAction}`
+    ].filter(Boolean);
+    return {
+        prompt: summaryLines.join("\n"),
+        title: questionTitle(shape),
+        question: questionText(shape),
+        checkpointKey: "first_research_shape_confirmation",
+        options: baseOptions(shape),
+        displayReason: displayReason(shape)
+    };
+}
+export function firstResearchShapeAnswerConfirms(answer) {
+    return answer === "stabilize_shape" || answer === "protect_decision";
+}
+export function firstResearchShapeAnswerStatus(answer) {
+    if (firstResearchShapeAnswerConfirms(answer)) {
+        return "confirmed";
+    }
+    if (answer === "keep_open") {
+        return "deferred";
+    }
+    return "active";
+}

package/dist/index.d.ts

@@ -1 +1,2 @@
+export * from "./first-research-shape.js";
 export * from "./server.js";

package/dist/index.js

@@ -1 +1,2 @@
+export * from "./first-research-shape.js";
 export * from "./server.js";

package/dist/server.js

@@ -10,9 +10,10 @@ import { classifyCheckpointTrigger } from "@longtable/checkpoints";
 import { renderQuestionRecordInput } from "@longtable/provider-claude";
 import { renderQuestionRecordPrompt } from "@longtable/provider-codex";
 import { loadSetupOutput } from "@longtable/setup";
-import { answerWorkspaceQuestion, createOrUpdateProjectWorkspace, createWorkspaceQuestion, inspectProjectWorkspace, loadProjectContextFromDirectory, loadWorkspaceState, syncCurrentWorkspaceView } from "@longtable/cli";
+import { answerWorkspaceQuestion, clearWorkspaceQuestion, createOrUpdateProjectWorkspace, createWorkspaceQuestion, inspectProjectWorkspace, loadProjectContextFromDirectory, loadWorkspaceState, syncCurrentWorkspaceView } from "@longtable/cli";
+import { buildFirstResearchShapeQuestion, firstResearchShapeAnswerConfirms, firstResearchShapeAnswerStatus } from "./first-research-shape.js";
 const SERVER_NAME = "longtable-state";
-const SERVER_VERSION = "0.1.32";
+const SERVER_VERSION = "0.1.34";
 const TOOL_NAMES = [
     "read_project",
     "read_session",
@@ -48,7 +49,9 @@ const firstResearchShapeSchema = z.object({
     protectedDecision: z.string().optional(),
     openQuestions: z.array(z.string().min(1)).default([]),
     nextAction: z.string().min(1),
-    confidence: z.enum(["low", "medium", "high"]).default("medium")
+    confidence: z.enum(["low", "medium", "high"]).default("medium"),
+    sourceHookId: z.string().optional(),
+    confirmedAt: z.string().optional()
 });
 function textResult(structuredContent) {
     return {
@@ -88,10 +91,14 @@ function createId(prefix) {
 function asInterviewState(state) {
     return state;
 }
+function isInterviewHookRun(hook) {
+    return hook?.kind === "longtable_interview";
+}
 function activeInterviewHook(state, hookId) {
     const hooks = state.hooks ?? [];
     if (hookId) {
-        return hooks.find((hook) => hook.id === hookId);
+        const hook = hooks.find((candidate) => candidate.id === hookId);
+        return isInterviewHookRun(hook) ? hook : undefined;
     }
     return [...hooks].reverse().find((hook) => hook.kind === "longtable_interview" &&
         (hook.status === "pending" || hook.status === "active" || hook.status === "ready_to_confirm"));
@@ -106,6 +113,61 @@ function upsertInterviewHook(state, hook) {
         hooks: nextHooks
     };
 }
+function upsertQuestionObligation(state, obligation) {
+    const current = state.questionObligations ?? [];
+    const next = current.some((entry) => entry.id === obligation.id)
+        ? current.map((entry) => entry.id === obligation.id ? obligation : entry)
+        : [...current, obligation];
+    return {
+        ...state,
+        questionObligations: next
+    };
+}
+function ensureFirstResearchShapeObligation(state, shape, options) {
+    const existing = (state.questionObligations ?? []).find((obligation) => obligation.kind === "first_research_shape_confirmation" &&
+        obligation.status === "pending" &&
+        obligation.sourceHookId === shape.sourceHookId);
+    if (!existing) {
+        return upsertQuestionObligation(state, {
+            id: createId("question_obligation"),
+            kind: "first_research_shape_confirmation",
+            status: "pending",
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            prompt: options.prompt,
+            reason: options.reason,
+            ...(shape.sourceHookId ? { sourceHookId: shape.sourceHookId } : {}),
+            ...(options.questionId ? { questionId: options.questionId } : {})
+        });
+    }
+    return upsertQuestionObligation(state, {
+        ...existing,
+        updatedAt: new Date().toISOString(),
+        prompt: options.prompt,
+        reason: options.reason,
+        ...(options.questionId ? { questionId: options.questionId } : existing.questionId ? { questionId: existing.questionId } : {}),
+        ...(shape.sourceHookId ? { sourceHookId: shape.sourceHookId } : {})
+    });
+}
+function resolveFirstResearchShapeObligation(state, options) {
+    return {
+        ...state,
+        questionObligations: (state.questionObligations ?? []).map((obligation) => {
+            const matches = obligation.kind === "first_research_shape_confirmation" && ((options.sourceHookId && obligation.sourceHookId === options.sourceHookId) ||
+                (options.questionId && obligation.questionId === options.questionId));
+            if (!matches || obligation.status !== "pending") {
+                return obligation;
+            }
+            return {
+                ...obligation,
+                status: options.status ?? "satisfied",
+                updatedAt: new Date().toISOString(),
+                ...(options.questionId ? { questionId: options.questionId } : obligation.questionId ? { questionId: obligation.questionId } : {}),
+                ...(options.decisionId ? { decisionId: options.decisionId } : obligation.decisionId ? { decisionId: obligation.decisionId } : {})
+            };
+        })
+    };
+}
 function interviewDepth(turns) {
     const usableTurns = turns.filter((turn) => turn.quality !== "thin").length;
     if (usableTurns >= 3)
@@ -136,6 +198,19 @@ async function beginInterviewHook(context, options) {
     if (existing) {
         return { hook: existing, state };
     }
+    const confirmedShape = state.firstResearchShape?.confirmedAt ? state.firstResearchShape : undefined;
+    if (confirmedShape) {
+        const confirmedHook = [...(state.hooks ?? [])].reverse().find((hook) => isInterviewHookRun(hook) &&
+            hook.status === "confirmed" &&
+            hook.firstResearchShape?.handle === confirmedShape.handle);
+        return {
+            hook: confirmedHook,
+            state,
+            alreadyConfirmed: true,
+            shape: confirmedShape,
+            nextQuestion: options.openingQuestion ?? confirmedShape.openQuestions[0] ?? confirmedShape.nextAction
+        };
+    }
     const timestamp = new Date().toISOString();
     const hook = {
         id: createId("hook_interview"),
@@ -283,6 +358,22 @@ function renderQuestionFallback(record, provider = "codex") {
         ? renderQuestionRecordInput(record)
         : renderQuestionRecordPrompt(record);
 }
+function compactInterviewHook(hook) {
+    if (!hook) {
+        return undefined;
+    }
+    return {
+        id: hook.id,
+        kind: hook.kind,
+        status: hook.status,
+        depth: hook.depth,
+        provider: hook.provider,
+        turnCount: hook.turns?.length ?? 0,
+        firstResearchShape: hook.firstResearchShape?.handle,
+        createdAt: hook.createdAt,
+        updatedAt: hook.updatedAt
+    };
+}
 async function markQuestionTransport(context, questionId, status, message) {
     const state = asInterviewState(await loadWorkspaceState(context));
     let updatedQuestion = null;
@@ -355,31 +446,10 @@ function acceptedAnswer(result) {
         answer
     };
 }
-function buildFirstResearchShapeQuestion(shape) {
-    return {
-        prompt: [
-            "Confirm the LongTable First Research Shape.",
-            `Handle: ${shape.handle}`,
-            `Goal: ${shape.currentGoal}`,
-            shape.currentBlocker ? `Blocker: ${shape.currentBlocker}` : undefined,
-            `Next action: ${shape.nextAction}`
-        ].filter(Boolean).join("\n"),
-        title: "First Research Shape",
-        question: "How should LongTable treat this first research handle?",
-        checkpointKey: "first_research_shape_confirmation",
-        displayReason: "This is the first structured handoff from open interview to durable project state.",
-        options: [
-            { value: "confirm", label: "Confirm this handle", description: "Use this as the provisional research handle.", recommended: true },
-            { value: "revise", label: "Revise the handle", description: "Keep interviewing before recording this shape." },
-            { value: "gather_context", label: "Gather more context", description: "Ask for one more scene, case, source, or material first." },
-            { value: "defer", label: "Keep it open", description: "Do not treat the research handle as ready yet." }
-        ]
-    };
-}
 async function markFirstResearchShapeConfirmation(context, shape, answer, questionId, decisionId) {
     const state = asInterviewState(await loadWorkspaceState(context));
     const timestamp = new Date().toISOString();
-    const confirmedShape = answer === "confirm"
+    const confirmedShape = firstResearchShapeAnswerConfirms(answer)
         ? { ...shape, confirmedAt: timestamp }
         : shape;
     state.firstResearchShape = confirmedShape;
@@ -388,12 +458,12 @@ async function markFirstResearchShapeConfirmation(context, shape, answer, questi
         firstResearchShape: confirmedShape
     };
     state.hooks = (state.hooks ?? []).map((hook) => {
-        if (hook.id !== shape.sourceHookId) {
+        if (hook.id !== shape.sourceHookId || !isInterviewHookRun(hook)) {
             return hook;
         }
         return {
             ...hook,
-            status: answer === "confirm" ? "confirmed" : answer === "defer" ? "deferred" : "active",
+            status: firstResearchShapeAnswerStatus(answer),
             updatedAt: timestamp,
             firstResearchShape: confirmedShape,
             linkedQuestionRecordIds: questionId
@@ -404,6 +474,12 @@ async function markFirstResearchShapeConfirmation(context, shape, answer, questi
                 : hook.linkedDecisionRecordIds
         };
     });
+    const nextState = resolveFirstResearchShapeObligation(state, {
+        sourceHookId: shape.sourceHookId,
+        questionId,
+        decisionId,
+        status: "satisfied"
+    });
     const session = {
         ...context.session,
         firstResearchShape: confirmedShape,
@@ -411,9 +487,49 @@ async function markFirstResearchShapeConfirmation(context, shape, answer, questi
     };
     context.session = session;
     await writeFile(context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
-    await writeFile(context.stateFilePath, JSON.stringify(state, null, 2), "utf8");
+    await writeFile(context.stateFilePath, JSON.stringify(nextState, null, 2), "utf8");
     await syncCurrentWorkspaceView(context);
-    return { state, session, shape: confirmedShape };
+    return { state: nextState, session, shape: confirmedShape };
+}
+async function markAlreadyConfirmedFirstResearchShape(context, shape) {
+    const state = asInterviewState(await loadWorkspaceState(context));
+    const timestamp = new Date().toISOString();
+    const confirmedShape = shape.confirmedAt ? shape : { ...shape, confirmedAt: timestamp };
+    state.firstResearchShape = confirmedShape;
+    state.workingState = {
+        ...state.workingState,
+        firstResearchShape: confirmedShape
+    };
+    state.hooks = (state.hooks ?? []).map((hook) => {
+        if (!isInterviewHookRun(hook)) {
+            return hook;
+        }
+        const matchesSource = shape.sourceHookId && hook.id === shape.sourceHookId;
+        const matchesHandle = !shape.sourceHookId && hook.firstResearchShape?.handle === shape.handle;
+        if (!matchesSource && !matchesHandle) {
+            return hook;
+        }
+        return {
+            ...hook,
+            status: "confirmed",
+            updatedAt: timestamp,
+            firstResearchShape: confirmedShape
+        };
+    });
+    const nextState = resolveFirstResearchShapeObligation(state, {
+        sourceHookId: confirmedShape.sourceHookId,
+        status: "satisfied"
+    });
+    const session = {
+        ...context.session,
+        firstResearchShape: confirmedShape,
+        lastUpdatedAt: timestamp
+    };
+    context.session = session;
+    await writeFile(context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
+    await writeFile(context.stateFilePath, JSON.stringify(nextState, null, 2), "utf8");
+    await syncCurrentWorkspaceView(context);
+    return { state: nextState, session, shape: confirmedShape };
 }
 function statusForElicitationError(error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -565,7 +681,18 @@ export function createLongTableMcpServer() {
                 openingQuestion,
                 seedAnswer
             });
-            return textResult(result);
+            return textResult({
+                hook: compactInterviewHook(result.hook),
+                alreadyConfirmed: "alreadyConfirmed" in result ? Boolean(result.alreadyConfirmed) : false,
+                shape: "shape" in result ? result.shape : result.hook?.firstResearchShape,
+                nextQuestion: "nextQuestion" in result ? result.nextQuestion : openingQuestion,
+                workspace: {
+                    projectName: context.project.projectName,
+                    currentGoal: context.session.currentGoal,
+                    currentBlocker: context.session.currentBlocker,
+                    nextAction: context.session.nextAction
+                }
+            });
         }
         catch (error) {
             return errorResult(error instanceof Error ? error.message : String(error));
@@ -617,7 +744,16 @@ export function createLongTableMcpServer() {
                 hookId,
                 shape: shape
             });
-            return textResult(result);
+            return textResult({
+                hook: compactInterviewHook(result.hook),
+                shape: result.shape,
+                session: {
+                    currentGoal: result.session.currentGoal,
+                    currentBlocker: result.session.currentBlocker,
+                    nextAction: result.session.nextAction,
+                    firstResearchShape: result.session.firstResearchShape
+                }
+            });
         }
         catch (error) {
             return errorResult(error instanceof Error ? error.message : String(error));
@@ -639,6 +775,13 @@ export function createLongTableMcpServer() {
             if (!shape) {
                 return errorResult("No First Research Shape was found to confirm. Run summarize_interview first.");
             }
+            if (shape.confirmedAt) {
+                const confirmation = await markAlreadyConfirmedFirstResearchShape(context, shape);
+                return textResult({
+                    shape: confirmation.shape,
+                    elicitation: { attempted: false, reason: "already_confirmed" }
+                });
+            }
             const spec = buildFirstResearchShapeQuestion(shape);
             const created = await createWorkspaceQuestion({
                 context,
@@ -651,6 +794,13 @@ export function createLongTableMcpServer() {
                 provider: provider,
                 required: true
             });
+            const createdState = ensureFirstResearchShapeObligation(asInterviewState(await loadWorkspaceState(context)), shape, {
+                prompt: spec.question,
+                reason: spec.displayReason,
+                questionId: created.question.id
+            });
+            await writeFile(context.stateFilePath, JSON.stringify(createdState, null, 2), "utf8");
+            await syncCurrentWorkspaceView(context);
             const fallback = renderQuestionFallback(created.question, provider);
             if (fallbackOnly) {
                 const marked = await markQuestionTransport(context, created.question.id, "fallback_rendered", "MCP elicitation skipped by fallbackOnly.");
@@ -670,8 +820,15 @@ export function createLongTableMcpServer() {
                         ? "declined"
                         : "fallback_rendered";
                     const marked = await markQuestionTransport(context, created.question.id, status, `MCP elicitation returned action: ${elicited.action}.`);
+                    const cleared = status === "declined"
+                        ? await clearWorkspaceQuestion({
+                            context,
+                            questionId: created.question.id,
+                            reason: `MCP elicitation returned action: ${elicited.action}; confirmation was deferred without a research-direction decision.`
+                        })
+                        : undefined;
                     return textResult({
-                        question: marked ?? created.question,
+                        question: cleared?.question ?? marked ?? created.question,
                         shape,
                         elicitation: { attempted: true, action: elicited.action },
                         fallback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtable/mcp",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "private": false,
   "description": "LongTable MCP transport for workspace state and Researcher Checkpoints",
   "type": "module",
@@ -26,12 +26,12 @@
     "self-test": "node ./dist/server.js --self-test"
   },
   "dependencies": {
-    "@longtable/checkpoints": "0.1.32",
-    "@longtable/cli": "0.1.32",
-    "@longtable/core": "0.1.32",
-    "@longtable/provider-claude": "0.1.32",
-    "@longtable/provider-codex": "0.1.32",
-    "@longtable/setup": "0.1.32",
+    "@longtable/checkpoints": "0.1.34",
+    "@longtable/cli": "0.1.34",
+    "@longtable/core": "0.1.34",
+    "@longtable/provider-claude": "0.1.34",
+    "@longtable/provider-codex": "0.1.34",
+    "@longtable/setup": "0.1.34",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.0"
   },