@apify/actors-mcp-server 0.10.14-beta.0 → 0.10.14-beta.2

package/dist/tools/common/get_dataset_schema.js

@@ -3,12 +3,12 @@ import { z } from 'zod';
 import { HelperTools, HTTP_NOT_FOUND, TOOL_STATUS } from '../../const.js';
 import { TOOL_TYPE } from '../../types.js';
 import { compileSchema } from '../../utils/ajv.js';
-import { wrapJsonText } from '../../utils/encode_text.js';
 import { stripQuoteWrappers } from '../../utils/generic.js';
 import { getHttpStatusCode } from '../../utils/logging.js';
 import { buildMCPResponse } from '../../utils/mcp.js';
 import { generateSchemaFromItems } from '../../utils/schema_generation.js';
-import { buildStorageNotFound } from './storage_helpers.js';
+import { datasetSchemaOutputSchema } from '../structured_output_schemas.js';
+import { buildStorageNotFound, buildStorageResponse } from './storage_helpers.js';
 const getDatasetSchemaArgs = z.object({
     datasetId: z.string().min(1).describe('Dataset ID or username~dataset-name.'),
     limit: z
@@ -40,6 +40,7 @@ export const getDatasetSchema = Object.freeze({
         - user_input: Generate schema for dataset 34das2 using 10 items
         - user_input: Show schema of username~my-dataset (clean items only)`,
     inputSchema: z.toJSONSchema(getDatasetSchemaArgs),
+    outputSchema: datasetSchemaOutputSchema,
     ajvValidate: compileSchema(z.toJSONSchema(getDatasetSchemaArgs)),
     paymentRequired: true,
     annotations: {
@@ -50,6 +51,7 @@ export const getDatasetSchema = Object.freeze({
         openWorldHint: false,
     },
     call: async (toolArgs) => {
+        var _a;
         const { args, apifyClient: client } = toolArgs;
         const parsed = getDatasetSchemaArgs.parse(args);
         const datasetId = stripQuoteWrappers(parsed.datasetId);
@@ -69,7 +71,11 @@ export const getDatasetSchema = Object.freeze({
         }
         const datasetItems = datasetResponse.items;
         if (datasetItems.length === 0) {
-            return { content: [{ type: 'text', text: `Dataset '${datasetId}' is empty.` }] };
+            // Empty dataset: no items to infer from, but still emit a schema-conforming
+            // response (empty schema = "any") rather than bare text.
+            const summary = `Dataset '${datasetId}' is empty; no schema to infer.`;
+            const nextStep = `Use ${HelperTools.DATASET_GET} with datasetId=${datasetId} to check itemCount and stats.`;
+            return buildStorageResponse({ structuredContent: { datasetId, schema: {} }, summary, nextStep });
         }
         // Generate schema using the shared utility
         const schema = generateSchemaFromItems(datasetItems, {
@@ -84,7 +90,10 @@ export const getDatasetSchema = Object.freeze({
                 telemetry: { toolStatus: TOOL_STATUS.FAILED },
             });
         }
-        return { content: [{ type: 'text', text: wrapJsonText(schema) }] };
+        const fieldCount = Object.keys((_a = schema.items.properties) !== null && _a !== void 0 ? _a : {}).length;
+        const summary = `Schema inferred from ${datasetItems.length} ${datasetItems.length === 1 ? 'item' : 'items'}, ${fieldCount} ${fieldCount === 1 ? 'field' : 'fields'}.`;
+        const nextStep = `Use ${HelperTools.DATASET_GET_ITEMS} with datasetId=${datasetId} and fields="..." to project specific fields.`;
+        return buildStorageResponse({ structuredContent: { datasetId, schema }, summary, nextStep });
     },
 });
 //# sourceMappingURL=get_dataset_schema.js.map

package/dist/tools/common/get_dataset_schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"get_dataset_schema.js","sourceRoot":"","sources":["../../../src/tools/common/get_dataset_schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"get_dataset_schema.js","sourceRoot":"","sources":["../../../src/tools/common/get_dataset_schema.ts"],"names":[],"mappings":"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"}

package/dist/tools/common/get_key_value_store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get_key_value_store.d.ts","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAoB,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AAWnF;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAiCpB,CAAC"}
+{"version":3,"file":"get_key_value_store.d.ts","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAoB,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AAWnF;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAyCpB,CAAC"}

package/dist/tools/common/get_key_value_store.js

@@ -3,9 +3,9 @@ import { z } from 'zod';
 import { HelperTools } from '../../const.js';
 import { TOOL_TYPE } from '../../types.js';
 import { compileSchema } from '../../utils/ajv.js';
-import { wrapJsonText } from '../../utils/encode_text.js';
 import { stripQuoteWrappers } from '../../utils/generic.js';
-import { buildStorageNotFound } from './storage_helpers.js';
+import { keyValueStoreOutputSchema } from '../structured_output_schemas.js';
+import { buildStorageNotFound, buildStorageResponse } from './storage_helpers.js';
 const getKeyValueStoreArgs = z.object({
     keyValueStoreId: z.string().min(1).describe('Key-value store ID or username~store-name'),
 });
@@ -26,6 +26,7 @@ export const getKeyValueStore = Object.freeze({
         - user_input: Show info for key-value store username~my-store
         - user_input: Get details for store adb123`,
     inputSchema: z.toJSONSchema(getKeyValueStoreArgs),
+    outputSchema: keyValueStoreOutputSchema,
     ajvValidate: compileSchema(z.toJSONSchema(getKeyValueStoreArgs)),
     paymentRequired: true,
     annotations: {
@@ -36,6 +37,7 @@ export const getKeyValueStore = Object.freeze({
         openWorldHint: false,
     },
     call: async (toolArgs) => {
+        var _a, _b;
         const { args, apifyClient: client } = toolArgs;
         const parsed = getKeyValueStoreArgs.parse(args);
         const keyValueStoreId = stripQuoteWrappers(parsed.keyValueStoreId);
@@ -43,7 +45,14 @@ export const getKeyValueStore = Object.freeze({
         if (!kvStore) {
             return buildStorageNotFound(`Key-value store '${keyValueStoreId}' not found.`);
         }
-        return { content: [{ type: 'text', text: wrapJsonText(kvStore) }] };
+        const bytes = (_a = kvStore.stats) === null || _a === void 0 ? void 0 : _a.storageBytes;
+        const summary = `Key-value store '${(_b = kvStore.name) !== null && _b !== void 0 ? _b : keyValueStoreId}'${bytes !== undefined ? ` holds ${bytes} bytes` : ''}.`;
+        const nextStep = `Use ${HelperTools.KEY_VALUE_STORE_KEYS_GET} with keyValueStoreId=${keyValueStoreId} to list keys.`;
+        return buildStorageResponse({
+            structuredContent: kvStore,
+            summary,
+            nextStep,
+        });
     },
 });
 //# sourceMappingURL=get_key_value_store.js.map

package/dist/tools/common/get_key_value_store.js.map

@@ -1 +1 @@
-{"version":3,"file":"get_key_value_store.js","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,2CAA2C,CAAC;CAC3F,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAc,MAAM,CAAC,MAAM,CAAC;IACrD,IAAI,EAAE,SAAS,CAAC,QAAQ;IACxB,IAAI,EAAE,WAAW,CAAC,mBAAmB;IACrC,WAAW,EAAE,MAAM,CAAA;;;;;;;;;mDAS4B;IAC/C,WAAW,EAAE,CAAC,CAAC,YAAY,CAAC,oBAAoB,CAAoB;IACpE,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,oBAAoB,CAAC,CAAC;IAChE,eAAe,EAAE,IAAI;IACrB,WAAW,EAAE;QACT,KAAK,EAAE,qBAAqB;QAC5B,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB;IACD,IAAI,EAAE,KAAK,EAAE,QAA0B,EAAE,EAAE;QACvC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;QAC/C,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,eAAe,GAAG,kBAAkB,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QACnE,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,GAAG,EAAE,CAAC;QAClE,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,oBAAoB,CAAC,oBAAoB,eAAe,cAAc,CAAC,CAAC;QACnF,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;IACxE,CAAC;CACK,CAAC,CAAC"}
+{"version":3,"file":"get_key_value_store.js","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAElF,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,2CAA2C,CAAC;CAC3F,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAc,MAAM,CAAC,MAAM,CAAC;IACrD,IAAI,EAAE,SAAS,CAAC,QAAQ;IACxB,IAAI,EAAE,WAAW,CAAC,mBAAmB;IACrC,WAAW,EAAE,MAAM,CAAA;;;;;;;;;mDAS4B;IAC/C,WAAW,EAAE,CAAC,CAAC,YAAY,CAAC,oBAAoB,CAAoB;IACpE,YAAY,EAAE,yBAAyB;IACvC,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,oBAAoB,CAAC,CAAC;IAChE,eAAe,EAAE,IAAI;IACrB,WAAW,EAAE;QACT,KAAK,EAAE,qBAAqB;QAC5B,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB;IACD,IAAI,EAAE,KAAK,EAAE,QAA0B,EAAE,EAAE;;QACvC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;QAC/C,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,eAAe,GAAG,kBAAkB,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QACnE,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,GAAG,EAAE,CAAC;QAClE,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,oBAAoB,CAAC,oBAAoB,eAAe,cAAc,CAAC,CAAC;QACnF,CAAC;QACD,MAAM,KAAK,GAAG,MAAC,OAAO,CAAC,KAA+C,0CAAE,YAAY,CAAC;QACrF,MAAM,OAAO,GAAG,oBAAoB,MAAA,OAAO,CAAC,IAAI,mCAAI,eAAe,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;QAC7H,MAAM,QAAQ,GAAG,OAAO,WAAW,CAAC,wBAAwB,yBAAyB,eAAe,gBAAgB,CAAC;QACrH,OAAO,oBAAoB,CAAC;YACxB,iBAAiB,EAAE,OAA6C;YAChE,OAAO;YACP,QAAQ;SACX,CAAC,CAAC;IACP,CAAC;CACK,CAAC,CAAC"}

package/dist/tools/common/get_key_value_store_keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get_key_value_store_keys.d.ts","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store_keys.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAoB,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AAkBnF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,SA6CxB,CAAC"}
+{"version":3,"file":"get_key_value_store_keys.d.ts","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store_keys.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAoB,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AAiBnF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAyDxB,CAAC"}

package/dist/tools/common/get_key_value_store_keys.js

@@ -3,11 +3,10 @@ import { z } from 'zod';
 import { HelperTools, HTTP_NOT_FOUND } from '../../const.js';
 import { TOOL_TYPE } from '../../types.js';
 import { compileSchema } from '../../utils/ajv.js';
-import { encodeToon } from '../../utils/encode_text.js';
 import { stripQuoteWrappers } from '../../utils/generic.js';
 import { getHttpStatusCode } from '../../utils/logging.js';
 import { keyValueStoreKeysOutputSchema } from '../structured_output_schemas.js';
-import { buildStorageNotFound } from './storage_helpers.js';
+import { buildKvsKeysSummaryNextStep, buildStorageNotFound, buildStorageResponse } from './storage_helpers.js';
 const getKeyValueStoreKeysArgs = z.object({
     keyValueStoreId: z.string().min(1).describe('Key-value store ID or username~store-name'),
     exclusiveStartKey: z
@@ -45,6 +44,7 @@ export const getKeyValueStoreKeys = Object.freeze({
         openWorldHint: false,
     },
     call: async (toolArgs) => {
+        var _a;
         const { args, apifyClient: client } = toolArgs;
         const parsed = getKeyValueStoreKeysArgs.parse(args);
         const keyValueStoreId = stripQuoteWrappers(parsed.keyValueStoreId);
@@ -62,7 +62,19 @@ export const getKeyValueStoreKeys = Object.freeze({
         if (!keys) {
             return buildStorageNotFound(`Key-value store '${keyValueStoreId}' not found.`);
         }
-        return { content: [{ type: 'text', text: encodeToon(keys) }], structuredContent: keys };
+        const { summary, nextStep } = buildKvsKeysSummaryNextStep({
+            keyValueStoreId,
+            count: keys.items.length,
+            isTruncated: keys.isTruncated,
+            nextExclusiveStartKey: keys.nextExclusiveStartKey,
+            firstKey: (_a = keys.items[0]) === null || _a === void 0 ? void 0 : _a.key,
+        });
+        return buildStorageResponse({
+            structuredContent: { keyValueStoreId, ...keys },
+            summary,
+            nextStep,
+            toon: true,
+        });
     },
 });
 //# sourceMappingURL=get_key_value_store_keys.js.map

package/dist/tools/common/get_key_value_store_keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"get_key_value_store_keys.js","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store_keys.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"get_key_value_store_keys.js","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store_keys.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE7D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE/G,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,2CAA2C,CAAC;IACxF,iBAAiB,EAAE,CAAC;SACf,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,kEAAkE,CAAC;IACjF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qDAAqD,CAAC;CACvG,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAc,MAAM,CAAC,MAAM,CAAC;IACzD,IAAI,EAAE,SAAS,CAAC,QAAQ;IACxB,IAAI,EAAE,WAAW,CAAC,wBAAwB;IAC1C,WAAW,EAAE,MAAM,CAAA;;;;;;;;;;6EAUsD;IACzE,WAAW,EAAE,CAAC,CAAC,YAAY,CAAC,wBAAwB,CAAoB;IACxE,YAAY,EAAE,6BAA6B;IAC3C,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,wBAAwB,CAAC,CAAC;IACpE,eAAe,EAAE,IAAI;IACrB,WAAW,EAAE;QACT,KAAK,EAAE,0BAA0B;QACjC,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB;IACD,IAAI,EAAE,KAAK,EAAE,QAA0B,EAAE,EAAE;;QACvC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;QAC/C,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpD,MAAM,eAAe,GAAG,kBAAkB,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QACnE,kFAAkF;QAClF,wEAAwE;QACxE,MAAM,IAAI,GAAG,MAAM,MAAM;aACpB,aAAa,CAAC,eAAe,CAAC;aAC9B,QAAQ,CAAC,EAAE,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;aAC9E,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACpB,IAAI,iBAAiB,CAAC,GAAG,CAAC,KAAK,cAAc,EAAE,CAAC;gBAC5C,OAAO,IAAI,CAAC;YAChB,CAAC;YACD,MAAM,GAAG,CAAC;QACd,CAAC,CAAC,CAAC;QACP,IAAI,CAAC,IAAI,EAAE,CAAC;YACR,OAAO,oBAAoB,CAAC,oBAAoB,eAAe,cAAc,CAAC,CAAC;QACnF,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,2BAA2B,CAAC;YACtD,eAAe;YACf,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;YACxB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,qBAAqB,EAAE,IAAI,CAAC,qBAAqB;YACjD,QAAQ,EAAE,MAAA,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,0CAAE,GAAG;SAC/B,CAAC,CAAC;QACH,OAAO,oBAAoB,CAAC;YACxB,iBAAiB,EAAE,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE;YAC/C,OAAO;YACP,QAAQ;YACR,IAAI,EAAE,IAAI;SACb,CAAC,CAAC;IACP,CAAC;CACK,CAAC,CAAC"}

package/dist/tools/common/get_key_value_store_record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get_key_value_store_record.d.ts","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store_record.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAoB,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AAYnF;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAwC1B,CAAC"}
+{"version":3,"file":"get_key_value_store_record.d.ts","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store_record.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAoB,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AAYnF;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAgD1B,CAAC"}

package/dist/tools/common/get_key_value_store_record.js

@@ -3,9 +3,9 @@ import { z } from 'zod';
 import { HelperTools } from '../../const.js';
 import { TOOL_TYPE } from '../../types.js';
 import { compileSchema } from '../../utils/ajv.js';
-import { wrapJsonText } from '../../utils/encode_text.js';
-import { stripQuoteWrappers } from '../../utils/generic.js';
-import { buildStorageNotFound, normalizeRecordKey } from './storage_helpers.js';
+import { computeValueBytes, stripQuoteWrappers } from '../../utils/generic.js';
+import { keyValueStoreRecordOutputSchema } from '../structured_output_schemas.js';
+import { buildStorageNotFound, buildStorageResponse, normalizeRecordKey } from './storage_helpers.js';
 const getKeyValueStoreRecordArgs = z.object({
     keyValueStoreId: z.string().min(1).describe('Key-value store ID or username~store-name'),
     recordKey: z.string().min(1).describe('Key of the record to retrieve.'),
@@ -27,6 +27,7 @@ export const getKeyValueStoreRecord = Object.freeze({
         - user_input: Get record INPUT from store abc123
         - user_input: Get record data.json from store username~my-store`,
     inputSchema: z.toJSONSchema(getKeyValueStoreRecordArgs),
+    outputSchema: keyValueStoreRecordOutputSchema,
     ajvValidate: compileSchema(z.toJSONSchema(getKeyValueStoreRecordArgs)),
     paymentRequired: true,
     annotations: {
@@ -51,7 +52,14 @@ export const getKeyValueStoreRecord = Object.freeze({
                 : `Key-value store '${keyValueStoreId}' not found.`;
             return buildStorageNotFound(text);
         }
-        return { content: [{ type: 'text', text: wrapJsonText(record) }] };
+        const bytes = computeValueBytes(record.value);
+        const details = [
+            record.contentType ? `contentType=${record.contentType}` : undefined,
+            bytes !== undefined ? `${bytes} bytes` : undefined,
+        ].filter(Boolean);
+        const summary = `Read '${recordKey}'${details.length ? ` (${details.join(', ')})` : ''}.`;
+        // Reading a record is terminal — no nextStep.
+        return buildStorageResponse({ structuredContent: { keyValueStoreId, ...record }, summary });
     },
 });
 //# sourceMappingURL=get_key_value_store_record.js.map

package/dist/tools/common/get_key_value_store_record.js.map

@@ -1 +1 @@
-{"version":3,"file":"get_key_value_store_record.js","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store_record.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,2CAA2C,CAAC;IACxF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,gCAAgC,CAAC;CAC1E,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAc,MAAM,CAAC,MAAM,CAAC;IAC3D,IAAI,EAAE,SAAS,CAAC,QAAQ;IACxB,IAAI,EAAE,WAAW,CAAC,0BAA0B;IAC5C,WAAW,EAAE,MAAM,CAAA;;;;;;;;;wEASiD;IACpE,WAAW,EAAE,CAAC,CAAC,YAAY,CAAC,0BAA0B,CAAoB;IAC1E,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,0BAA0B,CAAC,CAAC;IACtE,eAAe,EAAE,IAAI;IACrB,WAAW,EAAE;QACT,KAAK,EAAE,4BAA4B;QACnC,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB;IACD,IAAI,EAAE,KAAK,EAAE,QAA0B,EAAE,EAAE;QACvC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;QAC/C,MAAM,MAAM,GAAG,0BAA0B,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtD,MAAM,eAAe,GAAG,kBAAkB,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QACnE,MAAM,SAAS,GAAG,kBAAkB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACvD,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAChD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACvB,oFAAoF;YACpF,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,SAAS;gBAClB,CAAC,CAAC,WAAW,SAAS,mCAAmC,eAAe,IAAI;gBAC5E,CAAC,CAAC,oBAAoB,eAAe,cAAc,CAAC;YACxD,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;IACvE,CAAC;CACK,CAAC,CAAC"}
+{"version":3,"file":"get_key_value_store_record.js","sourceRoot":"","sources":["../../../src/tools/common/get_key_value_store_record.ts"],"names":[],"mappings":"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"}

package/dist/tools/common/key_value_store_collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"key_value_store_collection.d.ts","sourceRoot":"","sources":["../../../src/tools/common/key_value_store_collection.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAoB,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AA8BnF;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAqC7B,CAAC"}
+{"version":3,"file":"key_value_store_collection.d.ts","sourceRoot":"","sources":["../../../src/tools/common/key_value_store_collection.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAoB,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AA8BnF;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAkD7B,CAAC"}

package/dist/tools/common/key_value_store_collection.js

@@ -3,8 +3,8 @@ import { z } from 'zod';
 import { HelperTools } from '../../const.js';
 import { TOOL_TYPE } from '../../types.js';
 import { compileSchema } from '../../utils/ajv.js';
-import { encodeToon } from '../../utils/encode_text.js';
-import { keyValueStoreListOutputSchema } from '../structured_output_schemas.js';
+import { storageListOutputSchema } from '../structured_output_schemas.js';
+import { buildStorageListSummaryNextStep, buildStorageResponse } from './storage_helpers.js';
 const getUserKeyValueStoresListArgs = z.object({
     offset: z
         .number()
@@ -44,7 +44,7 @@ export const getUserKeyValueStoresList = Object.freeze({
         - user_input: List my last 10 key-value stores (newest first)
         - user_input: List unnamed key-value stores`,
     inputSchema: z.toJSONSchema(getUserKeyValueStoresListArgs),
-    outputSchema: keyValueStoreListOutputSchema,
+    outputSchema: storageListOutputSchema,
     ajvValidate: compileSchema(z.toJSONSchema(getUserKeyValueStoresListArgs)),
     annotations: {
         title: 'Get user key-value stores list',
@@ -62,7 +62,20 @@ export const getUserKeyValueStoresList = Object.freeze({
             desc: parsed.desc,
             unnamed: parsed.unnamed,
         });
-        return { content: [{ type: 'text', text: encodeToon(stores) }], structuredContent: stores };
+        const { summary, nextStep } = buildStorageListSummaryNextStep({
+            count: stores.items.length,
+            total: stores.total,
+            offset: stores.offset,
+            noun: 'key-value stores',
+            listToolName: HelperTools.KEY_VALUE_STORE_LIST_GET,
+            inspectHint: `Use ${HelperTools.KEY_VALUE_STORE_GET} with a keyValueStoreId from the list to inspect a store.`,
+        });
+        return buildStorageResponse({
+            structuredContent: stores,
+            summary,
+            nextStep,
+            toon: true,
+        });
     },
 });
 //# sourceMappingURL=key_value_store_collection.js.map

package/dist/tools/common/key_value_store_collection.js.map

@@ -1 +1 @@
-{"version":3,"file":"key_value_store_collection.js","sourceRoot":"","sources":["../../../src/tools/common/key_value_store_collection.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAEhF,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,MAAM,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,CAAC,iFAAiF,CAAC;SAC3F,OAAO,CAAC,CAAC,CAAC;IACf,KAAK,EAAE,CAAC;SACH,MAAM,EAAE;SACR,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,CAAC,oFAAoF,CAAC;SAC9F,OAAO,CAAC,EAAE,CAAC;IAChB,IAAI,EAAE,CAAC;SACF,OAAO,EAAE;SACT,QAAQ,CACL,yHAAyH,CAC5H;SACA,OAAO,CAAC,KAAK,CAAC;IACnB,OAAO,EAAE,CAAC;SACL,OAAO,EAAE;SACT,QAAQ,CACL,sGAAsG,CACzG;SACA,OAAO,CAAC,KAAK,CAAC;CACtB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAc,MAAM,CAAC,MAAM,CAAC;IAC9D,IAAI,EAAE,SAAS,CAAC,QAAQ;IACxB,IAAI,EAAE,WAAW,CAAC,wBAAwB;IAC1C,WAAW,EAAE,MAAM,CAAA;;;;;;;;;;;;oDAY6B;IAChD,WAAW,EAAE,CAAC,CAAC,YAAY,CAAC,6BAA6B,CAAoB;IAC7E,YAAY,EAAE,6BAA6B;IAC3C,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,6BAA6B,CAAC,CAAC;IACzE,WAAW,EAAE;QACT,KAAK,EAAE,gCAAgC;QACvC,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB;IACD,IAAI,EAAE,KAAK,EAAE,QAA0B,EAAE,EAAE;QACvC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;QAC/C,MAAM,MAAM,GAAG,6BAA6B,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC;YAC9C,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;SAC1B,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAChG,CAAC;CACK,CAAC,CAAC"}
+{"version":3,"file":"key_value_store_collection.js","sourceRoot":"","sources":["../../../src/tools/common/key_value_store_collection.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,+BAA+B,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE7F,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,MAAM,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,CAAC,iFAAiF,CAAC;SAC3F,OAAO,CAAC,CAAC,CAAC;IACf,KAAK,EAAE,CAAC;SACH,MAAM,EAAE;SACR,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,CAAC,oFAAoF,CAAC;SAC9F,OAAO,CAAC,EAAE,CAAC;IAChB,IAAI,EAAE,CAAC;SACF,OAAO,EAAE;SACT,QAAQ,CACL,yHAAyH,CAC5H;SACA,OAAO,CAAC,KAAK,CAAC;IACnB,OAAO,EAAE,CAAC;SACL,OAAO,EAAE;SACT,QAAQ,CACL,sGAAsG,CACzG;SACA,OAAO,CAAC,KAAK,CAAC;CACtB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAc,MAAM,CAAC,MAAM,CAAC;IAC9D,IAAI,EAAE,SAAS,CAAC,QAAQ;IACxB,IAAI,EAAE,WAAW,CAAC,wBAAwB;IAC1C,WAAW,EAAE,MAAM,CAAA;;;;;;;;;;;;oDAY6B;IAChD,WAAW,EAAE,CAAC,CAAC,YAAY,CAAC,6BAA6B,CAAoB;IAC7E,YAAY,EAAE,uBAAuB;IACrC,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,6BAA6B,CAAC,CAAC;IACzE,WAAW,EAAE;QACT,KAAK,EAAE,gCAAgC;QACvC,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB;IACD,IAAI,EAAE,KAAK,EAAE,QAA0B,EAAE,EAAE;QACvC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;QAC/C,MAAM,MAAM,GAAG,6BAA6B,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC;YAC9C,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;SAC1B,CAAC,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,+BAA+B,CAAC;YAC1D,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;YAC1B,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI,EAAE,kBAAkB;YACxB,YAAY,EAAE,WAAW,CAAC,wBAAwB;YAClD,WAAW,EAAE,OAAO,WAAW,CAAC,mBAAmB,2DAA2D;SACjH,CAAC,CAAC;QACH,OAAO,oBAAoB,CAAC;YACxB,iBAAiB,EAAE,MAA4C;YAC/D,OAAO;YACP,QAAQ;YACR,IAAI,EAAE,IAAI;SACb,CAAC,CAAC;IACP,CAAC;CACK,CAAC,CAAC"}

package/dist/tools/common/storage_helpers.d.ts

@@ -13,5 +13,74 @@ export declare function buildStorageNotFound(text: string): {
     }[];
     isError: boolean;
 };
+/**
+ * Build a storage tool response, mirroring `actor_run_response.ts`:
+ * `structuredContent` carries the data plus `summary` (and `nextStep` unless terminal).
+ * `nextStep` is omitted for terminal responses (e.g. get-key-value-store-record).
+ *
+ * `toon: true` (the list tools) emits a single text: the data TOON-encoded in a ```toon fence
+ * (token-cheaper for uniform-row arrays; `summary`/`nextStep` are prose, not tabular, so they
+ * stay out of the fence) followed by `summary`/`nextStep` as plain text. Single-object tools
+ * leave it off and ship `content[0]` as the raw-JSON dump of `structuredContent` plus
+ * `content[1]` with `summary`/`nextStep`. Either way `structuredContent` is the lossless source
+ * of truth — programmatic consumers read it, not `content[]`.
+ */
+export declare function buildStorageResponse(params: {
+    structuredContent: Record<string, unknown>;
+    summary: string;
+    nextStep?: string;
+    toon?: boolean;
+}): {
+    _meta?: Record<string, unknown> | undefined;
+    structuredContent?: {} | null | undefined;
+    toolTelemetry?: import("../../types.js").ToolTelemetryContext | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/**
+ * {summary, nextStep} for paginated storage listings (datasets, key-value stores).
+ * When more items remain, nextStep points at the next page; otherwise at inspecting an entry.
+ */
+export declare function buildStorageListSummaryNextStep(params: {
+    count: number;
+    total: number;
+    offset: number;
+    noun: string;
+    listToolName: string;
+    inspectHint: string;
+}): {
+    summary: string;
+    nextStep: string;
+};
+/**
+ * Pagination-aware {summary, nextStep}: when more items remain, point at the next page;
+ * otherwise point at get-dataset-schema for structure inspection.
+ */
+export declare function buildDatasetItemsSummaryNextStep(params: {
+    datasetId: string;
+    itemCount: number;
+    totalItemCount: number;
+    offset: number;
+}): {
+    summary: string;
+    nextStep: string;
+};
+/**
+ * {summary, nextStep} for cursor-paginated key-value store key listings.
+ * When truncated, nextStep points at the next page; otherwise at inspecting a record or the store.
+ */
+export declare function buildKvsKeysSummaryNextStep(params: {
+    keyValueStoreId: string;
+    count: number;
+    isTruncated: boolean;
+    nextExclusiveStartKey?: string;
+    firstKey?: string;
+}): {
+    summary: string;
+    nextStep: string;
+};
 export declare function normalizeRecordKey(key: string): string;
 //# sourceMappingURL=storage_helpers.d.ts.map

package/dist/tools/common/storage_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage_helpers.d.ts","sourceRoot":"","sources":["../../../src/tools/common/storage_helpers.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM;;;;;;;;;EAMhD;AAWD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD"}
+{"version":3,"file":"storage_helpers.d.ts","sourceRoot":"","sources":["../../../src/tools/common/storage_helpers.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM;;;;;;;;;EAMhD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IACzC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;CAClB;;;;;;;;;EAQA;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACvB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CASxC;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAClB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAgBxC;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAgBxC;AAWD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/tools/common/storage_helpers.js

@@ -1,4 +1,5 @@
-import { FAILURE_CATEGORY, TOOL_STATUS } from '../../const.js';
+import { FAILURE_CATEGORY, TOOL_STATUS, HelperTools } from '../../const.js';
+import { encodeToon } from '../../utils/encode_text.js';
 import { QUOTE_WRAPPER_CHARS } from '../../utils/generic.js';
 import { buildMCPResponse } from '../../utils/mcp.js';
 /**
@@ -13,6 +14,81 @@ export function buildStorageNotFound(text) {
         telemetry: { toolStatus: TOOL_STATUS.SOFT_FAIL, failureCategory: FAILURE_CATEGORY.INVALID_INPUT },
     });
 }
+/**
+ * Build a storage tool response, mirroring `actor_run_response.ts`:
+ * `structuredContent` carries the data plus `summary` (and `nextStep` unless terminal).
+ * `nextStep` is omitted for terminal responses (e.g. get-key-value-store-record).
+ *
+ * `toon: true` (the list tools) emits a single text: the data TOON-encoded in a ```toon fence
+ * (token-cheaper for uniform-row arrays; `summary`/`nextStep` are prose, not tabular, so they
+ * stay out of the fence) followed by `summary`/`nextStep` as plain text. Single-object tools
+ * leave it off and ship `content[0]` as the raw-JSON dump of `structuredContent` plus
+ * `content[1]` with `summary`/`nextStep`. Either way `structuredContent` is the lossless source
+ * of truth — programmatic consumers read it, not `content[]`.
+ */
+export function buildStorageResponse(params) {
+    const { structuredContent, summary, nextStep, toon } = params;
+    const full = { ...structuredContent, summary, ...(nextStep !== undefined && { nextStep }) };
+    const summaryText = nextStep !== undefined ? `${summary}\n${nextStep}` : summary;
+    return buildMCPResponse({
+        texts: toon ? [encodeToon(structuredContent), summaryText] : [JSON.stringify(structuredContent), summaryText],
+        structuredContent: full,
+    });
+}
+/**
+ * {summary, nextStep} for paginated storage listings (datasets, key-value stores).
+ * When more items remain, nextStep points at the next page; otherwise at inspecting an entry.
+ */
+export function buildStorageListSummaryNextStep(params) {
+    const { count, total, offset, noun, listToolName, inspectHint } = params;
+    return {
+        summary: `Listed ${count} of ${total} ${noun}.`,
+        nextStep: offset + count < total
+            ? `Call ${listToolName} again with offset=${offset + count} to fetch the next page.`
+            : inspectHint,
+    };
+}
+/**
+ * Pagination-aware {summary, nextStep}: when more items remain, point at the next page;
+ * otherwise point at get-dataset-schema for structure inspection.
+ */
+export function buildDatasetItemsSummaryNextStep(params) {
+    const { datasetId, itemCount, totalItemCount, offset } = params;
+    if (offset + itemCount < totalItemCount) {
+        return {
+            summary: `Fetched ${itemCount} of ${totalItemCount} items (offset=${offset}).`,
+            nextStep: `Call ${HelperTools.DATASET_GET_ITEMS} again with offset=${offset + itemCount} to fetch the next page.`,
+        };
+    }
+    const summary = offset === 0 && itemCount === totalItemCount
+        ? `Fetched all ${itemCount} items.`
+        : `Fetched ${itemCount} of ${totalItemCount} items (offset=${offset}); no more pages.`;
+    return {
+        summary,
+        nextStep: `Use ${HelperTools.DATASET_SCHEMA_GET} with datasetId=${datasetId} to inspect structure if needed.`,
+    };
+}
+/**
+ * {summary, nextStep} for cursor-paginated key-value store key listings.
+ * When truncated, nextStep points at the next page; otherwise at inspecting a record or the store.
+ */
+export function buildKvsKeysSummaryNextStep(params) {
+    const { keyValueStoreId, count, isTruncated, nextExclusiveStartKey, firstKey } = params;
+    const noun = count === 1 ? 'key' : 'keys';
+    const summary = `Listed ${count} ${noun}${isTruncated ? ' (more available)' : ''}.`;
+    if (isTruncated && nextExclusiveStartKey) {
+        return {
+            summary,
+            nextStep: `Call ${HelperTools.KEY_VALUE_STORE_KEYS_GET} again with exclusiveStartKey=${nextExclusiveStartKey} to fetch the next page.`,
+        };
+    }
+    return {
+        summary,
+        nextStep: firstKey
+            ? `Use ${HelperTools.KEY_VALUE_STORE_RECORD_GET} with keyValueStoreId=${keyValueStoreId} and recordKey=${firstKey} to read a value.`
+            : `Use ${HelperTools.KEY_VALUE_STORE_GET} with keyValueStoreId=${keyValueStoreId} to inspect the store.`,
+    };
+}
 /**
  * Normalize a key-value store record key before SDK lookup.
  *

package/dist/tools/common/storage_helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage_helpers.js","sourceRoot":"","sources":["../../../src/tools/common/storage_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC7C,OAAO,gBAAgB,CAAC;QACpB,KAAK,EAAE,CAAC,IAAI,CAAC;QACb,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,EAAE,UAAU,EAAE,WAAW,CAAC,SAAS,EAAE,eAAe,EAAE,gBAAgB,CAAC,aAAa,EAAE;KACpG,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,0BAA0B,GAAG,IAAI,MAAM,CAAC,KAAK,mBAAmB,OAAO,mBAAmB,KAAK,EAAE,GAAG,CAAC,CAAC;AAC5G,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC1C,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACrE,CAAC"}
+{"version":3,"file":"storage_helpers.js","sourceRoot":"","sources":["../../../src/tools/common/storage_helpers.ts"],"names":[],"mappings":"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"}

package/dist/tools/core/actor_run_response.js

@@ -261,7 +261,7 @@ function buildSucceededSummaryNextStep(runTimeSecs, statusMessage, dataset, keyV
         const fields = (_a = dataset === null || dataset === void 0 ? void 0 : dataset.fields) !== null && _a !== void 0 ? _a : [];
         return {
             summary: `SUCCEEDED in ${runTimeSecs}s. ${itemCount} ${itemCount === 1 ? 'item' : 'items'}; ${fields.length} fields available.${kv.summarySuffix}`,
-            nextStep: `Use ${HelperTools.DATASET_GET_ITEMS} with datasetId=${datasetId} and limit=20 to fetch items (${itemCount} total).${fieldsProjectionHint(fields)}`,
+            nextStep: `Use ${HelperTools.DATASET_GET_ITEMS} with datasetId=${datasetId} and limit (for example 20) to fetch items (${itemCount} total).${fieldsProjectionHint(fields)}`,
         };
     }
     // datasetId known but metadata unavailable (transient fetch failure on a terminal run). Don't
@@ -269,7 +269,7 @@ function buildSucceededSummaryNextStep(runTimeSecs, statusMessage, dataset, keyV
     if (itemCount === undefined && datasetId) {
         return {
             summary: `SUCCEEDED in ${runTimeSecs}s. Dataset metadata unavailable.${statusMessageLine(statusMessage)}${kv.summarySuffix}`,
-            nextStep: `Use ${HelperTools.DATASET_GET_ITEMS} with datasetId=${datasetId} and limit=20 to inspect output.`,
+            nextStep: `Use ${HelperTools.DATASET_GET_ITEMS} with datasetId=${datasetId} and limit (for example 20) to inspect output.`,
         };
     }
     // Metadata can report itemCount === 0 briefly after SUCCEEDED (eventual consistency). Surface the
@@ -277,7 +277,7 @@ function buildSucceededSummaryNextStep(runTimeSecs, statusMessage, dataset, keyV
     if (itemCount === 0 && datasetId) {
         return {
             summary: `SUCCEEDED in ${runTimeSecs}s. No dataset items found.${statusMessageLine(statusMessage)}${kv.summarySuffix}`,
-            nextStep: `Use ${HelperTools.DATASET_GET_ITEMS} with datasetId=${datasetId} and limit=20 to verify output (metadata reports 0 items).${fieldsProjectionHint(dataset === null || dataset === void 0 ? void 0 : dataset.fields)}`,
+            nextStep: `Use ${HelperTools.DATASET_GET_ITEMS} with datasetId=${datasetId} and limit (for example 20) to verify output (metadata reports 0 items).${fieldsProjectionHint(dataset === null || dataset === void 0 ? void 0 : dataset.fields)}`,
         };
     }
     // KV store is rarely the primary output for Apify actors (mostly SDK state / intermediate data),
@@ -300,7 +300,7 @@ function buildTimedOutSummaryNextStep(runTimeSecs, dataset, keyValueStore) {
         const fields = (_b = dataset === null || dataset === void 0 ? void 0 : dataset.fields) !== null && _b !== void 0 ? _b : [];
         return {
             summary: `TIMED-OUT after ${runTimeSecs}s.${kv.summarySuffix}`,
-            nextStep: `Use ${HelperTools.DATASET_GET_ITEMS} with datasetId=${datasetId} and limit=20 to fetch any partial output (${itemCount} ${itemCount === 1 ? 'item' : 'items'} written). Available fields: ${fields.length > 0 ? fields.join(', ') : 'none'}.`,
+            nextStep: `Use ${HelperTools.DATASET_GET_ITEMS} with datasetId=${datasetId} and limit (for example 20) to fetch any partial output (${itemCount} ${itemCount === 1 ? 'item' : 'items'} written). Available fields: ${fields.length > 0 ? fields.join(', ') : 'none'}.`,
         };
     }
     return {