qingflow-mcp 0.3.13 → 0.3.14

package/dist/server.js

@@ -46,6 +46,8 @@ class InputValidationError extends Error {
 }
 const FORM_CACHE_TTL_MS = Number(process.env.QINGFLOW_FORM_CACHE_TTL_MS ?? "300000");
 const formCache = new Map();
+const CONTINUATION_CACHE_TTL_MS = Number(process.env.QINGFLOW_CONTINUATION_CACHE_TTL_MS ?? "900000");
+const continuationCache = new Map();
 const DEFAULT_PAGE_SIZE = 50;
 const DEFAULT_SCAN_MAX_PAGES = 10;
 const DEFAULT_ROW_LIMIT = 200;
@@ -61,7 +63,7 @@ const ADAPTIVE_TARGET_PAGE_MS = toPositiveInt(process.env.QINGFLOW_ADAPTIVE_TARG
 const MAX_LIST_ITEMS_BYTES = toPositiveInt(process.env.QINGFLOW_LIST_MAX_ITEMS_BYTES) ?? 400000;
 const REQUEST_TIMEOUT_MS = toPositiveInt(process.env.QINGFLOW_REQUEST_TIMEOUT_MS) ?? 18000;
 const EXECUTION_BUDGET_MS = toPositiveInt(process.env.QINGFLOW_EXECUTION_BUDGET_MS) ?? 20000;
-const SERVER_VERSION = "0.3.13";
+const SERVER_VERSION = "0.3.14";
 const accessToken = process.env.QINGFLOW_ACCESS_TOKEN;
 const baseUrl = process.env.QINGFLOW_BASE_URL;
 if (!accessToken) {
@@ -227,6 +229,78 @@ const formSuccessOutputSchema = z.object({
     meta: apiMetaSchema
 });
 const formOutputSchema = formSuccessOutputSchema;
+const stringLikeSchema = z.string().min(1);
+const columnSelectorLikeSchema = z.union([stringLikeSchema, z.number().int()]);
+const columnReferenceLikeSchema = z.union([
+    columnSelectorLikeSchema,
+    z
+        .object({
+        que_id: columnSelectorLikeSchema.optional(),
+        queId: columnSelectorLikeSchema.optional()
+    })
+        .passthrough()
+]);
+const booleanLikeSchema = z.union([z.boolean(), stringLikeSchema]);
+function positiveIntLikeSchema(max) {
+    const base = z.number().int().positive();
+    return z.union([max !== undefined ? base.max(max) : base, stringLikeSchema]);
+}
+function nonNegativeIntLikeSchema(max) {
+    const base = z.number().int().nonnegative();
+    return z.union([max !== undefined ? base.max(max) : base, stringLikeSchema]);
+}
+const publicSortItemSchema = z
+    .object({
+    que_id: columnSelectorLikeSchema,
+    ascend: booleanLikeSchema.optional()
+})
+    .passthrough();
+const publicFilterItemSchema = z
+    .object({
+    que_id: columnSelectorLikeSchema.optional(),
+    search_key: stringLikeSchema.optional(),
+    search_keys: z.union([z.array(stringLikeSchema), stringLikeSchema]).optional(),
+    min_value: stringLikeSchema.optional(),
+    max_value: stringLikeSchema.optional(),
+    scope: z.union([z.number().int(), stringLikeSchema]).optional(),
+    search_options: z.union([z.array(columnSelectorLikeSchema), stringLikeSchema]).optional(),
+    search_user_ids: z.union([z.array(stringLikeSchema), stringLikeSchema]).optional()
+})
+    .passthrough();
+const publicTimeRangeSchema = z
+    .object({
+    column: columnSelectorLikeSchema,
+    from: stringLikeSchema.optional(),
+    to: stringLikeSchema.optional(),
+    timezone: stringLikeSchema.optional()
+})
+    .passthrough();
+const publicStatPolicySchema = z
+    .object({
+    include_negative: booleanLikeSchema.optional(),
+    include_null: booleanLikeSchema.optional()
+})
+    .passthrough();
+const publicAnswerInputSchema = z
+    .object({
+    que_id: columnSelectorLikeSchema.optional(),
+    queId: columnSelectorLikeSchema.optional(),
+    que_title: stringLikeSchema.optional(),
+    queTitle: stringLikeSchema.optional(),
+    que_type: z.unknown().optional(),
+    queType: z.unknown().optional(),
+    value: z.unknown().optional(),
+    values: z.union([z.array(z.unknown()), stringLikeSchema]).optional(),
+    table_values: z.union([z.array(z.array(z.unknown())), stringLikeSchema]).optional(),
+    tableValues: z.union([z.array(z.array(z.unknown())), stringLikeSchema]).optional()
+})
+    .passthrough();
+const toolSpecInputPublicSchema = z
+    .object({
+    tool_name: stringLikeSchema.optional(),
+    include_all: booleanLikeSchema.optional()
+})
+    .passthrough();
 const toolSpecInputSchema = z.preprocess(normalizeToolSpecInput, z.object({
     tool_name: z.string().min(1).optional(),
     include_all: z.boolean().optional()
@@ -250,6 +324,52 @@ const toolSpecOutputSchema = z.object({
         generated_at: z.string()
     })
 });
+const listInputPublicSchema = z
+    .object({
+    app_key: stringLikeSchema.optional(),
+    user_id: stringLikeSchema.optional(),
+    page_num: positiveIntLikeSchema().optional(),
+    page_token: stringLikeSchema.optional(),
+    page_size: positiveIntLikeSchema(200).optional(),
+    requested_pages: positiveIntLikeSchema(500).optional(),
+    scan_max_pages: positiveIntLikeSchema(500).optional(),
+    mode: z
+        .enum([
+        "todo",
+        "done",
+        "mine_approved",
+        "mine_rejected",
+        "mine_draft",
+        "mine_need_improve",
+        "mine_processing",
+        "all",
+        "all_approved",
+        "all_rejected",
+        "all_processing",
+        "cc"
+    ])
+        .optional(),
+    type: z.union([z.number().int().min(1).max(12), stringLikeSchema]).optional(),
+    keyword: z.string().optional(),
+    query_logic: z.union([z.enum(["and", "or"]), stringLikeSchema]).optional(),
+    apply_ids: z.union([z.array(z.union([z.string(), z.number()])), stringLikeSchema]).optional(),
+    sort: z.union([z.array(publicSortItemSchema), stringLikeSchema]).optional(),
+    filters: z.union([z.array(publicFilterItemSchema), stringLikeSchema]).optional(),
+    time_range: z.union([publicTimeRangeSchema, stringLikeSchema]).optional(),
+    max_rows: positiveIntLikeSchema(200).optional(),
+    max_items: positiveIntLikeSchema(200).optional(),
+    max_columns: positiveIntLikeSchema(MAX_COLUMN_LIMIT).optional(),
+    select_columns: z
+        .union([
+        z.array(columnReferenceLikeSchema).min(1).max(MAX_COLUMN_LIMIT),
+        stringLikeSchema
+    ])
+        .optional(),
+    include_answers: booleanLikeSchema.optional(),
+    strict_full: booleanLikeSchema.optional(),
+    output_profile: z.union([outputProfileSchema, stringLikeSchema]).optional()
+})
+    .passthrough();
 const listInputSchema = z
     .preprocess(normalizeListInput, z.object({
     app_key: z.string().min(1).optional(),
@@ -350,6 +470,19 @@ const listSuccessOutputSchema = z.object({
     meta: apiMetaSchema.optional()
 });
 const listOutputSchema = listSuccessOutputSchema;
+const recordGetInputPublicSchema = z
+    .object({
+    apply_id: columnSelectorLikeSchema.optional(),
+    max_columns: positiveIntLikeSchema(MAX_COLUMN_LIMIT).optional(),
+    select_columns: z
+        .union([
+        z.array(columnReferenceLikeSchema).min(1).max(MAX_COLUMN_LIMIT),
+        stringLikeSchema
+    ])
+        .optional(),
+    output_profile: z.union([outputProfileSchema, stringLikeSchema]).optional()
+})
+    .passthrough();
 const recordGetInputSchema = z.preprocess(normalizeRecordGetInput, z.object({
     apply_id: z.union([z.string().min(1), z.number().int()]),
     max_columns: z.number().int().positive().max(MAX_COLUMN_LIMIT).optional(),
@@ -382,6 +515,16 @@ const recordGetSuccessOutputSchema = z.object({
     meta: apiMetaSchema.optional()
 });
 const recordGetOutputSchema = recordGetSuccessOutputSchema;
+const createInputPublicSchema = z
+    .object({
+    app_key: stringLikeSchema.optional(),
+    user_id: stringLikeSchema.optional(),
+    force_refresh_form: booleanLikeSchema.optional(),
+    apply_user: z.union([z.record(z.unknown()), stringLikeSchema]).optional(),
+    answers: z.union([z.array(publicAnswerInputSchema), stringLikeSchema]).optional(),
+    fields: z.union([z.record(z.unknown()), stringLikeSchema]).optional()
+})
+    .passthrough();
 const createInputSchema = z
     .object({
     app_key: z.string().min(1),
@@ -411,6 +554,16 @@ const createSuccessOutputSchema = z.object({
     meta: apiMetaSchema
 });
 const createOutputSchema = createSuccessOutputSchema;
+const updateInputPublicSchema = z
+    .object({
+    apply_id: columnSelectorLikeSchema.optional(),
+    app_key: stringLikeSchema.optional(),
+    user_id: stringLikeSchema.optional(),
+    force_refresh_form: booleanLikeSchema.optional(),
+    answers: z.union([z.array(publicAnswerInputSchema), stringLikeSchema]).optional(),
+    fields: z.union([z.record(z.unknown()), stringLikeSchema]).optional()
+})
+    .passthrough();
 const updateInputSchema = z
     .object({
     apply_id: z.union([z.string().min(1), z.number().int()]),
@@ -441,6 +594,56 @@ const operationSuccessOutputSchema = z.object({
     meta: apiMetaSchema
 });
 const operationOutputSchema = operationSuccessOutputSchema;
+const queryInputPublicSchema = z
+    .object({
+    query_mode: z.union([z.enum(["auto", "list", "record", "summary"]), stringLikeSchema]).optional(),
+    app_key: stringLikeSchema.optional(),
+    apply_id: columnSelectorLikeSchema.optional(),
+    user_id: stringLikeSchema.optional(),
+    page_num: positiveIntLikeSchema().optional(),
+    page_token: stringLikeSchema.optional(),
+    page_size: positiveIntLikeSchema(200).optional(),
+    requested_pages: positiveIntLikeSchema(500).optional(),
+    mode: z
+        .enum([
+        "todo",
+        "done",
+        "mine_approved",
+        "mine_rejected",
+        "mine_draft",
+        "mine_need_improve",
+        "mine_processing",
+        "all",
+        "all_approved",
+        "all_rejected",
+        "all_processing",
+        "cc"
+    ])
+        .optional(),
+    type: z.union([z.number().int().min(1).max(12), stringLikeSchema]).optional(),
+    keyword: z.string().optional(),
+    query_logic: z.union([z.enum(["and", "or"]), stringLikeSchema]).optional(),
+    apply_ids: z.union([z.array(z.union([z.string(), z.number()])), stringLikeSchema]).optional(),
+    sort: z.union([z.array(publicSortItemSchema), stringLikeSchema]).optional(),
+    filters: z.union([z.array(publicFilterItemSchema), stringLikeSchema]).optional(),
+    max_rows: positiveIntLikeSchema(200).optional(),
+    max_items: positiveIntLikeSchema(200).optional(),
+    max_columns: positiveIntLikeSchema(MAX_COLUMN_LIMIT).optional(),
+    select_columns: z
+        .union([
+        z.array(columnReferenceLikeSchema).min(1).max(MAX_COLUMN_LIMIT),
+        stringLikeSchema
+    ])
+        .optional(),
+    include_answers: booleanLikeSchema.optional(),
+    amount_column: z.union([columnReferenceLikeSchema, stringLikeSchema]).optional(),
+    time_range: z.union([publicTimeRangeSchema, stringLikeSchema]).optional(),
+    stat_policy: z.union([publicStatPolicySchema, stringLikeSchema]).optional(),
+    scan_max_pages: positiveIntLikeSchema(500).optional(),
+    strict_full: booleanLikeSchema.optional(),
+    output_profile: z.union([outputProfileSchema, stringLikeSchema]).optional()
+})
+    .passthrough();
 const queryInputSchema = z
     .preprocess(normalizeQueryInput, z.object({
     query_mode: z.enum(["auto", "list", "record", "summary"]).optional(),
@@ -580,6 +783,58 @@ const querySuccessOutputSchema = z.object({
     meta: apiMetaSchema.optional()
 });
 const queryOutputSchema = querySuccessOutputSchema;
+const aggregateInputPublicSchema = z
+    .object({
+    app_key: stringLikeSchema.optional(),
+    user_id: stringLikeSchema.optional(),
+    page_num: positiveIntLikeSchema().optional(),
+    page_token: stringLikeSchema.optional(),
+    page_size: positiveIntLikeSchema(200).optional(),
+    requested_pages: positiveIntLikeSchema(500).optional(),
+    scan_max_pages: positiveIntLikeSchema(500).optional(),
+    mode: z
+        .enum([
+        "todo",
+        "done",
+        "mine_approved",
+        "mine_rejected",
+        "mine_draft",
+        "mine_need_improve",
+        "mine_processing",
+        "all",
+        "all_approved",
+        "all_rejected",
+        "all_processing",
+        "cc"
+    ])
+        .optional(),
+    type: z.union([z.number().int().min(1).max(12), stringLikeSchema]).optional(),
+    keyword: z.string().optional(),
+    query_logic: z.union([z.enum(["and", "or"]), stringLikeSchema]).optional(),
+    apply_ids: z.union([z.array(z.union([z.string(), z.number()])), stringLikeSchema]).optional(),
+    sort: z.union([z.array(publicSortItemSchema), stringLikeSchema]).optional(),
+    filters: z.union([z.array(publicFilterItemSchema), stringLikeSchema]).optional(),
+    time_range: z.union([publicTimeRangeSchema, stringLikeSchema]).optional(),
+    group_by: z
+        .union([z.array(columnReferenceLikeSchema).min(1).max(20), stringLikeSchema])
+        .optional(),
+    amount_column: z.union([columnReferenceLikeSchema, stringLikeSchema]).optional(),
+    amount_columns: z
+        .union([z.array(columnReferenceLikeSchema).min(1).max(5), stringLikeSchema])
+        .optional(),
+    metrics: z
+        .union([
+        z.array(z.enum(["count", "sum", "avg", "min", "max"])).min(1).max(5),
+        stringLikeSchema
+    ])
+        .optional(),
+    time_bucket: z.union([z.enum(["day", "week", "month"]), stringLikeSchema]).optional(),
+    stat_policy: z.union([publicStatPolicySchema, stringLikeSchema]).optional(),
+    max_groups: positiveIntLikeSchema(2000).optional(),
+    strict_full: booleanLikeSchema.optional(),
+    output_profile: z.union([outputProfileSchema, stringLikeSchema]).optional()
+})
+    .passthrough();
 const aggregateInputSchema = z
     .preprocess(normalizeAggregateInput, z.object({
     app_key: z.string().min(1),
@@ -695,6 +950,15 @@ const aggregateOutputSchema = z.object({
     ...queryContractFields,
     meta: apiMetaSchema.optional()
 });
+const fieldResolveInputPublicSchema = z
+    .object({
+    app_key: stringLikeSchema.optional(),
+    query: columnSelectorLikeSchema.optional(),
+    queries: z.union([z.array(columnSelectorLikeSchema).min(1).max(50), stringLikeSchema]).optional(),
+    top_k: positiveIntLikeSchema(10).optional(),
+    fuzzy: booleanLikeSchema.optional()
+})
+    .passthrough();
 const fieldResolveInputSchema = z.preprocess(normalizeFieldResolveInput, z.object({
     app_key: z.string().min(1),
     query: z.union([z.string().min(1), z.number().int()]).optional(),
@@ -722,6 +986,14 @@ const fieldResolveOutputSchema = z.object({
     }),
     meta: apiMetaSchema
 });
+const queryPlanInputPublicSchema = z
+    .object({
+    tool: stringLikeSchema.optional(),
+    arguments: z.union([z.record(z.unknown()), stringLikeSchema]).optional(),
+    resolve_fields: booleanLikeSchema.optional(),
+    probe: booleanLikeSchema.optional()
+})
+    .passthrough();
 const queryPlanInputSchema = z.preprocess(normalizeQueryPlanInput, z.object({
     tool: z.string().min(1),
     arguments: z.record(z.unknown()).optional(),
@@ -761,13 +1033,31 @@ const queryPlanOutputSchema = z.object({
                 page_amount: z.number().int().nonnegative().nullable()
             })
                 .nullable()
-        })
+        }),
+        ready_for_final_conclusion: z.boolean(),
+        final_conclusion_blockers: z.array(z.string()),
+        recommended_next_actions: z.array(z.string())
     }),
     meta: z.object({
         version: z.string(),
         generated_at: z.string()
     })
 });
+const batchGetInputPublicSchema = z
+    .object({
+    app_key: stringLikeSchema.optional(),
+    user_id: stringLikeSchema.optional(),
+    apply_ids: z.union([z.array(columnSelectorLikeSchema).min(1).max(200), stringLikeSchema]).optional(),
+    select_columns: z
+        .union([
+        z.array(columnReferenceLikeSchema).min(1).max(MAX_COLUMN_LIMIT),
+        stringLikeSchema
+    ])
+        .optional(),
+    max_columns: positiveIntLikeSchema(MAX_COLUMN_LIMIT).optional(),
+    output_profile: z.union([outputProfileSchema, stringLikeSchema]).optional()
+})
+    .passthrough();
 const batchGetInputSchema = z.preprocess(normalizeBatchGetInput, z.object({
     app_key: z.string().min(1),
     user_id: z.string().min(1).optional(),
@@ -799,6 +1089,52 @@ const batchGetOutputSchema = z.object({
     ...queryContractFields,
     meta: apiMetaSchema.optional()
 });
+const exportInputPublicSchema = z
+    .object({
+    app_key: stringLikeSchema.optional(),
+    user_id: stringLikeSchema.optional(),
+    page_num: positiveIntLikeSchema().optional(),
+    page_token: stringLikeSchema.optional(),
+    page_size: positiveIntLikeSchema(200).optional(),
+    requested_pages: positiveIntLikeSchema(500).optional(),
+    scan_max_pages: positiveIntLikeSchema(500).optional(),
+    mode: z
+        .enum([
+        "todo",
+        "done",
+        "mine_approved",
+        "mine_rejected",
+        "mine_draft",
+        "mine_need_improve",
+        "mine_processing",
+        "all",
+        "all_approved",
+        "all_rejected",
+        "all_processing",
+        "cc"
+    ])
+        .optional(),
+    type: z.union([z.number().int().min(1).max(12), stringLikeSchema]).optional(),
+    keyword: z.string().optional(),
+    query_logic: z.union([z.enum(["and", "or"]), stringLikeSchema]).optional(),
+    apply_ids: z.union([z.array(z.union([z.string(), z.number()])), stringLikeSchema]).optional(),
+    sort: z.union([z.array(publicSortItemSchema), stringLikeSchema]).optional(),
+    filters: z.union([z.array(publicFilterItemSchema), stringLikeSchema]).optional(),
+    time_range: z.union([publicTimeRangeSchema, stringLikeSchema]).optional(),
+    max_rows: positiveIntLikeSchema(EXPORT_MAX_ROWS).optional(),
+    max_columns: positiveIntLikeSchema(MAX_COLUMN_LIMIT).optional(),
+    select_columns: z
+        .union([
+        z.array(columnReferenceLikeSchema).min(1).max(MAX_COLUMN_LIMIT),
+        stringLikeSchema
+    ])
+        .optional(),
+    strict_full: booleanLikeSchema.optional(),
+    output_profile: z.union([outputProfileSchema, stringLikeSchema]).optional(),
+    export_dir: stringLikeSchema.optional(),
+    file_name: stringLikeSchema.optional()
+})
+    .passthrough();
 const exportInputSchema = z.preprocess(normalizeExportInput, z.object({
     app_key: z.string().min(1).optional(),
     user_id: z.string().min(1).optional(),
@@ -895,7 +1231,7 @@ const exportOutputSchema = z.object({
 server.registerTool("qf_tool_spec_get", {
     title: "Qingflow Tool Spec Get",
     description: "Return MCP tool parameter requirements, limits, aliases and minimal examples for agent prompt grounding.",
-    inputSchema: toolSpecInputSchema,
+    inputSchema: toolSpecInputPublicSchema,
     outputSchema: toolSpecOutputSchema,
     annotations: {
         readOnlyHint: true,
@@ -903,9 +1239,10 @@ server.registerTool("qf_tool_spec_get", {
     }
 }, async (args) => {
     try {
+        const parsedArgs = toolSpecInputSchema.parse(args);
         const allSpecs = buildToolSpecCatalog();
-        const requested = args.tool_name?.trim() ?? null;
-        const includeAll = args.include_all ?? false;
+        const requested = parsedArgs.tool_name?.trim() ?? null;
+        const includeAll = parsedArgs.include_all ?? false;
         const normalizedRequested = requested?.toLowerCase() ?? null;
         let tools = allSpecs;
         if (normalizedRequested && !includeAll) {
@@ -1018,7 +1355,7 @@ server.registerTool("qf_form_get", {
 server.registerTool("qf_field_resolve", {
     title: "Qingflow Field Resolve",
     description: "Resolve natural language field names/aliases into stable que_id mappings for one app.",
-    inputSchema: fieldResolveInputSchema,
+    inputSchema: fieldResolveInputPublicSchema,
     outputSchema: fieldResolveOutputSchema,
     annotations: {
         readOnlyHint: true,
@@ -1026,8 +1363,9 @@ server.registerTool("qf_field_resolve", {
     }
 }, async (args) => {
     try {
-        const payload = await executeFieldResolve(args);
-        return okResult(payload, `Resolved fields for ${args.app_key}`);
+        const parsedArgs = fieldResolveInputSchema.parse(args);
+        const payload = await executeFieldResolve(parsedArgs);
+        return okResult(payload, `Resolved fields for ${parsedArgs.app_key}`);
     }
     catch (error) {
         return errorResult(error);
@@ -1036,7 +1374,7 @@ server.registerTool("qf_field_resolve", {
 server.registerTool("qf_query_plan", {
     title: "Qingflow Query Plan",
     description: "Preflight query arguments: normalize inputs, validate required fields, resolve mappings and estimate scan limits before execution.",
-    inputSchema: queryPlanInputSchema,
+    inputSchema: queryPlanInputPublicSchema,
     outputSchema: queryPlanOutputSchema,
     annotations: {
         readOnlyHint: true,
@@ -1044,8 +1382,9 @@ server.registerTool("qf_query_plan", {
     }
 }, async (args) => {
     try {
-        const payload = await executeQueryPlan(args);
-        return okResult(payload, `Planned ${args.tool}`);
+        const parsedArgs = queryPlanInputSchema.parse(args);
+        const payload = await executeQueryPlan(parsedArgs);
+        return okResult(payload, `Planned ${parsedArgs.tool}`);
     }
     catch (error) {
         return errorResult(error);
@@ -1054,7 +1393,7 @@ server.registerTool("qf_query_plan", {
 server.registerTool("qf_records_list", {
     title: "Qingflow Records List",
     description: "List records with pagination, filters and sorting.",
-    inputSchema: listInputSchema,
+    inputSchema: listInputPublicSchema,
     outputSchema: listOutputSchema,
     annotations: {
         readOnlyHint: true,
@@ -1062,7 +1401,8 @@ server.registerTool("qf_records_list", {
     }
 }, async (args) => {
     try {
-        const executed = await executeRecordsList(args);
+        const parsedArgs = listInputSchema.parse(args);
+        const executed = await executeRecordsList(parsedArgs);
         return okResult(executed.payload, executed.message);
     }
     catch (error) {
@@ -1072,7 +1412,7 @@ server.registerTool("qf_records_list", {
 server.registerTool("qf_record_get", {
     title: "Qingflow Record Get",
     description: "Get one record by applyId.",
-    inputSchema: recordGetInputSchema,
+    inputSchema: recordGetInputPublicSchema,
     outputSchema: recordGetOutputSchema,
     annotations: {
         readOnlyHint: true,
@@ -1080,7 +1420,8 @@ server.registerTool("qf_record_get", {
     }
 }, async (args) => {
     try {
-        const executed = await executeRecordGet(args);
+        const parsedArgs = recordGetInputSchema.parse(args);
+        const executed = await executeRecordGet(parsedArgs);
         return okResult(executed.payload, executed.message);
     }
     catch (error) {
@@ -1090,7 +1431,7 @@ server.registerTool("qf_record_get", {
 server.registerTool("qf_records_batch_get", {
     title: "Qingflow Records Batch Get",
     description: "Fetch multiple records by apply_ids in one call and return strict flat rows.",
-    inputSchema: batchGetInputSchema,
+    inputSchema: batchGetInputPublicSchema,
     outputSchema: batchGetOutputSchema,
     annotations: {
         readOnlyHint: true,
@@ -1098,7 +1439,8 @@ server.registerTool("qf_records_batch_get", {
     }
 }, async (args) => {
     try {
-        const payload = await executeRecordsBatchGet(args);
+        const parsedArgs = batchGetInputSchema.parse(args);
+        const payload = await executeRecordsBatchGet(parsedArgs);
         return okResult(payload.payload, payload.message);
     }
     catch (error) {
@@ -1108,7 +1450,7 @@ server.registerTool("qf_records_batch_get", {
 server.registerTool("qf_export_csv", {
     title: "Qingflow Export CSV",
     description: "Export list query result to a CSV file and return file path + summary instead of large inline payloads.",
-    inputSchema: exportInputSchema,
+    inputSchema: exportInputPublicSchema,
     outputSchema: exportOutputSchema,
     annotations: {
         readOnlyHint: true,
@@ -1116,7 +1458,8 @@ server.registerTool("qf_export_csv", {
     }
 }, async (args) => {
     try {
-        const executed = await executeRecordsExport("csv", args);
+        const parsedArgs = exportInputSchema.parse(args);
+        const executed = await executeRecordsExport("csv", parsedArgs);
         return okResult(executed.payload, executed.message);
     }
     catch (error) {
@@ -1126,7 +1469,7 @@ server.registerTool("qf_export_csv", {
 server.registerTool("qf_export_json", {
     title: "Qingflow Export JSON",
     description: "Export list query result to a JSON file and return file path + summary instead of large inline payloads.",
-    inputSchema: exportInputSchema,
+    inputSchema: exportInputPublicSchema,
     outputSchema: exportOutputSchema,
     annotations: {
         readOnlyHint: true,
@@ -1134,7 +1477,8 @@ server.registerTool("qf_export_json", {
     }
 }, async (args) => {
     try {
-        const executed = await executeRecordsExport("json", args);
+        const parsedArgs = exportInputSchema.parse(args);
+        const executed = await executeRecordsExport("json", parsedArgs);
         return okResult(executed.payload, executed.message);
     }
     catch (error) {
@@ -1144,7 +1488,7 @@ server.registerTool("qf_export_json", {
 server.registerTool("qf_query", {
     title: "Qingflow Unified Query",
     description: "Unified read entry for list/record/summary. Use query_mode=auto to route automatically.",
-    inputSchema: queryInputSchema,
+    inputSchema: queryInputPublicSchema,
     outputSchema: queryOutputSchema,
     annotations: {
         readOnlyHint: true,
@@ -1152,9 +1496,10 @@ server.registerTool("qf_query", {
     }
 }, async (args) => {
     try {
-        const routedMode = resolveQueryMode(args);
+        const parsedArgs = queryInputSchema.parse(args);
+        const routedMode = resolveQueryMode(parsedArgs);
         if (routedMode === "record") {
-            const recordArgs = buildRecordGetArgsFromQuery(args);
+            const recordArgs = buildRecordGetArgsFromQuery(parsedArgs);
             const executed = await executeRecordGet(recordArgs);
             const completeness = executed.completeness;
             const evidence = executed.evidence;
@@ -1183,7 +1528,7 @@ server.registerTool("qf_query", {
             }, executed.message);
         }
         if (routedMode === "summary") {
-            const executed = await executeRecordsSummary(args);
+            const executed = await executeRecordsSummary(parsedArgs);
             const completeness = executed.completeness;
             const evidence = executed.evidence;
             return okResult({
@@ -1210,7 +1555,7 @@ server.registerTool("qf_query", {
                     : {})
             }, executed.message);
         }
-        const listArgs = buildListArgsFromQuery(args);
+        const listArgs = buildListArgsFromQuery(parsedArgs);
         const executed = await executeRecordsList(listArgs);
         const completeness = executed.completeness;
         const evidence = executed.evidence;
@@ -1245,7 +1590,7 @@ server.registerTool("qf_query", {
 server.registerTool("qf_record_create", {
     title: "Qingflow Record Create",
     description: "Create one record. Supports explicit answers and ergonomic fields mapping (title or queId).",
-    inputSchema: createInputSchema,
+    inputSchema: createInputPublicSchema,
     outputSchema: createOutputSchema,
     annotations: {
         readOnlyHint: false,
@@ -1253,22 +1598,23 @@ server.registerTool("qf_record_create", {
     }
 }, async (args) => {
     try {
-        const form = needsFormResolution(args.fields) || Boolean(args.force_refresh_form)
-            ? await getFormCached(args.app_key, args.user_id, Boolean(args.force_refresh_form))
+        const parsedArgs = createInputSchema.parse(args);
+        const form = needsFormResolution(parsedArgs.fields) || Boolean(parsedArgs.force_refresh_form)
+            ? await getFormCached(parsedArgs.app_key, parsedArgs.user_id, Boolean(parsedArgs.force_refresh_form))
             : null;
         const normalizedAnswers = resolveAnswers({
-            explicitAnswers: args.answers,
-            fields: args.fields,
+            explicitAnswers: parsedArgs.answers,
+            fields: parsedArgs.fields,
             form: form?.result
         });
         const payload = {
             answers: normalizedAnswers
         };
-        if (args.apply_user) {
-            payload.applyUser = args.apply_user;
+        if (parsedArgs.apply_user) {
+            payload.applyUser = parsedArgs.apply_user;
         }
-        const response = await client.createRecord(args.app_key, payload, {
-            userId: args.user_id
+        const response = await client.createRecord(parsedArgs.app_key, payload, {
+            userId: parsedArgs.user_id
         });
         const result = asObject(response.result);
         return okResult({
@@ -1279,7 +1625,7 @@ server.registerTool("qf_record_create", {
                 async_hint: "Use qf_operation_get with request_id when apply_id is null."
             },
             meta: buildMeta(response)
-        }, `Create request sent for app ${args.app_key}`);
+        }, `Create request sent for app ${parsedArgs.app_key}`);
     }
     catch (error) {
         return errorResult(error);
@@ -1288,7 +1634,7 @@ server.registerTool("qf_record_create", {
 server.registerTool("qf_record_update", {
     title: "Qingflow Record Update",
     description: "Patch one record by applyId with explicit answers or ergonomic fields mapping.",
-    inputSchema: updateInputSchema,
+    inputSchema: updateInputPublicSchema,
     outputSchema: updateOutputSchema,
     annotations: {
         readOnlyHint: false,
@@ -1296,19 +1642,20 @@ server.registerTool("qf_record_update", {
     }
 }, async (args) => {
     try {
-        const requiresForm = needsFormResolution(args.fields);
-        if (requiresForm && !args.app_key) {
+        const parsedArgs = updateInputSchema.parse(args);
+        const requiresForm = needsFormResolution(parsedArgs.fields);
+        if (requiresForm && !parsedArgs.app_key) {
             throw new Error("app_key is required when fields uses title-based keys");
         }
-        const form = requiresForm && args.app_key
-            ? await getFormCached(args.app_key, args.user_id, Boolean(args.force_refresh_form))
+        const form = requiresForm && parsedArgs.app_key
+            ? await getFormCached(parsedArgs.app_key, parsedArgs.user_id, Boolean(parsedArgs.force_refresh_form))
             : null;
         const normalizedAnswers = resolveAnswers({
-            explicitAnswers: args.answers,
-            fields: args.fields,
+            explicitAnswers: parsedArgs.answers,
+            fields: parsedArgs.fields,
             form: form?.result
         });
-        const response = await client.updateRecord(String(args.apply_id), { answers: normalizedAnswers }, { userId: args.user_id });
+        const response = await client.updateRecord(String(parsedArgs.apply_id), { answers: normalizedAnswers }, { userId: parsedArgs.user_id });
         const result = asObject(response.result);
         return okResult({
             ok: true,
@@ -1317,7 +1664,7 @@ server.registerTool("qf_record_update", {
                 async_hint: "Use qf_operation_get with request_id to fetch update result when needed."
             },
             meta: buildMeta(response)
-        }, `Update request sent for apply ${String(args.apply_id)}`);
+        }, `Update request sent for apply ${String(parsedArgs.apply_id)}`);
     }
     catch (error) {
         return errorResult(error);
@@ -1351,7 +1698,7 @@ server.registerTool("qf_operation_get", {
 server.registerTool("qf_records_aggregate", {
     title: "Qingflow Records Aggregate",
     description: "Aggregate records by group_by columns with optional amount metrics. Designed for deterministic, auditable statistics.",
-    inputSchema: aggregateInputSchema,
+    inputSchema: aggregateInputPublicSchema,
     outputSchema: aggregateOutputSchema,
     annotations: {
         readOnlyHint: true,
@@ -1359,7 +1706,8 @@ server.registerTool("qf_records_aggregate", {
     }
 }, async (args) => {
     try {
-        const executed = await executeRecordsAggregate(args);
+        const parsedArgs = aggregateInputSchema.parse(args);
+        const executed = await executeRecordsAggregate(parsedArgs);
         return okResult(executed.payload, executed.message);
     }
     catch (error) {
@@ -1653,6 +2001,9 @@ const COMMON_INPUT_ALIASES = {
     pageNum: "page_num",
     pageSize: "page_size",
     pageToken: "page_token",
+    rawNextPageToken: "page_token",
+    raw_next_page_token: "page_token",
+    rawPageToken: "page_token",
     requestedPages: "requested_pages",
     scanMaxPages: "scan_max_pages",
     queryMode: "query_mode",
@@ -2801,12 +3152,104 @@ function decodeContinuationToken(token) {
     if (!appKey || !nextPageNum || !pageSize) {
         throw new Error("Invalid page_token payload");
     }
+    const resumeKind = obj?.resume_kind === "summary" || obj?.resume_kind === "aggregate"
+        ? obj.resume_kind
+        : undefined;
+    const resumeId = asNullableString(obj?.resume_id) ?? undefined;
     return {
         app_key: appKey,
         next_page_num: nextPageNum,
-        page_size: pageSize
+        page_size: pageSize,
+        ...(resumeKind ? { resume_kind: resumeKind } : {}),
+        ...(resumeId ? { resume_id: resumeId } : {})
     };
 }
+function resolveContinuationPayload(pageToken, appKey) {
+    if (!pageToken) {
+        return null;
+    }
+    const payload = decodeContinuationToken(pageToken);
+    if (payload.app_key !== appKey) {
+        throw new Error(`page_token app_key mismatch: token for ${payload.app_key}, request for ${appKey}`);
+    }
+    return payload;
+}
+function buildQueryFingerprint(value) {
+    return stableJson(value);
+}
+function loadContinuationState(kind, payload, queryFingerprint, tool) {
+    if (!payload) {
+        return null;
+    }
+    if (payload.resume_kind !== kind || !payload.resume_id) {
+        throw new InputValidationError({
+            message: `${tool} received a page_token that cannot resume aggregated state`,
+            errorCode: "INVALID_PAGE_TOKEN",
+            fixHint: `Reuse the raw_next_page_token returned by ${tool}, or restart the query without page_token.`,
+            details: {
+                tool,
+                expected_resume_kind: kind,
+                received_resume_kind: payload.resume_kind ?? null
+            }
+        });
+    }
+    const state = getContinuationState(kind, payload.resume_id);
+    if (!state) {
+        throw new InputValidationError({
+            message: `${tool} continuation state expired`,
+            errorCode: "CONTINUATION_EXPIRED",
+            fixHint: "Restart the query without page_token to rebuild the aggregate from page 1.",
+            details: {
+                tool,
+                resume_id: payload.resume_id
+            }
+        });
+    }
+    if (state.query_fingerprint !== queryFingerprint) {
+        throw new InputValidationError({
+            message: `${tool} page_token no longer matches the current query arguments`,
+            errorCode: "CONTINUATION_MISMATCH",
+            fixHint: "When continuing a summary/aggregate query, keep app_key, filters, time_range, grouping, selected columns and stat options unchanged.",
+            details: {
+                tool,
+                resume_id: payload.resume_id
+            }
+        });
+    }
+    return {
+        resumeId: payload.resume_id,
+        state
+    };
+}
+function setContinuationState(kind, state, resumeId) {
+    const id = resumeId ?? randomUUID();
+    continuationCache.set(id, {
+        kind,
+        state: state,
+        expiresAt: Date.now() + CONTINUATION_CACHE_TTL_MS
+    });
+    return id;
+}
+function getContinuationState(kind, resumeId) {
+    const hit = continuationCache.get(resumeId);
+    if (!hit) {
+        return null;
+    }
+    if (hit.expiresAt <= Date.now()) {
+        continuationCache.delete(resumeId);
+        return null;
+    }
+    if (hit.kind !== kind) {
+        throw new Error(`page_token continuation kind mismatch: expected ${kind}, got ${hit.kind}`);
+    }
+    return hit.state;
+}
+function deleteContinuationState(resumeId) {
+    if (!resumeId) {
+        return;
+    }
+    continuationCache.delete(resumeId);
+}
 function isExecutionBudgetExceeded(startedAt) {
     return Date.now() - startedAt >= EXECUTION_BUDGET_MS;
 }
@@ -3221,6 +3664,54 @@ async function estimatePlanExecution(params) {
         probe: probeResult
     };
 }
+function assessPlanReadiness(params) {
+    const blockers = [];
+    const actions = [];
+    if (!params.validation.valid) {
+        blockers.push("arguments are not valid");
+        actions.push("Fix missing_required and warnings before execution.");
+    }
+    const unresolved = params.fieldMapping.filter((item) => !item.resolved);
+    if (unresolved.length > 0) {
+        blockers.push(`unresolved fields: ${unresolved.map((item) => `${item.role}:${item.requested}`).join(", ")}`);
+        actions.push("Use qf_form_get or qf_field_resolve to resolve field ids before execution.");
+    }
+    const tool = params.tool;
+    const routedMode = tool === "qf_query"
+        ? resolveQueryMode(params.normalizedArguments)
+        : null;
+    const strictFull = params.normalizedArguments.strict_full === true;
+    const scanLimit = resolveScanLimit(params.estimate.requested_pages ?? 1, params.estimate.scan_max_pages ?? params.estimate.requested_pages ?? 1);
+    const pageSize = params.estimate.page_size ?? null;
+    const probeResultAmount = params.estimate.probe?.result_amount ?? null;
+    const requiredPagesFromProbe = probeResultAmount !== null && pageSize !== null
+        ? Math.max(1, Math.ceil(probeResultAmount / pageSize))
+        : null;
+    if (tool === "qf_records_list" || (tool === "qf_query" && routedMode === "list")) {
+        blockers.push("list mode is not a safe final-analysis endpoint");
+        actions.push("Use qf_query(summary) or qf_records_aggregate for final statistics.");
+    }
+    if (tool === "qf_records_batch_get" || tool === "qf_export_csv" || tool === "qf_export_json") {
+        blockers.push(`${tool} is a data retrieval/export endpoint, not a final-analysis endpoint`);
+        actions.push("Use qf_query(summary) or qf_records_aggregate for final statistics.");
+    }
+    if (tool === "qf_records_aggregate" || (tool === "qf_query" && routedMode === "summary")) {
+        if (!strictFull) {
+            blockers.push("strict_full must be true for final conclusions");
+            actions.push("Set strict_full=true so incomplete raw scans fail with NEED_MORE_DATA.");
+        }
+        if (requiredPagesFromProbe !== null && scanLimit < requiredPagesFromProbe) {
+            blockers.push(`scan budget is smaller than estimated page count (${scanLimit} < ${requiredPagesFromProbe})`);
+            actions.push("Increase requested_pages/scan_max_pages or continue with raw_next_page_token.");
+        }
+    }
+    actions.push("After execution, still verify completeness.raw_scan_complete=true before concluding.");
+    return {
+        ready_for_final_conclusion: blockers.length === 0,
+        final_conclusion_blockers: uniqueStringList(blockers),
+        recommended_next_actions: uniqueStringList(actions)
+    };
+}
 function scoreFieldMatches(requested, fields, fuzzy, topK) {
     const normalizedRequested = requested.trim().toLowerCase();
     const requestedIsId = isNumericKey(normalizedRequested);
@@ -3669,6 +4160,18 @@ async function executeQueryPlan(args) {
         probe: args.probe !== false,
         warnings: validation.warnings
     });
+    const readiness = assessPlanReadiness({
+        tool: normalizedTool,
+        normalizedArguments,
+        validation,
+        fieldMapping: fieldMapping.map((item) => ({
+            role: item.role,
+            requested: item.requested,
+            resolved: item.resolved,
+            reason: item.reason
+        })),
+        estimate
+    });
     return {
         ok: true,
         data: {
@@ -3676,7 +4179,10 @@ async function executeQueryPlan(args) {
             normalized_arguments: normalizedArguments,
             validation,
             field_mapping: fieldMapping,
-            estimate
+            estimate,
+            ready_for_final_conclusion: readiness.ready_for_final_conclusion,
+            final_conclusion_blockers: readiness.final_conclusion_blockers,
+            recommended_next_actions: readiness.recommended_next_actions
         },
         meta: {
             version: SERVER_VERSION,
@@ -4327,6 +4833,108 @@ async function executeRecordGet(args) {
         outputProfile
     };
 }
+function normalizeSortForFingerprint(sort) {
+    return (sort ?? []).map((item) => ({
+        que_id: String(item.que_id),
+        ascend: item.ascend !== false
+    }));
+}
+function cloneByDayBuckets(source) {
+    return source.map(([day, bucket]) => [day, { count: bucket.count, amount: bucket.amount }]);
+}
+function cloneMetricAccumulator(accumulator) {
+    return {
+        count: accumulator.count,
+        sum: accumulator.sum,
+        min: accumulator.min,
+        max: accumulator.max
+    };
+}
+function serializeMetricAccumulatorMap(map) {
+    return Array.from(map.entries()).map(([key, value]) => [key, cloneMetricAccumulator(value)]);
+}
+function restoreMetricAccumulatorMap(values) {
+    return new Map(values.map(([key, value]) => [
+        key,
+        {
+            count: value.count,
+            sum: value.sum,
+            min: value.min,
+            max: value.max
+        }
+    ]));
+}
+function serializeAggregateGroupStats(groupStats) {
+    return Array.from(groupStats.entries()).map(([key, bucket]) => ({
+        key,
+        group: bucket.group,
+        count: bucket.count,
+        amount: bucket.amount,
+        metrics: serializeMetricAccumulatorMap(bucket.metrics)
+    }));
+}
+function restoreAggregateGroupStats(values) {
+    return new Map(values.map((item) => [
+        item.key,
+        {
+            group: item.group,
+            count: item.count,
+            amount: item.amount,
+            metrics: restoreMetricAccumulatorMap(item.metrics)
+        }
+    ]));
+}
+function buildSummaryContinuationFingerprint(params) {
+    return buildQueryFingerprint({
+        kind: "summary",
+        app_key: params.app_key,
+        mode: params.mode ?? null,
+        type: params.type ?? null,
+        keyword: params.keyword ?? null,
+        query_logic: params.query_logic ?? null,
+        apply_ids: uniqueStringList((params.apply_ids ?? []).map((item) => String(item))),
+        sort: normalizeSortForFingerprint(params.sort),
+        filters: params.filters,
+        select_columns: params.select_columns.map((item) => String(item.que_id)),
+        amount_column: params.amount_column ? String(params.amount_column.que_id) : null,
+        time_range: params.time_column
+            ? {
+                column: String(params.time_column.que_id),
+                from: params.time_range?.from ?? null,
+                to: params.time_range?.to ?? null,
+                timezone: params.time_range?.timezone ?? null
+            }
+            : null,
+        stat_policy: params.stat_policy,
+        row_cap: params.row_cap
+    });
+}
+function buildAggregateContinuationFingerprint(params) {
+    return buildQueryFingerprint({
+        kind: "aggregate",
+        app_key: params.app_key,
+        mode: params.mode ?? null,
+        type: params.type ?? null,
+        keyword: params.keyword ?? null,
+        query_logic: params.query_logic ?? null,
+        apply_ids: uniqueStringList((params.apply_ids ?? []).map((item) => String(item))),
+        sort: normalizeSortForFingerprint(params.sort),
+        filters: params.filters,
+        group_by: params.group_by.map((item) => String(item.que_id)),
+        amount_columns: params.amount_columns.map((item) => String(item.que_id)),
+        metrics: params.metrics,
+        time_range: params.time_column
+            ? {
+                column: String(params.time_column.que_id),
+                from: params.time_range?.from ?? null,
+                to: params.time_range?.to ?? null,
+                timezone: params.time_range?.timezone ?? null
+            }
+            : null,
+        time_bucket: params.time_bucket,
+        stat_policy: params.stat_policy
+    });
+}
 async function executeRecordsSummary(args) {
     if (!args.app_key) {
         throw missingRequiredFieldError({
@@ -4343,13 +4951,13 @@ async function executeRecordsSummary(args) {
         });
     }
     const outputProfile = resolveOutputProfile(args.output_profile);
-    const queryId = randomUUID();
     const strictFull = args.strict_full ?? true;
     const includeNegative = args.stat_policy?.include_negative ?? true;
     const includeNull = args.stat_policy?.include_null ?? false;
     const scanMaxPages = args.scan_max_pages ?? DEFAULT_SCAN_MAX_PAGES;
     const requestedPages = args.requested_pages ?? scanMaxPages;
-    const startPage = resolveStartPage(args.page_num, args.page_token, args.app_key);
+    const continuationPayload = resolveContinuationPayload(args.page_token, args.app_key);
+    const startPage = continuationPayload?.next_page_num ?? args.page_num ?? 1;
     const pageSize = args.page_size ?? DEFAULT_PAGE_SIZE;
     const adaptivePaging = createAdaptivePagingState(pageSize);
     const rowCap = Math.min(args.max_rows ?? DEFAULT_ROW_LIMIT, DEFAULT_ROW_LIMIT);
@@ -4375,6 +4983,27 @@ async function executeRecordsSummary(args) {
         });
     }
     validateDateRangeFilters(summaryFilters, index, "qf_query(summary)");
+    const queryFingerprint = buildSummaryContinuationFingerprint({
+        app_key: args.app_key,
+        mode: args.mode,
+        type: args.type,
+        keyword: args.keyword,
+        query_logic: args.query_logic,
+        apply_ids: args.apply_ids,
+        sort: normalizedSort,
+        filters: echoFilters(summaryFilters),
+        select_columns: effectiveColumns,
+        amount_column: amountColumn,
+        time_column: timeColumn,
+        time_range: args.time_range,
+        stat_policy: {
+            include_negative: includeNegative,
+            include_null: includeNull
+        },
+        row_cap: rowCap
+    });
+    const resumed = loadContinuationState("summary", continuationPayload, queryFingerprint, "qf_query(summary)");
+    const queryId = resumed?.state.query_id ?? randomUUID();
     const listState = {
         query_id: queryId,
         app_key: args.app_key,
@@ -4391,20 +5020,23 @@ async function executeRecordsSummary(args) {
     };
     let currentPage = startPage;
     const startedAt = Date.now();
-    let scannedPages = 0;
-    let scannedRecords = 0;
+    const callScanLimit = resolveScanLimit(requestedPages, scanMaxPages);
+    let scannedPagesThisCall = 0;
+    let scannedPagesTotal = resumed?.state.source_pages.length ?? 0;
+    let scannedRecords = resumed?.state.scanned_records ?? 0;
     let hasMore = false;
     let nextPageNum = null;
     let resultAmount = null;
     let summaryMeta = null;
     let stopReason = null;
-    let totalAmount = 0;
-    let missingCount = 0;
-    const sourcePages = [];
-    const rows = [];
-    const byDay = new Map();
-    while (scannedPages < requestedPages && scannedPages < scanMaxPages) {
-        if (scannedPages > 0 && isExecutionBudgetExceeded(startedAt)) {
+    let totalAmount = resumed?.state.total_amount ?? 0;
+    let missingCount = resumed?.state.missing_count ?? 0;
+    const sourcePages = resumed ? [...resumed.state.source_pages] : [];
+    const totalScanLimit = (resumed?.state.scan_limit_total ?? 0) + callScanLimit;
+    const rows = resumed ? [...resumed.state.rows] : [];
+    const byDay = new Map(resumed ? cloneByDayBuckets(resumed.state.by_day) : []);
+    while (scannedPagesThisCall < callScanLimit) {
+        if (scannedPagesThisCall > 0 && isExecutionBudgetExceeded(startedAt)) {
             hasMore = true;
             nextPageNum = currentPage;
             stopReason = "execution_budget";
@@ -4426,7 +5058,8 @@ async function executeRecordsSummary(args) {
         const response = await client.listRecords(args.app_key, payload, { userId: args.user_id });
         const fetchMs = Date.now() - fetchStartedAt;
         summaryMeta = summaryMeta ?? buildMeta(response);
-        scannedPages += 1;
+        scannedPagesThisCall += 1;
+        scannedPagesTotal += 1;
         sourcePages.push(currentPage);
         const result = asObject(response.result);
         const rawItems = asArray(result?.result);
@@ -4474,8 +5107,8 @@ async function executeRecordsSummary(args) {
         }
         const adaptiveDecision = applyAdaptivePaging({
             state: adaptivePaging,
-            fetchedPages: scannedPages,
-            requestedPages,
+            fetchedPages: scannedPagesThisCall,
+            requestedPages: callScanLimit,
             fetchMs,
             startedAt
         });
@@ -4533,33 +5166,49 @@ async function executeRecordsSummary(args) {
     }
     const knownResultAmount = resultAmount ?? scannedRecords;
     const omittedSourceItems = Math.max(0, knownResultAmount - scannedRecords);
-    const rawNextPageToken = hasMore && nextPageNum
-        ? encodeContinuationToken({
+    let rawNextPageToken = null;
+    const rawScanComplete = !hasMore && omittedSourceItems === 0;
+    if (!rawScanComplete && nextPageNum) {
+        const resumeId = setContinuationState("summary", {
+            query_id: queryId,
+            query_fingerprint: queryFingerprint,
+            scanned_records: scannedRecords,
+            total_amount: totalAmount,
+            missing_count: missingCount,
+            by_day: cloneByDayBuckets(Array.from(byDay.entries())),
+            rows: [...rows],
+            source_pages: [...sourcePages],
+            scan_limit_total: totalScanLimit
+        }, resumed?.resumeId);
+        rawNextPageToken = encodeContinuationToken({
             app_key: args.app_key,
             next_page_num: nextPageNum,
-            page_size: adaptivePaging.current_page_size
-        })
-        : null;
-    const rawScanComplete = !hasMore && omittedSourceItems === 0;
+            page_size: adaptivePaging.current_page_size,
+            resume_kind: "summary",
+            resume_id: resumeId
+        });
+    }
+    else {
+        deleteContinuationState(resumed?.resumeId);
+    }
     const outputPageComplete = rows.length >= scannedRecords;
-    const scanLimit = resolveScanLimit(requestedPages, scanMaxPages);
     const scanLimitHit = !rawScanComplete &&
-        (scannedPages >= scanLimit ||
+        (scannedPagesThisCall >= callScanLimit ||
             stopReason === "execution_budget" ||
             stopReason === "adaptive_budget");
     const completeness = buildExtendedCompleteness({
         resultAmount: knownResultAmount,
         returnedItems: scannedRecords,
-        fetchedPages: scannedPages,
-        requestedPages,
+        fetchedPages: scannedPagesTotal,
+        requestedPages: totalScanLimit,
         hasMore,
         nextPageToken: rawNextPageToken,
         omittedItems: omittedSourceItems,
         omittedChars: 0,
         rawScanComplete,
         scanLimitHit,
-        scannedPages,
-        scanLimit,
+        scannedPages: scannedPagesTotal,
+        scanLimit: totalScanLimit,
         outputPageComplete,
         rawNextPageToken,
         outputNextPageToken: null,
@@ -4605,11 +5254,11 @@ async function executeRecordsSummary(args) {
                         },
                         execution: {
                             scanned_records: scannedRecords,
-                            scanned_pages: scannedPages,
+                            scanned_pages: scannedPagesTotal,
                             truncated: !completeness.is_complete,
                             row_cap: rowCap,
                             column_cap: args.max_columns ?? null,
-                            scan_max_pages: scanMaxPages
+                            scan_max_pages: totalScanLimit
                         }
                     }
                 }
@@ -4625,7 +5274,6 @@ async function executeRecordsSummary(args) {
     };
 }
 async function executeRecordsAggregate(args) {
-    const queryId = randomUUID();
     const strictFull = args.strict_full ?? true;
     const outputProfile = resolveOutputProfile(args.output_profile);
     const includeNegative = args.stat_policy?.include_negative ?? true;
@@ -4634,7 +5282,8 @@ async function executeRecordsAggregate(args) {
     const adaptivePaging = createAdaptivePagingState(pageSize);
     const scanMaxPages = args.scan_max_pages ?? DEFAULT_SCAN_MAX_PAGES;
     const requestedPages = args.requested_pages ?? scanMaxPages;
-    const startPage = resolveStartPage(args.page_num, args.page_token, args.app_key);
+    const continuationPayload = resolveContinuationPayload(args.page_token, args.app_key);
+    const startPage = continuationPayload?.next_page_num ?? args.page_num ?? 1;
     const maxGroups = args.max_groups ?? 200;
     const timezone = args.time_range?.timezone ?? "Asia/Shanghai";
     const timeBucket = args.time_bucket ?? null;
@@ -4662,6 +5311,28 @@ async function executeRecordsAggregate(args) {
         });
     }
     validateDateRangeFilters(aggregateFilters, index, "qf_records_aggregate");
+    const queryFingerprint = buildAggregateContinuationFingerprint({
+        app_key: args.app_key,
+        mode: args.mode,
+        type: args.type,
+        keyword: args.keyword,
+        query_logic: args.query_logic,
+        apply_ids: args.apply_ids,
+        sort: normalizedSort,
+        filters: echoFilters(aggregateFilters),
+        group_by: groupColumns,
+        amount_columns: amountColumns,
+        metrics,
+        time_column: timeColumn,
+        time_range: args.time_range,
+        time_bucket: timeBucket,
+        stat_policy: {
+            include_negative: includeNegative,
+            include_null: includeNull
+        }
+    });
+    const resumed = loadContinuationState("aggregate", continuationPayload, queryFingerprint, "qf_records_aggregate");
+    const queryId = resumed?.state.query_id ?? randomUUID();
     const listState = {
         query_id: queryId,
         app_key: args.app_key,
@@ -4682,19 +5353,24 @@ async function executeRecordsAggregate(args) {
     };
     let currentPage = startPage;
     const startedAt = Date.now();
-    let scannedPages = 0;
-    let scannedRecords = 0;
+    const callScanLimit = resolveScanLimit(requestedPages, scanMaxPages);
+    let scannedPagesThisCall = 0;
+    let scannedPagesTotal = resumed?.state.source_pages.length ?? 0;
+    let scannedRecords = resumed?.state.scanned_records ?? 0;
     let hasMore = false;
     let nextPageNum = null;
     let resultAmount = null;
     let responseMeta = null;
     let stopReason = null;
-    let totalAmount = 0;
-    const sourcePages = [];
-    const groupStats = new Map();
-    const summaryMetricStats = new Map();
-    while (scannedPages < requestedPages && scannedPages < scanMaxPages) {
-        if (scannedPages > 0 && isExecutionBudgetExceeded(startedAt)) {
+    let totalAmount = resumed?.state.total_amount ?? 0;
+    const sourcePages = resumed ? [...resumed.state.source_pages] : [];
+    const totalScanLimit = (resumed?.state.scan_limit_total ?? 0) + callScanLimit;
+    const groupStats = resumed ? restoreAggregateGroupStats(resumed.state.group_stats) : new Map();
+    const summaryMetricStats = resumed
+        ? restoreMetricAccumulatorMap(resumed.state.summary_metric_stats)
+        : new Map();
+    while (scannedPagesThisCall < callScanLimit) {
+        if (scannedPagesThisCall > 0 && isExecutionBudgetExceeded(startedAt)) {
             hasMore = true;
             nextPageNum = currentPage;
             stopReason = "execution_budget";
@@ -4716,7 +5392,8 @@ async function executeRecordsAggregate(args) {
         const response = await client.listRecords(args.app_key, payload, { userId: args.user_id });
         const fetchMs = Date.now() - fetchStartedAt;
         responseMeta = responseMeta ?? buildMeta(response);
-        scannedPages += 1;
+        scannedPagesThisCall += 1;
+        scannedPagesTotal += 1;
         sourcePages.push(currentPage);
         const result = asObject(response.result);
         const rawItems = asArray(result?.result);
@@ -4770,8 +5447,8 @@ async function executeRecordsAggregate(args) {
         }
         const adaptiveDecision = applyAdaptivePaging({
             state: adaptivePaging,
-            fetchedPages: scannedPages,
-            requestedPages,
+            fetchedPages: scannedPagesThisCall,
+            requestedPages: callScanLimit,
             fetchMs,
             startedAt
         });
@@ -4791,34 +5468,49 @@ async function executeRecordsAggregate(args) {
     }
     const knownResultAmount = resultAmount ?? scannedRecords;
     const omittedSourceItems = Math.max(0, knownResultAmount - scannedRecords);
-    const rawNextPageToken = hasMore && nextPageNum
-        ? encodeContinuationToken({
-            app_key: args.app_key,
-            next_page_num: nextPageNum,
-            page_size: adaptivePaging.current_page_size
-        })
-        : null;
+    let rawNextPageToken = null;
     const groupsTotal = groupStats.size;
     const rawScanComplete = !hasMore && omittedSourceItems === 0;
+    if (!rawScanComplete && nextPageNum) {
+        const resumeId = setContinuationState("aggregate", {
+            query_id: queryId,
+            query_fingerprint: queryFingerprint,
+            scanned_records: scannedRecords,
+            total_amount: totalAmount,
+            source_pages: [...sourcePages],
+            scan_limit_total: totalScanLimit,
+            group_stats: serializeAggregateGroupStats(groupStats),
+            summary_metric_stats: serializeMetricAccumulatorMap(summaryMetricStats)
+        }, resumed?.resumeId);
+        rawNextPageToken = encodeContinuationToken({
+            app_key: args.app_key,
+            next_page_num: nextPageNum,
+            page_size: adaptivePaging.current_page_size,
+            resume_kind: "aggregate",
+            resume_id: resumeId
+        });
+    }
+    else {
+        deleteContinuationState(resumed?.resumeId);
+    }
     const outputPageComplete = groupsTotal <= maxGroups;
-    const scanLimit = resolveScanLimit(requestedPages, scanMaxPages);
     const scanLimitHit = !rawScanComplete &&
-        (scannedPages >= scanLimit ||
+        (scannedPagesThisCall >= callScanLimit ||
             stopReason === "execution_budget" ||
             stopReason === "adaptive_budget");
     const completeness = buildExtendedCompleteness({
         resultAmount: knownResultAmount,
         returnedItems: scannedRecords,
-        fetchedPages: scannedPages,
-        requestedPages,
+        fetchedPages: scannedPagesTotal,
+        requestedPages: totalScanLimit,
         hasMore,
         nextPageToken: rawNextPageToken,
         omittedItems: omittedSourceItems,
         omittedChars: 0,
         rawScanComplete,
         scanLimitHit,
-        scannedPages,
-        scanLimit,
+        scannedPages: scannedPagesTotal,
+        scanLimit: totalScanLimit,
         outputPageComplete,
         rawNextPageToken,
         outputNextPageToken: null,