feat: Resolve a bare Actor name in call-actor and fetch-actor-details

AGENTS.md

@@ -47,7 +47,7 @@ After `pnpm run build`, run `mcpc` (no args) to check sessions: if `@stdio` (def
 - **Integration tests**: `pnpm run test:integration` (needs build + `APIFY_TOKEN`, humans only).
 - **Conformance tests**: `pnpm run test:conformance` (needs `APIFY_TOKEN`) builds and runs both protocol eras locally. `_integration_tests.yaml` calls `_conformance_tests.yaml` for the same `2026-07-28` and `2025-11-25` coverage in CI. Both eras always run; the command exits with the first non-zero code. Scenarios excluded from each era's gate are listed with reasons in `scripts/conformance_expected_failures_2026_07_28.yaml` and `scripts/conformance_expected_failures_2025_11_25.yaml`.
 - **Package manager**: this repo uses **pnpm 11+**. `devEngines.packageManager` is pinned with `onFail: "error"`, so npm / yarn refuse to run inside the checkout — use `pnpm install` only.
-- `tests/integration/suite.ts` wires the `stdio`, `2025-11-25` (streamable HTTP) and `2026-07-28` (stateless HTTP) transport dimensions into one shared suite. Add new integration cases to the matching capability array in `tests/test_kit/cases/*.cases.ts` (registration, tools, actors, apps, tasks, storage, schedules, payments) — each is a plain `Case[]` (`{ name, isDeploymentTest, run, ... }`), registered via `registerCases(name, cases, ctx)`. Mark a case `isDeploymentTest: true` only if it's worth running against `apify-mcp-server-internal`'s live staging and production deploys — the flag doesn't just share the case, it makes internal execute it for real on every release (see [DEVELOPMENT.md](./DEVELOPMENT.md#test-organization-across-repos)). Shared assertion helpers live in `tests/test_kit/helpers.ts`. Cases that share expensive setup (e.g. one seeded Actor run, see `storage.cases.ts`'s `normalModeRunFixture`) do so via `ctx.getFixture(fixture)`, memoized once per transport dimension — not a vitest `beforeAll`, so any subset of cases can share it while staying flat `Case` objects.
+- `tests/integration/suite.ts` wires the `stdio`, `2025-11-25` (streamable HTTP) and `2026-07-28` (stateless HTTP) transport dimensions into one shared suite. Add new integration cases to the matching capability array in `tests/test_kit/cases/*.cases.ts` (registration, tools, actors, apps, tasks, storage, schedules, versions, payments) — each is a plain `Case[]` (`{ name, isDeploymentTest, run, ... }`), registered via `registerCases(name, cases, ctx)`. Mark a case `isDeploymentTest: true` only if it's worth running against `apify-mcp-server-internal`'s live staging and production deploys — the flag doesn't just share the case, it makes internal execute it for real on every release (see [DEVELOPMENT.md](./DEVELOPMENT.md#test-organization-across-repos)). Shared assertion helpers live in `tests/test_kit/helpers.ts`. Cases that share expensive setup (e.g. one seeded Actor run, see `storage.cases.ts`'s `normalModeRunFixture`) do so via `ctx.getFixture(fixture)`, memoized once per transport dimension — not a vitest `beforeAll`, so any subset of cases can share it while staying flat `Case` objects.
 - Follow existing test patterns (names, structure) — check neighboring files.
 - **Test naming**: `describe('fnName()')`, plain-verb `it()` names (no `should` prefix). Group with nested `describe()` per method when a factory/class exposes several.
 

README.md

@@ -249,7 +249,7 @@ Here are some special MCP operations and how the Apify MCP Server supports them:
 - **Actor tasks**: Create, inspect, and update your saved Actor tasks, and publish or unpublish their public landing pages.
 - **Schedules**: Create, inspect, update, and delete schedules that run your Actors and tasks automatically.
 - **Builds**: Build an Actor version, list builds, check the status of a build, and retrieve its build log.
