@apify/actors-mcp-server 0.18.4 → 0.18.5-beta.0

package/dist/tools/versions/create_actor.js

@@ -0,0 +1,171 @@
+import { ActorSourceType, ApifyApiError } from 'apify-client';
+import dedent from 'dedent';
+import { z } from 'zod';
+import { APIFY_ERROR_TYPE_ACTOR_NAME_NOT_UNIQUE, HELPER_TOOLS } from '../../const.js';
+import { UserInputError } from '../../errors.js';
+import { TOOL_TYPE } from '../../types.js';
+import { compileSchema, fixZodSchemaRequired } from '../../utils/ajv.js';
+import { respondAborted, respondUserError } from '../../utils/mcp.js';
+import { createActorToolOutputSchema } from '../structured_output_schemas.js';
+import { buildFilesManifest, buildFilesRevision } from './source_files.js';
+import { buildEmptyFilesWarnings, buildSourceFileEntry, extractSourceFiles, redactSourceToolArgs, resolveVersion, respondAfterWrite, respondToSourceToolError, SourcePathIndex, sourceFileArgs, validateFileContent, validateFilePath, validatePathCharacters, } from './source_helpers.js';
+const createActorArgs = z.object({
+    name: z.string().min(1).describe('Name of the new Actor, without a username, for example my-scraper.'),
+    title: z.string().min(1).optional().describe('Display title, for example My Scraper.'),
+    description: z.string().optional().describe('A short description of what the Actor does.'),
+    files: z.array(sourceFileArgs).min(1).describe("The Actor's files, each with its whole content."),
+    versionNumber: z
+        .string()
+        .optional()
+        .describe('Number of the version in MAJOR.MINOR form. Default: the version in .actor/actor.json, or 0.0 when it has none.'),
+    buildTag: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Tag that builds of the version get. The platform uses latest when it is omitted.'),
+    autoBuild: z
+        .boolean()
+        .default(false)
+        .describe('Start a build of the version after creating the Actor, and return without waiting. Default: false.'),
+});
+/**
+ * The entries to send, one per file; throws `UserInputError` for a path no file can be written at, and for a path
+ * given twice, since the platform puts the Actor name in the first .actor/actor.json and the build uses the last.
+ */
+function buildSourceFileEntries(files) {
+    const entries = [];
+    const pathIndex = new SourcePathIndex([]);
+    for (const [index, file] of files.entries()) {
+        validatePathCharacters(file.path, `files[${index}]`);
+        const entry = buildSourceFileEntry(file);
+        const label = `files[${index}] (${file.path})`;
+        validateFilePath(entry.name, label);
+        validateFileContent(entry, label);
+        if (pathIndex.hasFile(entry.name)) {
+            throw new UserInputError(`${label} repeats the path ${entry.name}; each path can be sent only once.`);
+        }
+        pathIndex.validateNewFilePath(entry.name, label);
+        pathIndex.addFile(entry.name);
+        entries.push(entry);
+    }
+    return entries;
+}
+/**
+ * The `version` of .actor/actor.json when it is a non-empty string in valid JSON, as `apify push` reads it. A leading
+ * byte order mark, which some editors write, is skipped, since JSON.parse refuses it.
+ */
+function readActorJsonVersion(entries) {
+    const actorJson = entries.find(({ name, format }) => name === '.actor/actor.json' && format === 'TEXT');
+    if (!actorJson)
+        return undefined;
+    try {
+        const { version } = JSON.parse(actorJson.content.replace(/^\uFEFF/, ''));
+        return typeof version === 'string' && version !== '' ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A refusal of the name as taken on a retry of the POST, which an earlier attempt of the same call may have caused. */
+function isRetriedNameTaken(error) {
+    return error instanceof ApifyApiError && error.type === APIFY_ERROR_TYPE_ACTOR_NAME_NOT_UNIQUE && error.attempt > 1;
+}
+/**
+ * https://docs.apify.com/api/v2/actors-post
+ *  /v2/actors
+ *
+ * One POST creates the Actor and its version together, private and in the token's account. apify-client retries the
+ * POST after a network error, a timeout, a 429, or a 5xx, so when the platform saved an attempt it did not answer, the
+ * retry fails on the name that attempt took, and the call says the Actor may exist.
+ */
+export const createActor = Object.freeze({
+    type: TOOL_TYPE.INTERNAL,
+    name: HELPER_TOOLS.ACTOR_CREATE,
+    title: 'Create Actor',
+    description: dedent `
+        Create a new private Actor in your account, with one version holding the files you give. It never changes an existing Actor: the platform refuses a name your account already uses.
+        - files: every file with its path and content. Binary files take base64 content with encoding base64; files with a binary extension such as .png default to it.
+        The platform sets the name field of .actor/actor.json to the Actor name, so the result lists each file's hash and the version's revision as stored.
+        autoBuild starts a build after creating the Actor and returns without waiting.
+
+        USAGE:
+        - Use to upload new Actor code to the Apify platform for the first time.
+
+        USAGE EXAMPLES:
+        - user_input: Create an Actor called hacker-news-scraper from these files`,
+    // `fixZodSchemaRequired` strips `autoBuild` from `required` because it has a default.
+    inputSchema: fixZodSchemaRequired(z.toJSONSchema(createActorArgs)),
+    outputSchema: createActorToolOutputSchema,
+    ajvValidate: compileSchema(z.toJSONSchema(createActorArgs)),
+    annotations: {
+        title: 'Create Actor',
+        readOnlyHint: false,
+        destructiveHint: false,
+        // A second call with the same name is refused rather than repeated.
+        idempotentHint: false,
+        // autoBuild starts a build, like build-actor.
+        openWorldHint: true,
+    },
+    redactArgs: (args) => redactSourceToolArgs(args, {
+        keys: ['name', 'title', 'description', 'versionNumber', 'buildTag', 'autoBuild'],
+        listKey: 'files',
+        entryKeys: ['path', 'encoding'],
+    }),
+    call: async (toolArgs) => {
+        const { args, apifyClient: client, signal, loadedToolNames } = toolArgs;
+        const parsed = createActorArgs.parse(args);
+        // A cancel before the POST creates nothing; per the MCP spec the cancelled request gets no response.
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+            return respondAborted();
+        try {
+            const sourceFiles = buildSourceFileEntries(parsed.files);
+            // The platform refuses a version without a number, so this defaults to what `apify push` uses.
+            // AJV turns a null versionNumber into an empty string, which counts as not given.
+            const versionNumber = parsed.versionNumber || readActorJsonVersion(sourceFiles) || '0.0';
+            const created = await client.actors().create({
+                name: parsed.name,
+                ...(parsed.title !== undefined && { title: parsed.title }),
+                ...(parsed.description !== undefined && { description: parsed.description }),
+                versions: [
+                    {
+                        versionNumber,
+                        ...(parsed.buildTag !== undefined && { buildTag: parsed.buildTag }),
+                        sourceType: ActorSourceType.SourceFiles,
+                        sourceFiles,
+                    },
+                ],
+            });
+            const fullName = `${created.username}/${created.name}`;
+            // The platform sets the name in .actor/actor.json on create, so the stored files, not the sent ones, match
+            // a later read.
+            const version = resolveVersion(created, undefined, fullName);
+            const files = buildFilesManifest(extractSourceFiles(version, `Version ${version.versionNumber} of ${fullName}`));
+            const emptyPaths = files.filter(({ sizeBytes }) => sizeBytes === 0).map(({ path }) => path);
+            return await respondAfterWrite({
+                toolArgs,
+                autoBuild: parsed.autoBuild,
+                target: { actorId: created.id, versionNumber: version.versionNumber },
+                structuredContent: {
+                    actorId: created.id,
+                    fullName,
+                    versionNumber: version.versionNumber,
+                    revision: buildFilesRevision(files),
+                    files: files.map(({ path, sizeBytes, hash }) => ({ path, sizeBytes, hash })),
+                    ...buildEmptyFilesWarnings(emptyPaths),
+                },
+                summary: `Created the private Actor ${fullName}.`,
+            });
+        }
+        catch (error) {
+            if (!isRetriedNameTaken(error))
+                return respondToSourceToolError(error);
+            const readTool = loadedToolNames.includes(HELPER_TOOLS.ACTOR_VERSION_GET)
+                ? `; ${HELPER_TOOLS.ACTOR_VERSION_GET} reads its files`
+                : '';
+            return respondUserError(`The platform refused the name ${parsed.name} as taken when the request was retried, so an earlier ` +
+                `attempt of this call may have created the Actor ${parsed.name}. ` +
+                `If it holds the files you sent, this call created it${readTool}.`, { httpStatus: error.statusCode });
+        }
+    },
+});
+//# sourceMappingURL=create_actor.js.map

package/dist/tools/versions/create_actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create_actor.js","sourceRoot":"","sources":["../../../src/tools/versions/create_actor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,sCAAsC,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACH,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,iBAAiB,EACjB,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,GACzB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,oEAAoE,CAAC;IACtG,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IACtF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;IAC1F,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IACjG,aAAa,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACL,gHAAgH,CACnH;IACL,QAAQ,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CAAC,kFAAkF,CAAC;IACjG,SAAS,EAAE,CAAC;SACP,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,oGAAoG,CAAC;CACtH,CAAC,CAAC;AAEH;;;GAGG;AACH,SAAS,sBAAsB,CAAC,KAAgD;IAC5E,MAAM,OAAO,GAA6B,EAAE,CAAC;IAC7C,MAAM,SAAS,GAAG,IAAI,eAAe,CAAC,EAAE,CAAC,CAAC;IAC1C,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC1C,sBAAsB,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,KAAK,GAAG,CAAC,CAAC;QACrD,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,SAAS,KAAK,MAAM,IAAI,CAAC,IAAI,GAAG,CAAC;QAC/C,gBAAgB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACpC,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAClC,IAAI,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,cAAc,CAAC,GAAG,KAAK,qBAAqB,KAAK,CAAC,IAAI,oCAAoC,CAAC,CAAC;QAC1G,CAAC;QACD,SAAS,CAAC,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACjD,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,OAAO,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAAC,OAA0C;IACpE,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,KAAK,mBAAmB,IAAI,MAAM,KAAK,MAAM,CAAC,CAAC;IACxG,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,IAAI,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAA0B,CAAC;QAClG,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,SAAS,CAAC;IACrB,CAAC;AACL,CAAC;AAED,wHAAwH;AACxH,SAAS,kBAAkB,CAAC,KAAc;IACtC,OAAO,KAAK,YAAY,aAAa,IAAI,KAAK,CAAC,IAAI,KAAK,sCAAsC,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC;AACxH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAc,MAAM,CAAC,MAAM,CAAC;IAChD,IAAI,EAAE,SAAS,CAAC,QAAQ;IACxB,IAAI,EAAE,YAAY,CAAC,YAAY;IAC/B,KAAK,EAAE,cAAc;IACrB,WAAW,EAAE,MAAM,CAAA;;;;;;;;;;kFAU2D;IAC9E,sFAAsF;IACtF,WAAW,EAAE,oBAAoB,CAAC,CAAC,CAAC,YAAY,CAAC,eAAe,CAAC,CAAoB;IACrF,YAAY,EAAE,2BAA2B;IACzC,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;IAC3D,WAAW,EAAE;QACT,KAAK,EAAE,cAAc;QACrB,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,oEAAoE;QACpE,cAAc,EAAE,KAAK;QACrB,8CAA8C;QAC9C,aAAa,EAAE,IAAI;KACtB;IACD,UAAU,EAAE,CAAC,IAA6B,EAAE,EAAE,CAC1C,oBAAoB,CAAC,IAAI,EAAE;QACvB,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,CAAC;QAChF,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC;KAClC,CAAC;IACN,IAAI,EAAE,KAAK,EAAE,QAA0B,EAAE,EAAE;QACvC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,QAAQ,CAAC;QACxE,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3C,qGAAqG;QACrG,IAAI,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,OAAO;YAAE,OAAO,cAAc,EAAE,CAAC;QAC7C,IAAI,CAAC;YACD,MAAM,WAAW,GAAG,sBAAsB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,+FAA+F;YAC/F,kFAAkF;YAClF,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,oBAAoB,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;YACzF,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC;gBACzC,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;gBAC1D,GAAG,CAAC,MAAM,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC;gBAC5E,QAAQ,EAAE;oBACN;wBACI,aAAa;wBACb,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;wBACnE,UAAU,EAAE,eAAe,CAAC,WAAW;wBACvC,WAAW;qBACd;iBACJ;aACmC,CAAC,CAAC;YAC1C,MAAM,QAAQ,GAAG,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACvD,2GAA2G;YAC3G,gBAAgB;YAChB,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC7D,MAAM,KAAK,GAAG,kBAAkB,CAC5B,kBAAkB,CAAC,OAAO,EAAE,WAAW,OAAO,CAAC,aAAa,OAAO,QAAQ,EAAE,CAAC,CACjF,CAAC;YACF,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;YAC5F,OAAO,MAAM,iBAAiB,CAAC;gBAC3B,QAAQ;gBACR,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE;gBACrE,iBAAiB,EAAE;oBACf,OAAO,EAAE,OAAO,CAAC,EAAE;oBACnB,QAAQ;oBACR,aAAa,EAAE,OAAO,CAAC,aAAa;oBACpC,QAAQ,EAAE,kBAAkB,CAAC,KAAK,CAAC;oBACnC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;oBAC5E,GAAG,uBAAuB,CAAC,UAAU,CAAC;iBACzC;gBACD,OAAO,EAAE,6BAA6B,QAAQ,GAAG;aACpD,CAAC,CAAC;QACP,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC;gBAAE,OAAO,wBAAwB,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,YAAY,CAAC,iBAAiB,CAAC;gBACrE,CAAC,CAAC,KAAK,YAAY,CAAC,iBAAiB,kBAAkB;gBACvD,CAAC,CAAC,EAAE,CAAC;YACT,OAAO,gBAAgB,CACnB,iCAAiC,MAAM,CAAC,IAAI,wDAAwD;gBAChG,mDAAmD,MAAM,CAAC,IAAI,IAAI;gBAClE,uDAAuD,QAAQ,GAAG,EACtE,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CACnC,CAAC;QACN,CAAC;IACL,CAAC;CACK,CAAC,CAAC"}

package/dist/tools/versions/get_actor_version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_actor_version.d.ts","sourceRoot":"","sources":["../../../src/tools/versions/get_actor_version.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAoB,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AA4HnF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,SA0EnB,CAAC"}

package/dist/tools/{source → versions}/get_actor_version.js

@@ -1,7 +1,4 @@
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9a02aa21-6712-56af-a634-93a1e782edda")}catch(e){}}();
 import { posix } from 'node:path';
-import { ActorSourceType } from 'apify-client';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { HELPER_TOOLS, MAX_INLINE_BYTES } from '../../const.js';
@@ -9,15 +6,15 @@ import { UserInputError } from '../../errors.js';
 import { TOOL_TYPE } from '../../types.js';
 import { compileSchema } from '../../utils/ajv.js';
 import { respondOk, respondUserError } from '../../utils/mcp.js';
-import { listVersionNumbers } from '../builds/build_helpers.js';
 import { getActorVersionToolOutputSchema } from '../structured_output_schemas.js';
 import { buildFilesManifest, buildFilesRevision } from './source_files.js';
+import { extractSourceFiles, fetchActor, resolveVersion, respondToSourceToolError } from './source_helpers.js';
 const INLINE_LIMIT_KIB = MAX_INLINE_BYTES / 1024;
 const getActorVersionArgs = z.object({
     actor: z
         .string()
         .min(1)
-        .describe('The Actor to read: its ID, or its full name as username/name or username~name. A name without the username is not enough.'),
+        .describe('The Actor to read: its ID, its name (resolved against your own Actors), or its full name as username/name or username~name.'),
     // Format is not enforced by a regex: the lookup against the Actor's versions rejects anything that is not an
     // existing version with a soft fail.
     versionNumber: z
@@ -41,80 +38,6 @@ const getActorVersionArgs = z.object({
         .optional()
         .describe('Number of lines to return from startLine; defaults to the rest of the file. Only with exactly one path in paths.'),
 });
-/** The requested version, or the only one when none is requested; throws `UserInputError` otherwise. */
-function resolveVersion(actor, requestedVersionNumber, actorSelector) {
-    const versionNumbers = listVersionNumbers(actor);
-    if (requestedVersionNumber === undefined && versionNumbers.length !== 1) {
-        // The source type and build tag tell the caller which version holds the code it is after.
-        const versions = actor.versions
-            .filter((version) => version.versionNumber !== undefined)
-            .map(({ versionNumber, sourceType, buildTag }) => {
-            const tag = buildTag ? `, build tag ${buildTag}` : '';
-            return `${versionNumber} (${sourceType}${tag})`;
-        });
-        throw new UserInputError(`Specify versionNumber; this Actor has versions: ${versions.join(', ')}.`);
-    }
-    const versionNumber = requestedVersionNumber !== null && requestedVersionNumber !== void 0 ? requestedVersionNumber : versionNumbers[0];
-    const version = actor.versions.find((candidate) => candidate.versionNumber === versionNumber);
-    if (!version) {
-        throw new UserInputError(`Actor '${actorSelector}' has no version ${versionNumber}; available versions: ${versionNumbers.join(', ')}.`);
-    }
-    return { ...version, versionNumber };
-}
-/**
- * The URL without what can grant access to it: the query string, the password, and, for http and https, the user. An
- * SSH user such as `git@` is not a secret and stays. A URL the parser cannot read, such as
- * `git@github.com:user/repo.git`, loses only its query string.
- */
-function formatUrlWithoutSecrets(url) {
-    if (URL.canParse(url)) {
-        const parsed = new URL(url);
-        parsed.search = '';
-        parsed.password = '';
-        if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
-            parsed.username = '';
-        }
-        return parsed.href;
-    }
-    const queryIndex = url.indexOf('?');
-    if (queryIndex === -1)
-        return url;
-    const hashIndex = url.indexOf('#', queryIndex);
-    return url.slice(0, queryIndex) + (hashIndex === -1 ? '' : url.slice(hashIndex));
-}
-/**
- * Why a version not stored as files is refused, and what to use instead. A version keeps the URL fields of a source
- * type it used before, so only the URL of its current type is named.
- */
-function formatSourceTypeRefusal(version, versionLabel) {
-    if (version.sourceType === ActorSourceType.GitRepo) {
-        const url = version.gitRepoUrl ? ` ${formatUrlWithoutSecrets(version.gitRepoUrl)}` : '';
-        return `${versionLabel} has its files in the Git repository${url}, not stored on Apify, so this tool cannot work on them; use the repository.`;
-    }
-    if (version.sourceType === ActorSourceType.GitHubGist) {
-        const url = version.gitHubGistUrl ? ` ${formatUrlWithoutSecrets(version.gitHubGistUrl)}` : '';
-        return `${versionLabel} has its files in the GitHub gist${url}, not stored on Apify, so this tool cannot work on them; use the gist.`;
-    }
-    // TODO(#1452): Read zip-stored (TARBALL) versions with adm-zip 0.6.1 or later, within the download and unpacking
-    // limits the issue lists.
-    if (version.sourceType === ActorSourceType.Tarball) {
-        return `${versionLabel} is stored as a zip archive (apify push does this for sources over 3 MiB), and this tool cannot work on zip-stored versions yet.`;
-    }
-    // The API's legacy SOURCE_CODE type and any type added later are not in apify-client's enum.
-    const { sourceType } = version;
-    return `${versionLabel} has source type ${sourceType}, which this tool cannot work on; only versions stored as files are supported.`;
-}
-/** Throws `UserInputError` for a version not stored as files and for one whose source the API hides. */
-function extractVersionFiles(version, versionLabel) {
-    if (version.sourceType !== ActorSourceType.SourceFiles) {
-        throw new UserInputError(formatSourceTypeRefusal(version, versionLabel));
-    }
-    // The API returns only the number, type, and build tag of a version whose source it hides from this account.
-    if (!version.sourceFiles) {
-        throw new UserInputError(`${versionLabel} came back without its source: the API hides it from accounts that cannot modify the Actor. Ask the Actor's owner for the source.`);
-    }
-    return buildFilesManifest(version.sourceFiles);
-}
 /** Lines with their line endings kept, so joined back they give the exact text. */
 function splitLines(text) {
     if (text === '')
@@ -224,15 +147,9 @@ export const getActorVersion = Object.freeze({
         }
         try {
             // TODO: The Actor GET returns every file of every version; read only the files asked for once the API can.
-            // apify-client turns username/name into the API's username~name.
-            const actor = await client.actor(parsed.actor).get();
-            // Extra path segments, such as username/name/runs/last, reach a sub-resource that is not an Actor.
-            if (!actor || typeof actor.name !== 'string' || typeof actor.username !== 'string') {
-                return respondUserError(`Actor '${parsed.actor}' not found. Give its ID or its full name, username/name; a name without the username is not enough.`);
-            }
-            const fullName = `${actor.username}/${actor.name}`;
+            const { actor, fullName } = await fetchActor(client, parsed.actor);
             const version = resolveVersion(actor, parsed.versionNumber, parsed.actor);
-            const files = extractVersionFiles(version, `Version ${version.versionNumber} of ${fullName}`);
+            const files = buildFilesManifest(extractSourceFiles(version, `Version ${version.versionNumber} of ${fullName}`));
             const structuredContent = {
                 actorId: actor.id,
                 fullName,
@@ -258,11 +175,8 @@ export const getActorVersion = Object.freeze({
             return respondOk([JSON.stringify(structuredContent), summary], { structuredContent });
         }
         catch (error) {
-            if (error instanceof UserInputError)
-                return respondUserError(error.message);
-            throw error;
+            return respondToSourceToolError(error);
         }
     },
 });
-//# sourceMappingURL=get_actor_version.js.map
-//# debugId=9a02aa21-6712-56af-a634-93a1e782edda
+//# sourceMappingURL=get_actor_version.js.map

package/dist/tools/versions/get_actor_version.js.map

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

package/dist/tools/{source → versions}/source_files.d.ts

@@ -11,13 +11,17 @@ export type SourceFile = {
     contentBytes: number;
     /** The content as returned: the text for utf8, the base64 for base64. */
     content: string;
+    /** The entry as stored, which a write sends back for a file it leaves alone. */
+    entry: ActorVersionSourceFile;
 };
 export declare function hasBinaryExtension(path: string): boolean;
 /** Paths in JavaScript's default string order, so the manifest and the revision do not depend on the locale. */
 export declare function compareSourcePaths(a: string, b: string): number;
 /**
- * Identifies the file set: one `path\0hash\n` line per regular file, sorted by path. The stored format does not go
- * in, so a file stored as TEXT or as BASE64 gives the same revision.
+ * Identifies the file set: the JSON array of `[path, hash]` pairs of its regular files, sorted by path. JSON quotes
+ * each path and escapes quotes and control characters in it, so two different file sets never give the same text, as
+ * a stored name with NUL and a line break once did. The stored format does not go in, so a file stored as TEXT or as
+ * BASE64 gives the same revision.
  */
 export declare function buildFilesRevision(files: readonly Pick<SourceFile, 'path' | 'hash'>[]): string;
 /**

package/dist/tools/versions/source_files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source_files.d.ts","sourceRoot":"","sources":["../../../src/tools/versions/source_files.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AA4D3D,qCAAqC;AACrC,MAAM,MAAM,UAAU,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,2GAA2G;IAC3G,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,KAAK,EAAE,sBAAsB,CAAC;CACjC,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGxD;AAOD,gHAAgH;AAChH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,MAAM,CAG9F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,UAAU,CAc9E;AAED,4HAA4H;AAC5H,wBAAgB,aAAa,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAEnE;AAED,mHAAmH;AACnH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GAAG,UAAU,EAAE,CAQ3F"}

package/dist/tools/{source → versions}/source_files.js

@@ -1,5 +1,3 @@
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4abfae6a-7ffb-53f2-a005-41621ac9f11d")}catch(e){}}();
 import { isUtf8 } from 'node:buffer';
 import { createHash } from 'node:crypto';
 import { posix } from 'node:path';
@@ -73,14 +71,14 @@ export function compareSourcePaths(a, b) {
     return a < b ? -1 : 1;
 }
 /**
- * Identifies the file set: one `path\0hash\n` line per regular file, sorted by path. The stored format does not go
- * in, so a file stored as TEXT or as BASE64 gives the same revision.
+ * Identifies the file set: the JSON array of `[path, hash]` pairs of its regular files, sorted by path. JSON quotes
+ * each path and escapes quotes and control characters in it, so two different file sets never give the same text, as
+ * a stored name with NUL and a line break once did. The stored format does not go in, so a file stored as TEXT or as
+ * BASE64 gives the same revision.
  */
 export function buildFilesRevision(files) {
-    const lines = [...files]
-        .sort((a, b) => compareSourcePaths(a.path, b.path))
-        .map(({ path, hash }) => `${path}\0${hash}\n`);
-    return getSha256Prefix(lines.join(''));
+    const pairs = [...files].sort((a, b) => compareSourcePaths(a.path, b.path)).map(({ path, hash }) => [path, hash]);
+    return getSha256Prefix(JSON.stringify(pairs));
 }
 /**
  * A file stored inline in the version, read as the build worker reads it: no `format` is TEXT, no `content` is empty,
@@ -92,7 +90,7 @@ export function buildInlineSourceFile(file) {
     const content = storedContent !== null && storedContent !== void 0 ? storedContent : '';
     const path = posix.normalize(name);
     const bytes = Buffer.from(content, format === 'BASE64' ? 'base64' : 'utf8');
-    const common = { path, sizeBytes: bytes.length, hash: getSha256Prefix(bytes) };
+    const common = { path, sizeBytes: bytes.length, hash: getSha256Prefix(bytes), entry: file };
     if (format !== 'BASE64') {
         return { ...common, encoding: 'utf8', contentBytes: bytes.length, content };
     }
@@ -117,5 +115,4 @@ export function buildFilesManifest(entries) {
     }
     return [...filesByPath.values()].sort((a, b) => compareSourcePaths(a.path, b.path));
 }
-//# sourceMappingURL=source_files.js.map
-//# debugId=4abfae6a-7ffb-53f2-a005-41621ac9f11d
+//# sourceMappingURL=source_files.js.map

package/dist/tools/versions/source_files.js.map

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

package/dist/tools/versions/source_helpers.d.ts

@@ -0,0 +1,107 @@
+import type { Actor, ActorVersion, ActorVersionSourceFile } from 'apify-client';
+import { z } from 'zod';
+import type { ApifyClient } from '../../apify_client.js';
+import type { InternalToolArgs } from '../../types.js';
+import type { ToolResponse } from '../../utils/mcp.js';
+/** The input shape of one file sent whole. */
+export declare const sourceFileArgs: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+    encoding: z.ZodOptional<z.ZodEnum<{
+        base64: "base64";
+        utf8: "utf8";
+    }>>;
+}, z.core.$strip>;
+/**
+ * The logged copy of a source tool's arguments (`redactArgs`), built as an allowlist: `keys`, and each entry of the
+ * list under `listKey` with its `entryKeys`, and with its content and its edits' oldText and newText as `REDACTED`.
+ * File content can hold secrets, such as an API key written into the code.
+ */
+export declare function redactSourceToolArgs(args: Record<string, unknown>, fields: {
+    keys: readonly string[];
+    listKey: string;
+    entryKeys: readonly string[];
+}): Record<string, unknown>;
+/**
+ * The Actor by its ID, its name (resolved against the token's own Actors), or its full name, `username/name` or
+ * `username~name` (apify-client turns username/name into the API's username~name); throws `UserInputError` when there
+ * is none.
+ */
+export declare function fetchActor(client: ApifyClient, actorSelector: string): Promise<{
+    actor: Actor;
+    fullName: string;
+}>;
+/** The requested version, or the only one when none is requested; throws `UserInputError` otherwise. */
+export declare function resolveVersion(actor: Pick<Actor, 'versions'>, requestedVersionNumber: string | undefined, actorSelector: string): ActorVersion & {
+    versionNumber: string;
+};
+/**
+ * The version's stored entries, folders included. Throws `UserInputError` for a version not stored as files and for
+ * one whose source the API hides.
+ */
+export declare function extractSourceFiles(version: ActorVersion, versionLabel: string): ActorVersionSourceFile[];
+/**
+ * The entry to store for a file sent whole: TEXT for utf8, BASE64 for base64, where no encoding means base64 for a
+ * binary extension, the rule get-actor-version reads by. The path is normalized the way get-actor-version lists it.
+ */
+export declare function buildSourceFileEntry({ path, content, encoding, }: z.infer<typeof sourceFileArgs>): ActorVersionSourceFile;
+/**
+ * Throws `UserInputError` for content the stored file would not hold as sent: base64 that does not decode without
+ * loss, and text with a lone UTF-16 surrogate, which UTF-8 stores as U+FFFD.
+ */
+export declare function validateFileContent({ format, content }: ActorVersionSourceFile, label: string): void;
+/**
+ * Throws `UserInputError` for a path with a control character, U+0000 to U+001F or U+007F, or with a lone UTF-16
+ * surrogate. The build writes the files to disk, where a file name cannot hold NUL, and UTF-8 stores a lone surrogate
+ * as U+FFFD.
+ */
+export declare function validatePathCharacters(path: string, label: string): void;
+/**
+ * Throws `UserInputError` for a normalized path no file can be written at. The build worker refuses a version with a
+ * path outside the Actor root, so every build of it would fail; `.` and a path ending in a slash name a folder. A
+ * backslash is refused too: the build takes it as part of the file name, so src\main.js would land in the Actor root.
+ */
+export declare function validateFilePath(path: string, label: string): void;
+/**
+ * The paths of a version's files and folder entries, to check where a new file can go: one path cannot be both a file
+ * and a folder, and the build worker fails to write such a file. Each check and change looks up only the folders of
+ * its path, since comparing each file with every other took 8 s for 20,000 files.
+ */
+export declare class SourcePathIndex {
+    private readonly filePaths;
+    /** The files under each folder, at any depth, in the order they were added. */
+    private readonly filePathsByFolder;
+    private readonly folderPaths;
+    constructor(filePaths: Iterable<string>, folderPaths?: readonly string[]);
+    hasFile(path: string): boolean;
+    /** A file added again keeps its place in the order. */
+    addFile(path: string): void;
+    deleteFile(path: string): void;
+    /**
+     * Throws `UserInputError` when a new file at `path` collides with another file or folder: a file at a folder of
+     * `path`, or else the first file added under `path`, or else the first folder entry at or under `path`. A file at
+     * `path` itself is for the caller to check.
+     */
+    validateNewFilePath(path: string, label: string): void;
+}
+/** The build worker skips a file whose content is empty, so the caller hears of such files. */
+export declare function buildEmptyFilesWarnings(paths: readonly string[]): {
+    warnings?: string[];
+};
+/**
+ * The response to a committed write. With autoBuild, a build of the version starts first; a cancel that arrives before
+ * the start gets the cancelled-call response.
+ */
+export declare function respondAfterWrite(params: {
+    toolArgs: Pick<InternalToolArgs, 'apifyClient' | 'apifyToken' | 'loadedToolNames' | 'signal'>;
+    autoBuild: boolean;
+    target: {
+        actorId: string;
+        versionNumber: string;
+    };
+    structuredContent: Record<string, unknown>;
+    summary: string;
+}): Promise<ToolResponse>;
+/** A `UserInputError` as a soft failure; anything else is rethrown for the tool-call engine to report. */
+export declare function respondToSourceToolError(error: unknown): ToolResponse;
+//# sourceMappingURL=source_helpers.d.ts.map

package/dist/tools/versions/source_helpers.d.ts.map

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