@askthew/mcp-plugin 0.2.8 → 0.4.0

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,349 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { codingSessionSignalSchema, createAskTheWMcpServer, normalizeInstallTokenInput, redactCodingSessionSignal, redactProvenanceSignal, } from "./index.js";
+test("install token normalization accepts copied shell-quoted values", () => {
+    assert.equal(normalizeInstallTokenInput("'atw_mcp_token'"), "atw_mcp_token");
+    assert.equal(normalizeInstallTokenInput('"atw_mcp_token"'), "atw_mcp_token");
+    assert.equal(normalizeInstallTokenInput("  atw_mcp_token  "), "atw_mcp_token");
+});
+test("coding session signal schema accepts compact checkpoints", () => {
+    const parsed = codingSessionSignalSchema.parse({
+        sessionId: "session-1",
+        sequence: 2,
+        kind: "direction_change",
+        summary: "User chose app-level inference and capture-only connector behavior.",
+        evidence: [{ role: "user", excerpt: "the app does many of it" }],
+        filesTouched: ["packages/mcp-plugin/src/index.ts"],
+        commandsRun: ["npm test --workspace @askthew/mcp-plugin"],
+        metadata: { hostType: "codex" },
+    });
+    assert.equal(parsed.kind, "direction_change");
+    assert.equal(parsed.evidence[0]?.role, "user");
+});
+test("coding session signal redaction removes obvious secrets", () => {
+    const redacted = redactCodingSessionSignal({
+        sessionId: "session-1",
+        sequence: 3,
+        kind: "verification_result",
+        summary: "Ran command with sk_live_1234567890abcdefghijklmnop",
+        evidence: [{ role: "assistant", excerpt: "Token eyJabcdefghijklmnopqrstuv.abcdefghijklmnopqrstuv.abcdefghijklmnopqrstuv" }],
+        filesTouched: [],
+        commandsRun: ["curl -H 'Authorization: Bearer AKIA1234567890ABCDEF'"],
+        metadata: { nested: { token: "sk_test_1234567890abcdefghijklmnop" } },
+    });
+    assert.match(redacted.summary, /\[REDACTED\]/);
+    assert.match(redacted.evidence[0]?.excerpt ?? "", /\[REDACTED\]/);
+    assert.match(redacted.commandsRun[0] ?? "", /\[REDACTED\]/);
+    assert.deepEqual(redacted.metadata, { nested: { token: "[REDACTED]" } });
+});
+test("redacts ATW hyphen-segmented install tokens in commands", () => {
+    const redacted = redactCodingSessionSignal({
+        sessionId: "session-1",
+        sequence: 4,
+        kind: "verification_result",
+        summary: "Installed the connector.",
+        evidence: [],
+        filesTouched: [],
+        commandsRun: [
+            "npx @askthew/mcp-plugin install --token atw_mcp_aed8621b-1456-4e63-833b-3c98109b6f18_f56c5683abc123ff --host codex",
+        ],
+        metadata: {},
+    });
+    assert.equal(redacted.commandsRun[0], "npx @askthew/mcp-plugin install --token [REDACTED] --host codex");
+});
+test("strips URL credentials and sensitive query parameters while preserving URL shape", () => {
+    const redacted = redactCodingSessionSignal({
+        sessionId: "session-1",
+        sequence: 5,
+        kind: "session_checkpoint",
+        summary: "Checked https://admin:pass@db.example.com/app?token=secret123&view=signals",
+        evidence: [],
+        filesTouched: [],
+        commandsRun: [],
+        metadata: {},
+    });
+    assert.equal(redacted.summary, "Checked https://[REDACTED]:[REDACTED]@db.example.com/app?token=[REDACTED]&view=signals");
+});
+test("sanitizes sensitive file paths without touching normal repo paths", () => {
+    const redacted = redactCodingSessionSignal({
+        sessionId: "session-1",
+        sequence: 6,
+        kind: "implementation_update",
+        summary: "Updated auth routes.",
+        evidence: [],
+        filesTouched: ["/Users/alice/.ssh/id_rsa", "apps/app/server/auth.ts"],
+        commandsRun: [],
+        metadata: {},
+    });
+    assert.deepEqual(redacted.filesTouched, ["[SENSITIVE_PATH]/id_rsa", "apps/app/server/auth.ts"]);
+});
+test("redacts CLI secret flags and preserves non-sensitive flags", () => {
+    const redacted = redactCodingSessionSignal({
+        sessionId: "session-1",
+        sequence: 7,
+        kind: "verification_result",
+        summary: "Ran setup.",
+        evidence: [],
+        filesTouched: [],
+        commandsRun: ["askthew-mcp install --token supersecret123abc --host codex --password \"secret-value\""],
+        metadata: {},
+    });
+    assert.equal(redacted.commandsRun[0], "askthew-mcp install --token [REDACTED] --host codex --password \"[REDACTED]\"");
+});
+test("redacts high entropy evidence and metadata without applying entropy to summary", () => {
+    const generatedSecret = "aZ9xP0vQ1rS2tU3wX4yZ5aB6cD7eF8gH9";
+    const redacted = redactCodingSessionSignal({
+        sessionId: "session-1",
+        sequence: 8,
+        kind: "session_checkpoint",
+        summary: `Architecture note ${generatedSecret}`,
+        evidence: [{ role: "assistant", excerpt: `Saw token ${generatedSecret}` }],
+        filesTouched: [],
+        commandsRun: [`curl --header X-Test:${generatedSecret}`],
+        metadata: { sample: generatedSecret },
+    });
+    assert.equal(redacted.summary, `Architecture note ${generatedSecret}`);
+    assert.equal(redacted.evidence[0]?.excerpt, "Saw token [REDACTED]");
+    assert.equal(redacted.commandsRun[0], "curl --header X-Test:[REDACTED]");
+    assert.deepEqual(redacted.metadata, { sample: "[REDACTED]" });
+});
+test("redacts PII and payment identifiers", () => {
+    const redacted = redactCodingSessionSignal({
+        sessionId: "session-1",
+        sequence: 9,
+        kind: "session_checkpoint",
+        summary: "Contact patient@hospital.org, SSN 123-45-6789, phone 415-555-1212, card 4242424242424242.",
+        evidence: [],
+        filesTouched: [],
+        commandsRun: [],
+        metadata: {},
+    });
+    assert.equal(redacted.summary, "Contact [REDACTED], SSN [REDACTED], phone [REDACTED], card [REDACTED].");
+});
+test("preserves raw decision-quality signal language and normal paths", () => {
+    const summary = [
+        "User approved switching from REST to GraphQL.",
+        "User rejected Redis caching approach.",
+        "Architecture decision: monorepo over multi-repo.",
+    ].join(" ");
+    const redacted = redactCodingSessionSignal({
+        sessionId: "session-1",
+        sequence: 10,
+        kind: "direction_change",
+        summary,
+        evidence: [],
+        filesTouched: ["apps/app/server/auth.ts"],
+        commandsRun: ["askthew-mcp install --host codex"],
+        metadata: {},
+    });
+    assert.equal(redacted.summary, summary);
+    assert.deepEqual(redacted.filesTouched, ["apps/app/server/auth.ts"]);
+    assert.deepEqual(redacted.commandsRun, ["askthew-mcp install --host codex"]);
+});
+test("provenance metadata is recursively redacted", () => {
+    const redacted = redactProvenanceSignal({
+        source: "mcp_plugin",
+        decision: "Keep raw signal capture.",
+        rationale: "Decision V5 owns extraction.",
+        confidence: 0.9,
+        filesAffected: ["/Users/alice/.env"],
+        sessionId: "session-1",
+        metadata: {
+            nested: {
+                url: "https://admin:secret@example.com/path?api_key=secret123",
+            },
+        },
+    });
+    assert.deepEqual(redacted.filesAffected, ["[SENSITIVE_PATH]/.env"]);
+    assert.equal(redacted.metadata.nested.url, "https://[REDACTED]:[REDACTED]@example.com/path?api_key=[REDACTED]");
+});
+test("happy-path MCP source exposes capture_session_signal and v1 API tools", () => {
+    const source = fs.readFileSync(path.resolve(process.cwd(), "src/index.ts"), "utf8");
+    for (const toolName of [
+        "capture_session_signal",
+        "list_decisions",
+        "get_decision",
+        "create_decision",
+        "update_decision",
+        "delete_decision",
+        "list_outcomes",
+        "get_outcome",
+        "list_outcome_signals",
+        "create_outcome",
+        "update_outcome",
+        "delete_outcome",
+        "get_north_star",
+        "update_north_star",
+        "list_signals",
+        "get_signal",
+    ]) {
+        assert.match(source, new RegExp(`"${toolName}"`));
+    }
+    assert.doesNotMatch(source, /server\.tool\(\s*"verify_install"/);
+    assert.doesNotMatch(source, /server\.tool\(\s*"record_decision"/);
+    assert.doesNotMatch(source, /server\.tool\(\s*"infer_decisions"/);
+    assert.doesNotMatch(source, /server\.tool\(\s*"get_session_decisions"/);
+    assert.doesNotMatch(source, /server\.tool\(\s*"link_outcome"/);
+    assert.doesNotMatch(source, /server\.tool\(\s*"get_decision_feed"/);
+});
+test("v1 API MCP tools dispatch to expected HTTP routes with install-token auth", async () => {
+    const calls = [];
+    const server = createAskTheWMcpServer({
+        apiBaseUrl: "https://askthew.example.com",
+        sendStartupHeartbeat: false,
+        credentials: {
+            installToken: "atw_mcp_tools",
+            clientId: "codex",
+            clientLabel: "Codex",
+            serverName: "askthew",
+        },
+        fetchImpl: (async (url, init) => {
+            calls.push({
+                url: String(url),
+                method: String(init?.method ?? "GET"),
+                headers: init?.headers,
+                body: init?.body ? JSON.parse(String(init.body)) : undefined,
+            });
+            return new Response(JSON.stringify({ ok: true, route: String(url), method: init?.method }), {
+                status: 200,
+            });
+        }),
+    });
+    const tools = server._registeredTools;
+    const cases = [
+        { name: "list_decisions", payload: { limit: 5, cursor: "c1" }, method: "GET", path: "/api/decisions?limit=5&cursor=c1" },
+        { name: "get_decision", payload: { id: "d1" }, method: "GET", path: "/api/decisions/d1" },
+        { name: "create_decision", payload: { content: "Adopt Bun" }, method: "POST", path: "/api/decisions" },
+        { name: "update_decision", payload: { id: "d1", headline: "Adopt Bun v2" }, method: "PATCH", path: "/api/decisions/d1" },
+        { name: "delete_decision", payload: { id: "d1", confirmText: "Adopt Bun v2" }, method: "DELETE", path: "/api/decisions/d1" },
+        { name: "list_outcomes", payload: { limit: 10 }, method: "GET", path: "/api/outcomes?limit=10" },
+        { name: "get_outcome", payload: { id: "o1" }, method: "GET", path: "/api/outcomes/o1" },
+        { name: "list_outcome_signals", payload: { id: "o1" }, method: "GET", path: "/api/outcomes/o1/signals" },
+        { name: "create_outcome", payload: { name: "Reduce churn" }, method: "POST", path: "/api/outcomes" },
+        { name: "update_outcome", payload: { id: "o1", summary: "New summary" }, method: "PATCH", path: "/api/outcomes/o1" },
+        { name: "delete_outcome", payload: { id: "o1", confirmText: "Reduce churn" }, method: "DELETE", path: "/api/outcomes/o1" },
+        { name: "get_north_star", payload: {}, method: "GET", path: "/api/north-star" },
+        { name: "update_north_star", payload: { metric: "Active users", current: "10", target: "100", reason: "API smoke" }, method: "POST", path: "/api/north-star" },
+        { name: "list_signals", payload: { limit: 25, cursor: "2026-01-01T00:00:00.000Z" }, method: "GET", path: "/api/signals?limit=25&cursor=2026-01-01T00%3A00%3A00.000Z" },
+        { name: "get_signal", payload: { id: "s1" }, method: "GET", path: "/api/signals/s1" },
+    ];
+    for (const entry of cases) {
+        assert.ok(tools[entry.name], `${entry.name} should be registered`);
+        await tools[entry.name].handler(entry.payload);
+    }
+    assert.equal(calls.length, cases.length);
+    cases.forEach((entry, index) => {
+        const call = calls[index];
+        assert.equal(call.method, entry.method);
+        assert.equal(call.url, `https://askthew.example.com${entry.path}`);
+        assert.deepEqual(call.headers, {
+            ...(entry.method === "GET" ? {} : { "Content-Type": "application/json" }),
+            Authorization: "Bearer atw_mcp_tools",
+        });
+        if (entry.method !== "GET") {
+            assert.equal(call.body.installToken, "atw_mcp_tools");
+            assert.equal(call.body.clientId, "codex");
+        }
+    });
+});
+test("v1 API MCP tools return server errors as JSON text", async () => {
+    const server = createAskTheWMcpServer({
+        apiBaseUrl: "https://askthew.example.com",
+        sendStartupHeartbeat: false,
+        credentials: {
+            installToken: "atw_mcp_tools",
+            clientId: "codex",
+        },
+        fetchImpl: (async () => new Response(JSON.stringify({ error: "Nope", code: "nope" }), {
+            status: 500,
+        })),
+    });
+    const result = await server._registeredTools.get_signal.handler({ id: "s1" });
+    const parsed = JSON.parse(result.content[0].text);
+    assert.equal(parsed.ok, false);
+    assert.equal(parsed.status, 500);
+    assert.equal(parsed.code, "nope");
+});
+test("createAskTheWMcpServer sends startup heartbeat and automated setup signal", async () => {
+    const calls = [];
+    createAskTheWMcpServer({
+        apiBaseUrl: "https://askthew.example.com",
+        credentials: {
+            installToken: "atw_mcp_startup",
+            clientId: "codex",
+            clientLabel: "Codex",
+            serverName: "askthew",
+            hostType: "codex",
+        },
+        runtimeMetadata: {
+            test_scope: "startup",
+        },
+        fetchImpl: (async (url, init) => {
+            calls.push({
+                url: String(url),
+                body: JSON.parse(String(init?.body ?? "{}")),
+            });
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        }),
+    });
+    for (let attempt = 0; attempt < 20 && calls.length < 2; attempt += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    assert.equal(calls.length, 2);
+    assert.equal(calls[0]?.url, "https://askthew.example.com/api/connectors/mcp/heartbeat");
+    assert.equal(calls[0]?.body.installToken, "atw_mcp_startup");
+    assert.equal(calls[0]?.body.clientId, "codex");
+    assert.equal(calls[1]?.url, "https://askthew.example.com/api/ingest/mcp");
+    assert.equal(calls[1]?.body.installToken, "atw_mcp_startup");
+    assert.equal(calls[1]?.body.clientId, "codex");
+    const signal = calls[1]?.body.sessionSignal;
+    assert.equal(signal.kind, "setup_complete");
+    assert.equal(signal.sequence, 0);
+    assert.match(signal.sessionId, /^mcp-startup:codex:/);
+    assert.equal(signal.metadata.automated, true);
+    assert.equal(signal.metadata.operational, true);
+    assert.equal(signal.metadata.origin, "mcp_server_startup");
+    assert.equal(signal.metadata.test_scope, "startup");
+});
+test("createAskTheWMcpServer accepts hosted connector identity overrides", async () => {
+    const calls = [];
+    const server = createAskTheWMcpServer({
+        apiBaseUrl: "https://askthew.example.com",
+        sendStartupHeartbeat: false,
+        credentials: {
+            installToken: "atw_mcp_remote",
+            clientId: "claude_remote",
+            clientLabel: "Claude Desktop / Cowork",
+            serverName: "askthew_workspace_a",
+        },
+        runtimeMetadata: {
+            connector_mode: "remote_mcp",
+        },
+        fetchImpl: (async (url, init) => {
+            calls.push({
+                url: String(url),
+                body: JSON.parse(String(init?.body ?? "{}")),
+            });
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        }),
+    });
+    const tool = server._registeredTools.capture_session_signal;
+    assert.ok(tool);
+    await tool.handler({
+        sessionId: "session-remote",
+        sequence: 1,
+        kind: "setup_complete",
+        summary: "Remote connector setup complete.",
+        evidence: [],
+        filesTouched: [],
+        commandsRun: [],
+        metadata: {},
+    });
+    assert.equal(calls[0]?.url, "https://askthew.example.com/api/ingest/mcp");
+    assert.equal(calls[0]?.body.installToken, "atw_mcp_remote");
+    assert.equal(calls[0]?.body.clientId, "claude_remote");
+    assert.equal(calls[0]?.body.clientLabel, "Claude Desktop / Cowork");
+    assert.equal(calls[0]?.body.sessionSignal.metadata.connector_mode, "remote_mcp");
+});

package/dist/install.d.ts

@@ -1,11 +1,12 @@
 export type SupportedHostType = "claude_code" | "codex" | "cursor";
 interface HostConfigInput {
     hostType: SupportedHostType;
-    token: string;
+    token?: string;
     apiUrl: string;
     serverName: string;
     clientId?: string;
     clientLabel?: string;
+    free?: boolean;
 }
 interface InstallHostConfigInput extends HostConfigInput {
     dryRun?: boolean;
@@ -20,6 +21,13 @@ export declare function createServerEntry(input: HostConfigInput): {
     command: string;
     args: string[];
     env: {
+        ASKTHEW_HOST_TYPE: SupportedHostType;
+        ASKTHEW_SERVER_NAME: string;
+        ASKTHEW_CLIENT_LABEL?: string | undefined;
+        ASKTHEW_CLIENT_ID?: string | undefined;
+        ASKTHEW_FREE_MODE: string;
+        ASKTHEW_API_URL: string;
+    } | {
         ASKTHEW_HOST_TYPE: SupportedHostType;
         ASKTHEW_SERVER_NAME: string;
         ASKTHEW_CLIENT_LABEL?: string | undefined;
@@ -40,6 +48,13 @@ export declare function createHostConfigSnippet(input: HostConfigInput): {
                 command: string;
                 args: string[];
                 env: {
+                    ASKTHEW_HOST_TYPE: SupportedHostType;
+                    ASKTHEW_SERVER_NAME: string;
+                    ASKTHEW_CLIENT_LABEL?: string | undefined;
+                    ASKTHEW_CLIENT_ID?: string | undefined;
+                    ASKTHEW_FREE_MODE: string;
+                    ASKTHEW_API_URL: string;
+                } | {
                     ASKTHEW_HOST_TYPE: SupportedHostType;
                     ASKTHEW_SERVER_NAME: string;
                     ASKTHEW_CLIENT_LABEL?: string | undefined;

package/dist/install.js

@@ -22,8 +22,8 @@ export function createServerEntry(input) {
         command: "npx",
         args: ["-y", "--prefer-online", "@askthew/mcp-plugin@latest"],
         env: {
-            ASKTHEW_INSTALL_TOKEN: input.token,
             ASKTHEW_API_URL: input.apiUrl,
+            ...(input.free ? { ASKTHEW_FREE_MODE: "1" } : { ASKTHEW_INSTALL_TOKEN: input.token ?? "" }),
             ...(input.clientId ? { ASKTHEW_CLIENT_ID: input.clientId } : {}),
             ...(input.clientLabel ? { ASKTHEW_CLIENT_LABEL: input.clientLabel } : {}),
             ASKTHEW_HOST_TYPE: input.hostType,
@@ -124,7 +124,7 @@ export function mergeHostSettings(input) {
     };
 }
 export function formatInstallCommand(input) {
-    return [
+    const parts = [
         "npx",
         "-y",
         "--prefer-online",
@@ -132,17 +132,22 @@ export function formatInstallCommand(input) {
         "install",
         "--host",
         input.hostType,
-        "--token",
-        JSON.stringify(input.token),
         "--api-url",
         JSON.stringify(input.apiUrl),
         "--server-name",
         JSON.stringify(input.serverName),
-    ].join(" ");
+    ];
+    if (input.free) {
+        parts.push("--free");
+    }
+    else {
+        parts.splice(7, 0, "--token", JSON.stringify(input.token ?? ""));
+    }
+    return parts.join(" ");
 }
 export function verificationNextStep(hostType) {
     const hostLabel = hostType === "claude_code" ? "Claude Code" : hostType === "cursor" ? "Cursor" : "Codex";
-    return `Refresh Ask The W to confirm the plugin shows Installed. Restart or reload ${hostLabel} if it is already open. On the next Ask The W setup check, choose Always allow if ${hostLabel} asks for tool permission. The installed project instructions tell the coding agent when to send updates automatically. list_mcp_resources/list_mcp_resource_templates may be empty for this tool-driven connector and are not failure signals.`;
+    return `Refresh Ask The W to confirm the plugin shows Installed. Restart or reload ${hostLabel} if it is already open. At the start of every new ${hostLabel} session in this repo, the installed project instructions tell the coding agent to send a setup_complete update before plan mode or exploration. Choose Always allow if ${hostLabel} asks for Ask The W tool permission. list_mcp_resources/list_mcp_resource_templates may be empty for this tool-driven connector and are not failure signals.`;
 }
 export function installHostConfig(input) {
     const settingsPath = resolveSettingsPath({
@@ -229,6 +234,11 @@ function behaviorInstructions(hostType) {
         "",
         `This workspace uses the Ask The W Plugin. When working in this repo with ${hostLabel}, send compact Ask The W updates automatically with the MCP tool \`capture_session_signal\`.`,
         "",
+        "Startup update:",
+        `- At the start of every new ${hostLabel} session in this repo, before plan mode, exploration, or any normal reply, call \`capture_session_signal\` with \`kind: "setup_complete"\` if the tool is available.`,
+        `- If the tool is unavailable, tell the user to restart or reload ${hostLabel}; do not use \`list_mcp_resources\` or \`list_mcp_resource_templates\` as pass/fail checks.`,
+        "- If you realize later in the conversation that the startup call was missed, send it immediately with `metadata.recovered_missed_startup=true`.",
+        "",
         "Send an update:",
         "- after the user accepts or rejects product, architecture, or implementation direction",
         "- after meaningful implementation changes",
@@ -238,8 +248,6 @@ function behaviorInstructions(hostType) {
         "",
         "Keep updates compact: short summary, minimal evidence excerpts, files touched, commands run, and useful metadata. Do not send full transcripts. Redact obvious secrets before sending.",
         "",
-        "If this is the first session after install or reload, immediately send a `setup_complete` update with `capture_session_signal` before continuing. If the host asks for Ask The W tool permission, the user should choose Always allow if available.",
-        "",
         ASKTHEW_INSTRUCTIONS_END,
         "",
     ].join("\n");

package/dist/install.test.d.ts

@@ -0,0 +1 @@
+export {};