-- **Actor source**: Read an Actor version's files, with a hash for each file and a revision for the whole set.
+- **Actor versions**: Read an Actor version's files with a hash for each file and a revision for the whole set, create an Actor from files, and change a version's files with checks that catch changes made since your last read.
 - **Apify API**: Search the Apify API reference, inspect an operation, and send requests to the API to read or change data.
 
 ### Overview of available tools
@@ -298,7 +298,9 @@ Legend for the **Enabled by default** column:
 | `get-actor-build-log` | builds | Retrieve the logs for a specific Actor build. |  |
 | `get-actor-build-list` | builds | List the account's builds, or one Actor's, in every status, newest first. |  |
 | `build-actor` | builds | Build an Actor version and wait a bounded time for the build to finish. |  |
-| `get-actor-version` | source | Get an Actor version's file listing with hashes and the content of the files you ask for. |  |
+| `get-actor-version` | versions | Get an Actor version's file listing with hashes and the content of the files you ask for. |  |
+| `create-actor` | versions | Create a private Actor in your account from files, optionally starting a build. |  |
+| `update-actor-version` | versions | Write, edit, or delete files of an Actor version in one all-or-nothing write. |  |
 | `apify-api-search` | api | Search the Apify API reference for operations by keywords. Returns each one's method, path, and docs page. |  |
 | `apify-api-details` | api | Get the parameters and request body schema of the Apify API operations on a path. |  |
 | `apify-api-read` | api | Send a GET request to an Apify API path, such as `actor-runs` or `/v2/actor-runs`, like `apify api` in the Apify CLI. Read-only: it refuses the `method` query parameter and a GET to the synchronous run endpoints, which starts a paid run. |  |
@@ -424,6 +426,7 @@ The v2 configuration preserves backward compatibility with v1 usage. Notes:
 - `call-actor` is now included by default via the `actors` category (additive change). To exclude it, specify an explicit `tools` list without `actors`.
 - `tools=add-actor`, `tools=experimental`, and `tools=preview` are retired: they are ignored and load no tools. Use `tools=call-actor` (or the default `actors` category) instead.
 - `tools=get-actor-log` is retired: the tool was renamed to `get-actor-run-log`. The old selector is ignored and loads no tools. Use `tools=get-actor-run-log` (or the `runs` category) instead.
+- `tools=source` is retired: the category was renamed to `versions`. The old selector is ignored and loads no tools. Use `tools=versions` instead.
 
 Existing URLs and commands using `?actors=...` or `--actors` continue to work unchanged.
 

src/const.ts

