@longtable/mcp 0.1.32 → 0.1.33

package/README.md

@@ -15,7 +15,7 @@ longtable-state
 Run:
 
 ```bash
-npx -y @longtable/mcp@0.1.32
+npx -y @longtable/mcp@0.1.33
 ```
 
 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 should stay explicitly open about ${shape.protectedDecision}?`;
+    }
+    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 ${shape.protectedDecision} open`,
+            description: "Treat this as the guarded judgment while the broader direction stays provisional.",
+            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

@@ -11,8 +11,9 @@ 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 { buildFirstResearchShapeQuestion, firstResearchShapeAnswerConfirms, firstResearchShapeAnswerStatus } from "./first-research-shape.js";
 const SERVER_NAME = "longtable-state";
-const SERVER_VERSION = "0.1.32";
+const SERVER_VERSION = "0.1.33";
 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)
@@ -267,10 +329,15 @@ async function summarizeInterviewHook(context, options) {
         visibility: "explicit",
         importance: shape.confidence
     });
+    const questionSpec = buildFirstResearchShapeQuestion(shape);
+    const withObligation = ensureFirstResearchShapeObligation(updated, shape, {
+        prompt: questionSpec.question,
+        reason: questionSpec.displayReason
+    });
     await writeFile(context.sessionFilePath, JSON.stringify(session, null, 2), "utf8");
-    await writeFile(context.stateFilePath, JSON.stringify(updated, null, 2), "utf8");
+    await writeFile(context.stateFilePath, JSON.stringify(withObligation, null, 2), "utf8");
     await syncCurrentWorkspaceView(context);
-    return { hook, shape, state: updated, session };
+    return { hook, shape, state: withObligation, session };
 }
 function findQuestion(records, questionId) {
     if (questionId) {
@@ -355,31 +422,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 +434,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 +450,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 +463,9 @@ 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 };
 }
 function statusForElicitationError(error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -651,6 +703,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.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtable/mcp",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "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.33",
+    "@longtable/cli": "0.1.33",
+    "@longtable/core": "0.1.33",
+    "@longtable/provider-claude": "0.1.33",
+    "@longtable/provider-codex": "0.1.33",
+    "@longtable/setup": "0.1.33",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.0"
   },