@@ -54,6 +54,7 @@ export const HELPER_TOOLS = {
     ACTOR_BUILD_LOG: 'get-actor-build-log',
     ACTOR_BUILD_LIST_GET: 'get-actor-build-list',
     ACTOR_CALL: 'call-actor',
+    ACTOR_CREATE: 'create-actor',
     ACTOR_CALL_WIDGET: 'call-actor-widget',
     ACTOR_DELETE: 'delete-actor',
     ACTOR_GET_DETAILS: 'fetch-actor-details',
@@ -70,6 +71,7 @@ export const HELPER_TOOLS = {
     ACTOR_TASK_PUBLISH: 'publish-actor-task',
     ACTOR_TASK_UNPUBLISH: 'unpublish-actor-task',
     ACTOR_VERSION_GET: 'get-actor-version',
+    ACTOR_VERSION_UPDATE: 'update-actor-version',
     DATASET_GET: 'get-dataset',
     DATASET_LIST_GET: 'get-dataset-list',
     DATASET_GET_ITEMS: 'get-dataset-items',
@@ -96,16 +98,17 @@ export type HelperToolName = (typeof HELPER_TOOLS)[keyof typeof HELPER_TOOLS];
 
 /**
  * Retired tool selectors: `add-actor` and `experimental` (add-actor was deleted in the stateless
- * migration), the deprecated `preview` pseudo-category, and `get-actor-log` (renamed to
- * `get-actor-run-log`). They name neither a registry category nor a real tool anymore, so they
- * resolve to nothing — never loaded, never treated as an Actor ID, never requiring a token by
- * themselves.
+ * migration), the deprecated `preview` pseudo-category, `get-actor-log` (renamed to
+ * `get-actor-run-log`), and the `source` category (renamed to `versions`). They name neither a
+ * registry category nor a real tool anymore, so they resolve to nothing — never loaded, never
+ * treated as an Actor ID, never requiring a token by themselves.
  */
 export const RETIRED_SELECTOR_NAMES: ReadonlySet<string> = new Set([
     'add-actor',
     'experimental',
     'preview',
     'get-actor-log',
+    'source',
 ]);
 
 /**
@@ -283,6 +286,7 @@ export const APIFY_ERROR_TYPE_MEMORY_LIMIT_EXCEEDED = 'memory-limit-exceeded';
 export const APIFY_ERROR_TYPE_CANNOT_START_ACTOR_RUNS = 'cannot-start-actor-runs';
 export const APIFY_ERROR_TYPE_CANNOT_PUBLISH_ACTOR_TASK = 'cannot-publish-actor-task';
 export const APIFY_ERROR_TYPE_INVALID_INPUT = 'invalid-input';
+export const APIFY_ERROR_TYPE_ACTOR_NAME_NOT_UNIQUE = 'actor-name-not-unique';
 export const APIFY_ERROR_TYPE_PAGE_NOT_FOUND = 'page-not-found';
 
 // HTTP status codes

src/tools/AGENTS.md

@@ -32,16 +32,20 @@ direct actor tools, `search-actors`, `fetch-actor-details`) is mode-agnostic.
   - `tasks/` — Actor task create/get/update plus publish/unpublish of the task's public
     landing page (`task_helpers.ts` holds the shared task response shape and the publication call).
   - `schedules/` — schedule create/get/update/delete for Actors and tasks; `schedule_helpers.ts`
-    converts the flat action shape to the API shape and back, and reuses the id helpers from
+    converts the flat action shape to the API shape and back, and reuses `getTaskByIdOrName` from
     `tasks/task_helpers.ts`.
   - `builds/` — `get-actor-build` (build status), `get-actor-build-log` (build log tail),
     `get-actor-build-list` (the account's builds, or one Actor's with `actorId`, in every status, newest
     first, pointing at the newest failed one) and `build-actor` (start a build of one version and wait for it); `build_helpers.ts` holds the
     allowlisted build result shape, the build start and wait calls (the wait reports progress), the
     shared `waitSecs` field, the shared build response and the by-status next-step text.
-  - `source/`: `get-actor-version` (an Actor version's file manifest with hashes, revision, and
-    requested content). `source_files.ts` holds the file shape, the manifest builder, the hash and
-    revision rules, and the text-or-base64 detection. Versions not stored as files (Git repository,
+  - `versions/`: `get-actor-version` (an Actor version's file manifest with hashes, revision, and
+    requested content), `create-actor` (a new Actor with one version in a single POST), and
+    `update-actor-version` (write, edit, and delete operations applied all-or-nothing to a fresh read,
+    stored with one version PUT that carries only the source keys). `source_files.ts` holds the file
+    shape, the manifest builder, the hash and revision rules, and the text-or-base64 detection;
+    `source_helpers.ts` holds the Actor and version lookup, the file input shape, and the response
+    after a write, which starts the build for autoBuild. Versions not stored as files (Git repository,
     gist, or zip) are refused.
   - `api/` — the generic Apify API tools: search the operations of the published OpenAPI spec, get the
     operations on a path, and send a GET, or a POST, PUT, PATCH, or DELETE, to a path. The write tool is in
@@ -76,6 +80,13 @@ direct actor tools, `search-actors`, `fetch-actor-details`) is mode-agnostic.
   - `docs/` — search and fetch Apify docs.
   - `dev/` — the `report-problem` tool for reporting a problem with a tool or Actor.
   - `widgets/` — the `*-widget` tool variants (apps mode only).
+- `../utils/apify_resource_id.ts` holds the helpers that resolve an Actor, task, or schedule given by ID or
+  name, where a name alone means one of the caller's own. The task, schedule, and versions tools use them,
+  and so do `build-actor` and the `actorId` filter of `get-actor-build-list` and `get-actor-run-list`.
+  `call-actor` (and `call-actor-widget`, which shares its pre-execution) and `fetch-actor-details` go through
+  `getActorByIdOrName` in `../utils/actor.ts`. Outside payment sessions it turns a name alone into
+  `username/name` with an uncached read, so `~name` never keys `actorDefinitionCache`. Under a payment provider
+  it resolves nothing: every value is passed on as given, a literal `~name` too.
 
 ## Rules when editing here
 

src/tools/actors/call_actor.ts

@@ -19,7 +19,14 @@ import { withRemoteMcpClient } from '../../mcp/remote_tool_call.js';
 import type { PaymentProvider } from '../../payments/types.js';
 import type { ApifyToken, InternalToolArgs, ToolDescriptionContext, ToolEntry, ToolInputSchema } from '../../types.js';
 import { ACTOR_TOOL_MODE, ALL_TOOLS_PRESENT, TOOL_TYPE } from '../../types.js';
-import { getActorDefinitionCached, getActorToolResolutionCached } from '../../utils/actor.js';
+import {
+    getActorByIdOrName,
+    getActorDefinitionCached,
+    getActorToolResolutionCached,
+    isOwnActorLookup,
+    OWN_ACTOR_NOT_FOUND_FACT,
+    ownActorWithoutBuildFact,
+} from '../../utils/actor.js';
 import { compileSchema } from '../../utils/ajv.js';
 import {
     ACTOR_RUN_LIMIT_MESSAGE,
@@ -137,7 +144,7 @@ export function buildCallActorDescription(ctx: ToolDescriptionContext = ALL_TOOL
         ...(hasTool(HELPER_TOOLS.STORE_SEARCH)
             ? [
                   '',
-                  `If the actor name is not in "username/name" format, use ${HELPER_TOOLS.STORE_SEARCH} to resolve the correct Actor first.`,
+                  `A name without a username means one of your own Actors, never another account's Actor; ${HELPER_TOOLS.STORE_SEARCH} returns the full "username/name" of Store Actors.`,
               ]
             : []),
     ].join('\n');
@@ -188,17 +195,24 @@ function respondStandbyRejection(
  * Canonical "Actor not found" answer, shared by the run path and the `actor:toolName` route so an
  * unknown Actor gets the same response regardless of call shape.
  */
-function respondActorNotFound(actorName: string, loadedToolNames: readonly string[]): ToolResponse {
+function respondActorNotFound(
+    actorName: string,
+    loadedToolNames: readonly string[],
+    { isOwnActorName = false }: { isOwnActorName?: boolean } = {},
+): ToolResponse {
     // See apify/apify-mcp-server#1296.
     // Only search-actors: the Actor does not exist, so buildCallFailureRecoveryHint's second
     // offer (get Actor details) would send the model to a lookup that fails the same way.
     const recovery = loadedToolNames.includes(HELPER_TOOLS.STORE_SEARCH)
         ? `\nYou can search for available Actors using the tool: ${HELPER_TOOLS.STORE_SEARCH}.`
         : '';
+    const reason = isOwnActorName
+        ? OWN_ACTOR_NOT_FOUND_FACT
+        : 'Please verify Actor ID or name format (e.g., "username/name" like "apify/rag-web-browser") and ensure that the Actor exists.';
     return respondUserError(
         dedent`
             Actor '${actorName}' was not found.
-            Please verify Actor ID or name format (e.g., "username/name" like "apify/rag-web-browser") and ensure that the Actor exists.
+            ${reason}
         ` + recovery,
         { httpStatus: 404, detail: `Actor '${actorName}' was not found` },
     );
@@ -308,7 +322,8 @@ export const callOptionsSchema = z.object({
 /** Zod schema for call-actor arguments — shared between default and apps variants. */
 export const callActorArgs = z.object({
     actor: z.string().describe(dedent`
-            The Actor to call: its ID, or its name in the "username/name" form (e.g., "apify/rag-web-browser").
+            The Actor to call: its ID, its name (resolved against your own Actors), or its full name as username/name or username~name (e.g., "apify/rag-web-browser").
+            A name without a username always means one of your own Actors, never another account's Actor.
 
             For MCP server Actors, use format "actorName:toolName" to call a specific tool (e.g., "username/name:tool-name").
         `),
@@ -348,7 +363,8 @@ export type CallActorParsedArgs = z.infer<typeof callActorArgs>;
  * generic payment-required short-circuit in the tool-call handler so the
  * agent receives the precise reason instead of a generic 402.
  *
- * Uses `actorDefinitionCache` — one definition fetch on a cold cache.
+ * Uses `actorDefinitionCache` — one definition fetch on a cold cache. Checks the name as given: under a payment
+ * provider `callActorPreExecute` does not resolve a name alone either (`isOwnActorLookup`), so both read the same Actor.
  */
 export async function checkPaymentProviderStandbyConflict(params: {
     actorName: string;
@@ -572,18 +588,38 @@ export async function callActorPreExecute(
           mcpToolName: string | undefined;
       }
 > {
-    const { args, apifyToken, mcpSessionId, loadedToolNames } = toolArgs;
+    const { args, apifyToken, apifyClient, paymentProvider, mcpSessionId, loadedToolNames } = toolArgs;
     const parsedArgs = callActorArgs.parse(args);
     const actorName = fixActorNameInputAndLog(parsedArgs.actor, { mcpSessionId, route: options.route });
     const parsed: CallActorParsedArgs = { ...parsedArgs, actor: actorName };
 
-    const { baseActorName, mcpToolName } = resolveActorContext(parsed.actor);
+    const { baseActorName: requestedActorName, mcpToolName } = resolveActorContext(parsed.actor);
 
     // For definition resolution we always use a token-based client; payment provider is only for actual Actor runs.
     // Standby/MCP-server Actors under a third-party payment provider are rejected upstream by
-    // `checkPaymentProviderStandbyConflict` — see src/mcp/tool_call_engine.ts.
+    // `checkPaymentProviderStandbyConflict` — see src/mcp/tool_call_engine.ts. `apifyClient` reads `~name` only
+    // without a payment provider, when it is token-based too.
     const apifyClientForDefinition = new ApifyClient({ token: apifyToken });
-    const resolution = await getActorToolResolutionCached(baseActorName, apifyClientForDefinition);
+    const lookup = await getActorByIdOrName({
+        actorIdOrName: requestedActorName,
+        apifyClient,
+        paymentProvider,
+        fetch: async (actorKey) => getActorToolResolutionCached(actorKey, apifyClientForDefinition),
+    });
+    if (lookup?.actor === null) {
+        return {
+            earlyResponse: respondUserError(ownActorWithoutBuildFact(lookup.actorKey), {
+                detail: 'own Actor has no default build',
+            }),
+        };
+    }
+    if (!lookup && isOwnActorLookup(requestedActorName, paymentProvider)) {
+        return { earlyResponse: respondActorNotFound(requestedActorName, loadedToolNames, { isOwnActorName: true }) };
+    }
+    // The run, the MCP tool call and their responses use the key the Actor was found under: a name alone became
+    // `username/name`, and `~name` must not reach the shared definition cache.
+    const baseActorName = lookup?.actorKey ?? requestedActorName;
+    const resolution = lookup?.actor ?? null;
 
     if (resolution?.toolMode === ACTOR_TOOL_MODE.STANDBY_WITHOUT_MCP) {
         return {